@eventmodelers/cli 1.0.54 → 1.0.55

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

@@ -0,0 +1,305 @@
+---
+name: build-state-change
+description: Build a write-side React slice for the Supabase stack — one dedicated component per COMMAND (splitting into a hook and/or a colocated Context/Provider only when the slice actually needs one) that POSTs to its slice-defined apiEndpoint via the shared api.ts, driven by the marked-up region of its actor HTML_SCREEN
+---
+
+# Build State Change Slice
+
+> Before doing anything else, read the slice definition from
+> `.build-kit/.slices/<contextSlug>/<sliceFolder>/slice.json`. This file (plus, when a screen is
+> involved, the live screen node fetched in Step 2) is the **source of truth** for every field,
+> event, and endpoint — never invent a field, prop, or path that isn't there.
+
+---
+
+## What a State Change Slice is
+
+One `COMMAND` element (`slice.json.commands[]`) that, when submitted, causes one or more `EVENT`
+elements (`slice.json.events[]`) to be recorded by the backend. This stack builds only the
+**frontend half**: a dedicated React component that collects the command's data (via props — this
+component never fetches or owns its own data) and POSTs it to an already-existing backend
+endpoint, via `postCommand` in `src/lib/api.ts` — never `fetch` directly. It does not generate any
+server-side code.
+
+Every component must be renderable and testable **in isolation**, with no real backend running —
+see Step 4 (numbered `samples/`) and `src/lib/api.ts`'s `VITE_DATA_MODE=mock`, which makes
+`postCommand` resolve locally instead of hitting the network.
+
+## Step 1 — Read slice.json
+
+Extract:
+- **title**, **context** — slice identity, used for file paths (see Step 3).
+- **commands[0]** — the command element. Each `Element` carries:
+  - `title` — the command name, e.g. `"ReserveBike"`.
+  - `fields[]` — one entry per data field (`name`, `type`, `optional?`, `cardinality?`, `example?`,
+    `subfields?`). This is the **exact and complete** set of props the component takes — no more,
+    no fewer.
+  - `apiEndpoint` — the path to POST to. **Read this literally from slice.json when it's present**
+    — do not guess a REST convention, invent a path, or infer one from the command name while a real
+    one exists. **When `apiEndpoint` is missing** (no backend endpoint decided yet), flag it but keep
+    building — this is a partial variant of `request-feedback`, not a full stop:
+    1. Post a comment on this slice node naming the command and stating the endpoint is missing
+       (`mcp__eventmodelers__add_comment`, same call `request-feedback` Step 3 uses), and mark the
+       slice `Blocked` (`mcp__eventmodelers__update_slice_status`, same as `request-feedback` Step 4).
+    2. Unlike a normal `request-feedback` escalation, **do not stop here** — continue on to build the
+       component exactly as normal, but against a mocked backend: give `postCommand` a clearly
+       provisional path, e.g. `/api/mock/<command-title-kebab-case>`, with a one-line comment marking
+       it as a placeholder pending the real endpoint. `postCommand` already resolves locally under
+       `VITE_DATA_MODE=mock` regardless of what the path string is (see `src/lib/api.ts`), so the
+       component is fully functional offline either way — only make Step 4's samples do extra work in
+       this case: cover every `command.fields[]` entry with realistic, meaningful values (never
+       placeholders like `"foo"`/`"test"`), plus whatever edge cases `specifications[]` call out,
+       since those samples are the only data this slice will see until a real endpoint is wired in.
+    3. Leave the slice's status as `Blocked` when you finish (see this stack's `CLAUDE.md` "Building
+       a Slice" step 6) — the built, mocked component still needs a real endpoint before it's done,
+       so don't flip it to `Done`.
+  - `description` — implementation hints (validation rules, business constraints).
+- **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
+  command has no UI trigger (rare — build the component from fields alone in that case, skip Step
+  2).
+- **specifications[]** — GWT scenarios; treat as acceptance criteria for the component's business
+  logic (e.g. "given empty `email`, submit is disabled").
+
+> **Comments**: each element carries `comments: string[]` (board comments) — read them as
+> implementation hints, and resolve consumed ones via
+> `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve`.
+
+## Step 2 — Read the screen, and especially its marks
+
+`slice.json`'s `screens[]` entries only carry `id`/`title`/`fields[]`/`description` (fields already
+scoped to this slice) — not the actual markup. Fetch the live node to get that:
+
+```
+mcp__eventmodelers__get_node { "boardId": "<BOARD_ID>", "nodeId": "<screen.id>" }
+```
+
+This returns the full `meta`, including `pages: string[]` (one HTML fragment per page) and,
+if the screen is shared across several slices, `marks: [{ id, color, pageIndex, blurOutside?,
+whiteOutside? }]`.
+
+- **If `meta.marks` is non-empty**: the same visual screen is shared by multiple slices, each
+  highlighting a different part. Find the mark(s) belonging to this node, then in
+  `meta.pages[mark.pageIndex]` locate the element carrying `data-em-mark-id="<mark.id>"` — **that
+  HTML subtree, not the rest of the page, is the blueprint for what this component builds.**
+  Ignore markup outside it; it belongs to other slices.
+- **If `meta.marks` is empty**: the whole page (every entry in `meta.pages`, in order, for a
+  multi-step flow) is the blueprint.
+- **If `screens[]` was empty in Step 1**: there is no visual reference — build the component from
+  `fields[]` alone, with plain, unstyled form markup.
+
+If this project has a `learn-styleguide` skill installed (`.claude/skills/learn-styleguide/`),
+read its references before turning markup into JSX and prefer its tokens/component classes over
+whatever ad hoc styling the mockup used — the mockup gives you *structure and content*, the style
+guide gives you the real visual language when the two disagree.
+
+**Also resolve this screen's lane** (skip if `screens[]` was empty in Step 1 — see Step 3's file
+path): the actor row this screen sits in becomes a folder segment. Fetch it cheaply with:
+
+```
+mcp__eventmodelers__get_board_outline { "boardId": "<BOARD_ID>", "chapterId": "<screen node's chapterId>" }
+```
+
+This returns `{id, type, title, lane}` for every node in the chapter — find the entry whose `id`
+matches `screen.id` and take its `lane`. Slugify it the same way `contextSlug` is derived
+(lowercase, spaces to hyphens, non-alphanumeric stripped) to get `laneSlug`.
+
+## Step 3 — Build the dedicated component
+
+**File**: `src/slices/<contextSlug>/<laneSlug>/<sliceFolder>/<CommandTitle>.tsx` — `contextSlug` and
+`sliceFolder` are derived exactly as in `load-slice` (lowercase-slugified context; slice title
+lowercased with spaces removed and any `slice:` prefix stripped); `laneSlug` comes from Step 2
+above. Omit the `<laneSlug>` segment (fall back to `<contextSlug>/<sliceFolder>/`) only for the
+rare headless command with no `screens[]` at all — there's no lane to resolve without a screen.
+Note this nests one level deeper than the staging data in
+`.build-kit/.slices/<contextSlug>/<sliceFolder>/slice.json` — `load-slice`'s own local index has no
+lane concept, so the frontend path isn't a strict 1:1 mirror of it. `CommandTitle` is the command's
+`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 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.
+
+**Props**: exactly `command.fields[]`, typed per each field's `type` (`String`→`string`,
+`Boolean`→`boolean`, `Int`/`Long`→`number`, etc. — `subfields[]` become a nested object type),
+respecting `optional`. Add two callback props: `onSuccess?: (result: TResponse) => void` and
+`onError?: (error: ApiError) => void`. **No other inputs** — no context/store reads, no fetching
+inside the component. All business data the component needs arrives via props from its parent.
+
+**Default — keep the logic in the component.** For an ordinary command (one form, one submit
+action, which is most of them) local state and the `postCommand` call live directly inside the
+component. This is the common case and needs nothing more:
+
+```tsx
+// ReserveBike.tsx
+import { useState } from 'react';
+import { postCommand, ApiError } from '../../../../lib/api'; // one less '../' if this command has no lane segment
+
+export interface ReserveBikeProps {
+  bikeId: string;
+  customerId: string;
+  onSuccess?: (result: unknown) => void;
+  onError?: (error: ApiError) => void;
+}
+
+export function ReserveBike({ bikeId, customerId, onSuccess, onError }: ReserveBikeProps) {
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const handleSubmit = async () => {
+    setSubmitting(true);
+    setError(null);
+    try {
+      const result = await postCommand('/api/reservebike', { bikeId, customerId });
+      onSuccess?.(result);
+    } catch (err) {
+      const message = err instanceof ApiError ? err.message : 'Something went wrong';
+      setError(message);
+      if (err instanceof ApiError) onError?.(err);
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  // ...JSX translated from the marked screen fragment, wired to handleSubmit...
+}
+```
+
+The component owns only: local form/loading/error state, whatever client-side validation the
+`specifications[]`/field `optional` flags imply, building the request body from props, and calling
+`postCommand(command.apiEndpoint, body)`. It never imports `supabase`, builds headers, or calls
+`fetch` directly — that is exclusively `src/lib/api.ts`'s job. In `VITE_DATA_MODE=mock`,
+`postCommand` never hits the network at all — it resolves immediately, so this component is fully
+exercisable (submitting/success/error UI states) offline.
+
+**Extract a `use<CommandTitle>.ts` hook only when it earns its keep** — e.g. the exact same logic
+is genuinely reused by more than one component in this slice, or the non-rendering logic (several
+async steps, non-trivial multi-field validation) has grown large enough that pulling it out of the
+component measurably improves readability. Don't extract a hook by default, for uniformity with
+other slices, or "for consistency" — a small command's logic reads perfectly fine inline, and a
+hook file that's just a thin wrapper around `postCommand` is pure ceremony working against
+deletability, not for it (one more file to keep in sync instead of one). When it *is* warranted,
+move the same logic verbatim into a colocated `use<CommandTitle>.ts` and have the component call
+it — nothing about the logic itself changes, only where it lives.
+
+## Step 4 — Add numbered samples
+
+Every command component ships a `samples/` folder colocated next to it, mirroring
+`build-state-view`'s convention:
+`src/slices/<contextSlug>/<laneSlug>/<sliceFolder>/samples/sample-<N>.json`. Since this component
+is driven entirely by props, each sample is a **full set of prop values** — there's no query for
+`postCommand` to serve (it's already mock-aware on its own, see Step 3). A sample is for whatever
+renders this component in isolation (a `src/pages/` composition, or ad hoc while developing) to
+spread as props, e.g. `<ReserveBike {...sample1} onSuccess={...} />`.
+
+Add `sample-1.json` for the ordinary case (`command.fields[].example` values); add more numbered
+ones for other scenarios `specifications[]` calls out (an edge case, an `optional` field omitted,
+...). As in `build-state-view`, the same number across different components' samples is meant to
+represent one coherent scenario across the app, not an arbitrary per-component index.
+
+## Step 5 — Context/Provider, only if the marked fragment needs shared local state
+
+Skip this step for the overwhelming majority of commands — an ordinary single-form command is
+fully covered by Step 3 alone, and adding a Context there is needless indirection with nothing to
+show for it.
+
+Reach for a Context **only** when the blueprint from Step 2 decomposes into several sibling
+components that must coordinate (e.g. a multi-step wizard, a shared "selected row" between a list
+and a submit bar) — i.e. state that a single component's own `useState` genuinely cannot hold
+because more than one sibling needs to read or change it. Follow the same `Context`/`Provider`/hook
+shape this project's components use elsewhere (see `useReadOnly`/`ReadOnlyProvider` and
+`useUser`/`UserProvider` for the two variants):
+
+```tsx
+// ReserveBikeContext.tsx — colocated in the SAME slice folder, never in src/lib
+import { createContext, useContext } from 'react';
+
+interface ReserveBikeContextType {
+  selectedBikeId: string | null;
+  selectBike: (bikeId: string) => void;
+}
+
+const ReserveBikeContext = createContext<ReserveBikeContextType | null>(null);
+
+export function ReserveBikeProvider({ children }: { children: React.ReactNode }) {
+  // ...state shared by this slice's sibling components...
+  return <ReserveBikeContext.Provider value={{ selectedBikeId, selectBike }}>{children}</ReserveBikeContext.Provider>;
+}
+
+export function useReserveBikeContext() {
+  const ctx = useContext(ReserveBikeContext);
+  if (!ctx) throw new Error('useReserveBikeContext must be used within ReserveBikeProvider');
+  return ctx;
+}
+```
+
+Throw when the context is missing (as above) — there is no sensible default for slice-scoped state,
+and failing fast surfaces a sub-component rendered outside its own slice's provider immediately.
+A plain default value (no throw) is only appropriate for a genuinely app-wide, always-available
+value — that belongs in `src/lib`, not here (see **Deletability** in `.build-kit/CLAUDE.md`).
+
+**File**: `src/slices/<contextSlug>/<laneSlug>/<sliceFolder>/<CommandTitle>Context.tsx` — colocated
+with the hook and component, never imported by another slice. The command's own `.tsx` file
+renders the `Provider` at its root, wrapping the sibling sub-components that call the context hook.
+
+## Step 6 — Compose onto the shared page, if this screen's name is shared
+
+A screen's **title is the page name**. The `html-screen` skill gives each slice its own copy of a
+shared visual screen — one node per slice, each with a different mark — so two slices whose
+screens carry the **same title** are meant to sit together on **one real page**, arranged exactly
+as their marks show. 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.
+
+1. Check whether any other slice references a screen with the same `title` as this slice's screen.
+   Search every context's local index, not just this slice's own:
+   ```bash
+   grep -l '"title": *"<ScreenTitle>"' .build-kit/.slices/*/index.json
+   ```
+   (Run `/load-slice` with no filter first if the board's other slices haven't been pulled locally
+   yet — this check is only as complete as what's on disk.)
+2. **No match** (this is the only slice on this screen so far): nothing further to do here — this
+   slice's component stands alone for now. A shared page gets created the first time a *second*
+   slice on the same screen is built.
+3. **Match found**: this screen is a shared page. Its composition lives at
+   `src/pages/<ScreenTitle>.tsx` (PascalCase, spaces stripped) — the **one place** in this codebase
+   allowed to import across slice folders; a slice component itself never does (see **Deletability**
+   in `.build-kit/CLAUDE.md`).
+   - Fetch the **whole, unmarked** page markup for this screen (every entry in `meta.pages`, from
+     Step 2) — this is the page-level layout blueprint, not just this slice's marked fragment.
+   - Translate it 1:1 into JSX, same rule as Step 3 — but at each position carrying a
+     `data-em-mark-id`, render that mark's owning slice's component instead of the mockup's static
+     content there, passing whatever props it declares. Only substitute positions whose slice
+     component already exists; leave any not-yet-built slice's marked area as the mockup's static
+     placeholder until that slice is built and this step runs again for it.
+   - The page owns threading shared inputs (route/query params, the current session, etc.) down as
+     props to each slice component — a slice component still only knows its own declared props, not
+     the rest of the page or its siblings.
+   - 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:
+- Every prop matches a `command.fields[]` entry exactly (name + type) — no invented or missing
+  fields.
+- The `postCommand` call uses `command.apiEndpoint` verbatim — or, when it was missing at build
+  time, the provisional `/api/mock/...` path noted in a comment (Step 1).
+- At least one numbered sample exists under this slice's `samples/` folder, shaped exactly like
+  this component's props.
+- If a screen was read in Step 2, the rendered JSX matches the marked (or whole, if unmarked)
+  HTML fragment structurally — no invented buttons/fields the mockup didn't show, nothing from
+  the mockup silently dropped.
+- Nothing in this slice's folder is imported from another slice's folder, and nothing outside this
+  slice's folder imports from it except `src/pages/` (Step 6) — deleting the folder should delete
+  the feature cleanly.
+
+## Quality gate
+
+Run `npm run build` (`tsc -b && vite build`) and `npm run lint` (`oxlint`) — both must pass clean.
+There is no component test runner configured in this stack yet; if a slice's `specifications[]`
+demand behavioral tests, flag that gap via `request-feedback` rather than inventing a test setup
+ad hoc.

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

@@ -0,0 +1,238 @@
+---
+name: build-state-view
+description: Build a read-side React slice for the Supabase stack — a component tailored to its READMODEL(s), reading its table/view through the shared api.ts (never Supabase directly), which is what lets it also be tested/previewed in isolation from numbered samples/sample-N.json files
+---
+
+# Build State View Slice
+
+> Before doing anything else, read the slice definition from
+> `.build-kit/.slices/<contextSlug>/<sliceFolder>/slice.json`. This file (plus, when a screen is
+> involved, the live screen node fetched in Step 2) is the **source of truth** for every field and
+> data source — never invent a field, prop, or table name that isn't there.
+
+---
+
+## What a State View Slice is
+
+One or more `READMODEL` elements (`slice.json.readmodels[]`) that display data back to the user.
+Read models here are **tailor-made for one component** — the default is a strict 1:1 correlation
+between a read model and the component that renders it. A single component may combine more than
+one read model (e.g. a dashboard-style screen), but the reverse — one read model reused by several
+different components — is rare; if the same read model turns up wired into more than one slice's
+screen, that's unusual enough to double-check rather than assume is intentional.
+
+This stack builds only the **frontend half**, and its read architecture is **direct table access,
+not a custom read API**: a read model is typically a real, persisted Postgres table (a projection
+the backend keeps up to date), protected by Row Level Security policies that already enforce which
+rows a given user may see. That RLS enforcement is exactly what makes it correct — not merely
+convenient — for a component to read it straight from Supabase, with no bespoke backend endpoint in
+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
+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.
+
+Assume a read model names a real persisted table unless its `comments[]`, `description`, or a
+custom prompt on the slice explicitly says otherwise (e.g. it's actually a view joining several
+tables, or computed on the fly) — check those before assuming a plain table lookup.
+
+## Step 1 — Read slice.json
+
+Extract:
+- **title**, **context** — slice identity, used for file paths (see Step 3).
+- **readmodels[]** — one entry per read model this slice's screen displays. Each `Element` carries:
+  - `title` — the read model's name, e.g. `"ActiveReservationView"`.
+  - `fields[]` — the exact and complete set of columns/values the component displays — no more,
+    no fewer.
+  - `apiEndpoint` — in this stack, **the Postgres table or view name to query**, not a REST path.
+    **Read it literally from slice.json when it's present** — never invent or guess a table name
+    while a real one exists. **When it's missing** (no table/view decided yet), flag it but keep
+    building — this is a partial variant of `request-feedback`, not a full stop:
+    1. Post a comment on this slice node naming the read model and stating the table/view is missing
+       (`mcp__eventmodelers__add_comment`, same call `request-feedback` Step 3 uses), and mark the
+       slice `Blocked` (`mcp__eventmodelers__update_slice_status`, same as `request-feedback` Step 4).
+    2. Unlike a normal `request-feedback` escalation, **do not stop here** — continue on to build the
+       component exactly as normal, but against a mocked read: give `queryReadModel` a clearly
+       provisional table name, e.g. `mock_<read_model_title_snake_case>`, with a one-line comment
+       marking it as a placeholder pending the real table/view. In mock mode `queryReadModel` never
+       touches Supabase regardless of the table name (see `src/lib/api.ts`), so the component is
+       fully functional offline either way — only make Step 4's samples do extra work in this case:
+       cover every `readmodel.fields[]` entry with realistic, meaningful values (never placeholders
+       like `"foo"`/`"test"`), plus whatever edge cases `specifications[]` call out, since those
+       samples are the only data this slice will see until a real table/view is wired in.
+    3. Leave the slice's status as `Blocked` when you finish (see this stack's `CLAUDE.md` "Building
+       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).
+- **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").
+
+> **Comments**: as in `build-state-change` — resolve consumed ones via the same node-comment
+> endpoint.
+
+## Step 2 — Read the screen, and especially its marks
+
+Identical to `build-state-change` Step 2 — fetch the live screen node
+(`mcp__eventmodelers__get_node`), find this slice's marked fragment in `meta.pages`/`meta.marks`
+(or the whole page if unmarked), and treat it as the blueprint. The same `learn-styleguide` note
+applies: prefer its tokens/classes over the mockup's ad hoc styling where they disagree.
+
+Also resolve this screen's lane the same way — `mcp__eventmodelers__get_board_outline` on the
+screen's chapter, match this node's `id` to get its `lane`, slugify it to `laneSlug` — skip only if
+`screens[]` was empty in Step 1.
+
+## Step 3 — Build the dedicated component
+
+**File**: `src/slices/<contextSlug>/<laneSlug>/<sliceFolder>/<ReadModelTitle>.tsx` (omit
+`<laneSlug>` only for the rare read model with no screen at all), `contextSlug`/`sliceFolder`/
+`laneSlug` derived exactly as in `build-state-change`. If a component genuinely combines more than
+one read model, name it after the screen/purpose rather than forcing one read model's title onto a
+multi-read-model component.
+
+**Markup**: same rule as `build-state-change` — translate the blueprint from Step 2 1:1 into JSX;
+the mockup is the design, not a starting point for a redesign.
+
+**Props**: whatever the component needs to *scope* its query (e.g. `customerId`) — passed in from
+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`:
+
+```tsx
+// ActiveReservationView.tsx
+import { useEffect, useState } from 'react';
+import { queryReadModel } from '../../../../lib/api'; // one less '../' if this read model has no lane segment
+
+export interface ActiveReservationViewProps {
+  customerId: string;
+}
+
+interface ActiveReservation {
+  status: string;
+  // ...remaining readmodel.fields[], typed per each Field.type
+}
+
+const samples = import.meta.glob<{ default: ActiveReservation }>('./samples/sample-*.json', { eager: true });
+const samplesByNumber = Object.fromEntries(
+  Object.entries(samples).map(([path, mod]) => [path.match(/sample-(\d+)\.json$/)![1], mod.default]),
+);
+
+export function ActiveReservationView({ customerId }: ActiveReservationViewProps) {
+  const [data, setData] = useState<ActiveReservation | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    queryReadModel<ActiveReservation>(
+      {
+        table: 'active_reservations', // readmodel.apiEndpoint, verbatim
+        select: 'status, ...', // every readmodel.fields[] name, by its actual column name — not '*'
+        filters: { customer_id: customerId },
+        single: true,
+      },
+      samplesByNumber,
+    )
+      .then((result) => {
+        if (cancelled) return;
+        setData(result);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        setError(err instanceof Error ? err.message : 'Something went wrong');
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [customerId]);
+
+  // ...JSX translated from the marked screen fragment. Render a sensible empty/background
+  // state for `data === null` (or `[]`), distinct from the loading and error states — a
+  // component must never assume data is always present...
+}
+```
+
+Select fields explicitly by name rather than `select('*')`. Map each field's `name` to its actual
+column name — check the paired backend stack's migrations if the naming convention (e.g. camelCase
+vs. snake_case) isn't obvious rather than guessing; if genuinely unclear, use `request-feedback`.
+
+Extract a `use<ReadModelTitle>.ts` hook, or introduce a colocated `<Name>Context.tsx`, under
+exactly the same conditions as `build-state-change` Steps 3-4 — only when genuinely warranted
+(logic reused by more than one sibling component, or state that must be shared across them). Don't
+reach for either by default; most read-model components are a query plus a render and need
+nothing more.
+
+## Step 4 — Add numbered samples
+
+Every read-model component ships a `samples/` folder colocated next to it:
+`src/slices/<contextSlug>/<laneSlug>/<sliceFolder>/samples/sample-<N>.json` (`sample-1.json`,
+`sample-2.json`, ...). Each file mimics **exactly the row shape `queryReadModel` returns** — the
+same field names/types as `readmodel.fields[]`, as a single object for `single: true` or an array
+otherwise; use `null`/`[]` for a sample meant to exercise the empty/background state.
+
+Add at least one sample (`sample-1.json`) covering the ordinary case from
+`readmodel.fields[].example` values; add more numbered ones for whatever other scenarios this
+read model's `specifications[]` call out (e.g. an empty result, a second customer's data). The
+same number across *different* components' `samples/` folders is meant to represent one coherent
+scenario across the whole app (e.g. every component's `sample-2.json` together tell the story of
+"a long-time customer") — keep that in mind when choosing what a given number represents, rather
+than numbering arbitrarily per component.
+
+No extra wiring is needed beyond the `import.meta.glob` shown in Step 3 — switching which sample is
+active for the *entire app* is just the `VITE_MOCK_SAMPLE` env var (see `.env.example`); this
+component doesn't do anything with that number itself, `queryReadModel` reads it internally.
+
+## 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
+of *distinct* screen titles across the board is a direct hint at how many pages this app needs, not
+one page per slice.
+
+1. Check whether any other slice references a screen with the same `title` as this slice's screen,
+   across every context's local index:
+   ```bash
+   grep -l '"title": *"<ScreenTitle>"' .build-kit/.slices/*/index.json
+   ```
+   (Run `/load-slice` with no filter first if the board's other slices haven't been pulled locally
+   yet.)
+2. **No match**: nothing further to do — this slice's component stands alone for now.
+3. **Match found**: this screen is a shared page, composed at `src/pages/<ScreenTitle>.tsx` — the
+   one place allowed to import across slice folders. Translate the screen's whole, unmarked
+   `meta.pages` markup into JSX (the page-level layout), and at each `data-em-mark-id` position
+   render that mark's owning slice's component (only for slices already built; leave the rest as
+   the mockup's static content until they are). The page threads shared inputs down as props; a
+   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
+
+- Every rendered field traces back to a `readmodel.fields[]` entry — no invented or missing
+  fields.
+- 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
+  slice.json.
+- At least one numbered sample exists under this slice's `samples/` folder, shaped exactly like
+  `queryReadModel`'s return value.
+- The component renders a sensible empty/background state, distinct from loading/error, when the
+  data is `null`/`[]`.
+- If a screen was read in Step 2, the rendered JSX matches the marked (or whole, if unmarked) HTML
+  fragment structurally.
+- Nothing in this slice's folder is imported from another slice's folder, and nothing outside it
+  imports from it except `src/pages/` (Step 5) — deleting the folder should delete the feature
+  cleanly.
+
+## Quality gate
+
+Run `npm run build` (`tsc -b && vite build`) and `npm run lint` (`oxlint`) — both must pass clean.
+There is no component test runner configured in this stack yet; if a slice's `specifications[]`
+demand behavioral tests, flag that gap via `request-feedback` rather than inventing a test setup
+ad hoc.

package/stacks/supabase-react/templates/.claude/skills/init-style-guide/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: init-style-guide
+description: Interview the user for CSS, design tokens, brand documents, or any existing style guide material, and persist it as references inside the learn-styleguide skill so UI-generating skills (build-state-change, build-state-view) stay on-brand
+---
+
+# Init Style Guide
+
+Run this whenever the user wants to give this project a design system to follow — "here's our
+style guide", "add our brand CSS", "use this doc for the UI" — or wants to add more material to
+one already started. This skill only collects and files material; it does not itself apply any
+styling to code.
+
+## Step 1 — Ask what they have
+
+Ask the user what they'd like to provide. Accept any of:
+- An existing CSS/SCSS file (a path) — design tokens, a component library stylesheet, a Tailwind
+  config, etc.
+- A brand/style guide document (Markdown, PDF, plain text, a Figma export, ...) — a path.
+- Pasted text/tokens directly in the conversation (e.g. a color palette, font stack, spacing
+  scale).
+- A URL to a live, publicly reachable style guide page — only if the user gives the URL
+  themselves; never search for or guess one.
+
+If they have nothing to add right now, stop — do not create empty placeholder files.
+
+## Step 2 — Persist each item as a reference, verbatim
+
+For every item provided, write it into `.claude/skills/learn-styleguide/references/`. **Never
+summarize, rewrite, or supplement** what was given — this is a store of source material, not an
+interpretation of it.
+
+- **A file path** → copy the file as-is into `references/<original-filename>`, preserving its
+  extension (`.css`, `.scss`, `.md`, `.pdf`, ...).
+- **A URL** → fetch it and save the raw content into `references/<slugified-title-or-host>.md`,
+  with a one-line header noting the source URL and the fetch date.
+- **Pasted text/tokens** → write into `references/<short-slug>.md`, wrapped in a fenced code block
+  when it's CSS/code, with a one-line header noting what it is and the date provided.
+
+Pick filenames that describe the content (`brand-colors.css`, `component-library.md`,
+`voice-and-tone.pdf`), never generic names like `input1`.
+
+If `references/` already has files from a previous run, list them back to the user first so they
+know what's already covered, then only add what's new. Never delete or overwrite an existing
+reference unless the user confirms that specific file should be replaced.
+
+## Step 3 — Refresh learn-styleguide's index
+
+In `.claude/skills/learn-styleguide/SKILL.md`, replace the `## References` section's contents with
+one bullet per file now in `references/` — filename plus a short (one-line) description of what it
+contains, based on a quick read of the file, never invented. Leave everything else in that file
+(frontmatter, the "How to use this skill" section) untouched.
+
+## Step 4 — Confirm
+
+Tell the user what was saved and where, e.g.:
+```
+Saved to .claude/skills/learn-styleguide/references/:
+  - brand-colors.css     (CSS custom properties: primary/secondary palette, spacing scale)
+  - voice-and-tone.md    (brand document — tone, terminology to avoid)
+```

package/stacks/supabase-react/templates/.claude/skills/learn-styleguide/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: learn-styleguide
+description: This project's visual style guide / design system reference material — read before generating or redesigning any UI (screens, components). Populated and kept up to date by the init-style-guide skill.
+---
+
+# Style Guide References
+
+## References
+
+_None yet — run `init-style-guide` to add CSS, design tokens, or brand documents._
+
+## How to use this skill
+
+Before turning a marked screen fragment into a component (`build-state-change`/`build-state-view`
+Step 2), or designing any new screen, read whichever file(s) under `references/` are relevant to
+the task at hand — colors/typography/spacing before styling, a component-library doc before
+choosing markup patterns, a voice-and-tone doc before writing copy.
+
+Prefer these references over values invented on the spot, and prefer them over an existing screen
+mockup's own ad hoc inline styles when the two disagree — the mockup gives structure and content,
+this skill gives the real visual language.
+
+Do not invent references that aren't listed above. If the current task needs a design decision
+these references don't cover, fall back to what the mockup/task already gives you rather than
+guessing a brand rule — or ask the user, if the choice materially affects business logic.
+
+This skill's content is entirely sourced from what the user provided via `init-style-guide` —
+never add, rewrite, or supplement it with invented material.

package/stacks/supabase-react/templates/.claude/skills/learn-styleguide/references/README.md

@@ -0,0 +1,5 @@
+# References
+
+Source material dropped here by `init-style-guide`, verbatim — CSS/SCSS files, brand or style
+guide documents, saved pages, or pasted design tokens. Each file is exactly what the user provided;
+nothing here is generated or summarized. See `../SKILL.md` for how these get used.