@eventmodelers/cli 1.0.154 → 1.0.155

package/README.md

@@ -202,7 +202,7 @@ and the agent starts building — `--local` skips platform config and credential
 
 **Backend → UI handover.** Besides the usual statuses a slice can be `Ready` (modeling done, waiting to be planned) and `Handover` (backend built, UI contract published, waiting for the UI kit). The flow is `Ready → Planned → InProgress → Handover → InProgress → Done`. Install with `init --handover` (or `re-init --handover`; switch later with `eventmodelers config --handover on|off`; for a single run `run --handover` overrides the setting without saving anything), which saves `"handover": true` in `.eventmodelers/config.json` — then a backend kit ends STATE_VIEW / STATE_CHANGE slices at `Handover` instead of `Done` (the `ui-contract` skill, Step 4, owns that rule); without the flag nothing changes: slices end at `Done`, exactly as before. A kit claims work from the status named in its `lib/kit.json` — `{ "pickupStatus": "Handover" }` for the `react` / `supabase-react` UI kits, absent (= `Planned`) for backend kits. A new UI kit ships that file and sets `Done` when its half is built; a new backend kit just invokes `ui-contract`. Needs a platform with the `Ready` / `Handover` statuses.
 
-**UI contract.** The scaffolded `build-state-view` / `build-state-change` skills already end by invoking the shared `ui-contract` skill, which publishes each slice's read (`GET`) or write (`POST`) contract as a `## UI Contract` section in the slice's feedback-lane markdown node (exported in `slice.json` `notes[]`, so a UI build kit can look it up directly). Two things are yours to decide: *where the contract is derived from* (point the `UI Contract` section of those skills at your stack's machine-readable API description, if it has one — the `node`/`supabase` stacks use their `@openapi` blocks via a `ui-contract-from-openapi.md` reference — otherwise the skill reads the route code), and, if you need a different shape or location, a whole-skill override: ship `.claude/skills/ui-contract/SKILL.md` in the stack's templates and it replaces the shared one (stack templates are applied after `shared/skills/`).
+**UI contract.** The scaffolded `build-state-view` / `build-state-change` skills already end by invoking the shared `ui-contract` skill, which publishes each slice's read (`GET`) or write (`POST`) contract — the endpoint's OpenAPI operation, as a ```` ```yaml ui-contract ```` block — as a `## UI Contract` section in the slice's feedback-lane markdown node (exported in `slice.json` `notes[]`, so a UI build kit can look it up directly). Two things are yours to decide: *where the contract is derived from* (point the `UI Contract` section of those skills at your stack's machine-readable API description, if it has one — the `node`/`supabase` stacks use their `@openapi` blocks via a `ui-contract-from-openapi.md` reference, taking the operation verbatim — otherwise the skill writes the equivalent OpenAPI operation from the route code), and, if you need a different shape or location, a whole-skill override: ship `.claude/skills/ui-contract/SKILL.md` in the stack's templates and it replaces the shared one (stack templates are applied after `shared/skills/`).
 
 Installing both a build stack and `init-modeling` into the same project reuses this one `.eventmodelers/config.json` — run whichever `init` command second and it finds the existing config already satisfies the required fields and skips straight past the credential prompt.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.154",
+  "version": "1.0.155",
   "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/ui-contract/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: ui-contract
-description: Publish the slice's UI contract (read contract = GET, write/state-change contract = POST) as its own `## UI Contract` section in the slice's MARKDOWN node in the feedback lane, which the slice export carries in `slice.json` `notes[]` — so the UI build kit finds the contract in one lookup instead of parsing the whole note. Called by every build-state-view / build-state-change skill after the endpoint is built. A build kit can override it by shipping its own `ui-contract` skill.
+description: Publish the slice's UI contract — the OpenAPI operation of its endpoint (read = GET, write/state-change = POST) — as its own `## UI Contract` section in the slice's MARKDOWN node in the feedback lane, which the slice export carries in `slice.json` `notes[]` — so the UI build kit finds the contract in one lookup instead of parsing the whole note. Called by every build-state-view / build-state-change skill after the endpoint is built. A build kit can override it by shipping its own `ui-contract` skill.
 ---
 
 # UI Contract
 
 The UI build kit builds the frontend against what the backend slice **actually exposes**. This skill
-records that as a contract — one per slice, in a fixed, machine-findable place.
+records that as a contract — the endpoint's **OpenAPI operation**, one per slice, in a fixed, machine-findable place.
 
 > Invoke `connect` first if not already connected (`BOARD_ID`). Prefer `mcp__eventmodelers__*` tools;
 > the REST equivalents are in `learn-eventmodelers-api`.
@@ -27,58 +27,24 @@ route, not the plan), before the final commit:
 | `STATE_CHANGE` (COMMAND) | **write** — `POST` (a state change) |
 | `AUTOMATION` | none — no UI counterpart, skip |
 
-## Step 1 — Derive the contract from the built endpoint
+## Step 1 — Derive the OpenAPI operation from the built endpoint
 
-Never copy from the plan — the contract describes what was built.
+Never copy from the plan — the contract describes what was built. The contract **is** the endpoint's
+OpenAPI 3 operation (one path, one verb) — no second, hand-made shape.
 
 1. **Use the source the stack names.** If the calling `build-state-view` / `build-state-change`
-   skill's `## UI Contract` section points to a more authoritative source for this stack (for example a
-   machine-readable API description it already maintains), derive from that, mechanically.
-2. **Otherwise read the endpoint's route/handler code**: method, path, parameter and field names,
-   success status, and the error codes/statuses the handler really returns.
-3. Field `type` / `optional` / `example` come from the `slice.json` element fields.
-4. **Cross-check against `slice.json`**: the `body` / `response.fields` names must equal the command's /
-   read model's `fields[]`. A mismatch is an implementation bug — fix the code, don't publish a
-   contract that disagrees with `slice.json`.
-
-**Read contract** (`kind: "read"`):
-
-```json
-{
-  "kind": "read",
-  "slice": "<slice title>",
-  "sliceId": "<SLICE_BORDER node id>",
-  "readModel": "<READMODEL title>",
-  "method": "GET",
-  "path": "/api/<...>",
-  "pathParams": [{ "name": "customerId", "type": "UUID" }],
-  "queryParams": [{ "name": "page", "type": "Int", "optional": true }],
-  "response": {
-    "cardinality": "Single | List",
-    "fields": [{ "name": "status", "type": "String", "optional": false, "example": "active" }]
-  },
-  "errors": [{ "status": 404, "code": "not_found", "when": "no row for this id" }]
-}
-```
-
-**Write contract** (`kind: "write"`):
-
-```json
-{
-  "kind": "write",
-  "slice": "<slice title>",
-  "sliceId": "<SLICE_BORDER node id>",
-  "command": "<COMMAND title>",
-  "method": "POST",
-  "path": "/api/<...>",
-  "pathParams": [],
-  "body": [{ "name": "itemId", "type": "UUID", "optional": false, "example": "..." }],
-  "response": { "status": 200, "body": [] },
-  "errors": [{ "status": 400, "code": "snake_case_code", "when": "business rule violated" }]
-}
-```
-
-Keep it to what a UI needs — no internal details (no table names, no auth plumbing beyond "requires bearer token" if `security` is set).
+   skill's `## UI Contract` section points to the stack's machine-readable API description (e.g. the
+   handler's `@openapi` block), take that operation **verbatim** — see the stack's
+   `ui-contract-from-openapi.md`. Do not rewrite it.
+2. **Otherwise read the endpoint's route/handler code** and write the equivalent OpenAPI operation:
+   method, path, `parameters` (path / query / header), `requestBody` schema, and a response for the
+   success status and for every error status the handler really returns.
+3. **Trim to what a UI needs**: drop `tags`, internal notes and anything about storage or auth plumbing
+   (keep `security` if set). Keep `summary`, `description`, parameter/field `example`s and the response
+   descriptions — they carry the business meaning of each error status.
+4. **Cross-check against `slice.json`**: the request-body / response property names must equal the
+   command's / read model's `fields[]` (path parameters such as the generated id excepted). A mismatch
+   is an implementation bug — fix the code, don't publish a contract that disagrees with `slice.json`.
 
 ## Step 2 — Write the `## UI Contract` section into the slice's MARKDOWN node
 
@@ -102,18 +68,27 @@ Keep it to what a UI needs — no internal details (no table names, no auth plum
 
 **READ** `GET /api/customers/{customerId}/reservation` — <one-line purpose>
 
-| Part | Name | Type | Optional | Example |
-|---|---|---|---|---|
-| path | customerId | UUID | no | … |
-| response | status | String | no | active |
-
-```json ui-contract
-{ ...the Step 1 JSON, verbatim... }
+```yaml ui-contract
+/api/customers/{customerId}/reservation:
+  get:
+    summary: ...
+    parameters: [...]
+    responses: {...}
 ```
 ````
 
-The table is for humans; the fenced block whose info string is `ui-contract` is the single
-machine-readable source. Both must say the same thing.
+`**READ**` for a `GET`, `**WRITE**` for a `POST`.
+
+**Formatting is part of the contract.** The note renders as Markdown, so `meta.description` must contain
+*real* line breaks — build the string with actual newlines (a multi-line string, or `\n` that the JSON
+parser turns into a newline), never a single line and never a literal backslash-`n` in the stored text.
+Blank line after the heading, blank line before and after the fenced block, the opening ```` ```yaml ui-contract ````
+and the closing ```` ``` ```` each on their own line, and the YAML keeps its indentation (2 spaces). After
+the write, read the node back once (`get_node`) and check that `description` has multiple lines and no
+literal `\n`; if it is flat, rewrite it before moving on.
+
+The fenced block whose info string is `ui-contract` is the single source: the operation alone, keyed by its path — no `openapi:`/`info:`/`servers:`
+wrapper, no restated table.
 
 ## Step 3 — Nothing else to write
 
@@ -140,8 +115,10 @@ runner resolves `run --handover` over the project setting), else `"handover": tr
 
 1. In the slice's `slice.json`, take the `notes[]` entry that contains a `## UI Contract` heading.
    Ignore every other entry.
-2. In that entry, take the fenced block whose info string is `ui-contract` (```` ```json ui-contract ````)
-   and parse just that JSON. Ignore the rest of the note.
+2. In that entry, take the fenced block whose info string is `ui-contract` (```` ```yaml ui-contract ````)
+   and parse just that YAML — an OpenAPI operation keyed by its path: request = path/verb +
+   `parameters` + `requestBody`, success = the 2xx `responses` entry, errors = every non-2xx entry.
+   Ignore the rest of the note.
 3. No such entry → the backend slice isn't built yet, or the slice wasn't re-fetched since; re-fetch
    once, and if still absent build against `slice.json` and note the assumption.
 

package/stacks/node/templates/.claude/skills/build-state-change/references/ui-contract-from-openapi.md

@@ -1,17 +1,13 @@
-# UI Contract — derive from the `@openapi` block
+# UI Contract — take the operation from the `@openapi` block
 
 Used by the `ui-contract` skill. This stack's `routes.ts` carries an `@openapi` JSDoc block above every
-handler (guarded by the `openapi-annotation` commit check), so derive the contract from it mechanically
-instead of re-reading handler logic.
+handler (guarded by the `openapi-annotation` commit check). The contract **is** that operation —
+publish it as is, don't translate it into another shape.
 
-| Contract key | OpenAPI source |
-|---|---|
-| `method` | the verb key under the path (`get` / `post`) |
-| `path` | the path key, verbatim (`{param}` style) |
-| `pathParams` / `queryParams` | `parameters[]` with `in: path` / `in: query` → `name`, `schema` (`optional` = not `required`) |
-| `body` (write) | `requestBody…schema.properties` |
-| `response.fields` (read) | the `200` response schema `properties` (follow a `$ref` to `components.schemas`); `Single` vs `List` = object vs `type: array` |
-| `response.status` (write) | the success response code |
-| `errors[]` | every non-2xx response: `status` = the key, `code` / `when` = its description / `error` example |
-| `type` | `string`+`uuid` → `UUID`, `integer`/`int32` → `Int`, `int64` → `Long`, `number`/`double` → `Double`, `number` → `Decimal`, `boolean` → `Boolean`, `date` / `date-time` → `Date` / `DateTime`, `object` → `Custom`, else `String` |
-| `example` | the schema's `example`, nothing invented |
+1. Take the YAML from the handler's `@openapi` block (strip the ` * ` comment prefix) — one path, one verb.
+2. Keep it keyed by its path (`/api/...:` → `get:`/`post:`), with `summary`, `description`, `parameters`,
+   `requestBody` and every `responses` entry. Follow a `$ref` into `components.schemas` and inline it, so
+   the operation is self-contained.
+3. Drop `tags` and anything internal. Add nothing the block doesn't say — examples come from the block.
+4. Write it as the ```` ```yaml ui-contract ```` block of the `## UI Contract` section, with real line
+   breaks and 2-space indentation (see the skill's formatting rule).

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

@@ -32,7 +32,7 @@ From the slice definition, extract:
 
 - **UI contract** — the backend slice's published write (`POST`) 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). It fixes the request: `path` (+ `pathParams`), the exact `body` fields, the success `response`, and `errors[]` (status + code) — surface each error code as its own user-facing state, not one generic failure. When absent, the backend slice isn't
+  `slice.json` `notes[]`, parse only its `ui-contract` block — an OpenAPI operation). It fixes the request: the path (+ path `parameters`), the exact `requestBody` properties, the 2xx `responses` entry, and every non-2xx response (status + description) — surface each error code as its own user-facing state, not one generic failure. When absent, the backend slice isn't
   built or re-fetched yet: build against `slice.json` and note the assumption in `progress.txt`.
 
 > **Comments & description**: each element carries a `comments: string[]` array (board comments) and a `description` field — use them as implementation hints, and resolve consumed comments via `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve`.

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

@@ -31,7 +31,7 @@ From the slice definition, extract:
 
 - **UI contract** — the backend slice's published read (`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). It fixes the request: `path` (+ `pathParams`/`queryParams`), the exact `response.fields` and `Single` vs `List` cardinality, and `errors[]` — render each error status as a distinct state. When absent, the backend slice isn't
+  `slice.json` `notes[]`, parse only its `ui-contract` block — an OpenAPI operation). It fixes the request: the path (+ path/query `parameters`), the exact 2xx response schema (object = `Single`, `type: array` = `List`), and every non-2xx response — render each error status as a distinct state. When absent, the backend slice isn't
   built or re-fetched yet: build against `slice.json` and note the assumption in `progress.txt`.
 
 > **Comments & description**: each element carries a `comments: string[]` array (board comments) and a `description` field — use them as implementation hints, and resolve consumed comments via `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve`.

package/stacks/supabase/templates/.claude/skills/build-state-change/references/ui-contract-from-openapi.md

@@ -1,17 +1,13 @@
-# UI Contract — derive from the `@openapi` block
+# UI Contract — take the operation from the `@openapi` block
 
 Used by the `ui-contract` skill. This stack's `routes.ts` carries an `@openapi` JSDoc block above every
-handler (guarded by the `openapi-annotation` commit check), so derive the contract from it mechanically
-instead of re-reading handler logic.
+handler (guarded by the `openapi-annotation` commit check). The contract **is** that operation —
+publish it as is, don't translate it into another shape.
 
-| Contract key | OpenAPI source |
-|---|---|
-| `method` | the verb key under the path (`get` / `post`) |
-| `path` | the path key, verbatim (`{param}` style) |
-| `pathParams` / `queryParams` | `parameters[]` with `in: path` / `in: query` → `name`, `schema` (`optional` = not `required`) |
-| `body` (write) | `requestBody…schema.properties` |
-| `response.fields` (read) | the `200` response schema `properties` (follow a `$ref` to `components.schemas`); `Single` vs `List` = object vs `type: array` |
-| `response.status` (write) | the success response code |
-| `errors[]` | every non-2xx response: `status` = the key, `code` / `when` = its description / `error` example |
-| `type` | `string`+`uuid` → `UUID`, `integer`/`int32` → `Int`, `int64` → `Long`, `number`/`double` → `Double`, `number` → `Decimal`, `boolean` → `Boolean`, `date` / `date-time` → `Date` / `DateTime`, `object` → `Custom`, else `String` |
-| `example` | the schema's `example`, nothing invented |
+1. Take the YAML from the handler's `@openapi` block (strip the ` * ` comment prefix) — one path, one verb.
+2. Keep it keyed by its path (`/api/...:` → `get:`/`post:`), with `summary`, `description`, `parameters`,
+   `requestBody` and every `responses` entry. Follow a `$ref` into `components.schemas` and inline it, so
+   the operation is self-contained.
+3. Drop `tags` and anything internal. Add nothing the block doesn't say — examples come from the block.
+4. Write it as the ```` ```yaml ui-contract ```` block of the `## UI Contract` section, with real line
+   breaks and 2-space indentation (see the skill's formatting rule).

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

@@ -56,9 +56,9 @@ Extract:
   - `description` — implementation hints (validation rules, business constraints).
 - **UI contract (write)** — the backend slice's published `POST` 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). When present it **overrides
-  `apiEndpoint`** and fixes everything the component must honour: `path` (+ `pathParams`), the exact
-  `body` fields, the success `response`, and `errors[]` (status + code) — surface each error code as a
+  `slice.json` `notes[]`; parse only its `ui-contract` block — an OpenAPI operation). When present it **overrides
+  `apiEndpoint`** and fixes everything the component must honour: the path (+ path `parameters`), the exact
+  `requestBody` properties, the 2xx `responses` entry, and every non-2xx response (status + description) — surface each error code as a
   distinct user-facing state through `onError`, not one generic failure. When absent, the backend slice
   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