@eventmodelers/cli 1.0.61 → 1.0.63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.61",
+  "version": "1.0.63",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, Cratis, OpenCQRS, UmaDB, Kurrent, or modeling-only)",
   "type": "module",
   "bin": {

package/shared/skills/connect/SKILL.md

@@ -9,6 +9,8 @@ description: Resolve eventmodelers connection config (token, boardId, baseUrl) f
 
 **This should happen once per session, not once per skill.** If `TOKEN`/`BOARD_ID`/`ORG_ID`/`BASE_URL` are already resolved and verified from earlier in the current session — including earlier in the *same turn*, e.g. one skill internally invoking a second skill (`add-next-slice` → `html-screen`) — every subsequent "invoke `connect`" instruction is satisfied immediately by reusing those values. Do not re-run Steps 0–4 below. Only re-run this skill from scratch when a value actually needs to change: a fresh `401`/`403`/access-denied response from some other call, a different `board_id` on this turn, or a new inline param that overrides what's already resolved.
 
+**Subagents are a fresh session — hand them the resolved values.** When you spawn a subagent to do board work, put the already-resolved credentials inline in its prompt (`token=… board=… org=… baseUrl=…`). Its `connect` then satisfies everything at Step 0 and skips Steps 1–4 entirely: no config-file walk, no MCP re-registration, no verify call. Spawning three subagents without passing them down means paying the whole resolve-and-verify round three more times for values you already have.
+
 This skill also registers the **eventmodelers MCP server** for the project (Step 3.5) so other skills can call MCP tools (`mcp__eventmodelers__*`) instead of raw curl. MCP is the preferred transport; curl remains a fallback for hosts without MCP support, or for the one or two endpoints (documented in `learn-eventmodelers-api`) the MCP server doesn't expose.
 
 ---
@@ -214,6 +216,23 @@ curl -s -o /dev/null -w "%{http_code}" \
 
 ---
 
+## Step 5 — Read the board once
+
+Connecting is also where the session's read discipline starts. Every skill that runs after this one shares the same board, so **fetch it once and index it in memory** instead of re-deriving it per step:
+
+- **Orientation** (what is where, how is it wired) — `get_board_outline { boardId, chapterId }`. One compact call per chapter: per-column node lists plus a flat edge list, no HTML pages or field bodies.
+- **Working set** (you need `meta.fields`, examples, descriptions) — `get_nodes { boardId, chapterId }`. One call returns every node in the chapter with full `meta`, plus `node.position` and `node.parentId`. A whole 70-node board is well under 100 KB unscoped; scoped to a chapter it is smaller still.
+- **A known, scattered subset** — `get_nodes { boardId, nodeIds: [...] }`. One call, not one per id.
+- **Just names/types** — add `projection: "line"`. **Just a chapter's grid** — `get_node { nodeId: <chapterId>, projection: "cells" }`. **Just one node's wiring** — `get_node { nodeId, projection: "edges" }`.
+
+`get_node` without a projection is for **one** node you did not already load — most often re-reading a node right after writing it. A step that issues it in a loop over nodes that were already in a list response is doing the same fetch N times; collapse it to the single chapter-scoped read above.
+
+The same discipline applies to writes: `submit_node_events` takes `events[]`, so a multi-node edit is **one** call carrying every event, not one call per node. Pass `compact: true` when you don't need the per-node hash map back.
+
+Where per-node calls genuinely can't be avoided, issue them together in one message so they run concurrently rather than in sequence.
+
+---
+
 ## Config file format
 
 `.eventmodelers/config.json`:

package/shared/skills/learn-eventmodelers-api/SKILL.md

@@ -48,6 +48,7 @@ Server name: `eventmodelers`. Every tool takes `boardId` explicitly; none need `
 | `get_slice_data` | `boardId`, `contextName?`, `contextId?`, `sliceId?` | Full element graph for slices in a context | §8 `GET /slicedata` |
 | `get_spec_info` | `boardId`, `timelineId`, `elementTypes?` | EVENT/COMMAND/READMODEL nodes valid in GWT steps. Pass `elementTypes` (subset of `EVENT`/`COMMAND`/`READMODEL`) to avoid pulling the full element list when only one or two types are needed — filtered server-side, not just after a full fetch | §6 `GET .../spec-info` |
 | `get_board_outline` | `boardId`, `chapterId` | One chapter's structure, compact: per-column node lists (`{id, type, title, lane}`) + a flat edge list, no HTML pages / field bodies / meta. The cheap "what is where and how is it wired" read — prefer over `get_nodes` (no projection) for orientation checks | — (MCP-only convenience) |
+| `get_connected_nodes` | `boardId`, `nodeId`, `chapterId?`, `direction?` (`inbound`/`outbound`/`both`), `depth?`, `types?`, `includeFields?` | Neighbours of **one** node — what feeds it and what it feeds. Answers from a single anchor, unlike `get_attribute_chain` (which needs both ends of the chain as cell names up front). `depth` follows a whole chain; `types` filters the result only, never the traversal. Each neighbour carries `via`: `"edge"` for a real connection, `"layout"` when the node has none in that direction and the neighbour was inferred from the grid using auto-connect's own window (own column + adjacent one, forward-only pairs). Real edges always win. The `layout` fallback is what makes hand-built/imported chapters — which routinely carry **zero** edges — readable instead of falsely empty | — (MCP-only convenience) |
 | `validate_model` | `boardId`, `chapterId`, `checks?[]` | Server-side Event Modeling structural checklist over one chapter — compact `findings` only. Checks: unplaced nodes, backward arrows (with the todo-list `EVENT→READMODEL` exception), zero/multi-issuer commands, sourceless read models, two-screens-in-a-column, missing scenarios. Replaces the manual per-type `get_nodes` + `get_node projection=edges` validation pass | — (MCP-only convenience) |
 | `add_scenario` | `boardId`, `timelineId`, `columnId`, `scenarios[]`, `compact?` | Append GWT scenario(s) to a column's spec node. `compact: true` returns `{specNodeId, added, scenarioCount, isNewNode}` instead of echoing every scenario back | §6 `POST .../scenarios` |
 | `add_storyline` | `boardId`, `timelineId`, `columnId`, `storylines[]`, `compact?` | Append storyline(s) (ordered, branchable beats over existing elements) to a column's spec node. Use whenever `eventmodeling-elaborating-scenarios`'s GWT-vs-storyline decision rule calls for one (e.g. a todo list's open→close lifecycle) — not only when a user explicitly names "storyline"; that skill's own per-read-model judgment is the trigger, this catalog entry isn't a stricter gate on top of it. `compact: true` suppresses the full storyline echo | §6 `POST .../storylines` |

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

@@ -59,24 +59,40 @@ Each node may have an `edges` array:
 ```json
 edges: [{ id, source, target, sourceHandle, targetHandle }]
 ```
-An **inbound** edge is one where `edge.target === currentNode.id`. For each inbound edge, fetch the source node:
+An **inbound** edge is one where `edge.target === currentNode.id`.
 
-**Prefer MCP:**
+**Prefer `get_connected_nodes`** — it does this entire walk server-side, in one call, from the target alone:
 ```
-mcp__eventmodelers__get_node { "boardId": "$BOARD_ID", "nodeId": "$EDGE_SOURCE_ID" }
+mcp__eventmodelers__get_connected_nodes {
+  "boardId": "$BOARD_ID",
+  "nodeId": "<TARGET_NODE.id>",
+  "direction": "inbound",
+  "depth": 10,
+  "includeFields": true
+}
 ```
+The result is already ordered by `hops` (nearest first) and carries each node's `cellName` and `fields[]`, which is everything Step 4 needs — so this replaces both the edge walk and the per-node field fetch. Stop at the node matching `SOURCE_NODE`; anything beyond it is outside the requested chain.
+
+Each neighbour reports `via`. `"edge"` means a real connection. `"layout"` means that node had no edge in that direction and the neighbour was inferred from the grid — correct, but worth a line in your Step 5 report so the user knows the chain was read off the layout rather than off wiring. A `chapterHasEdges: false` in the summary means the whole chapter is unwired.
 
-**Fallback (no MCP):** see `references/api-fallback.md` — "3a — Use Node Edges".
+Reach for a single-node fetch only for a node genuinely outside the anchor's chapter:
+```
+mcp__eventmodelers__get_node { "boardId": "$BOARD_ID", "nodeId": "$EDGE_SOURCE_ID", "projection": "edges" }
+```
+
+**Fallback (no MCP):** see `references/api-fallback.md` — "3a — Use Node Edges". Resolve the walk from **one** chapter-scoped read rather than a `get_node` per hop: `GET .../nodes?chapterId=` returns every node with full `meta`, `node.position` and `node.parentId` in a single response — index it and walk it locally.
 
 ### 3b — Column-based fallback (if no edges)
-If a node has no edges, use the chapter cell layout (already in memory) to find plausible inbound neighbours:
+Only needed without MCP; `get_connected_nodes` already applies this rule itself and labels the result `via: "layout"`.
+
+Hand-built or imported chapters frequently have **no edges at all** — every node comes back with `edges: []` and `get_board_outline`'s edge list is empty. That is not an error and not a reason to stop: in that case grid geometry *is* the chain. Use the chapter cell layout (already in memory from 3a) to find inbound neighbours:
 
 In a standard event modeling layout:
 - **READMODEL** in the interaction row → its inbound EVENT is in the swimlane row of the **same column**
 - **EVENT** in the swimlane row → its inbound COMMAND is in the interaction row of the **same column**
 - **COMMAND** in the interaction row → its inbound READMODEL is in the swimlane row of the **previous column**
 
-Fetch candidate nodes by their cellId (live), skip any that don't exist or are already in the chain.
+Resolve candidates from the chapter read you already have — do **not** issue a `?cellId=` lookup per candidate. If the chapter's `meta.timelineData.cells` is sparse or absent, derive each node's (column, row) from `node.position.x/y` bucketed against `meta.timelineData.columns[].width` and `rows[].height`; that mapping is enough to apply the three rules above. Skip candidates that don't exist or are already in the chain.
 
 ### 3c — Stop condition
 Stop traversal when:
@@ -86,11 +102,11 @@ Stop traversal when:
 
 ---
 
-## Step 4 — Apply the change to each node in the chain
+## Step 4 — Apply the change to the whole chain in one write
 
-Process nodes in order: TARGET_NODE first, then backwards to SOURCE_NODE.
+Compute the updated `fields` array for **every** node in the chain first, in order (TARGET_NODE first, then backwards to SOURCE_NODE), then submit them all in a **single** `submit_node_events` call. Do not write one node, check it, and move to the next — the chain is one logical edit and `events[]` takes the whole batch.
 
-For each node:
+For each node, compute (don't write yet):
 
 ### If operation is `add`:
 - Check if a field with that name already exists in `meta.fields` — if so, skip this node (log it).
@@ -114,27 +130,35 @@ For each node:
 - Find the field where `name === oldName` (case-insensitive). If not found in this node, skip it (log it).
 - Update only the `name` property to `newName`. Leave all other field properties unchanged.
 
-Build the updated `fields` array and send a `node:changed` event.
+Collect one `node:changed` event per affected node, then send them together.
 
-**Prefer MCP** — same event body, passed as a tool arg instead of `-d`:
+**Prefer MCP** — one call for the entire chain, one event per node in `events[]`:
 ```
 mcp__eventmodelers__submit_node_events {
   "boardId": "$BOARD_ID",
-  "events": [{
-    "id": "<uuid>",
-    "eventType": "node:changed",
-    "nodeId": "<NODE_ID>",
-    "boardId": "$BOARD_ID",
-    "timestamp": <epoch-ms>,
-    "changedAttributes": ["meta.fields"],
-    "meta": { "fields": "<updated_fields_array>" }
-  }]
+  "compact": true,
+  "events": [
+    {
+      "id": "<uuid>",
+      "eventType": "node:changed",
+      "nodeId": "<NODE_ID_1>",
+      "boardId": "$BOARD_ID",
+      "timestamp": <epoch-ms>,
+      "changedAttributes": ["meta.fields"],
+      "meta": { "fields": "<updated_fields_array_1>" }
+    },
+    { "…one more event per remaining node in the chain…" }
+  ]
 }
 ```
 
-**Fallback (no MCP):** see `references/api-fallback.md` — "Step 4 — Apply the Change to Each Node in the Chain".
+Nodes that are skipped (field already exists / field not found) simply contribute no event — don't send a no-op change for them.
+
+**Fallback (no MCP):** see `references/api-fallback.md` — "Step 4 — Apply the Change to Each Node in the Chain". The REST endpoint takes the same `NodeChangeEvent[]` body, so it batches identically — one POST, not one per node.
+
+Verify the response is HTTP 200. If the batch fails, report the error and stop; nothing was partially applied from your side, so re-run after fixing the cause rather than retrying node by node.
 
-Verify HTTP 200 before proceeding to the next node. If a node fails, report the error and stop.
+If you also need to verify the result, re-read the whole chain in one call — `get_nodes { "boardId": "$BOARD_ID", "nodeIds": [<every node id you just wrote>] }` — never one `get_node` per node.
 
 ---
 

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

@@ -25,6 +25,18 @@ From `$ARGUMENTS`, extract:
 
 ---
 
+## Step 1b — Many targets at once
+
+`target` is singular, but the common real request is "fill in the examples across this chapter". When you have more than one target, **do not run this skill once per element and do not fetch context a node at a time.**
+
+1. Read the chapter **once**: `mcp__eventmodelers__get_nodes { "boardId": "$BOARD_ID", "chapterId": "$CHAPTER_ID" }`. That single response carries every element's `meta.fields` *including the `example` values already filled in* — which is exactly the canonical-value pool Step 3c asks for, for the whole chapter, in one call.
+2. Pick the canonical value per field name from that pool (e.g. `customerId: "cust-123"`, `email: "jane@example.com"`) before writing anything, so every element ends up consistent.
+3. Then fill the targets. `add_field_examples` is still the preferred writer, one call per target — but it is the *only* per-target call you should be making. If you are generating the values yourself instead, batch every element's update into a single `submit_node_events { events: [...] }` call.
+
+A run that opens each element with its own `get_node` to "read existing examples first" is doing step 1 N times over.
+
+---
+
 ## Step 2 — Resolve and generate examples (prefer MCP)
 
 `add_field_examples` is a whole-algorithm convenience tool: it resolves the node, loads linked neighbours for cross-element consistency, fills any empty field examples, and writes the result back — collapsing the entire "find node → find linked nodes → build examples → submit_node_events" flow (Steps 2–5 below) into one call. Call it with whichever identifier matches `target`:

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

@@ -7,6 +7,8 @@ description: Business analyst exploration of an event model board. Reads all sli
 
 > **Before doing anything else**, invoke the `connect` skill — if not already connected — to resolve `TOKEN`, `BOARD_ID`, and `BASE_URL`. Do not proceed until the connect skill has completed.
 
+Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect` skill) — the REST calls below are the fallback for sessions without MCP connected.
+
 This step applies the shared element rules in **`eventmodeling-core-rules`** — read it once per session if you haven't already; it defines what a COMMAND/EVENT/READMODEL/SCREEN/AUTOMATION is, the anti-patterns to reject, and the four Structural Shapes (Category I below), so this step doesn't restate them.
 
 You are a **sharp business analyst** reviewing an event model. You don't know the domain yet — you're seeing it fresh. Your job is to read the model, understand the intended flows, and ask the hard questions that developers and domain experts tend to overlook because they're too close to the problem.
@@ -26,17 +28,27 @@ If the user already provided context name in their message, use it directly.
 
 ## Step 2 — Load the model
 
-**A. Get all slices:**
+**Prefer MCP — one call loads the whole context.** `sliceId` is optional; omitting it returns the full element graph for *every* slice in the context at once. Do **not** list slices and then fetch them one by one:
+
 ```
-GET /api/org/{orgId}/boards/{boardId}/slicedata/slices
+mcp__eventmodelers__get_slice_data {
+  "boardId": "$BOARD_ID",
+  "contextName": "<context name from Step 1>",
+  "format": "textual"
+}
 ```
-This returns `{ slices: [{ id, title, status }] }`.
 
-**B. For each slice, load its full data:**
+`format` matters here because this skill reads the entire model before it writes anything. `"textual"` is a compact markdown dump and `"toon"` a token-efficient tabular encoding — both carry the same graph as `"json"` in a fraction of the tokens. Use `"json"` only when you need to read exact `x`/`y`/`width`/`height` values for the drawings in Step 4.2.
+
+Each response contains screens, commands, events, read models, specs, scenarios, actors, automations, and the edges between them.
+
+`mcp__eventmodelers__list_slices { "boardId": "$BOARD_ID" }` is only needed when you must scope to **one** slice and don't know its id, or to read slice statuses — not as a precursor to loading the model.
+
+**Fallback (no MCP):**
 ```
-GET /api/org/{orgId}/boards/{boardId}/slicedata?contextName={contextName}&sliceId={sliceId}
+GET /api/org/{orgId}/boards/{boardId}/slicedata?contextName={contextName}
 ```
-Load all slices in parallel. Each response contains the full element graph for that slice: screens, commands, events, read models, specs, scenarios, actors, automations.
+Same shape — the whole context in one request. `&sliceId={sliceId}` narrows it to one slice; `GET .../slicedata/slices` lists `{ slices: [{ id, title, status }] }`.
 
 Keep track of:
 - All slice titles and their element types
@@ -132,10 +144,30 @@ Only post questions that are **genuinely unclear or missing** — don't post obs
 
 ### 4.2 Drawings (every relational or clustered finding, always)
 
-Use `POST /api/org/{orgId}/boards/{boardId}/drawing/draw` (auth headers same as every other call — `x-token`, `x-board-id`, `x-user-id: wdyt`). There are two kinds — no text-callout kind; a drawing never carries the question itself, only the shape of the concern:
+**Prefer MCP:** `mcp__eventmodelers__create_drawing` — one call per drawing, no auth headers needed.
+
+**Fallback (no MCP):** `POST /api/org/{orgId}/boards/{boardId}/drawing/draw` (auth headers same as every other call — `x-token`, `x-board-id`, `x-user-id: wdyt`). Same fields as the tool args below.
 
-- **Arrow** (`kind: "path"`, `arrowEnd: true`) — the concern is about a missing or unclear relationship *between two elements* (e.g. "does this event actually reach this automation?"). Draw a straight line from one element's position to the other's. `path` is `M 0 0 L <dx> <dy>` in the box's own local coordinates; `x`/`y`/`width`/`height` describe that box in canvas space (so `width`/`height` = the delta between the two elements' positions). Get element positions from the slice data already loaded in Step 2 (or `GET .../nodes/{nodeId}` if not present).
-- **Group loop** (`kind: "rect"`, drawn around a computed bounding box) — the concern spans a *cluster* of elements together (e.g. "this whole flow assumes nothing ever fails"). There's no dedicated group endpoint — union the elements' own `x`/`y`/`width`/`height` (plus some padding) yourself and draw one `rect` around that box via `.../drawing/draw`. This is a visual grouping only — unrelated to the `MODEL_CONTEXT` node type; never touch a `modelContext` field to satisfy this.
+There are two kinds — no text-callout kind; a drawing never carries the question itself, only the shape of the concern:
+
+- **Arrow** (`kind: "path"`, `arrowEnd: true`) — the concern is about a missing or unclear relationship *between two elements* (e.g. "does this event actually reach this automation?"). Draw a straight line from one element's position to the other's. `path` is `M 0 0 L <dx> <dy>` in the box's own local coordinates; `x`/`y`/`width`/`height` describe that box in canvas space (so `width`/`height` = the delta between the two elements' positions).
+```
+mcp__eventmodelers__create_drawing {
+  "boardId": "$BOARD_ID", "kind": "path",
+  "x": <sourceX>, "y": <sourceY>, "width": <dx>, "height": <dy>,
+  "path": "M 0 0 L <dx> <dy>", "arrowEnd": true
+}
+```
+Get element positions from the slice data already loaded in Step 2. If a position is missing, fetch the nodes you need in **one** call — `mcp__eventmodelers__get_nodes { "boardId": "$BOARD_ID", "nodeIds": [<the ids>] }` — not `get_node` per element.
+- **Group loop** (`kind: "rect"`, drawn around a computed bounding box) — the concern spans a *cluster* of elements together (e.g. "this whole flow assumes nothing ever fails"). There's no dedicated group endpoint — union the elements' own `x`/`y`/`width`/`height` (plus some padding) yourself and draw one `rect` around that box:
+```
+mcp__eventmodelers__create_drawing {
+  "boardId": "$BOARD_ID", "kind": "rect",
+  "x": <minX - pad>, "y": <minY - pad>,
+  "width": <maxX - minX + 2*pad>, "height": <maxY - minY + 2*pad>
+}
+```
+This is a visual grouping only — unrelated to the `MODEL_CONTEXT` node type; never touch a `modelContext` field to satisfy this.
 
 Every arrow/group loop is paired with a comment on the relevant node(s) from 4.1 — the drawing makes the concern visible at a glance on the canvas itself, the comment carries the actual worded question. Post both; neither replaces the other.