# Documentation by audience

> Pick the audience that matches you. Each page is a **reading
> list** that points into the rest of the docs in the right
> order. ~50–150 lines per page; pure navigation, no duplicated
> content.

| If you are… | …read | What you'll find |
|---|---|---|
| Evaluating mgf-common (have I picked the right library?) | [`shoppers.md`](shoppers.md) | Scope, fit, comparison, decision tree, "consumers using it today," when to NOT adopt |
| Already using it (building features against it) | [`users.md`](users.md) | Tutorial → recipes index → API reference → troubleshooting → version migration |
| Contributing or designing alongside | [`developers.md`](developers.md) | Design papers, the standards corpus, contribution flow, the FEEDBACK relay |
| A test/QA engineer | [`qa.md`](qa.md) | The four-layer test pyramid, per-module coverage, run-a-layer commands, decision tree for adding tests |
| Cutting releases / running CI | [`release.md`](release.md) | Release engineering rules, versioning, CI flows, cutover-guide pattern |
| Doing a security review | [`security.md`](security.md) | SC-* rules, redaction model, threat surface, secret handling |
| An AI agent (Claude or other) | [`ai-agents.md`](ai-agents.md) | The relay protocol, FEEDBACK paper template, paths-as-anchors discipline, doctor flow |

## Why audience-routing?

`mgf-common` is read by very different people for very
different reasons. A first-time evaluator wants a 5-minute
"is this what I need?" answer; a contributor wants 50-page
design papers; an AI agent needs machine-friendly file:line
anchors. One front door for all of them is friction.

Each audience page is small (~80 lines) and consists almost
entirely of links. The pages **never duplicate content** —
they route to the canonical location of each topic.

## Where the actual content lives

| Content kind | Path | Owner audience(s) |
|---|---|---|
| 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 | [`docs/recipes/`](../recipes/) | users |
| API reference (per-module) | [`docs/reference/`](../reference/) | users |
| Tutorial (zero → working app) | [`docs/tutorial.md`](../tutorial.md) | users, shoppers |
| Design papers (architecture, multi-tenancy, federation) | [`docs/design/`](../design/) | developers, shoppers |
| Test coverage map | [`docs/inprogress/coverage.md`](../inprogress/coverage.md) | qa |
| Release engineering runbook | [`docs/release/`](../release/) | release |
| Operations (benchmarks) | [`docs/ops/`](../ops/) | release, ops |
| Per-release migration guides | [`docs/cutover/`](../cutover/) | users (for upgrades) |
| Maintainer-only artifacts | [`docs/internal/`](../internal/) | maintainer |
| **In-flight tracking** (reliability, strategic review, federation, coverage) | [`docs/inprogress/`](../inprogress/) | developers, maintainer |

## Top-level files (intentionally not under `docs/`)

| File | Why it's at the root |
|---|---|
| [`README.md`](../../README.md) | First thing GitHub/Codeberg shows; needs to be on the project root |
| [`FEEDBACK.md`](../../FEEDBACK.md) | Consumer-relay anchor source; AI agents have hard-coded `FEEDBACK.md#paper-NN` paths |
| [`CHANGELOG.md`](../../CHANGELOG.md) | Per Keep-a-Changelog convention |
| [`PUBLIC_API.md`](../../PUBLIC_API.md), [`PUBLIC_API.json`](../../PUBLIC_API.json) | Surface-of-truth at the project root for downstream tooling discovery |
| [`STARTHERE.md`](../../STARTHERE.md) | Two-flow navigation hub for first-time users (alternative entry to README) |
| [`SECURITY.md`](../../SECURITY.md), [`CONTRIBUTING.md`](../../CONTRIBUTING.md) | GitHub/Codeberg surface conventions |

## How this layer maps to the file tree

```
docs/
├── audience/        ← reading lists (you are here)
├── standards/       ← rule corpus
├── recipes/         ← how-to
├── reference/       ← API reference
├── design/          ← design papers
├── qa/              ← test coverage
├── release/         ← release engineering
├── ops/             ← operations
├── cutover/         ← per-release migrations
├── internal/        ← maintainer-only
├── tutorial.md      ← zero → working app
└── claude/          ← AI agent session rules
```

The audience layer is **pure navigation**. Every other
directory is **content** organised by kind. This is the golden-standard layout (see `mgf-fed standards TESTING`)
that sibling Magogi libraries (`mgf-apiprobe`, future `mgf-*`)
inherit via the cookiecutter template.
