@eventmodelers/cli 2.0.8 → 2.0.10

package/README.md

@@ -162,7 +162,7 @@ npx @eventmodelers/cli run                          # start the agent loop (ralp
 npx @eventmodelers/cli run --all                      # every build kit in the project at once (this directory and up to two levels below, e.g. a scaffolded app's root and web/), prefixed output, Ctrl+c stops all; other flags (--agent, --handover, …) go to each
 npx @eventmodelers/cli run --all --modeling           # the same, plus a modeling agent running alongside the build kits
 npx @eventmodelers/cli run --local-ai [target]      # board work only via a local/self-hosted model (ralph-local-ai.js) — does NOT build slices; build locally with --exec
-npx @eventmodelers/cli run --agent <name>           # pick the agent: claude (default), opencode, codex, gemini — bare --agent lists them with their exact commands
+npx @eventmodelers/cli run --agent <name>           # pick the agent: claude (default), opencode, codex, gemini, hermes, cursor — bare --agent lists them with their exact commands
 npx @eventmodelers/cli run --agent <name> --model <id>  # …on a given model: -m for opencode/codex/gemini, --model for Claude, LOCAL_AI_MODEL for --local-ai
 npx @eventmodelers/cli run --exec "<command>"        # manual fallback for any other harness (ralph-exec.js) — agent tracing needs its JSON flag, e.g. "codex exec --json --full-auto"
 npx @eventmodelers/cli run --local                  # skip platform config/credential lookup entirely — local-only, no board sync
@@ -243,6 +243,7 @@ registered for it (`opencode.json`, `.gemini/settings.json`, or `-c` flags for C
 npx @eventmodelers/cli run --standalone --agent opencode   # = --exec "opencode run --standalone --auto"
 npx @eventmodelers/cli run --modeling --agent codex        # = --exec "codex exec --full-auto"
 npx @eventmodelers/cli run --modeling --agent gemini       # = --exec "gemini --yolo -p"
+npx @eventmodelers/cli run --modeling --agent cursor       # = --exec "agent -p --output-format text --approve-mcps --force --trust"; creates one Cursor chat and resumes it every turn, so only the first turn reads the kit
 npx @eventmodelers/cli run --modeling --agent claude       # the default, spelled out
 npx @eventmodelers/cli run --worker --agent opencode --model opencode/big-pickle  # pick the model (a free OpenCode Zen one here)
 npx @eventmodelers/cli run --agent                         # list the agents and the command each runs

package/cli.js

@@ -44,6 +44,7 @@ import { prunableEvents, pruneLog, rememberPruneAnswer, shouldOfferPrune } from
 import { fold } from './shared/build-kit/lib/slice-state.js';
 import { filterEvents, baselineIds, formatEvent, formatPayload, sliceTitles, summarize } from './shared/build-kit/lib/events-view.js';
 import { stableGlobalAgentId } from './lib/global-agent-id.js';
+import { AGENT_NAMES, presetCommand, withModel } from './shared/build-kit/lib/harnesses/index.js';
 import { ensureLearningsGitRules } from './shared/build-kit/lib/ralph.js';
 import { createCallTracker, heldPromptsRequest, journalPromptAction, shouldJournalCall, journalPromptFinished, journalPromptReceived, recoverOwnPrompts } from './shared/build-kit/lib/prompt-journal.js';
 import { INFO_KINDS, infoComment, recordInfo, recordTurnInfos } from './shared/build-kit/lib/slice-info.js';
@@ -95,23 +96,13 @@ function resolveLocalAiTarget(opts) {
 // build kit wants the JSON mode, the only one that reports the usage agent tracing records.
 // claude has no command — it is the default runner, named so it can be picked explicitly.
 // --exec stays the fallback for any harness or flag set not listed here.
-const AGENT_PRESETS = {
-  claude: null,
-  // --standalone: a plain `opencode run` hands the turn to opencode's shared background service,
-  // started with some other env — so the MCP header's {env:EVENTMODELERS_TOKEN} resolves to nothing
-  // there and every eventmodelers tool fails to authenticate. A private server inherits ours.
-  opencode: { modeling: 'opencode run --standalone --auto', build: 'opencode run --standalone --auto --format json' },
-  codex: { modeling: 'codex exec --full-auto', build: 'codex exec --json --full-auto' },
-  gemini: { modeling: 'gemini --yolo -p', build: 'gemini --yolo --output-format stream-json -p' },
-  // -q takes the prompt, so the preset ends with it (the --model flag is inserted before it, below).
-  // -Q is the plain-text mode a modeling turn reads its answer from; --format stream-json is the build kit's.
-  hermes: { modeling: 'hermes chat --yolo -Q -q', build: 'hermes chat --yolo --format stream-json -q' },
-};
+// The commands live with their harness, in shared/build-kit/lib/harnesses/<name>.js.
 
 function printAgentPresets() {
   console.log('Supported agents for run --agent <name>:\n');
-  for (const [name, preset] of Object.entries(AGENT_PRESETS)) {
-    console.log(`  ${name.padEnd(9)}${preset ? `modeling: ${preset.modeling}\n  ${''.padEnd(9)}build:    ${preset.build}` : 'the default runner (warm Claude process / ralph-claude.js)'}`);
+  for (const name of AGENT_NAMES) {
+    const modeling = presetCommand(name, 'modeling');
+    console.log(`  ${name.padEnd(9)}${modeling ? `modeling: ${modeling}\n  ${''.padEnd(9)}build:    ${presetCommand(name, 'build')}` : 'the default runner (warm Claude process / ralph-claude.js)'}`);
   }
   console.log('\nAny other harness: run --exec "<command>".');
   console.log(`A local or self-hosted model: run --local-ai [${LOCAL_AI_TARGETS.join('|')}].`);
@@ -126,8 +117,8 @@ function resolveAgentPreset(opts, loop) {
     process.exit(0);
   }
   const name = String(opts.agent).toLowerCase();
-  if (!(name in AGENT_PRESETS)) {
-    console.error(`❌ Unknown --agent "${opts.agent}" — one of: ${Object.keys(AGENT_PRESETS).join(', ')}.`);
+  if (!AGENT_NAMES.includes(name)) {
+    console.error(`❌ Unknown --agent "${opts.agent}" — one of: ${AGENT_NAMES.join(', ')}.`);
     console.error('   Any other harness works via --exec "<command>".');
     console.error(`   A local or self-hosted model works via --local-ai [${LOCAL_AI_TARGETS.join('|')}].`);
     process.exit(1);
@@ -140,13 +131,7 @@ function resolveAgentPreset(opts, loop) {
     console.error('❌ --agent is mutually exclusive with --local-ai — pick one runner.');
     process.exit(1);
   }
-  const cmd = AGENT_PRESETS[name]?.[loop] ?? null;
-  // The docker images set this: Codex's own sandbox (landlock) can't start inside a container, and the
-  // container already is the sandbox — the flag Codex documents for externally sandboxed environments.
-  if (name === 'codex' && cmd && process.env.EVENTMODELERS_CODEX_NO_SANDBOX === '1') {
-    return cmd.replace('--full-auto', '--dangerously-bypass-approvals-and-sandbox');
-  }
-  return cmd;
+  return presetCommand(name, loop);
 }
 
 const STACKS = {
@@ -2167,7 +2152,7 @@ async function runModeling(kitDir, projectDir, { codeDir = null, verbose = false
     if (localRunner) return body;
     // Every exec turn is a fresh process — a new session that has read nothing, so each one gets
     // the header its first turn would.
-    if (!firstTurn && !execRunner) return body;
+    if (!firstTurn && !(execRunner && !execRunner.keepsSession)) return body;
     firstTurn = false;
     return `MODE=modeling token=$EVENTMODELERS_TOKEN org=${cfg.organizationId} baseUrl=${cfg.baseUrl} standalone=${standalone ? 'on' : 'off'}${standalone ? ` max_agents=${maxAgents}` : ''} subagent_model=${subagentModel}\n\n${QUESTIONING_RULE}${execRunner?.mcpRegistered ? EXEC_CONNECTED : ''}Read .agent-modeling-kit/CLAUDE.md now and follow it for every prompt in this session — it's a one-time read; don't re-read it on later turns.\n\n${body}`;
   }
@@ -2414,7 +2399,8 @@ async function runModeling(kitDir, projectDir, { codeDir = null, verbose = false
     if (!standalone) return (warmUp = Promise.resolve());
     log('warm-up: connecting and listing chapters before the first turn (chapters are read on first use)');
     warmingUp = true;
-    warmUp = sendTurn(buildWarmUpTurn())
+    // An exec runner with a session of its own (Cursor's chat) is warmed through that session.
+    warmUp = (execRunner ? execRunner.runTurn(buildWarmUpTurn()) : sendTurn(buildWarmUpTurn()))
       .then((result) => log(`warm-up done — ${oneLine(result, 200) || 'session ready'}`))
       .catch((err) => {
         // Not fatal: put the session header back so the next real turn carries the
@@ -2460,10 +2446,10 @@ async function runModeling(kitDir, projectDir, { codeDir = null, verbose = false
   // Both warm-ups are the same bet — pay the session's fixed setup cost before a turn arrives
   // rather than making whoever sends the first prompt wait for it. For a local model that cost
   // is the MCP tool set; for Claude it is reading CLAUDE.md and running /connect.
-  // An exec runner has nothing to warm: every turn is its own process, so a warm-up would connect
-  // a session that exits right after.
+  // An exec runner without a session has nothing to warm: every turn is its own process, so a warm-up
+  // would connect one that exits right after. One with a session (Cursor's chat) does — the chat outlives the process.
   if (localRunner) localRunner.warmUp().catch((err) => log(`local-ai warm-up failed (the first turn will retry): ${err.message}`));
-  else if (!execRunner) warmUpSession();
+  else if (!execRunner || execRunner.hasSession) warmUpSession();
 
   async function getRealtimeToken() {
     const res = await fetch(`${cfg.baseUrl}/api/org/${cfg.organizationId}/prompts/realtime-token`, {
@@ -3813,8 +3799,8 @@ credentialFlags(program
   .description('Start the agent loop from the installed kit dir — build-kit stacks: ralph-claude.js (default); modeling-kit: --modeling, or --standalone, which needs no install at all')
   .option('--local-ai [target]', `Drive the loop with a local (or self-hosted) model instead of the default Claude runner: a build kit runs it via ralph-local-ai.js, and --modeling/--standalone via lib/modeling-local-ai.js (board tools over MCP, but no skills and no subagent fan-out — those are Claude Code features). Optional target preset picks the URL and wire dialect: ${LOCAL_AI_TARGETS.join(', ')} — bare --local-ai means ollama. Anything OpenAI-compatible (vLLM, LM Studio, llama.cpp, TGI) works by pointing LOCAL_AI_URL at it; see LOCAL_AI_* in the docs. Board work only: --local-ai never builds a Planned slice (no file, shell or git tools). To build code with a local model, use --exec with a coding harness pointed at it, e.g. "codex exec --oss --full-auto". Claude remains the default when this flag is absent.`)
   .addOption(new Option('--bash').hideHelp())
-  .option('--agent [name]', `Pick the agent that does the work by name: ${Object.keys(AGENT_PRESETS).join(', ')}. claude is the default runner; any other is a shortcut for --exec with that harness's headless command filled in — plain-text output for --modeling/--standalone/--worker, JSON output (for agent tracing) for a build kit. Bare --agent lists the agents and the exact command each runs, then stops. Mutually exclusive with --exec and --local-ai.`)
-  .option('--model <id>', 'The model the agent runs on, for this run only: `-m <id>` on the --agent opencode/codex/gemini command (e.g. opencode/big-pickle, gpt-5-codex, gemini-2.5-pro), `--model <id>` for Claude (overriding `model` from config), LOCAL_AI_MODEL for --local-ai. Not with --exec — put the harness\'s own model flag in the command there.')
+  .option('--agent [name]', `Pick the agent that does the work by name: ${AGENT_NAMES.join(', ')}. claude is the default runner; any other is a shortcut for --exec with that harness's headless command filled in — plain-text output for --modeling/--standalone/--worker, JSON output (for agent tracing) for a build kit. Bare --agent lists the agents and the exact command each runs, then stops. Mutually exclusive with --exec and --local-ai.`)
+  .option('--model <id>', 'The model the agent runs on, for this run only: `-m <id>` on the --agent opencode/codex/gemini command (`--model <id>` for cursor) (e.g. opencode/big-pickle, gpt-5-codex, gemini-2.5-pro), `--model <id>` for Claude (overriding `model` from config), LOCAL_AI_MODEL for --local-ai. Not with --exec — put the harness\'s own model flag in the command there.')
   .option('--exec [command]', 'Fallback for any harness --agent does not cover, or other flags than its preset. Hand each prompt to an external agent command instead of the default Claude runner — for agentic harnesses that bring their own tool loop, e.g. "codex exec --full-auto", "gemini --yolo -p" or "opencode run". One process per prompt; the prompt is appended as a quoted argument and also written to the file named by RALPH_PROMPT_FILE. Bare --exec uses localAi.exec from .eventmodelers/config.json. Claude remains the default when this flag is absent. A build kit runs it via ralph-exec.js; there, with agent tracing on, include the harness\'s JSON output flag (codex exec --json, opencode run --format json, gemini --output-format stream-json) — without it no slice cost is recorded. With --modeling/--standalone/--worker it is how any agent takes board prompts and chats: the loop claims each prompt or chat message and runs the command once for it. Keep the harness in its plain-text output mode there — stdout is the turn\'s answer — the eventmodelers MCP server is registered for it on every run (opencode.json, .gemini/settings.json, or -c flags for codex; any other command logs what to register by hand), authenticating with $EVENTMODELERS_TOKEN from the env the command inherits, and `init-agents --hosts <harness>` installs the skills for a harness that does not read .claude/skills. No subagents: self-directed work is done inline.')
   .option('--all', 'Run every build kit in this project at once — the one in this directory and any up to two levels below it (a scaffolded app has `.build-kit` at the root and in `web/`, so this works from the app or from the folder holding it) — each from its own directory, output prefixed with the directory, Ctrl+c stops them all. Every other flag is passed on to each run. Not interactive: the kits\' credentials must already be configured (except with --force, which asks once per kit up front, here, before the runs start). With --modeling, the modeling agent runs alongside the build kits. Not with --standalone, --worker, --global, --local or --id (one id cannot belong to several agents).')
   .option('--modeling', 'Connect a modeling agent to the board: it takes prompts and chat messages and hands each to an AI — by default one Claude process kept warm across prompts, for low-latency voice/live use; --agent (or --local-ai, or --exec as the manual fallback) picks another. Runs from a modeling-kit install in this directory, or from the global install (~/.eventmodelers/kit) when there is none. Built into the CLI, not a per-project file.')
@@ -3902,9 +3888,7 @@ credentialFlags(program
       process.exit(1);
     }
     if (model && agentExec) {
-      const modelFlag = `-m '${model.replace(/'/g, `'\\''`)}'`;
-      // A trailing -q takes the prompt as its value, so the model flag has to come before it.
-      opts.exec = agentExec.endsWith(' -q') ? `${agentExec.slice(0, -3)}${modelFlag} -q` : `${agentExec} ${modelFlag}`;
+      opts.exec = withModel(agentExec, model);
     }
     else if (model && resolveLocalAiTarget(opts) !== null) process.env.LOCAL_AI_MODEL = model;
     // The default Claude runner: the build kit's ralph-claude.js reads RALPH_MODEL from the env it

package/lib/modeling-exec.js

@@ -22,7 +22,7 @@ import { mkdtempSync, writeFileSync } from 'fs';
 import { tmpdir } from 'os';
 import { join } from 'path';
 import { turnTimeoutMs, superviseTurn } from '../shared/build-kit/lib/turn.js';
-import { shellQuote, harnessOf, registerMcp } from '../shared/build-kit/lib/mcp-register.js';
+import { shellQuote, harnessOf, harnessFor, registerMcp } from '../shared/build-kit/lib/harnesses/index.js';
 
 export { harnessOf, registerMcp };
 
@@ -31,6 +31,19 @@ export function createModelingExecRunner({ cfg, command: rawCommand, projectDir,
     throw new Error('no agent command — pass one, e.g. --exec "codex exec --full-auto", or persist it as localAi.exec in .eventmodelers/config.json');
   }
   const { command, registered: mcpRegistered } = registerMcp(rawCommand, projectDir, cfg.baseUrl, log);
+  // A harness with a session of its own (Cursor's chat) keeps what it read across turns: the process
+  // is still one per turn, but its turns share that session — see harnesses/cursor.js. Such a
+  // harness takes its turns one at a time (two turns resuming one session would race on it) and
+  // the kit preamble is only skipped once a turn has completed in it.
+  const session = harnessFor(rawCommand)?.session ?? null;
+  let sessionId = null;
+  let primed = false;
+  let queue = Promise.resolve();
+  function withSession(cmd) {
+    if (!session) return cmd;
+    if (sessionId === null) sessionId = session.start(cmd, { cwd: projectDir, env, log });
+    return sessionId ? session.resume(cmd, sessionId) : cmd;
+  }
   const timeoutMs = turnTimeoutMs(cfg);
   const promptDir = mkdtempSync(join(tmpdir(), 'modeling-exec-'));
   const env = {
@@ -42,6 +55,13 @@ export function createModelingExecRunner({ cfg, command: rawCommand, projectDir,
   };
 
   function runTurn(text) {
+    if (!session) return runTurnNow(text);
+    const result = queue.then(() => runTurnNow(text));
+    queue = result.catch(() => {});
+    return result;
+  }
+
+  function runTurnNow(text) {
     return new Promise((resolveTurn, rejectTurn) => {
       const promptFile = join(promptDir, 'prompt.md');
       writeFileSync(promptFile, text);
@@ -49,7 +69,7 @@ export function createModelingExecRunner({ cfg, command: rawCommand, projectDir,
       // stdin ignored: some harnesses append a piped stdin to the prompt, and nobody is there to
       // type into it. stdout is echoed as it comes — the harness owns its output format, there is
       // no cross-harness stream to condense — and kept as the turn's result.
-      const proc = spawn(`${command} ${shellQuote(text)}`, {
+      const proc = spawn(`${withSession(command)} ${shellQuote(text)}`, {
         cwd: projectDir,
         stdio: ['ignore', 'pipe', 'inherit'],
         shell: true,
@@ -65,6 +85,7 @@ export function createModelingExecRunner({ cfg, command: rawCommand, projectDir,
         const timeout = turn.timeoutError();
         if (timeout) return rejectTurn(timeout);
         if (code !== 0) return rejectTurn(new Error(`exec command exited ${code}`));
+        if (sessionId) primed = true;
         log(`done (${Date.now() - startedAt}ms)`);
         resolveTurn(out.trim());
       });
@@ -74,9 +95,11 @@ export function createModelingExecRunner({ cfg, command: rawCommand, projectDir,
 
   return {
     runTurn,
-    // Nothing to warm: every turn is its own process.
-    warmUp: async () => {},
+    // Only a harness with a session has anything to warm (the loop sends its warm-up turn through runTurn).
+    hasSession: Boolean(session),
     describe: () => rawCommand,
     mcpRegistered,
+    // True once a turn has succeeded in the shared session — until then every turn still carries the preamble.
+    get keepsSession() { return primed; },
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "2.0.8",
+  "version": "2.0.10",
   "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/harnesses/codex.js

@@ -0,0 +1,25 @@
+// OpenAI Codex CLI (`codex exec`).
+
+import { shellQuote } from './util.js';
+
+export default {
+  name: 'codex',
+  matches: (words) => words.slice(0, 3).some((w) => w.split('/').pop().replace(/@.*$/, '') === 'codex'),
+  preset(loop, env = process.env) {
+    const p = { modeling: 'codex exec --full-auto', build: 'codex exec --json --full-auto' };
+    // The docker images set this: Codex's own sandbox (landlock) can't start inside a container, and the
+    // container already is the sandbox — the flag Codex documents for externally sandboxed environments.
+    if (env.EVENTMODELERS_CODEX_NO_SANDBOX === '1') {
+      return { modeling: p.modeling.replace('--full-auto', '--dangerously-bypass-approvals-and-sandbox'), build: p.build.replace('--full-auto', '--dangerously-bypass-approvals-and-sandbox') };
+    }
+    return p;
+  },
+
+  // Codex only loads a project config for a trusted project, so the server rides on the command as flags.
+  registerMcp: (command, _projectDir, url) => ({
+    // -c values are TOML; env_http_headers names the env var each header is read from.
+    command: `${command} -c ${shellQuote(`mcp_servers.eventmodelers.url="${url}"`)} -c ${shellQuote('mcp_servers.eventmodelers.env_http_headers={x-token="EVENTMODELERS_TOKEN",x-agent-id="EVENTMODELERS_AGENT_ID"}')}`,
+    file: null,
+    manual: null,
+  }),
+};

package/shared/build-kit/lib/harnesses/cursor.js

@@ -0,0 +1,62 @@
+// Cursor's CLI (`cursor-agent`, or plain `agent` on current installs).
+//
+// The one harness with a session of its own. The CLI takes one prompt per process, but it can keep
+// a chat across runs: `create-chat` once, `--resume <id>` on every turn. The process is still new
+// each turn; what carries over is the conversation — the kit's CLAUDE.md and the MCP tool set it
+// has already read — so only the first turn pays for them.
+
+import { execFileSync, spawnSync } from 'child_process';
+import { join } from 'path';
+import { mergeJsonConfig } from './util.js';
+
+const binName = (word) => word.split('/').pop().replace(/@.*$/, '');
+
+// Whichever Cursor binary is on PATH; with neither, `cursor-agent` so the failure names a real binary.
+export function cursorBinary() {
+  for (const bin of ['cursor-agent', 'agent']) {
+    try { execFileSync('which', [bin], { stdio: 'ignore' }); return bin; } catch {}
+  }
+  return 'cursor-agent';
+}
+
+export default {
+  name: 'cursor',
+  // `agent` is far too generic a word to match anywhere but first.
+  matches: (words) => binName(words[0]) === 'agent' || words.slice(0, 3).some((w) => ['cursor-agent', 'cursor'].includes(binName(w))),
+  preset() {
+    const bin = cursorBinary();
+    return {
+      modeling: `${bin} -p --output-format text --approve-mcps --force --trust`,
+      build: `${bin} -p --output-format stream-json --approve-mcps --force --trust`,
+    };
+  },
+  modelFlag: '--model', // `-m` is an unknown option to this CLI
+
+  // The same project .cursor/mcp.json the editor reads; ${env:NAME} is resolved from the env the
+  // runner hands it. --approve-mcps in the command is what lets a headless run load it unprompted.
+  registerMcp(command, projectDir, url) {
+    const entry = { url, headers: { 'x-token': '${env:EVENTMODELERS_TOKEN}', 'x-agent-id': '${env:EVENTMODELERS_AGENT_ID}' } };
+    const ok = mergeJsonConfig(join(projectDir, '.cursor', 'mcp.json'), (config) => {
+      config.mcpServers = config.mcpServers || {};
+      config.mcpServers.eventmodelers = entry;
+    });
+    return { command, file: ok ? '.cursor/mcp.json' : null, manual: ok ? null : `add mcpServers.eventmodelers = ${JSON.stringify(entry)} to .cursor/mcp.json` };
+  },
+
+  // Turns share one chat. start() makes it (returns its id, or '' when it could not); resume() puts
+  // it on a command — right after the binary, ahead of the flags and the prompt.
+  session: {
+    start(command, { cwd, env, log }) {
+      const bin = command.trim().split(/\s+/)[0];
+      const r = spawnSync(bin, ['create-chat'], { cwd, encoding: 'utf8', env });
+      const id = String(r.stdout || '').trim().split(/\s+/).pop();
+      if (r.status !== 0 || !id) {
+        log(`cursor: could not create a chat (${String(r.stderr || '').trim() || `exit ${r.status}`}) — running without resume, every turn starts cold`);
+        return '';
+      }
+      log(`cursor: resuming chat ${id} on every turn`);
+      return id;
+    },
+    resume: (command, id) => command.replace(/^(\s*\S+)/, `$1 --resume ${id}`),
+  },
+};

package/shared/build-kit/lib/harnesses/gemini.js

@@ -0,0 +1,19 @@
+// Gemini CLI (`gemini -p`).
+
+import { join } from 'path';
+import { mergeJsonConfig } from './util.js';
+
+export default {
+  name: 'gemini',
+  matches: (words) => words.slice(0, 3).some((w) => w.split('/').pop().replace(/@.*$/, '') === 'gemini'),
+  preset: () => ({ modeling: 'gemini --yolo -p', build: 'gemini --yolo --output-format stream-json -p' }),
+
+  registerMcp(command, projectDir, url) {
+    const entry = { httpUrl: url, headers: { 'x-token': '$EVENTMODELERS_TOKEN', 'x-agent-id': '$EVENTMODELERS_AGENT_ID' } };
+    const ok = mergeJsonConfig(join(projectDir, '.gemini', 'settings.json'), (config) => {
+      config.mcpServers = config.mcpServers || {};
+      config.mcpServers.eventmodelers = entry;
+    });
+    return { command, file: ok ? '.gemini/settings.json' : null, manual: ok ? null : `add mcpServers.eventmodelers = ${JSON.stringify(entry)} to .gemini/settings.json` };
+  },
+};

package/shared/build-kit/lib/harnesses/hermes.js

@@ -0,0 +1,28 @@
+// Hermes (`hermes chat`).
+
+import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+export default {
+  name: 'hermes',
+  matches: (words) => words.slice(0, 3).some((w) => w.split('/').pop().replace(/@.*$/, '') === 'hermes'),
+  // -q takes the prompt, so the preset ends with it (the --model flag is inserted before it, see withModel).
+  // -Q is the plain-text mode a modeling turn reads its answer from; --format stream-json is the build kit's.
+  preset: () => ({ modeling: 'hermes chat --yolo -Q -q', build: 'hermes chat --yolo --format stream-json -q' }),
+  withModel: (command, flag) => (command.endsWith(' -q') ? `${command.slice(0, -3)} ${flag} -q` : `${command} ${flag}`),
+
+  // Hermes reads MCP servers from ~/.hermes/config.yaml only (there is no project-level file), so
+  // this never writes it — a user-wide file is not ours to rewrite. It reports the server as
+  // registered when the file already names it (the docker images ship it), and says what to add otherwise.
+  registerMcp(command, _projectDir, url) {
+    const file = join(process.env.HERMES_HOME || join(homedir(), '.hermes'), 'config.yaml');
+    const has = existsSync(file) && /^\s+eventmodelers:/m.test(readFileSync(file, 'utf8'));
+    return {
+      command,
+      file: null,
+      reason: '', // not a JSON file — there is nothing to say about its format
+      manual: has ? null : `add to ${file}:\nmcp_servers:\n  eventmodelers:\n    url: "${url}"\n    headers:\n      x-token: "\${EVENTMODELERS_TOKEN}"`,
+    };
+  },
+};

package/shared/build-kit/lib/harnesses/index.js

@@ -0,0 +1,66 @@
+// The agent harnesses `run --exec` / `run --agent` can hand a turn to, one module each — everything
+// a harness needs (its headless command, how to recognise it, how the eventmodelers MCP server gets
+// registered with it, its model flag, any session of its own) lives in its file. Claude is not here:
+// it has a dedicated runner. Adding a harness is one module and one line in HARNESSES.
+//
+// A module exports: name, matches(words), preset(loop?) -> {modeling, build}, registerMcp(command,
+// projectDir, url) -> {command, file, manual, reason?}, and optionally modelFlag (default `-m`),
+// withModel(command, flag) and session {start, resume}.
+
+import opencode from './opencode.js';
+import codex from './codex.js';
+import gemini from './gemini.js';
+import hermes from './hermes.js';
+import cursor from './cursor.js';
+import { shellQuote } from './util.js';
+
+export { shellQuote };
+export { opencodeSupportsStandalone, setOpencodeStandaloneSupport } from './opencode.js';
+
+const HARNESSES = [opencode, codex, gemini, hermes, cursor];
+
+// Every name `--agent` takes, claude (the default runner, no command) first.
+export const AGENT_NAMES = ['claude', ...HARNESSES.map((h) => h.name)];
+
+export function harnessByName(name) {
+  return HARNESSES.find((h) => h.name === name) ?? null;
+}
+
+// Which known harness a command runs — the first words naming one, so `npx @openai/codex exec`
+// and `/opt/bin/opencode run` are recognised as well as the bare names.
+export function harnessFor(command) {
+  const words = String(command).trim().split(/\s+/);
+  return HARNESSES.find((h) => h.matches(words)) ?? null;
+}
+
+export function harnessOf(command) {
+  return harnessFor(command)?.name ?? null;
+}
+
+// The headless command --agent <name> stands for, for the `modeling` or `build` loop.
+export function presetCommand(name, loop) {
+  return harnessByName(name)?.preset(loop)[loop] ?? null;
+}
+
+// `--model <id>` on a preset command, spelled the way that harness wants it.
+export function withModel(command, id) {
+  const h = harnessFor(command);
+  const flag = `${h?.modelFlag ?? '-m'} ${shellQuote(id)}`;
+  return h?.withModel ? h.withModel(command, flag) : `${command} ${flag}`;
+}
+
+// Registers the MCP server for the command's harness. Returns the command to run with it, and
+// whether the server is now registered — false for an unknown command or a config it could not
+// update, where the turn still has to connect the way the kit says to.
+export function registerMcp(command, projectDir, baseUrl, log) {
+  const url = `${baseUrl}/mcp`;
+  const harness = harnessFor(command);
+  if (!harness) {
+    log(`MCP: unknown agent command — register the eventmodelers MCP server with it yourself: ${url}, header x-token from $EVENTMODELERS_TOKEN (and x-agent-id from $EVENTMODELERS_AGENT_ID)`);
+    return { command, registered: false };
+  }
+  const reg = harness.registerMcp(command, projectDir, url);
+  if (reg.manual) log(`MCP: could not update the ${harness.name} config${reg.reason ?? ' (not plain JSON)'} — ${reg.manual}`);
+  else log(`MCP: eventmodelers registered for ${harness.name}${reg.file ? ` in ${reg.file}` : ' via -c flags'}`);
+  return { command: reg.command, registered: !reg.manual };
+}

package/shared/build-kit/lib/harnesses/opencode.js

@@ -0,0 +1,51 @@
+// OpenCode (`opencode run`).
+
+import { spawnSync } from 'child_process';
+import { join } from 'path';
+import { mergeJsonConfig } from './util.js';
+
+// Older OpenCode releases have no `run --standalone`; passing it makes `opencode run` print its
+// usage and exit 1, so every turn fails. Ask the installed binary once. Overridable for tests.
+let standaloneSupported = null;
+export function opencodeSupportsStandalone() {
+  if (standaloneSupported === null) {
+    const r = spawnSync('opencode', ['run', '--help'], { encoding: 'utf8' });
+    standaloneSupported = /--standalone\b/.test(`${r.stdout || ''}${r.stderr || ''}`);
+  }
+  return standaloneSupported;
+}
+export function setOpencodeStandaloneSupport(value) { standaloneSupported = value; }
+
+export default {
+  name: 'opencode',
+  matches: (words) => words.slice(0, 3).some((w) => binName(w) === 'opencode'),
+  // --standalone: a plain `opencode run` hands the turn to opencode's shared background service,
+  // started with some other env — so the MCP header's {env:EVENTMODELERS_TOKEN} resolves to nothing
+  // there and every eventmodelers tool fails to authenticate. A private server inherits ours.
+  preset: () => ({ modeling: 'opencode run --standalone --auto', build: 'opencode run --standalone --auto --format json' }),
+
+  registerMcp(command, projectDir, url) {
+    const entry = {
+      type: 'remote',
+      url,
+      headers: { 'x-token': '{env:EVENTMODELERS_TOKEN}', 'x-agent-id': '{env:EVENTMODELERS_AGENT_ID}' },
+    };
+    const ok = mergeJsonConfig(join(projectDir, 'opencode.json'), (config) => {
+      // OpenCode 2 nests servers under mcp.servers and still reads the older flat mcp.<name>;
+      // follow whichever form the file already uses.
+      config.mcp = config.mcp || {};
+      if (config.mcp.servers) config.mcp.servers.eventmodelers = entry;
+      else config.mcp.eventmodelers = entry;
+    });
+    // A plain `opencode run` hands the turn to opencode's shared background service, which was
+    // started with some other env: {env:EVENTMODELERS_TOKEN} resolves to nothing there and the
+    // server refuses every call. --standalone runs a private server that inherits this one's env.
+    // A binary without the flag runs the turn in-process already, so the flag is dropped, not added.
+    const supported = opencodeSupportsStandalone();
+    const standalone = !supported ? command.replace(/\s--standalone\b/, '')
+      : /\s--(standalone|server)\b/.test(` ${command}`) ? command : `${command} --standalone`;
+    return { command: standalone, file: ok ? 'opencode.json' : null, manual: ok ? null : `add mcp.eventmodelers = ${JSON.stringify(entry)} to opencode.json` };
+  },
+};
+
+function binName(word) { return word.split('/').pop().replace(/@.*$/, ''); }

package/shared/build-kit/lib/harnesses/util.js

@@ -0,0 +1,24 @@
+// Helpers the harness modules share.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+
+// POSIX single-quote escaping: close, insert an escaped quote, reopen. A turn is multi-line
+// text with backticks and $ in it, so it cannot go in unquoted.
+export function shellQuote(s) {
+  return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+// Adds or refreshes one key in a project JSON config, leaving everything else in it alone. A file
+// that isn't plain JSON (a JSONC one with comments) is not rewritten — returns false instead, and
+// the caller says what to add by hand.
+export function mergeJsonConfig(path, apply) {
+  let config = {};
+  if (existsSync(path)) {
+    try { config = JSON.parse(readFileSync(path, 'utf8')); } catch { return false; }
+  }
+  apply(config);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
+  return true;
+}

package/shared/build-kit/lib/mcp-register.js

@@ -1,125 +1,5 @@
-// Registers the eventmodelers MCP server with an external agent harness (OpenCode, Gemini, Codex, Hermes),
-// for both loops that hand turns to one: the modeling loop (lib/modeling-exec.js) and the build
-// loop (ralph-exec.js).
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
-import { spawnSync } from 'child_process';
-import { homedir } from 'os';
-import { dirname, join } from 'path';
-
-// POSIX single-quote escaping: close, insert an escaped quote, reopen. A turn is multi-line
-// text with backticks and $ in it, so it cannot go in unquoted.
-export function shellQuote(s) {
-  return `'${String(s).replace(/'/g, `'\\''`)}'`;
-}
-
-// Older OpenCode releases have no `run --standalone`; passing it makes `opencode run` print its
-// usage and exit 1, so every turn fails. Ask the installed binary once. Overridable for tests.
-let standaloneSupported = null;
-export function opencodeSupportsStandalone() {
-  if (standaloneSupported === null) {
-    const r = spawnSync('opencode', ['run', '--help'], { encoding: 'utf8' });
-    standaloneSupported = /--standalone\b/.test(`${r.stdout || ''}${r.stderr || ''}`);
-  }
-  return standaloneSupported;
-}
-export function setOpencodeStandaloneSupport(value) { standaloneSupported = value; }
-
-// Adds or refreshes one key in a project JSON config, leaving everything else in it alone. A file
-// that isn't plain JSON (a JSONC one with comments) is not rewritten — returns false instead, and
-// the caller says what to add by hand.
-function mergeJsonConfig(path, apply) {
-  let config = {};
-  if (existsSync(path)) {
-    try { config = JSON.parse(readFileSync(path, 'utf8')); } catch { return false; }
-  }
-  apply(config);
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
-  return true;
-}
-
-// How each known harness learns about the eventmodelers MCP server — the --exec counterpart of
-// ensureMcpRegistered's `.mcp.json` for Claude, and like it rewritten every run, always into the
-// harness's *project* config in the agent's working dir (never a user-wide one), and always with
-// the token as an env reference the harness resolves from the env this runner hands it, never its
-// value. Each entry returns the command to run, which is where a harness without a usable project
-// config (Codex only loads one for a trusted project) takes the server as flags instead. Adding a
-// harness is one entry here.
-const MCP_REGISTRATIONS = {
-  opencode: (command, projectDir, url) => {
-    const entry = {
-      type: 'remote',
-      url,
-      headers: { 'x-token': '{env:EVENTMODELERS_TOKEN}', 'x-agent-id': '{env:EVENTMODELERS_AGENT_ID}' },
-    };
-    const ok = mergeJsonConfig(join(projectDir, 'opencode.json'), (config) => {
-      // OpenCode 2 nests servers under mcp.servers and still reads the older flat mcp.<name>;
-      // follow whichever form the file already uses.
-      config.mcp = config.mcp || {};
-      if (config.mcp.servers) config.mcp.servers.eventmodelers = entry;
-      else config.mcp.eventmodelers = entry;
-    });
-    // A plain `opencode run` hands the turn to opencode's shared background service, which was
-    // started with some other env: {env:EVENTMODELERS_TOKEN} resolves to nothing there and the
-    // server refuses every call. --standalone runs a private server that inherits this one's env.
-    // A binary without the flag runs the turn in-process already, so the flag is dropped, not added.
-    const supported = opencodeSupportsStandalone();
-    const standalone = !supported ? command.replace(/\s--standalone\b/, '')
-      : /\s--(standalone|server)\b/.test(` ${command}`) ? command : `${command} --standalone`;
-    return { command: standalone, file: ok ? 'opencode.json' : null, manual: ok ? null : `add mcp.eventmodelers = ${JSON.stringify(entry)} to opencode.json` };
-  },
-  gemini: (command, projectDir, url) => {
-    const entry = { httpUrl: url, headers: { 'x-token': '$EVENTMODELERS_TOKEN', 'x-agent-id': '$EVENTMODELERS_AGENT_ID' } };
-    const ok = mergeJsonConfig(join(projectDir, '.gemini', 'settings.json'), (config) => {
-      config.mcpServers = config.mcpServers || {};
-      config.mcpServers.eventmodelers = entry;
-    });
-    return { command, file: ok ? '.gemini/settings.json' : null, manual: ok ? null : `add mcpServers.eventmodelers = ${JSON.stringify(entry)} to .gemini/settings.json` };
-  },
-  // Hermes reads MCP servers from ~/.hermes/config.yaml only (there is no project-level file), so
-  // this never writes it — a user-wide file is not ours to rewrite. It reports the server as
-  // registered when the file already names it (the docker images ship it), and says what to add otherwise.
-  hermes: (command, _projectDir, url) => {
-    const file = join(process.env.HERMES_HOME || join(homedir(), '.hermes'), 'config.yaml');
-    const has = existsSync(file) && /^\s+eventmodelers:/m.test(readFileSync(file, 'utf8'));
-    return {
-      command,
-      file: null,
-      manual: has ? null : `add to ${file}:\nmcp_servers:\n  eventmodelers:\n    url: "${url}"\n    headers:\n      x-token: "\${EVENTMODELERS_TOKEN}"`,
-    };
-  },
-  codex: (command, _projectDir, url) => ({
-    // -c values are TOML; env_http_headers names the env var each header is read from.
-    command: `${command} -c ${shellQuote(`mcp_servers.eventmodelers.url="${url}"`)} -c ${shellQuote('mcp_servers.eventmodelers.env_http_headers={x-token="EVENTMODELERS_TOKEN",x-agent-id="EVENTMODELERS_AGENT_ID"}')}`,
-    file: null,
-    manual: null,
-  }),
-};
-
-// Which known harness a command runs — the first word naming one, so `npx @openai/codex exec`
-// and `/opt/bin/opencode run` are recognised as well as the bare names.
-export function harnessOf(command) {
-  for (const word of String(command).trim().split(/\s+/).slice(0, 3)) {
-    const name = word.split('/').pop().replace(/@.*$/, '');
-    if (MCP_REGISTRATIONS[name]) return name;
-  }
-  return null;
-}
-
-// Registers the MCP server for the command's harness. Returns the command to run with it, and
-// whether the server is now registered — false for an unknown command or a config it could not
-// update, where the turn still has to connect the way the kit says to.
-export function registerMcp(command, projectDir, baseUrl, log) {
-  const url = `${baseUrl}/mcp`;
-  const harness = harnessOf(command);
-  if (!harness) {
-    log(`MCP: unknown agent command — register the eventmodelers MCP server with it yourself: ${url}, header x-token from $EVENTMODELERS_TOKEN (and x-agent-id from $EVENTMODELERS_AGENT_ID)`);
-    return { command, registered: false };
-  }
-  const reg = MCP_REGISTRATIONS[harness](command, projectDir, url);
-  if (reg.manual) log(`MCP: could not update the ${harness} config${harness === 'hermes' ? '' : ' (not plain JSON)'} — ${reg.manual}`);
-  else log(`MCP: eventmodelers registered for ${harness}${reg.file ? ` in ${reg.file}` : ' via -c flags'}`);
-  return { command: reg.command, registered: !reg.manual };
-}
+// Registers the eventmodelers MCP server with an external agent harness. The per-harness logic
+// lives in ./harnesses/<name>.js; this module is the stable import for both loops that hand turns
+// to one: the modeling loop (lib/modeling-exec.js) and the build loop (ralph-exec.js).
 
+export { shellQuote, harnessOf, registerMcp, opencodeSupportsStandalone, setOpencodeStandaloneSupport } from './harnesses/index.js';

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

@@ -70,7 +70,7 @@ Write tools take their items as an array (`nodeIds[]`, `elements[]`, `connection
 | `get_image_snapshot_description` | `boardId`, `nodeId` | Load the `{elements:[...]}` sketch description from storage | — (reads what §4 sketch endpoints write) |
 | `validate_slice_data` | `sliceData` | Offline validation of a `SliceDataOutput` payload — no board access | — (MCP-only, pure function) |
 | `commit_board_to_git` | `boardId` | Force a git-extension commit/push, bypassing the autoCommit gate | — (MCP-only; git extension) |
-| `update_prompt_status` | `promptId`, `newStatus`, `comment?` | Update a prompt's lifecycle status (`ADDED`/`CLAIMED`/`IN_PROGRESS`/`DONE`), optionally with a progress comment. Not board-scoped — no `boardId` arg; the prompt's board is resolved server-side. | §14 `POST .../prompts/:id/status` |
+| `update_prompt_status` | `promptId`, `newStatus`, `comment?` | Update a prompt's lifecycle status (`ADDED`/`CLAIMED`/`IN_PROGRESS`/`DONE`/`FAILED`), optionally with a progress comment. Not board-scoped — no `boardId` arg; the prompt's board is resolved server-side. | §14 `POST .../prompts/:id/status` |
 
 **Not exposed via MCP at all** — always use REST/curl for these: §7 Config Import, §10 Snapshots, §11–12 Invitations, §13 Utility (`/api/user`, swagger), and the rest of §14 Prompts (submission, claiming, deletion, realtime-token) — only the status-update endpoint has an MCP tool (`update_prompt_status`, used by the `update-prompt-status` skill); everything else in Prompts is an intentionally separate lifecycle the board-content MCP server doesn't otherwise own.
 
@@ -1013,7 +1013,7 @@ OpenAPI specification (JSON)
 
 **File**: `src/slices/change/api-prompts/routes.ts`
 
-Prompts are how a human submits work to a modeling agent from the board UI, and how that agent reports its lifecycle back onto the board. Every prompt row has a `status`: `ADDED` (submitted, default) → `CLAIMED` (an agent has picked it up) → `IN_PROGRESS` (an agent is actively working it) → `DONE` (finished). See the `update-prompt-status` skill for the agent-side half of this lifecycle.
+Prompts are how a human submits work to a modeling agent from the board UI, and how that agent reports its lifecycle back onto the board. Every prompt row has a `status`: `ADDED` (submitted, default) → `CLAIMED` (an agent has picked it up) → `IN_PROGRESS` (an agent is actively working it) → `DONE` (finished) or `FAILED` (not resolved, whether nothing or only part of it could be done — the board keeps the agent task, red, instead of fading it out). See the `update-prompt-status` skill for the agent-side half of this lifecycle.
 
 ### POST `/api/org/:orgId/prompts`
 Submit a prompt for a board timeline. Auth: Supabase JWT (`Authorization: Bearer`).

package/stacks/modeling-kit/templates/.claude/skills/update-prompt-status/SKILL.md

@@ -30,7 +30,8 @@ Valid `newStatus` values (case-sensitive):
 | `ADDED` | Default — submitted, not yet claimed. You should never need to set this yourself. |
 | `CLAIMED` | Already set automatically when `/api/org/:orgId/prompts/next` hands you the prompt — you should never need to set this yourself either. |
 | `IN_PROGRESS` | You have started working on this prompt. |
-| `DONE` | You have finished working on this prompt. |
+| `DONE` | You have finished working on this prompt and it is resolved. |
+| `FAILED` | The prompt is not resolved: you could not do it at all (nothing changed on the board), or only part of it, because it was ambiguous, blocked, or the work did not succeed. The board shows the task red and keeps it instead of fading it out like a `DONE` one. Always give a `comment` saying what is unresolved. |
 
 If `newStatus` is not one of these exact values, stop and tell the user the valid options.
 

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

@@ -103,7 +103,7 @@ attribute names, `get_node` `projection: "cells"` for a grid and `"edges"` for o
 `get_slice_data` `projection: "outline"` / `"fields"` / `"specs"` instead of the full graph unless the step needs
 elements, specs and comments together. The decision table is in `learn-eventmodelers-api` → *Which read to use*.
 
-**Every prompt gets exactly two `/update-prompt-status` calls per turn — never zero, never one.** `IN_PROGRESS` before you start the work (step 4), `DONE` after you finish it (step 6). This holds even for a prompt that turns out to be trivial or a no-op — the board UI has no other way to know the agent picked it up and finished it.
+**Every prompt gets exactly two `/update-prompt-status` calls per turn — never zero, never one.** `IN_PROGRESS` before you start the work (step 4), `DONE` (or `FAILED` if it could not be resolved) after you finish it (step 6). This holds even for a prompt that turns out to be trivial or a no-op — the board UI has no other way to know the agent picked it up and finished it.
 
 ## Per-turn steps
 
@@ -147,8 +147,8 @@ mention it in the `DONE` comment, and leave it for a self-directed turn (or for
 
    **Questioning rule**: you are running autonomously — no human is available to answer questions. (A `CHAT` turn never reaches this rule: there someone *is* waiting, and you ask back in the chat — see "Chat turns".) If you need clarification, do not pause or ask interactively — post a comment (`/handle-comment` with `action=place`, `type=COMMENT`) on the most relevant node. Then:
    - If a reasonable default interpretation exists, continue with it.
-   - If it doesn't — the prompt is ambiguous enough that any guess risks doing the wrong thing — stop instead of guessing. Skip straight to step 6 and mark the prompt `DONE` with a comment explaining what's unclear and pointing to the comment you just posted. Never leave a prompt neither progressed nor closed.
-6. **Mark the prompt as finished** — invoke `/update-prompt-status` with this turn's `prompt_id`, `newStatus=DONE`, and a `comment` that summarizes what you actually did (e.g. "Added the OrderPlaced event and wired it to the read model"). Do this once, right after the work is done — not per skill call within the turn.
+   - If it doesn't — the prompt is ambiguous enough that any guess risks doing the wrong thing — stop instead of guessing. Skip straight to step 6 and mark the prompt `FAILED` with a comment explaining what's unclear and pointing to the comment you just posted. Never leave a prompt neither progressed nor closed.
+6. **Mark the prompt as finished** — invoke `/update-prompt-status` with this turn's `prompt_id`, `newStatus=DONE`, and a `comment` that summarizes what you actually did (e.g. "Added the OrderPlaced event and wired it to the read model"). If the prompt was not resolved (you could not do it at all, stopped on an ambiguity, hit an error you could not fix, or only part of it was done), use `newStatus=FAILED` instead, with a `comment` saying what is unresolved — a `DONE` prompt disappears from the board, a `FAILED` one stays visible in red. Do this once, right after the work is done — not per skill call within the turn.
 7. If this turn has a `comment_id` field, invoke `/handle-comment` with `action=resolve`, `nodeId` from the resolved `NODE_ID` (step 3), `commentId` from `comment_id`.
 8. **`standalone=off` only** — if you noticed something reusable this turn (a pattern, a gotcha, useful context about this model), end your reply with one line per learning: `Learning [<topic>]: <one terse line>` (the topic is optional, at most five lines). The CLI records them — never write them into a file yourself, and add nothing that is already in `.agent-modeling-kit/AGENTS.md`. In a `standalone=on` session skip this: that session writes no files (see Mode), so note anything worth keeping as a board comment instead.
    **In every session, `standalone=on` too:** anything that is *not* a reusable learning — something you could not change and why, a decision you took — goes the same way as `Info [limitation|decision|note]: <one terse line>` (at most five lines). The CLI records each as an event; never leave it only in prose.