@eventmodelers/cli 1.0.72 → 1.0.73

package/README.md

@@ -38,6 +38,16 @@ npx @eventmodelers/cli init --stack node
 
 Answer the credential prompts once — the stack's scaffold, skills, and agent loop are all installed in this one step.
 
+**Trying it out before you have a board of your own:**
+
+```bash
+npx @eventmodelers/cli init --stack node --demo
+```
+
+`--demo` additionally writes a ready-made model into the kit's `.slices/` — the **Understanding Eventsourcing** context, a 16-slice shopping cart covering every slice type (state change, state view, automation, translation). It's ordinary fetched slice data in exactly the shape `fetch` writes, so the build skills, `activate-context`, `set-slice-status`, and the agent loop all work against it immediately, with no board connected. Build one with `/build-state-change` in Claude Code, or start `run` and let the agent work the queue.
+
+Nothing downstream treats it specially: `fetch --context <name>` replaces it with your own board whenever you're ready. `--demo` is skipped (with a message) if `.slices/` already holds slices, so it can never overwrite fetched work.
+
 **Already initialized — you just want the agent to start working the board:**
 
 ```bash
@@ -71,7 +81,8 @@ your-project/
 │   ├── ralph-claude.js            ← realtime agent + task loop
 │   ├── ralph-ollama.js            ← same, via local Ollama
 │   ├── ralph.sh                   ← bash-only loop (no realtime)
-│   └── lib/                       ← stack-specific agent prompts + helpers
+│   ├── lib/                       ← stack-specific agent prompts + helpers
+│   └── .slices/                   ← board slices, written by `fetch`/`listen` (or pre-seeded by `init --demo`)
 ├── .claude/
 │   └── skills/                    ← eventmodelers skills for Claude Code
 ├── src/ … (or the stack's own layout)
@@ -111,6 +122,7 @@ Which skills install depends on the chosen stack — see `stacks/<name>/template
 
 ```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 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 --ollama                 # same, via local Ollama (ralph-ollama.js)
@@ -130,7 +142,7 @@ npx @eventmodelers/cli config                       # print the fully resolved c
 
 `run` is a thin dispatcher — it just finds the installed kit dir (whatever it's named for the stack) and execs the runner file already sitting in it. The agent loop's actual logic stays in the scaffolded `<kit-dir>/`, not in this package, since you (and the agent itself, via `AGENT.md`) may customize those files per project.
 
-`fetch` calls `slicedata?contextName=<name>` for the required `--context` (full slice detail — commands/events/readmodels/screens/processors/specifications/comments), and writes `.slices/<context>/<slice>/slice.json`, `index.json`, and `context.json`. It does not fetch screen images (those only arrive via `listen`'s push, see Power users). Unlike every other command, `fetch` also works with no kit installed at all — it only needs credentials, not kit-specific files. If credentials are missing, it prompts the same way `init-config` does. `--slice-id`/`--slice-title` still fetch and persist the whole context, then just print the one slice you asked about.
+`fetch` calls `slicedata?contextName=<name>` for the required `--context` (full slice detail — commands/events/readmodels/screens/processors/specifications/comments), and writes `.slices/<context>/<slice>/slice.json`, `index.json`, and `context.json`. It does not fetch screen images (those only arrive via `listen`'s push, see Power users). Unlike every other command, `fetch` also works with no kit installed at all — it only needs credentials, not kit-specific files. If credentials are missing, it prompts the same way `init-config` does. `--slice-id`/`--slice-title` still fetch and persist the whole context, then just print the one slice you asked about. `init --demo` seeds that same `.slices/` layout from a bundled example context instead of from a board, for trying the kit out before connecting one.
 
 ---
 
@@ -284,10 +296,10 @@ windows if the defaults don't suit your board:
 
 | Env var | Default | What it controls |
 |---|---|---|
-| `EVENTMODELERS_STANDALONE_DEBOUNCE_MS` | `8000` | quiet period before buffered board changes turn into a turn |
+| `EVENTMODELERS_STANDALONE_DEBOUNCE_MS` | `2500` | quiet period before buffered board changes turn into a turn — long enough to coalesce one gesture (a placement, a drag) into a single turn |
 | `EVENTMODELERS_STANDALONE_MAX_WAIT_MS` | `90000` | cap on that quiet period, so a board being edited continuously still gets a turn |
-| `EVENTMODELERS_STANDALONE_ECHO_WINDOW_MS` | `20000` | after a turn, how long an *unattributed* incoming change is labelled as probably the agent's own echo (attributed ones are identified outright) |
-| `EVENTMODELERS_STANDALONE_MIN_INTERVAL_MS` | `60000` | floor between two self-directed turns |
+| `EVENTMODELERS_STANDALONE_ECHO_WINDOW_MS` | `0` (off) | after a turn, how long an *unattributed* incoming change is labelled as probably the agent's own echo. Off because every event carries `agent_id`/`user_id`, which answers the same question exactly and costs no delay; set it only on a backend whose writes arrive unattributed (the run log names the origin of every change) |
+| `EVENTMODELERS_STANDALONE_MIN_INTERVAL_MS` | `60000` | floor between two self-directed turns — a runaway-loop guard, so a change written from a browser session skips it (a person is not a loop; another agent's write still waits) |
 | `EVENTMODELERS_STANDALONE_BACKOFF_CAP_MS` | `900000` | ceiling that floor doubles up to while turns keep answering `NOOP` |
 | `EVENTMODELERS_STANDALONE_IDLE_MS` | `900000` | with nothing happening at all, how long before the agent reviews the model anyway (`0` disables it) |
 
@@ -541,6 +553,8 @@ npx @eventmodelers/cli uninstall --modeling-kit      # remove .agent-modeling-ki
 
 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.
 
+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).
+
 Once your `init --build-kit` scaffold (see above) works against a real backend, promote it to a first-class stack:
 
 1. Copy `.build-kit/` → `stacks/<name>/templates/build-kit/`, `.claude/skills/build-*` → `stacks/<name>/templates/.claude/skills/`, and whatever `root/` scaffold you built → `stacks/<name>/templates/root/`.

package/RELEASE_NOTES.md

@@ -1,3 +1,8 @@
+## v1.0.72
+
+### Features
+- `init --demo` seeds the kit's `.slices/` with a ready-made model — the "Understanding Eventsourcing" context, a 16-slice shopping cart covering every slice type — so the `build-*` skills, `activate-context`, `set-slice-status`, and the agent loop all have something real to work on before the project is connected to a board. It is a verbatim `fetch --format json` tree, so nothing downstream has a demo-only path and a later `fetch --context <name>` simply replaces it. Skipped with a message when `.slices/` already holds fetched slices, so it can never overwrite real board state. Works with every install mode (`--stack`, `--modeling`, `--build-kit`, `--bridge`, `--git`); modeling-kit gets it at the project root, matching where `fetch` writes for that kit.
+
 ## v1.0.56
 
 ### Features

package/cli.js

@@ -176,6 +176,11 @@ const BLANK_BUILD_KIT = {
 
 const KIT_DIR_NAMES = [...new Set([...Object.values(STACKS), MODELING_KIT, BRIDGE_KIT, BLANK_BUILD_KIT].map((s) => s.kitDirName))];
 
+// What `init --demo` installs, for the messages it prints. Kept in step with
+// shared/demo-slices/ (context.json's name, and the slice folders beside it).
+const DEMO_CONTEXT_NAME = 'Understanding Eventsourcing';
+const DEMO_SLICE_COUNT = 16;
+
 // Same principle Playwright MCP uses per harness: one shared server, but each coding
 // agent has its own registration mechanism. Automate the ones with a real, verified
 // CLI install command; for the rest, print manual steps instead of guessing at an
@@ -1009,6 +1014,14 @@ async function installStack(stackKey, stackCfg, options = {}) {
       }
     }
 
+    // --- 3c. Opt-in demo model (`init --demo`) ---
+    // After the kit dir exists (the .slices/ tree nests inside it for every kit but
+    // modeling-kit) and before npm install/credentials, so the "demo installed" line
+    // lands with the rest of the file copying rather than after a credential prompt.
+    if (options.demo) {
+      installDemoSlices({ kitDir, targetDir, stackCfg });
+    }
+
     // --- 4. Install kit dependencies ---
     // modeling-kit's package.json has no dependencies at all — it exists purely for its
     // `"type": "module"`, so lib/config.js can be ESM-imported. Running npm for that buys
@@ -1281,6 +1294,46 @@ async function configureMcp(options = {}) {
 // standalone `init-hooks` command so all three copy/chmod/git-config identically
 // instead of drifting apart — callers are responsible for checking `hooksSrc`
 // exists first, since what "no template for this stack" means differs per caller.
+// `init --demo` — drop a ready-made .slices/ tree into the install so the build
+// skills (and `activate-context`/`slice-status`/the agent loop) have something real
+// to work on before the project is ever connected to a board. The tree under
+// shared/demo-slices/ is a verbatim `fetch --format json` output for the
+// "Understanding Eventsourcing" context (a 16-slice shopping-cart model, every slice
+// type represented), so it is byte-identical in shape to what a real fetch writes —
+// a later `fetch` just overwrites it, and nothing downstream needs a demo-only path.
+//
+// The destination mirrors `fetch`'s own resolution exactly (see the SLICES_DIR comment
+// there): nested under the kit dir for every kit whose code-export.mjs hardcodes
+// `.slices/` next to itself, and at the project root for modeling-kit, which has no
+// code-export.mjs and no skill reading a nested copy.
+function installDemoSlices({ kitDir, targetDir, stackCfg }) {
+  const slicesDir = stackCfg.kitDirName === MODELING_KIT.kitDirName
+    ? join(targetDir, '.slices')
+    : join(kitDir, '.slices');
+  const rel = relative(targetDir, slicesDir) || '.slices';
+
+  // An existing .slices/ is fetched board state — the user's real model. The copy
+  // below merges rather than replaces, so installing over it would leave a half-demo,
+  // half-real tree with a current_context.json pointing at the wrong one. Refuse
+  // instead. Deliberately not overridable by --force: that flag means "don't re-ask
+  // about credentials", never "discard fetched work".
+  if (existsSync(slicesDir) && readdirSync(slicesDir).length > 0) {
+    console.log(`  ℹ️  --demo skipped — ${rel}/ already has slices in it (delete it first if you really want the demo model)`);
+    return;
+  }
+
+  const demoSrc = join(__dirname, 'shared', 'demo-slices');
+  if (!existsSync(demoSrc)) {
+    console.log('  ℹ️  --demo was given but this CLI build ships no shared/demo-slices/ — nothing to install');
+    return;
+  }
+
+  console.log('📦 Installing the demo model...');
+  copyDirContents(demoSrc, slicesDir);
+  console.log(`  ✓ Demo context "${DEMO_CONTEXT_NAME}" (${DEMO_SLICE_COUNT} slices) is active in ${rel}/`);
+  console.log('  ℹ️  It is ordinary fetched slice data — `fetch --context <name>` replaces it with your own board whenever you are ready');
+}
+
 function configureHooks({ hooksSrc, targetDir }) {
   copyDirContents(hooksSrc, join(targetDir, '.githooks'));
   const preCommitHook = join(targetDir, '.githooks', 'pre-commit');
@@ -1890,11 +1943,17 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
   }
 
   // A standalone session is long-lived and spends most of its life waiting, so the setup
-  // every turn needs — read CLAUDE.md, run /connect, read the board — is done once at
-  // startup instead of being paid by whoever happens to send the first prompt. By the time
-  // a real turn arrives the credentials are resolved and the board picture is in context,
-  // and the turn is straight into the work. It reads only: nothing is placed, no prompt
-  // status is touched (there is no prompt_id here), no subagent is dispatched.
+  // every turn needs — read CLAUDE.md, run /connect, find out which chapters exist — is done
+  // once at startup instead of being paid by whoever happens to send the first prompt. By the
+  // time a real turn arrives the credentials are resolved and the turn is straight into the
+  // work. It reads only: nothing is placed, no prompt status is touched (there is no prompt_id
+  // here), no subagent is dispatched.
+  //
+  // What it deliberately does *not* do is read the board. Reading every chapter up front cost a
+  // minute and a dollar before anyone had asked for anything, on a board where a turn typically
+  // touches one chapter — and it front-loaded the context every later turn then carries. Chapters
+  // are read lazily instead: the first turn with business in one fetches its outline and keeps it
+  // for the rest of the session, so the cost is paid once and only for chapters that see work.
   const WARM_UP_TASK =
     'This is the session warm-up, before any prompt or board change — nobody has asked for anything yet, and ' +
     'there is nothing to sanitize, no prompt_id and no progress entry. Do exactly this and then stop: ' +
@@ -1902,11 +1961,13 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
     'one-time reads for this session — do NOT read .agent-modeling-kit/CLAUDE-STANDALONE.md, that one still ' +
     'waits for the first self-directed turn; (2) invoke /connect with the credentials above and ' +
     `board=${cfg.boardId} — this is the session's one-time connect, so no later turn runs it again; ` +
-    '(3) orient yourself on the board: one get_board_outline per chapter (or get_nodes with ' +
-    'projection: "line"), and keep what comes back as this session\'s board picture — chapters, columns, ' +
-    'elements, slice statuses — so the first real turn starts from it instead of re-reading the board. ' +
-    'Change nothing: no nodes, no comments, no slice statuses, no subagents. Reply <promise>READY</promise> ' +
-    'with a one-line summary of the board (chapters, rough element count, slice statuses).';
+    '(3) learn which chapters exist, and nothing beyond that: one get_chapter_bounds call returns every ' +
+    'chapter\'s id and title. Do NOT read any chapter\'s contents here — no get_board_outline, no ' +
+    'per-chapter get_nodes, and skip the board read /connect Step 5 would otherwise have you do. A chapter ' +
+    'is read on the first turn that actually has business in it, and kept for the rest of the session ' +
+    'from then on. Change nothing: no nodes, no comments, no slice statuses, no subagents. Reply ' +
+    '<promise>READY</promise> with the chapter list — titles and how many; say nothing about what is in ' +
+    'them, you have not looked.';
 
   function buildWarmUpTurn() {
     const header = ['SESSION_START', `board_id=${cfg.boardId}`, `organization_id=${cfg.organizationId}`].join(' ');
@@ -1918,7 +1979,7 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
   function warmUpSession() {
     if (warmUp) return warmUp;
     if (!standalone) return (warmUp = Promise.resolve());
-    log('warm-up: connecting and reading the board before the first turn');
+    log('warm-up: connecting and listing chapters before the first turn (chapters are read on first use)');
     warmingUp = true;
     warmUp = sendTurn(buildWarmUpTurn())
       .then((result) => log(`warm-up done — ${oneLine(result, 200) || 'session ready'}`))
@@ -2050,7 +2111,15 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
   // org prompt queue, so the non-standalone case joins it too and simply throws every
   // event away (see onBoardEvent). One code path either way — and whatever the backend
   // later adds to these payloads lands here without a client change.
-  const BOARD_CHANGE_EVENTS = ['node:created', 'node:changed', 'node:deleted', 'edge:added', 'edge:removed', 'board:cleared'];
+  //
+  // The edge events are deliberately *not* in this list. An edge is almost never a change
+  // on its own: placing an element auto-connects it to its neighbours, so `edge:added`
+  // arrives as the tail of a `node:created` this loop already woke up for — the same
+  // gesture counted twice, and counted onto `(board)` rather than onto a node, since an
+  // edge payload names no single node to go look at. Wiring an existing chain by hand says
+  // nothing about the model's content either. Subscribing to them bought a second turn per
+  // placement and nothing else, so board changes here mean node changes.
+  const BOARD_CHANGE_EVENTS = ['node:created', 'node:changed', 'node:deleted', 'board:cleared'];
 
   // Four knobs. They govern *when* a self-directed turn fires — never whether an event is
   // remembered: everything that arrives is buffered (see onBoardEvent), so a burst that
@@ -2068,10 +2137,17 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
   //   ECHO_WINDOW  — how long after a turn its own writes are expected back; an
   //                  *unattributed* change in that window is labelled a possible echo, and
   //                  the next turn waits it out so a write and its echo don't each get one.
+  //                  Off by default: it predates the `agent_id` above, which answers the same
+  //                  question exactly and for free, and every turn paid its delay to cover a
+  //                  residue of unattributed writes that a stamping backend never produces.
+  //                  Set it (ms) on a backend where the logs below do show unattributed
+  //                  changes.
   //   MIN_INTERVAL — a floor between self-directed turns, so a mistake upstream can't
   //                  become a self-feeding loop burning tokens unattended. Doubles per
   //                  consecutive NOOP up to BACKOFF_CAP, and resets as soon as a turn
-  //                  actually does something.
+  //                  actually does something. A person's edit is exempt (see
+  //                  dispatchStandaloneTurn): a human cannot be the loop, and waiting a
+  //                  minute before reacting to them is the whole latency complaint.
   //   IDLE         — with nothing at all happening on the board, how long before the agent
   //                  looks the model over anyway (a BOARD_REVIEW turn). 0 disables it, and
   //                  it answers to the same MIN_INTERVAL backoff, so a board with nothing
@@ -2080,18 +2156,22 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
     const raw = Number(process.env[name]);
     return Number.isFinite(raw) && raw >= 0 ? raw : fallback;
   };
-  const STANDALONE_DEBOUNCE_MS = envMs('EVENTMODELERS_STANDALONE_DEBOUNCE_MS', 8_000);
+  const STANDALONE_DEBOUNCE_MS = envMs('EVENTMODELERS_STANDALONE_DEBOUNCE_MS', 2_500);
   const STANDALONE_MAX_WAIT_MS = envMs('EVENTMODELERS_STANDALONE_MAX_WAIT_MS', 90_000);
-  const STANDALONE_ECHO_WINDOW_MS = envMs('EVENTMODELERS_STANDALONE_ECHO_WINDOW_MS', 20_000);
+  const STANDALONE_ECHO_WINDOW_MS = envMs('EVENTMODELERS_STANDALONE_ECHO_WINDOW_MS', 0);
   const STANDALONE_MIN_INTERVAL_MS = envMs('EVENTMODELERS_STANDALONE_MIN_INTERVAL_MS', 60_000);
   const STANDALONE_BACKOFF_CAP_MS = envMs('EVENTMODELERS_STANDALONE_BACKOFF_CAP_MS', 15 * 60_000);
   const STANDALONE_IDLE_MS = envMs('EVENTMODELERS_STANDALONE_IDLE_MS', 15 * 60_000);
 
-  // node_id (or '(board)') -> { types: Set<string>, count, own, other, maybe } for
+  // node_id (or '(board)') -> { types: Set<string>, count, own, other, maybe, person } for
   // everything seen since the last self-directed turn, each event counted into exactly one
   // origin bucket: `own` = attributed to this agent's own id, `other` = attributed to a human
   // or another agent, `maybe` = carries no attribution at all and landed inside the echo
   // window, so it *might* be this agent's. Only `maybe` is a guess.
+  // `person` counts, alongside the bucket, the subset of `other` written from a browser
+  // session rather than by another agent. It is what lets a human's edit skip the
+  // MIN_INTERVAL floor: a person cannot be this agent's feedback loop, whereas two agents on
+  // one board can ping-pong, so another agent's write keeps waiting its turn.
   const observed = new Map();
   let observedCount = 0;
   let seqLo = null;
@@ -2144,10 +2224,12 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
             ? 'maybe'
             : 'other';
     const nodeId = payload?.node_id ?? '(board)';
-    const entry = observed.get(nodeId) ?? { types: new Set(), count: 0, own: 0, other: 0, maybe: 0 };
+    const entry = observed.get(nodeId) ?? { types: new Set(), count: 0, own: 0, other: 0, maybe: 0, person: 0 };
     entry.types.add(type);
     entry.count += 1;
     entry[origin] += 1;
+    // A browser session id and no agent id: a human at the canvas.
+    if (writerUser && !writerAgent) entry.person += 1;
     observed.set(nodeId, entry);
     observedCount += 1;
     if (!firstObservedAt) firstObservedAt = Date.now();
@@ -2220,9 +2302,11 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
     'best target for them, not a reason to wait, and the board was already quiet before this turn was ' +
     'handed to you. Only board-wide sweeps and structural moves (renames, deletions, re-shaping, slice ' +
     'statuses) get a comment first instead of being done. An unanswered question you posted earlier parks ' +
-    'that one sweep, never the fill-in work. Read the board in two calls, not twenty: every nodeId above in one ' +
-    'get_nodes, the area around them in one get_board_outline per chapter, and a full-meta read only on the nodes ' +
-    'you conclude you will actually touch. You do the analysis: look at every entry above, decide what ' +
+    'that one sweep, never the fill-in work. Read what this turn needs and no more: every nodeId above in one ' +
+    'get_nodes, plus one get_board_outline for each chapter they land in that you have not already read this ' +
+    'session — a chapter you already hold is not fetched again, you carry it forward and apply this turn\'s ' +
+    'changes to your copy. A full-meta read only on the nodes you conclude you will actually touch. ' +
+    'You do the analysis: look at every entry above, decide what ' +
     'actually needs doing, and then work in parallel rather than serially — dispatch one Agent per piece of ' +
     'work that needs doing, all in a single message, merging pieces that share a slice or chain so no two ' +
     `agents write to the same area. ${AGENT_BUDGET} Read .agent-modeling-kit/CLAUDE-STANDALONE.md now (once ` +
@@ -2306,12 +2390,20 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
       else armStandaloneTurn(nextDelayMs());
       return;
     }
+    // The floor is a runaway-loop guard, and a person is not a loop. Making a human wait out
+    // MIN_INTERVAL before their edit is even looked at is most of the delay they feel, and it
+    // guards nothing: the loop it exists to stop is this agent (or another one) reacting to a
+    // write and writing again, which `person` excludes by construction.
+    const byPerson = !idle && [...observed.values()].some((entry) => entry.person > 0);
     const waitLeft = minIntervalMs() - (Date.now() - lastStandaloneAt);
-    if (lastStandaloneAt && waitLeft > 0) {
+    if (lastStandaloneAt && waitLeft > 0 && !byPerson) {
       if (idle) armIdleReview();
       else armStandaloneTurn(waitLeft);
       return;
     }
+    if (byPerson && lastStandaloneAt && waitLeft > 0) {
+      log(`standalone floor skipped: a person edited the board (${Math.round(waitLeft / 1000)}s of min-interval left)`);
+    }
     const text = idle ? buildIdleReviewTurn() : buildStandaloneTurn();
     if (idle) {
       log(`standalone review turn: board quiet for ${Math.round(STANDALONE_IDLE_MS / 1000)}s`);
@@ -2533,6 +2625,7 @@ credentialFlags(program
   .option('--hook <command>', 'Persist a default shell command hook for `bridge` to run per batch of slice changes instead of Claude/Ollama (e.g. commit + push .slices/ for a CI pipeline to pick up) — only meaningful with --bridge. Can also be set per-run with `bridge --hook`.')
   .option('--build-kit', 'Install a blank build-kit scaffold (.build-kit/ + .claude/skills/build-*/SKILL.md placeholders, all TODO-marked) for a stack not built into this CLI yet — no fixed backend. Mutually exclusive with --stack/--modeling/--bridge.')
   .option('--hooks', 'Install the slice commit-scope guard (.githooks/pre-commit, running .build-kit/lib/check-commit-scope.cjs) and wire it up via `git config core.hooksPath .githooks` — only meaningful with --stack (build-kit stacks). Off by default.')
+  .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))
@@ -2554,6 +2647,7 @@ credentialFlags(program
         global: opts.global,
         force: opts.force,
         credentialOverrides: { ...credentialOverridesFromOpts(opts), ...identityOverridesFromOpts(opts) },
+        demo: opts.demo,
       });
       return;
     }
@@ -2565,6 +2659,7 @@ credentialFlags(program
         global: opts.global,
         force: opts.force,
         credentialOverrides: { ...credentialOverridesFromOpts(opts), ...identityOverridesFromOpts(opts) },
+        demo: opts.demo,
       });
       return;
     }
@@ -2584,6 +2679,7 @@ credentialFlags(program
         global: opts.global,
         force: opts.force,
         credentialOverrides: { ...credentialOverridesFromOpts(opts), ...identityOverridesFromOpts(opts) },
+        demo: opts.demo,
         target: opts.target,
       });
       // Deliberately NOT under .bridge-kit/.eventmodelers/ — that whole name is
@@ -2622,6 +2718,7 @@ credentialFlags(program
         global: opts.global,
         force: opts.force,
         credentialOverrides: { ...credentialOverridesFromOpts(opts), ...identityOverridesFromOpts(opts) },
+        demo: opts.demo,
         templatesSource: join(clonedDir, 'templates'),
         hooks: opts.hooks,
       });
@@ -2635,6 +2732,7 @@ credentialFlags(program
       global: opts.global,
       force: opts.force,
       credentialOverrides: { ...credentialOverridesFromOpts(opts), ...identityOverridesFromOpts(opts) },
+        demo: opts.demo,
       hooks: opts.hooks,
     });
   });

package/package.json

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

package/shared/demo-slices/Understanding Eventsourcing/additem/slice.json

@@ -0,0 +1,176 @@
+{
+  "id": "6829844f-fbb5-41ab-b948-fdef54c7e9c1",
+  "status": "Planned",
+  "title": "Add Item",
+  "context": "Understanding Eventsourcing",
+  "sliceType": "STATE_CHANGE",
+  "commands": [
+    {
+      "id": "75ed140d-12c0-44f9-bf81-c2fa4886cf9d",
+      "tags": [],
+      "lane": "Interaction",
+      "modelContext": "Understanding Eventsourcing",
+      "slice": "Add Item",
+      "title": "Add Item",
+      "fields": [
+        {
+          "name": "aggregateId",
+          "type": "UUID",
+          "example": "",
+          "mapping": "",
+          "optional": false,
+          "subfields": [],
+          "cardinality": "Single",
+          "idAttribute": false
+        },
+        {
+          "name": "description",
+          "type": "String",
+          "example": "",
+          "mapping": "",
+          "optional": false,
+          "subfields": [],
+          "cardinality": "Single",
+          "idAttribute": false
+        },
+        {
+          "name": "image",
+          "type": "String",
+          "example": "",
+          "mapping": "",
+          "optional": false,
+          "subfields": [],
+          "cardinality": "Single",
+          "idAttribute": false
+        },
+        {
+          "name": "price",
+          "type": "Double",
+          "example": "",
+          "mapping": "",
+          "optional": false,
+          "subfields": [],
+          "cardinality": "Single",
+          "idAttribute": false
+        },
+        {
+          "name": "itemId",
+          "type": "UUID",
+          "example": "",
+          "mapping": "",
+          "optional": false,
+          "subfields": [],
+          "cardinality": "Single",
+          "idAttribute": false
+        },
+        {
+          "name": "productId",
+          "type": "UUID",
+          "example": "",
+          "mapping": "",
+          "optional": false,
+          "subfields": [],
+          "cardinality": "Single",
+          "idAttribute": false
+        }
+      ],
+      "type": "COMMAND",
+      "description": "",
+      "aggregate": "default",
+      "aggregateDependencies": [],
+      "dependencies": [
+        {
+          "id": "a39b1e41-7b38-42b1-8ad3-c9cc18ca2f7c",
+          "type": "OUTBOUND",
+          "title": "Cart Created",
+          "elementType": "EVENT"
+        },
+        {
+          "id": "544d0a8c-809c-4670-a9d9-aa8259f43c46",
+          "type": "OUTBOUND",
+          "title": "Item Added",
+          "elementType": "EVENT"
+        }
+      ],
+      "apiEndpoint": "",
+      "createsAggregate": false,
+      "triggers": [],
+      "elementCopy": false,
+      "linkedId": "75ed140d-12c0-44f9-bf81-c2fa4886cf9d",
+      "sketched": false,
+      "prototype": {
+        "activeByDefault": false
+      },
+      "comments": []
+    }
+  ],
+  "events": [
+    {
+      "id": "a39b1e41-7b38-42b1-8ad3-c9cc18ca2f7c",
+      "tags": [],
+      "lane": "Events",
+      "modelContext": "Understanding Eventsourcing",
+      "slice": "Add Item",
+      "title": "Cart Created",
+      "fields": [
+        {
+          "name": "aggregateId",
+          "type": "UUID",
+          "example": "",
+          "mapping": "",
+          "optional": false,
+          "subfields": [],
+          "cardinality": "Single",
+          "idAttribute": false
+        }
+      ],
+      "type": "EVENT",
+      "description": "",
+      "aggregate": "default",
+      "aggregateDependencies": [],
+      "dependencies": [
+        {
+          "id": "22511305-2296-43ba-b8e8-d786d53cd25f",
+          "type": "OUTBOUND",
+          "title": "Carts with Products",
+          "elementType": "READMODEL"
+        },
+        {
+          "id": "631c5aa8-0f9e-4a8f-b7f6-91174cae2b82",
+          "type": "OUTBOUND",
+          "title": "cart items",
+          "elementType": "READMODEL"
+        },
+        {
+          "id": "75ed140d-12c0-44f9-bf81-c2fa4886cf9d",
+          "type": "INBOUND",
+          "title": "Add Item",
+          "elementType": "COMMAND"
+        }
+      ],
+      "apiEndpoint": "",
+      "createsAggregate": false,
+      "triggers": [],
+      "elementCopy": false,
+      "linkedId": "a39b1e41-7b38-42b1-8ad3-c9cc18ca2f7c",
+      "sketched": false,
+      "prototype": {
+        "activeByDefault": false
+      },
+      "comments": []
+    }
+  ],
+  "readmodels": [],
+  "screens": [],
+  "screenImages": [],
+  "screenLayouts": [],
+  "processors": [],
+  "tables": [],
+  "specifications": [],
+  "storylines": [],
+  "chapter": "Understanding Eventsourcing",
+  "codeGen": {},
+  "notes": [],
+  "comments": [],
+  "aggregates": []
+}