@eventmodelers/cli 0.0.39 → 1.0.1

package/shared/build-kit/lib/ralph.js

@@ -5,11 +5,11 @@
 //   onTask(prompt) — called when tasks.json has entries
 //   onPlannedSlice(prompt) — called when .slices/ has a "Planned" entry (omit to skip)
 
-import { createClient } from '@supabase/supabase-js';
 import { readFileSync, mkdirSync, writeFileSync, existsSync, readdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { homedir } from 'os';
 import { randomUUID } from 'crypto';
+import { createRealtimeAdapter } from './adapters/realtime-adapter.js';
 
 // ── HTTP helpers ──────────────────────────────────────────────────────────────
 
@@ -242,6 +242,20 @@ async function writeTask(payload, kitDir) {
   console.log(`[agent] Task written — slice="${payload.sliceTitle}" status="${payload.sliceStatus}"`);
 }
 
+async function handleSliceChanged(payload, cfg, kitDir, queueAllStatuses) {
+  console.log(`[agent] slice:changed — slice="${payload.sliceTitle}" status="${payload.sliceStatus}"`);
+  await retryOn401('fetchAndPersistSlices', () => fetchAndPersistSlices(cfg, kitDir)).catch((err) =>
+    console.error('[agent] Slice persist error:', err),
+  );
+  // Planned slices are handled by onPlannedSlice directly — no task needed.
+  // queueAllStatuses opts out of that split entirely (e.g. bridge has no
+  // onPlannedSlice consumer, so a lingering Planned slice would otherwise
+  // never naturally clear its own trigger — see lib/ralph.js callers).
+  if (queueAllStatuses || (payload.sliceStatus || '').toLowerCase() !== 'planned') {
+    await writeTask(payload, kitDir).catch((err) => console.error('[agent] writeTask error:', err));
+  }
+}
+
 async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllStatuses = false } = {}) {
   let realtimeToken = await retryOn401('getRealtimeToken', () => getRealtimeToken(cfg));
 
@@ -249,41 +263,26 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllSt
     console.error('[agent] Initial slice fetch error:', err),
   );
 
-  const supabase = createClient(cfg.supabaseUrl, cfg.supabaseAnonKey, {
-    realtime: { params: { apikey: cfg.supabaseAnonKey } },
-  });
-  await supabase.realtime.setAuth(realtimeToken);
-
   const channelName = `board:${cfg.boardId}-slicechanged`;
-
-  supabase
-    .channel(channelName, { config: { private: true } })
-    .on('broadcast', { event: 'message' }, (msg) => {
-      if (msg.payload === 'Exit') {
-        console.log('[agent] Received "Exit" — shutting down');
-        process.exit(0);
-      }
-    })
-    .on('broadcast', { event: 'slice:changed' }, async (msg) => {
-      const payload = msg.payload;
-      console.log(`[agent] slice:changed — slice="${payload.sliceTitle}" status="${payload.sliceStatus}"`);
-      await retryOn401('fetchAndPersistSlices', () => fetchAndPersistSlices(cfg, kitDir)).catch((err) =>
-        console.error('[agent] Slice persist error:', err),
-      );
-      // Planned slices are handled by onPlannedSlice directly — no task needed.
-      // queueAllStatuses opts out of that split entirely (e.g. bridge has no
-      // onPlannedSlice consumer, so a lingering Planned slice would otherwise
-      // never naturally clear its own trigger — see lib/ralph.js callers).
-      if (queueAllStatuses || (payload.sliceStatus || '').toLowerCase() !== 'planned') {
-        await writeTask(payload, kitDir).catch((err) => console.error('[agent] writeTask error:', err));
-      }
-    })
-    .subscribe((status) => console.log(`[agent] Channel "${channelName}": ${status}`));
+  const realtime = await createRealtimeAdapter(cfg, realtimeToken);
+  realtime.subscribe(
+    channelName,
+    {
+      message: (payload) => {
+        if (payload === 'Exit') {
+          console.log('[agent] Received "Exit" — shutting down');
+          process.exit(0);
+        }
+      },
+      'slice:changed': (payload) => handleSliceChanged(payload, cfg, kitDir, queueAllStatuses),
+    },
+    (status) => console.log(`[agent] Channel "${channelName}": ${status}`),
+  );
 
   setInterval(async () => {
     try {
       realtimeToken = await retryOn401('getRealtimeToken (refresh)', () => getRealtimeToken(cfg));
-      supabase.realtime.setAuth(realtimeToken);
+      await realtime.setAuth(realtimeToken);
       console.log('[agent] Token refreshed');
     } catch (err) {
       console.error('[agent] Token refresh failed:', err);

package/shared/build-kit/package.json

@@ -6,6 +6,8 @@
     "start": "node ralph.js"
   },
   "dependencies": {
-    "@supabase/supabase-js": "^2.0.0"
+    "@supabase/supabase-js": "^2.0.0",
+    "eventsource": "^3.0.7",
+    "pocketbase": "^0.27.0"
   }
 }

package/shared/build-kit/ralph-claude.js

@@ -15,19 +15,77 @@ const inlineHeader = cfg.boardId
   ? `board=${cfg.boardId} token=${cfg.token} org=${cfg.organizationId} baseUrl=${cfg.baseUrl}\n\n`
   : '';
 
-const claudeArgs = ['--dangerously-skip-permissions'];
+// --verbose here (set via `eventmodelers run --verbose`, passed down as RALPH_VERBOSE)
+// logs full tool input and assistant reasoning text; the default (condensed) mode logs
+// only the high-level step — a skill name, or a bare tool name — mirroring `run --modeling`'s
+// own two-tier logging in cli.js.
+const verbose = process.env.RALPH_VERBOSE === '1';
+
+const claudeArgs = ['--dangerously-skip-permissions', '--output-format', 'stream-json', '--verbose'];
 if (cfg.model) claudeArgs.push('--model', cfg.model);
-const claudeEnv = cfg.anthropicBaseUrl
-  ? { ...process.env, ANTHROPIC_BASE_URL: cfg.anthropicBaseUrl }
-  : process.env;
+const claudeEnv = {
+  ...process.env,
+  ...(cfg.anthropicBaseUrl ? { ANTHROPIC_BASE_URL: cfg.anthropicBaseUrl } : {}),
+  ...(cfg.token ? { EVENTMODELERS_TOKEN: cfg.token } : {}),
+};
+
+// Collapses whitespace/newlines to a single line and truncates past `max` chars — a long
+// multi-line curl command wrapped across many terminal lines is just as unreadable as no
+// detail at all. Keeps one tool call to one log line.
+function oneLine(s, max) {
+  const collapsed = String(s ?? '').replace(/\s+/g, ' ').trim();
+  return collapsed.length > max ? `${collapsed.slice(0, max)}…` : collapsed;
+}
+
+function describeToolUse(block) {
+  const input = block.input ?? {};
+  switch (block.name) {
+    case 'Bash': return `Bash: ${oneLine(input.command, 100)}`;
+    case 'Skill': return `Skill: ${input.skill}${input.args ? ` ${oneLine(input.args, 60)}` : ''}`;
+    case 'Read': return `Read: ${input.file_path}`;
+    case 'Edit': return `Edit: ${input.file_path}`;
+    case 'Write': return `Write: ${input.file_path}`;
+    case 'Grep': return `Grep: ${oneLine(input.pattern, 60)}`;
+    case 'Glob': return `Glob: ${input.pattern}`;
+    case 'WebFetch': return `WebFetch: ${input.url}`;
+    case 'Agent': return `Agent: ${oneLine(input.description ?? input.subagent_type ?? '', 60)}`;
+    default: return block.name;
+  }
+}
 
 function runClaude(prompt) {
   return new Promise((resolve, reject) => {
     const proc = spawn('claude', [...claudeArgs, '-p', inlineHeader + prompt], {
       cwd: projectDir,
-      stdio: 'inherit',
+      stdio: ['inherit', 'pipe', 'inherit'],
       env: claudeEnv,
     });
+
+    let buffer = '';
+    proc.stdout.on('data', (chunk) => {
+      buffer += chunk.toString();
+      const lines = buffer.split('\n');
+      buffer = lines.pop();
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        let msg;
+        try { msg = JSON.parse(line); } catch { continue; }
+
+        if (msg.type === 'assistant') {
+          for (const block of msg.message?.content ?? []) {
+            if (block.type === 'text' && block.text && verbose) console.log(block.text);
+            if (block.type === 'tool_use') {
+              if (verbose) console.log(`→ ${describeToolUse(block)}`);
+              else if (block.name === 'Skill') console.log(`→ Skill: ${block.input?.skill ?? ''}`);
+              else console.log(`→ ${block.name}`);
+            }
+          }
+        } else if (msg.type === 'result') {
+          console.log(`done (${msg.duration_ms}ms${msg.total_cost_usd ? `, $${msg.total_cost_usd.toFixed(4)}` : ''})`);
+        }
+      }
+    });
+
     proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`Claude exited ${code}`))));
     proc.on('error', reject);
   });

package/shared/skills/connect/SKILL.md

@@ -7,6 +7,10 @@ description: Resolve eventmodelers connection config (token, boardId, baseUrl) f
 
 **Every other skill invokes this skill first** before making any API calls. Do not proceed past this skill until all four values (`TOKEN`, `BOARD_ID`, `ORG_ID`, `BASE_URL`) are resolved.
 
+**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.
+
+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.
+
 ---
 
 ## What this skill produces
@@ -20,7 +24,7 @@ After running, the following variables are available for the rest of the session
 | `ORG_ID` | — | Organization UUID (used in all board-scoped URLs) |
 | `BASE_URL` | — | Base URL, e.g. `http://localhost:3000` |
 
-Every API call in every skill must include these headers:
+Every curl-fallback call in every skill must include these headers:
 ```
 x-token: <TOKEN>
 x-board-id: <BOARD_ID>
@@ -29,6 +33,8 @@ x-user-id: <skill-name>   ← set by each skill individually
 
 All board-scoped URLs follow the pattern: `<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/...`
 
+When calling MCP tools instead, no `x-*` headers are needed — the MCP server resolves `ORG_ID` from `TOKEN` itself and every tool takes `boardId` as an explicit argument. See `learn-eventmodelers-api` for the full tool catalog.
+
 ---
 
 ## Step 0 — Check for inline parameters
@@ -138,9 +144,51 @@ Tell the user: `"Config saved to .eventmodelers/config.json and added to .gitign
 
 ---
 
+## Step 3.5 — Register the MCP server
+
+Always run this step (not only when Step 3 ran) — it's idempotent and safe to repeat every time `connect` is invoked.
+
+The eventmodelers backend exposes the same board capabilities as an MCP server at `<BASE_URL>/mcp`, authenticated with the same `TOKEN` via an `x-token` header. Register it in the project's `.mcp.json` so Claude Code (or any other MCP-aware host) can connect and expose tools as `mcp__eventmodelers__<tool_name>`.
+
+**Do not put the raw token in `.mcp.json`** — that file is typically committed to share server config with the team. Instead reference an environment variable and keep the actual secret in a gitignored `.env` file:
+
+1. Read the existing `.mcp.json` at the project root if present (it may already list other MCP servers, e.g. a browser-automation server used by `discover-storyboard` — merge into `mcpServers`, never replace the whole file). If absent, start from `{"mcpServers": {}}`.
+2. Add or update the `eventmodelers` entry:
+   ```json
+   {
+     "mcpServers": {
+       "eventmodelers": {
+         "type": "http",
+         "url": "<BASE_URL>/mcp",
+         "headers": { "x-token": "${EVENTMODELERS_TOKEN}" }
+       }
+     }
+   }
+   ```
+3. Ensure a project-root `.env` file contains `EVENTMODELERS_TOKEN=<TOKEN>` (append/update the line; create the file if missing).
+4. Ensure `.env` is listed in `.gitignore` (same check-then-append pattern as Step 3 uses for `.eventmodelers/config.json`) — it holds the same secret and must never be committed.
+
+MCP tools only become visible to the current agent session after the host (re)connects to the server — a brand-new `.mcp.json` entry written mid-session may need the user to approve the new server or reconnect (e.g. Claude Code's `/mcp` command) before `mcp__eventmodelers__*` tools appear in the tool list. That's expected and not an error: tell the user once, then let every other skill fall back to curl automatically until the tools show up.
+
+---
+
 ## Step 4 — Verify
 
-Confirm the token and board are valid with a lightweight call:
+Prefer verifying through MCP if `mcp__eventmodelers__*` tools are already visible in this session (e.g. from a `.mcp.json` set up in an earlier turn or a previous session):
+
+```
+mcp__eventmodelers__get_nodes { "boardId": "<BOARD_ID>", "type": "CHAPTER" }
+```
+
+A successful result (even an empty array) confirms the token and board are valid. An error mentioning "not found or access denied" means the token/board pairing is wrong — treat it like the `403`/`404` curl cases below.
+
+If the MCP server itself shows as needing authentication (e.g. the host lists it as "needs authentication" rather than connected), ask the user once:
+
+> "The eventmodelers MCP server needs to be re-authenticated — please run `/mcp` and authenticate the `eventmodelers` server, then let me know when that's done."
+
+Wait for their reply. If they say it's done, retry the MCP verify call above. If they skip it, or it still isn't connected, or it's unreachable for some other reason entirely (not an auth prompt), don't keep blocking on it — fall back to the equivalent curl call for this and every subsequent skill in the session, same as if the tools were never visible.
+
+Otherwise (no MCP tools visible yet this session), fall back to the equivalent curl call:
 
 ```bash
 curl -s -o /dev/null -w "%{http_code}" \
@@ -152,7 +200,7 @@ curl -s -o /dev/null -w "%{http_code}" \
 
 | Response | Action |
 |----------|--------|
-| `200` | Config is valid. Print one line: `"Connected — board <BOARD_ID>"` and return. |
+| `200` | Config is valid. Print one line: `"Connected — board <BOARD_ID>"` (note if MCP tools aren't active yet, curl fallback is in use) and return. |
 | `401` | Token is invalid or missing. Tell the user and re-run from Step 2, clearing `token`. |
 | `403` | Token organization does not match board. Tell the user to check that the token was issued for the correct workspace. Re-run from Step 2 for both fields. |
 | `404` | Board not found. Tell the user and re-run from Step 2, clearing `boardId`. |
@@ -178,6 +226,7 @@ The `token` field is a secret. It is never logged or shown after initial confirm
 
 ## Security notes
 
-- The config file is workspace-local and gitignored — never commit it.
+- The config file (`.eventmodelers/config.json`) and the `.env` file holding `EVENTMODELERS_TOKEN` are both workspace-local and gitignored — never commit either.
+- `.mcp.json` itself is safe to commit — it only ever contains the `${EVENTMODELERS_TOKEN}` placeholder, never the literal token.
 - The token grants write access to all boards in its organization — treat it like a password.
-- If a skill receives a `401` or `403` mid-session, re-invoke this skill to refresh the config before retrying.
+- If a skill receives a `401`/`403` (curl) or an access-denied tool error (MCP) mid-session, re-invoke this skill to refresh the config before retrying.

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

@@ -5,7 +5,65 @@ description: Teaches an agent everything about the eventmodelers platform API
 
 # Eventmodelers Platform API Reference
 
-You now have complete knowledge of the eventmodelers platform API. Use this reference whenever you need to call, implement, or reason about any endpoint.
+You now have complete knowledge of the eventmodelers platform API. This is a reference for *how a skill talks to the platform once you're already executing one* — it is not a license to call the API directly instead of invoking the skill that matches the user's intent (see the Skill Selection table in `CLAUDE.md`). If a prompt matches a row in that table, invoke that skill first and let it decide which endpoint/tool to call; only reach for this reference directly when no skill matches the intent at all, or when you're implementing/debugging a skill itself.
+
+**Load this once per session, on demand — not as a mandatory preamble.** Every other skill already documents the exact API calls it needs inline; none of them require this full reference to be loaded before they can run. Reach for this skill only when you hit a specific endpoint, field, or element type that a skill's own instructions don't cover, and don't reload it again later in the same session once you have.
+
+**Two transports exist for board operations: MCP tools (preferred) and raw REST/curl (fallback).** The `connect` skill registers the MCP server in `.mcp.json`. Once `mcp__eventmodelers__*` tools are visible in your tool list, use them — they need no `x-token`/`x-board-id`/`x-user-id` headers (auth and org resolution happen server-side from the registered token) and return the same data as the REST endpoints below. Fall back to the numbered REST sections only when MCP tools aren't connected yet, or for the handful of endpoints (prompts lifecycle, snapshots, user management, board/extension CRUD) the MCP server intentionally doesn't expose — it only covers board-content operations (nodes, timelines, slices, comments, screens). This preference is about *which transport a skill's own instructions should use*, never about whether to invoke the skill in the first place.
+
+---
+
+## MCP Tool Catalog (Preferred)
+
+Server name: `eventmodelers`. Every tool takes `boardId` explicitly; none need `orgId` (resolved from the token) or `x-user-id` (the server attributes writes to the authenticated principal). REST section numbers below give the underlying implementation for tools that wrap a single endpoint 1:1.
+
+| Tool | Args | Purpose | REST equivalent |
+|---|---|---|---|
+| `list_boards` | — | List boards for the org | §1 `GET /api/boards` (org-scoped) |
+| `get_nodes` | `boardId`, `type?`, `name?` | List nodes, optionally by type and/or a partial case-insensitive title match | §3 `GET .../nodes` |
+| `get_node` | `boardId`, `nodeId` | Get one node | §3 `GET .../nodes/:nodeId` |
+| `get_node_comments` | `boardId`, `nodeId` | List comments on a node | §1 `GET .../nodes/:nodeId/comments` |
+| `get_board_events` | `boardId` | All board events, in sequence | §1 `GET .../events` |
+| `search_board_events` | `boardId`, `name` | Search events by node name | §1 `GET .../events/search` |
+| `submit_node_events` | `boardId`, `events[]` | Create/update nodes (raw `NodeChangeEvent`/edge events) | §3 `POST .../nodes/events` |
+| `delete_node` | `boardId`, `nodeId` | Delete a node | (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` |
+| `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` |
+| `remove_lane` | `boardId`, `timelineId`, `rowId` | Remove a lane | — (extends §2; no direct REST route) |
+| `move_node_in_timeline` | `boardId`, `timelineId`, `movedNodeId`, `toCellId` | Move a placed node to another cell | — (MCP-only convenience) |
+| `move_timeline_structure` | `boardId`, `timelineId`, `kind` (`'column'\|'lane'`), `id`, `toIndex` | Reorder a column or lane (row) — `kind` picks which `id` refers to | — (MCP-only convenience) |
+| `move_timeline_position` | `boardId`, `timelineId`, `x`, `y` | Move a chapter node on canvas | — (MCP-only convenience) |
+| `drop_node_to_cell` | `boardId`, `timelineId`, `cellId`, `nodeId`, `nodeType` | Place an existing node into a cell | §2 `POST .../cells/:cellId/drop` |
+| `clear_cell` | `boardId`, `timelineId`, `cellId` | Remove+delete the node in a cell | — (MCP-only convenience) |
+| `create_slice` | `boardId`, `timelineId`, `type`, `index?` | Create a full slice (column + nodes + SLICE_BORDER) | §5 `POST .../slices` |
+| `create_slice_definition` | `boardId`, `timelineId`, `columnId`, `title`, `data?`, `meta?` | Create a SLICE_BORDER over an existing column | §5 `POST .../slice-definitions` |
+| `place_element` | `boardId`, `timelineId`, `elementType`, `title`, `columnIndex?` | Find/create an empty cell in the right lane and place a COMMAND/READMODEL/EVENT | — (MCP-only convenience; composes §2+§3) |
+| `list_slices` | `boardId` | List slices (id, title, status) | §8 `GET .../slicedata/slices` |
+| `update_slice_status` | `boardId`, `sliceId`, `newStatus` | Change a SLICE_BORDER's `sliceStatus` | — (via `node:changed` event, §3) |
+| `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` |
+| `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) |
+| `update_comment` | `boardId`, `nodeId`, `commentId`, `action` (`'resolve'\|'delete'`) | Resolve or delete a comment | — (via comment events) |
+| `create_screen` | `boardId`, `contentType` (`'image'\|'sketch'\|'html'`), `nodeId?`, `chapterId`, `cellId?`/`cellName?`, plus content fields (`imageBase64`/`mimeType`, `elements[]`, or `pages[]`/`backgroundColor`), `description?` | Create + place a new screen node (SCREEN or HTML_SCREEN) atomically, in one call | §4 `POST .../images/:id/sketch` + `image-nodes` |
+| `render_screen` | `boardId`, `nodeId`, `elements[]?` (SCREEN) or `pages[]?`+`backgroundColor?` (HTML_SCREEN), `description?` | Update an existing screen's content — exactly one of `elements`/`pages` | §4 `POST .../images/:id/sketch` + `image-nodes` |
+| `add_field_examples` | `boardId`, `nodeId?`, `name?`, `cellName?`, `timelineId?` | Fill empty field examples using linked-node context | — (MCP-only convenience) |
+| `get_attribute_chain` | `boardId`, `timelineId`, `targetCellName`, `sourceCellName` | Resolve every node between two cells, ordered target→source | — (MCP-only convenience) |
+| `verify_screen` | `boardId`, `nodeId` | Check a screen node exists and has rendered content — works for both SCREEN and HTML_SCREEN, dispatching on the node's actual type | — (MCP-only convenience) |
+| `get_image_snapshot_description` | `boardId`, `nodeId` | Load the `{elements:[...]}` sketch description from storage | — (reads what §4 sketch endpoints write) |
+| `validate_slice_data` | `sliceData` | Offline validation of a `SliceDataOutput` payload — no board access | — (MCP-only, pure function) |
+| `commit_board_to_git` | `boardId` | Force a git-extension commit/push, bypassing the autoCommit gate | — (MCP-only; git extension) |
+| `update_prompt_status` | `promptId`, `newStatus`, `comment?` | Update a prompt's lifecycle status (`ADDED`/`CLAIMED`/`IN_PROGRESS`/`DONE`), optionally with a progress comment. Not board-scoped — no `boardId` arg; the prompt's board is resolved server-side. | §14 `POST .../prompts/:id/status` |
+
+**Not exposed via MCP at all** — always use REST/curl for these: §7 Config Import, §10 Snapshots, §11–12 User Management, §13 Utility (`/api/user`, swagger), and the rest of §14 Prompts (submission, claiming, deletion, realtime-token) — only the status-update endpoint has an MCP tool (`update_prompt_status`, used by the `update-prompt-status` skill); everything else in Prompts is an intentionally separate lifecycle the board-content MCP server doesn't otherwise own.
+
+**Capabilities with no direct MCP filter** — e.g. REST's `GET .../nodes?cellId=<id>` (§3) has no `cellId` param on `get_nodes`. Get the same answer by calling `get_node` on the CHAPTER and reading `meta.timelineData.cells` (sparse array; a cell absent from it is empty) instead of asking the server to filter by cell.
 
 ---
 
@@ -54,6 +112,29 @@ SLICE_BORDER   // Slice boundary marker
 
 ---
 
+## Field Types
+
+Every field on a `COMMAND`, `EVENT`, `READMODEL`, `SCREEN`, or `TABLE` element (`meta.fields[]`) has a `type` from this exact set — the canonical source is the [event-modeling-spec schema](https://github.com/dilgerma/event-modeling-spec/blob/main/eventmodeling.schema.json) (`$defs.Field.properties.type`):
+
+```typescript
+String     // text
+Boolean    // true / false
+Int        // 32-bit integer
+Long       // 64-bit integer
+Double     // floating-point number
+Decimal    // precise fixed-point number — prefer this over Double for money/currency
+Date       // calendar date only, no time component (e.g. "2026-06-01")
+DateTime   // date + time, ISO 8601 (e.g. "2026-06-01T09:00:00Z")
+UUID       // universally unique identifier
+Custom     // structured/nested value — use with `subfields` or `schema`
+```
+
+Other `Field` properties: `name`, `example`, `subfields[]` (nested `Field`s), `mapping`, `optional`, `technicalAttribute`, `generated`, `idAttribute`, `pii`, `schema`, `cardinality` (`"List"` | `"Single"`).
+
+Use exactly these type names (case-sensitive) — not lowercase (`string`), synonyms (`Number`, `Text`, `Integer`), or types outside this set.
+
+---
+
 ## Standard HTTP Status Codes
 
 | Code | Meaning |
@@ -354,10 +435,12 @@ Create a complete slice (1 column + 3 nodes automatically placed).
 ```
 
 **Slice node mapping**:
-- `state-change` → SCREEN (actor) + COMMAND (interaction) + EVENT (swimlane)
-- `state-view` → SCREEN (actor) + READMODEL (interaction) + EVENT (swimlane)
+- `state-change` → HTML_SCREEN (actor) + COMMAND (interaction) + EVENT (swimlane)
+- `state-view` → HTML_SCREEN (actor) + READMODEL (interaction) + EVENT (swimlane)
 - `automation` → AUTOMATION (actor) + COMMAND (interaction) + EVENT (swimlane)
 
+The actor HTML_SCREEN is created as a **stub** — a single visibly-placeholder page ("Untitled screen — design pending") unless `nodes.actor.pages` is passed explicitly. Whoever calls this (the `add-next-slice` skill — the one that creates a brand-new slice from scratch, as opposed to `eventmodeling-slicing-event-models`, which only makes existing elements explicit) is responsible for immediately replacing that stub via the `html-screen` skill — including gathering the board's existing screens first so the new one matches their established style, since `html-screen` itself has no visibility into other screens.
+
 **Response**: `200` — slice data
 
 ### POST `/api/org/:orgId/boards/:boardId/timelines/:timelineId/slice-definitions`
@@ -635,6 +718,8 @@ Claim the next pending (`ADDED`) prompt for a board — atomically flips it to `
 ### POST `/api/org/:orgId/prompts/:id/status`
 Set a prompt's status, optionally attaching a progress comment. Auth: `x-token` only (bot token — no user JWT needed, this is meant to be called directly by the agent working the prompt).
 
+**Prefer MCP**: `mcp__eventmodelers__update_prompt_status { "promptId": "<id>", "newStatus": "IN_PROGRESS", "comment": "..." }` — no `orgId`/`x-token` needed, same validation and response shape. Fall back to the curl below only when MCP tools aren't connected.
+
 **Request body**:
 ```typescript
 {

package/shared/skills/load-slice/SKILL.md

@@ -24,6 +24,22 @@ If neither is provided, load and persist all slices without filtering.
 
 ## Step 2 — Fetch all slices from the slicedata API
 
+Prefer the MCP tool when `mcp__eventmodelers__*` tools are visible in this session:
+
+```
+mcp__eventmodelers__list_slices { "boardId": "<BOARD_ID>" }
+```
+
+This returns `{ "slices": [ { "id": "...", "title": "...", "status": "..." } ] }` — lighter than the full slicedata payload (no `contextName`/`contextId`/`comments`). If Step 3/4 below need those richer fields for a specific slice, follow up with:
+
+```
+mcp__eventmodelers__get_slice_data { "boardId": "<BOARD_ID>", "contextName": "<name>" }
+```
+
+(`get_slice_data` requires a `contextName` or `contextId` — call `list_slices` first, then resolve context per slice via `mcp__eventmodelers__get_node` on each `SLICE_BORDER` id if the context isn't already known.)
+
+**Fallback (no MCP):**
+
 ```bash
 curl -s \
   -H "x-token: <TOKEN>" \

package/shared/skills/update-slice-status/SKILL.md

@@ -37,7 +37,13 @@ If `newStatus` is not one of these exact values, stop and tell the user the vali
 
 ## Step 2 — List all slices
 
-Fetch all slices on the board:
+Prefer the MCP tool when `mcp__eventmodelers__*` tools are visible in this session:
+
+```
+mcp__eventmodelers__list_slices { "boardId": "<BOARD_ID>" }
+```
+
+**Fallback (no MCP):**
 
 ```bash
 curl -s \
@@ -47,9 +53,7 @@ curl -s \
   "<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/slicedata/slices"
 ```
 
-Response: `{ "slices": [{ "id": "<nodeId>", "title": "<title>", "status": "<status>" }] }`
-
-The `id` here is the `SLICE_BORDER` node ID — use it directly in Step 3.
+Either way, the response is `{ "slices": [{ "id": "<nodeId>", "title": "<title>", "status": "<status>" }] }`. The `id` here is the `SLICE_BORDER` node ID — use it directly in Step 3.
 
 Find the slice whose `title` matches `sliceName` (case-insensitive). If no match is found, stop and list the available slice titles so the user can pick one.
 
@@ -61,7 +65,13 @@ Save the matched slice as:
 
 ## Step 3 — Update the slice status
 
-Send a `node:changed` event to update the `sliceStatus` field in the SLICE_BORDER node's meta:
+Prefer the MCP tool — it does the same `node:changed`/`sliceStatus` update in one call, no event envelope to hand-assemble:
+
+```
+mcp__eventmodelers__update_slice_status { "boardId": "<BOARD_ID>", "sliceId": "<SLICE_NODE_ID>", "newStatus": "<newStatus>" }
+```
+
+**Fallback (no MCP)** — send a `node:changed` event to update the `sliceStatus` field in the SLICE_BORDER node's meta directly:
 
 ```bash
 curl -s -X POST "<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/events" \

package/stacks/modeling-kit/templates/.claude/skills/add-next-slice/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: add-next-slice
+description: Decide on and create a genuinely new slice from scratch when there's no existing COMMAND/READMODEL/AUTOMATION left to slice — the model doesn't yet suggest an obvious next capability, or every existing element already has a Done slice. Use when eventmodeling-slicing-event-models finds nothing left to make explicit. Do not use for: making an already-modelled element's slice explicit (use eventmodeling-slicing-event-models — that skill only slices existing elements, it never invents new ones).
+---
+
+# Add Next Slice
+
+> **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. Every API call this skill needs (`create_slice`, `get_nodes`/`get_node`) is already given in full below — do not additionally load `learn-eventmodelers-api`; only reach for it if you hit an error this file doesn't cover.
+
+**Purpose**: Given a timeline where every existing COMMAND/READMODEL/AUTOMATION already has a slice (or there's no model content at all yet), decide on a plausible next capability and create it as a brand-new slice — screen, command/read model, and event all at once.
+
+This is the counterpart to `eventmodeling-slicing-event-models`, which only ever makes *existing* elements explicit as slices and correctly refuses to invent new ones. Something has to own deciding what comes next — that's this skill; `eventmodeling-slicing-event-models` points here whenever it finds nothing left to slice.
+
+---
+
+## Core Concept: A Slice Is One Command, One Read Model, or One Automation — Never Combined
+
+Same rules as `eventmodeling-slicing-event-models` — the slice you create here must obey them too, not just slices made from pre-existing elements.
+
+A **Feature Slice** is the thinnest possible vertical cut through the model — exactly one decision or one query:
+
+```
+state-change slice = SCREEN/Processor → COMMAND → EVENT(s)
+state-view slice   = EVENT(s) → READMODEL → SCREEN/Processor
+automation slice   = EVENT(s) → AUTOMATION → COMMAND → EVENT(s)
+```
+
+A slice never mixes a COMMAND and a READMODEL — the platform models these as two distinct slice types (`state-change` and `state-view`). If the capability you decide on in Step 1 needs both a command and a read model (e.g. "place an order" needs the `PlaceOrder` command *and* an `OrderDetailView` read model), that's **two slices** — create them one at a time, each its own `create_slice` call.
+
+**Key characteristics**:
+- Exactly one COMMAND (state-change), exactly one READMODEL (state-view), or one AUTOMATION's command — never combined
+- Named after that command, read model, or automation
+- Independently deployable
+- Communicates with other slices via events only
+
+---
+
+## This is never the ambiguous/no-default case the per-turn "Questioning rule" allows you to stop on
+
+"I don't know what the next capability is" is not the same as "any guess risks doing the wrong thing." A plausible next slice — the next lifecycle stage, an unaddressed affordance on an existing screen, a natural CRUD/notification gap — always exists for a working domain, and a wrong guess here costs nothing: it's just another slice on the board, easy to rename or discard later.
+
+**Posting a comment and closing the prompt with no board mutation is not an acceptable outcome of this skill.** That only defers the same empty decision to the next identical prompt, forever. If you already posted a `QUESTION`/`TASK` comment about this exact ambiguity on a previous turn, that does not make it acceptable to do so again instead of creating something — the comment already served its purpose (flagging the assumption for a human to correct later); this turn should still create the slice.
+
+---
+
+## Step 1: Decide on the next capability
+
+**If the prompt gives no specific instruction about what the next slice should be** (e.g. a bare "add the next slice"), don't ask for one — look at the previous slices already on the timeline and derive the next one yourself:
+
+- Read the existing COMMAND/READMODEL/AUTOMATION titles and their fields in narrative order (left to right on the timeline) — they tell a story (e.g. Reserve Table → Cancel Reservation → Check-In → ...).
+- Identify what the story is missing next: the natural following lifecycle stage, an unaddressed affordance implied by an existing screen (a button/link with nothing behind it yet), or a CRUD/notification gap the existing entity clearly has (created but never updated/cancelled/queried in detail, an action with no confirmation view, etc.).
+- Prefer the option that most directly continues the existing narrative over one that starts an unrelated new thread — the goal is the slice that makes the most sense as *next*, not just *any* plausible slice.
+
+If a specific instruction *is* given (the prompt names a capability, or references a comment/discussion that does), use that instead of inferring one.
+
+If, after looking at the existing slices, it's genuinely unclear which of several equally-reasonable next steps to pick, post a `QUESTION` comment (via `handle-comment`) noting the assumption you're about to make — then make it and create the slice in the same turn, every time. Never stop at just the comment.
+
+## Step 2: Create the slice
+
+```
+mcp__eventmodelers__create_slice { "boardId": "<BOARD_ID>", "timelineId": "<TL>", "type": "state-change", "nodes": {"interaction": {"title": "CancelReservation"}} }
+```
+
+Pick `type` based on what you decided in Step 1 — `state-change` for a new command, `state-view` for a new read model, `automation` for a new automation. Always pass `nodes.interaction.title` as the command/read model/automation name you decided on in Step 1 — per the Core Concept above, the slice is *named after that element*, and the backend only derives the slice title from this field; omitting it produces a useless generic "State Change"/"State View"/"Automation" label instead. This also creates the slice's `SLICE_BORDER` automatically — no separate `create_slice_definition` call needed.
+
+**Fallback (no MCP):**
+```bash
+curl -X POST $BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$TL/slices \
+  -H "x-token: $TOKEN" -H "Content-Type: application/json" \
+  -d '{"type":"state-change","nodes":{"interaction":{"title":"CancelReservation"}}}'
+```
+
+## Step 3: Replace the placeholder screen — matching the board's existing style
+
+For `state-change`/`state-view`, the actor node this creates is an `HTML_SCREEN` — but only as a **stub**: a single visibly-placeholder page ("Untitled screen — design pending"), never real content. Never leave it at that:
+
+1. Look up the board's other screens on this timeline (`mcp__eventmodelers__get_nodes { "boardId": "<BOARD_ID>", "type": "HTML_SCREEN" }`, or the equivalent already-loaded slice data) and note their established visual style — layout conventions, color/tone, recurring components (nav bar, card style, button treatment).
+2. Invoke the `html-screen` skill on the new stub node, passing a `description` that covers **both** what this screen should contain (derived from the new command/read model's fields) **and** the style to match (derived from what you just observed in step 1). `html-screen` has no visibility into other screens on the board — gathering that context and folding it into the description is this skill's job, not something to expect `html-screen` to do on its own.
+3. Default to `html-screen` here, never `storyboard-screen` (wireframe sketch) — a sketch is only for an explicit user request for one.
+
+## Step 4: Report back
+
+Tell the user (or, in an autonomous modeling session, note it in the turn's progress line):
+- The capability you decided on and why
+- The slice type and node IDs created
+- Whether the placeholder screen was replaced with a real design, and what style it matched

package/stacks/modeling-kit/templates/.claude/skills/analyze-existing-model/SKILL.md

@@ -5,7 +5,9 @@ description: Analyze the existing event model on a board — summarizes contexts
 
 # Analyze Existing Model
 
-> **Before doing anything else**, invoke the `connect` skill to resolve `TOKEN`, `BOARD_ID`, `ORG_ID`, and `BASE_URL`. Do not proceed until the connect skill has completed.
+> **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 the connect skill has completed.
+
+Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect` skill) — the curl blocks below are the fallback for sessions without MCP connected.
 
 Read the full event model from a board and produce a structured analysis: what contexts exist, how many slices are in each state, which slices have GWT specs, and where the visible gaps are. This skill is read-only — it never posts comments or modifies the board.
 
@@ -26,6 +28,12 @@ If `boardId` is explicitly passed it overrides `BOARD_ID` from `connect`.
 
 ## Step 2 — List all slices
 
+**Prefer MCP:**
+```
+mcp__eventmodelers__list_slices { "boardId": "$BOARD_ID" }
+```
+
+**Fallback (no MCP):**
 ```bash
 curl -s \
   -H "x-token: $TOKEN" \
@@ -48,6 +56,12 @@ Save the full slice list. Count total slices and group by status:
 
 Fetch all `MODEL_CONTEXT` nodes to identify bounded contexts on the board:
 
+**Prefer MCP:**
+```
+mcp__eventmodelers__get_nodes { "boardId": "$BOARD_ID", "type": "MODEL_CONTEXT" }
+```
+
+**Fallback (no MCP):**
 ```bash
 curl -s \
   -H "x-token: $TOKEN" \
@@ -66,6 +80,12 @@ curl -s \
 
 For each resolved context, fetch the full element graph:
 
+**Prefer MCP:**
+```
+mcp__eventmodelers__get_slice_data { "boardId": "$BOARD_ID", "contextName": "<CONTEXT_NAME>" }
+```
+
+**Fallback (no MCP):**
 ```bash
 curl -s \
   -H "x-token: $TOKEN" \
@@ -189,6 +209,14 @@ If a context was specified but not found, tell the user clearly and list the con
 
 ## Example — full board analysis
 
+**Prefer MCP:**
+```
+mcp__eventmodelers__list_slices { "boardId": "$BOARD_ID" }
+mcp__eventmodelers__get_nodes { "boardId": "$BOARD_ID", "type": "MODEL_CONTEXT" }
+mcp__eventmodelers__get_slice_data { "boardId": "$BOARD_ID", "contextName": "Ordering" }
+```
+
+**Fallback (no MCP):**
 ```bash
 # 1. List slices
 curl -s \