# `docs/design/` — architecture papers

**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 standards docs
when a rule's rationale is too long to inline.

## What goes here

- **Architecture papers** — long-form explanations of the federation's shape:
  why it is structured the way it is, what invariants it maintains, and what
  trade-offs were made.
- **ADRs** (architecture decision records) when they appear — each captures a
  single decision: context, decision, consequences. Numbered `ADR-NNN-<slug>.md`.

## What does NOT go here

- **Engineering rules / MUSTs** → `docs/standards/`. A paper may be cited by a
  standard for rationale, but the rule itself belongs in the standards bucket.
- **Federation-operations recipes** → `docs/recipes/`. Papers explain *why*;
  recipes explain *how to operate*.
- **Roadmap planning / active trackers** → `docs/inprogress/`.

## When to write a paper

The threshold: a contributor (or AI agent) reading the relevant standard 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 |
|---|---|
| [`federation.md`](federation.md) | **Pointer stub** — the v1 federation-pattern paper was archived (it predates the `mgf-standard` extraction + devpi cutover; Court review F-M5, 2026-07). Current authority: [`FEDERATION.md`](../../FEDERATION.md) + [`docs/standards/`](../standards/); the historical paper is kept at [`docs/archive/2026/federation-design-v1-pre-extraction.md`](../archive/2026/federation-design-v1-pre-extraction.md) |
