@eventmodelers/cli 1.0.35 → 1.0.37

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-storyboarding-events/SKILL.md

@@ -92,161 +92,22 @@ Optional: Write to `.trogonai/interviews/[timestamp]-storyboarding-events.interv
 Given the event timeline, create UI storyboards:
 
 ### 1. Identify UI Screens/Views
-Create a mockup for each state of the system:
-
-```
-Screen 1: Order Creation Form
-
- Place Your Order                
-
-                                 
- Customer ID: [____________]     
-                                 
- Items:                          
-Product 1  Qty: [_]  Price: $_
-Product 2  Qty: [_]  Price: $_
-Product 3  Qty: [_]  Price: $_
-                                 
- Total: $___                     
-                                 
- Shipping Address:               
- [_____________________]         
- [_____________________]         
-                                 
- [ Create Order ]                
-
-
-Trigger: CreateOrder command
-Result Events: OrderCreated
-Data captured from UI:
-  - customerId
-  - items (products + quantities)
-  - total
-  - shippingAddress
-```
+Create a mockup for each state of the system: for each screen, note the trigger action, the command it produces, the resulting event, and the data fields the screen captures. A full worked example (Order Creation Form) is in `references/examples.md`.
 
 ### 2. Show State Transitions Between Screens
-Document what changes when events occur:
-
-```
-Screen 2: Order Confirmation
-(After OrderCreated event)
-
-
- Order Confirmation              
-
-                                 
- Order ID: #12345                
- Status: Draft                   
-                                 
- Items: 3 products               
- Total: $150.00                  
-                                 
- Shipping: 123 Main St           
-                                 
- Payment Options:                
-Credit Card                   
-Bank Transfer                 
-                                 
- [ Confirm Order ]               
-
-
-Trigger: ConfirmOrder command
-Result Events: OrderConfirmed
-Data from UI:
-  - orderId (from OrderCreated)
-  - paymentMethod
-```
+Document what changes when events occur: after each event, the next screen shows the fields that were just set by that event, alongside the next command the user can trigger. A full worked example (Order Confirmation, after OrderCreated) is in `references/examples.md`.
 
 ### 3. Document All Data Fields
-For each screen, list what data is displayed:
-
-```
-Screen: Order Status View
-
- Your Order Status               
-
- Order ID: #12345                 (from OrderCreated)
- Status: Confirmed               (from OrderConfirmed)
- Confirmed at: 2024-12-31 10:00   (from OrderConfirmed)
-                                 
- Payment: Authorized             (from PaymentAuthorized)
- Auth Code: AUTH-789              (from PaymentAuthorized)
-                                 
- Inventory: Reserved             (from InventoryReserved)
- Expected Ship: 2025-01-02        (from InventoryReserved)
-                                 
- Shipped: Pending                 (awaiting OrderShipped)
- Tracking: -- (waiting for shipment)
-
-
-Fields and their origins:
-  orderId → OrderCreated event
-  status → OrderConfirmed event
-  confirmedAt → OrderConfirmed event
-  paymentStatus → PaymentAuthorized event
-  authCode → PaymentAuthorized event
-  inventoryStatus → InventoryReserved event
-  expectedShip → InventoryReserved event
-  tracking → OrderShipped event (when available)
-```
+For each screen, list what data is displayed, and the specific event each field's value originated from. A full worked example (Order Status View) is in `references/examples.md`.
 
 ### 4. Show Data Flow Through Screens
-Map how data enters/exits UI:
-
-```
-Order Entry UI
-   (user inputs)
-   customerId
-   items[]
-   total
-   shippingAddress
-      ↓
-      Command: CreateOrder
-      ↓
-      Event: OrderCreated
-      ↓
-      Order Status UI (displays)
-       orderId (from event)
-       items (from event)
-       total (from event)
-       shippingAddress (from event)
-```
+Map how data enters/exits UI: user input flows into a command, the command produces an event, and the event's data flows back out into the next screen that displays it. A full worked example is in `references/examples.md`.
 
 ### 5. Organize Screens by Swimlane (Actor/System)
 
 **MANDATORY**: Use the **Role Catalog** from Step 1 (eventmodeling-brainstorming-events) as the source of swimlanes. Every human role in the catalog MUST have its own swimlane. Every system actor that has a UI or todo-list view gets a swimlane too — but this swimlane is narrative-only (see "Board Integration" below): system actors never get a physical actor lane of their own on the board, only human roles do.
 
-Group screens by who interacts with them:
-
-```
-Swimlane: Customer (Human Role)
-   Screen 1: Order Entry Form
-   Screen 2: Order Confirmation
-   Screen 3: Order Status View
-   Screen 4: Tracking View
-
-Swimlane: Seller (Human Role)
-   Screen 1: Order Fulfillment Dashboard
-   Screen 2: Review Response Form
-   Screen 3: Product Management
-
-Swimlane: Support Agent (Human Role)
-   Screen 1: Escalation Queue
-   Screen 2: Manual Override Panel
-
-Swimlane: Payment Processor (System Actor)
-   Screen 1: Payment Verification (automated)
-   Screen 2: Authorization Confirmation
-
-Swimlane: Inventory System (System Actor)
-   Screen 1: Reservation Todo List (internal)
-   Screen 2: Availability Check
-
-Swimlane: Fulfillment System (System Actor)
-   Screen 1: Shipment Creation Todo
-   Screen 2: Shipping Confirmation
-```
+Group screens by who interacts with them: one swimlane per human role (Customer, Seller, Support Agent, ...) listing that role's screens, plus one narrative swimlane per system actor (Payment Processor, Inventory System, ...) listing the screens/views it interacts with. A full worked example (Order domain swimlane grouping) is in `references/examples.md`.
 
 **Validation**: If a role from the catalog has zero screens, either:
 - The role is missing screens (add them), or
@@ -257,34 +118,7 @@ This shows which actors interact with which screens and helps visualize system b
 **This grouping is not just narrative for human roles** — "Board Integration" below turns each *human role's* swimlane in this catalog into its own physical actor lane on the board, so a screen's role determines which lane it is actually placed in, not just how it is described in the report. System actor swimlanes stay narrative-only: their automations are placed in the chapter's shared default actor lane, never a lane fabricated to mimic a human role's lane (see "Placing Automations" below).
 
 ### 6. Show Processor "Todo List" Pattern
-For automated processors, show the todo list metaphor:
-
-```
-Processor: InventoryReserver
-
-Internal "Todo List" (based on received events):
-
- Inventory Reservation Todos     
-
-                                 
-Order-123: Reserve 2x Prod-1  (triggered by PaymentAuthorized)
-Order-124: Reserve 3x Prod-2  (triggered by PaymentAuthorized)
-Order-125: Reserve 1x Prod-3  (triggered by PaymentAuthorized)
-                                 
- Processor checks todo items:    
- For each: Check availability    
-          If available:  Mark done
-          Reserve inventory      
-          Produce event          
-                                 
-
-
-This todo list is driven by:
-Events received → Items added to todo
-Processor logic → Items processed
-Success → InventoryReserved event produced + todo marked done
-Failure → InventoryFailed event produced + todo marked failed
-```
+For automated processors, show the todo list metaphor: each received triggering event adds a todo item, the processor checks each item's condition, and success or failure produces a corresponding event while marking the item done or failed. A full worked example (InventoryReserver's todo list) is in `references/examples.md`.
 
 **When it comes time to elaborate scenarios for this todo list (`eventmodeling-elaborating-scenarios`), reach for a storyline rather than plain GWT scenarios.** A todo list is exactly the shape a storyline is built for: the *same* read model (the todo list itself) walked through multiple states — empty → item added → item marked done/failed — which is one narrated walkthrough, not a set of isolated before/after pairs. See that skill's "Storylines" section for the data shape and posting mechanics.
 
@@ -311,13 +145,7 @@ mcp__eventmodelers__get_nodes { "boardId": "$BOARD_ID", "type": "HTML_SCREEN" }
 mcp__eventmodelers__get_nodes { "boardId": "$BOARD_ID", "type": "SCREEN" }
 ```
 
-**Fallback (no MCP):**
-```bash
-curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=HTML_SCREEN"
-curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=SCREEN"
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Board Integration — Check existing screen nodes".
 
 After completing the screen analysis, use the `handle-comment` skill to post a QUESTION comment on any screen node where data fields are unclear or missing sources are identified.
 
@@ -327,17 +155,13 @@ After completing the screen analysis, use the `handle-comment` skill to post a Q
 
 1. Fetch the chapter and collect every row where `type === "actor"`, keyed by its `label`:
 
-   **Prefer MCP:**
+   **Prefer MCP** — `projection: "cells"` returns just `{rows, columns, cells}`, not the whole chapter node:
    ```
-   mcp__eventmodelers__get_node { "boardId": "$BOARD_ID", "nodeId": "$CHAPTER_ID" }
-   # → meta.timelineData.rows — collect every row where type === "actor" into { label → rowId }
+   mcp__eventmodelers__get_node { "boardId": "$BOARD_ID", "nodeId": "$CHAPTER_ID", "projection": "cells" }
+   # → rows — collect every row where type === "actor" into { label → rowId }
    ```
 
-   **Fallback (no MCP):**
-   ```bash
-   curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-     "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$CHAPTER_ID"
-   ```
+   **Fallback (no MCP):** see `references/api-fallback.md` — "Resolve One Actor Lane Per Human Role — Step 1: Fetch the chapter's actor rows".
 
 2. For every **human role only** in the Role Catalog (Step 1's swimlane list above), check the map for a `label` that matches the role name (case-insensitive). If found, reuse that `rowId`. **Skip system actors/processors entirely** — do not create or look up a lane for them here; they never get an entry in this map.
 
@@ -348,13 +172,7 @@ After completing the screen analysis, use the `handle-comment` skill to post a Q
    mcp__eventmodelers__add_lane { "boardId": "$BOARD_ID", "timelineId": "$CHAPTER_ID", "type": "actor", "label": "<Role Name>" }
    ```
 
-   **Fallback (no MCP):**
-   ```bash
-   curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$CHAPTER_ID/lanes" \
-     -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: storyboarding-events" \
-     -H "Content-Type: application/json" \
-     -d '{"type": "actor", "label": "<Role Name>"}'
-   ```
+   **Fallback (no MCP):** see `references/api-fallback.md` — "Resolve One Actor Lane Per Human Role — Step 3: Create a new actor lane".
 
    Add the returned `rowId` to the map under that role's name. Do this once per role, not once per screen.
 
@@ -445,7 +263,7 @@ Every screen node requires rendered content. **HTML_SCREEN (via the `html-screen
 
 **Step A — Compute the cell ID.** This applies to SCREEN nodes (human roles only) — AUTOMATION nodes follow "Placing Automations" below instead. Screens go in **that screen's own role's actor lane** in their target column — look up `actorRowId` from the role→lane map built above, keyed by the screen's role (e.g. "Admin", "User"). Never fall back to "the" actor lane as if there were only one.
 
-1. Determine the target column (same column as the event/command, OR one column to the right of the read model).
+1. Determine the target column (same column as the event/command for a command/input screen, OR the same column as the read model for a view/output screen — one column to the right only if that shared column isn't available).
 2. `actorRowId = roleLaneMap[<this screen's role>]` — the map was already resolved once for the whole chapter; do not re-fetch the chapter per screen. If this screen's role is genuinely new (wasn't in the original Role Catalog), resolve/create its lane now the same way (see above) and add it to the map before continuing.
 3. `cellId = actorRowId + "-" + columnId`
 
@@ -460,23 +278,16 @@ mcp__eventmodelers__create_screen {
   "chapterId": "<CHAPTER_ID>",
   "cellId": "<actorRowId>-<columnId>",
   "pages": ["<div>...</div>"],
-  "description": "<concise description of what this screen shows>"
+  "description": "<concise description of what this screen shows>",
+  "fields": [ /* per "Mandatory Field Definitions" below — set in this same call */ ]
 }
 ```
 
-**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: storyboarding-events" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "chapterId": "<CHAPTER_ID>",
-    "cellId": "<actorRowId>-<columnId>",
-    "pages": ["<div>...</div>"]
-  }'
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Mandatory Screen Rendering — Step B: Create the HTML_SCREEN node".
 
-Once the node is created, still set `meta.fields` on it (per "Mandatory Field Definitions" above) via `node:changed` — `create_screen`/the HTML endpoint owns page content, not the field-lineage metadata.
+The MCP `create_screen` call above already sets `meta.fields` (per "Mandatory Field Definitions" below) in the same call — no separate `node:changed` follow-up needed when using MCP.
+
+A storyboard screen is placed at a *provisional* position — Steps 4 and 5 wire it to its COMMAND / READMODEL once those exist, and may move it first. Pass `autoConnect: false` on `create_screen` / `create_screens` here so the placement doesn't pre-wire the screen to whatever happens to sit in the adjacent column; the real `SCREEN → COMMAND` and `READMODEL → SCREEN` edges are created deliberately in Steps 4 and 5. When creating several screens whose HTML is already authored, use `create_screens` (batch) with `autoConnect: false`.
 
 Design the page(s) as real HTML/CSS, following the `html-screen` skill's guidance: write full-size markup (16px body text, generous padding — the canvas scales it down, don't shrink it yourself), one complete self-contained fragment per page (no `<html>`/`<head>`/`<body>` wrapper — the canvas adds those), no `<script>`/inline handlers (stripped server-side), and Bulma CSS classes (`title`, `button`, `is-primary`, `field`/`control`/`input`, etc. — remember heading size modifiers like `class="title is-1"`) since Bulma 0.9.4 is loaded by default. Every page MUST include real field labels matching the actual event/command fields this screen captures or displays, and at least one primary action (submit/confirm button) for command screens.
 
@@ -501,22 +312,7 @@ mcp__eventmodelers__submit_node_events {
 }
 ```
 
-**Fallback (no MCP):**
-```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: storyboarding-events" \
-  -H "Content-Type: application/json" \
-  -d '[{
-    "id": "<event-uuid>",
-    "eventType": "node:created",
-    "nodeId": "<node-uuid>",
-    "boardId": "<BOARD_ID>",
-    "timestamp": 1234567890,
-    "chapterId": "<CHAPTER_ID>",
-    "cellId": "<actorRowId>-<columnId>",
-    "meta": {"type": "SCREEN", "title": "<Screen Title>", "fields": [...]}
-  }]'
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Mandatory Screen Rendering — Step B (sketch path): Create the SCREEN node".
 
 **Step C (sketch path only) — Render the wireframe sketch immediately** (`POST /images/$NODE_ID/sketch`).
 
@@ -541,21 +337,7 @@ mcp__eventmodelers__render_screen {
 }
 ```
 
-**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" -H "x-board-id: $BOARD_ID" -H "x-user-id: storyboarding-events" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "description": "<concise description of what this screen shows>",
-    "elements": [
-      {"type":"rectangle","gridX":0,"gridY":0,"gridWidth":50,"gridHeight":40,"fill":"white"},
-      {"type":"rectangle","gridX":0,"gridY":0,"gridWidth":50,"gridHeight":3,"fill":"violet"},
-      {"type":"headline","gridX":2,"gridY":1,"text":"Screen Title","fontSize":16,"fill":"white","gridWidth":46},
-      ...more elements...
-    ]
-  }'
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Mandatory Screen Rendering — Step C (sketch path): Render the wireframe sketch".
 
 Design each wireframe using the grid description language from the `storyboard-screen` skill (50×40 grid, 1 unit = 20 px):
 
@@ -587,17 +369,17 @@ When placing screens on the board, follow these alignment rules:
 | Screen type | Where it goes on the board |
 |-------------|---------------------------|
 | **Input/command screen** (triggers a command) | **The role's own actor lane, same column as the COMMAND and EVENT** it produces. The screen and command share a column — the screen sits in that role's actor lane, the command in the interaction row, the event in the swimlane row. |
-| **View/output screen** (displays a read model) | **The role's own actor lane, one column to the RIGHT of the READ MODEL** it displays. The read model occupies the interaction row of the preceding column; the screen gets its own column immediately after. This column is finalised in Step 5 (Identifying Outputs) — during storyboarding, just document which read model each view screen will query. |
+| **View/output screen** (displays a read model) | **The role's own actor lane, the SAME column as the READ MODEL** it displays (READMODEL in the interaction row, screen in the actor row — a downward connection, not a backward one). Only bumps one column to the right if that column's interaction row is already taken by something else. If the screen displays more than one read model, only the primary one shares its column — every additional read model goes further left. This column is finalised in Step 5 (Identifying Outputs) — during storyboarding, just document which read model each view screen will query. |
 
-> **Do not create standalone screen columns that are disconnected from commands or read models.** Every screen must either share its column with the command it submits, or be placed one column to the right of the read model it displays.
+> **Do not create standalone screen columns that are disconnected from commands or read models.** Every screen must either share its column with the command it submits, or share its column with the (primary) read model it displays.
 
 ### Multi-component screens are broken apart in Step 5, not here
 
-Storyboarding renders **one plain screen per screen state** — do not pre-split a screen into per-component copies here. Deciding how many components a view screen actually has, and breaking it apart into one highlighted copy per component, is `eventmodeling-identifying-outputs`'s job (its "Step 5a — Enumerate consumers and identify components" and "Step 5c — Break apart multi-component screens into copies"), because a component is defined by its read model and read models aren't designed until Step 5. During storyboarding, just place the single screen one column to the right of where its read model will end up (per the table above); document which read model it will query even before that read model exists.
+Storyboarding renders **one plain screen per screen state** — do not pre-split a screen into per-component copies here. Deciding how many components a view screen actually has, and breaking it apart into one highlighted copy per component, is `eventmodeling-identifying-outputs`'s job (its "Step 5a — Enumerate consumers and identify components" and "Step 5c — Break apart multi-component screens into copies"), because a component is defined by its read model and read models aren't designed until Step 5. During storyboarding, just place the single screen in the same column where its read model will end up (per the table above); document which read model it will query even before that read model exists.
 
 ### Placing Automations
 
-When a processor or system actor reacts to events automatically (no human interaction), place an **AUTOMATION** node in the chapter's **default actor lane** instead of a SCREEN — never create, reuse, or look up a per-system-actor lane for it, and never resolve it through the human role→lane map above. Automations go in the same column as the COMMAND they trigger and the READMODEL that feeds them.
+When a processor or system actor reacts to events automatically (no human interaction), place an **AUTOMATION** node in the chapter's **default actor lane** instead of a SCREEN — never create, reuse, or look up a per-system-actor lane for it, and never resolve it through the human role→lane map above. Automations go in the same column as the COMMAND they trigger. Unlike a view screen, an automation's READMODEL is never in that same column — the automation's own column already holds the COMMAND it issues (interaction row), so the read model that feeds it always goes one column to the left.
 
 **Do not design automation actor lanes to mimic human ones.** A "Payment Processor" or "Inventory System" swimlane in the narrative report (Step 5 above) is a documentation grouping only — it must never be materialized as its own labeled `actor`-type lane on the board. Only human roles get a physical lane; every automation, regardless of which system actor it narratively belongs to, renders in the same shared default actor lane.
 
@@ -639,95 +421,7 @@ If a second role also needs a screen related to the same event, insert a new col
 
 ## Output Format
 
-Present as:
-
-```markdown
-# Storyboard: [Domain Name]
-
-## Swimlane Organization (from Role Catalog)
-
-### Human Role Swimlanes
-
-#### Customer Swimlane
-- Screen 1: Order Entry Form
-- Screen 2: Order Confirmation
-- Screen 3: Order Status View
-
-#### [Other Human Role Swimlanes — one per role in the catalog]
-
-### System Actor Swimlanes
-
-_(Narrative grouping only — these are not physical board lanes. Every automation below renders in the chapter's shared default actor lane; see "Placing Automations".)_
-
-#### Payment Processor Swimlane
-- Screen 1: Payment Verification (automated)
-- [Shows what UI/views the processor interacts with]
-
-#### [Other System Actor Swimlanes]
-
----
-
-## Screen 1: [Screen Name]
-
-### Mockup
-```
-[ASCII art mockup or description]
-```
-
-### Data Displayed
-- Field 1: Description, source event
-- Field 2: Description, source event
-
-### User Actions (Commands)
-- Action: [Action], produces: [Event]
-
-### Business Rules
-- Rule about what can/cannot be done on this screen
-
----
-
-## Screen 2: [Screen Name]
-
-[Repeat for each screen]
-
----
-
-## Processor Todo Lists
-
-### Processor: [Processor Name]
-
-Internal "Todo List" pattern:
-```
-Triggered by: [Event type]
-Todo action: [What needs to be done]
-Success produces: [Event]
-Failure produces: [Event]
-```
-
-[Repeat for each processor]
-
----
-
-## Data Flow Diagram
-
-[Show how data enters from UI and returns via events]
-
----
-
-## Field Traceability Matrix
-
-| Field | Screen | Source Event | Status |
-|-------|--------|-------------|--------|
-| orderId | Status View | OrderCreated |  |
-| shipmentId | Status View | OrderShipped |  |
-| customerId | All | OrderCreated |  |
-
----
-
-## Missing Data Analysis
-
-[Any fields without clear source or destination]
-```
+Older versions of this skill wrote the storyboard as a markdown document (swimlane organization, one section per screen, processor todo lists, a field traceability matrix) rather than rendering and placing screen nodes on the board — that legacy template is kept in `references/examples.md` for reference only; it is not the actual output mechanism. The actual output is the rendered HTML_SCREEN/AUTOMATION nodes placed per "Mandatory Screen Rendering" and "Timeline Placement Rules" above.
 
 ## Quality Checklist
 

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-storyboarding-events/references/api-fallback.md

@@ -0,0 +1,77 @@
+# Storyboarding Events — curl Fallback Calls
+
+Only needed when MCP is not connected. Every call below has an MCP equivalent in the main SKILL.md — always prefer that.
+
+## Board Integration — Check existing screen nodes
+
+```bash
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=HTML_SCREEN"
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=SCREEN"
+```
+
+## Resolve One Actor Lane Per Human Role — Step 1: Fetch the chapter's actor rows
+
+```bash
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$CHAPTER_ID"
+```
+
+## Resolve One Actor Lane Per Human Role — Step 3: Create a new actor lane
+
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$CHAPTER_ID/lanes" \
+  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: storyboarding-events" \
+  -H "Content-Type: application/json" \
+  -d '{"type": "actor", "label": "<Role Name>"}'
+```
+
+## Mandatory Screen Rendering — Step B: Create the HTML_SCREEN node
+
+```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: storyboarding-events" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "chapterId": "<CHAPTER_ID>",
+    "cellId": "<actorRowId>-<columnId>",
+    "pages": ["<div>...</div>"]
+  }'
+```
+Then, over REST only (no `fields` param on the HTML-screen endpoint), still set `meta.fields` via a separate `node:changed` call.
+
+## Mandatory Screen Rendering — Step B (sketch path): Create the SCREEN node
+
+```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: storyboarding-events" \
+  -H "Content-Type: application/json" \
+  -d '[{
+    "id": "<event-uuid>",
+    "eventType": "node:created",
+    "nodeId": "<node-uuid>",
+    "boardId": "<BOARD_ID>",
+    "timestamp": 1234567890,
+    "chapterId": "<CHAPTER_ID>",
+    "cellId": "<actorRowId>-<columnId>",
+    "meta": {"type": "SCREEN", "title": "<Screen Title>", "fields": [...]}
+  }]'
+```
+
+## Mandatory Screen Rendering — Step C (sketch path): Render the wireframe 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: storyboarding-events" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "description": "<concise description of what this screen shows>",
+    "elements": [
+      {"type":"rectangle","gridX":0,"gridY":0,"gridWidth":50,"gridHeight":40,"fill":"white"},
+      {"type":"rectangle","gridX":0,"gridY":0,"gridWidth":50,"gridHeight":3,"fill":"violet"},
+      {"type":"headline","gridX":2,"gridY":1,"text":"Screen Title","fontSize":16,"fill":"white","gridWidth":46},
+      ...more elements...
+    ]
+  }'
+```