# Voice

The prose is most of the value. A blueprint whose blocks are labelled correctly
and whose hover cards say nothing is a worse artifact than a whiteboard photo,
because it looks authoritative.

The default register for generated documentation is wrong for this. Correct it
deliberately.

## Who you are writing for

A competent engineer who has never seen this system and has about four minutes.
They can read code. They cannot yet tell which parts matter, which decisions
were forced, and which things will bite them.

Write the way you would explain it to a colleague at a whiteboard, out loud.

## The one test that matters

**Every `why` ends with something the reader would not have guessed from the
name.** That last sentence is the entire reason to open a hover card.

Not guessable:

> Health checks are shallow on purpose: a deep check that touched the ledger
> took the whole pool down in March when a slow query made every instance look
> sick.

Guessable, therefore worthless:

> The load balancer distributes traffic across healthy instances for high
> availability and reliability.

If you cannot find the non-obvious sentence, you have not read enough of the
code yet. Go back rather than padding.

## Register

Short declaratives. Concrete nouns. Say the surprising thing plainly instead of
building up to it. Contractions are fine. Semicolons are fine.

Match this:

> The diagram is a loop because the system is: one archive → pick a parent →
> write a new doctrine → play it → rate it → file it → back to the archive.
> Everything below the loop is the game itself: the Rust engine sits beside it,
> finished and not switched on.

## Never write

- Marketing adjectives: powerful, seamless, robust, scalable, cutting-edge,
  state-of-the-art, best-in-class, enterprise-grade. The checker warns on some
  of these in the tagline; it cannot catch them everywhere.
- "Responsible for", "handles", "manages", "facilitates", "leverages",
  "utilises". Say what it does.
- Bullet lists of features inside a `why`.
- A restatement of the block's own label. `is` on a block called Load Balancer
  should not begin "load balances".
- Hedging you do not mean. "May potentially" is two hedges for no reason.
- Anything you would not say out loud to a colleague.

## Field by field

**`title`** — what the system *is*, not what the repo is called.
`metalcraft-agent` → "The Pod". `payments-platform` → "The Payment Path".

**`tagline`** — one lowercase sentence, no full stop needed. What it does.
`one rust binary that runs an agent as a scoped persona, on a box you own`

**`stat`** — facts a reader could not guess, and that reveal *shape* rather than
size. "582 distinct doctrines" is a stat. "47 source files" is not.

**`is`** — one clause, what it *is*, not what it is for. "the ledger — every
authorisation, capture and refund ever taken", not "handles order persistence".

**`why`** — 2–4 sentences. What it does, roughly how, then the non-obvious
thing. Do not open with "This module".

**connection `carry`** — the concrete thing, written for a human to read:
`INSERT INTO orders (id, cart_id, state, amount_cents)`, `POST /v1/checkout
{cart_id, payment_method}`, `AppContext { SqliteStore, BlobStore, OwnerIdentity }`.

**connection `why`** — when it fires, what it carries, and what failure looks
like. The failure sentence is the one people remember.

> Written before the processor is called, never after. If the process dies
> between the two, the reconciler finds the orphan by its state.

## The narrative panel

Two tabs. The first says what the system does and why it is shaped this way.
The second says how it is built and what was traded away.

Structure that works:

1. `h` — the title again, then a paragraph that gets a stranger oriented in
   three sentences.
2. The organising idea. Every system has one; find it and name it.
3. `note` — a short aside telling the reader how to use the drawing.
4. The rule or invariant the whole thing rests on, and what breaks without it.
5. In the second tab: the dependencies you did not write, the extension seam,
   the determinism or consistency story, and **what is deliberately missing**.

That last section is the most valuable and the most often skipped. Write down
the gaps — no service mesh, no fallback provider, no cross-region reads — with
one clause on why each was cheaper to live with than to run. It stops the next
person having to work out whether it was an oversight.

Close with a paragraph on where the file lives, so a reader who spots something
wrong knows what to edit.

## Links

Use 6–12 `[[phrase|block_id]]` links across the panel. Link the phrase that
names the thing, not a bare noun:

- Good: `[[a named, scoped tool set|persona_store]]`
- Good: `[[the load balancer|ingress]]`
- Weak: `[[it|ingress]]`

Do not link the same block five times. Do not link every block — a panel where
everything is highlighted has highlighted nothing.

## Glossary

Use `{{term}}` for words a competent engineer outside this domain would not
know, and define them in one sentence without jargon. Two or three per blueprint
is plenty. Do not define words the reader obviously knows.