diff --git a/docs/source/api/index.md b/docs/source/api/index.md
index ec29f35c..6fab98cd 100644
--- a/docs/source/api/index.md
+++ b/docs/source/api/index.md
@@ -1,20 +1,65 @@
 # Patternia API Reference
 
-patternia provides a **header-only DSL** for expressive pattern matching in modern C++.
+Patternia is a modern **header-only pattern matching DSL** for expressive and declarative logic in C++17 and above.
+
+This API Reference is generated using **Doxygen + Breathe + MyST**, and reflects
+the full public surface of the Patternia library.
 
 ---
 
-## Overview
+## Core Layer (`core`)
+
+The **Core Layer** defines the matching engine (`match_builder`),
+the DSL bridge (`case_expr`), and the entry-point function `match()`.
 
-This document describes the public API defined in  
-[`include/ptn/patternia.hpp`](https://github.com/sentomk/patternia/blob/main/include/ptn/patternia.hpp).
+```{doxygengroup} core
+:project: patternia
+:members:
+:outline:
+```
 
 ---
 
-## Core Interfaces
+## Pattern Layer (`patterns`)
+
+The **Pattern Layer** provides the built-in patterns shipped with Patternia:
+
+* `value_pattern`
+* relational patterns (`lt`, `le`, `gt`, `ge`, `eq`, `ne`)
+* `predicate_pattern`
+* `and_pattern` / `or_pattern` / `not_pattern`
+* `pattern_tag` and `pattern_base`
+
+```{doxygengroup} patterns
+:project: patternia
+:members:
+:outline:
+```
+
+---
+
+## Main Public Header
+
+Most users will interact with Patternia via the single entry header:
 
 ```{doxygenfile} patternia.hpp
 :project: patternia
 :members:
 :undoc-members:
 :outline:
+```
+
+> This aggregates the entire DSL, pattern modules, and core engine into a single interface.
+
+---
+
+## Navigation
+
+* **User Guide** — How to write patterns and match expressions
+* **Design Notes** — Architecture of Core/Pattern/Type layers
+* **Release Notes** — Version history and migration notes
+
+---
+
+Patternia aims to be expressive, extensible, and pleasant to use —
+**logic should feel beautiful**.
diff --git a/docs/source/index.md b/docs/source/index.md
index 8885859d..95194209 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -49,14 +49,7 @@ For a five-minute tutorial, check out {doc}`Quick Start <guide/quickstart>`.
 :maxdepth: 2
 :hidden:
 
-guide/quickstart
 usage
+guide/quickstart
 api/index
-```
-
-```{note}
-This documentation is generated using **Doxygen + Breathe + Sphinx (Furo)**.
-Source code is available at: https://github.com/sentomk/patternia
-
-© 2025 sentomk — MIT License.
-```
+```
\ No newline at end of file
diff --git a/include/ptn/detail/pattern_tag.hpp b/include/ptn/detail/pattern_tag.hpp
index b1315a16..7f224a7a 100644
--- a/include/ptn/detail/pattern_tag.hpp
+++ b/include/ptn/detail/pattern_tag.hpp
@@ -7,7 +7,7 @@
  * @file pattern_tag.hpp
  * @brief Marker base type and detection utilities for Patternia patterns.
  *
- * This header defines the @ref ptn::patterns::pattern_tag base struct and the
+ * This header defines the @ref ptn::detail::pattern_tag base struct and the
  * compile-time facilities for identifying "pattern-like" types.
  *
  * A type is considered *pattern-like* if:
diff --git a/include/ptn/patternia.hpp b/include/ptn/patternia.hpp
index 77ae9b85..5d73dc4d 100644
--- a/include/ptn/patternia.hpp
+++ b/include/ptn/patternia.hpp
@@ -6,6 +6,27 @@
 #include "ptn/core/match_builder.hpp" // core API
 #include "ptn/config.hpp"
 
+/**
+ * @file patternia.hpp
+ * @brief Public entry header for Patternia — the modern C++ pattern matching
+ * DSL.
+ */
+
+/** @defgroup core Core Layer
+ *  Core matching engine: match_builder, DSL, and evaluation logic.
+ */
+
+/** @defgroup patterns Pattern Layer
+ *  Built-in pattern implementations such as value_pattern,
+ *  relational patterns (lt/le/gt/ge), and predicate patterns.
+ */
+
+#include <tuple>
+#include <type_traits>
+#include <utility>
+#include "ptn/core/match_builder.hpp" // core API
+#include "ptn/config.hpp"
+
 /**
  * @defgroup main Main API
  * @brief Core public interface of Patternia.