0. What this document is#

This is the intent layer of versable-builder: the document that says why this project exists, what it must achieve, how it is supposed to be used, and, in more detail than anywhere else, the ways a project like this fails and how honestly we can currently claim to be fighting each one. The layers below it stay authoritative for their own domains: the design canon is law (docs/design-language/README.md), app-patterns is method (docs/app-patterns/README.md), the component docs are contract, and docs/index.md:30-41 says where truth lives for existence, contract, and appearance. This document justifies; it never overrides.

Three reading rules:

• Every load-bearing claim is numbered (S1, S2, ...) and carries either a citation into the tree or an explicit PARTIAL or MISSING marker. There is no third state. Audits (task #55 first) cite S-numbers.
• Claims of absence record the command that proved them, following the method of docs/plan/45-docs-value-audit.md.
• One pen. Like the canon, this doc changes only through an owner-visible diff, and every change re-runs node scripts/check-citations.mjs docs. The explicit docs argument matters: the checker's default scan set (scripts/check-citations.mjs:20) does not include the docs root, so a bare run never reads this file.

The sources this doc compresses are digested with full citations in docs/plan/49-scripture-evidence/ (origin, app lessons, docs sprint, attempts and gaps). The plan that authorized it is docs/plan/49-scripture-plan.md.

1. Intent: why this exists#

S1. The kit exists so that a correction made once stops being a thing anyone remembers. The founding form of this sentence is the forge model: versable-builder is "a repo forge: a monorepo holding a shared UI kit, frontend toolkit... plus the per-customer MVP apps composed from them" (docs/plan/archive/00-master-plan.md:17-19). A second app must not re-decide what a table, a modal, or an empty state is (packages/ui/README.md:8-9).

S2. The deeper target is duplicated vocabulary, not just duplicated code. "One vocabulary per concern... every major pain in enhancement-product traces to N parallel vocabularies for one concept (7 error taxonomies, 4 color unions, 3 meanings of widget)" (docs/plan/archive/00-master-plan.md:32-35). The kit is the place where one vocabulary is decided, and the apps are where it is spent.

S3. Shared code is held to a categorically higher bar than app code, on purpose: "apps/* may be expedient under deadline. packages/* ... never are" (docs/plan/archive/00-master-plan.md:25-28). The price of the higher bar is paid once; the discount is collected by every consumer.

S4. Abstractions are born from evidence, never ahead of it. A hack lives in an app until it earns graduation (two or more real consumers), and a shared contract ships with its first real consumer, not before: the canary discipline (docs/plan/archive/00-master-plan.md:27-28, 42-43). Where we violated this, it cost us; §6 F-entries carry the receipts.

S5. Dark mode, theming, and visual consistency are meant to be structurally free, not maintained by vigilance: the three token layers (docs/plan/archive/01-ui-system.md:15-27) exist because "that single discipline is what makes dark mode a config update" (docs/plan/archive/00-master-plan.md:152), with a lint gate banning raw color values from day one (docs/plan/archive/01-ui-system.md:35-41).

S6. Why should anyone bother using it? Because the alternative was lived and measured, not imagined: the pre-kit apps grew parallel error taxonomies and color unions (S2), and after the kit existed, the places that kept hand-rolling kept paying (walmart's dual Select, F2; two competing status-tone systems live in one app today, components/StatusChip.tsx:19 beside lib/statusColors.ts:1-3; the earlier exhibit at docs/plan/49-scripture-evidence/app-lessons.md:111-115 was repaired while the condition itself was not). The kit is the cheaper path exactly when it is actually reached for, and this doc's §6 is honest about when it has not been.

2. Goals, specific and overall#

Each goal names the success criterion that would prove it; criteria live in §7 with their measurements.

S7. One shared implementation per UI concept, consumed by every app. Tables, modals, toasts, empty states, toolbars, status language. Proof criterion: no app-local duplicate of a kit primitive survives a bump cycle. C4 and C6 are its nearest measurements; a dedicated duplicate-survival check does not exist yet, and saying so here is cheaper than pretending C4 covers it.

S8. Corrections propagate by version, not by memory. A fix lands in the kit once and reaches walmart and speedway on their next deliberate bump, per the union rule: the kit gets the superset, apps stay unchanged until they upgrade (owner ruling 2026-08-14, docs/plan/49-scripture-evidence/attempts-gaps.md:169-174 carries the measurement sketch).

S9. The closed prop vocabulary stays closed. Every component draws from one reviewed vocabulary table; "additions to this table are a review event, not a per-component decision. This is the anti-330-props mechanism" (docs/plan/archive/01-ui-system.md:102-103).

S10. The showcase is the kit's living proof, not its advertisement. Every export has a page, examples read as real app use, and printed source cannot drift from rendered truth (the shared-example-module mechanism, docs/plan/47-showcase-execution.md:26-37; the owner's doc 48 feedback is the standing evidence that presence alone is not this goal).

S11. An agent in a consumer app reaches for the kit by default. Desired behaviour is specified in §5 (S19 to S25); the mechanical rules already exist in AGENTS.md:12-45.

S12. The kit earns adoption rather than assuming it. "We still don't know if this will work as good as we think it will" is the owner's own standing sentence, and this doc keeps it in §8 until a fresh app or agent adopts the kit without us steering. Until then, adoption claims stay PARTIAL.

S13. A new customer MVP ships fast because it composes. The founding pitch is "an MVP speed lane and built as the seed of the replatform" (docs/plan/archive/00-master-plan.md:19-20): the same shared layer that makes apps consistent must make the next app FAST, with its first screens composed from kit plus recipes rather than designed from scratch. Speed is a goal in its own right, not a byproduct; a kit that is consistent but slow to compose with has failed this goal.

S14. The written system is a deliverable, not documentation. The project front door names three deliverables: "a component kit, a written design language, and the recipes that say what a request for a screen actually brings along" (README.md:8-9). The canon stays law derived from shipped code (docs/design-language/README.md:6-8), the recipes stay the method layer, and both stay CURRENT: a canon rule or recipe that drifts from the shipped reality is a defect of this goal, not a doc chore.

3. Non-goals#

S15. Not a general-purpose design system. The forge grows "in sync with real deliverable apps so every abstraction is requirement-fed, never speculative" (docs/plan/archive/00-master-plan.md:20-21). A component with no real consumer waiting is out of scope by definition (S4), however useful it might look.

S16. Not a rebuild of the platform underneath. "Don't fight daisyUI" is an owner rule: extend via theme vars and small CSS, "never rebuild a control it provides" (AGENTS.md:25-26).

Why a kit of our own at all, then, instead of an off-the-shelf design system and a style guide: the platform underneath is bought (Tailwind and daisyUI supply the controls and the themes), and what this repo adds is the part nothing off the shelf carries, the Versable vocabulary for tables, status, toolbars, empty and loading states, and the corrections the two apps have already paid for. A stock system would give every app the same controls and leave every app to re-decide the same screens; the kit exists for the second half of that sentence (S1, S2). Nobody had written this down before 2026-08-18; a review panel that could see only the front doors asked.

S17. Not a UI-only ambition that quietly claims the whole stack. The founding plan named a five-package toolkit layer (toolkit, query-kit, qsync, auth-kit, schemas; docs/plan/49-scripture-evidence/origin.md:61-67) and a Python core; only the kit is real today, and §6 F8 carries that honestly. This doc's claims are about the UI system unless a package earns its own S-claims.

S18. Not frozen aesthetics. The canon's cases are "worked from shipped code" (docs/design-language/README.md:8) and it changes by evidence through one pen; deviation by an app is legitimate and never free, recorded with its reason (docs/design-language/README.md:66-69).

4. Usage mechanism#

How the kit reaches an app, each step cited to the surface that owns it:

• Existence is the barrel. "If it is not exported [from packages/ui/src/index.ts], it does not exist" (docs/index.md:34-35).
• Distribution is the registry. Bump packages/ui/package.json, push to main, and the publish-kit workflow publishes any version the registry lacks; never publish from a laptop (CLAUDE.md:41-44). Bumping is therefore a release decision, the owner's, never a ride-along.
• Consumption is a pin. Apps pin an exact patch version; "a caret on a 0.0.x version is a patch pin, so ^0.0.14 resolves to exactly 0.0.14" (docs/design-language/00-overview.md:77-78).
• Upgrades are the union rule. The kit gets the superset; apps stay unchanged until their next deliberate upgrade (owner ruling 2026-08-14, recorded at docs/plan/47-showcase-execution.md:77 and docs/plan/44-showcase-refinement.md:193). Honest note: this load-bearing ruling lives only in plan docs; it has no ground-rule home in AGENTS.md yet.
• Truth for behaviour is layered. This doc defers to the handbook's orientation ladder (docs/index.md:30-41) rather than restating it; whether that ladder is THE canonical statement is exactly the unresolved question the PARTIAL below records.
• The showcase is gallery plus demo. /components/* is one page per component, every state; /demo/* is the product demo whose demo/jobs and demo/review are "the canonical composition references" (docs/index.md:46-61).

Two honest defects in the mechanism's own documentation, found while compressing it (docs/plan/49-scripture-evidence/docs-sprint.md:100-120):

• PARTIAL: the layering has no canonical statement. Three docs state the three-layer split three differently shaped ways (docs/design-language/README.md:48-58, docs/app-patterns/README.md:19-30, docs/index.md:30-41); each is complete, none is named the master.
• PARTIAL: the consumer-side upgrade path now has a written home and no reader yet. packages/ui/README.md (Upgrading an app's pin) (2026-08-18) is the checklist an app follows to move its pin, and packages/ui/CHANGELOG.md names what each release changes on existing screens and what it retires; both ship in the package. It stays PARTIAL until an app has followed it once and recorded the cost in docs/GUIDEBOOK.md section 4. Before 2026-08-18 the path was documented nowhere; only the kit-side bump and publish half existed.

5. Desired agent behaviour#

The mechanics live in AGENTS.md (ground rules 1 to 8) and are not restated here. This is the intent those rules serve: what an agent building in a consumer app should be TRYING to do.

S19. Reach for the kit before building. Existence means the barrel (S-claim above); if the thing is not there, the aligned move is to extend the kit or file the gap, not to fork a local copy. Every local reinvention is a future F2 entry.

S20. Extend by prop first, preset over it. "Presets are shorthands, never gates... A feature reachable ONLY through a preset is a design defect: build the prop first, then the preset over it" (AGENTS.md:38-41).

S21. Verify by running, not by reading. "A change is done when the page renders and the interaction works... Screenshot claims require having looked at the screenshot" (AGENTS.md:29-33).

S22. Treat an app-local fix as a loan. The kit absorbs it or the debt compounds; walmart's FacetChips becoming the canon's reference implementation is the worked example (docs/plan/46-speedway-conventions-sweep.md:48-49).

S23. Deviate openly or not at all. "Deviation is legitimate and never free... A surface that deviates records the reason in its own doc" (docs/design-language/README.md:66-69).

S24. Describe what ships. "A line describing an unshipped state is a lie with a good excuse" (docs/app-patterns/01-documenting-a-surface.md:49-51); behavioural claims carry a file:line or say they are unverified (docs/app-patterns/01-documenting-a-surface.md:57-60).

S25. Stop and flag instead of inventing exceptions. "Do not invent exceptions to the ground rules. Stop and flag instead" (AGENTS.md:100-101; punctuation adjusted from the source under this repo's style ban).

6. Acknowledged failure modes#

Four families: DRIFT (things fall out of sync), ADOPTION (the kit exists and apps do not benefit), HONESTY (we fool ourselves about state), and PROCESS (how we work betrays intent). Every entry ends in ATTACKED, PARTIAL, or MISSING, with no softer grade available; a MISSING entry records the command or read that proved the hole (the vocabulary as one page, cited by the platform contract too: docs/app-patterns/15-claim-status-vocabulary.md). F1 to F3 were the ratified slice's worked examples; the catalog continues from F4, and a short outside-evidence list closes the section, marked as native knowledge rather than lived history.

F1. Token and vocabulary drift in consumers. Status: ATTACKED. The mode: apps reach for raw palette classes or invent local color unions, and the one-vocabulary intent (S2) dies by a thousand conveniences. The attack is mechanical, not cultural: pnpm lint:tokens (root package.json:11) fails raw palette classes and bracket-arbitrary colors, locally per AGENTS.md:20-24 and in CI at .github/workflows/ci.yml:20, with runtime data colors forced through accentStyle(color) (packages/ui/src/internal/accent.ts). This is one of the few gates in the project that is fully wired today. Its reach is the forge only; see C5 for the consumer-side gap.

F2. Dual implementations of one primitive coexisting. Status: PARTIAL. The mode: a pre-kit local component survives beside the kit's version of the same thing, call sites split between them, and nothing forces migration. Lived: walmart's local Radix Select (frontend/src/components/ui/select.tsx, first committed 2026-05-30) is still imported at three call sites while the kit's Select serves others in the same app (docs/plan/49-scripture-evidence/app-lessons.md:79-96); the same app runs two competing status-tone systems today, lib/statusColors.ts:1-3 forbidding local variants in its own comment while components/StatusChip.tsx:19 defines a parallel five-tone map imported by 13 files (docs/plan/50-audit-evidence/verification.md, facet D row 2). The exhibit that stood here before, 18 hand-rolled skeleton divs, was repaired the day before this doc was authored; the repair retires the example and proves the class is fixable, not that it is gone. What attacks it today: the sweeps and parity rounds find these (that is how we know), and the showcase makes the kit version visible. What does not exist: any forcing function, migration task, or gate that notices a duplicate at build time. Finding is attacked; migrating is not. PARTIAL.

F3. Agent-verified done is not owner-verified done. Status: MISSING. The mode: passes complete, adversarial gates go green, commits land, and the owner's next message still reads as fresh dissatisfaction, because nothing in the process requires an owner-observed acceptance step before the queue moves on. Lived, at full scale, this week: plan 47's five passes all closed with gates (docs/plan/47-showcase-execution.md), and doc 48 arrived the next day (docs/plan/48-showcase-feedback.md:5-10). Checked for a countermeasure: rg -in "owner accept|acceptance gate|owner-verified|owner sign.?off" docs/ returns only ad-hoc per-item sign-offs (charter amendments, a layout acceptance), never a defined process stage. The audit's assumption seat widened the vocabulary and made the finding sharper, not weaker: a per-chunk owner-review step WAS once stated as process (docs/plan/25-ui-feedback-chunks.md:10, docs/plan/31-flow-simplification-chunks.md:9) and its blocking half was rescinded by owner directive (docs/plan/32-code-complete-program.md:151). The idea existed; nothing binding survived. MISSING. The nearest partial structures are the TRACKING.md To-be-reviewed queue, which parks agent-done work for owner testing but does not gate the next pass on it (docs/plan/TRACKING.md:24), and speedway's owner-only docs/completion.md sheet, which is per-module and app-scoped. Re-run note: this doc now matches its own absence command, so future re-runs must exclude docs/SCRIPTURE.md and the 49-scripture-evidence directory.

F4. Inventories restated in prose rot. Family: DRIFT. Status: PARTIAL. The mode: a doc restates what code already states (a prop table, a not-built list, a count), and the restatement drifts within weeks. Lived and self-recorded: the handbook's own prior inventory kept naming four things as not-built after all four had shipped (docs/index.md:43-44). The attack where applied is structural: stop restating, point at the barrel. But it is a principle, not a gate; nothing detects a new inventory being born.

F5. Citation rot is hours-scale. Family: DRIFT. Status: PARTIAL. Demonstrated, not assumed, twice. Past incident: one walmart commit landed five hours after a doc's verified-at timestamp and shifted every cited line by one, and canon doc 02 carried a wrong range pointing at a dropdown's keyboard handler instead of the button escalation it claimed (docs/plan/45-docs-value-audit.md:80-84, 34-36; both repaired by the G1 citation batch, task #47). Live re-demonstration, caught by this doc's own gate while this doc was being written: a single speedway commit rewriting WorkspaceNav.tsx and root.tsx put 21 new citations into ROT-SUSPECT in one stroke (85 to 106; docs/plan/49-scripture-evidence/honesty-gate.md, the ROT-SUSPECT section, with the grouping command). The attack: scripts/check-citations.mjs exists and runs (669 citations across 55 docs on its default set, measured 2026-08-15 by running it), but it is heuristic and non-blocking, and the ROT-SUSPECT tier stands unreviewed. A checker that never blocks is a review cue, not a gate.

F6. Docs claim exports the barrel does not have. Family: DRIFT. Status: PARTIAL. Lived: timestamp.md claimed three formatters exported while the barrel exports two, so the doc's own import line failed at compile time (docs/plan/45-docs-value-audit.md:117-121; since corrected, the doc now states the gap itself at packages/ui/docs/timestamp.md:17). Audits catch these; no gate compares contract docs against packages/ui/src/index.ts.

F7. Dev-tree pin masking. Family: DRIFT. Status: PARTIAL. Speedway pins ^0.0.14 for a clean install while its dev tree symlinks the live packages/ui, so development runs code an install would not deliver; "dev behaviour and a clean install disagree there" (docs/design-language/00-overview.md:78). The canon documents the footgun, which is awareness; nothing verifies any adoption claim against a clean install, which would be the attack. As of 2026-08-17 the wider fact is also on the record: both apps pin below every kit change of the 2026-08-10 week (speedway ^0.0.14, walmart ^0.0.24, kit 0.2.0), by owner ruling, until customer-facing work in an app makes an upgrade worth taking (docs/GUIDEBOOK.md, section 4).

F8. A shared package ships with zero consumers. Family: ADOPTION. Status: PARTIAL. The founding failure: the toolkit's own definition of done required a real call site (docs/plan/archive/02-toolkit.md:138-139), a sweep filed it shipped without checking, and roughly 82% of the duplication it exists to prevent was written after it existed (docs/plan/43-toolkit-rca.md:16-21). The RCA names the fix path, but it awaits an owner ruling, and no mechanism anywhere reads a package's definition-of-done at archive time. The rule that died is still dead; what changed is that we know it.

F9. Pin lag teaches hand-rolling that outlives the pin. Family: ADOPTION. Status: PARTIAL. Speedway documented its own reinvention rationally in a comment: "Interim local formatter until the kit pin carries Timestamp's absolute mode" (docs/plan/49-scripture-evidence/app-lessons.md:43-49). The union rule bounds the damage window, but nothing retires the interim copy when the pin catches up, and the consumer-side upgrade path is itself undocumented (§4's MISSING).

F10. The showcase persuades no one by itself. Family: ADOPTION. Status: PARTIAL. The owner's own words: "The select menu is shown here so flashily but walmart ended up re-inventing so much of this anyways" (docs/plan/48-showcase-feedback.md:47-49). Sweeps and parity rounds find the divergence after the fact; nothing at build time notices an app hand-rolling what the kit ships. Finding is attacked; preventing is not.

F11. Coverage-as-existence read as coverage-as-quality. Family: HONESTY. Status: PARTIAL. The P0 ledger measures export-to-page existence exactly and honestly (apps/playground/COVERAGE.md:11-30); the temptation is reading its 93/94 as "the showcase is good." Doc 48 is the standing refutation: ten of seventeen per-page items ask for more or more realistic examples on pages the ledger counts as covered (docs/plan/49-scripture-evidence/attempts-gaps.md:128-133). The ledger itself now states what it does not measure; no instrument measures the rest.

F12. Absence claims without a recorded command get reversed. Family: HONESTY. Status: ATTACKED. Doc 44's adversarial gate reversed both of the plan's absence claims (a "dead" page that was routed, a "missing" composite that mostly existed; docs/plan/44-showcase-refinement.md:11-14). The attack is now house method: every absence claim records its exact command (docs/plan/45-docs-value-audit.md Method; this doc's own §0 rule), and gates re-run them.

F13. Ledger claims calcify into assumed truth. Family: HONESTY. Status: PARTIAL. Claims that survive checkpoint after checkpoint without a verifying artifact start reading as facts. Caught twice while building this very doc: the deploy-path failure count turned out to be ledger-only while the path itself is real (docs/plan/49-scripture-evidence/attempts-gaps.md:101-109), and this entry's own first draft asserted a walmart lint gate into existence off a bare package.json:11 basename that had silently resolved to the forge's file instead of walmart's, which has none. The doc's own adversarial gate caught it (docs/plan/49-scripture-evidence/honesty-gate.md, finding H1). The attack is the VERBATIM-FROM-LEDGER discipline plus the gate that caught H1; both are practice, not mechanism.

F14. Standing assumptions get invented mid-build and reversed after. Family: PROCESS. Status: PARTIAL. Plan 47 baked in one-home-per-demo without an explicit ruling; doc 48's C3 overturned it after the work shipped (docs/plan/48-showcase-feedback.md:87-89). The countermeasure that exists: owner rulings get recorded as ground rules and presets when they land (AGENTS.md:38-45 is ruling D1 doing exactly that). What does not exist: a step that surfaces a plan's silent defaults as rulings-needed before build.

F15. A rule nothing reads is not a rule. Family: PROCESS. Status: PARTIAL. The general form of F8, and the project's sharpest lesson: the canary rule existed on paper and died unenforced; the handoff playbook's git-add ban was violated mid-project by the exact failure it named (docs/plan/49-scripture-evidence/origin.md:186-224). Where a rule became a mechanism this repo owns, it held: lint:tokens in CI (.github/workflows/ci.yml:20) and the publish-kit workflow (CLAUDE.md:41-44). The counter-case proves the same point: the em-dash style rule bound only agent-side tooling outside this repo, and the tree recorded 97 escapes needing a manual sweep (apps/playground/COVERAGE.md:30); the closed prop vocabulary is likewise "a review event" (docs/plan/archive/01-ui-system.md:102), a human process with no automated reader. The honest generalization: this project's rules bind exactly as far as their enforcement reaches, and several load-bearing rules still have no reader.

F16 to F19 came out of review round 2 (the magi panel of 2026-08-17, fold at docs/plan/TRACKING.md, the round-2 row) and were ratified by the owner on 2026-08-18. Each is graded as of that day, not as of the finding.

F16. The shipped package has no behavioural test. Family: HONESTY. Status: ATTACKED. The mode: the package consumers install is the one nothing exercises, while the package nobody consumes carries the suite. Lived: on 2026-08-17 packages/ui had no test script and zero test files against 19 in the zero-consumer toolkit, and CI's pnpm -r test skipped the kit silently (.github/workflows/ci.yml:21, fold row L1). The attack landed the next day: packages/ui/package.json:11 runs vitest, and packages/ui/test/render-smoke.test.tsx mounts every component export in both themes and pins the barrel as a snapshot, mutation-tested both ways (commit 6030b2d). It is a smoke, not a behavioural suite; the grade is ATTACKED because the gap it names, no test at all on the consumed package, is closed, and C1 to C10 can now carry a test criterion.

F17. A star re-export hides the inventory the docs told agents to grep. Family: HONESTY. Status: ATTACKED. The mode: the barrel is documented as the existence check ("if it is not exported from index.ts it does not exist"), and one export * from "./table" made 25 runtime names invisible to exactly that check; the panel's jester made the mistake the doc invited (fold row L9). The attack: the table module is exported by name (packages/ui/src/index.ts:130-202, commit cf0d756), the smoke's "names the table module by name, not by star" case pins it (packages/ui/test/render-smoke.test.tsx:50), and the barrel snapshot fails on any future star.

F18. Raw-source publish with an unannounced bundler contract. Family: ADOPTION. Status: PARTIAL. The mode: the kit publishes TypeScript source, not a build (exports maps . to ./src/index.ts, 44 files carry "use client"), so every consumer must transpile it, and each app carried its own vite incantation with nothing announcing the requirement; a third app would meet an obscure failure first (fold row L8). What attacks it: the contract is now stated where a new app reads first, packages/ui/README.md (Install) section 4, with the two Vite blocks copied from speedway. What does not exist: a build step, or any check that a consumer's config satisfies the contract. Stated is not enforced. PARTIAL.

F19. The proof surface out-costs the product it proves. Family: PROCESS. Status: MISSING. The mode: the playground and its docs, the surface with no consumer, grow faster than the kit and rot fastest. Measured by the panel's code seat over the 14 days to 2026-08-17: 23,884 playground lines across 88 pages against 12,043 kit lines, and 849 file-touches against 393 (fold row L14). Nothing bounds it. No budget, ratio, or gate compares proof surface to product, and no rule says when a showcase page has earned its upkeep. Absence check, run 2026-08-18: rg -in "budget|ratio" docs/SCRIPTURE.md docs/plan/TRACKING.md returns this entry and one unrelated board row (a hidden usage table in walmart), no bound. MISSING.

Outside evidence, marked as such. These are the known ways shared design systems fail in the wild, from native knowledge rather than this repo's history: the adoption cliff (teams sample the system, hit one missing piece, and fork wholesale); version-skew fragmentation (consumers scatter across old majors until upgrades cost more than forking); the docs site diverging from the shipped package until trust collapses; the contribution bottleneck (one owning team becomes the queue every feature waits in); and churn fatigue (theming or API rewrites that spend consumer goodwill faster than they add value). F2, F7, F9, and F10 are this repo's local instances of the first three; the last two have no local instance yet, which §8 treats as an open unknown rather than an immunity.

7. Success criteria#

Every criterion names its measurement and when it can first be evaluated. A criterion without a current measurement says so.

C1. Zero uncovered kit exports. Measurement: the COVERAGE.md re-derivation per its own method section. Evaluable now; currently 93 of 94 with one documented exception (apps/playground/COVERAGE.md:11-30).

C2. Zero BROKEN or OUT-OF-RANGE citations. Measurement: node scripts/check-citations.mjs after every docs-touching pass; the ROT-SUSPECT tier gets reviewed at each pass rather than accumulating. Evaluable now; the hard tier currently holds on the checker's DEFAULT scan set (canon, app-patterns, kit docs, playground; scripts/check-citations.mjs:20). This doc itself needs the explicit docs argument (§0), and that wider scan carries pre-existing BROKEN citations in docs/evidence/ and docs/plan/ outside this criterion's scope. The operating rule for that wider scan is a ratchet, stated here so it is not only a board entry: 164 BROKEN on 2026-08-17 (node scripts/check-citations.mjs docs), the count may not rise, and the governing layers (docs/design-language/, packages/ui/docs/, docs/breakdowns/) hold zero to one.

C3. Every pattern page's printed source is pullable. Measurement: copy the printed source into a fresh route; it renders (doc 47's acceptance bar, docs/plan/47-showcase-execution.md:59-60). Evaluable now, manual; not yet scripted.

C4. A correction lands once and reaches both apps within one bump cycle. Measurement: after each app's next kit bump, grep both trees for the corrected pattern's old form; zero survivals. First evaluable at the next deliberate bump of either app. This is S8 made falsifiable, and it is the criterion the toolkit's history says to watch most.

C5. Zero raw-palette classes in consumers. PARTIAL. The forge's gate is real, wired, and holds: pnpm lint:tokens (root package.json:11, CI at .github/workflows/ci.yml:20) exits clean. But walmart-mvp and speedway are separate repositories the root gate cannot reach, and neither runs any token lint of its own. The criterion keeps its consumer scope BECAUSE the gap is real: until a consumer-side lint exists, this measures the forge and trusts the consumers.

C6. A fresh page ships kit-only. Measurement: the COVERAGE.md import-grep method applied to any new app page; zero app-local duplicates of kit primitives introduced. Evaluable per new page.

C7. Both themes verified, screenshots read, for every changed page. Measurement: a screenshot pair exists and was judged for each page a commit touches. Evaluable now as practice; P4's light-theme-only slip is the standing reason this is a criterion and not an assumption (docs/plan/49-scripture-evidence/attempts-gaps.md:64-70).

C8. Owner-observed acceptance closes each pass. Measurement: a pass is DONE when the owner has seen it and said so, recorded on the board; the queue may proceed meanwhile, but nothing gets called finished on agent-verification alone. Not wired today; this criterion is F3's countermeasure, defined here so #55 can check for it.

C9. A fresh adopter composes without steering. Measurement: a new app or a fresh-context agent builds its first screens from kit plus recipes alone, and the time and the fork-count get recorded. First run 2026-08-17, by a site-only reviewer holding nothing but the playground URL: it failed at the first step, because no page said how to install the kit (the fix is packages/ui/README.md (Install)). This is S12 and S13's real test; until an adopter passes it, adoption claims stay PARTIAL.

C10. Gallery provenance resolves live. PARTIAL. Measurement: every showcase provenance line points at a file:line that exists and still shows the claimed pattern. The doc half rides C2; the gallery half does not, since provenance lines live in .tsx pages and the checker reads only .md (scripts/check-citations.mjs:43). Until that changes, the gallery half is a manual per-pass habit, and "still shows the claimed pattern" is human judgment either way.

8. What we still do not know#

This section exists so the doc cannot quietly round uncertainty up to confidence. Standing unknowns, kept until evidence retires them:

• Whether this works as well as we think. The owner's own sentence, kept verbatim per S12: "we still don't know if this will work as good as we think it will." The only retiring evidence is C9 actually running.
• Whether the docs corpus survives contact with a stranger. Its content audited healthy, and the reachability bottleneck the audit named (docs/plan/45-docs-value-audit.md:74-79) was mostly closed by the G4 breadcrumbs (task #48, walmart 28c8ebc, speedway 46b1c63): four of the six named docs now have inbound paths, with app-patterns 05 and 06 still at zero. The deeper unknown stands untouched: no stranger has tried yet.
• Whether the forge scales past two apps. Every lesson here comes from walmart and speedway; a third app is the first data point that would test the composition speed claim (S13) rather than extend the sample.
• Whether kit velocity and doc currency can coexist. The fastest-moving week outran the doc pass exactly as predicted (docs/plan/45-docs-audit-evidence/kit-docs.md:12); the union rule bounds consumer damage but nothing yet proves the contracts can keep pace.
• Whether the diffusion revision fixes the felt gap. Doc 48's C3 reverses a structural choice on the owner's read of the result; the reversal is itself untested until the next showcase pass ships under it.
• Whether the two outside failure modes with no local instance yet (the contribution bottleneck, churn fatigue) are absent or merely early. One pen and one owner is the current shape; it has not been load-tested.