@niroai/niro 0.16.0 → 0.18.0

package/docs/what-leaves-your-machine.md

@@ -0,0 +1,71 @@
+# What leaves your machine
+
+**Niro builds and answers from the graph on your computer.** A few things are sent to Niro's services. This page lists each one, what is in it, and what decides whether it is sent.
+
+## The short version
+
+Niro shows this text in `niro status` and `niro plan`:
+
+> Your code stays on this machine, except, for each line the audit flags, the method that holds it and one line for each name it uses, which are sent with secrets masked. 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.
+<!-- source: src/lib/planUsage.js:116-119 (AUDIT_CLAUSE, JOURNAL_SENTENCE, TOOLS_SENTENCE), :131-134 (sharingText) -->
+
+When **Help improve Niro** (code sharing) is on for your account, one more thing is sent, by itself: the code of every folder Niro indexes on your computer, redacted first. `niro plan` shows which way it is:
+
+```
+Help improve Niro  on
+  ✓ Your code is indexed and answered on this machine
+  ✓ Sent in the background: a record of which Niro tools ran, and the methods the audit flags with the lines they reference (secrets, author and company names removed)
+  ✓ Code shared in the background: the files Niro indexes, redacted here, deleted after processing, never used to train AI
+```
+
+With sharing off, the last line reads `✗ Code sharing is off`, and no code is shared.
+<!-- source: src/lib/planUsage.js sharingBlock; src/commands/plan.js -->
+
+## Everything that is sent
+
+| What | Where to | What is in it | When |
+|---|---|---|---|
+| **Sign-in** | Niro's account service | Your sign-in through the browser | When you run `niro start` or `niro login` |
+| **Your account details** | Niro's account service | Your sign-in, to read your account's email and identity | When you run `niro whoami` |
+| **Sign-out** | Niro's account service | Your sign-in token, so the service withdraws it | When you run `niro logout` |
+| **Old hosted projects check** (only on a computer that used hosted Niro before) | Niro's account service | Your sign-in, to list your hosted projects. For a hosted project that list no longer has, its id and its repositories' ids, to ask whether they still exist. No code | Every 6 hours, by the background watcher, while old hosted registrations are still listed in `~/.niro/projects.json` |
+| **Licence check** | Niro's billing service | A random number and your engine's version, with your sign-in | Each time the engine starts, and when its licence is renewed |
+| **Engine download** | Niro's billing service, then a download link | Nothing about your code. The download is checked against its published fingerprint (SHA-256) | When `niro start` or `niro engine install` installs the engine |
+| **Coverage audit** | Niro's audit service | For each line the build could not read: the file's path inside the repository, the method that holds the line, and one line per name it uses. Every other line is blank, and secrets are masked, in the path too. Separately, a list of the libraries and kinds of files the build saw, which carries no file names or paths | Every 5 minutes, on every plan. See [coverage-audit-and-consent.md](coverage-audit-and-consent.md) |
+| **Tool-usage record** | Niro's assistant service | Which tools your agent used, how long they took, failures, a short task summary, and the names, paths and search text asked about. Free text is masked first | Every 5 minutes |
+| **Shared code** (only while Help improve Niro is on) | Niro's indexing service | The files Niro indexes in each indexed folder: the source files it parses and the config, build and text files it reads. Never a file your `.gitignore` covers (unless git tracks it), a real `.env`, a key or key store, a tool's token file, or `node_modules` and other build output. Secrets are masked and author and company names removed first. The first time, a folder's whole indexed set; after that, only files that changed, and a note of files that were removed | Every 5 minutes, by the background watcher, only while your account's lease says sharing is on. A lease that cannot be read sends nothing. A folder you exclude with `niro share exclude <folder>` is never sent. See [licence-and-plans.md](licence-and-plans.md) |
+| **Whole repository** (only if you ask) | Niro's indexing service | The same files and the same redaction as shared code, for one folder. This is how you send a repository to Niro for support | Only when you type `niro audit-push-repo` and answer yes. It works with code sharing on or off, on every plan. For a folder you excluded with `niro share exclude`, it also asks "Send it anyway?" and sends only on yes |
+<!-- source: src/commands/login.js:1-14 and src/lib/api.js:10 (sign-in); src/commands/whoami.js:48 (/api/users/details); src/commands/logout.js:19-20 (token revoke); src/commands/watch.js:200, :379-384, :412-424 and src/commands/cleanup.js:185, :245-298 (the sweep: GET /api/projects every 6 hours, first after 60 s), src/commands/cleanup.js:174-182 and :459-466 with src/lib/agentApi.js:264-265, :288-297 (a gone project's id, and its repositories' ids, through GET /api/projects/{id} and GET /api/agent/repos/{gitId}/status); src/lib/lease.js:42-44, :172-176 (licence check); src/lib/engine.js:48, :93-96, :473, :551 (download); src/lib/auditUpload.js:27-30, :47, :168-244 and src/lib/redact.js:89-121 (audit); niro-local src/niro_local/cli.py:2413-2415, src/niro_local/audit/queue.py:838-846, src/niro_local/audit/collect.py:208-216 (each item carries the file's masked path); src/lib/journalUpload.js:9-37 and src/lib/planUsage.js comment above AUDIT_CLAUSE (journal); src/lib/repoPush.js (whole repository); src/lib/shareCode.js and src/lib/shareFiles.js (shared code: the gate, the engine's file list from `niro-local indexed-files`, the redaction, changed files only), src/lib/shareExclusions.js (`niro share exclude`); niro-local src/niro_local/share_files.py (which files); src/commands/watch.js startLocalUploads (every 5 minutes) -->
+
+## What is not sent
+
+- **The contents of your files, when your agent asks Niro a question.** The engine on your computer answers.
+<!-- source: src/lib/planUsage.js:118; src/mcp/server.js:359 -->
+- **Your code to a language model (an LLM).** This release does not include LLM documentation.
+<!-- source: src/lib/release.js:33 (llmDocs: false) -->
+- **The files of folders you once set up for hosted Niro.** A computer that used hosted Niro still lists those folders in `~/.niro/projects.json`. The background watcher never syncs them in this release: it uploads none of their files, also when that list changes. A folder the engine on your computer indexes is built there instead.
+<!-- source: src/commands/watch.js:238-240 (hostedFolders: no hosted folder without the cloud), :176 (the re-read when projects.json changes uses that list), :243 (so does start-up), :662-674 (startWatch: a locally indexed folder goes to the local watch, any other returns before the sync); src/lib/release.js:33 (cloud: false); test/watchHostedGuard.test.js -->
+- **Anything not in the table above.** The table lists every call `niro` makes to Niro's services in this release. How long each `niro start` step took is kept on your computer only. `niro upgrade` makes no check call of its own: it runs npm, which talks to the npm registry.
+<!-- source: the calls in this release: src/lib/api.js, src/lib/lease.js, src/lib/engine.js, src/lib/auditUpload.js, src/lib/journalUpload.js, src/lib/repoPush.js, src/lib/shareCode.js, src/commands/whoami.js:48, src/commands/logout.js:19-20, src/commands/cleanup.js:245-298 (src/lib/agentApi.js is used by `niro audit-push-repo` (src/lib/repoPush.js), by the background code sharing (src/lib/shareCode.js), and by the sweep's repository check, src/commands/cleanup.js:466; its sync and upload calls are reached otherwise only from the watcher's sync, which never starts without the cloud, src/commands/watch.js:671-674 and src/lib/release.js:33, and from the cloud commands, which this release does not register, src/index.js:475-482, as are the callers of src/lib/tempProject.js); src/lib/onboardingLog.js:1-6 ("Kept on the machine only"); src/commands/upgrade.js (npm install -g @niroai/niro@latest) -->
+
+## How secrets are hidden
+
+Everything that leaves is masked on your computer first: secret values are replaced with placeholders. In audit snippets and in shared code, the names of authors and companies are replaced with `<author>` and `<company>`. See [secrets-and-masking.md](secrets-and-masking.md).
+<!-- source: niro-local src/niro_local/redact/mask.py:1-75; src/lib/redact.js:1-18 -->
+
+## Niro's Data Processing Agreement
+
+Niro's Data Processing Agreement (DPA) sets out how Niro handles customer data. Version 3.0 is dated 2026-08-16. In short:
+<!-- source: Niro wiki, Legal collection, "Data Processing Agreement" v3.0 (status "Current. Authoritative version", classification "Public. Issued to customers", last_reviewed 2026-08-16) -->
+
+- **No training on your content.** Niro does not use your code to train or fine-tune an AI model. (Clause 10.1.)
+- **Outside AI providers.** Where Niro uses an outside AI provider, the provider is set up so that it does not keep your content or train on it. A masking step removes secrets and common personal data first. The DPA says this is best effort, not a guarantee. (Clause 10.2.)
+- **Small extracts kept to fix parsing.** To fix a parsing defect, Niro may keep a small extract of code, masked, for at most 90 days. (Clause 10.3.)
+- **Usage signals.** Niro records whether its answers were useful. Niro may use these signals to improve the service, including its own models. (Clause 10.4.)
+- **Opting out.** You can ask in writing to switch off the extracts in 10.3 and the signals in 10.4. Niro confirms within 10 business days. (Clause 10.5.)
+- **Breaches.** Niro tells you within 72 hours of learning about a data breach that affects your data. (Clause 7.1.)
+- **When you stop using Niro.** You can ask for your data back within 30 days. After that, Niro deletes it within 30 days. Copies in backups stay protected until the normal backup cycle deletes them. (Clause 8.)
+- **Account data** is deleted 90 days after the account is closed. (Annex 1.)
+
+To delete your account, email **help@niro.ai**. Ask the same address for a copy of the DPA.
+<!-- source: account deletion by email to help@niro.ai: Niraj, 2026-11-10 -->

package/docs/where-things-are-stored.md

@@ -0,0 +1,59 @@
+# Where things are stored
+
+**Niro keeps its files in two folders in your home folder.** `~/.niro` belongs to the `niro` command. `~/.niro-local` belongs to the local engine, which holds the graph. Both are readable by your user account only.
+<!-- source: src/lib/credentials.js:51-72 (credentials 0600, folder 0700); niro-local src/niro_local/registry.py:53-104 (home 0700, files 0600, umask 077) -->
+
+## `~/.niro`
+
+| File or folder | What it holds |
+|---|---|
+| `credentials.json` | Your sign-in. Readable by you only |
+| `config.json` | Settings: the service addresses and the console address you signed in through. See [reference-config-files.md](reference-config-files.md) |
+| `bin/<version>/` | The downloaded local engine. Set `NIRO_ENGINE_HOME` to keep it elsewhere |
+| `local-worktrees.json` | The worktrees the watcher has seen, and its build retries |
+| `onboarding.json` | How long each step of `niro start` took, and how it ended. Kept on this computer only |
+| `periodic.json` | When each regular job last ran |
+| `audit-repos.json` | Folders sent with `niro audit-push-repo` or shared in the background, and the workspace each went to |
+| `shared-code.json` | For code sharing: per folder, a fingerprint (SHA-256), size and time of each file last sent, so only changed files are sent again. No file contents. Readable by you only |
+| `share-excluded.json` | The folders kept out of code sharing (`niro share exclude`). Readable by you only |
+| `journal-refused/` | Tool-usage records the service refused, kept for you to look at |
+| `receipts/` | Used by older versions only. Removed when you remove Niro from Claude Code, or by `niro uninstall` |
+| `impact/` | The recent-edits log the impact check uses |
+| `receipts-off`, `impact-gate-off` | Empty files whose presence turns the end-of-task line or the impact check off |
+| `projects.json` | Used by hosted Niro only |
+<!-- source: src/lib/credentials.js:51-72; src/lib/config.js:16-38; src/lib/engine.js:44; src/lib/localWorktrees.js:28; src/lib/onboardingLog.js:1-13; src/lib/periodicClaim.js:29-30; src/lib/repoPush.js:78; src/lib/journalUpload.js:120-129; src/lib/receiptStore.js:64-75 and src/mcp/teardown.js:396 (receipts/ is removed with Niro's Claude Code entry); src/lib/impactLog.js:59-92; src/lib/receiptStore.js:33; src/lib/watchState.js:1-30 -->
+
+## `~/.niro-local`
+
+Set `NIRO_LOCAL_HOME` to keep this folder elsewhere.
+<!-- source: niro-local src/niro_local/registry.py:40-51 -->
+
+| File | What it holds |
+|---|---|
+| `graph.db` | The graph, for every project on this computer |
+| `build-state.db` | What each build needs to be quick next time: a fingerprint (hash), size and time of each file, and what reading each file found |
+| `registry.db` | Your projects, their folders and branches, and your settings for them |
+| `journal.db` | The record of which tools your agent used, waiting to be sent |
+| `audit-queue.db` | Coverage audit findings, waiting to be sent |
+| `docs.db` | For LLM documentation, which this release does not include |
+| `indexed-folders`, `locks/` | The list of indexed folders, and lock files that stop two builds from clashing |
+<!-- source: niro-local src/niro_local/home_files.py:16-17; src/niro_local/registry.py:132, :167-171; src/niro_local/journal/store.py:194; src/niro_local/audit/queue.py:654; src/niro_local/reuse/store.py:109; src/niro_local/build/state.py:1-40 -->
+
+There is one `graph.db` and one `build-state.db` for all projects. To check the graph file, run `niro db status`. To check that it opens, run `niro db check`.
+<!-- source: niro-local src/niro_local/home_files.py:1-8; src/commands/engineRoutes.js:36 (db) -->
+
+**Is your source code stored?** The graph does not keep your source. It keeps names, places and links. The build state keeps fingerprints of files, and what reading them found. That can include short values written in the code, such as a default value. All of it stays on this computer.
+<!-- source: niro-local src/niro_local/build/state.py:1-40; niro-local docs/NIRO-LOCAL-ISSUES.md:863 (a default written in source stays in build-state.db, on the machine only) -->
+
+## Files written into your coding agents
+
+`niro mcp install` writes into each agent's own settings. The files are listed on each agent's page, for example [agent-cursor.md](agent-cursor.md).
+
+## The background watcher
+
+The watcher is run by PM2, which keeps its list of programs in `~/.pm2/dump.pm2`. Niro makes that file readable by you only. On macOS, starting the watcher at login uses a file in `~/Library/LaunchAgents`.
+<!-- source: src/lib/service.js:36, :120, :264, :316 -->
+
+## What `niro uninstall` removes
+
+It removes `~/.niro`, `~/.niro-local`, the watcher and the agent settings. See [uninstall.md](uninstall.md).

package/docs/worktrees-and-branches.md

@@ -0,0 +1,55 @@
+# Worktrees and branches
+
+**Niro keeps one graph per folder and per branch.** When you switch branch, Niro answers from that branch's graph. A git worktree is a second folder checked out from the same repository. When you open a new worktree, Niro builds it too.
+
+## How Niro knows your branch
+
+Niro reads the file `.git/HEAD` in the folder. It never runs git.
+<!-- source: niro-local src/niro_local/repository_identity.py:1-24, :219-251 -->
+
+
+- **Detached HEAD.** If you are not on a named branch, Niro answers from the folder's last used graph, and says so.
+- **No git.** A folder outside git has no branch. Give it one when you add it: `niro init --branch <name>`.
+<!-- source: niro-local src/niro_local/repository_identity.py:1-24, :219-251; src/niro_local/mcp/server.py:724; src/index.js:490-502 (--branch) -->
+
+## Switching branch
+
+- **To a branch Niro has seen before.** Niro switches to that branch's graph. Each answer then carries one line saying which project and build it came from.
+<!-- source: niro-local src/niro_local/mcp/server.py:701-757, :734 -->
+- **To a new branch of a repository Niro already indexes.** Niro makes a **temporary project** for it. It copies only this folder's graph from the main project, so the first answers are quick, and then builds the folder from its own files. Until that build is done, answers carry a note saying the graph was copied and not yet built.
+<!-- source: niro-local src/niro_local/temporary.py:175-240; src/niro_local/offer.py:393-397; src/niro_local/mcp/server.py:775 -->
+  - It is named after the project and the branch, for example `shop-feature-login`.
+  - Your settings for the folder are copied with it: route rules, environment values and base address.
+<!-- source: niro-local src/niro_local/temporary.py:175-184, :187-240 -->
+- **All folders of one project must be on one branch.** If they are not, Niro says "A project's folders must all be on one branch".
+<!-- source: niro-local src/niro_local/offer.py:243; src/niro_local/onboard.py:267 -->
+
+## New worktrees
+
+The background watcher builds a new worktree of a repository Niro already indexes. Worktrees that already existed when Niro first saw the repository are noted, but not built. Build one of those with `niro build` in its folder.
+<!-- source: src/lib/localWorktrees.js:1-21; src/commands/watch.js:278-292 -->
+
+If a worktree's build fails, the watcher tries again after 2 minutes and after 10 minutes. After 3 tries it stops, and logs "Gave up building <folder> after N tries; run `niro build` there to see why."
+<!-- source: src/lib/localWorktrees.js:71-72, :198 -->
+
+## Which folder an agent's questions are about
+
+**Niro's tools answer for the folder the agent's session started in.** If you work in another folder (another worktree, or another service), two things help:
+
+- run `niro status` there to see whether it is indexed;
+- run `niro build <folder>` after editing it.
+<!-- source: src/mcp/localMode.js:39 (RELEASE_WORKTREE_SENTENCE) (RELEASE_WORKTREE_SENTENCE) -->
+
+## Clean-up
+
+Niro removes old copies by itself. It does this at the end of a build, never while answering a question:
+<!-- source: niro-local src/niro_local/cleanup.py:8-11 ("A build ends by calling `sweep`"; "An MCP answer never touches any of this") -->
+
+
+- **A temporary project** is removed after 14 days with no build and no question. It is kept while a build is running, while one of its folders is on that branch, or while a folder of it is missing.
+- **The graph of a folder deleted from disk** is removed 14 days after Niro first saw it missing.
+- **To remove missing folders now,** run `niro clean`.
+<!-- source: niro-local src/niro_local/cleanup.py:37-58, :116-147; src/commands/engineRoutes.js:35 (clean) -->
+
+Change the 14 days with `NIRO_LOCAL_BRANCH_INDEX_IDLE_DAYS` and `NIRO_LOCAL_MISSING_FOLDER_DAYS`. Set either to 0 to turn that clean-up off.
+<!-- source: niro-local src/niro_local/cleanup.py:37-40, :47-58 -->

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@niroai/niro",
-  "version": "0.16.0",
-  "description": "Niro \u2014 one package: the niro CLI plus the Niro MCP server (code intelligence for AI coding assistants).",
+  "version": "0.18.0",
+  "description": "Niro — one package: the niro CLI plus the Niro MCP server (code intelligence for AI coding assistants).",
   "keywords": [
     "niro",
     "mcp",
@@ -21,12 +21,14 @@
   },
   "main": "src/index.js",
   "scripts": {
-    "test": "node --test"
+    "test": "node --require ./test/_noRealDaemon.js --require ./test/_cloudOn.js --test"
   },
   "files": [
     "bin",
     "src",
     "docs/*.md",
+    "docs/llms.txt",
+    "docs/llms-full.txt",
     "README.md",
     "CHANGELOG.md"
   ],

package/src/commands/add-repo.js

@@ -26,6 +26,7 @@ const color = require("../lib/color");
 const watchDaemon = require("../lib/watchDaemon");
 const { login } = require("./login");
 const onboardTarget = require("../lib/onboardTarget");
+const cloudGuard = require("../lib/cloudGuard");
 
 async function addRepo(pathArg, opts = {}) {
   const targetRaw = pathArg || ".";
@@ -52,6 +53,10 @@ async function addRepo(pathArg, opts = {}) {
       process.exitCode = 1;
       return;
     }
+    // Before the login, for the same reason as the gate below: this command uploads the
+    // folder, and a folder the engine on this machine already indexes must not be uploaded
+    // and indexed a second time.
+    if (await cloudGuard.refuseIfIndexedLocally(targetDir, { command: "add repo" })) return;
     // Same onboarding gate as `niro init` — this command uploads a folder too, so it must
     // refuse $HOME / the filesystem root on the same terms. A folder this backend already
     // has a repo for is exempt from the BUILD-DESCRIPTOR half: that half gates new

package/src/commands/auditSend.js

@@ -0,0 +1,67 @@
+/**
+ * `niro audit-send` — hand the local engine's coverage-audit findings to niro-audit.
+ *
+ * The engine finds the places where the graph does not match the source, during the build it
+ * was already doing, and queues them. This sends them. It exists as a command of its own so
+ * the path can be run and watched by hand; in normal use the watcher calls the same library
+ * after a build, next to the MCP journal upload.
+ *
+ * Prints counts and never a payload: those carry the customer's source.
+ */
+const auditUpload = require("../lib/auditUpload");
+const color = require("../lib/color");
+
+async function auditSend(opts = {}) {
+  const limit = Number(opts.limit) || 50;
+  console.log(`Sending audit findings to ${auditUpload.auditUrl()}`);
+
+  const result = await auditUpload.uploadPending({ limit });
+  if (result.skipped) {
+    console.log(`  Nothing sent: ${result.skipped}.`);
+    return result;
+  }
+
+  const parts = [];
+  if (result.submitted) parts.push(`${result.submitted} file(s) submitted`);
+  if (result.duplicate) parts.push(`${result.duplicate} already held`);
+  if (result.resolved) parts.push(`${result.resolved} closed as clean`);
+  if (result.catalogs) parts.push(`${result.catalogs} catalogue list(s) of extensions and libraries sent`);
+  if (result.notText) parts.push(`${result.notText} flagged file(s) dropped, not UTF-8 text`);
+  if (result.notSnippet) parts.push(`${result.notSnippet} flagged file(s) dropped, could not be sent as a snippet`);
+  if (parts.length === 0 && !result.unmasked) parts.push("nothing waiting");
+  // Only when there is something to say: it printed a bare "  " line before.
+  if (parts.length > 0) console.log(`  ${parts.join(", ")}`);
+
+  if (result.unmasked) {
+    // Lines from an engine older than on-machine masking: never sent unmasked, so they wait.
+    console.log(color.yellow(
+      `  ${result.unmasked} item(s) not sent: the local engine is too old to mask secrets. Run \`niro upgrade\`.`
+    ));
+  }
+
+  if (result.catalogsWaiting) {
+    // An audit service from before the catalogue route: the lists wait on this machine until it takes them.
+    console.log(`  ${result.catalogsWaiting} catalogue list(s) kept: the audit service does not take them yet`);
+  }
+
+  if (result.closedNothing) {
+    // A resolve that matched nothing answers 200, so without this it would read as a clean
+    // close. It usually means the server never had an open item for that file.
+    console.log(
+      `  ${result.closedNothing} close request(s) matched nothing on the server`
+    );
+  }
+
+  if (result.failed) {
+    // Loud, because a silent failure here looks like a clean run and the findings would sit
+    // in the queue for ever. They stay queued on purpose and are retried next time.
+    console.log(color.yellow(`  ${result.failed} item(s) could not be sent, still queued:`));
+    for (const failure of result.failures.slice(0, 5)) console.log(`    ${failure}`);
+    if (result.failures.length > 5) {
+      console.log(`    ... and ${result.failures.length - 5} more`);
+    }
+  }
+  return result;
+}
+
+module.exports = { auditSend };

package/src/commands/build.js

@@ -3,6 +3,7 @@ const credentials = require("../lib/credentials");
 const spinner = require("../lib/spinner");
 const color = require("../lib/color");
 const { resolveProjectId } = require("./_resolveProject");
+const cloudGuard = require("../lib/cloudGuard");
 
 const TERMINAL = new Set(["COMPLETED", "FAILED", "CANCELLED"]);
 
@@ -15,6 +16,11 @@ function colorizeStatus(st) {
 }
 
 async function build(projectIdArg, opts = {}) {
+  // Before the credentials check, so a folder indexed on this machine is refused without
+  // first costing a login. Keyed on the FOLDER and not on the project id: a cloud build
+  // triggered from inside a locally indexed folder is the mistake this catches, whether the
+  // id was typed or came from the `.niro-project` pin.
+  if (await cloudGuard.refuseIfIndexedLocally(process.cwd(), { command: "build" })) return;
   credentials.requireCreds();
   const projectId = await resolveProjectId(projectIdArg, { apiUrl: opts.apiUrl });
   const force = opts.fullRebuild !== false;

package/src/commands/docsSend.js

@@ -0,0 +1,73 @@
+/**
+ * `niro docs-send`: send the local engine's documentation requests through Niro, once.
+ *
+ * For folders built with `niro-local build --llm`. The engine writes one request per batch of up
+ * to 12 methods; this sends them to ai-assistant with this machine's login and its licence lease,
+ * and hands the answers back to the engine. The watch daemon does the same about every ten
+ * minutes; this command exists so the path can be run and watched by hand.
+ *
+ * Prints counts and never a request or an answer: both carry or describe the customer's code.
+ */
+const docsUpload = require("../lib/docsUpload");
+const { assistantUrl } = require("../lib/journalUpload");
+const color = require("../lib/color");
+
+/** What a stopped round means, in words for a person. */
+const STOPPED = {
+  busy: "Another documentation run is going on this machine; this one did nothing.",
+  "no-engine": "The local engine is not installed on this machine, so there is nothing to send.",
+  "engine-refused": "The local engine did not hand over any requests",
+  "no-lease": "Could not get a licence lease from Niro, so nothing was sent",
+  "lease-refused": "Niro would not issue a licence lease, so nothing was sent",
+  unauthorized: "Niro did not accept this machine's login. Run `niro login` and try again.",
+  forbidden: "Niro refused documentation for this account",
+};
+
+function parseLimit(value) {
+  if (value === undefined) return docsUpload.DEFAULT_LIMIT;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1) {
+    throw new Error(`--limit must be a whole number of 1 or more, not "${value}".`);
+  }
+  return n;
+}
+
+async function docsSend(opts = {}) {
+  const limit = parseLimit(opts.limit);
+  console.log(`Sending documentation requests to ${assistantUrl()}`);
+
+  const result = await docsUpload.sendPending({ limit, log: console.log });
+
+  if (result.stopped) {
+    const text = STOPPED[result.stopped] || `Stopped (${result.stopped})`;
+    const line = result.reason && !text.endsWith(".") ? `${text}: ${result.reason}` : text;
+    console.log(color.yellow(`  ${line}`));
+  }
+  if (result.model && result.model.error) {
+    console.log(color.yellow(`  The embedding model could not be fetched: ${result.model.error}`));
+  } else if (result.model && result.model.fetched) {
+    console.log(`  Fetched ${result.model.fetched} embedding model file(s)`);
+  }
+  if (result.marked === 0) {
+    console.log("  no folder is built with --llm, so there is nothing to document");
+  } else if (result.lines === 0 && !result.stopped) {
+    console.log("  nothing waiting");
+  } else if (result.lines > 0) {
+    const parts = [`${result.sent} batch(es) sent`];
+    // Not said when the import failed: the engine stored nothing, so nothing was documented.
+    if (!result.importFailed) parts.push(`${result.documented} method(s) documented`);
+    if (result.waiting) parts.push(`${result.waiting} batch(es) waiting after earlier failures`);
+    console.log(`  ${parts.join(", ")}`);
+  }
+  if (result.failed) {
+    console.log(color.yellow(`  ${result.failed} batch(es) failed and will be asked for again later:`));
+    for (const failure of result.failures.slice(0, 5)) console.log(`    ${failure}`);
+    if (result.failures.length > 5) console.log(`    ... and ${result.failures.length - 5} more`);
+  }
+  if (result.importFailed) {
+    console.log(color.yellow(`  The engine could not store the answers: ${result.importFailed}`));
+  }
+  return result;
+}
+
+module.exports = { docsSend, parseLimit };

package/src/commands/engine.js

@@ -0,0 +1,120 @@
+/**
+ * `niro engine` — put the local engine on this machine, or say where it is.
+ *
+ * The local engine indexes a repository on the developer's own machine instead of uploading it.
+ * It is a compiled binary of its own, not part of this npm package, so it is downloaded on
+ * first use from Niro (Niraj, 2026-10-14) and cached under ~/.niro/bin.
+ *
+ * **Why this command exists at all**, when the plan says the download is called from the
+ * wizard, from `niro build` and from the MCP bridge: none of those three asks for the engine
+ * yet. `niro build` still builds in the cloud, and whether it keeps that option is an open
+ * decision; the bridge does not route to a local graph until the routing phase. Downloading an
+ * engine from a command that does not use it would be 60 MB nobody asked for. So the download
+ * is deliberate for now, and the three call sites come with the phases that need them.
+ */
+const engine = require("../lib/engine");
+const graphCheck = require("../lib/graphCheck");
+const color = require("../lib/color");
+
+/** How each way of finding the engine is named to the developer. */
+const WHERE_FROM = {
+  env: " (from NIRO_LOCAL_BIN)",
+  path: " (on your PATH)",
+  cache: "",
+};
+
+async function install(opts = {}) {
+  const already = engine.installed();
+  let where;
+  try {
+    where = await engine.ensure({
+      log: (line) => console.log(`    ${line}`),
+      force: !!opts.force,
+      latest: true,
+    });
+    if (already && where === already) {
+      // The published version is the one here. Asked of the service each time, so an old one is never left in place
+      // by being "already here".
+      console.log(`    The local engine is here: ${already}`);
+      await sayIfItCannotRun();
+      return;
+    }
+  } catch (err) {
+    if (already && !opts.force) {
+      // No connection, or the service said no: the engine here keeps working.
+      console.log(`    The local engine is here: ${already}`);
+      console.log(`    Could not check for a newer one: ${err.message}`);
+      await sayIfItCannotRun();
+      return;
+    }
+    // An answer from Niro, not a fault: the plan does not include the engine, or no engine is
+    // published for this platform yet. Said in the service's own words, with no route and no
+    // status code, and the command still ends non-zero so a script can tell.
+    if (!err || err.code !== "EENGINEREFUSED") throw err;
+    console.log(`    ${err.message}`);
+    console.log("    Nothing was installed.");
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`    ${color.green("✓")} The local engine is ready: ${where}`);
+  await sayIfItCannotRun();
+}
+
+/**
+ * The engine is here. Can it open its graph on this machine? Asked after the download, because
+ * the question is put to the engine itself (`niro-local db check`). When it cannot, its own
+ * words are shown and the command ends non-zero; nothing else is offered and nothing is
+ * uploaded (Niraj, 2026-10-31, D2: the cloud offer is dropped).
+ */
+async function sayIfItCannotRun() {
+  const usable = await graphCheck.graphDatabaseUsable();
+  if (usable.ok || usable.missing) return;
+  console.log("");
+  console.log(color.yellow("    The local engine cannot open its graph on this machine:"));
+  for (const line of usable.problem.split("\n")) {
+    console.log(`    ${line}`);
+  }
+  console.log("");
+  process.exitCode = 1;
+}
+
+async function status() {
+  let which = null;
+  try {
+    which = engine.label();
+  } catch (err) {
+    console.log(`    ${color.red("✗")} ${err.message}`);
+    return;
+  }
+  const found = engine.resolve();
+  console.log(`    platform   ${which}`);
+  if (!found) {
+    console.log(`    engine     not installed. Run:  niro engine install`);
+  } else {
+    // Where it came from is said out loud, because the three sources behave differently:
+    // only the cache is replaced by `niro engine install`, and a developer who has forgotten
+    // an exported variable has no other way to find out which engine is answering.
+    console.log(`    engine     ${found.path}${WHERE_FROM[found.source] || ""}`);
+    // A machine holds one version. The cache is what niro starts; a copy on the PATH is what a person gets by typing
+    // the name, and an older one refuses a home a newer one has used.
+    const onPath = found.source === "path" ? null : engine.onThePath(engine.EXECUTABLE);
+    if (onPath && onPath !== found.path) {
+      console.log(`    ${color.yellow("another")}    ${onPath} is also on your PATH. niro does not use it. Remove it, so`);
+      console.log("               that one version is on this machine.");
+    }
+  }
+  console.log(`    cache      ${engine.home()}`);
+  // Whether it can actually serve a graph here, which is a different question from whether
+  // it is installed.
+  const usable = await graphCheck.graphDatabaseUsable();
+  if (usable.ok) {
+    console.log(`    database   ready`);
+  } else if (usable.missing) {
+    console.log(`    database   unknown until the engine is installed`);
+  } else {
+    const first = usable.problem.split("\n")[0].replace(/^error:\s*/, "");
+    console.log(`    database   cannot run: ${first}`);
+  }
+}
+
+module.exports = { install, status };

package/src/commands/engineRoutes.js

@@ -0,0 +1,105 @@
+/**
+ * The local engine's commands, offered as niro commands (Niraj, 2026-11-06: "ensure all commands and
+ * options of niro-local are available to niro so that if user fires niro instead of niro-local, they
+ * are routed to niro-local").
+ *
+ * In a release, people have `niro` and not `niro-local`: the engine sits in niro-cli's cache, and a
+ * released engine builds and answers only with the licence niro passes it. So `niro env list`,
+ * `niro ui`, `niro ask get_call_chain method_fqn=X` and the rest run the engine with exactly the
+ * words typed after the command name, attached to the person's terminal, and niro exits with the
+ * engine's exit code.
+ *
+ * The rule for names (approved by Niraj, 2026-11-06, "2 okay with your advice"):
+ *   - niro keeps its own meaning for the four names both have: `init`, `build`, `status`, `mcp`.
+ *     `niro build` also takes the engine's `--full` and `--project`, and `niro status` shows the
+ *     engine's status after its own (both in src/index.js).
+ *   - every other engine command passes straight through, below.
+ *   - `remove` and `projects` are free only while the cloud is off: with it on they are niro's
+ *     cloud commands, so they are routed only then.
+ *
+ * Only `ask` and `docs` carry the licence: of the engine's commands, those are the ones that
+ * refuse without one (`build` and `mcp` too, but those names are niro's). The rest write nothing to
+ * the graph, and a lease request each time someone lists their settings is not worth making.
+ */
+const localEngine = require("../lib/localEngine");
+
+/** name, what it does (the engine's own help line), and whether it needs the licence. */
+const ENGINE_COMMANDS = [
+  ["ask", "Ask one graph tool from the shell and print its answer (no tool: list them). `niro ask --help` for more.", true],
+  ["ui", "Look at a folder's graph in a browser; runs until you stop it (Ctrl-C).", false],
+  ["env", "The settings this folder's code reads: find them, list them, and give them values for the graph.", false],
+  ["base-url", "Show or change the address this folder's service answers on.", false],
+  ["route-rule", "Say where a path goes when the project does not: list, add, remove, replace, unconnected.", false],
+  ["modules", "Which folders inside this one are their own deployable.", false],
+  ["clean", "Remove the index of every folder missing from disk, now, and give the space back.", false],
+  ["db", "The graph file: its status, a check that it opens, or its removal.", false],
+  ["journal", "What the MCP server was asked, waiting to be sent (`niro journal-send` sends it).", false],
+  ["audit", "What the last builds found wrong with their own graph (`niro audit-send` sends it).", false],
+  ["impact", "What Niro did for you in the last 7 and 30 days: numbers and good moments (`--days N`, `--project <name>`, `--json`).", false],
+  ["docs", "LLM documentation for folders built with --llm: requests out, answers in.", true],
+];
+
+/** Free only while the cloud is off; niro's own cloud commands when it is on. */
+const LOCAL_ONLY_RELEASE_COMMANDS = [
+  ["remove", "Stop indexing a folder: its graph is removed and it is forgotten (`--path <folder>`, `--project <name>`).", false],
+  ["projects", "List every project on this machine and its folders (`--json` for a program).", false],
+];
+
+/**
+ * The words typed after `name`, untouched, for the engine. Read from the command line itself rather
+ * than from what the parser collected, which would reorder options and operands. niro's one option
+ * before a command, `--api-url`, is refused for every command but login before this runs.
+ */
+function argsAfter(name, argv = process.argv) {
+  const at = argv.indexOf(name, 2);
+  return at === -1 ? [] : argv.slice(at + 1);
+}
+
+/** Said when there is no engine to start. Same words as `niro init` and `niro build`. */
+const NO_ENGINE = "The local engine is not installed. Run `niro start` once to set up this machine.";
+
+/**
+ * Run engine command `name` with `args`, attached, and set niro's exit code to the engine's.
+ * An engine stopped by a signal stops niro with the same signal, so a shell sees the same status
+ * it would have seen from the engine.
+ */
+async function routeToEngine(name, args, { licensed, runAttached = localEngine.runAttached, kill = process.kill } = {}) {
+  const result = await runAttached([name, ...args], { licensed });
+  if (result.error) {
+    console.error(result.error.code === "ENOENT" ? NO_ENGINE : `Could not start the local engine: ${result.error.message}`);
+    process.exitCode = 1;
+    return result;
+  }
+  if (result.signal) {
+    const number = require("os").constants.signals[result.signal];
+    process.exitCode = 128 + (number || 0);
+    try {
+      kill(process.pid, result.signal);
+    } catch {
+      // The exit code above stands.
+    }
+    return result;
+  }
+  process.exitCode = result.code == null ? 1 : result.code;
+  return result;
+}
+
+/**
+ * Register the routed commands on `program`. Each takes any words and options and leaves `--help`
+ * to the engine, so `niro env --help` shows the engine's own options.
+ */
+function register(program, { cloud, llmDocs }) {
+  const commands = cloud ? ENGINE_COMMANDS : [...ENGINE_COMMANDS, ...LOCAL_ONLY_RELEASE_COMMANDS];
+  for (const [name, description, licensed] of commands) {
+    program
+      .command(name, { hidden: name === "docs" && !llmDocs })
+      .description(description)
+      .argument("[args...]")
+      .helpOption(false)
+      .allowUnknownOption(true)
+      .allowExcessArguments(true)
+      .action(() => routeToEngine(name, argsAfter(name), { licensed }));
+  }
+}
+
+module.exports = { ENGINE_COMMANDS, LOCAL_ONLY_RELEASE_COMMANDS, argsAfter, register, routeToEngine, NO_ENGINE };