@eventmodelers/cli 0.0.1

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

@@ -0,0 +1,290 @@
+---
+name: place-element
+description: Place a COMMAND, READMODEL, EVENT, SCREEN, AUTOMATION, or SCENARIO spec node onto an existing eventmodelers board timeline at a specific position
+---
+
+# 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.
+
+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.
+---
+
+## Step 1 — Parse arguments
+
+From `$ARGUMENTS`, extract:
+
+| Field | How to find it | Default |
+|-------|---------------|---------|
+| `elementType` | `event`, `command`, `readmodel`, `screen`, or `automation` (case-insensitive) | **required** |
+| `title` | the element name, e.g. "Order Placed" | **required** |
+| `boardId` | a board UUID | from `connect` skill (`BOARD_ID`) |
+| `timelineId` | the chapter/timeline UUID | auto-detect (see Step 2) |
+| `position` | column index (0-based number), `"after <title>"`, or omitted | append at end |
+| `baseUrl` | explicit URL override | from `connect` skill (`BASE_URL`) |
+
+Normalise `elementType` to uppercase: `event` → `EVENT`, `command` → `COMMAND`, `readmodel` → `READMODEL`, `screen` → `SCREEN`, `automation` → `AUTOMATION`.
+
+Use `BOARD_ID` and `BASE_URL` from the `connect` skill. If a `boardId` argument is explicitly passed, it overrides `BOARD_ID`.
+
+---
+
+## Step 2 — Resolve the timeline
+
+If `timelineId` is not provided, discover chapters on the board:
+
+```bash
+curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=CHAPTER"
+```
+
+- **Exactly one chapter** → use it automatically, tell the user which one was selected.
+- **Multiple chapters** → list them by name/ID and ask the user which to target.
+- **No chapters** → stop and tell the user to create a chapter first (e.g. via the `/timeline` skill).
+
+---
+
+## Step 3 — Fetch existing columns and resolve position
+
+Always fetch the chapter node first to get the current timeline state:
+
+```bash
+curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$TIMELINE_ID"
+```
+
+From `meta.timelineData`, read `columns` (ordered array of column objects with `id` and `index`) and `cells`.
+
+Then resolve `position`:
+
+| Input | Behaviour |
+|-------|-----------|
+| A number (e.g. `2`) | Find the existing column whose `index === 2`. Save its `id` as `columnId`. **Do NOT create a new column.** |
+| `"after <title>"` | Cross-reference node titles to find the named column, then target the column at position + 1. If that next column already exists use it; if not, create one at that index. |
+| Omitted | No existing column is targeted → create a new column at the end (Step 5). |
+
+If `position` is a number and no column exists at that index, stop and tell the user: "No column at index `<n>` — did you mean to append instead?"
+
+---
+
+## Step 4 — Determine the target lane
+
+| `elementType` | Target lane `type` |
+|---------------|--------------------|
+| `EVENT`       | `swimlane`         |
+| `COMMAND`     | `interaction`      |
+| `READMODEL`   | `interaction`      |
+| `SCREEN`      | `actor`            |
+| `AUTOMATION`  | `actor`            |
+| `SCENARIO`    | `spec`             |
+
+---
+
+## Step 4a — SCENARIO only: append scenarios via the spec endpoint
+
+**Only applies when `elementType === "SCENARIO"`.**
+
+The `/scenarios` endpoint creates the SCENARIO spec node automatically if the spec cell is empty, then appends all provided scenarios in one call. Do **not** use `/nodes/events` to create the spec node or write scenarios manually.
+
+After resolving `columnId` (from step 3, or from step 5 if a new column was just created), call:
+
+```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" \
+  -d '[
+    {
+      "id": "<scenario-uuid>",
+      "title": "Happy path",
+      "given": [{"id":"<eventNodeId>","title":"OrderPlaced","type":"EVENT"}],
+      "when":  [{"id":"<commandNodeId>","title":"PlaceOrder","type":"COMMAND"}],
+      "then":  [{"id":"<eventNodeId2>","title":"OrderConfirmed","type":"EVENT"}]
+    },
+    {
+      "id": "<scenario-uuid>",
+      "title": "Insufficient stock",
+      "given": [{"id":"<eventNodeId>","title":"OrderPlaced","type":"EVENT"}],
+      "when":  [{"id":"<commandNodeId>","title":"PlaceOrder","type":"COMMAND"}],
+      "then":  [],
+      "expectError": true,
+      "errorDescription": "Stock below requested quantity"
+    }
+  ]'
+# → 201 { specNodeId, scenarios (all), added (count), isNewNode }
+```
+
+**Scenario object shapes:**
+
+| Scenario type | Shape |
+|---|---|
+| Happy path | `{ id, title, given[], when[], then[] }` |
+| Error case | `{ id, title, given[], when[], then: [], expectError: true, errorDescription: "..." }` |
+
+**Step item format** — each item in `given`, `when`, `then`:
+```json
+{ "id": "<board-node-uuid>", "title": "OrderPlaced", "type": "EVENT", "fields": [], "specRow": 0 }
+```
+`id` is required (board node UUID). `title` and `type` are informational.
+
+| Step | Allowed types |
+|------|--------------|
+| `given` | `EVENT` only |
+| `when`  | at most one `COMMAND`; empty when `then` has a READMODEL |
+| `then` (happy path) | `EVENT` or `READMODEL` — not mixed |
+| `then` (error case) | leave empty, use `expectError: true` |
+
+**Mapping config IDs to board node IDs** — if working from a slice config file, build a lookup first:
+```
+config_command_id → board COMMAND node ID  (from chapter cells for that column)
+config_event_id   → board EVENT node ID    (from chapter cells for that column)
+config_rm_id      → board READMODEL node ID
+```
+
+Once `/scenarios` returns `201`, proceed directly to **Step 8** — report back to the user.
+
+---
+
+## Step 5 — Create a column only when appending
+
+**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):
+
+```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" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+Response: `{ "columnId": "<uuid>", "index": <n>, "totalColumns": <n> }`
+
+Save `columnId` from the response.
+
+---
+
+## Step 6 — Compute the target cell ID and check availability
+
+Using the `timelineData` already fetched in Step 3 (re-fetch if a column was just created):
+
+- Find the row in `rows` whose `type` matches the target lane (`swimlane`, `interaction`, or `actor`).
+- Compute the cell ID directly: **`CELL_ID = targetRow.id + "-" + columnId`**
+
+Cell IDs are always `<rowId>-<columnId>` — no cell array search needed.
+
+**Check if the cell is already occupied**: query nodes in that cell:
+
+```bash
+curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?cellId=$CELL_ID"
+```
+
+**If the cell is occupied**, the behaviour depends on the element type being placed:
+
+| Element type | Occupant type in same cell | Action |
+|---|---|---|
+| `READMODEL` | `COMMAND` (state-change slice already owns this column) | Insert a **new column immediately after** the current column (not at the end) and use that new column as the target. |
+| `SCREEN` (view/output screen) | any | Same as READMODEL — insert immediately after. |
+| Any | Same element type | Stop and tell the user — true conflict, no safe default. |
+| Any | Different type but not a known pairing | Stop and tell the user. |
+
+**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.
+
+```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" \
+  -H "Content-Type: application/json" \
+  -d '{"index": <currentColumnIndex + 1>}'
+```
+
+If no matching row is found, stop and report the error — the timeline may be missing the required lane type.
+
+---
+
+## Step 7 — Create the node
+
+> **SCREEN nodes always require a sketch.** The server auto-generates a title-only placeholder when a SCREEN is created without one, but it will look empty. Always follow up a SCREEN node creation with a call to `POST /images/:nodeId/sketch` (or use `POST /image-nodes/:nodeId/sketch` to create and render in one call — see `learn-eventmodelers-api` for the sketch format).
+
+Include `x-token`, `x-board-id`, and `x-user-id: agent` on every call to `/nodes/events`:
+
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
+  -H "x-token: $TOKEN" \
+  -H "x-board-id: $BOARD_ID" \
+  -H "x-user-id: agent" \
+  -H "Content-Type: application/json" \
+  -d '[{
+    "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>" } }
+  }]'
+```
+
+Response: `{ "hashes": { "<event-uuid>": "<hash>" } }`
+
+> **`node:created` with `cellId` IS the placement** — do NOT also call the `drop` endpoint afterwards. The `drop` endpoint adds a second cell reference without removing the first, causing the node to appear in two columns simultaneously. Use `node:created + cellId` for all initial placements.
+
+---
+
+## Step 8 — Report back
+
+Tell the user:
+
+- **What was placed**: element type and title
+- **Where**: column index on the timeline
+- **Node ID**: the UUID of the placed element
+- **Cell ID**: the cell it was placed into
+- **Any errors**: raw API message if something failed
+
+Example success output:
+```
+Placed: EVENT "Order Placed" at column 3
+Node ID: a1b2c3d4-…
+Cell ID: e5f6g7h8-…
+Timeline: <timelineId>
+```
+
+---
+
+## Example — place an EVENT via curl
+
+Full working example placing an EVENT called "Order Placed" at the end of a timeline:
+
+```bash
+# 1. Add a column (append at end)
+curl -s -X POST "http://localhost:3000/api/org/<ORG_ID>/boards/<BOARD_ID>/timelines/<TIMELINE_ID>/columns" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+
+# 2. Fetch chapter to find the target lane cell for the new column
+curl -s -H "x-user-id: place-element-skill" \
+  "http://localhost:3000/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<TIMELINE_ID>"
+
+# 3. Create the EVENT node
+
+Do not skip the User-ID. 
+
+
+curl -s -X POST "http://localhost:3000/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/events" \
+  -H "Content-Type: application/json" \
+  -H "x-user-id: place-element-skill" \
+  -d '[{
+    "id": "<event-uuid>",
+    "eventType": "node:created",
+    "nodeId": "<node-uuid>",
+    "boardId": "<BOARD_ID>",
+    "timestamp": 1714900000000,
+    "chapterId": "<TIMELINE_ID>",
+    "cellId": "<CELL_ID>",
+    "meta": { "type": "EVENT", "title": "Order Placed" },
+    "node": { "id": "<node-uuid>", "data": { "title": "Order Placed" } }
+  }]'
+```
+
+Replace `<TIMELINE_ID>`, `<BOARD_ID>`, `<CELL_ID>`, `<event-uuid>`, and `<node-uuid>` with real UUIDs. Use `Date.now()` or a current unix-ms timestamp for `timestamp`.

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

@@ -0,0 +1,212 @@
+---
+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
+---
+
+# 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.
+
+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.
+
+## Step 1 — Parse arguments
+
+From `$ARGUMENTS`, extract:
+
+| Field | How to find it | Default |
+|-------|---------------|---------|
+| `description` | the flow name, e.g. "login flow", "checkout", "user onboarding" | required |
+| `screenCount` | any number mentioned, e.g. "6 screens", "with 4 steps" | 3 |
+| `boardId` | a board ID string, e.g. "board-abc" | from `connect` skill (`BOARD_ID`) |
+| `chapterId` | an existing chapter ID to reuse, e.g. "chapter-xyz" | empty — create a new chapter |
+| `baseUrl` | explicit URL override | from `connect` skill (`BASE_URL`) |
+
+`BOARD_ID` and `BASE_URL` come from the `connect` skill. Only ask the user for `boardId` if explicitly overriding.
+If `chapterId` is provided, skip chapter creation and go straight to Step 4.
+
+## Step 2 — Plan all screens and create tasks
+
+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)
+- `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
+
+Canvas: **50 × 40 grid units** (1000 × 800 px, 1 unit = 20 px).
+
+**Keep screens simple.** 5–8 elements is ideal. Speed matters more than detail — use rectangles as section placeholders, skip decorative elements. Skip circles.
+
+Every screen's `elements` array **must start** with a full white background:
+```json
+{"type":"rectangle","gridX":0,"gridY":0,"gridWidth":50,"gridHeight":40,"fill":"white"}
+```
+
+### Element types
+
+| type | required fields | optional fields |
+|------|----------------|-----------------|
+| `rectangle` | gridX, gridY, gridWidth, gridHeight | fill, stroke |
+| `text` | gridX, gridY, text | fontSize (default 12), fill, gridWidth |
+| `headline` | gridX, gridY, text | fontSize (default 20), fill, gridWidth |
+| `button` | gridX, gridY, gridWidth, gridHeight, text | fill, stroke |
+| `input` | gridX, gridY, gridWidth, gridHeight, text (placeholder) | fill, stroke |
+| `image` | gridX, gridY, gridWidth, gridHeight | fill (placeholder color) |
+| `line` | gridX, gridY, gridX2, gridY2 | stroke |
+| `circle` | gridX, gridY, gridRadius | fill, stroke |
+
+### Colors
+Limited to: `black` `grey` `light-violet` `violet` `blue` `light-blue` `yellow` `orange` `green` `light-green` `light-red` `red` `white`. No hex codes.
+
+Keep all coordinates within bounds: gridX 0–50, gridY 0–40.
+
+### Example — a simple screen (8 elements)
+```json
+{
+  "elements": [
+    {"type":"rectangle","gridX":0,"gridY":0,"gridWidth":50,"gridHeight":40,"fill":"white"},
+    {"type":"rectangle","gridX":0,"gridY":0,"gridWidth":50,"gridHeight":3,"fill":"light-violet"},
+    {"type":"headline","gridX":2,"gridY":1,"text":"Sign In","fontSize":18,"fill":"white"},
+    {"type":"input","gridX":15,"gridY":12,"gridWidth":20,"gridHeight":2,"text":"Email","fill":"white","stroke":"grey"},
+    {"type":"input","gridX":15,"gridY":16,"gridWidth":20,"gridHeight":2,"text":"Password","fill":"white","stroke":"grey"},
+    {"type":"button","gridX":15,"gridY":21,"gridWidth":20,"gridHeight":3,"text":"Sign In","fill":"blue"},
+    {"type":"text","gridX":18,"gridY":26,"text":"Forgot password?","fontSize":12,"fill":"blue"}
+  ]
+}
+```
+
+---
+
+## ONE-TIME SETUP — run Steps 3 and 4 exactly once before the screen loop
+
+### Step 3 — Resolve or create the chapter
+
+**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):
+
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/chapters" \
+  -H "Content-Type: application/json" \
+  -d '{"position":{"x":0,"y":0}}'
+```
+
+Extract `id` from the response → `CHAPTER_ID`.
+
+**You now have exactly one `CHAPTER_ID`. Do not create another chapter.**
+
+### Step 4 — Fetch chapter state and build empty-column queue
+
+```bash
+curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$CHAPTER_ID"
+```
+
+Parse `meta.timelineData` from the response:
+- `rows` — list of row objects, each with `id` and `type`
+- `columns` — list of column objects, each with `id`
+- `cells` — list of cell objects, each with `rowId`, `colId`, and optionally `nodeId` (used only to check occupancy)
+
+Find the row IDs for the `actor`, `interaction`, and `swimlane` row types. Save as `actorRowId`, `interactionRowId`, `swimlaneRowId`.
+
+> **Cell ID convention**: Cell IDs are always `<rowId>-<columnId>`. Compute them directly — never search the `cells` array for an ID.
+
+Build an **empty-column queue**: for each column (in order), compute `actorCellId = actorRowId + "-" + col.id`, `interactionCellId = interactionRowId + "-" + col.id`, `swimlaneCellId = swimlaneRowId + "-" + col.id`. Check these IDs in the `cells` array for a `nodeId` (absent or null). If ALL three have no `nodeId`, push `{actorCellId, interactionCellId, swimlaneCellId}` onto the queue.
+
+---
+
+## SCREEN LOOP — repeat Steps 5a–5d 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).
+
+**You have ONE chapter (`CHAPTER_ID`). All screens go into this same chapter. Do NOT call the chapter creation endpoint again inside this loop.**
+
+Only SCREEN nodes are created. COMMAND and EVENT nodes are not created.
+
+### Step 5a — Acquire a column slot for this screen
+
+**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):
+
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$CHAPTER_ID/columns" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+Extract `columnId` from the response. Compute the actor cell ID directly:
+
+**`actorCellId = actorRowId + "-" + columnId`**
+
+(Cell IDs are always `<rowId>-<columnId>` — no re-fetch or cell array search needed.)
+
+**In both cases**, generate a node UUID: `SCREEN_NODE_ID`. Generate an event UUID: `ACTOR_EVT_ID`.
+
+Place the SCREEN node into the actor cell using the `/nodes/events` endpoint (agent-compatible — requires `x-user-id: agent`):
+
+> **Do NOT use** `/boards/$BOARD_ID/events` — that endpoint requires a user JWT and will fail for agent (x-token) auth with "Authenticated user id is required".
+
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
+  -H "x-token: $TOKEN" \
+  -H "x-board-id: $BOARD_ID" \
+  -H "x-user-id: agent" \
+  -H "Content-Type: application/json" \
+  -d '[
+    {
+      "id":        "<ACTOR_EVT_ID>",
+      "eventType": "node:created",
+      "nodeId":    "<SCREEN_NODE_ID>",
+      "boardId":   "<BOARD_ID>",
+      "timestamp": <NOW_MS>,
+      "chapterId": "<CHAPTER_ID>",
+      "cellId":    "<actorCellId>",
+      "meta":      {"type": "SCREEN", "title": "<screenTitle>", "description": "<visualDescription>"},
+      "node":      {"id": "<SCREEN_NODE_ID>", "data": {}}
+    }
+  ]'
+```
+
+Verify the response contains `"hashes"`. If it fails, stop and report the error — do not proceed to the sketch step.
+
+> **Do NOT call the `drop` endpoint after this step.** `node:created` with `cellId` already places the node in the correct cell. Calling drop afterwards creates a duplicate cell reference without removing the original, causing the node to appear in two columns simultaneously.
+
+### Step 5b — Render the sketch onto the SCREEN node
+
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/images/$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 '{"description": "<screenTitle — what this screen shows>", "elements": [...]}'
+```
+
+### Step 5c — Verify the screen
+
+Confirm the node and its rendered image both actually exist before moving on:
+
+```bash
+curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/screens/$SCREEN_NODE_ID/verify" \
+  -H "x-token: $TOKEN"
+```
+
+Check the `valid` field in the response:
+- **`valid: true`** — proceed to Step 5d.
+- **`valid: false`** — read the `error` field. If `nodeExists` is `false`, the node creation in Step 5a failed; retry it. If `imageExists` is `false`, the sketch render in Step 5b failed silently; 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.
+
+### Step 5d — Mark the task complete
+
+After the node, sketch, and verification all succeed, mark the task for this screen as completed using TaskUpdate.
+
+---
+
+## Step 6 — Report back
+
+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

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

@@ -0,0 +1,123 @@
+---
+name: storyboard-screen
+description: Design and render a single AI-generated wireframe screen onto an existing SCREEN node using the sketch API
+---
+
+# 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.
+
+> **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.
+
+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.
+
+## Step 1 — Parse arguments
+
+From `$ARGUMENTS`, extract:
+
+| Field | How to find it | Default |
+|-------|---------------|---------|
+| `description` | what the screen should contain, e.g. "login with email and password" | required |
+| `boardId` | a board ID string | from `connect` skill (`BOARD_ID`) |
+| `nodeId` | the SCREEN node UUID to update | **ask the user if missing** |
+| `baseUrl` | explicit URL override | from `connect` skill (`BASE_URL`) |
+
+If `nodeId` is missing, ask for it before doing anything. `BOARD_ID` and `BASE_URL` come from the `connect` skill.
+
+## 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:
+
+```bash
+curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/images/$NODE_ID/description" \
+  -H "x-token: $TOKEN" \
+  -H "x-board-id: $BOARD_ID" \
+  -H "x-user-id: agent"
+```
+
+- `200` — returns the previously stored `{ elements: [...] }`. Use this as the base and apply only the requested change (e.g. edit one element's `text`/`fill`, add/remove a specific element) — leave everything else untouched.
+- `404` — no description stored yet (e.g. an older screen rendered before this endpoint existed, or a placeholder node). Fall back to designing from scratch in Step 3.
+
+Skip this step entirely when the node is brand-new (no prior render) — go straight to Step 3.
+
+## Step 3 — Design the screen
+
+Design the screen using the grid description language — either from scratch (new screen, or Step 2 returned `404`) or by editing the elements loaded in Step 2. Think carefully about the layout — what elements does this screen need? Where should they go on the 50×40 grid?
+
+Also compose a `visualDescription` — a prose description (2–4 sentences) of the screen's visual layout and content, written so that someone who cannot see the image can 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.
+
+## Grid description language
+
+Canvas: **50 × 40 grid units** (1000 × 800 px, 1 unit = 20 px).
+
+Always start with a full white background:
+```json
+{"type":"rectangle","gridX":0,"gridY":0,"gridWidth":50,"gridHeight":40,"fill":"white"}
+```
+
+### Element types
+
+| type | required fields | optional fields |
+|------|----------------|-----------------|
+| `rectangle` | gridX, gridY, gridWidth, gridHeight | fill, stroke |
+| `text` | gridX, gridY, text | fontSize (default 12), fill, gridWidth |
+| `headline` | gridX, gridY, text | fontSize (default 20), fill, gridWidth |
+| `button` | gridX, gridY, gridWidth, gridHeight, text | fill, stroke |
+| `input` | gridX, gridY, gridWidth, gridHeight, text (placeholder) | fill, stroke |
+| `image` | gridX, gridY, gridWidth, gridHeight | fill (placeholder color) |
+| `line` | gridX, gridY, gridX2, gridY2 | stroke |
+| `circle` | gridX, gridY, gridRadius | fill, stroke |
+
+### Colors
+Limited to: `black` `grey` `light-violet` `violet` `blue` `light-blue` `yellow` `orange` `green` `light-green` `light-red` `red` `white`. No hex codes.
+
+**Default palette — gray shades**: Unless instructed otherwise, use a grayscale palette. Prefer `white` for surfaces, `grey` for backgrounds, containers, borders, and secondary/placeholder text, and `black` for headings and primary text. Only introduce color when the user explicitly requests it.
+
+Keep all coordinates within bounds: gridX 0–50, gridY 0–40.
+
+### Example
+```json
+{
+  "elements": [
+    {"type":"rectangle","gridX":0,"gridY":0,"gridWidth":50,"gridHeight":40,"fill":"white"},
+    {"type":"rectangle","gridX":0,"gridY":0,"gridWidth":50,"gridHeight":3,"fill":"#424242"},
+    {"type":"headline","gridX":2,"gridY":1,"text":"Dashboard","fontSize":18,"fill":"white"},
+    {"type":"text","gridX":2,"gridY":6,"text":"Welcome back","fontSize":14,"fill":"grey"},
+    {"type":"rectangle","gridX":2,"gridY":9,"gridWidth":21,"gridHeight":8,"fill":"#e0e0e0","stroke":"#bdbdbd"},
+    {"type":"headline","gridX":4,"gridY":11,"text":"142","fontSize":24,"fill":"#424242"},
+    {"type":"text","gridX":4,"gridY":14,"text":"Orders this month","fontSize":11,"fill":"grey"},
+    {"type":"button","gridX":35,"gridY":36,"gridWidth":12,"gridHeight":2,"text":"Logout","fill":"#bdbdbd","stroke":"grey"}
+  ]
+}
+```
+
+## Step 4 — Render the sketch
+
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/images/$NODE_ID/sketch" \
+  -H "x-token: $TOKEN" \
+  -H "x-board-id: $BOARD_ID" \
+  -H "x-user-id: agent" \
+  -H "Content-Type: application/json" \
+  -d '{"description": "<what this screen shows>", "elements": [...]}'
+```
+
+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
+
+Tell the user:
+- The node ID that was updated
+- Whether the render succeeded (HTTP 204) and verification passed (`valid: true`)
+- Any errors