@eventmodelers/cli 1.0.163 → 2.0.2

package/README.md

@@ -92,7 +92,6 @@ your-project/
 │   ├── ralph-claude.js            ← realtime agent + task loop
 │   ├── ralph-local-ai.js          ← same, via a local/self-hosted model
 │   ├── ralph-exec.js              ← same, via an external agent command (Codex CLI, OpenCode, …)
-│   ├── ralph.sh                   ← bash-only loop (no realtime)
 │   ├── lib/                       ← stack-specific agent prompts + helpers
 │   └── .slices/                   ← board slices, written by `fetch`/`listen` (or pre-seeded by `init --demo`)
 ├── .claude/
@@ -138,24 +137,40 @@ Use skills in Claude Code with `/skill-name`:
 
 Which skills install depends on the chosen stack — see `stacks/<name>/templates/.claude/skills/`. `/connect`, `/learn-eventmodelers-api`, `/update-slice-status`, and `/request-feedback` have no stack-specific content and install into every stack from `shared/skills/` instead.
 
+## `scaffold`: a runnable app from your board
+
+`scaffold <dir>` reads the board and generates an app skeleton around the build kits, so slice building starts from an app that already runs. `--type` picks what gets installed and generated:
+
+| Type | Installs | You get |
+|---|---|---|
+| `supabase` (default) | `supabase` at the root, `supabase-react` in `web/` | Supabase email/password sign-in, a layout with one navigation entry per timeline, a page shell per screen at `web/src/pages/<ScreenTitle>.tsx`, `501 Not Implemented` for every modeled endpoint without a slice (a built route always wins), a "not built yet" placeholder in the UI, hot reload for both halves, `npm run up` |
+
+Needs on the machine: Node 22, Docker, Supabase CLI, Flyway + Java (the command lists what is missing). The skeleton itself needs nothing beyond Node, on macOS, Linux and Windows: `npm run up` / `down` / `db:stop` / `user -- <email> <password>` / `check` all go through one plain script, `scripts/dev.mjs`. `<dir>` must be empty or new, or an earlier skeleton, which is refreshed from the current model — generated files are rewritten, pages and anything a builder wrote are kept. Titles come from the board verbatim; a screen's route comes only from a `route /orders` line in its description, the post-sign-in page from a "home page" line, and Bulma is used when the screen mockups use it. `--no-install` stops after generating, `--no-check` skips the checks; ports are picked free automatically and a refresh keeps them (`--port api=3200` pins one; repeatable).
+
+**Your own templates.** `npx @eventmodelers/cli init-templates [paths...]` copies the built-in templates into `./templates/` for you to edit (`--list` shows the paths; name a file such as `web/src/app/Layout.tsx` or a folder such as `web/src/app` to copy only those, and take only what you mean to change — a copied template stops following the CLI's updates; existing files are kept unless `--force`). `scaffold` uses what it finds there and the built-in template for everything else. Or put `*.tmpl` files in a `templates/` folder in the app's root (or point `--templates <dir>` at one, which also works on the first run). A file there replaces the built-in template at the same path — `templates/web/src/app/Layout.tsx.tmpl` replaces `web/src/app/Layout.tsx` — and a path with no built-in counterpart is simply added. The same tokens apply (`__APP_TITLE__`, `__API_PORT__`, `__WEB_PORT__`, `__DB_PORT__`), and every refresh uses them again, so customisations survive a model change. Only `*.tmpl` files count, so nothing in `templates/` is compiled as project code. Files the scaffold writes once (pages, `extraEndpoints.ts`) are never overwritten whatever you put there; edit those in place.
+
+The `supabase` skeleton generator is adapted from the em-scaffold skill by Adrian Mowat (MIT, `shared/scaffold/LICENSE-em-scaffold`).
+
 ## Everyday commands
 
 ```bash
 npx @eventmodelers/cli init --stack <name>          # scaffold a stack + install + configure (alias: install)
 npx @eventmodelers/cli init --stack <name> --demo   # same, plus a ready-made demo model in the kit's .slices/ to build against
+npx @eventmodelers/cli scaffold <dir> --type supabase  # app skeleton from the board (sign-in, navigation, a page per screen, 501 for unbuilt slices) + both kits installed, ready for `run`
 npx @eventmodelers/cli re-init                      # refresh an already-installed kit's scripts/skills only — never touches the root scaffold
 npx @eventmodelers/cli run                          # start the agent loop (ralph-claude.js) from the installed kit dir
+npx @eventmodelers/cli run --all                      # every build kit in the project at once (this directory and up to two levels below, e.g. a scaffolded app's root and web/), prefixed output, Ctrl+c stops all; other flags (--agent, --handover, …) go to each
+npx @eventmodelers/cli run --all --modeling           # the same, plus a modeling agent running alongside the build kits
 npx @eventmodelers/cli run --local-ai [target]      # board work only via a local/self-hosted model (ralph-local-ai.js) — does NOT build slices; build locally with --exec
 npx @eventmodelers/cli run --agent <name>           # pick the agent: claude (default), opencode, codex, gemini — bare --agent lists them with their exact commands
 npx @eventmodelers/cli run --agent <name> --model <id>  # …on a given model: -m for opencode/codex/gemini, --model for Claude, LOCAL_AI_MODEL for --local-ai
 npx @eventmodelers/cli run --exec "<command>"        # manual fallback for any other harness (ralph-exec.js) — agent tracing needs its JSON flag, e.g. "codex exec --json --full-auto"
-npx @eventmodelers/cli run --bash                   # bash-only loop, no realtime (ralph.sh)
 npx @eventmodelers/cli run --local                  # skip platform config/credential lookup entirely — local-only, no board sync
 npx @eventmodelers/cli run --modeling               # modeling-kit: warm Claude process driven by the board's prompt queue
 npx @eventmodelers/cli run --standalone             # same, plus acting on board changes unprompted — and needs no install at all
 npx @eventmodelers/cli run --standalone --board-id <uuid>  # …from any directory, against any board (see Power users)
 npx @eventmodelers/cli run --id <id> --name <label>  # override this run's agent identity (id + display name); `init --name` persists a name instead
-npx @eventmodelers/cli run --handover               # backend kit, this run only: finish slices that have a UI at `Handover` instead of `Done` (see Backend → UI handover)
+npx @eventmodelers/cli run --handover               # backend kit, this run only: finish slices that have a UI at `Waiting` instead of `Done` (see Backend → UI handover)
 npx @eventmodelers/cli config --handover on|off      # persist that choice for the project (`handover` in .eventmodelers/config.json)
 npx @eventmodelers/cli fetch --context <name>                     # pull full slice detail for one context on the board into <kit-dir>/.slices/
 npx @eventmodelers/cli fetch --context <name> --slice-id <id>     # same, then print just that slice
@@ -200,7 +215,7 @@ npx @eventmodelers/cli run --local
 
 and the agent starts building — `--local` skips platform config and credential lookup entirely, so it works straight out of `init` with nothing connected. Every TODO you fill in gets exercised on the next iteration against real slice data covering all four slice types (state change, state view, automation, translation), which is exactly the coverage a new stack's `build-*` skills need before it's worth promoting.
 
-**Backend → UI handover.** Besides the usual statuses a slice can be `Ready` (modeling done, waiting to be planned) and `Handover` (backend built, UI contract published, waiting for the UI kit). The flow is `Ready → Planned → InProgress → Handover → InProgress → Done`. Install with `init --handover` (or `re-init --handover`; switch later with `eventmodelers config --handover on|off`; for a single run `run --handover` overrides the setting without saving anything), which saves `"handover": true` in `.eventmodelers/config.json` — then a backend kit ends STATE_VIEW / STATE_CHANGE slices at `Handover` instead of `Done` (the `ui-contract` skill, Step 4, owns that rule); without the flag nothing changes: slices end at `Done`, exactly as before. A kit claims work from the status named in its `lib/kit.json` — `{ "pickupStatus": "Handover" }` for the `react` / `supabase-react` UI kits, absent (= `Planned`) for backend kits. A new UI kit ships that file and sets `Done` when its half is built; a new backend kit just invokes `ui-contract`. Needs a platform with the `Ready` / `Handover` statuses.
+**Backend → UI handover.** Besides the usual statuses a slice can be `Ready` (modeling done, waiting to be planned) and `Waiting` (backend built, UI contract published, waiting for the UI kit). The flow is `Ready → Planned → InProgress → Waiting → InProgress → Done`. Install with `init --handover` (or `re-init --handover`; switch later with `eventmodelers config --handover on|off`; for a single run `run --handover` overrides the setting without saving anything), which saves `"handover": true` in `.eventmodelers/config.json` — then a backend kit ends STATE_VIEW / STATE_CHANGE slices at `Waiting` instead of `Done` (the `ui-contract` skill, Step 4, owns that rule); without the flag nothing changes: slices end at `Done`, exactly as before. A kit claims work from the status named in its `lib/kit.json` — `{ "pickupStatus": "Waiting" }` for the `react` / `supabase-react` UI kits, absent (= `Planned`) for backend kits. A new UI kit ships that file and sets `Done` when its half is built; a new backend kit just invokes `ui-contract`. Needs a platform with the `Ready` / `Waiting` statuses.
 
 **UI contract (handover only).** With handover on, the scaffolded `build-state-view` / `build-state-change` skills end by invoking the shared `ui-contract` skill, which publishes each slice's read (`GET`) or write (`POST`) contract — the endpoint's OpenAPI operation, as a ```` ```yaml ui-contract ```` block — as a `## UI Contract` section in the slice's feedback-lane markdown node (exported in `slice.json` `notes[]`, so a UI build kit can look it up directly). Two things are yours to decide: *where the contract is derived from* (point the `UI Contract` section of those skills at your stack's machine-readable API description, if it has one — the `node`/`supabase` stacks use their `@openapi` blocks via a `ui-contract-from-openapi.md` reference, taking the operation verbatim — otherwise the skill writes the equivalent OpenAPI operation from the route code), and, if you need a different shape or location, a whole-skill override: ship `.claude/skills/ui-contract/SKILL.md` in the stack's templates and it replaces the shared one (stack templates are applied after `shared/skills/`).
 
@@ -210,7 +225,7 @@ Installing both a build stack and `init-modeling` into the same project reuses t
 
 A modeling-kit install has one runtime: a warm Claude process the CLI keeps alive across
 turns and feeds directly over stdin, so a prompt typed (or spoken) on the board is picked up
-with no cold start and no `tasks.json` round trip.
+with no cold start and no task-queue round trip.
 
 ```bash
 npx @eventmodelers/cli run --modeling               # react to prompts sent to this board
@@ -273,7 +288,7 @@ pass `--model <id>` as usual.
 
 Claude and Gemini need a gateway (e.g. LiteLLM) in front of a non-native server, since they only speak their own protocol.
 
-`--agent`, `--exec`, `--local-ai` and `--bash` each pick the runner, so pass at most one of them —
+`--agent`, `--exec` and `--local-ai` each pick the runner, so pass at most one of them —
 any two together are rejected. For a local or self-hosted model use `--local-ai`, not `--agent`.
 
 To drive either one with a local model instead of Claude, see [Running the modeling agent on a local model](#running-the-modeling-agent-on-a-local-model).
@@ -524,40 +539,37 @@ npx @eventmodelers/cli init-modeling --global
 
 Everything else (the kit dir, project scaffold, credentials, MCP registration) still targets the current directory as usual — `--global` only changes where skills land.
 
-### Bridging to another spec framework
+### Syncing a context to Spec Kitty
 
-If you drive development with a different spec/task framework (Spec Kitty today; more later) instead of build-kit's own code generation, a **bridge** kit keeps that framework's artifacts in sync with the board instead of writing application code:
+If you drive development with Spec Kitty instead of build-kit's own code generation, `fetch` can restate a context for it in one shot:
 
 ```bash
-npx @eventmodelers/cli init --bridge --target spec-kitty
-npx @eventmodelers/cli bridge
+npx @eventmodelers/cli fetch --context Ticketing --spec-kitty
 ```
 
-`init --bridge` installs a `.bridge-kit/` (mirrors `.build-kit/`'s realtime + task-queue loop) plus only the skills for the chosen `--target` (`shared/bridge/<target>/`) — a `spec-kitty` bridge never installs Kiro's skills, and vice versa. `bridge` starts the loop: on every board slice change (not just "Planned", unlike build-kit), it regenerates that framework's spec artifacts from the current board state. It doesn't build code and doesn't claim slices.
+That sync is deterministic and stops well short of writing Spec Kitty's own artifacts — `lib/adapters/spec-kitty-adapter.js` fetches full slice detail and restates it as a plain markdown mission brief (one section per slice, its scenarios verbatim, nothing invented), then calls `spec-kitty intake --force` to install it at `.kittify/mission-brief.md`. It deliberately doesn't create the mission, write `spec.md`, or author work packages — Spec Kitty's own `/spec-kitty.specify` → `/spec-kitty.plan` → `/spec-kitty.tasks` pipeline does that, because those steps need real judgment (work package boundaries, which files a WP owns, which agent profile fits) that only makes sense with actual codebase context, which this adapter doesn't have. What it replaces is Spec Kitty's *interactive discovery interview*: `/spec-kitty.specify`'s own "Brief Context Detection" step reads `.kittify/mission-brief.md` when present and extracts requirements from it instead of asking the user, so the event model — not a live Q&A — becomes the input. No LLM call happens in this adapter.
 
-For `spec-kitty`, that sync is deterministic and stops well short of writing Spec Kitty's own artifacts — `lib/adapters/spec-kitty-adapter.js` fetches full slice detail and restates it as a plain markdown mission brief (one section per slice, its scenarios verbatim, nothing invented), then calls `spec-kitty intake --force` to install it at `.kittify/mission-brief.md`. It deliberately doesn't create the mission, write `spec.md`, or author work packages — Spec Kitty's own `/spec-kitty.specify` → `/spec-kitty.plan` → `/spec-kitty.tasks` pipeline does that, because those steps need real judgment (work package boundaries, which files a WP owns, which agent profile fits) that only makes sense with actual codebase context, which this adapter doesn't have. What it replaces is Spec Kitty's *interactive discovery interview*: `/spec-kitty.specify`'s own "Brief Context Detection" step reads `.kittify/mission-brief.md` when present and extracts requirements from it instead of asking the user, so the event model — not a live Q&A — becomes the input. No LLM call happens in this adapter's own path, and `bridge` picks it automatically whenever a target has one (`--claude` forces the Claude runner instead). Targets without a static adapter yet fall back to Claude re-running `bridge-<target>-specify`; pass `--local-ai` for the local-model runner instead (same caveat as build-kit's `--local-ai`: `lib/local-ai-agent.js` is shared as-is).
+`spec-kitty init` (Spec Kitty's own project setup) has to have already been run in the project root — the adapter checks for `.kittify/` first and stops with the exact command to run if it's missing, rather than failing deep inside a cryptic `spec-kitty` CLI error. After the sync, run `/spec-kitty.specify` in your coding agent to turn the brief into an actual mission (the plain `spec-kitty specify` CLI command only scaffolds — brief detection is in the agent-driven prompt).
 
-Don't want the standing loop at all? `fetch` can call the same adapter for a single one-shot sync, no `.bridge-kit/` install required:
+(The standing bridge loop — `init --bridge` / `bridge` — is retired for now.)
 
-```bash
-npx @eventmodelers/cli fetch --context Ticketing --spec-kitty
-```
-
-Either way, `spec-kitty init` (Spec Kitty's own project setup) has to have already been run in the project root — the adapter checks for `.kittify/` first and stops with the exact command to run if it's missing, rather than failing deep inside a cryptic `spec-kitty` CLI error. After the sync, run `/spec-kitty.specify` in your coding agent to turn the brief into an actual mission (the plain `spec-kitty specify` CLI command only scaffolds — brief detection is in the agent-driven prompt).
+### Reading the event log
 
-### Overriding the executor with a hook
-
-Claude is only the default — some teams don't want an AI agent in this loop at all, e.g. they'd rather just commit + push the board export and let a CI pipeline own the actual translation. `--hook` replaces the AI executor with an arbitrary shell command, run once per batch of slice changes:
+Everything an agent does to a slice, a task, a prompt or a learning is an event in the kit's log (`.build-kit/events/` and `events.log`, or `.agent-modeling-kit/` for a modeling agent). `eventmodelers events` decodes it in the terminal — one line per event, with the slice's title and the first four characters of the agent that wrote it:
 
 ```bash
-npx @eventmodelers/cli init --bridge --target spec-kitty --hook "git add .slices && git commit -m sync && git push"
-npx @eventmodelers/cli bridge
+npx @eventmodelers/cli events                          # the build kit of this project, else its modeling kit
+npx @eventmodelers/cli events --type claimed,settled   # only these event types
+npx @eventmodelers/cli events --slice "Add item"       # a slice by id prefix or part of its title
+npx @eventmodelers/cli events --tag ci --last 20       # by tag; only the last 20 that remain
+npx @eventmodelers/cli events --state                  # what the log folds to: slices, queue, open prompts, learnings
+npx @eventmodelers/cli events --json                   # the raw events, one per line (pipe to jq)
+npx @eventmodelers/cli events --follow                 # keep printing as events are appended
+npx @eventmodelers/cli events --kit ../other/.build-kit   # another kit's log, from anywhere
+npx @eventmodelers/cli events --global                 # the global install's log (~/.eventmodelers/kit): what runs without a project install wrote
+npx @eventmodelers/cli events --global --board c2b3b7da   # that log mixes every board; --board keeps one (an id prefix)
 ```
 
-`init --bridge --hook` persists the command to `.bridge-kit/bridge.json` — a plain, **committed** file (unlike `.eventmodelers/config.json`, which is gitignored for credentials) since the hook is project policy meant to be shared by every teammate and CI runner, not per-machine state. `bridge --hook "<command>"` overrides it for a single run without touching that file. Only one executor runs per invocation — `--local-ai`, `--hook`, and `--claude` are mutually exclusive.
-
-The hook command runs with `BRIDGE_TASK_COUNT`, `BRIDGE_SLICE_ID`/`_TITLE`/`_STATUS` (the most recent change in the batch), and `BRIDGE_BATCH_FILE` (path to the full batch as JSON) in its environment. It's invoked once per batch, not once per slice — any change that arrives while the hook is still running is left queued for the next batch rather than dropped.
-
 ### Claude execution & config resolution
 
 During install you can optionally point the agent at a local LLM server instead of the default
@@ -630,7 +642,7 @@ npx @eventmodelers/cli init-config --name ci-builder     # name the agent this c
 
 ### Naming an agent
 
-Every agent identifies itself to the platform with an `agentId`, and the board's live-agent view shows that bare uuid. A **project install** mints one on first use and reuses it on every restart (`agentIds` in the project root's `.eventmodelers/config.json`). A **standalone/global run** mints a fresh one per run instead: nothing stops two ad-hoc agents running for one board, and since the heartbeat is keyed on `(token, agentId, agentType)`, a shared id would make the second agent replace the first — one agent visible however many are running, and their board writes indistinguishable.
+Every agent identifies itself to the platform with an `agentId`, and the board's live-agent view shows it. An agent keeps **one id**: a **project install** mints it on first use (`agentIds` in the project root's `.eventmodelers/config.json`), a **standalone/global run** keeps one per board and repo — the directory it is started in — in `~/.eventmodelers/agent-ids.json`. It is the same agent on every restart, with its chat sessions, its star on the board and the prompts it holds. Two live processes must not share an id (the heartbeat is keyed on `(token, agentId, agentType)`, so the second would replace the first, and its start-up recovery would hand back the first one's prompts), so each run takes a small lock on its id (`.eventmodelers/locks/` in the project, `~/.eventmodelers/locks/` globally); if another live process already holds it, this run gets a fresh id and, unless you named it, an instance-marked name (`cart-service (modeling) · 3f9a`). `--id` is used as given, with no such check — for a second agent on purpose, or a supervisor that knows the id it wants. Without a name an agent shows as `<repo> (<type>)`, the repo being the `origin` remote's name or the folder.
 
 `--name` gives an agent a readable label instead of the uuid — accepted by `init`, `re-init`, and `init-config`, saved into `config.json` as `agentName`, and sent with every heartbeat from then on:
 
@@ -657,7 +669,7 @@ Pair it with `--id`: a `--standalone`/`--global` run mints a fresh id per run, s
 
 ### Backend → UI handover (`--handover`)
 
-A slice with a UI is only finished once two kits have each built their half: the backend kit builds the endpoint and publishes its contract, the UI kit builds the frontend against it. `--handover` makes the first kit stop at `Handover` instead of `Done`, so the second one can claim the slice.
+A slice with a UI is only finished once two kits have each built their half: the backend kit builds the endpoint and publishes its contract, the UI kit builds the frontend against it. `--handover` makes the first kit stop at `Waiting` instead of `Done`, so the second one can claim the slice.
 
 ```bash
 npx @eventmodelers/cli init --stack node --handover   # persisted: "handover": true in .eventmodelers/config.json (also re-init)
@@ -668,18 +680,18 @@ npx @eventmodelers/cli run --handover                 # this run only — writes
 
 | | Handover off (default) | Handover on |
 |---|---|---|
-| Backend kit, STATE_VIEW / STATE_CHANGE slice | ends at `Done`, no UI contract published | publishes the UI contract, ends at `Handover` |
+| Backend kit, STATE_VIEW / STATE_CHANGE slice | ends at `Done`, no UI contract published | publishes the UI contract, ends at `Waiting` |
 | Backend kit, automation / translation | `Done` | `Done` — no UI counterpart |
-| UI kit (`react`, `supabase-react`) | claims `Handover` only | claims `Handover` only, sets `Done` when its UI is built |
+| UI kit (`react`, `supabase-react`) | claims `Waiting` only | claims `Waiting` only, sets `Done` when its UI is built |
 
-Flow: `Ready → Planned → InProgress → Handover → InProgress → Done`. Precedence for a run is `run --handover` over the project's `handover` setting; the runner states the effective value to the agent as a `Handover: on|off` line in its task, so the agent never has to work it out from `config.json`. `config --handover` writes to the project's config (the installed kit's project, else the nearest `.eventmodelers/config.json` up the tree — never the account-wide one in `~/`).
+Flow: `Ready → Planned → InProgress → Waiting → InProgress → Done`. Precedence for a run is `run --handover` over the project's `handover` setting; the runner states the effective value to the agent as a `Handover: on|off` line in its task, so the agent never has to work it out from `config.json`. `config --handover` writes to the project's config (the installed kit's project, else the nearest `.eventmodelers/config.json` up the tree — never the account-wide one in `~/`).
 
 **What to know before relying on it**
 
-- **UI kits only ever claim `Handover`.** Against a board whose backend finished slices at `Done`, a `react` / `supabase-react` kit has nothing to do and replies `NO_TASKS` — the backend side must run with handover on.
+- **UI kits only ever claim `Waiting`.** Against a board whose backend finished slices at `Done`, a `react` / `supabase-react` kit has nothing to do and replies `NO_TASKS` — the backend side must run with handover on.
 - **Both sides need the new kit.** An already-installed backend kit keeps its old `ralph.js` and prompts and silently ignores `--handover` (slices still end at `Done`); `re-init` it to pick the feature up.
-- **The platform must know the `Ready` / `Handover` statuses.**
-- A kit declares what it claims in `lib/kit.json` — `{ "pickupStatus": "Handover" }`; absent means `Planned`.
+- **The platform must know the `Ready` / `Waiting` statuses.**
+- A kit declares what it claims in `lib/kit.json` — `{ "pickupStatus": "Waiting" }`; absent means `Planned`.
 - `run --status-trigger <status>` overrides that pickup status for a single run (e.g. `--status-trigger Ready`); nothing is saved.
 
 The contract itself is the shared `ui-contract` skill's job (see above); it also owns the rule for which status a slice ends at.
@@ -763,7 +775,7 @@ npx @eventmodelers/cli re-init --modeling            # refresh the modeling kit
 npx @eventmodelers/cli re-init --stack supabase      # override which stack to refresh from (manifest missing/stale, or switching stacks)
 ```
 
-`re-init` re-runs `init` against whichever stack `install-manifest.json` says was installed (no need to pass `--stack` again), but skips step 2 of `init` entirely — the root project scaffold (`package.json`, `src/`, `server.ts`, `docker-compose.yml`, etc.) and the root `CLAUDE.md` router are never touched. Use it after upgrading the CLI to pick up fixes to `ralph.js`/`ralph.sh`/skills without re-scaffolding a project you've since built on top of.
+`re-init` re-runs `init` against whichever stack `install-manifest.json` says was installed (no need to pass `--stack` again), but skips step 2 of `init` entirely — the root project scaffold (`package.json`, `src/`, `server.ts`, `docker-compose.yml`, etc.) and the root `CLAUDE.md` router are never touched. Use it after upgrading the CLI to pick up fixes to `ralph.js`/skills without re-scaffolding a project you've since built on top of.
 
 You don't have to remember to: on startup every command prints a 💡 hint (on stderr) when a newer CLI is on npm, or when a kit in the current directory was installed by an older CLI than the one running — naming the exact `re-init` command to run. The npm lookup happens at most once a day (cached in `~/.eventmodelers/update-check.json`, 1.5 s timeout, silent when offline). Set `EVENTMODELERS_NO_UPDATE_CHECK=1` to turn it off; it is also off when `CI` is set.
 

package/RELEASE_NOTES.md

@@ -1,6 +1,24 @@
-## Unreleased
+## v2.0.0
+
+### Architecture: the kit now runs on an event log
+The CLI's local state used to live in mutable files — `tasks.json` as the queue, `progress.txt` as the learnings journal, a `.claim.json` claim record, and status edited in place in `index.json`/`slice.json`. Concurrent writers, a stale board refresh or a crash could each leave those files disagreeing with the board or with each other (the failure modes are written down in `slice-state-learnings.md`). 2.0.0 replaces all of it with **event sourcing**: everything an agent does to a slice, a task, a prompt or a learning is an immutable event appended to a log, and every other file is a projection folded from that log.
+
+- **The store.** One JSON file per event under `.build-kit/events/` (`.agent-modeling-kit/` for the modeling agent), written whole before its id is appended to `events.log`; the index line is what commits the event, so concurrent writers cannot tear the log whatever the event size. Events carry tags and `agent_id`/`organization_id`/`board_id` metadata. The store is git-ignored, and the loop's git rules now live in `.git/info/exclude` and `.git/info/attributes`, so starting an agent never dirties the tracked tree.
+- **A pure core.** `fold` derives status, claim, pending outcome, attempts, blocked state, the task queue, open prompts and learnings from the event list; `decideSettle` and `decideRecovery` turn that into push/discard/release actions. Side effects sit around the fold, not inside it.
+- **Slice lifecycle as events.** The loop claims a slice (`claimed`/`claim-confirmed`), settles it after the build by executing `decideSettle` (push the recorded outcome, or discard the attempt, record `attempt-failed` and put the slice back to its pickup status), and settles claims left by dead processes at the top of every iteration. Board refreshes are recorded as `board-observed`, so a stale refresh during a build can no longer revert what the agent recorded. The build agent records its outcome with `eventmodelers slice-status <status>`; the loop owns the status on the board.
+- **Attempts and auto-blocks come from the log**, not from an in-memory map, so a restart no longer hands a stuck slice a fresh budget.
+- **The task queue is the log.** A slice change arrives as `task-queued` (a newer change to the same slice replaces its task); the loop replays the log for the oldest task, hands it to the agent and appends `task-done`. A change landing mid-turn is just another event.
+- **Prompts are journaled.** `prompt-received`/`prompt-finished` bracket every prompt the modeling agent takes; on start, what a crash left open is looked up on the platform and handed back unless it already finished. Recovery asks the platform who holds a prompt (`claimed_by`) rather than tracking process ids.
+- **Learnings are events.** `eventmodelers learn` records one (topic, tags, scope; duplicates skipped) and `learn --retract` withdraws it; `learnings` lists them. `AGENTS.md` is rendered from the events and adopts lines added by hand, so regenerating never loses them. After `RALPH_CURATE_AFTER` (default 10) new learnings, a curator turn that can only merge and retract tidies the list (`learning-merged`, `learnings-curated`).
+- **Look at it.** `eventmodelers events` decodes the log in the terminal — one line per event with the slice title and the writing agent; `--type`, `--slice`, `--tag`, `--last`, `--json`, `--state` (what the log folds to), `--follow`, `--kit`, `--global` and `--board` narrow or redirect it.
+- **One agent id, one live process.** A standalone run keeps a stable agent id per board and repo, and takes an exclusive lock on it, so two processes never share an id, a heartbeat row or each other's prompts. A global install records nothing, so one board's learnings never surface in another's.
+
+### Breaking changes
+- `tasks.json` is gone. Nothing reads or writes a queue file any more; the stacks' `prompt.md` files lose their queue steps and the `IDLE` reply, and `AGENT.md` is now a reference.
+- `progress.txt` is gone. Learnings go through `eventmodelers learn`, a failed attempt is read from the slice's `lastAttempt`, and a block reason lives on its event.
+- `run --bash` (the bash-only loop: `ralph.sh`, `lib/agent.sh`, `realtime-agent.js`) is retired. The flag is still recognised, only to say so.
+- The bridge kit is retired: `init --bridge` (with `--target`/`--hook`), the `bridge` command and `uninstall --bridge-kit`. `fetch --spec-kitty` keeps working on its own.
 
-### Features
 - `run --modeling`/`run --standalone` accept `--local-ai`, so the modeling agent can be driven by a local or self-hosted model instead of Claude. It was previously rejected as a build-kit-only flag, which conflated two different things: `--bash`/`--exec` select a *queue* the modeling loop has no equivalent of, while `--local-ai` selects a *model*. Both wire dialects are supported — `--local-ai` (bare) or `--local-ai ollama` for Ollama's native `POST /api/chat`, and `--local-ai vllm`/`lmstudio`/`llamacpp` for the OpenAI-compatible `POST /v1/chat/completions` that vLLM, LM Studio, llama.cpp-server, TGI and SGLang serve; anything else OpenAI-compatible works via `LOCAL_AI_URL`. The loop itself is untouched: the prompt queue, the standalone board-change lane and its damping, the idle review and the platform's full MCP tool set all behave as before, because everything Claude-specific already sat behind a single `runTurn(text)` seam. What a local model cannot bring along is the part that is not a wire format — the skills (`/place-element`, `/timeline`, `eventmodeling-*`) and the subagent fan-out are Claude Code features — so a self-directed turn does the most valuable piece of work itself, inline, and the board rules it needs come from the new runner's system prompt (`lib/modeling-local-ai.js`) instead of `.agent-modeling-kit/CLAUDE.md`. `--max-agents` is ignored in this mode. Ollama's `num_ctx` is raised to 49152 by default (the MCP tool schemas alone are ~16k tokens, well past Ollama's 4096 default, which would silently truncate the tool block), with a warning when the schemas still fill >60% of it and a turn cap of 24 tool iterations.
 
 - `run --non-interactive` never asks anything: the board and credentials that resolve from flags, `EVENTMODELERS_*` env vars and the config files are final, and an incomplete set fails the run with the reason instead of being interviewed for. A missing TTY already implied this, which covered CI and most supervisors, but not a container started with `-it` or a loop started from a terminal — stdin is a TTY nobody is watching, and the run stopped on the board confirmation or the credentials question forever. `EVENTMODELERS_TOKEN` also now answers the credentials question on its own, the way `EVENTMODELERS_BOARD_ID` always answered the board question: an env var that outranks every config file makes asking where the credentials come from moot. The README gains a container recipe, including the two things a container needs that a laptop already had — a writable HOME for the global kit and per-board credentials, and a `LOCAL_AI_URL` that isn't `localhost`.