@niroai/niro 0.17.0 → 1.0.0

package/src/mcp/teardown.js

@@ -11,7 +11,6 @@
  *   - the niro section in markdown config (CLAUDE.md / AGENTS.md / Windsurf rules)
  *   - the generated skills (~/.claude/skills, the shared ~/.agents/skills)
  *   - Cursor's "niro:*" allowlist entry and project rule
- *   - (with --all) the mcpServerUrl fallback in ~/.niro/config.json
  *
  * It deliberately LEAVES ~/.niro/credentials.json (your `niro login` session) alone —
  * use `niro logout` for that — and never deletes a user's own CLAUDE.md/AGENTS.md, only
@@ -33,11 +32,14 @@ const path = require("path");
 const readline = require("readline");
 const { execSync } = require("child_process");
 const { formatPrompt } = require("../lib/prompt");
+const { choose } = require("../lib/choose");
+const color = require("../lib/color");
 const {
   CLIENTS,
   NIRO_MD_MARKER,
-  NIRO_MD_SECTIONS,
+  NIRO_ALL_MD_SECTIONS,
   isNiroStopHook,
+  isNiroLineCheckHook,
   isNiroPostCompactHook,
   isNiroUserPromptHook,
   isNiroPreToolUseHook,
@@ -45,6 +47,7 @@ const {
   isNiroImpactHook,
   userHome,
 } = require("./setup");
+const { isNiroShellSearchHook } = require("./shellSearchHook");
 
 // ─── pure helpers (unit-tested — no fs, no $HOME) ────────────────────────────
 
@@ -55,14 +58,22 @@ const {
  * Primary path: delete the EXACT section text install wrote. Because we match the whole known
  * block (not "marker → next heading / EOF"), a user's own notes added BELOW the block survive,
  * the file is restored byte-for-byte, duplicate blocks are all removed, and a differently-worded
- * example of the marker elsewhere is untouched. Both LF and CRLF copies are tried.
+ * example of the marker elsewhere is untouched. Both LF and CRLF copies are tried. The text cut out
+ * starts and ends with a line break, so when the user's text touches it on both sides one line
+ * break is put back; without it the line above and the line below were joined into one (check of
+ * feat/niro-guide, 2026-11-10: 8 of 91 user lines on upgrade, 10 on uninstall).
  *
  * Fallback (the section text drifted — older install version or a hand-edit): a BOUNDED removal
- * that strips the marker line and the "## Niro MCP" block it heads but stops at the first blank
- * line / next heading / EOF, and refuses to touch a marker sitting inside a ``` code fence — so
- * trailing user content is never swallowed. Returns { content, removed }.
+ * that strips the marker line and, in the lines under it up to a blank line or EOF, only lines some
+ * known section holds as a whole line. It refuses to touch a marker sitting inside a ``` code fence.
+ * Returns { content, removed }.
+ *
+ * The choice, where niro cannot tell where an unknown section ends: keep the line. A line no known
+ * section holds is never deleted, so a hand-edited Niro line, or one an older release worded
+ * differently, may stay behind; that is safer than deleting the user's own line glued below
+ * (Niraj, 2026-11-10: "sure"). Before this, the whole block went, the user's glued line with it.
  */
-function removeMarkerSection(content, marker, knownSections = NIRO_MD_SECTIONS) {
+function removeMarkerSection(content, marker, knownSections = NIRO_ALL_MD_SECTIONS) {
   if (typeof content !== "string" || !content.includes(marker)) {
     return { content, removed: false };
   }
@@ -72,9 +83,11 @@ function removeMarkerSection(content, marker, knownSections = NIRO_MD_SECTIONS)
 
   // Primary: exact removal of every known section (LF, then a CRLF copy).
   for (const section of knownSections || []) {
-    for (const variant of [section, section.replace(/\n/g, "\r\n")]) {
-      while (next.includes(variant)) {
-        next = next.replace(variant, "");
+    for (const [variant, eol] of [[section, "\n"], [section.replace(/\n/g, "\r\n"), "\r\n"]]) {
+      let at;
+      while ((at = next.indexOf(variant)) !== -1) {
+        const after = at + variant.length;
+        next = next.slice(0, at) + (touchesTextOnBothSides(next, at, after) ? eol : "") + next.slice(after);
         removed = true;
       }
     }
@@ -84,7 +97,7 @@ function removeMarkerSection(content, marker, knownSections = NIRO_MD_SECTIONS)
   // handled; stop when no marker remains or a pass makes no progress (e.g. an in-fence marker
   // we deliberately leave alone), which also prevents an infinite loop.
   while (next.includes(marker)) {
-    const r = removeMarkerSectionBounded(next, marker);
+    const r = removeMarkerSectionBounded(next, marker, knownSections);
     if (!r.removed || r.content === next) break;
     next = r.content;
     removed = true;
@@ -94,13 +107,27 @@ function removeMarkerSection(content, marker, knownSections = NIRO_MD_SECTIONS)
 }
 
 /**
- * Bounded fallback for removeMarkerSection: remove the marker line and the "## Niro MCP" block
- * it heads, stopping at the first blank line, the next heading, or EOF. A marker inside a code
- * fence is treated as documentation and left untouched. Operates line-wise so CRLF survives.
+ * True when the text cut out of `content` between `at` and `after` had the user's text right against it on both
+ * sides: something other than a line break just before, and something other than a line break just after. The cut
+ * text starts and ends with a line break, so the two lines would be joined unless one is put back.
  */
-function removeMarkerSectionBounded(content, marker) {
-  const eol = content.includes("\r\n") ? "\r\n" : "\n";
-  const lines = content.split(/\r?\n/);
+function touchesTextOnBothSides(content, at, after) {
+  if (at === 0 || after >= content.length) return false;
+  return content[at - 1] !== "\n" && content[after] !== "\n" && content[after] !== "\r";
+}
+
+/**
+ * Bounded fallback for removeMarkerSection: remove the marker line and, in the block under it (up to a blank
+ * line or EOF), every line some known section holds as a whole line (the "## Niro MCP" heading and body lines
+ * a release wrote). A line no known section holds is kept, so a user's line glued below an unknown section
+ * survives. A marker inside a code fence is treated as documentation
+ * and left untouched. A marker sharing its line with other text loses only the marker. Each kept line keeps
+ * its own line ending.
+ */
+function removeMarkerSectionBounded(content, marker, knownSections = NIRO_ALL_MD_SECTIONS) {
+  // Each line keeps its own line ending, so LF, CRLF and a last line with no line break all come back as they were.
+  const lines = content.split(/(?<=\n)/);
+  const text = (line) => line.replace(/\r?\n$/, "");
   const markerLine = lines.findIndex((l) => l.includes(marker));
   if (markerLine === -1) return { content, removed: false };
 
@@ -111,23 +138,33 @@ function removeMarkerSectionBounded(content, marker) {
   }
   if (fences % 2 === 1) return { content, removed: false };
 
-  let end = markerLine + 1; // exclusive index of the first line to KEEP
-  if (end < lines.length && lines[end].startsWith("## ")) {
-    end++; // the "## Niro MCP" heading
-    while (end < lines.length && lines[end].trim() !== "" && !lines[end].startsWith("#")) {
-      end++; // contiguous niro body lines — stop at a blank line or the next heading
-    }
-  }
-
-  let begin = markerLine;
-  if (begin > 0 && lines[begin - 1].trim() === "") begin--; // drop install's separator blank line
+  // The marker shares its line with the user's text: that line keeps the user's text and loses only the marker.
+  const rest = lines[markerLine].split(marker).join("");
+  const markerAlone = text(rest).trim() === "";
+  if (!markerAlone) lines[markerLine] = rest;
 
-  lines.splice(begin, end - begin);
-  return { content: lines.join(eol), removed: true };
+  const knownLines = new Set();
+  for (const section of knownSections || []) {
+    for (const line of section.split(/\r?\n/)) if (line.trim() !== "") knownLines.add(line.trimEnd());
+  }
+  // The block is the lines right under the marker, up to a blank line or EOF. Of those, only a line some release
+  // wrote word for word goes (the heading, a body line). A line no release wrote stays where it is: the user's
+  // own line glued below, and also a Niro line the user edited or an older release worded differently, because
+  // niro cannot tell those apart from the user's. Known lines after it still go, so an edited line leaves only
+  // itself behind, not the rest of the old body.
+  const drop = new Set();
+  if (markerAlone) {
+    drop.add(markerLine);
+    if (markerLine > 0 && text(lines[markerLine - 1]).trim() === "") drop.add(markerLine - 1); // install's separator blank line
+  }
+  for (let i = markerLine + 1; i < lines.length && text(lines[i]).trim() !== ""; i++) {
+    if (knownLines.has(text(lines[i]).trimEnd())) drop.add(i);
+  }
+  return { content: lines.filter((_, i) => !drop.has(i)).join(""), removed: true };
 }
 
 /**
- * Strip niro's PostCompact, UserPromptSubmit, and PreToolUse (temp-project + explore-first + impact-gate) hook
+ * Strip niro's PostCompact, UserPromptSubmit, and PreToolUse (temp-project + explore-first + shell-search + impact-gate) hook
  * entries from a parsed Claude Code settings object (mutates and returns it). Uses the same matchers
  * install uses. Empty arrays / an empty `hooks` object are pruned so the file stays tidy. Other hooks
  * are untouched. Returns { settings, removed } where `removed` is the count deleted.
@@ -154,14 +191,14 @@ function filterNiroHooks(settings) {
   if (Array.isArray(hooks.PreToolUse)) {
     const before = hooks.PreToolUse.length;
     hooks.PreToolUse = hooks.PreToolUse.filter(
-      (h) => !isNiroPreToolUseHook(h) && !isNiroExploreHook(h) && !isNiroImpactHook(h),
+      (h) => !isNiroPreToolUseHook(h) && !isNiroExploreHook(h) && !isNiroImpactHook(h) && !isNiroShellSearchHook(h),
     );
     removed += before - hooks.PreToolUse.length;
     if (hooks.PreToolUse.length === 0) delete hooks.PreToolUse;
   }
   if (Array.isArray(hooks.Stop)) {
     const before = hooks.Stop.length;
-    hooks.Stop = hooks.Stop.filter((h) => !isNiroStopHook(h));
+    hooks.Stop = hooks.Stop.filter((h) => !isNiroStopHook(h) && !isNiroLineCheckHook(h));
     removed += before - hooks.Stop.length;
     if (hooks.Stop.length === 0) delete hooks.Stop;
   }
@@ -377,6 +414,7 @@ function forceRemoveAgentsSkills() {
   const home = userHome();
   deleteFileIfPresent(path.join(home, ".agents", "skills", "niro-skill", "SKILL.md"), "shared niro skill");
   deleteFileIfPresent(path.join(home, ".agents", "skills", "niro-cli", "SKILL.md"), "shared niro-cli skill");
+  deleteFileIfPresent(path.join(home, ".agents", "skills", "niro-local", "SKILL.md"), "shared niro-local skill");
 }
 
 // ─── per-client uninstallers (mirror setup.js's per-client installers) ────────
@@ -399,6 +437,15 @@ function uninstallClaudeCode() {
   stripMarkerFromFile(path.join(home, ".claude", "CLAUDE.md"), "Claude Code memory");
   deleteFileIfPresent(path.join(home, ".claude", "skills", "niro-skill", "SKILL.md"), "niro skill");
   deleteFileIfPresent(path.join(home, ".claude", "skills", "niro-cli", "SKILL.md"), "niro-cli skill");
+  deleteFileIfPresent(path.join(home, ".claude", "skills", "niro-local", "SKILL.md"), "niro-local skill");
+  // The saved mode (`niro mcp install --local`) goes too, so a later plain install starts from the
+  // cloud default rather than silently from local mode (verifier, 2026-11-02).
+  try {
+    const config = require("../lib/config");
+    if (config.load().mcpMode !== undefined) config.save({ mcpMode: undefined });
+  } catch {
+    /* best effort, as above */
+  }
 }
 
 function uninstallCodex(opts = {}) {
@@ -545,38 +592,8 @@ const UNINSTALLERS = {
   antigravity: uninstallAntigravity,
 };
 
-/**
- * Drop the mcpServerUrl fallback install saved to ~/.niro/config.json. Only invoked for a
- * full (--all) uninstall — it's a global, not per-client, value. apiUrl and any other keys
- * are preserved; credentials.json is never touched here.
- */
-function removeGlobalMcpServerUrl() {
-  let cfg;
-  try {
-    cfg = require("../lib/config");
-  } catch {
-    return;
-  }
-  try {
-    const current = cfg.load();
-    if (!Object.prototype.hasOwnProperty.call(current, "mcpServerUrl")) return;
-    delete current.mcpServerUrl;
-    fs.writeFileSync(cfg.FILE, JSON.stringify(current, null, 2) + "\n");
-    console.log(`    Removed mcpServerUrl from ${cfg.FILE}`);
-  } catch (e) {
-    console.warn(`    Could not update ~/.niro/config.json: ${e.message}`);
-  }
-}
-
 // ─── interactive entry ───────────────────────────────────────────────────────
 
-function printHeader() {
-  console.log("");
-  console.log("    Niro MCP Server Uninstall");
-  console.log("    -------------------------");
-  console.log("");
-}
-
 function printClients() {
   console.log("    Clients:");
   Object.keys(UNINSTALLERS).forEach((id) => {
@@ -604,18 +621,60 @@ function ask(rl, question, defaultValue) {
   });
 }
 
+/**
+ * Remove Niro from `targets`, one line per assistant. Each uninstaller's own step-by-step lines
+ * are kept back and shown only when that assistant fails, so a normal run reads as a checklist.
+ */
 function runUninstall(targets, isFull) {
-  for (const id of targets) UNINSTALLERS[id]({ full: isFull });
+  let failed = 0;
+  for (const id of targets) {
+    const said = [];
+    const [log, warn] = [console.log, console.warn];
+    console.log = (...a) => said.push(a.join(" "));
+    console.warn = (...a) => said.push(a.join(" "));
+    try {
+      UNINSTALLERS[id]({ full: isFull });
+      console.log = log;
+      console.warn = warn;
+      console.log(`│  ${color.green("✓")} ${nameOf(id)}`);
+    } catch (err) {
+      console.log = log;
+      console.warn = warn;
+      failed += 1;
+      console.log(`│  ${color.yellow("⚠")} ${nameOf(id)}: ${err.message}`);
+      for (const line of said) if (line.trim()) console.log(`│      ${line.trim()}`);
+    }
+  }
   if (isFull) {
-    // Every editor is gone — remove the shared cross-agent skills and the global URL.
-    forceRemoveAgentsSkills();
-    removeGlobalMcpServerUrl();
+    // Every editor is gone: remove the shared cross-agent skills. The saved mcpServerUrl stays: it
+    // is also where usage is sent, and removing it sent a dev or staging machine's usage to
+    // production (`niro uninstall` deletes ~/.niro, and it, anyway).
+    const [log] = [console.log];
+    console.log = () => {};
+    try {
+      forceRemoveAgentsSkills();
+    } finally {
+      console.log = log;
+    }
   }
+  console.log("│");
+  console.log(`└  ${failed ? "Done, with the problems above." : "Done."} Restart ${targets.length === 1 ? nameOf(targets[0]) : "those assistants"} for it to take effect.`);
+  console.log("");
+  console.log(`   Your sign-in and your graphs are kept. To remove Niro completely:  ${color.cyan("niro uninstall")}`);
+  console.log("");
+  if (failed) process.exitCode = 1;
+}
+
+const nameOf = (id) => (CLIENTS[id] ? CLIENTS[id].name : id);
 
-  console.log("\n    Uninstall complete. Restart your AI assistant for the change to take effect.\n");
-  console.log("    Your `niro login` session is kept. Run `niro logout` to clear it.");
-  console.log("    The `niro` command itself is still installed. To remove it too:");
-  console.log("    npm rm -g niro-mcp-and-cli\n");
+/** The assistants Niro is installed in on this machine, by id, each once. */
+function installedIds() {
+  try {
+    const { configured } = require("../lib/mcpClients").configuredClients();
+    return [...new Set(configured.map((c) => c.id))].filter((id) => UNINSTALLERS[id]);
+  } catch {
+    return [];
+  }
 }
 
 async function main() {
@@ -629,52 +688,75 @@ async function main() {
     else if (args[i] === "-y" || args[i] === "--yes") assumeYes = true;
   }
 
-  printHeader();
-
   const allIds = Object.keys(UNINSTALLERS);
   let targets;
+  let picked = false;
+
+  // Nothing to do is one plain line, not a box around one sentence.
+  const interactive = !all && clientArg !== "all" && !clientArg && process.stdin.isTTY;
+  const installed = interactive ? installedIds() : null;
+  if (interactive && !installed.length) {
+    console.log(`\nNiro is not set up in any AI assistant on this machine, so there is nothing to remove. To set it up:  ${color.cyan("niro mcp install")}\n`);
+    return;
+  }
+
+  console.log("");
+  console.log("┌  Remove Niro from your AI assistants");
+  console.log("│");
 
   if (all || clientArg === "all") {
     targets = allIds;
   } else if (clientArg) {
-    if (!UNINSTALLERS[clientArg]) {
-      console.error(`    Unknown client: ${clientArg}\n`);
+    const ids = clientArg.split(",").map((x) => x.trim()).filter(Boolean);
+    const unknown = ids.filter((id) => !UNINSTALLERS[id]);
+    if (unknown.length) {
+      console.error(`│  Unknown assistant: ${unknown.join(", ")}`);
       printClients();
       process.exit(1);
     }
-    targets = [clientArg];
+    targets = ids;
   } else if (!process.stdin.isTTY) {
     // Non-interactive with no target: refuse rather than guess.
-    console.error("    No client specified. Pass --client <id> or --all.\n");
+    console.error("│  No assistant named. Pass --client <id> or --all.");
     printClients();
     process.exit(1);
   } else {
-    printClients();
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    const choice = await ask(rl, "    Remove Niro from which client?", "claude-code");
-    rl.close();
-    if (choice === "all") targets = allIds;
-    else if (UNINSTALLERS[choice]) targets = [choice];
-    else {
-      console.error(`\n    Unknown client: ${choice}\n`);
-      process.exit(1);
+    console.log("◆  Which assistants should stop using Niro?");
+    targets = await choose({
+      prefix: "│  ",
+      items: installed.map((id) => ({ value: id, label: nameOf(id) })),
+      multi: true,
+      // Nothing ticked to start: pre-ticked, "space on each" unticked them all and Enter then
+      // took only the one under the cursor (Divya, 2026-11-05).
+      initial: [],
+      hint: "↑/↓ move · space tick · a all · enter remove",
+    });
+    picked = true;
+    if (!targets.length) {
+      console.log("└  Nothing picked. Nothing was changed.");
+      console.log("");
+      return;
     }
   }
 
-  const isFull = targets.length === allIds.length;
+  // Everything that was set up is going, so the shared files go too.
+  const remaining = installedIds().filter((id) => !targets.includes(id));
+  const isFull = targets.length === allIds.length || remaining.length === 0;
 
-  if (!assumeYes && process.stdin.isTTY) {
-    console.log(`\n    This removes Niro MCP config from: ${targets.join(", ")}`);
-    console.log("    (Your `niro login` session in ~/.niro/credentials.json is left intact.)\n");
+  // Picking in the list above is the confirmation; a command line naming assistants asks once.
+  if (!picked && !assumeYes && process.stdin.isTTY) {
+    console.log(`│  This removes Niro from: ${targets.map(nameOf).join(", ")}`);
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    const ans = await ask(rl, "    Proceed?", "yes");
+    const ans = await ask(rl, "│  Go ahead?", "yes");
     rl.close();
     if (!/^y/i.test(ans)) {
-      console.log("\n    Aborted. Nothing was changed.\n");
+      console.log("└  Nothing was changed.");
+      console.log("");
       return;
     }
   }
 
+  console.log("│");
   runUninstall(targets, isFull);
 }
 

package/src/mcp/usingNiro.js

@@ -0,0 +1,39 @@
+"use strict";
+
+/**
+ * "Using Niro": what a coding agent should do with Niro beyond code questions. Written into every instruction text a
+ * release without the cloud installs (the niro-skill, the CLAUDE.md section, the marked sections for Codex, Gemini
+ * CLI, Copilot CLI, Factory, OpenCode and Windsurf, and the Cursor, Cline and Kiro rules), and said by the released
+ * engine in its MCP instructions, which every one of the 14 assistants reads (niro-local
+ * `src/niro_local/mcp/using_niro.py`).
+ *
+ * Why (Niraj, 2026-11-11): 92 pages ship with niro (`niro guide`), and an agent asked a question about Niro never
+ * opened one, because no text it read named them; "this has to happen automatically part of the installation".
+ * How an agent finds a page (Niraj, 2026-11-11, "agreed"): it reads the list with its one-line descriptions and
+ * picks by meaning, because agents match meaning themselves, niro-cli carries no model, and the pages work offline.
+ * `--search` is named only for an exact message or word. Decision 01M75G5K5NYJDT1EWM3K2V3PTT.
+ *
+ * ONE text in each repository, equal word for word: test/usingNiro.test.js reads niro-local's copy and niro-local's
+ * tests/test_using_niro.py reads this one. Kept to a template literal with no `${}` so a reader outside JavaScript
+ * can take it out of this file. No blank line inside it: a marked section ends at its first blank line when an
+ * upgrade or an uninstall has to cut out a text it no longer knows word for word (teardown.js).
+ * Every command it names is checked against the CLI by that test.
+ */
+const USING_NIRO = `Using Niro:
+- Code questions: use the niro tools, as above.
+- A "how do I" question about Niro: run \`niro guide\`, which lists every page with one line on what it answers. Pick the page whose line fits the question, run \`niro guide <page>\`, and answer from it. The pages ship with niro and work offline. For work on code: playbook-debug-exception, playbook-change-safely, playbook-review-a-change, playbook-test-a-change.
+- A Niro error message, or an exact word such as an error code: \`niro guide --search "<the message>"\` names the page that explains it.
+- Code in a language, framework or tool Niro does not read: offer to ask Niro's team for it with the request_integration tool, which sends nothing until the user says yes. In a terminal: \`niro request-integration <name>\`.
+- Managing Niro, in the terminal:
+  - index another folder: \`niro init <folder>\`, only when the user asks or says yes
+  - rebuild a folder's graph: \`niro build <folder>\`
+  - what is indexed here: \`niro status\`
+  - the plan and its line limit: \`niro plan\`
+  - what Niro did for the user: \`niro impact\`
+  - connect calls between services: \`niro route-rule unconnected\`, after reading \`niro guide configuring-a-folder\`
+  - anything else: \`niro guide\``;
+
+/** The commands USING_NIRO names, each a real `niro` command (checked by test/usingNiro.test.js against src/index.js). */
+const USING_NIRO_COMMANDS = ["guide", "request-integration", "init", "build", "status", "plan", "impact", "route-rule"];
+
+module.exports = { USING_NIRO, USING_NIRO_COMMANDS };

package/docs/working-on-branches.md

@@ -1,162 +0,0 @@
-# Working on branches with Niro
-
-Your team decides what Niro indexes: you create projects, and each project
-covers the repos and branches you choose. One project might index main,
-another might index a develop or release branch. That is up to you.
-
-When you ask a question, Niro picks the project that matches your repo and
-the branch you are currently on. This page is about the moment when NO
-project matches: you created a new branch and changed code that no project
-has indexed yet. Two minutes to read.
-
-## The short version
-
-There is one command to remember:
-
-    niro new-temp-project
-
-Run it in your repo folder when Niro asks for it. That is all.
-
-## What you will see
-
-You create a branch that no project covers and start changing code.
-Then you ask your AI assistant something about the code.
-
-Niro notices that no project has indexed this branch. Instead of giving
-you a wrong answer based on some other branch, it replies with something
-like:
-
-    I cannot answer this safely. Your branch has diverged
-    from the branch Niro indexed.
-
-Your assistant will offer to fix this by running:
-
-    niro new-temp-project
-
-Say yes, or run it yourself in the repo folder. It takes a few seconds.
-
-## What the command does
-
-It creates your own private copy of the project inside Niro.
-
-- The copy follows your branch, including changes you have not committed.
-- Every save updates the copy, as long as "niro watch" is running.
-- Your original project is not changed. It keeps its own index.
-- The copy is fully separate and disposable.
-
-From then on, answers come from YOUR code.
-
-The commands follow too. `niro status` and `niro build` act on the copy for the branch you are on,
-not on the shared project, so "is my index up to date" and "rebuild it" mean what you expect while
-you are working on a branch. Name a project explicitly if you want a different one.
-
-`niro delete` and `niro remove --project` will not delete a private copy. They send you to
-`niro discard-temp-project`, which removes the copy AND points your folder back at the shared
-project. Deleting it any other way leaves your folder aimed at something that is gone.
-
-## Switching branches
-
-Nothing to do. Niro checks which branch you are on for every question.
-
-- On your new branch: answers come from your private copy.
-- On a branch one of your projects already indexes: answers come
-  from that project.
-
-## When your work is merged
-
-Run this in the repo folder:
-
-    niro discard-temp-project
-
-It deletes your private copy. Your local files are never touched.
-If you forget, Niro deletes unused copies by itself after two weeks.
-
-## Tidying up copies that were deleted for you
-
-When a copy goes after two weeks, or somebody deletes it in the web app,
-your machine is not told. The folder is left pointing at a copy that is
-no longer there. Nothing breaks, but "niro new-temp-project" in another
-worktree of the same repo will say the slot is already taken.
-
-Run this from anywhere to sort it out:
-
-    niro doctor sync-registry
-
-You will rarely need to type it. The background watcher runs the same
-check every six hours by itself.
-
-It sorts out three things, and treats them differently:
-
-- A folder pointing at a private copy that has gone goes back to the
-  original project, and carries on syncing.
-- A folder pointing at a project that has gone is only unregistered when
-  the repo has gone too. A project can be deleted while its repos are
-  moved somewhere else, and that folder is still syncing perfectly well.
-- A ".niro-project" file naming something the server does not know is
-  repaired where possible. That file can hold a project's NAME rather
-  than its id, so a renamed project looks exactly like a deleted one.
-  Niro checks your folder's git remote instead: if that points at one
-  project, the file is rewritten to that project's id, which a future
-  rename cannot break. If the remote points at nothing either, the file
-  names nothing and is removed.
-
-  Not if the file is committed to git, though. Then it is shared with
-  everyone who clones the repo, and a project that means nothing to you
-  may be a colleague's. Niro tells you and leaves the choice to you.
-  "niro info" mentions it too, when you are standing in that folder.
-
-Copies that are still there are left alone, and so is anything it could
-not check, so a dropped connection never costs you a working folder. Add
-"--dry-run" to see the list without changing anything.
-
-## When you run out of private copies
-
-You get a limited number of private copies of each project. When you hit
-the limit, Niro says which branches are holding them, and the CLI adds
-where each one is checked out on this machine:
-
-    You already have 5 working copies of this project, which is
-    the limit (5). They are for: feature/a, feature/b, ...
-
-        You have 5 working copies of this project on this machine:
-          feature/a    /home/you/work/service
-          feature/b    /home/you/work/service-wt2
-
-Run "niro discard-temp-project" in one you have finished with, then try
-again. Copies nobody has touched for a while are cleared automatically,
-so this usually sorts itself out.
-
-## A feature that spans several repos
-
-Run "niro new-temp-project" in each repo folder you branch.
-All of them join the same private copy, so questions that cross repos
-(for example: what breaks in service B if I change service A?) see all
-of your changes together.
-
-## Common questions
-
-Does this change my original project?
-No. The original project and its index stay exactly as they were.
-The copy is separate; deleting it later loses nothing.
-
-Does this work with my AI assistant and my git host?
-Yes. Any assistant that supports MCP (Claude Code, Cursor, Windsurf,
-Codex, and others) and any git server (GitHub, GitLab, Bitbucket,
-self-hosted).
-
-Is creating a copy slow?
-No. Niro copies the existing index instead of re-reading your code.
-It normally takes seconds.
-
-I just created a branch and have not changed anything. Will Niro nag me?
-No. Your code is still identical to the branch you started from, so Niro
-answers normally. It only steps in once your code actually differs.
-
-We already have projects for main and develop. Do I need this?
-Not while you are on main or develop: Niro routes to the matching project
-by itself. You only need a temporary project for a branch that none of
-your projects cover.
-
-What if I really want an answer from the shared project while on my branch?
-Tell your assistant so. The answer will be clearly labeled as describing
-the indexed branch, not your code.