# For users — building with mgf-common

> **Who you are.** You've adopted `mgf-common` (or are about
> to). You want to know how to wire it up, what recipes exist
> for your framework, where the API reference lives, and how
> to upgrade across releases.

## First steps

If you haven't bootstrapped yet:

1. [`docs/tutorial.md`](../tutorial.md) — zero → working app
   in ~30 minutes. Uses `mgf.common.bootstrap()` to wire
   identity + logging + OTel + excepthooks transactionally.
2. [`docs/reference/lifecycle.md`](../reference/lifecycle.md)
   — the `bootstrap()` + `AppContext` model in depth.

## Recipes by domain

Pattern-by-pattern cookbook. Each ~150–400 lines, with worked
examples + cross-references.

For the complete A–Z index + per-recipe paper closures see
[`docs/recipes/README.md`](../recipes/README.md). The list below
is the **users-routed** subset, grouped by adoption order rather
than alphabetically.

### Process orchestration

- [`docs/recipes/process-management.md`](../recipes/process-management.md)
  — `mgf.common.process.run` (one-shot subprocess with
  timeout + redaction + log correlation) and `Service`
  (long-lived process with readiness probe + clean shutdown).
- [`docs/recipes/framework-owned-logging.md`](../recipes/framework-owned-logging.md)
  — `bootstrap(setup_logging=False)` for Django / FastAPI /
  Flask consumers whose framework owns the logging stack.

### Web / API

- [`docs/recipes/fastapi.md`](../recipes/fastapi.md) —
  `ExceptionTranslationMiddleware` + `RequestIdMiddleware` +
  `setup_db` lifespan + the post-PAPER-24 simplification.
- [`docs/recipes/django.md`](../recipes/django.md) —
  `MgfCommonConfig` `AppConfig` + the settings bridge +
  BOOTSTRAP-01-shaped `setup_logging=False` adoption.
- [`docs/recipes/http.md`](../recipes/http.md) — `HttpError`
  hierarchy + multi-inheritance domain pattern.

### Storage / data

- [`docs/recipes/db.md`](../recipes/db.md) — sqlalchemy
  integration + lifespan management.
- [`docs/recipes/alembic.md`](../recipes/alembic.md) —
  `configure_env` + the post-PAPER-22 `include_object`
  pass-through.
- [`docs/recipes/versioned.md`](../recipes/versioned.md) —
  versioned-file-store primitive.

### Logging / observability

- [`docs/recipes/cloud-native-logging.md`](../recipes/cloud-native-logging.md)
  — LG-06 cloud-native branch (stdout-only, ephemeral
  filesystem deployments).
- [`docs/recipes/observability_shim.md`](../recipes/observability_shim.md)
  — coexistence with consumer-side observability stacks.

### CLI / operational

- [`docs/recipes/cli.md`](../recipes/cli.md) — building CLIs
  on top of `mgf.common.cli`.
- [`docs/recipes/script.md`](../recipes/script.md) — short
  scripts that need bootstrap.
- [`docs/recipes/notebook.md`](../recipes/notebook.md) —
  Jupyter notebooks.

### Testing

- [`docs/recipes/testing.md`](../recipes/testing.md) — the
  pytest plugin's fixtures + the editable-install caveat
  (PAPER-23).

### Setup / configuration

- [`docs/recipes/new_project.md`](../recipes/new_project.md)
  — start a new project that depends on mgf-common.
- [`docs/recipes/multi_tenant_settings.md`](../recipes/multi_tenant_settings.md)
  — per-tenant `MgfSettings` composition.
- [`docs/recipes/providers.md`](../recipes/providers.md) —
  the provider ABC pattern (rule DP-02).

## API reference (per-module)

Per-module narrative reference. The module docstrings are the
source of truth; these docs add usage context.

| Module | Reference |
|---|---|
| Top-level (`bootstrap`, `AppContext`, `current_context`) | [`docs/reference/lifecycle.md`](../reference/lifecycle.md) |
| `mgf.common.exceptions` | [`docs/reference/exceptions.md`](../reference/exceptions.md) |
| `mgf.common.config` | [`docs/reference/config.md`](../reference/config.md) |
| `mgf.common.settings` (`MgfSettings`) | [`docs/reference/settings.md`](../reference/settings.md) |
| `mgf.common.observability` | [`docs/reference/observability.md`](../reference/observability.md) |
| Crash reporter | [`docs/reference/crash_reporting.md`](../reference/crash_reporting.md) |
| `mgf.common.vault` | [`docs/reference/vault.md`](../reference/vault.md) |
| `mgf.common.progress` | [`docs/reference/progress.md`](../reference/progress.md) |
| `mgf.common.cli` | [`docs/reference/cli.md`](../reference/cli.md) |
| Full app integration | [`docs/reference/full_app.md`](../reference/full_app.md) |
| Reference index + decision tree | [`docs/reference/README.md`](../reference/README.md) |

For the canonical machine-readable surface:

- [`PUBLIC_API.md`](../../PUBLIC_API.md) — full surface table.
- [`PUBLIC_API.json`](../../PUBLIC_API.json) — auto-generated
  from `__all__` introspection. Use in your own tooling.

## Upgrading across releases

Each release ships a **cutover guide** with a migration table.
Last 3 minor versions live, older versions archived.

- [`docs/cutover/v0.24.0.md`](../cutover/v0.24.0.md) — TS-19/20/21 + four-layer pyramid as standard.
- [`docs/cutover/v0.23.0.md`](../cutover/v0.23.0.md) — process polish round 2; OTel span gating, public redactor.
- [`docs/cutover/v0.22.0.md`](../cutover/v0.22.0.md) — process polish round 1; early-exit, `Service.wait()`.
- Older guides: [`docs/cutover/archive/`](../cutover/archive/).

Per-release short-form: [`CHANGELOG.md`](../../CHANGELOG.md).

## Conformance bar

Your project commits to a conformance level — L1 / L2 / L3 —
measuring how strictly it follows the standards (see
`mgf-fed standards README`; canonical in `FEDERATION.md` §4).
Declare it in your `MGF_STANDARDS_CONFORMANCE.md`; a one-line pointer
goes in your top-level README:

```
Conformance: L2 per https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/
```

## Troubleshooting

- **"Why is `current_context()` returning None and emitting
  UnconfiguredWarning?"** — call `bootstrap()` (or
  `bootstrap_for_test()` in test fixtures). See
  [`lifecycle.md`](../reference/lifecycle.md).
- **"Why are my `.env` keys raising `extra_forbidden`?"** —
  shared `.env` with Django / Celery? See BOOTSTRAP-01 fix
  in [`docs/cutover/archive/v0.19.0.md`](../cutover/archive/v0.19.0.md);
  short answer: `dotenv_filtering="match_prefix"` is the
  v0.19+ default; consumers with `extra="allow"` who relied
  on the legacy permissive shape should pass
  `dotenv_filtering=None` to restore.
- **"Why is `pytest_plugin` not loading my fixtures in a
  sibling editable install?"** — see PAPER-23 in
  [`docs/recipes/testing.md`](../recipes/testing.md);
  workaround is `pytest_plugins = ["mgf.common.pytest_plugin"]`
  in your `tests/conftest.py`.

## Filing feedback

Found a paper-cut or a missing primitive? File via the
[`FEEDBACK.md`](../../FEEDBACK.md) entry template (§1.4). The
relay process pulls maintainer attention onto consumer-filed
issues with a structured triage.
