# `docs/design/` — architecture papers + design decisions

**Per `DOC-02`:** this directory holds the **WHY**, not the
HOW. Low rate-of-change; reads like a paper, not a manual.
Cross-referenced from the topic standards docs when a rule's
rationale is too long to inline.

## What goes here

- **Architecture papers** — long-form explanations of the
  library's shape: federation strategy, multi-tenancy model,
  the closed-box principle.
- **Extraction history** — the audit trail of which components
  moved from vm-vmanager-app → mgf-common, when, and why. The record
  the lift-checklist (`docs/internal/lift_checklist.md`)
  produces output for.
- **ADRs** (architecture decision records) when they appear —
  each ADR captures a single decision: context, decision,
  consequences. Numbered `ADR-NNN-<slug>.md`.

## What does NOT go here

- **Per-component user guides** → `docs/reference/`. Design
  papers explain *why* X exists; reference docs explain *how*
  to use X.
- **Engineering rules / MUSTs** → `docs/standards/`. A standard
  may CITE a design paper for rationale, but the rule itself
  belongs in the standards bucket.
- **Roadmap planning** → `docs/inprogress/strategic_review.md`
  / `federation_roadmap.md` (per `DOC-06` carve-out).
- **Cutover migration recipes** → `docs/cutover/`.

## When to write a design paper

The threshold: a future contributor (or AI agent) reading the
relevant standard / reference doc would ask *"but WHY is it
shaped this way?"* and the answer takes more than two
paragraphs. That's a design paper.

Below that threshold, the rationale inlines in the topic doc
itself.

## Index

| File | One-line description |
|---|---|
| `architecture.md` | The closed-box shape; layering; replaceability through provider ABCs |
| `federation.md` | **Moved** → [`mgf-standard/docs/design/federation.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/design/federation.md) (the federation-pattern paper is foundation-level; extracted with the standards corpus). |
| `multi_tenancy.md` | The multi-tenancy model for consumers that need it (PlasmaMapper-shape) — settings composition, AppContext-per-tenant, audit-log discipline |
| `extraction_history.md` | The audit trail of components lifted from vm-vmanager-app → mgf-common, with file:line citations + rationale per lift |
