@niroai/niro 0.17.0 → 1.0.0

package/CHANGELOG.md

@@ -4,6 +4,142 @@ Notable changes to `@niroai/niro`. Dates are release dates.
 
 ## Unreleased
 
+### Every coding agent learns how to use Niro beyond code questions
+
+The instruction text Niro installs for each agent now has a short "Using Niro" part: for a how-to question
+about Niro, the agent lists the pages with `niro guide`, picks the one whose description fits, and answers
+from it; for a Niro error message it runs `niro guide --search` with the message; and it knows the commands
+that manage Niro (`niro init` for another folder, `niro build`, `niro status`, `niro plan`, `niro impact`,
+`niro route-rule`). It reaches every agent: the engine says it when an agent connects, and it is in the
+Claude Code skill and CLAUDE.md section, the files for Codex, Gemini CLI, Copilot CLI, Factory, OpenCode
+and Windsurf, and the Cursor, Cline and Kiro rules. `niro upgrade` puts it in place and keeps your own lines.
+
+### `niro guide --search` understands a question in plain words
+
+"how do I uninstall" used to find nothing, because every word had to be on one line. Words such as how,
+do, I, what and the are now left out, and the heading says which words were searched for. When no line
+holds the words but a page does, that page is shown; when no page holds them all, the closest pages come
+first, and the heading says so. Some page descriptions in the `niro guide` list are clearer too.
+
+### `niro guide` reads the documentation in the terminal, offline
+
+The documentation pages ship inside the package. `niro guide` lists them, grouped as the start page
+groups them. `niro guide <topic>` shows one page, found by its name, its title or a few words.
+`niro guide --search <words>` searches every page and shows the lines that matched. A pasted error
+message finds the page that explains it, even with your own folder names and numbers in it. Source
+notes are left out, and links show the `niro guide` command to run next. `--json` gives a coding agent
+the same answers, and the skills and rule files Niro installs for agents with a terminal now mention it.
+
+### Refreshing Niro's part of an agent's instruction file no longer deletes your notes below it
+
+For Gemini CLI, Copilot CLI, Factory and OpenCode (and the CLAUDE.md, Codex and Windsurf files the same
+way), Niro adds a section to the agent's own instruction file and refreshes it when its text changes, on
+`niro upgrade` and `niro mcp install`. The refresh used to remove everything from Niro's section to the
+next `## ` heading, so anything you had written straight below it, with no heading or under a `#` or `###`
+heading, was deleted. It now removes only Niro's own text, the way uninstalling does, and every line you
+wrote stays as it was.
+
+### Upgrading and uninstalling keep each of your lines on its own line
+
+When your own line sat right against Niro's section, with no blank line above and none below, upgrading
+or uninstalling joined it to the next line. When Niro's section was worded by an older release or edited
+by you, your line directly below it was deleted. Now one line break is put back between the two lines,
+and under a section Niro does not know word for word, only lines Niro wrote go. A line Niro cannot tell
+from yours, such as a Niro sentence you edited, is kept, so a little of Niro's old text may stay behind.
+
+### Claude Code gets the "ask Niro first" note on shell searches too
+
+The note Claude Code already got before its own Grep, Glob and Read tools now also comes before a
+shell command that searches or reads source code in a folder Niro indexes: `grep`, `rg`, `ag`, `ack`,
+`git grep`, `cat`, `head`, `tail`, `sed -n`, `awk`, `less`, `nl`, `bat`, `find -name '*.py'`, and
+`xargs grep`. Agents mostly search through the shell, so the old note rarely fired. It never blocks a
+command, and it stays quiet for config, docs, logs and build output, for a file changed in the last
+10 minutes, for a command that reads a pipe (`ps aux | grep node`, `npm test | tail`), and for
+`git grep` over another commit. `niro mcp install` (or `niro upgrade`) adds it; `niro mcp uninstall`
+removes it. It runs no network call and no Niro command: one `awk` and a walk up the folders.
+
+### The coverage audit sends a few lines, not the whole flagged file
+
+When a build flags a line it thinks the parser missed, only the method that holds that line (or, when
+no method holds it, at most 10 lines before to 40 after) and one line for each name those lines use
+from the same file are sent, with secrets masked. Every other line of the file goes as an empty line,
+so line numbers stay where they were. `niro status` and `niro plan` say so. niro-cli refuses to post
+a snippet that holds any other line. Removing a copyright holder's name no longer drops a line after a
+`*/` header, which used to move every flag below it one line up on the server.
+
+### The background watcher no longer saves your whole shell environment
+
+`niro-watch` runs under PM2, and PM2 saves the environment it was started with in
+`~/.pm2/dump.pm2`. That used to be the whole shell, cloud keys and tokens included, in a file other
+users on the machine could read. The watcher is now started with only what it reads (HOME, PATH,
+locale, temp folders, proxy and certificate settings, and the Niro settings), and `dump.pm2` and its
+backup are made readable by you only. An install made by an earlier version is started again with
+the smaller environment the next time you run `niro start` or `niro service install`, which also
+rewrites the saved files.
+
+`niro status` and `niro plan` now say what leaves the machine: your code stays on it, and the files
+the coverage audit flags are sent with secrets masked, on every plan.
+
+### `niro watch` re-checks a locally indexed folder every few minutes
+
+A file event that fs.watch dropped, or a file added while one was lost, was not built into the local
+graph until some later edit arrived. The watcher now lists a locally indexed folder every five minutes
+(file names, sizes and modification times; no file is read) and builds it when the listing changed
+since the last build started. A folder with a build running or due is left to that build, so two
+builds never run at once. Set `NIRO_LOCAL_RECHECK_MS` to change the interval.
+
+### The MCP bridge speaks Streamable HTTP
+
+`niro mcp serve` now talks to the Niro server over MCP Streamable HTTP (`POST /mcp`) when the server
+offers it: each call is answered in its own HTTP response, so there is no long-lived stream to drop.
+An expired session is renewed and the call resent once; a failed call returns an error instead of
+hanging. A dropped connection is retried only when the call cannot run twice (it never left, or it
+is a read like `tools/list`); a `tools/call` that may have run returns an error instead. Servers without it (404/405 on `/mcp`) get the old SSE transport, unchanged. Force one with
+`NIRO_MCP_TRANSPORT=http` or `sse`. Editor configs do not change.
+
+### `niro audit-push-repo`, for the plans that include it
+
+Sends this folder's whole source to Niro, so we can measure what the local engine's parser
+misses on code we never see rather than only on the files it already failed to parse. It lands
+in the account-scoped object store, the same place a repository uploaded through `niro add repo`
+goes, and nothing in that chain creates a project.
+
+It is explicit: no watcher runs it and no other command triggers it, and it prints the folder,
+the file count and the size, then asks. With no terminal it refuses unless you pass `--yes`.
+
+Permission is a claim in the licence lease, and anything that is not a clear yes is a refusal,
+including a licence service that cannot be reached. The folder goes through the same gate as
+`niro init`, which refuses your home directory, the filesystem root and a folder that holds no
+project of its own. The file set is the manifest the CLI already uses, so `.gitignore` is
+honoured and, when git cannot answer on a work tree, every file whose name could carry a secret
+is dropped rather than uploaded unverified; the service then decides what it will take, as it
+does for every other upload. A folder that has been sent is remembered in
+`~/.niro/audit-repos.json`; a second run says when the first one was, and `--force` sends it
+again into the same workspace.
+
+### The local graph needs no container, and nothing is offered to the cloud
+
+The local engine keeps its graph in a single file on your machine (`~/.niro-local/graph.db`), so it
+needs no container runtime and no database server. An earlier draft of this release kept the graph
+in Memgraph, offered Niro's cloud on a machine that could not run it, and read
+`NIRO_APPROVE_CLOUD_INDEXING`; all of that was removed before release, and that variable is not
+read. `niro engine status` shows a `database` line (whether the graph file opens), printed whichever
+way the engine was found, including from `NIRO_LOCAL_BIN`.
+
+### A folder indexed on your own machine is no longer indexed in the cloud as well
+
+`niro build`, `niro init` and `niro add repo` now refuse a folder that the local engine
+(`niro-local`) already indexes, and name the two ways out: `niro-local build --path <folder>` to
+update the local index, or `niro-local remove --path <folder>` first if you do want it in the
+cloud. Before this, either command uploaded the folder's source and indexed it a second time,
+which is the one thing the local engine exists to avoid, and the second index was charged for and
+then went stale, because questions in that folder are answered from the local graph.
+
+A machine without the engine is unaffected, and so is any folder the engine does not index.
+`niro new-temp-project` is deliberately **not** refused: a temporary project is a cloud project on
+purpose, because it serves pull request review and root cause analysis, which the local graph does
+not answer. It now says so in one line before it uploads.
+
 ## 0.17.0 — 2026-09-23
 
 ### `niro init --defaults` still asks which project

package/README.md

@@ -1,190 +1,101 @@
-# niro: CLI + MCP server (`@niroai/niro`)
+# niro: Niro Local 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.
+Niro reads your code and builds a map of how it fits together: classes and methods, who calls
+what, HTTP endpoints and calls between services, events, and data access. 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.
+**Niro Local builds and keeps the map on your machine.** Your code is read here and the graph is
+stored here (`~/.niro-local/graph.db`). What is sent, and when, is listed under
+[What leaves your machine](#what-leaves-your-machine).
 
-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).
+One package installs 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: request access at
+[www.niro.ai](https://www.niro.ai).
 
 ---
 
 ## Get started
 
+Once per machine, in your first repo:
+
 ```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?"
-```
-
----
+`niro start` checks the machine, signs you in (one browser screen: choose a plan and approve
+this terminal), installs the local engine, builds this folder's graph, connects your AI
+assistant, and starts a background watcher that keeps the graph current as files change.
 
-## 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
+Then add every other repo with one command. It adds the folder and builds its graph:
 
 ```bash
-niro status
+cd ~/code/another-service
+niro init
 ```
-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.
+Each folder goes into a project named after it. To put a second service into the same project, so
+the calls between them are linked, name the project:
 
 ```bash
-niro info
+cd ~/code/llm-gateway
+niro init --project niro
 ```
-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).
+Restart your assistant and ask it something:
 
-```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
+"What breaks if I change PaymentService.refund?"
+"Which services call the /orders endpoint?"
 ```
-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).
-
-Full guide: [docs/working-on-branches.md](https://unpkg.com/@niroai/niro/docs/working-on-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:
+## Everyday commands
 
-| What is gone | What happens to your folder |
+| Command | What it does |
 |---|---|
-| 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.
+| `niro init [path]` | Add a folder and build its graph, in one step (an indexed folder is rebuilt). Needs `niro start` once first. Options: `--project <name>` joins or starts that project, `--force` adds a folder with no build file, `--path <folder>`, `--branch <name>` (a folder outside git), `--base-url <url>`. At or over the line limit a new folder is refused before it is added; a folder already indexed is still rebuilt. |
+| `niro build [path]` | Rebuild the graph of a folder already added. A folder not added yet is refused with a pointer to `niro init`. |
+| `niro status` | This folder: indexed or not, last build, plan, connected assistants, auto-sync. |
+| `niro plan` | Your plan, lines used against its limit, every indexed folder (largest first), and your options. |
+| `niro plan remove <folder>` | Stop indexing a folder and free its lines. Your code is not touched. |
+| `niro request-integration <name>` | Ask Niro's team to support a language, framework or tool Niro does not read yet (`--kind framework` or `--kind tool`, `--reason "<why>"`). Asks before sending; the request is kept with your account. Your assistant can do the same with the `request_integration` tool, which also asks you first. `niro start` names languages in a folder that Niro does not read yet. |
+| `niro mcp install` | Connect another AI assistant (Claude Code, Cursor, Codex, Windsurf and others). |
+| `niro service install` | Restart the background watcher if it stopped. |
+| `niro upgrade` | Update to the latest version. |
+| `niro uninstall` | Remove Niro from this machine. See [docs/uninstall.md](docs/uninstall.md). |
+
+Most commands take `--json` for scripts and agents (`niro plan --json`, `niro status --json`,
+`niro whoami --json`).
 
 ---
 
-## 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.
+## Plans and the line limit
+
+**Free** indexes up to 500,000 lines of code in total on your machine. Every line of every indexed
+file counts, blank lines and comments included (the same number `wc -l` gives). Each repository
+counts once, by its largest checkout: two checkouts of one repo are not counted twice.
+
+- A build starts while you are under the limit, and the build that takes you over is allowed to
+  finish. After that, adding a new repository or project stops until you choose how to continue.
+  Folders already indexed keep rebuilding, and so do new branches or worktrees of a repository
+  already indexed, and a service folder inside an indexed monorepo.
+- The graph you already have keeps answering your assistant in the meantime.
+- `niro start`, `niro init` and `niro plan` tell you when you are over, and open the console's
+  **/limit** page with three ways on:
+  1. **Unlock unlimited lines on Free** by turning on sharing of redacted code.
+  2. **Request a Pro free trial** (30 days, no line limit, no sharing needed). Your code stays on
+     this machine, except, for each line the audit flags, the whole method that holds it and one line
+     for each name it uses, sent with secrets masked and author and company names removed. A record of which Niro tools your
+     assistant used is also sent, to improve Niro and to show you its value. Niro's tools answer
+     your assistant from the graph on this machine and never send the contents of your files.
+  3. **Stay under the limit** with `niro plan remove <folder>`.
+
+You can turn sharing on or off at any time under Settings, Privacy in the console. Turned off on
+Free, the line limit applies again.
 
 ---
 
@@ -193,179 +104,89 @@ Stop early. Every session uses Niro again.
 ```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.
+Asks which assistant, writes Niro into its settings, and installs the skills. Restart the
+assistant afterwards; skills load at startup. "Other" prints a config block to paste into any
+assistant that is not listed.
 
 ---
 
-## 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`).
+## What leaves your machine
 
-```bash
-niro watch
-```
-Watch this folder in the foreground instead, for one session.
+- **Your account.** Sign-in, and your plan's licence (which plan, its line limit, whether sharing
+  is on), renewed while Niro runs.
+- **Which tools were used**, on every plan, to improve Niro and to show you its value. A record of
+  the Niro tools your assistant called: the tool names, how long each took, whether it failed,
+  whether Niro helped and how many native calls it saved, a short summary of the task written by
+  the assistant, and the names, paths and search text it asked about (each cut to 200 characters).
+  No source files.
+- **Coverage findings**, on every plan. For each line the graph missed (a class or a route with
+  nothing in the graph for it), the method that holds it (or the 10 lines before and 40 after it)
+  and one line for each name it uses are sent, with that file's path inside the repo, so the parser can be fixed. Every other line of the
+  file is sent blank; a whole file is never sent. Before sending, Niro removes secrets, author names
+  and company names it can recognise (your email domain, the git remote's owner, copyright holders).
+- **Catalogue signals**, on every plan, with the coverage findings and under the same rule (a signed-in
+  machine with a readable plan). After a build, for each indexed folder: the file extensions Niro read
+  no language in, with a count each (for example `.fs: 12`), and the names of outside libraries your
+  code imports, each with its ecosystem, whether Niro already has rules for it, and how many files
+  import it. This tells us which languages and libraries to support next. No file names, paths, import
+  lines or source are sent, and no name of your own code: a package whose source is in your project or
+  its other folders, or that shares your packages' own prefix (your npm scope, your Go organisation, your
+  Java packages), is never sent. A library whose source is in none of your project's folders is sent by
+  its name, even when that name is your company's (a private package or git host), because the catalogue
+  needs every outside library. Sent again only when the list changes.
+- **A request for a language, framework or tool, only when you send one** (`niro request-integration`, or
+  your assistant's `request_integration` tool after you say yes): its name and kind, your reason if you
+  give one, and your account's email.
+- **The code Niro indexes, only while sharing is on.** With "Share redacted code" on in the console,
+  the background watcher sends the files Niro indexes in each folder (source, config and build files;
+  never a gitignored file, a real `.env`, a key or `node_modules`), with secrets masked and author and
+  company names removed on this machine: the whole set the first time, then only changed files. Keep a
+  folder out with `niro share exclude <folder>`. Turning sharing off stops it.
+- **One folder at once, when you choose to.** `niro audit-push-repo` sends one folder's indexed files the
+  same way, only when sharing is on and your plan includes it. It asks first.
+
+Your graph stays on your machine, and your assistant's questions are answered from it there. A
+record of those tool calls is sent, as described above.
+
+Your AI assistant (for example Claude Code, Codex or Cursor) may send what Niro shows it to its own
+model provider, under that assistant's terms. That is the assistant's doing, not Niro's.
 
 ---
 
 ## 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.
+`niro upgrade` replaces the package with the latest version, re-installs Niro into every assistant
+you have configured, and restarts the background watcher. Restart your assistant afterwards.
 
 ---
 
 ## 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.
+**The assistant ignores Niro.** Restart it. Skills load at startup.
+
+**"This folder is not indexed on this machine".** Run `niro init` in that folder (or `niro start`
+there, on a machine that is not set up yet).
 
-**`niro: command not found`.** Your global npm bin is not on `PATH`. Check with `npm bin -g`.
+**`niro init` says you are not signed in, or the engine is missing.** Run `niro start` once on this
+machine.
 
-**This folder maps to several projects.** Pass `--project <alias|id>`, or pick one when asked.
+**"No room left under the limit".** See [Plans and the line limit](#plans-and-the-line-limit), or
+run `niro plan` for your options.
 
-**Auto-sync is not running.** `npm install -g pm2`, then `niro service install`.
+**`niro: command not found`.** Your global npm bin is not on `PATH`. Find npm's global folder with `npm prefix -g`; its `bin` folder must be on `PATH`.
 
-**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.
+**The graph does not update as you edit.** The watcher is not running: `niro service install`
+(it needs PM2: `npm install -g pm2`).
 
-**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.
+**A folder was refused.** Niro will not index your home folder or the root of the disk. Run it in
+the repo you meant. A git repository inside the folder you index is its own project: run
+`niro init` inside it.
 
 ---