How the Book Works
One source of truth
Canon lives in docs/ in the vinxi-kernel repo and builds into this site — The Vinxi
Book — via apps/book (Astro Starlight). There is exactly one published documentation site
and exactly one place a claim about the architecture may live. If two pages disagree,
Concepts wins on vocabulary and the
architecture canon wins on substance. Agents: fetch /llms.txt from the
deployed site for a machine-readable index.
The ten rooms
| Room | What belongs there |
|---|---|
| Start Here | The onboarding story and reading arc |
| Vision & Principles | North star and product thesis |
| Architecture | The kernel canon — the-seam, ports-and-adapters, LLD, data plane, surface platform |
| Decisions | The governed ADR series |
| Products | The four verticals on Vinxi; the NetworkAccess pilot |
| Domain Knowledge | Courses + evergreen primers |
| Reference | Live non-canon references, incl. the legacy SmartInventory studies |
| How We Work | This page; runbooks as they mature |
| Patterns · Experiments | Being written |
Outside the rooms: docs/plans/ (process artifacts, not published), docs/superpowers/
(specs/plans from working sessions), and docs/_archive/ — see below.
The archive rule
Superseded eras move wholesale to docs/_archive/, banner-marked, excluded from the build,
never cited as canon. Deleted iterations live only in git history. If you find yourself
reading an archived page to answer a live question, stop — the answer belongs in a live room
or it isn’t decided yet.
The ADR discipline
Decisions follow ADR-0000: one numbered series, one index, immutable once accepted, supersede-and-link. A decision that isn’t in the series isn’t a decision.
The naming canon
Words are load-bearing: one word per concept, one concept per word — a wrong word here is a thousand mistakes later. The hierarchy (Lepton → Vinxi → products), the package law, and the retired-terms table live in Naming. Never introduce a synonym for an existing term; never resurrect a retired one.
Enforcement
Enforced in CI (the book job in .github/workflows/ci.yml) on every push and PR:
pnpm --filter book lint— the retired-terms tripwire (apps/book/scripts/book-lint.mjs) over every live-room markdown source. Case-sensitive proper nouns, exact code tokens;_archive/,reference/,superpowers/, and the naming table itself are exempt. A retired term in a live room is a build failure.pnpm --filter book build— the Book must build.pnpm --filter book check-links— every internal link in the built site must resolve (apps/book/scripts/check-links.mjs).
Run all three locally before pushing doc changes.