How a capability becomes a module any app can call, and what every production app needs around it: identity, jobs, workers, storage, caching, observability, credits, deployment.
-6366F1){kind=icon}
What is this?#
versable-builder answers "how does a Versable app look and behave on
screen", with a kit, a canon, contract docs per component, recipes, and
breakdowns of the real apps that prove or embarrass the rules. This tree is
the same idea pointed at everything below the screen. It exists because the
estate has now shipped the same capabilities three or four times, in three
stacks, with three answers to auth, three answers to job state, and three
answers to "what happens when the worker dies", and the next round of modules
(content generation, image generation, part-type matching, attribute
normalization, data extraction) should not be a fourth copy.
It is written for an agent or a person building a module (a capability exposed as a service, callable from any app or directly over an API) or an app that composes modules (the Workflow Console is the first). It leans prescriptive, and it is deliberately fed by reality: every rule cites the real service it came from, and the instances layer exists so that when a module has to break a rule for a good reason, the rule is what changes.
Naming: Versable Foundry is the internal name for this doc set and the
recipes and template code that grow out of it. Business-side, the current
work sprint is called V6; the customer-facing app that comes out of it is
the Workflow Console. See 00-charter.md for the terms.
The layers, and which one answers you#
Same shape as the kit's four layers, because the question "which doc do I read for this" is the one that decides whether a build has to debug its own seams.
| You need | Read | Why |
|---|---|---|
| What is a module, what is an app, where is the line, what do the words mean | 00-charter.md | Intent, restated once so nobody re-derives it |
| Which word do we use for this kind of thing (payload, runner, module, fitting, app, contract, reference data, canon; bespoke as a label), and how sure are we | 01-system-classes.md | A working vocabulary for the factory, with maturity per word, the estate read through it, and its known weaknesses; not a taxonomy |
| What should a service do about X, and why (auth, jobs, workers, storage, caching, observability, credits, config, review, deployment, degradation) | canon/ | The design language below the screen. Law, with the reasoning attached |
| What exact shape a module exposes, what a job or an outcome or a caller looks like on the wire, what is required and what is optional | contracts/ | The normative surface. Scoped to one primitive each, so a module can be checked against them one at a time |
| I was asked to build a module / consume one / deploy one / add auth to one, what does that bring along | patterns/ | Methods and recipes. A request is bigger than any single rule |
| How does the real thing do it today, and where does it lapse | instances/ | The reality check. Every canon rule cites at least one of these; when a rule and an instance disagree, that is a finding, not an error |
| Why was this decided, what were the alternatives | adr/ | Decisions that would otherwise be relitigated |
| A thing is decided and not built; how would we build it | plans/ | Build plans a hands-lane agent can pick up cold: goal, design, migration, verification, done-when |
| This decision has been taken more than one way in the estate; which way fits my case | guides/ | Ways of taking a decision, with what each bought and cost in a real system, and the tells; not rules |
| Where did a claim come from | evidence/ | Dated inputs: recon reports, diffs, live GCP state. Point-in-time, never edited after the fact |
| How does the Workflow Console use all of the above | v6/ | The first app built on the contract, mapped concern by concern |
What changed, and which contract_version | CHANGELOG.md | One line per bump; the review-pass decisions inside 0.1 |
| Is the tree telling the truth about itself | scripts/ | Two stdlib-only checks: build-manifest-schema.py generates contracts/manifest.schema.json from contracts/manifest.md's field tables (--check fails when stale) and check-examples.py validates the tree's examples against it and the surface. A failing check is a doc defect; run both after any contract edit |
| What has been ruled against | DO-NOTS.md | Gathered from every canon "never" and every contract "banned", so a builder who never opens the source doc still meets the rule |
Read them in that order when unsure. A canon doc says why, a contract doc says exactly what for one primitive, a pattern shows several rules travelling together, an instance shows the rule meeting reality.
How this tree grows#
Three feedback paths, and the direction of each matters:
canon + contracts ──────▶ new module built against them ▲ │ │ rule was wrong, │ module ships, gets used │ or missing ▼ instances/ ◀────────── breakdown of the shipped module- A new module is built against
canon/andcontracts/, usingpatterns/. - Once it ships, it gets an
instances/breakdown like the existing ones, with a Lapses section that is honest. - Lapses that recur, or that turn out to be the right call, flow back up as edits to canon and contracts, with the instance cited.
The docs are not a 1:1 downstream of any one service, including
versable-runner. The idea is written here; the services balance it.
Status#
contract_version 0.1, 2026-08-18. Canon 00 to 15, six contracts, five
patterns, four guides, six ADRs, three plans, the v6 mapping, and the
working vocabulary are written; five instances are broken down
(versable-runner, speedway, walmart-mvp, enhancement-product,
extraction), a sixth (foundry-runner, the first module on the contract)
is a skeleton being filled as it is built; the tree-wide adversarial review
(31 findings), the class model review (29), the manifest review (20) and the
tree-wide review v2 (44, three seats incl. a jester) are dispositioned and
folded (2026-08-18). The manifest's field tables are machine-read into
contracts/manifest.schema.json and the examples validate against it. Built
against it so far: foundry-runner serves a validating /manifest and a
manifest-generated /guide (runner step 1, local); the console
(versable-forge-v6) is being built in its own repo against the kit.
PLAN.md carries status, BACKLOG.md what is parked, CHANGELOG.md what
moved. The concerns
matrix in canon/00-overview.md is the current best map of what is
settled, what is contested, and what nobody has built yet.
Eventual home: this tree, the recipes, and the template code are meant to
join versable-builder, whose original charter was UI and everything else.
Until then it lives here.