chore(release): 0.0.7

Squash-merge lib-standardisation: adopt repo standards across packaging,
tooling, docs, and CI.

- standardize pyproject.toml (canonical packaging, lint config, extras, GSDFC pydoclint)
- add py.typed marker, modernize type hints and Google-style docstrings
- nest generated docs under docs/lib and docs/mcp; add hand-written wiki
- adopt standard Type A PyPI CI pipeline (tag==version guard + quality gate)
- promote generated CHANGELOG.md; bump version to 0.0.7

docs/wiki/01_overview.md

@@ -0,0 +1,43 @@
+# Library Overview
+
+`docforge` turns GSDFC-compliant Python docstrings into maintainable reference
+documentation. It never edits source docstrings; it reads them, renders them,
+and assembles documentation sites from all available material.
+
+---
+
+## 🧭 Which Build Should You Use?
+
+| Kind      | Source                     | Output                          |
+|-----------|----------------------------|---------------------------------|
+| `lib`     | GSDFC docstrings           | `docs/lib/**` rendered markdown |
+| `api`     | OpenAPI JSON spec          | `docs/api/**` rendered markdown |
+| `wiki`    | Hand-written markdown      | `docs/wiki/**` (unchanged)      |
+| `mcp`     | GSDFC docstrings + renderers | `docs/mcp/**` structured JSON |
+
+---
+
+## 🏗️ Architecture
+
+Each enabled site kind produces its own MkDocs configuration and build:
+
+1. `--mkdocs` (lib) writes `docs/mkdocs.lib.yml` and builds `site/lib/`.
+2. `--api` writes `docs/mkdocs.api.yml` and builds `site/api/`.
+3. `--wiki` writes `docs/mkdocs.wiki.yml` and builds `site/wiki/`.
+
+Every site is self-contained (own theme assets and search index) with
+navigation derived or scoped to that kind. Hand-written wiki content is never
+overwritten or regenerated — only its navigation is derived automatically.
+
+---
+
+## 🔄 Lifecycle Rules
+
+`docs/mcp/**` is a self-contained, machine-readable reference generated from
+docforge's own GSDFC docstrings. `doc-forge serve --mcp --module docforge`
+serves it over MCP. See the [MCP Guide](05_development/04_mcp_guide.md).
+
+---
+
+## ➡️ Read Next
+- [02 – Components](02_components.md) · [03 – Conventions](03_conventions.md)

docs/wiki/02_components.md

@@ -0,0 +1,55 @@
+# Components
+
+`docforge` is split into four horizontal layers. Everything flows top to
+bottom through the CLI.
+
+---
+
+## 1. Loaders & Models
+
+The `docforge/loaders` package wraps `griffe` to extract modules, functions,
+classes, and Google-style docstring sections. Loaded data is normalized into
+the object model under `docforge/models` (`Project`, `Module`, `DocObject`).
+
+---
+
+## 2. Navigation
+
+`docforge/nav` parses `docforge.nav.yml` specs (`NavSpec`, `Resolver`, and the
+MkDocs nav emitter) and, since the wiki kind, derives wiki navigation from the
+file structure via `build_wiki_nav`.
+
+---
+
+## 3. Renderers
+
+`docforge/renderers` turn model data into artifacts:
+
+- `MkDocsRenderer` → `docs/lib/**` reference markdown
+- `MCPRenderer` → `docs/mcp/**` structured documentation
+
+---
+
+## 4. Servers
+
+`docforge/servers` serves generated artifacts over live protocols:
+
+- `MCPServer` → serves a pre-generated `docs/mcp/**` bundle through MCP
+  resources (`docs://index`, `docs://nav`, `docs://modules/{module}`)
+
+---
+
+## 5. CLI
+
+`docforge/cli` wires it all together:
+
+- `commands.py` — the `build` command and its `--mkdocs` / `--api` / `--wiki`
+  / `--mcp` modes
+- `mkdocs_utils.py` — per-kind config generation (`docs/mkdocs.{lib,api,wiki}.yml`)
+  with navigation re-rooted to each kind's `docs_dir`
+- `api_utils.py` — OpenAPI loading and API docs generation
+
+---
+
+## Related
+- [01 – Overview](01_overview.md) · [03 – Conventions](03_conventions.md)

docs/wiki/03_conventions.md

@@ -0,0 +1,58 @@
+# Conventions
+
+---
+
+## GSDFC docstrings
+
+All documented source uses the Google-Styled Doc-Forge Convention (GSDFC):
+`Args:`, `Returns:`, `Raises:`, and `Attributes:` sections with properly typed
+signatures.
+
+The authoritative GSDFC specification lives in the `docforge/__init__.py`
+package docstring, which is exported verbatim into
+`docs/mcp/modules/docforge.json`, so the MCP bundle is self-documenting.
+
+Key rules:
+
+1. Use parenthesized types in prose entries (`name (Type):`) that match the
+   signature types.
+2. Use `# Summary`, `# Examples`, and `# Notes` sections at module level.
+3. Use `Args:`, `Returns:`, `Raises:`, `Yields:`, `Notes:`, and `Example:`
+   sections at function and method level.
+4. Always update the matching `.pyi` stub alongside the `.py` implementation.
+5. Every distributable package ships a `py.typed` marker so type checkers
+   consume the authored signatures instead of `Any`.
+
+---
+
+## `.pyi` stubs and `py.typed`
+
+Every module ships a matching `.pyi` stub kept in sync with the `.py`
+implementation. When signatures change, update both files. Packages expose a
+`py.typed` marker so consumers and type checkers use the authored signatures.
+
+---
+
+## Wiki pages
+
+1. Hand-written markdown lives in `docs/wiki/**` and is never generated.
+2. File names use a numeric prefix: `01_overview.md`, `02_components.md`.
+3. Nested directories become nested navigation groups:
+   `05_development/01_environment.md` → group *Development*.
+4. `index.md` is the site `Home` at the root, and a section root inside a
+   directory.
+5. Navigation labels are derived by stripping the numeric prefix and applying
+   title case on the remaining words.
+
+---
+
+## Templates
+
+MkDocs config fragments live in `docforge/templates`. The `mkdocs.wiki.yml`
+fragment carries only the `search` plugin, since wiki pages contain no
+mkdocstrings directives.
+
+---
+
+## Related
+- [02 – Components](02_components.md) · [04 – Iterative Workflow](04_iterative_workflow.md)

docs/wiki/04_iterative_workflow.md

@@ -0,0 +1,61 @@
+# Iterative Workflow
+
+A docs build runs through the CLI in a single pass.
+
+---
+
+## 🚀 Build commands
+
+```bash
+# Library reference only
+doc-forge build --mkdocs --module docforge
+
+# Wiki + library (each an independent MkDocs build)
+doc-forge build --wiki --mkdocs --module docforge
+
+# Wiki only — no module required
+doc-forge build --wiki --site-name docforge
+
+# MCP structured bundle
+doc-forge build --mcp --module docforge
+```
+
+---
+
+## 🔄 What a build does
+
+1. Validates the requested modes (`--mkdocs`, `--api`, `--wiki`, `--mcp`).
+2. Generates library sources under `docs/lib/**` with `MkDocsRenderer`.
+3. Generates API sources under `docs/api/**` when `--api` is given.
+4. Derives the wiki navigation from `docs/wiki/**`.
+5. Writes one MkDocs config per site kind (`docs/mkdocs.{lib,api,wiki}.yml`),
+   re-rooting navigation paths to each kind's `docs_dir`.
+6. Runs `mkdocs build` once per config, emitting self-contained sites
+   `site/lib/`, `site/api/`, and `site/wiki/`.
+
+---
+
+## 🧭 Explore the sites
+
+```bash
+doc-forge build --wiki --mkdocs --module docforge
+doc-forge serve --wiki       # serves site preview from docs/mkdocs.wiki.yml
+doc-forge serve --lib
+doc-forge serve --api
+# or target any config directly:
+doc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml
+```
+
+---
+
+## 📦 Serve the MCP bundle
+
+```bash
+doc-forge build --mcp --module docforge
+doc-forge serve --mcp --module docforge
+```
+
+---
+
+## Related
+- [03 – Conventions](03_conventions.md) · [01 – Environment](05_development/01_environment.md)

docs/wiki/05_development/01_environment.md

@@ -0,0 +1,30 @@
+# Environment Setup
+
+---
+
+## 🚀 Create the environment
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate
+pip install -e .
+```
+
+Requires Python 3.10+ (per `pyproject.toml`).
+
+---
+
+## 📦 Dependencies
+
+Development extras include:
+
+- `pytest`, `pytest-cov` — test suite and coverage
+- `ruff` — lint and format checking
+- `black` — auto-formatting
+- `mypy` — strict typing checks
+- `pydoclint` — docstring ↔ signature consistency checks
+
+---
+
+## Related
+- [04 – Iterative Workflow](../04_iterative_workflow.md) · [02 – Quality Gates](02_quality_gates.md)

docs/wiki/05_development/02_quality_gates.md

@@ -0,0 +1,34 @@
+# Quality Gates
+
+Run all checks before pushing:
+
+---
+
+## 🚀 Commands
+
+```bash
+.venv\Scripts\python.exe -m pytest
+.venv\Scripts\python.exe -m ruff check docforge tests
+.venv\Scripts\python.exe -m black --check docforge tests
+.venv\Scripts\python.exe -m mypy docforge
+.venv\Scripts\pydoclint.exe docforge
+```
+
+---
+
+## 📁 Test layout
+
+| Path                     | Covers                             |
+|--------------------------|------------------------------------|
+| `tests/nav/`             | Nav spec, resolver, wiki nav       |
+| `tests/cli/`             | Build command flows and modes      |
+| `tests/renderers/`       | MkDocs / MCP rendering             |
+
+CLI tests use the `cli_runner` fixture with `mock_mkdocs_build` and
+`mock_mkdocs_load_config` so they exercise the full flow without invoking a
+real MkDocs build.
+
+---
+
+## Related
+- [01 – Environment](01_environment.md) · [03 – GSDFC Guide](03_gsdfc_guide.md)

docs/wiki/05_development/03_gsdfc_guide.md

@@ -0,0 +1,129 @@
+# GSDFC Docstring Guide
+
+This page is the practical companion to the authoritative GSDFC specification
+in the `docforge/__init__.py` package docstring. It describes how to write
+docstrings that render correctly in MkDocs and stay machine-parseable by
+doc-forge, MkDocs, and MCP clients.
+
+---
+
+## 🧭 Overview
+
+- Docstrings are the single source of truth.
+- `doc-forge` compiles docstrings but never rewrites them.
+- Every public symbol should have a complete, accurate docstring.
+- Type hints live in signatures; prose entries repeat the type in
+  parentheses and must match the signature.
+
+---
+
+## 📦 Module docstrings
+
+Modules use Markdown headings and `---` separators.
+
+Recommended sections:
+
+- `# Summary` — what the subsystem does
+- `# Examples` — a representative usage snippet
+- `# Notes` — guarantees, lifecycle, and thread-safety notes
+
+---
+
+## 📦 Class docstrings
+
+Recommended sections, in order:
+
+- summary line describing responsibility
+- `Attributes:` — instance attributes with `name (Type):` entries
+- `Notes:` — grouped subsections such as **Guarantees**, **Lifecycle**
+- `Example:` — indented `python` code block
+
+---
+
+## 📦 Function and method docstrings
+
+Recommended section order:
+
+1. `Args:`
+2. `Returns:`
+3. `Raises:`
+4. `Yields:`
+5. `Notes:`
+6. `Example:`
+
+Formatting rules:
+
+- `Args:` entries are `name (Type):` followed by an indented description.
+- `Returns:` entries are `Type:` followed by an indented description.
+- `Raises:` entries are `ExceptionType:` followed by an indented condition.
+- `Yields:` replaces `Returns:` for generators.
+- Summaries are written in the imperative mood.
+- Fenced `python` blocks are allowed inside `Example:` sections, indented
+  four spaces.
+
+---
+
+## 📦 Property docstrings
+
+Properties document their return values with a `Returns:` section and, when
+meaningful, an `Example:`.
+
+---
+
+## 🚀 Example
+
+```python
+def process(foo: Foo, multiplier: int) -> int:
+    """Process a Foo instance.
+
+    Args:
+        foo (Foo):
+            Foo instance to process.
+
+        multiplier (int):
+            Value used to scale foo.
+
+    Returns:
+        int:
+            Processed result.
+
+    Raises:
+        ValueError:
+            If multiplier is negative.
+
+    Example:
+        Process foo:
+
+            ```python
+            foo = Foo("example", value=10)
+            result = process(foo, multiplier=2)
+            print(result)
+            ```
+    """
+```
+
+---
+
+## 🔄 Keeping stubs in sync
+
+Every `.py` module ships a matching `.pyi` stub. When a signature or a public
+symbol changes, update both files. Signature annotations in the stub must
+match the implementation.
+
+---
+
+## 🛡️ Enforcement
+
+`pydoclint` (Google style) runs in CI and verifies that `Args:`/`Returns:`
+sections match function signatures, including types.
+
+- `allow-init-docstring = true` — `__init__` docstrings are allowed.
+- `skip-checking-raises = true` — `Raises:` sections are descriptive and are
+  not required to map to literal `raise` statements.
+- `check-class-attributes = false` — `Attributes:` sections document instance
+  attributes without class-level annotations.
+
+---
+
+## Related
+- [02 – Quality Gates](02_quality_gates.md) · [04 – MCP Guide](04_mcp_guide.md)

docs/wiki/05_development/04_mcp_guide.md

@@ -0,0 +1,62 @@
+# MCP Guide
+
+Doc-forge can export a machine-readable **MCP bundle** from a project's
+GSDFC docstrings and serve that bundle over the Model Context Protocol (MCP).
+The bundle is self-contained: readers can derive the full API reference —
+signatures, docstrings, and structure — for the documented project.
+
+---
+
+## 🚀 Building the bundle
+
+```bash
+doc-forge build --mcp --module docforge
+```
+
+This writes structured JSON into `docs/mcp/`:
+
+- `index.json` — project metadata and module count
+- `nav.json` — module list with `docs://modules/{module}` resource URIs
+- `modules/{dotted.path}.json` — per-module serialized documentation
+
+---
+
+## 🚀 Serving the bundle
+
+```bash
+doc-forge serve --mcp --module docforge
+```
+
+The `MCPServer` (in `docforge/servers/mcp_server.py`) exposes:
+
+| Resource             | Description                       |
+|----------------------|-----------------------------------|
+| `docs://index`       | Project metadata                  |
+| `docs://nav`         | Navigation structure              |
+| `docs://modules/{module}` | Individual module documentation |
+
+The server also registers a single diagnostic tool, `ping`, and is read-only.
+Missing resources are returned as structured error dictionaries rather than
+exceptions. The default transport is `streamable-http`; `stdio` and `sse` are
+supported via `MCPServer.run`.
+
+---
+
+## 📦 Bundle contents
+
+Each module resource contains:
+
+- `path` — dotted module path
+- `docstring` — the raw GSDFC module docstring
+- `objects` — a recursive mapping of public symbols with `name`, `kind`,
+  `path`, `signature`, and `docstring`, plus nested `members`
+
+Because the bundle is generated from docstrings, the quality of the bundle
+equals the quality of the project's GSDFC docstrings. For docforge itself,
+the GSDFC specification is carried in `modules/docforge.json` via the
+`docforge/__init__.py` package docstring, making the bundle self-documenting.
+
+---
+
+## Related
+- [03 – GSDFC Guide](03_gsdfc_guide.md) · [05 – MkDocs Configs](05_mkdocs_configs.md)

docs/wiki/05_development/05_mkdocs_configs.md

@@ -0,0 +1,59 @@
+# MkDocs Configuration Model
+
+Each documentation kind (lib, api, wiki) is built by its own MkDocs site. A
+repo that documents kind `{kind}` carries a config at `docs/mkdocs.{kind}.yml`
+that sets `docs_dir` to the kind's source directory and `site_dir` to
+`../site/{kind}`.
+
+---
+
+## 📄 File wins
+
+`docs/mkdocs.{kind}.yml` is a repo-owned file, not a build byproduct:
+
+- **Absent** — `doc-forge build --{kind}` materializes a copy from the
+  packaged templates (see below) and then builds `site/{kind}`.
+- **Present** — the build uses the file verbatim. Edits to the theme, palette,
+  plugins, markdown extensions, nav, or `site_dir` are respected as-is.
+- **`--refresh`** — force-regenerates the file from the templates,
+  replacing any local changes.
+
+Because a present file is never rewritten, rerunning a build is a no-op for
+versioned configs: the working tree stays clean.
+
+---
+
+## 🧩 Templates
+
+The built-in defaults live in `docforge/templates/`:
+
+| File                  | Role                                          |
+|-----------------------|-----------------------------------------------|
+| `mkdocs.common.yml`   | Shared theme + markdown extensions            |
+| `mkdocs.lib.yml`      | `mkdocstrings` handler for library reference  |
+| `mkdocs.api.yml`      | Swagger/OpenAPI plugins and API-side features |
+| `mkdocs.wiki.yml`     | Wiki look: horizontal `navigation.tabs` header, blue grey/teal palette, Roboto |
+
+A per-kind config is generated by deep-merging the common template with the
+kind fragment, then filling in generation-time values (`site_name`,
+`docs_dir`, `site_dir`, `nav`, API `site_description`/`site_author`, and the
+theme `icon` from `docforge.nav.yml`). Pass `--template <path>` to replace the
+built-in templates entirely.
+
+---
+
+## 🏗️ Supported layouts
+
+- **Per-kind config** — the standard layout; each kind builds to
+  `site/{kind}` and is served under `/<repo>/{kind}/`.
+- **Legacy root config** — a repo with a single kind may instead author root
+  `mkdocs.yml` (for example mongo-ops, whose wiki uses `docs_dir: docs/wiki`).
+  doc-forge never reads or writes root `mkdocs.yml`; the docs service maps the
+  kind to the root `site/` dir in this case.
+
+Commit `docs/mkdocs.{kind}.yml` so served docs are reproducible from source.
+
+---
+
+## Related
+- [04 – MCP Guide](04_mcp_guide.md)

docs/wiki/index.md

@@ -0,0 +1,325 @@
+# 🧩 docforge — Docstring-Driven Documentation Forge
+
+`docforge` is an internal documentation tool that generates reference documentation from Google-Styled Doc-Forge Convention (GSDFC) docstrings and assembles it into per-kind MkDocs sites, alongside hand-written wiki pages and OpenAPI-based API docs.
+
+> **Doc model:** this wiki is written for humans — how‑to guides, examples,
+> and testing recipes. The authoritative API contracts live in the code
+> (docstrings) and the machine‑readable bundle under `docs/mcp/`.
+
+---
+
+## 🚀 Key Features
+
+- 🧪 GSDFC docstring extraction via Griffe
+- 🧭 Auto-derived navigation for hand-written wiki pages
+- 🗂 Independent MkDocs builds per kind (lib, api, wiki) into `site/{kind}`
+- 🔌 Material MkDocs theming out of the box
+- 📦 MCP structured documentation resources
+
+---
+
+## 📦 Installation
+
+```bash
+# Internal PyPI (TBD)
+pip install docforge
+```
+
+---
+
+## 📁 Documentation Structure
+
+| Section                                      | Description                                        |
+|----------------------------------------------| -------------------------------------------------- |
+| [Overview](01_overview.md)                   | What docforge is and how it fits the pipeline      |
+| [Components](02_components.md)           | Loaders, models, nav, renderers, CLI, servers     |
+| [Conventions](03_conventions.md)             | GSDFC, `.pyi` stubs, and template conventions      |
+| [Iterative Workflow](04_iterative_workflow.md) | How a docs build runs end to end                  |
+| [Environment](05_development/01_environment.md) | Environment setup                              |
+| [Quality Gates](05_development/02_quality_gates.md) | Test layout and quality checks             |
+| [GSDFC Guide](05_development/03_gsdfc_guide.md) | How to write GSDFC-conformant docstrings        |
+| [MCP Guide](05_development/04_mcp_guide.md)  | Building, serving, and consuming the MCP bundle   |
+| [MkDocs Configs](05_development/05_mkdocs_configs.md) | MkDocs config generation and templates             |
+
+---
+
+## 🔗 Related Resources
+
+- **Source Code:** the `doc-forge` repository
+- **MCP Bundle:** generated by `doc-forge build --mcp --module docforge` into `docs/mcp/`
+- **Wiki Kind:** hand-written content lives in `docs/wiki/`; use the prompt in the
+  wiki-related resource below
+````markdown
+# AGENTS.md — Wiki Authoring Guide (Aetoskia)
+
+This file instructs AI agents how to create, extend, and maintain the wiki
+(`docs/wiki/**`) for any Aetoskia repository.
+
+> **Workflow:** this prompt covers **phase 2 only**. Phase 1 — writing GSDFC docstrings
+> (plus `.pyi` stubs and `py.typed`) — is done by the agent using the doc-forge MCP
+> bundle: `doc://modules/docforge` carries the full GSDFC spec. Write the wiki only
+> after docstrings exist and `doc-forge build --mcp --module <pkg>` produced the
+> repo's own bundle.
+
+---
+
+## 1. Doc model — know the two sources of truth
+
+Every repo keeps two distinct kinds of documentation that must **not** bleed
+into each other:
+
+| Kind              | Source                | Where                                    | Audience                           |
+|-------------------|-----------------------|------------------------------------------|------------------------------------|
+| **Wiki**          | Hand-written markdown | `docs/wiki/**`                           | Humans (how-to, examples, testing) |
+| **API reference** | Docstrings (GSDFC)    | Generated → `docs/lib/**`, `docs/mcp/**` | Consumers (exact contracts)        |
+
+Rules:
+
+- The wiki is written **for humans** — how-to guides, recipes, and testing
+  patterns. It is never generated.
+- API contracts (signatures, parameter types, exact behavior) live in the
+  docstrings and the machine-readable bundle under `docs/mcp/`. **Never**
+  duplicate full API documentation in the wiki — link to the lib site instead.
+- If a page starts to drift into contract territory, cut it down to usage and
+  point at `docs/lib/`.
+- This doc model is stated on every index page as a blockquote; keep it there:
+  > **Doc model:** this wiki is written for humans — how‑to guides, examples,
+  > and testing recipes. The authoritative API contracts live in the code
+  > (docstrings) and the machine‑readable bundle under `docs/mcp/`.
+
+---
+
+## 2. Directory layout & file naming
+
+```
+docs/wiki/
+├── index.md                      # site Home
+├── 01_overview.md
+├── 02_components.md
+├── 03_use_cases/                 # nested directory → nav group
+│   ├── 01_basic_crud.md
+│   ├── 02_custom_repo.md
+│   └── ...
+├── 04_best_practices.md
+├── 06_error_handling.md
+└── 07_testing_example.md
+```
+
+- Location: `docs/wiki/` (hand-written only).
+- File names: `NN_snake_case_name.md` with a **zero-padded two-digit** numeric
+  prefix. e.g. `01_overview.md`, `03_use_cases/07_caching.md`.
+- Top-level pages use `NN_name.md` directly. High-volume sections get their own
+  directory, e.g. `03_use_cases/NN_name.md` (nav group "Use Cases").
+- **No frontmatter.** Every file opens directly with an H1 `# Title`.
+- Navigation labels are short human titles set explicitly in
+  `docs/mkdocs.wiki.yml` (title case) — often **shorter** than the page H1.
+  Example: nav label `Basic CRUD` vs page H1 `Use Case 1: Basic FastAPI CRUD API`.
+  Never use the raw filename slug as the label.
+- Renumbering: prefixes order pages. When inserting a page, pick the next
+  number in the relevant group (subgroup numbers stay grouped).
+
+---
+
+## 3. Navigation — `docs/mkdocs.wiki.yml` is the source of truth
+
+Every wiki page **must** be wired into the nav defined in
+`docs/mkdocs.wiki.yml`. If a page is not in the nav, it is orphaned.
+
+- The `nav:` block mirrors the directory tree; directories become nested
+  groups.
+- When a section has many pages, group them **by theme** into nested
+  subgroups. mongo-ops groups its use cases into:
+  `Getting Started`, `Data & Queries`, `Caching`, `Population`,
+  `Advanced Usage`.
+- Keep `index.md`'s **Documentation Structure** table in sync with the nav —
+  it is the human-facing version of the same TOC. Every nav entry needs a row
+  (or nested bullet group) there.
+- Nav label = human title (title case), not the filename slug.
+
+---
+
+## 4. Page anatomy
+
+### 4.1 `index.md` (Home)
+
+```
+# 🧩 <package> — <slogan>
+<one-paragraph pitch>
+
+> **Doc model:** …   (see §1)
+
+---
+
+## 🚀 Key Features         (bullet list, emoji per feature)
+## 📦 Installation         (code blocks: internal PyPI, extras, local source)
+## 📁 Documentation Structure   (table = TOC, mirrors nav exactly)
+## 🔗 Related Resources    (bullets: source repo, internal PyPI, CI)
+---
+© Aetoskia Internal — `<package>` <version>
+```
+
+### 4.2 Overview page (`01_*`)
+
+- Opens with `# Library Overview`, one sentence about what the library does,
+  then a line stating the page builds the mental model.
+- Sections: `## 🏗️ Architecture` (ASCII diagram + numbered layer list),
+  `## 🔄 Lifecycle Rules` (table: step / call / why),
+  `## 🧭 Which … Should You Use?` (decision table).
+- Ends with `## ➡️ Read Next` (cross-links to the next pages to read).
+
+### 4.3 Components page (`02_*`)
+
+- Validated reference for the public API surface — describes what each
+  component is for and how the pieces wire together. Keep it usage-level;
+  exact signatures belong in `docs/lib/`.
+- Anatomy: numbered sections, one per component (`## 1. MongoConnectionManager`,
+  `## 2. BaseDocument`, …), with `### 8.1`-style sub-numbering for related
+  types under a component (e.g. the cache layer's backend / stats / config /
+  in-memory / redis implementations). Ends with `## Related`.
+
+### 4.4 Use-case page (the most common)
+
+Standard anatomy, in this order:
+
+```
+# Use Case N: <Human Title>
+
+**Scenario:** <one sentence: the problem this recipe solves>
+
+---
+
+## 📦 What's New?        (table: Component | Description — new API used here)
+## 🚀 Example            (languaged code block, complete runnable-looking snippet)
+## 💡 Tips               (bullets: gotchas, ordering, common mistakes)
+## Related               (§5)
+```
+
+### 4.5 Deep-dive / worked-example page
+
+For intricate flows (population shapes, cache round-trips), use numbered
+depth-first sections and comparison tables:
+
+```
+## 1. <Write path>              (### 1a., ### 1b., … per sub-case)
+## 2. <Read path>
+## 3. <Round trip / tricky bit>
+## 4. When to use which         (comparison table)
+## Related
+```
+
+### 4.6 Best Practices page (`04_*`)
+
+- Flat themed `##` sections (e.g. Layering, Lifecycle, Data & Performance,
+  Transactions & Errors, Testing), each a short list of numbered conventions.
+- Pure prose — no large code blocks.
+
+### 4.7 Error Handling (`06_*`) / Testing pages
+
+- **Error Handling:** an exceptions table (`Exception | Source | Meaning / fix`),
+  a `> ` note on which failures are by design, a `## 🚀 FastAPI Mapping Example`
+  code block, then `## 💡 Tips` bullets, then `## Related`.
+- **Testing example (`07_*`):** `## 🚀 Mock-Based Quickstart` (focused code
+  block), `## 💡 Notes` tip list, `## Related`.
+
+Common to all pages: no frontmatter, `---` between every major section, and a
+`## Related` (or variant) footer as the **last** section.
+
+---
+
+## 5. The `## Related` footer
+
+Every page ends with a cross-link footer. Rules:
+
+- Always the **last** section, always preceded by a `---`.
+- Standard heading: `## Related` (no emoji).
+- One bullet line; links separated by ` · ` (middle dot plus spaces).
+- Link label format: `[NN – Title](relative_path)` — en-dash, page number, title.
+- Paths are **relative**: same directory → `02_custom_repo.md`; parent →
+  `../01_overview.md`; child → `03_use_cases/01_basic_crud.md`.
+- Link order follows nav order (each `Related` points to related next/sibling
+  pages, plus the overview/components anchor).
+
+Examples (from mongo-ops):
+
+```
+## Related
+- [02 – Custom repository](02_custom_repo.md) · [04 – Pagination](04_pagination.md) · [Overview](../01_overview.md)
+```
+
+Variants:
+
+- `## ➡️ Read Next` — used on the overview page (linear reading order).
+- `## 🔗 Related Resources` — only on `index.md`, one bullet per external resource.
+
+---
+
+## 6. Tone & formatting rules
+
+- **Written for humans**: short sentences, concrete examples, plain words.
+- Emoji-prefixed H2 headings for recognizable section types
+  (`📦 What's New?`, `🚀 Example`, `💡 Tips`, `🚀 Key Features`).
+- `---` horizontal rule between every major section.
+- Code blocks always declare a language (```python, ```bash, etc.).
+- Use tables for comparisons and structured decisions; bullets for lists;
+  ASCII diagrams for architecture.
+- Bold key terms inline. Use `inline code` for symbols/APIs.
+- Keep pages focused: one recipe/purpose per page. If a page balloons past
+  ~10 KB, split it (add a numbered deep-dive page instead).
+- Match tone of existing pages in the repo before writing new ones.
+- Ground every `## 🚀 Example`, `💡 Tips`, and `📦 What's New?` row in the
+  library's actual source, tests, and its `docs/mcp` bundle — never invent
+  APIs or behavior. Signatures and exceptions come from the code; gotchas
+  come from the tests.
+
+---
+
+## 7. Build & verify workflow
+
+After creating or editing wiki pages:
+
+```bash
+# 1. Build the wiki (from the repo root)
+doc-forge build --wiki                       # wiki only
+doc-forge build --wiki --mkdocs --module <pkg>   # wiki + lib together
+
+# 2. Preview locally
+doc-forge serve --wiki
+
+# 3. Collect into the hub (run from the docs/ service repo)
+python collect.py                            # copies site, regenerates index + nginx.conf
+python collect.py --dry-run                  # preview without writing
+```
+
+Verification checklist:
+
+- `doc-forge build --wiki` completes with no warnings about missing files.
+- Every new page is present in `docs/mkdocs.wiki.yml` **and** in the index
+  Documentation Structure table.
+- Every page ends with a `## Related` block and no dead links (paths resolve).
+- After `collect.py`: the hub card links to both `/wiki/` and `/lib/` and the
+  pages render (spot-check with the served site).
+- If code/docstrings changed (no change when wiki-only), run the repo gates:
+  `black`, `ruff`, `mypy`, `pytest`.
+
+---
+
+## 8. Before/after checklist
+
+**Before creating a page:**
+
+- [ ] Confirm it is genuinely wiki material (how-to) and not API contract.
+- [ ] Find the right filename (`NN_snake_case.md`) and directory for its theme.
+- [ ] Outline the sections per §4 anatomy that fits the content.
+
+**After creating/editing a page:**
+
+- [ ] Page wired into `docs/mkdocs.wiki.yml` nav (themed subgroup if needed).
+- [ ] `index.md` Documentation Structure table updated.
+- [ ] `## Related` footer present, relative links, nav order.
+- [ ] `---` separators consistent; no frontmatter; emoji headings where apt.
+- [ ] Build passes; collect run; hub shows `/wiki/` + `/lib/` links.
+- [ ] No orphaned files, no dead links.
+````
+---
+
+© Aetoskia Internal — `docforge` 1.0