@eventmodelers/cli 1.0.55 → 1.0.56

package/package.json

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

package/stacks/node/templates/.claude/skills/build-automation/SKILL.md

@@ -57,6 +57,9 @@ Follow the **build-state-change** skill to create:
 
 **Do NOT create a `routes.ts`** for automations — the command is fired internally by the processor, not via HTTP.
 
+**No `routes.ts` also means no OpenAPI block** — an automation has no HTTP surface, so it contributes nothing to `/api-docs` or `/swagger.json`. If the slice also defines a todo-list read model that is queried over HTTP, that endpoint belongs to **build-state-view**, and its `@openapi` annotation is required there (see that skill's Step 6a).
+
+
 Refer to the build-state-change skill for the full command handler structure.
 
 ### Storyline-derived tests
@@ -269,4 +272,5 @@ src/common/
 - [ ] Command data fields map exclusively from fields available on the trigger event per slice.json — no invented mappings
 - [ ] No filtering conditions were invented — all conditions come from slice.json `description` or `comments`
 - [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
-- [ ] If `storylines[]` is present, its command-handler segment was covered via build-state-change's storyline-derived tests (no separate reactor test needed)
+- [ ] If `storylines[]` is present, its command-handler segment was covered via build-state-change's storyline-derived tests (no separate reactor test needed)
+- [ ] No `routes.ts`, therefore no `@openapi` block — any todo-list read-model query endpoint is documented by build-state-view instead

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

@@ -244,7 +244,7 @@ Put these in their own `describe` block named after the storyline (same pattern
 
 File: `src/slices/{context}/{SliceName}/routes.ts`
 
-> **Concrete example**: `src/slices/example/routes.ts` — shows the full pattern with `requireUser`, `assertNotEmpty`, error mapping, and OpenAPI annotations. Read it before implementing.
+> **Pattern reference**: the template below is the full pattern — auth, error mapping, and the mandatory `@openapi` annotation (Step 5a). If the project already has slices under `src/slices/`, open one of their `routes.ts` files first and match it.
 
 ```typescript
 import {Request, Response, Router} from 'express';
@@ -254,6 +254,59 @@ import {{SliceName}Command, handle{SliceName}} from './{SliceName}Command';
 
 export const api = (): WebApiSetup => (router: Router): void => {
 
+    /**
+     * @openapi
+     * /api/{slicename}/{id}:
+     *   post:
+     *     tags: [{Context}]
+     *     summary: {slice title from slice.json}
+     *     description: {slice.json description — plus any comments that explain the endpoint}
+     *     security:
+     *       - bearerAuth: []
+     *     parameters:
+     *       - in: path
+     *         name: id
+     *         required: true
+     *         schema:
+     *           type: string
+     *         description: Stream id this command is applied to
+     *       - in: header
+     *         name: correlation_id
+     *         required: false
+     *         schema:
+     *           type: string
+     *     requestBody:
+     *       required: true
+     *       content:
+     *         application/json:
+     *           schema:
+     *             type: object
+     *             required: [{command fields without optional: true}]
+     *             properties:
+     *               {fieldName}:
+     *                 type: string
+     *                 example: {the field's own example from slice.json, if it has one}
+     *     responses:
+     *       '201':
+     *         description: Accepted — {EmittedEventName} appended
+     *         content:
+     *           application/json:
+     *             schema:
+     *               type: object
+     *               properties:
+     *                 ok:
+     *                   type: boolean
+     *                 next_expected_stream_version:
+     *                   type: string
+     *                 last_event_global_position:
+     *                   type: string
+     *       '401':
+     *         description: Not authenticated
+     *       '409':
+     *         description: {message errorMapping returns — one line per error code}
+     *       '500':
+     *         description: Server error
+     */
     router.post('/api/{slicename}/:id', async (req: Request, res: Response) => {
         const auth = await requireUser(req, res);
         if (auth.error) return;
@@ -306,6 +359,39 @@ const errorMapping = (code: string): string | null => {
 
 ---
 
+### Step 5a — OpenAPI annotation (required)
+
+`src/swagger.ts` builds the published OpenAPI document by scanning `./src/slices/**/routes.ts` for `@openapi` JSDoc blocks. A handler without one is **invisible** in Swagger UI (`/api-docs`) and in `/swagger.json` — the endpoint works, but nobody can find it. `src/swagger.ts` is shared infra and outside a slice's commit scope, so the block in this slice's own `routes.ts` is the only place the endpoint can be documented. The `openapi-annotation` commit check rejects a `routes.ts` whose handlers have no matching block.
+
+Everything in the block comes from slice.json — same rule as the code: no invented fields, no guessed types.
+
+| slice.json field `type` | OpenAPI schema |
+|---|---|
+| `String` | `type: string` |
+| `UUID` | `type: string`, `format: uuid` |
+| `Int` | `type: integer`, `format: int32` |
+| `Long` | `type: integer`, `format: int64` |
+| `Double` | `type: number`, `format: double` |
+| `Decimal` | `type: number` |
+| `Boolean` | `type: boolean` |
+| `Date` | `type: string`, `format: date` |
+| `DateTime` | `type: string`, `format: date-time` |
+| `Custom` | `type: object` |
+
+Mapping rules:
+
+- **path key** — the express path with `:param` rewritten as `{param}` (`/api/foo/:id` → `/api/foo/{id}`). If the two disagree, Swagger publishes a path that does not exist.
+- **tags** — `[{Context}]`, the slice's context, so every slice of one context groups under one heading.
+- **summary** — the slice title. **description** — slice.json `description`, plus any `comments[]` that explain what the endpoint does.
+- **requestBody properties** — exactly `commands[].fields`, minus the ones taken from the URL path or a header. Types from the table above.
+- **required** — every command field not marked `optional: true`.
+- **example** — only from the field's own `example` in slice.json. A field with no example gets no `example:` line; do not invent one.
+- **responses** — `'201'` with the body the handler actually returns; one `'409'` per error code in `errorMapping` (i.e. per failing specification); `'401'` whenever the handler enforces auth; `'500'`.
+
+A placeholder left unreplaced ships straight into the published spec, and `npm run build` will not catch it — open `/api-docs` and look at the rendered endpoint before marking the slice `Done`.
+
+---
+
 ## Step 6 — Wire up the route
 
 Find the application's router registration (usually `src/index.ts` or `src/app.ts`) and add:
@@ -353,4 +439,6 @@ Before marking this slice as `Done`, verify the implementation against slice.jso
 - [ ] Every entry in `specifications[]` maps to a test case in `{SliceName}.test.ts`
 - [ ] No business rules, defaults, or constraints were added that do not appear in slice.json `description` or `comments`
 - [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
-- [ ] If `storylines[]` is present, a storyline-derived test was added for every COMMAND beat matching this slice's command
+- [ ] If `storylines[]` is present, a storyline-derived test was added for every COMMAND beat matching this slice's command
+- [ ] `routes.ts` carries an `@openapi` JSDoc block above every handler, and its path key matches the registered route with `:param` written as `{param}`
+- [ ] The documented request body is exactly `commands[].fields`, and every error code in `errorMapping` has a `'409'` line — no undocumented fields, no invented ones

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

@@ -352,7 +352,7 @@ Skip a beat pair when a COMMAND beat sits in between (that half belongs to build
 
 File: `src/slices/{context}/{SliceName}/routes.ts`
 
-> **Concrete example**: `src/slices/example/routes.ts` — shows the full pattern with `requireUser`, `assertNotEmpty`, error mapping, and OpenAPI annotations. Read it before implementing.
+> **Pattern reference**: the template below is the full pattern — auth, error mapping, and the mandatory `@openapi` annotation (Step 6a). If the project already has slices under `src/slices/`, open one of their `routes.ts` files first and match it.
 
 ```typescript
 import {Request, Response, Router} from 'express';
@@ -364,6 +364,48 @@ import createClient from '../../../supabase/api';
 
 export const api = (): WebApiSetup => (router: Router): void => {
 
+    /**
+     * @openapi
+     * /api/query/{slicename}-collection:
+     *   get:
+     *     tags: [{Context}]
+     *     summary: {slice title from slice.json}
+     *     description: {slice.json description — what this read model answers}
+     *     security:
+     *       - bearerAuth: []
+     *     parameters:
+     *       - in: query
+     *         name: _id
+     *         required: false
+     *         schema:
+     *           type: string
+     *         description: When set, returns the single row with this id instead of the full collection
+     *     responses:
+     *       '200':
+     *         description: The {SliceName} read model
+     *         content:
+     *           application/json:
+     *             schema:
+     *               oneOf:
+     *                 - $ref: '#/components/schemas/{SliceName}ReadModel'
+     *                 - type: array
+     *                   items:
+     *                     $ref: '#/components/schemas/{SliceName}ReadModel'
+     *       '401':
+     *         description: Not authenticated
+     *       '500':
+     *         description: Server error
+     * components:
+     *   schemas:
+     *     {SliceName}ReadModel:
+     *       type: object
+     *       properties:
+     *         id:
+     *           type: string
+     *         {fieldName}:
+     *           type: string
+     *           example: {the field's own example from slice.json, if it has one}
+     */
     router.get('/api/query/{slicename}-collection', async (req: Request, res: Response) => {
         try {
             const principal = await requireUser(req, res, true);
@@ -394,6 +436,40 @@ export const api = (): WebApiSetup => (router: Router): void => {
 
 ---
 
+### Step 6a — OpenAPI annotation (required)
+
+`src/swagger.ts` builds the published OpenAPI document by scanning `./src/slices/**/routes.ts` for `@openapi` JSDoc blocks. A handler without one is **invisible** in Swagger UI (`/api-docs`) and in `/swagger.json` — the endpoint works, but nobody can find it. `src/swagger.ts` is shared infra and outside a slice's commit scope, so the block in this slice's own `routes.ts` is the only place the endpoint can be documented. The `openapi-annotation` commit check rejects a `routes.ts` whose handlers have no matching block.
+
+Everything in the block comes from slice.json — same rule as the code: no invented fields, no guessed types.
+
+| slice.json field `type` | OpenAPI schema |
+|---|---|
+| `String` | `type: string` |
+| `UUID` | `type: string`, `format: uuid` |
+| `Int` | `type: integer`, `format: int32` |
+| `Long` | `type: integer`, `format: int64` |
+| `Double` | `type: number`, `format: double` |
+| `Decimal` | `type: number` |
+| `Boolean` | `type: boolean` |
+| `Date` | `type: string`, `format: date` |
+| `DateTime` | `type: string`, `format: date-time` |
+| `Custom` | `type: object` |
+
+Mapping rules:
+
+- **path key** — the express path exactly as registered (a query read model has no path params; if you do add one, rewrite `:param` as `{param}`).
+- **tags** — `[{Context}]`, the slice's context, so every slice of one context groups under one heading.
+- **summary** — the slice title. **description** — slice.json `description`, plus any `comments[]` that explain what the read model answers.
+- **schema properties** — exactly the read model fields from slice.json, the same set as the migration columns and the `{SliceName}ReadModel` type. Keep the JSON field spelling the route returns, not the snake_case column name, when they differ.
+- **required** — omit it unless slice.json marks fields as mandatory; a projection row can legitimately be sparse.
+- **example** — only from the field's own `example` in slice.json. A field with no example gets no `example:` line; do not invent one.
+- **`components.schemas`** — declaring the read model once and `$ref`-ing it keeps the single-row and collection responses in sync. swagger-jsdoc merges the `components` block from every scanned file, so name the schema `{SliceName}ReadModel` to avoid colliding with another slice's.
+- **responses** — `'200'` with the shape above, `'401'` whenever the handler enforces auth, `'500'`.
+
+A placeholder left unreplaced ships straight into the published spec, and `npm run build` will not catch it — open `/api-docs` and look at the rendered endpoint before marking the slice `Done`.
+
+---
+
 ## Step 7 — Wire up the route
 
 Find the application's router registration (usually `src/index.ts` or `src/app.ts`) and add:
@@ -434,8 +510,10 @@ src/common/
 - [ ] No `db.destroy()` calls in `evolve()` — the projection never owns its own connection
 - [ ] Tests use `runFlywayMigrations()` to apply the real schema
 - [ ] One test scenario per specification in slice.json
-o- [ ] Every field in the read model definition in slice.json has a column in the migration and a field in the TypeScript type — no invented columns
+- [ ] Every field in the read model definition in slice.json has a column in the migration and a field in the TypeScript type — no invented columns
 - [ ] Every event type in `events[]` is listed in the projection's `canHandle` — no assumed events
 - [ ] No extra columns or fields were added beyond what slice.json defines
 - [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
-- [ ] If `storylines[]` is present, a storyline-derived test was added for every isolable read-model-chain transition (adjacent READMODEL beats with only EVENT beats between them)
+- [ ] If `storylines[]` is present, a storyline-derived test was added for every isolable read-model-chain transition (adjacent READMODEL beats with only EVENT beats between them)
+- [ ] `routes.ts` carries an `@openapi` JSDoc block above every handler, and its path key matches the registered route
+- [ ] The documented response schema lists exactly the read model fields from slice.json — same set as the migration columns and the `{SliceName}ReadModel` type

package/stacks/node/templates/build-kit/CLAUDE.md

@@ -20,7 +20,9 @@ Read Events in src/events to understand the global structure.
 3. Follow TypeScript best practices for type definitions and interfaces
 
 Only check src/slices/{slice}/*.ts, do not check subfolders unless explicitely tasked to.
-If not tasked explicitely to change routes, ignore routes*.ts
+If not tasked explicitely to change routes, ignore routes*.ts — except the `routes.ts` of the slice you are
+building: the build skill owns that file, and its `@openapi` block has to stay in step with the slice's
+fields (the `openapi-annotation` check blocks the commit otherwise).
 
 Ignore case for files and slices in prompts. "CartItems" slice is the same as "cartitems"
 
@@ -72,6 +74,9 @@ It loads every check under `.build-kit/lib/checks/` and rejects the commit if an
   `.build-kit/.slices/{context}/{slice}/slice.json`
 - **spec-coverage** — heuristic: the test file needs at least as many `it(...)` blocks as slice.json
   has `specifications[]` entries
+- **openapi-annotation** — every handler in a slice's `routes.ts` needs an `@openapi` JSDoc block
+  above it, keyed on the registered path (`:param` written as `{param}`); without it the endpoint
+  never reaches `/api-docs` or `/swagger.json`
 - **tsc-build** — `npx tsc --noEmit` must still pass
 
 If a commit is rejected, split it — commit the out-of-scope file separately from the slice work, or add

package/stacks/node/templates/build-kit/lib/checks/60-openapi-annotation.cjs

@@ -0,0 +1,72 @@
+'use strict';
+
+// Every HTTP handler in a slice's routes.ts must carry an `@openapi` JSDoc block
+// directly above it. src/swagger.ts builds the published OpenAPI document by
+// scanning ./src/slices/**/routes.ts for those blocks, so a handler without one
+// is a working endpoint that never appears in Swagger UI (/api-docs) or in
+// /swagger.json — and swagger.ts itself is shared infra a slice commit may not
+// touch, so the block in routes.ts is the only place the endpoint can be
+// documented. See the build-state-change / build-state-view SKILL.md files for
+// the block template and the slice.json -> OpenAPI field mapping.
+//
+// Heuristic, not an OpenAPI parser: it checks that a block exists between the
+// previous handler and this one, and that the block names this handler's own
+// path (express `:param` rewritten as `{param}`). An invalid schema, or a
+// placeholder left unreplaced, still slips through — the rendered /api-docs
+// page is the real check.
+
+const fs = require('fs');
+const path = require('path');
+
+const ROUTES_FILE = /^src\/slices\/[^/]+\/[^/]+\/routes\.ts$/;
+const ROUTE_CALL = /\brouter\s*\.\s*(get|post|put|patch|delete)\s*\(\s*(['"`])([^'"`]+)\2/g;
+const OPENAPI_BLOCK = /\/\*\*(?:[\s\S]*?)@openapi(?:[\s\S]*?)\*\//g;
+
+// /api/foo/:id -> /api/foo/{id}
+const toOpenApiPath = (p) => p.replace(/:([A-Za-z0-9_]+)/g, '{$1}');
+
+module.exports = {
+  name: 'openapi-annotation',
+  run(ctx) {
+    const violations = [];
+
+    for (const { path: p } of ctx.changes) {
+      if (!ROUTES_FILE.test(p)) continue;
+
+      let content;
+      try {
+        content = fs.readFileSync(path.join(ctx.repoRoot, p), 'utf8');
+      } catch {
+        continue; // deleted — nothing to check
+      }
+
+      ROUTE_CALL.lastIndex = 0;
+      let cursor = 0; // start of the text belonging to the handler being checked
+      let call;
+      while ((call = ROUTE_CALL.exec(content))) {
+        const [, method, , routePath] = call;
+        const preceding = content.slice(cursor, call.index);
+        cursor = ROUTE_CALL.lastIndex;
+
+        const blocks = preceding.match(OPENAPI_BLOCK) || [];
+        if (blocks.length === 0) {
+          violations.push({
+            path: p,
+            reason: `${method.toUpperCase()} ${routePath} has no @openapi JSDoc block above it — the endpoint would be missing from /api-docs and /swagger.json`,
+          });
+          continue;
+        }
+
+        const documented = toOpenApiPath(routePath);
+        if (!blocks[blocks.length - 1].includes(documented)) {
+          violations.push({
+            path: p,
+            reason: `the @openapi block above ${method.toUpperCase()} ${routePath} does not document "${documented}" — the path key must match the registered route, with express ":param" written as "{param}"`,
+          });
+        }
+      }
+    }
+
+    return violations;
+  },
+};

package/stacks/supabase/templates/.claude/skills/build-automation/SKILL.md

@@ -57,6 +57,9 @@ Follow the **build-state-change** skill to create:
 
 **Do NOT create a `routes.ts`** for automations — the command is fired internally by the processor, not via HTTP.
 
+**No `routes.ts` also means no OpenAPI block** — an automation has no HTTP surface, so it contributes nothing to `/api-docs` or `/swagger.json`. If the slice also defines a todo-list read model that is queried over HTTP, that endpoint belongs to **build-state-view**, and its `@openapi` annotation is required there (see that skill's Step 6a).
+
+
 Refer to the build-state-change skill for the full command handler structure.
 
 > **Storyline-derived tests**: if slice.json has a `storylines[]` array, build-state-change's Step 4b applies here too — treat the trigger EVENT beat as the "given" and the fired command's resulting EVENT beat(s) as "then", exactly as it would for an ordinary command-change slice. Skip silently if there's nothing relevant.
@@ -267,4 +270,5 @@ src/common/
 - [ ] Every processor in `processors[]` has a corresponding `processor.ts` implementation
 - [ ] Command data fields map exclusively from fields available on the trigger event per slice.json — no invented mappings
 - [ ] No filtering conditions were invented — all conditions come from slice.json `description` or `comments`
-- [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
+- [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
+- [ ] No `routes.ts`, therefore no `@openapi` block — any todo-list read-model query endpoint is documented by build-state-view instead

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

@@ -251,7 +251,7 @@ Skip (do not fabricate) a segment when the command beat has no immediately-follo
 
 File: `src/slices/{context}/{SliceName}/routes.ts`
 
-> **Concrete example**: `src/slices/example/routes.ts` — shows the full pattern with `requireUser`, `assertNotEmpty`, error mapping, and OpenAPI annotations. Read it before implementing.
+> **Pattern reference**: the template below is the full pattern — auth, error mapping, and the mandatory `@openapi` annotation (Step 5a). If the project already has slices under `src/slices/`, open one of their `routes.ts` files first and match it.
 
 ```typescript
 import {Request, Response, Router} from 'express';
@@ -261,6 +261,59 @@ import {{SliceName}Command, handle{SliceName}} from './{SliceName}Command';
 
 export const api = (): WebApiSetup => (router: Router): void => {
 
+    /**
+     * @openapi
+     * /api/{slicename}/{id}:
+     *   post:
+     *     tags: [{Context}]
+     *     summary: {slice title from slice.json}
+     *     description: {slice.json description — plus any comments that explain the endpoint}
+     *     security:
+     *       - bearerAuth: []
+     *     parameters:
+     *       - in: path
+     *         name: id
+     *         required: true
+     *         schema:
+     *           type: string
+     *         description: Stream id this command is applied to
+     *       - in: header
+     *         name: correlation_id
+     *         required: false
+     *         schema:
+     *           type: string
+     *     requestBody:
+     *       required: true
+     *       content:
+     *         application/json:
+     *           schema:
+     *             type: object
+     *             required: [{command fields without optional: true}]
+     *             properties:
+     *               {fieldName}:
+     *                 type: string
+     *                 example: {the field's own example from slice.json, if it has one}
+     *     responses:
+     *       '201':
+     *         description: Accepted — {EmittedEventName} appended
+     *         content:
+     *           application/json:
+     *             schema:
+     *               type: object
+     *               properties:
+     *                 ok:
+     *                   type: boolean
+     *                 next_expected_stream_version:
+     *                   type: string
+     *                 last_event_global_position:
+     *                   type: string
+     *       '401':
+     *         description: Not authenticated
+     *       '409':
+     *         description: {message errorMapping returns — one line per error code}
+     *       '500':
+     *         description: Server error
+     */
     router.post('/api/{slicename}/:id', async (req: Request, res: Response) => {
         const auth = await requireUser(req, res);
         if (auth.error) return;
@@ -313,6 +366,39 @@ const errorMapping = (code: string): string | null => {
 
 ---
 
+### Step 5a — OpenAPI annotation (required)
+
+`src/swagger.ts` builds the published OpenAPI document by scanning `./src/slices/**/routes.ts` for `@openapi` JSDoc blocks. A handler without one is **invisible** in Swagger UI (`/api-docs`) and in `/swagger.json` — the endpoint works, but nobody can find it. `src/swagger.ts` is shared infra and outside a slice's commit scope, so the block in this slice's own `routes.ts` is the only place the endpoint can be documented. The `openapi-annotation` commit check rejects a `routes.ts` whose handlers have no matching block.
+
+Everything in the block comes from slice.json — same rule as the code: no invented fields, no guessed types.
+
+| slice.json field `type` | OpenAPI schema |
+|---|---|
+| `String` | `type: string` |
+| `UUID` | `type: string`, `format: uuid` |
+| `Int` | `type: integer`, `format: int32` |
+| `Long` | `type: integer`, `format: int64` |
+| `Double` | `type: number`, `format: double` |
+| `Decimal` | `type: number` |
+| `Boolean` | `type: boolean` |
+| `Date` | `type: string`, `format: date` |
+| `DateTime` | `type: string`, `format: date-time` |
+| `Custom` | `type: object` |
+
+Mapping rules:
+
+- **path key** — the express path with `:param` rewritten as `{param}` (`/api/foo/:id` → `/api/foo/{id}`). If the two disagree, Swagger publishes a path that does not exist.
+- **tags** — `[{Context}]`, the slice's context, so every slice of one context groups under one heading.
+- **summary** — the slice title. **description** — slice.json `description`, plus any `comments[]` that explain what the endpoint does.
+- **requestBody properties** — exactly `commands[].fields`, minus the ones taken from the URL path or a header. Types from the table above.
+- **required** — every command field not marked `optional: true`.
+- **example** — only from the field's own `example` in slice.json. A field with no example gets no `example:` line; do not invent one.
+- **responses** — `'201'` with the body the handler actually returns; one `'409'` per error code in `errorMapping` (i.e. per failing specification); `'401'` whenever the handler enforces auth; `'500'`.
+
+A placeholder left unreplaced ships straight into the published spec, and `npm run build` will not catch it — open `/api-docs` and look at the rendered endpoint before marking the slice `Done`.
+
+---
+
 ## Step 6 — Wire up the route
 
 Find the application's router registration (usually `src/index.ts` or `src/app.ts`) and add:
@@ -360,4 +446,6 @@ Before marking this slice as `Done`, verify the implementation against slice.jso
 - [ ] Every entry in `specifications[]` maps to a test case in `{SliceName}.test.ts`
 - [ ] If `storylines[]` is present, each command-to-event transition relevant to this slice has a corresponding test (or a documented reason it was skipped)
 - [ ] No business rules, defaults, or constraints were added that do not appear in slice.json `description` or `comments`
-- [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
+- [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
+- [ ] `routes.ts` carries an `@openapi` JSDoc block above every handler, and its path key matches the registered route with `:param` written as `{param}`
+- [ ] The documented request body is exactly `commands[].fields`, and every error code in `errorMapping` has a `'409'` line — no undocumented fields, no invented ones

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

@@ -327,7 +327,7 @@ Skip (do not fabricate) a segment when:
 
 File: `src/slices/{context}/{SliceName}/routes.ts`
 
-> **Concrete example**: `src/slices/example/routes.ts` — shows the full pattern with `requireUser`, `assertNotEmpty`, error mapping, and OpenAPI annotations. Read it before implementing.
+> **Pattern reference**: the template below is the full pattern — auth, error mapping, and the mandatory `@openapi` annotation (Step 6a). If the project already has slices under `src/slices/`, open one of their `routes.ts` files first and match it.
 
 ```typescript
 import {Request, Response, Router} from 'express';
@@ -339,6 +339,48 @@ import createClient from '../../../supabase/api';
 
 export const api = (): WebApiSetup => (router: Router): void => {
 
+    /**
+     * @openapi
+     * /api/query/{slicename}-collection:
+     *   get:
+     *     tags: [{Context}]
+     *     summary: {slice title from slice.json}
+     *     description: {slice.json description — what this read model answers}
+     *     security:
+     *       - bearerAuth: []
+     *     parameters:
+     *       - in: query
+     *         name: _id
+     *         required: false
+     *         schema:
+     *           type: string
+     *         description: When set, returns the single row with this id instead of the full collection
+     *     responses:
+     *       '200':
+     *         description: The {SliceName} read model
+     *         content:
+     *           application/json:
+     *             schema:
+     *               oneOf:
+     *                 - $ref: '#/components/schemas/{SliceName}ReadModel'
+     *                 - type: array
+     *                   items:
+     *                     $ref: '#/components/schemas/{SliceName}ReadModel'
+     *       '401':
+     *         description: Not authenticated
+     *       '500':
+     *         description: Server error
+     * components:
+     *   schemas:
+     *     {SliceName}ReadModel:
+     *       type: object
+     *       properties:
+     *         id:
+     *           type: string
+     *         {fieldName}:
+     *           type: string
+     *           example: {the field's own example from slice.json, if it has one}
+     */
     router.get('/api/query/{slicename}-collection', async (req: Request, res: Response) => {
         try {
             const principal = await requireUser(req, res, true);
@@ -369,6 +411,40 @@ export const api = (): WebApiSetup => (router: Router): void => {
 
 ---
 
+### Step 6a — OpenAPI annotation (required)
+
+`src/swagger.ts` builds the published OpenAPI document by scanning `./src/slices/**/routes.ts` for `@openapi` JSDoc blocks. A handler without one is **invisible** in Swagger UI (`/api-docs`) and in `/swagger.json` — the endpoint works, but nobody can find it. `src/swagger.ts` is shared infra and outside a slice's commit scope, so the block in this slice's own `routes.ts` is the only place the endpoint can be documented. The `openapi-annotation` commit check rejects a `routes.ts` whose handlers have no matching block.
+
+Everything in the block comes from slice.json — same rule as the code: no invented fields, no guessed types.
+
+| slice.json field `type` | OpenAPI schema |
+|---|---|
+| `String` | `type: string` |
+| `UUID` | `type: string`, `format: uuid` |
+| `Int` | `type: integer`, `format: int32` |
+| `Long` | `type: integer`, `format: int64` |
+| `Double` | `type: number`, `format: double` |
+| `Decimal` | `type: number` |
+| `Boolean` | `type: boolean` |
+| `Date` | `type: string`, `format: date` |
+| `DateTime` | `type: string`, `format: date-time` |
+| `Custom` | `type: object` |
+
+Mapping rules:
+
+- **path key** — the express path exactly as registered (a query read model has no path params; if you do add one, rewrite `:param` as `{param}`).
+- **tags** — `[{Context}]`, the slice's context, so every slice of one context groups under one heading.
+- **summary** — the slice title. **description** — slice.json `description`, plus any `comments[]` that explain what the read model answers.
+- **schema properties** — exactly the read model fields from slice.json, the same set as the migration columns and the `{SliceName}ReadModel` type. Keep the JSON field spelling the route returns, not the snake_case column name, when they differ.
+- **required** — omit it unless slice.json marks fields as mandatory; a projection row can legitimately be sparse.
+- **example** — only from the field's own `example` in slice.json. A field with no example gets no `example:` line; do not invent one.
+- **`components.schemas`** — declaring the read model once and `$ref`-ing it keeps the single-row and collection responses in sync. swagger-jsdoc merges the `components` block from every scanned file, so name the schema `{SliceName}ReadModel` to avoid colliding with another slice's.
+- **responses** — `'200'` with the shape above, `'401'` whenever the handler enforces auth, `'500'`.
+
+A placeholder left unreplaced ships straight into the published spec, and `npm run build` will not catch it — open `/api-docs` and look at the rendered endpoint before marking the slice `Done`.
+
+---
+
 ## Step 7 — Wire up the route
 
 Find the application's router registration (usually `src/index.ts` or `src/app.ts`) and add:
@@ -412,4 +488,6 @@ src/common/
 - [ ] Every field in the read model definition in slice.json has a column in the migration and a field in the TypeScript type — no invented columns
 - [ ] Every event type in `events[]` is listed in the projection's `canHandle` — no assumed events
 - [ ] No extra columns or fields were added beyond what slice.json defines
-- [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
+- [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
+- [ ] `routes.ts` carries an `@openapi` JSDoc block above every handler, and its path key matches the registered route
+- [ ] The documented response schema lists exactly the read model fields from slice.json — same set as the migration columns and the `{SliceName}ReadModel` type

package/stacks/supabase/templates/.claude/skills/build-webhook/SKILL.md

@@ -182,6 +182,48 @@ async function handle{SliceName}(id: string, command: {SliceName}Command) {
 
 console.info('{function-name} started');
 
+/**
+ * @openapi
+ * /functions/v1/{function-name}:
+ *   post:
+ *     tags: [{Context}]
+ *     summary: {slice title from slice.json}
+ *     description: {slice.json description — which external system calls this, and when}
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [{command fields without optional: true}]
+ *             properties:
+ *               id:
+ *                 type: string
+ *                 description: Aggregate id — generated when the caller omits it
+ *               {fieldName}:
+ *                 type: string
+ *                 example: {the field's own example from slice.json, if it has one}
+ *     responses:
+ *       '201':
+ *         description: Accepted — {EventName} appended
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *                 id:
+ *                   type: string
+ *                 nextExpectedStreamVersion:
+ *                   type: string
+ *                 lastEventGlobalPosition:
+ *                   type: string
+ *       '409':
+ *         description: {message thrown by decide — one line per error code}
+ *       '500':
+ *         description: Internal server error
+ */
 export default {
     fetch: withSupabase({auth: ['publishable', 'secret']}, async (req, _ctx) => {
         try {
@@ -233,6 +275,35 @@ export default {
 
 ---
 
+### Step 3a — OpenAPI annotation (required)
+
+`src/swagger.ts` scans `./supabase/functions/**/index.ts` alongside the express routes, so the webhook shows up in Swagger UI (`/api-docs`) and `/swagger.json` next to the rest of the API — but only if the function carries an `@openapi` JSDoc block. Without one the endpoint is undocumented, which matters more here than anywhere else: a webhook's only consumer is an external system whose integrator cannot read this codebase.
+
+The block goes directly above the `export default {` handler (as shown in the template above). Everything in it comes from slice.json.
+
+| slice.json field `type` | OpenAPI schema |
+|---|---|
+| `String` | `type: string` |
+| `UUID` | `type: string`, `format: uuid` |
+| `Int` | `type: integer`, `format: int32` |
+| `Long` | `type: integer`, `format: int64` |
+| `Double` | `type: number`, `format: double` |
+| `Decimal` | `type: number` |
+| `Boolean` | `type: boolean` |
+| `Date` | `type: string`, `format: date` |
+| `DateTime` | `type: string`, `format: date-time` |
+| `Custom` | `type: object` |
+
+Mapping rules:
+
+- **path key** — `/functions/v1/{function-name}`, the deployed URL, not the file path.
+- **requestBody properties** — exactly the `{SliceName}Payload` fields, which are exactly `commands[].fields`. **required** — every one not marked `optional: true` (never `id`, which the handler generates when absent).
+- **responses** — `'201'` with the body the handler returns; one `'409'` per error code thrown in `decide`; `'500'`.
+- **security** — a `verify_jwt = false` webhook takes no bearer token, so omit the `security:` block. When the function verifies a provider signature header instead (Stripe et al.), document that header under `parameters:` so the integrator knows to send it.
+- `example` only from the field's own `example` in slice.json; never invent one.
+
+---
+
 ## Step 4 — Verify event store schema migration
 
 The Emmett schema must be migrated before the edge function can write events. This happens once in the **backend startup**. Confirm that `src/common/loadPostgresEventstore.ts` calls `schema.migrate()`:
@@ -286,6 +357,8 @@ curl -i -X POST http://localhost:54321/functions/v1/{function-name} \
 - [ ] `supabase/config.toml` entry added with correct `verify_jwt` setting
 - [ ] `schema.migrate()` confirmed in backend startup (or run manually)
 - [ ] Local test with `supabase functions serve` passes
+- [ ] An `@openapi` block sits above the `export default` handler, keyed on `/functions/v1/{function-name}`
+- [ ] The documented request body is exactly the `{SliceName}Payload` fields, and every error code thrown in `decide` has a `'409'` line
 
 ---
 

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

@@ -20,7 +20,9 @@ Read Events in src/events to understand the global structure.
 3. Follow TypeScript best practices for type definitions and interfaces
 
 Only check src/slices/{slice}/*.ts, do not check subfolders unless explicitely tasked to.
-If not tasked explicitely to change routes, ignore routes*.ts
+If not tasked explicitely to change routes, ignore routes*.ts — except the `routes.ts` of the slice you are
+building: the build skill owns that file, and its `@openapi` block has to stay in step with the slice's
+fields (the `openapi-annotation` check blocks the commit otherwise).
 
 Ignore case for files and slices in prompts. "CartItems" slice is the same as "cartitems"
 
@@ -76,6 +78,9 @@ and rejects the commit if any of them find a problem:
   `.build-kit/.slices/{context}/{slice}/slice.json`
 - **spec-coverage** — heuristic: the test file needs at least as many `it(...)` blocks as slice.json
   has `specifications[]` entries
+- **openapi-annotation** — every handler in a slice's `routes.ts` needs an `@openapi` JSDoc block
+  above it, keyed on the registered path (`:param` written as `{param}`); without it the endpoint
+  never reaches `/api-docs` or `/swagger.json`
 - **tsc-build** — `npx tsc --noEmit` must still pass
 
 If a commit is rejected, split it — commit the out-of-scope file separately from the slice work, or add

package/stacks/supabase/templates/build-kit/lib/checks/60-openapi-annotation.cjs

@@ -0,0 +1,72 @@
+'use strict';
+
+// Every HTTP handler in a slice's routes.ts must carry an `@openapi` JSDoc block
+// directly above it. src/swagger.ts builds the published OpenAPI document by
+// scanning ./src/slices/**/routes.ts for those blocks, so a handler without one
+// is a working endpoint that never appears in Swagger UI (/api-docs) or in
+// /swagger.json — and swagger.ts itself is shared infra a slice commit may not
+// touch, so the block in routes.ts is the only place the endpoint can be
+// documented. See the build-state-change / build-state-view SKILL.md files for
+// the block template and the slice.json -> OpenAPI field mapping.
+//
+// Heuristic, not an OpenAPI parser: it checks that a block exists between the
+// previous handler and this one, and that the block names this handler's own
+// path (express `:param` rewritten as `{param}`). An invalid schema, or a
+// placeholder left unreplaced, still slips through — the rendered /api-docs
+// page is the real check.
+
+const fs = require('fs');
+const path = require('path');
+
+const ROUTES_FILE = /^src\/slices\/[^/]+\/[^/]+\/routes\.ts$/;
+const ROUTE_CALL = /\brouter\s*\.\s*(get|post|put|patch|delete)\s*\(\s*(['"`])([^'"`]+)\2/g;
+const OPENAPI_BLOCK = /\/\*\*(?:[\s\S]*?)@openapi(?:[\s\S]*?)\*\//g;
+
+// /api/foo/:id -> /api/foo/{id}
+const toOpenApiPath = (p) => p.replace(/:([A-Za-z0-9_]+)/g, '{$1}');
+
+module.exports = {
+  name: 'openapi-annotation',
+  run(ctx) {
+    const violations = [];
+
+    for (const { path: p } of ctx.changes) {
+      if (!ROUTES_FILE.test(p)) continue;
+
+      let content;
+      try {
+        content = fs.readFileSync(path.join(ctx.repoRoot, p), 'utf8');
+      } catch {
+        continue; // deleted — nothing to check
+      }
+
+      ROUTE_CALL.lastIndex = 0;
+      let cursor = 0; // start of the text belonging to the handler being checked
+      let call;
+      while ((call = ROUTE_CALL.exec(content))) {
+        const [, method, , routePath] = call;
+        const preceding = content.slice(cursor, call.index);
+        cursor = ROUTE_CALL.lastIndex;
+
+        const blocks = preceding.match(OPENAPI_BLOCK) || [];
+        if (blocks.length === 0) {
+          violations.push({
+            path: p,
+            reason: `${method.toUpperCase()} ${routePath} has no @openapi JSDoc block above it — the endpoint would be missing from /api-docs and /swagger.json`,
+          });
+          continue;
+        }
+
+        const documented = toOpenApiPath(routePath);
+        if (!blocks[blocks.length - 1].includes(documented)) {
+          violations.push({
+            path: p,
+            reason: `the @openapi block above ${method.toUpperCase()} ${routePath} does not document "${documented}" — the path key must match the registered route, with express ":param" written as "{param}"`,
+          });
+        }
+      }
+    }
+
+    return violations;
+  },
+};

package/stacks/supabase/templates/root/src/swagger.ts

@@ -28,7 +28,9 @@ const options = {
             },
         },
     },
-    apis: ['./src/slices/**/routes.ts'],
+    // Edge functions carry their own @openapi blocks (see the build-webhook skill),
+    // so a webhook shows up in the same document as the express routes.
+    apis: ['./src/slices/**/routes.ts', './supabase/functions/**/index.ts'],
 };
 
 export const specs = swaggerJsdoc(options);