How a Versable app is built and documented, as opposed to how it looks
The reusable methods, and the recipes that say what a request for a screen actually brings along.
What is this?#
How a screen on the kit gets built and written up: how data loads, how a surface is documented, how E2E cases are derived from that doc, how an app is deployed, started or migrated, and the recipes that say what a request like "a list page" or "a record detail" actually brings along. Start with the doc that matches what you were asked for; the table says which. What a surface should look like is ../design-language; what a component takes is ../../packages/ui/docs.
| Doc | What it covers |
|---|---|
00-data-loading.md | the cached-read layer: org-scoped keys, conditional keys, write-driven revalidation, what stays uncached and why |
01-documenting-a-surface.md | the eight-heading surface-doc template and the policies around it |
02-deriving-e2e.md | turning a surface doc into a test suite by transcription |
03-deploying-on-gcp.md | the three deploy paths, the build-info endpoint that makes a deploy verifiable without credentials, and the four traps that cost real builds |
04-migrating-an-app.md | bringing an app that already works onto the kit, starting with the parity ledger that stops a rebuild purging behaviour nobody wrote down |
05-starting-a-new-app.md | the same evidence read forwards: what a greenfield app gets free, the three decisions to make before the first screen, and the build order |
06-writing-a-repo-readme.md | the one shape every Versable repo README follows, extracted from enhancement-product, and the reasoning behind its order |
10-recipe-browsable-list.md | what a request for a list, table, queue or index brings along: 27 bundle rows, the two cross-app divergences, and the do-nots |
11-recipe-record-detail.md | what a request for one record's detail brings along, starting with the peek-modal-page decision |
12-primitives-and-rules.md | which rules a kit primitive already retires, which one would if built, and which need a person; the kit roadmap derived from real incidents |
13-when-a-solution-is-unsuitable.md | the tells that a solution does not fit (a duplicate, an override, an invented seat, an unchecked assumption, one tested state, a partial read) and the discipline that replaces a one-shot build when the request and the screen disagree |
14-validating-a-ui-change.md | the pass a UI change goes through before it is called done (typecheck, both themes at two widths, the categorical measurements, the confusion audit, the code review, the contract checklist), the skills that run each step and when they fire |
15-claim-status-vocabulary.md | the three grades a claim about the system may carry (ATTACKED, PARTIAL, MISSING), what each demands, absence claims with their command, and the rule that a rule nothing reads is not a rule; one page both the scripture and the platform contract cite |
16-recipe-module-settings-form.md | what a request for a module's settings page, run configuration or wizard step brings along: SchemaForm over the module's schema, the twenty rows the schema already handles (widths, sections, choosers, rows, tiers, options, validation voice, presets, the aside, review and snapshot) and the one it does not, the host's honest action bar |
The numbering splits at 10: 00 through 09 are methods, 10 and up are
request-shaped recipes and the analysis that spans them. A recipe answers "I was
asked for X, what does that bring along"; a method answers "how do we do Y here".
Publishing a docs tree is the one method here that ships as files rather than
prose, so it lives with them, in ../../pipelines. Note that
its docs-pages template is superseded: docs now publish to the Versable tech
nexus, and that folder's README carries the current status.
Why these are not in the design language#
Every design-language/ doc covers a visual trait, and each trait doc (01
through 11, the overview aside) carries §A principles, §B presets, §C use cases.
A data-loading model or an authoring convention filed there would dilute a doc
set whose entries are all traits. Filing them under packages/ui/docs/ would be
worse: that directory is keyed by component, and these cross every component.
The relationship to a consuming app#
These docs own the METHOD. An app's own docs own its instance of it, and point here rather than restating.
walmart-mvp is the reference consumer for the three methods that have one: its
surface docs implement 01, its docs/testing/e2e-derivation.md implements 02
and adds that app's environment traps and suite layout, and its
docs/technical/01-data-loading.md implements 00 with the actual key
inventory. The rest have no reference instance yet, which is worth knowing before
you assume a method has been exercised.
The split rule: if a second app would need it, it belongs here. If it names a route, a table, or an endpoint, it belongs to the app.
Created 2026-08-09, approved by vb-fable as part of the kit canon tree
(docs/evidence/20260809-kit-canon-tree/PROPOSAL.md).