@eventmodelers/cli 1.0.72 → 1.0.74

package/README.md

@@ -18,7 +18,6 @@ Running without `--stack` shows an arrow-key picker. Or go straight to a stack:
 npx @eventmodelers/cli init --stack node            # Node.js / TypeScript
 npx @eventmodelers/cli init --stack supabase         # Supabase
 npx @eventmodelers/cli init --stack axon             # Axon Framework (Java/Kotlin)
-npx @eventmodelers/cli init --stack cratis-csharp    # Cratis (.NET/C#)
 npx @eventmodelers/cli init --stack opencqrs         # OpenCQRS (Java, EventSourcingDB)
 npx @eventmodelers/cli init --stack umadb            # UmaDB (Java)
 npx @eventmodelers/cli init --stack kurrent          # Kurrent (Java, KurrentDB)
@@ -38,6 +37,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,14 +80,15 @@ 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)
 └── CLAUDE.md                      ← agent instructions
 ```
 
-The seven backend stacks (`node`, `supabase`, `axon`, `cratis-csharp`, `opencqrs`, `umadb`, `kurrent`) also scaffold a real project skeleton into your project root (`templates/root/`) — source layout, build files, migrations, etc.
+The six backend stacks (`node`, `supabase`, `axon`, `opencqrs`, `umadb`, `kurrent`) also scaffold a real project skeleton into your project root (`templates/root/`) — source layout, build files, migrations, etc.
 
 `react` and `supabase-react` are two more registered stacks (installable the same way). `supabase-react` is real, filled-in content — a Vite + React 19 + TypeScript scaffold that authenticates and issues command POSTs via a Supabase session (`src/lib/api.ts`/`src/lib/supabase.ts`), plus `init-style-guide`/`learn-styleguide` skills so generated UI stays on-brand. It's UI-only: `.build-kit/CLAUDE.md` only routes `STATE_CHANGE`/`STATE_VIEW` slices to `build-state-change`/`build-state-view` — an `AUTOMATION` slice has no UI counterpart and gets flagged via `request-feedback` instead, since it belongs to whichever backend stack is installed alongside this one. It needs no overrides at all and uses `shared/build-kit`'s realtime agent as-is.
 
@@ -111,6 +121,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 +141,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.
 
 ---
 
@@ -150,11 +161,19 @@ npx @eventmodelers/cli init --build-kit              # blank build-kit scaffold
 **Building a new kit for an unsupported stack:**
 
 ```bash
-npx @eventmodelers/cli init --build-kit
+npx @eventmodelers/cli init --build-kit --demo
 ```
 
 This scaffolds `.build-kit/CLAUDE.md`, `lib/prompt.md`, `lib/backend-prompt.md`, and the `build-*` skills with TODO placeholders instead of real content. Fill in the TODOs against the actual stack you're integrating (build/test commands, file layout, framework idioms) while building something real with it, then follow "Adding a stack" below to promote it to a first-class stack once it works.
 
+`--demo` is what gives you something to build *against* while you do that: it seeds the kit's `.slices/` with the ready-made 16-slice **Understanding Eventsourcing** model (see "Trying it out before you have a board of your own" above), so you don't need a board, credentials, or a connected project to exercise the kit you're writing. With it in place the whole loop is:
+
+```bash
+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.
+
 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`
@@ -284,10 +303,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 +560,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

@@ -63,13 +63,6 @@ const STACKS = {
     useShared: true,
     needsBoardId: true,
   },
-  'cratis-csharp': {
-    label: 'Cratis (.NET/C#)',
-    kitSubdir: 'build-kit',
-    kitDirName: '.build-kit',
-    useShared: true,
-    needsBoardId: true,
-  },
   opencqrs: {
     label: 'OpenCQRS (Java, EventSourcingDB)',
     kitSubdir: 'build-kit',
@@ -176,6 +169,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 +1007,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 +1287,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 +1936,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 +1954,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 +1972,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 +2104,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 +2130,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 +2149,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 +2217,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 +2295,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 +2383,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 +2618,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 +2640,7 @@ credentialFlags(program
         global: opts.global,
         force: opts.force,
         credentialOverrides: { ...credentialOverridesFromOpts(opts), ...identityOverridesFromOpts(opts) },
+        demo: opts.demo,
       });
       return;
     }
@@ -2565,6 +2652,7 @@ credentialFlags(program
         global: opts.global,
         force: opts.force,
         credentialOverrides: { ...credentialOverridesFromOpts(opts), ...identityOverridesFromOpts(opts) },
+        demo: opts.demo,
       });
       return;
     }
@@ -2584,6 +2672,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 +2711,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 +2725,7 @@ credentialFlags(program
       global: opts.global,
       force: opts.force,
       credentialOverrides: { ...credentialOverridesFromOpts(opts), ...identityOverridesFromOpts(opts) },
+        demo: opts.demo,
       hooks: opts.hooks,
     });
   });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.72",
-  "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, Cratis, OpenCQRS, UmaDB, Kurrent, or modeling-only)",
+  "version": "1.0.74",
+  "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": {
     "eventmodelers": "cli.js"

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": []
+}