Doctrine: this folder follows the Mirai reference-documentation design
[real: mirai-mdai/claude-doctrine/reference-docs-design.md, ruled R-C27,
Michele 2026-07-29] — Diátaxis quadrants, Mermaid-first diagrams with C4
conventions, and the freshness law (doc changes ride the same PR as the code
change they describe; see CLAUDE.md operating rules).
| Where | Diátaxis quadrant | What belongs there |
|---|---|---|
reference/ |
Reference | the facts: formats, interfaces, parameters, invariants — complete and dry |
explanation/ |
Explanation | the architecture: why it is shaped this way, boundaries, forks taken (tagged per behavioral law) |
how-to/ |
How-to | task recipes for the operated tool: build, test, run, fuzz |
| (tutorials) | Tutorial | deliberately absent — owed only where onboarding demands it (reuse-first: scale by repo weight); create tutorials/ when that day comes |
00-… – 04-… |
design corpus | the settled architecture session output — normative source the quadrants cite; do not restructure |
decisions/ |
ADRs | NNN-*.md, append-only; supersede, don't rewrite |
The numbered corpus is authoritative where it and a quadrant page overlap; quadrant pages summarize, diagram, and cite — they do not fork the design.
- Mermaid-first: renders natively on GitHub; source lives in the md file.
- Architecture views use C4 conventions via Mermaid's C4 diagram types (context → container → component; go deeper only where it earns its keep).
- Byte layouts use Mermaid
packet-beta; state machines usestateDiagram-v2. - PlantUML permitted only where Mermaid cannot express the view; same rule: source embedded, never committed binary images.
Reused from the awesome-copilot documentation-writer workflow
[real: reference-docs-design.md]: clarify audience → outline for approval →
generate. For substantial new pages, put the outline in the PR description.