@eventmodelers/cli 2.0.1 → 2.0.2

package/README.md

@@ -137,13 +137,30 @@ Use skills in Claude Code with `/skill-name`:
 
 Which skills install depends on the chosen stack — see `stacks/<name>/templates/.claude/skills/`. `/connect`, `/learn-eventmodelers-api`, `/update-slice-status`, and `/request-feedback` have no stack-specific content and install into every stack from `shared/skills/` instead.
 
+## `scaffold`: a runnable app from your board
+
+`scaffold <dir>` reads the board and generates an app skeleton around the build kits, so slice building starts from an app that already runs. `--type` picks what gets installed and generated:
+
+| Type | Installs | You get |
+|---|---|---|
+| `supabase` (default) | `supabase` at the root, `supabase-react` in `web/` | Supabase email/password sign-in, a layout with one navigation entry per timeline, a page shell per screen at `web/src/pages/<ScreenTitle>.tsx`, `501 Not Implemented` for every modeled endpoint without a slice (a built route always wins), a "not built yet" placeholder in the UI, hot reload for both halves, `npm run up` |
+
+Needs on the machine: Node 22, Docker, Supabase CLI, Flyway + Java (the command lists what is missing). The skeleton itself needs nothing beyond Node, on macOS, Linux and Windows: `npm run up` / `down` / `db:stop` / `user -- <email> <password>` / `check` all go through one plain script, `scripts/dev.mjs`. `<dir>` must be empty or new, or an earlier skeleton, which is refreshed from the current model — generated files are rewritten, pages and anything a builder wrote are kept. Titles come from the board verbatim; a screen's route comes only from a `route /orders` line in its description, the post-sign-in page from a "home page" line, and Bulma is used when the screen mockups use it. `--no-install` stops after generating, `--no-check` skips the checks; ports are picked free automatically and a refresh keeps them (`--port api=3200` pins one; repeatable).
+
+**Your own templates.** `npx @eventmodelers/cli init-templates [paths...]` copies the built-in templates into `./templates/` for you to edit (`--list` shows the paths; name a file such as `web/src/app/Layout.tsx` or a folder such as `web/src/app` to copy only those, and take only what you mean to change — a copied template stops following the CLI's updates; existing files are kept unless `--force`). `scaffold` uses what it finds there and the built-in template for everything else. Or put `*.tmpl` files in a `templates/` folder in the app's root (or point `--templates <dir>` at one, which also works on the first run). A file there replaces the built-in template at the same path — `templates/web/src/app/Layout.tsx.tmpl` replaces `web/src/app/Layout.tsx` — and a path with no built-in counterpart is simply added. The same tokens apply (`__APP_TITLE__`, `__API_PORT__`, `__WEB_PORT__`, `__DB_PORT__`), and every refresh uses them again, so customisations survive a model change. Only `*.tmpl` files count, so nothing in `templates/` is compiled as project code. Files the scaffold writes once (pages, `extraEndpoints.ts`) are never overwritten whatever you put there; edit those in place.
+
+The `supabase` skeleton generator is adapted from the em-scaffold skill by Adrian Mowat (MIT, `shared/scaffold/LICENSE-em-scaffold`).
+
 ## Everyday commands
 
 ```bash
 npx @eventmodelers/cli init --stack <name>          # scaffold a stack + install + configure (alias: install)
 npx @eventmodelers/cli init --stack <name> --demo   # same, plus a ready-made demo model in the kit's .slices/ to build against
+npx @eventmodelers/cli scaffold <dir> --type supabase  # app skeleton from the board (sign-in, navigation, a page per screen, 501 for unbuilt slices) + both kits installed, ready for `run`
 npx @eventmodelers/cli re-init                      # refresh an already-installed kit's scripts/skills only — never touches the root scaffold
 npx @eventmodelers/cli run                          # start the agent loop (ralph-claude.js) from the installed kit dir
+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> --model <id>  # …on a given model: -m for opencode/codex/gemini, --model for Claude, LOCAL_AI_MODEL for --local-ai
@@ -153,7 +170,7 @@ npx @eventmodelers/cli run --modeling               # modeling-kit: warm Claude
 npx @eventmodelers/cli run --standalone             # same, plus acting on board changes unprompted — and needs no install at all
 npx @eventmodelers/cli run --standalone --board-id <uuid>  # …from any directory, against any board (see Power users)
 npx @eventmodelers/cli run --id <id> --name <label>  # override this run's agent identity (id + display name); `init --name` persists a name instead
-npx @eventmodelers/cli run --handover               # backend kit, this run only: finish slices that have a UI at `Handover` instead of `Done` (see Backend → UI handover)
+npx @eventmodelers/cli run --handover               # backend kit, this run only: finish slices that have a UI at `Waiting` instead of `Done` (see Backend → UI handover)
 npx @eventmodelers/cli config --handover on|off      # persist that choice for the project (`handover` in .eventmodelers/config.json)
 npx @eventmodelers/cli fetch --context <name>                     # pull full slice detail for one context on the board into <kit-dir>/.slices/
 npx @eventmodelers/cli fetch --context <name> --slice-id <id>     # same, then print just that slice
@@ -198,7 +215,7 @@ npx @eventmodelers/cli run --local
 
 and the agent starts building — `--local` skips platform config and credential lookup entirely, so it works straight out of `init` with nothing connected. Every TODO you fill in gets exercised on the next iteration against real slice data covering all four slice types (state change, state view, automation, translation), which is exactly the coverage a new stack's `build-*` skills need before it's worth promoting.
 
-**Backend → UI handover.** Besides the usual statuses a slice can be `Ready` (modeling done, waiting to be planned) and `Handover` (backend built, UI contract published, waiting for the UI kit). The flow is `Ready → Planned → InProgress → Handover → InProgress → Done`. Install with `init --handover` (or `re-init --handover`; switch later with `eventmodelers config --handover on|off`; for a single run `run --handover` overrides the setting without saving anything), which saves `"handover": true` in `.eventmodelers/config.json` — then a backend kit ends STATE_VIEW / STATE_CHANGE slices at `Handover` instead of `Done` (the `ui-contract` skill, Step 4, owns that rule); without the flag nothing changes: slices end at `Done`, exactly as before. A kit claims work from the status named in its `lib/kit.json` — `{ "pickupStatus": "Handover" }` for the `react` / `supabase-react` UI kits, absent (= `Planned`) for backend kits. A new UI kit ships that file and sets `Done` when its half is built; a new backend kit just invokes `ui-contract`. Needs a platform with the `Ready` / `Handover` statuses.
+**Backend → UI handover.** Besides the usual statuses a slice can be `Ready` (modeling done, waiting to be planned) and `Waiting` (backend built, UI contract published, waiting for the UI kit). The flow is `Ready → Planned → InProgress → Waiting → InProgress → Done`. Install with `init --handover` (or `re-init --handover`; switch later with `eventmodelers config --handover on|off`; for a single run `run --handover` overrides the setting without saving anything), which saves `"handover": true` in `.eventmodelers/config.json` — then a backend kit ends STATE_VIEW / STATE_CHANGE slices at `Waiting` instead of `Done` (the `ui-contract` skill, Step 4, owns that rule); without the flag nothing changes: slices end at `Done`, exactly as before. A kit claims work from the status named in its `lib/kit.json` — `{ "pickupStatus": "Waiting" }` for the `react` / `supabase-react` UI kits, absent (= `Planned`) for backend kits. A new UI kit ships that file and sets `Done` when its half is built; a new backend kit just invokes `ui-contract`. Needs a platform with the `Ready` / `Waiting` statuses.
 
 **UI contract (handover only).** With handover on, the scaffolded `build-state-view` / `build-state-change` skills end by invoking the shared `ui-contract` skill, which publishes each slice's read (`GET`) or write (`POST`) contract — the endpoint's OpenAPI operation, as a ```` ```yaml ui-contract ```` block — as a `## UI Contract` section in the slice's feedback-lane markdown node (exported in `slice.json` `notes[]`, so a UI build kit can look it up directly). Two things are yours to decide: *where the contract is derived from* (point the `UI Contract` section of those skills at your stack's machine-readable API description, if it has one — the `node`/`supabase` stacks use their `@openapi` blocks via a `ui-contract-from-openapi.md` reference, taking the operation verbatim — otherwise the skill writes the equivalent OpenAPI operation from the route code), and, if you need a different shape or location, a whole-skill override: ship `.claude/skills/ui-contract/SKILL.md` in the stack's templates and it replaces the shared one (stack templates are applied after `shared/skills/`).
 
@@ -652,7 +669,7 @@ Pair it with `--id`: a `--standalone`/`--global` run mints a fresh id per run, s
 
 ### Backend → UI handover (`--handover`)
 
-A slice with a UI is only finished once two kits have each built their half: the backend kit builds the endpoint and publishes its contract, the UI kit builds the frontend against it. `--handover` makes the first kit stop at `Handover` instead of `Done`, so the second one can claim the slice.
+A slice with a UI is only finished once two kits have each built their half: the backend kit builds the endpoint and publishes its contract, the UI kit builds the frontend against it. `--handover` makes the first kit stop at `Waiting` instead of `Done`, so the second one can claim the slice.
 
 ```bash
 npx @eventmodelers/cli init --stack node --handover   # persisted: "handover": true in .eventmodelers/config.json (also re-init)
@@ -663,18 +680,18 @@ npx @eventmodelers/cli run --handover                 # this run only — writes
 
 | | Handover off (default) | Handover on |
 |---|---|---|
-| Backend kit, STATE_VIEW / STATE_CHANGE slice | ends at `Done`, no UI contract published | publishes the UI contract, ends at `Handover` |
+| Backend kit, STATE_VIEW / STATE_CHANGE slice | ends at `Done`, no UI contract published | publishes the UI contract, ends at `Waiting` |
 | Backend kit, automation / translation | `Done` | `Done` — no UI counterpart |
-| UI kit (`react`, `supabase-react`) | claims `Handover` only | claims `Handover` only, sets `Done` when its UI is built |
+| UI kit (`react`, `supabase-react`) | claims `Waiting` only | claims `Waiting` only, sets `Done` when its UI is built |
 
-Flow: `Ready → Planned → InProgress → Handover → InProgress → Done`. Precedence for a run is `run --handover` over the project's `handover` setting; the runner states the effective value to the agent as a `Handover: on|off` line in its task, so the agent never has to work it out from `config.json`. `config --handover` writes to the project's config (the installed kit's project, else the nearest `.eventmodelers/config.json` up the tree — never the account-wide one in `~/`).
+Flow: `Ready → Planned → InProgress → Waiting → InProgress → Done`. Precedence for a run is `run --handover` over the project's `handover` setting; the runner states the effective value to the agent as a `Handover: on|off` line in its task, so the agent never has to work it out from `config.json`. `config --handover` writes to the project's config (the installed kit's project, else the nearest `.eventmodelers/config.json` up the tree — never the account-wide one in `~/`).
 
 **What to know before relying on it**
 
-- **UI kits only ever claim `Handover`.** Against a board whose backend finished slices at `Done`, a `react` / `supabase-react` kit has nothing to do and replies `NO_TASKS` — the backend side must run with handover on.
+- **UI kits only ever claim `Waiting`.** Against a board whose backend finished slices at `Done`, a `react` / `supabase-react` kit has nothing to do and replies `NO_TASKS` — the backend side must run with handover on.
 - **Both sides need the new kit.** An already-installed backend kit keeps its old `ralph.js` and prompts and silently ignores `--handover` (slices still end at `Done`); `re-init` it to pick the feature up.
-- **The platform must know the `Ready` / `Handover` statuses.**
-- A kit declares what it claims in `lib/kit.json` — `{ "pickupStatus": "Handover" }`; absent means `Planned`.
+- **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.
 
 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

@@ -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,13 +35,14 @@ 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';
@@ -463,6 +468,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
@@ -3286,11 +3315,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 +3401,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 +3812,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 +3824,8 @@ 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('--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 +3833,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.
@@ -4019,22 +4092,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
@@ -4160,6 +4218,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 +4431,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 +4608,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 +4630,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`).")
@@ -4462,7 +4751,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 +4799,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 +4813,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 +4822,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;
+}