@niroai/niro 0.17.0 → 0.18.0

package/docs/playbook-test-a-change.md

@@ -0,0 +1,73 @@
+# Playbook: test a change
+
+**The question, in the user's words:** "I am changing how `JpaUserCredentialStore.createCredentialEntity` sets a new credential's priority. Which existing tests exercise it, and what is left untested?"
+
+**What you get at the end:** the tests that already reach the change, how far up each one sits, the production paths with no test on them, and the places to add one.
+<!-- source: outputs on this page: niro-local 43cce717 as `niro-local ask` from /home/niraj/projects/github/keycloak at 968726fe66, scratch home, 2026-11-10 (scratchpad niro-cli-task-playbooks/runs/test-01-rev.txt, brk-02-names.txt); `niro ask` runs the same engine command (src/commands/engineRoutes.js:28) -->
+
+## The steps
+
+### 1. Every caller three levels up, as places, with tests marked
+
+```
+niro ask get_reverse_call_chain method_fqn=org.keycloak.models.jpa.JpaUserCredentialStore.createCredentialEntity depth=3 answer=locations
+
+JpaUserCredentialStore.createCredentialEntity has 2 direct callers and 12 more further up (14 in all).
+confidence: complete | has_more: false — this is the COMPLETE caller chain. Use it directly.
+model/jpa/.../JpaUserCredentialStore.java:80  ...JpaUserCredentialStore.createCredential_Nzv6uN (depth 1)
+model/storage/.../UserCredentialManager.java:122  ...UserCredentialManager.createStoredCredential_Nj44zN (depth 2)
+model/infinispan/.../SubjectCredentialManagerCacheAdapter.java:53  ...createStoredCredential_N778tN (depth 3)
+services/.../PasswordCredentialProvider.java:133  ...PasswordCredentialProvider.createCredential_N0xesN (depth 3)
+tests/base/.../CredentialModelTest.java:56  ...CredentialModelTest.testCredentialCRUD_NkjyaN [test] (depth 3)
+tests/base/.../CredentialModelTest.java:176  ...testCredentialUpdateWithDuplicateLabel_NlanoN [test] (depth 3)
+testsuite/.../LDAPUserMultipleCredentialTest.java:100  ...afterImportTestRealm_NjqfxN [test] (depth 3)
+testsuite/.../UserStorageTest.java:938  ...UserStorageTest.testCredentialCRUD_Ni2geN [test] (depth 3)
+testsuite/.../UserStorageTest.java:1042  ...testCRUDCredentialsOfDifferentUser_Ns8n5N [test] (depth 3)
+testsuite/.../RecoveryAuthnCodesAuthenticatorTest.java:329  ...createRecoveryAuthnCodesForUser_Nyz8kN [test] (depth 3)
+model/jpa/.../JpaUserProvider.java:1065  ...JpaUserProvider.createCredential_N0sf7N (depth 1)
+[shown all 14 callers; ask without answer= for signatures and code]
+```
+<!-- source: runs/test-01-rev.txt (3,071 characters, 14 callers) -->
+
+`[test]` marks a caller in test code. Six tests can reach the change in the code as written, all three levels up, through a user's credential manager.
+
+**Check the branches that choose a class at run time.** Two of the six, both in `UserStorageTest`, use a user stored outside Keycloak's own database (a federated user, here "thor"). `UserCredentialManager.getStoreForUser` sends such a user's credentials to a different store, so at run time those two tests never reach `createCredentialEntity`. Four tests really run it. Niro lists every caller the code makes possible; which one a running program takes can depend on data, and only reading that branch tells you.
+<!-- source: keycloak model/storage/src/main/java/org/keycloak/credential/UserCredentialManager.java:310-316 (isLocalStorage ? userLocalStorage() : userFederatedStorage()); testsuite/.../federation/storage/UserStorageTest.java:923-924, :1038-1039 (getUserByUsername(realm, "thor"); assertFalse(StorageId.isLocalStorage(...))). Both arms of the playbook A/B said so in their answers to task p-03, in both sets (scratchpad niro-cli-task-playbooks/ab/answers-p1/p-03-a.md:31, answers-p2/p-03-a.md:41-43, answers-p1/p-03-b.md:23-25), then read by hand. -->
+
+**Do not combine this with `purpose=VERIFY`.** VERIFY gives names only and leaves the `[test]` marks out.
+<!-- source: docs/lifecycle-test.md ("The VERIFY purpose leaves the marks out"); niro-local docs/NIRO-LOCAL-ISSUES.md entry "2026-11-06, a Java call whose argument comes from a record accessor is marked `[possible]` ... and `purpose=VERIFY` drops the `[possible]` and `[test]` marks" (OPEN) -->
+
+### 2. What production paths have no test?
+
+The same list shows four credential providers (`OTPCredentialProvider`, `PasswordCredentialProvider`, `RecoveryAuthnCodesCredentialProvider`, `WebAuthnCredentialProvider`) at depth 3 with no test on the list beside them. Ask one level further for each, or ask the provider's own callers, to see whether a test reaches it from higher up:
+
+```
+niro ask get_reverse_call_chain method_fqn=org.keycloak.credential.PasswordCredentialProvider.createCredential depth=2 answer=locations
+```
+<!-- source: runs/test-01-rev.txt (the four providers at depth 3) -->
+
+### 3. Write the test next to an existing one
+
+`CredentialModelTest` is the closest model test: it calls `user.credentialManager().createStoredCredential(...)` inside a session. Open it with `get_source_code` at the line the list gave.
+<!-- source: keycloak tests/base/src/test/java/org/keycloak/tests/model/CredentialModelTest.java:56 -->
+
+## Why the answer is complete, and where it is not
+
+- **The chain crosses interfaces.** The tests call `credentialManager()`, which returns an interface; the graph follows it to `SubjectCredentialManagerCacheAdapter` and on down. A text search from the test has no class name to follow.
+<!-- source: keycloak CredentialModelTest.java:56 (`user.credentialManager().createStoredCredential(otp2)`); runs/test-01-rev.txt -->
+- **It is checked against a grep:** the test methods that call `createStoredCredential` directly are exactly these six (10 call lines in 4 files). A grep has the same blind spot as the graph here: it cannot tell which store a running test will use.
+<!-- source: `grep -rn --include=*.java "createStoredCredential(" . | grep "/test/"` = 10 lines in 4 files, enclosing methods matched by hand to the six above (Keycloak, 2026-11-10) -->
+- **Tests further up are not listed** until you raise `depth` (8 at most). A test that reaches the code through a REST call over HTTP to a running server is outside the graph.
+<!-- source: docs/lifecycle-test.md (3 by default, 8 at most) -->
+
+## What grep would do instead
+
+To get here by search, an agent needs to know that `createCredentialEntity` is reached through `createCredential`, then `createStoredCredential`, then the credential manager interface, before it can search the tests for `createStoredCredential(`. That is three searches and three reads before the useful one, and the middle step names an interface, not a class.
+
+## Cost
+
+What these steps cost depends on your code and your question. How Niro counts the size of its answers, and how to measure the cost on your own tasks, is in [tokens-speed-and-accuracy.md](tokens-speed-and-accuracy.md).
+
+## Related
+
+[lifecycle-test.md](lifecycle-test.md), [playbook-change-safely.md](playbook-change-safely.md), [playbook-review-a-change.md](playbook-review-a-change.md).

package/docs/reference-cli.md

@@ -0,0 +1,113 @@
+# The `niro` command: reference
+
+This page lists every `niro` command in this release, with its options. Run `niro <command> --help` for the same text in the terminal. The commands that `niro` passes to the local engine (`ask`, `ui`, `env`, `impact` and others) are in [reference-engine-commands.md](reference-engine-commands.md).
+<!-- source: src/index.js (commander definitions); src/commands/engineRoutes.js:27-46 -->
+
+## Global options
+
+| Option | What it does |
+|---|---|
+| `--version` | Prints the version |
+| `--api-url <url>` | The Niro service address to sign in to. **Only `niro login` accepts it.** Any other command refuses it |
+<!-- source: src/index.js:12, :30-39 -->
+
+Typing `niro` with nothing after it, before you have signed in, runs `niro start`.
+<!-- source: src/index.js:468-470 -->
+
+## Setting up
+
+| Command | What it does | Options |
+|---|---|---|
+| `niro start [path]` | First-time setup in five steps: checks this computer, signs you in, installs the local engine, builds the folder's graph, connects your agents. It also installs the background watcher. Running it again resumes at the first step that did not finish. Needs a terminal | none |
+| `niro login` | Signs in through your browser | `--api-key` (paste a key instead; due to be removed), `--password` (email and password instead), `--email <email>` (with `--password`) |
+| `niro logout` | Signs out on the server where it can, and deletes the saved sign-in | none |
+| `niro whoami` | Shows who is signed in | `--json` (includes `authed: true` or `false`) |
+| `niro engine [status\|install]` | `status` (the default) shows the platform, where the engine is, its cache folder and whether its database opens. `install` downloads the engine | `--force` (download again even if it is there) |
+<!-- source: src/index.js:41-58, :69-75, :88-95, :106-115; src/commands/start.js:61, :97-105, :390-411; src/commands/login.js:36-52; src/commands/logout.js; src/commands/engine.js:81-118; TODO.md:51-62 -->
+
+## Folders and the graph
+
+| Command | What it does | Options |
+|---|---|---|
+| `niro init [path]` | Adds a folder and builds its graph. Needs `niro start` to have set up this computer | `--project <name>` (project to join or create; defaults to the folder's name), `--branch <name>` (for a folder not in git), `--path <folder>`, `--base-url <url>` (the address the service answers on; an empty value leaves it unset), `--force` (add a folder that does not look like a project; never your home folder, the root or a system folder) |
+| `niro build [path]` | Rebuilds a folder's graph. A folder not added yet is refused | `--full` (read every file again), `--project <name>` (when several projects hold the folder) |
+| `niro status` | This folder's project, last build, plan, sharing, agent and background updates, then the engine's own status | `--json` (niro's part only) |
+| `niro plan` | Your plan, lines used, and the folders using them | `--json` |
+| `niro plan remove <folder>` | Stops indexing a folder, to free lines | none |
+<!-- source: src/index.js:77-86, :490-527; src/commands/plan.js:57-86; src/commands/status.js:76-98; src/commands/initLocal.js -->
+
+## Coding agents
+
+| Command | What it does | Options |
+|---|---|---|
+| `niro mcp install` | Connects coding agents. See [connect-your-ai-assistant.md](connect-your-ai-assistant.md) | `--client <id>[,<id>]`, `--list` |
+| `niro mcp uninstall` | Removes Niro from agents | `--client <id>[,<id>]`, `--all` (or `--client all`), `-y` / `--yes` |
+| `niro mcp serve` | The MCP server your agent starts. You do not run it yourself | none |
+| `niro mcp receipt` | Shows, or switches, the end-of-task Niro line | `--on`, `--off` |
+| `niro mcp line-check` | Used by Claude Code's end-of-task hook. You do not run it yourself | none |
+<!-- source: src/index.js:432-462; src/mcp/setup.js:683, :3000-3020; src/mcp/teardown.js:645-653; src/commands/mcp.js:79-90; bin/niro.js:3-10 -->
+
+## Background updates
+
+| Command | What it does |
+|---|---|
+| `niro service install` | Installs and starts the background watcher (`niro-watch`, run by PM2) |
+| `niro service uninstall` | Removes it |
+| `niro service status` | Shows whether it is running |
+<!-- source: src/index.js:398-426; src/lib/service.js -->
+
+## Uploads
+
+| Command | What it does | Options |
+|---|---|---|
+| `niro audit-send` | Sends the coverage audit now. The watcher also does this every 5 minutes | `--limit <n>` (default 50) |
+| `niro journal-send` | Sends the tool-usage record now | `--limit <n>` (default 20) |
+| `niro audit-push-repo [path]` | Sends one folder's indexed files to Niro, masked, so Niro can look at a problem with you. Works with code sharing on or off, on every plan. It shows the count and size and asks first; your yes is the consent. For a folder you excluded with `niro share exclude`, it asks "Send it anyway?" and sends only on yes | `--force` (send again if it was sent before), `-y` / `--yes` (skip the size question; needed without a terminal. It does not answer the excluded-folder question, so an excluded folder is never sent without a terminal) |
+| `niro share` | Lists the folders kept out of code sharing | |
+| `niro share exclude <folder>` | Keeps a folder, and every folder inside it, out of code sharing while sharing stays on | |
+| `niro share include <folder>` | Shares an excluded folder again | |
+
+While code sharing is on, the watcher also sends the files Niro indexes by itself, every 5 minutes. See [what-leaves-your-machine.md](what-leaves-your-machine.md).
+<!-- source: src/index.js (audit-send, journal-send, audit-push-repo, share); src/commands/auditSend.js:15; src/lib/repoPush.js; src/commands/share.js; src/lib/shareCode.js -->
+
+## Seeing what Niro did
+
+| Command | What it does | Options |
+|---|---|---|
+| `niro impact` | What Niro did for you in the last 7 and 30 days, from the record on this computer: tasks, answers, tokens against the by-hand estimate (labelled as one), searches avoided, look-ups avoided, round trips avoided, answers by kind, the median answer time, a line per project, good moments in the agents' own words, and the graph kept current. Nothing is sent. Passed to the local engine. See [evaluate-what-niro-did.md](evaluate-what-niro-did.md) | `--days <n>` (one window, 1 to 365), `--project <name>`, `--json` |
+<!-- source: src/commands/engineRoutes.js ENGINE_COMMANDS (impact); niro-local src/niro_local/cli.py _cmd_impact, src/niro_local/impact.py -->
+
+## Reading this documentation
+
+These pages ship inside the package, so `niro guide` reads them with no network and no sign-in.
+
+| Command | What it does | Options |
+|---|---|---|
+| `niro guide` | Lists every page, grouped as the start page groups them, one line each. A page the start page does not group is listed under "Other pages" | `--json` |
+| `niro guide <topic>` | Shows one page. The topic can be a page name (`agent-cursor`), a page title, or a few words. When several pages match, it lists them. When no page is called that, it shows the pages that mention it. Only when nothing mentions it does it exit with 1 | `--json`, `--no-pager` |
+| `niro guide --search <words>` | Searches every page and shows each matching page with the lines that matched. A pasted error message finds the page that explains it, even with your own folder names and numbers in it, because each of the pages' placeholders (such as `<folder>` and `N`) stands for one value. Words a question is phrased with (how, do, I, what, the and the like) are left out, so a question in plain words searches for the words that matter, and the heading says which words those were. Without a line holding the phrase, it shows the lines that hold the most of your words; when no line holds enough of them, the pages that hold them across their lines; and it says "closest" when a word you typed is on no page. When fewer than half your words are on any page, or nothing matches, it exits with 1 | `--json`, `--no-pager` |
+<!-- source: src/index.js:533; src/commands/guide.js:register, showTopic, showSearch; src/lib/guide.js:find; src/lib/guideSearch.js:search, messagePattern, FILLER, byPage; 21 of 21 pasted messages from reference-messages.md with real values found their page first, and 0 of 12 errors from other tools read as a full match (fix round 2, 2026-11-10) -->
+
+Pages are shown as plain text. The source notes are left out, and a link shows the command that opens it, such as `niro guide what-leaves-your-machine`. Long text goes through a pager (`$PAGER`, or `less` when it is not set) only when it is printed to a terminal and is taller than the window. `$PAGER` runs through your shell, as it does for `git` and `man`. With `--json`, every answer is one JSON object with the same keys (`mode`, `query`, `page`, `matches`, `results`, `total`, `error` and others), for a coding agent to read.
+<!-- source: src/lib/guide.js:render, renderLinks; src/commands/guide.js:pagerCommand, runPager, show, envelope -->
+
+## Updating and removing
+
+| Command | What it does | Options |
+|---|---|---|
+| `niro upgrade` | Installs the newest `niro` with npm, then refreshes your agents, the engine and the watcher | `--finish` (only the refresh, no npm), `--force` (upgrade even from a linked or local copy), `--from <version>` (set by Niro itself) |
+| `niro uninstall` | Removes Niro from this computer. See [uninstall.md](uninstall.md) | `-y` / `--yes` |
+<!-- source: src/index.js:60-67, :387-396; src/commands/upgrade.js; src/commands/uninstall.js -->
+
+## Hidden commands
+
+| Command | Why it is hidden |
+|---|---|
+| `niro watch` | The background watcher runs it. Typed with a folder, it refuses: "`niro watch <path>` syncs a folder to Niro's cloud, which this release does not include." |
+| `niro docs-send` | For LLM documentation, which this release does not include. It prints "LLM documentation is not available in this release." and exits with 2 |
+<!-- source: src/index.js:138-150, :298-304, :486-487; src/commands/watch.js:130-135; src/lib/docsUpload.js:43 -->
+
+## Commands of hosted Niro
+
+These belong to hosted Niro and are not in this release: `add`, `info`, `edit`, `delete`, `doctor`, `ab`, `new-temp-project`, `discard-temp-project`, and the hosted versions of `init`, `build`, `status`, `remove` and `projects`. The local `remove` and `projects` are in [reference-engine-commands.md](reference-engine-commands.md). See [hosted-only.md](hosted-only.md).
+<!-- source: src/index.js:474-487; src/lib/release.js:33 -->

package/docs/reference-config-files.md

@@ -0,0 +1,42 @@
+# Settings files
+
+**Most people never edit these.** The commands write them for you. They are listed so that you know what each holds. The full list of files is in [where-things-are-stored.md](where-things-are-stored.md).
+
+## `~/.niro/config.json`
+
+| Key | What it holds | Default |
+|---|---|---|
+| `apiUrl` | The account service address | `https://aiorchestrator.niroai.dev` |
+| `billingUrl` | The licence and engine-download service | `https://billing.cloud.niroai.dev` |
+| `auditUrl` | Where the coverage audit is sent | `https://audit.cloud.niroai.dev` |
+| `mcpServerUrl` | Where the tool-usage record is sent. Saved only when you pass `--url` to `niro mcp install` | `https://aiassistant.niroai.dev` |
+| `appUrl` | The console you signed in through, used for links such as the limit page | `https://console.niroai.dev` |
+| `mcpConnectedAt` | When `niro start` connected your agents | none |
+| `mcpMode` | Hosted or local. Only used by hosted Niro releases | none |
+| `cloudIndexingApproved` | Left from older versions. No longer read | none |
+<!-- source: src/lib/config.js:16-38; src/lib/api.js:10, :33-41; src/lib/lease.js:42, :93-97; src/lib/auditUpload.js:47, :53-57; src/lib/journalUpload.js:35, :42; src/mcp/setup.js:2971-2978; src/commands/login.js:258-265; src/lib/planUsage.js:90-92; src/commands/start.js:326, :335; src/lib/graphCheck.js:14-15 -->
+
+An environment variable with the same purpose wins over this file. One exception: once you are signed in, the account address saved with your sign-in (in `credentials.json`) wins over `NIRO_API_URL`. See [reference-environment-variables.md](reference-environment-variables.md).
+<!-- source: src/lib/api.js:33-41 (order: creds.apiUrl, then NIRO_API_URL, then config apiUrl); src/lib/lease.js:93-97; src/lib/auditUpload.js:53-57; src/lib/journalUpload.js:35, :42 -->
+
+## `~/.niro/credentials.json`
+
+Your sign-in. Readable by you only. Do not edit it: `niro login` and `niro logout` manage it.
+<!-- source: src/lib/credentials.js:51-72 -->
+
+## Engine settings
+
+| Setting | Where | How to change it |
+|---|---|---|
+| `show-config-values` (on or off; default off) | One folder, or the whole computer | The engine's `config set`, see [secrets-and-masking.md](secrets-and-masking.md) |
+| Environment values and env files | One folder, on one branch, in one project | `niro env`, see [configuring-a-folder.md](configuring-a-folder.md) |
+| The service address (base URL) | One folder or service | `niro base-url` |
+| Route rules | One folder | `niro route-rule` |
+
+All of these live in `~/.niro-local/registry.db`.
+<!-- source: niro-local src/niro_local/folder_settings.py:49-59; src/niro_local/env_settings.py:1-25; src/niro_local/route_rules.py; src/niro_local/registry.py:170-171 -->
+
+## Files written into coding agents
+
+Each agent's page lists the files `niro mcp install` writes into that agent's settings. Niro ignores an agent settings file larger than 4 MB.
+<!-- source: src/lib/mcpClients.js:47, :84 -->

package/docs/reference-engine-commands.md

@@ -0,0 +1,56 @@
+# Engine commands: reference
+
+**These commands are answered by the local engine. `niro` passes them on unchanged.** `niro <command> --help` shows the engine's own help. The exit code is the engine's. If the engine was stopped by a signal, the exit code is 128 plus the signal's number.
+<!-- source: src/commands/engineRoutes.js:27-46, :65-84 -->
+
+| Command | What it does | Needs sign-in |
+|---|---|---|
+| `niro ask [TOOL key=value ...]` | Asks one graph tool and prints its answer. With no tool, lists the tools | yes |
+| `niro ui [--port N] [--open]` | Draws the folder's graph in your browser, at 127.0.0.1 (port 8601 by default; 0 picks a free one). Runs until Ctrl-C | no |
+| `niro env ...` | The settings this folder's code reads. See below | no |
+| `niro base-url [value]` | Shows or sets the address this folder's service answers on. An empty value goes back to the address Niro worked out. `--module` names one service inside the folder | no |
+| `niro route-rule ...` | Says where a path goes when the code does not. See below | no |
+| `niro modules` | Lists the folders inside this one that are separate services | no |
+| `niro clean [--dry-run]` | Removes, now, the graph of every folder missing from disk | no |
+| `niro db status\|check\|remove` | The graph file: its status, a check that it opens, or its removal (`remove --delete-data`) | no |
+| `niro journal [--limit N]` | Shows the tool-usage record waiting to be sent | no |
+| `niro audit [--limit N] [--export DIR]` | Shows, or writes to a folder, the coverage audit waiting to be sent | no |
+| `niro impact [--days N] [--project <name>] [--json]` | What Niro did for you in the last 7 and 30 days, from the record on this computer: tasks, answers, tokens against the by-hand estimate, searches avoided, look-ups avoided, round trips avoided, answers by kind, the median answer time, a line per project, good moments, and the graph kept current. See [evaluate-what-niro-did.md](evaluate-what-niro-did.md) | no |
+| `niro remove [--path <folder>] [--project <name>] [--branch <name>]` | Stops indexing a folder: its graph is removed and it is forgotten | no |
+| `niro projects [--json]` | Lists every project on this computer and its folders | no |
+<!-- source: src/commands/engineRoutes.js:27-46; niro-local src/niro_local/cli.py:232 (base-url), :343 (clean), :350 (remove), :373 (modules), :409 (ask), :416 (ui), :428 (db), :441 (journal), :490 (audit), :478-487 (impact), :275 (projects); src/niro_local/ui/server.py:35-36 -->
+
+## `niro env`
+
+| Form | What it does |
+|---|---|
+| `niro env scan` | Finds the settings the code reads |
+| `niro env list [--json] [--root\|--module NAME]` | Shows them |
+| `niro env get KEY` | Shows one |
+| `niro env set KEY=VALUE ...` | Sets values |
+| `niro env set-from KEY=FILE ...` | Takes a value from a file |
+| `niro env unset KEY` | Removes your value |
+| `niro env files add\|remove\|list [file]` | Names extra env files to read address values from |
+<!-- source: niro-local src/niro_local/env_args.py:30-73 -->
+
+All forms take `--path` and `--project`. Passwords and tokens are refused and never stored. The older forms `env add` and `env remove` now print "This command moved: niro-local env files ...".
+<!-- source: niro-local src/niro_local/env_args.py:30-92 -->
+
+## `niro route-rule`
+
+| Form | What it does |
+|---|---|
+| `niro route-rule list` | Shows your rules |
+| `niro route-rule unconnected` | Shows the calls Niro could not link |
+| `niro route-rule add PATTERN --to SERVICE [--from SERVICE] [--at URL] [--strip N] [--prefix P] [--id ID]` | Adds a rule |
+| `niro route-rule remove ID` | Removes one |
+| `niro route-rule replace FILE` | Replaces all rules with a JSON file |
+<!-- source: niro-local src/niro_local/route_rules_cli.py:33-54 -->
+
+At most 200 rules. A list with one bad rule is refused whole.
+<!-- source: niro-local src/niro_local/route_rules_cli.py:33-54; src/niro_local/route_rules.py:34-36 -->
+
+## Commands of the engine that `niro` does not pass on
+
+The engine has more commands that `niro` uses itself or does not pass on yet: `init`, `build`, `status`, `mcp`, `config`, `receipts`, `docs` and `redact-files`. Use `niro init`, `niro build` and `niro status` instead. A released engine refuses `build`, `ask` and `init` typed by hand, because only `niro` hands it the licence.
+<!-- source: niro-local src/niro_local/cli.py:180-516; src/niro_local/commands.py:1-72 -->

package/docs/reference-environment-variables.md

@@ -0,0 +1,89 @@
+# Environment variables
+
+**An environment variable is a setting you give a program from the shell,** for example `NIRO_LOCAL_PARSE_WORKERS=4 niro build`. Most people need none of these. Each one below has a default that works.
+
+**For the background watcher, set them where PM2 can see them.** The watcher is started by PM2, and it receives only the variables on a short list plus every `NIRO_LOCAL_*` and `LC_*` variable. Set a variable, then run `niro service install` again. The short list includes the proxy variables `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` and `NODE_USE_ENV_PROXY`, and the certificate variables `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE` and `SSL_CERT_DIR`, so that a watcher behind a company proxy can upload.
+<!-- source: src/lib/service.js:72-73, :74-108 -->
+
+## For the `niro` command
+
+| Variable | What it does | Default |
+|---|---|---|
+| `NIRO_API_URL` | The account service address | `https://aiorchestrator.niroai.dev` |
+| `NIRO_BILLING_URL` | The licence and engine-download service | `https://billing.cloud.niroai.dev` |
+| `NIRO_AUDIT_URL` | Where the coverage audit is sent | `https://audit.cloud.niroai.dev` |
+| `NIRO_MCP_SERVER_URL` | Where the tool-usage record is sent | `https://aiassistant.niroai.dev` |
+| `NIRO_AUDIT_API_KEY` | A key the coverage audit upload signs with, instead of your sign-in. The audit still reads your plan through your `niro login` sign-in first, and sends nothing without it. The background watcher is never given this key | none |
+| `NIRO_API_KEY` | Used in the same way when `NIRO_AUDIT_API_KEY` is not set. The watcher is never given it either | none |
+| `NIRO_LOCAL_BIN` | Use this engine program instead of the downloaded one. It is never replaced by an upgrade | none |
+| `NIRO_ENGINE_HOME` | Where the downloaded engine is kept | `~/.niro/bin` |
+| `NIRO_TOOL_TIMEOUT_MS` | How long an agent's tool call may take | 120000 (2 minutes) |
+| `NIRO_LOCAL_CALL_TIMEOUT_MS` | How long one call to the engine may take | 30000 |
+| `NIRO_LOCAL_START_TIMEOUT_MS` | How long the engine may take to start | 30000 |
+| `NIRO_LOCAL_BUILD_SETTLE_MS` | How long a folder must be quiet before the watcher rebuilds it | 3000 |
+| `NIRO_LOCAL_RECHECK_MS` | How often the watcher checks for missed changes | 300000 (5 minutes) |
+| `NIRO_LOCAL_RECONCILE_MS` | How often the watcher checks the list of folders and worktrees | 30000 |
+| `NIRO_LOCAL_TASK_COMPLETE` | Set to `0` to turn the end-of-task Niro line off | on |
+| `NO_COLOR`, `FORCE_COLOR` | Turn colour off, or force it on (`FORCE_COLOR=1`) or off (`0`) | automatic |
+| `TERM=dumb` | Turns off the spinner and progress bar | none |
+| `PM2_HOME` | Where PM2 keeps its files | `~/.pm2` |
+| `CODEX_HOME` | Where Codex keeps its settings | `~/.codex` |
+<!-- source: src/lib/api.js:10, :33-41; src/lib/lease.js:42, :93-97; src/lib/auditUpload.js:47, :59-62, :83-86 (the key only replaces the upload's header), :168-177 (no sign-in: "not signed in", before the plan is asked for), :183-187 ("the plan could not be read, so nothing was sent"); src/lib/lease.js:339-343 and src/lib/api.js:140 (the plan is read with the login token); src/lib/service.js:101-104 (the watcher is never given the keys); src/lib/journalUpload.js:35, :42; src/lib/engine.js:44, :112, :211; src/lib/pendingRequests.js:24, :89-92; src/mcp/localBackend.js:183, :186; src/lib/localBuild.js:36, :46; src/commands/watch.js:268; src/mcp/lineCheck.js:330; src/lib/color.js:30-32; src/lib/spinner.js:74; src/lib/progressBar.js:26; src/lib/service.js:36; src/mcp/setup.js:2260 -->
+
+Also read, for rarer cases:
+
+| Variable | Default |
+|---|---|
+| `NIRO_ENGINE_LOCK_WAIT_MS` | 300000 |
+| `NIRO_ENGINE_LOCK_STALE_MS` | 600000 |
+| `NIRO_LEASE_TIMEOUT_MS` | 15000 |
+| `NIRO_LEASE_RETRY_MS` | 60000 |
+| `NIRO_LEASE_MIN_RENEW_MS` | 5000 |
+| `NIRO_LOCAL_LIST_TIMEOUT_MS` | 20000 |
+| `NIRO_DELETE_SETTLE_MS` | 5000 |
+| `NIRO_MISSING_CONFIRM_MS` | 24 hours |
+<!-- source: src/lib/engine.js:64, :68; src/lib/lease.js:50-63; src/commands/watch.js:54, :228; src/commands/cleanup.js:412 -->
+
+## For the local engine
+
+| Variable | What it does | Default |
+|---|---|---|
+| `NIRO_LOCAL_HOME` | The engine's folder, holding the graph | `~/.niro-local` |
+| `NIRO_LOCAL_MAX_FILE_BYTES` | The largest source file read | 2097152 (2 MB) |
+| `NIRO_LOCAL_PARSE_TIMEOUT_SECONDS` | How long a file over 256 KB may take to read | 20 |
+| `NIRO_LOCAL_PARSE_WORKERS` | Worker processes for reading files | the number of processor cores, up to 8 |
+| `NIRO_LOCAL_PARSE_POOL_MIN_FILES` | The fewest files for which workers are used | 200 |
+| `NIRO_LOCAL_BUILD_LOCK_WAIT` | How long a second build waits for the first, in seconds | 120 |
+| `NIRO_LOCAL_MISSING_FOLDER_DAYS` | Days before the graph of a folder missing from disk is removed (0 turns this off) | 14 |
+| `NIRO_LOCAL_BRANCH_INDEX_IDLE_DAYS` | Idle days before a temporary project is removed (0 turns this off) | 14 |
+| `NIRO_LOCAL_MAX_ANSWER_CHARS` | The longest `code_grep` or `get_source_code` answer, in characters | 20000 |
+| `NIRO_LOCAL_SEARCH_MAX_BYTES` | The largest file `code_grep` and `get_source_code` read | 8 MB |
+| `NIRO_LOCAL_STRICT_MAX_BYTES` | The largest config or text file those two tools read | 256 KB |
+| `NIRO_LOCAL_FRESHNESS_BUDGET` | Seconds spent checking whether an answer's files changed since the build | 1.0 |
+| `NIRO_LOCAL_WAL_LIMIT_MB` | The size the graph's write-ahead file is trimmed to | 64 |
+| `NIRO_LOCAL_MAX_GIT_INDEX_BYTES` | The largest `.git/index` read | 128 MB |
+| `NIRO_LOCAL_MAX_GIT_INDEX_SECONDS` | How long reading `.git/index` may take | 5.0 |
+| `NIRO_LOCAL_GIT_INDEX_CACHE_BYTES` | Memory kept for git's file lists | 64 MB |
+| `NIRO_LOCAL_CASE_INSENSITIVE_GIT_HOSTS` | Extra git hosts whose names ignore letter case, when counting repositories | none |
+| `NIRO_LOCAL_ALWAYS_LOAD_TOOLS` | Set to `0` so agents may load Niro's tools on demand | on |
+| `NIRO_LOCAL_TURN_REMINDER` | `1` forces the reminder in answers on, `0` forces it off | automatic |
+| `NIRO_LOCAL_JOURNAL_IDLE_SECONDS` | Quiet time before a tool-usage session is ready to send | 300 |
+| `NIRO_LOCAL_REDACT_FILE_SECONDS` | How long masking one file may take, for a whole-repository push | 10 |
+<!-- source: niro-local src/niro_local/registry.py:40-51; src/niro_local/walk.py:79; src/niro_local/build/parse_time_limit.py:44-57; src/niro_local/build/parallel_parse.py:59-61, :197-198; src/niro_local/build/lock.py:59; src/niro_local/cleanup.py:37-40; src/niro_local/mcp/source_tools.py:122, :151, :162; src/niro_local/mcp/freshness.py:76; src/niro_local/graph/sqlite_writer.py:105-111; src/niro_local/gitindex.py:42-44, :121; src/niro_local/licence/limit.py:65; src/niro_local/mcp/server.py:285-298, :320; src/niro_local/journal/store.py:81; src/niro_local/redact/files.py:50 -->
+
+The engine reads on-and-off values as `1`, `true`, `yes` or `on` (on) and `0`, `false`, `no` or `off` (off). For most variables, a value it cannot read is ignored with a warning, and the default is used.
+<!-- source: niro-local src/niro_local/settings.py:11-36 (int_env, bool_env) -->
+
+**Seven variables are read as plain numbers. A value that is not a number stops the engine with an error:** `NIRO_LOCAL_MAX_FILE_BYTES`, `NIRO_LOCAL_MAX_ANSWER_CHARS`, `NIRO_LOCAL_SEARCH_MAX_BYTES`, `NIRO_LOCAL_STRICT_MAX_BYTES`, `NIRO_LOCAL_FRESHNESS_BUDGET`, `NIRO_LOCAL_BUILD_LOCK_WAIT` and `NIRO_LOCAL_JOURNAL_IDLE_SECONDS`.
+<!-- source: niro-local src/niro_local/walk.py:79; src/niro_local/mcp/source_tools.py:122, :151, :162; src/niro_local/mcp/freshness.py:76; src/niro_local/build/lock.py:59; src/niro_local/journal/store.py:81 (each a bare int() or float()) -->
+
+## Do not set
+
+These are set by `niro` itself, or are for Niro's developers:
+
+- `NIRO_LOCAL_LEASE_FD_IN`, `NIRO_LOCAL_LEASE_FD_OUT`
+- `NIRO_START_BOOTSTRAPPED`, `NIRO_UPGRADE_HANDOVER`, `NIRO_OUTPUT_PREFIX`
+- `NIRO_MCP_MODE`, `NIRO_MCP_TRANSPORT`, `NIRO_DISABLE_ROUTING`
+- `NIRO_LOCAL_LEASE_PUBLIC_KEY`, `NIRO_LOCAL_LEASE_KEY_ID`
+- `NIRO_LOCAL_FAST_PATH`, `NIRO_LOCAL_CHANGES_ONLY_WRITE`, `NIRO_LOCAL_SQL_PLAN_CHECK`, `NIRO_LOCAL_C_UNIQUE_DEFINITION_FALLBACK`
+<!-- source: src/lib/lease.js:87-90; src/commands/start.js:66; src/commands/upgrade.js:51; src/mcp/setup.js:29; src/mcp/server.js:296, :359, :1298-1302; niro-local src/niro_local/licence/keys.py:13-34; src/niro_local/build/fast_path.py:110; src/niro_local/build/builder.py:261; src/niro_local/graph/sqlite_writer.py:127; src/niro_local/build/link_targets.py:44 -->

package/docs/reference-exit-codes.md

@@ -0,0 +1,67 @@
+# Exit codes
+
+**An exit code is the number a command hands back when it ends.** 0 means it worked. Any other number means it did not. Scripts read it to decide what to do next.
+
+| Code | Meaning |
+|---|---|
+| 0 | It worked. Signing in also ends with 0 when your account is on the waiting list, or when a trial request was sent |
+| 1 | It failed. The message above it says why. This is the code for nearly every failure |
+| 2 | `niro docs-send`, or an engine LLM option, in this release, which has no LLM documentation |
+| 130 | You pressed Ctrl-C at a question |
+| 128 plus a signal number | An engine command was stopped by a signal |
+| 129, 130, 143 | `niro audit-push-repo` was interrupted (hang-up, Ctrl-C, or stop). It deletes its masked copies before ending |
+<!-- source: src/index.js:30-39, :145, :544-556; src/commands/login.js:286-305; src/lib/prompt.js:85; src/lib/choose.js:96; src/commands/engineRoutes.js:73-84; src/lib/repoPush.js:295; niro-local src/niro_local/cli.py:84-90 -->
+
+## Common causes of code 1
+
+- **Setup:**
+  - `niro start` with no terminal;
+  - a computer type with no engine;
+  - Node older than 18;
+  - a folder that is missing, protected, or your home folder;
+  - not signed in;
+  - the engine download failed;
+  - the graph database cannot open;
+  - the build failed;
+  - over the line limit.
+<!-- source: src/commands/start.js:103, :169, :180, :189, :209, :239, :254, :288, :317 -->
+- **Sign-in:**
+  - an empty key, email or password;
+  - an invalid key;
+  - timed out;
+  - account blocked, access denied, or the code expired.
+<!-- source: src/commands/login.js:54, :70, :86, :98, :104, :214, :294-304 -->
+- **Folders:**
+  - not signed in;
+  - no engine;
+  - two folders given;
+  - a protected folder;
+  - a folder not added yet;
+  - over the limit;
+  - the engine refused.
+<!-- source: src/commands/initLocal.js:34, :63 -->
+- **Status and plan:**
+  - the folder is not indexed;
+  - the plan could not be read.
+<!-- source: src/commands/status.js:97-98; src/commands/plan.js:21, :42 -->
+- **Uninstall:**
+  - no terminal and no `--yes`;
+  - a step failed.
+<!-- source: src/commands/uninstall.js:109, :162 -->
+
+## `niro upgrade`
+
+| Code | Meaning |
+|---|---|
+| 1 | npm failed or was interrupted |
+| 2 | npm said it worked, but there is no `niro` in npm's global folder |
+| 3 | The new version could not finish the upgrade (handover failed) |
+| 4 | The refresh did not finish: at least one agent was not refreshed |
+| 5 | This is not the global copy of `niro` (for example a linked working copy). Use `--force` to upgrade anyway |
+<!-- source: src/commands/upgrade.js:54-58, :142, :192 -->
+
+## The engine
+
+- `status --check` ends with 0 when the folder is indexed, and 1 when it is not.
+- A licence refusal ends with 1.
+<!-- source: niro-local src/niro_local/cli.py:266, :2661 -->

package/docs/reference-limits.md

@@ -0,0 +1,75 @@
+# Limits
+
+**Every limit Niro applies, its default, and how to change it where you can.** Limits keep one question or one file from taking over your computer or flooding your agent.
+
+## Computer
+
+| Limit | Value |
+|---|---|
+| Node.js | 18 or newer |
+| Free disk space before `niro start` warns | 2 GB |
+| Computers | macOS and Linux, Intel and ARM. Windows: supported, details coming |
+<!-- source: src/lib/machineCheck.js:13-14; src/lib/engine.js:79-90; Windows: Niraj, 2026-11-10 -->
+
+## Plan
+
+| Limit | Value |
+|---|---|
+| Lines you can index | Set by your plan. See [licence-and-plans.md](licence-and-plans.md) |
+| Working without reaching Niro's licence service | About a day |
+<!-- source: src/lib/planUsage.js:53-66; src/lib/lease.js:282-286 -->
+
+## Building
+
+| Limit | Default | Change with |
+|---|---|---|
+| Largest source file read | 2 MB | `NIRO_LOCAL_MAX_FILE_BYTES` |
+| Time to read a file over 256 KB | 20 seconds | `NIRO_LOCAL_PARSE_TIMEOUT_SECONDS` |
+| How long a second build waits for the first | 120 seconds | `NIRO_LOCAL_BUILD_LOCK_WAIT` |
+| Repositories inside one folder you add | 60. More is refused | none |
+| Route rules per folder | 200 | none |
+| Clean-up of temporary projects and missing folders | 14 days | `NIRO_LOCAL_BRANCH_INDEX_IDLE_DAYS`, `NIRO_LOCAL_MISSING_FOLDER_DAYS` |
+| New worktree build attempts | 3, with waits of 2 and then 10 minutes | none |
+<!-- source: niro-local src/niro_local/walk.py:79; src/niro_local/build/parse_time_limit.py:44-57; src/niro_local/build/lock.py:59; src/niro_local/modules/resolve.py:61; src/niro_local/route_rules.py:34-36; src/niro_local/cleanup.py:37-40; src/lib/localWorktrees.js:71-72 -->
+
+## Answers to agents
+
+| Limit | Default |
+|---|---|
+| Time for one tool call from an agent | 120 seconds (`NIRO_TOOL_TIMEOUT_MS`) |
+| Time for one call to the engine | 30 seconds |
+| Names in one batch question | 10 |
+| Call chain depth | 3 by default, at most 8 |
+| Blast radius and impact depth | 3 by default, from 1 to 5 |
+| Exception flow depth | 3 by default, at most 5 |
+| Callers per page | 300 |
+| Types per page | 100 |
+| Events, data stores per page | 50 |
+| Routes, outbound calls per page | 20 |
+| Matches for one name (`resolve_name`) | 25 |
+| Source shown with an answer | the method asked about in full, up to 150 lines; 12 lines of each other method; at most 20 methods |
+<!-- source: src/lib/pendingRequests.js:24; src/mcp/localBackend.js:100, :183; niro-local src/niro_local/mcp/queries.py:55-56, :215, :2537-2538; src/niro_local/mcp/impact.py:40-41; src/niro_local/mcp/server.py:1103-1114; src/niro_local/mcp/purpose.py:49-58 -->
+
+## `code_grep` and `get_source_code`
+
+| Limit | Default |
+|---|---|
+| Search time before the answer is cut, with a way to continue | 1.5 seconds |
+| Answer length | 20,000 characters (`NIRO_LOCAL_MAX_ANSWER_CHARS`) |
+| Files per page | 50, at most 200 |
+| Matches per file | 5, at most 50 |
+| Search patterns in one call | 10 |
+| Items in one `get_source_code` batch | 25 |
+| Lines in one read | 2,000 |
+| Characters per line shown | 500 |
+| Largest file searched | 8 MB (`NIRO_LOCAL_SEARCH_MAX_BYTES`) |
+| Largest config or text file read | 256 KB (`NIRO_LOCAL_STRICT_MAX_BYTES`) |
+<!-- source: niro-local src/niro_local/mcp/source_tools.py:101-162 -->
+
+## Sign-in and network
+
+| Limit | Value |
+|---|---|
+| Time to approve a sign-in code in the browser | 10 minutes, unless the service says otherwise |
+| Time limit on sign-in and other account calls | **None.** On a stalled network they can wait until you press Ctrl-C |
+<!-- source: src/commands/login.js:23-24; src/lib/api.js:146-149 -->