@niroai/niro 0.17.0 → 0.18.0

package/docs/connect-terminal.md

@@ -0,0 +1,49 @@
+# Use Niro from the terminal
+
+**You do not need a coding agent to use Niro.** Every question an agent can ask, you can ask from the shell.
+
+## Ask the graph a question
+
+```
+niro ask
+niro ask find_api_endpoints
+niro ask get_reverse_call_chain method_fqn=InvoiceService.send depth=2
+```
+
+- With no tool named, `niro ask` lists the tools.
+- With a tool, it takes inputs as `key=value` and prints the same answer an agent would get.
+- `niro ask --help` shows more.
+- The tools and their inputs are in [reference-mcp-tools.md](reference-mcp-tools.md).
+<!-- source: src/commands/engineRoutes.js:28 ("Ask one graph tool from the shell and print its answer (no tool: list them)") -->
+
+`niro ask` answers for the folder you run it in. To ask about another folder, `cd` there first.
+<!-- source: niro-local src/niro_local/cli.py:2706-2707 (_cmd_ask: "One MCP tool's answer, printed, for this folder") -->
+
+`niro ask` needs your sign-in, because it uses the licence. See [licence-and-plans.md](licence-and-plans.md).
+<!-- source: src/commands/engineRoutes.js:28 (third field true: needs the licence) -->
+
+## See the graph in a browser
+
+```
+niro ui
+```
+
+- **What it shows:** a page that draws the folder's graph. You can switch kinds of nodes and links on and off.
+- **Where it runs:** at 127.0.0.1, on port 8601 by default. 127.0.0.1 means this computer only, so nothing else on your network can reach it.
+- **What it can do:** only read. It changes nothing.
+- **How to stop it:** it runs until you press Ctrl-C.
+<!-- source: src/commands/engineRoutes.js:29; niro-local src/niro_local/ui/server.py:35-36; niro-local CLAUDE.md (2026-10-08 amendment: read-only, 127.0.0.1 only) -->
+
+## Other everyday commands
+
+| Command | What it does |
+|---|---|
+| `niro status` | Shows this folder's project, when the graph was last built, your plan, sharing, your agent and the background updates |
+| `niro plan` | Shows your plan and how many lines are indexed |
+| `niro build` | Rebuilds this folder's graph now |
+| `niro modules` | Lists the folders inside this one that are separate services |
+| `niro projects` | Lists every project on this computer and its folders |
+
+<!-- source: src/index.js:77-86 (plan), :503-516 (status), :517-527 (build); src/commands/status.js:76-88 (status fields); src/commands/engineRoutes.js:34, :45 -->
+
+Every command is listed in [reference-cli.md](reference-cli.md) and [reference-engine-commands.md](reference-engine-commands.md).

package/docs/connect-web-agents.md

@@ -0,0 +1,9 @@
+# Agents in a web browser
+
+**Agents in a web browser, such as Claude or ChatGPT on their websites, cannot use the local graph in a release yet. For web agents, use hosted Niro** (see [hosted-only.md](hosted-only.md)).
+
+**Why:**
+
+- **No licence.** A web agent would need the engine to answer over the network. The engine can do that, but a released engine gets its licence only from niro-cli, through a channel that exists only when niro-cli starts the engine itself. Served over the network, every tool answers "The Niro CLI has not handed this engine its licence yet." and then refuses.
+- **No password or key.** The engine's network mode has no authentication: anyone who can reach the port could read the structure of your code. If it is started on an address other than this computer, it warns: "anything that can reach this port can read this graph."
+<!-- source: niro-local src/niro_local/cli.py:2622-2637 (docstring: no authentication; a released engine still needs a licence, which arrives on pipes a spawned child gets), :1368 (LEASE_PENDING), :2653-2679, :2687-2693 (warning) -->

package/docs/connect-your-ai-assistant.md

@@ -1,206 +1,90 @@
-# Connect your AI assistant to Niro
+# Connect your coding agent to Niro
 
-`niro mcp install` configures one AI client at a time to use Niro's MCP server. This page
-lists every supported client, the exact command for each, and what it does. If you'd rather
-drive setup from chat instead of a terminal, see [Scenario 2](../README.md#scenario-2--onboard-a-folder-youre-working-in)
-in the main README — the `niro-cli` skill can run these commands for you.
+**`niro mcp install` connects your coding agents to Niro.** `niro start` runs it for you at the end of setup. Run it yourself to connect another agent later.
+<!-- source: src/commands/start.js:61 (the "assistant" step); src/index.js:432-438 -->
 
 ## Before you start
 
-```bash
-npm install -g @niroai/niro
-niro login              # browser device flow — no API key to copy
-```
-
-After `niro login`, none of the commands below need an API key — the MCP server authenticates
-with your device token. If you'd rather use an API key instead (e.g. a headless CI box), get
-one from **console.niroai.dev > Settings > Account**; the wizard will ask for it when no
-`niro login` session is found.
-
-**Pointing at a different backend?** Every command below defaults to Niro's cloud
-(`https://aiassistant.niroai.dev`). Add `--url <your-backend-url>` to any `niro mcp install`
-command to use a self-hosted or dedicated instance instead (or set `NIRO_MCP_SERVER_URL`).
-
-## All Niro tools are read-only
-
-Every tool Niro exposes over MCP only *reads* your code graph — none can modify your code,
-your projects, or anything else. That's why several of the installers below turn on
-auto-approve for Niro's tools: there's nothing for a read-only tool call to break.
-
----
-
-## Claude Code
-
-```bash
-niro mcp install --client claude-code
-```
-
-Registers the server (`claude mcp add --scope user`), adds a `PostCompact` + `UserPromptSubmit`
-hook so Claude stays aware of Niro after context compaction, appends a short reminder to
-`~/.claude/CLAUDE.md`, and installs the **`niro-skill`** (routes code questions through the
-graph) and **`niro-cli`** skill (drives the CLI from chat) to `~/.claude/skills/`.
-
-Verify: type `/mcp` inside Claude Code — `niro` should be listed as connected.
-
-## Codex
-
-```bash
-niro mcp install --client codex
-```
-
-Registers the server in `~/.codex/config.toml`, sets `default_tools_approval_mode = "auto"`
-(safe — every niro tool is read-only), appends a reminder to `~/.codex/AGENTS.md`, and installs
-the shared `niro-skill` + `niro-cli` skill to `~/.agents/skills/` (also read by Windsurf).
-
-Verify: `/mcp` inside the Codex TUI.
-
-Note that `AGENTS.md` is read once at the start of a session, so on a long task the reminder to
-prefer niro's tools carries less weight than it does in Claude Code, where a per-tool-call hook
-reinforces it. A per-prompt hook for Codex is in progress.
-
-## Cursor
-
-```bash
-niro mcp install --client cursor
-```
-
-Writes `~/.cursor/mcp.json`, adds `"niro:*"` to `~/.cursor/permissions.json`'s `mcpAllowlist`
-(so Agent doesn't ask before every tool call), and writes a project rule to
-`.cursor/rules/niro.mdc` in the current repo.
-
-Requires Cursor's Agent **Auto-run** mode enabled (Settings) for the allowlist to take effect —
-"Ask every time" ignores it.
-
-## VS Code (GitHub Copilot)
-
-```bash
-niro mcp install --client vscode
-```
-
-Writes the user-profile `mcp.json` (`servers.niro`) — the same file VS Code's
-**MCP: Open User Configuration** command opens.
-
-Verify: run **MCP: List Servers** from the Command Palette, or check the Chat view's tools icon.
-First use of a new server needs a one-time trust confirmation.
-
-## Windsurf
-
-```bash
-niro mcp install --client windsurf
 ```
-
-Writes `~/.codeium/windsurf/mcp_config.json`, appends a reminder to
-`~/.codeium/windsurf/memories/global_rules.md`, and installs the shared `niro-skill` +
-`niro-cli` skill to `~/.agents/skills/` (also read by Codex).
-
-## Claude Desktop
-
-```bash
-niro mcp install --client claude-desktop
+npm install -g @niroai/niro
+niro start
 ```
 
-Writes `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows:
-`%APPDATA%\Claude\`, Linux: `~/.config/claude/`). Restart Claude Desktop after.
+`niro start` signs you in through your browser. **`niro mcp install` needs that sign-in.** If you signed in another way (`niro login --api-key` or `--password`), it refuses with "Not signed in. Run niro login".
+<!-- source: src/mcp/setup.js:574-583 (hasCliToken), :2950-2955 -->
 
-## Gemini CLI
+## Install
 
-```bash
-niro mcp install --client gemini-cli
 ```
-
-Runs `gemini mcp add -s user` to register the server (`~/.gemini/settings.json`) and appends a
-reminder to `~/.gemini/GEMINI.md`.
-
-Verify / reload: run `/mcp reload` inside Gemini CLI.
-
-## GitHub Copilot CLI
-
-```bash
-niro mcp install --client copilot-cli
+niro mcp install                          # pick from a list
+niro mcp install --client cursor          # one agent
+niro mcp install --client codex,cursor    # several
+niro mcp install --list                   # see the agents it knows
 ```
+<!-- source: src/index.js:432-438; src/mcp/setup.js:683 (--list), :3000 (the picker) -->
 
-Runs `copilot mcp add` (writes `~/.copilot/mcp-config.json`) and appends a reminder to
-`~/.copilot/copilot-instructions.md`.
+When it finishes, it prints one line per agent and then "Restart your AI assistant to start using Niro." **Restart the agent: it reads its settings only when it starts.**
+<!-- source: src/mcp/setup.js:3071-3085 -->
 
-Verify: run `/mcp` inside the Copilot CLI — servers are available immediately, no restart needed.
+## The 14 agents
 
-## Factory (droid)
+| Agent | `--client` | Page |
+|---|---|---|
+| Claude Code | `claude-code` | [agent-claude-code.md](agent-claude-code.md) |
+| Codex | `codex` | [agent-codex.md](agent-codex.md) |
+| Claude Desktop | `claude-desktop` | [agent-claude-desktop.md](agent-claude-desktop.md) |
+| Cursor | `cursor` | [agent-cursor.md](agent-cursor.md) |
+| Windsurf | `windsurf` | [agent-windsurf.md](agent-windsurf.md) |
+| VS Code (GitHub Copilot) | `vscode` | [agent-vscode.md](agent-vscode.md) |
+| Gemini CLI | `gemini-cli` | [agent-gemini-cli.md](agent-gemini-cli.md) |
+| GitHub Copilot CLI | `copilot-cli` | [agent-copilot-cli.md](agent-copilot-cli.md) |
+| Factory (droid) | `factory` | [agent-factory.md](agent-factory.md) |
+| Goose | `goose` | [agent-goose.md](agent-goose.md) |
+| OpenCode | `opencode` | [agent-opencode.md](agent-opencode.md) |
+| Cline | `cline` | [agent-cline.md](agent-cline.md) |
+| Kiro | `kiro` | [agent-kiro.md](agent-kiro.md) |
+| Antigravity | `antigravity` | [agent-antigravity.md](agent-antigravity.md) |
+<!-- source: src/mcp/setup.js:279-414 (CLIENTS) -->
 
-```bash
-niro mcp install --client factory
-```
+## How each agent learns to use Niro
 
-Runs `droid mcp add` (writes `~/.factory/mcp.json`) and appends a reminder to
-`~/.factory/AGENTS.md`. droid reloads automatically when the config file changes.
+Connecting an agent gives it the tools. Whether it reaches for them first depends on what else the agent is told:
 
-## Goose
+- **Claude Code** gets hooks: small commands Claude Code runs at fixed moments. They remind it to use Niro and show an impact check before an edit. It also gets two skills and a section in `~/.claude/CLAUDE.md`.
+- **Codex and Windsurf** get the same two skills, in `~/.agents/skills`, plus instruction text.
+- **Cursor, Cline, Kiro, Gemini CLI, Copilot CLI, Factory and OpenCode** get instruction text (a rule file) only.
+- **Claude Desktop, VS Code, Goose and Antigravity** get the connection only.
+<!-- source: src/mcp/setup.js:782-800 (Claude Code), :2393-2427 (skills in ~/.agents/skills), :2079-2100, :2436-2592 (rule and instruction files); docs/usecases/impact-gate.md:155 ("Only Claude Code has the hook") -->
 
-```bash
-niro mcp install --client goose
-```
+## All Niro tools only read
 
-Writes an `extensions.niro` entry into `~/.config/goose/config.yaml` (Windows:
-`%APPDATA%\Block\goose\config\config.yaml`). Restart Goose (or start a new session) after.
+Every Niro tool reads the graph or your files, and none changes your code. One tool, `mark_task_complete`, records the summary your agent writes at the end of a task. That summary is sent to Niro with the tool-usage record (see [what-leaves-your-machine.md](what-leaves-your-machine.md)).
+<!-- source: niro-local src/niro_local/journal/store.py:86-90, :121, :235, :270 (the report is stored in the journal); src/lib/journalUpload.js:9-37 (the journal is uploaded) -->
 
-If your `config.yaml` already has an unusual `extensions:` layout, the installer prints the
-YAML block to paste in by hand instead of guessing at a risky merge.
+Because the tools only read, some installers let them run without asking you each time:
 
-## OpenCode
+- **Cursor:** `niro:*` is added to Cursor's allowlist.
+- **Kiro:** `autoApprove: ["*"]` is set.
+- **Codex:** `default_tools_approval_mode = "writes"` is set, so Codex asks only for tools that write.
+<!-- source: src/mcp/setup.js:445-503 (Cursor allowlist), :382-395 (Kiro autoApprove), :2138, :2305-2318 (Codex) -->
 
-```bash
-niro mcp install --client opencode
-```
+## Other MCP clients
 
-Writes `~/.config/opencode/opencode.json` (`mcp.niro`) and appends a reminder to
-`~/.config/opencode/AGENTS.md`. Restart OpenCode after.
+If your agent is not in the list, choose "Other (print the config)" in the picker. It prints a block like this to paste into your agent's MCP settings:
 
-## Cline
-
-```bash
-niro mcp install --client cline
+```json
+{ "mcpServers": { "niro": { "command": "niro", "args": ["mcp", "serve"] } } }
 ```
 
-Writes Cline's `cline_mcp_settings.json` (under VS Code's `globalStorage` for Cline's
-publisher id) and adds a global rule file to Cline's Rules directory.
+The printed block also carries the settings your setup needs. Use the printed block, not this example.
+<!-- source: src/mcp/setup.js:658-667, :241-247 -->
 
-## Kiro
+## Remove Niro from an agent
 
-```bash
-niro mcp install --client kiro
 ```
-
-Writes `~/.kiro/settings/mcp.json` with `autoApprove: ["*"]` (safe — niro's tools are
-read-only) and adds a global steering file at `~/.kiro/steering/niro.md`. Kiro reconnects MCP
-servers automatically when you save the config.
-
-## Antigravity
-
-```bash
-niro mcp install --client antigravity
-```
-
-Writes `~/.gemini/config/mcp_config.json`. Reload via **Agent Settings → Customizations →
-Installed MCP Servers → Refresh** (or `/mcp` in the Antigravity CLI).
-
----
-
-## Test it
-
-After connecting any client, restart it (where noted above) and ask:
-
-> "What calls `chargeCard()`? Use Niro tools."
-> "What breaks if I change the `Invoice` schema?"
-> "Is there existing code that parses webhooks, before I write a new one?"
-
-If the assistant answers from the graph instead of grepping files, you're connected.
-
-## Disconnect
-
-```bash
-niro mcp uninstall --client <id>     # one client
-niro mcp uninstall --all -y          # every client, no confirm
+niro mcp uninstall --client cursor
+niro mcp uninstall --all
 ```
 
-`mcp uninstall` is the exact inverse of `mcp install` for each client — it only removes what
-install added, leaving your own config, rules, and other MCP servers untouched. See the main
-[README](../README.md#scenario-11--disconnect-an-ai-assistant-uninstall-the-mcp) for details.
+This removes everything the install added: the connection, the hooks, the instruction text, the skills, and the Cursor allowlist entry. It removes the Cursor rule only in the current folder. Your sign-in stays.
+<!-- source: src/mcp/teardown.js:1-27, :431-438, :645-653 -->

package/docs/coverage-audit-and-consent.md

@@ -0,0 +1,51 @@
+# The coverage audit
+
+**The coverage audit is how Niro learns what it fails to read in real code.** While building, the engine notes the lines it could not make sense of. For example, a call it could not link, or a framework it does not know. A small, masked piece of the code around each such line is sent to Niro, so support for that kind of code can be added.
+<!-- source: src/commands/engineRoutes.js:37 ("What the last builds found wrong with their own graph"); src/lib/auditUpload.js -->
+
+## What exactly is sent
+
+For each flagged line:
+
+- **the method that holds it**, or, outside a method, the 10 lines before and the 40 lines after;
+- **one line for each name that piece uses** that is defined in the same file;
+- **every other line of the file is sent blank**, so line numbers still match. A whole file is never sent;
+- **the file's path inside the repository**, so the gap can be found.
+<!-- source: niro-local src/niro_local/cli.py:2413-2415; src/niro_local/audit/queue.py:838-846; src/niro_local/audit/collect.py:208-216 -->
+<!-- source: src/lib/redact.js:89-121; CHANGELOG.md (Unreleased: the audit sends only a snippet) -->
+
+Before it leaves your computer:
+
+- **secrets are masked** by the engine, in the code and in the path;
+- the names of **authors and companies** become `<author>` and `<company>`.
+<!-- source: src/lib/auditUpload.js:216-220; src/lib/redact.js:1-18 -->
+
+Separately, the audit sends a list of the libraries and kinds of files the build saw. That list carries no file names or paths.
+<!-- source: src/lib/auditUpload.js:237-244 -->
+
+## When and on which plans
+
+**The audit is sent on every plan.** It does not depend on the code-sharing switch. The background watcher sends it every 5 minutes. You can also send it yourself with `niro audit-send`.
+<!-- source: src/lib/auditUpload.js:27-30 ("the coverage audit is sent on every plan"); src/commands/watch.js:423-426 -->
+
+There is no switch to turn it off in `niro`. For what Niro may keep and do with what it receives, read Niro's Data Processing Agreement, summarised in [what-leaves-your-machine.md](what-leaves-your-machine.md#niros-data-processing-agreement).
+
+## See it before it is sent
+
+```
+niro audit                  # what is waiting to be sent
+niro audit --export DIR     # write the waiting items to a folder, to read them
+```
+<!-- source: src/commands/engineRoutes.js:37 (audit, all arguments passed to the engine), :65-84; niro-local src/niro_local/cli.py:478 (--export DIR) -->
+
+## Code sharing is a separate choice
+
+**"Share redacted code" is a switch on your account, in the console under Settings, Privacy.** Switching it on is your consent; nothing more is asked on your computer. It does two things:
+
+- it removes the line limit on the Free plan;
+- the background watcher shares the files Niro indexes in each folder on your computer, by itself, with secrets masked and author and company names removed first: the whole indexed set the first time, then only changed files. A folder you keep out with `niro share exclude <folder>` is never sent.
+
+`niro audit-push-repo` is separate from the switch. It is how you send one folder's indexed files to Niro when something is wrong and you want us to look at it. It works with the switch on or off, on every plan: typing it and answering yes is the consent. The files are the same and are masked the same way. For a folder you excluded, it asks "Send it anyway?" first and sends only on yes.
+
+Turning the switch off stops the sharing: nothing more is sent after the next check. `niro uninstall` does not turn the switch off. Turn it off in the console.
+<!-- source: src/commands/plan.js:63-67; src/lib/shareCode.js; src/lib/shareExclusions.js; src/lib/repoPush.js; src/commands/uninstall.js:97-101 -->