Start here
The front door: what this is, how to install and upgrade the kit, and the map of everything written.
README
The repo's front door. What each layer is, who reads what, the map by what you came to do, and how work happens here.
Use the kit
For a person or agent about to build with the kit: a table from what you came for to the one page that answers it, the six steps to adopt, and the rule against refactoring the app around the kit.
Install and upgrade the kit
How an app gets the kit and keeps it current: prerequisites, registry and token, install and pin, the theme import, the bundler contract for Next and Vite, the upgrade checklist.
Docs map
The map of the written system: what the docs can do, where truth lives for a component, the showcase surfaces, what is on disk where.
Working here
How to work on this repo: the contributor's how-to, the agent's ground rules and doc map, and the toolkit.
Contributing
How to work on this repo itself: set it up, and add a component, a pattern, or a doc as the network of edits each really takes.
CLAUDE.md
Agent notes. Which doc is authoritative, what the canon owns, how the kit is released, and what is frozen.
AGENTS.md
The ground rules an agent must not break here: node, the dev server, semantic tokens, verify by running.
Toolkit
The toolkit's own README: nineteen modules, the runtime-suffix convention, what was fixed on port, and the pending publish decision.
Canon
Why the kit exists and how it can fail, how an app comes onto it, and everything that is banned.
Scripture
Why this project exists, what it must achieve, and an honest list of the ways it fails.
Guidebook
How to bring an app onto the kit, new or already built, and what went into speedway and walmart: the timeline, the lapses, what would have caught each sooner.
Do-nots
Every banned combination and canon do-not in the kit and the design language, in one place.
Reference
Looked up, not read through: what each release changed, the scripts the repo runs by hand, and the toolkit's backlog.
Why these stand apart
These three are reference, not reading. Nobody starts here and nobody reads them end to end: a release note is consulted when a pin moves, a script's entry when it is about to be run, the proposals file when a helper is about to be filed. Keeping them out of the reading groups keeps those groups short enough to read.
Kit changelog
Per release: added, changed on existing screens, and the Retires line naming the local copies it makes redundant.
Kit inventory
The derived inventory: what the kit provides, by surface, plus the rules for where a new thing goes. Regenerated by scripts/kit-inventory.mjs.
Kit standard
Reskin, layout, visual mess and hierarchy as checks: the measured half runs as the kit-standard bin, the reading half is sixteen yes-or-no questions, and a table names the kit defects that excuse a check.
Kit patterns index
The short pointer from the kit package to its patterns: the inventory holds the catalogue, this page holds the admission rule.
Scripts
The do-nots regen, the citation checkers, the inventory and method syncs, the prop-reach ledger, the dev-server guard, the triad push, and the retired hand publish, each from its own header.
Kit coverage ledger
The showcase pass instrument: exports vs gallery vs nav vs consumers, with the re-derivation method. Frozen at 0.0.25.
Toolkit proposals
Where an app agent files a generalizable helper in six lines. Open, snoozed, landed, discarded; nothing is deleted.
App templates
The starting points for a new app: one runnable skeleton per shape, each with its copy-out checklist, bundler contract, and build canary.
Which layer answers your question
The most common way to waste time here is reading the wrong layer.- Component propsWhat props does a component take
- Look and whyWhat should this look like, and why
- A list pageI was asked for a list page, what does that involve
- A record detailI was asked for a record detail
- Rules handled for youWhich rules does a component already handle for me
- MigratingHow do I bring an existing app onto this
- A new appHow do I start a new app
- A repo READMEHow should a repo README look
Working in walmart-mvp, speedway or the forge console?
The kit gets the superset of what the apps need; an app stays on its pinned version until its own deliberate kit upgrade.Check your pin first. A rule written for a kit version is unreachable below it: walmart pins , speedway pins , and the console pins an exact . A caret on a 0.0.x version is a patch pin, so walmart resolves to exactly 0.0.24. The owning copy of the numbers is the first paragraph of the repo's CLAUDE.md.
Bringing an app onto the kit?
New or already built: install first, copy a template or migrate, then read the recipe for the screen you were asked for.The install page is the first hour (prerequisites, registry and token, theme import, the bundler contract). A new app starts from a template; an existing one migrates screen by screen. The guidebook is what went wrong the first two times.
Start here
The front door: what this is, how to install and upgrade the kit, and the map of everything written- The shared UI system every Versable app is built from.
- The user's door: what you came for, one hop to it, the six steps to adopt the kit, and the scope rule that keeps an agent on task.
- The kit's front door: prerequisites, the registry line and token, install and pin, the theme import, the bundler contract, the upgrade checklist, where the design comes from.
- The four layers and what each can do for you, where truth lives for a component, the showcase surfaces, and where everything sits on disk.
Working here
How to work on this repo: the contributor's how-to, the agent's ground rules and doc map, and the toolkit- How to set up, run, use, and extend this repo (formerly USAGE.md): a component, a pattern, a doc, as the network of edits each is.
- Agent notes: how to work here, the doc map, the canon, releasing the kit, the freeze.
- Routing guide for any agent working in this repo.
- The framework-free utility package: what is in it, what each module belongs with, and who uses it.
Canon
Why the kit exists and how it can fail, how an app comes onto it, and everything that is banned- The intent layer: why this project exists, what it must achieve, how it works.
- Bringing an app onto the kit, new or already built: the layers, the order of work, the pin rules, how a correction flows back, and the retrospective on speedway and walmart.
- Every banned combination and canon do-not in one place, regenerated from source.
Design language
The cross-app visual canon: principles, presets, and worked cases cited to source- The thirteen traits, the layer-relation table, and the pin caveat.
- The UI decisions, patterns, and behaviors proven in Speedway, codified.
- Color, typography, spacing, radius, shadow, and responsiveness.
- The one clickable-action control and its color, weight, icon, and wording rules.
- Badges, chips, pills, dots, banners, alerts, and the vocabulary rules behind them.
- Skeletons, spinners, pending feedback, empty states, and in-page errors.
- Cards, framed sections, stat tiles, and surface spacing.
- The kit's richest component and the usage grammar around it.
- List toolbars, facet dropdowns, search, and filter-state conventions.
- Sidebar, topbar, breadcrumbs, page title, activity rail, and the shell contract.
- Page widths, padding, section rhythm, responsiveness, and the two page archetypes.
- Peek panels, modals, dropdowns, and toasts, and the decision tree between them.
- Animation conventions, entrance patterns, and working cues.
- The ramp, the roles, the title sets, the ink ladder, mono, tracking, truncation, and the do-nots.
- One field anatomy, the widths that give a form its rhythm, sections as cards, the mode chooser,…
- The words a component prop uses to describe how a thing looks or what state it is in.
- The rules that make a control reachable, nameable, and announced, across every component rather…
- The words in an app are part of the interface, and the kit is opinionated about them.
App patterns
How an app is built and documented: data loading, surface docs, E2E derivation- Methods versus recipes, and what each doc covers.
- How a Versable app gets data onto a screen.
- The authoring convention for a Versable app's surface docs.
- The method.
- A manual path for development, an automatic path for shipping, on GCP.
- Bringing an app that already works onto the kit without breaking what it does today.
- The mirror of 04-migrating-an-app.md.
- One README structure for every Versable repo.
- What a published version tells the person moving a pin.
- You were asked for a list, a table, a queue, an index, a "page showing all the X".
- Showing one record's detail: a preview, a drill-in, everything about the row.
- Every rule in this system was written because a human caught something on a screen.
- How to tell a solution does not fit, and how request-versus-reality drift means rethink, not one-shot.
- The pass a UI change goes through before it is called done, the skills that run it, and when each one fires.
- The three grades a claim about the system may carry, what each one demands, and the rule that a rule nobody reads is not a rule. Cited by the scripture and by the platform contract.
- You were asked for a settings page, a module's parameters, a wizard step that configures a run, a…
- Phones are out of scope for kit work (owner, sitting 1, D10, 2026-10-23).
- When something in an app looks or behaves wrong, name it before fixing it: what kind of defect it…
Layer breakdowns
Six shipping pages taken apart layer by layer, shell to canon rule, with the lapses each one shows- The breakdown template and the six pages it was applied to.
- The jobs list, layer by layer, a bespoke shell wrapping a work surface built almost entirely from one shared table component.
- The manual review queue, the same shell as the jobs list, but under a filtered work surface with selection and editing pulled outside the table model.
- The kit's AppShell in the first app to adopt it, a jobs table whose expanded row is a workflow stepper, and a toolbar the app built before the kit shipped one.
- The import flow, where a Dropzone plays the part of the page's own card and a duplicate-resolution modal carries most of the page's real logic.
- The AppShell gallery, seven real shell shapes behind one tab strip, and a toolbar link that now takes the shape its own contract doc names.
- The Button gallery, seventeen example cards deep, deliberately including the props no shipping screen has exercised yet.
Kit contract docs
One contract per component: props, sanctioned and banned combinations, snippets- The inline callout for a note, warning, or error that belongs in the page flow.
- Whole-app chrome: nav sidebar, topbar slots, and the padded page frame.
- Where the reader is, spelled out; the trail above a page and the topbar crumb.
- The kit's one clickable-action control; quiet by default, with an icon, in plain, icon-only, link, split and menu shapes.
- The surface everything sits on: title and subtitle header, optional actions, and a shape-matched skeleton for the loading frame.
- The small toggleable tag that communicates selection, never state or naming; removable when a value can be taken away.
- Stored text and code as a titled block: language label, line numbers, and a copy affordance in the header.
- What the kit provides for the things owners ask for in their own words.
- One click copies, the icon flips to a checkmark, the tooltip flips to Copied!, and both revert on a timer.
- The positioning primitive every menu-shaped surface composes on; it floats caller JSX near a trigger and owns nothing else.
- The drag-or-browse file picker that owns only selection and drag-over visuals; the caller decides what happens to the files.
- The "nothing here yet" preset over PageInfo for tables, lists, and search.
- The name of a data field or source file as a small pill: a label, never a value.
- The interaction hooks the apps lean on, keyboard shortcuts, debounced input, hydration-safe storage, link interception, disabled reasons and running an action with toasts, plus the theme switch, and the one rule each carries.
- The icon registry between every component and react-icons; one key per concept, one dispatcher, never a call-site import.
- IdentityRow and its avatar: the person, workspace, or org strip.
- Text that edits in place: hover reveals a pencil, click swaps to an input with the same box metrics, Enter or blur commits, Escape reverts. Empty or unchanged drafts never call back.
- One field for text, numbers, or a single checkbox or toggle.
- The small uppercase label that opens a section or names a tile: default for the eyebrow and group title, bricked for a tile's own label.
- One row of a list-in-card: icon or avatar, title, subtitle, metadata, actions.
- A stored markdown document rendered with the kit's parts: anchored headings, chip inline code, CodeBlock fences, Table tables, sanitized HTML.
- The dialog shell for a detail that is the task; opens by id from anywhere, closes on Escape, backdrop or its own button, with ConfirmModal as the yes/no gate.
- A small set of weighty choices shown as cards, each with a title and a sentence, where exactly one is picked.
- The centered icon, title, subtitle, and actions block when the page IS the message.
- The shape of the page that is coming, drawn while it loads, so nothing jumps when it lands.
- The page-level loading and error states on the same primitive as EmptyState, and the ListState switch that picks one of five states for a list surface.
- The page header row: identity, title and subtitle, inline zone, actions.
- A form generated from a module's JSON Schema, in the kit's one field anatomy; refuses anything outside its vocabulary by name.
- The picker: a control button that opens a keyboard-navigable option list.
- The persistent right-hand column for secondary content beside the page.
- Busy-state primitives: the loading scale, progress bars, and staggered skeleton groups for placeholder frames.
- The dashboard number tile: icon, label, one big figure, optional trend.
- The house vocabulary for how a record is doing, in two sizes, plus CodePill for a module's own codes; state only, never selection, naming or identity.
- A pipeline's stages in one strip: status circles, completion connectors, an optional click per stage with a polite blocked refusal.
- A lean presentational Table plus six independent feature hooks.
- The tab strip that switches one record's or one page's content panels; triggers carry a status dot, a count and a detail line, and it is never a filter.
- A quiet label for a fact about a record that is not its state, a selection or its name: a client, an environment, a file type.
- A relative time that reveals the exact clock on hover, or the reverse with absolute; carries its own tooltip, never wrap it in another. Includes the Refresh control that carries it.
- The app's transient notification stack, reached only through pushAlert.
- A hover and focus label for an icon's meaning or a truncated value's full text.
Reference
Looked up, not read through: what each release changed, the scripts the repo runs by hand, and the toolkit's backlog- What each release adds, what changes on screens an app already has, and what an app can delete once it takes it.
- Every component and pattern page the kit provides, derived from the registry, with the admission rules that place a new one. Generated; do not edit.
- The checks a consumer's screens are graded on, each runnable by the app's own agent with a pass or fail and no author in the loop.
- Where the pattern catalogue lives now and how a pattern earns a page.
- The scripts this repo runs by hand, what each is for, when to run it, and what it must never do.
- Every kit value export, where the gallery shows it, and how many files import it in each app. Frozen at 0.0.25; re-derive before quoting.
- The backlog of helpers that might belong in the toolkit: six lines to file, processed as a group.
- One runnable skeleton per app shape and which to pick: react-router-ssr, vite-spa, next.
- The repo's generated-output pipelines and what each produces.
Foundry contract
A snapshot of the foundry's docs as of 2026-09-03, frozen and stale; the contract itself is docs/ in github.com/versable-git/versable-foundry on main- The tree's own map: what each layer holds and where a question goes.
- Why the contract exists and what it must achieve.
- The kinds of thing a system can be, and what each owes the others.
- The banned moves, in one place.
- Where a new rule, doc, or decision goes in this tree.
- What changed in the contract and when.
Contract canon
How the system works, subsystem by subsystem: runner, identity, jobs, dispatch, storage, caching, observability, credits, deployment- The sixteen subsystem docs and how they relate.
- > Evidence: 14 file:line witnesses as of 2026-08-18.
- > Evidence: 16 file:line witnesses as of 2026-08-18.
- > Evidence: 10 file:line witnesses as of 2026-08-18.
- > Evidence: 9 file:line witnesses as of 2026-08-18.
- > Evidence: 22 file:line witnesses as of 2026-08-18.
- > Evidence: 3 file:line witnesses as of 2026-08-18.
- > Evidence: 2 file:line witnesses as of 2026-08-18.
- > Evidence: 5 file:line witnesses as of 2026-08-18.
- > Evidence: 2 file:line witnesses as of 2026-08-18.
- > Evidence: 3 file:line witnesses as of 2026-08-18.
- > Evidence: 0 file:line witnesses as of 2026-08-18.
- > Evidence: 1 file:line witnesses as of 2026-08-18.
- > Evidence: 3 file:line witnesses as of 2026-08-18.
- > Evidence: 0 file:line witnesses as of 2026-08-18.
- > Evidence: 1 file:line witnesses as of 2026-08-18.
- > Evidence: 0 file:line witnesses as of 2026-08-18.
Wire contracts
The exact shapes on the wire: module surface, runner verbs, manifest, caller keys, usage events, conformance- The binding shapes and what conformance means.
- The minimum a module must meet when it issues its own long-lived caller credentials instead of…
- The smoke suite a module runs against itself.
- The normative shape of GET /manifest and the shared vocabulary that requires and provides name…
- The HTTP surface every Foundry module exposes.
- The interface between a module's runner and its payload, in both directions.
- One unit of spend, as a module records it.
Contract guides
Judgment calls the contract leaves open: service granularity, outputs as a transform, data ownership, machine identity- The judgment calls and how to make them.
- Few big services with capabilities added inside, or many small modules?
- When a consumer wants a shape the worker does not naturally produce (M rows from N items, an…
- Which store holds which entity, which layer is the source of truth for it, who writes it, and where…
- Who mints the credential an app presents to a module, and how the estate supports more than one…
Contract patterns
How to build, consume, deploy and upgrade a module, end to end- The end-to-end walkthroughs.
- What a request for a new module brings along, in the order that keeps the build from debugging its…
- What a request for "call module X from our app" brings along: identity, the tenant, the job…
- How a module gets from a repo to something a caller can reach, on GCP first, with a Render variant…
- The first module is not greenfield: services-api runs today, does content generation for real…
- The owner asked for "an auth blueprint + recipe" because every app has a different auth model and…
- The doc the owner says keeps getting rewritten in every app: how an agentic capability (a model in…
Contract instances
Each real system read through the contract: what conforms, what diverges, what migrates- The systems and their conformance state.
- Covers the Python backend of App V5, on Render rather than GCP.
- Versable's agentic scraping web server, per the owner.
- > As of 2026-08-18 23:40 IST, runner step 1 in progress.
- Re-cut of ../evidence/20260817-speedway-recon.md against the canon matrix, plus a Lapses section.
- Covers services-api, runner-service, and runner-service-dev, which are three Cloud Run services in…
- Re-cut of ../evidence/20260817-walmart-recon.md against the canon matrix, plus a Lapses section.
Contract ADRs
The recorded decisions and why they hold- Every recorded decision, one line each.
- Status: accepted, 2026-08-17 (owner ruling, recorded in…
- Status: accepted, 2026-08-17 (owner ruling: "let's do b, can have a blueprint for a in the…
- Status: accepted, 2026-08-17 (owner ruling, ../evidence/20260817-source-docs-skeptical-read.md §B)
- Status: accepted, 2026-08-17 (owner ruling, ../evidence/20260817-source-docs-skeptical-read.md §C)
- Status: accepted, 2026-08-17 (owner answer 8)
- Status: accepted, 2026-08-18 (owner nod on two defaults proposed after the class-model review)