@eventmodelers/cli 1.0.123 → 1.0.124

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.124",
   "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/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 — pick a step to jump to it, 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` |