@eventmodelers/cli 0.0.7 → 0.0.9

package/cli.js

@@ -1,29 +1,37 @@
 #!/usr/bin/env node
 
 import { Command } from 'commander';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 import { dirname, join, relative, resolve, sep } from 'path';
 import {
   existsSync,
   mkdirSync,
   cpSync,
+  copyFileSync,
   rmSync,
   readdirSync,
   writeFileSync,
   readFileSync,
   appendFileSync,
 } from 'fs';
-import { execSync } from 'child_process';
+import { execSync, spawn } from 'child_process';
 import { createInterface, emitKeypressEvents, moveCursor, clearScreenDown } from 'readline';
 import { homedir } from 'os';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-// Each backend stack is a template set under stacks/<key>/templates/{.claude,root,build-kit}.
-// They also get shared/build-kit/* copied into their kit dir first — those files
-// (ralph-ollama.js, realtime-agent.js, code-export.mjs, lib/ollama-agent.js, package.json)
-// are identical across all of them.
+// 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) —
+// 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).
+// Each stack's own templates/<kitSubdir>/* is then overlaid on top for genuine
+// per-stack differences (ralph-claude.js's build tooling, lib/prompt.md, etc.) —
+// see stacks/modeling-kit for an example of a kit with fully different entry-point
+// logic that still reuses the shared runtime pieces.
 const STACKS = {
   node: {
     label: 'Node.js / TypeScript',
@@ -62,7 +70,7 @@ const MODELING_KIT = {
   label: 'Modeling only — skills + agent loop, no backend scaffold',
   kitSubdir: 'kit',
   kitDirName: '.agent-modeling-kit',
-  useShared: false,
+  useShared: true,
   needsBoardId: false,
 };
 
@@ -88,6 +96,112 @@ const MCP_MANUAL_CLIENTS = [
   { label: 'Windsurf', hint: (url) => `Add an HTTP MCP server pointing at ${url} in Windsurf's MCP settings` },
 ];
 
+// Other AI agent hosts can read our Event Modeling skills without us duplicating
+// skill content per host: a thin stub file in the host's own command/workflow
+// directory tells it to go read the canonical .claude/skills/<name>/SKILL.md and
+// follow it — the same pattern spec-kitty uses (verified directly against its repo,
+// not just its docs: every "stub" host below reads plain Markdown, no per-host
+// format transform needed). Codex CLI, Mistral Vibe, Pi, and Letta Code share one
+// convention that already matches our native SKILL.md format, so those get the
+// real file copied as-is instead of a stub.
+const AGENT_HOSTS = {
+  cursor: { label: 'Cursor', dir: '.cursor/commands', kind: 'stub' },
+  windsurf: { label: 'Windsurf', dir: '.windsurf/workflows', kind: 'stub' },
+  gemini: { label: 'Google Gemini CLI', dir: '.gemini/commands', kind: 'stub' },
+  qwen: { label: 'Qwen Code', dir: '.qwen/commands', kind: 'stub' },
+  opencode: { label: 'OpenCode', dir: '.opencode/command', kind: 'stub' },
+  copilot: { label: 'GitHub Copilot', dir: '.github/prompts', kind: 'stub' },
+  amazonq: { label: 'Amazon Q (legacy)', dir: '.amazonq/prompts', kind: 'stub' },
+  kiro: { label: 'Kiro', dir: '.kiro/prompts', kind: 'stub' },
+  kilocode: { label: 'Kilocode', dir: '.kilocode/workflows', kind: 'stub' },
+  augment: { label: 'Augment Code', dir: '.augment/commands', kind: 'stub' },
+  antigravity: { label: 'Google Antigravity', dir: '.agent/workflows', kind: 'stub' },
+  codex: {
+    label: 'Codex CLI / Mistral Vibe / Pi / Letta Code (shared .agents/skills/ convention)',
+    dir: '.agents/skills',
+    kind: 'skill-package',
+  },
+};
+
+function agentHostStub(skillName) {
+  return `# ${skillName} (eventmodelers)\n\nThis host should read the canonical skill at:\n\n**\`.claude/skills/${skillName}/SKILL.md\`**\n\nFollow those instructions when this command is invoked.\n`;
+}
+
+// Writes stub/skill-package files for the requested hosts and records exactly what
+// it wrote into every installed kit dir's manifest — same convention as
+// `mcpRegistered` — so `uninstall` can remove precisely these files later.
+async function configureAgentHosts({ hosts, global: useGlobal } = {}) {
+  const targetDir = process.cwd();
+  const skillsDir = useGlobal ? join(homedir(), '.claude', 'skills') : join(targetDir, '.claude', 'skills');
+
+  if (!existsSync(skillsDir)) {
+    console.error(`❌ No skills found at ${relative(targetDir, skillsDir) || skillsDir} — run \`eventmodelers init\` or \`init-modeling\` first.`);
+    process.exit(1);
+  }
+  const skills = readdirSync(skillsDir).filter((f) => existsSync(join(skillsDir, f, 'SKILL.md')));
+  if (!skills.length) {
+    console.error('❌ No installed skills found — nothing to expose.');
+    process.exit(1);
+  }
+
+  let hostKeys = hosts;
+  if (!hostKeys || !hostKeys.length) {
+    console.log('\nAvailable agent hosts:');
+    Object.entries(AGENT_HOSTS).forEach(([key, h]) => console.log(`  ${key.padEnd(12)} ${h.label}`));
+    const answer = await prompt('\nWhich hosts? (comma-separated keys, or "all"): ');
+    hostKeys = answer.trim() === 'all'
+      ? Object.keys(AGENT_HOSTS)
+      : answer.split(',').map((s) => s.trim()).filter(Boolean);
+  }
+
+  const unknown = hostKeys.filter((k) => !AGENT_HOSTS[k]);
+  if (unknown.length) {
+    console.error(`❌ Unknown host(s): ${unknown.join(', ')}. Available: ${Object.keys(AGENT_HOSTS).join(', ')}`);
+    process.exit(1);
+  }
+  if (!hostKeys.length) {
+    console.log('ℹ️  No hosts selected — nothing to do.');
+    return;
+  }
+
+  console.log(`\n📦 Exposing ${skills.length} skill(s) to ${hostKeys.length} host(s)...`);
+  const generatedFiles = [];
+
+  for (const key of hostKeys) {
+    const host = AGENT_HOSTS[key];
+    if (host.kind === 'stub') {
+      const hostDir = join(targetDir, host.dir);
+      mkdirSync(hostDir, { recursive: true });
+      for (const skill of skills) {
+        const filePath = join(hostDir, `${skill}.md`);
+        writeFileSync(filePath, agentHostStub(skill));
+        generatedFiles.push(relative(targetDir, filePath));
+      }
+    } else {
+      // skill-package: copy the real SKILL.md verbatim — already the native format.
+      for (const skill of skills) {
+        const pkgDir = join(targetDir, host.dir, `eventmodelers.${skill}`);
+        mkdirSync(pkgDir, { recursive: true });
+        const dest = join(pkgDir, 'SKILL.md');
+        copyFileSync(join(skillsDir, skill, 'SKILL.md'), dest);
+        generatedFiles.push(relative(targetDir, dest));
+      }
+    }
+    console.log(`  ✓ ${host.label} (${host.dir}/)`);
+  }
+
+  for (const dirName of KIT_DIR_NAMES) {
+    const manifestPath = join(targetDir, dirName, '.eventmodelers', 'install-manifest.json');
+    if (existsSync(manifestPath)) {
+      const manifest = readJsonSafe(manifestPath);
+      manifest.agentHostFiles = [...new Set([...(manifest.agentHostFiles || []), ...generatedFiles])];
+      writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    }
+  }
+
+  console.log(`\n✅ Done — ${generatedFiles.length} file(s) written.`);
+}
+
 // Every config field can also be set via an EVENTMODELERS_* env var — these always
 // win over whatever's in config.json, so scripted/CI installs can skip prompts entirely.
 const ENV_CONFIG_MAP = {
@@ -156,11 +270,31 @@ async function promptPasteBlock() {
   return lines.join('\n').trim();
 }
 
+// Platform base URL when a config doesn't specify one — every install method
+// (paste, manual entry, or a hand-edited config.json) should fall back to this
+// rather than silently disabling platform sync.
+const DEFAULT_BASE_URL = 'https://api.eventmodelers.ai';
+
 // Canonical order the account page pastes values in, regardless of which fields a
 // given stack actually requires — a modeling-kit install (no boardId required) still
 // gets a paste containing all 4 fields, so we must not drop the ones we don't need.
 const PASTE_FIELD_ORDER = ['organizationId', 'boardId', 'token'];
 
+// Values are sometimes copied with a "field=" prefix still attached (e.g. lifted
+// straight out of a query string) — and occasionally under the wrong JSON key
+// entirely, e.g. { "organizationId": "token=abc..." }. When a value carries its own
+// "field=" prefix, that's a more reliable source of truth than whatever key/position
+// it was pasted under, so it wins.
+const PASTE_FIELD_ALIASES = { organizationId: 'organizationId', orgId: 'organizationId', boardId: 'boardId', token: 'token', baseUrl: 'baseUrl' };
+
+function splitEmbeddedField(value) {
+  if (typeof value !== 'string') return null;
+  const match = value.match(/^([a-zA-Z]+)=(.+)$/);
+  if (!match) return null;
+  const field = PASTE_FIELD_ALIASES[match[1]];
+  return field ? { field, value: match[2] } : null;
+}
+
 // Accepts either a JSON object (as copied from the account page) or a comma-separated
 // line of values, in PASTE_FIELD_ORDER, with an optional base URL anywhere in the list.
 function parseCredentialsPaste(text, requiredFields) {
@@ -170,11 +304,18 @@ function parseCredentialsPaste(text, requiredFields) {
   try {
     const obj = JSON.parse(trimmed);
     if (obj && typeof obj === 'object') {
+      const raw = {};
+      if (obj.organizationId || obj.orgId) raw.organizationId = obj.organizationId || obj.orgId;
+      if (obj.boardId) raw.boardId = obj.boardId;
+      if (obj.token) raw.token = obj.token;
+      if (obj.baseUrl) raw.baseUrl = obj.baseUrl;
+
       const result = {};
-      if (obj.organizationId || obj.orgId) result.organizationId = obj.organizationId || obj.orgId;
-      if (obj.boardId) result.boardId = obj.boardId;
-      if (obj.token) result.token = obj.token;
-      if (obj.baseUrl) result.baseUrl = obj.baseUrl;
+      for (const [outerKey, value] of Object.entries(raw)) {
+        const embedded = splitEmbeddedField(value);
+        if (embedded) result[embedded.field] = embedded.value;
+        else result[outerKey] = value;
+      }
       if (requiredFields.every((f) => result[f])) return result;
       return null;
     }
@@ -186,18 +327,26 @@ function parseCredentialsPaste(text, requiredFields) {
   const result = {};
   const remaining = [];
   for (const v of values) {
-    if (/^https?:\/\//i.test(v)) result.baseUrl = v;
+    if (/^https?:\/\//i.test(v)) {
+      result.baseUrl = v;
+      continue;
+    }
+    const embedded = splitEmbeddedField(v);
+    if (embedded) result[embedded.field] = embedded.value;
     else remaining.push(v);
   }
-  if (remaining.length < requiredFields.length) return null;
+  if (remaining.length < requiredFields.length - Object.keys(result).length) return null;
   // If more values were pasted than this stack strictly requires (e.g. a boardId
   // in a modeling-kit paste), use the full canonical order so the extra field is
   // still captured instead of being mis-zipped against the shorter requiredFields
   // list and silently dropped/misassigned.
   const fieldOrder = remaining.length > requiredFields.length ? PASTE_FIELD_ORDER : requiredFields;
-  fieldOrder.forEach((field, i) => {
+  let i = 0;
+  for (const field of fieldOrder) {
+    if (result[field]) continue; // already resolved via an embedded "field=" prefix
     if (remaining[i] !== undefined) result[field] = remaining[i];
-  });
+    i++;
+  }
 
   return requiredFields.every((f) => result[f]) ? result : null;
 }
@@ -263,9 +412,15 @@ function findConfigInParents(startDir) {
     const candidate = join(dir, '.eventmodelers', 'config.json');
     if (existsSync(candidate)) return candidate;
     const parent = dirname(dir);
-    if (parent === dir) return null;
+    if (parent === dir) break;
     dir = parent;
   }
+  // Last resort: the walk above only passes through $HOME if the project happens
+  // to live under it. A project outside $HOME (e.g. /tmp/foo) never sees it, so
+  // check it explicitly — this is where `init-config --global` writes account-wide
+  // defaults (organizationId/token) shared across every project.
+  const globalCandidate = join(homedir(), '.eventmodelers', 'config.json');
+  return existsSync(globalCandidate) ? globalCandidate : null;
 }
 
 function readJsonSafe(path) {
@@ -356,6 +511,12 @@ async function installStack(stackKey, stackCfg, options = {}) {
     const targetDir = process.cwd();
     const templatesSource = join(__dirname, 'stacks', stackKey, 'templates');
     const sharedBuildKit = join(__dirname, 'shared', 'build-kit');
+    // Skills with no stack-specific content (connect, learn-eventmodelers-api,
+    // update-slice-status, ...) live once here instead of being copy-pasted into
+    // every stack's templates — that copy-pasting is exactly how they drifted out
+    // of sync with each other before (e.g. one stack's connect skill silently
+    // missing a bugfix another stack's copy had).
+    const sharedSkills = join(__dirname, 'shared', 'skills');
 
     if (!existsSync(templatesSource)) {
       console.error('❌ Templates directory not found at:', templatesSource);
@@ -366,16 +527,21 @@ async function installStack(stackKey, stackCfg, options = {}) {
     // Recorded into the install manifest (step 8) so `uninstall` can remove exactly
     // these files later and nothing the user added independently.
     const claudeSkillsSrc = join(templatesSource, '.claude', 'skills');
-    const installedSkills = existsSync(claudeSkillsSrc) ? readdirSync(claudeSkillsSrc) : [];
+    const installedSkills = [
+      ...(existsSync(sharedSkills) ? readdirSync(sharedSkills) : []),
+      ...(existsSync(claudeSkillsSrc) ? readdirSync(claudeSkillsSrc) : []),
+    ];
     let claudeExtras = [];
 
     if (options.global) {
       const globalSkillsDir = join(homedir(), '.claude', 'skills');
       console.log('📦 Installing skills globally...');
+      copyDirContents(sharedSkills, globalSkillsDir);
       copyDirContents(claudeSkillsSrc, globalSkillsDir);
     } else {
       console.log('📦 Installing skills...');
       copyDirContents(join(templatesSource, '.claude'), join(targetDir, '.claude'));
+      copyDirContents(sharedSkills, join(targetDir, '.claude', 'skills'));
       claudeExtras = existsSync(join(templatesSource, '.claude'))
         ? readdirSync(join(templatesSource, '.claude')).filter((f) => f !== 'skills')
         : [];
@@ -426,9 +592,60 @@ async function installStack(stackKey, stackCfg, options = {}) {
     const configPath = options.configPath
       ? resolve(targetDir, options.configPath)
       : join(targetDir, '.eventmodelers', 'config.json');
-    const configDir = dirname(configPath);
-    mkdirSync(configDir, { recursive: true });
 
+    const requiredFields = stackCfg.needsBoardId
+      ? ['organizationId', 'boardId', 'token']
+      : ['organizationId', 'token'];
+
+    const effective = loadEffectiveConfig(targetDir, kitDir, options.configPath);
+    if (effective.sources.length > 1) {
+      console.log(`\n  ✓ Found shared defaults in ${effective.sources[0]}`);
+    }
+
+    const config = await configureCredentials({
+      config: effective.config,
+      configPath,
+      targetDir,
+      requiredFields,
+      boardIdOptional: !stackCfg.needsBoardId,
+      overrides: options.credentialOverrides,
+      print: options.print,
+    });
+
+    // --- 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
+    // deliberately left out and never touched by uninstall.
+    const manifestDir = join(kitDir, '.eventmodelers');
+    mkdirSync(manifestDir, { recursive: true });
+    writeFileSync(
+      join(manifestDir, 'install-manifest.json'),
+      JSON.stringify({ stack: stackKey, global: !!options.global, skills: installedSkills, claudeExtras, mcpRegistered: false }, null, 2),
+    );
+
+    console.log('\n✅ Done! Start your agent:\n');
+    console.log('  npx @eventmodelers/cli run          (--ollama 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`);
+    console.log('Expose these skills to other AI agent hosts (Cursor, Windsurf, Gemini CLI, Copilot, Codex CLI, Kiro, ...):\n');
+    console.log(`  npx @eventmodelers/cli init-agents\n`);
+}
+
+// Extracted from installStack so `init-config` can reuse the exact same
+// paste/manual/instructions/skip flow without also scaffolding a stack.
+// `overrides` are values passed directly on the command line (--token, --board-id,
+// --organization-id, --base-url) — the most explicit source available, so they
+// win over both the config file and env vars before we even check what's missing.
+async function configureCredentials({ config, configPath, targetDir, requiredFields, boardIdOptional, overrides = {}, print, skipGitignore = false, force = false }) {
+  config = { ...config };
+  for (const [field, value] of Object.entries(overrides)) {
+    if (value) config[field] = value;
+  }
+
+  const configDir = dirname(configPath);
+  mkdirSync(configDir, { recursive: true });
+
+  if (!skipGitignore) {
     const gitignorePath = join(targetDir, '.gitignore');
     const relConfigDir = relative(targetDir, configDir);
     if (relConfigDir && !relConfigDir.startsWith('..')) {
@@ -442,147 +659,245 @@ async function installStack(stackKey, stackCfg, options = {}) {
         writeFileSync(gitignorePath, `${gitignoreEntry}\n`);
       }
     }
+  }
 
-    const requiredFields = stackCfg.needsBoardId
-      ? ['organizationId', 'boardId', 'token']
-      : ['organizationId', 'token'];
-
-    const effective = loadEffectiveConfig(targetDir, kitDir, options.configPath);
-    let config = effective.config;
-    if (effective.sources.length > 1) {
-      console.log(`\n  ✓ Found shared defaults in ${effective.sources[0]}`);
-    }
-    const hasConfig = requiredFields.every((f) => config[f]);
-
-    const stillMissing = requiredFields.some((f) => !config[f]);
-    if (stillMissing && options.print) {
-      console.log('\n  ℹ️  --print — skipping credential prompt, missing fields must be set via EVENTMODELERS_* env vars or config.json');
-    } else if (stillMissing) {
-      const choice = await selectPrompt('How do you want to configure credentials?', [
-        { label: 'Paste values copied from app.eventmodelers.ai/account', value: 'paste' },
-        { label: 'Enter values one by one', value: 'manual' },
-        { label: 'Get instructions for configuring later', value: 'instructions' },
-        { label: 'Skip for now', value: 'skip' },
-      ], 1);
-
-      if (choice === 'paste') {
-        console.log('\n  Copy your credentials from https://app.eventmodelers.ai/account,');
-        console.log('  then paste them below and press Enter:\n');
-        const pasted = await promptPasteBlock();
-        const parsed = parseCredentialsPaste(pasted, requiredFields);
-        if (parsed) {
-          config = { ...config, ...parsed };
-          writeFileSync(configPath, JSON.stringify(config, null, 2));
-          console.log(`\n  ✓ Saved to ${relative(targetDir, configPath)}`);
-        } else {
-          console.log(`\n  ⚠️  Couldn't make sense of that paste — nothing was saved.`);
-          console.log(`      Paste it into ${relative(targetDir, configPath)} yourself, or use /connect later.`);
-        }
-      } else if (choice === 'manual') {
-        console.log('\n🔑 Enter your Eventmodelers credentials:\n');
-        config.organizationId = await prompt('  Organization ID: ');
-        // Always ask, even when this stack doesn't strictly require it — it's still
-        // used as a fallback default by the agent loop (see BOARD_ID resolution).
-        const boardId = await prompt(`  Board ID${stackCfg.needsBoardId ? '' : ' (optional)'}: `);
-        if (boardId) config.boardId = boardId;
-        config.token = await prompt('  Token:           ');
+  const stillMissing = force || requiredFields.some((f) => !config[f]);
+  if (stillMissing && print) {
+    console.log('\n  ℹ️  --print — skipping credential prompt, missing fields must be set via flags, EVENTMODELERS_* env vars, or config.json');
+  } else if (stillMissing) {
+    const choice = await selectPrompt('How do you want to configure credentials?', [
+      { label: 'Paste values copied from app.eventmodelers.ai/account', value: 'paste' },
+      { label: 'Enter values one by one', value: 'manual' },
+      { label: 'Get instructions for configuring later', value: 'instructions' },
+      { label: 'Skip for now', value: 'skip' },
+    ], 1);
+
+    if (choice === 'paste') {
+      console.log('\n  Copy your credentials from https://app.eventmodelers.ai/account,');
+      console.log('  then paste them below and press Enter:\n');
+      const pasted = await promptPasteBlock();
+      const parsed = parseCredentialsPaste(pasted, requiredFields);
+      if (parsed) {
+        config = { ...config, ...parsed };
+        if (!config.baseUrl) config.baseUrl = DEFAULT_BASE_URL;
         writeFileSync(configPath, JSON.stringify(config, null, 2));
-        console.log(`\n  ✓ Credentials saved to ${relative(targetDir, configPath)}`);
-      } else if (choice === 'instructions') {
-        console.log(`\n  Paste your credentials into:\n`);
-        console.log(`    ${configPath}`);
-        console.log(`\n  (or any ancestor directory's .eventmodelers/config.json, e.g. ~/.eventmodelers/config.json`);
-        console.log(`  to share the same credentials across multiple projects)\n`);
-        console.log(`  The file should look like:`);
-        const sample = `  {\n    "token": "...",\n    "boardId": "...",\n    "organizationId": "...",\n    "baseUrl": "https://api.eventmodelers.ai"\n  }\n`;
-        console.log(sample);
-        console.log('  Then re-run this installer, or just run the agent afterwards.\n');
+        console.log(`\n  ✓ Saved to ${relative(targetDir, configPath)}`);
       } else {
-        console.log('\n  ℹ️  Skipped — use /connect in Claude Code to add credentials later');
+        console.log(`\n  ⚠️  Couldn't make sense of that paste — nothing was saved.`);
+        console.log(`      Paste it into ${relative(targetDir, configPath)} yourself, or use /connect later.`);
       }
+    } else if (choice === 'manual') {
+      console.log('\n🔑 Enter your Eventmodelers credentials:\n');
+      config.organizationId = await prompt('  Organization ID: ');
+      // Always ask, even when this install doesn't strictly require it — it's still
+      // used as a fallback default by the agent loop (see BOARD_ID resolution).
+      const boardId = await prompt(`  Board ID${boardIdOptional ? ' (optional)' : ''}: `);
+      if (boardId) config.boardId = boardId;
+      config.token = await prompt('  Token:           ');
+      if (!config.baseUrl) config.baseUrl = DEFAULT_BASE_URL;
+      writeFileSync(configPath, JSON.stringify(config, null, 2));
+      console.log(`\n  ✓ Credentials saved to ${relative(targetDir, configPath)}`);
+    } else if (choice === 'instructions') {
+      console.log(`\n  Paste your credentials into:\n`);
+      console.log(`    ${configPath}`);
+      console.log(`\n  (or any ancestor directory's .eventmodelers/config.json, e.g. ~/.eventmodelers/config.json`);
+      console.log(`  to share the same credentials across multiple projects)\n`);
+      console.log(`  The file should look like:`);
+      const sample = `  {\n    "token": "...",\n    "boardId": "...",\n    "organizationId": "...",\n    "baseUrl": "https://api.eventmodelers.ai"\n  }\n`;
+      console.log(sample);
+      console.log('  Then re-run this installer, or just run the agent afterwards.\n');
     } else {
-      console.log('\n  ✓ Config already present — skipping credential prompt');
+      console.log('\n  ℹ️  Skipped — use /connect in Claude Code to add credentials later');
     }
+  } else {
+    console.log('\n  ✓ Config already present — skipping credential prompt');
+  }
 
-    // Claude vs. Ollama, and any custom Anthropic-compatible base URL, is a `run`-time
-    // choice (`eventmodelers run` vs `--ollama`) — not an install-time one. Power users
-    // can still pin config.anthropicBaseUrl/model via EVENTMODELERS_ANTHROPIC_BASE_URL /
-    // EVENTMODELERS_MODEL env vars or by editing config.json directly; loadEffectiveConfig
-    // already picks those up above, so nothing further to do here.
-    writeFileSync(configPath, JSON.stringify(config, null, 2));
-    console.log(`\n  ✓ Saved to ${relative(targetDir, configPath)}`);
+  // Backfill baseUrl for configs that already had real credentials but predate
+  // this default (e.g. a config.json written by hand or by an older CLI version).
+  if (config.token && config.organizationId && !config.baseUrl) {
+    config.baseUrl = DEFAULT_BASE_URL;
+  }
 
-    // --- 6. MCP server in .claude/settings.json ---
-    console.log('🔌 Configuring MCP server...');
-    const claudeSettingsDir = join(targetDir, '.claude');
-    const settingsPath = join(claudeSettingsDir, 'settings.json');
-    mkdirSync(claudeSettingsDir, { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2));
+  console.log(`\n  ✓ Saved to ${relative(targetDir, configPath)}`);
+  return config;
+}
 
-    let settings = {};
-    if (existsSync(settingsPath)) {
+// Configure the MCP server registration for a project — split out of `init` into
+// its own command (`init-mcp`) since not every harness/workflow wants an
+// automatic .claude/settings.json edit or an interactive "connect elsewhere?"
+// prompt bundled into scaffolding.
+async function configureMcp(options = {}) {
+  const targetDir = process.cwd();
+  const effective = loadEffectiveConfig(targetDir, null, options.configPath);
+  const baseUrl = effective.config.baseUrl || DEFAULT_BASE_URL;
+
+  console.log('🔌 Configuring MCP server...');
+  const claudeSettingsDir = join(targetDir, '.claude');
+  const settingsPath = join(claudeSettingsDir, 'settings.json');
+  mkdirSync(claudeSettingsDir, { recursive: true });
+
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    } catch {
+      settings = {};
+    }
+  }
+
+  settings.mcpServers = settings.mcpServers || {};
+  settings.mcpServers.eventmodelers = {
+    type: 'http',
+    url: `${baseUrl}/mcp`,
+  };
+
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+  console.log('  ✓ MCP server configured in .claude/settings.json');
+
+  // Record that MCP was registered so `uninstall` knows to clean up the
+  // settings.json entry — checked against every kit dir's manifest.
+  for (const dirName of KIT_DIR_NAMES) {
+    const manifestPath = join(targetDir, dirName, '.eventmodelers', 'install-manifest.json');
+    if (existsSync(manifestPath)) {
+      const manifest = readJsonSafe(manifestPath);
+      manifest.mcpRegistered = true;
+      writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    }
+  }
+
+  const mcpUrl = `${baseUrl}/mcp`;
+  if (options.print) {
+    console.log('\nConnect the same MCP server in another harness:');
+    for (const client of Object.values(MCP_CLIENTS)) {
+      console.log(`  ${client.label.padEnd(12)} ${client.command(mcpUrl)}`);
+    }
+    for (const client of MCP_MANUAL_CLIENTS) {
+      console.log(`  ${client.label.padEnd(12)} ${client.hint(mcpUrl)}`);
+    }
+  } else {
+    const clientChoice = await selectPrompt('\nConnect the MCP globally to another harness?', [
+      { label: 'Skip', value: 'skip' },
+      ...Object.entries(MCP_CLIENTS).map(([key, c]) => ({ label: c.label, value: key })),
+    ], 0);
+
+    if (clientChoice !== 'skip') {
+      const client = MCP_CLIENTS[clientChoice];
+      const cmd = client.command(mcpUrl);
       try {
-        settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+        execSync(cmd, { stdio: 'inherit' });
+        console.log(`  ✓ ${client.label} connected via: ${cmd}`);
       } catch {
-        settings = {};
+        console.error(`  ⚠️  Command failed — you can run it manually:`);
+        console.error(`       ${cmd}`);
       }
     }
 
-    const baseUrl = config.baseUrl || 'https://api.eventmodelers.ai';
-    settings.mcpServers = settings.mcpServers || {};
-    settings.mcpServers.eventmodelers = {
-      type: 'http',
-      url: `${baseUrl}/mcp`,
-    };
-
-    writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
-    console.log('  ✓ MCP server configured in .claude/settings.json');
+    if (MCP_MANUAL_CLIENTS.length) {
+      console.log('\nOther harnesses without a scriptable installer:');
+      MCP_MANUAL_CLIENTS.forEach((c) => console.log(`  ${c.label.padEnd(12)} ${c.hint(mcpUrl)}`));
+    }
+  }
+}
 
-    const mcpUrl = `${baseUrl}/mcp`;
-    if (options.print) {
-      console.log('\nConnect the same MCP server in another harness:');
-      for (const client of Object.values(MCP_CLIENTS)) {
-        console.log(`  ${client.label.padEnd(12)} ${client.command(mcpUrl)}`);
-      }
-      for (const client of MCP_MANUAL_CLIENTS) {
-        console.log(`  ${client.label.padEnd(12)} ${client.hint(mcpUrl)}`);
-      }
-    } else {
-      const clientChoice = await selectPrompt('\nConnect the MCP globally to another harness?', [
-        { label: 'Skip', value: 'skip' },
-        ...Object.entries(MCP_CLIENTS).map(([key, c]) => ({ label: c.label, value: key })),
-      ], 0);
-
-      if (clientChoice !== 'skip') {
-        const client = MCP_CLIENTS[clientChoice];
-        const cmd = client.command(mcpUrl);
-        try {
-          execSync(cmd, { stdio: 'inherit' });
-          console.log(`  ✓ ${client.label} connected via: ${cmd}`);
-        } catch {
-          console.error(`  ⚠️  Command failed — you can run it manually:`);
-          console.error(`       ${cmd}`);
-        }
+// `run --real-time`: same job as ralph-claude.js (drive the installed kit's ralph
+// loop with Claude as the executor), but instead of spawning a fresh `claude -p`
+// process per task, it keeps ONE process warm across tasks via
+// `--input-format stream-json` and writes each task's prompt to its stdin —
+// verified (see dev notes) to stay alive and accept further turns after a result.
+// This closes the remaining latency gap for voice/live use: the realtime channel
+// + trigger wake in the kit's own lib/ralph.js already deliver new tasks with ~no
+// delay, so the dominant cost left was the cold start (process boot, CLAUDE.md
+// re-read, /connect, skill discovery) a fresh spawn pays every single task.
+//
+// Deliberately NOT a templated file in the kit dir (unlike ralph-claude.js) —
+// this is exactly the kind of stack-agnostic runtime plumbing that drifted out of
+// sync when duplicated per stack before (see the "Unify ralph/agent runtime
+// files" commit). It ships once, here, and reuses whatever lib/ralph.js the kit
+// already has installed — that file legitimately differs per kit (modeling-kit's
+// org-wide prompt queue vs. build-kit's per-board slice tracking), so it stays
+// where `init`/`init-modeling` put it.
+async function runRealtime(kitDir, projectDir) {
+  const ralphLibPath = join(kitDir, 'lib', 'ralph.js');
+  if (!existsSync(ralphLibPath)) {
+    console.error(`❌ ${relative(process.cwd(), ralphLibPath)} not found — --real-time needs a kit installed via \`init\`/\`init-modeling\`.`);
+    process.exit(1);
+  }
+  const { startRalph, loadLocalConfig } = await import(pathToFileURL(ralphLibPath).href);
+
+  const cfg = loadLocalConfig(kitDir);
+  const QUESTIONING_RULE =
+    'IMPORTANT: You are running autonomously — no human is available to answer questions. ' +
+    'If you need clarification to proceed, do NOT pause or ask interactively. Instead, post your question ' +
+    'as a QUESTION-type comment (via /handle-comment with action=place and type=QUESTION) on the most ' +
+    'relevant slice or column node on the board, then continue with your best interpretation of the prompt.\n\n';
+  const inlineHeader = cfg.boardId
+    ? `board=${cfg.boardId} token=${cfg.token} org=${cfg.organizationId} baseUrl=${cfg.baseUrl}\n\n${QUESTIONING_RULE}`
+    : QUESTIONING_RULE;
+
+  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;
+
+  let proc = null;
+  let stdoutBuffer = '';
+  let pending = null; // one in-flight task at a time, matching the ralph loop's own serial processing
+  const log = (line) => console.log(`[realtime] ${line}`);
+
+  // 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.
+  function handleLine(line) {
+    if (!line.trim()) return;
+    let msg;
+    try { msg = JSON.parse(line); } catch { return; }
+
+    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(`→ ${block.name}`);
       }
+      return;
+    }
+    if (msg.type === 'result') {
+      log(`done (${msg.duration_ms}ms${msg.total_cost_usd ? `, $${msg.total_cost_usd.toFixed(4)}` : ''})`);
+      const turn = pending;
+      pending = null;
+      if (turn) (msg.is_error ? turn.reject(new Error(msg.result || 'Claude turn errored')) : turn.resolve());
+    }
+  }
 
-      if (MCP_MANUAL_CLIENTS.length) {
-        console.log('\nOther harnesses without a scriptable installer:');
-        MCP_MANUAL_CLIENTS.forEach((c) => console.log(`  ${c.label.padEnd(12)} ${c.hint(mcpUrl)}`));
+  function spawnProcess() {
+    proc = spawn('claude', claudeArgs, { cwd: projectDir, env: claudeEnv, stdio: ['pipe', 'pipe', 'inherit'] });
+    stdoutBuffer = '';
+    proc.stdout.on('data', (chunk) => {
+      stdoutBuffer += chunk.toString();
+      const lines = stdoutBuffer.split('\n');
+      stdoutBuffer = lines.pop();
+      for (const l of lines) handleLine(l);
+    });
+    proc.on('exit', (code) => {
+      log(`process exited (${code}) — will respawn on next task`);
+      proc = null;
+      if (pending) {
+        const turn = pending;
+        pending = null;
+        turn.reject(new Error(`claude process exited (${code}) mid-turn`));
       }
-    }
+    });
+    log('warm session started');
+  }
 
-    // --- 7. 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
-    // deliberately left out and never touched by uninstall.
-    const manifestDir = join(kitDir, '.eventmodelers');
-    mkdirSync(manifestDir, { recursive: true });
-    writeFileSync(
-      join(manifestDir, 'install-manifest.json'),
-      JSON.stringify({ stack: stackKey, global: !!options.global, skills: installedSkills, claudeExtras, mcpRegistered: true }, null, 2),
-    );
+  function runClaudeWarm(prompt) {
+    if (!proc) spawnProcess();
+    return new Promise((resolveTurn, rejectTurn) => {
+      pending = { resolve: resolveTurn, reject: rejectTurn };
+      proc.stdin.write(JSON.stringify({ type: 'user', message: { role: 'user', content: inlineHeader + prompt } }) + '\n');
+    });
+  }
 
-    console.log('\n✅ Done! Start your agent:\n');
-    console.log('  npx @eventmodelers/cli run          (--ollama or --bash for other runners)\n');
+  spawnProcess();
+  await startRalph({ kitDir, projectDir, onTask: runClaudeWarm });
 }
 
 const program = new Command();
@@ -594,26 +909,131 @@ program
   .option('--config <path>', 'Path to an explicit config.json, overriding directory-based resolution (individual fields can also be set via EVENTMODELERS_* env vars, which always win)')
   .option('--print', 'Print follow-up commands (e.g. claude mcp add) instead of prompting to run them');
 
-program
+// Shared by init/init-modeling/init-config: direct command-line credentials,
+// Protractor-style (--base-url=..., not a generic --param key=value passthrough) —
+// self-documenting in --help and typo-safe. These win over both the config file
+// and EVENTMODELERS_* env vars, same as any explicitly-passed flag should.
+function credentialFlags(cmd) {
+  return cmd
+    .option('--token <uuid>', 'API token (overrides config file / env var)')
+    .option('--board-id <uuid>', 'Board ID (overrides config file / env var)')
+    .option('--organization-id <uuid>', 'Organization ID (overrides config file / env var)')
+    .option('--base-url <url>', 'Platform base URL (overrides config file / env var)');
+}
+
+function credentialOverridesFromOpts(opts) {
+  return { token: opts.token, boardId: opts.boardId, organizationId: opts.organizationId, baseUrl: opts.baseUrl };
+}
+
+credentialFlags(program
   .command('init')
   .alias('install')
   .description('Scaffold a stack + install the agent modeling kit into the current directory')
   .option('--stack <name>', `Stack to install (${Object.keys(STACKS).join(', ')})`)
-  .option('--global', 'Install skills into ~/.claude/skills/ instead of the project — available in every project')
+  .option('--global', 'Install skills into ~/.claude/skills/ instead of the project — available in every project'))
   .action(async (opts, command) => {
     const stackKey = await resolveStack(opts.stack);
     const globalOpts = command.optsWithGlobals();
-    await installStack(stackKey, STACKS[stackKey], { configPath: globalOpts.config, print: globalOpts.print, global: opts.global });
+    await installStack(stackKey, STACKS[stackKey], {
+      configPath: globalOpts.config,
+      print: globalOpts.print,
+      global: opts.global,
+      credentialOverrides: credentialOverridesFromOpts(opts),
+    });
   });
 
-program
+credentialFlags(program
   .command('init-modeling')
   .alias('modeling')
   .description('Install skills + the agent loop only — no backend scaffold')
-  .option('--global', 'Install skills into ~/.claude/skills/ instead of the project — available in every project')
+  .option('--global', 'Install skills into ~/.claude/skills/ instead of the project — available in every project'))
+  .action(async (opts, command) => {
+    const globalOpts = command.optsWithGlobals();
+    await installStack(MODELING_KIT.key, MODELING_KIT, {
+      configPath: globalOpts.config,
+      print: globalOpts.print,
+      global: opts.global,
+      credentialOverrides: credentialOverridesFromOpts(opts),
+    });
+  });
+
+program
+  .command('init-mcp')
+  .description('Register the eventmodelers MCP server in .claude/settings.json (and optionally another harness)')
+  .action(async (opts, command) => {
+    const globalOpts = command.optsWithGlobals();
+    await configureMcp({ configPath: globalOpts.config, print: globalOpts.print });
+  });
+
+program
+  .command('init-agents')
+  .description(`Expose installed skills to other AI agent hosts (${Object.keys(AGENT_HOSTS).join(', ')}) as thin stub commands pointing at the canonical .claude/skills/ files — no skill content duplicated per host`)
+  .option('--hosts <list>', `Comma-separated host keys (${Object.keys(AGENT_HOSTS).join(', ')})`)
+  .option('--all', 'Expose to every known host')
+  .option('--global', 'Read skills from ~/.claude/skills/ instead of the project')
+  .action(async (opts) => {
+    const hosts = opts.all
+      ? Object.keys(AGENT_HOSTS)
+      : opts.hosts
+        ? opts.hosts.split(',').map((s) => s.trim()).filter(Boolean)
+        : null;
+    await configureAgentHosts({ hosts, global: opts.global });
+  });
+
+credentialFlags(program
+  .command('init-config')
+  .description('Configure credentials only — writes .eventmodelers/config.json in the current directory, or ~/.eventmodelers/config.json with --global')
+  .option('--global', 'Write account-wide defaults (organizationId + token only) to ~/.eventmodelers/config.json instead of the project'))
   .action(async (opts, command) => {
     const globalOpts = command.optsWithGlobals();
-    await installStack(MODELING_KIT.key, MODELING_KIT, { configPath: globalOpts.config, print: globalOpts.print, global: opts.global });
+    const overrides = credentialOverridesFromOpts(opts);
+
+    if (opts.global) {
+      // Deliberately narrower than a project config: a board is specific to one
+      // project, and baseUrl already has its own runtime default, so the only
+      // things worth defaulting across every project are your identity (org)
+      // and how you authenticate (token).
+      const configPath = join(homedir(), '.eventmodelers', 'config.json');
+      const requiredFields = ['organizationId', 'token'];
+      const existing = readJsonSafe(configPath);
+      const base = { organizationId: existing.organizationId, token: existing.token };
+      if (overrides.organizationId) base.organizationId = overrides.organizationId;
+      if (overrides.token) base.token = overrides.token;
+
+      const configured = await configureCredentials({
+        config: base,
+        configPath,
+        targetDir: homedir(),
+        requiredFields,
+        boardIdOptional: true,
+        overrides: {},
+        print: globalOpts.print,
+        skipGitignore: true,
+        force: true,
+      });
+
+      // configureCredentials' generic paste/manual flow may have picked up
+      // boardId/baseUrl too (e.g. from a pasted JSON blob) — strip them back out
+      // before the final write, since --global only ever persists identity.
+      writeFileSync(configPath, JSON.stringify({ organizationId: configured.organizationId, token: configured.token }, null, 2));
+      console.log(`\n  ✓ Saved account-wide defaults to ${configPath}`);
+    } else {
+      const targetDir = process.cwd();
+      const configPath = globalOpts.config
+        ? resolve(targetDir, globalOpts.config)
+        : join(targetDir, '.eventmodelers', 'config.json');
+      const effective = loadEffectiveConfig(targetDir, null, globalOpts.config);
+      await configureCredentials({
+        config: effective.config,
+        configPath,
+        targetDir,
+        requiredFields: ['organizationId', 'token'],
+        boardIdOptional: true,
+        overrides,
+        print: globalOpts.print,
+        force: true,
+      });
+    }
   });
 
 program
@@ -621,7 +1041,8 @@ program
   .description('Start the agent loop from the installed kit dir (default: ralph-claude.js)')
   .option('--ollama', 'Use ralph-ollama.js instead of the default Claude runner')
   .option('--bash', 'Use the bash-only ralph.sh loop (no realtime)')
-  .action((opts) => {
+  .option('--real-time', 'Keep one Claude process warm across tasks instead of spawning a fresh one per task, for low-latency voice/live use. Built into the CLI, not a per-project file.')
+  .action(async (opts) => {
     const cwd = process.cwd();
     const kitDir = findInstalledKitDir(cwd);
     if (!kitDir) {
@@ -629,6 +1050,23 @@ program
       process.exit(1);
     }
 
+    const pickedCount = [opts.bash, opts.ollama, opts.realTime].filter(Boolean).length;
+    if (pickedCount > 1) {
+      console.error('❌ --bash, --ollama, and --real-time are mutually exclusive — pick one.');
+      process.exit(1);
+    }
+
+    if (opts.realTime) {
+      console.log(`▶ Starting real-time loop (warm Claude process) for ${relative(cwd, kitDir)}...\n`);
+      try {
+        await runRealtime(kitDir, resolve(kitDir, '..'));
+      } catch (err) {
+        console.error('[realtime] Fatal:', err);
+        process.exit(1);
+      }
+      return;
+    }
+
     // The actual agent loop lives in the scaffolded kit dir, not in this package — this
     // 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
@@ -689,6 +1127,33 @@ function uninstallKitDir(kitDir, cwd) {
     }
   }
 
+  if (manifest.agentHostFiles?.length) {
+    const touchedDirs = new Set();
+    for (const relPath of manifest.agentHostFiles) {
+      const p = join(cwd, relPath);
+      if (existsSync(p)) {
+        rmSync(p, { force: true });
+        console.log(`  ✓ Removed ${relPath}`);
+        touchedDirs.add(dirname(p));
+      }
+    }
+    // Prune now-empty host/package directories (e.g. .cursor/commands/,
+    // .agents/skills/eventmodelers.timeline/) so uninstall doesn't leave an
+    // empty dotfile forest behind — but never walk above cwd.
+    for (const dir of touchedDirs) {
+      let d = dir;
+      while (d.startsWith(cwd) && d !== cwd) {
+        try {
+          if (readdirSync(d).length > 0) break;
+          rmSync(d, { recursive: true, force: true });
+          d = dirname(d);
+        } catch {
+          break;
+        }
+      }
+    }
+  }
+
   if (manifest.mcpRegistered) {
     const settingsPath = join(cwd, '.claude', 'settings.json');
     if (existsSync(settingsPath)) {
@@ -714,7 +1179,7 @@ function uninstallKitDir(kitDir, cwd) {
 
 program
   .command('uninstall')
-  .description('Remove everything init/init-modeling installed: the kit dir, the skills it copied (project-local or ~/.claude/skills with --global), and its MCP entry in .claude/settings.json. Leaves the root project scaffold untouched.')
+  .description('Remove everything init/init-modeling installed: the kit dir, the skills it copied (project-local or ~/.claude/skills with --global), its MCP entry in .claude/settings.json, and any files written by init-agents. Leaves the root project scaffold untouched.')
   .option('--build-kit', `Remove ${STACKS.node.kitDirName}/ (the backend-stack kit dir)`)
   .option('--modeling-kit', `Remove ${MODELING_KIT.kitDirName}/ (the modeling-only kit dir)`)
   .action((opts) => {
@@ -767,7 +1232,7 @@ program
     console.log(`Ralph agent:    ${ralphPath && existsSync(ralphPath) ? '✅ present' : '❌ missing'}`);
 
     if (sources.length) {
-      console.log(`\nConnected to:   ${cfg.baseUrl || 'https://api.eventmodelers.ai'}`);
+      console.log(`\nConnected to:   ${cfg.baseUrl || DEFAULT_BASE_URL}`);
       console.log(`Organization:   ${cfg.organizationId}`);
       if (cfg.boardId) console.log(`Board:          ${cfg.boardId}`);
       console.log(`\nConfig source${sources.length > 1 ? 's (later overrides earlier)' : ''}:`);