CLAUDE.md

Agent notes: how to work here, the doc map, the canon, releasing the kit, the freeze.

Three things live here: the kit (packages/ui, published as @versable-git/ui), the playground that shows every export, pattern, and doc (apps/playground, pm2 playground-dev on :5104), and the cross-app design canon (docs/). Beside them, smaller: two more published packages (packages/toolkit, framework-free utilities with no app consumer yet, and packages/qsync, the URL half of the table sync seam), the app templates (apps/_templates), and one tenant, contract/, the foundry contract for everything below the screen, served in the docs browser and due to move to versable-foundry in the org split (row #63).

Three apps consume the kit, and this paragraph is the one place their pins are stated (every other doc points here). The kit is at 0.6.0, published 2026-10-24 to GitHub Packages and the versable-forge-v6 Artifact Registry. Each app has a draft upgrade PR to 0.6.0 on its kit-upgrade-0.6.0 branch; until those merge, the pins below hold. Read on 2026-10-24: ../walmart-mvp/frontend/package.json pins an exact 0.2.2. ../speedway/package.json pins an exact 0.2.2 at HEAD (its working copy temporarily links ../versable-builder/packages/ui, uncommitted). ../versable-forge-v6 pins an exact 0.5.0 in its package.json; its scripts/kit-registry.sh takes the pin as an argument and defaults to 0.2.0, so run it with the version you mean. Walmart and speedway take a deliberate upgrade before any change after 0.2.x reaches them. CONTRIBUTING.md is the how-to (setup, run, add a component, a pattern, a doc); README.md is the repo's front door for humans; packages/ui/USAGE.md is the door for a person or agent putting the kit into an app; docs/SCRIPTURE.md says why the kit is shaped the way it is.

How to work here (2026-08-16)#

The bar for done. A UI change is done when it has been exercised in the running playground on :5104 in BOTH themes (dark is the literal theme name versable-dark; the toggle writes pg-theme to localStorage and the root layout applies it before paint), not when it typechecks. Before that, the CI list passes locally: the seven commands .github/workflows/ci.yml runs, quoted verbatim in CONTRIBUTING.md section 3, "The bar for done", and nowhere else, so the list cannot drift between doors. A change that meets this bar cannot redden main.
One registry. apps/playground/src/app/showcase-registry.ts is the route registry: sidebar groups, index cards, breadcrumbs, the header's See also and contract-doc link, the awareness prompt, and search all derive from it. A new page is a registry entry first. apps/playground/src/lib/docs-registry.ts is the same thing for the docs browser (its ROOTS list is an exact allowlist of doc trees and singleton files).
One frame, one header. Every UI page sits in PageFrame (apps/playground/src/app/page-frame.tsx, the /patterns width) and opens with ShowcaseTitle (or DocTitle for docs, PatternShell for patterns). Header actions are icon-only with a rich two-line tooltip: the label the icon replaced as the tip's title, one line of help as its body (packages/ui/docs/tooltip.md, "The rich preset").
Prose rules, enforced by hooks. Zero em dashes anywhere (rendered UI, docs, commit messages); mono only for identifiers; a component doc keeps the contract shape in packages/ui/docs/ (contract, sanctioned and banned combinations, a "Before you adopt this" checklist, travels with, snippet; Banned sections feed the generated docs/DO-NOTS.md, so regenerate it with node scripts/build-do-nots.mjs after editing one). Frontmatter keys are shared with mkdocs, so the playground's icon key is kit_icon: (mkdocs claims icon:).
Kit changes ride the owner's next bump. Never bump packages/ui/package.json as a ride-along; the workflow publishes on push to main. Note unpublished kit surface in the apps' CLAUDE.md files, never auto-upgrade them.
Canon edits stay one pen. docs/design-language/, docs/app-patterns/, and docs/SCRIPTURE.md are edited by one agent at a time and every change re-runs node scripts/check-citations.mjs docs.
Owner review rounds. The owner's feedback is recorded verbatim with stable IDs (docs/plan/48-, 53-, 55-showcase-feedback-*.md) and planned in the sibling execution doc (56-review-round-1-plan.md: buckets by how much owner time an item needs, waves, one decision page per sitting). Tasks cite the IDs. docs/plan/TRACKING.md is the board and is never a mirror of a session's task list. Incoming defects, proposals and questions from the consuming apps land in docs/plan/INBOX.md (one entry each, the shape is in the file) and wait for a review run; nothing is built from the inbox directly (owner, 2026-09-03).
Sub-agent seats get a territory (exact files), no commit, no kit edits unless named, no browser (the parent verifies live), no nesting, an absolute report path, and stop when done. Every git add is path-scoped; never stage user_docs/speedway-todo.md or speedway/docs/user-notes.md.

The canon (2026-08-09)#

This repo owns the cross-app design canon, and walmart-mvp is its second consumer. Extend in place rather than opening a third home for conventions.

docs/design-language/: 13 docs, the cross-app visual canon. Section A is principles, B is presets, C is worked use cases cited to file:line.
docs/app-patterns/: how an app is built and documented rather than how it looks. Data loading, the surface-doc template, the E2E derivation method.
packages/ui/docs/: per-component API reference. Contract, not law.
A canon doc's section C renames from "through Speedway" to "through the apps" in the same commit that adds its first non-speedway case. Owner-ruled lazy migration, no sweep.

Overlay canon section A1 is the default decision tree for peek versus modal versus page. A surface may deviate only when the deviation buys better and more consistent UX, with the reasoning stated in that surface's own doc.

Releasing the kit#

Never bump as a ride-along, never publish from a laptop; [skip kit] holds a push. The owning copy of the procedure (bump, scripts/ship-kit.sh, pins, the upgrade checklist) is the Releasing section of packages/ui/README.md.

Speedway is frozen for product work#

Owner ruling 2026-08-09. UI, component and code-pattern work is fine; anything that changes product behaviour needs a fresh ask. See speedway/CLAUDE.md.