@niroai/niro 0.17.0 → 0.18.0

package/docs/lifecycle-onboarding.md

@@ -0,0 +1,32 @@
+# Learn a codebase with Niro
+
+**When you are new to a codebase, Niro gives you its shape before you read any file.** It shows the services, how they call each other, the routes they serve, the data they keep and the events they send.
+
+## See it in a browser
+
+```
+niro ui
+```
+
+This opens a page that draws the graph. It runs on your computer only (at the address 127.0.0.1, on port 8601 by default), it is read-only, and it stops when you press Ctrl-C.
+<!-- source: src/commands/engineRoutes.js:29; niro-local src/niro_local/ui/server.py:35-36 -->
+
+## Ask in the terminal, or let your agent ask
+
+| Question | Tool, or command |
+|---|---|
+| Which service calls which? | `get_service_topology` |
+| Which routes does this code serve? | `find_api_endpoints` |
+| Which other services does it call? | `find_outbound_http_calls` |
+| Which tables and stores does it use? | `list_data_resources`, then `get_data_resource_usage` |
+| Which events does it send and handle? | `list_events`, `find_orphaned_events` |
+| Which classes exist? | `list_types` |
+| Which folders are separate services? | `niro modules` |
+<!-- source: niro-local src/niro_local/mcp/server.py:1860, :1731, :1837, :1920, :1932, :1790, :1825, :1719; src/commands/engineRoutes.js:34 (modules) -->
+
+If services are linked wrongly or not at all, you can tell Niro where they live. See [configuring-a-folder.md](configuring-a-folder.md).
+
+## Playbook
+
+[Learn a new codebase](playbook-onboard.md) walks the first six questions on Keycloak and on a synthetic monorepo of 68 services.
+<!-- source: docs/playbook-onboard.md -->

package/docs/lifecycle-overview.md

@@ -0,0 +1,77 @@
+# Where Niro fits in how you build software
+
+**Niro is a ground truth layer.** Ground truth means facts read from the code itself, not from memory or guesses. Before a person or an agent changes code, reviews it, tests it or debugs it, they can check it against a map built from the code as it is now. The map says who calls what, which routes exist, which services talk to each other, and which tables and events are touched.
+
+**An everyday comparison:** a builder checks the plans of the building before knocking down a wall, to see which pipes run through it. Niro is the plan of your code, and it is redrawn as the code changes.
+<!-- source: src/lib/localBuild.js:16-46 (the background watcher rebuilds a folder after it changes) -->
+
+**Why it matters for an agent:** an agent that builds a list of callers from a text search is usually close and sometimes wrong (measured: in one of our Keycloak A/B sets, every fact the shell-only agent missed was a class reached through an interface). That a wrong list then leads to a wrong edit and a second round of work is reasoning, not measured. Niro's lists say whether they are complete, and why not when they are not. How that pays off over a session is in [tokens-speed-and-accuracy.md](tokens-speed-and-accuracy.md).
+<!-- source: docs/how-the-graph-works.md ("How to read an answer": confidence, has_more); scratchpad niro-local-receipt-recheck/NATIVE-CHOICES.md (21 c4 misses, all implementations behind an interface) -->
+
+## What people actually ask
+
+These shares come from 794 recorded Niro calls in agent sessions over 14 days, each labelled by task. **Three limits:** the sessions are mostly Niro's own development (so debugging is under-represented), hosted and local Niro calls are counted together, and the labels were made by hand by one agent, so treat each share as about plus or minus 10%.
+
+| Task | Share of calls | Playbook |
+|---|---|---|
+| Understand how existing code works | 41% | [playbook-onboard.md](playbook-onboard.md) |
+| Change code safely: map callers before an edit | 18% | [playbook-change-safely.md](playbook-change-safely.md) |
+| Add a feature: find what exists, follow its shape | 9% | [playbook-add-a-feature.md](playbook-add-a-feature.md) |
+| Debug a wrong value, a slow path or an exception | 6% | the debugging playbooks below |
+| Find where something is | 4% | [playbook-onboard.md](playbook-onboard.md) |
+| Calls between services | 3% | [playbook-debug-failing-service-call.md](playbook-debug-failing-service-call.md) |
+| Data stores and events | 3% | [playbook-data-and-events.md](playbook-data-and-events.md) |
+| Config and environment | 3% | [playbook-debug-config.md](playbook-debug-config.md) |
+| Testing and review | 2% | [playbook-test-a-change.md](playbook-test-a-change.md), [playbook-review-a-change.md](playbook-review-a-change.md) |
+<!-- source: scratchpad niro-cli-task-playbooks/TASKS.md (calls.jsonl from niro-local-answer-shapes, customer calls removed; 794 code calls labelled by hand by one agent, about plus or minus 10%; the other 11% checked the index or the tools themselves). The recordings are mostly Niro's own development, so debugging is under-represented. -->
+
+## The playbooks
+
+Each playbook starts from a question in a user's own words and runs real tool calls on public code: Keycloak, and a synthetic multi-service corpus. It shows the real answers, says why each answer is complete or where it is not, and compares it with grep and file reads.
+<!-- source: the pages listed below, each with its runs cited (niro-local 43cce717, 2026-11-10) -->
+
+**Debugging:**
+- [An error message or a stack trace](playbook-debug-exception.md): the thrower, its callers, who catches it.
+- [A wrong value](playbook-debug-wrong-value.md): who writes the table or field, and which event delivered it.
+- [A failing call between services](playbook-debug-failing-service-call.md): the caller, the handler, the address, two services on one route.
+- ["It broke after my change"](playbook-debug-after-a-change.md): what the change reaches, tests first.
+- [Config and environment](playbook-debug-config.md): which settings the code reads, where they are set, calls with no address.
+- [A slow path](playbook-debug-slow-path.md): what a slow method calls, and where it goes to the database.
+
+**Building and checking:**
+- [Change code safely](playbook-change-safely.md)
+- [Add a feature](playbook-add-a-feature.md)
+- [Review a change](playbook-review-a-change.md)
+- [Test a change](playbook-test-a-change.md)
+- [Learn a new codebase](playbook-onboard.md)
+- [Data stores and events](playbook-data-and-events.md)
+
+## The stages
+
+| Stage | Who | How they reach Niro | What Niro gives them | Page |
+|---|---|---|---|---|
+| Plan and design | A developer, or a planning agent | A coding agent, or `niro ask` in the terminal | What a planned change reaches, in both directions | [lifecycle-plan-and-design.md](lifecycle-plan-and-design.md) |
+| Write code | The coding agent; the developer | 14 coding agents over MCP (the Model Context Protocol, the standard way coding agents call outside tools); `niro ask` | Call chains, callers before an edit, the source of one method | [lifecycle-write-code.md](lifecycle-write-code.md) |
+| Review | A reviewer; a review bot | The reviewer's own agent, or `niro ask`, on the branch | What the change reaches. **Pull request review as a product is hosted Niro only.** | [lifecycle-review.md](lifecycle-review.md) |
+| Test | A developer, QA, a test-writing agent | MCP or `niro ask` | Which callers a change reaches, and which of them are tests | [lifecycle-test.md](lifecycle-test.md) |
+| Debug | A developer, a debugging agent | MCP or `niro ask` | Exceptions, writers of a table, handlers of a route or event, what a method calls. **Root cause analysis from alerts is hosted Niro only.** | [lifecycle-debug.md](lifecycle-debug.md) |
+| Onboarding | A new team member; an agent in a new repository | `niro ui`, `niro ask`, MCP | Services and how they connect, endpoints, data stores, events | [lifecycle-onboarding.md](lifecycle-onboarding.md) |
+| Security and privacy | A security reviewer, an admin | Any of the above | What Niro reads, keeps and sends; every route and every outbound call, for an attack-surface list | [lifecycle-security-and-privacy.md](lifecycle-security-and-privacy.md) |
+<!-- source: src/mcp/setup.js:279-414 (14 agents); src/commands/engineRoutes.js:28-29 (ask, ui) -->
+
+## Four habits that make answers smaller and better
+
+1. **Ask for the shortest form that answers you.** `answer=count` for "how many", `answer=locations` for "where", `answer=names` for "which". See [answer-shapes.md](answer-shapes.md).
+2. **Use the graph tool for structure, and `code_grep` for text.** Callers, routes, tables and events come from the graph; error messages, setting names and comments come from `code_grep`.
+3. **Ask the name the callers use.** For a method declared on an interface, ask the interface name the calls are written against. See [faq-wrong-or-missing-answers.md](faq-wrong-or-missing-answers.md).
+4. **Read the confidence line.** "complete" means use it as it is. "PARTIAL" says what was cut and how to get the rest.
+<!-- source: docs/answer-shapes.md; niro-local server instructions ("Which tool (the most specific wins; one call each)"); docs/how-the-graph-works.md ("How to read an answer") -->
+
+## See what it did for you
+
+The line at the end of each task, the record of what was asked, and a do-it-yourself A/B: [evaluate-what-niro-did.md](evaluate-what-niro-did.md).
+
+## What this version does not do
+
+This version of niro-cli answers everything from the graph on your computer. **Pull request review and root cause analysis are features of hosted Niro, because the local graph does not answer them.** See [hosted-only.md](hosted-only.md).
+<!-- source: src/lib/cloudGuard.js:66-69 (the printed message: "pull request review and root cause analysis, which the local graph does not answer"); src/lib/release.js:33 (cloud: false) -->

package/docs/lifecycle-plan-and-design.md

@@ -0,0 +1,44 @@
+# Plan and design with Niro
+
+**Before you change code, find out what the change reaches.** Niro answers in both directions:
+
+- **Upstream:** what depends on the code (its callers, and services that call it over HTTP or through events).
+- **Downstream:** what the code depends on (what it calls, the tables it reads and writes, the events it sends).
+
+## Who and how
+
+- **Who:** a developer planning a change, or a planning agent.
+- **How:** a coding agent connected over MCP (see [connect-your-ai-assistant.md](connect-your-ai-assistant.md)), or the terminal:
+
+```
+niro ask get_blast_radius method_fqn=OrderService.cancel
+niro ask get_impact_analysis http_path=/api/orders
+```
+<!-- source: src/commands/engineRoutes.js:28 (niro ask TOOL key=value) -->
+
+## Which tool answers which question
+
+| Question | Tool |
+|---|---|
+| What does a change to this method reach, both ways? | `get_blast_radius` (default depth 3, from 1 to 5) |
+| What breaks if this method, class, route or event changes? | `get_impact_analysis` (upstream by default) |
+| Which routes does this project serve, and which does it call? | `find_api_endpoints`, `find_outbound_http_calls` |
+| Which events are sent and handled? | `list_events`, `get_event_producers_and_handlers` |
+| Does similar code already exist? | `code_grep` (text search), `resolve_name` (find a name), `list_types` (every class by name) |
+<!-- source: niro-local src/niro_local/mcp/server.py:1573 (get_blast_radius), :1638 (get_impact_analysis), :1731, :1837, :1790, :1810, :2024, :1474, :1719; src/niro_local/mcp/impact.py:40-41 (depth 1 to 5) -->
+
+**Finding reusable code by meaning is not in this release.** The tool for it, `find_reusable_code`, needs LLM documentation, which this release does not include. Use `code_grep` and `list_types` instead.
+<!-- source: niro-local src/niro_local/reuse/__init__.py:37-40 (IN_THIS_RELEASE = False, "LLM documentation is not available in this release.") -->
+
+## Reading the answer
+
+- An answer marked **"confidence: partial"** listed every caller it could place, and says what it could not. See [how-the-graph-works.md](how-the-graph-works.md).
+- Callers across services that Niro inferred but could not confirm are listed separately, as "inferred". They are not counted in the risk.
+<!-- source: niro-local src/niro_local/mcp/impact.py:1018-1022, :1140 -->
+
+## Playbooks
+
+- [Change code safely](playbook-change-safely.md): the size of a planned change (`answer=count`), then its callers by name.
+- [Data stores and events](playbook-data-and-events.md): every reader and writer of a table across services, and the publishers and handlers of a topic.
+- [Add a feature](playbook-add-a-feature.md): what exists to copy before you design.
+<!-- source: the linked pages -->

package/docs/lifecycle-review.md

@@ -0,0 +1,30 @@
+# Review changes with Niro
+
+**When a reviewer looks at a change, the question is what else it touches.** Niro can answer that for the branch on the reviewer's own computer.
+
+## What works locally
+
+With the branch checked out and its folder indexed, the reviewer (or the reviewer's coding agent) can ask four kinds of question:
+
+- **Who depends on each changed method:** `get_blast_radius` or `get_impact_analysis`.
+- **Whether a route was removed or changed:** `find_api_endpoints`, compared with the main branch's folder.
+- **Whether a call to another service changed:** `find_outbound_http_calls`.
+- **Which tests reach the changed code:** `get_reverse_call_chain`. Test callers are marked `[test]`.
+<!-- source: niro-local src/niro_local/mcp/server.py:1528, :1573, :1638, :1731, :1837 -->
+
+A new branch of a folder Niro already indexes gets its own copy of the graph automatically. See [worktrees-and-branches.md](worktrees-and-branches.md).
+<!-- source: niro-local src/niro_local/temporary.py:175-240 -->
+
+## Review bots
+
+**Review bots, such as Cursor Bugbot or CodeRabbit, cannot use the local graph in this release.** They run on someone else's servers, and the local engine is not reachable from there. See [connect-review-bots.md](connect-review-bots.md).
+
+## Pull request review as a product
+
+**Automatic pull request review is a hosted Niro feature.** It runs on Niro's servers, against a copy of your code there, and the local graph does not answer it. See [hosted-only.md](hosted-only.md).
+<!-- source: src/lib/cloudGuard.js:66-69 (the printed message: "pull request review and root cause analysis, which the local graph does not answer") -->
+
+## Playbook
+
+[Review a change](playbook-review-a-change.md) runs the whole check on an example two-method change in Keycloak: one `get_blast_radius` call with `method_fqns` for the size, one with `answer=names` for the list, then the routes and calls to other services compared with the main branch.
+<!-- source: docs/playbook-review-a-change.md (runs brk-01-multi, brk-02-names) -->

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

@@ -0,0 +1,35 @@
+# Security and privacy across the lifecycle
+
+**Two questions matter here:**
+
+- What does Niro itself read, keep and send?
+- How can Niro help a security review of your own code?
+
+## What Niro reads, keeps and sends
+
+- **Reads:** the source, config and text files in the folders you add. It never opens real `.env` files, private keys, key stores or tool credential files.
+<!-- source: niro-local src/niro_local/mcp/text_files.py -->
+- **Keeps:** the graph and the build state, on your computer, in files only your user account can read.
+<!-- source: niro-local src/niro_local/registry.py:53-104 (folder 0700, files 0600, umask 077) -->
+- **Sends:** a small set of things, each listed in [what-leaves-your-machine.md](what-leaves-your-machine.md).
+
+The tools your agent uses answer from the graph on your computer. In Niro's own words: "Niro's tools answer your assistant from the graph on this machine and never send the contents of your files."
+<!-- source: src/lib/planUsage.js:118 (TOOLS_SENTENCE) -->
+
+More detail:
+
+- [secrets-and-masking.md](secrets-and-masking.md): how secrets are hidden before anything is shown or sent.
+- [coverage-audit-and-consent.md](coverage-audit-and-consent.md): the one place where small pieces of code leave the computer.
+- [where-things-are-stored.md](where-things-are-stored.md): every file Niro writes.
+
+## Using Niro in a security review
+
+Niro can help in three ways:
+
+- **List the attack surface.** `find_api_endpoints` lists every route your code serves. `find_outbound_http_calls` lists every call it makes to other services.
+- **Follow the data.** `list_data_resources` and `get_data_resource_usage` show which code reads and writes each table.
+- **Check reach before a fix.** `get_blast_radius` shows what a security fix will touch.
+<!-- source: niro-local src/niro_local/mcp/server.py:1731, :1837, :1920, :1932, :1573 -->
+
+**One limit to keep in mind:** a route built while the program runs, from values computed at that time, is not in the graph. Niro lists only routes written as fixed text, and says so in the answer.
+<!-- source: niro-local src/niro_local/mcp/server.py:3849-3857, :3876-3881, :3924 -->

package/docs/lifecycle-test.md

@@ -0,0 +1,28 @@
+# Decide what to test with Niro
+
+**To test a change well, you need to know what it reaches.** Niro lists what calls the changed code, through as many levels as you ask. It also lists the routes, tables and events on the way.
+
+## How
+
+```
+niro ask get_reverse_call_chain method_fqn=PriceCalculator.total depth=3
+niro ask get_blast_radius method_fqn=PriceCalculator.total
+```
+
+- `get_reverse_call_chain` lists callers up to the depth you ask (3 by default, 8 at most), 300 to a page.
+- `get_blast_radius` adds what the method calls, and the routes and events in between.
+<!-- source: niro-local src/niro_local/mcp/server.py:1528 (limit 300); src/niro_local/mcp/queries.py:55-56 (default depth 3, max 8) -->
+
+## Things to know
+
+- **Test code is in the graph.** Callers that are tests are marked `[test]`, so you can see which tests already reach the change.
+<!-- source: niro-local TODO.md:3679 (test code is indexed) -->
+- **The VERIFY purpose leaves the marks out.** With `purpose=VERIFY`, an answer gives names only, and drops the `[test]` and `[possible]` marks. Leave `purpose` empty when you need them.
+<!-- source: 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) -->
+- **A `[possible]` caller** is one Niro could not tie down to one target. For example, the call is made on a value whose type the code does not state. Check those by reading them.
+<!-- source: niro-local src/niro_local/mcp/chains.py:1945-1947 -->
+
+## Playbook
+
+[Test a change](playbook-test-a-change.md) finds, in one call with `answer=locations`, the six Keycloak tests the code makes possible three levels up through an interface, of which four really run `JpaUserCredentialStore.createCredentialEntity`. Two use a user stored outside Keycloak's database, so at run time they go to another store. It also checks the list against a grep.
+<!-- source: docs/playbook-test-a-change.md (runs test-01-rev) -->

package/docs/lifecycle-write-code.md

@@ -0,0 +1,35 @@
+# Write code with Niro
+
+**While code is being written, the coding agent asks the graph instead of searching through files.** One question to the graph can replace many text searches and file reads. For example: "who calls this method, three levels up?"
+
+## Who and how
+
+- **The coding agent** reaches Niro over MCP (the Model Context Protocol, the standard way coding agents use outside tools). Niro sets this up for 14 agents. See [connect-your-ai-assistant.md](connect-your-ai-assistant.md).
+<!-- source: src/mcp/setup.js:279-414 (the CLIENTS table, 14 entries) -->
+- **The developer** asks from the terminal with `niro ask`. Run it with no tool name to list the tools.
+<!-- source: src/commands/engineRoutes.js:28 -->
+
+## What agents are taught to do
+
+The skill Niro installs tells the agent to do four things:
+<!-- source: src/mcp/localSkill.js:97-161 (NIRO_SKILL_LOCAL) -->
+
+1. **Explore first.** Use `code_grep`, `get_source_code`, `resolve_name`, `list_types`, `get_class_structure`, `find_api_endpoints` and `find_handler` before reading files by hand.
+2. **Check both directions before changing anything.** Use `get_blast_radius`, `get_reverse_call_chain` and `get_impact_analysis`.
+3. **Follow flows across services.** Use the HTTP, event and data tools.
+4. **Say when Niro does not apply.** For example: the folder is not indexed, or the graph is behind the files.
+
+**Claude Code gets more help than the other agents.** Niro adds hooks to Claude Code: small commands that Claude Code runs at fixed moments. One of them shows an "impact check" before Claude Code edits a file. It is advisory only: it shows the information and never blocks the edit. To turn it off, run `touch ~/.niro/impact-gate-off`. The other agents get instruction text instead of hooks.
+<!-- source: src/mcp/setup.js:782-791 (Claude Code hooks), :1376-1405, :1512-1514 ("Advisory only. Off switch: touch ~/.niro/impact-gate-off"); docs/usecases/impact-gate.md:155 -->
+
+## When the graph is behind your edits
+
+The graph is rebuilt in the background about 3 seconds after a folder stops changing. If an answer is about a file that changed after the last build, the answer says so, and lists the files to read directly.
+<!-- source: src/lib/localBuild.js:36 (settle 3000 ms); niro-local src/niro_local/mcp/freshness.py:583-590 -->
+
+## Playbooks for this stage
+
+- [Change code safely](playbook-change-safely.md): callers before an edit, overloads, static imports, common names grep cannot narrow.
+- [Add a feature](playbook-add-a-feature.md): the interface to implement, its methods, existing implementations to copy.
+- [Ask for less](answer-shapes.md): `answer=count`, `locations`, `names`, `exists` and `match`, so an answer carries only what the next step needs.
+<!-- source: the linked pages (niro-local 43cce717, Keycloak 968726fe66, 2026-11-10) -->