create-substrat 0.0.1 → 0.1.1

package/template/.substrat/playbook.md

@@ -0,0 +1,386 @@
+# Playbook — build a vertical on Substrat
+
+The always-on rules live in [`AGENTS.md`](../AGENTS.md); read them first. This playbook is
+the **flow**: interview the user, tell them honestly how much of their app already exists, and
+**land a design document they can review and approve before a line of code is written** — then
+reshape the reference into it. Read the whole thing before starting — both the design gate
+(Step 4) and the checkpoints (Step 7) are hard stops.
+
+**The target is a reviewed design, not running code.** Steps 1–2 learn the domain and map it
+onto what already exists; Step 3 writes a checked-in `DESIGN.md` in the user's own vocabulary;
+Step 4 is a **hard stop** where the user reads and approves it. Only then does Step 5 reshape
+the reference into their domain. The design gate (Step 4) is *upstream* of the two code
+checkpoints (Step 7) — a user with zero Substrat knowledge gets to say "yes, that's the app I
+want" before implementation, not after.
+
+This project ships with a small **working reference vertical** — a bike-repair shop on
+`engine-workorder` + `engine-invoicing`, green out of the box (`npm test`). It is your worked
+example and your build starting point: once the design is approved you **reshape** it into the
+user's domain rather than building from an empty directory. Work in the project root.
+
+---
+
+## Step 1 — Interview
+
+Ask, don't assume. **Three to five questions, conversational, one message.** You are learning
+the *shape* of the domain — the answers become the design document (Step 3), so listen for
+vocabulary, the cast, and who must be denied what, not just features. **Adapt depth to the
+user**: someone who already knows their domain cold needs fewer, sharper questions; someone
+thinking out loud needs you to draw the shape out. One flow, not branching tracks — read the
+room and dial the teaching up or down.
+
+1. **What are you building, and who uses it?** (the firm, the cast)
+2. **What's the thing that moves through the system?** A job, a repair, an inspection, an
+   order, a case? What happens to it from start to finish?
+3. **Who must be denied what?** The most important question and the one nobody expects.
+   Does a customer log in? Should a technician see pricing? This drives the whole
+   permission model, and it is what Substrat is *for*.
+4. **Does money come out the other end?** Invoice, quote, receipt, nothing?
+5. **Anything that must be signed off or checked before a step can happen?**
+
+Don't ask about tech, hosting, or databases yet. If the user already described their app in
+detail, skip to Step 2 and confirm your reading of it instead of re-asking.
+
+---
+
+## Step 2 — The coverage map
+
+**This is the most valuable thing you do, and the easiest to get wrong by being
+flattering.** Work out what already exists and what the user is actually signing up to build.
+Be specific and honest. This analysis is the analytical core of the design document (Step 3) —
+sections 3 ("what already exists vs. what's yours") and 4 ("who is denied what") are this map,
+written down.
+
+**First, list the engines that actually exist. Do not trust any hard-coded list:**
+
+```sh
+npm search @substrat-run --json | grep -E '"name"|"description"'
+```
+
+Substrat publishes frequently, so any inventory in a doc goes stale between releases. A
+missing engine does not fail loudly — it silently becomes Tier 3, and you hand the user an
+estimate for work that already exists. Run the search, then read the `dist/index.d.ts` of
+anything relevant.
+
+Coverage has four tiers:
+
+### Tier 0 — the kernel. Always. Free.
+
+Every vertical gets this whether or not it uses a single engine:
+
+- **Tenancy** — tenants and scopes, isolated at the database level. A scope is one
+  SQLite/DO database. Cross-tenant access is not a bug you avoid; there is no API for it.
+- **Permissions** — roles, grants, entity-narrowed grants, and every decision carries a
+  proof path (why it was allowed).
+- **Events + audit** — every mutation emits a kernel-stamped event. Origin fields (tenant,
+  scope, actor, time) are stamped by the kernel; your code cannot mislabel one.
+- **Migrations** — journaled per module, applied lazily per scope.
+
+This is usually *most of what the user would otherwise build badly*. Say so plainly.
+
+### Tier 1 — engines you compose
+
+Imported directly; their in-scope functions run in **your** transaction. Read each one's
+`node_modules/@substrat-run/engine-*/dist/index.d.ts` for the real surface before composing
+— in-scope functions, `PERM` keys, and types. Typical examples (verify with the search):
+
+- **`engine-workorder`** — a job with a lifecycle that cannot skip states, plus time and
+  material reporting. Note there is **no `workorder/create` operation** — creation goes
+  through `createWorkOrder(ctx, …)`, an in-scope function, because the vertical must
+  price/label it first. The hole is deliberate: the engine owns the state machine, you own
+  vocabulary and pricing.
+- **`engine-protocol`** — checklists/inspections with templates, responses, and signatures.
+  Contributes a guard predicate so you can declare an operation blocked until signed.
+- **`engine-booking`** — reservations. Owns one invariant: concurrent allocations never
+  exceed capacity over any overlapping interval. Knows nothing about pricing, opening
+  hours, recurrence, or timezones — all vertical policy.
+- **`engine-invites`** — how a person joins an org they are not in. Identifiers stored
+  hashed and never returned; an invitation confers nothing until accepted. Reach for it
+  before hand-rolling any invite flow.
+
+### Tier 2 — engines you feed by event
+
+**No import.** You emit; they consume. This is the star topology.
+
+- **`engine-invoicing`** — invoice basis and lines, immutable after export. Consumes
+  `workorder.completed` and `commerce.order-placed`, so a vertical that imports zero engines
+  still gets invoicing by emitting an event. Its consumer find-or-creates the customer's
+  *open* basis and appends. It has **no tax/VAT concept** — say so before an EU user
+  discovers it.
+
+### Tier 2b — connectors, for anything off-box
+
+Module code may not touch the network (rule 2), so a third party is reached by a
+**connector**: `host.registerConnector(id, eventType, handler, options)`, with retry
+policy, timeout, dead letters, and per-connection state. The handler runs *outside* the
+scope transaction. Delivery is at-least-once — key a dispatch ledger in connector state and
+return early on redelivery. Granting door access twice is harmless; charging a card twice
+is not.
+
+### Tier 3 — yours
+
+Vocabulary, price list, screens, roles, and any domain the engines don't own. If the user's
+core noun isn't a job/inspection, this is most of the app — **a normal, supported outcome,
+not a failure.**
+
+### Deliver it like this
+
+> Your bike shop: a repair is a **work order** — the engine owns its lifecycle, so it can't
+> jump from booked to closed. Time and parts reporting: engine. The invoice at the end:
+> invoicing, by event — you emit, it listens. **Yours:** bikes, customers, your price list,
+> the pricing rule when a repair takes 20 minutes but you bill a minimum hour, and the
+> screens. Tenancy, permissions, and the audit trail come from the kernel — including the
+> part where a customer logs in and sees *only their own* bikes.
+
+### The honest no
+
+Substrat is the wrong tool for plenty. Say so — it's what makes the yes trustworthy. Bad
+fits: single-tenant apps, content/marketing sites, pure CRUD with no permission story,
+real-time collaborative editing, analytics workloads, anything where the hard part isn't
+*who may do what to which record*. If it's a bad fit, say why, name a better tool, and
+stop. Do not scaffold.
+
+---
+
+## Step 3 — Write the design document
+
+**This is the deliverable.** Everything before now was learning; this is where it lands
+somewhere the user can hold. Write a **checked-in `DESIGN.md`** in the project root, in the
+user's own vocabulary — no Substrat internals, no decision refs, no cross-references to
+platform docs. Someone who has never heard of Substrat must be able to read it and recognise
+their own business.
+
+**Top line, verbatim** — the house marker for a pre-code design:
+
+```
+Status: draft v0.1 · Last updated: <date> · For review before any code
+```
+
+**The template** — the coverage map (Step 2) is sections 3–4, already done; the rest is the
+interview written down. Two sections deliberately *preview* the code checkpoints of Step 7 in
+plain language, so nothing there is a surprise:
+
+1. **What we're building & who uses it** — the firm and the cast, one paragraph.
+2. **The thing that moves through the system** — the core noun and its lifecycle
+   (the states it passes through, and which transitions must not be skippable).
+3. **What already exists vs. what's yours** — the coverage map as tiers: the kernel
+   (free), the engines you compose, the connectors, and the Tier-3 vocabulary/pricing/
+   screens that are yours. If it's a **bad fit, this is where the honest no lands** — say
+   so and stop; do not write the rest.
+4. **Who is denied what** — the load-bearing section, and a plain-language *preview of the
+   permission diff*: each role and what it can and cannot see. Make two answers impossible
+   to miss — **who can see the money, and who can see other customers' data.**
+5. **Money & sign-off** — invoice / quote / receipt / none; anything gated on a signature
+   or a check before a step can happen.
+6. **The cast, roles, and tenancy** — the named roles per persona (roles are the user's
+   vocabulary — name them for the persona: `workshop-admin`, not `role_1`). **Two tenants,
+   always** — the second exists to be attacked, which is how isolation gets proven rather
+   than claimed.
+7. **The data we'll store** — the vertical's own tables and fields in plain terms. This
+   *previews the migration diff*; migrations are **append-only forever after first ship**,
+   so this is the cheap moment to get the shape right.
+8. **The scenario the test will replay** — the happy path plus the denials that prove
+   isolation (wrong role denied, customer A sees theirs and customer B sees nothing, a
+   cross-tenant attacker gets nothing).
+9. **Open decisions** — each with a **recommended default**, so the user chooses rather
+   than specifies:
+   - **Auth.** Local dev uses an `x-principal` header — a dev seam, not a login. Default to
+     it and note it must be replaced before anything real; offer to wire a real login (the
+     bike-shop reference shows the Better Auth pattern) now if they want it. Real auth gates
+     *exposing* the app, not *building* it.
+   - **Deploy or stay local.** Local-first is a legitimate endpoint; default to it.
+10. **Out of scope / deferred** — what you are deliberately not building, so the review is
+    about a bounded thing.
+
+End with a short **"Review questions for the human"** block (2–3 questions) — the things the
+user must actively confirm, not rubber-stamp.
+
+---
+
+## Step 4 — The design gate. STOP HERE.
+
+**Present the design document and wait for approval. Do not reshape the reference, do not
+write code.**
+
+This is a *human* gate, and it is the whole point: it happens **before** any code, upstream of
+the two implementation checkpoints in Step 7. Walk the user through section 4 ("who is denied
+what") in **their own vocabulary** until they can answer, without your help: *who can see the
+money, and who can see other customers' data?*
+
+**A gate assumes a competent reviewer.** If the user cannot evaluate the permission preview,
+say so rather than letting them wave it through — a design nobody understands is theater, and
+reproduces exactly the failure Substrat exists to prevent. Iterate the document until they
+can, and only then take explicit approval.
+
+Approval of the design is what unlocks Step 5. Until you have it, you are still in design.
+
+---
+
+## Step 5 — Reshape the reference
+
+The design is approved. The scaffold already contains a working vertical in `src/` + `test/` —
+the bike-repair shop. **Read it first** (it's your Callout: the real, green implementation of
+every pattern this step describes), then reshape it into the user's domain from the approved
+`DESIGN.md`:
+
+- **Rename the vocabulary** — `shop_customers`/`shop_bikes` → the user's nouns, the `shop/*`
+  operation names, the roles, the price-list shape. If the user's core noun maps onto a work
+  order (a repair, a job, an inspection, a case), most of the structure carries over
+  unchanged and you are editing labels and the pricing rule.
+- **Keep the load-bearing patterns** — the permission check as every operation's first line,
+  the pricing moment, the portal proof-walk, the two-tenant seed, the pinned-message
+  denials. These are what make it a Substrat vertical rather than a CRUD app; the reference
+  demonstrates each one working.
+- **Drop what the domain doesn't need, add its own tables** for anything the engines don't
+  own. If the user's core noun *isn't* work-order-shaped, you may replace more of `src/` —
+  but the seed/server/test scaffolding and the layout still hold.
+- **Re-run the gates as you go** (Step 6) — the reference is green, so any red is something
+  you just changed.
+
+The dependencies are already wired in `package.json` (the `@substrat-run/*` packages, `hono`,
+`better-sqlite3`; engines added as needed). If you compose a **different** engine, add it and
+read its surface — the engines are self-describing:
+`node_modules/@substrat-run/engine-*/dist/index.d.ts` is the reference; never guess at it.
+
+**Do NOT add `zod` as a dependency, and never `import { z } from 'zod'`** (rule 10). Import
+everything from contracts:
+
+```ts
+import { z, entityRef, money, moduleManifest } from '@substrat-run/contracts';
+```
+
+**After install, the engines are self-describing — read them.** Do not guess at their
+surface: `node_modules/@substrat-run/engine-*/dist/index.d.ts` is the reference.
+
+### `src/manifest.ts`, `src/migrations.ts`, `src/module.ts`
+
+Three separate files. `manifest.ts` holds the `PERM` consts + `moduleManifest.parse`,
+`migrations.ts` exports the `SqlMigration[]`, `module.ts` imports both and holds only the
+operations + the `ModuleRegistration`. Keep the split — the linter and tests expect it.
+
+- `moduleManifest.parse({ … })` — id, version, `kernelContract: '^0.0.1'`, `permissions`
+  (key + human description; these feed the permission diff), `events` emits/consumes,
+  `attachmentTargets`, `entityRelations`, `entitlementKey`.
+- **`entityRelations` must declare every edge you traverse** — your own (`bike → customer`)
+  and the ones the engine makes on your behalf (`workorder → bike`). The adapter rejects a
+  `ctx.link` for an undeclared edge. This is also what makes the portal proof-walk reach
+  the customer.
+- Migrations: `SqlMigration[]`, tables prefixed `<vertical>_`, TEXT ids, ISO-8601 TEXT
+  timestamps, money/decimals as TEXT. **Append-only forever after first ship.**
+- Operations: first line is always `assertAllowed(await ctx.check(PERM))`. Parse inputs
+  with Zod. `ctx.link(child, parent)` when creating related entities.
+- **The pricing moment is the pattern to copy**: read the engine's reported lines with
+  `getReportedLines(ctx, orderId)` → apply the vertical's price list → call the engine's
+  `completeWorkOrder`. One transaction, invariants intact.
+- Portal listing: iterate and `ctx.check(perm, entityRef)` **per entity** — a proof walk,
+  not UI filtering.
+
+### `src/seed.ts`
+
+`new SqliteScopeHost({ dir })`, then `registerModule` per engine + the vertical. The control
+plane comes first and is audited:
+
+```ts
+host.admin.createTenant(actor, { id: tenant, slug: 'acme', name: 'Acme' });
+host.admin.grantEntitlement(actor, tenant, '<entitlementKey>');   // per module
+await host.provisionScope(actor, { tenantId: tenant, scopeId: scope, jurisdiction: 'eu' });
+```
+
+Define roles **per tenant** from the engines' `PERM` + your keys, assign them, create seed
+entities via `stub.invoke` (**never raw SQL**), give portal principals entity-narrowed
+grants. Make it idempotent.
+
+### `test/scenario.test.ts`
+
+Replay the domain scenario headlessly against a temp dir. **The denial assertions are the
+whole point:**
+
+```ts
+await expect(host.getScope(mallory, t2, s1)).rejects.toThrow(/unknown scope/);   // wrong pair
+const m = await host.getScope(mallory, t1, s1);                                  // right pair, no tuples
+await expect(m.invoke('workorder/list')).rejects.toThrow(/permission denied/);
+```
+
+Cover: happy path → wrong-role denied → portal isolation (customer A sees theirs, B sees
+nothing) → cross-tenant attacker denied → pricing exact to the öre → the state machine
+refusing to skip. Never write a bare `.rejects.toThrow()` — pin the message, and pair every
+closed-door assertion with a control proving a neighbouring door is still open.
+
+---
+
+## Step 6 — Run it
+
+Build confidence in this order, and **show the user the output of each**:
+
+```sh
+pnpm install
+pnpm test                        # the scenario, including the denials
+npx @substrat-run/boundary-lint  # the layer rules
+pnpm dev                         # API on :8871 (PORT=… WEB_PORT=… to move it)
+```
+
+Then **actually exercise it** — don't just report that the server started. A green scenario
+test never touches `server.ts`, its routes, or the principal picker, so it can be green
+while the app is broken. Drive the real flow with curl (create → assign → start → report →
+complete) as two personas, switching `x-principal` to show a denial landing as a denial.
+The moment the attack fails is the demo; make sure the user sees it.
+
+If they want a UI, scaffold a minimal Vite + React app under `app/` with a principal picker
+and typed wrappers over the routes. Ask first — it roughly doubles the work.
+
+---
+
+## Step 7 — The two checkpoints. STOP HERE.
+
+**You may never self-approve these. Present them and wait.** The design gate (Step 4) already
+took the user's approval of *what* to build; these confirm that the code matches it.
+
+1. **Migration diff** — every new `SqlMigration`, verbatim. Append-only forever once
+   shipped, so this is the last cheap moment to change your mind.
+2. **Permission diff** — a table: key → description → which roles hold it → why.
+
+| Key | Description | Roles |
+|---|---|---|
+| `repair:create` | Book a repair for a customer's bike | workshop-admin |
+| `workorder:report` | Report time and materials | workshop-admin, mechanic |
+| `bike:read-own` | See your own bikes (entity-narrowed) | portal-customer |
+
+**A checkpoint assumes a competent reviewer.** If the user cannot evaluate the table, walk
+them through it in their own vocabulary until they can answer: *who can now see the money,
+and who can see other tenants' data?* A permission diff nobody understands is theater.
+
+---
+
+## Step 8 — Deploy (optional)
+
+Only if the user asks. Local-first is a legitimate stopping point.
+
+Substrat runs on Cloudflare via `@substrat-run/adapter-cloudflare` (Durable Objects). A
+vertical declares what it needs at runtime with a `substrat.runtimeNeeds` block in
+`package.json` (stores, node-compat, build). The deploy path is the authenticated CLI, and
+the author never holds a Cloudflare token:
+
+- `substrat login` / `substrat whoami` — authenticate against the control plane.
+- `substrat push` — push the vertical; the version auto-bumps. A **private** (tenant-owned)
+  vertical is admitted automatically; a **listed/shared** one waits for staff admission.
+- `substrat promote <slug> --channel dev|staging|prod --version … [--ack-permissions]
+  [--ack-migrations]` — the owner promotes every channel, prod included, for their own
+  private vertical.
+- `substrat hostnames bind <slug> --surface <s> [--domain <d>]` — mint a live hostname, or
+  record a custom domain pending DNS validation (`substrat hostnames verify`).
+
+Updates deploy **in place** from one stable script — data carries forward, migrations run
+against prod data, backout is a time-boxed PITR rewind.
+
+Before deploying: the `x-principal` dev header **must** be gone. Shipping it is a
+cross-tenant hole with a UI.
+
+---
+
+## Step 9 — Leave the project competent
+
+The next session — in any tool — starts cold. The scaffold already ships `AGENTS.md`,
+`CLAUDE.md`, and the Cursor/opencode command stubs, so the rules and this flow survive. Your
+job here is to make them *specific to this app*: append the vertical's own vocabulary, cast,
+and roles to `AGENTS.md` (it's the file every tool reads), so the next session knows the
+domain and not just the framework. Do this before the user comes back.

package/template/AGENTS.md

@@ -0,0 +1,117 @@
+# Building on Substrat — agent instructions
+
+This project is a **Substrat vertical**: a multi-tenant business app built on the
+Substrat kernel and its engines. This file is the always-on constitution — the rules
+that hold no matter what you touch. It is read by every AI tool (Claude Code, Cursor,
+opencode); do not duplicate it into tool-specific config.
+
+The full build flow — interview, coverage map, a reviewed design document you approve
+before any code, then reshape, run, and the checkpoints — is a **playbook**, not always-on
+context. Invoke it when you start or extend a vertical:
+
+- **Claude Code**: `/substrat`
+- **Cursor / opencode**: the `new-vertical` command, or read [`.substrat/playbook.md`](.substrat/playbook.md)
+
+Read the playbook before scaffolding. This file is what a session already mid-build
+must never violate.
+
+## The mental model
+
+Three layers. You only own the third.
+
+1. **Kernel — free, always.** Tenancy (one scope = one isolated database; there is no
+   cross-tenant API), permissions (roles, grants, and a proof path for every decision),
+   events + audit (every mutation emits a kernel-stamped event you cannot mislabel),
+   migrations (journaled per module, applied lazily per scope).
+2. **Engines — compose or feed.** Headless, own invariants that cannot be violated
+   (state machines that can't skip states, append-only entries). You either **compose**
+   an engine (import it; its in-scope functions run in *your* transaction) or **feed** it
+   (emit a fat event; it consumes — no import). Engines never import each other. Read an
+   engine's real surface from `node_modules/@substrat-run/engine-*/dist/index.d.ts` —
+   never guess at it.
+3. **Your vertical — everything a user touches.** Vocabulary, price list, extra fields,
+   roles, screens. If your core noun isn't something an engine already owns, this is most
+   of the app — a normal, supported outcome.
+
+## Project layout
+
+The linter and tests expect this shape. `manifest`/`migrations`/`module` are **module
+code** (the rules below bind them); `seed`/`server` are **harness** (exempt).
+
+```
+src/manifest.ts        moduleManifest.parse({…}) + PERM consts   ← module code
+src/migrations.ts      the SqlMigration[]                         ← module code
+src/module.ts          imports both; operations + registration    ← module code
+src/seed.ts            host, tenants, roles, grants, seed world    ← harness
+src/server.ts          thin wrapper, one route per operation       ← harness
+test/scenario.test.ts  the scenario — including the denials
+```
+
+## The rules (non-negotiable)
+
+**Module code** = everything reachable from a `ModuleRegistration` (operations,
+consumers). Rules 1–4 are enforced mechanically by `boundary-lint`.
+
+1. **Data access is `ctx.sql` only.** Never import `better-sqlite3`, an adapter, or
+   `node:*` in module code.
+2. **No `fetch` / network in module code.** It would hold the scope's transaction open on
+   a third party. The sanctioned path is a **connector**: emit a fat event, register a
+   handler that runs outside the transaction. An integration is never impossible because
+   of this rule — it has an answer.
+3. **Never write `_substrat_*` tables.** Reads are fine (timelines are projections);
+   writes forge the audit spine.
+4. **Another module's tables are private.** Never `SELECT` from `workorder_*` etc. — use
+   the engine's exported in-scope functions. This is the rule with no runtime equivalent:
+   the shortcut *works* and silently welds you to an engine's private schema forever. Need
+   extra data on an engine entity? Add **your own side table keyed by the engine's id** —
+   never a column upstream.
+5. **Every operation checks a permission first.** `assertAllowed(await ctx.check(PERM))`
+   is the first line.
+6. **Every mutation emits a fat event** — a consumer must never need a cross-module read.
+7. **Never fork an engine.** Extend by composition. If you must fork, the engine drew its
+   line wrong — that's design feedback, not a coding problem.
+8. **IDs are `ulid()`. Money is strings** via `@substrat-run/contracts` helpers
+   (`moneyOf`, `mulMoney`, `addDecimal`, `compareDecimal`) — never floats.
+9. **Web-standard APIs always** — `globalThis.crypto`, `TextEncoder`, `URL`. Never
+   hand-roll a hash to dodge an import ban.
+10. **Parse, don't trust.** Zod at every boundary — but import `z` from
+    `@substrat-run/contracts`, **never from `zod`**. Zod schemas don't compose across
+    copies or majors; composing a contracts schema into one built from a separate `zod`
+    fails at *runtime* (`expected a Zod schema`) with an error pointing nowhere near the
+    cause.
+
+## Declare every link edge
+
+`entityRelations` in the manifest must declare every edge you traverse — both your own
+(`bike → customer`) and the ones an engine makes on your behalf (`workorder → bike`). The
+adapter **rejects** a `ctx.link` for an undeclared edge, so a missing one fails loudly.
+This is also what lets a portal permission-walk reach the owner.
+
+## The gates — run them, believe them
+
+```sh
+npm test                        # the scenario, including the denials
+npx @substrat-run/boundary-lint # the layer rules (1–4)
+npm run typecheck
+```
+
+`boundary-lint` exits non-zero if it *couldn't do its job* (no module code found, no
+engines resolvable) — a pass that checked nothing is worse than no linter. Never wave that
+through; fix the setup until it can see your code.
+
+A green scenario test does **not** mean the app works: the test calls operations directly
+and never exercises `server.ts`, its routes, or the principal picker. Before calling a
+vertical done, boot the server and drive the real flow over HTTP as two personas — one who
+should succeed and one who should be denied — and confirm the denial arrives as a denial
+(not a generic error).
+
+## Two human checkpoints — you may never self-approve
+
+Present these and stop:
+
+1. **Migration diff** — every new `SqlMigration`, verbatim. Migrations are append-only
+   forever once shipped, so this is the last cheap moment to change your mind.
+2. **Permission diff** — a table: key → description → which roles hold it → why. Walk the
+   reviewer through it in their own vocabulary until they can answer *who can now see the
+   money, and who can see other tenants' data?* A permission diff nobody understands is
+   theater — it reproduces the exact failure Substrat exists to prevent.

package/template/CLAUDE.md

@@ -0,0 +1,8 @@
+@AGENTS.md
+
+<!--
+Claude Code reads CLAUDE.md, not AGENTS.md. This one-line @-import pulls the shared
+constitution in verbatim, so there is a single source of truth every tool reads.
+Add Claude-only notes below this line if you ever need them; keep the shared rules in
+AGENTS.md so Cursor and opencode see them too.
+-->

package/template/src/manifest.ts

@@ -0,0 +1,48 @@
+import { moduleManifest, permissionKey } from '@substrat-run/contracts';
+
+// ============================================================================
+// The vertical's MANIFEST — the reviewable contract the kernel reads at
+// registration. A minimal bike-repair shop composed onto two engines:
+//
+//   engine-workorder  — the repair's state machine and append-only lines
+//   engine-invoicing  — turns a completed repair into an invoice basis, by EVENT
+//
+// This vertical owns only vocabulary (customers, bikes, a price list) and the
+// PRICING MOMENT. Every invariant that matters — a repair can't skip states,
+// a completed repair is immutable, every mutation emits an event — lives in the
+// engine. Read CLAUDE.md / AGENTS.md before you touch it.
+// ============================================================================
+
+/** The vertical's own permission keys (the engines declare their own). */
+export const SHOP_PERM = {
+  customerManage: permissionKey.parse('customer:manage'),
+  bikeManage: permissionKey.parse('bike:manage'),
+};
+
+export const bikeShopManifest = moduleManifest.parse({
+  id: 'bikeshop',
+  version: '0.0.1',
+  kernelContract: '^0.0.1',
+  permissions: [
+    { key: 'customer:manage', description: 'Manage customers and the workshop price list' },
+    { key: 'bike:manage', description: "Register and manage customers' bikes" },
+  ],
+  // The vertical emits and consumes no events of its own: the invoicing engine
+  // consumes the WORKORDER engine's `workorder.completed` directly (star
+  // topology — engines cooperate by event, never by import).
+  events: { emits: [], consumes: [] },
+  migrations: { journalDir: './migrations', compatibleFrom: '0.0.1' },
+  attachmentTargets: [
+    { entityType: 'customer', readPermission: 'customer:manage' },
+    { entityType: 'bike', readPermission: 'bike:manage' },
+  ],
+  // The portal permission walk is workorder → bike → customer. The engine links
+  // workorder → <facility ref>; in this vertical that facility ref IS a bike, so
+  // the vertical declares BOTH of its own edges. An entity-narrowed
+  // `workorder:read` grant on a customer then resolves all the way up.
+  entityRelations: [
+    { entityType: 'bike', parentType: 'customer' },
+    { entityType: 'workorder', parentType: 'bike' },
+  ],
+  entitlementKey: 'bikeshop',
+});

package/template/src/migrations.ts

@@ -0,0 +1,39 @@
+import type { SqlMigration } from '@substrat-run/kernel';
+
+// ============================================================================
+// The vertical's OWN tables, prefixed `shop_` so they can never collide with an
+// engine's. Ids are TEXT (ULIDs), timestamps ISO-8601 TEXT, money/decimals TEXT
+// — never a float, never a native DATE. Migrations are append-only and ordered:
+// once a version has shipped, you add a new one, you never edit it.
+// ============================================================================
+
+export const bikeShopMigrations: SqlMigration[] = [
+  {
+    version: '0001-init',
+    sql: `
+      CREATE TABLE shop_customers (
+        id          TEXT PRIMARY KEY,
+        number      TEXT NOT NULL UNIQUE,
+        name        TEXT NOT NULL,
+        phone       TEXT,
+        created_at  TEXT NOT NULL
+      );
+      CREATE TABLE shop_bikes (
+        id          TEXT PRIMARY KEY,
+        customer_id TEXT NOT NULL REFERENCES shop_customers(id),
+        label       TEXT NOT NULL,
+        frame_no    TEXT,
+        created_at  TEXT NOT NULL
+      );
+      CREATE TABLE shop_price_list (
+        article      TEXT PRIMARY KEY,
+        description  TEXT NOT NULL,
+        unit         TEXT NOT NULL,
+        price_amount TEXT NOT NULL,
+        currency     TEXT NOT NULL DEFAULT 'SEK',
+        min_qty      TEXT,
+        internal     INTEGER NOT NULL DEFAULT 0
+      );
+    `,
+  },
+];