feat(standards): serve service version-wiring rule + bundle wiki pages in MCP

Versioning standard now states services must read their VERSION (e.g. a build arg) rather than hardcoding it; the compliance prompt repeats it. build_bundle also bundles src/wiki/** as wiki_-prefixed modules (e.g. docs://modules/wiki_development_releasing), so the release runbook is reachable from the MCP. Bundle grows to 22 modules.

build.py

@@ -99,13 +99,26 @@ def _read_title(path: Path) -> str:
     return _module_name(path.stem).replace("_", " ").title()
 
 
+def _wiki_module_name(rel: Path) -> str:
+    """Map a wiki page path to a namespaced module name.
+
+    ``04_development/02_releasing.md`` -> ``wiki_development_releasing``; the
+    ``wiki_`` prefix keeps wiki pages from colliding with lib modules (both have
+    an ``index``).
+    """
+    parts = [NUM_PREFIX.sub("", part) or part for part in rel.with_suffix("").parts]
+    return "wiki_" + "_".join(parts)
+
+
 def build_bundle(folder: Path, dry_run: bool = False) -> None:
-    """Regenerate ``<name>/mcp`` from ``folder/src/lib`` markdown.
+    """Regenerate ``<name>/mcp`` from ``folder/src/lib`` and ``folder/src/wiki``.
 
     The bundle mirrors the lib site (in the same way doc-forge's MCP output
     mirrors its lib documentation). Writes ``index.json``, ``nav.json`` and
     ``modules/*.json`` in the doc-forge MCP bundle shape. Hand-authored extras
-    (e.g. ``libraries.json``) are left untouched.
+    (e.g. ``libraries.json``) are left untouched. Wiki pages (``src/wiki/**``)
+    are also bundled, under a ``wiki_`` namespaced module name, so the runbooks
+    are reachable from the MCP.
 
     Args:
         folder (Path): The hub folder owning a ``src/lib``.
@@ -149,6 +162,17 @@ def build_bundle(folder: Path, dry_run: bool = False) -> None:
             "title": _read_title(path),
         })
 
+    wiki = folder / "src" / "wiki"
+    if wiki.is_dir():
+        for path in sorted(wiki.rglob("*.md")):
+            module = _wiki_module_name(path.relative_to(wiki))
+            write_module(module, path.read_text(encoding="utf-8"))
+            nav.append({
+                "module": module,
+                "resource": f"docs://modules/{module}",
+                "title": _read_title(path),
+            })
+
     (out_dir / "nav.json").write_text(
         json.dumps(nav, indent=2, ensure_ascii=False), encoding="utf-8"
     )

registry.py

@@ -107,7 +107,8 @@ _COMPLIANCE_TEXT = (
     "  from `get_drone_template(\"drone-pypi\")` (`python-lib.yaml`, tag-triggered).\n"
     "- **service / site** — root `VERSION`; root `CHANGELOG.md`; Drone file from\n"
     "  `get_drone_template(\"drone-service\")` (`service-docker.yaml`; tag-triggered\n"
-    "  service variant, push-triggered site variant).\n\n"
+    "  service variant, push-triggered site variant). The service must read its\n"
+    "  version from `VERSION` (e.g. a build arg) — never hardcode it.\n\n"
     "Steps:\n"
     "1. Inspect each repo (`git -C <path> tag`, version file, `CHANGELOG.md`,\n"
     "   `.drone.yml`) and list the gaps — never assume.\n"

standards/lib/11_versioning_and_changelog/index.html

@@ -869,7 +869,7 @@ and tag contract is exactly what those two CI shapes consume.</p>
 <tr>
 <td>Service / site (Docker)</td>
 <td><code>VERSION</code> file at the repo root</td>
-<td>one line, <code>x.y.z</code></td>
+<td>one line, <code>x.y.z</code>; the service <strong>reads</strong> it (build-arg) — never hardcode the version</td>
 </tr>
 </tbody>
 </table>

standards/mcp/index.json

@@ -1,6 +1,6 @@
 {
   "project": "standards",
   "type": "standards",
-  "modules_count": 16,
+  "modules_count": 22,
   "source": "hand-authored"
 }

standards/mcp/modules/wiki_development_releasing.json

@@ -0,0 +1,8 @@
+{
+  "module": "wiki_development_releasing",
+  "content": {
+    "path": "wiki_development_releasing",
+    "docstring": "# Releasing & Versioning\n\nHow to cut a release of any Aetos repository. The rule lives in the reference\npage [Versioning & Changelog](../lib/11_versioning_and_changelog/); this is the\nrunbook you follow.\n\nEvery repository is one of two Drone shapes — a **PyPI package** or a **Docker\ndeployment** ([Drone Pipelines](../lib/10_drone_pipelines/)). Both release the\nsame way: the version bump and changelog promotion go **in the merge request**,\nand the tag is created on the merged commit.\n\n---\n\n## 🧾 Before you start\n\n- You have an open **merge request** holding the change, and `main` is green\n  (the Drone quality gate passed on the last run).\n- You know whether this is a **breaking**, **feature**, or **fix** release.\n- The version file exists:\n  - package → `version` in `pyproject.toml`\n  - service / site → `VERSION` at the repo root\n\n---\n\n## 🚦 Pick the next version\n\nThe version file and the tag must be identical. For `0.y.z`, `0.y` is the major\nline (see the reference page); once at `1.0.0`, normal SemVer applies.\n\n| Change | `0.y.z` → | `1.0.0+` → |\n|--------|-----------|------------|\n| Breaking | `0.(y+1).0` | `(x+1).0.0` |\n| Feature | `0.y.(z+1)` | `x.(y+1).0` |\n| Fix | `0.y.(z+1)` | `x.y.(z+1)` |\n\n---\n\n## 🌿 Release in the MR\n\nThe version is known while the change is still a merge request, so the bump\nrides along with it. Do both edits **in the MR**:\n\n- **Promote the changelog** in `CHANGELOG.md`: move the `[Unreleased]` content\n  under a new `## [x.y.z] - YYYY-MM-DD` heading, leave a fresh empty\n  `[Unreleased]` on top, and add the compare links — naming the **version/tag**,\n  never a commit id:\n\n  ```markdown\n  [Unreleased]: https://git.aetoskia.com/aetos/<repo>/compare/x.y.z...HEAD\n  [x.y.z]: https://git.aetoskia.com/aetos/<repo>/compare/x.y.(z-1)...x.y.z\n  ```\n\n- **Bump the version file** to the intended release version: `version = \"x.y.z\"`\n  in `pyproject.toml` (packages) or the `VERSION` file (services/sites).\n\n---\n\n## 🏷️ Tag the merged commit\n\n1. **Merge or squash** the MR into `main`.\n2. **Create the tag** on the resulting commit: `git tag x.y.z` (lightweight).\n3. **Push the tag** (`git push origin x.y.z`) — Drone builds the release.\n\n### 🤖 Agent-assisted tagging\n\nThe agent does not author or merge the MR and never tags before the merge. After\nyou confirm the MR is merged/squashed and tell it to proceed, the agent:\n\n1. Waits for that explicit go-ahead.\n2. Finds the commit that introduced the bump:\n   - package:\n     `git log -S 'version = \"x.y.z\"' -n 1 --format='%H %s' -- pyproject.toml`\n   - service / site:\n     `git log -S 'x.y.z' -n 1 --format='%H %s' -- VERSION`\n3. Verifies that commit's version file equals `x.y.z`, then tags **only** that\n   commit: `git tag x.y.z <sha>`.\n4. Does **not** push — it asks you to run `git push origin x.y.z`.\n\n---\n\n## 🤖 What Drone does\n\n- **Type A (package):** asserts `tag == pyproject version`, then skips if that\n  version already exists on the index, runs the quality gate, builds, and\n  uploads the wheel + sdist.\n- **Type B (service):** asserts `tag == VERSION`, resolves the tag, skips if the\n  image already exists, runs the quality gate, builds, pushes, and restarts the\n  container.\n- **Type B (site):** triggered on push, ships `:latest` and has no tag guard.\n\nIf the guard fails, nothing is published — fix the version file, amend the\ncommit, and move the tag **only** if it was never pushed.\n\n---\n\n## 🛟 Backfill / recovery\n\nIf an older tag never published (a past version-file mismatch, an index\noutage):\n\n- **Package:** run the `backfill-pypi-from-tags` pipeline (custom event). It\n  checks out every tag, verifies `tag == pyproject version` at that commit,\n  and uploads the ones missing from the index. Already-fixed history is never\n  rewritten.\n- **Service:** rebuild the image for the missing tag with a fresh commit and a\n  new patch version; do not move a published tag.\n\n---\n\n## 🔁 If a release is wrong\n\n- Never reuse or force-move a pushed tag.\n- Fix forward: bump to the next patch, promote the changelog, tag again.\n\n---\n\n## Related\n\n- [Testing & Quality Gates](01_testing.md) · [Versioning & Changelog](../lib/11_versioning_and_changelog/) · [Drone Pipelines](../lib/10_drone_pipelines/)\n",
+    "objects": {}
+  }
+}

standards/mcp/modules/wiki_development_testing.json

@@ -0,0 +1,8 @@
+{
+  "module": "wiki_development_testing",
+  "content": {
+    "path": "wiki_development_testing",
+    "docstring": "# Testing & Quality Gates\n\nTwo suites run under pytest with asyncio auto mode: **integration** (the HTTP\nedge against fakes) and **unit** (pure domain and pipeline logic). Finish a\nblueprint app only when every gate below passes.\n\n---\n\n## 🗂️ Layout\n\n```\ntests/\n    integration/     # TestClient(app) + mocked resources\n    unit/            # models, converters, pipeline stages/roots\n    conftest.py      # fixtures\n```\n\n---\n\n## 🚀 Integration tests\n\n- Build the app with `TestClient`.\n- Replace `app.state.db_resources` with fake repositories/services so no database\n  is required.\n- Patch the auth introspection call (`httpx.AsyncClient.post`) to return a\n  canned identity.\n- Assert status codes and bodies for list/get/create/update/delete, plus\n  `400`, `404`, `204`, and the streaming endpoint's fallback.\n\n```python\nclient = TestClient(app)\napp.state.db_resources = {\"item_svc\": FakeItemService(), ...}\n\ndef test_create_item():\n    r = client.post(\"/items\", json={\"name\": \"x\"})\n    assert r.status_code == 200\n```\n\n---\n\n## 🧪 Unit tests\n\n- Domain models and converters: pure, no I/O.\n- Pipeline stages: feed a fixture state, assert the transformed state.\n- Assembled pipeline roots: **fixture parity** — replay a stored fixture input\n  and compare against a golden output file.\n\n---\n\n## 🔐 Config-consistency tests\n\nFor rule-driven pipelines, add a test that cross-references rules against the\ndeclared pattern registry: every flag emitted must be defined; every defined\nflag must be reachable. This catches drift without running the pipeline.\n\n---\n\n## ✅ Quality gates\n\nA **definition of done** for any standard app:\n\n- `python -c \"import main\"` succeeds.\n- `pytest` passes.\n- The app serves the spec's operations; the worker drains its queue.\n- No domain module imports a web framework.\n- No infrastructure was reimplemented that a library already provides.\n\n---\n\n## 💡 Conventions\n\n- `asyncio_mode = \"auto\"`; no manual event loops.\n- Fixtures are checked into the repo (inputs + golden outputs).\n- Tests skip (not fail) when a required fixture is absent.\n- Do not mock the domain; mock only the infrastructure edge.\n\n---\n\n## Related\n\n- [02 – App Components](../02_components.md) · [03 – Start an App](../03_start_an_app.md) · [Overview](../01_overview.md)\n",
+    "objects": {}
+  }
+}

standards/mcp/modules/wiki_index.json

@@ -0,0 +1,8 @@
+{
+  "module": "wiki_index",
+  "content": {
+    "path": "wiki_index",
+    "docstring": "# 🧩 Standards — the Aetos App Blueprint\n\nOne reusable architecture for every backend application in the Aetos ecosystem:\na spec-first HTTP edge, a framework-free domain core, a pluggable infrastructure\nlayer, and a single composition root.\n\nFill in **two axes only** and a new app is done: your **resource model**, and\n(if needed) your **pipeline family**. The blueprint itself never names a\nbusiness domain — expenses, health metrics, inventory, and analytics are all\nthe same shape underneath.\n\n> **Doc model:** this wiki is written for humans — how-to guides, the build\n> recipe, and quality gates. The enforceable rules (layering, composition root,\n> CRUD template, pipeline scaffold) and the library registry live in the\n> **reference** pages, mirrored by the machine-readable `standards` MCP bundle.\n> Query `find_library` before writing any infrastructure.\n\n---\n\n## 🚀 Key Features\n\n- 🧭 **Spec-first routing** — the OpenAPI document, not decorator routers, is\n  the source of truth (operationId lookup)\n- 🏗️ **One-way layering** — `interfaces → domain → infra`, enforced\n- 🔌 **Single composition root** — every dependency is wired in exactly one place\n- 🧩 **Generic, not app-specific** — reusable rules versus two authoring axes\n- 📚 **Library-backed** — DB, DI, pipelines, ingestion, auth, and docs come from\n  internal libraries, never hand-written\n- 🚦 **Explicit state machines** — durable job statuses, progress, and\n  human-in-the-loop pauses\n\n---\n\n## 📁 Documentation Structure\n\n| Section                                             | Description                                            |\n|-----------------------------------------------------|--------------------------------------------------------|\n| [Overview](01_overview.md)                          | Philosophy, the one-way dependency rule, architecture  |\n| [App Components](02_components.md)                  | The component model and how the pieces wire together   |\n| [Start an App](03_start_an_app.md)                  | The entry point: gather the two axes, then build       |\n| [Testing & Quality](04_development/01_testing.md)   | Test layout and acceptance gates                       |\n\n**Reference** (separate site, mirrors the MCP bundle): the enforceable\nrules — [Build Recipe](../lib/01_build_recipe/), [Layering](../lib/02_layering_rules/), [Composition\nRoot](../lib/03_composition_root/), [Spec-First\nRouting](../lib/04_spec_first_routing/), [CRUD\nTemplate](../lib/05_crud_template/), [Pipeline\nScaffold](../lib/06_pipeline_scaffold/), [Worker &\nProgress](../lib/07_worker_and_progress/), [Human-in-the-Loop](../lib/08_human_in_loop/),\n[Infra Adapters](../lib/09_infra_adaptors/), [Genericity\nMatrix](../lib/12_genericity_matrix/), [Library\nRegistry](../lib/13_library_registry/).\n\n---\n\n## 🔗 Related Resources\n\n- **MCP bundle** — `standards` server on `:8009`: read `docs://index`,\n  `docs://nav`, `docs://modules/{module}`; call `find_library(capability)`\n- **Library registry** — the catalog of internal libraries behind every app\n  (`libraries.json`, served as `registry://libraries`)\n- **Template** — the runnable skeleton at `standards/src/templates/app/`\n- **Start a build** — invoke the `start_app` prompt on the `standards` server,\n  or read the [Start an App](03_start_an_app.md) guide\n\n---\n\n© Aetoskia Internal — `standards`\n",
+    "objects": {}
+  }
+}

standards/mcp/modules/wiki_overview.json

@@ -0,0 +1,8 @@
+{
+  "module": "wiki_overview",
+  "content": {
+    "path": "wiki_overview",
+    "docstring": "# Overview\n\nThe blueprint is a **hexagonal (ports & adapters) application** with a\n**spec-first** web edge and a **single composition root**. It favors explicit\nwiring over implicit magic and existing internal libraries over hand-written\ninfrastructure. Start here to build the mental model; the enforceable details\nlive in the reference pages.\n\n---\n\n## 🏗️ Architecture\n\n```mermaid\nflowchart LR\n    subgraph EDGE[\"interfaces/ — HTTP edge\"]\n        OAS[\"openapi.yaml<br/>operationId contract\"]\n        RT[\"<resource>/routes.py<br/>thin handlers\"]\n    end\n\n    subgraph CORE[\"domain/ — business core\"]\n        MD[\"models\"]\n        PT[\"ports (adapter binding seam)\"]\n        SV[\"services\"]\n    end\n\n    subgraph INFRA[\"infra/ — adapters\"]\n        RP[\"mongo repos (mongo-ops)\"]\n        AD[\"cache · stores · llm · mail\"]\n        DB[(\"MongoDB\")]\n    end\n\n    CR[\"init.py<br/>composition root\"]\n\n    OAS --> RT\n    RT --> SV\n    SV --> PT\n    SV --> RP\n    PT -. depends on .- RP\n    CR --- RT\n    CR --- SV\n    CR --- RP\n    RP --> DB\n    AD --- CR\n```\n\nThe rule holds at every edge: code in an outer ring may depend on a ring closer\nto the core, never the reverse. `domain/` never imports a web framework;\nonly its `ports/` seam reaches into `infra/` to bind adapters.\n\n> **Legend** — solid arrows are compile-time calls; dotted arrows are the\n> port/adapter binding, performed by the composition root at startup.\n\n---\n\n## 🔄 The one-way dependency rule\n\n| Ring        | May import                         | Never imports                    |\n|-------------|------------------------------------|----------------------------------|\n| `interfaces/` | `domain`, framework glue (glue only) | business logic, `infra` directly |\n| `domain/`   | its own models + its `ports/` seam (which binds `infra`/libraries) | web frameworks, `interfaces/` |\n| `infra/`    | `domain` ports, drivers, libraries | —                                |\n| `init.py`   | everything (the wiring point)      | —                                |\n\n---\n\n## 🧭 Core principles\n\n1. **One-way dependencies.** `interfaces -> domain -> infra` is allowed; the\n   reverse is forbidden.\n2. **Ports in the domain, adapters in infra.** A service depends on a port; the\n   port's factory binds the concrete adapter, and the composition root calls\n   those factories.\n3. **One composition root.** Nothing constructs its own dependencies. All\n   wiring lives in one module (`init.py`) exposed as a flat resource registry.\n4. **Spec-first.** The HTTP contract is declared in `openapi.yaml`; route\n   handlers are looked up by `operationId`. There are no decorator routers.\n5. **Reuse the libraries.** Orchestration, DI, Mongo repositories, ingestion,\n   auth, and docs come from internal libraries — see the [Library\n   Registry](../lib/13_library_registry/).\n6. **Explicit state machines.** Long-running work moves through explicit,\n   durable statuses and can pause for human input.\n\n---\n\n## ⚙️ Runtime processes\n\nA standard app may run as up to three processes that share the same composition\nroot:\n\n| Process | Entry point            | Responsibility                            |\n|---------|------------------------|-------------------------------------------|\n| API     | `main.py`              | serve HTTP; start/stop resources via lifespan |\n| Worker  | `worker.py`            | poll durable jobs, run pipelines, publish progress |\n| Scripts | `python -m scripts.<name>` | one-shot operator tasks                  |\n\n---\n\n## ➡️ Read Next\n\n- [02 – App Components](02_components.md) · [03 – Start an App](03_start_an_app.md)\n",
+    "objects": {}
+  }
+}

standards/mcp/modules/wiki_start_an_app.json

@@ -0,0 +1,8 @@
+{
+  "module": "wiki_start_an_app",
+  "content": {
+    "path": "wiki_start_an_app",
+    "docstring": "# 🚀 Start an App\n\nThis is the entry point for building a new application from the blueprint. The\ngoal is one deterministic pass: you supply only the **two axes**, and the agent\ndoes the rest by reading the `standards` MCP, importing Tier A libraries, and\ncopying Tier B template components.\n\n> **Doc model:** this page is the human entry point. The deterministic,\n> machine-facing checklist lives in the reference page\n> [Build Recipe](../lib/01_build_recipe/), served as `docs://modules/build_recipe`.\n\n---\n\n## 🧾 What the agent needs from you\n\nGather these before starting — the `start_app` MCP prompt asks for them:\n\n1. **App name + one-line purpose.**\n2. **Axis 1 — resources.** Each resource, its fields, and relationships. Paste\n   `openapi.yaml` if you already have it.\n3. **Axis 2 — pipelines.** Only if an input needs a multi-step transformation:\n   the families and their input formats (or \"none\").\n4. **Auth needed now?** Default **no**. Auth is deferred (`py-jwt` primitives\n   only), and an authless app is just a spec with no `security` keys — see\n   [Spec-First Routing → Authless apps](../lib/04_spec_first_routing/#authless-apps).\n5. **Integrations.** Mongo, ingestion formats, email, LLM provider.\n\nIf you can state axes 1 and 2, the rest is mechanical.\n\n---\n\n## ▶️ How to start\n\nFrom an MCP client connected to the `standards` server:\n\n1. Invoke the **`intake`** prompt (or `start_app` with no arguments) to get the\n   intake questions.\n2. Answer them, then invoke **`build`**\n   (`build(app_name=..., resources=..., pipelines=..., auth=...)`), or use\n   **`start_app`** to intake-and-build in one call.\n3. The prompt hands off to `docs://modules/build_recipe`; the agent scaffolds\n   with `get_app_template()` and pulls exact files with\n   `get_app_component(kind, resource=..., family=...)`, authoring only the\n   app-specific parts.\n4. To validate the standard without touching a real app, invoke **`trial`**\n   (`trial(app_name=..., build_path=...)`) to build into a scratch directory,\n   prove it builds, and report findings.\n\nManual alternative — copy the skeleton and follow the reference recipe:\n\n```bash\ncp -r <docs>/standards/src/templates/app apps/<your-app>\n```\n\n---\n\n## 📚 Reference\n\n- [Build Recipe](../lib/01_build_recipe/) — the deterministic checklist\n- [Genericity Matrix](../lib/12_genericity_matrix/) — Tier A / B / C\n- [Library Registry](../lib/13_library_registry/) — the Tier A catalog\n- [App Components](02_components.md) — the component model\n\n---\n\n## Related\n\n- [01 – Overview](01_overview.md) · [02 – App Components](02_components.md) · [04 – Testing & Quality](04_development/01_testing.md)\n",
+    "objects": {}
+  }
+}

standards/mcp/nav.json

@@ -78,5 +78,35 @@
     "module": "index",
     "resource": "docs://modules/index",
     "title": "Standards Reference"
+  },
+  {
+    "module": "wiki_overview",
+    "resource": "docs://modules/wiki_overview",
+    "title": "Overview"
+  },
+  {
+    "module": "wiki_components",
+    "resource": "docs://modules/wiki_components",
+    "title": "App Components"
+  },
+  {
+    "module": "wiki_start_an_app",
+    "resource": "docs://modules/wiki_start_an_app",
+    "title": "🚀 Start an App"
+  },
+  {
+    "module": "wiki_development_testing",
+    "resource": "docs://modules/wiki_development_testing",
+    "title": "Testing & Quality Gates"
+  },
+  {
+    "module": "wiki_development_releasing",
+    "resource": "docs://modules/wiki_development_releasing",
+    "title": "Releasing & Versioning"
+  },
+  {
+    "module": "wiki_index",
+    "resource": "docs://modules/wiki_index",
+    "title": "🧩 Standards — the Aetos App Blueprint"
   }
 ]

standards/src/lib/11_versioning_and_changelog.md

@@ -19,7 +19,7 @@ and tag contract is exactly what those two CI shapes consume.
 | Artifact | Source of truth | Notes |
 |----------|-----------------|-------|
 | Library (PyPI package) | `version` in `pyproject.toml` | `check-version` also reads it to skip duplicates |
-| Service / site (Docker) | `VERSION` file at the repo root | one line, `x.y.z` |
+| Service / site (Docker) | `VERSION` file at the repo root | one line, `x.y.z`; the service **reads** it (build-arg) — never hardcode the version |
 
 Rules: