# Recipes

> **Audience:** anyone building with `mgf-common` who wants a
> worked example of a specific pattern.
> **What this is:** the canonical index for every recipe that
> ships with the project. Each recipe is a self-contained
> how-to with at-a-glance code and the cross-references back
> to standards / reference docs.

Recipes are **how-to**, not specification. For specification
(MUST/SHOULD/MAY rules) run `mgf-fed standards <TOPIC>` or browse
[`https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/).
For per-module API reference (the sentence-level surface) see
[`../reference/`](../reference/).

| Doc kind | Where | Who writes it | Truth on |
|---|---|---|---|
| **Recipe** (this directory) | `docs/recipes/` | maintainer + consumers | how to wire a working pattern |
| **Standard rule** | `mgf-fed standards <TOPIC>` | maintainer | what the project requires |
| **Reference** | [`docs/reference/`](../reference/) | maintainer (auto from `__all__`) | the API surface |

The rules from `mgf-fed standards <TOPIC>` are canonical; recipes show how to
apply them. If a recipe and a rule disagree, file the
discrepancy via [`FEEDBACK.md`](../../FEEDBACK.md) so the
recipe can be brought into line.

---

## Recipes by domain

The kind-organised index. Same shape audience pages route into,
but every recipe has a slot here.

### Bootstrapping a project

| Recipe | What it covers |
|---|---|
| [`new_project.md`](new_project.md) | Start a new project on the mgf-common standards via `mgf-fed init-project` + `catch-up`. The right entry point for any net-new repo. |
| [`script.md`](script.md) | Shortest possible `bootstrap()` for a one-off script — admin tools, data-fixes, REPL sessions. No CLI ceremony. |
| [`notebook.md`](notebook.md) | Jupyter / IPython kernels (JupyterLab, classic, VS Code notebooks). Notebooks are neither apps nor libraries; this is their shape. |

### Restructuring a project

| Recipe | What it covers |
|---|---|
| [`library-app-separation.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/recipes/library-app-separation.md) → mgf-standard | Cut a monolithic app into a reusable `mgf-*` domain library + thin CLI/GUI consumer app(s). The four-phase playbook — prep, extract, consume, presentation layer — with the vm-vmanager-app extraction worked through end to end. |

### Federation operations

| Recipe | What it covers |
|---|---|
| [sibling_rename](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/recipes/sibling_rename.md) | Rename a federation sibling (`mgf_x → mgf-x` separator drift, `mgf-ubs → mgf-hrb` whole-name). Eight-surface checklist (sibling code + PyPI + Codeberg + mgf-common refs + each consumer's pyproject + uv.sources + venv `.pth` + on-disk husks). Closes PAPER-79 Approach A. |
| [cohort-release-wave](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/recipes/cohort-release-wave.md) | Federation cohort-release procedure (REL-10/11/12). Phase A parallel mechanical edits + Phase B sequential ship. Required when a `mgf-common` MINOR breaks any sibling's pin upper-bound. |
| [`local-ci-pipeline.md`](local-ci-pipeline.md) | Run `.woodpecker.yml` locally on demand via [`scripts/ci-local.sh`](../../scripts/ci-local.sh) — full validation, a single step, the perf sweep, or the release flow (dry-run / real publish) — in real Docker, against the working tree. Serialized so local runs don't race on shared `.gates/`/`dist/` state; `publish` is gated to `release --publish` only. |
| [federation-sync-prompt](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/recipes/federation-sync-prompt.md) | The single reusable prompt to drop into any sibling `mgf-*` repo so an agent syncs it with `mgf-common` + the federation, catches every update (pins, extractions, standards), and brings it into conformance — read-only on the federation, no unsolicited releases. |

### Application kinds

| Recipe | What it covers |
|---|---|
| [`cli.md`](cli.md) | Building an ergonomic CLI on `mgf.common.cli` — typed exit codes, structured logging, OTel, friendly errors, pluggable subcommands. |
| `fastapi` (sibling) | FastAPI service: `ExceptionTranslationMiddleware` + `RequestIdMiddleware` + `setup_lifespan` + worked `status_map` examples. **Moved to `mgf-fastapi`** at v0.28.0 per [`../inprogress/federation_roadmap.md`](../inprogress/federation_roadmap.md) D5 — see `mgf-fastapi/docs/recipes/fastapi.md`. |
| `django` (sibling) | Django app on `mgf.django` (sibling `mgf-django`) — `MgfCommonConfig`, middleware, JsonFormatter, settings bridge. **Moved to `mgf-django`** at v0.31.0 per [`../inprogress/federation_roadmap.md`](../inprogress/federation_roadmap.md) D5 — see `mgf-django/docs/recipes/django.md`. |

### Logging / observability

| Recipe | What it covers |
|---|---|
| [`framework-owned-logging.md`](framework-owned-logging.md) | `bootstrap(setup_logging=False)` for any framework that owns its logging stack — Django (`LOGGING` dictConfig), FastAPI/uvicorn, Flask, Pyramid, aiohttp. Closes BOOTSTRAP-01 (v0.19.0). |
| [`cloud-native-logging.md`](cloud-native-logging.md) | LG-06 cloud-native branch: stdout-only emission for ephemeral container filesystems (Kubernetes, Docker Compose, Heroku, Cloud Run, Fly.io). Closes LOG-01 (v0.18.0). |
| [`observability_shim.md`](observability_shim.md) | Layering project-side redactors / handlers / formatters via a re-export shim, without forking `mgf.common.observability`. |

### HTTP / data

| Recipe | What it covers |
|---|---|
| `http` (sibling) | Async HTTP client on `mgf.http` (sibling `mgf-http`) — retries, timeouts, redaction. **Moved to `mgf-http`** at v0.29.0 per [`../inprogress/federation_roadmap.md`](../inprogress/federation_roadmap.md) D5 — see `mgf-http/docs/recipes/http.md`. |
| `webhooks` (sibling) | Svix-shape HMAC webhook verification (`HmacWebhookVerifier` + `verify_request`). **Moved to `mgf-fastapi`** at v0.28.0 — see `mgf-fastapi/docs/recipes/webhooks.md`. |
| `sqlalchemy` (sibling) | Async SQLAlchemy 2 on `mgf.sqlalchemy` (sibling `mgf-sqlalchemy`) — engine + sessionmaker + tenant RLS. **Moved to `mgf-sqlalchemy`** at v0.30.0 per [`../inprogress/federation_roadmap.md`](../inprogress/federation_roadmap.md) D5 — see `mgf-sqlalchemy/docs/recipes/sqlalchemy.md`. The FastAPI-shaped helpers (`get_session`, `setup_db`) live in `mgf-fastapi[sqlalchemy]` as `mgf.fastapi.db` since v0.2.0. |
| `alembic` (sibling) | Schema migrations: `configure_env` (with PAPER-22 knobs) for async-SQLAlchemy `env.py` boilerplate replacement. **Moved to `mgf-alembic`** at v0.30.0 — see `mgf-alembic/docs/recipes/alembic.md`. |
| [`versioned.md`](versioned.md) | Versioned satellite-config files via `mgf.common.versioned` — typed schema, version field, migration callback, atomic write. |
| [`web-sse.md`](web-sse.md) | Server-Sent Events through a dev/prod proxy: the three SSE-only buffering-disable response headers, the forwarding-`fetch` `duplex: 'half'` requirement, and the two Playwright gotchas (`networkidle` never fires with an open `EventSource`; `webServer` boots before `globalSetup`). Closes PAPER-93. |

### Patterns / seams

| Recipe | What it covers |
|---|---|
| [`providers.md`](providers.md) | Provider-seam pattern (makes rule DP-02 concrete): `ProviderABC` + `translate_at_seam` for clean third-party SDK boundaries. |
| [`multi_tenant_settings.md`](multi_tenant_settings.md) | Per-tenant `MgfSettings` composition. Pattern (not a primitive yet — promotes if a second multi-tenant consumer signals demand). |
| [`process-management.md`](process-management.md) | `mgf.common.process.run()` (one-shot subprocess) and `Service` (long-lived process with readiness probe + clean shutdown). v0.21.0+. |

### Testing

| Recipe | What it covers |
|---|---|
| [`testing.md`](testing.md) | The pytest plugin's five fixtures + the editable-install caveat from PAPER-23 (`pytest_plugins = ["mgf.common.pytest_plugin"]` in `tests/conftest.py`). |

### CI gates

| Recipe | What it covers |
|---|---|
| [`scan-deps.md`](scan-deps.md) | Dependency-vulnerability scanning gate (`pip-audit` for Python, `pnpm/npm audit` for frontend). Lock-export run shape, `.pip-audit-ignore` triage file with sunset dates, `--audit-level=high` for frontend. Closes PAPER-34. |

---

## Recipes A–Z

Quick lookup. Sorted alphabetically; same recipes as above. The
**Closes** column is a strict back-reference: it lists papers /
rules the recipe **currently documents**. See *Known integration
gaps* below for cases where a paper shipped but the recipe hasn't
caught up yet.

| Recipe | One-liner | Optional extra | Closes |
|---|---|---|---|
| `alembic` (sibling) | Alembic env.py with async-SQLAlchemy auto-detect (moved to `mgf-alembic` at v0.30) | `mgf-alembic` | PAPER-22 |
| [`cli`](cli.md) | Ergonomic CLI on `mgf.common.cli` | — | — |
| [`cloud-native-logging`](cloud-native-logging.md) | Stdout-only logging for ephemeral container filesystems | — | LG-06, LOG-01 |
| `sqlalchemy` (sibling) | Async SQLAlchemy 2 with `mgf.sqlalchemy` (moved to `mgf-sqlalchemy` at v0.30); FastAPI-shaped helpers in `mgf-fastapi[sqlalchemy]` as `mgf.fastapi.db` | `mgf-sqlalchemy` (+ `mgf-fastapi[sqlalchemy]` for FastAPI) | — |
| `django` (sibling) | Django app on `mgf.django` (moved to `mgf-django` at v0.31) | `mgf-django` | — |
| `fastapi` (sibling) | FastAPI service on `mgf.fastapi` (moved from `mgf.common.fastapi` at v0.28) | `mgf-fastapi` | — |
| [`framework-owned-logging`](framework-owned-logging.md) | `bootstrap(setup_logging=False)` for framework-owned logging | — | BOOTSTRAP-01, PAPER-25 |
| `http` (sibling) | Async HTTP client (moved to `mgf-http` at v0.29) | `mgf-http` | — |
| [`library-app-separation`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/recipes/library-app-separation.md) → mgf-standard | Cut a monolith into an `mgf-*` library + CLI/GUI consumer app(s) | — | — |
| [`multi_tenant_settings`](multi_tenant_settings.md) | Per-tenant settings composition (pattern, not primitive) | — | — |
| [`new_project`](new_project.md) | Bootstrapping a new project on the mgf-common standards | — | — |
| [`notebook`](notebook.md) | Jupyter / IPython kernels | — | — |
| [`observability_shim`](observability_shim.md) | Project-side observability extension via re-export shim | — | — |
| [`process-management`](process-management.md) | `mgf.common.process.run()` + `Service` (v0.21.0+) | — | EH-04 |
| [`providers`](providers.md) | Provider-seam pattern (`ProviderABC` + `translate_at_seam`) | — | DP-02 (demonstrated, not named) |
| [`scan-deps`](scan-deps.md) | Dependency-vulnerability scanning CI gate (pip-audit + pnpm audit) | — | PAPER-34 |
| [`script`](script.md) | Shortest possible `bootstrap()` for one-off scripts | — | — |
| [sibling_rename](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/recipes/sibling_rename.md) | Rename a federation sibling (eight-surface checklist) | — | PAPER-79 |
| [`testing`](testing.md) | Pytest plugin fixtures + editable-install caveat | — | PAPER-23 |
| [`versioned`](versioned.md) | Versioned satellite-config files | — | — |
| [`web-sse`](web-sse.md) | Server-Sent Events through a dev/prod proxy (buffering-disable headers, `duplex: 'half'`, Playwright gotchas) | — | PAPER-93 |
| `webhooks` (sibling) | Svix-shape HMAC webhook verification (moved to `mgf-fastapi` at v0.28) | `mgf-fastapi` | PAPER-26 |

---

## Known integration gaps

A few recipes lag the v0.18 – v0.20 ships. The features shipped
to PyPI; the recipes haven't been updated to demonstrate them
yet. Until they're integrated, consumers should follow the
linked cutover-archive section for the working pattern.

| Recipe | What's missing | Where to read meanwhile |
|---|---|---|
| `alembic` (sibling: `mgf-alembic/docs/recipes/alembic.md`) | PAPER-22 demonstration — `configure_env(include_object=, include_schemas=)` pass-through (PostGIS / TimescaleDB / pgvector hygiene), shipped v0.19.0; carried to mgf-alembic v0.1.0 byte-identical. The sibling recipe DOES cover it (added at the v0.30 cutover); the gap is that mgf-common's index used to point at the local `alembic.md` and that file is gone. | The sibling recipe at `mgf-alembic/docs/recipes/alembic.md` covers the PAPER-22 shape inline. |
| `django` (sibling: `mgf-django/docs/recipes/django.md`) | BOOTSTRAP-01 — `dotenv_filtering="match_prefix"` default + `bootstrap(setup_logging=False)` Django wiring, shipped v0.19.0. The django recipe moved to the `mgf-django` sibling at v0.31; mgf-common no longer ships a local `django.md`. The BOOTSTRAP-01 Django shape is covered mgf-common-side by `framework-owned-logging.md`. | [`framework-owned-logging.md`](framework-owned-logging.md) and [`../cutover/archive/v0.19.0.md#bootstrap-01--django-adoption-blocker`](../cutover/archive/v0.19.0.md#bootstrap-01--django-adoption-blocker) |
| [`providers.md`](providers.md) | DP-02 named explicitly — recipe demonstrates the rule's shape (`ProviderABC` + `translate_at_seam`) but doesn't cite the rule code. Cosmetic; integration is to add the cross-reference. | `mgf-fed standards DESIGN_PRINCIPLES` (DP-02 row) |

The recipe-update batch is itself a candidate for a future
FEEDBACK paper — see *Filing a new recipe* below.

---

## Per-kind narrative reading lists

This README is a **flat index**. For audience-routed reading lists
that order recipes by adoption phase, use:

- [`../audience/users.md`](../audience/users.md) — for consumers
  building with mgf-common; recipes grouped by domain with
  surrounding context.
- `mgf-fed standards web/README` — for web consumers
  (Django / FastAPI / Flask); recipes plus the per-rule
  applicability matrix and the framework-fit narrative.

If a future per-kind subtree opens (`mgf-standard/docs/standards/desktop/`,
`mgf-standard/docs/standards/data-science/`, …), it will provide an analogous
reading list rooted in this index.

---

## Filing a new recipe

If you've adopted a pattern that's **repeatable across consumers**
and isn't already a recipe, file via the FEEDBACK process — see
[`../../FEEDBACK.md`](../../FEEDBACK.md) §1.4 (entry template) and
§1.5 ground rules. Recipes typically promote from:

- A cutover-guide section that's permanent reference (the v0.20.0
  PAPER-25 promotion of BOOTSTRAP-01's adoption pattern is the
  canonical example).
- A worked example inside a topic-doc that grew big enough to
  deserve its own file.
- A second consumer hitting the same shape — the
  "second-consumer" framing in the strategic review treats this
  as the inflection point where a single-consumer pattern
  generalises into a primitive or a recipe.

The same FEEDBACK channel handles **integration gaps** — the
five recipes flagged above are themselves candidates for a paper
batch ("recipes lag v0.18–v0.20 ships; align them"). File one
batch entry or per-recipe; either is fine.
