For an agent or a person bringing an app onto the kit, whether the app already exists or has not been started. It gives you the order of work that keeps a build or a migration from debugging its own seams, the pin and correction mechanics that decide whether a rule you are reading reaches the app you are in, and the retrospective on the two apps that did this first: what went in, what lapsed, and what would have caught each lapse sooner. The procedures themselves live in the install page, the app patterns and the contract docs; this file points at them where they exist.

Audience: an agent (or person) bringing an app onto the kit, migrating or new.

1. The four layers, and which one answers you#

The layer map is owned by docs/index.md (what each layer can do for you and where truth lives for a component) and the ruled-against list by docs/DO-NOTS.md. This guidebook does not carry a copy; a fifth copy is how the copies drifted. One sentence survives because a migrator needs it before anything else: existence is settled by the barrel export (packages/ui/src/index.ts), never by intent or a plan doc.

2. Starting fresh, or bringing one over#

Two doors into the kit, and both procedures are already written down in full: docs/app-patterns/05-starting-a-new-app.md for an app that does not exist yet, docs/app-patterns/04-migrating-an-app.md for one that already works. Read whichever door applies before writing a line. What this section adds is what a procedure cannot state for itself: which door you are actually in, and the traps that show up regardless of it.

Which door is decided by one question, not preference: does the app have behaviour a user would notice losing? If yes, you are migrating, and the migration guide's step zero is not optional, a parity ledger written before the first replacement (docs/app-patterns/04-migrating-an-app.md:16). If no, you are starting fresh, and you are exempt from that entire cost (docs/app-patterns/05-starting-a-new-app.md:21-23).

Both doors share the same build order, and the same reason for it: shell first, then page composition, then loading and empty and error states, then the real screens, because a page built inside an unsettled shell inherits two conflicting layout owners and you debug the seam instead of the page (docs/app-patterns/04-migrating-an-app.md:100-116, docs/app-patterns/05-starting-a-new-app.md:62-65).

Two traps neither doc can warn you about until you hit them. A local component sharing a kit export's name makes every call site ambiguous until it is renamed, and it is cheaper to write a second implementation than to find the first one already shadowing yours, which is exactly why the migration guide's step one exists (docs/app-patterns/04-migrating-an-app.md:57, :64-66). And a kit export existing is not evidence it is the proven path: FilterBar is complete, shipped, and used by nobody, because both existing apps built their own toolbars instead (docs/app-patterns/04-migrating-an-app.md:126-129). Check packages/ui/docs/ for shipped usage before adopting a component on the strength of it being in the barrel alone.

3. Reading order for an agent starting cold#

The governing copy of the cold-start reading order is AGENTS.md; read it there, not here (four copies of this list existed and no two agreed). The one stop the list cannot carry: after the reading, the awareness prompt on the showcase page you are about to touch names that surface's own source and contract doc (apps/playground/src/app/showcase-registry.ts:556), and it is the fastest ground truth once you know where you are going.

4. Pins, and the upgrade you have to choose to take#

The kit publishes on the owner's bump, never as a ride-along on an unrelated commit, and an app does not receive that bump automatically (CLAUDE.md:39-41, :94-97). Both consumer apps stay unchanged until their own deliberate upgrade; that is the union rule, the kit accumulating the superset while apps hold their pin until they choose to move it (docs/SCRIPTURE.md:93-96).

Where the pins stand and why they stay there, as of 2026-08-17: speedway pins ^0.0.14, walmart ^0.0.24, the kit is published at 0.2.0. Nothing built in the week of 2026-08-10 runs in a shipping app yet. That is a decision, not a lapse; the owner's ruling, verbatim: "I'm not updating speedway and walmart right now because it serves us no biz value right now until there's actual customer facing work to be done." The upgrade rides the next customer-facing piece of work in each app, and section 6 below is what that upgrade costs. The procedure itself, from pin to pin, is packages/ui/README.md, "Upgrading an app's pin", and packages/ui/CHANGELOG.md says per release what changes on existing screens and what an app can delete once it takes it.

The pin is the part that is easy to get wrong silently. Under npm semver, a caret on a 0.0.x version is a patch pin, so ^0.0.14 resolves to exactly 0.0.14, not to whatever the kit has shipped since (docs/design-language/00-overview.md:83, docs/app-patterns/05-starting-a-new-app.md:31-33). A canon rule written "as of kit 0.0.N" is unreachable in an app pinned below N regardless of what the rule says. Check the app's lockfile against packages/ui/package.json before relying on a prop, not after it fails silently at runtime.

What "deliberate" costs in practice, from a recent example: sidebar groups became collapsible by default on 2026-08-16, so an app that upgrades past 0.2.0 sees carets on every labelled group unless it opts out with collapsible: false (packages/ui/docs/app-shell.md:23). A version bump is not free even when nothing in your own code changed; read the contract doc for anything you use before taking the bump, not after.

5. How a correction becomes law#

A defect caught on a shipping screen is not fixed once, in place, and left for the next person to rediscover the same way. It has a path into something reusable, and the path is consistent enough now to name.

The worked example three docs already point at independently: a page shipped a second theme toggle while the navbar already carried one, and the owner named it an anti-pattern. The fix did not stop at removing the toggle. It became a general rule in the AppShell contract doc's Banned combinations, "do not mount a second toast stack, modal host, or file-preview host per shell instance" (packages/ui/docs/app-shell.md:54), and that doc's "Before you adopt this" checklist now opens by naming the case directly (packages/ui/docs/app-shell.md:60). docs/DO-NOTS.md picked both up automatically the next time it was regenerated, because it reads every contract doc's Banned section by construction (docs/DO-NOTS.md:22-26). And docs/app-patterns/13-when-a-solution-is-unsuitable.md generalised the same case into its first tell, something that only fits without a build because a parent already renders it (docs/app-patterns/13-when-a-solution-is-unsuitable.md:24-28).

The same lens also reads the canon directly, not only contract docs: any sentence in the twelve design-language docs containing "never," "do not," "must not," "is a defect," or "banned" is picked up under docs/DO-NOTS.md's "By canon doc" section without anyone filing it a second time, for example "Mono is for identifiers... never decoration" (docs/design-language/01-foundations.md:28, surfaced at docs/DO-NOTS.md:230).

The two routes in, then: write the fix at its smallest true scope, a component's Banned combinations section if it is one component's mistake, a canon trait doc's own principle if it crosses components. Then regenerate the lens, node scripts/build-do-nots.mjs (CLAUDE.md:37-38). Skipping that step is the specific failure the scripture already names for the general case: a rule nothing reads is not a rule (docs/SCRIPTURE.md:399-400).

6. Validating a change#

Two typechecks and a real browser, at minimum, before any UI change is done. Kit: pnpm typecheck and pnpm vitest run in packages/ui. Playground: pnpm exec tsc --noEmit in apps/playground (both through fnm, AGENTS.md rule 1). CI additionally runs pnpm lint:tokens, pnpm -r test, the citation ratchet and the do-nots regeneration on every push (.github/workflows/ci.yml), so a change that skips them locally reddens main. Then the page itself, in both themes, dark being the literal theme name versable-dark (CLAUDE.md:14-19). This wave's own landing build additionally gated at a 375px phone width alongside 1280px desktop, with reduced motion emulated separately (docs/plan/58-w2-1-landing-design.md:146-147); carry that habit into any surface with real layout risk, not only the pages built under it.

Which review pass or skill fires for which kind of change is docs/app-patterns/14-validating-a-ui-change.md: the categorical pass, the adversary, the routing table, and, from the retrospective below, which checks caught what and in which order. The two typechecks and the browser above are the floor; that doc is the rest.

7. The retrospective: what went into speedway and walmart#

The owner asked for this half in the words "what went into speedway and walmart, the lapses, when each was noticed, what would have caught it sooner", and then ruled that no interview would feed it (doc 57 D8c): the material is gathered by agents from the record and checked by a second agent, with the owner's own review optional at the end. So everything below is cited or it is not here. The strata, in the order they were trusted: the three commit histories since 2026-06-20 (dated, attributable), the atone ledger of recorded mistakes with each event's precheck (the question that would have caught it), the sessions' own runtime notes, 235 owner messages that carry lapse-signal phrasing (quoted only verbatim, with their timestamp), and the plan docs. A machine digest of seventeen docs was used as a checklist and re-derived; five of its twenty-four candidates could not be grounded and are absent. A separate adversarial vet then checked every citation mechanically, trimmed thirteen lapse rows of a citation that did not hold, merged two timeline rows, and corrected four rows that had claimed a remedy postdated the lapse it would have caught when the remedy predated it (the run's most common draft defect, and it flattered the record in one direction). What the vet could not check is listed at the end of this section.

7.1 The timeline#

7.2 The lapses#

7.3 The families that recur#

Family 1: a rebuild replaces accumulated UX without a parity audit. Rows 2, 3, 10, 11, 26. A page or an app gets rewritten from scratch instead of ported, and the rewrite is verified against itself rather than against the reference the owner remembers, so the gap surfaces only when the owner opens the page. The instruments that exist now: ~/.claude/rules/invariant-graduation.md and its "UI surface purge gate", graduated directly from row 2 and requiring a parity ledger or explicit owner approval before any owner-reviewed surface is deleted or replaced; /vis-compare for rendering the reference and the result side by side, which already existed at the time of row 3 and was not invoked; and docs/app-patterns/04-migrating-an-app.md:16, whose Step 0 is writing the parity ledger before anything is replaced.

Family 2: a local surface diverges from the canon or a design mock and ships unverified against it. Rows 6, 7, 8, 9, 14, 17, 18. A component or a piece of copy is built from memory, from a nearby sibling, or from a cheaper extraction instead of the mock or the canon rule that governs it, and the divergence is caught only when the owner looks at the pixels. The instruments that exist now: the [design-mocks] rule in ~/.claude/rules/testing.md; docs/DO-NOTS.md, generated by scripts/build-do-nots.mjs over every contract doc's Banned section and every canon "never" sentence; the "Before you adopt this" checklist on 32 of the 33 files in packages/ui/docs/; and /ui-categorical-check for the measurable classes of drift, which predates rows 8, 9, 14, 17 and 18 and was reached for in none of them.

Family 3: the instrument was absent, not the judgment. Rows 1, 13, 16, 21, 22, 23, 24. These are not bad decisions but missing or unfindable checks: no definition-of-done check on an archive sweep, no citation checker, no drift guard between a token and its component-layer consumer, no fresh-eyes README exercise. The instruments that exist now: scripts/check-citations.mjs (ruling D11, versable-builder@27a10f1, 666 citations clean at that run) and the do-nots lens (scripts/build-do-nots.mjs, docs/DO-NOTS.md). Still unbuilt: a numeric token-versus-component drift guard (row 22) and any recurring fresh-consumer exercise of the README (row 24).

Family 4: a new surface skips the sibling or naming sweep. Rows 4, 5, 19, 20, 25. A page or component is added without diffing the nearest sibling that solves the same problem, producing a missing pagination model, a re-authored panel shell, a shadowed component name, or a duplicated control on one screen. The instruments that exist now: the sibling-diff prechecks recorded in rows 4 and 5; the naming-collision question that opens the "Before you adopt this" checklist in packages/ui/docs/; and the walmart tech-debt review (walmart-mvp/docs/04-technical-debt.md) as the channel that routes app-blocked-on-kit findings to the kit. Row 20 is the family's exception: the kit genuinely lagged the app's need, and its remedy is release cadence rather than a check.

Family 5: a process declared complete without its own steps having run. Rows 12, 15, 27, 28. A route set, a build gate, a handoff or a UI pass is reported done because its name was invoked or its happy path was seen once, while the steps that make it done (boot into every mapped route, run the gate that was named, hand over the prerequisite you yourself hit two days earlier, build the pass that was asked for three times) never ran. This is the shape the atone ledger records most often across every project, sixteen events by 2026-08-17, and it graduated to a rule with a mechanical gate: ~/.claude/rules/exercise-based-verification.md (run the changed path in the state that matters before saying done; a collect, a compile or a lint is not a run) and the declared-ready Stop hook behind it. In this repo the same rule is CLAUDE.md's own bar for done: exercised in the running playground, in both themes, not merely typechecked.

Rows 12, 15, 27 and 28 were left unclaimed by the vet, which named their shared shape and left the fifth family to the author; the atone slug behind them is declared-ready-without-runtime-exercise.

7.4 What this half is built from, and what it could not check#

Method: /pyramid-sweep's spine (manifest, extract, mechanical cut, one synthesis seat, one adversarial vet, human bake) with the instruments swapped for this domain: the sessions had already distilled themselves into commits, atone events and runtime notes, so raw transcripts were mined mechanically for the owner's own words and nothing else. Run dir: ~/.claude/style/sweep/20260817-guidebook-retro/ (candidates, the draft, the vetted output with its per-row log).

Not checked, stated so it is not mistaken for checked: whether the five-family cut is the right taxonomy (families are an interpretive claim; the vet checked only that each row is claimed once and every remedy cited exists); the 2026-07-13 owner batch beyond its opening 2,500 characters; and whether row 25 is a defect at all (walmart-mvp/docs/04-technical-debt.md:105 states the two search boxes as fact and records that the finding was never confirmed).

The owner's optional review of this half is task #92; if it happens, its corrections land here as further rows or as edits with their own citation.