@eventmodelers/cli 1.0.151 → 1.0.153

package/README.md

@@ -119,6 +119,7 @@ Use skills in Claude Code with `/skill-name`:
 | `/timeline` | Live event storming facilitator |
 | `/wdyt` | Business analyst review of your event model |
 | `/walkthrough` | Slice-by-slice player through a feature, or through every slice a planned feature needs (existing, to adjust, new) |
+| `/prototype` | Clickable prototype of one context as one platform-served page: built slice by slice with per-slice hashes (only changed slices rebuild), screens as tabs, in-browser event sourcing with a browsable log, logic from the scenarios, automations runnable from their own tab |
 | `/data-journey` | Where one piece of information (e.g. the customer email) originates, is stored, transformed, used and sent out — as a table in the chat |
 | `/domain-story` | Retells chapters as Domain Storytelling — actors, work objects and numbered activities, drawn as a graph per chapter in the chat |
 | `/stressor-analysis` | Residuality-theory stress test of one chapter: wide stressors and their residues, a stressor × element matrix that exposes hidden coupling, redesigns proposed as new slices |

package/cli.js

@@ -28,7 +28,7 @@ import { modelingPermissions } from './lib/agent-permissions.js';
 // copy that every useShared:true stack also gets copied into its installed kit (see
 // copyDirContents in installStack) for ralph.js to import standalone — see
 // shared/build-kit/lib/adapters/realtime-adapter.js for why it lives there instead.
-import { createRealtimeAdapter } from './shared/build-kit/lib/adapters/realtime-adapter.js';
+import { createRealtimeAdapter, keepSubscribed } from './shared/build-kit/lib/adapters/realtime-adapter.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -2349,7 +2349,7 @@ async function runModeling(kitDir, projectDir, { codeDir = null, verbose = false
   }
 
   if (!otherRunner) spawnProcess();
-  log(`agent: ${cfg.agentName ? `${cfg.agentName} (${cfg.agentId})` : cfg.agentId}`);
+  log(`agent: ${cfg.agentName ? `${cfg.agentName} (${cfg.agentId})` : cfg.agentId} — eventmodelers-cli v${CLI_VERSION}`);
   if (localRunner) log(`runner: local model — ${localRunner.describe()} (board tools over MCP; no skills, no subagents)`);
   if (execRunner) log(`runner: ${execRunner.describe()} — one process per turn (skills from the kit; no subagents)`);
   log(
@@ -3076,8 +3076,8 @@ async function runModeling(kitDir, projectDir, { codeDir = null, verbose = false
 
   let lastTokenRefreshAt = 0;
   async function refreshRealtimeToken(reason) {
-    // Guard against hammering the token endpoint: a rejected channel retries every
-    // ~14s on its own, so without this a bad token would trigger a refresh call per retry.
+    // Guard against hammering the token endpoint: the three channels below usually fail
+    // together, and each asks for a refresh before rejoining.
     if (Date.now() - lastTokenRefreshAt < 5000) return;
     lastTokenRefreshAt = Date.now();
     try {
@@ -3100,18 +3100,20 @@ async function runModeling(kitDir, projectDir, { codeDir = null, verbose = false
     process.exit(0);
   };
 
+  // Each channel is rejoined after a failure with exponential backoff and a fresh token
+  // (see keepSubscribed) — never left to realtime-js's own fixed-interval rejoin loop.
+  const keep = (topic, handlers, onSubscribed) => keepSubscribed(realtime, topic, handlers, {
+    log,
+    refreshToken: refreshRealtimeToken,
+    onSubscribed,
+  });
+
   // The kill signal is broadcast on the BOARD channel (see the platform's agent-kill /
   // backoffice/killagent slices), not on the org channel this agent uses for prompts — without
   // this second subscription a modeling agent can only be stopped with a kill(1).
-  realtime.subscribe(
-    `board:${cfg.boardId}-slicechanged`,
-    {message: exitIfAddressed},
-    (status) => log(`channel "board:${cfg.boardId}-slicechanged": ${status}`),
-  ).catch((err) => {
-    log(`board channel subscribe failed, remote kill won't reach this agent: ${err.message}`);
-  });
+  keep(`board:${cfg.boardId}-slicechanged`, {message: exitIfAddressed});
 
-  realtime.subscribe(
+  keep(
     channelName,
     {
       message: exitIfAddressed,
@@ -3125,33 +3127,15 @@ async function runModeling(kitDir, projectDir, { codeDir = null, verbose = false
         drain().catch((err) => log(`drain error: ${err.message}`));
       },
     },
-    (status) => {
-      log(`channel "${channelName}": ${status}`);
-      if (status === 'SUBSCRIBED') drain().catch((err) => log(`initial drain error: ${err.message}`));
-      // A bad/stale token otherwise sits in realtime-js's own rejoin-retry loop until the
-      // next scheduled refresh below — up to 10 minutes of failed joins. Refresh immediately
-      // instead of waiting on the clock.
-      if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT') {
-        refreshRealtimeToken(status).catch(() => {});
-      }
-    },
-  ).catch((err) => {
-    log(`realtime subscribe failed, prompts won't be pushed live: ${err.message}`);
-  });
+    // Also after a reconnect: prompts created while the channel was down were never pushed.
+    () => drain().catch((err) => log(`initial drain error: ${err.message}`)),
+  );
 
-  const boardChannelName = `board:${cfg.boardId}`;
-  realtime.subscribe(
-    boardChannelName,
+  if (!boardLane) log(`channel "board:${cfg.boardId}": events dropped — --worker`);
+  keep(
+    `board:${cfg.boardId}`,
     Object.fromEntries(BOARD_CHANGE_EVENTS.map((event) => [event, (payload) => onBoardEvent(event, payload)])),
-    (status) => {
-      log(`channel "${boardChannelName}": ${status}${boardLane ? '' : ' (events dropped — --worker)'}`);
-      if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT') {
-        refreshRealtimeToken(status).catch(() => {});
-      }
-    },
-  ).catch((err) => {
-    log(`board subscribe failed, board changes won't be seen live: ${err.message}`);
-  });
+  );
 
   setInterval(() => {
     refreshRealtimeToken('scheduled').catch(() => {});

package/lib/bash-guard.js

@@ -8,7 +8,9 @@
 // Rules:
 // - Programs: curl (only to the platform's baseUrl), python3 (two exact forms), uuidgen, jq, git (read-only
 //   subcommands), and read-only text tools (cat, head, tail, wc, sort, uniq, grep, cut, tr, ls), echo, printf,
-//   mkdir, sleep, date, true. Nothing else — no sh/bash/eval/env/xargs/find/sed/awk/node/npm/rm/mv/cp.
+//   mkdir, sleep, date, true, and node for exactly one script: the kit's own prototype skill (.claude/skills/prototype/
+//   assets/prototype.mjs status|assemble|upload — the agent can't edit .claude/, so what runs is fixed). Nothing else —
+//   no sh/bash/eval/env/xargs/find/sed/awk/npm/rm/mv/cp, no other node.
 // - No command substitution ($(…), `…`, $((…)), <(…)) except exactly $(uuidgen) and $(seq N) / $(seq A B) — they mint
 //   ids and run nothing else. No subshells, brace groups, brace expansion, background jobs or ~ paths. The only control
 //   flow is `for NAME in …; do …; done` (its body checked like any other command; NAME counts as set).
@@ -395,11 +397,39 @@ function checkTextTool(prog, args, policy) {
   }
 }
 
+// The prototype skill's script, the one thing the agent may run with node. Resolved against the working directory (the
+// kit) — not the temp roots, where the agent could write its own script.
+const PROTOTYPE_SCRIPT = ['.claude', 'skills', 'prototype', 'assets', 'prototype.mjs'];
+const PROTOTYPE_FLAGS = new Set(['--base', '--org', '--board', '--context', '--out']);
+
+function isPrototypeRun(cmd, policy) {
+  const [prog, script] = cmd.words;
+  return prog?.text === 'node' && !!script && !script.refs.length
+    && resolve(policy.cwd, script.text) === resolve(policy.cwd, ...PROTOTYPE_SCRIPT);
+}
+
+function checkPrototypeRun(cmd, policy) {
+  const [, , sub, ...rest] = cmd.words;
+  if (!['status', 'assemble', 'upload'].includes(sub?.text)) refuse('the prototype script runs as: status, assemble or upload');
+  if (rest.length % 2) refuse('the prototype script takes --flag value pairs');
+  for (let k = 0; k < rest.length; k += 2) {
+    const flag = rest[k].text;
+    const value = rest[k + 1];
+    if (!PROTOTYPE_FLAGS.has(flag)) refuse(`prototype script option ${flag} is not allowed`);
+    if (flag === '--out') checkPath(value.text, 'prototype output directory', policy);
+    else if (flag === '--base') checkUrl(value, policy);
+  }
+  if (cmd.redirects.some((r) => r.op !== '>&' && r.target.text !== '/dev/null')) refuse('the prototype script runs without redirections');
+}
+
 function checkProgram(cmd, policy) {
   const [progWord, ...args] = cmd.words;
   const prog = progWord.text;
   if (progWord.refs.length || prog.includes('/')) refuse(`run programs by plain name — "${prog}"`);
   switch (prog) {
+    case 'node':
+      if (!isPrototypeRun(cmd, policy)) refuse('node may only run the kit\'s .claude/skills/prototype/assets/prototype.mjs');
+      return checkPrototypeRun(cmd, policy);
     case 'curl': return checkCurl(args, policy);
     case 'git': return checkGit(args, policy);
     case 'python3': return checkPython(args, policy);
@@ -423,6 +453,14 @@ export function checkBashCommand(command, policy) {
     const assigned = new Set(unwrapLoops(commands));
     for (const cmd of commands) {
       for (const a of cmd.assignments) {
+        // The one place besides curl -H the token may go: the prototype script's EM_TOKEN, nothing else assigned to it.
+        if (a.name === 'EM_TOKEN') {
+          if (!isPrototypeRun(cmd, policy) || !/^\$(?:TOKEN|EVENTMODELERS_TOKEN)$/.test(a.word.text.slice(a.name.length + 1))) {
+            refuse('EM_TOKEN may only be set to the board token for the prototype script');
+          }
+          a.word.tokenAllowed = true;
+          continue;
+        }
         if (PROTECTED_VAR.test(a.name) || TOKEN_VARS.has(a.name)) refuse(`setting ${a.name} is not allowed`);
         if (a.name === 'BASE_URL' && a.value.replace(/\/+$/, '') !== policy.baseUrl.replace(/\/+$/, '')) refuse(`BASE_URL may only be ${policy.baseUrl}`);
         assigned.add(a.name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.151",
+  "version": "1.0.153",
   "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/adapters/pocketbase-realtime-adapter.js

@@ -24,21 +24,25 @@ export async function createPocketBaseRealtimeAdapter(cfg, initialToken, deps =
   const pb = new PocketBase(cfg.pocketbaseUrl);
   pb.authStore.save(initialToken, null);
 
-  // subscribe() replaces the previous listener (see realtime-adapter.js).
-  let unsubscribe = null;
+  // One listener per topic; subscribe() replaces the topic's previous one (see realtime-adapter.js).
+  const listeners = new Map();
+  const remove = async (topic) => {
+    const unsubscribe = listeners.get(topic);
+    if (!unsubscribe) return;
+    listeners.delete(topic);
+    await unsubscribe().catch(() => {});
+  };
 
   return {
     async subscribe(topic, handlers, onStatus) {
-      if (unsubscribe) {
-        await unsubscribe().catch(() => {});
-        unsubscribe = null;
-      }
+      await remove(topic);
       for (let attempt = 0; ; attempt++) {
         try {
-          unsubscribe = await pb.collection(REALTIME_EVENTS_COLLECTION).subscribe('*', (e) => {
+          const unsubscribe = await pb.collection(REALTIME_EVENTS_COLLECTION).subscribe('*', (e) => {
             if (e.action !== 'create' || e.record.topic !== topic) return;
             handlers[e.record.event]?.(e.record.payload);
           });
+          listeners.set(topic, unsubscribe);
           onStatus?.('SUBSCRIBED');
           return;
         } catch (err) {
@@ -48,6 +52,9 @@ export async function createPocketBaseRealtimeAdapter(cfg, initialToken, deps =
         }
       }
     },
+    unsubscribe(topic) {
+      return remove(topic);
+    },
     setAuth(token) {
       pb.authStore.save(token, null);
     },

package/shared/build-kit/lib/adapters/realtime-adapter.js

@@ -4,8 +4,9 @@
 //
 //   subscribe(topic, handlers, onStatus?) — handlers is a { [eventName]: (payload) => void }
 //     map; onStatus?.(status) fires once the subscription is live ('SUBSCRIBED'). Calling it
-//     again replaces the previous subscription — never adds to it — and a replaced one no
-//     longer reports status.
+//     again for the same topic replaces that topic's subscription — never adds to it — and a
+//     replaced one no longer reports status. Different topics live side by side.
+//   unsubscribe(topic) — drop the topic's subscription (a no-op if there is none).
 //   setAuth(token) — refresh the short-lived realtime token on the live connection.
 //
 // cfg.realtimeProvider absent (older servers, predating PocketBase support) means
@@ -20,6 +21,7 @@
 
 import { createSupabaseRealtimeAdapter } from './supabase-realtime-adapter.js';
 import { createPocketBaseRealtimeAdapter } from './pocketbase-realtime-adapter.js';
+import { backoffMs } from '../backoff.js';
 
 export async function createRealtimeAdapter(cfg, initialToken) {
   const provider = cfg.realtimeProvider ?? 'supabase';
@@ -27,3 +29,64 @@ export async function createRealtimeAdapter(cfg, initialToken) {
     ? createPocketBaseRealtimeAdapter(cfg, initialToken)
     : createSupabaseRealtimeAdapter(cfg, initialToken);
 }
+
+const FAILED = new Set(['CHANNEL_ERROR', 'TIMED_OUT', 'CLOSED']);
+// A subscription has to hold this long before its failures are forgiven. Resetting on the
+// bare SUBSCRIBED let a channel that flaps (SUBSCRIBED, CHANNEL_ERROR, SUBSCRIBED, …) retry
+// at the shortest delay forever.
+const STABLE_MS = 60_000;
+
+// Keeps one topic subscribed for the life of the process. A failed channel is removed at
+// once — otherwise realtime-js keeps rejoining it on its own fixed schedule, which is where
+// the flood of SUBSCRIBED/CHANNEL_ERROR lines came from — and re-joined after an exponential
+// backoff, with a fresh token, for as long as it takes.
+//
+// onSubscribed({ recovered }) runs on every successful join; recovered is true when it
+// follows a failure (broadcasts sent while the channel was down are gone).
+export function keepSubscribed(realtime, topic, handlers, {
+  log = console.log,
+  refreshToken = async () => {},
+  onSubscribed = () => {},
+  backoff = { baseMs: 2_000, capMs: 5 * 60_000 },
+} = {}) {
+  let failures = 0;
+  let down = false;
+  let retryPending = false;
+  let stableTimer = null;
+
+  const onFailure = (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 (retryPending) return;
+    retryPending = true;
+    down = true;
+    clearTimeout(stableTimer);
+    failures += 1;
+    const delay = backoffMs(failures, backoff);
+    log(`channel "${topic}": ${reason} (attempt ${failures}) — resubscribing in ${Math.round(delay / 1000)}s`);
+    realtime.unsubscribe(topic).catch(() => {});
+    setTimeout(async () => {
+      // A failed refresh is the caller's to log; rejoining on the old token is still worth a try.
+      await refreshToken(`channel ${reason}`).catch(() => {});
+      retryPending = false;
+      subscribe();
+    }, delay);
+  };
+
+  const onStatus = (status) => {
+    if (FAILED.has(status)) return onFailure(status);
+    if (status !== 'SUBSCRIBED') return log(`channel "${topic}": ${status}`);
+    const recovered = down;
+    down = false;
+    log(`channel "${topic}": SUBSCRIBED${recovered ? ` — recovered after ${failures} failed attempt(s)` : ''}`);
+    clearTimeout(stableTimer);
+    stableTimer = setTimeout(() => { failures = 0; }, STABLE_MS);
+    onSubscribed({ recovered });
+  };
+
+  const subscribe = () => {
+    realtime.subscribe(topic, handlers, onStatus)
+      .catch((err) => onFailure(`subscribe failed: ${err.message}`));
+  };
+  subscribe();
+}

package/shared/build-kit/lib/adapters/supabase-realtime-adapter.js

@@ -10,23 +10,32 @@ export async function createSupabaseRealtimeAdapter(cfg, initialToken, deps = {}
   });
   await supabase.realtime.setAuth(initialToken);
 
-  // supabase.channel(topic) hands back the existing channel for a topic it already knows, so
-  // re-subscribing on it would stack another set of handlers — the old channel is removed first.
-  let current = null;
+  // One live channel per topic. supabase.channel(topic) hands back the existing channel for a
+  // topic it already knows, so re-subscribing on it would stack another set of handlers — the
+  // old channel is removed first.
+  const channels = new Map();
+  const remove = async (topic) => {
+    const channel = channels.get(topic);
+    if (!channel) return;
+    // Detach before removing: the removal itself makes the old channel report CLOSED, and a
+    // late status from a removed channel must not count as the topic's current subscription's.
+    channels.delete(topic);
+    await supabase.removeChannel(channel).catch(() => {});
+  };
 
   return {
     async subscribe(topic, handlers, onStatus) {
-      // Detach before removing: the removal itself makes the old channel report CLOSED, and a
-      // late status from a replaced channel must not count as this subscription's.
-      const previous = current;
-      current = null;
-      if (previous) await supabase.removeChannel(previous).catch(() => {});
+      await remove(topic);
       let channel = supabase.channel(topic, { config: { private: true } });
       for (const [event, handler] of Object.entries(handlers)) {
         channel = channel.on('broadcast', { event }, (msg) => handler(msg.payload));
       }
-      current = channel;
-      channel.subscribe((status) => { if (channel === current) onStatus?.(status); });
+      channels.set(topic, channel);
+      channel.subscribe((status) => { if (channels.get(topic) === channel) onStatus?.(status); });
+    },
+    // Also stops realtime-js's own rejoin loop for an errored channel.
+    unsubscribe(topic) {
+      return remove(topic);
     },
     setAuth(token) {
       return supabase.realtime.setAuth(token);

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

@@ -11,11 +11,11 @@ import { readFileSync, mkdirSync, writeFileSync, existsSync, readdirSync, rename
 import { join, dirname } from 'path';
 import { homedir } from 'os';
 import { randomUUID } from 'crypto';
-import { createRealtimeAdapter } from './adapters/realtime-adapter.js';
+import { createRealtimeAdapter, keepSubscribed } from './adapters/realtime-adapter.js';
 import { backoffMs, sleep } from './backoff.js';
 import { redactConsole } from './redact.js';
 
-// Backoff for calls to the platform that failed for a reason on its side (startup, the channel).
+// Backoff for calls to the platform that failed for a reason on its side (startup).
 const PLATFORM_BACKOFF = { baseMs: 2_000, capMs: 5 * 60_000 };
 
 // ── HTTP helpers ──────────────────────────────────────────────────────────────
@@ -446,66 +446,34 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllSt
     return refreshing;
   };
 
-  // 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, and nothing
-  // else ever re-joins it, so this retries for as long as it takes, with backoff so a
-  // lasting failure doesn't hammer the platform. (A revoked token ends the process anyway:
-  // refreshToken's fetch gets the 401.)
-  let channelErrorStreak = 0;
-  let resubscribePending = false;
-  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 (resubscribePending) return;
-    resubscribePending = true;
-    channelErrorStreak += 1;
-    const delay = backoffMs(channelErrorStreak, PLATFORM_BACKOFF);
-    console.warn(`[agent] ${ts()} Channel "${channelName}": ${reason} (attempt ${channelErrorStreak}) — resubscribing in ${Math.round(delay / 1000)}s`);
-    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.
-      }
-      resubscribePending = false;
-      subscribeChannel();
-    }, delay);
-  };
-  const subscribeChannel = () => {
-    realtime.subscribe(
-      channelName,
-      {
-        // A kill names exactly one agent: {type: 'kill', id: '<agentId>', instruction: 'exit'}.
-        // Anything that doesn't name this agent is ignored — a broadcast reaches every agent on
-        // the board, and the older signal (the bare string "Exit") took all of them down at once.
-        // That string form is gone for good, not just unhandled: Supabase's broadcast API rejects
-        // a non-object payload with 422, so it never actually arrived here.
-        message: (payload) => {
-          if (payload?.type !== 'kill' || payload?.id !== cfg.agentId) return;
-          console.log(`[agent] ${ts()} Received kill (instruction: ${payload.instruction ?? 'exit'}) — shutting down`);
-          process.exit(0);
-        },
-        'slice:changed': (payload) => handleSliceChanged(payload, cfg, kitDir, queueAllStatuses),
-      },
-      (status) => {
-        if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT') return onChannelFailure(status);
-        if (status !== 'SUBSCRIBED' || channelErrorStreak === 0) {
-          console.log(`[agent] ${ts()} Channel "${channelName}": ${status}`);
-          return;
-        }
-        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.
-        fetchAndPersistSlices(cfg, kitDir).catch((err) =>
-          console.error(`[agent] ${ts()} Slice re-fetch after reconnect failed:`, err),
-        );
-      },
-    ).catch((err) => onChannelFailure(`subscribe failed: ${err.message}`));
-  };
-  subscribeChannel();
+  // A channel that errors (often a stale token) needs a fresh token AND a new join —
+  // keepSubscribed does both, with backoff, for as long as it takes. (A revoked token ends
+  // the process anyway: refreshToken's fetch gets the 401.)
+  keepSubscribed(realtime, channelName, {
+    // A kill names exactly one agent: {type: 'kill', id: '<agentId>', instruction: 'exit'}.
+    // Anything that doesn't name this agent is ignored — a broadcast reaches every agent on
+    // the board, and the older signal (the bare string "Exit") took all of them down at once.
+    // That string form is gone for good, not just unhandled: Supabase's broadcast API rejects
+    // a non-object payload with 422, so it never actually arrived here.
+    message: (payload) => {
+      if (payload?.type !== 'kill' || payload?.id !== cfg.agentId) return;
+      console.log(`[agent] ${ts()} Received kill (instruction: ${payload.instruction ?? 'exit'}) — shutting down`);
+      process.exit(0);
+    },
+    'slice:changed': (payload) => handleSliceChanged(payload, cfg, kitDir, queueAllStatuses),
+  }, {
+    log: (msg) => console.log(`[agent] ${ts()} ${msg}`),
+    refreshToken,
+    onSubscribed: ({ recovered }) => {
+      if (!recovered) return;
+      // 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.
+      fetchAndPersistSlices(cfg, kitDir).catch((err) =>
+        console.error(`[agent] ${ts()} Slice re-fetch after reconnect failed:`, err),
+      );
+    },
+  });
 
   setInterval(() => {
     refreshToken('scheduled 10min refresh').catch((err) => console.error(`[agent] ${ts()} Scheduled token refresh failed:`, err));

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

@@ -707,8 +707,13 @@ Append Given-When-Then scenario(s) to a column's spec node — the node is creat
 // A step is addressed either way:
 { id: 'node-uuid' }                          // a board node
 { title: 'OrderPlaced', type: 'EVENT' }      // resolved against this timeline's own elements
+
+// Either form also carries the step's values for this scenario — the fields essential to it, each with its example:
+{ title: 'OrderPlaced', type: 'EVENT', fields: [{ name: 'orderId', example: 'o-42' }, { name: 'placedAt', example: '2026-10-12' }] }
 ```
 
+`fields` is what the board shows on the step and what generated tests use as the scenario's data. Fill the values the scenario depends on (what the rule decides on, linking ids, the asserted outcome) and leave the rest out, so it is clear which data is relevant — a value that only appears in `contextNote` is not part of the specification.
+
 A step given as `{title, type}` is resolved server-side, so the names you already know need **no `get_spec_info`/`get_nodes` call first**. A title matching more than one element is rejected (`SCENARIO_ITEM_AMBIGUOUS`) with the candidates rather than guessed at, and resolution runs before anything is written — a bad name leaves no empty spec node behind.
 
 **Validation rules**:
@@ -857,6 +862,26 @@ avgChangesPerSlice }` — `firstTimeRightRate` is the share of the slices that r
 
 ---
 
+### POST `/api/org/:orgId/boards/:boardId/prototype/:contextId`
+**File**: `src/slices/change/api-prototypes/routes.ts`
+
+Store a context's generated prototype page (the `prototype` skill). REST only, no MCP tool — `prototype.mjs upload` calls it.
+
+**Request**: the page as the raw body, `Content-Type: text/html`, at most 5 MB. `contextId` is a MODEL_CONTEXT node or a
+timeline; a timeline resolves to its effective context (the rule `slicedata` uses), so every timeline of one context
+stores to the same place.
+
+The page is sanitized — inline scripts and the `text/plain` slice blocks stay byte for byte; removed are scripts and
+stylesheets from anywhere but `/vendor/`, module scripts, frames, objects, `base`, `<meta http-equiv>`, `on*` attributes,
+`javascript:` URLs and HTML comments — then gzipped and stored in the organization's bucket at
+`<boardId>/<effective context id>.gz`, replacing the previous version.
+
+**Response**: `201` — `{ contextId, contextName, path, bytes, gzippedBytes, removed: string[] }` (`removed`: what the
+sanitizer took out, one line each). `400` `PROTOTYPE_HTML_REQUIRED` (empty body / not `text/html`) /
+`PROTOTYPE_HTML_INVALID` (no `<body>`) · `404` `CONTEXT_NOT_FOUND` · `413` larger than 5 MB.
+
+---
+
 ## 9. Extensions
 
 **File**: `src/slices/extensions/routes.ts`
@@ -1148,9 +1173,10 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
 | to answer where one piece of information comes from and where it ends up ("where is the customer email used?") | `dataJourney` | nothing — element names pan the canvas |
 | to show a diagram you drew yourself — a context map, a domain story, a sketch, any picture that isn't a chart | `svg` | nothing |
 | to lay out rows and columns — a comparison, a matrix (stressors × elements), a short list with a few attributes | `table` | nothing — linked cells pan the canvas |
+| to show a prototype you just built and uploaded (the `prototype` skill), running in the chat | `prototype` | nothing — **Full screen** opens the board's prototype player |
 | something the customer defined their own snippet type for (a risk card, a sign-off — see `list_snippet_types`) | `custom` | the clicked action's `answer`; `context.snippetReply.then` says what to do |
 
-`confirm`, `poll`, `tasks` and `changes` are questions: a person answers once, then they show as answered. `link`, `image`, `code`, `report`, `walkthrough`, `screen`, `dataJourney`, `svg` and `table` are display only and never wait for anything.
+`confirm`, `poll`, `tasks` and `changes` are questions: a person answers once, then they show as answered. `link`, `image`, `code`, `report`, `walkthrough`, `screen`, `dataJourney`, `svg`, `table` and `prototype` are display only and never wait for anything.
 
 ### Shapes
 ```typescript
@@ -1204,6 +1230,8 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
                             align?: 'left' | 'center' | 'right' }>,
   rows: Array<Array<string | number | true | null                                // 1–200, one cell per column; true = check mark, null = empty
                     | { text: string, nodeId?: string }>> }                      // a cell linking to an element; shown 5 rows per page
+{ kind: 'prototype', timelineId: string,                                          // the context the prototype was uploaded for: a MODEL_CONTEXT or timeline id
+  title?: string, caption?: string }                                              // (html: string ≤ 60000 chars instead of timelineId exists, but a built page never fits)
 ```
 
 ### How to use them
@@ -1220,6 +1248,7 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
 - **`svg`** is for a picture you draw yourself: give the root a `viewBox` (and `width`/`height` for its natural size), inline colours and fonts — it is shown as an image, so scripts, `<a>` links and external resources do nothing. To make parts of it clickable, list them in `links`: a rectangle in the viewBox coordinates you drew in plus the element it stands for (only real ids from this board); the app lays a clickable area over each that zooms the canvas there. Prefer `report` for numbers. A domain story (who does what with which work object) is an `svg` you draw — the `domain-story` skill (modeling kit) has the procedure and the drawing style. Every SVG snippet has a download-as-PNG button.
   - **"Place it on the board" after you drew an SVG always means: put that picture on the board as an image** — never rebuild it from elements (stickies, lanes, a timeline), never a SCREEN, never a new snippet. `place_image` with `imageBase64` = the SVG document itself, base64-encoded, `mimeType: "image/svg+xml"`, `title` = the snippet's title: it becomes an OUTLINE (the drawing tools' image element), free-floating at `x`/`y`, in no chapter and connected to nothing. Place it where the person says, else in free space next to the chapter it is about (`get_chapter_bounds`: right of or below it). Add a white background `<rect>` first if the SVG has none, or it is unreadable on a dark board. One SVG = one image. The image on the board has no clickable areas — `links` stay in the chat.
 - **`table`** is for anything that is rows and columns and not a chart: a comparison of options, an incidence matrix (rows = stressors, columns = elements, `true` where it hits), a short list with a few attributes per item. It computes nothing — totals are a row you add. Put element ids in `nodeId` (header or cell) so names are links; a row longer than the columns is cut, a shorter one padded, an empty one dropped. Prefer `report` for numbers you want *seen* as a trend or share, `dataJourney` for one piece of data's path.
+- **`prototype`** runs a prototype in the chat: the page the platform stored for `timelineId` (the `contextId` the `prototype` skill uploaded under — any timeline of that context works too), in a sandboxed iframe with **Restart** (empty event log) and **Full screen** (the same player as the timeline's ▶). Send it only after `upload` succeeded — before that it shows "No prototype has been built for this yet". The `text` is the short report of what was built; the prototype itself is the snippet.
 - A snippet is shown exactly as you send it — keep secrets and tokens out of `code` and `image`.
 
 ### Custom snippet types

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

@@ -15,6 +15,19 @@ This step applies the shared element rules in **`eventmodeling-core-rules`** —
 
 Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect` skill) — the curl blocks below are the fallback for sessions without MCP connected.
 
+## Examples Are the Scenario — Non-Negotiable
+
+**A scenario without concrete example values is not a scenario.** The element names in
+`given`/`when`/`then` only say *which* facts are involved; the example values say *what* happened
+and *why* the outcome follows — they are the actual specification, and the only thing a generated
+test can assert against. Every value **essential to the scenario** — the ones the rule decides on
+and the ones that tie the steps together — is filled in as `fields: [{name, example}]` on the
+step it belongs to (`given` events, the `when` command, `then` events, `context`/`then` read
+models, storyline beats), and list read models carry their expected rows in `examples` (or
+`expectEmptyList: true`). Never post a scenario, never report one done, and never mark this step
+complete while an essential value is missing. Details: "Fill the values essential to the scenario"
+below.
+
 ## GWT vs. Storyline — Decision Rule
 
 A GWT scenario asserts one isolated transition (one precondition → one action → one outcome). A
@@ -65,6 +78,37 @@ assumption or regulation behind the case, why the case matters, a time gap betwe
 cart total is 120 €" (→ field examples), "an email is sent" (→ a `then` event), restating the
 title. Most scenarios need no note; keep any note to a few lines.
 
+### Fill the values essential to the scenario — mandatory
+
+The goal is not to fill every field, but every value **the scenario depends on**: change one of
+them and the outcome changes, or the steps no longer belong together. Essential are:
+
+- **the values the rule decides on** — the dates of an expiry rule, the wrong token, the outcome
+  `Unclear` that routes a check into review, the second registration's duplicate email;
+- **the ids linking the steps** — the same `customerId` in the given events, the command and the
+  outcome, so it is clear they are about the same thing;
+- **the asserted outcome** — the `then` event's or read model's values that the scenario expects
+  (the `status: Rejected` and its reason, the row that appears in the list).
+
+**Leave every other field empty — that is best practice, not laziness.** The empty fields are
+what make it clear which data is relevant: a reader sees at a glance that this case turns on the
+dates and the token, not on the name, address or phone number. Padding every step with every field
+buries the values that carry the rule. The test for the result: someone reading only the filled
+values can tell why the outcome follows. A
+scenario whose essential values are missing is incomplete, even when a note explains the
+situation: the fields are the specification, the note is not.
+
+The values are what make the rule visible and testable. For an expiry rule, the dates go into the
+fields — `CustomerRegistered.registeredAt: 2026-10-12`, `ConfirmEmail.confirmedAt: 2026-10-13` —
+not into a note saying "registered on 2026-10-12, confirms on 2026-10-13". Keep ids consistent
+across the steps of one scenario (the same `customerId` in every given event, the command and the
+outcome), and pick values that sit on the interesting side of the rule (one day past the limit, not
+a vague "long ago").
+
+Read the elements' field names once (`get_nodes` with `projection: "fields"`, scoped by
+`chapterId`) and pick the essential ones per scenario from that. If a value the rule depends on has no field on any element (e.g. the expiry rule needs a
+timestamp no event carries), add that field to the element — don't move the value into the note.
+
 ### Storyline data shape
 
 ```json
@@ -466,7 +510,8 @@ Rejection scenario example:
   "expectError": true,
   "errorDescription": "reservation date is in the past",
   "given": [],
-  "when": [{"id": "<commandNodeId>", "title": "Reservation Command", "type": "COMMAND"}],
+  "when": [{"id": "<commandNodeId>", "title": "Reservation Command", "type": "COMMAND",
+            "fields": [{"name": "reservationId", "example": "r-123"}, {"name": "date", "example": "2026-10-12"}]}],
   "then": [],
   "examples": [],
   "expectEmptyList": false
@@ -480,8 +525,10 @@ State-violation rejection (given events establish the wrong state):
   "title": "Reject confirming an already-confirmed reservation",
   "expectError": true,
   "errorDescription": "reservation already confirmed",
-  "given": [{"id": "<eventNodeId>", "title": "ReservationConfirmed", "type": "EVENT"}],
-  "when": [{"id": "<commandNodeId>", "title": "Confirm Reservation", "type": "COMMAND"}],
+  "given": [{"id": "<eventNodeId>", "title": "ReservationConfirmed", "type": "EVENT",
+             "fields": [{"name": "reservationId", "example": "r-123"}, {"name": "confirmedAt", "example": "2026-10-12"}]}],
+  "when": [{"id": "<commandNodeId>", "title": "Confirm Reservation", "type": "COMMAND",
+            "fields": [{"name": "reservationId", "example": "r-123"}]}],
   "then": [],
   "examples": [],
   "expectEmptyList": false
@@ -511,6 +558,7 @@ After posting, tell the user:
 **No command has only 2 scenarios unless all other types were reviewed and found inapplicable.**
 
 **Per read model — this is a separate, equally mandatory pass, not an afterthought of the command pass above:**
+- [ ] **Essential example values filled (blocking — no exceptions)** — every value the rule decides on, the ids linking the steps and the asserted outcome carry a concrete `example` on their step; every other field left empty, so it is clear which data is relevant; a scenario whose values only appear in its note is not done
 - [ ] **Notes carry nothing an element could** — every `contextNote` and note beat holds only background no event, command field or read model can express; anything else is moved into `given`/`when`/`then`/`context` and the note removed
 - [ ] **Every READMODEL on the board has at least one view scenario** — GWT (`given`: source EVENTs, `when`: empty, `then`: the READMODEL) or a storyline. A model with dozens of command scenarios and 0 read-model scenarios is not a complete Step 7 — it's easy to walk away thinking coverage is thorough because the command side looks exhaustive, so check the read-model side explicitly before reporting this step done.
 - [ ] **Population scenario** — the view shows correct data after its source event(s)