@niroai/niro 0.17.0 → 0.18.0

package/docs/faq-install-and-setup.md

@@ -0,0 +1,103 @@
+# FAQ: install and setup
+
+### Which computers does Niro run on?
+macOS and Linux, on Intel and ARM processors. Windows is supported, and the details are coming.
+<!-- source: src/lib/engine.js:79-90; Windows: Niraj, 2026-11-10 -->
+
+### I am on Windows. Setup says "Niro Local runs on macOS and Linux. On Windows, use WSL 2."
+Windows support is coming to this guide. Until it arrives, follow the message: install WSL 2 (Windows Subsystem for Linux, which runs Linux inside Windows), and run Niro inside it.
+<!-- source: src/commands/start.js:165-167 (the message); Windows supported, details coming: Niraj, 2026-11-10 -->
+
+### "Node vX. Niro needs Node 18 or newer."
+Install Node.js 18 or newer, then run `niro start` again.
+<!-- source: src/commands/start.js:178; src/lib/machineCheck.js:13 -->
+
+### "N GB free. A large repository's graph may need more."
+This is a warning, not a stop. It appears when less than 2 GB of disk is free. Free some space if you are indexing a large repository.
+<!-- source: src/commands/start.js:175; src/lib/machineCheck.js:14 -->
+
+### "`niro start` is interactive and there is no terminal to prompt on."
+`niro start` asks questions, so it needs a terminal. Run it in a terminal window. For a machine with no person at it, see [connect-ci.md](connect-ci.md).
+<!-- source: src/commands/start.js:97-104 -->
+
+### "Global install failed. Install it yourself, then run niro start"
+You ran Niro through `npx`, and Niro tried to install itself for good, so that background updates keep working after npx clears its cache. That failed, often for lack of permission. Run `npm install -g @niroai/niro`, then `niro start`.
+<!-- source: src/commands/start.js:537-552 -->
+
+### "<folder> is your home folder ... Niro will not index it."
+Niro refuses your home folder, a folder above it, the root of the disk and system folders, because it would index everything below as one project. Run `niro start` from your project's folder instead. `--force` does not change this.
+<!-- source: src/lib/onboardTarget.js:81-104; niro-local src/niro_local/onboard.py:137-140 -->
+
+### "<folder> does not exist." or "<folder> is a file, not a folder."
+Check the path you gave, then run the command again.
+<!-- source: src/commands/start.js:579-598 -->
+
+### "Nothing that looks like a project in <folder>."
+Niro looks for a build file (such as `package.json`, `pom.xml` or `go.mod`) in the folder, or up to three levels below it. If your folder really is a project without one, add it anyway with `niro init --force`.
+<!-- source: niro-local src/niro_local/onboard.py:154-159 -->
+
+### "It holds more than 60 repositories, too many to index as one folder."
+Add the repositories one by one, or add a smaller folder.
+<!-- source: niro-local src/niro_local/offer.py:251; src/niro_local/modules/resolve.py:61 -->
+
+### "It holds no source file niro-local can read."
+The folder has no file in a language Niro reads. See [supported-overview.md](supported-overview.md).
+<!-- source: niro-local src/niro_local/offer.py:262 -->
+
+### I ran `niro start` again. Will it redo everything?
+No. It carries on from the first step that did not finish.
+<!-- source: src/commands/start.js:61 (a second run resumes at the first unfinished step) -->
+
+### I typed `niro` on its own and it started setup.
+Before you have signed in, `niro` on its own runs `niro start`.
+<!-- source: src/index.js:468-470 -->
+
+### "The local engine is not installed. Run `niro start` once to set up this machine."
+The engine (the program that builds and answers from the graph) is missing. Run `niro start`, or `niro engine install`.
+<!-- source: src/commands/engineRoutes.js:58; src/commands/initLocal.js:43 -->
+
+### "Downloading the local engine failed: HTTP n" or "The engine manifest came back incomplete."
+The download did not finish. Check your connection, then run `niro engine install`.
+<!-- source: src/lib/engine.js:415, :475 -->
+
+### "The local engine that arrived is not the one Niro published, so it was not installed."
+The downloaded file did not match its published fingerprint (SHA-256), so Niro threw it away. Try again. If it keeps happening, tell Niro (help@niro.ai).
+<!-- source: src/lib/engine.js:551 -->
+
+### "Another process has been downloading the local engine for too long."
+A lock folder from an earlier download is still there. If nothing else is downloading, remove the lock folder the message names, and try again.
+<!-- source: src/lib/engine.js:449 -->
+
+### "There is no local engine for <platform> <arch>."
+There is no engine built for this kind of computer.
+<!-- source: src/lib/engine.js:84-87 -->
+
+### `niro engine status` says another niro-local is on my PATH.
+A second copy of the engine is installed somewhere on your PATH. `niro` does not use it. Remove it, so that only one version is on this computer.
+<!-- source: src/commands/engine.js:92-116 -->
+
+### The engine install ended with "Nothing was installed."
+Niro's service refused the download. The message above it gives the service's reason, for example that your plan does not include the engine.
+<!-- source: src/commands/engine.js:54-56 -->
+
+### "The local engine cannot open its graph on this machine" or "Make that folder writable, or set NIRO_LOCAL_HOME"
+The engine cannot write to `~/.niro-local`. Make that folder writable by you. Or set `NIRO_LOCAL_HOME` to a folder you can write, and run `niro service install` so the watcher uses it too.
+<!-- source: src/commands/engine.js:73; niro-local src/niro_local/graph/sqlite_writer.py:389-390; src/niro_local/cli.py:105-143; src/lib/service.js:74-108 -->
+
+### "PM2 is not installed." / "PM2 install failed" / "PM2 was installed but [is not] runnable from this shell"
+PM2 is the tool that keeps Niro's background watcher running.
+
+- **Install failed.** If installing it failed (usually a permission error), run `sudo npm install -g pm2`, then `niro service install`.
+- **Installed but not found.** If it installed but cannot be found, npm's global folder is not on your PATH. Find it with `npm prefix -g`, and add its `bin` folder to your PATH.
+<!-- source: src/lib/watchDaemon.js:36-81 (messages; the last one is quoted from code, which uses a contraction) -->
+
+### "Could not set niro-watch to start on login"
+The watcher runs, but will not start again by itself after you log out. The message gives the command to try again. That command may need `sudo`.
+<!-- source: src/lib/service.js:276-277 -->
+
+### `niro status` says the background updates are "stopped", "not installed" or "OFF".
+The graph will not follow your edits until the watcher runs. The status line names the fix:
+
+- **Stopped or not installed:** run `niro service install`.
+- **OFF:** PM2 is missing. Install it with `npm install -g pm2`, then run `niro service install`.
+<!-- source: src/commands/status.js:35-40 -->

package/docs/faq-licence-and-plans.md

@@ -0,0 +1,86 @@
+# FAQ: licence and plans
+
+### What plans are there, and how many lines does each allow?
+Free allows 500,000 lines. Free with code sharing on has no line limit. There is also a 30-day Pro trial. `niro plan` shows yours. See [licence-and-plans.md](licence-and-plans.md).
+<!-- source: Niraj, 2026-11-10; src/lib/planUsage.js:53-66 -->
+
+### What counts as a line?
+Every line of every file Niro reads, blank lines and comments included. Two copies of one repository (branches, worktrees) count once, by the larger. Different repositories add up. A folder inside another indexed folder counts once.
+<!-- source: niro-local src/niro_local/licence/limit.py:9-60; src/lib/planUsage.js:1-21 -->
+
+### "Not built: this machine already holds N lines of code, over the M line limit."
+This computer is at or over your plan's line limit, and this folder would add new lines. A page in the console opens to help you choose. The choices are also listed under the next questions.
+<!-- source: src/commands/initLocal.js:59-62; src/commands/start.js:305-318 -->
+
+### "No room left under the limit, so a new folder will not be indexed. Folders already indexed still rebuild."
+You are at your limit. Folders you already index keep updating. A new folder is refused until you free room or change plan.
+<!-- source: src/lib/planUsage.js:75 -->
+
+### "Not indexing: this machine already holds N lines ..." with a list ending "removing it frees nothing"
+The engine lists your folders and how many lines each counts for. "Same repository: removing it frees nothing" marks a second copy of a repository you already count. Removing it does not lower your total.
+<!-- source: niro-local src/niro_local/licence/limit.py:145-190 -->
+
+### How do I get past the limit?
+`niro plan` lists three ways:
+
+1. **Turn on "Share redacted code"** in the console (Settings, Privacy). On the Free plan this removes the limit.
+2. **Ask for a Pro free trial** at `console.niroai.dev/request?plan=pro`.
+3. **Stop indexing a folder** with `niro plan remove <folder>`.
+<!-- source: src/commands/plan.js:63-67 -->
+
+### What does "no line limit while you share" mean, and what is shared?
+Code sharing is the "Share redacted code" switch on your account. With it on, the Free plan has no line limit, and the background watcher sends the files Niro indexes, masked, by itself: the whole set the first time, then only changed files. Keep a folder out with `niro share exclude <folder>`. You can also send one folder at once with `niro audit-push-repo`.
+<!-- source: src/lib/planUsage.js:53-66; src/lib/shareCode.js; src/lib/shareExclusions.js; src/lib/repoPush.js -->
+
+### Is code sharing the same as the coverage audit?
+No. The coverage audit sends small masked snippets on every plan, whether sharing is on or off. See [coverage-audit-and-consent.md](coverage-audit-and-consent.md).
+<!-- source: src/lib/auditUpload.js:27-30 -->
+
+### "Could not read your plan from Niro. Check your connection, then run niro plan again."
+Niro's service could not be reached, or did not answer. Check your connection.
+<!-- source: src/commands/plan.js:20, :41 -->
+
+### "Niro will not license the local engine: <reason>"
+Niro's service refused the licence, so the engine stopped. The reason follows the message. If it is about your account, write to help@niro.ai.
+<!-- source: src/lib/lease.js:271-276 -->
+
+### "Could not renew the local engine's licence ... It keeps working offline for up to a day."
+The licence service could not be reached. Niro keeps working for up to a day, and renews when it can.
+<!-- source: src/lib/lease.js:282-286 -->
+
+### "Working on an expired licence: N hours of offline allowance left"
+The licence has run out and could not be renewed. The engine keeps working for the hours shown. Reconnect before they run out.
+<!-- source: niro-local src/niro_local/licence/report.py:122 -->
+
+### "Not indexing: ..." followed by "Reason given: ..."
+The engine refused to build because its licence was missing or not valid. The reasons are:
+
+- **No licence reached the engine.** It was started some other way than by `niro`.
+- **The service refused it.**
+- **It has run out.**
+- **It does not match this engine, or its signature or key is not one the engine trusts.**
+- **It is damaged or incomplete.**
+<!-- source: niro-local src/niro_local/licence/report.py:17-71 (NO_LEASE, REFUSED_BY_SERVICE, EXPIRED, WRONG_NONCE, BAD_SIGNATURE, UNSUPPORTED_VERSION, UNKNOWN_KEY, MALFORMED, INCOMPLETE, NO_TRUSTED_KEY) -->
+
+Run the command again through `niro` (for example `niro build`). If it persists, run `niro upgrade`.
+<!-- source: niro-local src/niro_local/licence/report.py:17-71, :81-101 (NO_LEASE, REFUSED_BY_SERVICE, EXPIRED, WRONG_NONCE, BAD_SIGNATURE, UNSUPPORTED_VERSION, UNKNOWN_KEY, MALFORMED, INCOMPLETE, NO_TRUSTED_KEY) -->
+
+### "The Niro CLI has not handed this engine its licence yet."
+The engine has just started and is waiting for its licence. Ask again in a few seconds. If it keeps saying this, the engine was not started by `niro`: connect your agent with `niro mcp install`.
+<!-- source: niro-local src/niro_local/cli.py:1368, :2662, :2678 -->
+
+### Typing `niro-local build` or `niro-local ask` is refused.
+The engine runs only with the licence `niro` hands it. Use `niro build` and `niro ask`.
+<!-- source: niro-local src/niro_local/commands.py:1-72; src/lib/release.js:25-31 -->
+
+### Does the Pro trial have a line limit?
+The Pro trial lasts 30 days. `niro plan` shows its limit, if it has one.
+<!-- source: Niraj, 2026-11-10 (30-day Pro trial); README.md (Pro trial: "no line limit, no sharing needed"); src/commands/plan.js:57-61 -->
+
+### I am over the limit. Will my folders and branches still update?
+Yes. Folders already indexed keep rebuilding, and so do new branches and worktrees of them. Only a new folder is refused.
+<!-- source: src/lib/planUsage.js:71-87 -->
+
+### A page opened in my browser by itself, at ".../limit".
+That is the console's page for choosing what to do at the limit. `niro start` and `niro init` open it when a folder would take you over.
+<!-- source: src/commands/start.js:305-318; src/commands/initLocal.js:59 -->

package/docs/faq-login-and-account.md

@@ -0,0 +1,69 @@
+# FAQ: login and account
+
+### Do I need an account to use Niro on my own computer?
+Yes. The account carries your plan, and the engine needs a licence from it to run. Sign up at console.niroai.dev.
+<!-- source: src/lib/lease.js:42-44; sign-up: Niraj, 2026-11-10 -->
+
+### The browser did not open when I signed in.
+Niro prints the address and a code. Open the address yourself, in any browser, and enter the code.
+<!-- source: src/commands/login.js:168-176, :231-250 -->
+
+### "Login timed out. Run niro login to try again."
+The code was not approved in time. A code lasts 10 minutes unless the service says otherwise. Run `niro start` or `niro login` again for a new code.
+<!-- source: src/commands/login.js:23-24, :213 -->
+
+### "You are on the list. We will email you when you are in."
+Your account is waiting to be let in. Niro emails you when it is. Then run `niro start` again.
+<!-- source: src/commands/login.js:286-305 (account_waiting) -->
+
+### "Request sent. We reply within one business day."
+Your request (for example for a trial) has reached Niro. Run `niro start` again once you hear back.
+<!-- source: src/commands/login.js:286-305 (request_submitted) -->
+
+### "This account cannot sign in to Niro."
+This account is blocked. If you think that is a mistake, reply to any Niro email, or write to help@niro.ai.
+<!-- source: src/commands/login.js:286-305 (account_blocked) -->
+
+### "The sign-in was not completed. Run niro start again to get a new code."
+The sign-in was declined in the browser, or the code ran out. Run `niro start` again.
+<!-- source: src/commands/login.js:286-305 (access_denied, expired_token) -->
+
+### "Not logged in", "Session expired" or "Token refresh failed"
+Your saved sign-in is missing or no longer valid. Run `niro login`.
+<!-- source: src/lib/credentials.js:61, :66; src/lib/api.js:72, :82, :110 -->
+
+### "Credentials rejected by server (401). Run niro login to refresh."
+The service no longer accepts your saved sign-in. Run `niro login`.
+<!-- source: src/commands/whoami.js:21 -->
+
+### I signed in with `--api-key` or `--password`, and `niro mcp install` says "Not signed in. Run niro login".
+Connecting agents needs the browser sign-in. Run `niro login` with no options, approve in the browser, then run `niro mcp install` again. `niro start` does not help here: it sees the saved key, skips the sign-in, and the installer refuses again. Signing in with a key is due to be removed.
+<!-- source: src/mcp/setup.js:574-583, :2950-2955; src/commands/start.js:197-198, :470-473; src/commands/login.js:35-38; TODO.md:51-62 -->
+
+### A command says "`--api-url` ..." is not accepted.
+Only `niro login` accepts `--api-url`. Sign in with it once: the other commands then use the address you signed in to.
+<!-- source: src/index.js:30-39; src/lib/api.js:33-41 -->
+
+### Signing in hangs and nothing happens.
+Sign-in and other account calls have no time limit, so on a stalled network they wait. Press Ctrl-C, check your connection, and try again.
+<!-- source: src/lib/api.js:146-149 -->
+
+### "Device flow not available on this server, falling back to API key login."
+Niro could not use the browser sign-in, so it asks for a key instead. This happens when the service has no browser sign-in (a custom `--api-url`), and also when the check for it fails with a network error. In the second case, press Ctrl-C, check your connection, and run `niro login` again.
+<!-- source: src/commands/login.js:36-42, :132-141 (a network error with no HTTP status returns false, and login falls back) -->
+
+### "Invalid API key." or "Server did not return a token."
+The key was wrong or has been withdrawn. Use the browser sign-in instead: `niro login`.
+<!-- source: src/commands/login.js:69, :85 -->
+
+### What does `niro logout` remove?
+It withdraws the sign-in on Niro's service where it can, and deletes `~/.niro/credentials.json`. Your graphs stay.
+<!-- source: src/commands/logout.js:19-20 -->
+
+### `niro whoami` says I am signed in, but I am offline.
+When the service cannot be reached, `niro whoami --json` reports your saved sign-in. It does not check that sign-in with the service.
+<!-- source: src/commands/whoami.js:52-58 -->
+
+### How do I delete my account?
+Email help@niro.ai.
+<!-- source: Niraj, 2026-11-10 -->

package/docs/faq-offline.md

@@ -0,0 +1,34 @@
+# FAQ: offline use
+
+### Can I use Niro offline?
+Yes, for up to about a day at a time. The engine needs a licence from Niro's service, and keeps working for about a day when it cannot renew it. Your agent's questions never need the network.
+<!-- source: src/lib/lease.js:282-286; niro-local src/niro_local/licence/report.py:122; src/lib/planUsage.js:118 -->
+
+### What needs the network?
+- signing in;
+- renewing the licence;
+- downloading the engine;
+- sending the coverage audit and the tool-usage record.
+
+Everything else runs on your computer.
+<!-- source: src/lib/api.js; src/lib/lease.js; src/lib/engine.js; src/lib/auditUpload.js; src/lib/journalUpload.js -->
+
+### Can Niro run on a computer with no internet at all?
+Not for more than about a day. The licence needs Niro's service. There is no offline licence.
+<!-- source: src/lib/lease.js:9-57 -->
+
+### Does Niro work behind a company proxy?
+`niro` has no proxy setting of its own. When the background watcher is installed, it is given four proxy variables from your environment: `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` and `NODE_USE_ENV_PROXY`. It is also given `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE` and `SSL_CERT_DIR`, for a company's own certificates. This is so that a watcher behind a company proxy can upload. Set them before you run `niro service install`. Other proxy setups have not been tested.
+<!-- source: src/lib/service.js:72-73 ("without them a watcher behind a company proxy or private certificate cannot upload"), :83 (the four proxy names) -->
+
+### What happens to the audit and tool-usage records while I am offline?
+They wait on your computer, and the watcher tries every 5 minutes. A record the service refuses is kept in `~/.niro/journal-refused`.
+<!-- source: src/commands/watch.js:423-426; src/lib/journalUpload.js:120-129 -->
+
+### "Network error calling <method> <path>"
+Niro's service could not be reached. Check your connection, and try again.
+<!-- source: src/lib/api.js:155, :192-200 -->
+
+### The first answer of a session takes about 20 seconds when I am offline.
+The engine waits for its licence before answering. Known problem.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:3617 (open) -->

package/docs/faq-performance.md

@@ -0,0 +1,33 @@
+# FAQ: performance
+
+### A build is slow.
+A build with 200 or more files to read uses one worker process per processor core, up to 8. Set `NIRO_LOCAL_PARSE_WORKERS` to change that. Later builds handle only what changed. For scale: a full build of about 9,000 files was measured at about 103 seconds.
+<!-- source: niro-local src/niro_local/build/parallel_parse.py:59-61, :197-198; niro-local TODO.md:189 -->
+
+### Answers slow down while a build runs.
+Known: questions asked without pause during a build slow the build down several times.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:4172 (open) -->
+
+### A deep reverse call chain is slow.
+A reverse chain 8 levels deep on a much-called name can take several seconds. Ask fewer levels (`depth=3`), or use `purpose=ASSESS_RISK` for counts.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:3774 (open); src/niro_local/mcp/purpose.py -->
+
+### The graph file keeps growing.
+The graph keeps a side file of recent writes (the write-ahead log), trimmed to 64 MB by default (`NIRO_LOCAL_WAL_LIMIT_MB`). A tool that holds the graph open for a long time can stop the trim. Run `niro db status` to see the size. Run `niro clean` to remove the graphs of deleted folders.
+<!-- source: niro-local src/niro_local/graph/sqlite_writer.py:105-111; niro-local docs/NIRO-LOCAL-ISSUES.md:3729 (open); src/commands/engineRoutes.js:35-36 -->
+
+### How much disk does the graph use?
+It depends on your code. `niro db status` shows it for your computer.
+<!-- source: src/commands/engineRoutes.js:36 -->
+
+### How much memory and processor time does the background watcher use?
+Not measured yet. It waits for file changes, and builds only after a folder goes quiet.
+<!-- source: src/lib/localBuild.js:16-46 -->
+
+### `code_grep` stops early, or an answer is cut short.
+A search stops after 1.5 seconds, and gives a `continue_from` value to carry on. An answer is cut at 20,000 characters. Narrow the search with `path_pattern`, or raise `NIRO_LOCAL_MAX_ANSWER_CHARS`.
+<!-- source: niro-local src/niro_local/mcp/source_tools.py:101-162 -->
+
+### A tool call took more than 30 seconds and stopped.
+One call to the engine may take 30 seconds. Ask a narrower question, or a lower `depth`.
+<!-- source: src/mcp/localBackend.js:183 -->

package/docs/faq-privacy-and-security.md

@@ -0,0 +1,113 @@
+# FAQ: privacy and security
+
+### What leaves my computer?
+A short list:
+
+- your sign-in;
+- the licence check;
+- the engine download;
+- masked snippets from the coverage audit;
+- a record of which tools your agent used;
+- while "Share redacted code" is on: the files Niro indexes, masked, sent by the background watcher;
+- a whole repository, only if you send one yourself.
+
+See [what-leaves-your-machine.md](what-leaves-your-machine.md).
+<!-- source: src/lib/planUsage.js:116-134; src/lib/lease.js; src/lib/auditUpload.js; src/lib/journalUpload.js; src/lib/shareCode.js; src/lib/repoPush.js -->
+
+### Is my code sent to an AI model?
+Not in this release. It has no LLM documentation, and your agent's questions are answered on your computer. Niro's Data Processing Agreement also says Niro does not train AI models on your code.
+<!-- source: src/lib/release.js:33 (llmDocs: false); src/lib/planUsage.js:118; Niro DPA v3.0 clause 10.1 -->
+
+### What is the coverage audit, and can I turn it off?
+It sends small masked snippets of code the build could not read, so Niro can add support for it. It is sent on every plan, and `niro` has no switch for it. For what Niro may keep and do with what it receives, read Niro's Data Processing Agreement, summarised in [what-leaves-your-machine.md](what-leaves-your-machine.md). See [coverage-audit-and-consent.md](coverage-audit-and-consent.md).
+<!-- source: src/lib/auditUpload.js:27-30 -->
+
+### What exactly is in an audit snippet? Can I see it first?
+For each flagged line, the snippet holds the method around it, plus one line per name that method uses. Every other line is blank, and secrets are masked. Each item also carries the file's path inside the repository, masked. To see what is waiting, run `niro audit`. To write it to a folder, run `niro audit --export DIR`.
+<!-- source: src/lib/redact.js:89-121; niro-local src/niro_local/cli.py:2413-2415, src/niro_local/audit/queue.py:838-846 (the masked path); src/commands/engineRoutes.js:37; niro-local src/niro_local/cli.py:478 -->
+
+### How are secrets masked?
+Each secret value is replaced with a placeholder, and the name is kept. The rules are the ones Niro's own service uses before anything reaches an AI model. See [secrets-and-masking.md](secrets-and-masking.md).
+<!-- source: niro-local src/niro_local/redact/mask.py:1-75, :898 -->
+
+### Why were names in my code replaced with `<author>` or `<company>`?
+In audit snippets and in shared code, the names of copyright holders, your email's company and the git remote's owner are replaced, so they do not leave your computer.
+<!-- source: src/lib/redact.js:1-18 -->
+
+### "N item(s) not sent: the local engine is too old to mask secrets. Run `niro upgrade`."
+Niro sends nothing that has not been masked. Upgrade, and the waiting items go out masked.
+<!-- source: src/commands/auditSend.js; src/lib/journalUpload.js -->
+
+### What is in the tool-usage record?
+It holds:
+
+- the tools your agent used, how long each took, and any failures;
+- a short summary of the task;
+- the names, paths and search text your agent asked about.
+
+Free text is masked first and cut to about 1,000 characters. It never holds the contents of your files. A search pattern your agent typed can, though, be a short piece of code.
+<!-- source: src/lib/journalUpload.js:9-26; src/lib/planUsage.js (comment above AUDIT_CLAUSE); src/lib/journalUpload.js:12-14 and niro-local src/niro_local/journal/store.py:90 (about 1,000 characters of free text); niro-local src/niro_local/journal/sanitise.py:81-84 (200 characters per argument) -->
+
+### What does "Share redacted code" send?
+The code Niro indexes on your computer, by itself. While it is on, the background watcher sends, every 5 minutes, the files Niro indexes in each folder: the source files it parses and the config, build and text files it reads. It never sends a gitignored file, a real `.env`, a key or key store, or `node_modules`. Secrets are masked and author and company names removed first. The first time, a folder's whole indexed set goes; after that, only changed files. Niro deletes it after processing and never uses it to train AI. It also removes the Free line limit.
+
+### How do I send my repository to Niro for support?
+Run `niro audit-push-repo` in the folder. It sends that folder's indexed files, with secrets masked and author and company names removed first. It shows how many files and how large, and asks before it sends; your yes is the consent. It works with "Share redacted code" on or off, on every plan.
+<!-- source: src/lib/repoPush.js; src/commands/repoPush.js -->
+<!-- source: src/lib/planUsage.js:53-66 and sharingBlock; src/lib/shareCode.js; src/lib/shareFiles.js; niro-local src/niro_local/share_files.py; src/lib/repoPush.js -->
+
+### Can I keep one folder out while sharing stays on?
+Yes. Run `niro share exclude <folder>`. The watcher never sends that folder, or any folder inside it. If you later run `niro audit-push-repo` in it, it asks "You excluded this folder from sharing. Send it anyway?" and sends only if you say yes. `niro share` lists the folders kept out, and `niro share include <folder>` shares one again. `niro plan` lists them too. Another checkout of the same repository in a different folder is not kept out by this.
+<!-- source: src/commands/share.js; src/lib/shareExclusions.js; src/lib/shareCode.js; src/lib/repoPush.js; src/commands/plan.js -->
+
+### How do I stop sharing?
+Turn "Share redacted code" off in the console, under Settings, Privacy. The watcher checks before each round and before each batch of files, so nothing more is sent after that check.
+<!-- source: src/lib/shareCode.js (the lease gate and its re-check before each batch) -->
+
+### "the Niro service cannot yet promise to delete this code when sharing is switched off, so nothing was sent"
+Niro refuses to send a whole repository, or share code in the background, until its service can promise to delete the copy when you turn sharing off.
+<!-- source: src/lib/repoPush.js -->
+
+### Does uninstalling Niro turn off code sharing?
+No. It is a setting on your account. Turn it off in the console, under Settings, Privacy.
+<!-- source: src/commands/uninstall.js:97-101 -->
+
+### Which files does Niro never open?
+Real `.env` files, private keys and key stores, and tool credential files (such as `.npmrc` and `.netrc`). Config and text files named as secrets (such as `secrets.yaml`), and config and text files that `.gitignore` covers, are not read either. Source code is read whatever its name. See [secrets-and-masking.md](secrets-and-masking.md).
+<!-- source: niro-local src/niro_local/mcp/text_files.py:186-202 (secret_named) -->
+
+### Does Niro keep a copy of my source code?
+No full copy. The graph keeps names, places and links. The tools read your files from disk when asked. The build state can hold short values written in the code, such as a default value. It stays on your computer, readable by you only.
+<!-- source: niro-local src/niro_local/mcp/freshness.py:305-308; src/niro_local/build/state.py:1-40; niro-local docs/NIRO-LOCAL-ISSUES.md:863 -->
+
+### Who can read the files Niro keeps?
+Only your user account. Niro's folders are readable by their owner only.
+<!-- source: niro-local src/niro_local/registry.py:53-104; src/lib/credentials.js:51-72 -->
+
+### Can someone on my network reach my graph?
+No. Your agent talks to Niro through its own standard input and output, not the network. `niro ui` listens only at 127.0.0.1, which is this computer.
+<!-- source: src/mcp/setup.js:241-247; niro-local src/niro_local/ui/server.py:35 -->
+
+### "Passwords and tokens are refused and never stored"
+`niro env` stores addresses only. It refuses a value that looks like a password or token.
+<!-- source: niro-local src/niro_local/env_args.py:34 -->
+
+### "That is not a form of this command, and it is not repeated here in case it holds a secret."
+You typed a form of a command the engine does not know. It does not print what you typed back, in case it held a secret.
+<!-- source: niro-local src/niro_local/env_args.py:76-88 -->
+
+### Why does `code_grep` show `<MASK_...>` in my config file?
+Config values are masked in answers by default. To see real values on your own computer, see [secrets-and-masking.md](secrets-and-masking.md).
+<!-- source: niro-local src/niro_local/folder_settings.py:43-46 -->
+
+### Does Niro send telemetry?
+Everything `niro` sends is listed in [what-leaves-your-machine.md](what-leaves-your-machine.md), including the account calls `niro whoami` and `niro logout` make. The tool-usage record is the record of use.
+<!-- source: src/commands/whoami.js:48; src/commands/logout.js:19-20; src/lib/journalUpload.js:9-37; src/lib/onboardingLog.js:1-6 (kept on the machine only) -->
+
+### Is the downloaded engine checked?
+Yes. Niro checks its fingerprint (SHA-256) against the published one. It refuses an engine that does not match.
+<!-- source: src/lib/engine.js:551 -->
+
+### Is there a Data Processing Agreement? How do I delete my account?
+Yes, there is a Data Processing Agreement (version 3.0). It is summarised in [what-leaves-your-machine.md](what-leaves-your-machine.md). To delete your account, email help@niro.ai.
+<!-- source: Niro DPA v3.0 (wiki, Legal collection); account deletion: Niraj, 2026-11-10 -->

package/docs/faq-uninstall.md

@@ -0,0 +1,47 @@
+# FAQ: uninstall
+
+The steps are in [uninstall.md](uninstall.md).
+
+### How do I remove Niro completely?
+Run `niro uninstall`, then `npm uninstall -g @niroai/niro`, then restart your agents.
+<!-- source: src/commands/uninstall.js:164-168 -->
+
+### How do I remove Niro from one agent only?
+Run `niro mcp uninstall --client <id>`.
+<!-- source: src/mcp/teardown.js:645-653 -->
+
+### How do I stop indexing one folder?
+Run `niro plan remove <folder>`, or `niro remove --path <folder>`. Its graph is deleted, and the lines it used are freed.
+<!-- source: src/commands/plan.js:76-86; src/commands/engineRoutes.js:44 -->
+
+### "Nothing removed: there is no terminal to confirm on. Pass --yes to go ahead."
+`niro uninstall` asks before it removes anything. In a script, add `--yes`.
+<!-- source: src/commands/uninstall.js:108 -->
+
+### "Niro is partly removed; see the problems above."
+Some steps failed. The lines above name them. Fix those, and run `niro uninstall` again.
+<!-- source: src/commands/uninstall.js:164-168 -->
+
+### PM2's start-at-login entry is still there after uninstalling.
+`niro uninstall` removes the watcher itself. What happens to PM2's start-at-login entry depends on your computer:
+
+- **PM2 still runs other programs:** the entry is kept, because it is not Niro's.
+- **macOS, with nothing else in PM2:** the entry is removed.
+- **Otherwise (Linux):** removing it needs administrator rights, so the uninstall prints the command for you to run. Until you run it, PM2 starts on login with nothing of Niro's in it.
+<!-- source: src/lib/service.js:301-328; src/commands/uninstall.js:150, :169-171 ("PM2 still starts on login (with nothing of Niro's). To remove that too: ...") -->
+
+### Cursor rule files are still in other folders.
+`niro mcp uninstall` removes the Cursor rule from the current folder only. Delete `.cursor/rules/niro.mdc` in the other folders yourself.
+<!-- source: src/mcp/teardown.js:431-438 -->
+
+### "Could not send the waiting usage and audit records"
+Before deleting anything, `niro uninstall` tries to send the records that are waiting. It could not, and it goes on with the uninstall anyway.
+<!-- source: src/commands/uninstall.js:46-59, :128-137 -->
+
+### "Niro is not installed on this machine, so there is nothing to remove."
+Niro found nothing of its own. If the `niro` command is still there, run `npm uninstall -g @niroai/niro`.
+<!-- source: src/commands/uninstall.js:79 -->
+
+### Does uninstalling delete my account or turn off code sharing?
+No to both. Turn sharing off in the console (Settings, Privacy). To delete your account, email help@niro.ai.
+<!-- source: src/commands/uninstall.js:94-101; account deletion: Niraj, 2026-11-10 -->

package/docs/faq-updates.md

@@ -0,0 +1,59 @@
+# FAQ: updates
+
+### How do I upgrade?
+Run `niro upgrade`. It does three things:
+
+1. It installs the newest `niro` with npm.
+2. It refreshes every agent you connected, the engine and the background watcher.
+3. It tells you to restart your agents.
+
+Your graphs, sign-in and settings stay.
+<!-- source: src/commands/upgrade.js:85-293 -->
+
+### "npm could not replace the package. The usual cause is that your npm global folder needs root"
+npm could not write to its global folder. Run the upgrade with the permissions npm needs. Or point npm's global folder at a folder you own. (Exit code 1.)
+<!-- source: src/commands/upgrade.js:125-132 -->
+
+### "Not upgrading: niro is npm-linked to a working copy" or "you are not running the globally installed niro"
+The `niro` you ran is not the copy npm installed for everyone. Upgrade anyway with `niro upgrade --force`. (Exit code 5.)
+<!-- source: src/commands/upgrade.js:85-103 -->
+
+### "npm reported success, but there is no niro in your npm global folder."
+npm finished, but the `niro` command is not where it should be. Run `npm install -g @niroai/niro` yourself. (Exit code 2.)
+<!-- source: src/commands/upgrade.js:137-142 -->
+
+### "The version just installed does not support `niro upgrade --finish`"
+The new version could not finish the job. The message lists the commands to run by hand: `niro mcp install` and `niro service install`. (Exit code 3.)
+<!-- source: src/commands/upgrade.js:75-78, :150-156 -->
+
+### "N of M refreshed, K failed."
+Some agents were not refreshed. Run `niro mcp install --client <id>` for each one named, to see why. (Exit code 4.)
+<!-- source: src/commands/upgrade.js (finish phase) -->
+
+### "The local engine was not upgraded: <message>. Try again with niro engine install."
+`niro` was upgraded, but the engine was not. Run `niro engine install`.
+<!-- source: src/commands/upgrade.js (finish phase) -->
+
+### Does the engine update by itself?
+No. `niro upgrade` updates it. Niro keeps an engine newer than the published one rather than going back. It does not replace an engine that is running: close your agents and the watcher first.
+<!-- source: src/lib/engine.js:505-528 -->
+
+### After an upgrade, answers say to rebuild.
+A new major version stores the graph in a new format. Run `niro build` once.
+<!-- source: niro-local src/niro_local/graph/sqlite_writer.py:311-313 -->
+
+### Two versions of Niro keep rebuilding each other's graph.
+Known problem when two versions share one `~/.niro-local`. Keep one version on the computer. `niro engine status` warns when a second engine is on your PATH.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:3759 (open); src/commands/engine.js:92-116 -->
+
+### "Heads up: you are not signed in, so each client's installer will stop without refreshing it."
+The upgrade itself worked, but your agents were not refreshed: each one's installer stops with "Not signed in", and the run ends "N of M refreshed, K failed". Run `niro login`, then `niro upgrade --finish`.
+<!-- source: src/commands/upgrade.js:334-346, :365-380; src/mcp/setup.js:2952-2956 -->
+
+### "Folders from Niro web: N folder(s) were set up with Niro web on this machine."
+These folders were set up with hosted Niro by an older version. This version indexes on your computer, and no longer uploads them. To keep using Niro in one of them, run `niro init` in it. `niro start` offers to do this, up to your line limit.
+<!-- source: src/lib/migrationNotice.js:108-114; src/commands/start.js:353-373 -->
+
+### Do I need Docker? I have an old `niro-local-memgraph` container.
+No. Niro no longer uses Docker or Memgraph. Remove the old container with `docker rm -f niro-local-memgraph`, and its data with `docker volume rm niro-local-memgraph-data`.
+<!-- source: niro-local docs/NIRO-LOCAL-USER-FLOW.md:247-254; niro-local CLAUDE.md (2026-10-31: the graph moved to a SQLite file) -->

package/docs/faq-worktrees-and-branches.md

@@ -0,0 +1,59 @@
+# FAQ: worktrees and branches
+
+How it works is in [worktrees-and-branches.md](worktrees-and-branches.md). This page answers the messages you may see.
+
+### "This folder is now on <branch>, which niro-local has not indexed."
+You switched to a branch with no graph yet. If the repository is indexed on another branch, Niro makes a temporary copy and builds it. Otherwise it offers to index the folder.
+<!-- source: niro-local src/niro_local/offer.py:291; src/niro_local/temporary.py -->
+
+### "this folder's index was copied from project P and has not been built from this folder's files yet"
+Answers come from a copy of the main project's graph until this folder's own build finishes. That takes moments for small changes.
+<!-- source: niro-local src/niro_local/mcp/server.py:775; src/niro_local/offer.py:393-397 -->
+
+### "A project's folders must all be on one branch."
+A project's folders must all be on the same branch. Put them on one branch. Or add the folder to a different project with `niro init --project <name>`.
+<!-- source: niro-local src/niro_local/offer.py:243; src/niro_local/onboard.py:267 -->
+
+### "This folder is on no named branch"
+You have a commit checked out directly (a detached HEAD). Niro answers from the folder's last used graph, and names its branch.
+<!-- source: niro-local src/niro_local/mcp/server.py:724 -->
+
+### I switched back to my old branch. Is its graph still there?
+Yes. Niro keeps one graph per folder and per branch, and switches without rebuilding. Each answer then carries one line saying which project it came from.
+<!-- source: niro-local src/niro_local/mcp/server.py:734; src/niro_local/cli.py:366-369 -->
+
+### A new git worktree was built by itself, but an older one was not.
+The watcher builds worktrees it sees appear. Worktrees that existed before Niro first saw the repository are only noted. Build one with `niro build` in its folder.
+<!-- source: src/lib/localWorktrees.js:1-21 -->
+
+### "Gave up building <folder> after N tries; run `niro build` there to see why."
+The watcher tried three times, waiting 2 and then 10 minutes in between. Run `niro build` in that folder to see the error.
+<!-- source: src/lib/localWorktrees.js:71-72, :198 -->
+
+### When are temporary projects deleted?
+After 14 days with no build and no question. They are kept while a build runs, while a folder of them is on that branch, or while a folder of them is missing. Change the 14 days with `NIRO_LOCAL_BRANCH_INDEX_IDLE_DAYS`.
+<!-- source: niro-local src/niro_local/cleanup.py:39-40, :116-147; niro-local TODO.md:124 -->
+
+### A folder that came back still shows its old "missing since" date.
+Known. The first date it went missing is kept.
+<!-- source: niro-local TODO.md:214 -->
+
+### The same file has two names in two worktrees.
+Known problem.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:2208 (open) -->
+
+### My folder is not in git. How does it get a branch?
+Give one when you add it: `niro init --branch <name>`. For a folder in git, the branch is read from git, and `--branch` is ignored.
+<!-- source: src/index.js:490-502; niro-local src/niro_local/cli.py:189 -->
+
+### Folders on different branches ended up in one project.
+Known problem for folders added without a branch (outside git).
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:3548 (open) -->
+
+### My folder holds several repositories on different branches.
+Niro treats such a folder as having mixed branches. Add the repositories one by one if you need each on its own branch.
+<!-- source: niro-local src/niro_local/repository_identity.py (MIXED) -->
+
+### "<path> is now on X; its part of this answer describes Y"
+Another folder of this project switched branch since its last build. That part of the answer is about the old branch until it is rebuilt.
+<!-- source: niro-local src/niro_local/mcp/server.py:803 -->