@eventmodelers/cli 1.0.73 → 1.0.75

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)
@@ -79,7 +78,7 @@ your-project/
 │   └── config.json                ← your token + org/board (gitignored) — shared by every kit in this project
 ├── .build-kit/                    ← agent runner (name is .agent-modeling-kit/ for the modeling-kit stack)
 │   ├── ralph-claude.js            ← realtime agent + task loop
-│   ├── ralph-ollama.js            ← same, via local Ollama
+│   ├── ralph-local-ai.js          ← same, via a local/self-hosted model
 │   ├── 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`)
@@ -89,11 +88,11 @@ your-project/
 └── 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.
 
-`react` (the plain-REST/board-polling variant, no Supabase) is still in the same state as a fresh `init --build-kit` scaffold — CLAUDE.md, the `build-*` skills, and `templates/root/` are all TODO-marked placeholders, not real content, pending an equivalent reference implementation. It overrides `lib/ralph.js` (+ `ralph-claude.js`/`ralph-ollama.js`/`package.json`/`README.md`) for board-polling sync. Fill in the TODOs (and add a real `templates/root/` scaffold) against an actual project before relying on it.
+`react` (the plain-REST/board-polling variant, no Supabase) is still in the same state as a fresh `init --build-kit` scaffold — CLAUDE.md, the `build-*` skills, and `templates/root/` are all TODO-marked placeholders, not real content, pending an equivalent reference implementation. It overrides `lib/ralph.js` (+ `ralph-claude.js`/`ralph-local-ai.js`/`package.json`/`README.md`) for board-polling sync. Fill in the TODOs (and add a real `templates/root/` scaffold) against an actual project before relying on it.
 
 ## Skills
 
@@ -125,7 +124,7 @@ npx @eventmodelers/cli init --stack <name>          # scaffold a stack + 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)
+npx @eventmodelers/cli run --local-ai [target]      # same, via a local/self-hosted model (ralph-local-ai.js)
 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
@@ -162,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`
@@ -328,7 +335,7 @@ npx @eventmodelers/cli bridge
 
 `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.
 
-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 `--ollama` for the local-Ollama runner instead (same caveat as build-kit's `--ollama`: `lib/ollama-agent.js` is shared as-is).
+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).
 
 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:
 
@@ -347,7 +354,7 @@ npx @eventmodelers/cli init --bridge --target spec-kitty --hook "git add .slices
 npx @eventmodelers/cli bridge
 ```
 
-`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 — `--ollama`, `--hook`, and `--claude` are mutually exclusive.
+`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.
 

package/cli.js

@@ -31,8 +31,8 @@ const __dirname = dirname(__filename);
 
 // Each stack is a template set under stacks/<key>/templates/{.claude,root,<kitSubdir>}.
 // Stacks with useShared:true also get shared/build-kit/* copied into their kit dir
-// first (ralph.js, ralph-claude.js, ralph-ollama.js, ralph.sh, realtime-agent.js,
-// code-export.mjs, lib/agent.sh, lib/ollama-agent.js, package.json, README.md) —
+// first (ralph.js, ralph-claude.js, ralph-local-ai.js, ralph.sh, realtime-agent.js,
+// code-export.mjs, lib/agent.sh, lib/local-ai-agent.js, package.json, README.md) —
 // those files have no per-stack content, so they live once instead of being
 // copy-pasted into every stack (that copy-pasting is exactly how they drifted out
 // of sync before: a bugfix or default landing in one stack's copy but not another's).
@@ -41,6 +41,29 @@ const __dirname = dirname(__filename);
 // modeling-kit (below) is the one kit that opts out of all of this (useShared:false)
 // — it has no cold-spawn/tasks.json runtime at all, so none of shared/build-kit/*
 // applies to it; see its own templates/kit for its (much smaller) self-contained set.
+// --- Local-AI runner selection ------------------------------------------------
+// One runner drives every local/self-hosted backend. What differs between Ollama,
+// vLLM, LM Studio and llama.cpp is the wire dialect (native /api/chat vs the
+// OpenAI-compatible /v1/chat/completions) plus a default URL — both handled inside
+// lib/local-ai-agent.js. Splitting this per vendor would multiply the one file that
+// is currently shared across every stack, so these are presets, not runners.
+// Claude (ralph-claude.js) stays the default executor; this is opt-in.
+const LOCAL_AI_TARGETS = ['ollama', 'vllm', 'lmstudio', 'llamacpp'];
+
+// null = not requested. true = requested with no preset (the agent then falls back to
+// LOCAL_AI_*/config, defaulting to Ollama). A string is a validated preset name.
+function resolveLocalAiTarget(opts) {
+  const raw = opts.localAi;
+  if (raw === undefined || raw === false) return null;
+  if (raw === true) return true;
+  if (!LOCAL_AI_TARGETS.includes(raw)) {
+    console.error(`❌ Unknown --local-ai target "${raw}" — one of: ${LOCAL_AI_TARGETS.join(', ')}.`);
+    console.error('   Any other OpenAI-compatible server works by URL instead: LOCAL_AI_URL=http://host:8000/v1');
+    process.exit(1);
+  }
+  return raw;
+}
+
 const STACKS = {
   node: {
     label: 'Node.js / TypeScript',
@@ -63,13 +86,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',
@@ -93,7 +109,7 @@ const STACKS = {
   },
   // Frontend-only kits (UI-only: build STATE_CHANGE/STATE_VIEW slices, not
   // AUTOMATION — those belong to whichever backend stack is installed alongside).
-  // react overrides lib/ralph.js (+ralph-claude.js/ralph-ollama.js/package.json/
+  // react overrides lib/ralph.js (+ralph-claude.js/ralph-local-ai.js/package.json/
   // README.md) for board-polling instead of the realtime channel every other
   // stack uses; supabase-react needs no overrides at all — it uses
   // shared/build-kit's realtime agent as-is. react's CLAUDE.md/build-*
@@ -995,7 +1011,7 @@ async function installStack(stackKey, stackCfg, options = {}) {
     }
 
     // Make scripts executable
-    for (const script of ['ralph.sh', 'lib/agent.sh', 'ralph-claude.js', 'ralph-ollama.js']) {
+    for (const script of ['ralph.sh', 'lib/agent.sh', 'ralph-claude.js', 'ralph-local-ai.js']) {
       const p = join(kitDir, script);
       if (existsSync(p)) {
         try { execSync(`chmod +x "${p}"`); } catch {}
@@ -1103,7 +1119,7 @@ async function installStack(stackKey, stackCfg, options = {}) {
     } 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');
+      console.log('  npx @eventmodelers/cli run          (--local-ai or --bash for other runners)\n');
     }
     console.log('Connect this project to an MCP client (Claude Code, VS Code, ...):\n');
     console.log(`  npx @eventmodelers/cli init-mcp\n`);
@@ -3024,7 +3040,7 @@ credentialFlags(program
 credentialFlags(program
   .command('run')
   .description('Start the agent loop from the installed kit dir — build-kit stacks: ralph-claude.js (default); modeling-kit: --modeling, or --standalone, which needs no install at all')
-  .option('--ollama', 'Use ralph-ollama.js instead of the default Claude runner (build-kit stacks only)')
+  .option('--local-ai [target]', `Drive the loop with a local (or self-hosted) model instead of the default Claude runner, via ralph-local-ai.js (build-kit stacks only). Optional target preset picks the URL and wire dialect: ${LOCAL_AI_TARGETS.join(', ')} — bare --local-ai means ollama. Anything OpenAI-compatible (vLLM, LM Studio, llama.cpp, TGI) works by pointing LOCAL_AI_URL at it; see LOCAL_AI_* in the docs. Claude remains the default when this flag is absent.`)
   .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. Runs from a modeling-kit install in this directory, or from the global install (~/.eventmodelers/kit) when there is none. Built into the CLI, not a per-project file.')
   .option('--standalone', 'Let the modeling agent work the board in the background, on its own initiative: on top of direct prompts it subscribes to the board\'s change channel (like the build agents do) and, whenever the board goes quiet after an edit — or has simply been idle for a while — it takes a turn nobody asked for. Changed nodes are a notification, not the task: it judges the model as a whole and fans the work out over parallel subagents, one per changed area (examples on a new node, specs for a new command or read model, a missing attribute along a chain, a screen, a question comment). Filling that detail in while the human keeps modeling is the point — it does not wait for the board to be finished. Implies --modeling.')
@@ -3078,13 +3094,13 @@ credentialFlags(program
     const bridgeKitDir = installedKitDirs.find((d) => d.endsWith(BRIDGE_KIT.kitDirName)) ?? null;
     // A bridge kit is not a build-kit stand-in even though it also reuses
     // lib/ralph.js — it has its own `eventmodelers bridge` entrypoint (no
-    // onPlannedSlice/--ollama/--bash support), so it's excluded here rather
+    // onPlannedSlice/--local-ai/--bash support), so it's excluded here rather
     // than falling through to the generic build-kit runner below.
     const buildKitDir = installedKitDirs.find((d) => d !== modelingKitDir && d !== bridgeKitDir) ?? null;
 
     // No overlap between the two stacks' runtimes: modeling-kit only ever runs the
     // warm, direct-dispatch loop (--modeling); build-kit only ever runs the
-    // cold-spawn/tasks.json loop (default, or --ollama/--bash). Neither falls back
+    // cold-spawn/tasks.json loop (default, or --local-ai/--bash). Neither falls back
     // to the other's mechanism, so each side is gated explicitly below rather than
     // just being left to fail on a missing file.
     // --standalone implies --modeling: it already refused every other runner, so there
@@ -3093,8 +3109,8 @@ credentialFlags(program
     // no meaning for a build kit, which is scaffolded per project by definition.
     if (opts.modeling || opts.standalone || opts.global) {
       const picked = opts.modeling ? '--modeling' : opts.standalone ? '--standalone' : '--global';
-      if (opts.bash || opts.ollama) {
-        console.error(`❌ ${picked} is mutually exclusive with --bash/--ollama — those select a build-kit runner, which the modeling loop has no use for.`);
+      if (opts.bash || opts.localAi) {
+        console.error(`❌ ${picked} is mutually exclusive with --bash/--local-ai — those select a build-kit runner, which the modeling loop has no use for.`);
         process.exit(1);
       }
       if (opts.local) {
@@ -3143,7 +3159,7 @@ credentialFlags(program
       if (modelingKitDir) {
         console.error(`❌ A modeling-kit install (${MODELING_KIT.kitDirName}/) only runs via \`eventmodelers run --modeling\` — there is no cold-spawn/tasks.json loop for modeling-only projects.`);
       } else if (bridgeKitDir) {
-        console.error(`❌ A bridge-kit install (${BRIDGE_KIT.kitDirName}/) only runs via \`eventmodelers bridge\` — it has no --modeling/--ollama/--bash modes.`);
+        console.error(`❌ A bridge-kit install (${BRIDGE_KIT.kitDirName}/) only runs via \`eventmodelers bridge\` — it has no --modeling/--local-ai/--bash modes.`);
       } else {
         console.error(`❌ No kit installed in ${cwd} — run \`eventmodelers install\` first.`);
         console.error('   (A modeling agent needs no install at all: eventmodelers run --standalone --board-id <uuid>)');
@@ -3152,9 +3168,10 @@ credentialFlags(program
     }
     const kitDir = buildKitDir;
 
-    const pickedCount = [opts.bash, opts.ollama].filter(Boolean).length;
+    const localAiTarget = resolveLocalAiTarget(opts);
+    const pickedCount = [opts.bash, localAiTarget !== null].filter(Boolean).length;
     if (pickedCount > 1) {
-      console.error('❌ --bash and --ollama are mutually exclusive — pick one.');
+      console.error('❌ --bash and --local-ai are mutually exclusive — pick one.');
       process.exit(1);
     }
 
@@ -3162,7 +3179,7 @@ credentialFlags(program
     // is just a thin dispatcher so users don't have to remember the kit-dir name or which
     // runner file to invoke. Users (and the agent itself, via AGENT.md) may customize these
     // files freely; `run` always executes whatever is currently on disk.
-    const runner = opts.bash ? 'ralph.sh' : opts.ollama ? 'ralph-ollama.js' : 'ralph-claude.js';
+    const runner = opts.bash ? 'ralph.sh' : localAiTarget !== null ? 'ralph-local-ai.js' : 'ralph-claude.js';
     const runnerPath = join(kitDir, runner);
     if (!existsSync(runnerPath)) {
       console.error(`❌ ${relative(cwd, runnerPath)} not found.`);
@@ -3172,13 +3189,13 @@ credentialFlags(program
     console.log(`▶ Starting ${relative(cwd, runnerPath)}...\n`);
     const cmd = runner.endsWith('.sh') ? `"${runnerPath}"` : `node "${runnerPath}"`;
     try {
-      // Only ralph-claude.js reads RALPH_VERBOSE — the bash loop and the ollama executor have
+      // Only ralph-claude.js reads RALPH_VERBOSE — the bash loop and the local-AI executor have
       // their own separate output paths with no stream-json parsing to gate. RALPH_LOCAL is
       // read by all three runners (ralph.js's startRalph, and ralph.sh directly) to force the
       // local-only branch even when .eventmodelers/config.json has valid credentials.
       // RALPH_AGENT_ID/RALPH_AGENT_NAME (--id/--name) are read in ralph.js's startRalph, so
       // they reach both node runners but not ralph.sh, which has no heartbeat to identify.
-      execSync(cmd, { cwd: kitDir, stdio: 'inherit', env: { ...process.env, RALPH_VERBOSE: opts.verbose ? '1' : '', RALPH_LOCAL: opts.local ? '1' : '', RALPH_AGENT_ID: identity.agentId ?? '', RALPH_AGENT_NAME: identity.agentName ?? '' } });
+      execSync(cmd, { cwd: kitDir, stdio: 'inherit', env: { ...process.env, RALPH_VERBOSE: opts.verbose ? '1' : '', RALPH_LOCAL: opts.local ? '1' : '', RALPH_AGENT_ID: identity.agentId ?? '', RALPH_AGENT_NAME: identity.agentName ?? '', ...(typeof localAiTarget === 'string' ? { LOCAL_AI_TARGET: localAiTarget } : {}) } });
     } catch (err) {
       process.exit(err.status || 1);
     }
@@ -3186,8 +3203,8 @@ credentialFlags(program
 
 program
   .command('bridge')
-  .description('Start the bridge agent loop from the installed .bridge-kit/ — translates board slice changes into another spec framework instead of building code. A deterministic adapter runs with no LLM call if one exists for the configured target (e.g. spec-kitty); otherwise Claude is the default executor. --ollama, --hook, or --claude override the pick.')
-  .option('--ollama', 'Use ralph-ollama.js instead of the default runner')
+  .description('Start the bridge agent loop from the installed .bridge-kit/ — translates board slice changes into another spec framework instead of building code. A deterministic adapter runs with no LLM call if one exists for the configured target (e.g. spec-kitty); otherwise Claude is the default executor. --local-ai, --hook, or --claude override the pick.')
+  .option('--local-ai [target]', `Use ralph-local-ai.js instead of the default runner — a local or self-hosted model. Optional target preset: ${LOCAL_AI_TARGETS.join(', ')} (bare flag means ollama).`)
   .option('--hook <command>', 'Run this shell command instead of an AI agent for each batch of slice changes (e.g. commit + push .slices/ for a CI pipeline to pick up) — overrides any hook persisted via `init --bridge --hook` for this run only')
   .option('--claude', 'Force the Claude runner even if a static adapter exists for this target')
   .action((opts) => {
@@ -3198,8 +3215,9 @@ program
       process.exit(1);
     }
 
-    if ([opts.ollama, opts.hook, opts.claude].filter(Boolean).length > 1) {
-      console.error('❌ --ollama, --hook, and --claude are mutually exclusive — pick one executor.');
+    const localAiTarget = resolveLocalAiTarget(opts);
+    if ([localAiTarget !== null, opts.hook, opts.claude].filter(Boolean).length > 1) {
+      console.error('❌ --local-ai, --hook, and --claude are mutually exclusive — pick one executor.');
       process.exit(1);
     }
 
@@ -3219,8 +3237,8 @@ program
 
     const runner = hookCmd
       ? 'ralph-hook.js'
-      : opts.ollama
-        ? 'ralph-ollama.js'
+      : localAiTarget !== null
+        ? 'ralph-local-ai.js'
         : !opts.claude && hasStaticAdapter
           ? 'ralph-static.js'
           : 'ralph-claude.js';

package/package.json

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

@@ -8,8 +8,11 @@ Ralph's runtime directory. Contains the agent loop, realtime subscription, promp
 # Claude (default)
 node .build-kit/ralph-claude.js
 
-# Local Ollama model — run `ollama serve` first
-OLLAMA_MODEL=qwen3.5:9b node .build-kit/ralph-ollama.js
+# Local or self-hosted model — Ollama (run `ollama serve` first)
+LOCAL_AI_TARGET=ollama node .build-kit/ralph-local-ai.js
+
+# …or any OpenAI-compatible server (vLLM, LM Studio, llama.cpp, TGI)
+LOCAL_AI_TARGET=vllm LOCAL_AI_MODEL=Qwen/Qwen3-8B node .build-kit/ralph-local-ai.js
 
 # Custom project directory (defaults to the parent of .build-kit)
 node .build-kit/ralph-claude.js /path/to/project
@@ -22,7 +25,7 @@ node .build-kit/ralph-claude.js /path/to/project
 | File | Purpose |
 |------|---------|
 | `ralph-claude.js` | Runs the full loop using Claude Code as the executor |
-| `ralph-ollama.js` | Runs the full loop using a local Ollama model |
+| `ralph-local-ai.js` | Runs the full loop using a local/self-hosted model (Ollama, vLLM, LM Studio, llama.cpp) |
 | `ralph.sh` | Shell-based loop — alternative to the JS entry points |
 | `realtime-agent.js` | Standalone realtime agent — only needed to run it in a separate terminal |
 
@@ -31,7 +34,7 @@ node .build-kit/ralph-claude.js /path/to/project
 | File | Purpose |
 |------|---------|
 | `lib/ralph.js` | Shared library — realtime agent + loop logic; imported by the entry points |
-| `lib/ollama-agent.js` | Ollama executor — called by `ralph-ollama.js`, can also run manually |
+| `lib/local-ai-agent.js` | Local-AI executor — called by `ralph-local-ai.js`, can also run manually |
 | `lib/agent.sh` | Thin shell wrapper around `claude` — called by `ralph.sh` |
 | `lib/prompt.md` | Phase 1 prompt: tells Claude how to load a slice from the board |
 | `lib/backend-prompt.md` | Phase 2 prompt: tells Claude how to build a planned slice |
@@ -41,13 +44,13 @@ node .build-kit/ralph-claude.js /path/to/project
 
 **Phase 1** — triggered when `tasks.json` has entries:
 - The realtime agent writes a task to `tasks.json` each time a `slice:changed` event arrives from the board
-- The loop picks it up and runs Claude (or Ollama) with `prompt.md`
+- The loop picks it up and runs Claude (or a local model) with `prompt.md`
 - Claude loads the slice data and updates `.slices/`
 
 **Phase 2** — triggered when any file in `.slices/` contains `"status": "Planned"`:
 - The loop runs Claude with `backend-prompt.md`
 - Claude implements the slice in the project
-- Phase 2 is Claude-only; Ollama mode skips it (ollama-agent handles its own queue)
+- Phase 2 is Claude-only; local-AI mode skips it (local-ai-agent handles its own queue)
 
 Both phases run in a continuous loop with a 3-second idle sleep. The realtime agent runs concurrently in the same process.
 
@@ -63,13 +66,27 @@ node .build-kit/realtime-agent.js
 .build-kit/ralph.sh
 ```
 
-## Ollama configuration
+## Local-AI configuration
+
+`ralph-local-ai.js` drives any local or self-hosted model that can do tool calling.
+Claude (`ralph-claude.js`) stays the default runner — this is opt-in.
 
 ```bash
-OLLAMA_MODEL=qwen3.5:9b         # model to use (default: qwen3.5:9b)
-OLLAMA_URL=http://host:11434   # Ollama server URL (default: http://localhost:11434)
+LOCAL_AI_TARGET=ollama          # preset: ollama | vllm | lmstudio | llamacpp
+LOCAL_AI_URL=http://host:8000/v1  # any OpenAI-compatible server (overrides the preset URL)
+LOCAL_AI_MODEL=qwen3.5:9b       # model name as the server knows it
+LOCAL_AI_API=openai             # force the wire dialect: ollama | openai (normally inferred)
+LOCAL_AI_API_KEY=local          # sent as `Authorization: Bearer` on the openai dialect
+LOCAL_AI_NUM_CTX=32768          # ollama only — context window (default 32768)
 ```
 
+**Do not lower `LOCAL_AI_NUM_CTX`.** The MCP tool schemas are ~16k tokens on their own.
+Ollama's own default is 4096, which silently truncates them — the model then sees a
+fragment of the tool list and invents tool names instead of failing, which is why the
+default here is raised rather than left to the server. On the `openai` dialect the
+equivalent is set when you launch the server (vLLM `--max-model-len 32768`,
+llama.cpp `-c 32768`); an overflow there surfaces as an HTTP 400.
+
 ## Config
 
 Credentials are stored in `.build-kit/.eventmodelers/config.json` (written by `eventmodelers init`):