@eventmodelers/cli 1.0.128 → 1.0.130

package/README.md

@@ -107,6 +107,7 @@ Use skills in Claude Code with `/skill-name`:
 | `/timeline` | Live event storming facilitator |
 | `/wdyt` | Business analyst review of your event model |
 | `/walkthrough` | Slice-by-slice player through a feature, or through every slice a planned feature needs (existing, to adjust, new) |
+| `/data-journey` | Where one piece of information (e.g. the customer email) originates, is stored, transformed, used and sent out — as a table in the chat |
 | `/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.128",
+  "version": "1.0.130",
   "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

@@ -1122,8 +1122,10 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
 | 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 feature works, or walk through what a planned feature takes, slice by slice ("how does registration work?", "we need to add an email — walk me through it") | `walkthrough` | nothing — selecting a step pans the canvas |
+| to show what a screen could look like, without putting it on the board | `screen` | nothing |
+| to answer where one piece of information comes from and where it ends up ("where is the customer email used?") | `dataJourney` | nothing — element names pan the canvas |
 
-`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.
+`confirm`, `poll`, `tasks` and `changes` are questions: a person answers once, then they show as answered. `link`, `image`, `code`, `report`, `walkthrough`, `screen` and `dataJourney` are display only and never wait for anything.
 
 ### Shapes
 ```typescript
@@ -1152,10 +1154,22 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
                  nodeId?: string,                                                 // the slice's SLICE_BORDER — drawn in its lanes, selecting the step zooms to it; none for a new slice
                  status?: 'existing' | 'changed' | 'new',                         // planned feature: used as is / needs adjustment / built from scratch
                  elements?: Array<{ type: 'SCREEN' | 'COMMAND' | 'EVENT' | 'READMODEL' | 'AUTOMATION',
-                                    title: string, fields?: string[] }>,          // a new slice only: its sketch, drawn in lanes
+                                    title: string, fields?: string[],
+                                    html?: string }>,                              // a new slice only: its sketch, drawn in lanes; html = the SCREEN as a small HTML page (≤ 16000 chars)
                  screenId?: string,                                               // a SCREEN / HTML_SCREEN outside the slice the person sees in this step
                  rules?: string[],                                                // business rules of this slice
                  changes?: string[] }> }                                          // planned feature: what has to change or be built here
+{ kind: 'screen', html: string,                                                  // a screen mock-up as a small HTML page (≤ 16000 chars), shown sandboxed
+  title?: string, caption?: string }
+{ kind: 'dataJourney', subject: string,                                           // the piece of information followed, in the person's words ("Customer email")
+  summary?: string,                                                               // 1–2 sentences: where it comes from, where it goes
+  stops: Array<{ title: string,                                                   // 1+, in flow order: the element the data passes through
+                 nodeId?: string,                                                 // makes the title a link; the element's type is read from the board
+                 elementType?: string,                                            // SCREEN, COMMAND, EVENT, READMODEL, AUTOMATION … for an element not on the board
+                 role: 'origin' | 'stored' | 'transformed' | 'used' | 'sent',     // entered/imported here / kept in this event / renamed, derived, reformatted / read, shown, decided on / leaves the system
+                 field?: string,                                                  // the field holding it here — names change along the way (email → customerEmail)
+                 slice?: string,
+                 note?: string }> }                                               // how it is used or changed here, a few words
 ```
 
 ### How to use them
@@ -1166,7 +1180,9 @@ 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", **one step per slice**. It opens with a summary page — the slice count (with `status`: how many exist, need adjustment, are new) above your `summary` — then shows each slice in its lanes like Slice View (screen, command / read model, events), a `new` slice sketched from its `elements`; each step zooms the canvas to its slice, and **Play** opens it full-screen with description, changes 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. Keep `text` to one line naming the feature and the number of slices.
+- **`walkthrough`** answers "how does X work?" and "walk me through what changes for Y", **one step per slice**. It opens with a summary page — the slice count (with `status`: how many exist, need adjustment, are new) above your `summary` — then shows each slice in its lanes like Slice View (screen, command / read model, events), a `new` slice sketched from its `elements` (its SCREEN rendered from the `html` you write: a real, simple page — a form, a list, a table — with inline styles only; scripts and external resources are blocked; without `html` a plain form/table is generated from the fields); each step zooms the canvas to its slice, and **Play** opens it full-screen with description, changes 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. Keep `text` to one line naming the feature and the number of slices.
+- **`screen`** shows a mock-up in the chat — "what could the registration screen look like?", a variant to compare — without creating anything on the board (that is the `html-screen` skill's job). `html` follows the walkthrough's screen rules: body content, inline styles or one `<style>` block, no scripts, no external images, fonts or stylesheets (they are blocked), at most 16000 characters.
+- **`dataJourney`** answers "where does X come from / where is X used?" for **one piece of information**, as a table: one stop per element it passes through, in flow order, each with its `role`, the field name there and the slice. A headline counts the roles ("Originates in 1 place, stored in 2 elements and used in 3 places"). Build it from the board — the `data-journey` skill (modeling kit) has the procedure; every `nodeId` must be a real id from this board, and a field the board doesn't carry is not a stop. Keep `text` to one line naming the data and where it originates.
 - 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/data-journey/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: data-journey
+description: Follow one piece of information through the model — "where does the customer email come from, and where is it used?" — and show it in the chat as a table. One stop per element it passes through, in flow order — where it originates (a screen, an external event, an import), which events store it, where it is renamed or derived, which read models, screens and automations use it, and where it leaves the system — each with the field name it has there and its slice. Read-only — changes nothing on the board.
+---
+
+# Data journey — where a piece of information comes from and where it goes
+
+> **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 `dataJourney` shape.
+
+The result is **one `dataJourney` snippet** in the chat: a table with one row ("stop") per element the information passes through, in the order it flows. Each stop has a **role** — `origin`, `stored`, `transformed`, `used`, `sent` — the **field** it is held in there (names change along the way: `email` on the screen, `customerEmail` in the event), the slice and a few words on what happens to it. A headline above the table counts the roles ("Originates in 1 place, stored in 2 elements and used in 3 places"). Element names are links that zoom the canvas.
+
+Typical questions: *"Where is the customer email used?"*, *"Where does the delivery address come from?"*, *"Which events store the IBAN?"*, *"What happens to the discount code?"*, *"/data-journey customer email"*.
+
+**This skill never writes to the board.**
+
+---
+
+## Step 1 — The subject
+
+The **subject** is one piece of information in the person's words ("customer email", "order total"). From `$ARGUMENTS` / the message, and the turn's `context=`: a selected element with one field selected, or a message like "this field", means that field.
+
+No subject, or several equally likely ("the customer data"): **ask first** and end the turn — a `poll` of the candidates (at most ~8 field names you found, each option's `message` a complete `/data-journey <name>` request), or text only when there is nothing to offer. One piece of information per journey: "name and email" is two journeys — do the first and offer the second in the text.
+
+---
+
+## Step 2 — Find every element that carries it
+
+Cheap reads first, never the whole board in full:
+
+1. **Name search**: `get_nodes { boardId, name: "<term>", projection: "line" }` finds elements whose *title* mentions it; the field names are in `fields`. Search for the obvious variants (`email`, `mail`, `e-mail`; the board's language).
+2. **Field search**: per chapter, `get_slice_data { boardId, contextName, projection: "fields", format: "toon" }` — every element's fields with their `mapping`. Collect every field that holds the subject: the same name, a prefixed/renamed one (`customerEmail`, `newEmail`, `recipient`), and — via `mapping` — every field mapped **from** one you already have. Follow `mapping` both ways until nothing new turns up; that is how a rename is traced, not by guessing from names. A field that only *sounds* related (`emailVerified`, `emailCount`) is a different piece of information — leave it out, or mention it in `note` on the stop it sits on.
+3. Note `pii: true` on a field — say so in the `summary` if the subject is personal data.
+
+---
+
+## Step 3 — Order and classify the stops
+
+Order the stops the way the information flows — follow the edges (screen → command → event → read model → screen; event → automation → command → …), from where it enters to where it ends. Branches follow their source: after the event that stores it, list the read models fed by it, then the automations.
+
+| `role` | The element … |
+|---|---|
+| `origin` | is where the information first enters the system: a SCREEN the person types it into, an external/translated event, an import, an API. Usually one; more when it can enter in several ways (registration *and* "change email") |
+| `stored` | is an EVENT that records it — the source of truth. Every event carrying the field is a stop |
+| `transformed` | changes it: a renamed field via `mapping` (`email` → `recipient`), a derived value, a normalisation stated in the element's description or scenarios ("lower-cased") — say what in `note` |
+| `used` | reads it: a COMMAND that only passes it through or checks it, a READMODEL that projects it, a SCREEN that shows it, a scenario that decides on it ("email must be unique") — `note` says how |
+| `sent` | hands it outside the system: an automation calling an external service (mail provider, payment, CRM), an outbound integration event |
+
+A command that takes the field from its screen is `used` (it carries it), unless the screen isn't modelled — then the command is the `origin`. Each element appears once; pick the role that says most about it.
+
+Per stop: `title` as on the board, `nodeId` (the element's real id), `field` (the field name on that element), `slice` (the slice title from `list_slices`), `note` in a few business words — no ids, no cell addresses. `elementType` only for a stop that is not a board node.
+
+**Faithfulness.** Only what the board says. If the information is shown on a screen but no read model carries it, or an event stores it but nothing ever reads it, that is a finding — put it in the `summary` ("Stored in Email Changed, but no read model picks the new email up"), not as an invented stop.
+
+---
+
+## Step 4 — 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": "The customer email enters at registration and ends up in 5 more places.",
+  "snippet": {
+    "kind": "dataJourney",
+    "subject": "Customer email",
+    "summary": "Entered once at registration (personal data), kept in two events and used for login and mails. Nothing shows the changed email after Email Changed.",
+    "stops": [
+      { "title": "Registration",        "nodeId": "<id>", "role": "origin",      "field": "email",         "slice": "Register Customer", "note": "typed in by the customer" },
+      { "title": "Register Customer",   "nodeId": "<id>", "role": "used",        "field": "email",         "slice": "Register Customer", "note": "must be unique" },
+      { "title": "Customer Registered", "nodeId": "<id>", "role": "stored",      "field": "customerEmail", "slice": "Register Customer" },
+      { "title": "Email Changed",       "nodeId": "<id>", "role": "stored",      "field": "newEmail",      "slice": "Change Email" },
+      { "title": "Customer Profile",    "nodeId": "<id>", "role": "used",        "field": "email",         "slice": "Customer Profile",  "note": "shown on the profile page" },
+      { "title": "Send Welcome Mail",   "nodeId": "<id>", "role": "sent",        "field": "recipient",     "slice": "Welcome Mail",      "note": "to the mail provider" }
+    ]
+  }
+}
+```
+
+- `text` is one line — the subject and where it originates; it is the fallback and must make sense alone.
+- Every `nodeId` is an id you read in Step 2 — never a guessed one.
+- Long journeys page themselves (5 rows per page); keep every stop in the one snippet.
+- If the person then asks to change something (add the field to a read model, mark it as `pii`), that is ordinary work — prompts per the kit's CLAUDE.md.
+
+**No chat** (run from a terminal): print the summary and the stops as a table (role, element, field, slice, note) instead of posting.

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

@@ -107,11 +107,13 @@ Per step:
 | `description` | 1–3 sentences: what happens in this slice and why it matters, in the board's language. No ids, no cell addresses. |
 | `nodeId` | the slice's `SLICE_BORDER` id from `list_slices` — the player draws the slice from it and zooms the canvas to it. Left out for a `new` slice |
 | `status` | **impact mode: required on every step** — `existing`, `changed` or `new` (table above). Omitted in explain mode |
-| `elements` | **`new` slices only**: the sketch — `[{ "type": "SCREEN" \| "COMMAND" \| "EVENT" \| "READMODEL" \| "AUTOMATION", "title": "…", "fields": ["…"] }]`, the elements the slice will have (a state change: screen → command → event; a state view: event(s) → read model → screen; an automation: read model → automation → command → event). Titles and fields in the board's style; reuse the names of existing events the slice reads from |
+| `elements` | **`new` slices only**: the sketch — `[{ "type": "SCREEN" \| "COMMAND" \| "EVENT" \| "READMODEL" \| "AUTOMATION", "title": "…", "fields": ["…"] }]`, the elements the slice will have (a state change: screen → command → event; a state view: event(s) → read model → screen; an automation: read model → automation → command → event). Titles and fields in the board's style; reuse the names of existing events the slice reads from. **Give the SCREEN an `html`** — see *Screen HTML* below |
 | `screenId` | only when the screen a person sees in this step is not part of the slice itself |
 | `rules` | the business rules of this slice, taken from its 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 or be built in this slice, one line each — "add field `email` (String) to Register Customer", "new scenario: duplicate email is rejected" |
 
+**Screen HTML.** A new slice's SCREEN is shown as a real screen, so write it: `html` is a small HTML page of what the person sees there — a form for a state change (an input per command field, labelled in business words, a button named after the command), a list or table for a state view (columns from the read model's fields, 2–3 rows of plausible example data), whatever fits the screen otherwise (a checklist, a confirmation page). Keep it rough and simple: a heading and the content, no navigation, header or footer. Body content only (no `<html>`/`<head>` needed), inline `style` attributes or one `<style>` block, at most 16000 characters. It renders sandboxed: scripts, external images, fonts and stylesheets are blocked, so no `<script>`, no CDN, no `https://` images. Without `html` the player generates a plain form/table from the fields.
+
 **Faithfulness.** Existing slices come 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. A sketched new slice is a proposal, and the `description` should read like one.
 
 ---
@@ -152,7 +154,8 @@ Impact mode, same shape with `status` (and `changes`, or `elements` for a new sl
   { "title": "Confirm Email", "status": "new",
     "description": "Proposed: the customer opens the link and the email is marked as confirmed.",
     "elements": [
-      { "type": "SCREEN",  "title": "Confirm Email Page" },
+      { "type": "SCREEN",  "title": "Confirm Email Page",
+        "html": "<h3>Confirm your email</h3><p>We sent a link to <b>jane@example.com</b>.</p><label>Code<br><input value=\"8F3K-21\"></label><br><br><button>Confirm Email</button>" },
       { "type": "COMMAND", "title": "Confirm Email",   "fields": ["customerId", "token"] },
       { "type": "EVENT",   "title": "Email Confirmed", "fields": ["customerId", "confirmedAt"] }
     ],
@@ -163,7 +166,7 @@ Impact mode, same shape with `status` (and `changes`, or `elements` for a new sl
 ```
 
 - `text` is one line: the subject and the number of slices — in impact mode with the split ("Startup license in 8 slices: 3 new, 2 to adjust"). It is the fallback, so it must make sense alone.
-- Impact mode: before posting, check that every step has a `status`, every `changed` step has `changes` and every `new` step has `elements` and no `nodeId`.
+- Impact mode: before posting, check that every step has a `status`, every `changed` step has `changes` and every `new` step has `elements` (its SCREEN with `html`) and no `nodeId`.
 - `summary` is always there — the first page shows it under the slice count.
 - Every `nodeId` / `screenId` is an id you read in Steps 2–3 — never a guessed or remembered one. A `new` slice has no `nodeId`.
 - The snippet is at most 64 KB; keep descriptions short rather than dropping steps.

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

@@ -208,6 +208,10 @@ for it. Instead:
      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: every slice marked existing / needs adjustment / new, new ones sketched — the walkthrough is the proposal, and the changes become work only
      when the person asks for them afterwards.
+   - **data journey** — "where does X come from?", "where is X used?", "which events store X?", or `/data-journey …`, about
+     **one piece of information** (a field, "the customer email"): run the `/data-journey` skill **in this turn** — it only reads
+     the board, so no prompt is needed. Its `dataJourney` snippet (a table: origin, stored, transformed, used, sent — per element,
+     with the field name there) is your one reply. Without a clear subject it asks first which information.
    - **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,
@@ -274,6 +278,8 @@ for it. Instead:
    - a **choice between alternatives** ("A or B?", "which one first?") → `poll`;
    - a **list of things for the person to pick from** (findings, candidates, drifts, "which of these?") → `tasks`;
    - a **pointer to an element, a picture or a command** → `link` / `image` / `code`, instead of describing it.
+   - a **screen idea** in the conversation ("what could that screen look like?") → `screen`, a sandboxed HTML mock-up in the chat; putting a screen on the board is `/html-screen` work;
+   - **where one piece of information comes from and where it is used** → `dataJourney` (the `/data-journey` skill).
    Plain text stays for answers, explanations and open questions that need words. `text` is still
    required and stays short — it is the lead-in, the snippet carries the detail. A snippet changes
    nothing on the board: the click comes back as the next `CHAT` turn, and only then do you