Set down the decision record shape and land the records for the container, the table, the tokens and the prose

[iderex]

The decision directory gets its shape, and four of the questions the rest of the
plan walks into get answers written down before the code that would assume them.

File	Issue
decisions/README.md, decisions/0000-template.md	#1
decisions/0002-what-docker-is-for.md	#3
decisions/0004-one-table-two-places.md	#5
decisions/0007-where-the-design-tokens-live.md	#65
decisions/0010-where-the-plugin-page-prose-comes-from.md	#79

Closes #1, closes #3, closes #5, closes #65, closes #79.

The evidence

Every measurement quoted in a record was re-run at this commit against the
published references rather than copied from the issue that asked for it. All of
them reproduce.

gh api repos/Flowfin/hub/pages --jq '{cname,html_url,https_enforced,source}'
{"cname":"flowfin.dev","html_url":"https://flowfin.dev/","https_enforced":true,"source":{"branch":"main","path":"/docs"}}

gh api repos/Flowfin/.github/contents/profile/README.md --jq '.content' \
  | base64 -d | grep -c '^| \['
12

gh api 'repos/Flowfin/hub/git/trees/HEAD?recursive=1' --jq '[.tree[].path|select(startswith("docs/"))]'
["docs/CNAME","docs/design-system.html","docs/index.html"]

curl -s https://flowfin.dev/design-system.html | grep -o -- '--[a-z0-9-]*:' | sort -u | wc -l
16

All four run 2026-08-09.

The index makes a claim about its own directory and carries the command that
decides it, run at this commit:

for h in "## Why" "## What the alternatives cost"; do
  for f in decisions/0[0-9][0-9][0-9]-*.md; do grep -qx "$h" "$f" || echo "$h  $f"; done
done
## Why  decisions/0005-the-speed-budget.md
## Why  decisions/0011-what-this-site-will-never-do.md
## Why  decisions/0012-the-browser-in-the-gate.md
## What the alternatives cost  decisions/0005-the-speed-budget.md
## What the alternatives cost  decisions/0011-what-this-site-will-never-do.md
## What the alternatives cost  decisions/0012-the-browser-in-the-gate.md

The four records added here carry all four headings, which is why they are not
in that output. Nothing reads these headings and no check refuses a record that
omits one, so the index says so in place rather than presenting the shape as
enforced.

The means

Markdown files in the tree. A record has to be readable by somebody who was not
there, diffable, and reachable from the work that assumes it without a tool to
render it. Nothing here needs a runtime and nothing is added that the tree does
not already carry. The template is a file rather than a section of the index for
the same reason: copying something already right beats reading a description and
approximating it.

Scope

Only decisions/:

git diff --name-only origin/main...HEAD
decisions/0000-template.md
decisions/0002-what-docker-is-for.md
decisions/0004-one-table-two-places.md
decisions/0007-where-the-design-tokens-live.md
decisions/0010-where-the-plugin-page-prose-comes-from.md
decisions/README.md

Size

Over the 400-line guidance at 416 added lines:

git diff --shortstat origin/main...HEAD
 6 files changed, 416 insertions(+)

The property that holds across every changed byte is that each file stands
alone: one record answering one question, plus the index and the template that
describe the directory those records sit in. No file is read by any other, so
the diff is six independent reads rather than one long one. Splitting it into
five landings would have moved the mainline under each of the others for no
reading benefit.

Review

There is no second reader for this change. That is stated rather than worked
around, and the evidence above stands in place of one: the commands are in the
records, they were run at this commit, and a reader can re-run every one of
them.