@eventmodelers/cli 1.0.61 → 1.0.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.61",
+  "version": "1.0.62",
   "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/stacks/modeling-kit/templates/.claude/skills/attributes/SKILL.md

@@ -59,24 +59,26 @@ 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:**
+Resolve the whole walk from **one** chapter-scoped read rather than a `get_node` per hop — `get_board_outline { "boardId": "$BOARD_ID", "chapterId": "$TIMELINE_ID" }` returns every node in the chapter (`{id, type, title, lane}` per column) *plus* a flat edge list, which is exactly what the traversal needs. Index it in memory and walk it locally; you only need the per-node `meta.fields` (Step 4), which one `get_nodes { "boardId": "$BOARD_ID", "chapterId": "$TIMELINE_ID" }` returns for the whole chapter in a single call.
+
+Reach for a single-node fetch only for a node genuinely outside that chapter:
 ```
-mcp__eventmodelers__get_node { "boardId": "$BOARD_ID", "nodeId": "$EDGE_SOURCE_ID" }
+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".
 
 ### 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:
+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 +88,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 +116,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`: