@eventmodelers/cli 1.0.87 → 1.0.89

package/README.md

@@ -55,6 +55,8 @@ npx @eventmodelers/cli run
 
 `run` doesn't re-configure anything. It finds whatever kit dir `init` already created in this project and starts its agent loop (`ralph-claude.js`) against your existing `.eventmodelers/config.json`.
 
+Each agent turn is capped at 60 minutes by default so a hung agent can't stall the loop: it gets SIGTERM, then SIGKILL 10s later, and a slice that keeps timing out is Blocked by the stuck-slice guard. Change the cap with `"turnTimeoutMinutes"` in `.eventmodelers/config.json` or `RALPH_TURN_TIMEOUT_MIN` for one run; `0` turns it off.
+
 **Pulling the latest board state without starting an agent** — e.g. to inspect a context's slices, or in a script:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.87",
+  "version": "1.0.89",
   "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/lib/backoff.js

@@ -0,0 +1,12 @@
+// Exponential backoff with jitter: baseMs, 2×, 4×, … capped at capMs. Half the delay is
+// fixed, half random, so agents that failed together (a platform restart takes every agent
+// on it down at once) don't all come back in the same second.
+//
+// attempt is 1-based — the delay before the first retry is between baseMs/2 and baseMs.
+
+export function backoffMs(attempt, { baseMs, capMs }) {
+  const ceiling = Math.min(capMs, baseMs * 2 ** Math.max(0, attempt - 1));
+  return Math.round(ceiling / 2 + Math.random() * (ceiling / 2));
+}
+
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

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

@@ -11,6 +11,7 @@ import { join, dirname } from 'path';
 import { homedir } from 'os';
 import { randomUUID } from 'crypto';
 import { createRealtimeAdapter } from './adapters/realtime-adapter.js';
+import { backoffMs, sleep } from './backoff.js';
 
 // ── HTTP helpers ──────────────────────────────────────────────────────────────
 
@@ -275,6 +276,15 @@ async function handleSliceChanged(payload, cfg, kitDir, queueAllStatuses) {
   await retryOn401('fetchAndPersistSlices', () => fetchAndPersistSlices(cfg, kitDir)).catch((err) =>
     console.error('[agent] Slice persist error:', err),
   );
+  // This agent's own status writes (claim → InProgress, → Done, → Blocked) come straight back
+  // as slice:changed. Queuing them only buys a turn in which the agent reads its own echo and
+  // skips it. Attribution decides, never a guess: only an agentId equal to ours is dropped —
+  // a person's edit or another agent's (different id), or an event with no attribution at all,
+  // is still queued, so a missing field degrades to the old behaviour rather than losing work.
+  if (payload?.agentId && cfg.agentId && payload.agentId === cfg.agentId) {
+    console.log(`[agent] Own write — not queued (slice="${payload.sliceTitle}" status="${payload.sliceStatus}")`);
+    return;
+  }
   // 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
@@ -321,11 +331,33 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllSt
 
   // A subscribe that errors on a stale token needs a fresh token AND a new join
   // attempt — setAuth alone doesn't re-join a channel that already errored out.
-  // Capped so a non-expiry auth failure (e.g. genuinely revoked access) can't turn
-  // into a tight resubscribe loop hammering the platform forever.
+  // Retried with exponential backoff (2s → 5min) rather than a fixed delay and a cap:
+  // the cap used to leave the channel dead for good — the scheduled refresh only calls
+  // setAuth, it never re-joins — while the backoff alone keeps a genuinely revoked
+  // access from hammering the platform. A revoked token ends the process anyway, via
+  // retryOn401 inside refreshToken.
   let channelErrorStreak = 0;
+  let resubscribeTimer = null;
+  const onChannelFailure = (reason) => {
+    // One failure can be reported more than once (a channel erroring while its retry is
+    // already scheduled); a second resubscribe on top would join the channel twice.
+    if (resubscribeTimer) return;
+    channelErrorStreak += 1;
+    const delay = backoffMs(channelErrorStreak, { baseMs: 2_000, capMs: 5 * 60_000 });
+    console.warn(`[agent] ${ts()} Channel "${channelName}": ${reason} (attempt ${channelErrorStreak}) — resubscribing in ${Math.round(delay / 1000)}s`);
+    resubscribeTimer = setTimeout(async () => {
+      try {
+        await refreshToken(`channel ${reason}`);
+      } catch {
+        // Logged by refreshToken. Rejoining on the old token is still worth a try —
+        // if it fails too, that's just the next failure, with a longer delay.
+      }
+      resubscribeTimer = null;
+      subscribeChannel();
+    }, delay);
+  };
   const subscribeChannel = () => {
-    realtime.subscribe(
+    Promise.resolve(realtime.subscribe(
       channelName,
       {
         // A kill names exactly one agent: {type: 'kill', id: '<agentId>', instruction: 'exit'}.
@@ -340,32 +372,22 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllSt
         },
         'slice:changed': (payload) => handleSliceChanged(payload, cfg, kitDir, queueAllStatuses),
       },
-      async (status) => {
-        if (status !== 'CHANNEL_ERROR' && status !== 'TIMED_OUT') {
-          if (channelErrorStreak > 0) {
-            console.log(`[agent] ${ts()} Channel "${channelName}": ${status} — recovered after ${channelErrorStreak} failed attempt(s)`);
-          } else {
-            console.log(`[agent] ${ts()} Channel "${channelName}": ${status}`);
-          }
-          channelErrorStreak = 0;
-          return;
-        }
-        channelErrorStreak += 1;
-        console.warn(`[agent] ${ts()} Channel "${channelName}": ${status} (attempt ${channelErrorStreak}/5)`);
-        if (channelErrorStreak > 5) {
-          console.error(`[agent] ${ts()} Channel "${channelName}" failed ${channelErrorStreak} times in a row — giving up until the next scheduled token refresh (every 10min)`);
+      (status) => {
+        if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT') return onChannelFailure(status);
+        if (status !== 'SUBSCRIBED' || channelErrorStreak === 0) {
+          console.log(`[agent] ${ts()} Channel "${channelName}": ${status}`);
           return;
         }
-        try {
-          await refreshToken(`channel ${status}`);
-          await new Promise((r) => setTimeout(r, 2_000));
-          console.log(`[agent] ${ts()} Resubscribing to channel "${channelName}" (attempt ${channelErrorStreak}/5)...`);
-          subscribeChannel();
-        } catch (err) {
-          console.error(`[agent] ${ts()} Token refresh after channel error failed, will not resubscribe this round:`, err);
-        }
+        console.log(`[agent] ${ts()} Channel "${channelName}": ${status} — recovered after ${channelErrorStreak} failed attempt(s)`);
+        channelErrorStreak = 0;
+        // Broadcasts sent while the channel was down are gone. Re-read the slices once so a
+        // slice set to Planned during the gap still gets built — .slices/ is what ralphLoop
+        // picks Planned work from.
+        retryOn401('fetchAndPersistSlices (after reconnect)', () => fetchAndPersistSlices(cfg, kitDir)).catch((err) =>
+          console.error(`[agent] ${ts()} Slice re-fetch after reconnect failed:`, err),
+        );
       },
-    );
+    )).catch((err) => onChannelFailure(`subscribe failed: ${err.message}`));
   };
   subscribeChannel();
 
@@ -531,15 +553,26 @@ async function blockStuckSlice(kitDir, cfg, credentialed, planned, attempts) {
   console.error(`[ralph] ${reason} Marked "${planned.title}" (id=${planned.id}) as Blocked — moving on.`);
 }
 
+// Returns true once fn succeeds; false for a turn that timed out (see lib/turn.js). A timeout
+// is not retried in place: re-running the same hung turn every 60s would spin forever without
+// the stuck-slice guard ever seeing it, so it goes back to ralphLoop, which recounts the slice.
+// Any other failure is retried in place with exponential backoff (30s → 10min): a harness
+// that fails fast (API outage, rate limit, broken install) used to be relaunched every 60s
+// for as long as it stayed broken.
 async function runWithRetry(label, fn) {
-  while (true) {
+  for (let attempt = 1; ; attempt++) {
     try {
       console.log(`[ralph] ${label}`);
       await fn();
-      return;
+      return true;
     } catch (err) {
-      console.error(`[ralph] Error — retrying in 60s:`, err.message);
-      await new Promise((r) => setTimeout(r, 60_000));
+      if (err?.timedOut) {
+        console.error(`[ralph] ${err.message} — back to the loop`);
+        return false;
+      }
+      const delay = backoffMs(attempt, { baseMs: 30_000, capMs: 10 * 60_000 });
+      console.error(`[ralph] Error (attempt ${attempt}) — retrying in ${Math.round(delay / 1000)}s:`, err.message);
+      await sleep(delay);
     }
   }
 }
@@ -580,7 +613,7 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
       }
 
       const prompt = readFileSync(backendPromptFile, 'utf-8');
-      await runWithRetry(`onPlannedSlice: building slice "${planned.title}"...`, () => onPlannedSlice(prompt, {
+      const built = await runWithRetry(`onPlannedSlice: building slice "${planned.title}"...`, () => onPlannedSlice(prompt, {
         sliceId: planned.id,
         sliceTitle: planned.title,
         context: planned.ctx,
@@ -588,7 +621,7 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
         boardId: cfg.boardId ?? null,
         attempt: stuckSlice.count,
       }));
-      console.log(`[ralph] Slice build complete — waiting for next slice`);
+      if (built) console.log(`[ralph] Slice build complete — waiting for next slice`);
       if (credentialed) await fetchAndPersistSlices(cfg, kitDir).catch(() => {});
       didWork = true;
     }

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.
@@ -114,10 +114,9 @@ export function createSliceTracer({ baseUrl, token, organizationId, agentId, tra
   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/lib/turn.js

@@ -0,0 +1,57 @@
+// Wall-clock cap on one agent turn. Without it a hung harness (a stuck tool call, a
+// network stall, an interactive prompt nobody answers) blocks the loop forever — no
+// further tasks, no further slices, and the stuck-slice guard never gets a look in.
+//
+// RALPH_TURN_TIMEOUT_MIN (env) or turnTimeoutMinutes (.eventmodelers/config.json);
+// default 60, 0 turns the cap off.
+
+import { execFile } from 'child_process';
+
+const KILL_GRACE_MS = 10_000;
+
+export function turnTimeoutMs(cfg) {
+  const raw = process.env.RALPH_TURN_TIMEOUT_MIN ?? cfg?.turnTimeoutMinutes ?? 60;
+  const minutes = Number(raw);
+  return Number.isFinite(minutes) && minutes > 0 ? minutes * 60_000 : 0;
+}
+
+// Thrown (rejected) by a runner whose turn hit the cap. ralph.js's runWithRetry lets it
+// through to the outer loop instead of re-running the same turn in place, so a slice
+// that times out again is counted — and eventually Blocked — by the stuck-slice guard.
+export class TurnTimeoutError extends Error {
+  constructor(label, timeoutMs) {
+    super(`${label} timed out after ${Math.round(timeoutMs / 60_000)}min`);
+    this.timedOut = true;
+  }
+}
+
+// SIGTERM, then SIGKILL after a grace period. `shell: true` means proc is only the /bin/sh
+// wrapping the real command, so its children are signalled first — killing just the shell
+// would orphan the harness and leave it running. (A separate process group would be
+// cleaner, but a background group reading the terminal gets stopped by SIGTTIN, and
+// Ctrl-C would no longer reach it.)
+// The shell is only signalled once pkill has returned: killed any earlier, its children are
+// re-parented to init before pkill -P gets to look for them, and survive.
+function signal(proc, sig, viaShell) {
+  const killSelf = () => { try { proc.kill(`SIG${sig}`); } catch { /* already gone */ } };
+  if (viaShell && proc.pid) execFile('pkill', [`-${sig}`, '-P', String(proc.pid)], killSelf);
+  else killSelf();
+}
+
+export function superviseTurn(proc, { timeoutMs, label, log, viaShell = false }) {
+  let timedOut = false;
+  let killTimer;
+  const timer = timeoutMs
+    ? setTimeout(() => {
+        timedOut = true;
+        log(`${label} exceeded ${Math.round(timeoutMs / 60_000)}min — stopping it`);
+        signal(proc, 'TERM', viaShell);
+        killTimer = setTimeout(() => signal(proc, 'KILL', viaShell), KILL_GRACE_MS);
+      }, timeoutMs)
+    : null;
+  proc.on('close', () => {
+    clearTimeout(timer);
+    clearTimeout(killTimer);
+  });
+  return { timedOut: () => timedOut };
+}

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

@@ -4,6 +4,7 @@
 
 import { startRalph, loadLocalConfig, resolveAgentIdentity } from './lib/ralph.js';
 import { createSliceTracer, usageFromClaudeResult } from './lib/tracing.js';
+import { turnTimeoutMs, superviseTurn, TurnTimeoutError } from './lib/turn.js';
 import { spawn } from 'child_process';
 import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
@@ -33,9 +34,17 @@ const tracer = createSliceTracer({
 // --local must mean zero board contact — never hand Claude live board
 // credentials via the inline header, even if config.json has them, or it'll
 // treat them as already-connected and skip straight to board sync.
+// The token itself stays out of the prompt: `-p` is argv, visible to every local
+// user in `ps`, and the prompt lands in session transcripts. The header names the
+// env var instead (set in claudeEnv below) — connect treats it as the inline token,
+// and a curl header written as "x-token: $EVENTMODELERS_TOKEN" expands in the shell.
 const inlineHeader = !localOnly && cfg.boardId
-  ? `board=${cfg.boardId} token=${cfg.token} org=${cfg.organizationId} baseUrl=${cfg.baseUrl}\n\n`
+  ? `board=${cfg.boardId} token=$EVENTMODELERS_TOKEN org=${cfg.organizationId} baseUrl=${cfg.baseUrl}\n\n`
   : '';
+const timeoutMs = turnTimeoutMs(cfg);
+// The model can still surface the token (e.g. a Bash command it expanded by hand), and
+// --verbose logs tool input and assistant text as is — mask it before it hits the log.
+const redact = (s) => (cfg.token ? String(s).split(cfg.token).join('***') : s);
 
 // --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
@@ -86,6 +95,7 @@ function runClaude(prompt, slice = null) {
       stdio: ['inherit', 'pipe', 'inherit'],
       env: claudeEnv,
     });
+    const turn = superviseTurn(proc, { timeoutMs, label: 'Claude turn', log: (line) => console.error(`[ralph] ${line}`) });
 
     let buffer = '';
     proc.stdout.on('data', (chunk) => {
@@ -99,9 +109,9 @@ function runClaude(prompt, slice = null) {
 
         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 === 'text' && block.text && verbose) console.log(redact(block.text));
             if (block.type === 'tool_use') {
-              if (verbose) console.log(`→ ${describeToolUse(block)}`);
+              if (verbose) console.log(`→ ${redact(describeToolUse(block))}`);
               else if (block.name === 'Skill') console.log(`→ Skill: ${block.input?.skill ?? ''}`);
               else console.log(`→ ${block.name}`);
             }
@@ -113,7 +123,11 @@ function runClaude(prompt, slice = null) {
       }
     });
 
-    proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`Claude exited ${code}`))));
+    proc.on('close', (code) => {
+      if (turn.timedOut()) reject(new TurnTimeoutError('Claude turn', timeoutMs));
+      else if (code === 0) resolve();
+      else reject(new Error(`Claude exited ${code}`));
+    });
     proc.on('error', reject);
   });
 }

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

@@ -19,6 +19,7 @@
 
 import { startRalph, loadLocalConfig, resolveAgentIdentity } from './lib/ralph.js';
 import { createSliceTracer, usageFromHarnessEvent, sumUsage } from './lib/tracing.js';
+import { turnTimeoutMs, superviseTurn, TurnTimeoutError } from './lib/turn.js';
 import { spawn } from 'child_process';
 import { writeFileSync, mkdtempSync } from 'fs';
 import { tmpdir } from 'os';
@@ -42,10 +43,12 @@ if (!execCmd) {
 }
 
 // Same rule as ralph-claude.js: --local must mean zero board contact, so credentials
-// never reach the child even when config.json has them.
+// never reach the child even when config.json has them. Also as there: the token is
+// passed by env var name, never by value — the prompt goes on the command line.
 const inlineHeader = !localOnly && cfg.boardId
-  ? `board=${cfg.boardId} token=${cfg.token} org=${cfg.organizationId} baseUrl=${cfg.baseUrl}\n\n`
+  ? `board=${cfg.boardId} token=$EVENTMODELERS_TOKEN org=${cfg.organizationId} baseUrl=${cfg.baseUrl}\n\n`
   : '';
+const timeoutMs = turnTimeoutMs(cfg);
 
 const childEnv = {
   ...process.env,
@@ -122,8 +125,10 @@ function runExec(prompt, slice = null) {
       shell: true,
       env: { ...childEnv, RALPH_PROMPT_FILE: promptFile },
     });
+    const turn = superviseTurn(proc, { timeoutMs, label: 'exec turn', viaShell: true, log: (line) => console.error(`[ralph-exec] ${line}`) });
     const usage = traced ? collectUsage(proc.stdout) : null;
     proc.on('close', (code) => {
+      if (turn.timedOut()) return reject(new TurnTimeoutError('exec turn', timeoutMs));
       if (traced) {
         const u = usage();
         if (u) tracer.record({ ...slice, status: code === 0 ? 'ok' : 'error' }, { ...u, durationMs: u.durationMs ?? Date.now() - startedAt });

package/shared/skills/connect/SKILL.md

@@ -61,6 +61,8 @@ If an inline `board=<uuid>` is found, use it as `BOARD_ID` — **it takes priori
 
 (`agent=<uuid>` is not one of the four required values — it is optional, and its absence never makes this skill ask anything.)
 
+**`token=$EVENTMODELERS_TOKEN` is an inline token too.** The build loop passes the env var's *name*, not its value, so the secret never sits in the prompt. Treat it exactly like a literal inline token: `TOKEN` is `$EVENTMODELERS_TOKEN` (it counts toward "all four inline" below). Keep using the reference, never its value — write curl headers as `-H "x-token: $EVENTMODELERS_TOKEN"` (double quotes, so the shell expands it), don't `echo` or print it, and hand it to a subagent as `token=$EVENTMODELERS_TOKEN` (it inherits the same environment). MCP calls need nothing extra — `.mcp.json` already reads the same variable.
+
 **All four inline means this skill is already finished — stop here.** `token=`, `board=`, `org=` and `baseUrl=` arriving together is the shape a parent agent hands a subagent, and it resolves every required value in this one step. Do not walk the config file (Step 1), do not ask anything (Step 2), do not persist (Step 3), and do not make the verify call (Step 4): the parent resolved these values against this board and verified them there, so a subagent verifying them again learns nothing it wasn't just told and pays a round trip for it. Step 3.5 is a no-op too whenever `.mcp.json` already carries an `eventmodelers` entry — read the file, don't rewrite it, and don't re-register a server the session is already connected to. Print `Connected — board <BOARD_ID>` and return to the skill that invoked you.
 
 ---

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