# Documentation

Welcome to the `mgf-common` docs.

## Pick your starting point

The docs are organised by **audience**. Each page below is a
**reading list** that points into the rest of the tree.

| If you are… | Read |
|---|---|
| **Evaluating** mgf-common (is this a fit?) | [`audience/shoppers.md`](audience/shoppers.md) |
| **Building** with it | [`audience/users.md`](audience/users.md) |
| **Contributing** or designing | [`audience/developers.md`](audience/developers.md) |
| A **test/QA** engineer | [`audience/qa.md`](audience/qa.md) |
| Cutting **releases** | [`audience/release.md`](audience/release.md) |
| Doing a **security** review | [`audience/security.md`](audience/security.md) |
| An **AI agent** | [`audience/ai-agents.md`](audience/ai-agents.md) |

For the meta-routing overview: [`audience/README.md`](audience/README.md).

## Where the actual content lives

Audience pages route to **content directories** organised by
kind. The same content serves multiple audiences.

| Content | Path | Example readers |
|---|---|---|
| Engineering rules (MUST/SHOULD/MAY) | [`mgf-standard/docs/standards/`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/) | developers, qa, release, security |
| How-to recipes | [`recipes/`](recipes/) | users |
| API reference (per-module) | [`reference/`](reference/) | users |
| Tutorial (zero → working app) | [`tutorial.md`](tutorial.md) | users, shoppers |
| Design papers | [`design/`](design/) | developers, shoppers |
| Test coverage map | [`qa/`](qa/) | qa |
| Release engineering runbook | [`release/`](release/) | release |
| Operations / benchmarks | [`ops/`](ops/) | release, ops |
| Per-release migration guides | [`cutover/`](cutover/) | users |
| Maintainer-only artifacts | [`internal/`](internal/) | maintainer |
| AI agent session rules | [`claude/`](claude/) | AI agents |

## Top-level files (intentionally outside `docs/`)

The repo root carries files that are conventionally surfaced
by GitHub/Codeberg, used by tooling, or cited by hard-coded
paths in consumer agents:

- [`../README.md`](../README.md) — repo front door (badges, audience routing).
- [`../STARTHERE.md`](../STARTHERE.md) — two-flow nav hub.
- [`../FEEDBACK.md`](../FEEDBACK.md) — relay process queue (consumer agents have hard-coded `FEEDBACK.md#paper-NN` paths; do not move).
- [`../CHANGELOG.md`](../CHANGELOG.md) — Keep-a-Changelog form.
- [`../PUBLIC_API.md`](../PUBLIC_API.md), [`../PUBLIC_API.json`](../PUBLIC_API.json) — public surface.
- [`../SECURITY.md`](../SECURITY.md), [`../CONTRIBUTING.md`](../CONTRIBUTING.md) — community files.

## Why this layout

Three audiences read these docs for very different reasons.
Forcing them through the same front door creates friction. The
audience layer is **pure navigation** (no duplicated content);
content directories are **kind-organised** (one canonical home
per topic).

The full design rationale lives in the
[v0.25.0 cutover guide](cutover/v0.25.0.md) — it documents
this restructure as the canonical pattern that sibling Magogi
libraries (`mgf-apiprobe`, future `mgf-*`) adopt via the
[cookiecutter template](../templates/).
