@eventmodelers/cli 0.0.39 → 1.0.0

package/README.md

@@ -2,7 +2,11 @@
 
 One CLI, real-time Claude agent, and skill kit for the [Eventmodelers](https://eventmodelers.ai) platform — pick a stack, scaffold it, connect it to a board.
 
-## Quick start
+This CLI covers two audiences. If you just want a project connected to a board and an agent working slices, **Getting started** below is all you need — `init`, `run`, `fetch`, and a couple of read-only helpers. Everything under **Power users** is for customizing the install itself (bridging to another spec framework, CI-driven installs, multi-project config, hooks, adding a new stack) — skip it until you actually need it.
+
+## Getting started
+
+### Quick start
 
 ```bash
 npx @eventmodelers/cli init
@@ -15,21 +19,44 @@ 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-modeling                 # skills + agent loop only, no backend scaffold
-npx @eventmodelers/cli init --build-kit              # blank build-kit scaffold for a stack not built into this CLI yet
 ```
 
-`init-modeling` isn't a stack — it's the option for when you don't want a backend scaffolded at all, just the skills and the agent loop. `init --build-kit` isn't one of the four either — it installs the same `.build-kit/` + skills shape as a real stack, but with TODO-marked placeholders instead of real content, for integrating a stack this CLI doesn't support yet (see "Adding a stack" below).
+The installer prompts for your API token, Organization ID, and Board ID from [app.eventmodelers.ai/account](https://app.eventmodelers.ai/account), scaffolds the stack into your project, and writes `.eventmodelers/config.json` with your credentials.
 
-The installer prompts for your API token, Organization ID (and Board ID, for the four backend stacks) from [app.eventmodelers.ai/account](https://app.eventmodelers.ai/account).
+### Common scenarios
 
-`init`/`init-modeling` scaffold and configure credentials, but don't register the MCP server — run that as a separate step once you're ready to connect a harness:
+**Starting from scratch on a new project:**
 
 ```bash
-npx @eventmodelers/cli init-mcp
+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.
+
+**Already initialized — you just want the agent to start working the board:**
+
+```bash
+npx @eventmodelers/cli run
 ```
 
-## What gets installed
+`run` doesn't re-configure anything. It finds whatever kit dir `init` already created in this project and starts its agent loop (`ralph-claude.js`) against your existing `.eventmodelers/config.json`.
+
+**Pulling the latest board state without starting an agent** — e.g. to inspect a context's slices, or in a script:
+
+```bash
+npx @eventmodelers/cli fetch --context <name>
+```
+
+This writes the current slice/event/command detail for that context to disk and prints a summary — no agent loop, no listener, just a one-shot pull.
+
+**Checking what's installed or which credentials are active:**
+
+```bash
+npx @eventmodelers/cli status   # what's installed in this project
+npx @eventmodelers/cli config   # the fully resolved config (file + env), token masked
+```
+
+### What gets installed
 
 ```
 your-project/
@@ -46,9 +73,73 @@ your-project/
 └── CLAUDE.md                      ← agent instructions
 ```
 
-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 four backend stacks (`node`, `supabase`, `axon`, `cratis-csharp`) also scaffold a real project skeleton into your project root (`templates/root/`) — source layout, build files, migrations, etc.
+
+## Skills
+
+Use skills in Claude Code with `/skill-name`:
+
+| Skill | Description |
+|-------|-------------|
+| `/connect` | Set up board connection |
+| `/timeline` | Live event storming facilitator |
+| `/wdyt` | Business analyst review of your event model |
+| `/storyboard` | Build a full visual storyboard |
+| `/html-screen` | Design individual real HTML/CSS screens (default) |
+| `/storyboard-screen` | Design individual wireframe/sketch screens (explicit request only) |
+| `/place-element` | Place commands/events/read models on the board |
+| `/learn-eventmodelers-api` | Full API reference for agent use |
+| `/attributes` | Add/rename attributes across a chain of elements |
+| `/examples` | Add example data to element fields |
+| `/update-slice-status` | Update slice status on the board |
+| `/load-slice` | Persist board slices to disk (backend stacks) |
+| `/build-state-change`, `/build-state-view`, `/build-automation`, `/build-webhook` | Implement a slice's command/view/automation/webhook (backend stacks) |
+
+Which skills install depends on the chosen stack — see `stacks/<name>/templates/.claude/skills/`. `/connect`, `/learn-eventmodelers-api`, and `/update-slice-status` have no stack-specific content and install into every stack from `shared/skills/` instead.
+
+## Everyday commands
+
+```bash
+npx @eventmodelers/cli init --stack <name>          # scaffold a stack + install + configure (alias: install)
+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)
+npx @eventmodelers/cli run --bash                   # bash-only loop, no realtime (ralph.sh)
+npx @eventmodelers/cli fetch --context <name>                     # pull full slice detail for one context on the board into <kit-dir>/.slices/
+npx @eventmodelers/cli fetch --context <name> --slice-id <id>     # same, then print just that slice
+npx @eventmodelers/cli fetch --context <name> --slice-title <title> # same, then print just the slice matching this title
+npx @eventmodelers/cli stacks                       # list available stacks
+npx @eventmodelers/cli status                       # check what's installed
+npx @eventmodelers/cli config                       # print the fully resolved config (file + env), token masked
+```
+
+`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.
+
+---
+
+## Power users
+
+Everything below customizes *how the install itself works* — skills-only installs, bridging to another spec framework, CI-driven/non-interactive installs, multi-project config sharing, hooks that replace the AI executor, MCP registration for other harnesses, and adding a new stack. Casual usage never needs this section.
 
-The four backend stacks (`node`, `supabase`, `axon`, `cratis-csharp`) also scaffold a real project skeleton into your project root (`templates/root/`) — source layout, build files, migrations, etc. `modeling-kit` only installs skills + the agent loop, with no backend opinion.
+### Skills-only / no backend scaffold
+
+```bash
+npx @eventmodelers/cli init-modeling                 # skills + agent loop only, no backend scaffold
+npx @eventmodelers/cli init --build-kit              # blank build-kit scaffold for a stack not built into this CLI yet
+```
+
+`init-modeling` isn't a stack — it's the option for when you don't want a backend scaffolded at all, just the skills and the agent loop. `init --build-kit` isn't one of the four either — it installs the same `.build-kit/` + skills shape as a real stack, but with TODO-marked placeholders instead of real content, for integrating a stack this CLI doesn't support yet (see "Adding a stack" below).
+
+**Building a new kit for an unsupported stack:**
+
+```bash
+npx @eventmodelers/cli init --build-kit
+```
+
+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.
+
+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.
 
 ### Installing skills globally
 
@@ -60,7 +151,7 @@ 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
+### Bridging to another spec framework
 
 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:
 
@@ -94,7 +185,7 @@ npx @eventmodelers/cli bridge
 
 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
+### Claude execution & config resolution
 
 During install you can optionally point the agent at a local LLM server (vLLM, Ollama) instead of the default Claude Code endpoint, and/or pin a specific model:
 
@@ -180,9 +271,16 @@ npx @eventmodelers/cli --config ../shared/config.json status
 
 Run `npx @eventmodelers/cli config` at any time to see the fully resolved config (file + env overrides merged, token masked).
 
+`--config <path>` and `--print` are global flags accepted by every command. `--print` skips the "connect MCP globally?" prompt during `init-mcp` and just prints the `claude mcp add` command instead of running it — combined with the env vars or direct flags above, `--print` makes both `init` and `init-mcp` fully non-interactive:
+
+```bash
+EVENTMODELERS_ORGANIZATION_ID=... EVENTMODELERS_BOARD_ID=... EVENTMODELERS_TOKEN=... \
+  npx @eventmodelers/cli --print init --stack node
+```
+
 ### MCP for other harnesses
 
-MCP registration is a separate step from `init`/`init-modeling` — run `init-mcp` whenever you're ready to connect a harness:
+`init`/`init-modeling` scaffold and configure credentials, but don't register the MCP server — run that as a separate step once you're ready to connect a harness:
 
 ```bash
 npx @eventmodelers/cli init-mcp
@@ -199,58 +297,14 @@ It writes the MCP server into `.claude/settings.json` for Claude Code. For other
 
 Cursor and Windsurf don't have a safe scriptable install, so the installer prints their manual setup steps instead of writing anything. Pass `--print` to always print every harness's command/steps instead of prompting.
 
-## Skills
-
-Use skills in Claude Code with `/skill-name`:
-
-| Skill | Description |
-|-------|-------------|
-| `/connect` | Set up board connection |
-| `/timeline` | Live event storming facilitator |
-| `/wdyt` | Business analyst review of your event model |
-| `/storyboard` | Build a full visual storyboard |
-| `/storyboard-screen` | Design individual wireframe screens |
-| `/html-screen` | Design individual real HTML/CSS screens (explicit request only) |
-| `/place-element` | Place commands/events/read models on the board |
-| `/learn-eventmodelers-api` | Full API reference for agent use |
-| `/attributes` | Add/rename attributes across a chain of elements |
-| `/examples` | Add example data to element fields |
-| `/update-slice-status` | Update slice status on the board |
-| `/load-slice` | Persist board slices to disk (backend stacks) |
-| `/build-state-change`, `/build-state-view`, `/build-automation`, `/build-webhook` | Implement a slice's command/view/automation/webhook (backend stacks) |
-
-Which skills install depends on the chosen stack — see `stacks/<name>/templates/.claude/skills/`. `/connect`, `/learn-eventmodelers-api`, and `/update-slice-status` have no stack-specific content and install into every stack from `shared/skills/` instead.
-
-## Commands
+### `listen` — push-based slice export
 
 ```bash
-npx @eventmodelers/cli init --stack <name>          # scaffold a stack + install + configure (alias: install)
-npx @eventmodelers/cli init --stack <name> --global # same, but skills go to ~/.claude/skills/ (every project)
-npx @eventmodelers/cli init-modeling                # skills + agent loop only, no backend scaffold (alias: modeling)
-npx @eventmodelers/cli init-modeling --global       # same, but skills go to ~/.claude/skills/ (every project)
-npx @eventmodelers/cli init --build-kit             # blank build-kit scaffold (TODO placeholders) for a stack not built into this CLI yet
-npx @eventmodelers/cli init-mcp                     # register the MCP server in .claude/settings.json (+ optionally another harness)
-npx @eventmodelers/cli init-config                  # credentials only, no scaffold — writes ./.eventmodelers/config.json
-npx @eventmodelers/cli init-config --global         # same, but writes organizationId + token to ~/.eventmodelers/config.json
-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)
-npx @eventmodelers/cli run --bash                   # bash-only loop, no realtime (ralph.sh)
 npx @eventmodelers/cli listen                       # start the code-export listener (code-export.mjs) from the installed kit dir
-npx @eventmodelers/cli listen --port 4000           # same, on a different port
-npx @eventmodelers/cli fetch --context <name>                     # pull full slice detail for one context on the board into <kit-dir>/.slices/ (project root if no kit, or a modeling-kit, is installed)
-npx @eventmodelers/cli fetch --context <name> --slice-id <id>     # same, then print just that slice
-npx @eventmodelers/cli fetch --context <name> --slice-title <title> # same, then print just the slice matching this title
-npx @eventmodelers/cli stacks                       # list available stacks
-npx @eventmodelers/cli status                       # check what's installed
-npx @eventmodelers/cli config                       # print the fully resolved config (file + env), token masked
-npx @eventmodelers/cli uninstall                    # remove everything init/init-modeling installed
+npx @eventmodelers/cli listen --port 4000            # same, on a different port
 ```
 
-`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.
-
-`listen` is the same kind of dispatcher, but for `<kit-dir>/code-export.mjs` — a local HTTP server (port 3001 by default) that the eventmodelers board UI posts slice/screen data to, which then gets written under `<kit-dir>/.slices/`.
-
-`fetch` is the pull-based counterpart to `listen`: instead of waiting for the board UI to push data to a running listener, it calls `slicedata?contextName=<name>` for the required `--context` (full slice detail — commands/events/readmodels/screens/processors/specifications/comments), and writes the same `.slices/<context>/<slice>/slice.json`, `index.json`, and `context.json` layout — useful in CI or any context where nothing is listening on a port. It does not fetch screen images (those only arrive via `listen`'s push). Unlike every other command, `fetch` also works with no kit installed at all — it only needs credentials, not kit-specific files — and, unique to modeling-kit, writes `.slices/` to the project root instead of nesting it under `.agent-modeling-kit/`, since nothing reads it from there (modeling-kit has no `code-export.mjs`/`listen`). 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.
+`listen` is a dispatcher for `<kit-dir>/code-export.mjs` — a local HTTP server (port 3001 by default) that the eventmodelers board UI posts slice/screen data to, which then gets written under `<kit-dir>/.slices/`. Unlike `fetch`, it does receive screen images, since the board UI pushes them directly.
 
 ### Uninstall
 
@@ -272,18 +326,11 @@ npx @eventmodelers/cli uninstall --build-kit         # remove .build-kit/ specif
 npx @eventmodelers/cli uninstall --modeling-kit      # remove .agent-modeling-kit/ specifically
 ```
 
-`--config <path>` and `--print` are global flags accepted by every command. `--print` skips the "connect MCP globally?" prompt during `init-mcp` and just prints the `claude mcp add` command instead of running it — combined with the env vars or direct flags above, `--print` makes both `init` and `init-mcp` fully non-interactive:
-
-```bash
-EVENTMODELERS_ORGANIZATION_ID=... EVENTMODELERS_BOARD_ID=... EVENTMODELERS_TOKEN=... \
-  npx @eventmodelers/cli --print init --stack node
-```
-
-## Adding a stack
+### Adding a stack
 
 Each stack lives under `stacks/<name>/templates/` with `.claude/` (skills), `root/` (spread into the project root), and either `build-kit/` (backend stacks) or `kit/` (modeling-only) for the agent runner. Files identical across all backend stacks live once in `shared/build-kit/` and get layered in automatically — only put stack-specific overrides under `stacks/<name>/templates/build-kit/`. Skills with no stack-specific content (`connect`, `learn-eventmodelers-api`, `update-slice-status`) 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.
 
-`init --build-kit` (see above) installs exactly that layout into a real project — `.build-kit/CLAUDE.md`, `lib/prompt.md`, `lib/backend-prompt.md`, and `.claude/skills/build-{state-change,state-view,automation}/SKILL.md` — but with TODO-marked placeholders instead of real content, since there's no fixed backend to generate them from. Fill in the TODOs against the actual stack you're integrating (build/test commands, file layout, framework idioms) while building something real with it. Once it works, promote it to a first-class stack:
+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/`.
 2. Add an entry for `<name>` to the `STACKS` object in `cli.js` (`label`, `kitSubdir: 'build-kit'`, `kitDirName: '.build-kit'`, `useShared: true`, `needsBoardId: true`).

package/cli.js

@@ -20,6 +20,11 @@ import { homedir } from 'os';
 import { randomUUID } from 'crypto';
 import { runFetch, FetchAuthError } from './lib/fetch.js';
 import { run as runSpecKittyAdapter } from './lib/adapters/spec-kitty-adapter.js';
+// Not a root-level adapter like spec-kitty-adapter.js above: this is the one canonical
+// copy that every useShared:true stack also gets copied into its installed kit (see
+// copyDirContents in installStack) for ralph.js to import standalone — see
+// shared/build-kit/lib/adapters/realtime-adapter.js for why it lives there instead.
+import { createRealtimeAdapter } from './shared/build-kit/lib/adapters/realtime-adapter.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -713,6 +718,7 @@ async function installStack(stackKey, stackCfg, options = {}) {
     // skills. Only relevant to a bridge install — never copied into the four
     // backend stacks or modeling-kit.
     const isBridge = stackKey === BRIDGE_KIT.key;
+    const isModelingKit = stackKey === MODELING_KIT.key;
     const sharedBridgeSkills = isBridge ? join(__dirname, 'shared', 'bridge', options.target) : null;
 
     if (!existsSync(templatesSource)) {
@@ -919,6 +925,14 @@ async function installStack(stackKey, stackCfg, options = {}) {
       force: options.force,
     });
 
+    // Register the MCP server up front so it's available from the very first
+    // `claude` invocation (whether that's an interactive session opened right
+    // after install, or the agent loop's first spawn) instead of only appearing
+    // once `run`/`run --modeling` or `init-mcp` happens to run. Safe to write
+    // even without a token yet — the file only ever holds the env-var
+    // placeholder, never the literal secret (see connect/SKILL.md's Security notes).
+    ensureMcpRegistered(targetDir, config.baseUrl || DEFAULT_BASE_URL);
+
     // --- 6. Install manifest (drives precise `uninstall` later) ---
     // Only the footprint listed here is ever removed by `uninstall` — the root
     // scaffold (step 2) is real project source the user builds on, so it's
@@ -933,6 +947,8 @@ async function installStack(stackKey, stackCfg, options = {}) {
     console.log('\n✅ Done! Start your agent:\n');
     if (isBridge) {
       console.log('  npx @eventmodelers/cli bridge\n');
+    } else if (isModelingKit) {
+      console.log('  npx @eventmodelers/cli run --modeling\n');
     } else {
       console.log('  npx @eventmodelers/cli run          (--ollama or --bash for other runners)\n');
     }
@@ -1118,6 +1134,27 @@ async function configureMcp(options = {}) {
   }
 }
 
+// Registers the eventmodelers MCP server in `.mcp.json` at the project root, the
+// same file/shape the `connect` skill's Step 3.5 produces — kept here as a
+// belt-and-suspenders guarantee, since an agent executing that skill can skip a
+// step, but a `claude` process only ever discovers MCP servers at its own
+// startup. Anything spawning a `claude` process for this project (cold-spawn
+// per task, or a long-lived warm process) must call this first — a `.mcp.json`
+// written mid-session by the process itself is too late for that same process.
+// The token itself is never written to disk here — `${EVENTMODELERS_TOKEN}` is
+// resolved by `claude` from its own process env, which the caller must set.
+function ensureMcpRegistered(projectDir, baseUrl) {
+  const mcpConfigPath = join(projectDir, '.mcp.json');
+  const mcpConfig = readJsonSafe(mcpConfigPath);
+  mcpConfig.mcpServers = mcpConfig.mcpServers || {};
+  mcpConfig.mcpServers.eventmodelers = {
+    type: 'http',
+    url: `${baseUrl}/mcp`,
+    headers: { 'x-token': '${EVENTMODELERS_TOKEN}' },
+  };
+  writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2));
+}
+
 // `run --modeling`: modeling-kit's one and only runtime mode — there is no
 // cold-spawn/tasks.json loop for this kit (that's a build-kit concept; see the
 // `run` command's build-kit-vs-modeling-kit gate above). It keeps ONE Claude
@@ -1129,14 +1166,13 @@ async function configureMcp(options = {}) {
 // from the kit's lib/config.js, to avoid duplicating the config-file-walk logic.
 // See `.agent-modeling-kit/CLAUDE.md` for the per-turn instructions this mode's
 // modeling session follows.
-async function runModeling(kitDir, projectDir) {
+async function runModeling(kitDir, projectDir, verbose = false) {
   const configLibPath = join(kitDir, 'lib', 'config.js');
   if (!existsSync(configLibPath)) {
     console.error(`❌ ${relative(process.cwd(), configLibPath)} not found — --modeling needs a kit installed via \`init --modeling\`.`);
     process.exit(1);
   }
   const { loadLocalConfig, fetchPlatformConfig } = await import(pathToFileURL(configLibPath).href);
-  const { createClient } = await import('@supabase/supabase-js');
 
   const local = loadLocalConfig(kitDir);
   local.agentId = ensureAgentId(kitDir, 'MODELING');
@@ -1144,7 +1180,7 @@ async function runModeling(kitDir, projectDir) {
     console.error('❌ --modeling needs platform credentials in .eventmodelers/config.json (token + organizationId) — run `/connect` once or paste your config first.');
     process.exit(1);
   }
-  const cfg = await fetchPlatformConfig(local); // adds supabaseUrl/supabaseAnonKey (+ boardId if the config has a default one)
+  const cfg = await fetchPlatformConfig(local); // adds realtimeProvider + its provider-specific fields (supabaseUrl/supabaseAnonKey or pocketbaseUrl), + boardId if the config has a default one
   if (!cfg.boardId) {
     console.error('❌ --modeling needs a boardId — a modeling agent always runs for exactly one board. Run `/connect board=<uuid>` once, or add boardId to .eventmodelers/config.json.');
     process.exit(1);
@@ -1181,33 +1217,50 @@ async function runModeling(kitDir, projectDir) {
 
   const claudeArgs = ['--dangerously-skip-permissions', '-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose'];
   if (cfg.model) claudeArgs.push('--model', cfg.model);
-  const claudeEnv = cfg.anthropicBaseUrl ? { ...process.env, ANTHROPIC_BASE_URL: cfg.anthropicBaseUrl } : process.env;
+  const claudeEnv = {
+    ...process.env,
+    ...(cfg.anthropicBaseUrl ? { ANTHROPIC_BASE_URL: cfg.anthropicBaseUrl } : {}),
+    EVENTMODELERS_TOKEN: cfg.token,
+  };
 
   let proc = null;
   let stdoutBuffer = '';
   let pending = null; // one in-flight turn at a time
 
+  // Collapses whitespace/newlines to a single line and truncates past `max` chars —
+  // a long multi-line curl command or grep pattern wrapped across many terminal lines
+  // is just as unreadable as no detail at all. Keeps one tool call to one log line.
+  function oneLine(s, max) {
+    const collapsed = String(s ?? '').replace(/\s+/g, ' ').trim();
+    return collapsed.length > max ? `${collapsed.slice(0, max)}…` : collapsed;
+  }
+
   // Bare tool names (`→ Bash`, `→ Skill`) tell you nothing happened worth
   // reading — this pulls out the one input field that actually says what the
-  // tool did, so the trace is skimmable without the interactive TUI.
+  // tool did, so the trace is skimmable without the interactive TUI. Only used
+  // in --verbose mode; the condensed default logs the bare name (or, for Skill,
+  // just the skill name) instead — see handleLine.
   function describeToolUse(block) {
     const input = block.input ?? {};
     switch (block.name) {
-      case 'Bash': return `Bash: ${input.command}`;
-      case 'Skill': return `Skill: ${input.skill}${input.args ? ` ${input.args}` : ''}`;
+      case 'Bash': return `Bash: ${oneLine(input.command, 100)}`;
+      case 'Skill': return `Skill: ${input.skill}${input.args ? ` ${oneLine(input.args, 60)}` : ''}`;
       case 'Read': return `Read: ${input.file_path}`;
       case 'Edit': return `Edit: ${input.file_path}`;
       case 'Write': return `Write: ${input.file_path}`;
-      case 'Grep': return `Grep: ${input.pattern}`;
+      case 'Grep': return `Grep: ${oneLine(input.pattern, 60)}`;
       case 'Glob': return `Glob: ${input.pattern}`;
       case 'WebFetch': return `WebFetch: ${input.url}`;
-      case 'Agent': return `Agent: ${input.description ?? input.subagent_type ?? ''}`;
+      case 'Agent': return `Agent: ${oneLine(input.description ?? input.subagent_type ?? '', 60)}`;
       default: return block.name;
     }
   }
 
   // stream-json output loses the normal interactive TUI (tool cards, live diffs) —
   // this is a plain-text approximation, good enough for a headless/voice runner.
+  // --verbose logs full tool input and assistant reasoning text; the default
+  // (condensed) mode logs only the high-level step — a skill name, or a bare tool
+  // name — so a long session reads as a step list instead of a full trace.
   function handleLine(line) {
     if (!line.trim()) return;
     let msg;
@@ -1215,8 +1268,12 @@ async function runModeling(kitDir, projectDir) {
 
     if (msg.type === 'assistant') {
       for (const block of msg.message?.content ?? []) {
-        if (block.type === 'text' && block.text) log(block.text);
-        if (block.type === 'tool_use') log(`→ ${describeToolUse(block)}`);
+        if (block.type === 'text' && block.text && verbose) log(block.text);
+        if (block.type === 'tool_use') {
+          if (verbose) log(`→ ${describeToolUse(block)}`);
+          else if (block.name === 'Skill') log(`→ Skill: ${block.input?.skill ?? ''}`);
+          else log(`→ ${block.name}`);
+        }
       }
       return;
     }
@@ -1278,10 +1335,6 @@ async function runModeling(kitDir, projectDir) {
   }
 
   let realtimeToken = await getRealtimeToken();
-  const supabase = createClient(cfg.supabaseUrl, cfg.supabaseAnonKey, {
-    realtime: { params: { apikey: cfg.supabaseAnonKey } },
-  });
-  await supabase.realtime.setAuth(realtimeToken);
 
   let draining = false;
   async function drain() {
@@ -1303,26 +1356,30 @@ async function runModeling(kitDir, projectDir) {
   }
 
   const channelName = `org:${cfg.organizationId}`;
-  supabase
-    .channel(channelName, { config: { private: true } })
-    .on('broadcast', { event: 'message' }, (msg) => {
-      if (msg.payload === 'Exit') {
-        log('received "Exit" — shutting down');
-        process.exit(0);
-      }
-    })
-    .on('broadcast', { event: 'prompt:created' }, () => {
-      drain().catch((err) => log(`drain error: ${err.message}`));
-    })
-    .subscribe((status) => {
+  const realtime = await createRealtimeAdapter(cfg, realtimeToken);
+  realtime.subscribe(
+    channelName,
+    {
+      message: (payload) => {
+        if (payload === 'Exit') {
+          log('received "Exit" — shutting down');
+          process.exit(0);
+        }
+      },
+      'prompt:created': () => {
+        drain().catch((err) => log(`drain error: ${err.message}`));
+      },
+    },
+    (status) => {
       log(`channel "${channelName}": ${status}`);
       if (status === 'SUBSCRIBED') drain().catch((err) => log(`initial drain error: ${err.message}`));
-    });
+    },
+  );
 
   setInterval(async () => {
     try {
       realtimeToken = await getRealtimeToken();
-      await supabase.realtime.setAuth(realtimeToken);
+      await realtime.setAuth(realtimeToken);
       log('token refreshed');
     } catch (err) {
       log(`token refresh failed: ${err.message}`);
@@ -1577,7 +1634,7 @@ credentialFlags(program
         ? resolve(targetDir, globalOpts.config)
         : join(targetDir, '.eventmodelers', 'config.json');
       const effective = loadEffectiveConfig(targetDir, null, globalOpts.config);
-      await configureCredentials({
+      const cfg = await configureCredentials({
         config: effective.config,
         configPath,
         targetDir,
@@ -1587,6 +1644,12 @@ credentialFlags(program
         print: globalOpts.print,
         force: true,
       });
+
+      // Keep `.mcp.json` in sync — this command can change `baseUrl` (e.g.
+      // switching a project from prod to beta) independently of `init`, and a
+      // stale MCP registration pointing at the wrong host is worse than none
+      // (see the beta-api protected-resource-metadata incident this fixed).
+      ensureMcpRegistered(targetDir, cfg.baseUrl || DEFAULT_BASE_URL);
     }
   });
 
@@ -1596,6 +1659,7 @@ program
   .option('--ollama', 'Use ralph-ollama.js instead of the default Claude runner (build-kit stacks only)')
   .option('--bash', 'Use the bash-only ralph.sh loop (build-kit stacks only, no realtime)')
   .option('--modeling', 'Keep one Claude process warm across prompts instead of spawning a fresh one per task, for low-latency voice/live use. Modeling-kit installs only — there is no cold-spawn/tasks.json loop for modeling-kit. Built into the CLI, not a per-project file.')
+  .option('--verbose', 'Log every tool call\'s full input (commands, skill args, file paths) and assistant reasoning text. Default is condensed, high-level per-step logging only.')
   .action(async (opts) => {
     const cwd = process.cwd();
     // Both kit dirs can be installed side by side (e.g. running a build-kit and a
@@ -1633,7 +1697,7 @@ program
       // runModeling's own [modeling] log lines instead of before them.
       await new Promise((res) => process.stdout.write(`▶ Starting modeling loop (warm Claude process) for ${relative(cwd, modelingKitDir)}...\n\n`, res));
       try {
-        await runModeling(modelingKitDir, resolve(modelingKitDir, '..'));
+        await runModeling(modelingKitDir, resolve(modelingKitDir, '..'), !!opts.verbose);
       } catch (err) {
         console.error('[modeling] Fatal:', err);
         process.exit(1);
@@ -1673,7 +1737,9 @@ program
     console.log(`▶ Starting ${relative(cwd, runnerPath)}...\n`);
     const cmd = runner.endsWith('.sh') ? `"${runnerPath}"` : `node "${runnerPath}"`;
     try {
-      execSync(cmd, { cwd: kitDir, stdio: 'inherit' });
+      // Only ralph-claude.js reads this — the bash loop and the ollama executor have
+      // their own separate output paths with no stream-json parsing to gate.
+      execSync(cmd, { cwd: kitDir, stdio: 'inherit', env: { ...process.env, RALPH_VERBOSE: opts.verbose ? '1' : '' } });
     } catch (err) {
       process.exit(err.status || 1);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "0.0.39",
+  "version": "1.0.0",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, Cratis, or modeling-only)",
   "type": "module",
   "bin": {
@@ -30,7 +30,9 @@
   },
   "dependencies": {
     "@supabase/supabase-js": "^2.0.0",
-    "commander": "^12.0.0"
+    "commander": "^12.0.0",
+    "eventsource": "^3.0.7",
+    "pocketbase": "^0.27.0"
   },
   "engines": {
     "node": ">=18.0.0"

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

@@ -0,0 +1,29 @@
+// PocketBase realtime adapter — the self-hosted/on-prem transport. PocketBase has no
+// generic pub/sub broadcast API; realtime only fires on record create/update/delete
+// within a subscribed collection, so the backend piggybacks broadcasts onto a
+// `realtime_events` collection (topic/event/payload fields) and this adapter filters
+// that collection's create-stream down to the requested topic. See realtime-adapter.js
+// for the interface both this and the Supabase adapter implement.
+
+const REALTIME_EVENTS_COLLECTION = 'realtime_events';
+
+export async function createPocketBaseRealtimeAdapter(cfg, initialToken) {
+  const { EventSource } = await import('eventsource');
+  if (!globalThis.EventSource) globalThis.EventSource = EventSource; // PocketBase's SDK assumes a browser-style global
+  const { default: PocketBase } = await import('pocketbase');
+  const pb = new PocketBase(cfg.pocketbaseUrl);
+  pb.authStore.save(initialToken, null);
+
+  return {
+    async subscribe(topic, handlers, onStatus) {
+      await pb.collection(REALTIME_EVENTS_COLLECTION).subscribe('*', (e) => {
+        if (e.action !== 'create' || e.record.topic !== topic) return;
+        handlers[e.record.event]?.(e.record.payload);
+      });
+      onStatus?.('SUBSCRIBED');
+    },
+    setAuth(token) {
+      pb.authStore.save(token, null);
+    },
+  };
+}

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

@@ -0,0 +1,27 @@
+// Realtime adapter — picks the platform's realtime transport per cfg.realtimeProvider
+// (set by /api/config: Supabase broadcast channels for the hosted SaaS, PocketBase
+// record-change events for self-hosted/on-prem) and hands back one common interface:
+//
+//   subscribe(topic, handlers, onStatus?) — handlers is a { [eventName]: (payload) => void }
+//     map; onStatus?.(status) fires once the subscription is live ('SUBSCRIBED').
+//   setAuth(token) — refresh the short-lived realtime token on the live connection.
+//
+// cfg.realtimeProvider absent (older servers, predating PocketBase support) means
+// 'supabase' — the only transport that ever existed before it.
+//
+// Single source of truth for both runtimes that need it: cli.js's modeling loop
+// imports this file directly out of the npm package (shared/build-kit/lib/adapters/...),
+// and every useShared:true stack gets this whole adapters/ folder copied alongside
+// ralph.js into the installed kit (see copyDirContents in cli.js), so ralph.js's copy
+// imports it via the relative path './adapters/realtime-adapter.js' from wherever it
+// ends up on disk.
+
+import { createSupabaseRealtimeAdapter } from './supabase-realtime-adapter.js';
+import { createPocketBaseRealtimeAdapter } from './pocketbase-realtime-adapter.js';
+
+export async function createRealtimeAdapter(cfg, initialToken) {
+  const provider = cfg.realtimeProvider ?? 'supabase';
+  return provider === 'pocketbase'
+    ? createPocketBaseRealtimeAdapter(cfg, initialToken)
+    : createSupabaseRealtimeAdapter(cfg, initialToken);
+}

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

@@ -0,0 +1,24 @@
+// Supabase realtime adapter — the hosted-SaaS transport. Subscribes to a private
+// broadcast channel and dispatches named broadcast events to caller-supplied handlers.
+// See realtime-adapter.js for the interface both this and the PocketBase adapter implement.
+
+export async function createSupabaseRealtimeAdapter(cfg, initialToken) {
+  const { createClient } = await import('@supabase/supabase-js');
+  const supabase = createClient(cfg.supabaseUrl, cfg.supabaseAnonKey, {
+    realtime: { params: { apikey: cfg.supabaseAnonKey } },
+  });
+  await supabase.realtime.setAuth(initialToken);
+
+  return {
+    subscribe(topic, handlers, onStatus) {
+      let channel = supabase.channel(topic, { config: { private: true } });
+      for (const [event, handler] of Object.entries(handlers)) {
+        channel = channel.on('broadcast', { event }, (msg) => handler(msg.payload));
+      }
+      channel.subscribe((status) => onStatus?.(status));
+    },
+    setAuth(token) {
+      return supabase.realtime.setAuth(token);
+    },
+  };
+}