@eventmodelers/cli 1.0.9 → 1.0.11

package/package.json

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

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

@@ -29,7 +29,8 @@ Server name: `eventmodelers`. Every tool takes `boardId` explicitly; none need `
 | `delete_node` | `boardId`, `nodeId` | Delete a node. 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) |
 | `create_drawing` | `boardId`, `kind`, `x`, `y`, `width`, `height`, ... | Freehand canvas annotation (path/rect/text) — never placed in a cell | — (no REST equivalent; MCP-only) |
 | `find_nodes_in_drawing` | `boardId`, `drawingId` | Nodes fully contained inside a drawing's bounding box | — (no REST equivalent; MCP-only) |
-| `create_chapter` | `boardId`, `x?`, `y?` | Create a timeline | §2 `POST .../chapters` |
+| `create_chapter` | `boardId`, `x?`, `y?` | Create a timeline. Omitting `x`/`y` auto-stacks it below the lowest existing chapter (by its *actual current* row-height total, not the height it was created with — safe even after `add_lane` growth), plus a fixed margin | §2 `POST .../chapters` |
+| `get_chapter_bounds` | `boardId` | Absolute canvas bounding box `{id, title, x, y, width, height}` of every chapter on the board — width/height derived from each chapter's current row/column layout, not a guessed default. Use before picking explicit `x`/`y` for `create_chapter` (e.g. placing below the chapter with the largest `y + height`) to avoid overlapping one that grew since it was created | §2 `GET .../chapters/bounds` |
 | `add_column` | `boardId`, `timelineId`, `index?` | Add a column | §2 `POST .../timelines/:id/columns` |
 | `delete_column` | `boardId`, `timelineId`, `columnId` | Delete a column | §2 `DELETE .../columns/:columnId` |
 | `add_lane` | `boardId`, `timelineId`, `type`, `label?`, `index?` | Add a lane/row | §2 `POST .../timelines/:id/lanes` |
@@ -47,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` | EVENT/COMMAND/READMODEL nodes valid in GWT steps | §6 `GET .../spec-info` |
 | `add_scenario` | `boardId`, `timelineId`, `columnId`, `scenarios[]` | Append GWT scenario(s) to a column's spec node | §6 `POST .../scenarios` |
+| `add_storyline` | `boardId`, `timelineId`, `columnId`, `storylines[]` | **Experimental — only use when explicitly asked for a storyline/walkthrough.** Append storyline(s) (ordered, branchable beats over existing elements) to a column's spec node | §6 `POST .../storylines` |
 | `set_connection` | `boardId`, `source`, `target`, `action` (`'connect'\|'remove'`) | Add or remove a type-checked directed edge | — (via `edges` on §3 events) |
 | `auto_connect_node` | `boardId`, `nodeId` | Re-run auto-connect for a node | §3 `POST .../nodes/:nodeId/auto-connect` |
 | `add_comment` | `boardId`, `nodeId`, `text`, `type?` (`'COMMENT'\|'TASK'\|'QUESTION'`), `author?` | Add a comment — `QUESTION` flags gaps/edge cases during review | — (via comment events) |
@@ -217,6 +219,15 @@ Create a chapter node.
 **Request body**: `{ position?: { x: number, y: number } }`  
 **Response**: `200` — chapter data
 
+Omitting `position` auto-stacks the new chapter below the lowest existing chapter on the board, using each existing chapter's *actual current* row-height total (not the height it was created with) plus a fixed margin — so a chapter that grew via `add_lane`/`add_column` after another was stacked below it won't get overlapped by yet another auto-stacked chapter.
+
+---
+
+### GET `/api/org/:orgId/boards/:boardId/chapters/bounds`
+Get the absolute canvas bounding box of every chapter on the board — the same real-current-size derivation `create_chapter`'s auto-stacking uses internally, exposed for callers who want to compute a placement themselves (e.g. an explicit `x`/`y`, or a position relative to a specific chapter rather than "below everything").
+
+**Response**: `200` — `{ chapters: Array<{ id: string, title?: string, x: number, y: number, width: number, height: number }> }`
+
 ---
 
 ### POST `/api/org/:orgId/boards/:boardId/timelines/:timelineId/columns`
@@ -513,6 +524,48 @@ Get valid elements for a specific slice.
 
 ---
 
+### Storylines (experimental)
+
+> **Only create a storyline when the user's request explicitly asks for one** — the word
+> "storyline", "walkthrough", or "narrative" (or equivalent) must appear in what they asked for.
+> Otherwise keep creating normal GWT scenarios via `add_scenario`/`POST .../scenarios` as before.
+
+An ordered, branchable walkthrough of existing board elements ("beats"), stored alongside GWT
+scenarios on the same SCENARIO spec node, in a sibling `meta.storylines` collection.
+
+### POST `/api/org/:orgId/boards/:boardId/timelines/:timelineId/columns/:columnId/storylines`
+Append one or more storylines to a column's spec node. The spec node is auto-created if missing
+(shared with scenarios).
+
+**Request body**: a single storyline object or an array:
+```typescript
+{
+  id: string
+  title: string          // must be unique within the spec node
+  description?: string
+  layout?: 'horizontal' | 'vertical'
+  beats: Array<{
+    instanceId: string   // unique per beat, even when refId repeats
+    refId: string        // board node id — must belong to the same timeline
+    type?: string
+    title?: string
+    isError?: boolean    // marks an alternate/error branch off the previous beat
+    fields?: unknown[]
+    expectEmptyList?: boolean
+    exampleMode?: string
+    examples?: unknown[]
+  }>
+}
+```
+
+**Response**:
+- `201` — `{ specNodeId, storylines, added, isNewNode }`
+- `400` — validation error
+- `404` — timeline, column, or referenced node not found
+- `409` — duplicate storyline title
+
+---
+
 ## 7. Config Import
 
 **File**: `src/slices/change/config-import/routes.ts`

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-elaborating-scenarios/SKILL.md

@@ -13,6 +13,61 @@ allowed-tools:
 
 Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect` skill) — the curl blocks below are the fallback for sessions without MCP connected.
 
+## Storylines — an On-Demand Alternative to GWT Scenarios (Experimental)
+
+**By default, this skill always produces GWT scenarios.** Storylines are a separate, experimental
+artifact — only build one when the user's request explicitly asks for a "storyline", "walkthrough",
+or "narrative". Never generate a storyline as a side effect of ordinary scenario elaboration.
+
+A GWT scenario asserts one isolated transition: a single precondition, a single action, a single
+resulting outcome. A storyline instead narrates one specific use case as an ordered sequence of
+**beats**, where the *same* element (usually a read model) is walked through multiple states across
+one flow — something no single GWT scenario can express, since GWT only ever asserts one
+before/after pair at a time.
+
+**Example** — a customer-activation walkthrough of a Todos read model:
+1. **Beat 1** — the Todos read model, starting empty.
+2. **Beat 2** — after a `CustomerRegistered` event, the same Todos read model now shows one entry
+   (an "activate your account" todo).
+3. **Beat 3** — after a `CustomerActivated` event, the same Todos read model is empty again (the
+   todo was completed and removed).
+
+Three separate GWT scenarios could each assert one of those transitions in isolation, but a
+storyline threads all three together as one narrated walkthrough of the read model's lifecycle —
+useful for a stakeholder-facing walkthrough of a use case, not for exhaustive GWT coverage. Keep
+producing ordinary Given/When/Then scenarios for everything else.
+
+### Storyline data shape
+
+```json
+{
+  "id": "<uuid>",
+  "title": "Customer activation walkthrough",
+  "description": "Optional narrative summary",
+  "layout": "horizontal",
+  "beats": [
+    { "instanceId": "<uuid>", "refId": "<readmodel-node-id>", "type": "READMODEL", "title": "Todos", "exampleMode": "list", "expectEmptyList": true, "examples": [] },
+    { "instanceId": "<uuid>", "refId": "<event-node-id>", "type": "EVENT", "title": "CustomerRegistered" },
+    { "instanceId": "<uuid>", "refId": "<readmodel-node-id>", "type": "READMODEL", "title": "Todos", "exampleMode": "list", "examples": [{"task": "Activate your account"}] },
+    { "instanceId": "<uuid>", "refId": "<event-node-id-2>", "type": "EVENT", "title": "CustomerActivated" },
+    { "instanceId": "<uuid>", "refId": "<readmodel-node-id>", "type": "READMODEL", "title": "Todos", "exampleMode": "list", "expectEmptyList": true, "examples": [] }
+  ]
+}
+```
+
+- `layout`: `"horizontal"` or `"vertical"` — how the beats are laid out in the storyline editor.
+- Each beat has an `instanceId` (unique per beat, even when the same `refId` repeats — this is what
+  lets the *same* element, like the Todos read model above, appear multiple times across the
+  walkthrough, once per state) and a `refId` (the board node this beat walks through — any element
+  type, not just EVENT/COMMAND/READMODEL — e.g. a SCREEN beat to show the resulting UI).
+- `isError` marks a beat as an alternate/error branch off the previous beat.
+- `fields`, `expectEmptyList`, `exampleMode`, `examples` mirror the same fields GWT scenario steps
+  use, letting a beat show concrete example data the same way a "then" readmodel step does.
+
+Post storylines via `POST .../timelines/:tl/columns/:col/storylines` (see `learn-eventmodelers-api`
+for the full endpoint contract) — the same auto-create-if-missing SCENARIO spec node scenarios use,
+in a sibling `meta.storylines` collection.
+
 ## Interview Phase (Optional)
 
 **When to Interview**: Skip if the user has already specified: scenario coverage depth (happy path + validation + state violations), known edge cases to include, and stakeholders available for review. Interview when coverage goals are unclear or edge cases haven't been identified.