# System documentation (docs/architecture/systems/{system}.md)

Truth document. Use for: **one machine that spans packages**, which a person cannot point at — the walk, the egress, the ingest, the settlement, a gate, a sweep, a door an agent calls. One file per machine, named for the machine. A thing a person navigates to is a feature document, even when it owns tables; a unit of distribution is a package document.

**A document is read by people, and its footer is for the agent** (`references/style-guide.md` § Owning documents — the body and the footer). A system document explains a machine to a person: what it is for, why it is split where it is split, how it behaves from the outside, what it guarantees at the far end, what re-drives it when it stalls. Its stages, tables, routes, frames, bindings and files are the code graph's (`docs/architecture/systems/knowledge-layer.md`), not a hand-typed tour. The body names code only at a cross-cutting seam another machine or feature would not find from its own files.

**A system document's deepest layer is the machine's behaviour across packages** (`references/style-guide.md` § Shape — the model first, the detail after): the order it runs in, the sequence and state diagrams at role level, the invariant that holds at each place where parts meet, and what re-drives a stall. That layer is earned because no single file shows a cross-package flow. It stops before per-function steps, tables, columns and routes.

**A system document speaks for the files the machine is made of.** Their headers name it, which outranks the package document's residual claim. Until the ownership scan switches to header pointers, its transitional `owns:` names the machine's subtrees as region globs, narrower than the package glob; every glob matches a file on disk at `status: active`.

**Sharp, bulleted, labelled with noun phrases** (`references/style-guide.md` § Labels). The opening paragraph defines the machine; everything after it is bullets under noun-phrase headings, each bullet a bold noun-phrase label followed by one or two sentences.

**Sections:** the frontmatter and the opening paragraph (the machine defined in its first sentence, what enters, what it leaves behind) are required. Then:

| Section | When |
| --- | --- |
| `Scope` | required. What this document does not decide, and which document does — subjects with owners, never bare links |
| `Flow` | required |
| `Decisions` | once any choice was made that the code cannot explain, including why this is one machine and not two |
| `Promises` | required |
| `Gaps` | only when there is one |
| `For the agent` | required |

Nothing else. The lint rules of the feature template apply. Sixty to a hundred and sixty lines.

```yaml
---
type: system                                     # required tooling key
description: "{at most 300 characters: what this document settles and where its boundary sits}" # required — the per-file account a folder is browsed by (references/frontmatter.md)
status: active                                   # required — draft = the machine as a whole does not run
objects: [run, run ledger, settlement]           # required — the objects this machine owns or moves
owns:                                            # transitional — region globs, one per subtree; read only by the ownership scan until it switches to header pointers (references/frontmatter.md)
  - packages/{pkg}/src/{machine}/**
---
```

```
# {The machine}

{The machine defined in its first sentence — bold the term — then what it takes in, what it leaves behind, and what a reader sees at the far end. Plain words.}

## Scope

- **In scope:** {what this machine decides}
- **Out of scope:** {subject} — {owning document}; {subject} — {owning document}

## Flow

### {Stage as a noun phrase — e.g. "Intake", "Settlement", "Re-drive"}

- **{Noun-phrase label}:** {what starts it or what it does at this step, as a person would describe it; what it writes that outlives it; what it refuses.}

{A role-level sequence or state diagram where the stages cross packages.}

## Decisions

- **{The decision as a noun phrase}:** {why; the alternative only where a reader would reach for it.}

## Promises

- **{Noun-phrase label}:** {a checkable guarantee or refusal; what holds at the far end; what a stalled run gets.}

## Gaps

- **{Noun-phrase label}:** {what is missing and what it would take.}

## For the agent

- **Objects:** {…}
- **Code roots:** {…} — directories, one per package the machine spans
- **Seams:** {…} by name
- **Checklist:** `docs/tests/{system}.md`
- **See also:** {neighbour}: {why}

No tables, routes or symbol rosters — those are the graph's.
```

### Marking what is decided and unbuilt

Where a stage is decided and not built, wrap its bullets in `<!-- UNBUILT:START — {what, where decided, the evidence it is not built} -->` … `<!-- UNBUILT:END -->` and say under Promises what runs instead. A design decided *against* carries no marker.