Record architecture decisions

[t4k]

Adopts the MADR format already in use in caltechlibrary/alchemist and caltechlibrary/workflows, and records the two decisions behind #46.

Additive only — three Markdown files, no code changes.

Why

The reasoning for #46 lived in its description, which stops being read the moment it merges. Both decisions leave behind something that looks like a mistake to anyone who did not watch it being made:

• Documentation sources live in docs/, but several Markdown files stay in the root
• The workflow calls an action directly rather than the shorter reusable workflow that exists for the purpose

Each is the survivor of an alternative that was tried or costed and rejected. Without that written down, the obvious move for the next person is to "simplify" them back.

The ADRs

0001	Record architecture decisions — the practice and its conventions
0002	Build the documentation site rather than publishing the repository
0003	Keep sources and generated files in separate namespaces

0002 records that a self-contained build workflow was written first and worked — the resulting site was byte-identical to what was published — and was rejected anyway, because it would be a copy that every other Caltech Library site needs too. It also records why the reusable workflow cannot be used here: the site compiles component bundles, so deno task build has to run first, and a caller cannot add steps to a job it did not write.

0003 records why some Markdown stays in the root. Not preference — cmt writes those files there, and its generator registry keys on the exact output filename, so cmt codemeta.json docs/about.md exits with unsupported format. It also collects what the flat layout actually cost: ten filenames shadowed between / and src/, a Lua filter referenced for three months but never committed, and generated HTML that drifted from its source.

Notes

• These are not rendered into the site. The build globs docs/*.md without recursing, so docs/decisions/ is carried in the repository and read on GitHub. That suits the audience — they are for people changing this repository, not for people using the components. ADR-0001 says so explicitly, since it is the obvious thing to wonder about.
• ADRs are immutable once accepted. A decision that changes gets a new ADR that supersedes the old one, rather than an edit.
• Routine changes do not need one. A new component, a documentation fix, a dependency bump — none of those qualify.

🤖 Generated with Claude Code