@eventmodelers/cli 0.0.39 → 1.0.1

package/stacks/modeling-kit/templates/.claude/skills/place-element/SKILL.md

@@ -5,7 +5,9 @@ description: Place a COMMAND, READMODEL, EVENT, SCREEN, AUTOMATION, or SCENARIO
 
 # Place Element
 
-> **Before doing anything else**, invoke the `connect` skill to resolve `TOKEN`, `BOARD_ID`, and `BASE_URL`. Then invoke the `learn-eventmodelers-api` skill to load the full API reference. Do not proceed until both skills have been loaded.
+> **Before doing anything else**, invoke the `connect` skill — if not already connected — to resolve `TOKEN`, `BOARD_ID`, and `BASE_URL`. Do not proceed until it has completed. Consult `learn-eventmodelers-api` only if you need to look up a specific endpoint or field this file doesn't cover — don't load it eagerly.
+
+Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect` skill) — the curl blocks below are the fallback for sessions without MCP connected.
 
 Place a single element — COMMAND, READMODEL, EVENT, SCREEN, AUTOMATION, or SCENARIO spec node — onto an existing timeline on an eventmodelers board. Uses an existing column when a position is given; only creates a new column when appending.
 ---
@@ -34,8 +36,36 @@ Use `BOARD_ID` and `BASE_URL` from the `connect` skill. If a `boardId` argument
 
 ---
 
+## Prefer MCP — `place_element` (COMMAND / READMODEL / EVENT only)
+
+**When `elementType` is `COMMAND`, `READMODEL`, or `EVENT` and `position` is either omitted or a plain numeric column index** (not `"after <title>"`, not an explicit `cellName`), skip Steps 2–7b entirely and make one call:
+
+```
+mcp__eventmodelers__place_element {
+  "boardId": "<BOARD_ID>",
+  "timelineId": "<TIMELINE_ID>",
+  "elementType": "<COMMAND|READMODEL|EVENT>",
+  "title": "<title>",
+  "columnIndex": <position, if given>
+}
+```
+
+This tool finds or creates an empty cell in the correct lane and places the node in one call — it collapses the "resolve timeline → fetch columns → determine lane → check occupancy → create node" sequence (Steps 2–3, 4, 6, 7b below) into a single round trip. If `timelineId` is unknown, resolve it first via Step 2's MCP call. Go straight to Step 8 once it returns.
+
+**This does not cover**: `SCREEN`/`AUTOMATION`/`SCENARIO` (see their dedicated steps below), the `"after <title>"` position form, or an explicit `cellName` fast path (Step 1) — `place_element` has no way to express either. For those cases, or when MCP isn't connected, fall through to the manual steps below.
+
+---
+
 ## Step 2 — Resolve the timeline
 
+**Prefer MCP:**
+
+```
+mcp__eventmodelers__get_nodes { "boardId": "<BOARD_ID>", "type": "CHAPTER" }
+```
+
+**Fallback (no MCP):**
+
 If `timelineId` is not provided, discover chapters on the board:
 
 ```bash
@@ -50,7 +80,15 @@ curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=CHAPTER"
 
 ## Step 3 — Fetch existing columns and resolve position
 
-Always fetch the chapter node first to get the current timeline state:
+Always fetch the chapter node first to get the current timeline state.
+
+**Prefer MCP:**
+
+```
+mcp__eventmodelers__get_node { "boardId": "<BOARD_ID>", "nodeId": "<TIMELINE_ID>" }
+```
+
+**Fallback (no MCP):**
 
 ```bash
 curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$TIMELINE_ID"
@@ -91,6 +129,21 @@ The `/scenarios` endpoint creates the SCENARIO spec node automatically if the sp
 
 After resolving `columnId` (from step 3, or from step 5 if a new column was just created), call:
 
+**Prefer MCP:**
+
+```
+mcp__eventmodelers__add_scenario {
+  "boardId": "<BOARD_ID>",
+  "timelineId": "<TL>",
+  "columnId": "<COL>",
+  "scenarios": [ /* same scenario objects as the curl body below */ ]
+}
+```
+
+Same rules apply (given=EVENTs only, when=at most one COMMAND or QUERY, then=EVENTs only or exactly one READMODEL, `expectError`+`errorDescription` for error cases). This auto-creates the spec node if the cell is empty, same as the curl endpoint.
+
+**Fallback (no MCP):**
+
 ```bash
 curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$TL/columns/$COL/scenarios" \
   -H "x-token: $TOKEN" -H "Content-Type: application/json" \
@@ -150,7 +203,15 @@ Once `/scenarios` returns `201`, proceed directly to **Step 8** — report back
 
 **Skip this step entirely** when `columnId` was already resolved in Step 3 (i.e. the user targeted an existing column).
 
-Only run this when position was omitted (append mode):
+Only run this when position was omitted (append mode).
+
+**Prefer MCP:**
+
+```
+mcp__eventmodelers__add_column { "boardId": "<BOARD_ID>", "timelineId": "<TIMELINE_ID>" }
+```
+
+**Fallback (no MCP):**
 
 ```bash
 curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$TIMELINE_ID/columns" \
@@ -176,7 +237,11 @@ Using the `timelineData` already fetched in Step 3 (re-fetch if a column was jus
 
 Cell IDs are always `<rowId>-<columnId>` — no cell array search needed.
 
-**Check if the cell is already occupied**: query nodes in that cell:
+**Check if the cell is already occupied.**
+
+**No direct MCP equivalent**: `get_nodes` only filters by `type`, not `cellId` — there is no MCP tool that filters nodes by cell. Instead, use the `meta.timelineData.cells` you already fetched in Step 3 via `get_node` on the chapter/timeline node: `cells` is a sparse array, so a `nodeId` absent from the entry for `CELL_ID` means the cell is empty. Only fall back to the curl call below if you haven't already loaded `timelineData` (e.g. MCP wasn't used in Step 3 either):
+
+**Fallback (no MCP):**
 
 ```bash
 curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?cellId=$CELL_ID"
@@ -193,6 +258,14 @@ curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?cellId=$CELL_ID"
 
 **Insert immediately after** means: create the new column with `index = currentColumnIndex + 1`, not by appending to the end. This keeps the read model visually adjacent to the event that drives it.
 
+**Prefer MCP:**
+
+```
+mcp__eventmodelers__add_column { "boardId": "<BOARD_ID>", "timelineId": "<TIMELINE_ID>", "index": <currentColumnIndex + 1> }
+```
+
+**Fallback (no MCP):**
+
 ```bash
 curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$TIMELINE_ID/columns" \
   -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: agent" \
@@ -208,7 +281,56 @@ If no matching row is found, stop and report the error — the timeline may be m
 
 ### Step 7a — SCREEN only: create and render in one atomic call
 
-**Only applies when `elementType === "SCREEN"`.** Do not create the node via `/nodes/events` first and render the sketch onto it in a second call — that leaves a window where the node exists with no image (an empty "Board Image" placeholder if anything interrupts between the two calls). Design the sketch elements first (same grid language as `storyboard-screen`), then send a single call that creates the node, places it, and renders the sketch together:
+**Only applies when `elementType === "SCREEN"`.** Do not create the node via `/nodes/events` first and render its content onto it in a second call — that leaves a window where the node exists with no image (an empty "Board Image" placeholder if anything interrupts between the two calls). Send a single call that creates the node, places it, and renders it together.
+
+**Default — HTML (`contentType: "html"`, HTML_SCREEN node):** design the page(s) as real HTML/CSS (see the `html-screen` skill's page-design guidance).
+
+**Prefer MCP:**
+
+```
+mcp__eventmodelers__create_screen {
+  "boardId": "<BOARD_ID>",
+  "contentType": "html",
+  "nodeId": "<node-uuid>",
+  "chapterId": "<TIMELINE_ID>",
+  "cellId": "<CELL_ID>",
+  "pages": ["<div>...</div>"],
+  "description": "<title — what this screen shows>"
+}
+```
+
+**Fallback (no MCP):**
+
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/html-screen-nodes/<node-uuid>" \
+  -H "x-token: $TOKEN" \
+  -H "x-board-id: $BOARD_ID" \
+  -H "x-user-id: agent" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "chapterId": "<TIMELINE_ID>",
+    "cellId": "<CELL_ID>",
+    "pages": ["<div>...</div>"]
+  }'
+```
+
+**Sketch path (explicit request only) — `contentType: "sketch"`, plain SCREEN node:** only use this when the user explicitly asked for a "sketch"/"wireframe"/"low-fidelity mockup". Design the sketch elements first (same grid language as `storyboard-screen`):
+
+**Prefer MCP:**
+
+```
+mcp__eventmodelers__create_screen {
+  "boardId": "<BOARD_ID>",
+  "contentType": "sketch",
+  "nodeId": "<node-uuid>",
+  "chapterId": "<TIMELINE_ID>",
+  "cellId": "<CELL_ID>",
+  "elements": [...],
+  "description": "<title — what this screen shows>"
+}
+```
+
+**Fallback (no MCP):**
 
 ```bash
 curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/image-nodes/<node-uuid>/sketch" \
@@ -224,14 +346,36 @@ curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/image-nodes/<node-uu
   }'
 ```
 
-Pass whichever cell reference you already resolved — `CELL_ID` from Step 6, or `CELL_NAME` from Step 1's fast path (the endpoint accepts either `cellId` or `cellName` field). Expect `204`. On `400`, read the validation error, fix the payload, and retry once. Then skip the rest of Step 7 and go to Step 8.
+Pass whichever cell reference you already resolved — `CELL_ID` from Step 6, or `CELL_NAME` from Step 1's fast path (either path accepts `cellId` or `cellName`). Expect success (MCP: `created: true`; curl: `204`). On failure, read the validation error, fix the payload, and retry once. Then skip the rest of Step 7 and go to Step 8.
 
 ### Step 7b — All other element types
 
 Include `x-token`, `x-board-id`, and `x-user-id: agent` on every call to `/nodes/events`.
 
+This step applies to `SCREEN` (view/output conflict case), `AUTOMATION`, `SCENARIO`-adjacent cleanup, and to `COMMAND`/`READMODEL`/`EVENT` whenever the "Prefer MCP — `place_element`" fast path above doesn't apply (explicit `cellName`, `"after <title>"` positioning, or conflict-insertion cases resolved manually in Step 6).
+
 **Normal path** (position/lane resolved manually in Steps 3–6) — use `cellId`:
 
+**Prefer MCP:**
+
+```
+mcp__eventmodelers__submit_node_events {
+  "boardId": "<BOARD_ID>",
+  "events": [{
+    "eventType": "node:created",
+    "nodeId": "<node-uuid>",
+    "boardId": "<BOARD_ID>",
+    "timestamp": <Date.now()>,
+    "chapterId": "<TIMELINE_ID>",
+    "cellId": "<CELL_ID>",
+    "meta": { "type": "<ELEMENT_TYPE>", "title": "<title>" },
+    "node": { "data": { "title": "<title>" } }
+  }]
+}
+```
+
+**Fallback (no MCP):**
+
 ```bash
 curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
   -H "x-token: $TOKEN" \
@@ -255,6 +399,26 @@ curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
 
 **Fast path** (`cellName` given directly, e.g. `"A2"` — see the Step 1 shortcut) — pass `cellName` instead of `cellId` and let the backend resolve it; nothing else in the payload changes:
 
+**Prefer MCP:**
+
+```
+mcp__eventmodelers__submit_node_events {
+  "boardId": "<BOARD_ID>",
+  "events": [{
+    "eventType": "node:created",
+    "nodeId": "<node-uuid>",
+    "boardId": "<BOARD_ID>",
+    "timestamp": <Date.now()>,
+    "chapterId": "<TIMELINE_ID>",
+    "cellName": "<CELL_NAME>",
+    "meta": { "type": "<ELEMENT_TYPE>", "title": "<title>" },
+    "node": { "data": { "title": "<title>" } }
+  }]
+}
+```
+
+**Fallback (no MCP):**
+
 ```bash
 curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
   -H "x-token: $TOKEN" \
@@ -304,6 +468,8 @@ Timeline: <timelineId>
 
 ## Example — place an EVENT via curl
 
+**This whole example is the curl fallback.** With MCP connected, the same result is one call: `mcp__eventmodelers__place_element { "boardId": "<BOARD_ID>", "timelineId": "<TIMELINE_ID>", "elementType": "EVENT", "title": "Order Placed" }` (see "Prefer MCP" above).
+
 Full working example placing an EVENT called "Order Placed" at the end of a timeline:
 
 ```bash

package/stacks/modeling-kit/templates/.claude/skills/storyboard/SKILL.md

@@ -1,13 +1,17 @@
 ---
 name: storyboard
-description: Build a complete visual storyboard with AI-generated screens from a natural language description — creates a chapter, N columns, and N custom sketch screens
+description: Build a complete visual storyboard with AI-generated screens from a natural language description — creates a chapter, N columns, and N custom HTML screens (wireframe sketches only if explicitly requested)
 ---
 
 # Storyboard Builder
 
-> **Before doing anything else**, invoke the `connect` skill to resolve `TOKEN`, `BOARD_ID`, and `BASE_URL`. Do not proceed until the connect skill has completed.
+> **Before doing anything else**, invoke the `connect` skill — if not already connected — to resolve `TOKEN`, `BOARD_ID`, and `BASE_URL`. Do not proceed until the connect skill has completed.
 
-You are building a complete visual storyboard by calling the board HTTP API. You generate the screen designs yourself using the grid description language below, then create the storyboard structure via `curl`. Only SCREEN nodes are created — no COMMAND or EVENT nodes.
+Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect` skill) — the curl blocks below are the fallback for sessions without MCP connected.
+
+> **HTML is the default content type**: every screen this skill creates is a real HTML/CSS mockup (`contentType: "html"`, HTML_SCREEN node) unless the user's request explicitly asks for a "sketch", "wireframe", or "low-fidelity mockup" — only then does a screen use the sketch path (`contentType: "sketch"`, plain SCREEN node) described under "Sketch path (explicit request only)" below. Decide this once per storyboard, before Step 2 — do not mix content types across screens in the same storyboard unless the user asked for that mix.
+
+You are building a complete visual storyboard by calling the board API. You generate the screen designs yourself — HTML pages by default (see "HTML page design" below), or grid elements only when the sketch path applies — then create the storyboard structure via `mcp__eventmodelers__*` tools (or `curl` as a fallback — see each step below). Only SCREEN/HTML_SCREEN nodes are created — no COMMAND or EVENT nodes.
 
 ## Step 1 — Parse arguments
 
@@ -29,12 +33,27 @@ If `chapterId` is provided, skip chapter creation and go straight to Step 4.
 Before making any API calls, plan all N screens. For each screen, decide:
 
 - `screenTitle` — human-readable name (e.g. "Enter Credentials")
-- `elements` — a minimal list of grid elements (see language below, aim for 5–8 elements)
+- `pages` (default) — one or more complete HTML/CSS fragments for this screen (see "HTML page design" below), or `elements` — a minimal list of grid elements (see "Sketch path" below, aim for 5–8 elements) **only** when the sketch path applies for this storyboard
 - `visualDescription` — a prose description of the screen's visual layout and content (2–4 sentences) that lets someone who cannot see the image understand what is shown: what UI sections appear, what text/labels are visible, where buttons and inputs are placed, and the overall purpose of the screen
 
 Then **create one task per screen** using TaskCreate, naming each task after the screen title. This gives you a visible queue of work. Create the screens directly after each task has been planned.
 
-## Grid description language
+## HTML page design (default)
+
+Write normal, full-size HTML/CSS for each screen — as if designing a real webpage, not a tiny thumbnail. The canvas node renders this at a real page width and visually scales it down to fit, so there is no need to shrink font sizes or padding.
+
+- Each page is one complete, standalone HTML fragment — not a `data-step` div nested inside a shared blob. A multi-step flow is multiple pages, each fully self-contained.
+- Inline styles (`style="..."`) are the simplest way to keep each page self-contained.
+- No `<script>` tags, no inline event handlers (`onclick`, `onload`, ...), no `javascript:` URIs — these are stripped server-side before persisting. This is a static visual mockup, not an interactive prototype.
+- A real page background (e.g. a light gray full-bleed background behind a centered white card) reads more realistically than a bare form floating on white.
+- Don't add `<html>`/`<head>`/`<body>` tags — every page is a body-only fragment; the canvas wraps it at render time.
+- Bulma CSS (0.9.4) is loaded by default — classes like `title`, `button`, `is-primary`, `field`/`control`/`input` etc. all work out of the box. Headings need a size modifier too, e.g. `class="title is-1"`.
+
+## Sketch path (explicit request only)
+
+Only use this path when the user's request explicitly asked for a "sketch", "wireframe", or "low-fidelity mockup" for this storyboard. Otherwise skip straight to the HTML page design above.
+
+### Grid description language
 
 Canvas: **50 × 40 grid units** (1000 × 800 px, 1 unit = 20 px).
 
@@ -86,7 +105,15 @@ Keep all coordinates within bounds: gridX 0–50, gridY 0–40.
 
 **If `chapterId` was provided in Step 1** — set `CHAPTER_ID = chapterId` and skip to Step 4. Do not make any API call here.
 
-**If `chapterId` was NOT provided** — create a new chapter (exactly once):
+**If `chapterId` was NOT provided** — create a new chapter (exactly once).
+
+**Prefer MCP:**
+
+```
+mcp__eventmodelers__create_chapter { "boardId": "<BOARD_ID>", "x": 0, "y": 0 }
+```
+
+**Fallback (no MCP):**
 
 ```bash
 curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/chapters" \
@@ -100,6 +127,14 @@ Extract `id` from the response → `CHAPTER_ID`.
 
 ### Step 4 — Fetch chapter state and build empty-column queue
 
+**Prefer MCP:**
+
+```
+mcp__eventmodelers__get_node { "boardId": "<BOARD_ID>", "nodeId": "<CHAPTER_ID>" }
+```
+
+**Fallback (no MCP):**
+
 ```bash
 curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$CHAPTER_ID"
 ```
@@ -117,9 +152,9 @@ Build an **empty-column queue**: for each column (in order), compute `actorCellI
 
 ---
 
-## SCREEN LOOP — repeat Steps 5a–5d once per screen (N iterations total)
+## SCREEN LOOP — repeat Steps 5a–5c once per screen (N iterations total)
 
-Process screens **one at a time**. Do not start the next screen until the current one is fully complete (node created + sketch rendered + verified).
+Process screens **one at a time**. Do not start the next screen until the current one is fully complete (node created + sketch rendered).
 
 **You have ONE chapter (`CHAPTER_ID`). All screens go into this same chapter. Do NOT call the chapter creation endpoint again inside this loop.**
 
@@ -129,7 +164,15 @@ Only SCREEN nodes are created. COMMAND and EVENT nodes are not created.
 
 **If the empty-column queue is non-empty** — pop the first entry. Use its `actorCellId` directly, proceed to Step 5b.
 
-**If the empty-column queue is empty** — add a new column (this does NOT create a new chapter):
+**If the empty-column queue is empty** — add a new column (this does NOT create a new chapter).
+
+**Prefer MCP:**
+
+```
+mcp__eventmodelers__add_column { "boardId": "<BOARD_ID>", "timelineId": "<CHAPTER_ID>" }
+```
+
+**Fallback (no MCP):**
 
 ```bash
 curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$CHAPTER_ID/columns" \
@@ -145,12 +188,30 @@ Extract `columnId` from the response. Compute the actor cell ID directly:
 
 **In both cases**, generate a node UUID: `SCREEN_NODE_ID`.
 
-### Step 5b — Create the node and render the sketch in one atomic call
+### Step 5b — Create the node and render it in one atomic call
+
+Build the payload, then send a single call that creates the screen node, places it into the actor cell, and renders its content — all in one request. There is no intermediate state where the node exists without content or without a cell.
+
+**Default — HTML (`contentType: "html"`, HTML_SCREEN node):**
 
-Build the payload, then send a single call that creates the SCREEN node, places it into the actor cell, and renders the sketch — all in one request. There is no intermediate state where the node exists without an image or without a cell:
+**Prefer MCP:**
+
+```
+mcp__eventmodelers__create_screen {
+  "boardId": "<BOARD_ID>",
+  "contentType": "html",
+  "nodeId": "<SCREEN_NODE_ID>",
+  "chapterId": "<CHAPTER_ID>",
+  "cellId": "<actorCellId>",
+  "pages": ["<div>...</div>"],
+  "description": "<screenTitle — what this screen shows>"
+}
+```
+
+**Fallback (no MCP):**
 
 ```bash
-curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/image-nodes/$SCREEN_NODE_ID/sketch" \
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/html-screen-nodes/$SCREEN_NODE_ID" \
   -H "x-token: $TOKEN" \
   -H "x-board-id: $BOARD_ID" \
   -H "x-user-id: agent" \
@@ -158,29 +219,47 @@ curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/image-nodes/$SCREEN_
   -d '{
     "chapterId": "<CHAPTER_ID>",
     "cellId": "<actorCellId>",
-    "description": {"elements": [...]},
-    "semanticDescription": "<screenTitle — what this screen shows>"
+    "pages": ["<div>...</div>"]
   }'
 ```
 
-Pass the already-computed `actorCellId` directly as `cellId` (the endpoint accepts either `cellId` or `cellName`). Expect `204`. On `400`, read the validation error, fix the payload, and retry once before reporting failure.
+**Sketch path (explicit request only) — `contentType: "sketch"`, plain SCREEN node:**
+
+**Prefer MCP:**
 
-### Step 5c — Verify the screen
+```
+mcp__eventmodelers__create_screen {
+  "boardId": "<BOARD_ID>",
+  "contentType": "sketch",
+  "nodeId": "<SCREEN_NODE_ID>",
+  "chapterId": "<CHAPTER_ID>",
+  "cellId": "<actorCellId>",
+  "elements": [...],
+  "description": "<screenTitle — what this screen shows>"
+}
+```
 
-Confirm the node and its rendered image both actually exist before moving on:
+**Fallback (no MCP):**
 
 ```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/screens/$SCREEN_NODE_ID/verify" \
-  -H "x-token: $TOKEN"
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/image-nodes/$SCREEN_NODE_ID/sketch" \
+  -H "x-token: $TOKEN" \
+  -H "x-board-id: $BOARD_ID" \
+  -H "x-user-id: agent" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "chapterId": "<CHAPTER_ID>",
+    "cellId": "<actorCellId>",
+    "description": {"elements": [...]},
+    "semanticDescription": "<screenTitle — what this screen shows>"
+  }'
 ```
 
-Check the `valid` field in the response:
-- **`valid: true`** — proceed to marking the task complete.
-- **`valid: false`** — read the `error` field and retry Step 5b once. If it fails verification again, log the error for this screen in the final report and move on to the next screen — do not get stuck retrying indefinitely.
+Pass the already-computed `actorCellId` directly as `cellId` in either path. Expect success (MCP: `created: true`; curl: `204`). On failure, read the validation error, fix the payload, and retry once before reporting failure.
 
-### Step 5d — Mark the task complete
+### Step 5c — Mark the task complete
 
-After the node, sketch, and verification all succeed, mark the task for this screen as completed using TaskUpdate.
+After the node and sketch succeed, mark the task for this screen as completed using TaskUpdate.
 
 ---
 
@@ -189,4 +268,4 @@ After the node, sketch, and verification all succeed, mark the task for this scr
 After all screens are done, summarise:
 - Chapter ID
 - Numbered list: screen title
-- Any errors (with status codes), including screens that failed the Step 5c verification
+- Any errors (with status codes)

package/stacks/modeling-kit/templates/.claude/skills/storyboard-screen/SKILL.md

@@ -1,13 +1,17 @@
 ---
 name: storyboard-screen
-description: Design and render a single AI-generated wireframe screen onto an existing SCREEN node using the sketch API
+description: Design and render a single AI-generated wireframe sketch screen onto an existing SCREEN node using the sketch API — use only when the user explicitly asks for a wireframe/sketch; html-screen is the default for ordinary screen requests
 ---
 
 # Storyboard Screen Designer
 
-> **Before doing anything else**, invoke the `connect` skill to resolve `TOKEN`, `BOARD_ID`, and `BASE_URL`. Do not proceed until the connect skill has completed.
+> **Before doing anything else**, invoke the `connect` skill — if not already connected — to resolve `TOKEN`, `BOARD_ID`, and `BASE_URL`. Do not proceed until the connect skill has completed.
 
-> **MANDATORY RENDER + VERIFY**: The sketch API call in Step 4 and the verification in Step 5 are **not optional**. This skill exists solely to produce a rendered wireframe. A SCREEN node without a rendered sketch is an empty placeholder that adds no value to the model. If the sketch API call is skipped or fails, or verification reports `valid: false`, the task is incomplete — retry or report the error.
+Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect` skill) — the curl blocks below are the fallback for sessions without MCP connected.
+
+> **EXPLICIT USE ONLY**: Do not reach for this skill on an ordinary "design a screen" / "storyboard this" request — the default is `html-screen`, which renders a real HTML/CSS mockup onto an HTML_SCREEN node. Use this skill **only** when the user explicitly asks for a "sketch", a "wireframe", a "low-fidelity mockup", or names the SCREEN node type directly.
+
+> **MANDATORY RENDER**: The sketch API call in Step 4 is **not optional**. This skill exists solely to produce a rendered wireframe. A SCREEN node without a rendered sketch is an empty placeholder that adds no value to the model. If the sketch API call is skipped or fails, the task is incomplete — retry or report the error.
 
 Design a single wireframe screen and render it onto an existing SCREEN node. Use this to redesign a screen, add detail to a placeholder, or update a screen after a flow changes.
 
@@ -26,7 +30,15 @@ If `nodeId` is missing, ask for it before doing anything. `BOARD_ID` and `BASE_U
 
 ## Step 2 — If updating an existing screen, load its current description first
 
-If `nodeId` refers to a screen that has already been rendered (i.e. this is an adjustment/tweak, not a brand-new screen), **do not design from scratch**. First load the existing sketch description so the edit preserves the rest of the layout:
+If `nodeId` refers to a screen that has already been rendered (i.e. this is an adjustment/tweak, not a brand-new screen), **do not design from scratch**. First load the existing sketch description so the edit preserves the rest of the layout.
+
+**Prefer MCP:**
+
+```
+mcp__eventmodelers__get_image_snapshot_description { "boardId": "<BOARD_ID>", "nodeId": "<NODE_ID>" }
+```
+
+**Fallback (no MCP):**
 
 ```bash
 curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/images/$NODE_ID/description" \
@@ -93,6 +105,19 @@ Keep all coordinates within bounds: gridX 0–50, gridY 0–40.
 
 ## Step 4 — Render the sketch
 
+**Prefer MCP:**
+
+```
+mcp__eventmodelers__render_screen {
+  "boardId": "<BOARD_ID>",
+  "nodeId": "<NODE_ID>",
+  "elements": [...],
+  "description": "<what this screen shows>"
+}
+```
+
+**Fallback (no MCP):**
+
 ```bash
 curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/images/$NODE_ID/sketch" \
   -H "x-token: $TOKEN" \
@@ -104,20 +129,9 @@ curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/images/$NODE_ID/sket
 
 Expect `204 No Content` on success.
 
-## Step 5 — Verify the screen
-
-Confirm the node and its rendered image both actually exist:
-
-```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/screens/$NODE_ID/verify" \
-  -H "x-token: $TOKEN"
-```
-
-If `valid` is `false`, read the `error` field and retry the failing step (Step 4 if `imageExists` is `false`) once before reporting failure.
-
-## Step 6 — Report back
+## Step 5 — Report back
 
 Tell the user:
 - The node ID that was updated
-- Whether the render succeeded (HTTP 204) and verification passed (`valid: true`)
+- Whether the render succeeded (HTTP 204)
 - Any errors