@eventmodelers/cli 1.0.153 → 1.0.154

package/README.md

@@ -155,6 +155,8 @@ 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 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
 npx @eventmodelers/cli fetch --context <name> --slice-title <title> # same, then print just the slice matching this title
@@ -198,6 +200,10 @@ 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.
+
+**UI contract.** The scaffolded `build-state-view` / `build-state-change` skills already end by invoking the shared `ui-contract` skill, which publishes each slice's read (`GET`) or write (`POST`) contract 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 — otherwise the skill reads 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/`).
+
 Installing both a build stack and `init-modeling` into the same project reuses this one `.eventmodelers/config.json` — run whichever `init` command second and it finds the existing config already satisfies the required fields and skips straight past the credential prompt.
 
 ### The modeling agent — `run --modeling` and `--standalone`
@@ -649,6 +655,34 @@ Only prompts carrying this agent's id are worked. Anything untargeted is handed
 
 Pair it with `--id`: a `--standalone`/`--global` run mints a fresh id per run, so prompts addressed to the previous run's id are never claimed. `--exclusive` applies to the prompt queue only — a `--standalone` agent's self-directed turns are nobody's prompt, and it keeps taking them.
 
+### 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.
+
+```bash
+npx @eventmodelers/cli init --stack node --handover   # persisted: "handover": true in .eventmodelers/config.json (also re-init)
+npx @eventmodelers/cli config --handover on           # switch it on later…
+npx @eventmodelers/cli config --handover off          # …or back off
+npx @eventmodelers/cli run --handover                 # this run only — writes nothing
+```
+
+| | Handover off (default) | Handover on |
+|---|---|---|
+| Backend kit, STATE_VIEW / STATE_CHANGE slice | ends at `Done` | publishes the UI contract, ends at `Handover` |
+| 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 |
+
+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 `~/`).
+
+**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.
+- **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 contract itself is the shared `ui-contract` skill's job (see above); it also owns the rule for which status a slice ends at.
+
 ### Env vars and `--config` (scripted/CI installs)
 
 Every config field can be set via an `EVENTMODELERS_*` env var instead of the interactive prompts — these always win over whatever's in `config.json`, so a fully env-driven install never prompts for credentials or Claude execution settings:
@@ -759,7 +793,7 @@ npx @eventmodelers/cli uninstall --modeling-kit      # remove .agent-modeling-ki
 
 ### Adding a stack
 
-Each stack lives under `stacks/<name>/templates/` with `.claude/` (skills), `root/` (spread into the project root), and either `build-kit/` (backend stacks) or `kit/` (modeling-only) for the agent runner. Files identical across all backend stacks live once in `shared/build-kit/` and get layered in automatically — only put stack-specific overrides under `stacks/<name>/templates/build-kit/`. Skills with no stack-specific content (`connect`, `learn-eventmodelers-api`, `update-slice-status`, `request-feedback`) work the same way via `shared/skills/` — a new stack gets them for free without copying anything; add a skill there only once it needs a stack-specific fork.
+Each stack lives under `stacks/<name>/templates/` with `.claude/` (skills), `root/` (spread into the project root), and either `build-kit/` (backend stacks) or `kit/` (modeling-only) for the agent runner. Files identical across all backend stacks live once in `shared/build-kit/` and get layered in automatically — only put stack-specific overrides under `stacks/<name>/templates/build-kit/`. Skills with no stack-specific content (`connect`, `learn-eventmodelers-api`, `update-slice-status`, `request-feedback`, `ui-contract`) work the same way via `shared/skills/` — a new stack gets them for free without copying anything; add a skill there only once it needs a stack-specific fork. A stack overrides a shared skill by shipping one of the same name under its own `.claude/skills/` (e.g. a custom `ui-contract`).
 
 The demo model `init --demo` installs is shared the same way, in `shared/demo-slices/` — a verbatim `fetch --format json` tree (`current_context.json` plus `<context>/{context,index,config}.json` and `<slice>/slice.json`), copied as-is into the kit's `.slices/`. It's stack-agnostic board data, so a new stack gets `--demo` for free. To replace or extend it, `fetch` a context into an empty directory and copy the result in, then update `DEMO_CONTEXT_NAME`/`DEMO_SLICE_COUNT` in `cli.js` (used only for the line `init` prints).
 

package/cli.js

@@ -710,6 +710,18 @@ function findConfigInParents(startDir) {
   return existsSync(globalCandidate) ? globalCandidate : null;
 }
 
+// Where a project-level setting (`config --handover`, `--agent-tracing`) is written: the explicit
+// --config, else the installed kit's project, else the nearest project config up the tree — so it
+// lands in the file `run` merges in, even from a subdirectory — else this directory. The
+// account-wide ~/.eventmodelers/config.json is never a target: these are per-project policies.
+function projectConfigPath(cwd, kitDir, explicitConfig) {
+  if (explicitConfig) return resolve(explicitConfig);
+  if (kitDir) return join(dirname(kitDir), '.eventmodelers', 'config.json');
+  const found = findConfigInParents(cwd);
+  const globalPath = join(homedir(), '.eventmodelers', 'config.json');
+  return found && found !== globalPath ? found : join(cwd, '.eventmodelers', 'config.json');
+}
+
 function readJsonSafe(path) {
   if (!path || !existsSync(path)) return {};
   try {
@@ -983,9 +995,11 @@ async function installStack(stackKey, stackCfg, options = {}) {
       copyDirContents(claudeSkillsSrc, globalSkillsDir);
     } else {
       console.log('📦 Installing skills...');
-      copyDirContents(join(templatesSource, '.claude'), join(targetDir, '.claude'));
+      // Shared skills first, the stack's own templates last — so a build kit can override
+      // a shared skill (e.g. `ui-contract`) just by shipping a skill of the same name.
       copyDirContents(sharedSkills, join(targetDir, '.claude', 'skills'));
       if (isBridge) copyDirContents(sharedBridgeSkills, join(targetDir, '.claude', 'skills'));
+      copyDirContents(join(templatesSource, '.claude'), join(targetDir, '.claude'));
       claudeExtras = existsSync(join(templatesSource, '.claude'))
         ? readdirSync(join(templatesSource, '.claude')).filter((f) => f !== 'skills')
         : [];
@@ -1357,6 +1371,10 @@ async function configureCredentials({ config, configPath, targetDir, requiredFie
   if (!skipWrite) {
     writeFileSync(configPath, JSON.stringify(config, null, 2));
     console.log(`\n  ✓ Saved to ${relative(targetDir, configPath)}`);
+  } else if (overrides.handover) {
+    // A policy flag, not a credential — it must stick even when credentials were skipped.
+    writeFileSync(configPath, JSON.stringify({ ...readJsonSafe(configPath), handover: true }, null, 2));
+    console.log(`  ✓ Handover on — saved to ${relative(targetDir, configPath)}`);
   }
   return config;
 }
@@ -3241,9 +3259,19 @@ const AGENT_NAME_OPTION = [
   'Human-readable name for the agent this kit runs (e.g. "ci-builder", "martins-laptop"), saved to config.json as `agentName` and sent with every heartbeat so the board shows a name instead of a bare uuid. Also settable via EVENTMODELERS_AGENT_NAME, and overridable for a single run with `run --name`.',
 ];
 
+// `--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
+// `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`.',
+];
+
 function identityOverridesFromOpts(opts) {
   const agentName = typeof opts.name === 'string' ? opts.name.trim() : undefined;
-  return agentName ? { agentName } : {};
+  return { ...(agentName ? { agentName } : {}), ...(opts.handover ? { handover: true } : {}) };
 }
 
 credentialFlags(program
@@ -3262,7 +3290,8 @@ credentialFlags(program
   .option('--demo', 'Install a ready-made demo model into the kit\'s .slices/ — the "Understanding Eventsourcing" context (16 shopping-cart slices covering every slice type), in exactly the shape `fetch` writes, so the build skills and the agent loop have something real to work on before this project is connected to a board. Skipped if .slices/ already holds fetched slices. Off by default.')
   .option('--global', 'Install skills into ~/.claude/skills/ instead of the project — available in every project')
   .option('-f, --force', 'Re-prompt for credentials even if a config already has everything required — overwrites the existing config.json')
-  .option(...AGENT_NAME_OPTION))
+  .option(...AGENT_NAME_OPTION)
+  .option(...HANDOVER_OPTION))
   .action(async (opts, command) => {
     const globalOpts = command.optsWithGlobals();
 
@@ -3384,7 +3413,8 @@ credentialFlags(program
   .option('--hooks', 'Install the slice commit-scope guard (.githooks/pre-commit) and wire it up via `git config core.hooksPath .githooks` — same as `init --hooks`, for turning it on after the fact without a full re-scaffold. Off by default.')
   .option('--global', 'Re-install skills into ~/.claude/skills/ instead of the project — defaults to however they were originally installed')
   .option('-f, --force', 'Re-prompt for credentials even if a config already has everything required — overwrites the existing config.json')
-  .option(...AGENT_NAME_OPTION))
+  .option(...AGENT_NAME_OPTION)
+  .option(...HANDOVER_OPTION))
   .action(async (opts, command) => {
     const globalOpts = command.optsWithGlobals();
     const targetDir = process.cwd();
@@ -3686,6 +3716,7 @@ 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('--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. A project install otherwise mints one id per project and reuses it on every restart; --global/--standalone mints a fresh one per run, since two ad-hoc agents for one board must not share a row (the heartbeat is keyed on token + agent_id + agent_type, so the second would replace the first). Pass this when an agent has to keep ONE identity across restarts — a supervisor that already knows the id, or a board where it is the starred "preferred agent". 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.')
@@ -3956,7 +3987,7 @@ credentialFlags(program
       // local-only branch even when .eventmodelers/config.json has valid credentials.
       // RALPH_AGENT_ID/RALPH_AGENT_NAME (--id/--name) are read in ralph.js's startRalph, so
       // they reach both node runners but not ralph.sh, which has no heartbeat to identify.
-      execSync(cmd, { cwd: kitDir, stdio: 'inherit', env: { ...process.env, RALPH_VERBOSE: opts.verbose ? '1' : '', RALPH_LOCAL: opts.local ? '1' : '', 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_LOCAL: opts.local ? '1' : '', RALPH_HANDOVER: opts.handover ? '1' : '', 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);
     }
@@ -4174,7 +4205,9 @@ const SLICE_STATUSES = [
   { label: '🔄 InProgress', value: 'InProgress' },
   { label: '🔍 Review', value: 'Review' },
   { label: '🚫 Blocked', value: 'Blocked' },
+  { label: '🧭 Ready', value: 'Ready' },
   { label: '📅 Planned', value: 'Planned' },
+  { label: '🤝 Handover', value: 'Handover' },
   { label: 'ℹ️ Informational', value: 'Informational' },
 ];
 
@@ -4504,21 +4537,31 @@ program
 program
   .command('config')
   .description('Print the fully resolved config (merged across the directory hierarchy + EVENTMODELERS_* env vars), with the token masked')
+  .option('--handover <on|off>', "Turn the backend→UI handover on or off for this project (saved as `handover` in the project's .eventmodelers/config.json). On: a backend build kit ends slices that have a UI at `Handover`; off: at `Done`.")
   .option('--agent-tracing <on|off>', "Turn agent tracing on or off for this project (saved as `agentTracing` in the project's .eventmodelers/config.json). Off: the build agent sends no slice cost data to the platform at all. A non-Claude agent via run --exec is only traced when its command includes the harness's JSON output flag, e.g. \"codex exec --json --full-auto\".")
   .action((opts, command) => {
     const cwd = process.cwd();
     const kitDir = findInstalledKitDir(cwd);
     const explicitConfig = command.optsWithGlobals().config;
 
+    if (opts.handover !== undefined) {
+      const value = String(opts.handover).toLowerCase();
+      if (!['on', 'off'].includes(value)) {
+        console.error('❌ --handover takes "on" or "off"');
+        process.exit(1);
+      }
+      const configPath = projectConfigPath(cwd, kitDir, explicitConfig);
+      mkdirSync(dirname(configPath), { recursive: true });
+      writeFileSync(configPath, JSON.stringify({ ...readJsonSafe(configPath), handover: value === 'on' }, null, 2));
+      console.log(`✓ Handover ${value} — saved to ${relative(cwd, configPath) || configPath}\n`);
+    }
     if (opts.agentTracing !== undefined) {
       const value = String(opts.agentTracing).toLowerCase();
       if (!['on', 'off'].includes(value)) {
         console.error('❌ --agent-tracing takes "on" or "off"');
         process.exit(1);
       }
-      const configPath = explicitConfig
-        ? resolve(explicitConfig)
-        : join(kitDir ? dirname(kitDir) : cwd, '.eventmodelers', 'config.json');
+      const configPath = projectConfigPath(cwd, kitDir, explicitConfig);
       mkdirSync(dirname(configPath), { recursive: true });
       writeFileSync(configPath, JSON.stringify({ ...readJsonSafe(configPath), agentTracing: value === 'on' }, null, 2));
       console.log(`✓ Agent tracing ${value} — saved to ${relative(cwd, configPath) || configPath}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.153",
+  "version": "1.0.154",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, OpenCQRS, UmaDB, Kurrent, or modeling-only)",
   "type": "module",
   "bin": {

package/shared/build-kit/lib/adapters/pocketbase-realtime-adapter.js

@@ -24,33 +24,59 @@ export async function createPocketBaseRealtimeAdapter(cfg, initialToken, deps =
   const pb = new PocketBase(cfg.pocketbaseUrl);
   pb.authStore.save(initialToken, null);
 
-  // One listener per topic; subscribe() replaces the topic's previous one (see realtime-adapter.js).
-  const listeners = new Map();
+  // The SDK adds one EventSource listener per subscribe() call — and keeps it when the call
+  // fails — so a flaky connection retrying per topic piles listeners up (Node warns at 11).
+  // Hence a single SDK subscription for the whole adapter, fanned out to topics here.
+  // subscribe() replaces the topic's previous handlers (see realtime-adapter.js).
+  const topics = new Map();
+  let sdkUnsubscribe = null;
+  let connecting = null;
+
+  const connect = async () => {
+    for (let attempt = 0; ; attempt++) {
+      try {
+        sdkUnsubscribe = await pb.collection(REALTIME_EVENTS_COLLECTION).subscribe('*', (e) => {
+          if (e.action !== 'create') return;
+          const entry = topics.get(e.record.topic);
+          entry?.handlers[e.record.event]?.(e.record.payload);
+        });
+        return;
+      } catch (err) {
+        // Drop the listener the failed call left behind before trying again.
+        await pb.collection(REALTIME_EVENTS_COLLECTION).unsubscribe('*').catch(() => {});
+        if (attempt >= RECONNECT_INTERVALS_MS.length) throw err;
+        topics.forEach((t) => t.onStatus?.(`RECONNECTING (attempt ${attempt + 1}/${RECONNECT_INTERVALS_MS.length}): ${err.message}`));
+        await new Promise((resolve) => setTimeout(resolve, RECONNECT_INTERVALS_MS[attempt]));
+      }
+    }
+  };
+
+  // Concurrent subscribe() calls share one in-flight connect — sdkUnsubscribe is only set
+  // after the await, so without this each would open its own SDK subscription.
+  const ensureSdkSubscription = () => {
+    if (sdkUnsubscribe) return Promise.resolve();
+    connecting ??= connect().finally(() => { connecting = null; });
+    return connecting;
+  };
+
   const remove = async (topic) => {
-    const unsubscribe = listeners.get(topic);
-    if (!unsubscribe) return;
-    listeners.delete(topic);
+    topics.delete(topic);
+    if (topics.size || !sdkUnsubscribe) return;
+    const unsubscribe = sdkUnsubscribe;
+    sdkUnsubscribe = null;
     await unsubscribe().catch(() => {});
   };
 
   return {
     async subscribe(topic, handlers, onStatus) {
-      await remove(topic);
-      for (let attempt = 0; ; attempt++) {
-        try {
-          const unsubscribe = await pb.collection(REALTIME_EVENTS_COLLECTION).subscribe('*', (e) => {
-            if (e.action !== 'create' || e.record.topic !== topic) return;
-            handlers[e.record.event]?.(e.record.payload);
-          });
-          listeners.set(topic, unsubscribe);
-          onStatus?.('SUBSCRIBED');
-          return;
-        } catch (err) {
-          if (attempt >= RECONNECT_INTERVALS_MS.length) throw err;
-          onStatus?.(`RECONNECTING (attempt ${attempt + 1}/${RECONNECT_INTERVALS_MS.length}): ${err.message}`);
-          await new Promise((resolve) => setTimeout(resolve, RECONNECT_INTERVALS_MS[attempt]));
-        }
+      topics.set(topic, { handlers, onStatus });
+      try {
+        await ensureSdkSubscription();
+      } catch (err) {
+        topics.delete(topic);
+        throw err;
       }
+      onStatus?.('SUBSCRIBED');
     },
     unsubscribe(topic) {
       return remove(topic);

package/shared/build-kit/lib/ralph.js

@@ -242,7 +242,8 @@ async function fetchAndPersistSlices(cfg, kitDir) {
   if (!activeCtx || !contexts[activeCtx]) {
     // First run (or the current context disappeared): seed with a context that
     // has planned work, else the first one. This is the ONLY place we choose it.
-    const plannedCtx = Object.keys(contexts).find(c => contexts[c].slices.some(s => (s.status || '').toLowerCase() === 'planned'));
+    const pickup = readPickupStatus(kitDir).toLowerCase();
+    const plannedCtx = Object.keys(contexts).find(c => contexts[c].slices.some(s => (s.status || '').toLowerCase() === pickup));
     activeCtx = plannedCtx || Object.keys(contexts)[0] || 'default';
     writeFileSync(ctxPath, JSON.stringify({ name: activeCtx }, null, 2), 'utf-8');
   }
@@ -400,11 +401,12 @@ async function handleSliceChanged(payload, cfg, kitDir, queueAllStatuses) {
   await fetchAndPersistSlices(cfg, kitDir).catch((err) =>
     console.error('[agent] Slice persist error:', err),
   );
-  // Planned slices are handled by onPlannedSlice directly — no task needed.
+  // Slices in the kit's pickup status (Planned, or Handover for UI kits) are handled by
+  // onPlannedSlice directly — no task needed.
   // queueAllStatuses opts out of that split entirely (e.g. bridge has no
   // onPlannedSlice consumer, so a lingering Planned slice would otherwise
   // never naturally clear its own trigger — see lib/ralph.js callers).
-  if (queueAllStatuses || (payload.sliceStatus || '').toLowerCase() !== 'planned') {
+  if (queueAllStatuses || (payload.sliceStatus || '').toLowerCase() !== readPickupStatus(kitDir).toLowerCase()) {
     await writeTask(payload, kitDir).catch((err) => console.error('[agent] writeTask error:', err));
   }
 }
@@ -513,6 +515,17 @@ function hasPendingTasks(kitDir) {
   return readTasks(join(kitDir, 'tasks.json')).length > 0;
 }
 
+// The slice status this kit claims work from. A stack declares it in `lib/kit.json`
+// ({ "pickupStatus": "Handover" } for the UI kits, which build what a backend kit handed over);
+// absent means "Planned", the backend default.
+export function readPickupStatus(kitDir) {
+  try {
+    const s = JSON.parse(readFileSync(join(kitDir, 'lib', 'kit.json'), 'utf-8')).pickupStatus;
+    if (typeof s === 'string' && s.trim()) return s.trim();
+  } catch {}
+  return 'Planned';
+}
+
 function readCurrentContext(kitDir) {
   const ctxPath = join(kitDir, '.slices', 'current_context.json');
   if (!existsSync(ctxPath)) return null;
@@ -541,13 +554,14 @@ function getFirstPlannedSlice(kitDir) {
   try {
     others = readdirSync(slicesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
   } catch {}
+  const pickup = readPickupStatus(kitDir).toLowerCase();
   const candidates = [...(currentCtx ? [currentCtx] : []), ...others.filter((c) => c !== currentCtx)];
   for (const ctx of candidates) {
     const indexPath = join(slicesDir, ctx, 'index.json');
     if (!existsSync(indexPath)) continue;
     try {
       const { slices } = JSON.parse(readFileSync(indexPath, 'utf-8'));
-      const planned = slices && slices.find((s) => (s.status || '').toLowerCase() === 'planned');
+      const planned = slices && slices.find((s) => (s.status || '').toLowerCase() === pickup);
       if (!planned) continue;
       if (ctx !== currentCtx) {
         writeFileSync(join(slicesDir, 'current_context.json'), JSON.stringify({ name: ctx }, null, 2), 'utf-8');
@@ -673,11 +687,20 @@ async function runWithRetry(label, fn) {
 // alone, the agent read it as background, answered "what would you like me to help with?" with
 // no tool calls, and a Planned slice stayed Planned until the stuck-slice guard blocked it. So
 // every turn ends with the concrete request — here, once, for every runner.
-function taskRequest(planned = null) {
+// Whether a backend kit finishes UI-bearing slices at `Handover` instead of `Done`: this run's
+// `run --handover` (RALPH_HANDOVER) over the project's `handover` setting in config.json.
+export function resolveHandover(cfg) {
+  return process.env.RALPH_HANDOVER === '1' || cfg?.handover === true;
+}
+
+function taskRequest(planned = null, cfg = null, pickupStatus = 'Planned') {
   const task = planned
-    ? `build the Planned slice "${planned.title}" (id=${planned.id}, context="${planned.ctx}")`
+    ? `build the ${pickupStatus} slice "${planned.title}" (id=${planned.id}, context="${planned.ctx}")`
     : 'process the pending tasks in tasks.json';
-  return `\n\n---\n\nYour task now: ${task}, following the instructions above. Start immediately.\n`;
+  // Stated explicitly so the agent never has to work it out from config.json: this run's effective
+  // value, which is what the `ui-contract` skill (Step 4) follows. UI kits (pickup Handover) ignore it.
+  const handover = planned && pickupStatus === 'Planned' ? `\nHandover: ${resolveHandover(cfg) ? 'on' : 'off'}\n` : '';
+  return `\n\n---\n\nYour task now: ${task}, following the instructions above. Start immediately.\n${handover}`;
 }
 
 async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false) {
@@ -718,7 +741,7 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
         continue;
       }
 
-      const prompt = readFileSync(backendPromptFile, 'utf-8') + taskRequest(planned);
+      const prompt = readFileSync(backendPromptFile, 'utf-8') + taskRequest(planned, cfg, readPickupStatus(kitDir));
       if (credentialed) await fetchFullSlice(cfg, kitDir, planned.id);
       lastReply = null;
       const built = await runWithRetry(`onPlannedSlice: building slice "${planned.title}"...`, async () => { lastReply = await onPlannedSlice(prompt, {

package/shared/skills/connect/SKILL.md

@@ -289,7 +289,7 @@ Connecting is also where the session's read discipline starts. Every skill that
 
 The orientation read also tells you what you may write to. `get_board_outline` returns `sliceStatus` per column — a slice owns a column, so every element in that column shares its status. `get_nodes` does **not** carry it, so take it from the outline before any write:
 
-**Only a slice in `Created` may be written to.** Any other status — `Planned`, `Assigned`, `InProgress`, `Review`, `Blocked`, `Done`, `Informational` — means someone is working on that slice: read its elements for context, but never change, move, rename or delete them, and never add scenarios, fields or examples to them. An element in a column with **no** `sliceStatus` is in no slice at all, which is not the same as locked — that one is writable.
+**Only a slice in `Created` may be written to.** Any other status — `Ready`, `Planned`, `Assigned`, `InProgress`, `Handover`, `Review`, `Blocked`, `Done`, `Informational` — means someone is working on that slice: read its elements for context, but never change, move, rename or delete them, and never add scenarios, fields or examples to them. An element in a column with **no** `sliceStatus` is in no slice at all, which is not the same as locked — that one is writable.
 
 Never spend a `list_slices`/`get_slice_data` call to answer this; the outline already did.
 

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

@@ -644,7 +644,7 @@ Create a complete slice (1 column + its nodes automatically placed).
     interaction?: Partial<NodeData> & { rowId?: string, fields?: FieldDef[] }
     swimlane?: Partial<NodeData> & { rowId?: string, fields?: FieldDef[] }
   }
-  status?: 'Created' | 'Planned' | 'InProgress' | 'Review' | 'Done' | 'Blocked' | 'Assigned' | 'Informational'
+  status?: 'Created' | 'Ready' | 'Planned' | 'InProgress' | 'Handover' | 'Review' | 'Done' | 'Blocked' | 'Assigned' | 'Informational'
 }
 ```
 
@@ -671,7 +671,7 @@ Create a standalone SLICE_BORDER node spanning an **existing** column. Unlike th
 {
   columnId: string   // id of an existing column on this timeline
   title: string      // slice title — always taken from this field, never derived
-  status?: 'Created' | 'Planned' | 'InProgress' | 'Review' | 'Done' | 'Blocked' | 'Assigned' | 'Informational'
+  status?: 'Created' | 'Ready' | 'Planned' | 'InProgress' | 'Handover' | 'Review' | 'Done' | 'Blocked' | 'Assigned' | 'Informational'
   data?: Record<string, unknown>   // optional node.data payload
   meta?: Record<string, unknown>   // optional extra meta fields (type, colId, title are always set explicitly and cannot be overridden here)
 }
@@ -845,7 +845,8 @@ How much each slice of one context has been reworked — read-only, derived from
 for it.
 
 A slice's rework is read from its own SLICE_BORDER history. Going backwards means a step down the progress order
-(Created → Planned → Assigned → InProgress → Review → Done), or reaching `Blocked` from `Review`/`Done`;
+(Created → Ready → Planned → Assigned → InProgress → Handover → Review → Done), or reaching `Blocked` from
+`Handover`/`Review`/`Done`;
 `Informational` is never scored. `reopens` counts transitions leading away from `Done`, `changes` counts writes to the
 slice itself. This says nothing about edits to the elements inside a slice.
 
@@ -854,6 +855,7 @@ context (the same rule `slicedata` uses), so one that inherits a context is repo
 none is its own. Any other node type is rejected. Always scoped to one context; there is no board-wide form.
 
 **Response**: `200` — `{ contextId, contextName, metrics, slices[] }`, slices most reworked first.
+`metrics.progress` is where the slices stand now: `done`, `inProgress` (Assigned/InProgress/Review), `handover`, `ready`, `blocked`, `planned` (Planned/Created) as counts plus a `…Rate` share each, over the non-Informational slices, summing to 1.
 `slices[]` = `{ sliceId, title, status, changes, reopens, regressions, everReachedDone }`.
 `metrics` = `{ slices, everReachedDone, reopenedAfterDone, firstTimeRightRate, currentlyReopened, avgReopensPerSlice,
 avgChangesPerSlice }` — `firstTimeRightRate` is the share of the slices that reached Done and never came back, or
@@ -1172,11 +1174,12 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
 | to show several screens at once — a list, a gallery, a storyboard ("show me all screens of X") | `walkthrough`, one step per screen | nothing — selecting a step pans the canvas |
 | to answer where one piece of information comes from and where it ends up ("where is the customer email used?") | `dataJourney` | nothing — element names pan the canvas |
 | to show a diagram you drew yourself — a context map, a domain story, a sketch, any picture that isn't a chart | `svg` | nothing |
+| to show a UML or flow diagram you write as Mermaid — a sequence, flowchart, state, ER or class diagram | `mermaid` | nothing |
 | to lay out rows and columns — a comparison, a matrix (stressors × elements), a short list with a few attributes | `table` | nothing — linked cells pan the canvas |
 | to show a prototype you just built and uploaded (the `prototype` skill), running in the chat | `prototype` | nothing — **Full screen** opens the board's prototype player |
 | something the customer defined their own snippet type for (a risk card, a sign-off — see `list_snippet_types`) | `custom` | the clicked action's `answer`; `context.snippetReply.then` says what to do |
 
-`confirm`, `poll`, `tasks` and `changes` are questions: a person answers once, then they show as answered. `link`, `image`, `code`, `report`, `walkthrough`, `screen`, `dataJourney`, `svg`, `table` and `prototype` are display only and never wait for anything.
+`confirm`, `poll`, `tasks` and `changes` are questions: a person answers once, then they show as answered. `link`, `image`, `code`, `report`, `walkthrough`, `screen`, `dataJourney`, `svg`, `mermaid`, `table` and `prototype` are display only and never wait for anything.
 
 ### Shapes
 ```typescript
@@ -1225,6 +1228,8 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
   title?: string, caption?: string,
   links?: Array<{ nodeId: string, x: number, y: number,                           // ≤ 200 clickable areas over the picture, in the svg's viewBox coordinates;
                   width: number, height: number, title?: string }> }             // a click zooms the canvas to nodeId; title = tooltip (else the element's title)
+{ kind: 'mermaid', source: string,                                               // Mermaid source, no ``` fence (≤ 60000 chars); the app draws it
+  title?: string, caption?: string }
 { kind: 'table', title?: string, caption?: string,
   columns: Array<string | { label: string, nodeId?: string,                      // 1–12; nodeId makes the header a link (a matrix with one column per element)
                             align?: 'left' | 'center' | 'right' }>,
@@ -1247,6 +1252,7 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
 - **`dataJourney`** answers "where does X come from / where is X used?" for **one piece of information**, as a table: one stop per element it passes through, in flow order, each with its `role`, the field name there and the slice. A headline counts the roles ("Originates in 1 place, stored in 2 elements and used in 3 places"). Build it from the board — the `data-journey` skill (modeling kit) has the procedure; every `nodeId` must be a real id from this board, and a field the board doesn't carry is not a stop. Keep `text` to one line naming the data and where it originates.
 - **`svg`** is for a picture you draw yourself: give the root a `viewBox` (and `width`/`height` for its natural size), inline colours and fonts — it is shown as an image, so scripts, `<a>` links and external resources do nothing. To make parts of it clickable, list them in `links`: a rectangle in the viewBox coordinates you drew in plus the element it stands for (only real ids from this board); the app lays a clickable area over each that zooms the canvas there. Prefer `report` for numbers. A domain story (who does what with which work object) is an `svg` you draw — the `domain-story` skill (modeling kit) has the procedure and the drawing style. Every SVG snippet has a download-as-PNG button.
   - **"Place it on the board" after you drew an SVG always means: put that picture on the board as an image** — never rebuild it from elements (stickies, lanes, a timeline), never a SCREEN, never a new snippet. `place_image` with `imageBase64` = the SVG document itself, base64-encoded, `mimeType: "image/svg+xml"`, `title` = the snippet's title: it becomes an OUTLINE (the drawing tools' image element), free-floating at `x`/`y`, in no chapter and connected to nothing. Place it where the person says, else in free space next to the chapter it is about (`get_chapter_bounds`: right of or below it). Add a white background `<rect>` first if the SVG has none, or it is unreadable on a dark board. One SVG = one image. The image on the board has no clickable areas — `links` stay in the chat.
+- **`mermaid`** is for a diagram you can write as text: a sequence diagram (`sequenceDiagram`), a flow (`flowchart LR`), states (`stateDiagram-v2`), an ER or class diagram. Send just the source; the app draws it, with a *Show source* toggle and a copy button, and shows the source when it has a syntax error — so keep the syntax plain (quote labels with special characters). Prefer it over a `code` block for any diagram: a `code` block with `language: "mermaid"` is drawn too, but `mermaid` says what you mean. It has no element links; for clickable parts draw an `svg`.
 - **`table`** is for anything that is rows and columns and not a chart: a comparison of options, an incidence matrix (rows = stressors, columns = elements, `true` where it hits), a short list with a few attributes per item. It computes nothing — totals are a row you add. Put element ids in `nodeId` (header or cell) so names are links; a row longer than the columns is cut, a shorter one padded, an empty one dropped. Prefer `report` for numbers you want *seen* as a trend or share, `dataJourney` for one piece of data's path.
 - **`prototype`** runs a prototype in the chat: the page the platform stored for `timelineId` (the `contextId` the `prototype` skill uploaded under — any timeline of that context works too), in a sandboxed iframe with **Restart** (empty event log) and **Full screen** (the same player as the timeline's ▶). Send it only after `upload` succeeded — before that it shows "No prototype has been built for this yet". The `text` is the short report of what was built; the prototype itself is the snippet.
 - A snippet is shown exactly as you send it — keep secrets and tokens out of `code` and `image`.