@niroai/niro 0.3.0

package/src/mcp/setup.js

@@ -0,0 +1,1976 @@
+#!/usr/bin/env node
+
+/**
+ * Interactive setup for Niro MCP Server.
+ *
+ * Configures the MCP server for Claude Code, Cursor, Windsurf, or other
+ * AI coding assistants. The MCP server URL is resolved automatically
+ * (--url flag > NIRO_MCP_SERVER_URL env > ~/.niro/config.json > cloud
+ * default) and printed — it is never prompted for. Only the API key is
+ * asked, and only when there is no `niro login` session.
+ *
+ * Usage:
+ *   niro mcp install
+ *   niro mcp install --client cursor
+ *   niro mcp install --url https://aiassistant.my-company.internal
+ */
+
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+const { execSync } = require("child_process");
+const config = require("../lib/config");
+const { formatPrompt } = require("../lib/prompt");
+
+/** Cross-platform user home (~). */
+function userHome() {
+  return process.env.HOME || process.env.USERPROFILE || "";
+}
+
+/**
+ * Marker line that brackets the niro section appended to markdown config files
+ * (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, Windsurf global_rules.md). Single source
+ * of truth so the installer (which checks "already present?") and the uninstaller
+ * (which removes the section) can never drift apart.
+ */
+const NIRO_MD_MARKER = "<!-- niro-mcp -->";
+
+/**
+ * The exact niro sections appended to each markdown config file. These are the single source
+ * of truth: the installer appends them and the uninstaller removes them verbatim (so a user's
+ * own notes added below the block survive uninstall — see teardown.js removeMarkerSection).
+ * Each begins with a leading "\n" because install does `existing + section`.
+ */
+const NIRO_MULTI_REPO_SENTENCE = "The temporary project answer is per (repo, BRANCH): after you create/switch a branch in a repo — and before your first edit on that branch — call should_create_temp_project with the repo's git url, its CURRENT branch, and its `.niro-project` id if present, then run `niro new-temp-project` in its folder if needs_temp_project is true. Re-check after every branch change (a `false` from another branch does NOT carry over); this applies to every repo you touch, including when the session started in a parent folder that is not itself a git repo.";
+const NIRO_CLAUDE_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP tools are available for code intelligence. Use them (call chains, blast radius, impact analysis, source lookup) before falling back to native grep/read for code questions.\nBefore adding/writing any new code, you MUST use the find_reusable_code tool from niro to figure out if there is anything reusable.\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+const NIRO_CODEX_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools and the \`niro-skill\` are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase; the niro-skill has the full tool-routing playbook. Before adding or writing any new code, use find_reusable_code to check for reusable code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+const NIRO_WINDSURF_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools and the niro-skill are available. Prefer them over grep/read for questions about this codebase (structure, call chains, blast radius, impact, data flows, reuse); the niro-skill has the full routing playbook. Before writing any new code, use find_reusable_code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+/**
+ * Shared generic section for clients whose "always-on instructions" file has no companion
+ * skill mechanism we've verified (Gemini CLI's GEMINI.md, GitHub Copilot CLI's
+ * copilot-instructions.md, Factory's AGENTS.md, OpenCode's AGENTS.md) — one wording, reused
+ * across those destination files (teardown matches it per-file, so reuse is safe).
+ */
+const NIRO_GENERIC_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase. Before adding or writing any new code, use find_reusable_code to check for reusable code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+
+/** All niro markdown sections — the uninstaller tries each for an exact removal. */
+const NIRO_MD_SECTIONS = [NIRO_CLAUDE_MD_SECTION, NIRO_CODEX_MD_SECTION, NIRO_WINDSURF_MD_SECTION, NIRO_GENERIC_MD_SECTION];
+
+/**
+ * Upsert a niro markdown section into an agent-rules file's existing content. Returns {content, action}:
+ *   - exact section already present            -> {existing, "unchanged"}
+ *   - no niro marker at all                     -> {existing + section, "added"}
+ *   - marker present but content DIFFERS        -> strip the old bounded niro block, append fresh, "refreshed"
+ * The "refreshed" path fixes the review bug where an existing user never received UPDATED instructions (the
+ * new temp-project sentence) because the installer skipped whenever the marker was present. The strip is
+ * bounded: it removes only from the niro block's start to the next top-level `## ` heading (or EOF), so a
+ * user's own sections below the niro block are preserved.
+ */
+function upsertNiroMarkerSection(existing, section) {
+  if (existing.includes(section)) return { content: existing, action: "unchanged" };
+  if (!existing.includes(NIRO_MD_MARKER)) return { content: existing + section, action: "added" };
+  const idx = existing.indexOf(NIRO_MD_MARKER);
+  let start = idx;
+  while (start > 0 && existing[start - 1] === "\n") start--;
+  const ourHeading = existing.indexOf("\n## ", idx);                 // niro's own "## Niro MCP" heading
+  const nextHeading = ourHeading < 0 ? -1 : existing.indexOf("\n## ", ourHeading + 4);
+  const end = nextHeading < 0 ? existing.length : nextHeading;
+  return { content: existing.slice(0, start) + existing.slice(end) + section, action: "refreshed" };
+}
+
+/**
+ * True if `h` is the niro PostCompact hook entry (new nested or old flat shape).
+ * Shared by the installer's idempotency check and the uninstaller's removal filter so
+ * both agree on exactly which entries are niro's.
+ */
+function isNiroPostCompactHook(h) {
+  if (typeof h === "object" && h && Array.isArray(h.hooks)) {
+    return h.hooks.some((inner) => inner && typeof inner.command === "string" && inner.command.includes("Niro MCP"));
+  }
+  return typeof h === "object" && h && typeof h.command === "string" && h.command.includes("Niro MCP");
+}
+
+/**
+ * True if `h` is a niro UserPromptSubmit hook entry — matches any niro version (old
+ * unconditional or new .niro-project-gated). Shared by installer (upgrade-in-place) and
+ * uninstaller (removal) so both target the same set.
+ */
+function isNiroUserPromptHook(h) {
+  const cmds = [];
+  if (h && Array.isArray(h.hooks)) h.hooks.forEach((i) => i && typeof i.command === "string" && cmds.push(i.command));
+  if (h && typeof h.command === "string") cmds.push(h.command);
+  return cmds.some((c) => c.includes(".niro-project") || c.includes("find_reusable_code") || c.includes("`niro` skill"));
+}
+
+/**
+ * True if `h` is niro's PreToolUse temporary project-reminder entry. Keyed on the unique `should_create_temp_project`
+ * marker so a foreign PreToolUse hook (e.g. a user's dashboard hook) is never matched or removed.
+ * Shared by installer (upgrade-in-place) and uninstaller (removal).
+ */
+function isNiroPreToolUseHook(h) {
+  const cmds = [];
+  if (h && Array.isArray(h.hooks)) h.hooks.forEach((i) => i && typeof i.command === "string" && cmds.push(i.command));
+  if (h && typeof h.command === "string") cmds.push(h.command);
+  // Match the current marker AND the legacy one, so `niro mcp install`/uninstall upgrades or removes a
+  // hook installed before the sandbox→temp-project rename in place (no orphaned old hook).
+  return cmds.some((c) => c.includes("should_create_temp_project") || c.includes("should_sandbox_repo"));
+}
+
+/**
+ * Writes a niro-managed skill/rule file, refreshing it when the generated content has
+ * changed. These files are GENERATED (not hand-edited), so refresh-on-change is correct:
+ *   - file missing            -> mkdir -p + write, returns "added"
+ *   - file present, identical  -> no write, returns "unchanged"
+ *   - file present, differs    -> overwrite, returns "updated"
+ * `label` is a short human name used in the log line (e.g. "niro skill").
+ * Returns one of: "added" | "unchanged" | "updated".
+ */
+function writeManagedSkill(absPath, content, label) {
+  if (!fs.existsSync(absPath)) {
+    fs.mkdirSync(path.dirname(absPath), { recursive: true });
+    fs.writeFileSync(absPath, content);
+    console.log(`  ${label} added: ${absPath}`);
+    return "added";
+  }
+  const existing = fs.readFileSync(absPath, "utf-8");
+  if (existing === content) {
+    console.log(`  ${label} already up to date — skipping (${absPath}).`);
+    return "unchanged";
+  }
+  fs.writeFileSync(absPath, content);
+  console.log(`  ${label} updated: ${absPath}`);
+  return "updated";
+}
+
+const CLIENTS = {
+  "claude-code": {
+    name: "Claude Code",
+    description: "CLI / IDE extension",
+  },
+  codex: {
+    name: "Codex",
+    description: "OpenAI Codex CLI (writes ~/.codex/config.toml)",
+  },
+  "claude-desktop": {
+    name: "Claude Desktop",
+    description: "Desktop app",
+    configPath: () => {
+      const platform = process.platform;
+      if (platform === "darwin") return path.join(process.env.HOME, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+      if (platform === "win32") return path.join(process.env.APPDATA, "Claude", "claude_desktop_config.json");
+      return path.join(process.env.HOME, ".config", "claude", "claude_desktop_config.json");
+    },
+  },
+  cursor: {
+    name: "Cursor",
+    description: "AI code editor (Composer / built-in MCP use ~/.cursor/mcp.json)",
+    /** Canonical Cursor MCP registry — NOT the Cline extension path. See https://cursor.com/docs */
+    configPath: () => path.join(userHome(), ".cursor", "mcp.json"),
+  },
+  windsurf: {
+    name: "Windsurf",
+    description: "AI code editor",
+    configPath: () => {
+      const platform = process.platform;
+      if (platform === "darwin") return path.join(process.env.HOME, ".codeium", "windsurf", "mcp_config.json");
+      if (platform === "win32") return path.join(process.env.APPDATA, ".codeium", "windsurf", "mcp_config.json");
+      return path.join(process.env.HOME, ".codeium", "windsurf", "mcp_config.json");
+    },
+  },
+  vscode: {
+    name: "VS Code",
+    description: "GitHub Copilot's native MCP support (writes the user-profile mcp.json)",
+    configPath: () => {
+      const platform = process.platform;
+      if (platform === "darwin") return path.join(process.env.HOME, "Library", "Application Support", "Code", "User", "mcp.json");
+      if (platform === "win32") return path.join(process.env.APPDATA, "Code", "User", "mcp.json");
+      return path.join(process.env.HOME, ".config", "Code", "User", "mcp.json");
+    },
+    topLevelKey: "servers",
+    buildEntry: (apiKey, mcpServerUrl) => ({
+      type: "stdio",
+      command: "niro",
+      args: ["mcp", "serve"],
+      env: apiKey ? { NIRO_API_KEY: apiKey, NIRO_MCP_SERVER_URL: mcpServerUrl } : { NIRO_MCP_SERVER_URL: mcpServerUrl },
+    }),
+  },
+  "gemini-cli": {
+    name: "Gemini CLI",
+    description: "Google's Gemini CLI (writes ~/.gemini/settings.json)",
+  },
+  "copilot-cli": {
+    name: "GitHub Copilot CLI",
+    description: "The `copilot` terminal CLI (writes ~/.copilot/mcp-config.json)",
+  },
+  factory: {
+    name: "Factory (droid)",
+    description: "Factory's droid CLI (writes ~/.factory/mcp.json)",
+  },
+  goose: {
+    name: "Goose",
+    description: "Block's Goose CLI/desktop (writes ~/.config/goose/config.yaml)",
+  },
+  opencode: {
+    name: "OpenCode",
+    description: "writes ~/.config/opencode/opencode.json",
+    configPath: () => path.join(userHome(), ".config", "opencode", "opencode.json"),
+    topLevelKey: "mcp",
+    buildEntry: (apiKey, mcpServerUrl) => ({
+      type: "local",
+      command: ["niro", "mcp", "serve"],
+      enabled: true,
+      environment: apiKey
+        ? { NIRO_API_KEY: apiKey, NIRO_MCP_SERVER_URL: mcpServerUrl }
+        : { NIRO_MCP_SERVER_URL: mcpServerUrl },
+    }),
+  },
+  cline: {
+    name: "Cline",
+    description: "VS Code extension (writes cline_mcp_settings.json)",
+    /**
+     * globalStorage path for publisher id `saoudrizwan.claude-dev`, under VS Code's own
+     * profile dir. Community-confirmed (cline/cline#10894), not an official Cline doc page —
+     * same caveat as the existing Cursor/Windsurf paths above.
+     */
+    configPath: () => {
+      const platform = process.platform;
+      const globalStorage = ["Code", "User", "globalStorage", "saoudrizwan.claude-dev", "settings", "cline_mcp_settings.json"];
+      if (platform === "darwin") return path.join(process.env.HOME, "Library", "Application Support", ...globalStorage);
+      if (platform === "win32") return path.join(process.env.APPDATA, ...globalStorage);
+      return path.join(process.env.HOME, ".config", ...globalStorage);
+    },
+    buildEntry: (apiKey, mcpServerUrl) => ({
+      command: "niro",
+      args: ["mcp", "serve"],
+      env: apiKey ? { NIRO_API_KEY: apiKey, NIRO_MCP_SERVER_URL: mcpServerUrl } : { NIRO_MCP_SERVER_URL: mcpServerUrl },
+      disabled: false,
+      autoApprove: [],
+    }),
+  },
+  kiro: {
+    name: "Kiro",
+    description: "AWS's IDE (writes ~/.kiro/settings/mcp.json)",
+    configPath: () => path.join(userHome(), ".kiro", "settings", "mcp.json"),
+    buildEntry: (apiKey, mcpServerUrl) => ({
+      command: "niro",
+      args: ["mcp", "serve"],
+      env: apiKey ? { NIRO_API_KEY: apiKey, NIRO_MCP_SERVER_URL: mcpServerUrl } : { NIRO_MCP_SERVER_URL: mcpServerUrl },
+      disabled: false,
+      // Kiro's autoApprove supports a "*" wildcard for "all tools on this server" — safe here
+      // because every niro tool is read-only.
+      autoApprove: ["*"],
+    }),
+  },
+  antigravity: {
+    name: "Antigravity",
+    description: "Google's IDE (writes ~/.gemini/config/mcp_config.json)",
+    configPath: () => {
+      const home = userHome();
+      const legacy = path.join(home, ".gemini", "antigravity", "mcp_config.json");
+      const unified = path.join(home, ".gemini", "config", "mcp_config.json");
+      // Antigravity 2.0 / IDE / CLI share the unified path; older IDE-only installs used the
+      // legacy one. If only the legacy file exists, keep writing there; otherwise use unified.
+      if (fs.existsSync(legacy) && !fs.existsSync(unified)) return legacy;
+      return unified;
+    },
+    buildEntry: (apiKey, mcpServerUrl) => ({
+      command: "niro",
+      args: ["mcp", "serve"],
+      env: apiKey ? { NIRO_API_KEY: apiKey, NIRO_MCP_SERVER_URL: mcpServerUrl } : { NIRO_MCP_SERVER_URL: mcpServerUrl },
+    }),
+  },
+};
+
+/**
+ * ~/.cursor/permissions.json — MCP tools must be allowlisted for Agent auto-run.
+ * Docs: https://cursor.com/docs/reference/permissions
+ */
+function userCursorDir() {
+  return path.join(userHome(), ".cursor");
+}
+
+/** Patterns that already whitelist all Niro tools (case-insensitive per Cursor). */
+function allowlistAlreadyCoversAllNiroTools(allowlist) {
+  if (!Array.isArray(allowlist)) return false;
+  return allowlist.some((e) => {
+    if (typeof e !== "string") return false;
+    const s = e.trim().toLowerCase();
+    return s === "*:*" || s === "niro:*";
+  });
+}
+
+/**
+ * Ensures Cursor can invoke Niro MCP tools without per-tool confirmation.
+ *
+ * Behaviour (avoids overwriting a user's richer allowlist unknowingly):
+ * - New permissions.json → write { "mcpAllowlist": ["niro:*"] }.
+ * - Existing file with valid mcpAllowlist array → append "niro:*" if missing.
+ * - Existing file without mcpAllowlist key → print instructions only (setting that key alone
+ *   would replace the whole in-app MCP allowlist; merging with Cursor UI is ambiguous).
+ *
+ * Requires Cursor Agent "Auto-run" mode (not "Ask every time") — see Cursor docs.
+ */
+function ensureCursorPermissionsForNiro() {
+  const permPath = path.join(userCursorDir(), "permissions.json");
+  const existedBefore = fs.existsSync(permPath);
+  let data = {};
+
+  try {
+    if (existedBefore) {
+      data = JSON.parse(fs.readFileSync(permPath, "utf8"));
+      if (!data || typeof data !== "object") data = {};
+    }
+  } catch (e) {
+    console.warn(`  Could not read ${permPath}: ${e.message}`);
+    console.warn('  Fix the file manually or merge: { "mcpAllowlist": ["niro:*"] }\n');
+    return;
+  }
+
+  const hasKey = Object.prototype.hasOwnProperty.call(data, "mcpAllowlist");
+
+  if (!existedBefore) {
+    data = { ...data, mcpAllowlist: ["niro:*"] };
+  } else if (hasKey && Array.isArray(data.mcpAllowlist)) {
+    if (allowlistAlreadyCoversAllNiroTools(data.mcpAllowlist)) {
+      console.log("  Cursor MCP allowlist already includes Niro (`niro:*` or broader).\n");
+      return;
+    }
+    data.mcpAllowlist = [...data.mcpAllowlist, "niro:*"];
+  } else if (hasKey && !Array.isArray(data.mcpAllowlist)) {
+    console.warn("  ~/.cursor/permissions.json has invalid mcpAllowlist — not modifying it.");
+    console.warn('  Add this string after fixing JSON: \"niro:*\"\n');
+    return;
+  } else if (Object.keys(data).length > 0) {
+    console.log("");
+    console.log("  ~/.cursor/permissions.json exists but has no \"mcpAllowlist\" entry.");
+    console.log(
+      '  Cursor replaces the Settings MCP allowlist when you add \"mcpAllowlist\" — skipped auto-merge to avoid dropping other MCP tools.',
+    );
+    console.log("  Merge manually (include other MCP servers if you need them), e.g.:");
+    console.log('      \"mcpAllowlist\": [\"niro:*\", \"github:*\"]\n');
+    return;
+  } else {
+    data.mcpAllowlist = ["niro:*"];
+  }
+
+  if (!data.mcpAllowlist || !allowlistAlreadyCoversAllNiroTools(data.mcpAllowlist)) {
+    console.warn("  [niro-setup] Unexpected state writing permissions.json; skipping.\n");
+    return;
+  }
+
+  try {
+    fs.mkdirSync(path.dirname(permPath), { recursive: true });
+    fs.writeFileSync(permPath, JSON.stringify(data, null, 2) + "\n");
+    console.log(`  Cursor MCP permissions updated: ${permPath}`);
+    console.log('    • Added pattern \"niro:*\" so Agent can run all Niro tools without approval prompts.');
+    console.log("    • Enable Cursor Agent Auto-run / sandbox auto-run — \"Ask every time\" ignores allowlists.");
+    console.log("    • Reference: https://cursor.com/docs/reference/permissions\n");
+  } catch (e) {
+    console.warn(`  Could not write ${permPath}: ${e.message}\n`);
+  }
+}
+
+function ask(rl, question, defaultValue) {
+  const prompt = formatPrompt(question, defaultValue);
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (answer) => {
+      if (done) return;
+      done = true;
+      rl.removeListener("close", onClose);
+      resolve((answer || "").trim() || defaultValue || "");
+    };
+    // If stdin reaches EOF (e.g. a piped/headless install) before this question is
+    // answered, readline 'close' fires and the question callback never would — resolve
+    // with the default so multi-prompt setup still completes non-interactively.
+    const onClose = () => finish("");
+    rl.once("close", onClose);
+    rl.question(prompt, (answer) => finish(answer));
+  });
+}
+
+const SAAS_URL = "https://aiassistant.niroai.dev";
+
+/**
+ * Read a key=value pair out of ${INSTALL_DIR:-$HOME/niro}/.env
+ * (matches niro-distribution/install.sh convention).
+ * Returns { value, source } or null if not present.
+ */
+function readInstallEnvValue(key) {
+  const installDir = process.env.INSTALL_DIR || path.join(process.env.HOME || "", "niro");
+  const envFile = path.join(installDir, ".env");
+  try {
+    if (!fs.existsSync(envFile) || !fs.statSync(envFile).isFile()) return null;
+    const contents = fs.readFileSync(envFile, "utf8");
+    const re = new RegExp(`^\\s*${key}\\s*=\\s*(.+?)\\s*$`);
+    for (const line of contents.split(/\r?\n/)) {
+      if (line.trim().startsWith("#")) continue;
+      const match = line.match(re);
+      if (match) {
+        // Strip surrounding single or double quotes if present
+        const raw = match[1].replace(/^["']|["']$/g, "");
+        return { value: raw, source: envFile };
+      }
+    }
+  } catch (_e) {
+    // Fall through
+  }
+  return null;
+}
+
+/**
+ * Resolve a default API key to pre-fill the setup prompt.
+ * Order:
+ *   1. NIRO_API_KEY env var
+ *   2. ${INSTALL_DIR:-$HOME/niro}/.env
+ *   3. null (user must type it)
+ */
+function resolveApiKey() {
+  const fromEnv = (process.env.NIRO_API_KEY || "").trim();
+  if (fromEnv) return fromEnv;
+  const found = readInstallEnvValue("NIRO_API_KEY");
+  return found ? found.value : null;
+}
+
+/**
+ * Detect a durable per-device CLI token written by `niro login` (~/.niro/credentials.json).
+ * When present, the MCP server authenticates with it (read at runtime from credentials.json) and
+ * NO API key needs to be configured — so setup skips the key prompt and omits NIRO_API_KEY from the
+ * written config. Returns true if a cli-token is available. The token value itself is never read out
+ * here or logged — only its presence matters for the install decision.
+ */
+function hasCliToken() {
+  try {
+    const credsPath = path.join(userHome(), ".niro", "credentials.json");
+    if (!fs.existsSync(credsPath)) return false;
+    const creds = JSON.parse(fs.readFileSync(credsPath, "utf8"));
+    return !!(creds && creds.cliToken && String(creds.cliToken).trim());
+  } catch {
+    return false;
+  }
+}
+
+
+/**
+ * Resolve the MCP server URL (ai-assistant) the editor will connect to —
+ * WITHOUT prompting. Almost every user wants the default, so asking was one
+ * wasted step per install; dedicated-backend users pass --url (or set the env
+ * var) instead. The resolved URL and where it came from are printed by the
+ * caller, so a wrong pick is visible and correctable rather than silent.
+ *
+ * Precedence: --url flag > NIRO_MCP_SERVER_URL env > ~/.niro/config.json
+ * (saved by a previous install) > SaaS default.
+ *
+ * `explicit` marks a URL the user chose THIS run (--url / env): only those are
+ * persisted to config.json. Never save the resolved default — that would pin
+ * today's SaaS URL forever and a future backend migration (new default in a
+ * new release) would silently not reach existing installs.
+ *
+ * We deliberately do NOT handle the ai-orchestrator (API) URL here: `niro login` runs first and
+ * already establishes it (saved as apiUrl in credentials.json), and the CLI reads it from there.
+ * The MCP bridge only ever talks to ai-assistant, so this is the one URL setup actually needs.
+ *
+ * `env` / `saved` are injection seams for tests; production passes only `cliUrl`.
+ */
+function resolveMcpServerUrl(cliUrl, env = process.env, saved = null) {
+  if (cliUrl) return { url: cliUrl, source: "--url", explicit: true };
+  if (env.NIRO_MCP_SERVER_URL) {
+    return { url: env.NIRO_MCP_SERVER_URL, source: "NIRO_MCP_SERVER_URL env var", explicit: true };
+  }
+  const cfg = saved || config.load();
+  if (cfg && cfg.mcpServerUrl) {
+    return { url: cfg.mcpServerUrl, source: `saved in ${config.FILE}`, explicit: false };
+  }
+  return { url: SAAS_URL, source: "Niro cloud default", explicit: false };
+}
+
+/**
+ * Guards the CLI-registration path (setupClaudeCode, setupCodex, and the vscode/gemini-cli/
+ * copilot-cli/factory setups below) — all of them shell out via `execSync(cmd.join(" "))`,
+ * which keeps cross-platform resolution of npm-installed `.cmd`/`.bat` shims on Windows (an
+ * `execFileSync`/no-shell rewrite would need Windows-specific handling this project doesn't
+ * have tests for). Because the resulting command string is built by joining args with a
+ * plain space and NOT quoted, an apiKey or mcpServerUrl containing shell metacharacters would
+ * be interpreted by the shell. This is a defense-in-depth boundary check — reject such values
+ * before they reach any shell-composed command, rather than attempting to escape them.
+ */
+function hasShellMetacharacters(value) {
+  return /[\s;&|`$()<>"'\\]/.test(value || "");
+}
+
+function printHeader() {
+  console.log("");
+  console.log("  Niro MCP Server Setup");
+  console.log("  ---------------------");
+  console.log("");
+}
+
+function printClients() {
+  console.log("  Supported clients:");
+  Object.entries(CLIENTS).forEach(([id, client]) => {
+    console.log(`    ${id.padEnd(18)} ${client.name} (${client.description})`);
+  });
+  console.log("");
+}
+
+async function setupClaudeCode(apiKey, mcpServerUrl) {
+  console.log("\n  Configuring Claude Code...\n");
+
+  const cmd = [
+    "claude", "mcp", "add",
+    "--scope", "user",
+    "niro",
+  ];
+  // Only embed NIRO_API_KEY when there is no cli-token (legacy/key flow). With a `niro login`
+  // session the server reads the cli-token from ~/.niro/credentials.json at runtime.
+  if (apiKey) cmd.push("-e", `NIRO_API_KEY=${apiKey}`);
+  // The bridge (src/mcp/server.js) reads NIRO_MCP_SERVER_URL (ai-assistant), not NIRO_API_URL.
+  cmd.push("-e", `NIRO_MCP_SERVER_URL=${mcpServerUrl}`);
+  cmd.push("--", "niro", "mcp", "serve");
+
+  try {
+    execSync(cmd.join(" "), { stdio: "inherit" });
+    console.log("  MCP server registered globally in Claude Code.\n");
+  } catch (err) {
+    console.error("  Failed to register MCP server. Is Claude Code installed?");
+    console.error("  Install: https://claude.ai/code\n");
+    console.error(`  Manual command:\n    ${cmd.join(" ")}\n`);
+    return false;
+  }
+
+  addClaudeCodePostCompactHook();
+  addClaudeCodeUserPromptHook();
+  addClaudeCodePreToolUseHook();
+  addClaudeCodeMemory();
+  addClaudeCodeSkill();
+  addClaudeCodeCliSkill();
+
+  return true;
+}
+
+/**
+ * Adds a PostCompact hook to ~/.claude/settings.json so Claude is reminded
+ * about Niro tools after context compaction (the point where tool awareness
+ * most commonly degrades in long sessions).
+ */
+function addClaudeCodePostCompactHook() {
+  const settingsPath = path.join(process.env.HOME || "", ".claude", "settings.json");
+  const hookCommand = "echo 'Niro MCP tools are available for code intelligence (call chains, blast radius, impact analysis, source lookup). Use niro tools before native grep/read for code questions.'";
+
+  let settings = {};
+  try {
+    if (fs.existsSync(settingsPath)) {
+      settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+    }
+  } catch {
+    // Corrupt or missing — start fresh
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.PostCompact) settings.hooks.PostCompact = [];
+
+  const alreadyPresent = settings.hooks.PostCompact.some(isNiroPostCompactHook);
+
+  if (alreadyPresent) {
+    console.log("  PostCompact hook already configured — skipping.\n");
+    return;
+  }
+
+  settings.hooks.PostCompact.push({
+    matcher: "",
+    hooks: [{ type: "command", command: hookCommand }],
+  });
+
+  const exampleEntry = { matcher: "", hooks: [{ type: "command", command: hookCommand }] };
+  try {
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    console.log("  PostCompact hook added to ~/.claude/settings.json\n");
+    console.log("  → Claude will be reminded about Niro tools after context compaction.\n");
+  } catch (err) {
+    console.warn(`  Could not write ~/.claude/settings.json: ${err.message}`);
+    console.warn("  Add manually to the PostCompact array in ~/.claude/settings.json:\n");
+    console.warn(JSON.stringify(exampleEntry, null, 2) + "\n");
+  }
+}
+
+/**
+ * Appends a Niro reminder section to ~/.claude/CLAUDE.md so Claude is aware
+ * of Niro tools across all projects and sessions.
+ */
+function addClaudeCodeMemory() {
+  const claudeMdPath = path.join(process.env.HOME || "", ".claude", "CLAUDE.md");
+  const section = NIRO_CLAUDE_MD_SECTION;
+
+  let existing = "";
+  try {
+    if (fs.existsSync(claudeMdPath)) {
+      existing = fs.readFileSync(claudeMdPath, "utf-8");
+    }
+  } catch {
+    // File unreadable — will create fresh
+  }
+
+  const { content, action } = upsertNiroMarkerSection(existing, section);
+  if (action === "unchanged") {
+    console.log("  CLAUDE.md entry already up to date — skipping.\n");
+    return;
+  }
+
+  try {
+    fs.mkdirSync(path.dirname(claudeMdPath), { recursive: true });
+    fs.writeFileSync(claudeMdPath, content);
+    console.log(`  Niro reminder ${action === "refreshed" ? "refreshed in" : "added to"} ~/.claude/CLAUDE.md\n`);
+    console.log("  → Claude will see Niro tool guidance in every session.\n");
+  } catch (err) {
+    console.warn(`  Could not write ~/.claude/CLAUDE.md: ${err.message}`);
+    console.warn("  Add manually to ~/.claude/CLAUDE.md:\n");
+    console.warn(section + "\n");
+  }
+}
+
+/**
+ * Adds a UserPromptSubmit hook to ~/.claude/settings.json so Claude is reminded
+ * about Niro tools + the `niro` skill before every prompt. This is the lightweight,
+ * always-on pointer that fixes "Claude forgets Niro mid-session"; the long-form
+ * guidance lives in the skill, so this is deliberately terse.
+ */
+function addClaudeCodeUserPromptHook() {
+  const settingsPath = path.join(process.env.HOME || "", ".claude", "settings.json");
+  // Folder-gated: walks up from the project dir and only emits the reminder when a
+  // `.niro-project` marker exists (i.e. this tree is actually indexed). The wording is
+  // conditional ("IF the niro tools are present") because a shell hook cannot see which
+  // MCP tools Claude has loaded — so it stays correct when Niro is disabled or an A/B
+  // session exposes only a subset of niro tools.
+  // Reads the prompt on stdin so it can add a SANDBOX reminder when the message asks to create/switch a
+  // branch — the exact moment a repo's local state diverges from what Niro indexed (ADR-017). The branch
+  // match is a coarse keyword heuristic (a shell hook can't call an LLM); a false positive only shows an
+  // extra harmless reminder, never gates behaviour. Base reminder is unchanged and still `.niro-project`-gated.
+  const hookCommand =
+    "IN=\"$(cat)\"; d=\"${CLAUDE_PROJECT_DIR:-$PWD}\"; while [ -n \"$d\" ] && [ \"$d\" != \"/\" ]; do " +
+    "if [ -f \"$d/.niro-project\" ]; then echo 'This repo is indexed by Niro. IF the niro MCP tools are present in your current toolset, prefer them over grep/read for codebase questions (structure, call chains, blast radius, impact, data flows, reuse) and call find_reusable_code before writing new code. If the niro tools are absent (disabled or A/B-limited) or a query is out of scope, use native tools and do not mention Niro.'; " +
+    "printf '%s' \"$IN\" | grep -qiE 'new branch|create[^.]{0,24}branch|switch[^.]{0,24}branch|checkout -b|change[^.]{0,24}branch|different branch|another branch' && " +
+    "echo 'You appear to be about to create or switch a branch. The temporary project check is per (repo, branch), so do it AFTER you are on the new branch (not before) and pass that CURRENT branch: call should_create_temp_project(git_url, branch, project_id from its .niro-project) and run niro new-temp-project if needs_temp_project is true. A check you ran on the old branch does not count.'; break; fi; " +
+    "d=\"$(dirname \"$d\")\"; done";
+
+  let settings = {};
+  try {
+    if (fs.existsSync(settingsPath)) {
+      settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+    }
+  } catch {
+    // Corrupt or missing — start fresh
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.UserPromptSubmit) settings.hooks.UserPromptSubmit = [];
+
+  // Loose signature for ANY niro UserPromptSubmit entry (old unconditional or new gated),
+  // so re-running upgrades a stale hook in place instead of leaving a duplicate.
+  const alreadyCurrent = settings.hooks.UserPromptSubmit.some(
+    (h) => Array.isArray(h.hooks) && h.hooks.some((i) => i && i.command === hookCommand),
+  );
+  if (alreadyCurrent) {
+    console.log("  UserPromptSubmit hook already up to date — skipping.\n");
+    return;
+  }
+
+  const hadStale = settings.hooks.UserPromptSubmit.some(isNiroUserPromptHook);
+  settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter((h) => !isNiroUserPromptHook(h));
+  // UserPromptSubmit hooks have no tool matcher — just the hooks array.
+  settings.hooks.UserPromptSubmit.push({
+    hooks: [{ type: "command", command: hookCommand }],
+  });
+
+  try {
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    console.log(`  UserPromptSubmit hook ${hadStale ? "upgraded" : "added"} in ~/.claude/settings.json`);
+    console.log("  → Claude is reminded about Niro before each prompt, but only in repos");
+    console.log("    that have a .niro-project marker (no nagging in un-indexed folders).\n");
+  } catch (err) {
+    console.warn(`  Could not write ~/.claude/settings.json: ${err.message}`);
+    console.warn('  Add manually to the UserPromptSubmit array in ~/.claude/settings.json:\n');
+    console.warn(JSON.stringify({ hooks: [{ type: "command", command: hookCommand }] }, null, 2) + "\n");
+  }
+}
+
+/**
+ * The niro PreToolUse hook command (matcher Edit|Write). At edit time it enforces the temporary project check that
+ * prose instructions can be read past: it resolves the git repo of the file being edited, and — once per
+ * (session, repo) — injects a reminder to call should_create_temp_project for THAT repo before
+ * editing it (ADR-017). Advisory ONLY: it emits `additionalContext` with NO permissionDecision, so it
+ * never approves/denies the edit — the user's normal edit-permission flow is untouched. (Emitting
+ * permissionDecision:"allow" would AUTO-APPROVE every edit and bypass that prompt — a bug, not the goal.)
+ *
+ * Dependency-free (no jq): reads the PreToolUse JSON on stdin, pulls file_path + session_id with grep/sed,
+ * walks up for a `.niro-project` marker (so it stays silent in un-indexed repos), and dedupes via a marker
+ * file keyed by session_id + repo root. Portable grep -oE / sed -E / tr (GNU + BSD).
+ */
+const NIRO_PRETOOL_COMMAND = [
+  'IN="$(cat)"',
+  // file_path from tool_input; bail quietly if absent (e.g. a Write with unusual shape)
+  `f="$(printf '%s' "$IN" | grep -oE '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)"/\\1/')"`,
+  '[ -z "$f" ] && exit 0',
+  'r="$(git -C "$(dirname "$f")" rev-parse --show-toplevel 2>/dev/null)"',
+  '[ -z "$r" ] && exit 0',
+  // only remind inside a niro-indexed tree
+  'd="$r"; ok=0; while [ -n "$d" ] && [ "$d" != "/" ]; do if [ -f "$d/.niro-project" ]; then ok=1; break; fi; d="$(dirname "$d")"; done',
+  '[ "$ok" = 0 ] && exit 0',
+  `s="$(printf '%s' "$IN" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)"/\\1/')"`,
+  // Branch-aware dedup: the temporary project answer is per (repo, BRANCH) — a "no" on main must NOT silence the
+  // reminder after the dev switches to a feature branch. Keying the once-per marker on the current branch
+  // re-fires the check on every branch change (the stale-cached-answer bug from live use).
+  'b="$(git -C "$r" rev-parse --abbrev-ref HEAD 2>/dev/null)"',
+  // Newline-delimit the three fields before hashing so distinct (session,repo,branch) triples cannot
+  // collide (e.g. session "x_a"+repo "/b" vs session "x"+repo "/a/b"). cksum sees the raw delimiter;
+  // if cksum is somehow absent, $k is empty -> one shared marker -> harmless over-dedup (advisory only).
+  `k="$(printf '%s\\n%s\\n%s' "$s" "$r" "$b" | cksum | cut -d' ' -f1)"`,
+  'm="${TMPDIR:-/tmp}/niro-tmpproj-$k"',
+  '[ -f "$m" ] && exit 0',
+  'touch "$m"',
+  // Advisory context injection ONLY — NO permissionDecision, so the user's normal edit-approval flow is
+  // untouched (permissionDecision:"allow" would auto-approve the edit). Message is quote/backtick-free.
+  `printf '%s' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"Niro temporary project check: you are editing a Niro-indexed repo on its CURRENT branch. The temporary project answer is per branch, so a check you ran on a different branch (e.g. before switching) does NOT count here. Call should_create_temp_project(git_url, branch=current branch, project_id from its .niro-project) for THIS repo now and run niro new-temp-project if it returns needs_temp_project. Shown once per repo per branch per session."}}'`,
+].join('; ');
+
+/**
+ * Adds the PreToolUse (Edit|Write) temporary project-reminder hook to ~/.claude/settings.json. Idempotent:
+ * upgrades a stale niro entry in place, never touches a foreign PreToolUse hook (matched by the
+ * should_create_temp_project marker via isNiroPreToolUseHook).
+ */
+function addClaudeCodePreToolUseHook() {
+  const settingsPath = path.join(process.env.HOME || "", ".claude", "settings.json");
+  let settings = {};
+  try {
+    if (fs.existsSync(settingsPath)) settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+  } catch {
+    // Corrupt or missing — start fresh
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
+
+  const entry = { matcher: "Edit|Write", hooks: [{ type: "command", command: NIRO_PRETOOL_COMMAND }] };
+  const alreadyCurrent = settings.hooks.PreToolUse.some(
+    (h) => Array.isArray(h.hooks) && h.hooks.some((i) => i && i.command === NIRO_PRETOOL_COMMAND),
+  );
+  if (alreadyCurrent) {
+    console.log("  PreToolUse temporary project hook already up to date — skipping.\n");
+    return;
+  }
+
+  const hadStale = settings.hooks.PreToolUse.some(isNiroPreToolUseHook);
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter((h) => !isNiroPreToolUseHook(h));
+  settings.hooks.PreToolUse.push(entry);
+
+  try {
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    console.log(`  PreToolUse temporary project hook ${hadStale ? "upgraded" : "added"} in ~/.claude/settings.json`);
+    console.log("  → Before editing a Niro-indexed repo, Claude is reminded once/session to run the");
+    console.log("    should_create_temp_project check (non-blocking; silent in un-indexed repos).\n");
+  } catch (err) {
+    console.warn(`  Could not write ~/.claude/settings.json: ${err.message}`);
+    console.warn("  Add manually to the PreToolUse array in ~/.claude/settings.json:\n");
+    console.warn(JSON.stringify(entry, null, 2) + "\n");
+  }
+}
+
+/** Body of the `niro` skill (long-form tool-routing playbook). */
+const NIRO_SKILL = `---
+name: niro-skill
+description: Use Niro code-intelligence MCP tools to answer questions about THIS codebase — structure, behavior, call chains, blast radius / impact, data & event flows, and reuse — instead of grep/read. Invoke whenever a task involves understanding, tracing, debugging, or assessing the impact of code, or BEFORE writing new code (check for reusable code first).
+---
+
+# Niro code intelligence
+
+Niro indexes this codebase into a graph (AST + call/HTTP/event/data edges + LLM enrichment)
+and exposes MCP tools under the \`niro\` server. For any question answerable from the indexed
+code — structure, behavior, impact, data/event flows, semantics — prefer these tools over
+native grep/read. For anything outside the indexed code (config files, docs, runtime state),
+use your native tools.
+
+\`project_id\` auto-resolves from a \`.niro-project\` file at the repo root — omit it. If there
+is no such file, call \`list_projects\` and pass the chosen \`project_id\`.
+
+## Availability self-check — read FIRST
+
+Niro is not always applicable. Check these before relying on it, and fall back to native
+tools **silently** (do not announce Niro's absence) whenever a check fails:
+
+1. **Are the tools present?** Only call \`mcp__niro__*\` tools that actually appear in your
+   current toolset. During A/B sessions, or when the Niro MCP server is disabled, some or
+   all niro tools may be missing — use the next-best present tool or native grep/read.
+2. **Is this repo indexed?** If there's no \`.niro-project\` and \`list_projects\` returns
+   nothing matching this repo — or \`get_index_status\` is not COMPLETED, or a tool reports
+   "not indexed / not found" — this codebase isn't covered. Use native tools; don't loop.
+3. **Is the question in scope?** Structure / behavior / impact / data & event flows / reuse
+   → Niro. Config, docs, runtime state, anything non-code → native tools.
+
+## Cross-project queries — when the question is about a DIFFERENT repo than the cwd
+
+\`project_id\` defaults to the CURRENT folder's project (its \`.niro-project\` pin or git remote).
+That default is WRONG when the user asks about a repo/folder you are NOT running in — every tool call
+would silently search the current project's graph and return empty/irrelevant results ("Niro gets
+lost"). When the target of the question is a repo other than the current one:
+
+1. **Identify the target** from the user's words — a repo name (e.g. \`ai-orchestrator\`), a git URL,
+   or a path that isn't the current repo.
+2. **Find its project.** Call \`list_projects\` and match the target against each project's
+   \`repositories[]\` (compare on \`name\` and \`git_remote\`; ignore a \`.git\` suffix and treat
+   \`git@host:org/repo\` the same as \`https://host/org/repo\`).
+3. **Resolve, never guess:**
+   - exactly one project matches → use its \`project_id\` (its \`alias\` works too);
+   - more than one matches → ASK the user which, listing each candidate by \`alias\` (or \`project_id\`)
+     and the repos it contains;
+   - none match → tell the user that repo isn't indexed under their account, and use native tools.
+4. **Target it.** Pass the resolved \`project_id\` (or alias) as the \`project_id\` argument on EVERY
+   niro tool call for that question — it overrides the cwd default and queries that repo's graph. When a
+   later question is about the current repo again, drop \`project_id\` so it resolves from the cwd.
+5. **Prefer structure over content-grep, and don't give up if grep is empty.** For "list / find the
+   classes/methods/handlers" questions, reach for a STRUCTURE tool (\`get_class_structure\`,
+   \`get_index_status\`, the routing tools below) — they read the graph and include annotations.
+   \`code_grep\` searches indexed source text, which a project can lack even when its graph is built. So
+   if \`code_grep\` returns nothing for a project \`list_projects\` shows as indexed, do NOT conclude the
+   code is absent and fall back to filesystem — retry the question with a structure/graph tool (same
+   \`project_id\`) first.
+
+## Local temporary project — make Niro reflect YOUR branch + uncommitted edits
+
+Niro indexes a repo at ONE branch (the team's tracked branch). Identity is (git url, branch): a graph
+built on \`main\` does NOT reflect your feature branch or uncommitted edits. A **temporary project** is a private,
+temporary index of your branch (\`niro new-temp-project\` to create, \`niro discard-temp-project\` to remove — teammates unaffected).
+
+- **Obey \`🔔 Niro ACTION\` notices.** When a tool result appends "the coding assistant should run
+  \`niro new-temp-project\` / \`niro discard-temp-project\`", run that command with the Bash tool (cwd = that
+  repo's folder) — it's how Niro's answers catch up to your local work. These are directives, not FYIs.
+- **Handle 🛑 refusals.** When your branch has diverged and no temporary project covers it, Niro REFUSES
+  to answer (a stale answer would describe the indexed branch, not your code) and returns three options.
+  Prefer \`niro new-temp-project\` (then retry). Only pass \`allow_stale=true\` after the USER explicitly
+  agrees to a stale answer — never on your own. Or fall back to native tools for that question.
+- **Multi-repo work — the tool you must call.** The MCP only sees the folder this session started in, so
+  it CANNOT tell you a DIFFERENT repo you're editing needs a temporary project. YOU know which repo you're about to
+  change. **The answer is per (repo, BRANCH) — this is the #1 thing agents get wrong.** A \`needs_temp_project=false\`
+  you got while on \`main\` is meaningless once you switch to a feature branch; it does NOT carry over. So:
+  - **Check on the branch you'll actually edit, not before you switch.** If the task says "on a new branch",
+    create/switch the branch FIRST, THEN run the check on that branch. Checking while still on the old
+    branch just tells you the old branch is fine — useless.
+  - **Re-check after every branch create/switch.** Do not cache or reuse a prior result across a branch
+    change. "I already checked this repo" is wrong if you've since changed its branch.
+  - This applies even when the session started in a **parent folder that isn't itself a git repo** — then
+    EVERY repo under it is one you must check (a common miss: treating the siblings as "the project").
+
+  For each repo, once you are ON the branch you'll edit:
+  1. \`git -C <that repo's folder> remote get-url origin\`, \`git -C <that repo's folder> branch --show-current\`
+     (the CURRENT branch, after any switch); read its pin \`cat <that repo's folder>/.niro-project\` if present.
+  2. call \`should_create_temp_project(git_url, branch, dirty, project_id)\` — read-only. Pass the current \`branch\`
+     and the \`.niro-project\` \`project_id\` (without the pin it can't decide when the URL maps to several
+     projects and returns "pass project_id to disambiguate").
+  3. if it returns \`needs_temp_project=true\`, run \`niro new-temp-project\` with the Bash tool (cwd = that repo's
+     folder). All the repos your feature touches then share ONE temporary project, so cross-repo answers (a call
+     from repo A into repo B) stay coherent. Skip it when the tool says already covered, on the indexed branch,
+     or not a Niro project.
+
+## Calling conventions (apply to every tool)
+
+- **Partials auto-resolve.** Pass \`ClassName.method\`, a bare class name, or an HTTP path —
+  tools resolve to the best match. Do NOT pre-call \`resolve_fqn\`; use it only to disambiguate
+  a name that genuinely collides across repos.
+- **\`purpose\` tunes the response.** Most tools take a \`purpose\` (LOCATE / ORIENT / COMPREHEND
+  / TRACE / DEBUG / PROPAGATE / ASSESS_RISK / AUDIT / IMPLEMENT / VERIFY / SCOUT). Set it to
+  your intent to get the right fields and avoid token bloat.
+- **Batch over loop.** Tools accept arrays (\`entity_fqns\`, \`method_fqns\`, \`sources\`,
+  \`patterns\`) — fetch many in one call instead of N calls.
+- **Collapse stacked calls.** Pick the single most-specific tool; don't fire every relevant
+  one. \`get_blast_radius\` returns upstream callers + downstream callees + impacted files in
+  one call (it subsumes \`get_reverse_call_chain\` + \`find_handler\`); pass
+  \`include_source_code=true\` instead of a follow-up \`get_source_code\`. \`get_impact_analysis\`
+  subsumes a manual reverse-chain walk. If your plan has 3+ niro calls, re-check for a
+  subsuming tool.
+
+## Routing — curated high-value tools, most specific wins
+
+**Understand**
+<!-- how_does_x_work temporarily disabled (hidden MCP tool) — re-add this row when re-enabled:
+| How a method / endpoint works (forward flow, cross-service, events) | \`how_does_x_work\` | -->
+| Intent | Tool |
+|---|---|
+| What an entity does — AI functionality docs for a method/class/module | \`explain_code\` |
+| Exact source of a symbol or file (batch via \`sources\`) | \`get_source_code\` |
+| Members (methods/fields) of a class/interface/enum | \`get_class_structure\` |
+
+**Navigate & trace**
+| Intent | Tool |
+|---|---|
+| What X calls (callees) — \`scope=transitive\` for deep | \`get_call_chain\` |
+| Who calls X (callers) — \`scope=transitive\` for upstream | \`get_reverse_call_chain\` |
+| Full path from A to B (prefer \`to_service\` for cross-service) | \`trace_execution_path\` |
+| HTTP endpoints a service exposes | \`find_api_endpoints\` |
+| Outbound HTTP calls a service makes | \`find_outbound_http_calls\` |
+| What handles an outgoing HTTP call / event | \`find_handler\` |
+
+**Change safely**
+| Intent | Tool |
+|---|---|
+| BEFORE implementing/adding anything — reusable code? (pass \`steps\`) | \`find_reusable_code\` |
+| What breaks if I change X — callers + callees, cross-service, one call | \`get_blast_radius\` |
+| Upstream callers that break (lighter than blast radius) | \`get_impact_analysis\` |
+
+**Debug**
+<!-- why_could_x_happen temporarily disabled (hidden MCP tool) — re-add this row when re-enabled:
+| Why could this fail / behave this way — candidate causes along the chain | \`why_could_x_happen\` | -->
+| Intent | Tool |
+|---|---|
+| Pre-detected issues / bugs (project → service → entity) | \`find_known_issues\` |
+| What's already initialized / authed when control reaches a method | \`get_state_at_entry\` |
+
+**Data & events**
+| Intent | Tool |
+|---|---|
+| Who reads / writes / deletes a collection, table, or bucket | \`get_data_resource_usage\` |
+| Event producers ↔ handlers wiring | \`get_event_producers_and_handlers\` |
+
+**Search & status**
+| Intent | Tool |
+|---|---|
+| Regex / literal search in source contents (batch \`patterns\`) | \`code_grep\` |
+| Is the project indexed? node/edge counts | \`get_index_status\` |
+
+Also available (catalog / utility, use when the above don't fit): \`list_projects\`,
+\`list_data_resources\`, \`list_events\`, \`find_orphaned_events\`, \`get_config_symbols\`,
+\`resolve_fqn\`, and \`list_niro_bugs\` + \`get_bug_with_resolution\` (Niro-tracked bug RCA).
+
+## Hard rules
+
+- **Before adding or writing ANY new code, call \`find_reusable_code\` first.** Mandatory.
+- For comprehension / debugging, set \`purpose\` to COMPREHEND or DEBUG and, on
+  \`get_blast_radius\` / \`get_impact_analysis\`, pass \`include_source_code=true\`.
+- If a result contains **⚠️ ACTION REQUIRED**, the graph is stale — read the listed files
+  via \`get_source_code\` before trusting structural answers.
+- Niro is authoritative for indexed code; data/event recall may be partial. Don't use Niro
+  for non-code questions.
+
+## Onboarding / re-indexing a repo
+
+Niro indexing is done outside the agent with the \`niro\` CLI (e.g. \`niro init\` in the
+terminal), not via MCP tools. The \`niro-cli\` skill drives those CLI commands from chat and can
+also report which backend the niro MCP connects to.
+`;
+
+/**
+ * Body of the `niro-cli` skill — a param-collector playbook that teaches the agent to DRIVE
+ * the `niro` CLI from chat (status / onboard / edit / rebuild / remove). Unlike `niro-skill`
+ * (which routes MCP code-intelligence tools), this one runs the CLI via shell and parses --json.
+ * The agent gathers inputs in conversation, then runs ONE non-interactive command — no business
+ * logic of its own. Avoids unescaped backticks beyond the template's own use.
+ */
+const NIRO_CLI_SKILL = `---
+name: niro-cli
+description: manage Niro projects from chat: check status, onboard, edit, rebuild, remove, and show which backend the niro MCP connects to
+---
+
+# Niro CLI — manage Niro from chat
+
+You manage a user's Niro projects by running the \`niro\` CLI via the shell (Bash) and parsing
+its \`--json\` output. You are a PARAM-COLLECTOR, not a decision engine: gather the inputs you
+need in conversation, then run ONE non-interactive \`niro\` command, parse the JSON, and report
+back in plain English. Do not invent business logic — the CLI owns it.
+
+## Golden rules (apply to EVERY task)
+
+1. **Auth first, always.** Run \`niro whoami --json\` before anything else. It returns
+   \`{authed, email, user_id, account_id, api_url}\`. If \`authed\` is false, tell the USER to
+   run \`niro login\` THEMSELVES in their terminal — it opens a browser device flow. You cannot
+   run it, handle credentials, or complete the flow for them. STOP until they confirm they are
+   logged in, then re-run \`niro whoami --json\`.
+2. **\`niro info --json\` is your context primitive.** Run it to learn the repo. It returns
+   \`{git_root, repo_url, branch, indexed, ambiguous, projects:[{project_id, alias, status,
+   doc_gen_status, updated_at}]}\`. \`branch\` is null when HEAD is detached. The CLI already
+   walks up to the git ROOT, so run it from anywhere inside the tree. Failure reasons include
+   \`not_a_git_repo\` and \`no_origin\`.
+3. **Never guess which project.** If \`info.ambiguous\` is true OR \`projects\` has more than
+   one entry, ASK the user which project (by alias). Then pass it explicitly
+   (\`--project <alias>\` / \`--target <alias>\`). Never assume.
+4. **Env-var values are secrets.** NEVER print, echo, or repeat env-var VALUES. Collect them
+   from the user privately and pass them via flags. \`niro edit --list-env\` shows non-secret
+   candidate values but MASKS secret-pattern keys (passwords/tokens/keys) — rely on that, do
+   not unmask. When choosing which file drives a var, pick by FILE NAME only; for a secret key
+   you will only ever see \`****\` for the value, never the plaintext — that is correct.
+5. **Confirm destructive actions explicitly.** \`niro remove --project\` deletes a project. You
+   MUST pass \`--confirm-name <the exact alias or project_id>\`; the CLI refuses to delete
+   without a matching name. Always confirm with the user first. \`--unmap-repo\` is
+   non-destructive but still confirm.
+6. **One non-interactive command per action.** Collect inputs in chat, then run a single
+   \`niro\` command with explicit flags (no interactive prompts). Parse \`--json\` and report.
+
+## Command flows (numbered)
+
+### 1. Status / "what's the state?"
+1. \`niro whoami --json\` (rule 1).
+2. \`niro info --json\` to see repo_url, branch, indexed, and the project list FOR THE CURRENT FOLDER.
+   For ALL projects in the account (not folder-scoped — e.g. "list my projects"), run
+   \`niro projects --json\` -> \`{projects:[{project_id, alias, repo_count, created_at}]}\`.
+3. For an indexed project's live build state, run \`niro status [project] --json\`
+   (pass the alias if ambiguous, per rule 3).
+4. Report: authed user, repo + branch, whether indexed, project alias(es) + status +
+   doc_gen_status, in plain English.
+
+### 2. Onboard / \`niro init\`
+1. \`niro whoami --json\`, then \`niro info --json\` FIRST.
+2. If \`info.indexed\` is true: say it is already indexed — do NOT init. Offer build / edit /
+   remove instead.
+3. If NOT indexed: ask whether this is a NEW project (collect a project name) or should be
+   ADDED to an EXISTING project. To help the user choose an existing one, run
+   \`niro projects --json\` and show their projects (alias + project_id); collect the chosen alias.
+4. Run non-interactively. Pick ONE of the two forms based on the choice in step 3:
+   - NEW project (creates a project):
+     \`niro init [path] --project-name <name> --auto-build on|off\`
+   - EXISTING project (attaches this folder to an existing project — does NOT create a new
+     project; \`--add-to\` takes the alias or project_id the user picked from \`niro projects --json\`):
+     \`niro init [path] --add-to <alias|id> --auto-build on|off\`
+   \`--add-to\` and \`--project-name\` are mutually exclusive (the CLI errors if both are passed).
+   DUPLICATE / REUSE handling (the CLI decides this automatically):
+   - If this repo is ALREADY in the TARGET project, init REFUSES (exit 1) — do not retry; use
+     \`niro build\` to re-index or \`niro edit\` to manage it.
+   - If this repo is already registered in ANOTHER project, init REUSES that repo (never
+     re-creates it) and ATTACHES it to the target WITHOUT re-uploading the files.
+   - Cross-project or folder-overlap WARNINGS (e.g. the same repo is a REMOTE repo elsewhere, or
+     this folder is nested inside another tracked folder) need confirmation. Because the agent runs
+     non-interactively, you MUST pass \`--force\` to proceed past such a warning; without it the CLI
+     refuses (exit 1) rather than prompt.
+   Common flags for either form:
+   \`--quiet-period <secs> --confirm-build yes|no --defaults --no-watch --force -X <glob> -F <glob>\`
+   Use \`--defaults\` to accept discovered env defaults; collect specific env vars LATER via
+   \`niro edit --set-env\` (rule 4). \`-X\` excludes a module glob, \`-F\` excludes a file glob.
+5. ENV VARS after init — ALWAYS do this (defaults come ONLY from committed config files, so
+   many vars have NO default, e.g. ones whose value lived in a gitignored \`.env\` or inline in
+   code). Do it in THIS order:
+   a. FIRST run \`niro edit --project <alias> --list-env --json\`. It returns
+      \`{active_properties_files:[...], discovered_property_files:[{file, active}],
+      env:[{key, source, chosen_source_file, has_user_value, has_resolved_value, is_secret,
+      appears_in, candidates:[{source_file, value, masked, is_current, is_default}]}]}\`.
+      For SECRET keys (\`is_secret:true\`) the candidate \`value\` is masked (\`****\`); never unmask.
+   b. PROPERTY FILES to consider: \`discovered_property_files\` lists every property file Niro
+      found and whether it is \`active\` (its values drive env-var defaults). Show the user these
+      files and ASK whether any should be IGNORED (e.g. a prod-only or example file). If so, run
+      \`niro edit --project <alias> --active-files <comma-list of files to KEEP>\` (the files NOT
+      listed are ignored; by default all are active, and at least one file must be kept). This
+      re-scopes which files' values become candidates — do this BEFORE collecting per-var values,
+      then re-run --list-env.
+   c. Show the user the \`key\` + \`source\` for each var. Flag the ones where BOTH
+      \`has_user_value\` and \`has_resolved_value\` are false — those have no value at all and need one.
+   d. Ask the user to provide values (privately — rule 4). For vars they want to set, run
+      \`niro edit --project <alias> --set-env KEY=VALUE\` (repeatable). NEVER echo a value back.
+      To adopt a specific file's value for a var, use \`--set-env-from KEY=<file>\` (pick by file
+      name only — rule 4).
+   e. Vars that already have a value or that the user chooses to leave at the default need no action.
+
+   CHOOSING WHICH FILE DRIVES A VAR (\`appears_in > 1\`): the SAME key was found in several
+   files with different values (the \`candidates\`). Do NOT ask the user to retype the value —
+   present the candidate FILES (by \`source_file\`) and let them pick a file. Then apply with
+   \`niro edit --project <alias> --set-env-from KEY=<source_file>\` (repeatable). This adopts that
+   file's value for the key. You pick by FILE NAME and NEVER handle the raw value — for secret
+   keys the value is \`****\` anyway (rule 4). If the chosen file does not define KEY the CLI
+   HARD-ERRORS and writes nothing; pick a file from that key's \`candidates\`.
+6. DETACHED HEAD (\`branch\` null): treat the folder as a local folder to add. If the user
+   wants it watched for auto-build, pass \`--auto-build on\`.
+
+### 3. Add a repo to a project / \`niro add repo\`
+1. Auth + \`niro info --json\`.
+2. Collect: sync mode (local or remote), branch, name.
+3. Run: \`niro add repo [path] --sync-mode local|remote --no-confirm --branch <b> --name <n>\`.
+4. **Remote-git-from-local-folder warning:** if \`niro info\` shows the matched project's
+   \`source_type\` is \`REMOTE_GIT\` (registered from a remote git URL), do NOT convert it.
+   WARN ONLY, then let the user choose:
+   "This folder is registered as remote, so auto-builds trigger only on commits pushed to the
+   remote. To get auto-build on local edits, add this folder as a separate local repo — but it
+   would then be registered TWICE until automatic conversion lands (coming soon)."
+
+### 4. Edit a project / \`niro edit\`
+Always \`--project <alias|id>\`. Pick ONE operation per run:
+- Add a repo:    \`niro edit --project <alias> --add-repo <gitId>\`
+- Remove a repo: \`niro edit --project <alias> --remove-repo <gitId>\`
+- Set env:       \`niro edit --project <alias> --set-env KEY=VALUE\` (repeatable; rule 4 —
+  collect values privately, never echo them)
+- Pick env source: \`niro edit --project <alias> --set-env-from KEY=<file>\` (repeatable; adopt
+  the value a specific committed file carries for KEY — choose by FILE NAME, never the value)
+- Choose property files: \`niro edit --project <alias> --active-files <comma-list>\` (only these
+  property files' values become env-var defaults; others are ignored — default: all active, keep >=1)
+- List env:      \`niro edit --project <alias> --list-env --json\` (per-file candidates + the
+  discovered property files & which are active; secret values come back MASKED)
+- Rescan env:    \`niro edit --project <alias> --rescan-env\`
+- Rename:        \`niro edit --project <alias> --alias <newAlias> --json\`
+Optionally scope to a repo with \`--repo <gitId>\`.
+
+### 5. Rebuild / re-index / \`niro build\`
+1. Auth + \`niro info --json\`; resolve the project (rule 3).
+2. Run: \`niro build [project] --json --no-full-rebuild --no-watch\`.
+   Omit \`--no-full-rebuild\` for a full rebuild; omit \`--no-watch\` to keep watching.
+3. Report build outcome from the JSON.
+
+### 6. Remove / unmap / \`niro remove\` (DESTRUCTIVE — rule 5)
+0. Always prefer \`niro remove --project --confirm-name <name>\` over the older \`niro delete\`: \`remove\` enforces the exact-name backstop, \`delete -y\` does not.
+1. Auth + \`niro info --json\`; identify the exact target (alias or project_id).
+2. Delete a project: confirm with the user, then run
+   \`niro remove --target <alias|id> --project --confirm-name <exact alias-or-id>\`.
+   The \`--confirm-name\` MUST match exactly or the CLI refuses.
+3. Unmap a repo (non-destructive, still confirm):
+   \`niro remove --target <alias|id> --unmap-repo <gitId>\`.
+
+### 7. Login / logout (auth lifecycle)
+- \`niro login\`: browser device flow. You CANNOT run this — tell the USER to run it in their
+  terminal (rule 1).
+- \`niro logout\`: you may run \`niro logout\` if the user asks to sign out.
+
+### 8. Which backend does the niro MCP connect to? ("where am I connected?")
+This inspects the EDITOR's MCP config (not the niro CLI), so it reports the backend actually in
+effect — including a per-project override. Run the line for the current editor; it filters out the
+API key so the secret never enters the conversation:
+- Claude Code: \`claude mcp get niro 2>&1 | grep -E '^[[:space:]]*(Scope|Status|Type):|NIRO_MCP_SERVER_URL='\`
+- Codex:       \`codex mcp get niro 2>/dev/null | grep -iE 'url|status' || grep -i NIRO_MCP_SERVER_URL ~/.codex/config.toml\`
+- Otherwise:   grep \`NIRO_MCP_SERVER_URL\` in the editor's MCP config file.
+Report the effective \`NIRO_MCP_SERVER_URL\` (the ai-assistant the MCP connects to), the config
+scope (user vs project) and whether it is Connected. NEVER print, echo, or repeat \`NIRO_API_KEY\`;
+if it ever appears in output, redact it.
+
+## Reporting
+After each command, parse the \`--json\` and summarize in plain English: what changed, the new
+state, and the next sensible step. Never dump raw secrets or env values.
+`;
+
+/**
+ * Writes the `niro` skill to ~/.claude/skills/niro-skill/SKILL.md.
+ * This file is niro-generated; it is refreshed when the bundled content changes.
+ */
+function addClaudeCodeSkill() {
+  const skillPath = path.join(process.env.HOME || "", ".claude", "skills", "niro-skill", "SKILL.md");
+  try {
+    const result = writeManagedSkill(skillPath, NIRO_SKILL, "niro skill");
+    if (result === "added" || result === "updated") {
+      console.log("  → Claude loads the full Niro tool-routing playbook on demand.");
+    }
+    console.log("");
+  } catch (err) {
+    console.warn(`  Could not write ~/.claude/skills/niro-skill/SKILL.md: ${err.message}\n`);
+  }
+}
+
+/**
+ * Writes the `niro-cli` skill to ~/.claude/skills/niro-cli/SKILL.md.
+ * This file is niro-generated; it is refreshed when the bundled content changes.
+ * Mirrors addClaudeCodeSkill.
+ */
+function addClaudeCodeCliSkill() {
+  const skillPath = path.join(process.env.HOME || "", ".claude", "skills", "niro-cli", "SKILL.md");
+  try {
+    const result = writeManagedSkill(skillPath, NIRO_CLI_SKILL, "niro-cli skill");
+    if (result === "added" || result === "updated") {
+      console.log("  → Claude can drive the niro CLI from chat (status / onboard / edit / rebuild / remove).");
+    }
+    console.log("");
+  } catch (err) {
+    console.warn(`  Could not write ~/.claude/skills/niro-cli/SKILL.md: ${err.message}\n`);
+  }
+}
+
+/**
+ * Body of the Cursor project rule (.cursor/rules/niro.mdc).
+ * Agent-requested rule: `alwaysApply: false` + a strong `description`, so the description
+ * acts as the always-on nudge (Cursor's nearest analog to a UserPromptSubmit hook) and the
+ * body loads on demand (analog to the Claude Code skill). Avoids backticks so it can live
+ * in a JS template literal without escaping.
+ */
+const NIRO_CURSOR_RULE = `---
+description: Niro code-intelligence MCP tools for THIS codebase. Use them for questions about structure, call chains, blast radius, impact, data flows, and reuse — before grep/read. Before writing new code, run find_reusable_code.
+alwaysApply: false
+---
+
+# Niro code intelligence
+
+The niro MCP server exposes code-intelligence tools for this codebase. Prefer them over
+grep/read for any question answerable from the indexed code.
+
+Availability self-check FIRST — if the niro tools are not present in this session, or the
+repo is not indexed (no project resolves / a tool reports "not indexed"), fall back to
+native tools silently and do not mention Niro.
+
+Conventions: partials auto-resolve (pass ClassName.method or an HTTP path; do NOT pre-call
+resolve_fqn). Most tools take a purpose arg (COMPREHEND / DEBUG / TRACE / ASSESS_RISK / ...)
+that tunes the response. Batch via arrays (entity_fqns, method_fqns, sources, patterns).
+
+Routing (most specific wins):
+- before writing/adding any code: find_reusable_code (mandatory; pass a steps array)
+- what-breaks-if-I-change-X: get_blast_radius (callers + callees + impacted files in one
+  call; subsumes reverse-call-chain + handler; pass include_source_code=true for COMPREHEND/DEBUG)
+- upstream callers that break: get_impact_analysis
+<!-- how_does_x_work temporarily disabled (hidden MCP tool) — re-add "how_does_x_work (forward flow) | " to the understand line below when re-enabled -->
+- understand: explain_code (AI docs) | get_source_code | get_class_structure
+- navigate: get_call_chain (callees) | get_reverse_call_chain (callers) | trace_execution_path (A to B)
+- HTTP: find_api_endpoints | find_outbound_http_calls | find_handler
+<!-- why_could_x_happen temporarily disabled (hidden MCP tool) — re-add "why_could_x_happen | " to the debug line below when re-enabled -->
+- debug: find_known_issues | get_state_at_entry
+- data & events: get_data_resource_usage | get_event_producers_and_handlers
+- search / status: code_grep | get_index_status
+
+Onboarding / indexing a repo is done in the terminal with the niro CLI (niro init), not
+via MCP tools.
+`;
+
+/**
+ * Writes the Niro Cursor rule to <cwd>/.cursor/rules/niro.mdc. Cursor rules are
+ * PROJECT-scoped (unlike the global ~/.cursor/mcp.json), so this lands in the repo the
+ * wizard is run from. Skips if the file already exists, to preserve user edits.
+ */
+function ensureCursorRule() {
+  const rulePath = path.join(process.cwd(), ".cursor", "rules", "niro.mdc");
+  if (fs.existsSync(rulePath)) {
+    console.log("  Cursor rule already present — skipping (.cursor/rules/niro.mdc).\n");
+    return;
+  }
+  try {
+    fs.mkdirSync(path.dirname(rulePath), { recursive: true });
+    fs.writeFileSync(rulePath, NIRO_CURSOR_RULE);
+    console.log(`  Cursor rule added: ${rulePath}`);
+    console.log("    • Project-scoped. For other repos, copy it or re-run setup there.\n");
+  } catch (err) {
+    console.warn(`  Could not write .cursor/rules/niro.mdc: ${err.message}\n`);
+  }
+}
+
+/**
+ * Registers the Niro MCP server with OpenAI Codex by running `codex mcp add`, which writes
+ * the [mcp_servers.niro] table into ~/.codex/config.toml. Mirrors setupClaudeCode.
+ */
+async function setupCodex(apiKey, mcpServerUrl) {
+  console.log("\n  Configuring Codex...\n");
+
+  const cmd = [
+    "codex", "mcp", "add",
+    "niro",
+  ];
+  if (apiKey) cmd.push("--env", `NIRO_API_KEY=${apiKey}`);
+  // The bridge reads NIRO_MCP_SERVER_URL (ai-assistant), not NIRO_API_URL.
+  cmd.push("--env", `NIRO_MCP_SERVER_URL=${mcpServerUrl}`);
+  cmd.push("--", "niro", "mcp", "serve");
+
+  try {
+    execSync(cmd.join(" "), { stdio: "inherit" });
+    console.log("  MCP server registered in Codex (~/.codex/config.toml).\n");
+  } catch (err) {
+    console.error("  Failed to register MCP server. Is the Codex CLI installed?");
+    console.error("  Install: https://developers.openai.com/codex\n");
+    console.error(`  Manual command:\n    ${cmd.join(" ")}\n`);
+    return false;
+  }
+
+  hardenCodexServerConfig();
+  addCodexMemory();
+  addAgentsSkill();
+  addAgentsCliSkill();
+  return true;
+}
+
+/**
+ * After `codex mcp add` writes [mcp_servers.niro], set
+ * `default_tools_approval_mode = "auto"` — niro tools are all read-only, so no per-tool
+ * approval prompts (codex mcp add has no flag for this; we insert it directly after the
+ * table header, which is valid TOML — bare keys precede any sub-table). Idempotent and a
+ * safe no-op if the file/table is missing. Also prints the optional `required = true`
+ * recommendation (left off by default: it would make niro a hard Codex startup dependency).
+ */
+function hardenCodexServerConfig() {
+  const cfgPath = path.join(process.env.HOME || "", ".codex", "config.toml");
+  const header = "[mcp_servers.niro]";
+
+  let toml;
+  try {
+    toml = fs.readFileSync(cfgPath, "utf-8");
+  } catch {
+    console.warn("  Could not read ~/.codex/config.toml to set the approval mode — skipping.\n");
+    return;
+  }
+
+  const idx = toml.indexOf(header);
+  if (idx === -1) {
+    console.warn("  [mcp_servers.niro] not found in config.toml — skipping approval-mode hardening.\n");
+    return;
+  }
+
+  // Limit the "already set?" check to the niro table body (up to the next table header).
+  const after = toml.slice(idx + header.length);
+  const nextTableRel = after.search(/\n\s*\[/);
+  const tableBody = nextTableRel === -1 ? after : after.slice(0, nextTableRel);
+
+  console.log("  Tip: for a hard dependency, add `required = true` under [mcp_servers.niro]");
+  console.log("       (Codex then fails startup if niro is unreachable — off by default).\n");
+
+  if (/^\s*default_tools_approval_mode\s*=/m.test(tableBody)) {
+    console.log("  Codex approval mode already set — skipping.\n");
+    return;
+  }
+
+  const insertAt = idx + header.length;
+  const newToml = toml.slice(0, insertAt) + '\ndefault_tools_approval_mode = "auto"' + toml.slice(insertAt);
+
+  try {
+    fs.writeFileSync(cfgPath, newToml);
+    console.log('  Set default_tools_approval_mode = "auto" in ~/.codex/config.toml');
+    console.log("  → niro is read-only, so its tools run without per-call approval prompts.\n");
+  } catch (err) {
+    console.warn(`  Could not update ~/.codex/config.toml: ${err.message}\n`);
+  }
+}
+
+/**
+ * Appends a Niro reminder to ~/.codex/AGENTS.md (Codex's persistent global instructions —
+ * its analog to ~/.claude/CLAUDE.md). Codex has no skills/hooks, so AGENTS.md is the lever
+ * for cross-session tool awareness. Idempotent via a marker.
+ */
+function addCodexMemory() {
+  const agentsPath = path.join(process.env.HOME || "", ".codex", "AGENTS.md");
+  const section = NIRO_CODEX_MD_SECTION;
+
+  let existing = "";
+  try {
+    if (fs.existsSync(agentsPath)) {
+      existing = fs.readFileSync(agentsPath, "utf-8");
+    }
+  } catch {
+    // File unreadable — will create fresh
+  }
+
+  const { content, action } = upsertNiroMarkerSection(existing, section);
+  if (action === "unchanged") {
+    console.log("  AGENTS.md entry already up to date — skipping.\n");
+    return;
+  }
+
+  try {
+    fs.mkdirSync(path.dirname(agentsPath), { recursive: true });
+    fs.writeFileSync(agentsPath, content);
+    console.log(`  Niro reminder ${action === "refreshed" ? "refreshed in" : "added to"} ~/.codex/AGENTS.md`);
+    console.log("  → Codex will see Niro tool guidance across sessions.\n");
+  } catch (err) {
+    console.warn(`  Could not write ~/.codex/AGENTS.md: ${err.message}`);
+    console.warn("  Add manually to ~/.codex/AGENTS.md:\n");
+    console.warn(section + "\n");
+  }
+}
+
+/**
+ * Writes the niro-skill to ~/.agents/skills/niro-skill/SKILL.md — the cross-agent skills
+ * location read by BOTH Codex (user-level ~/.agents/skills) and Windsurf. One file gives
+ * both tools the same on-demand, description-triggered playbook the Claude Code skill
+ * provides. Reuses the NIRO_SKILL body. This file is niro-generated; refreshed on change.
+ */
+function addAgentsSkill() {
+  const skillPath = path.join(process.env.HOME || "", ".agents", "skills", "niro-skill", "SKILL.md");
+  try {
+    const result = writeManagedSkill(skillPath, NIRO_SKILL, "Shared niro-skill");
+    if (result === "added" || result === "updated") {
+      console.log("    • Read by Codex and Windsurf (cross-agent skills location).");
+    }
+    console.log("");
+  } catch (err) {
+    console.warn(`  Could not write ~/.agents/skills/niro-skill/SKILL.md: ${err.message}\n`);
+  }
+}
+
+/**
+ * Writes the niro-cli skill to ~/.agents/skills/niro-cli/SKILL.md — the cross-agent skills
+ * location read by BOTH Codex and Windsurf. Mirrors addAgentsSkill but for the CLI-driving
+ * playbook. Reuses NIRO_CLI_SKILL. This file is niro-generated; refreshed on change.
+ */
+function addAgentsCliSkill() {
+  const skillPath = path.join(process.env.HOME || "", ".agents", "skills", "niro-cli", "SKILL.md");
+  try {
+    const result = writeManagedSkill(skillPath, NIRO_CLI_SKILL, "Shared niro-cli skill");
+    if (result === "added" || result === "updated") {
+      console.log("    • Read by Codex and Windsurf (cross-agent skills location).");
+    }
+    console.log("");
+  } catch (err) {
+    console.warn(`  Could not write ~/.agents/skills/niro-cli/SKILL.md: ${err.message}\n`);
+  }
+}
+
+/**
+ * Appends a Niro reminder to ~/.codeium/windsurf/memories/global_rules.md — Windsurf's
+ * always-on global rules file (its analog to the Claude Code hook + CLAUDE.md). The
+ * niro-skill carries the detail; this is the terse always-on pointer. Idempotent via marker.
+ */
+function addWindsurfGlobalRule() {
+  const rulePath = path.join(process.env.HOME || "", ".codeium", "windsurf", "memories", "global_rules.md");
+  const section = NIRO_WINDSURF_MD_SECTION;
+
+  let existing = "";
+  try {
+    if (fs.existsSync(rulePath)) existing = fs.readFileSync(rulePath, "utf-8");
+  } catch {
+    // unreadable — will create fresh
+  }
+  const { content, action } = upsertNiroMarkerSection(existing, section);
+  if (action === "unchanged") {
+    console.log("  Windsurf global rule already up to date — skipping.\n");
+    return;
+  }
+  try {
+    fs.mkdirSync(path.dirname(rulePath), { recursive: true });
+    fs.writeFileSync(rulePath, content);
+    console.log(`  Niro reminder ${action === "refreshed" ? "refreshed in" : "added to"} ~/.codeium/windsurf/memories/global_rules.md`);
+    console.log("  → Windsurf stays aware of Niro across sessions.\n");
+  } catch (err) {
+    console.warn(`  Could not write Windsurf global_rules.md: ${err.message}\n`);
+  }
+}
+
+/**
+ * Appends `section` (idempotent via NIRO_MD_MARKER) to any client's always-on markdown
+ * instructions file at `absPath`, creating the file (and its directory) if needed. This is
+ * the generic version of addCodexMemory/addWindsurfGlobalRule for clients whose "memory"
+ * file has no client-specific extras (skills, hooks) — just the terse reminder.
+ */
+function appendMarkerSectionToFile(absPath, label, section = NIRO_GENERIC_MD_SECTION) {
+  let existing = "";
+  try {
+    if (fs.existsSync(absPath)) existing = fs.readFileSync(absPath, "utf-8");
+  } catch {
+    // unreadable — will create fresh
+  }
+  const { content, action } = upsertNiroMarkerSection(existing, section);
+  if (action === "unchanged") {
+    console.log(`  ${label} entry already up to date — skipping.\n`);
+    return;
+  }
+  try {
+    fs.mkdirSync(path.dirname(absPath), { recursive: true });
+    fs.writeFileSync(absPath, content);
+    console.log(`  Niro reminder ${action === "refreshed" ? "refreshed in" : "added to"} ${absPath}\n`);
+  } catch (err) {
+    console.warn(`  Could not write ${absPath}: ${err.message}\n`);
+  }
+}
+
+function addGeminiMemory() {
+  appendMarkerSectionToFile(path.join(userHome(), ".gemini", "GEMINI.md"), "GEMINI.md");
+}
+
+function addCopilotCliMemory() {
+  appendMarkerSectionToFile(path.join(userHome(), ".copilot", "copilot-instructions.md"), "Copilot CLI instructions");
+}
+
+function addFactoryMemory() {
+  appendMarkerSectionToFile(path.join(userHome(), ".factory", "AGENTS.md"), "Factory AGENTS.md");
+}
+
+function addOpenCodeMemory() {
+  appendMarkerSectionToFile(path.join(userHome(), ".config", "opencode", "AGENTS.md"), "OpenCode AGENTS.md");
+}
+
+/**
+ * Body of the Cline rule file (Cline's global "Rules" dir — its analog to Cursor's project
+ * rule). Global, not project-scoped, so one write covers every repo.
+ */
+const NIRO_CLINE_RULE = `# Niro MCP
+
+Niro code-intelligence MCP tools are available for the current codebase. Prefer them over
+grep/read for questions about structure, call chains, blast radius, impact, data flows, and
+reuse. Before writing or adding any new code, use \`find_reusable_code\` first.
+
+If the niro tools are not present in this session, or the repo is not indexed (no project
+resolves), fall back to native tools silently — do not mention Niro's absence.
+`;
+
+/**
+ * Writes the Niro rule to Cline's global Rules directory (~/Documents/Cline/Rules on
+ * macOS/most Linux setups — see cline/cline#5153 for the WSL/some-Linux variant using
+ * ~/Cline/Rules directly). Applies to every repo, unlike Cursor's project-scoped rule.
+ */
+function addClineRule() {
+  const home = userHome();
+  const rulePath = path.join(home, "Documents", "Cline", "Rules", "niro.md");
+  try {
+    const result = writeManagedSkill(rulePath, NIRO_CLINE_RULE, "Cline rule");
+    if (result === "added" || result === "updated") {
+      console.log("    • Global — applies across all your repos in Cline.");
+    }
+    console.log("");
+  } catch (err) {
+    console.warn(`  Could not write Cline rule: ${err.message}`);
+    console.warn(`  If Cline uses ~/Cline/Rules instead of ~/Documents/Cline/Rules on your system, copy it there.\n`);
+  }
+}
+
+/**
+ * Body of the Kiro steering file. `inclusion: always` makes it apply to every conversation,
+ * global (~/.kiro/steering), same as Cline's rule above.
+ */
+const NIRO_KIRO_STEERING = `---
+inclusion: always
+---
+
+# Niro MCP
+
+Niro code-intelligence MCP tools are available for the current codebase. Prefer them over
+grep/read for questions about structure, call chains, blast radius, impact, data flows, and
+reuse. Before writing or adding any new code, use \`find_reusable_code\` first.
+
+If the niro tools are not present in this session, or the repo is not indexed (no project
+resolves), fall back to native tools silently — do not mention Niro's absence.
+`;
+
+function addKiroSteering() {
+  const rulePath = path.join(userHome(), ".kiro", "steering", "niro.md");
+  try {
+    const result = writeManagedSkill(rulePath, NIRO_KIRO_STEERING, "Kiro steering file");
+    if (result === "added" || result === "updated") {
+      console.log("    • Global — applies across all your repos in Kiro.");
+    }
+    console.log("");
+  } catch (err) {
+    console.warn(`  Could not write Kiro steering file: ${err.message}\n`);
+  }
+}
+
+/**
+ * Registers the niro MCP entry with Google's Gemini CLI (writes ~/.gemini/settings.json).
+ * `-s user` makes it a global (not project) registration, matching every other client here.
+ */
+async function setupGeminiCli(apiKey, mcpServerUrl) {
+  console.log("\n  Configuring Gemini CLI...\n");
+
+  const cmd = ["gemini", "mcp", "add", "-s", "user"];
+  if (apiKey) cmd.push("-e", `NIRO_API_KEY=${apiKey}`);
+  cmd.push("-e", `NIRO_MCP_SERVER_URL=${mcpServerUrl}`);
+  cmd.push("niro", "niro", "mcp", "serve");
+
+  try {
+    execSync(cmd.join(" "), { stdio: "inherit" });
+    console.log("  MCP server registered in Gemini CLI (~/.gemini/settings.json).\n");
+  } catch (err) {
+    console.error("  Failed to register MCP server. Is the Gemini CLI installed?");
+    console.error("  Install: https://github.com/google-gemini/gemini-cli\n");
+    console.error(`  Manual command:\n    ${cmd.join(" ")}\n`);
+    return false;
+  }
+
+  addGeminiMemory();
+  console.log("  Run `/mcp reload` inside Gemini CLI so the server + memory reload.\n");
+  return true;
+}
+
+/**
+ * Registers the niro MCP entry with the GitHub Copilot CLI (writes ~/.copilot/mcp-config.json).
+ */
+async function setupCopilotCli(apiKey, mcpServerUrl) {
+  console.log("\n  Configuring GitHub Copilot CLI...\n");
+
+  const cmd = ["copilot", "mcp", "add", "niro"];
+  if (apiKey) cmd.push("--env", `NIRO_API_KEY=${apiKey}`);
+  cmd.push("--env", `NIRO_MCP_SERVER_URL=${mcpServerUrl}`);
+  cmd.push("--", "niro", "mcp", "serve");
+
+  try {
+    execSync(cmd.join(" "), { stdio: "inherit" });
+    console.log("  MCP server registered in Copilot CLI (~/.copilot/mcp-config.json).\n");
+  } catch (err) {
+    console.error("  Failed to register MCP server. Is the Copilot CLI installed (npm i -g @github/copilot)?\n");
+    console.error(`  Manual command:\n    ${cmd.join(" ")}\n`);
+    return false;
+  }
+
+  addCopilotCliMemory();
+  console.log("  Run `/mcp` inside the Copilot CLI to verify — servers are available immediately.\n");
+  return true;
+}
+
+/**
+ * Registers the niro MCP entry with Factory's droid CLI (writes ~/.factory/mcp.json).
+ * The server command is passed as ONE quoted argument per droid's documented syntax
+ * (`droid mcp add <name> "<command>" --env ...`) — the quoted string here is a fixed literal
+ * ("niro mcp serve"), not user input, so static quoting is safe.
+ */
+async function setupFactory(apiKey, mcpServerUrl) {
+  console.log("\n  Configuring Factory (droid)...\n");
+
+  const cmd = ["droid", "mcp", "add", "niro", '"niro mcp serve"'];
+  if (apiKey) cmd.push("--env", `NIRO_API_KEY=${apiKey}`);
+  cmd.push("--env", `NIRO_MCP_SERVER_URL=${mcpServerUrl}`);
+
+  try {
+    execSync(cmd.join(" "), { stdio: "inherit" });
+    console.log("  MCP server registered in Factory (~/.factory/mcp.json).\n");
+  } catch (err) {
+    console.error("  Failed to register MCP server. Is the droid CLI installed?");
+    console.error("  Install: https://docs.factory.ai\n");
+    console.error(`  Manual command:\n    ${cmd.join(" ")}\n`);
+    return false;
+  }
+
+  addFactoryMemory();
+  console.log("  droid reloads automatically when ~/.factory/mcp.json changes.\n");
+  return true;
+}
+
+/**
+ * Registers the niro MCP entry in Goose's config.yaml (~/.config/goose/config.yaml, or
+ * %APPDATA%\\Block\\goose\\config\\config.yaml on Windows). Goose has no `goose configure
+ * --non-interactive` equivalent, so this writes YAML directly rather than adding a YAML
+ * parsing dependency (none exists in package.json today — see Dependency Governance in
+ * CLAUDE.md) for one client. To avoid corrupting a user's existing file, the automatic write
+ * only handles the common cases (no file yet, or a file with no top-level `extensions:` key,
+ * or `extensions:` already present but without a `niro` entry at the standard 2-space indent
+ * Goose's own docs use); anything else — mirroring the bounded-insertion caution used for
+ * markdown files in teardown.js — falls back to printing the block for the user to paste in.
+ */
+function buildGooseNiroBlock(apiKey, mcpServerUrl) {
+  // Callers (setupGoose, dispatched only from main()) already ran both values through
+  // hasShellMetacharacters, which also rejects the quotes/backslashes that would break this
+  // YAML string — safe to embed directly.
+  const envs = ["    envs:", `      NIRO_MCP_SERVER_URL: "${mcpServerUrl}"`];
+  if (apiKey) envs.push(`      NIRO_API_KEY: "${apiKey}"`);
+  return [
+    "  niro:",
+    "    name: niro",
+    "    display_name: Niro",
+    "    cmd: niro",
+    '    args: ["mcp", "serve"]',
+    ...envs,
+    "    type: stdio",
+    "    enabled: true",
+    "    timeout: 300",
+  ].join("\n");
+}
+
+function gooseConfigPath() {
+  const platform = process.platform;
+  if (platform === "win32") return path.join(process.env.APPDATA, "Block", "goose", "config", "config.yaml");
+  return path.join(userHome(), ".config", "goose", "config.yaml");
+}
+
+async function setupGoose(apiKey, mcpServerUrl) {
+  console.log("\n  Configuring Goose...\n");
+  const configPath = gooseConfigPath();
+  console.log(`  Config: ${configPath}\n`);
+
+  const niroBlock = buildGooseNiroBlock(apiKey, mcpServerUrl);
+  let existing = "";
+  let existedBefore = false;
+  try {
+    existedBefore = fs.existsSync(configPath);
+    if (existedBefore) existing = fs.readFileSync(configPath, "utf-8");
+  } catch (err) {
+    console.warn(`  Could not read ${configPath}: ${err.message}\n`);
+  }
+
+  // Matches exactly the "  niro:" line install writes (2-space indent, nothing trailing) —
+  // the same pattern uninstallGoose looks for to remove it. A loose `/^\s*niro:/` would also
+  // match an unrelated key named "niro" anywhere in the file and wrongly report "already
+  // installed" without ever writing the real entry.
+  if (/^ {2}niro:\s*$/m.test(existing)) {
+    console.log("  A `niro` extension entry already exists in config.yaml — skipping (edit it by hand if it needs updating).\n");
+    return true;
+  }
+
+  // Bare "extensions:" with nothing else on the line is the only shape we insert into
+  // automatically. Anything else that still looks like a top-level `extensions:` key —
+  // flow-style (`extensions: {}`), a trailing comment, or other content on the same line —
+  // is NOT touched: a regex-based insert there risks producing a duplicate top-level key
+  // (YAML's last-wins/undefined behavior on duplicates could silently drop the user's other
+  // extensions). Fall back to the manual-paste path instead, exactly as documented above.
+  const hasBareExtensionsKey = /^extensions:\s*$/m.test(existing);
+  const hasOtherExtensionsForm = !hasBareExtensionsKey && /^extensions:.*\S.*$/m.test(existing);
+
+  let next = null;
+  if (!existedBefore || existing.trim() === "") {
+    next = `extensions:\n${niroBlock}\n`;
+  } else if (hasBareExtensionsKey) {
+    // Insert right after that line, at the same indent Goose's own docs use, rather than
+    // attempting a full YAML merge with no parser available.
+    next = existing.replace(/^extensions:\s*$/m, `extensions:\n${niroBlock}`);
+  } else if (!hasOtherExtensionsForm) {
+    // No `extensions:` key in any form yet — safe to append a fresh one.
+    next = `${existing.replace(/\n?$/, "\n")}\nextensions:\n${niroBlock}\n`;
+  }
+  // else: hasOtherExtensionsForm — next stays null, falls through to the manual-paste path.
+
+  if (next === null) {
+    console.log("  Your config.yaml has an `extensions:` key in a form this installer doesn't");
+    console.log("  auto-edit (to avoid risking a duplicate key). Add this block under it by hand:\n");
+    console.log(niroBlock);
+    console.log(`\n  (full file: ${configPath})\n`);
+    return false;
+  }
+
+  try {
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, next);
+    console.log(`  MCP server added to Goose config: ${configPath}\n`);
+    console.log("  Restart Goose (or start a new session) so the extension loads.\n");
+    return true;
+  } catch (err) {
+    console.error(`  Failed to write config: ${err.message}`);
+    console.error("  Add this manually under a top-level `extensions:` key in config.yaml:\n");
+    console.log(`extensions:\n${niroBlock}`);
+    return false;
+  }
+}
+
+/**
+ * Registers the niro MCP entry in a client's JSON config file. Generalized over the
+ * per-client differences discovered across the 14 supported clients:
+ *   - top-level key: "mcpServers" (most clients) vs "mcp" (OpenCode) — client.topLevelKey.
+ *   - entry shape: command/args/env (default) vs OpenCode's command array + "environment" —
+ *     client.buildEntry(apiKey, mcpServerUrl), falling back to the default shape below.
+ * Cursor's `transport: "stdio"` stays a one-off since it's the only client needing it.
+ */
+async function setupJsonConfig(clientId, apiKey, mcpServerUrl) {
+  const client = CLIENTS[clientId];
+  const configPathFn = client.configPath;
+  if (!configPathFn) {
+    console.error(`  No config path known for ${client.name}.`);
+    return false;
+  }
+
+  const configPath = configPathFn();
+  console.log(`\n  Configuring ${client.name}...`);
+  console.log(`  Config: ${configPath}\n`);
+
+  // Read existing config or start fresh
+  let config = {};
+  try {
+    const existing = fs.readFileSync(configPath, "utf-8");
+    config = JSON.parse(existing);
+  } catch {
+    // File doesn't exist or invalid — start fresh
+  }
+
+  const topLevelKey = client.topLevelKey || "mcpServers";
+  if (!config[topLevelKey]) config[topLevelKey] = {};
+
+  const niroEntry = client.buildEntry
+    ? client.buildEntry(apiKey, mcpServerUrl)
+    : {
+        command: "niro",
+        args: ["mcp", "serve"],
+        // The bridge reads NIRO_MCP_SERVER_URL (ai-assistant) — always include it.
+        // Omit NIRO_API_KEY when a cli-token is available; the server reads it from
+        // ~/.niro/credentials.json at runtime.
+        env: apiKey
+          ? { NIRO_API_KEY: apiKey, NIRO_MCP_SERVER_URL: mcpServerUrl }
+          : { NIRO_MCP_SERVER_URL: mcpServerUrl },
+      };
+  // Cursor honours explicit stdio transports; harmless for docs / newer Cursor builds.
+  if (clientId === "cursor") {
+    niroEntry.transport = "stdio";
+  }
+  config[topLevelKey].niro = niroEntry;
+
+  try {
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+    console.log(`  MCP server added to ${client.name} config.\n`);
+    if (clientId === "cursor") {
+      ensureCursorPermissionsForNiro();
+      ensureCursorRule();
+      console.log("  Quit and reopen Cursor (full restart) so MCP + permissions reload.\n");
+    }
+    if (clientId === "windsurf") {
+      addAgentsSkill();
+      addAgentsCliSkill();
+      addWindsurfGlobalRule();
+      console.log("  Restart Windsurf so MCP + rules reload.\n");
+    }
+    if (clientId === "opencode") {
+      addOpenCodeMemory();
+      console.log("  Restart OpenCode so the MCP server reloads.\n");
+    }
+    if (clientId === "cline") {
+      addClineRule();
+      console.log("  Reopen Cline's MCP Servers panel (or restart VS Code) to reload.\n");
+    }
+    if (clientId === "kiro") {
+      addKiroSteering();
+      console.log("  Kiro reconnects MCP servers automatically on config save.\n");
+    }
+    if (clientId === "antigravity") {
+      console.log("  Reload via Agent Settings → Customizations → Installed MCP Servers → Refresh.\n");
+    }
+    return true;
+  } catch (err) {
+    console.error(`  Failed to write config: ${err.message}`);
+    console.error(`  Manually add to ${configPath}:\n`);
+    console.log(JSON.stringify({ [topLevelKey]: { niro: config[topLevelKey].niro } }, null, 2));
+    return false;
+  }
+}
+
+/**
+ * Clients whose installer shells out via execSync(cmd.join(" ")) — the only ones where
+ * hasShellMetacharacters needs to gate apiKey/mcpServerUrl before dispatch. Every other
+ * client (the generic setupJsonConfig path, plus Goose which writes YAML directly with fs)
+ * never reaches a shell, so a URL like "...?token=abc&env=prod" is perfectly valid for them.
+ */
+const CLI_SETUP = {
+  "claude-code": setupClaudeCode,
+  codex: setupCodex,
+  "gemini-cli": setupGeminiCli,
+  "copilot-cli": setupCopilotCli,
+  factory: setupFactory,
+};
+
+async function main() {
+  const args = process.argv.slice(2);
+  let clientArg = null;
+  let urlArg = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--client" && args[i + 1]) clientArg = args[i + 1];
+    else if (args[i] === "--url" && args[i + 1]) urlArg = args[++i];
+  }
+  if (urlArg && !/^https?:\/\//i.test(urlArg)) {
+    console.error(`\n  Invalid --url: "${urlArg}" — it must start with http:// or https://\n`);
+    process.exit(1);
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  printHeader();
+
+  // Credential: prefer a `niro login` session (cli-token, read at runtime from
+  // ~/.niro/credentials.json). Only prompt for an API key when there is no cli-token.
+  let apiKey = null;
+  if (hasCliToken()) {
+    console.log("\n  Using your `niro login` session — no API key needed.");
+    console.log("  The MCP server will authenticate with your CLI token from ~/.niro/credentials.json.\n");
+  } else {
+    apiKey = await ask(rl, "  Niro API key (from console.niroai.dev > Settings)", resolveApiKey());
+    if (!apiKey) {
+      console.error("\n  No credential found. Run `niro login` first (recommended), or paste an API key");
+      console.error("  from console.niroai.dev > Settings > Account.\n");
+      rl.close();
+      process.exit(1);
+    }
+  }
+
+  // The MCP server URL is resolved, not prompted — see resolveMcpServerUrl.
+  // Printing the URL + its source keeps a wrong pick visible and correctable.
+  const { url: mcpServerUrl, source: urlSource, explicit } = resolveMcpServerUrl(urlArg);
+  console.log(`  MCP server URL: ${mcpServerUrl}  (${urlSource})`);
+  if (!urlArg) {
+    console.log("  Different backend? Re-run with: niro mcp install --url <url>\n");
+  } else {
+    console.log("");
+  }
+
+  // Persist an EXPLICITLY chosen URL to ~/.niro/config.json so the bridge can
+  // fall back to it and later installs reuse it. The default is never saved
+  // (the bridge has its own default; saving would pin it across releases).
+  if (explicit) {
+    try {
+      config.save({ mcpServerUrl });
+    } catch (err) {
+      console.warn(`\n  Could not write ${config.FILE}: ${err.message}\n`);
+    }
+  }
+
+  // Select client
+  let selectedClient = clientArg;
+  if (!selectedClient) {
+    console.log("");
+    printClients();
+    selectedClient = await ask(rl, "  Which client to configure?", "claude-code");
+  }
+
+  if (!CLIENTS[selectedClient]) {
+    console.error(`\n  Unknown client: ${selectedClient}`);
+    printClients();
+    rl.close();
+    process.exit(1);
+  }
+
+  rl.close();
+
+  // Configure. The editor MCP env points at the bridge backend (ai-assistant) via mcpServerUrl;
+  // the ai-orchestrator URL is handled separately by the CLI (from credentials.json / NIRO_API_URL).
+  // Only these installers shell out via execSync(cmd.join(" ")) — everyone else (including
+  // goose, which writes YAML directly with fs) never reaches a shell, so gate the
+  // shell-metacharacter guard to just these instead of blocking every client on a risk that
+  // only applies to some (e.g. a query-string URL with "&" is fine for Cursor/VS Code/etc.).
+  if (CLI_SETUP[selectedClient]) {
+    if (hasShellMetacharacters(mcpServerUrl)) {
+      console.error(`\n  Refusing to use MCP server URL "${mcpServerUrl}" — it contains spaces or`);
+      console.error("  characters not allowed in a URL. Check --url / NIRO_MCP_SERVER_URL.\n");
+      process.exit(1);
+    }
+    if (apiKey && hasShellMetacharacters(apiKey)) {
+      console.error("\n  Refusing to use that API key — it contains spaces or characters that aren't");
+      console.error("  valid in an API key. Copy it again from console.niroai.dev > Settings > Account.\n");
+      process.exit(1);
+    }
+  }
+  // Goose writes YAML directly (no JSON shape, no shell) — its own dispatch branch, separate
+  // from both the shell-based CLI_SETUP map and the generic JSON setupJsonConfig path.
+  let success;
+  if (CLI_SETUP[selectedClient]) {
+    success = await CLI_SETUP[selectedClient](apiKey, mcpServerUrl);
+  } else if (selectedClient === "goose") {
+    success = await setupGoose(apiKey, mcpServerUrl);
+  } else {
+    success = await setupJsonConfig(selectedClient, apiKey, mcpServerUrl);
+  }
+
+  if (success) {
+    console.log("  Setup complete! Restart your AI assistant to start using Niro.\n");
+    if (selectedClient !== "claude-code") {
+      console.log("  Tip: drop a `.niro-project` file at the repo root (single line");
+      console.log("  with the project_id) to pin that tree to a Niro project.");
+      console.log("  Without it, Niro runs in multi-project mode and discovers");
+      console.log("  projects via the list_projects tool.\n");
+    }
+  }
+}
+
+// Only run the interactive wizard when invoked directly (niro mcp install). When
+// required as a module, expose the skill installers so they can be (re)installed
+// on their own — without re-running the wizard, which would rewrite MCP config.
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(`Setup failed: ${err.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  writeManagedSkill,
+  addClaudeCodeSkill,
+  addClaudeCodeCliSkill,
+  addAgentsSkill,
+  addAgentsCliSkill,
+  // Shared with teardown.js so uninstall removes exactly what install wrote.
+  CLIENTS,
+  NIRO_MD_MARKER,
+  NIRO_MD_SECTIONS,
+  isNiroPostCompactHook,
+  isNiroUserPromptHook,
+  isNiroPreToolUseHook,
+  userHome,
+  // Exposed for content regression tests (e.g. the cross-project routing guidance).
+  NIRO_SKILL,
+  NIRO_CLI_SKILL,
+  // Exposed for tests: URL resolution replaced the install-time prompt.
+  resolveMcpServerUrl,
+  SAAS_URL,
+  // Exposed for tests: shell-injection boundary guard, shared by every CLI-registration path.
+  hasShellMetacharacters,
+  // Exposed for tests: Goose's hand-rolled YAML block (no YAML dependency — see its own doc comment).
+  buildGooseNiroBlock,
+  gooseConfigPath,
+  // Exposed for tests: exactly which clients are gated by hasShellMetacharacters (shell-based installers only).
+  CLI_SETUP,
+  // Exposed for tests: exercise the real YAML install path (duplicate-key avoidance, idempotency).
+  setupGoose,
+};