# v0.25.0 — Cutover guide

> **Audience:** consumer agents (and humans relaying for them)
> upgrading to `mgf-common` 0.25.0.
> **What this is:** the canonical migration document for this
> release. Per [`RELEASING.md`](../standards/RELEASING.md) **REL-09**.

This is a **documentation restructure release**. No Python-
surface change; no behaviour change. The docs tree was
reorganised around three principles:

1. **Audience-routing front door** — `docs/audience/` with 7
   reading lists by persona (shoppers / users / developers /
   qa / release / security / ai-agents).
2. **Flat content directories** — drop the `/public/` and
   most of the `/internal/` intermediates; content directories
   are kind-organised (`recipes/` / `reference/` / `design/` /
   `qa/` / `release/` / `ops/`).
3. **Cutover archive policy** — last 3 minor versions live;
   older guides move to `docs/cutover/archive/`.

The shape is now the **golden-standard layout** that sibling
Magogi libraries inherit via the cookiecutter template.

---

## At-a-glance

| What landed | Severity | What it covers |
|---|---|---|
| `docs/audience/` (8 new files) | new directory | `shoppers.md`, `users.md`, `developers.md`, `qa.md`, `release.md`, `security.md`, `ai-agents.md`, plus master `README.md` |
| Top-level `README.md` rewritten | revision | ~100 lines, mostly audience-routing links |
| `docs/README.md` (new) | new file | Doc index + "where the actual content lives" map |
| Content moves (40+ files) | path map below | `git mv` preserved history; cross-references updated in batches |
| Cutover archive | last-3-live policy | v0.18–v0.21 → `docs/cutover/archive/`; v0.22–v0.24 stay live |
| Cookiecutter template | mirrors new shape | Sibling libraries adopt the layout via `templates/cookiecutter-mgf-project/` |

**Pin bump:** `mgf-common = ">=0.25,<0.26"` per the 0.x window
discipline.

**Public-Python-surface change:** none.

**Behaviour change:** none.

**No deprecation cycles introduced.**

---

## Path-mapping table (consumer agents read this)

If your project / scripts / docs reference any of these paths,
update them.

### Recipes (drop `/public/`)

| Old | New |
|---|---|
| `docs/public/recipes/alembic.md` | `docs/recipes/alembic.md` |
| `docs/public/recipes/cli.md` | `docs/recipes/cli.md` |
| `docs/public/recipes/cloud-native-logging.md` | `docs/recipes/cloud-native-logging.md` |
| `docs/public/recipes/db.md` | `docs/recipes/db.md` |
| `docs/public/recipes/django.md` | `docs/recipes/django.md` |
| `docs/public/recipes/fastapi.md` | `docs/recipes/fastapi.md` |
| `docs/public/recipes/framework-owned-logging.md` | `docs/recipes/framework-owned-logging.md` |
| `docs/public/recipes/http.md` | `docs/recipes/http.md` |
| `docs/public/recipes/multi_tenant_settings.md` | `docs/recipes/multi_tenant_settings.md` |
| `docs/public/recipes/new_project.md` | `docs/recipes/new_project.md` |
| `docs/public/recipes/notebook.md` | `docs/recipes/notebook.md` |
| `docs/public/recipes/observability_shim.md` | `docs/recipes/observability_shim.md` |
| `docs/public/recipes/process-management.md` | `docs/recipes/process-management.md` |
| `docs/public/recipes/providers.md` | `docs/recipes/providers.md` |
| `docs/public/recipes/script.md` | `docs/recipes/script.md` |
| `docs/public/recipes/testing.md` | `docs/recipes/testing.md` |
| `docs/public/recipes/versioned.md` | `docs/recipes/versioned.md` |

### Reference (numbered → semantic)

| Old | New |
|---|---|
| `docs/public/library_common.md` | `docs/reference/README.md` |
| `docs/public/01_lifecycle.md` | `docs/reference/lifecycle.md` |
| `docs/public/02_exceptions.md` | `docs/reference/exceptions.md` |
| `docs/public/03_config.md` | `docs/reference/config.md` |
| `docs/public/04_settings.md` | `docs/reference/settings.md` |
| `docs/public/05_observability.md` | `docs/reference/observability.md` |
| `docs/public/06_crash_reporting.md` | `docs/reference/crash_reporting.md` |
| `docs/public/07_vault.md` | `docs/reference/vault.md` |
| `docs/public/08_progress.md` | `docs/reference/progress.md` |
| `docs/public/09_cli.md` | `docs/reference/cli.md` |
| `docs/public/10_full_app.md` | `docs/reference/full_app.md` |

### Tutorial / design / qa / release / ops

| Old | New |
|---|---|
| `docs/public/tutorial.md` | `docs/tutorial.md` |
| `docs/public/multi_tenancy.md` | `docs/design/multi_tenancy.md` |
| `docs/public/federation.md` | `docs/design/federation.md` |
| `docs/internal/ARCHITECTURE.md` | `docs/design/architecture.md` |
| `docs/internal/STRATEGIC_REVIEW.md` | `docs/design/strategic_review.md` |
| `docs/internal/EXTRACTION_HISTORY.md` | `docs/design/extraction_history.md` |
| `docs/internal/TEST_COVERAGE.md` | `docs/qa/coverage.md` |
| `docs/internal/CI_STARTHERE.md` | `docs/release/ci.md` |
| `docs/internal/BENCHMARKS.md` | `docs/ops/benchmarks.md` |
| `docs/internal/LIFT_CHECKLIST.md` | `docs/internal/lift_checklist.md` (lowercase) |

### Cutover archive

| Old | New |
|---|---|
| `docs/cutover/v0.18.0.md` | `docs/cutover/archive/v0.18.0.md` |
| `docs/cutover/v0.19.0.md` | `docs/cutover/archive/v0.19.0.md` |
| `docs/cutover/v0.20.0.md` | `docs/cutover/archive/v0.20.0.md` |
| `docs/cutover/v0.21.0.md` | `docs/cutover/archive/v0.21.0.md` |

v0.22, v0.23, v0.24 stay live at `docs/cutover/`.

### What did NOT move

These paths are **stable** — consumer agents have hard-coded
references; the relay process depends on them:

- `FEEDBACK.md` (root)
- `CHANGELOG.md` (root)
- `PUBLIC_API.md`, `PUBLIC_API.json` (root)
- `STARTHERE.md` (root)
- `SECURITY.md`, `CONTRIBUTING.md` (root)
- `docs/standards/*` (entire tree — rules + per-kind subtrees + principles)
- `docs/claude/CLAUDE.md`

### Backwards-compat stubs

For one release (this one), `docs/internal/TEST_COVERAGE.md`
ships as a 1-line redirect to `docs/qa/coverage.md`. Removed
in v0.26.

---

## The new audience routing

Three new entry points:

- **Top-level [`README.md`](../../README.md)** — first-time
  visitors land here. ~100 lines, mostly audience-routing
  links.
- **[`docs/README.md`](../README.md)** — entry point for
  anyone who navigated into `docs/`. Same routing, scoped to
  the `docs/` tree.
- **[`docs/audience/README.md`](../audience/README.md)** —
  the meta-routing index for ambiguous personas.

The 7 audience pages are short reading lists (~80 lines
each). They contain almost no content — just links into the
content directories.

| Audience | Read first |
|---|---|
| **shoppers** (evaluating mgf-common) | [`docs/audience/shoppers.md`](../audience/shoppers.md) |
| **users** (already adopted; building) | [`docs/audience/users.md`](../audience/users.md) |
| **developers** (contributing or designing) | [`docs/audience/developers.md`](../audience/developers.md) |
| **qa** (testing / coverage) | [`docs/audience/qa.md`](../audience/qa.md) |
| **release** (cutting releases / CI) | [`docs/audience/release.md`](../audience/release.md) |
| **security** (security review) | [`docs/audience/security.md`](../audience/security.md) |
| **ai-agents** (Claude or other AI) | [`docs/audience/ai-agents.md`](../audience/ai-agents.md) |

---

## Per-consumer migration notes

### vm-vmanager-app (Qt desktop)

**Suggested adoption:** moderate — update internal references
to moved paths.

Concrete steps:

1. Search your project for `docs/public/recipes/` references → rewrite to `docs/recipes/`.
2. Search for `docs/public/0[1-9]_` numbered references → rewrite to `docs/reference/<semantic-name>.md`.
3. Search for `docs/internal/TEST_COVERAGE.md` references → rewrite to `docs/qa/coverage.md`.
4. Update any `docs/public/multi_tenancy.md` reference to `docs/design/multi_tenancy.md`.

If you have automation (`mgf-fed app-doctor` integrations,
custom CI link-checkers), point them at the new paths.

Pin: `mgf-common = ">=0.25,<0.26"`.

### inthewords (Django web)

**Suggested adoption:** the same as vm-vmanager-app. Plus consider
adopting the layout for your own project's `docs/`:

- Add `docs/audience/` with 5–7 reading lists (skip ones that
  don't apply — security if no security review process,
  release if you don't ship to PyPI, etc.).
- Promote `docs/internal/ARCHITECTURE.md` → `docs/design/`.
- Promote test coverage docs → `docs/qa/`.
- Add `docs/standards/PROJECT_OVERLAY.md` for project-specific
  exceptions to inherited mgf-common standards.

The cookiecutter template at
`templates/cookiecutter-mgf-project/{{cookiecutter.project_slug}}/docs/`
ships the canonical shape; copy from there as needed.

Pin: `mgf-common = ">=0.25,<0.26"`.

### PlasmaMapper (FastAPI scientific platform)

**Suggested adoption:** moderate for path updates; **per the
"small consumer" scope discipline you've codified
([`docs/standards/principles/non-adoption-is-valid.md`](../standards/principles/non-adoption-is-valid.md))**,
adopting the full audience-routing layer is optional. A
minimum viable shape for a small consumer:

- `docs/audience/users.md` — single audience page.
- `docs/recipes/` — your project's recipes (if any).
- `docs/qa/coverage.md` — test coverage map (per TS-19/20/21
  in mgf-common's TESTING.md).
- `docs/standards/PROJECT_OVERLAY.md` — empty placeholder
  documenting "we follow mgf-common's standards as canon."

Pin: `mgf-common = ">=0.25,<0.26"`.

---

## Cookiecutter template update

Sibling Magogi libraries (current: `mgf-apiprobe`; future:
`mgf-qt`, `mgf-cli`) inherit this layout via the cookiecutter:

```
templates/cookiecutter-mgf-project/{{cookiecutter.project_slug}}/docs/
├── README.md
├── audience/
│   ├── README.md, shoppers.md, users.md, developers.md,
│   ├── qa.md, release.md, security.md, ai-agents.md
├── recipes/, reference/, design/, qa/, release/, standards/
├── qa/coverage.md (skeleton)
└── standards/PROJECT_OVERLAY.md (placeholder for project-specific exceptions)
```

A sibling library generated by the cookiecutter starts with
the same audience-routing layer, ready to be filled in with
project-specific content.

---

## Engineering note

This release names a pattern that emerged organically across
the v0.21–v0.24 sequence:

- **v0.21** shipped `mgf.common.process` with comprehensive
  unit tests (the audit-first design).
- **v0.22** added polish (early-exit detection, race-safe
  snapshot, no-leak rollback, `Service.wait()`).
- **v0.23** expanded the test pyramid to four layers
  (smoke / unit / integration / e2e).
- **v0.24** codified the four-layer pattern as TS-19/20/21 in
  the standards.
- **v0.25** restructures the docs to match — and codifies the
  audience-routing layout as the golden-standard for sibling
  libraries.

The cycle: prove → polish → expand → codify → restructure-to-
match. Same arc as the documented-non-adoption principle
(LOG-01/CONFIG-01/BOOTSTRAP-01 carve-outs implicit; named
explicitly in v0.20). When a pattern proves itself across
multiple consumers, it gets promoted to a standard; when a
standard proves itself across multiple releases, the docs
get restructured to put it at the front door.

The full design rationale + question/answer log: see commit
`<this commit's SHA>` and the message that opened this round
in the maintainer-side conversation.

---

## What stays unchanged (explicit)

- `FEEDBACK.md` (root) — relay queue; consumer agents have
  hard-coded `FEEDBACK.md#paper-NN` paths.
- `CHANGELOG.md` (root) — Keep-a-Changelog format unchanged.
- `PUBLIC_API.md`, `PUBLIC_API.json` (root) — surface tables
  unchanged. Splitting into per-module `docs/reference/`
  files is deferred to v0.26+.
- `docs/standards/*` — entire tree unchanged. Rules + per-kind
  subtrees (`web/`, `principles/`) + filenames all stable.
  Only the master `docs/standards/README.md` got a cross-link
  to the new audience layer.
- All public Python names — `mgf.common.*` surface is exactly
  the same as v0.24.
- All test counts — 1445 tests still pass.
- The release cadence (minor-bump per closure batch),
  versioning policy (AP-03 0.x window), and consumer-relay
  process (REL-09).
