# 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 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) ``` # 🧩 — > **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 — `` ``` ### 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: **Scenario:** --- ## 📦 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. (### 1a., ### 1b., … per sub-case) ## 2. ## 3. ## 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. --- ## 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 # 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.