@eventmodelers/cli 1.0.159 → 1.0.161

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.159",
+  "version": "1.0.161",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, OpenCQRS, UmaDB, Kurrent, or modeling-only)",
   "type": "module",
   "bin": {

package/shared/skills/learn-eventmodelers-api/SKILL.md

@@ -631,6 +631,8 @@ Create a SCREEN node from a sketch description.
 
 **File**: `src/slices/change/api-.slices/routes.ts`
 
+**One slice border per column.** Every node write (`/nodes/events`, MCP tools, the web UI) rejects a `SLICE_BORDER` whose `colId` — read from `meta.colId` or `node.data.colId` — already belongs to another `SLICE_BORDER` on the board, with `SLICE_BORDER_EXISTS` (`context.existingSliceBorderId` names the border to update or delete instead). Re-sending the same border, or creating a new one after the old one was deleted, is fine. Slice reads (`slicedata`) only ever return one slice per column, so a second border would otherwise exist on the board yet read back as an empty slice.
+
 ### POST `/api/org/:orgId/boards/:boardId/timelines/:timelineId/slices`
 Create a complete slice (1 column + its nodes automatically placed).
 
@@ -1175,11 +1177,12 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
 | to answer where one piece of information comes from and where it ends up ("where is the customer email used?") | `dataJourney` | nothing — element names pan the canvas |
 | to show a diagram you drew yourself — a context map, a domain story, a sketch, any picture that isn't a chart | `svg` | nothing |
 | to show a UML or flow diagram you write as Mermaid — a sequence, flowchart, state, ER or class diagram | `mermaid` | nothing |
+| to ask a complex question with several fields at once — a short form with text, choices, a slider, a date, checkboxes ("which environment, when, and who to notify?") | `a2ui` | `Answer to "<title>" (<action>):` + one `- label: value` line per input |
 | to lay out rows and columns — a comparison, a matrix (stressors × elements), a short list with a few attributes | `table` | nothing — linked cells pan the canvas |
 | to show a prototype you just built and uploaded (the `prototype` skill), running in the chat | `prototype` | nothing — **Full screen** opens the board's prototype player |
 | something the customer defined their own snippet type for (a risk card, a sign-off — see `list_snippet_types`) | `custom` | the clicked action's `answer`; `context.snippetReply.then` says what to do |
 
-`confirm`, `poll`, `tasks` and `changes` are questions: a person answers once, then they show as answered. `link`, `image`, `code`, `report`, `walkthrough`, `screen`, `dataJourney`, `svg`, `mermaid`, `table` and `prototype` are display only and never wait for anything.
+`confirm`, `poll`, `tasks`, `changes` and `a2ui` are questions: a person answers once, then they show as answered. `link`, `image`, `code`, `report`, `walkthrough`, `screen`, `dataJourney`, `svg`, `mermaid`, `table` and `prototype` are display only and never wait for anything.
 
 ### Shapes
 ```typescript
@@ -1230,6 +1233,12 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
                   width: number, height: number, title?: string }> }             // a click zooms the canvas to nodeId; title = tooltip (else the element's title)
 { kind: 'mermaid', source: string,                                               // Mermaid source, no ``` fence (≤ 60000 chars); the app draws it
   title?: string, caption?: string }
+{ kind: 'a2ui', title?: string,                                                   // an A2UI v0.9 form (https://a2ui.org), basic catalog subset
+  components: Array<{ id: string, component: string, ... }>,                      // flat list, ≤ 150; one has id 'root'; children refer to ids, no cycles
+  data?: object }                                                                 // initial data model; inputs bind to it with value: { path: '/form/x' }
+//   Text{text, variant?}  Row/Column/List{children:[id], align?}  Card{child}  Divider  TextField{label, value?, variant?: 'shortText'|'longText'|'number'}
+//   CheckBox{label, value?}  ChoicePicker{label, options:[{label,value}], value?:[…], variant?:'mutuallyExclusive'}  Slider{label, min, max, value?}
+//   DateTimeInput{label, enableDate?, enableTime?}  Button{child:<Text id>, variant?:'primary', action:{event:{name, context?}}}
 { kind: 'table', title?: string, caption?: string,
   columns: Array<string | { label: string, nodeId?: string,                      // 1–12; nodeId makes the header a link (a matrix with one column per element)
                             align?: 'left' | 'center' | 'right' }>,
@@ -1252,6 +1261,7 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
 - **`dataJourney`** answers "where does X come from / where is X used?" for **one piece of information**, as a table: one stop per element it passes through, in flow order, each with its `role`, the field name there and the slice. A headline counts the roles ("Originates in 1 place, stored in 2 elements and used in 3 places"). Build it from the board — the `data-journey` skill (modeling kit) has the procedure; every `nodeId` must be a real id from this board, and a field the board doesn't carry is not a stop. Keep `text` to one line naming the data and where it originates.
 - **`svg`** is for a picture you draw yourself: give the root a `viewBox` (and `width`/`height` for its natural size), inline colours and fonts — it is shown as an image, so scripts, `<a>` links and external resources do nothing. To make parts of it clickable, list them in `links`: a rectangle in the viewBox coordinates you drew in plus the element it stands for (only real ids from this board); the app lays a clickable area over each that zooms the canvas there. Prefer `report` for numbers. A domain story (who does what with which work object) is an `svg` you draw — the `domain-story` skill (modeling kit) has the procedure and the drawing style. Every SVG snippet has a download-as-PNG button.
   - **"Place it on the board" after you drew an SVG always means: put that picture on the board as an image** — never rebuild it from elements (stickies, lanes, a timeline), never a SCREEN, never a new snippet. `place_image` with `imageBase64` = the SVG document itself, base64-encoded, `mimeType: "image/svg+xml"`, `title` = the snippet's title: it becomes an OUTLINE (the drawing tools' image element), free-floating at `x`/`y`, in no chapter and connected to nothing. Place it where the person says, else in free space next to the chapter it is about (`get_chapter_bounds`: right of or below it). Add a white background `<rect>` first if the SVG has none, or it is unreadable on a dark board. One SVG = one image. The image on the board has no clickable areas — `links` stay in the chat.
+- **`a2ui`** is for a question that needs several answers at once — instead of five chat turns, send one form. Build it as a flat component list: a `Column` with id `root`, then the fields, then a primary `Button` whose `action.event.name` says what the click means (`submit`, `approve` …). Several buttons are fine (`approve` / `reject`); the clicked one's `name` is in the answer. The person's answer is one chat message — `Answer to "<title>" (<action>):` and a `- label: value` line per filled input, chosen options by their labels, then the action's `context` — so give every input a clear `label`. Keep it small (≤ ~8 fields) and send a meaningful `text`. Not supported (renders nothing): Image, Icon, Video, AudioPlayer, Tabs, Modal, template children (`{path, componentId}`) and function calls; a missing `root`, an unknown child id or a cycle makes the whole snippet invisible. Like every question it answers once.
 - **`mermaid`** is for a diagram you can write as text: a sequence diagram (`sequenceDiagram`), a flow (`flowchart LR`), states (`stateDiagram-v2`), an ER or class diagram. Send just the source; the app draws it, with a *Show source* toggle and a copy button, and shows the source when it has a syntax error — so keep the syntax plain (quote labels with special characters). Prefer it over a `code` block for any diagram: a `code` block with `language: "mermaid"` is drawn too, but `mermaid` says what you mean. It has no element links; for clickable parts draw an `svg`.
 - **`table`** is for anything that is rows and columns and not a chart: a comparison of options, an incidence matrix (rows = stressors, columns = elements, `true` where it hits), a short list with a few attributes per item. It computes nothing — totals are a row you add. Put element ids in `nodeId` (header or cell) so names are links; a row longer than the columns is cut, a shorter one padded, an empty one dropped. Prefer `report` for numbers you want *seen* as a trend or share, `dataJourney` for one piece of data's path.
 - **`prototype`** runs a prototype in the chat: the page the platform stored for `timelineId` (the `contextId` the `prototype` skill uploaded under — any timeline of that context works too), in a sandboxed iframe with **Restart** (empty event log) and **Full screen** (the same player as the timeline's ▶). Send it only after `upload` succeeded — before that it shows "No prototype has been built for this yet". The `text` is the short report of what was built; the prototype itself is the snippet.

package/stacks/modeling-kit/templates/.claude/skills/build-snippet-type/SKILL.md

@@ -51,7 +51,7 @@ Ask only what you cannot infer, one question per turn, with a snippet whenever t
 - `instructions`: at most 4000 characters.
 
 ### Based on a built-in kind — when the built-in snippet already looks right
-A type doesn't have to be custom-drawn. With `base` set to a built-in kind (`table`, `report`, `poll`, `tasks`, `confirm`, `dataJourney`, `link`, `code`, …) the type has **no template and no actions**, and the `schema` is optional. Its data is exactly that kind's JSON without `kind` (for `table`: `{ title?, columns, rows }`), and the chat draws and answers it like that kind — element links (`nodeId`), paging and its own answer buttons included.
+A type doesn't have to be custom-drawn. With `base` set to a built-in kind (`table`, `report`, `poll`, `tasks`, `confirm`, `dataJourney`, `link`, `code`, `a2ui`, …) the type has **no template and no actions**, and the `schema` is optional. Its data is exactly that kind's JSON without `kind` (for `table`: `{ title?, columns, rows }`) — an `a2ui` base is the way to keep a reusable form (`{ title?, components, data? }`, see `learn-eventmodelers-api` §16), and the chat draws and answers it like that kind — element links (`nodeId`), paging and its own answer buttons included.
 
 - Prefer this whenever the person wants to keep a built-in snippet you showed, and whenever the card must **link to elements** on the board — a template's sandboxed frame can't.
 - The `instructions` carry what makes it reusable: what to collect each time and how to fill the kind's fields (*"One row per chapter (CHAPTER elements), sorted by title; column 'Chapter'; each cell `{text: <title>, nodeId: <id>}`."*).

package/stacks/modeling-kit/templates/kit/CLAUDE.md

@@ -315,6 +315,7 @@ for it. Instead:
    - **"draw" / "sketch" / "diagram" something** (a UML diagram, a flow, a class model) → a snippet in the chat (`mermaid` for a sequence/flow/state/ER/class diagram written as
      Mermaid, `svg` for a picture you draw yourself, or a `code` block with PlantUML/ASCII), **never** drawn on the board with stickies, arrows or `create_drawing`.
      Only an explicit request to put it on the board changes that, and then as an image (`/domain-story` § board), not rebuilt from shapes;
+   - **a question with several fields** (environment + date + who to notify, a small form) → `a2ui`, one form instead of several chat turns;
    - **rows and columns** — a comparison, a matrix, a short list with a few attributes per item → `table`.
    - **a prototype you just built** (the `/prototype` skill) → `prototype`, the uploaded page running in the chat with a Full screen button;
    - anything the customer defined **their own snippet type** for → `custom` with its `ref`: `list_snippet_types`

package/stacks/supabase-react/templates/.claude/skills/build-state-change/SKILL.md

@@ -63,6 +63,9 @@ Extract:
   isn't built or re-fetched yet: fall back to `apiEndpoint` / `fields[]` as above and note the assumption
   in `progress.txt`. If contract and `command.fields[]` disagree, the contract wins for the request and
   you record the mismatch in `progress.txt`.
+  **Build the call from it**: `postCommand(buildPath('<contract path>', { <path params> }), { <requestBody
+  properties> })` — `buildPath` (in `src/lib/api.ts`) fills and URL-encodes `{param}` segments; the body
+  carries exactly the contract's `requestBody` properties (props the contract doesn't list stay out).
 - **events[]** — informational only (what the backend is expected to emit); this stack does not
   act on them directly.
 - **screens[]** — the actor `SCREEN` element(s) that trigger this command, if any. Empty when the
@@ -127,11 +130,14 @@ lane concept, so the frontend path isn't a strict 1:1 mirror of it. `CommandTitl
 `title` verbatim (e.g. `ReserveBike.tsx`).
 
 **Markup**: translate the blueprint HTML from Step 2 into JSX **1:1** — same tags, same classes
-(Bulma or whatever the mockup used), same layout and copy. This is not a redesign; the screen *is*
+(the screen's `cssFrameworks` framework), same layout and copy. This is not a redesign; the screen *is*
 the design. Only change what must become dynamic:
 - A field's example value becomes that input's controlled `value`.
 - An element repeated for a `cardinality: "List"` field becomes a `.map()` over that field.
-- `class`/`style`/structure otherwise stay exactly as drawn.
+- `class`/`style`/structure otherwise stay exactly as drawn — except the board's own mark plumbing:
+  drop every `data-em-mark-id` attribute and `em-mark`/`em-mark-<hex>` class (they only draw the
+  highlight outline on the canvas; the app never ships it).
+- The classes only render correctly if the screen's CSS framework (`cssFrameworks`) is loaded in the app — see Step 7 (styles); don't hand-write CSS to compensate.
 
 **Props**: exactly `command.fields[]`, typed per each field's `type` (`String`→`string`,
 `Boolean`→`boolean`, `Int`/`Long`→`number`, etc. — `subfields[]` become a nested object type),
@@ -290,9 +296,52 @@ how many pages this app needs — not one page per slice.
    - If `src/pages/<ScreenTitle>.tsx` already exists, update only this slice's marked position;
      leave every other position (already-wired slices, and untouched mockup content) exactly as is.
 
-## Step 7 — Verify against slice.json
-
-After writing the hook/component (and context/page, if any), confirm:
+## Step 7 — Load the screen's styles, every slice
+
+The mockup's classes only mean something with the CSS framework the board renders it with, so the
+app must load that same one. This runs on **every** slice (not just the first) and is idempotent —
+an existing project that is missing it gets fixed on its next build.
+
+1. **Detect** the framework the screen loads, from the node fetched in Step 2: `cssFrameworks` (one id).
+   If it isn't returned, infer it from the classes in `meta.pages` (`title`/`field`/`is-*` → bulma,
+   `btn`/`form-control`/`col-*` → bootstrap, utility classes like `flex p-6` → tailwind). If the
+   screen loads **no** framework (`[]`, or nothing detectable), use Vite's default: change nothing —
+   skip this whole step, leave `index.html` and `src/index.css` as the template ships them.
+2. **Ensure it's loaded** in `index.html`'s `<head>`, same pinned version the board uses — check with
+   `grep -n -i "bulma\|bootstrap\|cdn.tailwindcss" index.html` first, add only what's missing:
+   - `bulma` → `<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.4/css/bulma.min.css">`
+   - `bootstrap` → `<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css">`
+   - `tailwind` → `<script src="https://cdn.tailwindcss.com/3.4.16"></script>`
+
+   A *different* framework already there means two screens disagree: don't mix them — keep what's
+   there and flag it via `request-feedback`.
+3. **Neutralise the Vite demo CSS** (only because a framework was detected). If `src/index.css` still holds the demo (it contains `#social` or
+   `--social-bg`), replace the whole file with `body { margin: 0; }` — the centred 1126px `#root`,
+   dark-mode palette, `color-scheme: light dark`, grey text and 56px `h1` all fight the mockup. A file
+   without those markers was already customised (or filled from `learn-styleguide`): leave it alone.
+
+## Step 8 — Base page, only if this is the first slice
+
+`src/App.tsx` ships as the Vite demo scaffold. The **first slice built in this project** replaces it
+with the app's **base page**, so there is something real to open in the browser; every later slice
+leaves it alone.
+
+1. **First slice?** Yes only if `src/slices/` holds no other slice folder than this one (only
+   `.gitkeep` besides it) *and* `src/App.tsx` still contains the scaffold (`Get started` heading).
+   Otherwise skip this step entirely.
+2. Rewrite `src/App.tsx` as the base page: a minimal `<main>` that renders the top-level thing this
+   slice produced — `src/pages/<ScreenTitle>.tsx` when Step 6 composed a shared page, else this
+   slice's own component. Nothing from the Vite demo (counter, logos, doc links) stays. No router and
+   no new dependency — a single page needs neither.
+3. Delete what the scaffold alone used and nothing else now imports: `src/App.css` and
+   `src/assets/{hero.png,react.svg,vite.svg}` (check with `grep -rn` first); `public/icons.svg` too if
+   nothing references it. Leave `src/main.tsx` and `src/index.css` (Step 7 handles it) as they are.
+4. Keep the page working with no backend, per the isolation rule in `.build-kit/CLAUDE.md`: the
+   slice component must render its empty state, and `VITE_DATA_MODE=mock` must show its sample.
+
+## Step 9 — Verify against slice.json
+
+After writing the hook/component (and context/page/base page, if any), confirm:
 - Every prop matches a `command.fields[]` entry exactly (name + type) — no invented or missing
   fields.
 - The `postCommand` call uses the UI contract's `path` and `body` when one was found, else `command.apiEndpoint` verbatim — or, when it was missing at build

package/stacks/supabase-react/templates/.claude/skills/build-state-view/SKILL.md

@@ -29,7 +29,8 @@ convenient — for a component to read it straight from Supabase, with no bespok
 between, the same way `miro-eventmodeling` and this stack's other Supabase-backed components do.
 
 That said, a component never calls `supabase.from(...)` (or imports `src/lib/supabase.ts`) itself —
-it calls `queryReadModel(...)` from `src/lib/api.ts`, same as `build-state-change` components only
+it calls `getReadModel(...)` (backend `GET` UI contract available) or `queryReadModel(...)` (table
+read) from `src/lib/api.ts`, same as `build-state-change` components only
 ever call `postCommand`. `queryReadModel` is the real Supabase call in production, but in mock mode
 it serves a numbered sample instead (see Step 4) — routing every read through this one seam is what
 makes a component testable/previewable in isolation, with zero Supabase project needed.
@@ -66,10 +67,22 @@ Extract:
        a Slice" step 6) — the built, mocked component still needs a real table/view before it's done,
        so don't flip it to `Done`.
   - `description` — implementation hints (filtering rules, sort order, business meaning).
-- **No UI contract for reads** — the backend's `ui-contract` skill publishes a `GET` contract, but this
-  stack reads the table/view directly (RLS-protected) and never calls a read endpoint, so that
-  contract does not apply here. `readmodel.apiEndpoint` (table/view name) and `fields[]` stay the
-  source. (Only the write side, `build-state-change`, consumes a contract.)
+- **UI contract (read)** — the backend slice's published `GET` contract: look it up as described in
+  the `ui-contract` skill ("How the UI build kit looks the contract up" — the `## UI Contract` entry in
+  `slice.json` `notes[]`; parse only its `ui-contract` block — an OpenAPI operation). **When present it
+  is the specification and you build the call from it** — it overrides `apiEndpoint` and the table read:
+  - fetch with `getReadModel(buildPath('<contract path>', { <path params> }), { <query params> }, samples)`
+    from `src/lib/api.ts` — path and query `parameters` exactly as the contract names them, never a
+    guessed URL, never `supabase.from(...)`;
+  - type the result from the 2xx `responses` schema (it must match `readmodel.fields[]`; the contract
+    wins for the wire shape, record any mismatch in `progress.txt`);
+  - render **every** non-2xx response (status + description) as its own distinct state — a 404 "no
+    reservation" is an empty state, not an error banner; don't collapse them into one generic failure;
+  - the numbered samples (Step 4) are shaped like the contract's 2xx response body.
+
+  **When absent** (backend slice not built or not re-fetched yet): fall back to the table read —
+  `readmodel.apiEndpoint` (table/view name) + `fields[]` via `queryReadModel` — and note the assumption
+  in `progress.txt`.
 - **screens[]** — the actor `SCREEN` element(s) that display this data, if any (see Step 2).
 - **specifications[]** — GWT scenarios/storyline; treat as acceptance criteria (e.g. "given no
   active reservation, show an empty state").
@@ -103,8 +116,13 @@ the mockup is the design, not a starting point for a redesign.
 its parent, never read from a global store. The queried data itself is **not** a prop — the
 component fetches it.
 
-**Default — call `queryReadModel` from `src/lib/api.ts` inside the component**. Never `supabase.from(...)`
-directly, never a raw `fetch`:
+**With a UI contract (Step 1)**: call `getReadModel(buildPath(path, pathParams), queryParams, samples)`
+from `src/lib/api.ts` inside the component instead of the `queryReadModel` snippet below — same
+effect shape (`useEffect` → loading / empty / error / data), but each documented non-2xx response
+(`ApiError.status`) maps to its own state. Never a raw `fetch`.
+
+**Default (no contract) — call `queryReadModel` from `src/lib/api.ts` inside the component**. Never
+`supabase.from(...)` directly, never a raw `fetch`:
 
 ```tsx
 // ActiveReservationView.tsx
@@ -196,7 +214,7 @@ component doesn't do anything with that number itself, `queryReadModel` reads it
 
 ## Step 5 — Compose onto the shared page, if this screen's name is shared
 
-Identical to `build-state-change` Step 5 — a screen's **title is the page name**, and the number
+Identical to `build-state-change` Step 6 — a screen's **title is the page name**, and the number
 of *distinct* screen titles across the board is a direct hint at how many pages this app needs, not
 one page per slice.
 
@@ -216,10 +234,55 @@ one page per slice.
    slice component still only knows its own declared props. Update only this slice's marked
    position if the page file already exists.
 
-## Step 6 — Verify against slice.json
+## Step 6 — Load the screen's styles, every slice
+
+The mockup's classes only mean something with the CSS framework the board renders it with, so the
+app must load that same one. This runs on **every** slice (not just the first) and is idempotent —
+an existing project that is missing it gets fixed on its next build.
+
+1. **Detect** the framework the screen loads, from the node fetched in Step 2: `cssFrameworks` (one id).
+   If it isn't returned, infer it from the classes in `meta.pages` (`title`/`field`/`is-*` → bulma,
+   `btn`/`form-control`/`col-*` → bootstrap, utility classes like `flex p-6` → tailwind). If the
+   screen loads **no** framework (`[]`, or nothing detectable), use Vite's default: change nothing —
+   skip this whole step, leave `index.html` and `src/index.css` as the template ships them.
+2. **Ensure it's loaded** in `index.html`'s `<head>`, same pinned version the board uses — check with
+   `grep -n -i "bulma\|bootstrap\|cdn.tailwindcss" index.html` first, add only what's missing:
+   - `bulma` → `<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.4/css/bulma.min.css">`
+   - `bootstrap` → `<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css">`
+   - `tailwind` → `<script src="https://cdn.tailwindcss.com/3.4.16"></script>`
+
+   A *different* framework already there means two screens disagree: don't mix them — keep what's
+   there and flag it via `request-feedback`.
+3. **Neutralise the Vite demo CSS** (only because a framework was detected). If `src/index.css` still holds the demo (it contains `#social` or
+   `--social-bg`), replace the whole file with `body { margin: 0; }` — the centred 1126px `#root`,
+   dark-mode palette, `color-scheme: light dark`, grey text and 56px `h1` all fight the mockup. A file
+   without those markers was already customised (or filled from `learn-styleguide`): leave it alone.
+
+## Step 7 — Base page, only if this is the first slice
+
+`src/App.tsx` ships as the Vite demo scaffold. The **first slice built in this project** replaces it
+with the app's **base page**, so there is something real to open in the browser; every later slice
+leaves it alone.
+
+1. **First slice?** Yes only if `src/slices/` holds no other slice folder than this one (only
+   `.gitkeep` besides it) *and* `src/App.tsx` still contains the scaffold (`Get started` heading).
+   Otherwise skip this step entirely.
+2. Rewrite `src/App.tsx` as the base page: a minimal `<main>` that renders the top-level thing this
+   slice produced — `src/pages/<ScreenTitle>.tsx` when Step 5 composed a shared page, else this
+   slice's own component. Nothing from the Vite demo (counter, logos, doc links) stays. No router and
+   no new dependency — a single page needs neither.
+3. Delete what the scaffold alone used and nothing else now imports: `src/App.css` and
+   `src/assets/{hero.png,react.svg,vite.svg}` (check with `grep -rn` first); `public/icons.svg` too if
+   nothing references it. Leave `src/main.tsx` and `src/index.css` (Step 6 handles it) as they are.
+4. Keep the page working with no backend, per the isolation rule in `.build-kit/CLAUDE.md`: the
+   slice component must render its empty state, and `VITE_DATA_MODE=mock` must show its sample.
+
+## Step 8 — Verify against slice.json
 
 - Every rendered field traces back to a `readmodel.fields[]` entry — no invented or missing
   fields.
+- With a UI contract: the `getReadModel` call uses the contract's path and query `parameters`
+  verbatim, and every non-2xx response has its own rendered state. Otherwise:
 - The `queryReadModel` call targets `readmodel.apiEndpoint` verbatim as `table` — or, when it was
   missing at build time, the provisional `mock_...` table name noted in a comment (Step 1) — never a
   raw `fetch`, a direct `supabase.from(...)` call, or a hardcoded table name that doesn't match

package/stacks/supabase-react/templates/build-kit/CLAUDE.md

@@ -11,8 +11,9 @@ not attempt to build it, flag it via `request-feedback` instead.
 ## File Structure Constraints
 
 - **Strict Path Limitation**: `src/slices/{contextSlug}/{laneSlug}/{slicename}/*` — the one
-  exception is `src/pages/`, where multiple slices sharing one screen get composed together (see
-  guideline 8 below)
+  exceptions are `src/pages/`, where multiple slices sharing one screen get composed together (see
+  guideline 7 below), and — for the **first slice only** — `src/App.tsx` plus the Vite demo files it
+  replaces (guideline 10 below); `index.html` and the demo `src/index.css` for every slice (guideline 11)
 - **Slice Organization**: Each feature/domain should be organized as a separate slice
 
 ## Code Standards
@@ -27,7 +28,7 @@ not attempt to build it, flag it via `request-feedback` instead.
 2. Maintain clear separation of concerns within each slice
 3. Headers, auth, `fetch`, and Supabase table access live exclusively in `src/lib/api.ts` — a
    slice component never imports `src/lib/supabase.ts` itself, never calls `fetch`, and never
-   calls `supabase.from(...)` directly; it calls `postCommand`/`queryReadModel` and only contains
+   calls `supabase.from(...)` directly; when the backend slice published a UI contract (`ui-contract` skill, `slice.json` `notes[]`) the slice is built *from* it — path, parameters, body and every error response — and falls back to `apiEndpoint`/`fields[]` only when none exists; it calls `postCommand`/`getReadModel`/`queryReadModel` and only contains
    business logic (validation, request-body shaping, response handling)
 4. A command's/read-model's screen markup (`meta.pages` on its actor HTML_SCREEN node, scoped to
    this slice's `meta.marks` when the screen is shared) is the visual blueprint — translate it into
@@ -82,6 +83,18 @@ not attempt to build it, flag it via `request-feedback` instead.
    the app, not an arbitrary per-component index. See `build-state-change`/`build-state-view`'s
    samples step for the full convention.
 
+10. **The first slice also builds the base page.** `src/App.tsx` ships as the Vite demo. When the
+    slice being built is the first one in the project (no other folder under `src/slices/`), replace
+    it with a minimal base page rendering that slice's page or component and delete the demo-only
+    files; no router, no new dependency. Later slices never touch `src/App.tsx`. See
+    `build-state-change` Step 8 / `build-state-view` Step 7.
+11. **Every slice loads its screen's styles.** The mockup's classes are meaningless without the CSS
+    framework the board renders them with. Each slice detects it (`cssFrameworks`, else the classes
+    in `meta.pages`; none → Vite's default stays as is), makes sure `index.html` loads it, and neutralises the Vite demo
+    `src/index.css` if it's still there — automatically, idempotently, so an existing project heals
+    on its next build. Never hand-write CSS to imitate a framework. See `build-state-change` Step 7 /
+    `build-state-view` Step 6.
+
 At the start of every session, read `.build-kit/AGENTS.md` if it exists to load accumulated project learnings.
 
 When starting to work on a slice, invoke the `update-slice-status` skill with `InProgress` status before doing anything else.
@@ -124,6 +137,7 @@ src/lib/supabase.ts                                # Supabase client singleton
 src/lib/api.ts                                     # postCommand/queryReadModel + auth headers + mock-mode switch (shared, not per-slice)
 src/lib/<CrossCutting>Provider.tsx                  # only for concerns every slice might need (session, theme, ...)
 src/pages/<ScreenTitle>.tsx                         # only when >1 slice shares a screen title — composes their components
+src/App.tsx                                        # base page — replaces the Vite demo when the first slice is built, untouched afterwards
 src/slices/<contextSlug>/<laneSlug>/<sliceFolder>/
   <CommandTitle>.tsx                                # STATE_CHANGE slice — component (logic inline by default)
   use<CommandTitle>.ts                              # only if the logic was genuinely worth splitting out

package/stacks/supabase-react/templates/root/src/lib/api.ts

@@ -84,6 +84,58 @@ export async function postCommand<TResponse = unknown>(
   return payload as TResponse;
 }
 
+/**
+ * Fill an OpenAPI path template (`/api/customers/{customerId}/reservation`) with values,
+ * URL-encoding each one. Throws if a `{param}` has no value — a contract's path parameters are
+ * required. Use the contract's path verbatim as `template`; never hand-assemble a URL.
+ */
+export function buildPath(template: string, params: Record<string, string | number> = {}): string {
+  return template.replace(/\{(\w+)\}/g, (_, name: string) => {
+    const value = params[name];
+    if (value === undefined) throw new Error(`Missing path parameter "${name}" for ${template}`);
+    return encodeURIComponent(String(value));
+  });
+}
+
+function mockSample<T>(samples: Record<string, T> | undefined, what: string): T {
+  const n = activeMockSample();
+  const sample = samples?.[n];
+  if (sample === undefined) {
+    throw new Error(
+      `Mock mode is on (VITE_MOCK_SAMPLE=${n}) but no sample-${n}.json exists for ${what} — add one under this component's samples/ folder.`,
+    );
+  }
+  return sample;
+}
+
+/**
+ * GET a read model from the backend's published `GET` UI contract (`path` already filled via
+ * `buildPath`, `query` = the contract's query `parameters`). Resolves with the parsed JSON, or
+ * throws `ApiError` on a non-2xx response — the status and body let a component render each
+ * documented error response as its own state. Mock mode serves `samples` like `queryReadModel`.
+ */
+export async function getReadModel<T>(
+  path: string,
+  query?: Record<string, string | number | boolean | undefined>,
+  samples?: Record<string, T>,
+): Promise<T> {
+  if (isMockMode()) return mockSample(samples, `GET ${path}`);
+
+  const qs = new URLSearchParams(
+    Object.entries(query ?? {}).filter(([, v]) => v !== undefined).map(([k, v]) => [k, String(v)]),
+  ).toString();
+  const headers = await getAuthHeaders();
+  const res = await fetch(`${API_BASE}${path}${qs ? `?${qs}` : ''}`, { method: 'GET', headers });
+
+  const payload = await res.json().catch(() => undefined);
+  if (!res.ok) {
+    const message =
+      (payload && (payload.error || payload.message)) || `Request failed with status ${res.status}`;
+    throw new ApiError(message, res.status, payload);
+  }
+  return payload as T;
+}
+
 export interface ReadModelParams {
   /** `readmodel.apiEndpoint`, verbatim — the Postgres table/view name. */
   table: string;
@@ -105,16 +157,7 @@ export async function queryReadModel<T>(
   params: ReadModelParams,
   samples?: Record<string, T>,
 ): Promise<T> {
-  if (isMockMode()) {
-    const n = activeMockSample();
-    const sample = samples?.[n];
-    if (sample === undefined) {
-      throw new Error(
-        `Mock mode is on (VITE_MOCK_SAMPLE=${n}) but no sample-${n}.json exists for table "${params.table}" — add one under this component's samples/ folder.`,
-      );
-    }
-    return sample;
-  }
+  if (isMockMode()) return mockSample(samples, `table "${params.table}"`);
 
   let query = supabase.from(params.table).select(params.select);
   for (const [column, value] of Object.entries(params.filters ?? {})) {