@niroai/niro 0.16.0 → 0.18.0

package/src/mcp/setup.js

@@ -21,7 +21,13 @@ const path = require("path");
 const readline = require("readline");
 const { execSync } = require("child_process");
 const config = require("../lib/config");
+const localMode = require("./localMode");
+const shellSearchHook = require("./shellSearchHook");
 const { formatPrompt } = require("../lib/prompt");
+const { choose } = require("../lib/choose");
+const color = require("../lib/color");
+/** Inside `niro start` these lines sit on its rail ("│  "), so they take the rail's indent. */
+const IND = process.env.NIRO_OUTPUT_PREFIX ? "  " : "    ";
 
 /** Cross-platform user home (~). */
 function userHome() {
@@ -35,6 +41,7 @@ function userHome() {
  * (which removes the section) can never drift apart.
  */
 const NIRO_MD_MARKER = "<!-- niro-mcp -->";
+const { USING_NIRO } = require("./usingNiro");
 
 /**
  * The exact niro sections appended to each markdown config file. These are the single source
@@ -73,10 +80,83 @@ const NIRO_WINDSURF_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP cod
  * 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_EXPLORE_FIRST_SENTENCE}\n${NIRO_IMPACT_BOTH_WAYS_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+/**
+ * One line telling an agent with a terminal that Niro's own pages are readable offline (`niro guide`, in both
+ * releases). Given to the agents that get only a rule file and can run commands: Cursor, Cline, Kiro, and the
+ * generic section (Gemini CLI, Copilot CLI, Factory, OpenCode). Without backticks, so the Cursor rule can carry it.
+ */
+const NIRO_GUIDE_SENTENCE = "For a Niro error message or a question about Niro itself, run niro guide --search <the message> in the terminal and answer from the page it names.";
+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_EXPLORE_FIRST_SENTENCE}\n${NIRO_IMPACT_BOTH_WAYS_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n${NIRO_GUIDE_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];
+/**
+ * The instruction text for a release without the cloud: drops the rules that name what only the
+ * cloud has, the mandatory find_reusable_code call (an engine offers it only after a --llm build)
+ * and the temporary-project rule (`niro new-temp-project` is a cloud command). Every tool it names
+ * must be one the engine serves (test/releaseToolNames.test.js): the cloud's resolve_fqn is the
+ * engine's resolve_name, and the Cursor rule's cloud-only routes (explain_code,
+ * trace_execution_path, find_known_issues, get_state_at_entry, and the comments about hidden
+ * tools) are left out.
+ */
+function localTextBeforeUsingNiro(text) {
+  return text
+    .split("resolve_fqn").join("resolve_name")
+    .replace(/\n<!-- [^\n]*\(hidden MCP tool\)[^\n]*-->/g, "")
+    .replace(/explain_code \(AI docs\) \| /g, "")
+    .replace(/ \| trace_execution_path \(A to B\)/g, "")
+    .replace(/\n- debug: find_known_issues \| get_state_at_entry/g, "")
+    .split(`\n${NIRO_MULTI_REPO_SENTENCE}`).join("")
+    .replace(/\n[^\n]*before writing\/adding any code: find_reusable_code[^\n]*/g, "")
+    .replace(/\n[ \t]*Before (?:adding\/writing|adding or writing|writing or adding|writing)(?: any)? new code,[^.]*find_reusable_code[^.]*\.[ \t]*(?=\n)/g, "")
+    .replace(/[ \t]*Before (?:adding\/writing|adding or writing|writing or adding|writing)(?: any)? new code,[^.]*find_reusable_code[^.]*\.[ \t]*/g, "")
+    .replace(/[ \t]*If find_reusable_code[^.]*\./g, "")
+    .replace(/(\S) +\n/g, "$1\n");
+}
+
+/**
+ * A release text with "Using Niro" in it (src/mcp/usingNiro.js): in place of the one guide sentence where a text has
+ * it (the generic section, the Cursor, Cline and Kiro rules), else at the end of a marked section (Claude Code's
+ * CLAUDE.md through localMode.js, Codex's AGENTS.md, Windsurf's global rules). A plain sentence passes unchanged.
+ */
+function withUsingNiro(text) {
+  if (text.includes(NIRO_GUIDE_SENTENCE)) return text.split(NIRO_GUIDE_SENTENCE).join(USING_NIRO);
+  if (text.startsWith(`\n${NIRO_MD_MARKER}\n`)) return `${text}${USING_NIRO}\n`;
+  return text;
+}
+
+/** The text a release without the cloud installs: the engine's tool names, no cloud-only rules, and Using Niro. */
+function localText(text) {
+  return withUsingNiro(localTextBeforeUsingNiro(text));
+}
+
+/** Pick the wording for this release. */
+function forRelease(text) {
+  return require("../lib/release").cloud ? text : localText(text);
+}
+
+const CLOUD_MD_SECTIONS = [NIRO_CLAUDE_MD_SECTION, NIRO_CODEX_MD_SECTION, NIRO_WINDSURF_MD_SECTION, NIRO_GENERIC_MD_SECTION];
+// Every wording, so teardown and a refresh remove a section whichever release wrote it: the cloud's, this release's,
+// and this release's before Using Niro was added (9255e24), which `niro upgrade` must replace exactly.
+const NIRO_MD_SECTIONS = [
+  ...CLOUD_MD_SECTIONS,
+  ...CLOUD_MD_SECTIONS.map(localText),
+  ...CLOUD_MD_SECTIONS.map(localTextBeforeUsingNiro),
+];
+/**
+ * Every section the uninstaller removes exactly: the cloud ones above (both wordings) and local mode's
+ * (src/mcp/localMode.js). Kept apart because the cloud sections all carry the cloud rules word for word,
+ * which the local one, naming the engine's tools, deliberately does not.
+ */
+/**
+ * The sections as the installer wrote them before NIRO_GUIDE_SENTENCE was added (3a585c8, the release before
+ * `niro guide`), so a refresh and the uninstaller remove those exactly too, instead of falling back to a
+ * bounded strip. Derived by taking the sentence out, and checked against the 3a585c8 texts in
+ * test/fixtures/md-sections-3a585c8.json.
+ */
+const BEFORE_GUIDE_MD_SECTIONS = NIRO_MD_SECTIONS
+  .map((section) => section.split(`${NIRO_GUIDE_SENTENCE}\n`).join(""))
+  .filter((section) => !NIRO_MD_SECTIONS.includes(section));
+const NIRO_ALL_MD_SECTIONS = [...NIRO_MD_SECTIONS, ...BEFORE_GUIDE_MD_SECTIONS, ...localMode.LOCAL_CLAUDE_MD_SECTIONS];
 
 /**
  * Upsert a niro markdown section into an agent-rules file's existing content. Returns {content, action}:
@@ -84,20 +164,20 @@ const NIRO_MD_SECTIONS = [NIRO_CLAUDE_MD_SECTION, NIRO_CODEX_MD_SECTION, NIRO_WI
  *   - 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.
+ * new temp-project sentence) because the installer skipped whenever the marker was present. The old block is
+ * removed as teardown removes it (removeMarkerSection): a known section text exactly, otherwise only the lines a
+ * known section holds, up to the first blank line, so every line a user wrote below it survives.
  */
 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" };
+  // The old section comes out the way the uninstaller takes it out: every section text this installer has
+  // written, exactly, and only for a text it does not know, the lines of the marker's block (up to the first blank
+  // line) that a known section holds. Until 2026-11-10 this cut everything up to the next "## " heading, so a
+  // user's note written under the section (no heading, a "#" or "###" heading) was deleted on every refresh
+  // (check of f1abc9f).
+  const { content } = require("./teardown").removeMarkerSection(existing, NIRO_MD_MARKER, NIRO_ALL_MD_SECTIONS);
+  return { content: content + section, action: "refreshed" };
 }
 
 /**
@@ -121,7 +201,10 @@ 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"));
+  // The local reminder (localMode.js) has neither `.niro-project` nor, with LLM documentation off, find_reusable_code:
+  // its generated opening is what names it.
+  return cmds.some((c) => c.includes(".niro-project") || c.includes("find_reusable_code") || c.includes("`niro` skill")
+    || c.includes(NIRO_USER_PROMPT_GENERATED_MARKERS[0]));
 }
 
 /**
@@ -149,6 +232,18 @@ function isNiroStopHook(h) {
   return cmds.some((c) => c.includes("mcp receipt --hook"));
 }
 
+/**
+ * True if `h` is niro's line-check Stop hook. Keyed on the exact subcommand it runs, so a developer's
+ * own Stop hook is never matched. Deliberately not isNiroStopHook, which finds the retired hook that
+ * printed the line itself so an install can delete it; this one is meant to stay.
+ */
+function isNiroLineCheckHook(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_LINE_CHECK_SUBCOMMAND));
+}
+
 /**
  * True if `h` is niro's PreToolUse explore-first reminder entry (matcher Grep|Glob|Read). Keyed on the
  * unique `niro-explore-` marker-file prefix so a foreign PreToolUse hook on the same matcher is never
@@ -174,6 +269,21 @@ function isNiroImpactHook(h) {
   return cmds.some((c) => c.includes("niro-impact-"));
 }
 
+/**
+ * The environment every assistant starts `niro mcp serve` with: the key when there is no `niro login` session, and the
+ * bridge's server address. With the cloud off (src/lib/release.js) it also carries NIRO_MCP_MODE=local, the setting
+ * Claude Code is registered with (setupClaudeCode), so every assistant's bridge answers from the engine on this
+ * machine. Without it, an assistant started with no login stopped at the bridge's credential check before the engine
+ * was started (13 of 14 clients, the checker's note 1 on fix/cli-small, 2026-11-06).
+ */
+function bridgeEnv(apiKey, mcpServerUrl) {
+  return {
+    ...(apiKey ? { NIRO_API_KEY: apiKey } : {}),
+    NIRO_MCP_SERVER_URL: mcpServerUrl,
+    ...(require("../lib/release").cloud ? {} : { NIRO_MCP_MODE: "local" }),
+  };
+}
+
 /**
  * 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:
@@ -183,7 +293,11 @@ function isNiroImpactHook(h) {
  * `label` is a short human name used in the log line (e.g. "niro skill").
  * Returns one of: "added" | "unchanged" | "updated".
  */
+/** Skills written or refreshed during this run, so the summary can say where they went. */
+const installedSkills = [];
+
 function writeManagedSkill(absPath, content, label) {
+  installedSkills.push({ label, dir: path.dirname(absPath) });
   if (!fs.existsSync(absPath)) {
     fs.mkdirSync(path.dirname(absPath), { recursive: true });
     fs.writeFileSync(absPath, content);
@@ -249,7 +363,7 @@ const CLIENTS = {
       type: "stdio",
       command: "niro",
       args: ["mcp", "serve"],
-      env: apiKey ? { NIRO_API_KEY: apiKey, NIRO_MCP_SERVER_URL: mcpServerUrl } : { NIRO_MCP_SERVER_URL: mcpServerUrl },
+      env: bridgeEnv(apiKey, mcpServerUrl),
     }),
   },
   "gemini-cli": {
@@ -277,9 +391,7 @@ const CLIENTS = {
       type: "local",
       command: ["niro", "mcp", "serve"],
       enabled: true,
-      environment: apiKey
-        ? { NIRO_API_KEY: apiKey, NIRO_MCP_SERVER_URL: mcpServerUrl }
-        : { NIRO_MCP_SERVER_URL: mcpServerUrl },
+      environment: bridgeEnv(apiKey, mcpServerUrl),
     }),
   },
   cline: {
@@ -300,7 +412,7 @@ const CLIENTS = {
     buildEntry: (apiKey, mcpServerUrl) => ({
       command: "niro",
       args: ["mcp", "serve"],
-      env: apiKey ? { NIRO_API_KEY: apiKey, NIRO_MCP_SERVER_URL: mcpServerUrl } : { NIRO_MCP_SERVER_URL: mcpServerUrl },
+      env: bridgeEnv(apiKey, mcpServerUrl),
       disabled: false,
       autoApprove: [],
     }),
@@ -312,7 +424,7 @@ const CLIENTS = {
     buildEntry: (apiKey, mcpServerUrl) => ({
       command: "niro",
       args: ["mcp", "serve"],
-      env: apiKey ? { NIRO_API_KEY: apiKey, NIRO_MCP_SERVER_URL: mcpServerUrl } : { NIRO_MCP_SERVER_URL: mcpServerUrl },
+      env: bridgeEnv(apiKey, mcpServerUrl),
       disabled: false,
       // Kiro's autoApprove supports a "*" wildcard for "all tools on this server" — safe here
       // because every niro tool is read-only.
@@ -334,7 +446,7 @@ const CLIENTS = {
     buildEntry: (apiKey, mcpServerUrl) => ({
       command: "niro",
       args: ["mcp", "serve"],
-      env: apiKey ? { NIRO_API_KEY: apiKey, NIRO_MCP_SERVER_URL: mcpServerUrl } : { NIRO_MCP_SERVER_URL: mcpServerUrl },
+      env: bridgeEnv(apiKey, mcpServerUrl),
     }),
   },
 };
@@ -556,13 +668,6 @@ function hasShellMetacharacters(value) {
   return /[\s;&|`$()<>"'\\]/.test(value || "");
 }
 
-function printHeader() {
-  console.log("");
-  console.log("    Niro MCP Server Setup");
-  console.log("    ---------------------");
-  console.log("");
-}
-
 /** How many clients to name before summarising the rest. */
 const CLIENTS_SHOWN = 5;
 
@@ -588,6 +693,22 @@ function runClientCommand(command) {
  * a question nearly everyone answers with the default. The full list is one flag away, and
  * anyone hunting for a client they cannot see is exactly the person who will use it.
  */
+/** The picker's last row: an MCP client not in CLIENTS. */
+const OTHER = "other";
+
+/** The stdio entry every JSON client gets (setupJsonConfig's default), to paste by hand. */
+function printOtherConfig(apiKey, mcpServerUrl) {
+  const env = bridgeEnv(apiKey, mcpServerUrl);
+  const entry = { mcpServers: { niro: { command: "niro", args: ["mcp", "serve"], env } } };
+  console.log(`${IND}Add this to your assistant's MCP settings, then restart it:`);
+  JSON.stringify(entry, null, 2).split("\n").forEach((l) => console.log(color.dim(`${IND}  ${l}`)));
+}
+
+/** "claude-code, cursor" or "claude-code cursor" → unique ids in the order typed. */
+function parseClients(input) {
+  return [...new Set(String(input || "").split(/[\s,]+/).filter(Boolean))];
+}
+
 function printClients({ all = false } = {}) {
   const entries = Object.entries(CLIENTS);
   const shown = all ? entries : entries.slice(0, CLIENTS_SHOWN);
@@ -615,10 +736,12 @@ function registeredServerUrl(getOutput) {
  *   "keep"    registered and already pointing at the wanted URL
  *   "replace" registered, but at another URL or in a shape this cannot read: remove, then add
  */
-function planClaudeRegistration({ existingOutput, wantedUrl }) {
+function planClaudeRegistration({ existingOutput, wantedUrl, mode = "cloud" }) {
   if (existingOutput == null) return "add";
+  const local = /NIRO_MCP_MODE=local\b/.test(String(existingOutput));
+  if (mode === "local") return local ? "keep" : "replace";
   const url = registeredServerUrl(existingOutput);
-  return url && url === wantedUrl ? "keep" : "replace";
+  return !local && url && url === wantedUrl ? "keep" : "replace";
 }
 
 /**
@@ -635,8 +758,12 @@ function planClaudeRegistration({ existingOutput, wantedUrl }) {
  * `deps` is for tests only: `get` returns the `claude mcp get niro` output or null, `run` runs a
  * client command; both default to the real thing.
  */
-async function setupClaudeCode(apiKey, mcpServerUrl, deps = {}) {
-  console.log("\n    Configuring Claude Code...\n");
+async function setupClaudeCode(apiKey, mcpServerUrl, deps = {}, mode = "cloud") {
+  // A release without the cloud (src/lib/release.js) sets Claude Code up for the engine on this machine: the bridge
+  // in local mode and the hooks that read niro-local's own list of indexed folders, not the cloud hooks that look
+  // for a `.niro-project` file and so never fire in a Niro Local folder (Niraj, 2026-11-06, Q5).
+  if (!require("../lib/release").cloud) mode = "local";
+  console.log(`\n    Configuring Claude Code${mode === "local" ? " for niro-local, the engine on this machine" : ""}...\n`);
   const run = deps.run || runClientCommand;
   const get = deps.get || (() => {
     try {
@@ -651,16 +778,25 @@ async function setupClaudeCode(apiKey, mcpServerUrl, deps = {}) {
     "--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}`);
+  if (mode === "local") {
+    // The same bridge, told to answer everything from the engine on this machine: initialize and the
+    // tool list as well as tool calls (src/mcp/server.js, localSend). No server URL and no key: nothing
+    // is asked of the cloud to answer, and the licence comes from the `niro login` session.
+    cmd.push("-e", "NIRO_MCP_MODE=local");
+  } else {
+    // 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");
 
-  const plan = planClaudeRegistration({ existingOutput: get(), wantedUrl: mcpServerUrl });
+  const plan = planClaudeRegistration({ existingOutput: get(), wantedUrl: mcpServerUrl, mode });
   if (plan === "keep") {
-    console.log(`    MCP server already registered in Claude Code at ${mcpServerUrl}. Keeping it.\n`);
+    console.log(mode === "local"
+      ? "    MCP server already registered in Claude Code for niro-local. Keeping it.\n"
+      : `    MCP server already registered in Claude Code at ${mcpServerUrl}. Keeping it.\n`);
   } else {
     if (plan === "replace") {
       try {
@@ -681,12 +817,37 @@ async function setupClaudeCode(apiKey, mcpServerUrl, deps = {}) {
     }
   }
 
+  if (mode === "local") {
+    addClaudeCodePostCompactHook(localMode.LOCAL_POST_COMPACT_COMMAND);
+    addClaudeCodeUserPromptHook(localMode.LOCAL_USER_PROMPT_COMMAND);
+    // Temporary projects are a cloud idea: niro-local follows the folder whatever branch it is on.
+    removeClaudeCodeTempProjectHook();
+    addClaudeCodeExploreHook(localMode.localHook(NIRO_EXPLORE_COMMAND));
+    shellSearchHook.addClaudeCodeShellSearchHook(localMode.localHook(shellSearchHook.NIRO_SHELL_SEARCH_COMMAND));
+    addClaudeCodeImpactHook(localMode.localHook(NIRO_IMPACT_COMMAND));
+    removeStaleNiroStopHook();
+    addClaudeCodeLineCheckHook();
+    addClaudeCodeMemory(localMode.LOCAL_CLAUDE_MD_SECTION);
+    // The two skills: local mode's own in a cloud release. With the cloud off, the release's own (src/mcp/localSkill.js):
+    // the tool skill naming the engine's tools, and the `niro-local` command skill, whose commands (`niro init`,
+    // `niro build`, `niro plan`) are the ones that release has (Niraj, 2026-11-06, Q5: our hooks, her skill text).
+    if (require("../lib/release").cloud) {
+      addClaudeCodeSkill(localMode.LOCAL_SKILL);
+      addClaudeCodeCliSkill(localMode.LOCAL_CLI_SKILL);
+    } else {
+      addClaudeCodeSkill();
+      addClaudeCodeCliSkill();
+    }
+    return true;
+  }
   addClaudeCodePostCompactHook();
   addClaudeCodeUserPromptHook();
   addClaudeCodePreToolUseHook();
   addClaudeCodeExploreHook();
+  shellSearchHook.addClaudeCodeShellSearchHook();
   addClaudeCodeImpactHook();
   removeStaleNiroStopHook();
+  addClaudeCodeLineCheckHook();
   addClaudeCodeMemory();
   addClaudeCodeSkill();
   addClaudeCodeCliSkill();
@@ -694,6 +855,31 @@ async function setupClaudeCode(apiKey, mcpServerUrl, deps = {}) {
   return true;
 }
 
+/**
+ * Take niro's temporary-project hook out of ~/.claude/settings.json (local mode, where it does not
+ * apply). Only entries isNiroPreToolUseHook recognises are touched; a missing or unreadable file is
+ * left as it is.
+ */
+function removeClaudeCodeTempProjectHook() {
+  const settingsPath = path.join(process.env.HOME || "", ".claude", "settings.json");
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+  } catch {
+    return;
+  }
+  const hooks = settings && settings.hooks && settings.hooks.PreToolUse;
+  if (!Array.isArray(hooks) || !hooks.some(isNiroPreToolUseHook)) return;
+  settings.hooks.PreToolUse = hooks.filter((h) => !isNiroPreToolUseHook(h));
+  if (settings.hooks.PreToolUse.length === 0) delete settings.hooks.PreToolUse;
+  try {
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    console.log("    PreToolUse temporary project hook removed (it does not apply to niro-local).\n");
+  } catch (err) {
+    console.warn(`    Could not write ~/.claude/settings.json: ${err.message}`);
+  }
+}
+
 /**
  * Adds a PostCompact hook to ~/.claude/settings.json so Claude is reminded
  * about Niro tools after context compaction (the point where tool awareness
@@ -742,16 +928,15 @@ const NIRO_POST_COMPACT_COMMAND =
   + "Keep that list and verify those flows after the edit; the graph lags your edit, so do not re-query it to verify. "
   + "A log line or comment needs no map.'";
 
-function addClaudeCodePostCompactHook() {
+function addClaudeCodePostCompactHook(hookCommand = NIRO_POST_COMPACT_COMMAND) {
   // Guard the invariant that keeps upgrade-in-place working: if the reminder is ever reworded so it
   // no longer starts with the generated prefix, every install would append a fresh entry instead of
   // replacing the old one. Fail loudly at the boundary rather than quietly stacking hooks.
-  if (!NIRO_POST_COMPACT_COMMAND.startsWith(NIRO_POST_COMPACT_PREFIX)) {
-    throw new Error("NIRO_POST_COMPACT_COMMAND must start with NIRO_POST_COMPACT_PREFIX, or upgrade-in-place breaks");
+  if (!hookCommand.startsWith(NIRO_POST_COMPACT_PREFIX)) {
+    throw new Error("the PostCompact command must start with NIRO_POST_COMPACT_PREFIX, or upgrade-in-place breaks");
   }
 
   const settingsPath = path.join(process.env.HOME || "", ".claude", "settings.json");
-  const hookCommand = NIRO_POST_COMPACT_COMMAND;
 
   let settings = {};
   try {
@@ -801,9 +986,8 @@ function addClaudeCodePostCompactHook() {
  * Appends a Niro reminder section to ~/.claude/CLAUDE.md so Claude is aware
  * of Niro tools across all projects and sessions.
  */
-function addClaudeCodeMemory() {
+function addClaudeCodeMemory(section = forRelease(NIRO_CLAUDE_MD_SECTION)) {
   const claudeMdPath = path.join(process.env.HOME || "", ".claude", "CLAUDE.md");
-  const section = NIRO_CLAUDE_MD_SECTION;
 
   let existing = "";
   try {
@@ -900,16 +1084,15 @@ function isNiroGeneratedUserPromptHook(h) {
   );
 }
 
-function addClaudeCodeUserPromptHook() {
+function addClaudeCodeUserPromptHook(hookCommand = NIRO_USER_PROMPT_COMMAND) {
   // Guard the invariant that keeps upgrade-in-place working: if the reminder is reworded so it no longer
   // carries a known generated marker, every install would append a fresh entry instead of replacing the
   // old one. Fail loudly at the boundary rather than quietly stacking hooks in the user's settings.
-  if (!NIRO_USER_PROMPT_GENERATED_MARKERS.some((m) => NIRO_USER_PROMPT_COMMAND.includes(m))) {
-    throw new Error("NIRO_USER_PROMPT_COMMAND must contain a known generated marker, or upgrade-in-place breaks");
+  if (!NIRO_USER_PROMPT_GENERATED_MARKERS.some((m) => hookCommand.includes(m))) {
+    throw new Error("the UserPromptSubmit command must contain a known generated marker, or upgrade-in-place breaks");
   }
   const settingsPath = path.join(process.env.HOME || "", ".claude", "settings.json");
-  const hookCommand = NIRO_USER_PROMPT_COMMAND;
-
+  
   let settings = {};
   try {
     if (fs.existsSync(settingsPath)) {
@@ -991,6 +1174,51 @@ const NIRO_PRETOOL_COMMAND = [
   `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('; ');
 
+/** The subcommand the line-check hook runs, which is also how the installer recognises its own. */
+const NIRO_LINE_CHECK_SUBCOMMAND = "mcp line-check";
+/**
+ * Guarded, because this one fires on every stop in every session, Niro or not. A person who removed the
+ * package without `niro mcp uninstall` would otherwise see an error at the end of every turn.
+ */
+const NIRO_LINE_CHECK_COMMAND = `command -v niro >/dev/null 2>&1 && niro ${NIRO_LINE_CHECK_SUBCOMMAND} || true`;
+/** Seconds. Claude Code's default for a command hook is 600, far too long to hold up a stop. */
+const NIRO_LINE_CHECK_TIMEOUT = 5;
+
+/**
+ * Adds the Stop hook that asks the assistant, once, for an end-of-task line it forgot
+ * (src/mcp/lineCheck.js). Same file, same shape, and the same care as the other hooks: an unreadable
+ * settings file is left alone, and anything not recognised by isNiroLineCheckHook is never touched.
+ */
+function addClaudeCodeLineCheckHook() {
+  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 (err) {
+    console.warn(`    Could not read ~/.claude/settings.json, so the end-of-task check was not added: ${err.message}`);
+    return;
+  }
+  const entry = {
+    matcher: "",
+    hooks: [{ type: "command", command: NIRO_LINE_CHECK_COMMAND, timeout: NIRO_LINE_CHECK_TIMEOUT }],
+  };
+  if (!settings.hooks) settings.hooks = {};
+  const stop = Array.isArray(settings.hooks.Stop) ? settings.hooks.Stop : [];
+  const current = stop.filter(isNiroLineCheckHook);
+  if (current.length === 1 && JSON.stringify(current[0]) === JSON.stringify(entry)) {
+    console.log("    End-of-task check already up to date. Skipping.\n");
+    return;
+  }
+  settings.hooks.Stop = [...stop.filter((h) => !isNiroLineCheckHook(h)), entry];
+  try {
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    console.log("    End-of-task check added in ~/.claude/settings.json: it asks for the Niro line when it was forgotten.\n");
+  } catch (err) {
+    console.warn(`    Could not write ~/.claude/settings.json: ${err.message}`);
+  }
+}
+
 /**
  * Removes a Stop hook left behind by an earlier version of this installer.
  *
@@ -1136,7 +1364,7 @@ const NIRO_EXPLORE_COMMAND = [
  * upgrades a stale niro entry in place, never touches a foreign PreToolUse hook on the same matcher
  * (matched by the niro-explore- marker via isNiroExploreHook).
  */
-function addClaudeCodeExploreHook() {
+function addClaudeCodeExploreHook(hookCommand = NIRO_EXPLORE_COMMAND) {
   const settingsPath = path.join(process.env.HOME || "", ".claude", "settings.json");
   let settings = {};
   try {
@@ -1148,9 +1376,9 @@ function addClaudeCodeExploreHook() {
   if (!settings.hooks) settings.hooks = {};
   if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
 
-  const entry = { matcher: "Grep|Glob|Read", hooks: [{ type: "command", command: NIRO_EXPLORE_COMMAND }] };
+  const entry = { matcher: "Grep|Glob|Read", hooks: [{ type: "command", command: hookCommand }] };
   const alreadyCurrent = settings.hooks.PreToolUse.some(
-    (h) => Array.isArray(h.hooks) && h.hooks.some((i) => i && i.command === NIRO_EXPLORE_COMMAND),
+    (h) => Array.isArray(h.hooks) && h.hooks.some((i) => i && i.command === hookCommand),
   );
   if (alreadyCurrent) {
     console.log("    PreToolUse explore-first hook already up to date. Skipping.\n");
@@ -1293,7 +1521,7 @@ const NIRO_IMPACT_COMMAND = [
  * stale niro entry in place, never touches a foreign PreToolUse hook on the same matcher nor niro's own
  * temp-project hook (matched by the niro-impact- token via isNiroImpactHook).
  */
-function addClaudeCodeImpactHook() {
+function addClaudeCodeImpactHook(hookCommand = NIRO_IMPACT_COMMAND) {
   const settingsPath = path.join(process.env.HOME || "", ".claude", "settings.json");
   let settings = {};
   try {
@@ -1305,9 +1533,9 @@ function addClaudeCodeImpactHook() {
   if (!settings.hooks) settings.hooks = {};
   if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
 
-  const entry = { matcher: "Edit|Write", hooks: [{ type: "command", command: NIRO_IMPACT_COMMAND }] };
+  const entry = { matcher: "Edit|Write", hooks: [{ type: "command", command: hookCommand }] };
   const alreadyCurrent = settings.hooks.PreToolUse.some(
-    (h) => Array.isArray(h.hooks) && h.hooks.some((i) => i && i.command === NIRO_IMPACT_COMMAND),
+    (h) => Array.isArray(h.hooks) && h.hooks.some((i) => i && i.command === hookCommand),
   );
   if (alreadyCurrent) {
     console.log("    PreToolUse impact-gate hook already up to date. Skipping.\n");
@@ -1570,6 +1798,8 @@ You manage a user's Niro projects by running the \`niro\` CLI via the shell (Bas
 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.
+For a Niro error message or a how-to question, run \`niro guide --search <the message>\` first and
+answer from the page it names (\`niro guide <page>\` prints it; the pages ship with niro, offline).
 
 ## Golden rules (apply to EVERY task)
 
@@ -1737,10 +1967,10 @@ 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() {
+function addClaudeCodeSkill(content = toolSkill()) {
   const skillPath = path.join(process.env.HOME || "", ".claude", "skills", "niro-skill", "SKILL.md");
   try {
-    const result = writeManagedSkill(skillPath, NIRO_SKILL, "niro skill");
+    const result = writeManagedSkill(skillPath, content, "niro skill");
     if (result === "added" || result === "updated") {
     }
     console.log("");
@@ -1749,15 +1979,47 @@ function addClaudeCodeSkill() {
   }
 }
 
+/**
+ * Which CLI skill this release installs: the cloud `niro-cli` playbook, or, with the cloud off
+ * (src/lib/release.js), the `niro-local` one, whose commands are the ones this release has.
+ */
+function cliSkill(cloudLabel) {
+  if (require("../lib/release").cloud) return { dir: "niro-cli", body: NIRO_CLI_SKILL, label: cloudLabel };
+  return { dir: "niro-local", body: require("./localSkill").NIRO_LOCAL_SKILL, label: cloudLabel.replace("niro-cli", "niro-local") };
+}
+
+/** The tool-usage skill: the cloud's, or with the cloud off one naming only the local engine's tools. */
+function toolSkill() {
+  return require("../lib/release").cloud ? NIRO_SKILL : require("./localSkill").NIRO_SKILL_LOCAL;
+}
+
+/** Take out a `niro-cli` skill an earlier install wrote, so it does not point at hidden commands. */
+function dropCloudCliSkill(skillsDir) {
+  const file = path.join(skillsDir, "niro-cli", "SKILL.md");
+  try {
+    if (!fs.existsSync(file)) return;
+    fs.unlinkSync(file);
+    try { fs.rmdirSync(path.dirname(file)); } catch { /* not empty: something else lives there */ }
+    console.log(`    niro-cli skill removed (this release uses niro-local): ${file}`);
+  } catch (err) {
+    console.warn(`    Could not remove ${file}: ${err.message}`);
+  }
+}
+
 /**
  * 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");
+function addClaudeCodeCliSkill(content) {
+  // No content: this release's own CLI skill (the cloud `niro-cli` one, or `niro-local` with the cloud off). Content:
+  // local mode in a cloud release, which writes its own text to the `niro-cli` skill file.
+  const { dir, body, label } =
+    content === undefined ? cliSkill("niro-cli skill") : { dir: "niro-cli", body: content, label: "niro-cli skill" };
+  const skillPath = path.join(process.env.HOME || "", ".claude", "skills", dir, "SKILL.md");
+  if (dir !== "niro-cli") dropCloudCliSkill(path.join(process.env.HOME || "", ".claude", "skills"));
   try {
-    const result = writeManagedSkill(skillPath, NIRO_CLI_SKILL, "niro-cli skill");
+    const result = writeManagedSkill(skillPath, body, label);
     if (result === "added" || result === "updated") {
     }
     console.log("");
@@ -1823,24 +2085,59 @@ Routing (most specific wins):
 - data & events: get_data_resource_usage | get_event_producers_and_handlers
 - search / status: code_grep | get_index_status
 
+${NIRO_GUIDE_SENTENCE}
+
 Onboarding / indexing a repo is done in the terminal with the niro CLI (niro init), not
 via MCP tools.
 `;
 
+/** How every version of NIRO_CURSOR_RULE has begun and ended (all six in git history, 2026-11-06). */
+const CURSOR_RULE_START = "---\ndescription: Niro code-intelligence";
+const CURSOR_RULE_END = "\nvia MCP tools.\n";
+
+/**
+ * A Cursor rule file with Niro's part replaced by `fresh`, and every line the user added before or after it kept.
+ * Niro's part is the span from its front matter to its last line ("via MCP tools."), which every version written so
+ * far shares. Returns {content, action}: "unchanged" when it already says `fresh`, "refreshed" when Niro's part was
+ * replaced, and "foreign" for a file Niro did not write (no such span), which is left alone. A line typed INSIDE
+ * Niro's part goes with it, as it does for the markdown sections (upsertNiroMarkerSection).
+ */
+function refreshCursorRule(existing, fresh) {
+  const start = existing.indexOf(CURSOR_RULE_START);
+  const endAt = start === -1 ? -1 : existing.indexOf(CURSOR_RULE_END, start);
+  const ending = endAt === -1 && start !== -1 && existing.endsWith(CURSOR_RULE_END.trimEnd()) ? existing.length : -1;
+  if (start === -1 || (endAt === -1 && ending === -1)) return { content: existing, action: "foreign" };
+  const end = endAt !== -1 ? endAt + CURSOR_RULE_END.length : ending;
+  const content = existing.slice(0, start) + fresh + existing.slice(end);
+  return { content, action: content === existing ? "unchanged" : "refreshed" };
+}
+
 /**
  * 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.
+ * wizard is run from. A rule an earlier install wrote is refreshed, keeping the user's own lines
+ * (refreshCursorRule): until 2026-11-06 an existing file was skipped, so a rule written by a cloud
+ * install kept naming resolve_fqn and four cloud-only tools after an upgrade to this release
+ * (the checker's note 3 on fix/cli-small).
  */
 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;
-  }
+  const fresh = forRelease(NIRO_CURSOR_RULE);
   try {
+    if (fs.existsSync(rulePath)) {
+      const { content, action } = refreshCursorRule(fs.readFileSync(rulePath, "utf-8"), fresh);
+      if (action === "foreign") {
+        console.log("    A Cursor rule Niro did not write is at .cursor/rules/niro.mdc. Leaving it as it is.\n");
+      } else if (action === "unchanged") {
+        console.log("    Cursor rule already up to date. Skipping (.cursor/rules/niro.mdc).\n");
+      } else {
+        fs.writeFileSync(rulePath, content);
+        console.log(`    Cursor rule refreshed, your own lines kept: ${rulePath}\n`);
+      }
+      return;
+    }
     fs.mkdirSync(path.dirname(rulePath), { recursive: true });
-    fs.writeFileSync(rulePath, NIRO_CURSOR_RULE);
+    fs.writeFileSync(rulePath, fresh);
     console.log(`    Cursor rule added: ${rulePath}`);
     console.log("        • Project-scoped. For other repos, copy it or re-run setup there.\n");
   } catch (err) {
@@ -1859,9 +2156,8 @@ async function setupCodex(apiKey, mcpServerUrl) {
     "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}`);
+  for (const [key, value] of Object.entries(bridgeEnv(apiKey, mcpServerUrl))) cmd.push("--env", `${key}=${value}`);
   cmd.push("--", "niro", "mcp", "serve");
 
   try {
@@ -2108,7 +2404,7 @@ function locateCodexNiroTable(cfgPath) {
  */
 function addCodexMemory() {
   const agentsPath = path.join(process.env.HOME || "", ".codex", "AGENTS.md");
-  const section = NIRO_CODEX_MD_SECTION;
+  const section = forRelease(NIRO_CODEX_MD_SECTION);
 
   let existing = "";
   try {
@@ -2146,7 +2442,7 @@ function addCodexMemory() {
 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");
+    const result = writeManagedSkill(skillPath, toolSkill(), "Shared niro-skill");
     if (result === "added" || result === "updated") {
       console.log("        • Read by Codex and Windsurf (cross-agent skills location).");
     }
@@ -2162,9 +2458,11 @@ function addAgentsSkill() {
  * 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");
+  const { dir, body, label } = cliSkill("Shared niro-cli skill");
+  const skillPath = path.join(process.env.HOME || "", ".agents", "skills", dir, "SKILL.md");
+  if (dir !== "niro-cli") dropCloudCliSkill(path.join(process.env.HOME || "", ".agents", "skills"));
   try {
-    const result = writeManagedSkill(skillPath, NIRO_CLI_SKILL, "Shared niro-cli skill");
+    const result = writeManagedSkill(skillPath, body, label);
     if (result === "added" || result === "updated") {
       console.log("        • Read by Codex and Windsurf (cross-agent skills location).");
     }
@@ -2181,7 +2479,7 @@ function addAgentsCliSkill() {
  */
 function addWindsurfGlobalRule() {
   const rulePath = path.join(process.env.HOME || "", ".codeium", "windsurf", "memories", "global_rules.md");
-  const section = NIRO_WINDSURF_MD_SECTION;
+  const section = forRelease(NIRO_WINDSURF_MD_SECTION);
 
   let existing = "";
   try {
@@ -2210,7 +2508,7 @@ function addWindsurfGlobalRule() {
  * 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) {
+function appendMarkerSectionToFile(absPath, label, section = forRelease(NIRO_GENERIC_MD_SECTION)) {
   let existing = "";
   try {
     if (fs.existsSync(absPath)) existing = fs.readFileSync(absPath, "utf-8");
@@ -2275,6 +2573,8 @@ The graph updates only after your edit is synced and rebuilt, so do not re-query
 change that cannot alter behaviour at all (a log line, a comment, formatting) needs no map: say so
 in one sentence.
 
+${NIRO_GUIDE_SENTENCE}
+
 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.
 `;
@@ -2288,7 +2588,7 @@ 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");
+    const result = writeManagedSkill(rulePath, forRelease(NIRO_CLINE_RULE), "Cline rule");
     if (result === "added" || result === "updated") {
       console.log("        • Global: applies across all your repos in Cline.");
     }
@@ -2331,6 +2631,8 @@ The graph updates only after your edit is synced and rebuilt, so do not re-query
 change that cannot alter behaviour at all (a log line, a comment, formatting) needs no map: say so
 in one sentence.
 
+${NIRO_GUIDE_SENTENCE}
+
 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.
 `;
@@ -2338,7 +2640,7 @@ 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");
+    const result = writeManagedSkill(rulePath, forRelease(NIRO_KIRO_STEERING), "Kiro steering file");
     if (result === "added" || result === "updated") {
       console.log("        • Global: applies across all your repos in Kiro.");
     }
@@ -2356,8 +2658,7 @@ 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}`);
+  for (const [key, value] of Object.entries(bridgeEnv(apiKey, mcpServerUrl))) cmd.push("-e", `${key}=${value}`);
   cmd.push("niro", "niro", "mcp", "serve");
 
   try {
@@ -2382,8 +2683,7 @@ 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}`);
+  for (const [key, value] of Object.entries(bridgeEnv(apiKey, mcpServerUrl))) cmd.push("--env", `${key}=${value}`);
   cmd.push("--", "niro", "mcp", "serve");
 
   try {
@@ -2410,8 +2710,7 @@ 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}`);
+  for (const [key, value] of Object.entries(bridgeEnv(apiKey, mcpServerUrl))) cmd.push("--env", `${key}=${value}`);
 
   try {
     execSync(cmd.join(" "), { stdio: "inherit" });
@@ -2443,8 +2742,9 @@ 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}"`);
+  const { NIRO_API_KEY: key, ...rest } = bridgeEnv(apiKey, mcpServerUrl);
+  const envs = ["    envs:", ...Object.entries(rest).map(([name, value]) => `      ${name}: "${value}"`)];
+  if (key) envs.push(`      NIRO_API_KEY: "${key}"`);
   return [
     "  niro:",
     "    name: niro",
@@ -2572,9 +2872,7 @@ async function setupJsonConfig(clientId, apiKey, mcpServerUrl) {
         // 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 },
+        env: bridgeEnv(apiKey, mcpServerUrl),
       };
   // Cursor honours explicit stdio transports; harmless for docs / newer Cursor builds.
   if (clientId === "cursor") {
@@ -2653,15 +2951,58 @@ async function main() {
     output: process.stdout,
   });
 
-  printHeader();
-
+  // Cloud or this machine, in a release WITH the cloud. `--local` / `--cloud` choose; otherwise the last install's
+  // choice holds, which is what keeps `niro upgrade` (it re-runs this with only --client) from flipping it back.
+  // The saved mode is Claude Code's alone, since local mode configures no other client yet: setting up
+  // another client neither reads nor changes it (verifier, 2026-11-02: `--cloud` for Cursor used to
+  // save cloud, and the next `niro upgrade` put Claude Code back on the cloud).
+  // A release without the cloud (src/lib/release.js) has no choice to make: Claude Code is always set up for the
+  // engine on this machine (setupClaudeCode), and every assistant goes through the picker below.
+  if (require("../lib/release").cloud) {
+    const asked = localMode.modeFromArgs(args);
+    const forClaude = !clientArg || clientArg === "claude-code";
+    const mode = forClaude ? localMode.chooseMode(args, config.load().mcpMode) : asked || "cloud";
+    if (mode === "local") {
+      rl.close();
+      if (!forClaude) {
+        console.error(`\n    Local mode configures Claude Code only, so far; ${clientArg} is not supported yet.`);
+        console.error(`    Leave out --local to set ${clientArg} up for the cloud; Claude Code stays as it is.\n`);
+        process.exit(1);
+      }
+      if (process.argv.includes("--list")) {
+        console.log("\n    Local mode configures Claude Code only, so far.\n");
+        return;
+      }
+      if (!hasCliToken()) {
+        console.log("\n    You are not signed in. A development build of niro-local answers without it. A released");
+        console.log("    one needs a licence, and so do the journal and audit uploads: run `niro login`.\n");
+      }
+      const done = await setupClaudeCode(null, null, {}, "local");
+      if (done) {
+        config.save({ mcpMode: "local" });
+        // One step: `init` adds the folder and builds it (fix/init-builds). This branch runs only in a release WITH the
+        // cloud, where `niro init` is the cloud's onboarding and local mode sits next to a niro-local the person runs
+        // themselves (the same texts as src/mcp/localMode.js with CLOUD_RELEASE), so the engine's own command is the
+        // one that works. A release without the cloud never reaches this: it has no mode to choose (see above).
+        console.log("    The niro tools now answer from niro-local on this machine. Index a folder by running");
+        console.log("    `niro-local init --project <name>` in it (it adds the folder and builds its graph).");
+        console.log("    Back to the cloud: `niro mcp install --cloud`. Remove everything: `niro mcp uninstall`.");
+        console.log("    Setup complete! Restart your AI assistant to start using Niro.\n");
+      }
+      return;
+    }
+    if (asked === "cloud" && forClaude) config.save({ mcpMode: "cloud" });
+  }
   // 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, so no API key needed.");
-    console.log("    The MCP server will authenticate with your CLI token from ~/.niro/credentials.json.\n");
-  } else {
+  // Without the cloud there is no API key to paste: `niro login`'s browser flow (not `niro start`, which skips it for a saved key).
+  if (!hasCliToken() && !require("../lib/release").cloud) {
+    console.error(`\nNot signed in. Run ${require("../lib/color").cyan("niro login")}, approve in your browser, then try again.\n`);
+    rl.close();
+    process.exit(1);
+  }
+  if (!hasCliToken()) {
     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");
@@ -2672,14 +3013,7 @@ async function main() {
   }
 
   // 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("");
-  }
+  const { url: mcpServerUrl, explicit } = resolveMcpServerUrl(urlArg);
 
   // 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
@@ -2701,16 +3035,37 @@ async function main() {
     return;
   }
 
-  // Select client
-  let selectedClient = clientArg;
-  if (!selectedClient) {
-    console.log("");
-    printClients();
-    selectedClient = await ask(rl, "    Which client to configure?", "claude-code");
+  // Select clients: one or more, comma- or space-separated.
+  let selectedClients;
+  if (clientArg) {
+    selectedClients = parseClients(clientArg);
+  } else {
+    // readline would echo the arrow keys the picker reads, so it lets go of stdin first.
+    rl.close();
+    console.log(`\n${IND}Which AI assistants should use Niro?`);
+    selectedClients = await choose({
+      prefix: `${require("../lib/nestedOutput").currentPad()}${IND}`,
+      items: [...Object.entries(CLIENTS).map(([value, c]) => ({ value, label: c.name })), { value: OTHER, label: "Other (print the config)" }],
+      multi: true,
+      initial: ["claude-code"],
+      echo: false,
+    });
+    // The picker erased itself; the question goes too. The "Installed" block below names
+    // what was picked.
+    if (process.stdout.isTTY) process.stdout.write("\x1b[1A\r\x1b[2K");
+  }
+  // "Other": any MCP client this list does not know, so print the entry to paste and write nothing.
+  if (selectedClients.includes(OTHER)) {
+    selectedClients = selectedClients.filter((id) => id !== OTHER);
+    printOtherConfig(apiKey, mcpServerUrl);
+    if (!selectedClients.length) {
+      rl.close();
+      return;
+    }
   }
-
-  if (!CLIENTS[selectedClient]) {
-    console.error(`\n    Unknown client: ${selectedClient}`);
+  const unknown = selectedClients.filter((id) => !CLIENTS[id]);
+  if (!selectedClients.length || unknown.length) {
+    console.error(`\n    Unknown client: ${unknown.join(", ") || "(none given)"}`);
     printClients();
     rl.close();
     process.exit(1);
@@ -2724,7 +3079,7 @@ async function main() {
   // 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 (selectedClients.some((id) => CLI_SETUP[id])) {
     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");
@@ -2738,34 +3093,53 @@ async function main() {
   }
   // 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) {
-    // One line about what all of that was for, instead of a paragraph under each item.
-    console.log("    Those hooks and skills are what remind your assistant to use Niro, and let");
-    console.log("    you drive the CLI from chat. `niro mcp uninstall` removes all of them.");
-    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");
+  // Each installer reports every file it touches; that detail is muted here and each
+  // client gets one line. Errors (console.error) still come through.
+  let success = true;
+  const results = [];
+  for (const selectedClient of selectedClients) {
+    const log = console.log;
+    console.log = () => {};
+    installedSkills.length = 0;
+    let ok;
+    try {
+      if (CLI_SETUP[selectedClient]) {
+        ok = await CLI_SETUP[selectedClient](apiKey, mcpServerUrl);
+      } else if (selectedClient === "goose") {
+        ok = await setupGoose(apiKey, mcpServerUrl);
+      } else {
+        ok = await setupJsonConfig(selectedClient, apiKey, mcpServerUrl);
+      }
+    } finally {
+      console.log = log;
+    }
+    results.push({ name: CLIENTS[selectedClient].name, ok: !!ok, dirs: installedSkills.map((k) => k.dir) });
+    success = success && !!ok;
+  }
+
+  // One summary, like `npx skills`: what was installed, then where, per assistant.
+  const installed = results.filter((r) => r.ok);
+  if (installed.length) {
+    console.log(`${IND}${color.bold(`Installed "niro" v${require("../../package.json").version}`)}`);
+    const width = Math.max(...installed.map((r) => r.name.length));
+    for (const r of installed) {
+      const where = r.dirs.length ? r.dirs : ["connected"];
+      where.forEach((d, i) => console.log(color.dim(`${IND}  ${(i ? "" : r.name).padEnd(width)} → ${d}`)));
     }
   }
+  for (const r of results.filter((x) => !x.ok)) console.log(`${IND}${color.red("✗")} ${r.name} could not be set up`);
+  // None set up: say so in the exit code, so `niro start` does not go on to call the assistant connected.
+  if (results.length && !installed.length) process.exitCode = 1;
+
+  // Inside `niro start` the step's closing line says this instead.
+  if (success && !process.env.NIRO_OUTPUT_PREFIX) console.log("\n    Restart your AI assistant to start using Niro.\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) => {
+  require("../lib/nestedOutput").withPrefix(process.env.NIRO_OUTPUT_PREFIX || "", main).catch((err) => {
     console.error(`Setup failed: ${err.message}`);
     process.exit(1);
   });
@@ -2777,6 +3151,12 @@ module.exports = {
   // resolver would drift the first time that order changed, and the two would then disagree
   // about which backend a machine is pointed at.
   resolveMcpServerUrl,
+  // Exported so `niro upgrade` warns exactly when this installer would refuse (or ask for a key):
+  // a second "is this machine signed in?" rule drifted from this one and stayed silent after
+  // `niro login --api-key`, which saves a key but no cli token.
+  hasCliToken,
+  parseClients,
+  printOtherConfig,
   writeManagedSkill,
   addClaudeCodeSkill,
   addClaudeCodeCliSkill,
@@ -2788,6 +3168,9 @@ module.exports = {
   gooseConfigPath,
   NIRO_MD_MARKER,
   NIRO_MD_SECTIONS,
+  localText,
+  localTextBeforeUsingNiro,
+  NIRO_ALL_MD_SECTIONS,
   isNiroPostCompactHook,
   isNiroUserPromptHook,
   isNiroPreToolUseHook,
@@ -2798,6 +3181,9 @@ module.exports = {
   planClaudeRegistration,
   registeredServerUrl,
   isNiroStopHook,
+  isNiroLineCheckHook,
+  addClaudeCodeLineCheckHook,
+  NIRO_LINE_CHECK_COMMAND,
   clearCodexPerToolApprovals,
   hardenCodexServerConfig,
   userHome,
@@ -2821,6 +3207,8 @@ module.exports = {
   NIRO_EXPLORE_FIRST_SENTENCE,
   NIRO_IMPACT_BOTH_WAYS_SENTENCE,
   NIRO_CURSOR_RULE,
+  refreshCursorRule,
+  bridgeEnv,
   NIRO_CLINE_RULE,
   NIRO_KIRO_STEERING,
   upsertNiroMarkerSection,