@eventmodelers/cli 1.0.150 → 1.0.152

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);
@@ -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.150",
+  "version": "1.0.152",
   "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

@@ -696,6 +696,8 @@ Append Given-When-Then scenario(s) to a column's spec node — the node is creat
   title: string
   vertical?: boolean
   examples?: unknown[]
+  context?: SpecStep[]  // READMODELs the command decides against
+  contextNote?: string  // markdown background — ONLY what events, commands and read models can't express
   given?: SpecStep[]  // EVENTs from this timeline
   when?: SpecStep[]   // at most one COMMAND, or one inline QUERY object; empty if then has a READMODEL
   then?: SpecStep[]   // EVENTs only OR exactly one READMODEL (not mixed)
@@ -705,12 +707,18 @@ 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**:
 - `context`: only READMODELs (the state the command decides against)
+- `contextNote`: free markdown, last resort. State belongs in `given` events (or `context` read models), inputs in the `when` command's fields, outcomes in `then` — a note never replaces or repeats any of them. Use it only for background no element can carry: an external condition ("the payment provider is in maintenance"), a business assumption, the reason a case matters. Blank notes are dropped. Exported as `contextNote` on the scenario in slice data
 - `given`: only EVENTs from same timeline
 - `when`: max one COMMAND; must be empty when `then` contains a READMODEL (use an inline QUERY item for a state-view)
 - `then`: all EVENTs OR exactly one READMODEL — never mixed
@@ -765,8 +773,13 @@ Append one or more storylines to a column's spec node. The spec node is auto-cre
     examples?: unknown[]
   }>
 }
+
+// A note beat — free markdown anywhere in the sequence, referencing no element:
+{ instanceId: 'uuid', refId: '', type: 'STORYLINE_NOTE', title: 'Note', note: 'markdown' }
 ```
 
+A note beat is the storyline's `contextNote`: only for what the beats themselves can't express (an external condition, an assumption, a time gap like "two weeks later"). Never use one to stand in for an event, command or read model that should be a beat — model the element instead. It is exported as an element `{id: instanceId, type: 'STORYLINE_NOTE', description: note}`; an empty note is rejected (`STORYLINE_NOTE_EMPTY`).
+
 A beat is addressed either way, like a scenario step:
 ```typescript
 { refId: 'node-uuid' }                           // a board node — always wins, never re-resolved
@@ -849,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`
@@ -1140,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
@@ -1196,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
@@ -1212,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/axon/templates/.claude/skills/build-automation/SKILL.md

@@ -396,6 +396,8 @@ class {AutomationName}ProcessorTest {
 
 ### Storyline-Derived Tests (Optional)
 
+> **Note beats**: an entry with `type: STORYLINE_NOTE` is a note the board author placed in the walkthrough — its `description` is markdown context (an assumption, an external condition, a time gap), and its `id` is not a board node. Read it as background for the beats around it, but it is never a step: skip it when looking for COMMAND/EVENT/READMODEL beats or judging which beats are adjacent, and never turn it into test setup or an assertion on its own.
+
 `slice.json` may also carry a `storylines[]` array — narrated walkthroughs with an ordered
 `elements[]` "beats" sequence (EVENT/COMMAND/READMODEL/...). This is a secondary, supplementary
 source; `specifications[]` above stays the primary and default source of test cases. Most slices

package/stacks/axon/templates/.claude/skills/build-state-change/SKILL.md

@@ -405,6 +405,8 @@ see [references/axon-test-fixture-patterns.md](references/axon-test-fixture-patt
 
 ## Step 7b: Storyline-Derived Tests (Optional)
 
+> **Note beats**: an entry with `type: STORYLINE_NOTE` is a note the board author placed in the walkthrough — its `description` is markdown context (an assumption, an external condition, a time gap), and its `id` is not a board node. Read it as background for the beats around it, but it is never a step: skip it when looking for COMMAND/EVENT/READMODEL beats or judging which beats are adjacent, and never turn it into test setup or an assertion on its own.
+
 `slice.json` may carry a `storylines[]` array alongside `specifications[]` — narrated walkthroughs
 where an ordered sequence of `elements[]` "beats" (EVENT/COMMAND/READMODEL/...) shows one use case
 end to end. This is a secondary, supplementary source — `specifications[]` (Step 7) stays the

package/stacks/axon/templates/.claude/skills/build-state-view/SKILL.md

@@ -210,6 +210,8 @@ Do not design your own test cases unless specifically instructed to do so.
 
 ## Step 4b: Storyline-Derived Tests (Optional)
 
+> **Note beats**: an entry with `type: STORYLINE_NOTE` is a note the board author placed in the walkthrough — its `description` is markdown context (an assumption, an external condition, a time gap), and its `id` is not a board node. Read it as background for the beats around it, but it is never a step: skip it when looking for COMMAND/EVENT/READMODEL beats or judging which beats are adjacent, and never turn it into test setup or an assertion on its own.
+
 `slice.json` may also carry a `storylines[]` array — narrated walkthroughs where the *same* read
 model appears as multiple ordered "beats" across one flow (see `elements[]` on each storyline).
 This is a secondary, supplementary source: `specifications[]` (Step 4) remains the primary and

package/stacks/classic/templates/.claude/skills/build-automation/SKILL.md

@@ -39,6 +39,8 @@ Follow `/build-state-change` for this slice's command and events — all of its
 
 ### Storyline-derived tests
 
+> **Note beats**: an entry with `type: STORYLINE_NOTE` is a note the board author placed in the walkthrough — its `description` is markdown context (an assumption, an external condition, a time gap), and its `id` is not a board node. Read it as background for the beats around it, but it is never a step: skip it when looking for COMMAND/EVENT/READMODEL beats or judging which beats are adjacent, and never turn it into test setup or an assertion on its own.
+
 If `storylines[]` includes a beat sequence running through this automation's trigger → this slice's command, the command test for that segment is already covered by build-state-change's own "Storyline-derived tests" step.
 
 ## Step 3 — Find the trigger point

package/stacks/classic/templates/.claude/skills/build-state-change/SKILL.md

@@ -77,6 +77,8 @@ Name each test after the specification title so it can be traced back to the boa
 
 ### Storyline-derived tests (optional)
 
+> **Note beats**: an entry with `type: STORYLINE_NOTE` is a note the board author placed in the walkthrough — its `description` is markdown context (an assumption, an external condition, a time gap), and its `id` is not a board node. Read it as background for the beats around it, but it is never a step: skip it when looking for COMMAND/EVENT/READMODEL beats or judging which beats are adjacent, and never turn it into test setup or an assertion on its own.
+
 `storylines[]` in slice.json (optional — only present when the board author built an explicit walkthrough) can supply additional tests. A storyline embedded in this slice's slice.json already belongs entirely to this slice — no need to match beats against `commands[]` by id/title. Scan each storyline's ordered `elements` for a `type: COMMAND` beat followed by its EVENT beat(s):
 
 - `given` — the cumulative ordered events from the start of the storyline up to (not including) the command beat, set up as state as above

package/stacks/classic/templates/.claude/skills/build-state-view/SKILL.md

@@ -80,6 +80,8 @@ Name each test after the specification title.
 
 ### Storyline-derived tests (optional)
 
+> **Note beats**: an entry with `type: STORYLINE_NOTE` is a note the board author placed in the walkthrough — its `description` is markdown context (an assumption, an external condition, a time gap), and its `id` is not a board node. Read it as background for the beats around it, but it is never a step: skip it when looking for COMMAND/EVENT/READMODEL beats or judging which beats are adjacent, and never turn it into test setup or an assertion on its own.
+
 `storylines[]` in slice.json is optional — present only when the board author explicitly built a walkthrough for this flow. When present, mine it for **additional** tests, on top of (never instead of) the specification tests.
 
 A storyline is `{ id, title, elements: [...] }`, where `elements` is an ordered list of beats — the same element can repeat to show its state at different points in the flow. A storyline embedded in this slice's slice.json already belongs entirely to this slice — no need to match beats against `readmodels[]` by id/title. Scan for a pair of adjacent beats that are both `type: READMODEL`, with only EVENT beat(s) between them and no COMMAND beat in that run. That pair is one self-contained test: