@niroai/niro 0.17.0 → 0.18.0

package/docs/answer-shapes.md

@@ -0,0 +1,69 @@
+# Ask for less: the `answer` input
+
+**Most questions need only part of an answer.** An agent often wants to know whether something exists, how many there are, or where they are. The full answer also carries signatures, notes and sometimes code. The `answer` input asks a tool for a short form of the same list.
+<!-- source: niro-local docs/usecases/answer-shapes.md "What it is" (43cce717) -->
+
+**An everyday comparison:** asking a librarian "how many books do you have on this?" instead of "bring me every book on this".
+
+## Which tools take it
+
+`code_grep`, `get_call_chain`, `get_reverse_call_chain`, `get_blast_radius`, `get_impact_analysis` and `get_class_structure`.
+<!-- source: niro-local src/niro_local/mcp/shapes.py:24-45 (VALUES and the three descriptions); docs/reference-mcp-tools.md (generated from 43cce717, the `answer` rows) -->
+
+| Value | What comes back | Use it when |
+|---|---|---|
+| `exists` | yes or no, with the total | you only need to know whether there is any |
+| `count` | the numbers only | you need "how many" (callers, affected methods, matches, members) |
+| `locations` | one line per entry: `file:line` and the exact id to pass to the next call | you will open a few of them, or ask about one next |
+| `names` | one name per line | you need a list to read, not places |
+| `match` (only `code_grep`) | only the text the pattern matched, at its place | you want the value, not the whole line |
+<!-- source: niro-local src/niro_local/mcp/shapes.py:30-45 -->
+
+## What stays true in a short answer
+
+- **The numbers are the full answer's numbers.** They come from the same code. For `code_grep`, the count covers every file searched, not only the page shown.
+<!-- source: niro-local docs/usecases/answer-shapes.md rule 4 -->
+- **Notes that change what the numbers mean are kept:** "confidence: partial", the "Not listed" note about calls Niro could not place, and `code_grep`'s PARTIAL and SKIPPED lines.
+<!-- source: niro-local docs/usecases/answer-shapes.md rule 6 -->
+- **Every short answer ends with one line in square brackets** saying what was left out and how to get it. For example: `[shown 39 of 100 callers; offset=39 shows the next callers]`.
+<!-- source: niro-local docs/usecases/answer-shapes.md rule 7; real answer in the Keycloak run of 2026-11-10 (scratchpad niro-cli-task-playbooks/runs/eval-01-loc.txt) -->
+- **A short answer never carries code.** If you also ask for source (`include_source_code`, or `purpose=DEBUG`), the footer says the code was left out.
+<!-- source: niro-local docs/usecases/answer-shapes.md rule 3 -->
+- **A short name that matches several methods is answered once per match,** up to 5. For example, `ErrorResponse.error` in Keycloak has two overloads (methods with the same name and different parameters), and `answer=count` gives a count for each: 100 callers and 3 callers.
+<!-- source: niro-local docs/usecases/answer-shapes.md rule 9; `niro-local ask get_reverse_call_chain method_fqn=ErrorResponse.error answer=count` on Keycloak 968726fe66, 2026-11-10 (runs/chg-20-overloads.txt) -->
+- **Without `answer`, every answer is exactly what it was before.**
+<!-- source: niro-local docs/usecases/answer-shapes.md "What must not change"; merge commit 43cce717 ("476 of 476 calls without answer identical") -->
+
+## `purpose` and `answer` together
+
+`purpose` chooses which list you get, and `answer` shortens that list. So `answer=count` with `purpose=ASSESS_RISK` gives the same number as the ASSESS_RISK answer would.
+<!-- source: niro-local docs/usecases/answer-shapes.md rule 2 -->
+
+## A real example
+
+A search of the Keycloak source (a public Java project) for an error message, asking only how many places hold it:
+
+```
+niro ask code_grep pattern="User exists with same" answer=count
+10 matching lines in 4 files in the files searched so far
+PARTIAL: the search stopped at its 1.5 s limit after 9793 of 11045 file(s) ...
+[counts only; ask without answer= for the list]
+```
+<!-- source: runs/exc-01-grep-count.txt (Keycloak 968726fe66, niro-local 43cce717, 2026-11-10; `niro ask` passes its words to the same engine command, src/commands/engineRoutes.js:28) -->
+
+The PARTIAL line is kept, because it changes what "10" means: it is a floor. `code_grep` stops after a time limit (1.5 seconds a call), so on a busy machine the same search can count fewer, even "0 matching lines" with PARTIAL. A count with PARTIAL never means "none". Call again with the `continue_from` it gives, or pass a folder as `path_pattern` to search less; on a busy machine even one folder can stop early, and the PARTIAL line says so.
+<!-- source: runs/exc-01-grep-count.txt ("Call again with continue_from=9793"); niro-local docs/NIRO-LOCAL-ISSUES.md entry "2026-11-10: code_grep counts change with machine load, and a busy machine can give '0 matching lines ... PARTIAL'" (OPEN, committed f1a9fe59); scratchpad niro-cli-task-playbooks-check/reruns (claim check round 1: 59 of 59 graph-tool reruns byte-identical, 7 code_grep reruns differed under load 17 to 30) -->
+
+The graph tools have no such limit: the same question on the same graph gives the same answer.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md entry "2026-11-10: code_grep counts change with machine load, and a busy machine can give '0 matching lines ... PARTIAL'" (OPEN, committed f1a9fe59); scratchpad niro-cli-task-playbooks-check/reruns (claim check round 1: 59 of 59 graph-tool reruns byte-identical, 7 code_grep reruns differed under load 17 to 30) -->
+<!-- source: runs/exc-01-grep-count.txt; runs/exc-03-grep-full.txt (path_pattern=services/, no PARTIAL line) -->
+
+## How much it saves
+
+It depends on the question and on your code: a count is a line or two, while a full list names every entry. The shapes were chosen by reading recorded calls from real sessions with what the agent did next, and checking which short form still held what the agent then used. How that was measured is in [tokens-speed-and-accuracy.md](tokens-speed-and-accuracy.md).
+<!-- source: scratchpad niro-local-answer-shapes/page-data.json and BRIEF.md (the trial); niro-local docs/usecases/answer-shapes.md "What the replay showed" -->
+
+## Not in this release
+
+Line filters (keep only lines matching a pattern, or the first N lines) were planned and not built.
+<!-- source: niro-local docs/usecases/answer-shapes.md "Not in this change" (parked by Niraj, D6) -->

package/docs/builds-and-updates.md

@@ -0,0 +1,68 @@
+# Builds and updates
+
+**Niro keeps the graph in step with your files by rebuilding it in the background.** You rarely need to run a build yourself.
+
+## The first build
+
+`niro start` builds the folder you are in. `niro init <folder>` adds and builds another folder.
+<!-- source: src/commands/start.js:61; src/index.js:490-502 -->
+
+The measured time for a full build of a repository of about 9,000 files is about 103 seconds.
+<!-- source: niro-local TODO.md:189 -->
+
+## Keeping it current
+
+- **Who does it.** `niro start` installs a background watcher called `niro-watch`. It is run by PM2, a tool that keeps programs running in the background.
+<!-- source: src/commands/start.js:390-411; src/lib/watchDaemon.js:34-79 -->
+- **When it starts.** Where it can, the watcher starts again every time you log in.
+<!-- source: src/lib/watchDaemon.js:75-79 -->
+- **When it rebuilds.** About 3 seconds after a folder stops changing. Only one build runs at a time. If files change during a build, one more build is queued.
+<!-- source: src/lib/localBuild.js:16-21, :36 (NIRO_LOCAL_BUILD_SETTLE_MS, default 3000) -->
+- **Missed changes.** Every 5 minutes it also checks for changes it may have missed.
+<!-- source: src/lib/localBuild.js:46 (NIRO_LOCAL_RECHECK_MS, default 300000) -->
+- **On start.** When the watcher starts, it builds every folder once.
+<!-- source: src/commands/watch.js:578 -->
+- **Folders that go away.** A folder deleted from disk stops being watched.
+<!-- source: src/commands/watch.js:594-596 -->
+
+`niro status` shows whether the watcher is running. If it is not, run `niro service install`.
+<!-- source: src/commands/status.js:35-40 -->
+
+## A rebuild does only what is needed
+
+**A rebuild processes the files that changed, and everything connected to them.** The result is the same graph a full build would give. To parse every file again anyway, run:
+
+```
+niro build --full
+```
+<!-- source: niro-local CLAUDE.md ("An incremental build processes what changed and everything connected to it, and must equal a full build"); src/index.js:517-527 (--full) -->
+
+## How Niro notices changes
+
+Niro reads your files to see what changed. **It never runs git, and never reads your history.** It reads three small git files:
+
+- `.git/HEAD`, to know your branch;
+- `.git/index`, to know which files git tracks, so that it applies `.gitignore` the way git does;
+- `.git/config`, to tell two copies of one repository apart.
+<!-- source: niro-local CLAUDE.md amendments 2026-11-03, 2026-11-04, 2026-11-07; src/niro_local/repository_identity.py:1-24; src/niro_local/gitindex.py -->
+
+## While a build runs
+
+During a full build, the graph is being rewritten. Most tools then say so instead of answering, and suggest searching files for that request. `get_index_status`, `code_grep` and `get_source_code` keep answering. During a smaller rebuild, answers carry a note listing the files being updated.
+<!-- source: niro-local src/niro_local/mcp/freshness.py:309-334, :598 -->
+
+## Files left out
+
+| Left out | Default limit | Change it with |
+|---|---|---|
+| A source file larger than | 2 MB | `NIRO_LOCAL_MAX_FILE_BYTES` |
+| A file over 256 KB that takes longer to read than | 20 seconds | `NIRO_LOCAL_PARSE_TIMEOUT_SECONDS` |
+<!-- source: niro-local src/niro_local/walk.py:79; src/niro_local/build/parse_time_limit.py:44-57 -->
+
+Answers name the files left out (the first 5), with a line starting "SKIPPED". Files that git ignores, editor scratch files and links to other places on disk (symlinks) are not read either.
+<!-- source: niro-local src/niro_local/too_large.py:41, :164-182; src/niro_local/mcp/source_tools.py:825-850 -->
+
+## Using several processor cores
+
+A build with 200 or more files to read uses several worker processes: by default one per processor core, up to 8. Change the number with `NIRO_LOCAL_PARSE_WORKERS`.
+<!-- source: niro-local src/niro_local/build/parallel_parse.py:59-61, :197-198 -->

package/docs/cloud-README.md

@@ -0,0 +1,372 @@
+# niro: CLI + MCP server (`@niroai/niro`)
+
+Command-line tool and MCP server for [Niro](https://niroai.dev). Niro reads your code and builds
+a map of how it fits together, so your AI assistant answers from that map instead of guessing.
+
+One package installs three things: the `niro` command, the MCP server your assistant talks to,
+and two agent skills so you can ask for Niro tasks in plain English.
+
+Requires Node.js 18 or newer. Niro is in private beta: you need an access code, which you get
+from the **Request Access** button at [www.niro.ai](https://www.niro.ai).
+
+---
+
+## Get started
+
+```bash
+cd ~/code/my-service
+npx @niroai/niro start
+```
+
+Signs you in, installs itself, shows you what it is about to index and asks first, builds the
+graph, and connects your assistant. Run it again in any other repo; it skips what is done.
+
+Then restart your assistant and ask it something:
+
+```
+"What breaks if I change PaymentService.refund?"
+```
+
+---
+
+## What you can ask for
+
+| | |
+|---|---|
+| Anything about your code | call chains, structure, entry points, API endpoints |
+| What breaks if you change something | blast radius across services, including callers a search cannot find |
+| A standing review | issues already in the code, by severity, in the browser |
+| Root causes from your alerts | connect Sentry, Slack, Jira, Linear or CloudWatch and an alert arrives as a bug with the analysis done |
+
+---
+
+## Everyday commands
+
+```bash
+niro status
+```
+Is my index up to date? It answers about the project this folder is synced to **on the branch you
+are on**, so once you have run `niro new-temp-project` it reports that copy rather than the shared
+project. Name one explicitly to ask about a different project: `niro status <project-id>`.
+
+```bash
+niro start
+```
+Index another repo. Cross-service answers need more than one.
+
+```bash
+niro info
+```
+What does Niro know about this folder: repo, branch, which project it maps to.
+
+```bash
+niro projects
+```
+Every project in your account.
+
+```bash
+niro build
+```
+Rebuild the index by hand and watch it finish. Like `niro status`, it picks the project for the
+branch you are on, so on a branch with a temporary project it rebuilds that one. Name a project to
+rebuild a different one.
+
+```bash
+niro upgrade
+```
+Get the latest version, and bring your hooks, skills and watcher with it. See
+[Upgrading](#upgrading).
+
+```bash
+niro doctor
+```
+Check this machine against the server and repair what is safe to repair. Today that is
+`niro doctor sync-registry`, which fixes folders and `.niro-project` files left pointing at projects
+that have gone or been renamed. The background watcher runs it for you every six hours.
+
+---
+
+## Working on a branch
+
+Your index covers the branches you chose to build. On a branch nothing covers, Niro says so
+rather than answering from stale code.
+
+```bash
+niro new-temp-project
+```
+Run once in the repo folder. Makes a private copy that follows your branch and uncommitted
+edits. Your shared project is untouched.
+
+```bash
+niro discard-temp-project
+```
+Run when the branch is merged. Forgotten copies are cleaned up after two weeks.
+
+If a copy is deleted for you, or a project is renamed, your machine is not told and the folder keeps
+pointing at something that is gone. `niro doctor sync-registry` sorts that out, and the background
+watcher runs it every six hours — see [When a project is deleted](#when-a-project-is-deleted).
+
+The full guide to working on branches with hosted Niro is not shipped in this package. For branches with the local graph, see [worktrees-and-branches.md](worktrees-and-branches.md).
+
+---
+
+## When a project is deleted
+
+Delete a project, or let an unused private copy expire, and your machine is not told. The folder
+carries on pointing at something that is no longer there.
+
+That is not just untidy. It is what makes `niro new-temp-project` in another folder say the slot is
+already taken, naming a copy that no longer exists. And a `.niro-project` file left naming a deleted
+project keeps answering, because it is read before your git remote.
+
+The background watcher checks every six hours and sorts this out for you. `niro
+doctor sync-registry` does the same thing on demand.
+
+What it does depends on what went missing:
+
+| What is gone | What happens to your folder |
+|---|---|
+| A private copy of a project | Goes back to the original project and carries on syncing |
+| The project itself | Left alone if the repo still exists; unregistered only when both are gone |
+| Neither, just a stale `.niro-project` | Repaired if your git remote says which project it should name; removed if it names nothing and is not shared; otherwise you are told |
+
+It never deletes anything on the server, and it never touches a `.niro-project` file. Everything it
+acts on has already gone. It only acts on what it can check, too: a folder git cannot read, or a
+project it could not reach, is left exactly as it is and reported. A bad connection can never cost
+you a working folder.
+
+**How it decides what to do with a stale `.niro-project`.** That file can hold a project's name
+rather than its id, so a renamed project looks exactly like a deleted one. Niro uses a second signal:
+your folder's git remote. If the remote points at exactly one project, the pin is rewritten to that
+project's id, which cannot be broken by a future rename. If the remote points at nothing either, the
+pin identifies nothing and is removed.
+
+**Unless the file is committed.** A `.niro-project` in git is shared with everyone who clones the
+repo, and what looks like a dead project to you may be a colleague's. Niro never changes a committed
+one for you. It tells you, and you decide.
+
+`niro info` also mentions it when you are standing in an affected folder, so you do not have to go
+looking.
+
+## When you run out of private copies
+
+You get a limited number of private copies of each project. If you hit that limit, Niro tells you
+which branches are holding them, and the CLI adds where each one is checked out:
+
+```
+You already have 5 working copies of this project, which is the limit (5).
+They are for: feature/a, feature/b, feature/c, feature/d, feature/e.
+
+    You have 5 working copies of this project on this machine:
+      feature/a    /home/you/work/service
+      feature/b    /home/you/work/service-wt2
+      ...
+```
+
+Run `niro discard-temp-project` in one you have finished with, then try again. Copies nobody has
+touched for a while are also cleared automatically.
+
+---
+
+## Measure what Niro changes
+
+```bash
+niro ab enable
+```
+Runs Niro **off** for half your sessions for 14 days, so you can compare. Applies to your whole
+account, and asks before it starts.
+
+```bash
+niro ab report
+```
+The with-Niro and without-Niro comparison.
+
+```bash
+niro ab disable
+```
+Stop early. Every session uses Niro again.
+
+---
+
+## Connect another assistant
+
+```bash
+niro mcp install
+```
+Pick from the list, or `--client <id>` to skip the prompt. Restart the assistant afterwards.
+
+```bash
+niro mcp install --list
+```
+All 14 supported clients and the file each one is configured through.
+
+```bash
+niro mcp uninstall --all -y
+```
+Removes everything install added: MCP config, hooks and skills. Leaves you logged in.
+
+Per-client details: [docs/connect-your-ai-assistant.md](https://unpkg.com/@niroai/niro/docs/connect-your-ai-assistant.md)
+
+---
+
+## Managing projects
+
+```bash
+niro edit --list-env
+```
+Environment variables Niro found, with secret values masked.
+
+```bash
+niro edit --set-env KEY=VALUE
+```
+Set one. The value is never printed or logged.
+
+```bash
+niro edit --alias new-name
+```
+Rename a project.
+
+```bash
+niro remove --unmap-repo <gitId>
+```
+Detach a repo from a project. Nothing is deleted.
+
+```bash
+niro remove --project --confirm-name <name>
+```
+Delete a whole project. Destructive, hence the confirmation. It refuses on a temporary project and
+sends you to `niro discard-temp-project` instead, because that removes the copy **and** points this
+folder back at the shared project; deleting it here would leave the folder aimed at a project that
+no longer exists. `niro delete` refuses for the same reason.
+
+---
+
+## Keeping in sync
+
+```bash
+niro service status
+```
+Is the background watcher running? It syncs your indexed folders as you edit.
+
+```bash
+niro service install
+```
+Start it and have it come back on login. Needs PM2 (`npm install -g pm2`).
+
+```bash
+niro watch
+```
+Watch this folder in the foreground instead, for one session.
+
+---
+
+## Upgrading
+
+**Check which you are on first:**
+
+```bash
+niro --version
+```
+
+**On 0.13.0 or newer**, one command:
+
+```bash
+niro upgrade
+```
+
+Replaces the package with the latest published version, then puts back the two things replacing the
+package cannot reach: it re-runs the installer for every assistant you have configured, and
+restarts the background watcher. Restart your assistant afterwards.
+
+**On anything older than 0.13.0**, you do not have `niro upgrade` yet, so it is two commands, once:
+
+```bash
+npm install -g @niroai/niro@latest
+niro upgrade --finish
+```
+
+The first gets the package. The second does the half npm cannot: your hooks, skills and the
+watcher. After that, `niro upgrade` on its own is enough. Do not stop after the first command:
+that leaves you on the new version running the old version's hooks, skills and instruction files,
+which is the problem `niro upgrade` exists to solve.
+
+**Why it is more than an npm install.** The hooks, skills and instruction files are written into
+your home folder as fixed text when you install, not read out of the package as it runs, so a newer
+package does not change them. The watcher is a long-running process still holding the code it
+started with. The MCP config is the one part that needs nothing done to it: it runs plain `niro`
+from your `PATH` with no version pinned in it, so the new server is picked up on its own.
+
+**Restart your assistant last.** Skills and hooks are read when it starts, so nothing above reaches
+a session that is already open.
+
+Fully by hand, if you would rather:
+
+```bash
+npm install -g @niroai/niro@latest
+niro mcp install       # once per assistant you use
+niro service install   # only if you run the watcher
+```
+
+`niro start` upgrades nothing. On a machine that has connected an assistant once it skips the
+connect step, so the old hooks and skills stay where they are.
+
+---
+
+## Reference
+
+Add `--help` to any command for its flags. Add `--json` to `whoami`, `info`, `status`,
+`projects`, `build`, `ab report`, `edit --list-env` and `doctor sync-registry` for machine-readable
+output.
+
+| File | What it holds |
+|---|---|
+| `~/.niro/credentials.json` | Your login, mode `0600` |
+| `~/.niro/config.json` | Backend URLs saved during setup |
+| `~/.niro/projects.json` | Per-folder sync state |
+| `.niro-project` | Pins a repo folder to a Niro project |
+
+| Variable | What it sets | Default |
+|---|---|---|
+| `NIRO_API_URL` | Backend the CLI talks to | `https://aiorchestrator.niroai.dev` |
+| `NIRO_MCP_SERVER_URL` | Backend the MCP server talks to | `https://aiassistant.niroai.dev` |
+| `NIRO_API_KEY` | Read by the MCP server when running headless. For CI, prefer `niro login --api-key` | none |
+| `NIRO_UPLOAD_CONCURRENCY` / `_TIMEOUT_MS` / `_MAX_TOTAL_BYTES` / `_MAX_FILES` | Tune the first upload | 4 / 60000 / 1 GiB / 50000 |
+
+Running your own instance? Set `NIRO_API_URL` before `niro login`, and pass `--url <url>` to
+`niro mcp install`.
+
+---
+
+## What leaves your machine
+
+Source and config files from the folder you confirmed, and nothing else. `.gitignore` is
+honoured, so a gitignored `.env` is never sent. Raw `.env` and `*.properties` files are not in
+the upload set; committed files like `application.yml` and `.env.example` are, because they hold
+defaults rather than secrets.
+
+Secret values are never printed: `--set-env` does not echo them, and `--list-env` masks anything
+that looks like a secret by name or by content.
+
+---
+
+## If something is wrong
+
+**The assistant ignores Niro.** Restart it. Skills load at startup, so a fresh `niro mcp install`
+does nothing until you do.
+
+**`niro: command not found`.** Your global npm bin is not on `PATH`. Check with `npm bin -g`.
+
+**This folder maps to several projects.** Pass `--project <alias|id>`, or pick one when asked.
+
+**Auto-sync is not running.** `npm install -g pm2`, then `niro service install`.
+
+**A command or feature in the changelog is missing.** You are on an older version. Check with
+`niro --version`, then see [Upgrading](#upgrading): before 0.13.0 it takes two commands, after it
+one. Plain `npm install -g` on its own always leaves your hooks and skills on the old version.
+
+**A folder was refused.** Niro will not index your home folder, or a folder with no build file
+in it. Point it at the repo you meant.
+
+---
+
+MIT

package/docs/configuring-a-folder.md

@@ -0,0 +1,51 @@
+# Telling Niro what it cannot work out
+
+**Sometimes the code alone does not say where a call goes.** For example, a service calls `ORDERS_URL + "/orders"`, and the value of `ORDERS_URL` is only set when the program is deployed. Niro then cannot link that call to the orders service's route. These commands let you fill in what is missing, for one folder. Run each one inside the folder.
+
+## Which folders are services
+
+```
+niro modules
+```
+
+Lists the folders inside this one that Niro treats as separate services (deployables).
+<!-- source: src/commands/engineRoutes.js:34; niro-local src/niro_local/cli.py:373 -->
+
+## The settings your code reads
+
+```
+niro env scan                       # find the settings the code reads
+niro env list                       # show them
+niro env set ORDERS_URL=http://orders:8080
+niro env set-from ORDERS_URL=deploy/orders.env
+niro env unset ORDERS_URL
+niro env files add deploy/staging.env
+```
+
+Niro reads the template files `.env.example`, `.env.sample` and `.env.template` by itself. A real env file is read only if you name it with `niro env files add`, and then only its address values. **Passwords and tokens are refused and never stored.**
+<!-- source: niro-local src/niro_local/env_args.py:30-73, :34, :65-69; docs/usecases/env-settings.md -->
+
+## The address a service answers on
+
+```
+niro base-url                         # show it
+niro base-url http://orders:8080      # set it
+niro base-url ""                      # go back to the address Niro worked out
+```
+
+You can also give it when adding the folder: `niro init --base-url <url>`.
+<!-- source: niro-local src/niro_local/cli.py:232; src/index.js:490-502 -->
+
+## Where a path goes, when the project does not say
+
+```
+niro route-rule unconnected                           # calls Niro could not link
+niro route-rule add "/api/orders/*" --to orders
+niro route-rule list
+niro route-rule remove <id>
+```
+
+A rule says that calls to a path go to a given service. You can have up to 200 rules. Rules are copied to temporary projects for new branches.
+<!-- source: niro-local src/niro_local/route_rules_cli.py:33-54; src/niro_local/route_rules.py:34-36; src/niro_local/temporary.py:187-240 -->
+
+Niro uses the new values at the next build. To build now, run `niro build`.

package/docs/connect-ci.md

@@ -0,0 +1,24 @@
+# Niro in CI
+
+**CI is a build machine with no person at it.** Niro's setup is built for a person at a terminal, so CI support is partial.
+
+## What does not work without a person
+
+- **`niro start` needs a terminal.** Without one it stops with "`niro start` is interactive and there is no terminal to prompt on."
+<!-- source: src/commands/start.js:97-104 -->
+- **Connecting agents needs a browser sign-in.** `niro mcp install` accepts only the browser sign-in that `niro start` does. After `niro login --api-key` it refuses with "Not signed in. Run niro login".
+<!-- source: src/mcp/setup.js:574-583, :2950-2955 -->
+
+- **Sending the coverage audit.** The audit reads your plan through your `niro login` sign-in before it sends anything, so on a machine with no sign-in nothing is sent. Setting `NIRO_AUDIT_API_KEY` does not change that: the key only replaces the upload's own sign-in header. When the sign-in is missing, `niro audit-send` says so: "Nothing sent: not signed in. The audit reads your plan through your `niro login` sign-in, so run `niro login` first."
+<!-- source: src/lib/auditUpload.js:83-86, :168-177, :183-187; src/commands/auditSend.js:19-20; src/lib/lease.js:339-343; src/lib/api.js:140 -->
+
+## What works
+
+- **Confirming without a prompt.** `niro uninstall --yes` and `niro audit-push-repo --yes` skip their question. Without a terminal they need `--yes`, and refuse without it.
+<!-- source: src/index.js:60-67, :117-125; src/commands/uninstall.js:108; src/lib/repoPush.js:350 -->
+- **Signing in with a key from a pipe.** `niro login --api-key` reads the key from a pipe when there is no terminal. This way of signing in is due to be removed.
+<!-- source: src/commands/login.js:44-52; src/lib/prompt.js:47-61; TODO.md:51-62 -->
+
+## Not yet established
+
+Whether a key-based sign-in lets `niro build` and `niro ask` run on a build machine has not been tested. Treat Niro in CI as not supported until this page says otherwise.

package/docs/connect-overview.md

@@ -0,0 +1,20 @@
+# Every way into Niro
+
+**There are several ways to reach the graph, and not all of them work in this version.** This table says which do. Each "yes" comes from the code, and each "no" says why.
+
+| Way in | Works today? | Page |
+|---|---|---|
+| The terminal: `niro ask`, `niro ui`, `niro status`, `niro plan` | **Yes** | [connect-terminal.md](connect-terminal.md) |
+| 14 coding agents, connected over MCP | **Yes.** How much help each agent gets differs (see its page) | [connect-your-ai-assistant.md](connect-your-ai-assistant.md) |
+| Any other MCP client | **Yes, by hand:** the installer prints a block to paste | [connect-your-ai-assistant.md](connect-your-ai-assistant.md#other-mcp-clients) |
+| Review bots (Cursor Bugbot, CodeRabbit, Copilot review) | **No** | [connect-review-bots.md](connect-review-bots.md) |
+| Agents in a web browser (Claude, ChatGPT) | **Not in a release yet.** Use hosted Niro | [connect-web-agents.md](connect-web-agents.md) |
+| CI (a build machine with no person at it) | **Partly** | [connect-ci.md](connect-ci.md) |
+| One shared server for a team | **Not in a release yet** | [connect-team-server.md](connect-team-server.md) |
+<!-- source: src/commands/engineRoutes.js:27-46 (terminal commands); src/mcp/setup.js:279-414 (CLIENTS, 14), :658-667, :3000 ("Other (print the config)"); niro-local src/niro_local/cli.py:2622-2694 (HTTP serving: licence and no authentication) -->
+
+**MCP** (the Model Context Protocol) is the standard way a coding agent uses an outside tool. Niro's MCP server runs on your computer, and your agent starts it when the agent starts. It talks to the agent through the agent's standard input and output, not over the network.
+<!-- source: src/mcp/setup.js:241-247 (every client runs `niro mcp serve` over stdio) -->
+
+**Computers:** Niro runs on macOS and Linux, on Intel and ARM. Windows is supported, and the details are coming.
+<!-- source: src/lib/engine.js:79-90 (macOS, Linux; x64, arm64); Windows: Niraj, 2026-11-10 -->

package/docs/connect-review-bots.md

@@ -0,0 +1,17 @@
+# Review bots and Niro
+
+**Review bots cannot use the local graph in this version.** Review bots are tools such as Cursor Bugbot, CodeRabbit or GitHub Copilot's pull request review, which comment on pull requests by themselves. niro-cli has no setup for them.
+<!-- source: no review-bot code in src/ (searched for Bugbot, CodeRabbit and Copilot review; the only Copilot entries are the VS Code and Copilot CLI agents, src/mcp/setup.js:314-338) -->
+
+**Why:**
+
+- These bots run on their makers' servers.
+- The local engine runs on your computer, and talks only to an agent your computer starts.
+- So a bot on someone else's server has no way to reach it.
+<!-- source: src/mcp/setup.js:241-247 (stdio only) -->
+
+**What you can do instead:**
+
+1. **Review with your own agent.** Check out the branch, and let your coding agent ask Niro what the change reaches. See [lifecycle-review.md](lifecycle-review.md).
+2. **Use hosted Niro for pull request review.** It reviews pull requests on Niro's servers. See [hosted-only.md](hosted-only.md).
+<!-- source: src/lib/cloudGuard.js:66-69 -->

package/docs/connect-team-server.md

@@ -0,0 +1,12 @@
+# One shared server for a team
+
+**A shared Niro server for a team is not supported in a release yet.** A shared server would be one computer that builds the graph and answers everyone's agents.
+
+**Why:**
+
+- **No licence.** A released engine gets its licence only from niro-cli, through a channel that exists only when niro-cli starts it, so an engine serving over the network refuses.
+- **No password or key.** The network mode has no authentication, so anyone who can reach it could read the structure of the code.
+- **One folder per process.** One running engine answers for one folder only.
+<!-- source: niro-local src/niro_local/cli.py:2622-2637 (docstring: points 1 to 3), :2687-2693 -->
+
+For now, each developer runs Niro on their own computer. For a shared view of a team's code, use hosted Niro (see [hosted-only.md](hosted-only.md)).