create-merlin-brain 3.11.0 → 3.12.0

package/bin/install.cjs

@@ -11,6 +11,11 @@
 const isServeMode = process.argv.includes('serve');
 const isInjectMode = process.argv.includes('inject-headers');
 
+// --runtime flag: 'all' | 'claude' | 'codex' | 'opencode' | 'gemini'
+// Default: 'all' (configure all detected runtimes)
+const runtimeFlagIdx = process.argv.indexOf('--runtime');
+const RUNTIME_FLAG = runtimeFlagIdx !== -1 ? (process.argv[runtimeFlagIdx + 1] || 'all') : 'all';
+
 // =============================================================================
 // MODE: inject-headers - Add Merlin reminder to CLAUDE.md files
 // =============================================================================
@@ -101,12 +106,14 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const readline = require('readline');
+const { detectRuntimes, configureRuntimes } = require('./runtime-adapters.cjs');
 
 const CLAUDE_DIR = path.join(os.homedir(), '.claude');
 const MERLIN_DIR = path.join(CLAUDE_DIR, 'merlin');
 const AGENTS_DIR = path.join(CLAUDE_DIR, 'agents');
 const COMMANDS_DIR = path.join(CLAUDE_DIR, 'commands', 'merlin');
 const LOOP_DIR = path.join(CLAUDE_DIR, 'loop');
+const RULES_DIR = path.join(CLAUDE_DIR, 'rules');
 
 const colors = {
   reset: '\x1b[0m',
@@ -838,7 +845,7 @@ async function install() {
   }
 
   // Step 0: Clean up legacy GSD/ccwiki artifacts
-  logStep('0/11', 'Cleaning up legacy installations...');
+  logStep('0/13', 'Cleaning up legacy installations...');
   const cleaned = cleanupLegacy();
   if (cleaned.length > 0) {
     for (const item of cleaned) {
@@ -849,11 +856,24 @@ async function install() {
   }
 
   // Step 1: Ensure Claude Code is installed and up to date
-  logStep('1/11', 'Checking Claude Code...');
+  logStep('1/13', 'Checking Claude Code...');
   const claudeCheck = ensureClaudeCode();
 
-  // Step 2: Install globally for instant startup across all terminals
-  logStep('2/11', 'Installing globally (fast startup for all terminals)...');
+  // Step 2: Detect runtimes
+  logStep('2/13', 'Detecting runtimes...');
+  const detectedRuntimes = detectRuntimes();
+  log(`  ${colors.green}✅${colors.reset} Claude Code (primary)`);
+  for (const rt of detectedRuntimes) {
+    const icon = rt.found ? `${colors.green}✅${colors.reset}` : `${colors.yellow}⬚${colors.reset}`;
+    const suffix = rt.found ? '' : ' (not found)';
+    log(`  ${icon} ${rt.label}${suffix}`);
+  }
+  if (RUNTIME_FLAG === 'claude') {
+    log(`  ${colors.yellow}--runtime claude:${colors.reset} other runtimes will not be configured`);
+  }
+
+  // Step 3: Install globally for instant startup across all terminals
+  logStep('3/13', 'Installing globally (fast startup for all terminals)...');
   try {
     const { execSync } = require('child_process');
     // Check if already installed globally and up-to-date
@@ -893,16 +913,16 @@ async function install() {
     useGlobalBinary = false;
   }
 
-  // Step 3: Create directories
-  logStep('3/11', 'Creating directories...');
+  // Step 4: Create directories
+  logStep('4/13', 'Creating directories...');
   ensureDir(CLAUDE_DIR);
   ensureDir(MERLIN_DIR);
   ensureDir(AGENTS_DIR);
   ensureDir(COMMANDS_DIR);
   logSuccess('Directories created');
 
-  // Step 4: Install Merlin core (workflows, references, templates)
-  logStep('4/11', 'Installing Merlin workflows...');
+  // Step 5: Install Merlin core (workflows, references, templates)
+  logStep('5/13', 'Installing Merlin workflows...');
   const merlinSrc = path.join(filesDir, 'merlin');
   if (fs.existsSync(merlinSrc)) {
     const count = copyDirRecursive(merlinSrc, MERLIN_DIR);
@@ -914,8 +934,8 @@ async function install() {
     logWarn('Merlin workflows not found in package');
   }
 
-  // Step 5: Install agents (tiered)
-  logStep('5/11', 'Installing Merlin agents...');
+  // Step 6: Install agents (tiered)
+  logStep('6/13', 'Installing Merlin agents...');
   const agentsSrc = path.join(filesDir, 'agents');
   if (fs.existsSync(agentsSrc)) {
     // Load agent manifest for tiered display
@@ -942,8 +962,32 @@ async function install() {
     logWarn('Agents not found in package');
   }
 
-  // Step 6: Install commands
-  logStep('6/11', 'Installing /merlin:* commands...');
+  // Step 7: Install path-scoped rules
+  logStep('7/13', 'Installing path-scoped rules...');
+  const rulesSrc = path.join(filesDir, 'rules');
+  if (fs.existsSync(rulesSrc)) {
+    ensureDir(RULES_DIR);
+    const ruleFiles = fs.readdirSync(rulesSrc).filter(f => f.endsWith('.md'));
+    let installedCount = 0;
+    let skippedCount = 0;
+    for (const ruleFile of ruleFiles) {
+      const destPath = path.join(RULES_DIR, ruleFile);
+      // Never overwrite existing user rules — they may have been customized
+      if (fs.existsSync(destPath)) {
+        skippedCount++;
+      } else {
+        fs.copyFileSync(path.join(rulesSrc, ruleFile), destPath);
+        installedCount++;
+      }
+    }
+    if (installedCount > 0) logSuccess(`Installed ${installedCount} path-scoped rule files`);
+    if (skippedCount > 0) logSuccess(`Skipped ${skippedCount} existing rule files (user customizations preserved)`);
+  } else {
+    logWarn('Rules not found in package');
+  }
+
+  // Step 8: Install commands
+  logStep('8/13', 'Installing /merlin:* commands...');
   const commandsSrc = path.join(filesDir, 'commands', 'merlin');
   if (fs.existsSync(commandsSrc)) {
     const count = copyDirRecursive(commandsSrc, COMMANDS_DIR);
@@ -952,8 +996,8 @@ async function install() {
     logWarn('Commands not found in package');
   }
 
-  // Step 7: Install CLAUDE.md
-  logStep('7/11', 'Configuring Claude Code...');
+  // Step 9: Install CLAUDE.md
+  logStep('9/13', 'Configuring Claude Code...');
   const claudeMdSrc = path.join(filesDir, 'CLAUDE.md');
   const claudeMdDest = path.join(CLAUDE_DIR, 'CLAUDE.md');
 
@@ -964,12 +1008,12 @@ async function install() {
     logSuccess('Installed CLAUDE.md (Merlin instructions)');
   }
 
-  // Step 8: Install Merlin Loop (legacy — kept for backward compatibility)
+  // Step 10: Install Merlin Loop (legacy — kept for backward compatibility)
   // NOTE: Claude Code now has a native /loop command that replaces these scripts.
   // Use /merlin:loop-recipes in Claude Code for pre-built loop patterns.
   // These scripts are still copied so existing users and terminal workflows
   // (merlin-loop, merlin session) continue to work without interruption.
-  logStep('8/11', 'Installing Merlin Loop (legacy scripts)...');
+  logStep('10/13', 'Installing Merlin Loop (legacy scripts)...');
   const loopSrc = path.join(filesDir, 'loop');
   if (fs.existsSync(loopSrc)) {
     ensureDir(LOOP_DIR);
@@ -996,12 +1040,13 @@ async function install() {
     logSuccess(`Installed ${count} loop files`);
     logSuccess(`Added 'merlin-loop' command`);
     logSuccess(`Added 'merlin session' command (interactive orchestrator)`);
+    logWarn(`Note: Custom loop scripts are deprecated. Use /loop with /merlin:loop-recipes instead.`);
   } else {
     logWarn('Merlin Loop not found in package');
   }
 
-  // Step 9: Install Claude Code hooks
-  logStep('9/11', 'Installing Claude Code hooks...');
+  // Step 11: Install Claude Code hooks
+  logStep('11/13', 'Installing Claude Code hooks...');
   const HOOKS_DIR = path.join(CLAUDE_DIR, 'hooks');
   const hooksSrc = path.join(filesDir, 'hooks');
   if (fs.existsSync(hooksSrc)) {
@@ -1100,6 +1145,27 @@ async function install() {
       hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/session-end.sh' }]
     });
 
+    // Stop hook: desktop notification (fires after session-end analytics)
+    addHookIfMissing(settings.hooks.Stop, {
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/notify-desktop.sh' }]
+    });
+
+    // Stop hook: webhook notification (Slack / Discord, fire-and-forget)
+    addHookIfMissing(settings.hooks.Stop, {
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/notify-webhook.sh' }]
+    });
+
+    // Stop hook: auto-memory sync (extracts session decisions → Sights cloud)
+    addHookIfMissing(settings.hooks.Stop, {
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/session-end-memory-sync.sh' }]
+    });
+
+    // Notification hook: desktop alert when Claude needs input
+    settings.hooks.Notification = settings.hooks.Notification || [];
+    addHookIfMissing(settings.hooks.Notification, {
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/notify-desktop.sh' }]
+    });
+
     // TeammateIdle hook (Agent Teams quality gate — only fires when Teams active)
     settings.hooks.TeammateIdle = settings.hooks.TeammateIdle || [];
     addHookIfMissing(settings.hooks.TeammateIdle, {
@@ -1124,6 +1190,48 @@ async function install() {
       hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/task-completed-verify.sh' }]
     });
 
+    // InstructionsLoaded hook (cold-start Sights pre-warm)
+    settings.hooks.InstructionsLoaded = settings.hooks.InstructionsLoaded || [];
+    addHookIfMissing(settings.hooks.InstructionsLoaded, {
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/instructions-loaded.sh' }]
+    });
+
+    // WorktreeCreate hook (propagate Merlin config into new worktrees)
+    settings.hooks.WorktreeCreate = settings.hooks.WorktreeCreate || [];
+    addHookIfMissing(settings.hooks.WorktreeCreate, {
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/worktree-create.sh' }]
+    });
+
+    // WorktreeRemove hook (cleanup + lifecycle analytics)
+    settings.hooks.WorktreeRemove = settings.hooks.WorktreeRemove || [];
+    addHookIfMissing(settings.hooks.WorktreeRemove, {
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/worktree-remove.sh' }]
+    });
+
+    // ConfigChange hook (validate API key + audit trail)
+    settings.hooks.ConfigChange = settings.hooks.ConfigChange || [];
+    addHookIfMissing(settings.hooks.ConfigChange, {
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/config-change.sh' }]
+    });
+
+    // PostToolUse: file size enforcement (implementation agents only)
+    addHookIfMissing(settings.hooks.PostToolUse, {
+      matcher: 'Edit|Write',
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/check-file-size.sh' }]
+    });
+
+    // PreToolUse: security scanner (prompt injection, secrets, data exfiltration)
+    addHookIfMissing(settings.hooks.PreToolUse, {
+      matcher: 'Write|Edit|Bash|NotebookEdit',
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/security-scanner.sh' }]
+    });
+
+    // PreToolUse: smart bash auto-approval (read-only safe, dangerous blocked, unknown pass-through)
+    addHookIfMissing(settings.hooks.PreToolUse, {
+      matcher: 'Bash',
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/smart-approve.sh' }]
+    });
+
     // --- Prompt-based hooks cleanup & registration ---
     // Remove ALL prompt-type hooks from Merlin (identified by type: 'prompt').
     // This prevents duplicates across version upgrades and removes broken hooks.
@@ -1144,6 +1252,10 @@ async function install() {
     settings.hooks.Notification = removeAllPromptHooks(settings.hooks.Notification);
     settings.hooks.TaskCompleted = settings.hooks.TaskCompleted || [];
     settings.hooks.TaskCompleted = removeAllPromptHooks(settings.hooks.TaskCompleted);
+    settings.hooks.InstructionsLoaded = removeAllPromptHooks(settings.hooks.InstructionsLoaded || []);
+    settings.hooks.WorktreeCreate = removeAllPromptHooks(settings.hooks.WorktreeCreate || []);
+    settings.hooks.WorktreeRemove = removeAllPromptHooks(settings.hooks.WorktreeRemove || []);
+    settings.hooks.ConfigChange = removeAllPromptHooks(settings.hooks.ConfigChange || []);
 
     // NOTE: The PreToolUse prompt hook has been REMOVED. It caused an infinite
     // rejection loop because the evaluator model cannot see conversation history
@@ -1189,8 +1301,8 @@ async function install() {
     return cfg;
   }
 
-  // Step 10: Optional Merlin Sights configuration
-  logStep('10/11', 'Merlin Sights configuration...');
+  // Step 12: Optional Merlin Sights configuration
+  logStep('12/13', 'Merlin Sights configuration...');
 
   // Check if API key is already configured (skip prompt on updates)
   let existingApiKey = '';
@@ -1321,8 +1433,20 @@ async function install() {
     logWarn('Skipped Merlin Sights (you can configure it later)');
   }
 
-  // Step 11: Set up shell integration
-  logStep('11/11', 'Setting up shell integration...');
+  // Step 13: Configure non-Claude-Code runtimes
+  logStep('13/13', 'Configuring additional runtimes...');
+  configureRuntimes({
+    runtimeFlag: RUNTIME_FLAG,
+    useGlobalBinary,
+    apiKey,
+    logSuccess,
+    logWarn,
+    logInfo: (msg) => log(msg),
+    quiet: true, // step 2 already printed the detection summary
+  });
+
+  // Shell integration (runs after runtime adapters)
+  log(`\n${colors.cyan}[shell]${colors.reset} Setting up shell integration...`);
   const shellConfigured = setupShellIntegration();
   if (shellConfigured) {
     log(`\n  ${colors.yellow}IMPORTANT:${colors.reset} Run ${colors.cyan}source ~/.zshrc${colors.reset} or ${colors.bright}restart your terminal${colors.reset}`);

package/bin/runtime-adapters.cjs

@@ -0,0 +1,396 @@
+// MERLIN RUNTIME ADAPTERS
+// Detects and configures Merlin for non-Claude-Code runtimes.
+// Claude Code is always handled by the main installer (install.cjs).
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+// ---------------------------------------------------------------------------
+// Runtime definitions
+// ---------------------------------------------------------------------------
+
+const RUNTIMES = [
+  {
+    id: 'codex',
+    label: 'Codex CLI',
+    configDir: path.join(os.homedir(), '.codex'),
+    binary: 'codex',
+  },
+  {
+    id: 'opencode',
+    label: 'OpenCode',
+    configDir: path.join(os.homedir(), '.opencode'),
+    binary: 'opencode',
+  },
+  {
+    id: 'gemini',
+    label: 'Gemini CLI',
+    configDir: path.join(os.homedir(), '.gemini'),
+    binary: 'gemini',
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Detection helpers
+// ---------------------------------------------------------------------------
+
+function inPath(binary) {
+  try {
+    execSync(`which ${binary} 2>/dev/null`, { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function detectRuntimes() {
+  return RUNTIMES.map((rt) => ({
+    ...rt,
+    found: fs.existsSync(rt.configDir) || inPath(rt.binary),
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// MCP server command helper (mirrors logic in install.cjs)
+// ---------------------------------------------------------------------------
+
+function buildMcpCommand(useGlobalBinary) {
+  if (useGlobalBinary) {
+    return { command: 'merlin-brain', args: undefined };
+  }
+  return { command: 'node', args: [path.join(__dirname, 'serve.js')] };
+}
+
+// ---------------------------------------------------------------------------
+// AGENTS.md content for instruction-file runtimes
+// ---------------------------------------------------------------------------
+
+function buildAgentsMd() {
+  return `# Merlin Brain — AI Development System
+
+> Installed by Merlin (https://merlin.build). Keep this file to preserve Merlin context.
+>
+> Note: Tool names in these instructions reflect Claude Code conventions (Read, Write, Edit,
+> Bash, Grep, Glob). Names may differ in your runtime — adapt as needed.
+
+## Boot Sequence (run at session start)
+
+1. Call \`merlin_get_selected_repo\` — connect Merlin Sights to this project.
+2. Call \`merlin_get_project_status\` — load current project state and active tasks.
+3. Show a brief status summary, then handle the user's request.
+
+Do NOT skip these steps. Do NOT start working without Merlin context.
+
+## Before Every File Edit
+
+Call \`merlin_get_context("your task")\` before writing or modifying any code.
+
+## Routing Specialist Work
+
+Route tasks to the right specialist agent:
+- Architecture decisions → system-architect
+- Implementation → implementation-dev
+- Testing → tests-qa
+- Security review → merlin-security
+- Documentation → docs-keeper
+
+## MCP Tools Available
+
+The Merlin MCP server exposes these tools:
+- \`merlin_get_selected_repo\` — identify current repository
+- \`merlin_get_project_status\` — load tasks and project state
+- \`merlin_get_context(task)\` — fetch relevant code context for a task
+- \`merlin_find_files(query)\` — locate files by description
+- \`merlin_search(query)\` — semantic code search
+
+## Core Principles
+
+- Always search before writing — reuse existing functions and patterns.
+- Keep files under 400 lines — split into sub-modules when approaching the limit.
+- Graceful failure — if Merlin Sights is unavailable, continue with file exploration.
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Codex CLI adapter
+// Writes: ~/.codex/AGENTS.md + ~/.codex/config.toml (MCP section)
+// ---------------------------------------------------------------------------
+
+function configureCodex(rt, useGlobalBinary, apiKey) {
+  const results = [];
+
+  // Ensure config dir exists
+  if (!fs.existsSync(rt.configDir)) {
+    fs.mkdirSync(rt.configDir, { recursive: true });
+  }
+
+  // Write AGENTS.md
+  const agentsMdPath = path.join(rt.configDir, 'AGENTS.md');
+  const agentsMd = buildAgentsMd();
+  const existingAgentsMd = fs.existsSync(agentsMdPath)
+    ? fs.readFileSync(agentsMdPath, 'utf8')
+    : '';
+
+  if (existingAgentsMd.includes('Merlin Brain')) {
+    results.push('AGENTS.md already has Merlin (skipped)');
+  } else {
+    const combined = existingAgentsMd
+      ? existingAgentsMd.trimEnd() + '\n\n---\n\n' + agentsMd
+      : agentsMd;
+    fs.writeFileSync(agentsMdPath, combined);
+    results.push('Wrote ~/.codex/AGENTS.md');
+  }
+
+  // Write / update config.toml with MCP section
+  const configTomlPath = path.join(rt.configDir, 'config.toml');
+  const { command, args } = buildMcpCommand(useGlobalBinary);
+  const argsToml = args
+    ? `args = [${args.map((a) => `"${a}"`).join(', ')}]`
+    : '';
+  const envToml = apiKey ? `\n  MERLIN_API_KEY = "${apiKey}"` : '';
+  const mcpToml = `
+[mcp.merlin]
+command = "${command}"
+${argsToml ? argsToml + '\n' : ''}${apiKey ? `[mcp.merlin.env]${envToml}\n` : ''}`;
+
+  let tomlContent = fs.existsSync(configTomlPath)
+    ? fs.readFileSync(configTomlPath, 'utf8')
+    : '';
+
+  if (tomlContent.includes('[mcp.merlin]')) {
+    results.push('config.toml already has Merlin MCP (skipped)');
+  } else {
+    fs.appendFileSync(configTomlPath, mcpToml);
+    results.push('Added Merlin MCP to ~/.codex/config.toml');
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// OpenCode adapter
+// Writes: ~/.opencode/config.json (mcpServers section) + ~/.opencode/AGENTS.md
+// ---------------------------------------------------------------------------
+
+function configureOpenCode(rt, useGlobalBinary, apiKey) {
+  const results = [];
+
+  if (!fs.existsSync(rt.configDir)) {
+    fs.mkdirSync(rt.configDir, { recursive: true });
+  }
+
+  // MCP config JSON
+  const configJsonPath = path.join(rt.configDir, 'config.json');
+  let config = {};
+  if (fs.existsSync(configJsonPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(configJsonPath, 'utf8'));
+    } catch {
+      config = {};
+    }
+  }
+
+  config.mcpServers = config.mcpServers || {};
+  if (config.mcpServers.merlin) {
+    results.push('config.json already has Merlin MCP (skipped)');
+  } else {
+    const { command, args } = buildMcpCommand(useGlobalBinary);
+    const mcpEntry = { command, type: 'stdio' };
+    if (args) mcpEntry.args = args;
+    if (apiKey) mcpEntry.env = { MERLIN_API_KEY: apiKey };
+    config.mcpServers.merlin = mcpEntry;
+    fs.writeFileSync(configJsonPath, JSON.stringify(config, null, 2));
+    results.push('Added Merlin MCP to ~/.opencode/config.json');
+  }
+
+  // Instructions file
+  const agentsMdPath = path.join(rt.configDir, 'AGENTS.md');
+  const existingAgentsMd = fs.existsSync(agentsMdPath)
+    ? fs.readFileSync(agentsMdPath, 'utf8')
+    : '';
+  if (existingAgentsMd.includes('Merlin Brain')) {
+    results.push('AGENTS.md already has Merlin (skipped)');
+  } else {
+    const combined = existingAgentsMd
+      ? existingAgentsMd.trimEnd() + '\n\n---\n\n' + buildAgentsMd()
+      : buildAgentsMd();
+    fs.writeFileSync(agentsMdPath, combined);
+    results.push('Wrote ~/.opencode/AGENTS.md');
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Gemini CLI adapter
+// Writes: ~/.gemini/GEMINI.md + ~/.gemini/settings.json (mcpServers section)
+// ---------------------------------------------------------------------------
+
+function configureGemini(rt, useGlobalBinary, apiKey) {
+  const results = [];
+
+  if (!fs.existsSync(rt.configDir)) {
+    fs.mkdirSync(rt.configDir, { recursive: true });
+  }
+
+  // GEMINI.md instructions file
+  const geminiMdPath = path.join(rt.configDir, 'GEMINI.md');
+  const existingGeminiMd = fs.existsSync(geminiMdPath)
+    ? fs.readFileSync(geminiMdPath, 'utf8')
+    : '';
+  if (existingGeminiMd.includes('Merlin Brain')) {
+    results.push('GEMINI.md already has Merlin (skipped)');
+  } else {
+    const combined = existingGeminiMd
+      ? existingGeminiMd.trimEnd() + '\n\n---\n\n' + buildAgentsMd()
+      : buildAgentsMd();
+    fs.writeFileSync(geminiMdPath, combined);
+    results.push('Wrote ~/.gemini/GEMINI.md');
+  }
+
+  // settings.json MCP config
+  const settingsPath = path.join(rt.configDir, 'settings.json');
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch {
+      settings = {};
+    }
+  }
+
+  settings.mcpServers = settings.mcpServers || {};
+  if (settings.mcpServers.merlin) {
+    results.push('settings.json already has Merlin MCP (skipped)');
+  } else {
+    const { command, args } = buildMcpCommand(useGlobalBinary);
+    const mcpEntry = { command };
+    if (args) mcpEntry.args = args;
+    if (apiKey) mcpEntry.env = { MERLIN_API_KEY: apiKey };
+    settings.mcpServers.merlin = mcpEntry;
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+    results.push('Added Merlin MCP to ~/.gemini/settings.json');
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Per-project runtime files
+// Writes AGENTS.md alongside CLAUDE.md when initializing a project.
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate per-project runtime instruction files next to a CLAUDE.md.
+ * Call this whenever Merlin creates or updates a project's CLAUDE.md.
+ *
+ * @param {string} projectDir  - Absolute path to the project directory
+ * @param {string[]} runtimeIds - Which runtime files to generate ('codex'|'opencode'|'gemini'|'all')
+ */
+function generateProjectRuntimeFiles(projectDir, runtimeIds = ['all']) {
+  const results = [];
+  const targets = runtimeIds.includes('all')
+    ? ['codex', 'opencode', 'gemini']
+    : runtimeIds;
+
+  const agentsMd = buildAgentsMd();
+
+  // AGENTS.md — used by Codex and OpenCode
+  if (targets.includes('codex') || targets.includes('opencode')) {
+    const agentsMdPath = path.join(projectDir, 'AGENTS.md');
+    if (!fs.existsSync(agentsMdPath)) {
+      fs.writeFileSync(agentsMdPath, agentsMd);
+      results.push(`Created ${agentsMdPath}`);
+    }
+  }
+
+  // GEMINI.md — used by Gemini CLI
+  if (targets.includes('gemini')) {
+    const geminiMdPath = path.join(projectDir, 'GEMINI.md');
+    if (!fs.existsSync(geminiMdPath)) {
+      fs.writeFileSync(geminiMdPath, agentsMd);
+      results.push(`Created ${geminiMdPath}`);
+    }
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point called from install.cjs
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect and configure all non-Claude-Code runtimes.
+ *
+ * @param {object} opts
+ * @param {string}   opts.runtimeFlag     - Value of --runtime flag ('all'|'claude'|runtime-id)
+ * @param {boolean}  opts.useGlobalBinary - Whether merlin-brain global binary is available
+ * @param {string}   opts.apiKey          - Merlin Sights API key (may be empty)
+ * @param {Function} opts.logSuccess      - Logging helper
+ * @param {Function} opts.logWarn         - Logging helper
+ * @param {Function} opts.logInfo         - Plain log helper (console.log compatible)
+ * @param {boolean}  [opts.quiet]         - If true, skip printing the detection summary
+ * @returns {{ detected: object[], configured: string[] }}
+ */
+function configureRuntimes({ runtimeFlag, useGlobalBinary, apiKey, logSuccess, logWarn, logInfo, quiet }) {
+  const detected = detectRuntimes();
+
+  // Print detection summary (skipped when caller already printed it)
+  if (!quiet) {
+    for (const rt of detected) {
+      const icon = rt.found ? '\u2705' : '\u2B1A';
+      const suffix = rt.found ? '' : ' (not found)';
+      logInfo(`  ${icon} ${rt.label}${suffix}`);
+    }
+  }
+
+  // Determine which runtimes to configure
+  const skip = runtimeFlag === 'claude'; // --runtime claude → Claude Code only
+  if (skip) {
+    if (!quiet) logInfo('  Skipping other runtimes (--runtime claude)');
+    return { detected, configured: [] };
+  }
+
+  const filterToOne = !['all', 'claude', undefined, ''].includes(runtimeFlag);
+  const targetRuntimes = filterToOne
+    ? detected.filter((rt) => rt.found && rt.id === runtimeFlag)
+    : detected.filter((rt) => rt.found);
+
+  const configured = [];
+
+  for (const rt of targetRuntimes) {
+    let results = [];
+    try {
+      if (rt.id === 'codex') {
+        results = configureCodex(rt, useGlobalBinary, apiKey);
+      } else if (rt.id === 'opencode') {
+        results = configureOpenCode(rt, useGlobalBinary, apiKey);
+      } else if (rt.id === 'gemini') {
+        results = configureGemini(rt, useGlobalBinary, apiKey);
+      } else {
+        logWarn(`  Unknown runtime "${rt.id}" — skipped`);
+        continue;
+      }
+      for (const msg of results) {
+        logSuccess(msg);
+        configured.push(msg);
+      }
+    } catch (err) {
+      logWarn(`  Failed to configure ${rt.label}: ${err.message}`);
+    }
+  }
+
+  return { detected, configured };
+}
+
+module.exports = {
+  detectRuntimes,
+  configureRuntimes,
+  generateProjectRuntimeFiles,
+  buildAgentsMd,
+};