refactor: conform standards docs to doc-forge wiki/lib layout; generic build.py; static kind links

mcp/standards/modules/build_recipe.json

@@ -1,8 +0,0 @@
-{
-  "module": "build_recipe",
-  "content": {
-    "path": "build_recipe",
-    "docstring": "# Build Recipe\n\n## Summary\n\nFollow this ordered checklist to generate a new application of the standard\nshape. Every step is deterministic; only steps 2 and 7 require app-specific\nauthoring.\n\n---\n\n## 0. Query the registry\n\nBefore writing anything, read the **library registry** and note which internal\nlibraries provide DB, DI, routing, ingestion, auth, and docs. Do not\nreimplement them.\n\n## 1. Scaffold the repository\n\nCopy the `templates/` skeleton. It provides: `pyproject.toml`, `openapi.yaml`,\n`main.py`, `init.py`, `worker.py`, `config.py`, `Dockerfile`,\n`docker-compose.yaml`, `.env.example`, and the package tree\n(`domain/ infra/ interfaces/ pipelines/ tests/ scripts/`).\n\n## 2. Author the spec  *(app-specific)*\n\nWrite `openapi.yaml`: resources, schemas, `operationId`s, security, and any\nextension metadata. This is the contract.\n\n## 3. Write each CRUD slice  *(app-specific)*\n\nFor each resource, create the four-file slice (see **CRUD Template**):\n`models.py`, `ports/db.py`, `ports/service.py`, optional `converters.py`.\n\n## 4. Wire the composition root\n\nIn `init.py`: build leaf repositories, then dependent repositories, then\nservices; add infrastructure adaptors (cache store, progress bus, stores,\nfetchers). Add `get_svc` overloads.\n\n## 5. Add routes\n\nCreate `interfaces/<resource>/routes.py` (thin handlers) and re-export them in\n`interfaces/openapi.py`. Add a cache decorator to read endpoints.\n\n## 6. Bootstrap the app and worker\n\nConfirm `main.py` wires the OpenAPI-first app with the lifespan. If the app has\nlong-running jobs, adapt `worker.py` to poll the relevant job collection.\n\n## 7. Add a pipeline family  *(only if data-driven)*\n\nCreate `pipelines/<family>/` with `abc.py`, `impl.py`, `pipeline.yaml`,\n`resources/`, and register the root in `registry.py`. Add fixtures and a parity\ntest.\n\n## 8. Add infrastructure as needed\n\nOnly where the standard adaptors do not cover the need. Prefer library-backed\nadapters.\n\n## 9. Tests\n\nAdd integration tests with fakes and unit tests for domain/pipeline logic; add\na config-consistency test if using rule-driven pipelines.\n\n## 10. Scripts and seeds\n\nAdd operator scripts under `scripts/` that use `init()` / `get_svc()` /\n`shutdown()`.\n\n## 11. Docs\n\nAuthor GSDFC docstrings, generate the type stubs (`.pyi`), mark the package\n`py.typed`, and build docs.\n\n## Definition of done\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",
-    "objects": {}
-  }
-}

mcp/standards/modules/index.json

@@ -2,7 +2,7 @@
   "module": "index",
   "content": {
     "path": "index",
-    "docstring": "# The Aetos Standard App Blueprint\n\nA single, reusable architecture for backend applications in the Aetos ecosystem.\n\nEvery application built with this blueprint has the same shape:\n\n- a **spec-first HTTP layer** driven by an OpenAPI document;\n- a **domain layer** of pure models, ports, and services;\n- an **infrastructure layer** of adapters (MongoDB, cache, workers, LLM, mail);\n- a **composition root** that wires everything in exactly one place;\n- an optional **pipeline layer** for data-driven extraction/enrichment;\n- an optional **background worker** that runs long-running jobs and reports progress.\n\n> This blueprints is deliberately **app-agnostic**. It never names a concrete\n> business domain. Any application — expenses, health metrics, inventory,\n> analytics — is produced by filling in **two axes only**: the resource model\n> and (if needed) the pipeline family.\n\n## How to read this\n\n| Page | What it covers |\n|---|---|\n| Overview | The philosophy and the one-way dependency rule |\n| Layering Rules | Which package may import which |\n| Composition Root | The single wiring point |\n| Spec-First Routing | OpenAPI as the source of truth |\n| CRUD Template | The canonical resource slice |\n| Pipeline Scaffold | Data-driven processing families |\n| Worker & Progress | Async jobs, status machine, streaming progress |\n| Human-in-the-Loop | Pausing a job to ask a question |\n| Infra Adapters | MongoDB, cache, stores, LLM, mail |\n| Testing | Integration + unit conventions |\n| Build Recipe | The ordered checklist to generate a new app |\n| Genericity Matrix | What is reusable vs what you must write |\n\n## For AI agents\n\nThis content is served as MCP resources under `docs://index`, `docs://nav`,\nand `docs://modules/{module}`. To build a new app:\n\n1. Read `build_recipe` first.\n2. Read `genericity_matrix` to know what you must author.\n3. Query the **library registry** (`find_library`) before writing any\n   infrastructure yourself.\n4. Copy the `templates/` skeleton and fill the two app-specific axes.\n",
+    "docstring": "# Standards Reference\n\nThe reference half of the Standards description: the enforceable rules,\npatterns, and the internal library catalog that agents consult while coding.\n\n- **Layering Rules** — the strict request → domain → repository layering and\n  the rules that enforce it.\n- **Composition Root** — a single composition point wiring the whole app.\n- **Spec-First Routing** — the OpenAPI contract as the routing source of truth.\n- **CRUD Template** — the standardized generic resource endpoint scaffold.\n- **Pipeline Scaffold** — the deterministic pipeline skeleton for multi-stage\n  jobs.\n- **Worker & Progress** — queued work, progress reporting, and visibility.\n- **Human-in-the-Loop** — guardrails and approvals inside automations.\n- **Infra Adapters** — how infrastructure connects without leaking into domain.\n- **Genericity Matrix** — what is generic vs app-specific.\n- **Library Registry** — the catalog of internal libraries behind all of it.\n\nRead the **Wiki** for the philosophy and rationale; these pages are the\nreference that mirrors the `standards` MCP bundle.\n",
     "objects": {}
   }
 }

mcp/standards/modules/overview.json

@@ -1,8 +0,0 @@
-{
-  "module": "overview",
-  "content": {
-    "path": "overview",
-    "docstring": "# Overview\n\n## Summary\n\nThe blueprint is a **hexagonal (ports and adapters) application** with a\n**spec-first** web edge and a **single composition root**. It favors explicit\nwiring over implicit magic, and it prefers existing internal libraries over\nhand-written infrastructure.\n\n---\n\n## The three layers\n\n```\ninterfaces/   ← HTTP edge: thin handlers bound to an OpenAPI operationId\ndomain/       ← business core: models, ports (interfaces), services, orchestrators\ninfra/        ← adapters: databases, caches, external clients, hardware\n```\n\nPlus two optional layers:\n\n```\npipelines/    ← data-driven transformation graphs (extraction, enrichment)\nscripts/      ← operator scripts that reuse the composition root\n```\n\n## Core principles\n\n1. **One-way dependencies.** `interfaces -> domain -> infra` is allowed;\n   the reverse is forbidden. The domain never imports a framework it does not\n   own.\n2. **Ports in the domain, adapters in infra.** A service depends on an\n   abstract port; the composition root injects a concrete adapter.\n3. **One composition root.** Nothing constructs its own dependencies. All\n   wiring lives in one module (`init.py`) and is exposed as a flat resource\n   registry.\n4. **Spec-first.** The HTTP contract is declared in an OpenAPI document. Route\n   handlers are looked up by `operationId`. There are no decorator routers.\n5. **Reuse the libraries.** Pipeline orchestration, DI, Mongo repositories,\n   ingestion, auth, and docs are provided by internal libraries. Do not\n   reimplement them — see the library registry.\n6. **Explicit state machines.** Long-running work moves through explicit,\n   durable statuses and can pause for human input.\n\n## Runtime processes\n\nA standard app may run as up to three processes that share the same\ncomposition root:\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",
-    "objects": {}
-  }
-}

mcp/standards/modules/testing.json

@@ -1,8 +0,0 @@
-{
-  "module": "testing",
-  "content": {
-    "path": "testing",
-    "docstring": "# Testing\n\n## Summary\n\nTwo test suites: **integration** (the HTTP edge with fakes) and **unit** (pure\ndomain and pipeline logic). Both run under pytest with asyncio auto mode.\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## Integration tests\n\n- Build the app with `TestClient`.\n- Replace `app.state.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.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## 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## 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## 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",
-    "objects": {}
-  }
-}