# Documentation

`mgf-standard` docs are organised by **kind**, not by audience — this repo
is a standards and governance artefact, not a library with a user guide.

## Buckets

| Path | What |
|---|---|
| [`standards/`](standards/) | The engineering-standards corpus — AP / CF / EH / LG / SC / TS / DP / DOC / NM / OB / PF / AG / TM / … rules. The **star of this repo**. Master index + per-topic Rules boxes. |
| [`design/`](design/) | The federation-pattern architecture paper — the WHY behind the federation shape. Low rate-of-change; reads like a paper, not a manual. |
| [`recipes/`](recipes/) | Federation-operations recipes and governance templates — cohort releases, sibling renames, the sync prompt, pointer-stub / adoption / conformance / deps / feedback templates, PR test-plan template, and process recipes for library-app separation and test-supervisor adoption. |
| [`reference-consumers/`](reference-consumers/) | Per-consumer evidence profiles (one file per known consumer) showing how each project implements the standards — the desktop/Qt shape (VManager), Django/web shape (inthewords), and FastAPI/SaaS shape (TelePlasma). Used as reference by standards authors and adopters. |
| [`inprogress/`](inprogress/) | Active maintainer trackers and long-horizon planning docs. A workspace, not a graveyard; closed trackers move to `docs/archive/<year>/`. |
| [`claude/`](claude/) | Agent-session docs (DOC-07 format) — dense-lookup facts for AI agents working in this repo. |
| [`../templates/`](../templates/) | Cookiecutter new-project scaffold (`cookiecutter-mgf-project`) — the canonical starting point for any new `mgf-*` sibling or consumer project that wants the full DOC-01 + DOC-02 root-doc baseline pre-wired. |

## Reading the standards

You almost never read the standards by opening files in this repo directly.
The canonical path is through `mgf-common`'s CLI, which is installed in every
federation project:

```sh
mgf-fed standards             # list all topics
mgf-fed standards LOGGING     # print one
mgf-fed agents                # the full AI-agent briefing
```

Those commands resolve the corpus via `mgf.standard.standards_dir()` —
the same content, without a checkout of this repo.

## Top-level files

| File | What |
|---|---|
| [`../FEDERATION.md`](../FEDERATION.md) | The canonical federation contract (every other repo ships a pointer stub) |
| [`../MGF_LIBRARIES.md`](../MGF_LIBRARIES.md) | The library registry (generated; REL-13 gate) |
| [`../CHANGELOG.md`](../CHANGELOG.md) | Keep-a-Changelog release history |
| [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | Dev setup, gates, PR process, commit-trailer convention |
| [`../SECURITY.md`](../SECURITY.md) | Vulnerability-reporting policy (SC-12) |
| [`../FEEDBACK.md`](../FEEDBACK.md) | Standards proposals and cross-cutting rule discussion |
