@eventmodelers/cli 2.0.1 → 2.0.3

package/cli.js

@@ -20,6 +20,10 @@ import { createInterface, emitKeypressEvents, moveCursor, clearScreenDown } from
 import { homedir, tmpdir } from 'os';
 import { randomUUID } from 'crypto';
 import { runFetch, FetchAuthError } from './lib/fetch.js';
+import { SCAFFOLD_TYPES, scaffoldTypeNames, missingPrerequisites, runScaffold, builtInTemplates, initTemplates } from './lib/scaffold.js';
+import { supervise } from './lib/supervise.js';
+import { findBuildKitDirs } from './lib/build-kits.js';
+import { buildModel } from './lib/scaffold-model.js';
 import { createModelingLocalAiRunner } from './lib/modeling-local-ai.js';
 import { run as runSpecKittyAdapter } from './lib/adapters/spec-kitty-adapter.js';
 import { latestPublishedVersion, updateHints } from './lib/update-check.js';
@@ -31,16 +35,18 @@ import { modelingPermissions } from './lib/agent-permissions.js';
 // shared/build-kit/lib/adapters/realtime-adapter.js for why it lives there instead.
 import { createRealtimeAdapter, keepSubscribed } from './shared/build-kit/lib/adapters/realtime-adapter.js';
 import { recordAgentStatus } from './shared/build-kit/lib/slice-run.js';
+import { findSliceDir, fingerprint, readBaseline, writeBaseline, compare } from './lib/ui-baseline.js';
 import { defaultAgentName, withInstanceSuffix } from './shared/build-kit/lib/agent-name.js';
 import { acquireAgentId } from './shared/build-kit/lib/agent-lock.js';
 import { readEvents } from './shared/build-kit/lib/slice-events.js';
 import { findPromptEvent, replayRequest } from './shared/build-kit/lib/prompt-replay.js';
 import { prunableEvents, pruneLog, rememberPruneAnswer, shouldOfferPrune } from './shared/build-kit/lib/event-prune.js';
 import { fold } from './shared/build-kit/lib/slice-state.js';
-import { filterEvents, formatEvent, formatPayload, sliceTitles, summarize } from './shared/build-kit/lib/events-view.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 { 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';
 import { listLearnings, mergeLearnings, recordLearning, recordTurnLearnings, retractLearning, syncLearnings } from './shared/build-kit/lib/slice-learnings.js';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -463,6 +469,30 @@ function getSharedRl() {
   return sharedRl;
 }
 
+// --force on a build kit: the credentials step of `init-config` against the project-root config the
+// runner reads. Interactive, so under `run --all` the parent runs it for each kit one after the other —
+// the supervised children have no stdin to ask on. `shared` (another kit's answer) is applied
+// instead of asking, so every kit of one run ends up on the same credentials.
+async function forceBuildKitCredentials(kitDir, cwd, opts, globalOpts, shared = null) {
+  const projectDir = dirname(kitDir);
+  const configPath = globalOpts.config
+    ? resolve(projectDir, globalOpts.config)
+    : join(projectDir, '.eventmodelers', 'config.json');
+  const cfg = await configureCredentials({
+    config: loadEffectiveConfig(cwd, kitDir, globalOpts.config).config,
+    configPath,
+    targetDir: projectDir,
+    requiredFields: ['organizationId', 'boardId', 'token'],
+    overrides: shared ?? credentialOverridesFromOpts(opts),
+    print: false,
+    force: !shared,
+  });
+  ensureMcpRegistered(projectDir, cfg.baseUrl || DEFAULT_BASE_URL);
+  ensureEnvToken(projectDir, cfg.token);
+  ensureMcpEnabled(projectDir);
+  return cfg;
+}
+
 // Pulls one line from the shared readline's own async iterator rather than calling
 // its `.question()` — `.question()` attaches a one-shot 'line' listener *after* the
 // prompt is issued, but when stdin is piped (a file, `<<<`, scripted/CI input) readline
@@ -2652,15 +2682,18 @@ async function runModeling(kitDir, projectDir, { codeDir = null, verbose = false
         try {
           turnPromptId = p.id;
           const reply = await runTurn(buildTurn(p));
-          // The agent cannot run `learn` (locked-down Bash), so it states learnings in its reply and they are recorded here.
-          // Best effort: a failed write never takes the prompt queue down.
-          if (keepsRecord) {
-            try {
+          // The agent cannot run `learn` or `info` (locked-down Bash), so it states them in its reply and they are recorded here.
+          // Best effort: a failed write never takes the prompt queue down. Infos are events stamped with their board, so every
+          // run records them — standalone included; learnings are kept only where `keepsRecord` (they feed AGENTS.md).
+          try {
+            if (keepsRecord) {
               const n = recordTurnLearnings({ kitDir, reply, meta: journalMeta });
               if (n) log(`recorded ${n} learning${n === 1 ? '' : 's'} from the turn`);
-            } catch (err) {
-              log(`could not record the turn's learnings: ${err.message}`);
             }
+            const infos = recordTurnInfos({ kitDir, reply, meta: journalMeta });
+            if (infos) log(`recorded ${infos} info event${infos === 1 ? '' : 's'} from the turn`);
+          } catch (err) {
+            log(`could not record the turn's learnings or infos: ${err.message}`);
           }
           journal(() => journalPromptFinished({ kitDir, id: p.id, outcome: 'worked', meta: journalMeta }));
         } catch (err) {
@@ -3286,11 +3319,11 @@ 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', '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', '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.
-const NO_KIT_UPDATE_HINT = new Set(['init', 're-init', 'uninstall']);
+const NO_KIT_UPDATE_HINT = new Set(['init', 'scaffold', 'init-templates', 're-init', 'uninstall']);
 
 // Retired: still recognised, so an old script or muscle memory gets an explanation instead of "unknown option".
 // The hidden options and the `bridge` command exist only to say so; they do nothing else.
@@ -3372,13 +3405,13 @@ const AGENT_NAME_OPTION = [
 ];
 
 // `--handover` is the project policy for how a backend build kit finishes a slice with a UI:
-// set, it ends STATE_VIEW / STATE_CHANGE slices at `Handover` (the UI kit builds the rest and sets
+// set, it ends STATE_VIEW / STATE_CHANGE slices at `Waiting` (the UI kit builds the rest and sets
 // `Done`); unset, it ends at `Done`, exactly as before. Persisted as `handover: true` in the project's
 // config.json — the `ui-contract` skill (Step 4) reads it there. Switch it later with
 // `eventmodelers config --handover on|off`.
 const HANDOVER_OPTION = [
   '--handover',
-  'Backend build kit: finish slices that have a UI at status `Handover` (UI build kit takes over, then sets `Done`) instead of `Done`. Saved as `handover: true` in .eventmodelers/config.json; without it slices end at `Done`. Turn it off later with `eventmodelers config --handover off`.',
+  'Backend build kit: finish slices that have a UI at status `Waiting` (UI build kit takes over, then sets `Done`) instead of `Done`. Saved as `handover: true` in .eventmodelers/config.json; without it slices end at `Done`. Turn it off later with `eventmodelers config --handover off`.',
 ];
 
 function identityOverridesFromOpts(opts) {
@@ -3783,6 +3816,7 @@ credentialFlags(program
   .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('--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.')
   .option('-f, --force', 'Ask for credentials again before the modeling loop starts, even when a config already has everything required. With a modeling kit in this directory it re-runs the same prompt as `init --modeling`, overwriting the project\'s .eventmodelers/config.json; with the global install it drops the "keep the stored credentials" choice, so a board\'s credentials have to be answered afresh. Applies to build-kit runs too, where it re-asks against the project\'s .eventmodelers/config.json. Cannot be combined with --non-interactive, --print or --local.')
   .option('--non-interactive', 'Never ask anything: take the board and credentials that resolve from flags, EVENTMODELERS_* env vars and the config files, and fail with the reason if they are incomplete instead of interviewing for them. A TTY was previously the only signal — right for CI or a supervisor, wrong for a loop started from a terminal, where stdin is a TTY nobody is watching and the run stops on a question. Only affects the modeling loop (--modeling/--standalone/--worker/--global).')
@@ -3794,8 +3828,9 @@ credentialFlags(program
   .option('--local', 'Skip platform config/credential lookup entirely and run the local-only loop (no board sync, no realtime agent) — even if .eventmodelers/config.json has credentials (build-kit stacks only)')
   .option('--dangerously-skip-permissions', 'Run the modeling agent\'s Claude process with --dangerously-skip-permissions, as before the lockdown: every tool call is approved — any shell command, curl to anywhere, any file the user can read or write, every MCP server the machine configures. Off by default because the agent takes chat messages and snippet clicks from any collaborator on the board; pass it only for a board whose collaborators you trust with your shell. Default Claude runner of --modeling/--standalone/--worker/--global only — not with --agent, --exec or --local-ai, which bring their own permission flags.')
   .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 `Handover` 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, Handover). Defaults to the kit\'s own pickup status — `Planned` for backend kits, `Handover` for the UI kits. Nothing is written to disk.')
+  .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('--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.')
   .option('--name <name>', 'A human-readable name for this agent, sent with every heartbeat so the board shows which agent is live rather than a bare uuid (e.g. "ci-builder", "martins-laptop"). Per-run only, like --id: the persistent name is `agentName` in config.json (set via `init --name` / `init-config --name`), and this overrides it for one run without writing anything.')
@@ -3803,6 +3838,49 @@ credentialFlags(program
   .action(async (opts, command) => {
     const globalOpts = command.optsWithGlobals();
     const cwd = process.cwd();
+    if (opts.all) {
+      const clashing = [['--standalone', opts.standalone], ['--worker', opts.worker], ['--global', opts.global], ['--local', opts.local], ['--id', opts.id !== undefined]]
+        .filter(([, set]) => set).map(([flag]) => flag);
+      if (clashing.length) {
+        console.error(`❌ --all runs build kits and cannot be combined with ${clashing.join(', ')}.`);
+        process.exit(1);
+      }
+      const kitDirNames = [...new Set(Object.values(STACKS).map((st) => st.kitDirName))];
+      const dirs = findBuildKitDirs(cwd, kitDirNames);
+      if (!dirs.length && !opts.modeling) {
+        console.error(`❌ No build kit found in this directory or up to two levels below it (looked for ${kitDirNames.join(', ')}).`);
+        process.exit(1);
+      }
+      // Each kit runs as its own `run` with whatever else was typed; only --all is dropped, and
+      // --modeling too — that one is its own run, below, not something a build kit takes.
+      // --force is the one flag that asks questions, and the children have no terminal to ask on
+      // (the supervisor pipes their stdin, so the first prompt dies with ERR_USE_AFTER_CLOSE). The
+      // credentials step runs here once per kit instead, then --force is not forwarded.
+      if (opts.force) {
+        if (opts.nonInteractive || globalOpts.print) {
+          console.error('❌ --force asks for credentials again, which --non-interactive/--print rule out — pick one.');
+          process.exit(1);
+        }
+        // Asked once, for the kit in this directory (the first one found when there is none), and
+        // handed to the others — the modeling agent reads this directory's config.
+        const rootDir = dirs.find((dir) => dirname(dir) === cwd) ?? dirs[0];
+        console.log(`\n🔑 Credentials for ${relative(cwd, rootDir) || '.'}, shared by all`);
+        const { organizationId, boardId, token, baseUrl } = await forceBuildKitCredentials(rootDir, cwd, opts, globalOpts);
+        for (const dir of dirs.filter((d) => d !== rootDir)) {
+          await forceBuildKitCredentials(dir, cwd, opts, globalOpts, { organizationId, boardId, token, baseUrl });
+        }
+        if (sharedRl) sharedRl.close();
+        console.log('');
+      }
+      const forwarded = process.argv.slice(2).filter((a) => a !== '--all' && a !== '--modeling' && !(opts.force && a === '--force'));
+      const cliJs = join(__dirname, 'cli.js');
+      const specs = dirs.map((dir) => ({ name: relative(cwd, dir) || '.', file: process.execPath, args: [cliJs, ...forwarded], cwd: dir }));
+      // --modeling adds the modeling agent next to the build kits: one process, from this directory
+      // (its modeling kit, or the global install when there is none), like a plain `run --modeling`.
+      if (opts.modeling) specs.push({ name: 'modeling', file: process.execPath, args: [cliJs, ...forwarded, '--modeling'], cwd });
+      console.log(`▶ Running ${dirs.length} build kit(s)${opts.modeling ? ' + the modeling agent' : ''}: ${specs.map((sp) => sp.name).join(', ')} (Ctrl+c stops all)\n`);
+      process.exit(await supervise(specs));
+    }
     // Validated up front, before any runner is selected: a cost guard given as garbage
     // should fail on the spot, not once the loop is already up — and a cap passed where
     // nothing will read it is worth saying out loud rather than ignoring silently.
@@ -3876,6 +3954,7 @@ credentialFlags(program
     // no meaning for a build kit, which is scaffolded per project by definition.
     if (opts.modeling || opts.standalone || opts.worker || opts.global) {
       const picked = opts.modeling ? '--modeling' : opts.standalone ? '--standalone' : opts.worker ? '--worker' : '--global';
+      if (opts.sync) console.log(`ℹ️  --sync shares a build agent's log — it does nothing with ${picked}.`);
       // --local-ai and --exec name what does a turn, not a queue, and the modeling loop has its own
       // runner for each (lib/modeling-local-ai.js, lib/modeling-exec.js).
       const modelingLocalAi = resolveLocalAiTarget(opts);
@@ -4019,22 +4098,7 @@ credentialFlags(program
         console.error('❌ --force asks for credentials, which --local (no platform config) never uses — pick one.');
         process.exit(1);
       }
-      const projectDir = dirname(kitDir);
-      const configPath = globalOpts.config
-        ? resolve(projectDir, globalOpts.config)
-        : join(projectDir, '.eventmodelers', 'config.json');
-      const cfg = await configureCredentials({
-        config: loadEffectiveConfig(cwd, kitDir, globalOpts.config).config,
-        configPath,
-        targetDir: projectDir,
-        requiredFields: ['organizationId', 'boardId', 'token'],
-        overrides: credentialOverridesFromOpts(opts),
-        print: false,
-        force: true,
-      });
-      ensureMcpRegistered(projectDir, cfg.baseUrl || DEFAULT_BASE_URL);
-      ensureEnvToken(projectDir, cfg.token);
-      ensureMcpEnabled(projectDir);
+      await forceBuildKitCredentials(kitDir, cwd, opts, globalOpts);
     }
 
     // ralph-claude.js hands every turn to a `claude` that only discovers MCP servers from
@@ -4056,7 +4120,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_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_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);
     }
@@ -4160,6 +4224,162 @@ program
     }
   });
 
+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). 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).')
+  .option('--type <name>', `Kind of app to scaffold (${scaffoldTypeNames().join(', ')})`, 'supabase')
+  .option('--no-install', 'Stop after generating the skeleton: no npm install, checks or commit')
+  .option('--no-check', 'Install dependencies but skip the type-check, tests and web build/lint')
+  .option('--templates <dir>', 'Folder of *.tmpl files that replace the built-in skeleton template of the same path (or add files). Default: the target\'s own templates/ folder when it exists, so customisations survive a refresh')
+  .option('--port <name=value>', "Pin one of the type's ports instead of picking a free one, e.g. --port api=3200 (repeatable; the names are listed in the error when one is unknown). A refresh keeps its ports unless pinned here", (v, all) => [...all, v], [])
+  .action(async (target, args, opts, command) => {
+    if (target === 'add-user') {
+      const [email, password, dir] = args;
+      if (!email || !password) {
+        console.error('❌ usage: eventmodelers scaffold add-user <email> <password> [dir]');
+        process.exit(1);
+      }
+      const addUser = SCAFFOLD_TYPES[opts.type]?.addUser;
+      if (!addUser) {
+        console.log(`ℹ️  The "${opts.type}" scaffold has no users — nothing to do.`);
+        return;
+      }
+      const appDir = resolve(process.cwd(), dir ?? '.');
+      if (!existsSync(join(appDir, addUser.requires))) {
+        console.error(`❌ ${appDir} is not a scaffolded "${opts.type}" app (no ${addUser.requires}) — run this in its folder or pass the folder as the last argument.`);
+        process.exit(1);
+      }
+      const [file, ...fileArgs] = addUser.command(email, password);
+      try {
+        execFileSync(file, fileArgs, { cwd: appDir, stdio: 'inherit' });
+      } catch {
+        process.exit(1);
+      }
+      return;
+    }
+    if (args.length) {
+      console.error(`❌ Unexpected argument(s): ${args.join(' ')}`);
+      process.exit(1);
+    }
+    const type = SCAFFOLD_TYPES[opts.type];
+    if (!type) {
+      console.error(`❌ Unknown --type "${opts.type}". Available: ${scaffoldTypeNames().join(', ')}`);
+      process.exit(1);
+    }
+    const missing = missingPrerequisites(type);
+    if (missing.length) {
+      console.error(`❌ Missing on this machine:\n${missing.map((m) => `   - ${m}`).join('\n')}`);
+      process.exit(1);
+    }
+
+    const cwd = process.cwd();
+    const globalOpts = command.optsWithGlobals();
+    let cfg = loadEffectiveConfig(cwd, findInstalledKitDir(cwd), globalOpts.config).config;
+    const explicit = Object.fromEntries(Object.entries(credentialOverridesFromOpts(opts)).filter(([, v]) => v));
+    cfg = { ...cfg, ...explicit };
+    const configPath = globalOpts.config ? resolve(cwd, globalOpts.config) : join(cwd, '.eventmodelers', 'config.json');
+    const requiredFields = ['organizationId', 'boardId', 'token'];
+    const promptForCredentials = async () => {
+      cfg = await configureCredentials({ config: cfg, configPath, targetDir: cwd, requiredFields, boardIdOptional: false, overrides: {}, print: globalOpts.print });
+      if (requiredFields.some((f) => !cfg[f])) {
+        console.error('❌ Still missing token/organizationId/boardId — re-run `eventmodelers scaffold` once configured.');
+        process.exit(1);
+      }
+    };
+    if (requiredFields.some((f) => !cfg[f])) await promptForCredentials();
+
+    const readModel = async () => {
+      const baseUrl = cfg.baseUrl || 'https://api.eventmodelers.ai';
+      const headers = { 'x-token': cfg.token, 'x-user-id': 'cli-scaffold', 'content-type': 'application/json' };
+      const call = async (url, what, init) => {
+        const res = await fetch(url, { headers, ...init }).catch((err) => {
+          console.error(`❌ Request failed (${what}): ${err.message}`);
+          process.exit(1);
+        });
+        if (res.status === 401 || res.status === 403) throw new FetchAuthError(res.status, `${what}: ${res.status === 401 ? 'invalid or expired token' : "token's organization does not match this board"}`);
+        if (!res.ok) {
+          console.error(`❌ ${what}: HTTP ${res.status}`);
+          process.exit(1);
+        }
+        return res.json();
+      };
+      const boardBase = `${baseUrl}/api/org/${cfg.organizationId}/boards/${cfg.boardId}`;
+      const boards = await call(`${baseUrl}/api/boards`, 'boards').catch((err) => { if (err instanceof FetchAuthError) throw err; return []; });
+      const board = (Array.isArray(boards) ? boards : boards.boards ?? []).find((b) => b.id === cfg.boardId);
+      return buildModel({
+        appTitle: board?.name ?? board?.title,
+        api: {
+          get: (path) => call(`${boardBase}${path}`, path.split('?')[0]),
+          post: (path, body) => call(`${boardBase}${path}`, path, { method: 'POST', body: JSON.stringify(body) }),
+        },
+      });
+    };
+
+    console.log(`▶ Reading the model of board ${cfg.boardId}...`);
+    let model;
+    try {
+      model = await readModel();
+    } catch (err) {
+      if (!(err instanceof FetchAuthError)) throw err;
+      console.error(`❌ ${err.message}`);
+      if (err.status === 404) delete cfg.boardId;
+      else delete cfg.token;
+      await promptForCredentials();
+      model = await readModel();
+    }
+    console.log(`  ${model.timelines.length} timeline(s), ${model.slices.length} slice(s), ${model.screens.length} screen(s), css: ${model.css}`);
+
+    try {
+      const { root, ports } = await runScaffold({
+        typeName: opts.type,
+        target,
+        cfg,
+        model,
+        cliPath: join(__dirname, 'cli.js'),
+        install: opts.install,
+        check: opts.check,
+        templates: opts.templates ? resolve(cwd, opts.templates) : undefined,
+        ports: Object.fromEntries(opts.port.map((kv) => kv.split(/=(.*)/s).slice(0, 2))),
+      });
+      console.log(`\n✅ Skeleton ready in ${root}`);
+      console.log(`   cd ${relative(cwd, root) || '.'} && npm run up        # ${Object.entries(ports).map(([n, v]) => `${n} :${v}`).join(', ')}`);
+      console.log('   npx @eventmodelers/cli scaffold add-user <email> <password>   # a user to sign in with (no sign-up screen)');
+      console.log('   npx @eventmodelers/cli run --all   # then build: every kit in the project, in this terminal');
+    } catch (err) {
+      console.error(`❌ ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('init-templates [paths...]')
+  .description('Copy the built-in scaffold templates into ./templates/ (or --dir) so you can edit them: `scaffold` uses a template found there and falls back to the built-in one for everything else. Name paths (a file like web/src/app/Layout.tsx, or a folder like web/src/app) to copy only those — a copied template no longer follows the CLI\'s own updates, so take only what you mean to change. Existing files are kept unless --force.')
+  .option('--type <name>', `Scaffold type whose templates to copy (${scaffoldTypeNames().join(', ')})`, 'supabase')
+  .option('--dir <dir>', 'Where to copy them', 'templates')
+  .option('--list', 'Only list the built-in template paths')
+  .option('-f, --force', 'Overwrite templates already in the folder')
+  .action((paths, opts) => {
+    const type = SCAFFOLD_TYPES[opts.type];
+    if (!type) {
+      console.error(`❌ Unknown --type "${opts.type}". Available: ${scaffoldTypeNames().join(', ')}`);
+      process.exit(1);
+    }
+    if (opts.list) {
+      for (const rel of builtInTemplates(type).keys()) console.log(rel);
+      return;
+    }
+    try {
+      const dest = resolve(process.cwd(), opts.dir);
+      const { copied, kept } = initTemplates(type, dest, { only: paths, force: opts.force });
+      for (const rel of copied) console.log(`  ✓ ${relative(process.cwd(), join(dest, `${rel}.tmpl`))}`);
+      if (kept.length) console.log(`  ${kept.length} already there, kept (use --force to overwrite)`);
+      console.log(`\n✅ ${copied.length} template(s) copied. Edit them, then run \`eventmodelers scaffold <dir>\` — it uses ${relative(process.cwd(), dest) || '.'}/ when that is the target's templates/ folder, or pass --templates.`);
+    } catch (err) {
+      console.error(`❌ ${err.message}`);
+      process.exit(1);
+    }
+  });
+
 program
   .command('activate-context')
   .description('Choose which fetched context is active — writes .slices/current_context.json, which `run` works through first; once it has no planned slices left, `run` moves on to the next context that does')
@@ -4217,7 +4437,7 @@ const SLICE_STATUSES = [
   { label: '🚫 Blocked', value: 'Blocked' },
   { label: '🧭 Ready', value: 'Ready' },
   { label: '📅 Planned', value: 'Planned' },
-  { label: '🤝 Handover', value: 'Handover' },
+  { label: '🤝 Waiting', value: 'Waiting' },
   { label: 'ℹ️ Informational', value: 'Informational' },
 ];
 
@@ -4394,11 +4614,13 @@ function agentEventMeta(cwd, kitDir, command) {
 
 program
   .command('slice-status <status>')
-  .description("For a build agent: record the outcome of the slice the run loop is building (Done, Handover, Blocked, ...). The loop owns the slice's status on the board and pushes it when the build ends — never edit index.json or call update-slice-status for a loop build.")
+  .description("For a build agent: record the outcome of the slice the run loop is building (Done, Waiting, Blocked, ...). The loop owns the slice's status on the board and pushes it when the build ends — never edit index.json or call update-slice-status for a loop build.")
   .option('--slice <idOrTitle>', 'The slice, when the loop has claimed more than one (default: the one it is building)')
   .action((status, opts, command) => {
     const cwd = process.cwd();
-    const canonical = SLICE_STATUSES.find((s) => s.value.toLowerCase() === status.toLowerCase())?.value;
+    // `Handover` is the old name of `Waiting`; older skills and prompts still say it
+    const wanted = status.toLowerCase() === 'handover' ? 'waiting' : status.toLowerCase();
+    const canonical = SLICE_STATUSES.find((s) => s.value.toLowerCase() === wanted)?.value;
     if (!canonical) {
       console.error(`❌ "${status}" is not a slice status. Valid: ${SLICE_STATUSES.map((s) => s.value).join(', ')}`);
       process.exit(1);
@@ -4414,6 +4636,79 @@ program
     }
   });
 
+program
+  .command('ui-baseline <action>')
+  .alias('build-baseline')
+  .description("For a build agent: decide whether a slice's UI needs work. `check` compares the board's hashes of the slice's screen and of every element of the slice and its codeGen.uiPrompts with what was recorded after the last UI build and prints NO_BASELINE, UNCHANGED or CHANGED (UNCHANGED = skip all UI work). `record` stores the current state once the UI is built — commit the resulting ui-baseline.json with the slice.")
+  .option('--slice <idOrTitle>', 'The slice (default: the one the run loop has claimed)')
+  .option('--scope <scope>', 'ui (default): screen, elements and UI prompts · backend: elements only, for a kit that builds no UI', 'ui')
+  .action(async (action, opts, command) => {
+    if (!['ui', 'backend'].includes(opts.scope)) {
+      console.error('❌ --scope must be `ui` or `backend`.');
+      process.exit(1);
+    }
+    if (!['check', 'record'].includes(action)) {
+      console.error('❌ Action must be `check` or `record`.');
+      process.exit(1);
+    }
+    const cwd = process.cwd();
+    const kitDir = requireBuildKitDir(cwd);
+    let wanted = opts.slice;
+    if (!wanted) {
+      const claimed = Object.entries(fold(readEvents(kitDir)).slices).filter(([, s]) => s.claim);
+      if (claimed.length !== 1) {
+        console.error(`❌ ${claimed.length ? `${claimed.length} slices are claimed` : 'No slice is claimed by the run loop'} — name the slice with --slice.`);
+        process.exit(1);
+      }
+      wanted = claimed[0][0];
+    }
+    const found = findSliceDir(kitDir, wanted);
+    if (!found) {
+      console.error(`❌ Slice "${wanted}" not found under ${relative(cwd, join(kitDir, '.slices'))}.`);
+      process.exit(1);
+    }
+    const globalOpts = command.optsWithGlobals();
+    const cfg = loadEffectiveConfig(cwd, kitDir, globalOpts.config).config;
+    const fetchNodes = async (ids) => {
+      if (['organizationId', 'boardId', 'token'].some((f) => !cfg[f])) throw new Error('token/organizationId/boardId are not configured (.eventmodelers/config.json)');
+      const res = await fetch(`${cfg.baseUrl || DEFAULT_BASE_URL}/api/org/${cfg.organizationId}/boards/${cfg.boardId}/nodes/query`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'x-token': cfg.token, 'x-user-id': 'cli-ui-baseline', ...agentHeaders(cfg) },
+        body: JSON.stringify({ ids }),
+      });
+      if (!res.ok) throw new Error(`board returned HTTP ${res.status}`);
+      return res.json();
+    };
+    let fp;
+    try {
+      fp = await fingerprint({ slice: found.slice, fetchNodes, scope: opts.scope });
+    } catch (err) {
+      // Cannot tell — the safe answer is the full check, never a skip.
+      console.log('UNKNOWN');
+      console.log(`Could not read the screen from the board (${err.message}) — do the full screen diff.`);
+      return;
+    }
+    if (action === 'record') {
+      writeBaseline(found.path, fp, opts.scope);
+      console.log(`✅ Recorded the ${opts.scope === 'backend' ? 'build' : 'UI'} baseline for "${found.slice.title}" (${relative(cwd, join(found.path, 'ui-baseline.json'))}) — commit it with the slice.`);
+      return;
+    }
+    const result = compare(readBaseline(found.path), fp, opts.scope);
+    console.log(result.verdict);
+    if (result.verdict === 'UNCHANGED') {
+      console.log('Screen, elements and UI prompts are as of the last UI build — skip all UI work.');
+      return;
+    }
+    if (result.verdict === 'NO_BASELINE') console.log('No UI build recorded for this slice yet — do one full screen diff, apply every UI prompt, then `ui-baseline record`.');
+    const nodeLine = (label, list) => (list.length ? `\n  ${label}: ${list.map((n) => `${n.title} (${n.kind === 'screen' ? 'screen' : n.kind.replace(/s$/, '')})`).join(', ')}` : '');
+    const nodeDetail = nodeLine('changed', result.changedNodes) + nodeLine('added', result.addedNodes) + nodeLine('removed', result.removedNodes);
+    if (nodeDetail) console.log(`Since the last recorded build:${nodeDetail}\nWork on exactly these; leave what matches alone.`);
+    if (result.screenChanged && result.verdict === 'CHANGED') console.log('SCREEN_CHANGED: re-fetch the screen node, diff the components against it and adjust the UI.');
+    if (result.elementsChanged && result.verdict === 'CHANGED') console.log('ELEMENTS_CHANGED: an element of the slice (command, event, read model, processor, table, actor, aggregate, specification, ...) changed on the board — diff slice.json against the code field by field.');
+    if (result.promptsChanged) console.log(`PROMPTS_CHANGED: apply ${result.newPrompts.length ? 'these new/changed UI prompts' : 'the UI prompts (they were edited or removed — re-read them)'}:${result.newPrompts.map((p) => `\n  - ${p.trim()}`).join('')}`);
+    console.log('When the UI is done, run `ui-baseline record`.');
+  });
+
 program
   .command('learn [text]')
   .description("For a build agent: record one reusable learning (a codebase pattern, a gotcha, a command that works or doesn't, what a failed approach tried and why it failed). .build-kit/AGENTS.md is generated from the recorded learnings — never edit it by hand. --retract withdraws a wrong or obsolete one (ids: `learnings --ids`).")
@@ -4451,6 +4746,42 @@ program
     }
   });
 
+program
+  .command('info <text>')
+  .description("For a build agent: record something that is not a reusable learning — what you cannot change and why (limitation), a decision you took, a note. It is an event in the log and a comment on the slice. Reusable knowledge about the codebase or model is a `learn`, not an info.")
+  .option('--kind <kind>', `${INFO_KINDS.join(' · ')} (default note)`, 'note')
+  .option('--slice <idOrTitle>', 'The slice it is about (default: the one the run loop has claimed)')
+  .option('--tag <tag>', 'Label the info (repeatable)', (tag, tags) => [...tags, tag], [])
+  .action(async (text, opts, command) => {
+    const cwd = process.cwd();
+    const kitDir = requireBuildKitDir(cwd);
+    const meta = agentEventMeta(cwd, kitDir, command);
+    try {
+      let sliceId;
+      if (opts.slice) sliceId = findSliceDir(kitDir, opts.slice)?.slice.id ?? opts.slice;
+      else {
+        const claimed = Object.entries(fold(readEvents(kitDir)).slices).filter(([, s]) => s.claim);
+        if (claimed.length === 1) sliceId = claimed[0][0];
+      }
+      const info = recordInfo({ kitDir, text, kind: opts.kind, slice: sliceId, tags: opts.tag, meta });
+      console.log(`✅ Recorded ${info.kind} (${info.id.slice(0, 8)}).`);
+      if (!sliceId) return console.log('ℹ️  No slice named or claimed — not posted to the board.');
+      // Best effort: the event is the record, the comment is how the board shows it.
+      const cfg = loadEffectiveConfig(cwd, kitDir, command.optsWithGlobals().config).config;
+      if (['organizationId', 'boardId', 'token'].some((f) => !cfg[f])) return console.log('ℹ️  No board credentials — not posted to the board.');
+      const res = await fetch(`${cfg.baseUrl || DEFAULT_BASE_URL}/api/org/${cfg.organizationId}/boards/${cfg.boardId}/nodes/${sliceId}/comments`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'x-token': cfg.token, 'x-user-id': 'cli-info', ...agentHeaders(cfg) },
+        body: JSON.stringify({ text: infoComment(info), type: 'COMMENT', author: 'build-agent' }),
+        signal: AbortSignal.timeout(15_000),
+      });
+      console.log(res.ok ? '✅ Posted as a comment on the slice.' : `⚠️  Board returned HTTP ${res.status} — the info is only in the event log.`);
+    } catch (err) {
+      console.error(`❌ ${err.message}`);
+      process.exit(1);
+    }
+  });
+
 program
   .command('events')
   .description("Decode a kit's event log in the terminal: one line per event (claims, settles, learnings, tasks, prompts …) with the slice's title and the agent that wrote it. Filter it, print the raw events, or print the state the log folds to.")
@@ -4462,7 +4793,7 @@ program
   .option('--tag <tag>', 'Only events carrying this tag')
   .option('--last <n>', 'Only the last n events (after the other filters)')
   .option('--json', 'Print the raw events, one JSON object per line')
-  .option('--verbose', 'Print each event\'s payload under its line — for a tool call, the input it was sent (recorded by runs started with --verbose)')
+  .option('--verbose', 'Print each event\'s payload under its line — for a tool call, the input it was sent (recorded by runs started with --verbose). Also shows the baseline events: the kit\'s first look at each slice (a fresh kit records every slice already on the board), which are hidden by default. `--type board-observed` and `--json` show them too.')
   .option('--state', 'Print the state the log folds to (slices, queue, open prompts, learnings) instead of the events')
   .option('--prune', 'Delete the events nothing reads any more — the journal of finished prompts — and stop. Slice state, learnings and open prompts are kept; the same prune a run offers at every 1000 events.')
   .option('--follow', 'Keep running and print events as they are appended')
@@ -4510,6 +4841,8 @@ program
 
     const follow = opts.follow || opts.watch;
     const events = readEvents(kitDir);
+    // The baseline (each slice's first board-observed) is noise unless asked for: --verbose, the raw --json, or the type itself.
+    const hideBaseline = !opts.verbose && !opts.json && !filter.types?.includes('board-observed');
     const titles = sliceTitles(events);
     if (opts.state) {
       if (follow) console.error('ℹ️  --follow/--watch does not apply to --state.');
@@ -4522,7 +4855,7 @@ program
       if (!opts.global && !opts.kit && readEvents(globalLog).length) console.log('The global install has a log of its own: `eventmodelers events --global`.');
       return;
     }
-    print(filterEvents(events, { ...filter, last }, titles), titles);
+    print(filterEvents(events, { ...filter, last, omit: hideBaseline ? baselineIds(events) : undefined }, titles), titles);
     if (!follow) return;
 
     // Follow: what has been printed is remembered by event id, and the log is read again twice a second.
@@ -4531,7 +4864,7 @@ program
       const all = readEvents(kitDir);
       const fresh = all.filter((e) => !seen.has(e.id));
       for (const e of fresh) seen.add(e.id);
-      if (fresh.length) print(filterEvents(fresh, filter, sliceTitles(all)), sliceTitles(all));
+      if (fresh.length) print(filterEvents(fresh, { ...filter, omit: hideBaseline ? baselineIds(all) : undefined }, sliceTitles(all)), sliceTitles(all));
     }, 500);
   });
 

package/lib/build-kits.js

@@ -0,0 +1,23 @@
+// Where the build kits of a project live: the root and up to two directory levels below it, so `run --all` finds
+// both kits of a scaffolded app (root and web/) whether it is started in the app or in the folder holding it.
+// Hidden directories and node_modules are not searched.
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const MAX_DEPTH = 2;
+
+export function findBuildKitDirs(root, kitDirNames) {
+  const has = (dir) => kitDirNames.some((name) => existsSync(join(dir, name)));
+  const found = [];
+  const visit = (dir, depth) => {
+    if (has(dir)) found.push(dir);
+    if (depth === MAX_DEPTH) return;
+    const children = readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith('.') && e.name !== 'node_modules')
+      .map((e) => join(dir, e.name))
+      .sort();
+    for (const child of children) visit(child, depth + 1);
+  };
+  visit(root, 0);
+  return found;
+}