@eventmodelers/cli 2.0.9 → 2.0.11

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
@@ -694,6 +695,7 @@ Flow: `Ready → Planned → InProgress → Waiting → InProgress → Done`. Pr
 - **The platform must know the `Ready` / `Waiting` statuses.**
 - A kit declares what it claims in `lib/kit.json` — `{ "pickupStatus": "Waiting" }`; absent means `Planned`.
 - `run --status-trigger <status>` overrides that pickup status for a single run (e.g. `--status-trigger Ready`); nothing is saved.
+- `run --feature <name>` picks up only the slices that belong to that feature (the names set per slice on the board, matched case-insensitively); without it every slice in the pickup status is built. Slices without a feature wait for a run without the flag. Nothing is saved.
 
 The contract itself is the shared `ui-contract` skill's job (see above); it also owns the rule for which status a slice ends at.
 

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`, {
@@ -3319,7 +3305,7 @@ program
 // dir: a modeling run falls back to the global install (see ensureGlobalKit) rather than
 // requiring one here, and the build-kit branch reports a better-targeted error of its own
 // than this generic gate can.
-const NO_INIT_REQUIRED = new Set(['init', 'scaffold', 'init-templates', 'init-config', 'stacks', 'status', 'config', 'uninstall', 'fetch', 'activate-context', 'set-slice-status', 'release-notes', 'run', 'listen', 'events', 'replay', 'bridge']);
+const NO_INIT_REQUIRED = new Set(['init', 'scaffold', 'init-templates', 'init-config', 'stacks', 'status', 'config', 'uninstall', 'fetch', 'export', 'activate-context', 'set-slice-status', 'release-notes', 'run', 'listen', 'events', 'replay', 'bridge']);
 
 // Commands that install or refresh the kit themselves — a "your kit is outdated" hint in
 // front of them would only be noise.
@@ -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.')
@@ -3830,6 +3816,7 @@ credentialFlags(program
   .option('--browser', 'Give the locked-down modeling agent a browser: the Playwright MCP server (npx @playwright/mcp) next to the eventmodelers one, for discover-storyboard. Off by default because a browser can reach any site, which the lockdown otherwise rules out. Default Claude runner only; --dangerously-skip-permissions already loads every MCP server the machine configures.')
   .option('--handover', 'Backend build kit: for this run only, finish slices that have a UI at `Waiting` instead of `Done` (same as the project setting `handover: true`, which `init --handover` / `config --handover on` save — this flag writes nothing). Without it the project setting applies; without both, slices end at `Done`.')
   .option('--status-trigger <status>', 'Build kit: the slice status the agent picks work up from, for this run only (e.g. Ready, Planned, Waiting). Defaults to the kit\'s own pickup status — `Planned` for backend kits, `Handover` for the UI kits. Nothing is written to disk.')
+  .option('--feature <name>', 'Build kit: only pick up slices that belong to this feature (the free-text names set per slice on the board, matched case-insensitively), for this run only. Other slices wait for a run without it or with their own feature. Nothing is written to disk.')
   .option('--sync', 'Build kit: share this agent\'s event log with the board — events that name a slice are uploaded constantly (POST …/buildlog) for a live dashboard. The platform keeps one iteration per slice, 1000 entries at most. A no-op for --modeling/--standalone, and with --local.')
   .option('--verbose', 'Log every tool call\'s full input (commands, skill args, file paths) and assistant reasoning text. Default is condensed, high-level per-step logging only.')
   .option('--id <id>', 'Pin the agent id this run identifies itself with on the platform. Without it an agent keeps one id: a project install per project, a --global/--standalone run per board and repo (the directory it is started in) — the same agent on every restart, with its chat, its star on the board and the prompts it holds. If another live process already runs under that id, this one gets a fresh id instead (two agents must not share a heartbeat row). Pass --id when a supervisor already knows the id you want, or for a second agent on purpose; it is used as given, with no such check. Per-run only: nothing is written to disk.')
@@ -3902,9 +3889,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
@@ -4122,7 +4107,7 @@ credentialFlags(program
       // path with no stream-json parsing to gate. RALPH_LOCAL is read by ralph.js's startRalph to force
       // the local-only branch even when .eventmodelers/config.json has valid credentials.
       // RALPH_AGENT_ID/RALPH_AGENT_NAME (--id/--name) are read there too.
-      execSync(cmd, { cwd: kitDir, stdio: 'inherit', env: { ...process.env, RALPH_VERBOSE: opts.verbose ? '1' : '', RALPH_SYNC: opts.sync ? '1' : '', RALPH_LOCAL: opts.local ? '1' : '', RALPH_HANDOVER: opts.handover ? '1' : '', RALPH_STATUS_TRIGGER: opts.statusTrigger ? String(opts.statusTrigger).trim() : '', RALPH_AGENT_ID: identity.agentId ?? '', RALPH_AGENT_NAME: identity.agentName ?? '', ...(typeof localAiTarget === 'string' ? { LOCAL_AI_TARGET: localAiTarget } : {}), ...(typeof opts.exec === 'string' ? { RALPH_EXEC_CMD: opts.exec } : {}) } });
+      execSync(cmd, { cwd: kitDir, stdio: 'inherit', env: { ...process.env, RALPH_VERBOSE: opts.verbose ? '1' : '', RALPH_SYNC: opts.sync ? '1' : '', RALPH_LOCAL: opts.local ? '1' : '', RALPH_HANDOVER: opts.handover ? '1' : '', RALPH_STATUS_TRIGGER: opts.statusTrigger ? String(opts.statusTrigger).trim() : '', RALPH_FEATURE: opts.feature ? String(opts.feature).trim() : '', RALPH_AGENT_ID: identity.agentId ?? '', RALPH_AGENT_NAME: identity.agentName ?? '', ...(typeof localAiTarget === 'string' ? { LOCAL_AI_TARGET: localAiTarget } : {}), ...(typeof opts.exec === 'string' ? { RALPH_EXEC_CMD: opts.exec } : {}) } });
     } catch (err) {
       process.exit(err.status || 1);
     }
@@ -4226,6 +4211,139 @@ program
     }
   });
 
+const EXPORT_TYPES = ['eventcatalog'];
+
+program
+  .command('export')
+  .description('Export the event model into another tool\'s format. --type eventcatalog writes an EventCatalog project (domain, flow, events, commands, queries). Reads the board by default; --local reads .slices/ or config.json instead')
+  .requiredOption('--type <type>', `Export target: ${EXPORT_TYPES.join(', ')}`)
+  .option('--context <name>', 'Name or id of the context to export. Omitted (or not found) on the board: pick from the board\'s contexts. Filters --local')
+  .option('--local [path]', 'Read local files instead of the board: ./.slices/, then ./config.json, or the given path')
+  .option('--out <dir>', 'Directory to write into (the catalog root)', '.')
+  .option('--owner <id>', 'Owner (team or user id from the catalog) set on every exported resource; repeat for several', (v, all) => [...all, v], [])
+  .option('--check', 'Compare the model with what the last export wrote and exit 1 if they differ — writes nothing (for CI)')
+  .option('-f, --force', 'Overwrite resources that already exist in the catalog, and re-prompt for credentials when reading the board')
+  .action(async (opts, command) => {
+    if (!EXPORT_TYPES.includes(opts.type)) {
+      console.error(`❌ Unknown export type "${opts.type}". Supported: ${EXPORT_TYPES.join(', ')}`);
+      process.exit(1);
+    }
+    const cwd = process.cwd();
+    const ext = await import('./extensions/eventcatalog/index.js');
+    // Checked first, before any credentials or board access: the export only makes sense inside a catalog.
+    if (!ext.isCatalog(resolve(cwd, opts.out))) {
+      console.error(`❌ ${resolve(cwd, opts.out)} is not an EventCatalog project (no eventcatalog.config.* and no @eventcatalog/core dependency).`);
+      console.error('   Run this inside your catalog, or point --out at it. Create one with: npx @eventcatalog/create-eventcatalog@latest my-catalog --empty');
+      process.exit(1);
+    }
+    let slices;
+    try {
+      if (opts.local) {
+        slices = ext.loadFromLocal({ cwd, local: opts.local, context: opts.context });
+      } else {
+        const kitDir = findInstalledKitDir(cwd);
+        const globalOpts = command.optsWithGlobals();
+        const explicitConfig = globalOpts.config;
+        let cfg = loadEffectiveConfig(cwd, kitDir, explicitConfig).config;
+        const configPath = explicitConfig ? resolve(cwd, explicitConfig) : join(cwd, '.eventmodelers', 'config.json');
+        const requiredFields = ['organizationId', 'boardId', 'token'];
+        const promptForCredentials = async (force = false) => {
+          cfg = await configureCredentials({ config: cfg, configPath, targetDir: cwd, requiredFields, boardIdOptional: false, overrides: {}, print: globalOpts.print, force });
+          if (requiredFields.some((f) => !cfg[f])) {
+            console.error('❌ Still missing token/organizationId/boardId — re-run `eventmodelers export` once configured.');
+            process.exit(1);
+          }
+        };
+        // --force re-asks for credentials, like `init --force` / `init-config --force`.
+        if (opts.force || requiredFields.some((f) => !cfg[f])) await promptForCredentials(opts.force);
+        // A 401/403 re-asks for the token, like `fetch`; any other failure goes to the caller.
+        const withAuthRetry = async (fn) => {
+          try {
+            return await fn();
+          } catch (err) {
+            if (err.status !== 401 && err.status !== 403 && err.status !== 404) throw err;
+            console.error(`❌ ${err.message}`);
+            if (err.status === 404) delete cfg.boardId;
+            else delete cfg.token;
+            await promptForCredentials();
+            return fn();
+          }
+        };
+        const pickContext = async (question) => {
+          const contexts = await withAuthRetry(() => ext.listContexts({ cfg }));
+          if (!contexts.length) throw new Error(`Board ${cfg.boardId} has no contexts with slices.`);
+          return selectPrompt(question, contexts.map((c) => ({ label: `${c.name} (${c.slices} slice${c.slices === 1 ? '' : 's'})`, value: c.name })));
+        };
+        let context = opts.context || (await pickContext('Which context do you want to export?'));
+        try {
+          console.log(`▶ Reading context "${context}" from the board...`);
+          slices = await withAuthRetry(() => ext.loadFromBoard({ cfg, context }));
+        } catch (err) {
+          if (!(err instanceof ext.ContextNotFoundError)) throw err;
+          console.error(`❌ ${err.message}`);
+          context = await pickContext(`No context named "${context}" — pick one of the contexts on this board:`);
+          console.log(`▶ Reading context "${context}" from the board...`);
+          slices = await withAuthRetry(() => ext.loadFromBoard({ cfg, context }));
+        }
+        opts.context = context;
+      }
+    } catch (err) {
+      console.error(`❌ ${err.message}`);
+      process.exit(1);
+    }
+    const outDir = resolve(cwd, opts.out);
+    if (opts.check) {
+      const result = ext.check({ slices, outDir, context: opts.context });
+      if (!result) {
+        console.log('ℹ️  No slices found — nothing to check.');
+        return;
+      }
+      if (result.new.length) console.log(`new (${result.new.length}):\n${result.new.map((l) => `   ${l}`).join('\n')}`);
+      if (result.changed.length) {
+        console.log(`changed (${result.changed.length}):`);
+        for (const { label, changes, renamedFrom } of result.changed) console.log(`   ${label}${renamedFrom ? ` (renamed from ${renamedFrom})` : ''}\n${changes.map((c) => `      ${c}`).join('\n')}`);
+      }
+      if (result.removed.length) console.log(`removed from the model (${result.removed.length}):\n${result.removed.map((l) => `   ${l}`).join('\n')}`);
+      if (result.inSync) {
+        console.log(`✅ "${result.context}" is in sync with the catalog (${result.unchanged.length} resources).`);
+        return;
+      }
+      console.log(`❌ "${result.context}" is out of sync. Run \`eventmodelers export --type eventcatalog --context "${result.context}"\` (add --force to update resources already in the catalog).`);
+      process.exit(1);
+    }
+    // The SDK comes from the catalog, never from this CLI. Missing → offer to install it there.
+    let sdk = await ext.loadSdk(outDir);
+    if (!sdk) {
+      console.log(`@eventcatalog/sdk is not installed in ${outDir}.`);
+      const install = await selectPrompt('Install @eventcatalog/sdk into this catalog now (npm install)?', [
+        { label: 'Yes, run `npm install @eventcatalog/sdk` there', value: true },
+        { label: 'No, cancel the export', value: false },
+      ]);
+      if (!install) {
+        console.error('❌ The export needs @eventcatalog/sdk in the catalog. Install it (npm install @eventcatalog/sdk) and re-run.');
+        process.exit(1);
+      }
+      try {
+        ext.installSdk(outDir);
+        sdk = await ext.loadSdk(outDir);
+      } catch (err) {
+        console.error(`❌ Could not install @eventcatalog/sdk: ${err.message}`);
+        process.exit(1);
+      }
+      if (!sdk) {
+        console.error('❌ @eventcatalog/sdk still cannot be resolved from the catalog after installing.');
+        process.exit(1);
+      }
+    }
+    const { written, skipped, model } = await ext.run({ slices, outDir, context: opts.context, force: opts.force, owners: opts.owner, sdk });
+    if (!model) {
+      console.log('ℹ️  No slices found — nothing exported.');
+      return;
+    }
+    console.log(`✅ Exported "${model.domain.name}" to ${outDir}: ${written.length} files written${skipped.length ? `, ${skipped.length} skipped (already in the catalog; use --force to overwrite)` : ''}.`);
+    for (const f of skipped) console.log(`   skipped ${f}`);
+  });
+
 program
   .command('scaffold <target> [args...]')
   .description('`scaffold add-user <email> <password> [dir]` adds a sign-in user to a scaffolded app (run in its folder, or pass dir). `scaffold re-init [dir]` refreshes every kit the app has (root and web/) from this CLI version — `re-init --stack` for each, the skeleton itself untouched. Otherwise: generate a runnable app skeleton from the board — sign-in, navigation with one entry per timeline, a page shell per screen, 501 for every unbuilt endpoint, hot reload — and install the build kits of the chosen --type into it, ready for `run` to add slices. <target> is an empty or new directory, or a skeleton made earlier (which is refreshed from the current model).')

package/extensions/eventcatalog/README.md

@@ -0,0 +1,23 @@
+# EventCatalog export
+
+```
+eventmodelers export --type eventcatalog [--context <name>] [--local [path]] [--out <dir>] [--owner <id>]... [-f, --force]
+```
+
+Reads the slices of an event model and writes EventCatalog resources into `--out` (default: cwd), using the
+**EventCatalog SDK** (`@eventcatalog/sdk`).
+
+- Source: the board by default (no `--context` → pick from the board's contexts). `--local` reads `./.slices/`, then `./config.json`, or the path you give.
+- The SDK is resolved from the target catalog's `node_modules` — it is not a dependency of this CLI. If the catalog lacks it, the CLI asks before running `npm install @eventcatalog/sdk` there.
+- `--owner <id>` (repeatable) sets `owners` on every resource; the id must be a team or user in the catalog, or the linter flags it.
+- Resources already in the catalog (same id and version) are skipped. `--force` overwrites them, and — reading the board — asks for credentials again.
+
+| Event model | EventCatalog |
+|---|---|
+| context | `domains/<Context>` |
+| chapter | `flows/<Chapter>Flow` (steps ordered by first appearance, edges from dependencies) |
+| events, commands | `events/`, `commands/` with `schema.json` (de-duplicated by title) |
+| read models | `queries/` with `schema.json` |
+| processors, screens | not exported: the event model has no services, so none is imported or created |
+
+`model.js` (slices → model) and `render.js` (model → SDK resources) are pure; `write.js` is the only part that touches the catalog.

package/extensions/eventcatalog/index.js

@@ -0,0 +1,32 @@
+// `eventmodelers export --type eventcatalog` — writes an EventCatalog project's resources
+// (domain, flow, events, commands, queries) from the slices of an event model, through the
+// EventCatalog SDK. Exports run({ slices, outDir, context, force, owners, sdk }).
+
+import { buildModel } from './model.js';
+import { toResources } from './render.js';
+import { writeResources } from './write.js';
+import { diffAgainst, readManifest, snapshotsOf, updateManifest } from './manifest.js';
+
+export { loadFromBoard, loadFromLocal, listContexts, ContextNotFoundError } from './load.js';
+export { loadSdk, installSdk, isCatalog } from './write.js';
+
+// `export --check`: compares the model with what the last export recorded. Writes nothing, needs no SDK.
+export function check({ slices, outDir, context }) {
+  if (!slices.length) return null;
+  const model = buildModel(slices, { context });
+  const diff = diffAgainst(readManifest(outDir), model.domain.name, snapshotsOf(model));
+  return { context: model.domain.name, ...diff, inSync: !diff.new.length && !diff.changed.length && !diff.removed.length };
+}
+
+// `sdk` is the SDK's factory (see loadSdk); the catalog at `outDir` is where it writes.
+export async function run({ slices, outDir, context, force = false, owners = [], sdk }) {
+  if (!slices.length) return { written: [], skipped: [], model: null };
+  const model = buildModel(slices, { context });
+  const resources = toResources(model, { owners });
+  const { written, skipped } = await writeResources(sdk(outDir), resources, { force });
+  // Only what was actually written is recorded: a skipped resource keeps its old snapshot (or none), so
+  // `--check` keeps reporting it until it is really brought up to date.
+  const snapshots = snapshotsOf(model);
+  updateManifest(outDir, model.domain.name, Object.fromEntries(written.map((label) => [label, snapshots[label]])));
+  return { written, skipped, model };
+}

package/extensions/eventcatalog/load.js

@@ -0,0 +1,78 @@
+// Where the slices come from: the board (default) or local files (--local).
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join, resolve } from 'path';
+import { FetchAuthError } from '../../lib/fetch.js';
+
+export class ContextNotFoundError extends Error {}
+
+const DEFAULT_BASE_URL = 'https://api.eventmodelers.ai';
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+const readJson = (p) => JSON.parse(readFileSync(p, 'utf-8'));
+
+// Every context on the board, as the server resolves them — a timeline with no assigned context counts as its own
+// context. Derived from the slice summaries, so contexts without slices do not show up (there is nothing to export).
+export async function listContexts({ cfg }) {
+  const baseUrl = cfg.baseUrl || DEFAULT_BASE_URL;
+  const res = await fetch(`${baseUrl}/api/org/${cfg.organizationId}/boards/${cfg.boardId}/slicedata/slices`, { headers: { 'x-token': cfg.token, 'x-user-id': 'cli-export' } });
+  if (res.status === 401) throw new FetchAuthError(401, 'slicedata/slices: invalid or expired token');
+  if (res.status === 403) throw new FetchAuthError(403, "slicedata/slices: token's organization does not match this board");
+  if (res.status === 404) throw new FetchAuthError(404, `slicedata/slices: board ${cfg.boardId} not found`);
+  if (!res.ok) throw new Error(`slicedata/slices: HTTP ${res.status}`);
+  const counts = new Map();
+  for (const s of (await res.json()).slices ?? []) {
+    const name = s.contextName || 'default';
+    counts.set(name, (counts.get(name) ?? 0) + 1);
+  }
+  return [...counts].map(([name, slices]) => ({ name, slices }));
+}
+
+// Same endpoint `fetch` uses (json format); throws FetchAuthError on 401/403 so the CLI can re-prompt.
+export async function loadFromBoard({ cfg, context }) {
+  if (!context) throw new Error('No context given.');
+  const baseUrl = cfg.baseUrl || DEFAULT_BASE_URL;
+  const query = UUID_RE.test(context) ? `contextId=${encodeURIComponent(context)}` : `contextName=${encodeURIComponent(context)}`;
+  const url = `${baseUrl}/api/org/${cfg.organizationId}/boards/${cfg.boardId}/slicedata?${query}&format=json`;
+  const res = await fetch(url, { headers: { 'x-token': cfg.token, 'x-user-id': 'cli-export' } });
+  if (res.status === 401) throw new FetchAuthError(401, 'slicedata: invalid or expired token');
+  if (res.status === 403) throw new FetchAuthError(403, "slicedata: token's organization does not match this board");
+  if (res.status === 404) {
+    const body = await res.json().catch(() => null);
+    throw new ContextNotFoundError(`slicedata: ${body?.error || `no context or timeline named "${context}"`} (board ${cfg.boardId})`);
+  }
+  if (!res.ok) throw new Error(`slicedata: HTTP ${res.status}`);
+  return (await res.json()).slices ?? [];
+}
+
+// `local` is true (auto-detect) or a path to a config.json, a .slices/ folder, a context folder, or a slice.json.
+// Auto-detect tries ./.slices/ first, then ./config.json.
+export function loadFromLocal({ cwd, local, context }) {
+  const candidates = typeof local === 'string' ? [resolve(cwd, local)] : [join(cwd, '.slices'), join(cwd, 'config.json')];
+  const path = candidates.find((p) => existsSync(p));
+  if (!path) throw new Error(`No local slices found (looked for ${candidates.join(', ')}).`);
+  const slices = statSync(path).isDirectory() ? fromFolder(path) : fromFile(path);
+  const wanted = context?.toLowerCase();
+  return wanted ? slices.filter((s) => (s.context ?? '').toLowerCase() === wanted) : slices;
+}
+
+function fromFile(path) {
+  const data = readJson(path);
+  return Array.isArray(data.slices) ? data.slices : [data];
+}
+
+// A .slices/ folder holds <context>/<slice>/slice.json (and a <context>/config.json dump of the same data).
+function fromFolder(dir) {
+  const slices = [];
+  const walk = (d, depth) => {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, entry.name);
+      if (entry.isDirectory() && depth < 3) walk(p, depth + 1);
+      else if (entry.name === 'slice.json') slices.push(readJson(p));
+    }
+  };
+  walk(dir, 0);
+  // slice.json drops `index`; order from the context's index.json when there is one.
+  slices.forEach((s, i) => { if (s.index === undefined) s.index = i; });
+  return slices;
+}

package/extensions/eventcatalog/manifest.js

@@ -0,0 +1,139 @@
+// What the last export wrote, so `export --check` can tell what moved in the model since — and say what.
+// Only the parts EM-Studio owns are recorded and compared (name, summary from the description, fields,
+// flow steps). Everything else in a catalog resource belongs to the catalog and is never looked at.
+// Kept in the catalog, per context: label ("events/OrderPlaced") → snapshot.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+
+const FILE = join('.eventmodelers', 'eventcatalog-export.json');
+
+const field = (f) => ({
+  name: f.name,
+  type: f.type ?? 'String',
+  cardinality: f.cardinality ?? 'Single',
+  optional: Boolean(f.optional),
+  ...(f.example ? { example: f.example } : {}),
+  ...(f.subfields?.length ? { subfields: f.subfields.map(field) } : {}),
+});
+
+// The summary is only EM-Studio's when the model has a description; otherwise null = "not ours".
+const message = (n) => ({ name: n.name, summary: n.description || null, keys: [...n.elementIds].sort(), fields: n.fields.map(field) });
+
+export function snapshotsOf(model) {
+  const out = {};
+  for (const [folder, list] of [['events', model.events], ['commands', model.commands], ['queries', model.queries]]) {
+    for (const n of list) out[`${folder}/${n.id}`] = message(n);
+  }
+  for (const flow of model.flows) {
+    out[`flows/${flow.id}`] = {
+      name: flow.name,
+      steps: flow.steps.map((s) => ({
+        id: s.id, title: s.node.name, keys: [...s.node.elementIds].sort(),
+        // next carries the target's keys too, so a renamed target is still the same target
+        next: s.next.map((nid) => { const t = flow.steps.find((x) => x.id === nid).node; return { id: nid, keys: [...t.elementIds].sort() }; }),
+      })),
+    };
+  }
+  out[`domains/${model.domain.id}`] = { name: model.domain.name };
+  return out;
+}
+
+export function readManifest(catalogDir) {
+  const path = join(catalogDir, FILE);
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return {}; // unreadable → treated as "nothing exported yet"
+  }
+}
+
+// Merges `snapshots` into the context's entry.
+export function updateManifest(catalogDir, context, snapshots) {
+  const manifest = readManifest(catalogDir);
+  manifest[context] = { resources: { ...(manifest[context]?.resources ?? {}), ...snapshots }, exportedAt: new Date().toISOString() };
+  const path = join(catalogDir, FILE);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(manifest, null, 2) + '\n');
+}
+
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const quote = (s) => (s === null || s === undefined ? '(none)' : `"${s}"`);
+
+function describeFields(before, after, prefix = '') {
+  const lines = [];
+  const was = new Map(before.map((f) => [f.name, f]));
+  const now = new Map(after.map((f) => [f.name, f]));
+  for (const [name, f] of now) {
+    const old = was.get(name);
+    if (!old) { lines.push(`+ field ${prefix}${name} (${f.type}${f.cardinality === 'Single' ? '' : ` ${f.cardinality}`}${f.optional ? ', optional' : ''})`); continue; }
+    const parts = [];
+    if (old.type !== f.type) parts.push(`type ${old.type} → ${f.type}`);
+    if (old.cardinality !== f.cardinality) parts.push(`cardinality ${old.cardinality} → ${f.cardinality}`);
+    if (old.optional !== f.optional) parts.push(f.optional ? 'now optional' : 'now required');
+    if (old.example !== f.example) parts.push(`example ${quote(old.example)} → ${quote(f.example)}`);
+    if (parts.length) lines.push(`~ field ${prefix}${name}: ${parts.join(', ')}`);
+    if (old.subfields || f.subfields) lines.push(...describeFields(old.subfields ?? [], f.subfields ?? [], `${prefix}${name}.`));
+  }
+  for (const name of was.keys()) if (!now.has(name)) lines.push(`- field ${prefix}${name}`);
+  return lines;
+}
+
+// Two entries are the same element when they share a board id; entries without ids (stubs) match by id.
+const matches = (a, b) => (a.keys?.length && b.keys?.length ? a.keys.some((k) => b.keys.includes(k)) : a.id === b.id);
+const nextIds = (list) => list.map((n) => n.id).join(', ') || '(none)';
+
+function describeSteps(before, after) {
+  const lines = [];
+  const used = new Set();
+  for (const s of after) {
+    const old = before.find((b) => !used.has(b) && matches(b, s));
+    if (!old) { lines.push(`+ step ${s.id}`); continue; }
+    used.add(old);
+    if (old.id !== s.id) lines.push(`~ step ${old.id} → ${s.id}`);
+    const oldNext = old.next.map((n) => (typeof n === 'string' ? { id: n } : n));
+    const gone = oldNext.filter((o) => !s.next.some((n) => matches(o, n)));
+    const added = s.next.filter((n) => !oldNext.some((o) => matches(o, n)));
+    if (gone.length || added.length) lines.push(`~ step ${s.id}: next ${nextIds(oldNext)} → ${nextIds(s.next)}`);
+  }
+  for (const b of before) if (!used.has(b)) lines.push(`- step ${b.id}`);
+  return lines;
+}
+
+// The human-readable changes between two snapshots of one resource.
+export function describeChange(before, after) {
+  const lines = [];
+  if (before.name !== after.name) lines.push(`name: ${quote(before.name)} → ${quote(after.name)}`);
+  // A summary only counts when the model has a description (see `message`).
+  if (after.summary !== null && after.summary !== undefined && before.summary !== after.summary) lines.push(`summary: ${quote(before.summary)} → ${quote(after.summary)}`);
+  if (after.fields) lines.push(...describeFields(before.fields ?? [], after.fields));
+  if (after.steps) lines.push(...describeSteps(before.steps ?? [], after.steps));
+  return lines;
+}
+
+// new: not exported yet · changed: [{ label, changes, renamedFrom? }] · removed: exported before, gone from the model.
+// A "new" and a "removed" resource of the same kind that share a board element id are one resource, renamed.
+export function diffAgainst(manifest, context, snapshots) {
+  const before = manifest[context]?.resources ?? {};
+  const result = { new: [], changed: [], removed: [], unchanged: [] };
+  const kind = (label) => label.split('/')[0];
+  const missing = Object.keys(before).filter((label) => !(label in snapshots));
+
+  for (const [label, snap] of Object.entries(snapshots)) {
+    const old = before[label];
+    if (old && typeof old === 'object') {
+      const changes = describeChange(old, snap);
+      if (changes.length) result.changed.push({ label, changes });
+      else result.unchanged.push(label);
+      continue;
+    }
+    const was = snap.keys?.length ? missing.find((m) => kind(m) === kind(label) && before[m]?.keys?.some((k) => snap.keys.includes(k))) : null;
+    if (!was) { result.new.push(label); continue; }
+    missing.splice(missing.indexOf(was), 1);
+    const id = (l) => l.split('/').slice(1).join('/');
+    result.changed.push({ label, renamedFrom: was, changes: [`id: ${id(was)} → ${id(label)}`, ...describeChange(before[was], snap)] });
+  }
+  result.removed = missing;
+  return result;
+}