@eventmodelers/cli 1.0.123 → 1.0.125

package/README.md

@@ -106,6 +106,7 @@ Use skills in Claude Code with `/skill-name`:
 | `/connect` | Set up board connection |
 | `/timeline` | Live event storming facilitator |
 | `/wdyt` | Business analyst review of your event model |
+| `/walkthrough` | Step-by-step player through a process, or through everything a planned change touches |
 | `/storyboard` | Build a full visual storyboard |
 | `/html-screen` | Design individual real HTML/CSS screens (default) |
 | `/storyboard-screen` | Design individual wireframe/sketch screens (explicit request only) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.123",
+  "version": "1.0.125",
   "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/learn-eventmodelers-api/SKILL.md

@@ -30,7 +30,7 @@ Write tools take their items as an array (`nodeIds[]`, `elements[]`, `connection
 | `get_node` | `boardId`, `nodeId`, `projection?` (`"cells"` \| `"edges"`) | Get one node (no `cellName` — address it by `nodeId`; cell addresses come only from `get_board_outline`). `projection: "cells"` (CHAPTER nodes only) returns just `{rows, columns, cells}` instead of the full `timelineData` — use whenever only the grid/occupancy is needed, not the whole chapter; `projection: "edges"` returns just that node's inbound/outbound connections instead of `findNodeById`'s full record. Both are opt-in — omitting `projection` is the unchanged full response. An unknown id is a `NODE_NOT_FOUND` error | §3 `GET .../nodes/:nodeId` (REST returns the node as stored, without `cellName`; `404` carries `code: 'NODE_NOT_FOUND'`) |
 | `get_node_comments` | `boardId`, `nodeId` | List comments on a node | §1 `GET .../nodes/:nodeId/comments` |
 | `get_chat_attachment` | `boardId`, `sessionId`, `attachmentId` | The file a chat message came with — the message's `attachments` list `{id, type, ending}`. Images come back as images, a PDF as an embedded resource, csv / xml / txt / json as text. Only the agent the message was addressed to can read it (`CHAT_ATTACHMENT_NOT_FOUND`); needs the connection's `x-agent-id` (`CHAT_AGENT_REQUIRED`). Max 5 MB per file. | §15 `GET /api/org/:orgId/chat/sessions/:sessionId/attachments/:attachmentId` |
-| `post_chat_message` | `boardId`, `text`, `replyTo?`, `sessionId?`, `preferUserId?`, `snippet?` | Write into a person's chat — a reply (`replyTo` marks their message answered) or a question you start (`preferUserId`). `text` ≤ 1000 characters. `snippet` attaches one interactive element under the text (confirm, poll, tasks, changes, link, image, code, report); the person's choice comes back as their next chat message. See §16 | §16 `POST /api/org/:orgId/boards/:boardId/chat/agent-messages` |
+| `post_chat_message` | `boardId`, `text`, `replyTo?`, `sessionId?`, `preferUserId?`, `snippet?` | Write into a person's chat — a reply (`replyTo` marks their message answered) or a question you start (`preferUserId`). `text` ≤ 1000 characters. `snippet` attaches one interactive element under the text (confirm, poll, tasks, changes, link, image, code, report, walkthrough); the person's choice comes back as their next chat message. See §16 | §16 `POST /api/org/:orgId/boards/:boardId/chat/agent-messages` |
 | `get_board_events` | `boardId`, `since?`, `seq?` | A page of at most 300 board events, oldest first, as `{events, pageSize, hasMore}`. Not the whole log: while `hasMore` is true, page on by passing the last event's `seq` as `since`. `seq` returns only the event of exactly that seq | §1 `GET .../events` |
 | `submit_node_events` | `boardId`, `events[]`, `autoConnect?`, `compact?` | Create/update nodes (raw `NodeChangeEvent`/edge events). Every event property is described on the tool's own `events[]` schema — read that rather than this skill when all you need is the event shape. An event needs its own `id` (required — a fresh uuid per event, never the node id) and its `eventType`, plus the keys of its kind (`nodeId`/`meta`/`node`, or `edgeId`/`source`/`target`). The `id` keys the returned `hashes` map and makes a resubmit idempotent — the same event sent twice under one id writes a single board event. Don't send `boardId` or `timestamp` per event — the server takes the board from the call and stamps the time itself, and ignores both if sent. `autoConnect: false` places freshly-created nodes without wiring them to their own/previous-column neighbors (avoids a stray nearest-left edge); `compact: true` returns `{persisted: <count>}` instead of the per-node hash map | §3 `POST .../nodes/events` |
 | `delete_node` | `boardId`, `nodeIds[]` | Delete nodes, applied in order — one failure doesn't stop the rest; answers `{results}`. Deleting a chapter (timeline) cascades — every node placed in one of its cells, plus any node parented to it (e.g. SLICE_BORDER), is deleted too, along with all their edges | (via `node:deleted` event, §3) |
@@ -1120,8 +1120,9 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
 | to show a picture | `image` | nothing |
 | to show a command or payload | `code` | nothing |
 | to show numbers as a diagram (counts per slice, a trend, shares of a whole) | `report` | nothing |
+| to explain how a process works, or walk through what a planned change touches, step by step ("how does registration work?", "we need to add an email — walk me through it") | `walkthrough` | nothing — selecting a step pans the canvas |
 
-`confirm`, `poll`, `tasks` and `changes` are questions: a person answers once, then they show as answered. `link`, `image`, `code` and `report` are display only and never wait for anything.
+`confirm`, `poll`, `tasks` and `changes` are questions: a person answers once, then they show as answered. `link`, `image`, `code`, `report` and `walkthrough` are display only and never wait for anything.
 
 ### Shapes
 ```typescript
@@ -1143,6 +1144,13 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
   labels: string[],                                                               // 1–50 points: x axis, or the pie slices
   series: Array<{ name: string, values: number[] }>,                             // one number per label; bar/line up to 6 series, pie uses only the first (no negatives)
   confirm?: { headline: string, yesLabel?: string, noLabel?: string } }          // optional yes/no question under the diagram, like a confirm snippet
+{ kind: 'walkthrough', title: string, intro?: string,                             // a step-by-step player through a process
+  steps: Array<{ title: string,                                                   // 1+, in the order the process runs
+                 description?: string,                                            // what happens in this step, in business words
+                 nodeId?: string,                                                 // the element, slice (SLICE_BORDER) or scenario (SCENARIO) of this step — selecting the step zooms to it
+                 screenId?: string,                                               // the SCREEN / HTML_SCREEN the person sees in this step
+                 rules?: string[],                                                // business rules that apply in this step
+                 changes?: string[] }> }                                          // for a planned change: what has to change here
 ```
 
 ### How to use them
@@ -1153,6 +1161,7 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
 - **Answers are text.** For a `tasks` answer, match the titles (or ids) back to your list; an element the person left unticked was declined, not forgotten. A `poll` option with a `message` of your own makes the answer unambiguous.
 - `get_chat_session` shows your snippet on the message as `snippet`, and the person's answer is the user message after it, carrying `context.snippetReply.messageId` (your message's id) — useful to tell an answer to a snippet from a new message.
 - **`report`** draws the numbers you send — it computes nothing, so aggregate first. A series whose length differs from `labels`, or a non-number, makes the whole snippet invisible. Keep `text` as a one-line summary of what the diagram shows. Add `confirm` when the diagram leads to a follow-up question ("Want me to look into the backward arrows?"): the answer comes back like a `confirm` answer, and without it the report is display only.
+- **`walkthrough`** answers "how does X work?" and "walk me through what changes for Y": the person steps back and forth through the process in the chat, each step zooming the canvas to its element, and **Play** opens it full-screen as a movie strip of the steps' screens with description and rules underneath. Build it from the board, never from memory — the `walkthrough` skill (modeling kit) has the procedure. Every `nodeId`/`screenId` must be a real id from this board; a step without a screen just shows its element. Keep `text` to one line naming the process and the number of steps.
 - A snippet is shown exactly as you send it — keep secrets and tokens out of `code` and `image`.
 
 ---

package/stacks/modeling-kit/templates/.claude/skills/detect-model-drift/SKILL.md

@@ -65,11 +65,10 @@ Index the result in memory: per slice → commands, events, read models, screens
 
 The code base is the directory resolved in Step 0 (`$EVENTMODELERS_CODE_DIR`, else the current directory) — every path below is relative to it, and it may hold any stack. Find out which, don't assume.
 
-**With a `branch` other than the one checked out, read the code from git, never from the working tree:** `git ls-tree -r --name-only $REF [<dir>]` lists the files, `git show $REF:<path>` reads one. That applies to everything below — `.build-kit/CLAUDE.md`, the `.build-kit/.slices` snapshot, the slice folders. Never `git checkout`/`git switch`: the working tree may hold someone's uncommitted work. Without `branch`, or when it is the current branch, read the working tree as usual.
+**With a `branch` other than the one checked out, read the code from git, never from the working tree:** `git ls-tree -r --name-only $REF [<dir>]` lists the files, `git show $REF:<path>` reads one. That applies to everything below — `.build-kit/CLAUDE.md`, the slice folders. Never `git checkout`/`git switch`: the working tree may hold someone's uncommitted work. Without `branch`, or when it is the current branch, read the working tree as usual.
 
 1. Read `.build-kit/CLAUDE.md` (and `.build-kit/AGENTS.md` if present) — its *Structure* section says where slices live and how they're named (e.g. `src/slices/{slice}/` for Node, `src/main/java/.../slices/{context}/{slice}/` for Axon).
-2. If `.build-kit/.slices/<context>/<slice>/slice.json` exists, it is the snapshot the code was **last built from** — useful for telling "the code changed" apart from "the model changed since the build" (see Step 5).
-3. Without a build kit, infer the layout from the repo (folders named after slices, `*Command*`, `*Event*`, projection/read-model files, route/UI files). If you cannot find any slice structure, stop and tell the user what you looked at — do not fabricate a mapping.
+2. Without a build kit, infer the layout from the repo (folders named after slices, `*Command*`, `*Event*`, projection/read-model files, route/UI files). If you cannot find any slice structure, stop and tell the user what you looked at — do not fabricate a mapping.
 
 Build a **code inventory** per slice folder: the command type and its fields, the events it emits and their fields, read-model/projection types and fields, the screens/components/routes wired to it, tests and what they assert, and what each handler/projection/automation reads and writes.
 
@@ -109,9 +108,7 @@ For every finding, pick who should move:
 
 | Evidence | Fix goes to | How it's done |
 |----------|-------------|---------------|
-| Code differs from `.build-kit/.slices` snapshot (read from the same branch as the code), board still equals the snapshot | **Model** — the code moved on deliberately | Skill that changes the board: `/attributes` (fields), `/timeline` / `/place-element` (elements), `/eventmodeling-elaborating-scenarios` (specs), `/storyboard-screen` or `/html-screen` (screens — including updating every existing screen connected to a changed element, see below) |
-| Board differs from the snapshot, code still equals it | **Code** — the model moved on | Set the slice back to `Planned` with `/update-slice-status` so the build kit picks it up again and diffs code against `slice.json` |
-| Both moved, or no snapshot | **Judgement call** — present both options, recommend one | Recommend by which side is more specific/complete |
+| A field, element, spec, screen or edge differs | **Judgement call** — present both options, recommend one | Recommend by which side is more specific/complete. Model fix: `/attributes` (fields), `/timeline` / `/place-element` (elements), `/eventmodeling-elaborating-scenarios` (specs), `/storyboard-screen` or `/html-screen` (screens — including updating every existing screen connected to a changed element, see below). Code fix: set the slice back to `Planned` with `/update-slice-status` so the build kit picks it up again |
 | Slice only in code | **Model** | Add the slice, via `/eventmodeling-slicing-event-models` after placing its elements |
 | Slice missing in code, board says `Done` | **Model status** (it isn't done) | `/update-slice-status` → `Planned` |
 
@@ -190,3 +187,4 @@ Omit empty sections. Say plainly when nothing drifted.
 - Fixing drift on the model side means updating the existing screens connected to the changed elements too (pages and `meta.fields`), in place — not just the command/event/read model.
 - `--branch` reads the code via `git ls-tree`/`git show` from that ref — never check it out, the working tree may hold someone's uncommitted work. No `--branch` = the working tree, as before.
 - Always read the MARKDOWN note in the feedback lane of each chapter's first column first — it is the chapter's context, and differences it explains are not drift.
+- `.build-kit/.slices` is no evidence for the direction of a fix: every fetch, `/load-slice` and runner loop rewrites it, so it holds the last fetch, not what the code was built from — reading it as "the build" recommends undoing board changes. The direction is a judgement call.

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

@@ -235,7 +235,8 @@ mcp__eventmodelers__submit_node_events {
     "changedAttributes": ["meta.title"],
     "meta": { "type": "CHAPTER", "title": "<flow name>" },
     "node": { "id": "<CHAPTER_ID>", "data": {} }
-  }]
+  }],
+  "compact": true
 }
 ```
 

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

@@ -116,7 +116,8 @@ mcp__eventmodelers__submit_node_events {
     "eventType": "node:changed",
     "nodeId": "<chapterId>",
     "meta": {"type": "CHAPTER", "title": "Reservation & Lending"}
-  }]
+  }],
+  "compact": true
 }
 ```
 
@@ -219,7 +220,8 @@ mcp__eventmodelers__submit_node_events {
         {"name": "reservedAt",    "type": "DateTime", "example": "2026-05-29T10:00:00Z"}
       ]
     }
-  }]
+  }],
+  "compact": true
 }
 ```
 

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-designing-automation-chains/SKILL.md

@@ -88,7 +88,8 @@ mcp__eventmodelers__place_element {
     "elementType": "READMODEL",
     "title": "NotificationsToSend",
     "columnIndex": <automationColumnIndex - 1>
-  }]
+  }],
+  "compact": true
 }
 ```
 Then set `meta.fields` and `meta.listElement: true` on the returned node id:
@@ -98,7 +99,8 @@ mcp__eventmodelers__submit_node_events {
   "events": [{
     "id": "<event-uuid>", "eventType": "node:changed", "nodeId": "<returned-node-id>",
     "meta": {"type": "READMODEL", "title": "NotificationsToSend", "fields": [...], "listElement": true}
-  }]
+  }],
+  "compact": true
 }
 ```
 
@@ -114,11 +116,11 @@ For a **translation-chain automation**, place its three columns left to right in
 
 1. **READMODEL → AUTOMATION first** — the automation reads its own todo list. The closing connection below is only accepted once this edge exists.
    ```
-   mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "connections": [{ "source": "<readmodelNodeId>", "target": "<automationNodeId>", "action": "connect" }] }
+   mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "connections": [{ "source": "<readmodelNodeId>", "target": "<automationNodeId>", "action": "connect" }], "compact": true }
    ```
 2. **Every opening EVENT → READMODEL.**
    ```
-   mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "connections": [{ "source": "<openingEventNodeId>", "target": "<readmodelNodeId>", "action": "connect" }] }
+   mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "connections": [{ "source": "<openingEventNodeId>", "target": "<readmodelNodeId>", "action": "connect" }], "compact": true }
    ```
 3. **Every closing EVENT → READMODEL — worker-stage todo lists only.** Including the automation's own resulting event, even though that event is produced by the command this same automation issues. This is not a backward arrow: `EVENT → READMODEL` connections are exempt from column ordering when the read model already has a `READMODEL → AUTOMATION` edge (see `learn-eventmodelers-api` §3) — this todo-list read model qualifies because of the edge from step 1 above. A read model in this shape is a live projection, not a frozen snapshot — a later event closing an earlier-opened item is the normal case, not an exception to reach for only when convenient. **Do not add this edge for a translation automation's todo list** — it has no closing event at all (see the translation-chain rule above); wiring one back is a modeling error, not a convenience.
 

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-identifying-inputs/SKILL.md

@@ -151,7 +151,8 @@ mcp__eventmodelers__place_element {
   "elements": [{
     "elementType": "COMMAND",
     "title": "ReserveBike"
-  }]
+  }],
+  "compact": true
 }
 ```
 `place_element` finds/creates the empty cell in the interaction lane in the correct column and places the node. Pass each entry's `fields` in the same call when the attributes are already known; otherwise follow up with `submit_node_events` (`node:changed`) to set `meta.fields` (with `mapping`/`generated`/`cardinality` per the rules above) on the node it returned:
@@ -171,7 +172,8 @@ mcp__eventmodelers__submit_node_events {
         {"name": "startTime",  "type": "DateTime", "example": "2026-06-01T09:00:00Z","mapping": "user-input"}
       ]
     }
-  }]
+  }],
+  "compact": true
 }
 ```
 
@@ -203,7 +205,7 @@ After `place-element` returns the COMMAND node ID, create the arrows that comple
    ```
    Read `cells["<actorRowId>-<columnId>"]` for the occupying node id (a cell id absent from that sparse array is empty — no SCREEN placed yet). Then connect with the type-checked edge tool, which auto-corrects direction and skips duplicates:
    ```
-   mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "connections": [{ "source": "<screenNodeId>", "target": "<commandNodeId>", "action": "connect" }] }
+   mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "connections": [{ "source": "<screenNodeId>", "target": "<commandNodeId>", "action": "connect" }], "compact": true }
    ```
    If wiring more than one COMMAND in the same pass, put every SCREEN→COMMAND and COMMAND→EVENT pair across all of them into one `set_connection` call's `connections` array (see step 2 below) instead of one call per pair.
 
@@ -219,7 +221,7 @@ After `place-element` returns the COMMAND node ID, create the arrows that comple
    ```
    Read `cells["<swimlaneRowId>-<columnId>"]` for the occupying node id, then:
    ```
-   mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "connections": [{ "source": "<commandNodeId>", "target": "<eventNodeId>", "action": "connect" }] }
+   mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "connections": [{ "source": "<commandNodeId>", "target": "<eventNodeId>", "action": "connect" }], "compact": true }
    ```
 
    **Fallback (no MCP):** see `references/api-fallback.md` — "Wire connections — Step 2: COMMAND → EVENT".

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-identifying-outputs/SKILL.md

@@ -260,7 +260,8 @@ mcp__eventmodelers__place_element {
     "elementType": "READMODEL",
     "title": "ActiveReservationView",
     "columnIndex": <consumerScreenColumnIndex>  // or <automationColumnIndex - 1> for an AUTOMATION consumer
-  }]
+  }],
+  "compact": true
 }
 ```
 Then set `meta.fields` (with `mapping`/`generated`/`cardinality`) — and `meta.listElement: true` if this read model is list-shaped — on the returned node id:
@@ -270,7 +271,8 @@ mcp__eventmodelers__submit_node_events {
   "events": [{
     "id": "<event-uuid>", "eventType": "node:changed", "nodeId": "<returned-node-id>",
     "meta": {"type": "READMODEL", "title": "ActiveReservationView", "fields": [...]}
-  }]
+  }],
+  "compact": true
 }
 ```
 To determine the consumer's column index beforehand, or to check whether a specific interaction cell is already occupied (`get_nodes` filters by `type`, `name`, `chapterId` and `nodeIds`, but has no `cellId` filter — see the note under "Wire connections" below), fetch the chapter and read its cell map — `projection: "cells"` returns just `{rows, columns, cells}`, not the whole chapter node:
@@ -327,7 +329,7 @@ After `place-element` returns the READMODEL node ID, create the arrows that comp
    ```
    mcp__eventmodelers__get_node { "boardId": "<BOARD_ID>", "nodeId": "<CHAPTER_ID>", "projection": "cells" }
    # → read cells["<swimlaneRowId>-<columnId>"] for the occupying node id
-   mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "connections": [{ "source": "<eventNodeId>", "target": "<readmodelNodeId>", "action": "connect" }] }
+   mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "connections": [{ "source": "<eventNodeId>", "target": "<readmodelNodeId>", "action": "connect" }], "compact": true }
    ```
 
    **Fallback (no MCP):** see `references/api-fallback.md` — "Step 5h.1 — Wire EVENT → READMODEL".
@@ -336,7 +338,7 @@ After `place-element` returns the READMODEL node ID, create the arrows that comp
 
    **Prefer MCP:**
    ```
-   mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "connections": [{ "source": "<readmodelNodeId>", "target": "<screenNodeId>", "action": "connect" }] }
+   mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "connections": [{ "source": "<readmodelNodeId>", "target": "<screenNodeId>", "action": "connect" }], "compact": true }
    ```
 
    **Fallback (no MCP):** see `references/api-fallback.md` — "Step 5h.2 — Wire READMODEL → SCREEN".
@@ -347,7 +349,7 @@ After `place-element` returns the READMODEL node ID, create the arrows that comp
 
    **Prefer MCP:**
    ```
-   mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "connections": [{ "source": "<readmodelNodeId>", "target": "<automationNodeId>", "action": "connect" }] }
+   mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "connections": [{ "source": "<readmodelNodeId>", "target": "<automationNodeId>", "action": "connect" }], "compact": true }
    ```
 
    **Fallback (no MCP):** see `references/api-fallback.md` — "Step 5h.3 — Wire READMODEL → AUTOMATION".

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-orchestrating-event-modeling/SKILL.md

@@ -163,7 +163,7 @@ For a "what is on the board and how is it wired right now" check between steps
 
 **Structural validation is one call, not a scan.** `validate_model` (`{boardId, chapterId}`) runs the whole structural checklist server-side — unplaced nodes, backward arrows (todo-list exception applied), zero/multi-issuer commands, sourceless read models, two-screens-in-a-column, missing scenarios — and returns only `findings`. Use it for the mandatory post-step unplaced check and as the first move in Step 9, instead of per-type `get_nodes` loops and `get_node` `projection: "edges"` spot-checks.
 
-**Ask echo-heavy write tools for less.** `add_scenario`, `add_storyline`, `set_connection` and `submit_node_events` each accept `compact: true`, which drops the full-object echo from the response (returning `{specNodeId, added, count, isNewNode}`, a `{connected, existed, removed, notFound, failed, errors}` tally, or `{persisted: <count>}` respectively). Pass it whenever you're not going to read individual fields back off the response — which is almost always for a large `set_connection` batch or a bulk scenario post.
+**Ask echo-heavy write tools for less.** `place_element`, `add_scenario`, `add_storyline`, `set_connection` and `submit_node_events` each accept `compact: true`, which drops the full-object echo from the response (returning `{nodeId, cellName, columnIndex}` per placed node, `{specNodeId, added, count, isNewNode}`, a `{connected, existed, removed, notFound, failed, errors}` tally, or `{persisted: <count>}` respectively). Pass it by default — every example in these skills does — and drop it only when a later step reads a field the compact form leaves out (e.g. `place_element`'s `autoConnected` edge list). Failures are still reported in full either way.
 
 ### Documenting decisions inline, at any step
 
@@ -440,7 +440,8 @@ Not delegated to a separate skill — performed directly by this orchestrating s
        "id": "<event-uuid>", "eventType": "node:created", "nodeId": "<node-uuid>",
        "chapterId": "$CHAPTER_ID", "cellId": "<feedbackLaneId>-<firstColumnId>",
        "meta": { "type": "MARKDOWN", "title": "Modeling Reasoning — <Chapter Name>", "description": "<full markdown body>" }
-     }]
+     }],
+     "compact": true
    }
    ```
 

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

@@ -263,7 +263,8 @@ mcp__eventmodelers__submit_node_events {
     "chapterId": "<CHAPTER_ID>",
     "cellId": "<actorRowId>-<columnId>",
     "meta": {"type": "SCREEN", "title": "<Screen Title>", "fields": [...]}
-  }]
+  }],
+  "compact": true
 }
 ```
 

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

@@ -105,7 +105,8 @@ mcp__eventmodelers__submit_node_events {
     "nodeId": "<TARGET_NODE.id>",
     "changedAttributes": ["meta.fields"],
     "meta": { "fields": "<updated-fields-array>" }
-  }]
+  }],
+  "compact": true
 }
 ```
 

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

@@ -105,7 +105,8 @@ mcp__eventmodelers__submit_node_events {
       "marks": [{"id": "em-abc123", "color": "#e74c3c", "pageIndex": 0, "blurOutside": true, "whiteOutside": false}],
       "fields": [...]
     }
-  }]
+  }],
+  "compact": true
 }
 ```
 
@@ -181,7 +182,8 @@ mcp__eventmodelers__submit_node_events {
     "meta": { "type": "HTML_SCREEN", "fields": [
       {"name": "status", "type": "String", "example": "confirmed", "mapping": "ActiveReservationView.status", "cardinality": "Single"}
     ] }
-  }]
+  }],
+  "compact": true
 }
 ```
 

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

@@ -50,7 +50,8 @@ mcp__eventmodelers__place_element {
     "columnIndex": <position,
     if given>,
     "fields": [{ "name": "orderId", "type": "String", "example": "ord-1" }]
-  }]
+  }],
+  "compact": true
 }
 ```
 
@@ -132,7 +133,8 @@ mcp__eventmodelers__add_scenario {
   "boardId": "<BOARD_ID>",
   "timelineId": "<TL>",
   "columnId": "<COL>",
-  "scenarios": [ /* same scenario objects as the curl body below */ ]
+  "scenarios": [ /* same scenario objects as the curl body below */ ],
+  "compact": true
 }
 ```
 
@@ -335,7 +337,8 @@ mcp__eventmodelers__submit_node_events {
     "cellId": "<CELL_ID>",
     "meta": { "type": "<ELEMENT_TYPE>", "title": "<title>" },
     "node": { "data": { "title": "<title>" } }
-  }]
+  }],
+  "compact": true
 }
 ```
 
@@ -356,7 +359,8 @@ mcp__eventmodelers__submit_node_events {
     "cellName": "<CELL_NAME>",
     "meta": { "type": "<ELEMENT_TYPE>", "title": "<title>" },
     "node": { "data": { "title": "<title>" } }
-  }]
+  }],
+  "compact": true
 }
 ```
 
@@ -385,7 +389,7 @@ Take the inbound edges (`target === COMMAND_NODE_ID`) and resolve their source t
 - **2 or more** → keep the edge whose source sits in the COMMAND's own column (the deliberate, same-slice issuer) and remove every other one:
 
 ```
-mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "connections": [{ "source": "<extra-issuer-node-id>", "target": "<COMMAND_NODE_ID>", "action": "remove" }] }
+mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "connections": [{ "source": "<extra-issuer-node-id>", "target": "<COMMAND_NODE_ID>", "action": "remove" }], "compact": true }
 ```
 
 If it's not clear which edge is the deliberate one (e.g. neither source sits in the COMMAND's own column), do not guess — leave both edges and post a comment on the COMMAND node via `handle-comment` instead, describing the ambiguity.
@@ -416,4 +420,4 @@ Timeline: <timelineId>
 
 ## Example — place an EVENT via curl
 
-A full worked example (add column → fetch chapter → create node) placing an EVENT called "Order Placed" at the end of a timeline lives in `references/api-fallback.md`'s "Full worked example" section. With MCP connected, the same result is one call: `mcp__eventmodelers__place_element { "boardId": "<BOARD_ID>", "timelineId": "<TIMELINE_ID>", "elements": [{ "elementType": "EVENT", "title": "Order Placed" }] }` (see "Prefer MCP" above).
+A full worked example (add column → fetch chapter → create node) placing an EVENT called "Order Placed" at the end of a timeline lives in `references/api-fallback.md`'s "Full worked example" section. With MCP connected, the same result is one call: `mcp__eventmodelers__place_element { "boardId": "<BOARD_ID>", "timelineId": "<TIMELINE_ID>", "elements": [{ "elementType": "EVENT", "title": "Order Placed" }], "compact": true }` (see "Prefer MCP" above).

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

@@ -230,7 +230,8 @@ mcp__eventmodelers__submit_node_events {
     "id": "<event-uuid>", "eventType": "node:changed", "nodeId": "<SCREEN_NODE_ID>",
     "changedAttributes": ["meta.fields"],
     "meta": { "type": "HTML_SCREEN", "fields": [ /* planned fields */ ] }
-  }]
+  }],
+  "compact": true
 }
 ```
 

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

@@ -126,7 +126,8 @@ mcp__eventmodelers__submit_node_events {
     "meta": { "type": "SCREEN", "fields": [
       {"name": "status", "type": "String", "example": "confirmed", "mapping": "ActiveReservationView.status", "cardinality": "Single"}
     ] }
-  }]
+  }],
+  "compact": true
 }
 ```
 

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

@@ -290,7 +290,8 @@ mcp__eventmodelers__submit_node_events {
     "cellId": "<CELL_ID>",
     "meta": { "type": "EVENT", "title": "<EventName>" },
     "node": { "id": "<node-uuid>", "data": { "title": "<EventName>" } }
-  }]
+  }],
+  "compact": true
 }
 ```
 
@@ -300,7 +301,7 @@ mcp__eventmodelers__submit_node_events {
 
 **Prefer MCP:** this whole "find/create a column, compute the cell, place the node" sequence collapses into one call:
 ```
-mcp__eventmodelers__place_element { "boardId": "<BOARD_ID>", "timelineId": "<CHAPTER_ID>", "elements": [{ "elementType": "EVENT", "title": "<EventName>", "columnIndex": <index> }] }
+mcp__eventmodelers__place_element { "boardId": "<BOARD_ID>", "timelineId": "<CHAPTER_ID>", "elements": [{ "elementType": "EVENT", "title": "<EventName>", "columnIndex": <index> }], "compact": true }
 ```
 Extract `nodeId` and `columnId` directly from the tool result.
 
@@ -343,7 +344,8 @@ mcp__eventmodelers__submit_node_events {
     "changedAttributes": ["meta.title"],
     "meta": { "type": "EVENT", "title": "<NewTitle>" },
     "node": { "id": "<eventNodeId>", "data": {} }
-  }]
+  }],
+  "compact": true
 }
 ```
 

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

@@ -0,0 +1,146 @@
+---
+name: walkthrough
+description: Walk a person through the board step by step, as a player in the chat. Two modes — explain ("how does registration work?") follows a process through its screens, commands, events and read models; impact ("we need to add an email — walk me through the changes") lists, in order, every slice, element and scenario a planned change touches and what has to change there. Each step carries a description, the business rules that apply, a link that zooms the canvas to it, and its screen; the person can play it full-screen like the screen movie strip. Read-only — changes nothing on the board.
+---
+
+# Walkthrough — step by step through the board
+
+> **Before doing anything else**, invoke the `connect` skill — if not already connected — to resolve `TOKEN`, `BOARD_ID`, `ORG_ID`, and `BASE_URL`. Do not proceed until it has completed.
+
+Prefer `mcp__eventmodelers__*` tools. See `learn-eventmodelers-api` for the curl fallback and §16 *Chat snippets* for the `walkthrough` shape.
+
+The result is **one `walkthrough` snippet** in the chat. The person steps back and forth through it; selecting a step zooms the canvas to that step's element, slice or scenario, and **Play** opens all steps full-screen as a strip of their screens with the description, the changes and the rules underneath. The walkthrough is only as good as its links: every step points at a real node on this board.
+
+**This skill never writes to the board.** In impact mode it shows what would change; making those changes is separate work the person asks for afterwards.
+
+---
+
+## Step 1 — Mode and subject
+
+From `$ARGUMENTS` / the message, and the turn's `context=` (selected nodes, `timelineId`, `focusArea` — resolved as in the kit's CLAUDE.md):
+
+| Mode | Typical message | The steps are |
+|---|---|---|
+| `explain` | "How does registration work?", "walk me through checkout", "/walkthrough Registration" | the process in the order it runs, as a person experiences it |
+| `impact` | "We need to add an email — walk me through the changes", "what does it take to support refunds?" | every place in the model the change touches, in the order it should be changed |
+
+The **subject** is the process or the change, in the person's words. "This"/"here" means what they have selected or zoomed to.
+
+### No subject yet — ask first
+
+Called without one (a bare `/walkthrough`, the chat menu's entry sent as is, "walk me through" with nothing named), **ask before reading anything in detail** — the selection or the chapter in view is not enough on its own to guess which flow or which feature they mean. One cheap read for the options: `get_nodes { boardId, type: "CHAPTER", projection: "line" }` (and, for a single chapter, `list_slices`). Then reply once and **end the turn**:
+
+```
+mcp__eventmodelers__post_chat_message {
+  "boardId": "$BOARD_ID",
+  "replyTo": "<message_id>",
+  "text": "Which flow should I walk you through? Or tell me the new feature you're planning, and I'll walk you through what it changes.",
+  "snippet": {
+    "kind": "poll",
+    "question": "Walk through which flow?",
+    "options": [
+      { "label": "Registration", "message": "/walkthrough How does Registration work?" },
+      { "label": "Checkout",     "message": "/walkthrough How does Checkout work?" }
+    ]
+  }
+}
+```
+
+- The options are the board's flows — chapters, or the main slices when the board has one chapter — at most ~8, the one in the person's view first. Each option's `message` is a complete `/walkthrough …` request, so the pick comes back as a new message that runs this skill with its subject.
+- The text always offers the **impact** mode in words ("tell me the new feature you're planning") — a planned change can't be picked from a list; the person types it, and their reply is the subject.
+- Fewer than two flows on the board: ask in the text only, no snippet. An empty board: say there is nothing to walk through yet.
+
+The same goes for a subject that is still too vague with the context (several chapters equally likely): ask with a `poll` of those candidates — don't guess between them.
+
+---
+
+## Step 2 — Outline first: where on the board is it?
+
+Orient cheaply before reading anything in detail — the board can be large, and only a handful of nodes matter.
+
+1. **Chapters**: `get_nodes { boardId, type: "CHAPTER", projection: "line" }` — pick the chapter(s) the subject belongs to by title. With a `timelineId` in context, start there.
+2. **Context notes**: for each candidate chapter, `get_board_outline { boardId, chapterId }`, then read the MARKDOWN note in the first column's `feedback` lane (`get_node`, `meta.description`) if there is one. It says what the chapter is for and often names the decisions behind it — use it in the descriptions.
+3. **Slices**: `list_slices { boardId, contextName }` and `get_slice_data { boardId, contextName, projection: "outline", format: "toon" }` — every slice with its elements as `{id, title, type}`.
+4. **Find the nodes that matter.** With the outline in hand, decide which slices and elements belong to the subject:
+   - **explain**: the slices whose commands, events, read models or screens are about the subject; follow the edges in the outline (screen → command → event → read model → next screen, events → automations) from where the process starts to where it ends. Other chapters only when the flow crosses into them (an external or translated event).
+   - **impact**: start from the element the change lands on first (the screen or command where the new data enters, or the event whose meaning changes), then follow the flow **downstream** — every event that would carry it, every read model and automation fed by those events, every screen that shows those read models — and **upstream** where the data has to come from. A name search helps: `get_nodes { boardId, name: "<term>", projection: "line" }` for the field or concept ("email") finds the places that mention it already.
+
+Stop widening when a further step adds nothing the person asked about. A walkthrough of 4–12 steps is typical; 20+ means the subject is really several — say so in the text and walk the first one.
+
+---
+
+## Step 3 — Read only those
+
+Now read the working set in detail — never the whole board:
+
+- `get_slice_data { boardId, contextName, sliceId, projection: "fields" }` per relevant slice — fields and dependencies.
+- `get_slice_data { boardId, contextName, sliceId, projection: "specs", format: "toon" }` — the **scenarios**: these are the business rules. A scenario's title in business words ("Email must be unique") is a rule; its Given/When/Then says when it applies.
+- `get_nodes { boardId, type: "SCENARIO", chapterId, projection: "line" }` — the ids of the scenario nodes, so an impact step can point at a scenario directly.
+- Full `get_nodes { boardId, nodeIds: [...] }` only for the few nodes whose `description` you need.
+
+---
+
+## Step 4 — Build the steps
+
+One step per thing the person should look at, in order.
+
+**explain** — follow the process as the person living it experiences it. One step per meaningful moment, usually one slice: *what they see → what they do → what is recorded → what that makes visible or triggers*. Merge a command and its event into one step when nothing happens between them; give an automation its own step.
+
+**impact** — one step per place that has to change, ordered so each step builds on the previous one (where the data enters → the command → the event → read models → screens → automations → scenarios). Include **scenarios** as their own steps when they need a new case or an update (e.g. "add: Register with an email that is already taken → rejected"). Say what is *not* affected only if the person would reasonably expect it to be.
+
+Per step:
+
+| Field | What goes in |
+|---|---|
+| `title` | short, business words — the moment ("Customer submits registration") or the place ("Register Customer — command") |
+| `description` | 1–3 sentences: what happens here and why it matters, in the board's language. No ids, no cell addresses. |
+| `nodeId` | the node to zoom to: the **slice** (its `SLICE_BORDER` id from `list_slices`) when the step is about the slice as a whole, the **element** when it is about one element, the **scenario** node when the step is a scenario |
+| `screenId` | the SCREEN / HTML_SCREEN shown in this step, if there is one — that is what the player shows. Leave it out otherwise; don't point at an unrelated screen to fill the frame |
+| `rules` | the business rules that apply here, taken from the scenarios (and the context note); one line each, thresholds verbatim. Empty when there are none — never invent one |
+| `changes` | **impact mode only**: what has to change here, one line each — "add field `email` (String)", "new scenario: duplicate email is rejected", "show email in the confirmation screen" |
+
+**Faithfulness.** Everything comes from the board. A rule nobody modelled is not a rule — if the walkthrough reveals a gap ("nothing says what happens when confirmation never arrives"), mention it in the step's `description` as an open question, not as a rule.
+
+---
+
+## Step 5 — Post it
+
+**One** `post_chat_message`: in a `CHAT` turn `replyTo` = this turn's `message_id`; in a prompt turn that came from a chat, `sessionId` = `CHAT_SESSION_ID` and no `replyTo`.
+
+```
+mcp__eventmodelers__post_chat_message {
+  "boardId": "$BOARD_ID",
+  "replyTo": "<message_id>",
+  "text": "Registration in 5 steps — step through it here, or press Play.",
+  "snippet": {
+    "kind": "walkthrough",
+    "title": "How registration works",
+    "intro": "From the sign-up form to a confirmed account.",
+    "steps": [
+      { "title": "Customer fills in the sign-up form", "nodeId": "<slice id>", "screenId": "<screen id>",
+        "description": "Name, email and password are entered on the registration screen.",
+        "rules": ["Email must be unique", "Password at least 12 characters"] },
+      { "title": "Customer registered", "nodeId": "<event id>",
+        "description": "The registration is recorded; the account is not active yet." }
+    ]
+  }
+}
+```
+
+Impact mode, same shape with `changes` per step:
+
+```
+{ "title": "Register Customer — command", "nodeId": "<command id>",
+  "description": "The email enters here and has to be validated before anything is recorded.",
+  "changes": ["Add field email (String)", "Reject the command when the email is already registered"],
+  "rules": ["Customer name is required"] },
+{ "title": "Scenario: duplicate email", "nodeId": "<scenario id>",
+  "changes": ["New case: Given Customer registered with x@y.z, When Register Customer with x@y.z, Then rejected"] }
+```
+
+- `text` is one line: the subject and the number of steps. It is the fallback, so it must make sense alone.
+- Every `nodeId` / `screenId` is an id you read in Steps 2–3 — never a guessed or remembered one.
+- The snippet is at most 64 KB; keep descriptions short rather than dropping steps.
+- **Impact mode** ends there: the walkthrough is the proposal. If the person then asks for the changes, that is ordinary work (prompts per the kit's CLAUDE.md) — and a slice that is not `Created` still needs their confirmation first.
+
+**No chat** (run from a terminal): print the steps as a numbered list with the same fields instead of posting.

package/stacks/modeling-kit/templates/kit/CLAUDE.md

@@ -202,6 +202,12 @@ for it. Instead:
      (`timelineId` for the chapter, what they have selected). It sends its findings back as a snippet to tick
      and posts nothing to the board until they answer (`/wdyt` Step 4.0). Your reply here is one line —
      *"On it — looking at Registration."*
+   - **walkthrough** — "how does X work?", "walk me through …", "what does it take to add …?", or `/walkthrough …`:
+     run the `/walkthrough` skill **in this turn** — it only reads the board, so no prompt is needed. It finds the
+     slices, elements and scenarios involved and its `walkthrough` snippet is your one reply (step 4). Without a
+     subject (a bare `/walkthrough`) it asks first — which flow, or which new feature — and that question is the reply. A planned change
+     ("we need to add an email") is its impact mode: the walkthrough is the proposal, and the changes become work only
+     when the person asks for them afterwards.
    - **a skill by name** — the message starts with `/<name>` of one of your skills (the chat panel's menu
      writes these: `/analyze-existing-model`, `/analyze-code-base`, `/detect-model-drift`, `/add-next-slice`, `/examples`, `/timeline …`,
      `/html-screen …`, `/storyboard …`): the person chose that skill, so it **is** the work — create one prompt,
@@ -358,6 +364,7 @@ nothing to sanitize either, since a board change is not user text.
 | Analyse the existing model structure, slice coverage, element counts | `/analyze-existing-model` |
 | Reverse-engineer the business process of an existing code base into the model, as an interview — all chapters first, then one chapter at a time | `/analyze-code-base` |
 | Find where the model and the code have drifted apart (fields, specs, screens, edges, missing/extra slices) and propose fixes | `/detect-model-drift` |
+| Walk someone through a process step by step, or through every slice, element and scenario a planned change touches, as a player in the chat | `/walkthrough` |
 | Turn a document or image (e.g. a tender/RFP) into a chaptered event model with screens, scenarios and a written blueprint summary | `/summarize` |
 | Look up any API endpoint or element type not already covered by the skill you're executing | `/learn-eventmodelers-api` |
 | Add or rename an attribute across a chain of elements | `/attributes` |