doc-forge/WIKI.md

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. The reference implementation is mongo-ops — its wiki went through several revisions to reach the structure below and should be treated as the canonical example.

---

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 derived from the page title, not the filename.
• 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/wiki/../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/.

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

• Scenario-style: explain the failure modes / test approaches, a 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.

---

7. Build & verify workflow

After creating or editing wiki pages:

# 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.