@niroai/niro 0.17.0 → 0.18.0

package/src/mcp/localMode.js

@@ -0,0 +1,383 @@
+/**
+ * What `niro mcp install --local` writes instead of the cloud texts: the assistant is pointed at
+ * niro-local, the engine on this machine, rather than at a Niro project in the cloud.
+ *
+ * Why a separate set at all. The cloud hooks, CLAUDE.md section and skill decide where to speak up
+ * from a `.niro-project` file and name tools the engine does not serve (resolve_fqn,
+ * should_create_temp_project, get_state_at_entry, list_projects ...), so in a
+ * folder only niro-local indexes they either stay silent or send the assistant after tools that are
+ * not there. Here every gate reads niro-local's own list of indexed folders and every text names
+ * only the engine's tools.
+ *
+ * Swapping back and forth is the point (Niraj, 2026-11-02: "I may have to remove niro local and
+ * reinstall niro's current mcp, skill etc and vice versa"). So each local text keeps the identity
+ * token the cloud one has (the PostCompact prefix, the NIRO ACTIVE marker, niro-explore-,
+ * niro-impact-, the <!-- niro-mcp --> marker, the same skill files): installing one mode replaces
+ * the other in place, and `niro mcp uninstall` removes either.
+ *
+ * The mode is remembered in ~/.niro/config.json (`mcpMode`), so `niro upgrade`, which re-runs the
+ * installer per client with no mode flag, keeps what the person chose.
+ */
+
+/**
+ * Whether this release has the cloud (src/lib/release.js). Without it, the engine is the released one, which builds and
+ * answers only with the licence niro-cli passes it, so a `niro-local build` or `niro-local ask` typed by the assistant
+ * is refused. The texts below then name the niro-cli commands that do the same through niro-cli (`niro build`,
+ * `niro status`, `niro init`) and the MCP tools, and never a direct `niro-local` command (the release's own
+ * niro-local skill: "Never run the engine (`niro-local`) directly"). Read once, when this module loads.
+ */
+const CLOUD_RELEASE = require("../lib/release").cloud !== false;
+const { USING_NIRO } = require("./usingNiro");
+
+/**
+ * The two rules niro-local's own server instructions carry word for word (its `mcp/server.py`
+ * WORKTREE_SENTENCE and OFFER_SENTENCE), so the skill, the CLAUDE.md section and the engine say one
+ * thing. Pinned on both sides (test/localMode.test.js; niro-local tests/test_agent_guidance.py). The release
+ * wordings are the same rules through niro-cli; niro-local's server text is being changed to match (lead, 2026-11-06).
+ */
+const ENGINE_WORKTREE_SENTENCE = "When you work in another folder (a git worktree, a sibling service), ask from that folder with `niro-local ask <tool> key=value`, and run `niro-local build` there after each edit.";
+const ENGINE_OFFER_SENTENCE = "If a tool says a folder is not indexed, follow its answer: ask the user once, and index it only on a yes.";
+const RELEASE_WORKTREE_SENTENCE = "When you work in another folder (a git worktree, a sibling service), the niro tools still answer for the folder the session started in: run `niro status` in that folder to see whether it is indexed, and `niro build <that folder>` after each edit there.";
+const RELEASE_OFFER_SENTENCE = "If a tool says a folder is not indexed, ask the user once, and only on a yes run `niro init` in that folder.";
+const WORKTREE_SENTENCE = CLOUD_RELEASE ? ENGINE_WORKTREE_SENTENCE : RELEASE_WORKTREE_SENTENCE;
+const OFFER_SENTENCE = CLOUD_RELEASE ? ENGINE_OFFER_SENTENCE : RELEASE_OFFER_SENTENCE;
+/** How the graph is rebuilt by hand, as the texts name it. */
+const REBUILD_COMMAND = CLOUD_RELEASE ? "niro-local build" : "niro build";
+
+const MODES = ["cloud", "local"];
+
+/**
+ * LLM documentation (`niro-local build --llm`, find_reusable_code, find_known_issues) is off in this release
+ * (src/lib/release.js `llmDocs`; niro-local `reuse.IN_THIS_RELEASE`), so no text below names it. Read once, when this
+ * module loads: the texts are constants that the installer writes and the uninstaller matches.
+ */
+const LLM_DOCS = require("../lib/release").llmDocs === true;
+
+/** The mode asked for on the command line (`--local` / `--cloud`), or null when neither was. */
+function modeFromArgs(args) {
+  if (args.includes("--local")) return "local";
+  if (args.includes("--cloud")) return "cloud";
+  return null;
+}
+
+/** The mode to install: the one asked for, else the one saved by the last install, else cloud. */
+function chooseMode(args, saved) {
+  const asked = modeFromArgs(args);
+  if (asked) return asked;
+  return MODES.includes(saved) ? saved : "cloud";
+}
+
+/**
+ * The shell test the local hooks use instead of walking up for `.niro-project`: is `$d`, or a folder
+ * above it, one niro-local indexes? niro-local writes the list beside its registry, one resolved path
+ * per line (niro-local `registry.FOLDER_LIST_NAME`). A shell grep of a small file, because these
+ * hooks run on every prompt and every native search; asking `niro-local status --check` took 0.54 s.
+ */
+const FOLDER_LIST = '"${NIRO_LOCAL_HOME:-$HOME/.niro-local}/indexed-folders"';
+const LOCAL_WALK =
+  `IF=${FOLDER_LIST}; [ -f "$IF" ] || exit 0; ` +
+  'd="$d0"; ok=0; while [ -n "$d" ] && [ "$d" != "/" ] && [ "$d" != "." ]; do if grep -qxF "$d" "$IF"; then ok=1; break; fi; p="$(dirname "$d")"; [ "$p" = "$d" ] && break; d="$p"; done';
+
+/** The cloud hooks' walk up for `.niro-project`, as it appears in the explore and impact commands. */
+const CLOUD_WALK =
+  'd="$d0"; ok=0; while [ -n "$d" ] && [ "$d" != "/" ] && [ "$d" != "." ]; do if [ -f "$d/.niro-project" ]; then ok=1; break; fi; p="$(dirname "$d")"; [ "$p" = "$d" ] && break; d="$p"; done';
+
+/**
+ * The same two walks without a process per folder level, used by the Bash hook (shellSearchHook.js),
+ * which runs before every shell command. The walks above start a `dirname` and, in local mode, a
+ * `grep` at each level: about 23 ms for a folder six levels deep under load. These read the folder
+ * list once and match each level with `case`, and take the parent with `${d%/*}`. The explore and
+ * impact hooks keep the walks above, so their installed text does not change.
+ */
+const FAST_LOCAL_WALK =
+  `IF=${FOLDER_LIST}; [ -f "$IF" ] || exit 0; L="$(cat "$IF")"; N="$(printf '\\n.')"; N="\${N%.}"; ` +
+  'd="$d0"; ok=0; while [ -n "$d" ] && [ "$d" != "/" ] && [ "$d" != "." ]; do case "$N$L$N" in *"$N$d$N"*) ok=1; break ;; esac; p="${d%/*}"; [ -z "$p" ] && p=/; [ "$p" = "$d" ] && break; d="$p"; done';
+const FAST_CLOUD_WALK =
+  'd="$d0"; ok=0; while [ -n "$d" ] && [ "$d" != "/" ] && [ "$d" != "." ]; do if [ -f "$d/.niro-project" ]; then ok=1; break; fi; p="${d%/*}"; [ -z "$p" ] && p=/; [ "$p" = "$d" ] && break; d="$p"; done';
+
+/** Cloud tool names, and wording, that mean something else on this machine. */
+const LOCAL_WORDING = [
+  ["get_source_code or resolve_fqn", "get_source_code or resolve_name"],
+  ["resolve_fqn", "resolve_name"],
+  LLM_DOCS
+    ? ["find_reusable_code (before new code)", "find_reusable_code (before new code, when the folder was built with --llm)"]
+    : [", find_reusable_code (before new code)", ""],
+  ["synced and rebuilt", "rebuilt by niro-local"],
+  ["the Niro bridge has not answered", "the niro-local engine has not answered"],
+  ["niro-indexed repo", "folder niro-local indexes"],
+];
+
+/**
+ * A cloud hook command made local: its `.niro-project` walk swapped for the folder-list test, its
+ * tool names for the engine's. Throws when the walk is not found, because a command that kept the
+ * cloud gate would install silently and then never fire in a local folder.
+ */
+function localHook(command) {
+  let local;
+  if (command.includes(CLOUD_WALK)) local = command.replace(CLOUD_WALK, LOCAL_WALK);
+  else if (command.includes(FAST_CLOUD_WALK)) local = command.replace(FAST_CLOUD_WALK, FAST_LOCAL_WALK);
+  else throw new Error("the cloud hook no longer contains the .niro-project walk localHook replaces");
+  for (const [cloud, here] of LOCAL_WORDING) local = local.split(cloud).join(here);
+  return local;
+}
+
+/**
+ * The standing reminder before every prompt, in a folder niro-local indexes. Keeps the cloud
+ * reminder's opening, "NIRO ACTIVE. Standing rule for this whole session", which is how the
+ * installer and the uninstaller recognise its own hook (setup.js isNiroUserPromptHook). No branch notice: niro-local
+ * follows the folder, whatever branch it is on.
+ */
+const LOCAL_USER_PROMPT_COMMAND =
+  'IN="$(cat)"; d="${CLAUDE_PROJECT_DIR:-$PWD}"; d="$(cd -P "$d" 2>/dev/null && pwd -P || printf \'%s\' "$d")"; ' +
+  `IF=${FOLDER_LIST}; [ -f "$IF" ] || exit 0; ` +
+  'while [ -n "$d" ] && [ "$d" != "/" ] && [ "$d" != "." ]; do if grep -qxF "$d" "$IF"; then ' +
+  "echo 'NIRO ACTIVE. Standing rule for this whole session, at the start and mid-task alike: this folder is " +
+  "indexed by niro-local on this machine. Before Grep/Glob/Read or any native file hunt, use the niro tools " +
+  "(code_grep, get_source_code, resolve_name, get_call_chain, get_reverse_call_chain, get_blast_radius). " +
+  (LLM_DOCS
+    ? "Before writing new code, call find_reusable_code when it is in your toolset (it is there only for a folder " +
+      "built with --llm). "
+    : "") +
+  "Before you plan or propose a change to existing code, call get_blast_radius to see who " +
+  "calls it and what it calls, and put that impact in the plan. Keep that list and verify those flows after " +
+  "the edit; the graph changes only when niro-local rebuilds, so do not re-query it to verify. A log line or " +
+  "comment needs no map. Native tools only for config, docs, logs, generated or non-code text. If the niro " +
+  "tools are not in your toolset at all, use native tools and do not mention Niro.'; break; fi; " +
+  'd="$(dirname "$d")"; done';
+
+/** After compaction. Starts with the cloud prefix, which is how the installer finds its own hook. */
+const LOCAL_POST_COMPACT_COMMAND =
+  "echo 'Niro MCP tools are available for code intelligence, answered by niro-local on this machine "
+  + "(call chains, blast radius, source lookup, data and event flows). Use niro tools before native "
+  + "grep/read for code questions in a folder niro-local indexes. Before you plan or propose a change to "
+  + "existing code, call get_blast_radius to see who calls it and what it calls, and put that impact in the "
+  + "plan. Keep that list and verify those flows after the edit; the graph changes only when niro-local "
+  + "rebuilds, so do not re-query it to verify. The niro tools answer for the folder the MCP server was "
+  + "started in. " + WORKTREE_SENTENCE.replace(/`/g, "") + " The niro-skill has the full routing playbook.'";
+
+const MD_MARKER = "<!-- niro-mcp -->";
+
+/**
+ * The ~/.claude/CLAUDE.md section. Its own heading, after the shared marker, as every niro section has. Both
+ * wordings (with and without the LLM sentence) are kept for the uninstaller, which removes a section only by its
+ * exact text, so one written by a release with LLM documentation on is still removed.
+ */
+const localClaudeMdSection = (llm, usingNiro = !CLOUD_RELEASE) => `\n${MD_MARKER}\n## Niro MCP (niro-local)\n`
+  + "The niro MCP tools answer from niro-local, a code graph built on this machine from the files on disk. "
+  + "Nothing is sent to the cloud to answer them. Use them before native grep/read for code questions in "
+  + "a folder niro-local indexes; the niro-skill has the routing playbook.\n"
+  + "MUST FOLLOW: before you run grep, find, glob, or open a file to hunt for something, first check whether "
+  + "a niro tool answers it (code_grep for content search, resolve_name and get_source_code for a known "
+  + "symbol, find_handler and find_api_endpoints for entry points). Use the connection tools (get_call_chain, "
+  + "get_reverse_call_chain, get_blast_radius, get_service_topology, get_exception_flow) to understand how code "
+  + "connects BEFORE deciding which file to read next. Native search is the fallback for what the graph does "
+  + "not cover (config files, docs, logs, generated output, non-code text) and for a folder niro-local does "
+  + "not index. This rule does not expire.\n"
+  + "MUST FOLLOW: before you plan, propose, or start any change to existing code, call get_blast_radius on it "
+  + "and put both sides in the plan: who depends on it (callers, HTTP and event callers, tests) and what it "
+  + "depends on. Keep the list and verify those flows after the edit; the graph changes only when niro-local "
+  + "rebuilds (`" + REBUILD_COMMAND + "`, or the watcher), so verify from the list, not a fresh query.\n"
+  + (llm
+    ? "Before writing new code, call find_reusable_code when it is in your toolset (a folder built with "
+      + "`niro-local build --llm`).\n"
+    : "")
+  + "In a folder niro-local does not index, call get_index_status once. " + OFFER_SENTENCE + " "
+  + "The niro tools answer for the folder the MCP server was started in. " + WORKTREE_SENTENCE + "\n"
+  // Using Niro (src/mcp/usingNiro.js) names niro-cli's own commands (`niro init`, `niro build`), which are the
+  // engine's only in a release without the cloud; a cloud release's local mode keeps the text it had.
+  + (usingNiro ? `${USING_NIRO}\n` : "");
+const LOCAL_CLAUDE_MD_SECTION = localClaudeMdSection(LLM_DOCS);
+/** Every wording, for the uninstaller and a refresh: the current two, then the two from before Using Niro (9255e24). */
+const LOCAL_CLAUDE_MD_SECTIONS = [
+  localClaudeMdSection(true), localClaudeMdSection(false), localClaudeMdSection(true, false), localClaudeMdSection(false, false),
+].filter((section, i, all) => all.indexOf(section) === i);
+
+const LOCAL_SKILL = `---
+name: niro-skill
+description: Use the niro MCP tools, answered by niro-local from a code graph built on this machine, to answer questions about THIS codebase (structure, call chains, blast radius, exception flow, HTTP routes, data and event flows) instead of grep/read. Invoke whenever a task involves understanding, tracing, debugging, or assessing the impact of code, or BEFORE changing it.
+---
+
+# Niro code intelligence, on this machine (niro-local)
+
+niro-local builds a code graph from the files on disk (classes, methods, calls, HTTP routes and
+calls, events, data stores) and serves it through the \`niro\` MCP server. Nothing leaves the
+machine to answer a question. For anything outside the indexed code (config files, docs, runtime
+state), use your native tools.
+
+## Is this folder indexed? Read FIRST
+
+1. **Are the tools present?** Only call \`mcp__niro__*\` tools that appear in your toolset. If none
+   do, use native tools and do not mention Niro.
+2. **Is this folder indexed?** \`get_index_status\` says what the graph holds for this folder. If
+   the folder is not indexed, the answer says whether it can be, and which projects it can join.
+   ${OFFER_SENTENCE}
+   - **When it offers, ask the user once, in plain words:** should it be indexed, and into which
+     project or a new one? Show the projects as the answer lists them and let the user choose, even
+     when only one fits. Never choose for them, and never index without a yes.
+   - **On a yes,** run the commands the answer gives, from that folder, then ask your question again.
+   - **On a no,** use native tools and do not ask again in this session. Do not loop.
+   - **When it makes no offer** (no source niro-local reads, a protected folder), use native tools and
+     do not bring it up.
+   - **The branch rule.** Every folder of a project must be on one branch. A folder outside git, or on
+     a detached HEAD, has no branch and can join any project. A project on another branch is not
+     offered and refuses the folder: start a new project, as the answer says.
+   - **A branch switch is followed.** niro-local keeps one index per folder and branch, and answers
+     from the index of the branch the folder is on at each call. After \`git checkout\`, a branch it
+     has indexed answers at once. On a new one, niro-local makes a temporary copy of the project by
+     itself: nothing to ask. Use native tools for a moment and ask again; the answer says what to run
+     if nothing builds by itself.
+3. **Is the question in scope?** Structure, behaviour, impact, routes, data and event flows ->
+   niro. Config, docs, runtime state, anything non-code -> native tools.
+
+## Explore first (MUST FOLLOW)
+
+Before you run grep, find, glob, or open a file to hunt for something, check whether a niro tool
+answers it: \`code_grep\` for content, \`get_source_code\` for a known method, class or line range,
+\`resolve_name\` when a name may match several things, \`find_handler\` and \`find_api_endpoints\` for
+entry points. Use the connection tools (\`get_call_chain\`, \`get_reverse_call_chain\`,
+\`get_blast_radius\`, \`get_service_topology\`, \`get_exception_flow\`) to see how the code connects
+BEFORE you decide which file to read next.
+
+## Check both directions before you change anything (MUST FOLLOW)
+
+Before you plan, propose, or start any change to existing code, call \`get_blast_radius\` on it. One
+call returns both sides: what depends on it (callers, HTTP and event callers, and the files that hold
+them) and what it depends on. Put that in the plan you show the user: the callers you found, which you
+will update, and which you are deliberately leaving alone. A one-line change is not exempt.
+
+Keep the list. After the edit, verify those flows still hold (run their tests, trace them, read the
+callers) and say what you verified. The graph changes only when niro-local rebuilds the folder, so a
+fresh query right after your edit still shows the old code: use the list you captured. A change that
+cannot alter behaviour (a log line, a comment, formatting) needs no map: say so in one sentence.
+
+## Keeping the graph current
+
+The graph is what the last \`${REBUILD_COMMAND}\` saw. When a tool says the graph is behind, or files
+were edited since the build, run \`${REBUILD_COMMAND}\` in that folder (it updates only what changed,
+usually in seconds) and ask again. The niro watcher (\`niro watch\`) does this by itself when it runs.
+
+## Working in another folder (MUST FOLLOW)
+
+The niro tools answer for the folder the MCP server was started in, not for where you are working.
+${WORKTREE_SENTENCE}
+${CLOUD_RELEASE ? "\`niro-local ask\` alone lists the tools. " : ""}A folder that is not indexed yet gets the same offer as above.
+
+## Calling conventions
+
+- **Short names work.** Pass \`ClassName.method\` or a bare method name; tools resolve it. Use
+  \`resolve_name\` only when a name may match several things.
+- **\`from_line\`** on most tools continues a paged answer.
+- **\`purpose\`** (LOCATE, ORIENT, COMPREHEND, TRACE, DEBUG, PROPAGATE, ASSESS_RISK, ...) on the
+  chain and blast-radius tools tunes how much comes back.
+- **Collapse stacked calls.** \`get_blast_radius\` covers callers, callees and files in one call;
+  do not follow it with \`get_reverse_call_chain\` for the same name.
+
+## Routing (most specific wins)
+
+| Intent | Tool |
+|---|---|
+| What breaks if I change X: callers and callees in one call | \`get_blast_radius\` |
+| Upstream callers that break, several levels up (lighter than blast radius) | \`get_impact_analysis\` |
+| Who calls X (\`scope=transitive\` for further up) | \`get_reverse_call_chain\` |
+| What X calls, or callers with \`direction\` | \`get_call_chain\` |
+| Which exceptions can escape a method, and where they are caught | \`get_exception_flow\` |
+| Source of a method, class, or a line range of a file | \`get_source_code\` |
+| Search inside source files (regex or literal) | \`code_grep\` |
+| Members of a class, interface or enum | \`get_class_structure\` |
+| Every class, interface and enum | \`list_types\` |
+| What a name matches (at most 25) | \`resolve_name\` |
+| HTTP endpoints this project exposes | \`find_api_endpoints\` |
+| HTTP calls it makes, and where they land | \`find_outbound_http_calls\` |
+| What answers the HTTP calls a method makes | \`find_handler\` |
+| Which folder of the project calls which, over HTTP | \`get_service_topology\` |
+| Databases, caches and queues it touches | \`list_data_resources\` |
+| Who reads, writes or deletes one store | \`get_data_resource_usage\` |
+| Events it publishes or listens to | \`list_events\` |
+| Who publishes and who handles one event | \`get_event_producers_and_handlers\` |
+| Events with only one side | \`find_orphaned_events\` |
+| What is indexed for this folder | \`get_index_status\` |
+${LLM_DOCS ? "| Reusable code, and known issues (folder built with \`--llm\` only) | \`find_reusable_code\`, \`find_known_issues\` |\n" : ""}
+Not on this machine: \`trace_execution_path\`, \`get_state_at_entry\`, \`explain_code\`, temporary projects and
+\`list_projects\`. There is no project id to pass: niro-local answers for the folder the session runs in. For another
+folder, see "Working in another folder".
+
+## Task completion
+
+Call \`mark_task_complete\` before your reply on every turn where you called a niro tool, or read or
+searched this project's source yourself, as the server's instructions say. If it returns a line
+starting with the receipt prefix, copy it as the last line of your reply in single backticks. A reply
+without that line is unfinished: it is how the person sees what the niro tools did.
+`;
+
+const LOCAL_CLI_SKILL = `---
+name: niro-cli
+description: drive niro-local and the niro CLI from chat on this machine: index a folder, rebuild it, check what is indexed, remove a folder, and check the engine and the login
+---
+
+# niro-local from chat
+
+The niro MCP tools answer from niro-local, the engine on this machine. You manage it by running
+commands in the shell and reporting back in plain words. Run ONE command per action, from the
+folder it is about.
+
+## Golden rules
+
+1. **Login is the user's.** \`niro whoami --json\` says whether the user is signed in. If not, tell
+   them to run \`niro login\` themselves; it opens a browser. You cannot complete it for them.
+2. **Never print a secret.** Do not echo environment values, tokens or credential files.
+3. **Confirm before removing.** \`niro-local remove\` takes a folder out of the graph; ask first.
+4. **Ask before indexing.** Index a folder only after the user says yes and has chosen the project.
+   These commands never wait for an answer when run from your shell.
+
+## Tasks
+
+| The user wants | Run |
+|---|---|
+| Which project this folder belongs to, and when it was built | \`niro-local status\` |
+| Every project and its folders | \`niro-local projects\` |
+| Index this folder for the first time | \`niro-local status\` first (it lists the projects this folder can join), then \`niro-local init --project <name>\` (it adds the folder and builds it) |
+| Add another folder to the same project (it must be on the same branch, or have no branch) | in that folder: \`niro-local init --project <name>\` |
+| A project refuses this folder because of its branch | start a new one with the name the refusal gives: \`niro-local init --project <name>\` |
+| A second project uses this folder (a shared library) | \`niro-local init --project <second>\`; each project keeps its own copy, and a build refreshes them all |
+| Answer from another project's copy of this folder | \`niro-local build --project <name>\` |
+| Remove this folder from one project | \`niro-local remove --project <name>\` (confirm first); its copies in other projects stay |
+| This folder is on a new branch | nothing to choose: \`niro-local build\` makes a temporary copy of its project, and the old branch's index is kept |
+| Free the space of folders gone from disk | \`niro-local clean\` (\`--dry-run\` shows what it would remove); done by itself after 14 days |
+| Bring the graph up to date after edits | \`niro-local build\` (only what changed; \`--full\` rebuilds all) |
+${LLM_DOCS ? "| Reusable-code search and known issues for this folder | \`niro-local build --llm\` (makes LLM documentation in the background) |\n" : ""}| Stop indexing this folder | \`niro-local remove\` (confirm first) |
+| Is the graph file healthy | \`niro-local db status\`, or \`niro-local db check\` |
+| Ask one tool from the shell | \`niro-local ask <tool> key=value ...\` (\`niro-local ask\` lists them) |
+| A Niro error message, or how Niro works | \`niro guide --search <the message>\`, then \`niro guide <page>\` (the pages ship with niro, offline) |
+| Is the engine installed, and where | \`niro engine status\` (\`niro engine install\` puts it on this machine) |
+| Keep folders rebuilt as files change | \`niro watch\`, or \`niro service install\` to run it in the background |
+| What the MCP server was asked, waiting to be sent | \`niro-local journal\`; \`niro journal-send\` sends it |
+| What the builds found wrong with their own graph | \`niro-local audit\`; \`niro audit-send\` sends it |
+| Point the assistant back at the Niro cloud | \`niro mcp install --cloud\` (the user runs it, then restarts the assistant) |
+
+Report what each command printed, in plain words. A command that fails prints why and what to run;
+pass that on rather than guessing.
+`;
+
+module.exports = {
+  MODES,
+  modeFromArgs,
+  chooseMode,
+  localHook,
+  LOCAL_USER_PROMPT_COMMAND,
+  LOCAL_POST_COMPACT_COMMAND,
+  LOCAL_CLAUDE_MD_SECTION,
+  LOCAL_CLAUDE_MD_SECTIONS,
+  LLM_DOCS,
+  LOCAL_SKILL,
+  LOCAL_CLI_SKILL,
+  CLOUD_WALK,
+  LOCAL_WALK,
+  FAST_CLOUD_WALK,
+  FAST_LOCAL_WALK,
+  WORKTREE_SENTENCE,
+  OFFER_SENTENCE,
+  ENGINE_WORKTREE_SENTENCE,
+  ENGINE_OFFER_SENTENCE,
+  RELEASE_WORKTREE_SENTENCE,
+  RELEASE_OFFER_SENTENCE,
+};

package/src/mcp/localSkill.js

@@ -0,0 +1,189 @@
+/**
+ * The `niro-local` skill, written by `niro mcp install` in a release without the cloud
+ * (src/lib/release.js). It teaches an assistant the local commands: what is indexed on this
+ * machine, the plan's line limit, adding or removing a folder, and what it must leave to the user.
+ * The cloud `niro-cli` skill is not installed alongside it, so the assistant never reaches for a
+ * command this release does not have.
+ */
+const { USING_NIRO } = require("./usingNiro");
+
+const NIRO_LOCAL_SKILL = `---
+name: niro-local
+description: manage Niro Local from chat - which folders are indexed on this machine, the plan and its line limit, add a folder (niro init), rebuild one (niro build), stop indexing one (niro plan remove), and what to do over the limit
+---
+
+# Niro Local - manage it from chat
+
+Niro Local builds a code graph of the user's repositories ON THEIR MACHINE and answers your
+code questions from it through the \`niro\` MCP tools. You manage it by running the \`niro\`
+CLI in the shell and reading its \`--json\` output. Gather what you need in conversation, run
+ONE command, and report back in plain English.
+For a how-to question about Niro, run \`niro guide\` (every page with one line on what it answers), pick the
+page whose line fits, and answer from \`niro guide <page>\`. For a Niro error message,
+\`niro guide --search "<the message>"\` names the page that explains it. The pages ship with niro, offline.
+
+## Rules
+
+1. **Signed in first.** Run \`niro whoami --json\`. If \`authed\` is false, ask the USER to
+   run \`niro start\` themselves in a terminal. It opens a browser to sign in and approve the
+   terminal; you cannot do that for them. Never run \`niro start\`, \`niro login\` or
+   \`niro uninstall\` yourself: they are interactive or destructive.
+2. **Never guess the folder.** Commands act on the current folder unless given a path. Say
+   which folder you mean before acting on it.
+3. **Ask before removing.** \`niro plan remove <folder>\` stops indexing a folder and deletes
+   its graph (the code itself is untouched). Confirm with the user first, naming the folder.
+4. **Sharing is the user's choice.** Turning on code sharing (which lifts the Free line limit, and
+   makes the watcher send the files Niro indexes, redacted, by itself) is done by the user in the
+   console; never turn it on for them and never describe it as required. A folder is kept out with
+   \`niro share exclude <folder>\`; run it only when the user asks. Coverage findings (for each line the graph missed,
+   the method that holds it and its file's path, with secrets masked) and the tool-usage record are sent on every plan.
+
+## What to run
+
+### "Is this folder set up?" / "What is Niro doing?"
+\`niro status --json\` in the folder: \`indexed\`, \`last_build_at\`, \`plan\`, \`share_code\`,
+\`assistants\`, \`auto_sync\`. If the folder is not indexed, offer to add it (below).
+
+### "Which folders are indexed?" / "How many lines am I using?"
+\`niro plan --json\`: \`plan\`, \`max_lines\` (null means no line limit), \`lines_used\`,
+\`over_by\`, \`no_room\`, \`limit_url\`, and \`folders\` with each folder's \`lines\`, largest
+first. \`lines_used\` is the engine's own total: each repository counts once, by its largest
+checkout (two checkouts of one repo are not counted twice), and a folder inside another indexed
+folder is not counted again, so the folders' lines do not add up to it. Report usage as "X of Y
+lines", or "Unlimited Lines of Code" when \`max_lines\` is null.
+
+### "Add this repo" / "Index this folder"
+\`niro init\` in the folder, or \`niro init <path>\`. It adds the folder to the local engine if
+it is new and builds its graph; an indexed folder is built again. \`--project <name>\` joins
+that project (or starts it) instead of the one named after the folder: ask the user which, never
+choose for them. \`--force\` adds a folder with no build file, when the user says it is meant. It
+needs a machine already set up by \`niro start\`; if it says so, ask the user to run \`niro start\` once.
+
+### "Rebuild the graph" / "Update the graph"
+\`niro build\` in the folder, or \`niro build <path>\`. It rebuilds a folder already added; only
+changed files are reparsed. A folder not added yet is refused with a pointer to \`niro init\`.
+Never run the engine (\`niro-local\`) directly: it builds only when \`niro\` passes it the licence.
+
+### "What about my folders from Niro web?"
+This version indexes on this machine only and no longer uploads anything to Niro web. The folders
+that were set up with Niro web are listed in \`~/.niro/projects.web.json\`; a leftover
+\`.niro-project\` file in one is ignored. To use Niro on one of them, run \`niro init\` in it.
+
+### "Stop indexing X" / "Free up lines"
+Confirm the folder with the user, then \`niro plan remove <folder>\`. Then \`niro plan --json\`
+to show the new usage.
+
+### Over the limit
+A build starts only while the machine is under its line limit; the one that crosses it is
+allowed to finish, and after that builds stop until something changes. When \`no_room\` is
+true, explain the three ways on and let the user choose:
+- **Unlock unlimited lines on Free** by turning on sharing of redacted code (the user does
+  this in the console; give them \`limit_url\`).
+- **Request a Pro free trial** (no line limit, no sharing needed), also from \`limit_url\`.
+  Your code stays on this machine, except, for each line the audit flags, the whole method that
+  holds it and one line for each name it uses, sent with secrets masked and author and company names removed. A record of
+  which Niro tools your assistant used is also sent, to improve Niro and to show you its value.
+  Niro's tools answer your assistant from the graph on this machine and never send the contents
+  of your files.
+- **Stay under the limit**: remove folders they no longer need (\`niro plan remove\`).
+The graph already built keeps answering questions in the meantime; only new builds stop.
+
+### "What has Niro done for me?"
+\`niro impact\`: what Niro did over the last 7 and 30 days (\`--json\` for the numbers). Report it in plain words.
+
+### "Calls between my services are not connected"
+\`niro route-rule\` says where a path goes when the project does not (list, add, remove). Read
+\`niro guide configuring-a-folder\` first, and confirm the rule with the user before adding it.
+
+### "Can Niro read Scala?" / "Please support framework X"
+Niro reads ${require("../lib/languages").supportedList()}. For anything else (a language, a framework whose routes are missing, a tool),
+offer to ask Niro's team for it. Call the \`request_integration\` tool without \`confirm\` first: it sends
+nothing and returns what would be sent, from which account. Show that to the user, and call it again
+with \`confirm: true\` only after they say yes. Without the tool, the user can run
+\`niro request-integration <name>\` (\`--kind framework\` or \`--kind tool\`, \`--reason "<why>"\`); it asks
+before sending. The request is kept with their account.
+
+### "Which assistant is connected?" / "Connect another one"
+\`niro status --json\` lists \`assistants\`. To connect another, ask the user to run
+\`niro mcp install\` (it asks which assistant).
+
+### "Remove Niro from this machine"
+Tell the user to run \`niro uninstall\` themselves; it asks before removing anything. It takes
+out the assistant entries, the background watcher, \`~/.niro\` and \`~/.niro-local\` (with
+every graph), then prints the npm command that removes the CLI itself.
+
+## Reporting
+
+One or two sentences: what you ran, what it means, the next sensible step. Numbers with
+thousands separators. Never paste raw JSON at the user.
+`;
+
+/**
+ * `niro-skill` for a release without the cloud: how to use the MCP tools, naming only the tools
+ * the local engine serves (niro-local's `tools/list`). The cloud version names tools such as
+ * find_reusable_code and list_projects that the engine does not offer in this release. get_impact_analysis is served
+ * by the engine since 2026-11-02 and is named here (lead, 2026-11-06).
+ */
+const NIRO_SKILL_LOCAL = `---
+name: niro-skill
+description: Use Niro code-intelligence MCP tools to answer questions about THIS codebase - structure, call chains, blast radius / impact, entry points, HTTP calls, events and data access - from the graph Niro Local builds on this machine, instead of grep/read. Invoke whenever a task involves understanding, tracing, debugging, or assessing the impact of code, and for how-to questions about Niro itself or a Niro error message.
+---
+
+# Niro code intelligence (Niro Local)
+
+Niro Local indexes this repository into a graph on this machine (classes, methods, calls,
+HTTP endpoints and calls, events, data access) and serves it through the \`niro\` MCP tools.
+For any question answerable from the indexed code, prefer these tools over native grep/read.
+For anything outside it (config values, docs, runtime state), use your native tools.
+
+## Explore first - MUST FOLLOW
+
+Before you grep, glob or open files to hunt for something, check whether a Niro tool answers it:
+- \`code_grep\` for a text search across the indexed files, \`get_source_code\` to read a symbol.
+- \`resolve_name\` to turn a short or partial name into the exact class or method.
+- \`list_types\` and \`get_class_structure\` for what exists and what a class holds.
+- \`find_api_endpoints\` and \`find_handler\` for entry points (a route to its handler).
+Then use the connection tools to see how the code fits together BEFORE choosing a file to read:
+\`get_call_chain\` (what this calls), \`get_reverse_call_chain\` (who calls this),
+\`get_blast_radius\`, \`get_service_topology\`, \`get_exception_flow\`.
+
+## Check both directions before you change anything (MUST FOLLOW)
+
+Before you plan or start a change to existing code, establish:
+- **Upstream, what depends on this:** callers here and in other services (HTTP, events).
+- **Downstream, what this depends on:** what it calls, the data it touches, the events it sends.
+\`get_blast_radius\` answers both in one call; \`get_reverse_call_chain\` is the upstream view.
+\`get_impact_analysis\` is the lighter upstream-only view: the callers that break, several levels up, in one call.
+Name the callers you found in the plan you show the user, and after the edit verify them with
+tests or by reading them. The graph updates after the files are saved and rebuilt, so use the
+list you captured before the edit rather than re-querying to verify.
+
+## Flows across services
+
+- HTTP: \`find_outbound_http_calls\` (calls this code makes), \`find_api_endpoints\` (routes it
+  serves), \`get_service_topology\` (who talks to whom).
+- Events: \`list_events\`, \`get_event_producers_and_handlers\`, \`find_orphaned_events\`
+  (published with no handler, or handled with nothing publishing).
+- Data: \`list_data_resources\`, \`get_data_resource_usage\` (which code reads or writes a
+  table or collection).
+
+## When Niro does not apply - fall back silently
+
+1. **Tools missing.** Only call \`niro\` tools that are in your toolset.
+2. **Folder not indexed.** \`get_index_status\`, or a tool answering "not indexed on this
+   machine", means this folder has no graph. Use native tools, and tell the user once that
+   \`niro init\` in this folder would index it.
+3. **Out of scope.** Config, docs, runtime state and non-code questions go to native tools.
+4. **Graph behind.** A tool may say the graph is behind the files on disk; it rebuilds in the
+   background. Trust the files you just edited over the graph for those.
+
+## Beyond code questions
+
+${USING_NIRO}
+
+## Finishing
+
+When the task is done, call \`mark_task_complete\` if it is in your toolset.
+`;
+
+module.exports = { NIRO_LOCAL_SKILL, NIRO_SKILL_LOCAL };