@eventmodelers/cli 0.0.39 → 1.0.0

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

@@ -7,6 +7,8 @@ description: Live event storming facilitator — asks questions about any busine
 
 > **Before doing anything else**, invoke the `connect` skill to resolve `TOKEN`, `BOARD_ID`, and `BASE_URL`. Then invoke the `learn-eventmodelers-api` skill to load the full API reference. Do not proceed until both skills have been loaded.
 
+> Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect` skill) — the curl blocks below are the fallback for sessions without MCP connected.
+
 You are a live event storming facilitator. You discover domain events through conversation — or from any input (pasted text, documents, notes) — and **immediately place them on the board as they emerge**. The timeline grows and evolves in real time. You don't wait until the end.
 
 A **domain event** is something that happened in the business domain. Past tense. Meaningful to a business person. Examples: `Order Placed`, `Payment Received`, `Shipment Dispatched`, `Invoice Sent`, `Account Suspended`.
@@ -29,8 +31,14 @@ From `$ARGUMENTS` and the conversation, extract:
 
 ### 1a — Discover existing timelines
 
-Before doing anything else, fetch all chapters (timelines) on the board:
+Before doing anything else, fetch all chapters (timelines) on the board.
+
+**Prefer MCP:**
+```
+mcp__eventmodelers__get_nodes { "boardId": "<BOARD_ID>", "type": "CHAPTER" }
+```
 
+**Fallback (no MCP):**
 ```bash
 curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=CHAPTER"
 ```
@@ -50,8 +58,14 @@ curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=CHAPTER"
 
 A chapter and a timeline are the same thing — the terms are interchangeable.
 
-If `timelineId` is provided, first resolve it to a UUID if a name was given instead:
+If `timelineId` is provided, first resolve it to a UUID if a name was given instead.
+
+**Prefer MCP:**
+```
+mcp__eventmodelers__get_nodes { "boardId": "<BOARD_ID>", "type": "CHAPTER" }
+```
 
+**Fallback (no MCP):**
 ```bash
 curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=CHAPTER"
 ```
@@ -60,8 +74,14 @@ curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=CHAPTER"
 - If it looks like a name, find the CHAPTER node whose `meta.title` matches (case-insensitive) and use its `id` as `CHAPTER_ID`.
 - If no match is found, tell the user and stop.
 
-Fetch the chapter node to read its grid structure:
+Fetch the chapter node to read its grid structure.
 
+**Prefer MCP:**
+```
+mcp__eventmodelers__get_node { "boardId": "<BOARD_ID>", "nodeId": "<CHAPTER_ID>" }
+```
+
+**Fallback (no MCP):**
 ```bash
 curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$CHAPTER_ID"
 ```
@@ -71,8 +91,14 @@ From `meta.timelineData`:
 - `columns` — ordered list of columns, each with an `id`
 - `cells` — each cell has `colId`, `rowId`, and optionally `nodeId`
 
-Then load the existing EVENT nodes:
+Then load the existing EVENT nodes.
 
+**Prefer MCP:**
+```
+mcp__eventmodelers__get_nodes { "boardId": "<BOARD_ID>", "type": "EVENT" }
+```
+
+**Fallback (no MCP):**
 ```bash
 curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=EVENT"
 ```
@@ -93,8 +119,14 @@ Tell the user which timeline was loaded and how many events already exist (one l
 
 ### 1c — Creating a new timeline
 
-If no `timelineId` is provided, **create the chapter immediately** — before any events are known:
+If no `timelineId` is provided, **create the chapter immediately** — before any events are known.
 
+**Prefer MCP:**
+```
+mcp__eventmodelers__create_chapter { "boardId": "<BOARD_ID>", "x": 0, "y": 0 }
+```
+
+**Fallback (no MCP):**
 ```bash
 curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/chapters" \
   -H "Content-Type: application/json" \
@@ -152,8 +184,14 @@ Compare against the current `events` state:
 
 ### 3c — Inspect the timeline and maintain continuity
 
-Before placing any new events, fetch the chapter node to get the current grid state:
+Before placing any new events, fetch the chapter node to get the current grid state.
 
+**Prefer MCP:**
+```
+mcp__eventmodelers__get_node { "boardId": "<BOARD_ID>", "nodeId": "<CHAPTER_ID>" }
+```
+
+**Fallback (no MCP):**
 ```bash
 curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$CHAPTER_ID"
 ```
@@ -171,6 +209,12 @@ emptyColumns = [columnId, ...]   // in column order, ready to reuse
 - If you have new events to place: **reuse empty columns first** (see Step 4a) before creating new ones. This keeps the timeline contiguous.
 - After all placements, delete any columns still left in the `emptyColumns` pool — they are gaps that should not remain.
 
+**Prefer MCP:**
+```
+mcp__eventmodelers__delete_column { "boardId": "<BOARD_ID>", "timelineId": "<CHAPTER_ID>", "columnId": "<columnId>" }
+```
+
+**Fallback (no MCP):**
 ```bash
 curl -s -X DELETE "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$CHAPTER_ID/columns/<columnId>"
 ```
@@ -215,8 +259,27 @@ Compute the cell ID directly: **`CELL_ID = swimlaneRowId + "-" + columnId`**
 
 (Cell IDs are always `<rowId>-<columnId>` — no cell array search needed.)
 
-Then create the EVENT node directly (place-element Steps 6–7):
+Then create the EVENT node directly (place-element Steps 6–7).
+
+**Prefer MCP:**
+```
+mcp__eventmodelers__submit_node_events {
+  "boardId": "<BOARD_ID>",
+  "events": [{
+    "id": "<event-uuid>",
+    "eventType": "node:created",
+    "nodeId": "<node-uuid>",
+    "boardId": "<BOARD_ID>",
+    "timestamp": <Date.now()>,
+    "chapterId": "<CHAPTER_ID>",
+    "cellId": "<CELL_ID>",
+    "meta": { "type": "EVENT", "title": "<EventName>" },
+    "node": { "id": "<node-uuid>", "data": { "title": "<EventName>" } }
+  }]
+}
+```
 
+**Fallback (no MCP):**
 ```bash
 curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
   -H "Content-Type: application/json" \
@@ -236,7 +299,13 @@ curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
 
 #### If no empty column is available — create one
 
-Invoke the **place-element skill** with:
+**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>", "elementType": "EVENT", "title": "<EventName>", "columnIndex": <index> }
+```
+Extract `nodeId` and `columnId` directly from the tool result.
+
+**Fallback (no MCP):** invoke the **place-element skill** with:
 
 | Parameter | Value |
 |-----------|-------|
@@ -262,8 +331,26 @@ events.splice(index, 0, { index, title: "<EventName>", eventNodeId: "<nodeId>",
 
 ### 4b — Rename an existing event
 
-Use `eventNodeId` from your local state. Send a `node:changed` event:
+Use `eventNodeId` from your local state. Send a `node:changed` event.
 
+**Prefer MCP:**
+```
+mcp__eventmodelers__submit_node_events {
+  "boardId": "<BOARD_ID>",
+  "events": [{
+    "id": "<new-uuid>",
+    "eventType": "node:changed",
+    "nodeId": "<eventNodeId>",
+    "boardId": "<BOARD_ID>",
+    "timestamp": <Date.now()>,
+    "changedAttributes": ["meta.title"],
+    "meta": { "type": "EVENT", "title": "<NewTitle>" },
+    "node": { "id": "<eventNodeId>", "data": {} }
+  }]
+}
+```
+
+**Fallback (no MCP):**
 ```bash
 curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
   -H "Content-Type: application/json" \
@@ -288,6 +375,12 @@ Two steps — delete the node, then delete the column:
 
 **1. Delete the EVENT node:**
 
+**Prefer MCP:**
+```
+mcp__eventmodelers__delete_node { "boardId": "<BOARD_ID>", "nodeId": "<eventNodeId>" }
+```
+
+**Fallback (no MCP):**
 ```bash
 curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
   -H "Content-Type: application/json" \
@@ -301,13 +394,19 @@ curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
   }]'
 ```
 
-**2. Delete the column** using `columnId` from local state:
+**2. Delete the column** using `columnId` from local state.
+
+**Prefer MCP:**
+```
+mcp__eventmodelers__delete_column { "boardId": "<BOARD_ID>", "timelineId": "<CHAPTER_ID>", "columnId": "<columnId>" }
+```
 
+**Fallback (no MCP):**
 ```bash
 curl -s -X DELETE "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$CHAPTER_ID/columns/<columnId>"
 ```
 
-If `columnId` is not in local state, fetch the chapter node, scan `meta.timelineData.cells` for the cell where `nodeId === eventNodeId`, and use that cell's `colId`.
+If `columnId` is not in local state, fetch the chapter node (`mcp__eventmodelers__get_node { "boardId": "<BOARD_ID>", "nodeId": "<CHAPTER_ID>" }`, or the curl fallback above), scan `meta.timelineData.cells` for the cell where `nodeId === eventNodeId`, and use that cell's `colId`.
 
 Remove from local state and re-number remaining indexes.
 

package/stacks/modeling-kit/templates/.claude/skills/update-prompt-status/SKILL.md

@@ -7,6 +7,8 @@ description: Update the lifecycle status (and optionally a progress comment) of
 
 > **Before doing anything else**, invoke the `connect` skill to resolve `TOKEN`, `ORG_ID`, and `BASE_URL`. Do not proceed until the connect skill has completed.
 
+Prefer `mcp__eventmodelers__update_prompt_status` when available (registered by the `connect` skill) — the curl block below is the fallback for sessions without MCP connected. This is the one prompt-queue operation MCP does expose (submission, claiming, and deletion remain curl-only — the MCP server otherwise doesn't own this lifecycle).
+
 Every prompt drained from a board's queue (`/api/org/:orgId/prompts/next`) carries a `PROMPT_ID` — passed into this session as the `prompt_id` field of the current turn. This skill flips that prompt's status so the board UI reflects what the agent is doing with it in real time.
 
 ---
@@ -36,6 +38,13 @@ If `newStatus` is not one of these exact values, stop and tell the user the vali
 
 ## Step 2 — Update the status
 
+**Prefer MCP:**
+```
+mcp__eventmodelers__update_prompt_status { "promptId": "<PROMPT_ID>", "newStatus": "<newStatus>", "comment": "<comment>" }
+```
+Omit `comment` entirely when there isn't one — don't pass an empty string.
+
+**Fallback (no MCP):**
 ```bash
 curl -s -X POST "$BASE_URL/api/org/$ORG_ID/prompts/$PROMPT_ID/status" \
   -H "Content-Type: application/json" \

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

@@ -1,6 +1,6 @@
 ---
 name: wdyt
-description: Business analyst exploration of an event model board. Reads all slices, analyzes them from a business perspective, and posts questions/observations as QUESTION-type comments on relevant nodes to uncover gaps, edge cases, and missing scenarios.
+description: Business analyst exploration of an event model board. Reads all slices, analyzes them from a business perspective, and posts questions/observations as QUESTION-type comments on relevant nodes. Findings about a relationship between elements or a cluster of elements are always additionally drawn on the canvas (arrows, group loops) — comments carry every textual question, drawings carry every visual/structural hint.
 ---
 
 # WDYT — What Do You Think?
@@ -95,7 +95,14 @@ Every question and every summary theme must be written in plain business languag
 
 ---
 
-## Step 4 — Post questions as comments
+## Step 4 — Comments carry every textual question; drawings carry every visual/structural hint
+
+The two channels have a strict division of labor, always applied the same way — never swap them:
+
+- **Every textual question is a comment.** If the finding is "what happens / who does this / what do we expect" about a single element, it is worded and lives only in a `QUESTION` comment. Never draw a text callout on the canvas to carry a question — that content belongs in 4.1, full stop.
+- **Every visual/structural hint is a drawing.** If the finding is inherently about *where things are relative to each other* — a relationship between two elements, or a cluster of elements sharing one concern — it is always additionally drawn on the canvas (4.2), not left as text alone. This isn't a selective "top 3" step; it's determined by the shape of the finding itself: relational or clustered → draw it, every time.
+
+### 4.1 Comments (every textual question, always)
 
 For each question you want to ask, post it as a `QUESTION`-type comment on the most relevant node (the COMMAND, EVENT, SCREEN, or READMODEL the question is about). If a question is about the whole slice rather than a specific element, post it on the first/primary EVENT of the slice.
 
@@ -109,6 +116,17 @@ The comment API has no batch endpoint — `handle-comment` sends one request per
 
 Only post questions that are **genuinely unclear or missing** — don't post observations that are clearly intentional design decisions.
 
+### 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:
+
+- **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.
+
+Every arrow/group loop is paired with a `QUESTION` 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.
+
+A finding about a single element with no relational or cluster dimension gets a comment only — don't manufacture an arrow or loop for it just to add a drawing.
+
 ---
 
 ## Step 5 — Report back to the user
@@ -117,8 +135,9 @@ After posting all comments, give the user a concise summary:
 
 1. **Flows analysed**: count and list them by their business name
 2. **Total questions posted**: count (it is perfectly fine if this is 0 — don't force questions)
-3. **Top themes** as business questions, not modelling observations. Examples of good themes: "What happens when registration fails?", "Who is allowed to register a customer?", "What do we expect when invalid data is submitted?" — never: "No failure modelling", "No specs", "No actor on command"
-4. **One concrete next step** — only if there's a clear gap worth highlighting
+3. **Visual annotations added**: count and a one-line description of each (e.g. "arrow from OrderPlaced to ShipOrder — unclear if it always fires")
+4. **Top themes** as business questions, not modelling observations. Examples of good themes: "What happens when registration fails?", "Who is allowed to register a customer?", "What do we expect when invalid data is submitted?" — never: "No failure modelling", "No specs", "No actor on command"
+5. **One concrete next step** — only if there's a clear gap worth highlighting
 
 Keep the report tight. If there are no meaningful questions, say so — don't pad it out.
 

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

@@ -35,7 +35,9 @@ At the start of every session, read `.agent-modeling-kit/AGENTS.md` if it exists
    **Resolve `NODE_ID`** from the first entry of this turn's `context.selectedNodes`, if that array is present and non-empty; otherwise use this turn's `node_id` field. `context.selectedNodes` reflects what was actually selected on the canvas when the prompt was issued, which can differ from `node_id` — set only when the prompt originated from a specific node/comment — so it wins whenever both are present.
    **Resolve `CELL_ID`** from this turn's `context.selectedCell.id`, if present and non-null. When present, it overrules any cell reference (e.g. `"A2"`) parsed from the prompt text itself — it reflects the actual cell the user had selected on the canvas when they issued the prompt, and is more reliable than free-text parsing.
 4. **Mark the prompt as started** — invoke `/update-prompt-status` with this turn's `prompt_id` and `newStatus=IN_PROGRESS`, before doing any of the actual work below. This is what makes the board UI show the prompt as being actively worked on.
-5. Execute the prompt using the skill matched in the Skill Selection table below, passing the resolved `TIMELINE_ID`, `NODE_ID`, and `CELL_ID` from step 3 as that skill's `timelineId`/node-reference/`cellName` arguments (not the raw `timeline_id`/`node_id` fields, and not a cell reference parsed from the prompt text). For a skill like `/place-element` that accepts a `cellName`, pass the resolved `CELL_ID` as `cellName` whenever it's present — skip parsing the prompt text for a cell reference entirely in that case.
+5. **Invoke the matched skill — never substitute direct tool calls for it.** Execute the prompt using the skill matched in the Skill Selection table below, passing the resolved `TIMELINE_ID`, `NODE_ID`, and `CELL_ID` from step 3 as that skill's `timelineId`/node-reference/`cellName` arguments (not the raw `timeline_id`/`node_id` fields, and not a cell reference parsed from the prompt text). For a skill like `/place-element` that accepts a `cellName`, pass the resolved `CELL_ID` as `cellName` whenever it's present — skip parsing the prompt text for a cell reference entirely in that case.
+
+   `mcp__eventmodelers__*` tools (and the REST fallback) are building blocks a skill calls *internally* once you've invoked it — they are not a substitute for invoking the skill. Being able to see `mcp__eventmodelers__get_node`/`create_slice`/etc. in your tool list does not mean you should reach for them directly to satisfy a prompt that matches a row in the Skill Selection table: e.g. "add the next slice" always goes through `/eventmodeling-slicing-event-models` (falling through to `/add-next-slice` when nothing existing is left to slice) or `/place-element`, even though technically a couple of raw MCP calls could produce something on the board. The skill is what encodes the actual domain reasoning (which node type follows which, naming, field derivation, dependency notes) — a raw tool call skips all of that and produces a shallower result even when it "works." Only call MCP/REST directly when no row in the table matches the prompt's intent at all.
    **Questioning rule**: you are running autonomously — no human is available to answer questions. If you need clarification, do not pause or ask interactively — post a `QUESTION`-type comment (`/handle-comment` with `action=place`, `type=QUESTION`) on the most relevant node. Then:
    - If a reasonable default interpretation exists, continue with it.
    - If it doesn't — the prompt is ambiguous enough that any guess risks doing the wrong thing — stop instead of guessing. Skip straight to step 6 and mark the prompt `DONE` with a comment explaining what's unclear and pointing to the `QUESTION` comment you just posted. Never leave a prompt neither progressed nor closed.
@@ -52,13 +54,15 @@ At the start of every session, read `.agent-modeling-kit/AGENTS.md` if it exists
 | Add, rename, or reorder events on a timeline | `/timeline` |
 | Place a COMMAND, READMODEL, or EVENT at a position | `/place-element` |
 | Generate a full storyboard with multiple screens | `/storyboard` |
-| Design or update a single wireframe screen | `/storyboard-screen` |
-| Design or update a single real HTML/CSS screen (explicit request only) | `/html-screen` |
+| Design or update a single screen | `/html-screen` |
+| Design or update a single wireframe/sketch screen (explicit request only) | `/storyboard-screen` |
 | Business analysis, gap spotting, posting questions | `/wdyt` |
 | Analyse the existing model structure, slice coverage, element counts | `/analyze-existing-model` |
 | Look up any API endpoint or element type | `/learn-eventmodelers-api` |
 | Add or rename an attribute across a chain of elements | `/attributes` |
 | Add or improve example data on element fields | `/examples` |
+| Make an existing timeline element's (COMMAND/READMODEL/AUTOMATION) slice explicit | `/eventmodeling-slicing-event-models` |
+| Add the next slice when nothing existing is left to slice | `/add-next-slice` |
 | Update the status of a slice (e.g. done, in-progress) | `/update-slice-status` |
 | Update the status of the current prompt (e.g. in-progress, done) | `/update-prompt-status` |
 

package/stacks/node/templates/.claude/skills/build-state-view/SKILL.md

@@ -43,16 +43,22 @@ CREATE TABLE IF NOT EXISTS "public"."{tablename}"
 );
 ```
 
-**Column type guide:**
+**Column type guide** — field `type` values are the canonical set from the [event-modeling-spec schema](https://github.com/dilgerma/event-modeling-spec/blob/main/eventmodeling.schema.json):
 
 | Field type | SQL type |
 |-----------|---------|
-| string / UUID | `TEXT` |
-| number (integer) | `INTEGER` |
-| number (float) | `NUMERIC` |
-| boolean | `BOOLEAN` |
-| date | `TIMESTAMP` |
-| nullable number | `INTEGER` (allow NULL) |
+| `String` | `TEXT` |
+| `UUID` | `TEXT` |
+| `Int` | `INTEGER` |
+| `Long` | `BIGINT` |
+| `Double` | `DOUBLE PRECISION` |
+| `Decimal` | `NUMERIC` |
+| `Boolean` | `BOOLEAN` |
+| `Date` | `DATE` |
+| `DateTime` | `TIMESTAMP` |
+| `Custom` | `JSONB` |
+
+Nullable columns (`optional: true` on the field): allow `NULL` instead of adding a default.
 
 The PRIMARY KEY column is the one used in `.onConflict(...)` in the projection.
 

package/stacks/supabase/templates/.claude/skills/build-state-view/SKILL.md

@@ -43,16 +43,22 @@ CREATE TABLE IF NOT EXISTS "public"."{tablename}"
 );
 ```
 
-**Column type guide:**
+**Column type guide** — field `type` values are the canonical set from the [event-modeling-spec schema](https://github.com/dilgerma/event-modeling-spec/blob/main/eventmodeling.schema.json):
 
 | Field type | SQL type |
 |-----------|---------|
-| string / UUID | `TEXT` |
-| number (integer) | `INTEGER` |
-| number (float) | `NUMERIC` |
-| boolean | `BOOLEAN` |
-| date | `TIMESTAMP` |
-| nullable number | `INTEGER` (allow NULL) |
+| `String` | `TEXT` |
+| `UUID` | `TEXT` |
+| `Int` | `INTEGER` |
+| `Long` | `BIGINT` |
+| `Double` | `DOUBLE PRECISION` |
+| `Decimal` | `NUMERIC` |
+| `Boolean` | `BOOLEAN` |
+| `Date` | `DATE` |
+| `DateTime` | `TIMESTAMP` |
+| `Custom` | `JSONB` |
+
+Nullable columns (`optional: true` on the field): allow `NULL` instead of adding a default.
 
 The PRIMARY KEY column is the one used in `.onConflict(...)` in the projection.