@eventmodelers/cli 1.0.86 → 1.0.88

package/README.md

@@ -125,8 +125,8 @@ npx @eventmodelers/cli init --stack <name>          # scaffold a stack + install
 npx @eventmodelers/cli init --stack <name> --demo   # same, plus a ready-made demo model in the kit's .slices/ to build against
 npx @eventmodelers/cli re-init                      # refresh an already-installed kit's scripts/skills only — never touches the root scaffold
 npx @eventmodelers/cli run                          # start the agent loop (ralph-claude.js) from the installed kit dir
-npx @eventmodelers/cli run --local-ai [target]      # same, via a local/self-hosted model (ralph-local-ai.js)
-npx @eventmodelers/cli run --exec "<command>"        # same, via an external agent harness (ralph-exec.js)
+npx @eventmodelers/cli run --local-ai [target]      # board work only via a local/self-hosted model (ralph-local-ai.js) — does NOT build slices; build locally with --exec
+npx @eventmodelers/cli run --exec "<command>"        # same, via an external agent harness (ralph-exec.js) — agent tracing needs its JSON flag, e.g. "codex exec --json --full-auto"
 npx @eventmodelers/cli run --bash                   # bash-only loop, no realtime (ralph.sh)
 npx @eventmodelers/cli run --local                  # skip platform config/credential lookup entirely — local-only, no board sync
 npx @eventmodelers/cli run --modeling               # modeling-kit: warm Claude process driven by the board's prompt queue

package/cli.js

@@ -3193,8 +3193,8 @@ credentialFlags(program
 credentialFlags(program
   .command('run')
   .description('Start the agent loop from the installed kit dir — build-kit stacks: ralph-claude.js (default); modeling-kit: --modeling, or --standalone, which needs no install at all')
-  .option('--local-ai [target]', `Drive the loop with a local (or self-hosted) model instead of the default Claude runner: a build kit runs it via ralph-local-ai.js, and --modeling/--standalone via lib/modeling-local-ai.js (board tools over MCP, but no skills and no subagent fan-out — those are Claude Code features). Optional target preset picks the URL and wire dialect: ${LOCAL_AI_TARGETS.join(', ')} — bare --local-ai means ollama. Anything OpenAI-compatible (vLLM, LM Studio, llama.cpp, TGI) works by pointing LOCAL_AI_URL at it; see LOCAL_AI_* in the docs. Claude remains the default when this flag is absent.`)
-  .option('--exec [command]', 'Hand each prompt to an external agent command instead of the default Claude runner, via ralph-exec.js (build-kit stacks only) — for agentic harnesses that bring their own tool loop, e.g. "codex exec --full-auto" or "opencode run". The prompt is appended as a quoted argument and also written to the file named by RALPH_PROMPT_FILE. Bare --exec uses localAi.exec from .eventmodelers/config.json. Claude remains the default when this flag is absent.')
+  .option('--local-ai [target]', `Drive the loop with a local (or self-hosted) model instead of the default Claude runner: a build kit runs it via ralph-local-ai.js, and --modeling/--standalone via lib/modeling-local-ai.js (board tools over MCP, but no skills and no subagent fan-out — those are Claude Code features). Optional target preset picks the URL and wire dialect: ${LOCAL_AI_TARGETS.join(', ')} — bare --local-ai means ollama. Anything OpenAI-compatible (vLLM, LM Studio, llama.cpp, TGI) works by pointing LOCAL_AI_URL at it; see LOCAL_AI_* in the docs. Board work only: --local-ai never builds a Planned slice (no file, shell or git tools). To build code with a local model, use --exec with a coding harness pointed at it, e.g. "codex exec --oss --full-auto". Claude remains the default when this flag is absent.`)
+  .option('--exec [command]', 'Hand each prompt to an external agent command instead of the default Claude runner, via ralph-exec.js (build-kit stacks only) — for agentic harnesses that bring their own tool loop, e.g. "codex exec --full-auto" or "opencode run". The prompt is appended as a quoted argument and also written to the file named by RALPH_PROMPT_FILE. Bare --exec uses localAi.exec from .eventmodelers/config.json. Claude remains the default when this flag is absent. With agent tracing on, include the harness\'s JSON output flag (codex exec --json, opencode run --format json, gemini --output-format stream-json) — without it no slice cost is recorded.')
   .option('--bash', 'Use the bash-only ralph.sh loop (build-kit stacks only, no realtime)')
   .option('--modeling', 'Keep one Claude process warm across prompts instead of spawning a fresh one per task, for low-latency voice/live use. Runs from a modeling-kit install in this directory, or from the global install (~/.eventmodelers/kit) when there is none. Built into the CLI, not a per-project file.')
   .option('--non-interactive', 'Never ask anything: take the board and credentials that resolve from flags, EVENTMODELERS_* env vars and the config files, and fail with the reason if they are incomplete instead of interviewing for them. A TTY was previously the only signal — right for CI or a supervisor, wrong for a loop started from a terminal, where stdin is a TTY nobody is watching and the run stops on a question. Only affects the modeling loop (--modeling/--standalone/--global).')
@@ -3907,7 +3907,7 @@ program
 program
   .command('config')
   .description('Print the fully resolved config (merged across the directory hierarchy + EVENTMODELERS_* env vars), with the token masked')
-  .option('--agent-tracing <on|off>', "Turn agent tracing on or off for this project (saved as `agentTracing` in the project's .eventmodelers/config.json). Off: the build agent sends no slice cost data to the platform at all.")
+  .option('--agent-tracing <on|off>', "Turn agent tracing on or off for this project (saved as `agentTracing` in the project's .eventmodelers/config.json). Off: the build agent sends no slice cost data to the platform at all. A non-Claude agent via run --exec is only traced when its command includes the harness's JSON output flag, e.g. \"codex exec --json --full-auto\".")
   .action((opts, command) => {
     const cwd = process.cwd();
     const kitDir = findInstalledKitDir(cwd);

package/package.json

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

package/shared/build-kit/README.md

@@ -51,7 +51,7 @@ node .build-kit/ralph-claude.js /path/to/project
 **Phase 2** — triggered when any file in `.slices/` contains `"status": "Planned"`:
 - The loop runs Claude with `backend-prompt.md`
 - Claude implements the slice in the project
-- Phase 2 is Claude-only; local-AI mode skips it (local-ai-agent handles its own queue)
+- Phase 2 (building slices) never runs with `--local-ai` — see *`--local-ai` does not build code*. Build with `--exec` instead
 
 Both phases run in a continuous loop with a 3-second idle sleep. The realtime agent runs concurrently in the same process.
 
@@ -72,6 +72,34 @@ node .build-kit/realtime-agent.js
 `ralph-local-ai.js` drives any local or self-hosted model that can do tool calling.
 Claude (`ralph-claude.js`) stays the default runner — this is opt-in.
 
+### `--local-ai` does not build code
+
+**`--local-ai` works on the board only. It never builds a slice.** Planned slices stay
+Planned. That is by design, not a bug:
+
+- **Planned slices are never handed to it.** `ralph-local-ai.js` gives `startRalph` no
+  `onPlannedSlice`, so the loop only feeds it `tasks.json` prompts.
+- **It has no coding tools.** `lib/local-ai-agent.js` exposes only the board MCP tools:
+  no file read/write, no shell, no git, no test run.
+- **Its system prompt forbids file and shell access.** Such a request is answered with
+  `Blocked: …`.
+- **A prompt stops after 12 tool-call rounds.** That is enough for board edits, but far
+  short of a slice build.
+
+Here the kit is the agent loop and the model only picks tools. Building would mean
+rewriting a full coding agent inside the kit, so it is left out on purpose.
+
+**To build with a local model, use `--exec`** with a coding harness pointed at that model
+(see *External agent commands* below):
+
+```bash
+npx @eventmodelers/cli run --exec "codex exec --oss --json --full-auto"   # Codex on local Ollama
+npx @eventmodelers/cli run --exec "opencode run --auto --format json"     # OpenCode, with an Ollama/vLLM/LM Studio provider in its config
+```
+
+Or keep Claude Code as the builder and point `anthropicBaseUrl` at a local endpoint that
+speaks the Anthropic API.
+
 ```bash
 LOCAL_AI_TARGET=ollama          # preset: ollama | vllm | lmstudio | llamacpp
 LOCAL_AI_URL=http://host:8000/v1  # any OpenAI-compatible server (overrides the preset URL)
@@ -109,6 +137,20 @@ child runs with the project dir as its cwd and inherits stdio — a harness owns
 output format, so there is no condensed per-step logging here the way `ralph-claude.js`
 has it.
 
+**Agent tracing needs the harness's JSON output flag.** With agent tracing on
+(`eventmodelers config --agent-tracing on`), slice builds are costed just like with Claude —
+but only if the harness runs in its JSON output mode. Its normal output has no token counts,
+so without the flag a turn is not traced (the runner logs a hint). Add the flag yourself:
+
+```bash
+npx @eventmodelers/cli run --exec "codex exec --json --full-auto"
+npx @eventmodelers/cli run --exec "opencode run --auto --format json"
+npx @eventmodelers/cli run --exec "gemini --yolo --output-format stream-json -p"
+```
+
+The terminal then shows the raw JSON events. Only OpenCode reports a dollar cost; Codex and
+Gemini turns record tokens and duration with no cost. See `agent-tracking.md`.
+
 Persist a default alongside the local-AI settings:
 
 ```json

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

@@ -1,5 +1,5 @@
 // What a slice costs: one trace per build turn against one slice, posted to the platform's
-// /api/org/:orgId/boards/:boardId/agent-traces. Only the runner can see what a turn cost, so it reports it.
+// /api/org/:orgId/agent-traces. Only the runner can see what a turn cost, so it reports it.
 //
 // Best effort: each trace is appended to a local JSONL file, then POSTed once. No retries, no
 // buffering. A failed upload is logged and forgotten; the file is the record.
@@ -45,16 +45,78 @@ export function usageFromLocalAi(raw, durationMs) {
   };
 }
 
+/** One event from an external harness's JSON output (ralph-exec.js), or null if it carries no usage.
+ *  Matched on shape, not on the command name, so a wrapper script around a harness still counts:
+ *   - Codex `codex exec --json`: `turn.completed` with `usage` (input_tokens includes the cached ones)
+ *   - OpenCode `opencode run --format json`: `step_finish` per model step, with tokens and cost
+ *   - Gemini CLI `--output-format stream-json`: the final `result` with `stats`;
+ *     `--output-format json`: one object whose `stats.models` holds tokens per model
+ *  Only OpenCode reports a cost — the others leave costUsd null rather than guessing a price. */
+export function usageFromHarnessEvent(msg) {
+  if (msg?.type === 'turn.completed' && msg.usage) {
+    const u = msg.usage;
+    const cached = n(u.cached_input_tokens);
+    return { inputTokens: Math.max(0, n(u.input_tokens) - cached), outputTokens: n(u.output_tokens), cacheReadTokens: cached };
+  }
+  if (msg?.type === 'step_finish' && msg.part?.tokens) {
+    const t = msg.part.tokens;
+    return {
+      inputTokens: n(t.input),
+      outputTokens: n(t.output) + n(t.reasoning),
+      cacheReadTokens: n(t.cache?.read),
+      cacheWriteTokens: n(t.cache?.write),
+      costUsd: Number.isFinite(msg.part.cost) ? msg.part.cost : null,
+    };
+  }
+  if (msg?.type === 'result' && msg.stats && !('total_cost_usd' in msg)) {
+    const s = msg.stats;
+    return {
+      inputTokens: n(s.input_tokens),
+      outputTokens: n(s.output_tokens),
+      durationMs: Number.isFinite(s.duration_ms) ? s.duration_ms : null,
+    };
+  }
+  if (msg?.stats?.models && typeof msg.stats.models === 'object') {
+    const models = Object.entries(msg.stats.models);
+    const tok = (key) => models.reduce((sum, [, m]) => sum + n(m?.tokens?.[key]), 0);
+    const cached = tok('cached');
+    const [dominant] = models.sort((a, b) => n(b[1]?.tokens?.candidates) - n(a[1]?.tokens?.candidates))[0] ?? [];
+    return {
+      inputTokens: Math.max(0, tok('prompt') - cached),
+      outputTokens: tok('candidates') + tok('thoughts'),
+      cacheReadTokens: cached,
+      model: dominant ?? null,
+    };
+  }
+  return null;
+}
+
+/** Sums the usage of every event in one turn. A field no event reported stays null (cost, model)
+ *  or 0 (tokens), so a harness without a cost does not show up as a free turn. */
+export function sumUsage(parts) {
+  if (!parts.length) return null;
+  const add = (key) => parts.reduce((sum, p) => sum + n(p[key]), 0);
+  const costs = parts.map((p) => p.costUsd).filter(Number.isFinite);
+  return {
+    inputTokens: add('inputTokens'),
+    outputTokens: add('outputTokens'),
+    cacheReadTokens: add('cacheReadTokens'),
+    cacheWriteTokens: add('cacheWriteTokens'),
+    costUsd: costs.length ? costs.reduce((a, b) => a + b, 0) : null,
+    durationMs: parts.findLast((p) => Number.isFinite(p.durationMs))?.durationMs ?? null,
+    model: parts.findLast((p) => p.model)?.model ?? null,
+  };
+}
+
 /** Records slice build turns. The agent id is the session: the platform requires one, and a
  *  restart of the same build agent is still the same agent building the same slices. */
 export function createSliceTracer({ baseUrl, token, organizationId, agentId, traceFile, log = () => {}, enabled = true } = {}) {
   const canUpload = !!(enabled && baseUrl && token && organizationId && agentId);
 
   async function post(trace) {
-    // The platform files a trace under the board in its path — a turn without a board has nowhere to go.
-    if (!canUpload || !trace.boardId) return;
+    if (!canUpload) return;
     try {
-      const res = await fetch(`${baseUrl}/api/org/${organizationId}/boards/${trace.boardId}/agent-traces`, {
+      const res = await fetch(`${baseUrl}/api/org/${organizationId}/agent-traces`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', 'x-token': token, 'x-agent-id': agentId },
         body: JSON.stringify({ traces: [trace] }),

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

@@ -18,6 +18,7 @@
 // Or persist it as localAi.exec in .eventmodelers/config.json.
 
 import { startRalph, loadLocalConfig, resolveAgentIdentity } from './lib/ralph.js';
+import { createSliceTracer, usageFromHarnessEvent, sumUsage } from './lib/tracing.js';
 import { spawn } from 'child_process';
 import { writeFileSync, mkdtempSync } from 'fs';
 import { tmpdir } from 'os';
@@ -52,6 +53,21 @@ const childEnv = {
   ...(cfg.agentId && !localOnly ? { EVENTMODELERS_AGENT_ID: cfg.agentId } : {}),
 };
 
+// What each slice build turn cost — see lib/tracing.js. Same opt-in as ralph-claude.js, but a
+// harness only reports usage in its JSON output mode (`codex exec --json`, `opencode run --format
+// json`, `gemini --output-format stream-json`), so without that flag a turn has nothing to record.
+const tracingOn = !localOnly && cfg.agentTracing === true;
+if (!tracingOn && !localOnly) console.log('[ralph-exec] agent tracing off — no slice cost data is sent (turn on: eventmodelers config --agent-tracing on)');
+const tracer = createSliceTracer({
+  baseUrl: cfg.baseUrl,
+  token: cfg.token,
+  organizationId: cfg.organizationId,
+  agentId: cfg.agentId,
+  traceFile: join(projectDir, '.eventmodelers', 'trace', 'slices.jsonl'),
+  log: (line) => console.log(`[ralph-exec] ${line}`),
+  enabled: tracingOn,
+});
+
 const promptDir = mkdtempSync(join(tmpdir(), 'ralph-exec-'));
 
 // POSIX single-quote escaping: close, insert an escaped quote, reopen. The prompt is
@@ -62,22 +78,59 @@ function shellQuote(s) {
 
 console.log(`[ralph-exec] command: ${execCmd}`);
 
-function runExec(prompt) {
+// Parses a harness's stdout for usage while still passing it through. Most harnesses emit JSONL;
+// Gemini's `--output-format json` is one pretty-printed object, hence the whole-output fallback.
+function collectUsage(stream) {
+  const parts = [];
+  let buffer = '';
+  let all = '';
+  const take = (text) => {
+    try { const u = usageFromHarnessEvent(JSON.parse(text)); if (u) parts.push(u); } catch { /* not JSON */ }
+  };
+  stream.on('data', (chunk) => {
+    process.stdout.write(chunk);
+    const text = chunk.toString();
+    all += text;
+    buffer += text;
+    const lines = buffer.split('\n');
+    buffer = lines.pop();
+    for (const line of lines) if (line.trim()) take(line);
+  });
+  return () => {
+    if (buffer.trim()) take(buffer);
+    if (!parts.length && all.trim()) take(all);
+    return sumUsage(parts);
+  };
+}
+
+// `slice` is set for a planned-slice build (see startRalph) — the only turns that are traced.
+function runExec(prompt, slice = null) {
   return new Promise((resolvePromise, reject) => {
     const full = inlineHeader + prompt;
     const promptFile = join(promptDir, 'prompt.md');
     writeFileSync(promptFile, full);
+    const traced = tracingOn && !!slice;
+    const startedAt = Date.now();
 
     // stdio inherit: the harness owns its own output format, and there is no
     // cross-harness stream schema to parse into the condensed per-step logging
-    // that ralph-claude.js does — so it goes straight through.
+    // that ralph-claude.js does — so it goes straight through. A traced turn pipes
+    // stdout instead, only to read usage from it; the output is still echoed as is.
     const proc = spawn(`${execCmd} ${shellQuote(full)}`, {
       cwd: projectDir,
-      stdio: 'inherit',
+      stdio: ['inherit', traced ? 'pipe' : 'inherit', 'inherit'],
       shell: true,
       env: { ...childEnv, RALPH_PROMPT_FILE: promptFile },
     });
-    proc.on('close', (code) => (code === 0 ? resolvePromise() : reject(new Error(`exec command exited ${code}`))));
+    const usage = traced ? collectUsage(proc.stdout) : null;
+    proc.on('close', (code) => {
+      if (traced) {
+        const u = usage();
+        if (u) tracer.record({ ...slice, status: code === 0 ? 'ok' : 'error' }, { ...u, durationMs: u.durationMs ?? Date.now() - startedAt });
+        else console.log('[ralph-exec] trace: no usage in the command output — run the harness in its JSON output mode to record slice cost');
+      }
+      code === 0 ? resolvePromise() : reject(new Error(`exec command exited ${code}`));
+    });
     proc.on('error', reject);
   });
 }

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

@@ -27,8 +27,7 @@ Write tools take their items as an array (`nodeIds[]`, `elements[]`, `connection
 | `get_nodes` | `boardId`, `type?`, `name?`, `chapterId?`, `nodeIds?`, `projection?` (`"line"`) | List nodes, optionally by type and/or a partial case-insensitive title match. `chapterId` scopes to one timeline — prefer this over an unscoped board-wide call whenever the step is working within one chapter (the common case); `nodeIds` fetches a known, scattered subset in one call (e.g. re-verifying exactly the nodes just touched by a batch write) instead of a full `type` refetch; `projection: "line"` maps each match to `{id, type, title}` only. Every node carries `cellName`, its cell address in the chapter it is placed in (absent when unplaced) — read the cell names the cell-addressed tools need from here, never derive or invent one | §3 `GET .../nodes` |
 | `get_node` | `boardId`, `nodeId`, `projection?` (`"cells"` \| `"edges"`) | Get one node — the full response carries `cellName`, its cell address in the chapter it is placed in. `projection: "cells"` (CHAPTER nodes only) returns just `{rows, columns, cells}` instead of the full `timelineData` — use whenever only the grid/occupancy is needed, not the whole chapter; `projection: "edges"` returns just that node's inbound/outbound connections instead of `findNodeById`'s full record. Both are opt-in — omitting `projection` is the unchanged full response | §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` |
+| `get_board_events` | `boardId`, `since?`, `seq?` | A page of at most 300 board events, oldest first, as `{events, pageSize, hasMore}`. Not the whole log: while `hasMore` is true, page on by passing the last event's `seq` as `since`. `seq` returns only the event of exactly that seq | §1 `GET .../events` |
 | `submit_node_events` | `boardId`, `events[]`, `autoConnect?`, `compact?` | Create/update nodes (raw `NodeChangeEvent`/edge events). Every event property is described on the tool's own `events[]` schema — read that rather than this skill when all you need is the event shape. An event needs its own `id` (required — a fresh uuid per event, never the node id) and its `eventType`, plus the keys of its kind (`nodeId`/`meta`/`node`, or `edgeId`/`source`/`target`). The `id` keys the returned `hashes` map and makes a resubmit idempotent — the same event sent twice under one id writes a single board event. Don't send `boardId` or `timestamp` per event — the server takes the board from the call and stamps the time itself, and ignores both if sent. `autoConnect: false` places freshly-created nodes without wiring them to their own/previous-column neighbors (avoids a stray nearest-left edge); `compact: true` returns `{persisted: <count>}` instead of the per-node hash map | §3 `POST .../nodes/events` |
 | `delete_node` | `boardId`, `nodeIds[]` | Delete nodes, applied in order — one failure doesn't stop the rest; answers `{results}`. 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`, `drawings[]` (each `kind`, `x`, `y`, `width`, `height`, ...) | Freehand canvas annotation (path/rect/text/sticky) — never placed in a cell. An annotation is rarely one stroke: a loop plus its arrows and label is one call with several `drawings` entries, applied in order, not three calls | — (REST `POST .../drawing/draw` accepts a single drawing or an array) |
@@ -59,9 +58,8 @@ Write tools take their items as an array (`nodeIds[]`, `elements[]`, `connection
 | `link_element` | `boardId`, `nodeId`, plus either `targetNodeId` or `timelineId` (+ `columnIndex?`, `lane?`) | Turn a node into a linked copy of `nodeId` — it receives a full copy of that node's meta plus `meta.linkedTo`. Name an existing `targetNodeId`, or pass `timelineId` to have the copy placed and linked in this one call (inheriting the original's type and title), which is what a translation or automation chain wants | §3 `POST .../nodes/:nodeId/link` |
 | `add_comment` | `boardId`, `comments[]` (each `nodeId`, `text`, `type?` `'COMMENT'\|'TASK'\|'QUESTION'`, `author?`) | Add comments on any nodes of one board — `QUESTION` is the type for a gap/edge case raised during review, and a review posts all its questions in one call; answers `{results}` in request order | §1 `POST .../boards/:boardId/comments` (batch) |
 | `update_comment` | `boardId`, `nodeId`, `commentId`, `action` (`'resolve'\|'delete'`) | Resolve or delete a comment | — (via comment events) |
-| `create_screen` | `boardId`, `screens[]` (each `contentType` `'image'\|'sketch'\|'html'`, `chapterId`, `cellId?`/`cellName?`, `nodeId?`, content fields `imageBase64`/`mimeType`, `elements[]`, or `pages[]`/`backgroundColor`, `title?`, `description?`, `fields?`), `autoConnect?` | Create + place new screen nodes (SCREEN or HTML_SCREEN) with their content, in one call; entries applied in order, one failure doesn't stop the rest; answers `{results}`. `title` names the node (`meta.title`) in the same call — no follow-up `node:changed` just to label the screen. `autoConnect: false` places without wiring to timeline neighbors | §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) |
+| `create_screen` | `boardId`, `screens[]` (each `contentType` `'image'\|'sketch'\|'html'`, `chapterId`, `cellId?`/`cellName?`, `nodeId?`, content fields `imageBase64`/`mimeType`, `elements[]`, or `pages[]`/`backgroundColor`, `title?`, `description?`, `fields?`), `autoConnect?` | Create + place new screen nodes (SCREEN or HTML_SCREEN) with their content, in one call; each HTML page at most 6000 characters (`HTML_SCREEN_PAGE_TOO_LONG` otherwise); entries applied in order, one failure doesn't stop the rest; answers `{results}`. `title` names the node (`meta.title`) in the same call — no follow-up `node:changed` just to label the screen. `autoConnect: false` places without wiring to timeline neighbors | §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`; each HTML page at most 6000 characters (`HTML_SCREEN_PAGE_TOO_LONG` otherwise) | §4 `POST .../images/:id/sketch` + `image-nodes` |
 | `get_attribute_chain` | `boardId`, `timelineId`, `targetCellName`, `sourceCellName` | Resolve every node between two cells, ordered target→source. Both cell names must come from a node's reported `cellName` (`get_board_outline`, `get_nodes`, `get_node`) — a guessed address that happens to exist silently resolves the wrong chain | — (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) |
@@ -188,18 +186,27 @@ Delete a board.
 
 ---
 
-### GET `/api/org/:orgId/boards/:boardId/events/search`
-Search events by node name.
-
-**Query params**: `name` (string)  
-**Response**: `200` — matching event array
-
----
-
 ### GET `/api/org/:orgId/boards/:boardId/events`
-Get all board events in sequence.
+Get a page of board events in sequence order — **at most 300 per call**, oldest first. One call is not the whole log: to read it all, pass the last event's `seq` as `since` and repeat while the `X-Has-More` response header is `true`. `X-Page-Size` carries the page size that applied.
 
-**Response**: `200` — event array
+**Query params**:
+- `since` (integer, optional) — only events with a `seq` greater than this
+- `skipSilent` (boolean, default `true`) — `false` also includes events marked silent
+- `seq` (integer, optional) — only the event of exactly this seq (silent or not); `since` and `skipSilent` are ignored
+
+**Response**: `200` — event array (at most 300; at most one with `seq`, empty if there is none — `X-Has-More` is then `false`)
+**Errors**: `400` `EVENT_SEQ_INVALID` — `seq` is not a non-negative integer
+
+```bash
+since=0
+while :; do
+  more=$(curl -s -D - -o page.json "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/events?since=$since" -H "x-token: $TOKEN" \
+    | tr -d '\r' | awk -F': ' 'tolower($1)=="x-has-more"{print $2}')
+  # ...use page.json...
+  [ "$more" = "true" ] || break
+  since=$(jq '.[-1].seq' page.json)
+done
+```
 
 ---
 

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

@@ -317,6 +317,8 @@ mcp__eventmodelers__create_screen {
 
 **Never pass an empty `pages` array** — an empty array produces a blank placeholder, same as in `html-screen`/`eventmodeling-storyboarding-events`.
 
+**Keep every reconstructed page at most 6000 characters per page (the server rejects a longer page with `400 HTML_SCREEN_PAGE_TOO_LONG` — split the screen into more pages or trim the markup instead).** A reconstructed real-world page easily runs longer — keep only the structure and content the screen is about, not every nav link, footer, or repeated list item.
+
 **Image path — `renderMode == "image"` only, when the user explicitly asked for screenshots:**
 
 ```

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-storyboarding-events/SKILL.md

@@ -245,7 +245,7 @@ The MCP `create_screen` call above already sets the node's `title` and `meta.fie
 
 A storyboard screen is placed at a *provisional* position — Steps 4 and 5 wire it to its COMMAND / READMODEL once those exist, and may move it first. Pass `autoConnect: false` on `create_screen` here so the placement doesn't pre-wire the screen to whatever happens to sit in the adjacent column; the real `SCREEN → COMMAND` and `READMODEL → SCREEN` edges are created deliberately in Steps 4 and 5. When creating several screens whose HTML is already authored, put them all in one `create_screen` call's `screens` array with `autoConnect: false`.
 
-Design the page(s) as real HTML/CSS, following the `html-screen` skill's guidance: write full-size markup (16px body text, generous padding — the canvas scales it down, don't shrink it yourself), one complete self-contained fragment per page (no `<html>`/`<head>`/`<body>` wrapper — the canvas adds those), no `<script>`/inline handlers (stripped server-side), and Bulma CSS classes (`title`, `button`, `is-primary`, `field`/`control`/`input`, etc. — remember heading size modifiers like `class="title is-1"`) since Bulma 0.9.4 is loaded by default. Every page MUST include real field labels matching the actual event/command fields this screen captures or displays, and at least one primary action (submit/confirm button) for command screens.
+Design the page(s) as real HTML/CSS, following the `html-screen` skill's guidance: write full-size markup (16px body text, generous padding — the canvas scales it down, don't shrink it yourself), one complete self-contained fragment per page (no `<html>`/`<head>`/`<body>` wrapper — the canvas adds those), no `<script>`/inline handlers (stripped server-side), and Bulma CSS classes (`title`, `button`, `is-primary`, `field`/`control`/`input`, etc. — remember heading size modifiers like `class="title is-1"`) since Bulma 0.9.4 is loaded by default. Keep every page at most 6000 characters per page (the server rejects a longer page with `400 HTML_SCREEN_PAGE_TOO_LONG` — split the screen into more pages or trim the markup instead). Every page MUST include real field labels matching the actual event/command fields this screen captures or displays, and at least one primary action (submit/confirm button) for command screens.
 
 > **CRITICAL: NEVER pass an empty `pages` array.** An empty pages array produces a blank placeholder and is always wrong. You MUST design and include actual page markup before calling the render API.
 

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

@@ -31,31 +31,21 @@ From `$ARGUMENTS`, extract:
 
 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.
+3. Then generate every target's values and write them all in a single `submit_node_events { events: [...] }` call — one `node:changed` event per element, never one call per element.
 
 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)
+## Step 2 — Resolve the element (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`:
+Resolve `target` to a node, with whichever identifier it is:
 
-- `target` is a UUID → pass `nodeId`
-- `target` is a name → pass `name`
-- `target` is a cell name (e.g. `B3`) → pass `cellName` + `timelineId` (the chapter id — if multiple chapters exist on the board, resolve which one first using 2c-fallback's chapter lookup, or `mcp__eventmodelers__get_nodes { "boardId": "$BOARD_ID", "type": "CHAPTER" }`, and ask the user if ambiguous). Only pass a cell name you were given or read back as a node's `cellName` (`get_board_outline`/`get_nodes`/`get_node` all report it) — if all you have is a node id or title, pass that instead rather than constructing an address.
+- `target` is a UUID → `mcp__eventmodelers__get_node { "boardId": "$BOARD_ID", "nodeId": "<target>" }`
+- `target` is a name → `mcp__eventmodelers__get_nodes { "boardId": "$BOARD_ID", "name": "<target>" }` — a partial, case-insensitive title match; prefer an exact title, and if several elements still match, list them and ask the user to pick one
+- `target` is a cell name (e.g. `B3`) → `mcp__eventmodelers__get_nodes { "boardId": "$BOARD_ID", "chapterId": "$CHAPTER_ID" }` and take the node whose `cellName` is `target` (if multiple chapters exist, find the chapter first with `get_nodes { "type": "CHAPTER" }` and ask the user if ambiguous). Never construct a cell address yourself — only use one you were given or read back as a node's `cellName`.
 
-```
-mcp__eventmodelers__add_field_examples { "boardId": "$BOARD_ID", "nodeId": "<target, if a UUID>" }
-```
-```
-mcp__eventmodelers__add_field_examples { "boardId": "$BOARD_ID", "name": "<target, if a name>" }
-```
-```
-mcp__eventmodelers__add_field_examples { "boardId": "$BOARD_ID", "cellName": "<target, if a cell name>", "timelineId": "$CHAPTER_ID" }
-```
-
-If this succeeds, skip straight to Step 6 (report back), describing the fields the tool reports as changed. Use the manual fallback flow below (Steps 2–5) only if MCP isn't connected.
+Then continue with Step 3 (linked elements) — `mcp__eventmodelers__get_connected_nodes { "boardId": "$BOARD_ID", "nodeId": "<resolved id>", "includeFields": true }` returns the neighbours and their fields in one call.
 
 **Fallback (no MCP):** see `references/api-fallback.md` — "Step 2 — Resolve the element".
 

package/stacks/modeling-kit/templates/.claude/skills/examples/references/api-fallback.md

@@ -15,11 +15,12 @@ curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$target" \
 ```
 
 ### 2b — Name search
-If `target` is not a UUID, search by name:
+If `target` is not a UUID, list the board's nodes and match on `meta.title` (the REST nodes endpoint has no name filter):
 
 ```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/events/search?name=$(python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))' "$target")" \
-  -H "x-user-id: examples-skill"
+curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes" \
+  -H "x-user-id: examples-skill" \
+  | jq --arg t "$target" '[.[] | select((.meta.title // "") | ascii_downcase | contains($t | ascii_downcase))]'
 ```
 
 Pick the best match (exact title match preferred; case-insensitive). If multiple matches exist, list them and ask the user to pick one.

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

@@ -54,6 +54,7 @@ Write normal, full-size HTML/CSS for each page — as if designing a real webpag
 Guidelines:
 - **Keep it simple — this is a view-only mockup, not a working app.** No JavaScript, no interactivity beyond what a static page can show (enforced server-side, see below). Keep the CSS compact: inline styles or a handful of Bulma classes are enough — don't write a large embedded `<style>` block or reinvent what Bulma already gives you for free.
 - Each page is one complete, standalone HTML fragment — not a `data-step` div nested inside a shared blob. A multi-step flow (e.g. cart → payment → confirmation) is three separate pages in the array, each fully self-contained.
+- **Each page may be at most 6000 characters** (the full markup string, including inline styles). The server rejects a longer page with `400 HTML_SCREEN_PAGE_TOO_LONG` (`context: {pageIndex, length, maxLength}`) and saves nothing — the render call fails as a whole. Check each page's length before rendering; if one is over, trim it (fewer inline styles, Bulma classes instead of custom CSS, fewer repeated sample rows) or split the content into another page. Adding a mark also counts toward the limit, since it adds attributes to the page's markup.
 - Inline styles (`style="..."`) are the simplest way to keep each page self-contained.
 - No `<script>` tags, no inline event handlers (`onclick`, `onload`, ...), no `javascript:` URIs — these are stripped server-side from every page before persisting regardless of what's sent. This is a static visual mockup, not an interactive prototype.
 - A real page background (e.g. a light gray full-bleed background behind a centered white card) reads more realistically than a bare form floating on white.
@@ -149,7 +150,7 @@ mcp__eventmodelers__create_screen {
 
 **Fallback (no MCP):** see `references/api-fallback.md` — "Step 4 — Creating a new node".
 
-Expect `204 No Content` on success from either curl call.
+Expect `204 No Content` on success from either curl call. A `HTML_SCREEN_PAGE_TOO_LONG` error means a page exceeds 6000 characters — shorten or split that page (see Step 3's guidelines) and send the call again; don't give up on the render.
 
 ## Step 5 — Define field data lineage (mandatory)
 

package/stacks/modeling-kit/templates/.claude/skills/html-screen/references/api-fallback.md

@@ -2,6 +2,8 @@
 
 Only needed when MCP is not connected. Every call below has an MCP equivalent in the main SKILL.md — always prefer that.
 
+Each entry in `pages` may be at most 6000 characters — a longer page returns `400 {"code": "HTML_SCREEN_PAGE_TOO_LONG", "context": {"pageIndex", "length", "maxLength"}}` and nothing is saved.
+
 ## Step 2 — Load existing pages
 
 ```bash

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

@@ -43,7 +43,7 @@ Then **create one task per screen** using TaskCreate, naming each task after the
 
 ## HTML page design (default)
 
-Design each page as real, full-size HTML/CSS following the `html-screen` skill's conventions: full-size markup (16px body text, generous padding — the canvas scales it down, don't shrink it yourself), one complete self-contained fragment per page (no `<html>`/`<head>`/`<body>` wrapper), no `<script>`/inline handlers (stripped server-side), and Bulma CSS classes (`title`, `button`, `is-primary`, `field`/`control`/`input`, etc. — remember heading size modifiers like `class="title is-1"`) since Bulma 0.9.4 is loaded by default.
+Design each page as real, full-size HTML/CSS following the `html-screen` skill's conventions: full-size markup (16px body text, generous padding — the canvas scales it down, don't shrink it yourself), one complete self-contained fragment per page (no `<html>`/`<head>`/`<body>` wrapper), no `<script>`/inline handlers (stripped server-side), and Bulma CSS classes (`title`, `button`, `is-primary`, `field`/`control`/`input`, etc. — remember heading size modifiers like `class="title is-1"`) since Bulma 0.9.4 is loaded by default. Keep every page at most 6000 characters per page (the server rejects a longer page with `400 HTML_SCREEN_PAGE_TOO_LONG` — split the screen into more pages or trim the markup instead).
 
 ## Sketch path (explicit request only)
 

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

@@ -53,10 +53,7 @@ Steps:
    chain they belong to, the timeline around them — and spend a full-`meta` `get_nodes` only
    on the handful you conclude you are actually going to touch. One `get_node` per changed
    node, or a second outline call for a chapter you already read this turn, is the same
-   fetch paid for twice (see `connect` Step 5).
-   `mcp__eventmodelers__get_board_events` with the header's `seq` range tells you what the
-   change actually was when the node's current state doesn't make it obvious. Then judge the
-   board as a whole: run `/analyze-existing-model` once per session to get that picture and
+   fetch paid for twice (see `connect` Step 5). Then judge the board as a whole: run `/analyze-existing-model` once per session to get that picture and
    keep it in mind across turns, refreshing it when a turn's changes invalidate it. On a
    `BOARD_REVIEW` turn that model-wide picture *is* the starting point.
    **What you read here is what you hand down in step 3.** Index it and keep it: every fact