@niroai/niro 0.17.0 → 1.0.0

package/docs/faq-wrong-or-missing-answers.md

@@ -0,0 +1,275 @@
+# FAQ: wrong or missing answers
+
+**Niro's graph is read from the code, and some code does not say plainly what it calls.** This page lists the known cases where an answer is wrong or incomplete, and what to do about each. For how to read the marks in an answer, see [how-the-graph-works.md](how-the-graph-works.md).
+
+## General
+
+### "Nothing in the graph is called '<name>'."
+Check three things, in this order:
+
+1. **The spelling.** `resolve_name` lists close matches.
+2. **The folder.** The code may be in a folder that is not indexed. The tools answer for the folder your agent started in.
+3. **The graph's age.** It may be out of date: run `niro build`.
+<!-- source: niro-local src/niro_local/mcp/server.py:894-899; src/mcp/localMode.js:39 (RELEASE_WORKTREE_SENTENCE) -->
+
+### "N files in this folder are not in the graph because they are larger than 2 MB ... rebuilding does not change that"
+The name may be in one of those files. Raise `NIRO_LOCAL_MAX_FILE_BYTES` and rebuild if they matter.
+<!-- source: niro-local src/niro_local/mcp/server.py:981-985 -->
+
+### What do "confidence: partial" and "has_more: true" mean?
+- **"Partial":** Niro listed every caller it could place, and found others it could not tie to one target.
+- **"has_more: true":** the answer is one page of a longer list.
+<!-- source: niro-local src/niro_local/mcp/chains.py:2053; src/niro_local/mcp/impact.py:1060-1064 -->
+
+### What do `[possible]`, `[test]` and "inferred, target unconfirmed" mean?
+- **`[possible]`:** a caller that may reach the method, but not certainly.
+- **`[test]`:** a caller in test code.
+- **"Inferred, target unconfirmed":** an HTTP link whose address Niro could not work out. It is not counted in the risk.
+
+With `purpose=VERIFY`, the `[possible]` and `[test]` marks are left out.
+<!-- source: niro-local src/niro_local/mcp/chains.py:377; src/niro_local/mcp/impact.py:1018-1022, :1140; 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) -->
+
+### Answers changed between two builds of the same code.
+A few answers can differ between builds of the same code. This is a known problem.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:3914 (open) -->
+
+### Answers differ from hosted Niro.
+They can. The local engine:
+
+- reads test code;
+- fixes some mistakes hosted Niro makes (rather than copying them);
+- has a few gaps of its own.
+
+`get_impact_analysis` has known differences, for example in the error flags and entry-point tags.
+<!-- source: niro-local TODO.md:297, :3679, :103; niro-local CLAUDE.md rule P13 (where Niro is wrong, niro-local does it right) -->
+
+## Missing callers
+
+### "Not listed: N call(s) with this method's name on a receiver of unknown type"
+A receiver is the value a method is called on. When the code does not say its type, Niro cannot tell which method the call reaches, so it does not link it. The answer points at those calls: read them.
+<!-- source: niro-local src/niro_local/mcp/chains.py:1945-1947 -->
+
+### A method shows no callers, but a framework calls it.
+Methods a framework calls for you (for example a route handler) have no caller in your code. The answer says "it is called by its framework".
+<!-- source: niro-local src/niro_local/mcp/chains.py:2075; niro-local docs/NIRO-LOCAL-ISSUES.md:4646 -->
+
+### A callback, or a function declared inside another function, shows no callers.
+Such a function is reached through what the outer function returns or passes on. The answer says so. Some inner functions have no node at all yet.
+<!-- source: niro-local src/niro_local/mcp/chains.py:2084-2093; niro-local docs/NIRO-LOCAL-ISSUES.md:1977, :2789, :4268 (open) -->
+
+### A caller is missing where the call goes through a value typed `any`, `object` or untyped.
+Niro cannot know the target, so it does not link the call.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:289, :3137, :4061 (open) -->
+
+### A caller is missing where the code imports a name under another name.
+Imports under another name (aliases) are not always followed.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:18, :1082, :3394, :3826 (open) -->
+
+### A call inside a lambda (a small unnamed function) or a macro is missing.
+Some calls inside lambdas, and inside Rust macro arguments, are not recorded.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:1699, :3011, :4547 (open) -->
+
+### `super.method()`, or a method of a parent interface, is not linked.
+Some calls to a parent class or interface miss their target.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:967, :1167, :2510, :5506 (open) -->
+
+### An implementation, or the interface that declares the method, shows "0 callers" when its callers use a child interface.
+In Java, if interface `B` extends interface `A`, and `A` declares `m()`, a call written on a `B` value (`b.m()`) is linked to a stand-in named `B.m`, not to `A.m`. So asking about `A.m`, or about a class that implements it, answers "0 callers, complete". Ask the name the callers use instead. Example in Keycloak: `JpaUserProvider.getUserByEmail` answers 0 callers, and `UserProvider.getUserByEmail` answers 17, because callers write `session.users().getUserByEmail(...)` and `getUserByEmail` is declared on `UserLookupProvider`, a parent of `UserProvider`. A known problem in this release.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md entry "2026-11-10: a call to an interface method inherited from a parent interface lands on a stand-in, so the declaring method and its implementations read '0 callers, complete'" (OPEN, committed f1a9fe59); scratchpad niro-cli-task-playbooks/runs/chg-03-impl-full.txt, chg-06-decl-count.txt, chg-07-iface-loc.txt; keycloak server-spi/.../UserProvider.java:33-37 -->
+
+### A call on a value that was cast to another type is missing.
+A cast is code that tells the compiler to treat a value as another type. Calls on cast values are not always linked.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:1139, :5075 (open) -->
+
+### Calls at the top of a file, or in a static block, are missing.
+Some calls outside any method are not recorded.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:1502, :2379 (open) -->
+
+### A call goes to a "stand-in" instead of my code.
+A stand-in is a placeholder for a target Niro could not find in your project. Known cases:
+
+- a value made by a factory function;
+- a struct literal in Go;
+- a namespace import;
+- an import from a sibling package in a workspace;
+- a Go call to another package in the same module.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:2263, :2402, :2570, :2613, :2963 (open) -->
+
+### Known gaps by language
+- **Python:** calls through a holder object's attribute; `cls()` in a class method; `X | None` types; module-level objects; parameters typed with a project generic; dotted imports of project modules; lookup tables; builtins linked to project methods; `@property` reads; dataclass members; Optional receivers.
+- **TypeScript and JavaScript:** overload calls; bare calls to globals; fields typed only by a constructor assignment; arrow functions inside functions; anonymous default exports; functions taken from a React hook's return value.
+- **Kotlin:** locals filled by a constructor; `with {}` and `apply {}`; chained calls recorded twice; bare calls guessed project-wide.
+- **Swift:** parent types; collection calls; UserDefaults stores.
+- **Go:** struct fields and embedded interfaces; aliases stored as parents; generic type methods; pointer receivers; dot imports.
+- **Rust:** `impl Trait for` a standard type; `self.field` calls; trait implementers; `use crate::` and `super::` paths; an impl in another file.
+- **PHP:** static calls; `$this` typed-property calls; routes registered by calls.
+- **C#:** constructor calls to a base class; `global using`; calls through `var` locals.
+- **C and C++:** by-value locals; `struct X *p` making a false class; client calls read as routes.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md: Python 187, 267, 510, 1026, 1196, 1420, 1747, 1774, 1872, 1887, 2591; TypeScript/JavaScript 1347, 1393, 1946, 1977, 2427, TODO.md:635; Kotlin 992, 1925, 4909, 5008; Swift 907, 1646, 2118; Go 2613, 2699, 2734, 2990, 5066; Rust 2052, 2634, 2676, 2806, 2831; PHP 1224, 1901, 565; C# 1113, 1481, 4432; C/C++ 1962, 3103, 710 (all open) -->
+
+## Routes and calls between services
+
+### A route is missing from `find_api_endpoints`.
+Niro lists routes written as fixed text. A route built while the program runs, from computed values, is not in the graph, and the answer says so. If your framework is not recognised, see [supported-overview.md](supported-overview.md).
+<!-- source: niro-local src/niro_local/mcp/server.py:3849-3857, :3876-3881, :3924 -->
+
+### "(no handler method)" or "(no handler in this project serves it)"
+- **"(no handler method)":** Niro found the route, but not the method that serves it.
+- **"(no handler in this project serves it)":** a call goes to a route that no code in this project serves.
+<!-- source: niro-local src/niro_local/mcp/server.py:3897, :4849 -->
+
+### An outbound call says "address not stated", or has no address.
+The address comes from a setting Niro does not know, such as an environment variable set only when the program is deployed. Tell Niro with `niro env set` or `niro base-url`. See [configuring-a-folder.md](configuring-a-folder.md).
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:362, :2067, :2085 (open) -->
+
+### A call to another service is not linked to that service's route.
+Run `niro route-rule unconnected` to see such calls, and add a rule with `niro route-rule add`. Known gaps:
+
+- calls through a proxy such as nginx;
+- calls through a shared send method that receives the address;
+- calls between modules in one folder.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:1582, :1724, :3864 (open); niro-local TODO.md:555; niro-local src/niro_local/route_rules_cli.py:33-54 -->
+
+### Two services with the same route are shown as one.
+This is a known problem.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:467 (open) -->
+
+### The service map shows only calls that start in my folder.
+`get_service_topology` shows calls from the folder your agent started in.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:3843 (open) -->
+
+### Known false links: cases where Niro links code it should not
+Niro's own test catalog checks that look-alike code is NOT linked. These cases fail, or are not tested yet:
+
+- **Java: a home-made `@GetMapping`.** An annotation named `@GetMapping` from your own package, with no Spring import, is taken for a Spring route. (Test fails today.)
+- **Java: one route on two services.** When two services declare the same path, a call meant for one can be linked to the other. (Test fails today.)
+- **Kotlin: the same, with Retrofit.** A Retrofit call to one service is linked to another service that declares the same path. (Test fails today.)
+- **C#: a hand-written class shaped like a gRPC base.** A class such as `BillingBase`, written by hand with no gRPC import, should give no route. Not tested yet.
+- **C#: generated gRPC code checked into the repository.** Checked-in generated client and service code should add no route and no call of yours. Not tested yet.
+
+Check such links by reading the code they point at.
+<!-- source: coverage catalog (niro-coverage-corpus 607dff9) rows java.http-server.trap.lookalike-get-mapping and java.http-client.trap.same-route-two-services (measured: missed), kotlin.http-client.trap.same-route-two-services (missed), csharp.grpc.grpc.trap-lookalike-base and csharp.grpc.grpc.trap-generated-base (not-measured), all status pending -->
+
+### Something that is not HTTP is listed as an HTTP call or route.
+Some look-alike names are taken for HTTP clients or routes. Examples: a `@mock.patch` test read as a PATCH route, or a map's `put` read as an HTTP PUT. Check them by reading the code.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:689, :730, :752, :2894, :5530 (open) -->
+
+## Data and events
+
+### A table or data store is missing.
+Some libraries record no store. Known cases: drizzle queries, Swift UserDefaults, and file reads with fixed paths in Python.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:2118, :2915, :3083 (open) -->
+
+### A method that changes a loaded JPA entity is listed as a reader, not a writer.
+JPA saves a change to an object it loaded (`em.find`, then setters) when the transaction ends, with no further call. Niro sees the `em.find` and lists the method under "read by", or not at all when the object was loaded elsewhere. Example in Keycloak: `get_data_resource_usage resource_fqn=CREDENTIAL` lists `JpaUserCredentialStore.updateCredential` only as a reader, and leaves out `moveCredentialTo`, which reorders priorities. Search the setters with `code_grep` (`answer=names`). A known problem in this release.
+<!-- source: scratchpad niro-cli-task-playbooks/runs/data-02-usage.txt; keycloak model/jpa/.../JpaUserCredentialStore.java:63-75 (updateCredential), :245 (moveCredentialTo); niro-local docs/NIRO-LOCAL-ISSUES.md entry "2026-11-10: a write made by changing a loaded JPA entity is listed as a read, or not at all" (OPEN) -->
+
+### A JPA named query is not listed as a read of its table.
+`em.createNamedQuery("name", Entity.class)` is not linked to the entity's table, while `em.persist`, `em.find`, `em.remove`, `createQuery` and `createNativeQuery` are. Example in Keycloak: `get_data_resource_usage resource_fqn=CREDENTIAL` does not list `JpaUserCredentialStore.getStoredCredentialEntities`, which reads it through the named query `credentialByUser`. A known problem in this release.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md entry "2026-11-10: a JPA named query (`em.createNamedQuery("name", Entity.class)`) is not a read of the entity's table" (OPEN, committed f1a9fe59); scratchpad niro-cli-task-playbooks/runs/data-02-usage.txt -->
+
+### A Kafka Streams topology or an Apache Camel route is not listed as a consumer.
+`builder.stream("topic")` and `from("kafka:topic?...")` are not read yet, so `get_event_producers_and_handlers` lists fewer handlers than the topic has. Search the topic name with `code_grep` as well.
+<!-- source: niro-coverage-corpus/catalog/java.json rows java.messaging.kafka-streams.builder and java.messaging.camel.route-uris (status pending, measured missed); scratchpad niro-cli-task-playbooks/runs/de-05-orders.txt (1 handler; java-mono has 3) -->
+
+### Any `.send("text")` is listed as a Kafka event.
+A known false match.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:2938 (open) -->
+
+### What does `find_orphaned_events` mean by "one side missing"?
+An event that is sent but never handled, or handled but never sent. That can mean three things:
+
+- the other side is outside this project;
+- the names do not match;
+- it is a real gap.
+<!-- source: niro-local src/niro_local/mcp/server.py:4688 -->
+
+### `get_impact_analysis` ignores `data_resource_fqn`, or `include_http_candidates=false`.
+These two inputs are listed but not supported yet. Use `get_data_resource_usage` for a table.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:336, :2158 (open); src/niro_local/mcp/impact.py:81; niro-local TODO.md:297 -->
+
+## Exceptions, classes and source
+
+### With `answer=names`, a deep call chain shows a direct callee at depth 2.
+On `get_call_chain ... scope=transitive answer=names`, a method that is called directly and also by another direct callee can be labelled with the deeper depth. The count is right. Ask without `answer` when the depth matters.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md entry "2026-11-10: `get_call_chain ... scope=transitive answer=names` labels a direct callee '(depth 2)' when a direct callee also calls it" (OPEN, committed f1a9fe59); scratchpad niro-cli-task-playbooks/runs/slow-02-names.txt against runs/slow-03-full.txt -->
+
+### Exception flow lists an exception that is caught and wrapped.
+Known. A catch is matched only by the exact exception name.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:1560, :3230 (open) -->
+
+### "Error: direction=upstream needs 'exception_type'"
+To ask which callers must handle an exception, name it with `exception_type`.
+<!-- source: niro-local src/niro_local/mcp/server.py:2694 -->
+
+### "Error: Unrecognised direction"
+Use `both`, `upstream` or `downstream` (for chains: `callers` or `callees`).
+<!-- source: niro-local src/niro_local/mcp/impact.py:91; src/niro_local/mcp/chains.py:84 -->
+
+### Class structure gives a member count but no names, or says "no members".
+Known for module files, Python dataclasses and Java enum constructors.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:136, :165, :497, :1887 (open) -->
+
+### Parameter lists look wrong outside Java.
+Known.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:4800 -->
+
+### `get_source_code` printed the wrong file, or a whole test file.
+This can happen when the name points at a stand-in. Ask by file and line instead.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:2872, :3263 (open) -->
+
+### "WARNING: <path> has changed since the last build"
+The lines shown come from the file as it is now. They may not match the graph's line numbers until the next build.
+<!-- source: niro-local src/niro_local/mcp/source_tools.py:2147 -->
+
+## Search and reading files
+
+### "PARTIAL: the search stopped at its 1.5 s limit ... Call again with continue_from=N"
+The search ran out of time. Call again with the `continue_from` value it gives, or narrow the search with `path_pattern`.
+<!-- source: niro-local src/niro_local/mcp/source_tools.py:1082-1167 -->
+
+### `code_grep` in exact mode refuses my text.
+Known: exact mode can refuse text that is not a valid regular expression (a search pattern). Escape the special characters.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:4019 (open) -->
+
+### "Refused: '<x>' is outside this worktree" or "leads outside this worktree through a symlink"
+The tools read only files inside the folder they answer for.
+<!-- source: niro-local src/niro_local/mcp/source_tools.py:907, :924 -->
+
+### `get_source_code` refuses a file.
+The answer gives one of these reasons:
+
+- the name marks it as a secret or credential file;
+- no service in the folder reads its folder;
+- it is a symlink;
+- it is not a file the tools read;
+- the build skips it;
+- `.gitignore` covers it;
+- it is an editor scratch file.
+<!-- source: niro-local src/niro_local/mcp/source_tools.py:825-850 -->
+
+## Tools
+
+### Where are `find_reusable_code` and `find_known_issues`?
+They need LLM documentation, which this release does not include.
+<!-- source: niro-local src/niro_local/reuse/__init__.py:37-40 -->
+
+### "<tool> is not answered for this folder: it is indexed locally by niro-local, whose graph holds structure and not source text or documentation"
+A tool from hosted Niro was asked, and the local graph has nothing for it.
+<!-- source: src/mcp/localBackend.js:636-652 -->
+
+### "Nothing in this folder's graph serves <path>, so the question was not answered"
+No route in this folder matches the path asked about.
+<!-- source: src/mcp/localBackend.js:416-428 -->
+
+### "The first 10 of N names are answered above."
+A batch question answers 10 names at most. Ask again for the rest.
+<!-- source: src/mcp/localBackend.js:100, :501 -->
+
+### A question about another folder gets "Nothing in the graph".
+The tools answer for the folder your agent started in. Run `niro ask` from the other folder.
+<!-- source: src/mcp/localMode.js:39 (RELEASE_WORKTREE_SENTENCE); niro-local docs/HOW-TO.md:644-692 -->
+
+### How do I report a wrong answer?
+Email help@niro.ai with the question, the answer and what you expected. The coverage audit also reports many gaps by itself. To check an answer before you report it, see [evaluate-what-niro-did.md](evaluate-what-niro-did.md).
+<!-- source: help@niro.ai: Niraj, 2026-11-10; src/lib/auditUpload.js -->

package/docs/hosted-only.md

@@ -0,0 +1,33 @@
+# Features of hosted Niro
+
+**Two features need hosted Niro: pull request review, and root cause analysis.** Hosted Niro runs on Niro's servers. This version of niro-cli answers everything from the graph on your own computer, and in Niro's own words, these two serve needs "which the local graph does not answer".
+<!-- source: src/lib/cloudGuard.js:66-69; src/commands/takeover.js:43-46 -->
+
+- **Pull request review.** Niro reviews each pull request against the full graph of your code: what the change reaches, routes removed, and calls across services. It is not a review bot, such as Cursor Bugbot.
+<!-- source: ai-assistant InternalCodeReviewController (/internal/code-review/impact, /cross-impact, /removed-endpoints, /context, /neighbourhood), lines 39-142 -->
+- **Root cause analysis (RCA).** Connect your alert sources (for example Sentry, Slack, Jira or CloudWatch). Niro traces each alert back to its likely cause in the code.
+<!-- source: monorepo CLAUDE.md service map (niro-connectors: Sentry, Slack, Jira, CloudWatch/SNS, log shippers); docs/cloud-README.md:37-38; ai-assistant BugController /api/bugs, lines 44-307 -->
+
+Agents in a web browser (such as Claude or ChatGPT on their websites) also need hosted Niro. See [connect-web-agents.md](connect-web-agents.md).
+
+## Where to go
+
+Sign up, or sign in, at **console.niroai.dev**. The old guide to the hosted product is kept in [cloud-README.md](cloud-README.md).
+<!-- source: Niraj, 2026-11-10 (sign-up at console.niroai.dev); src/lib/planUsage.js:90-92 -->
+
+## Questions
+
+### Can I switch this `niro` to hosted mode?
+No. This version is local only, by design: hosted mode is fixed in the package, and no setting turns it on.
+<!-- source: src/lib/release.js:13-14, :33 -->
+
+### Where did `niro new-temp-project`, `niro projects` and the other hosted commands go?
+They belong to hosted Niro, and are not in this version. The local `niro projects` and `niro remove` work on your own graph.
+<!-- source: src/index.js:474-487; src/commands/engineRoutes.js:42-45 -->
+
+### "`niro watch <path>` syncs a folder to Niro's cloud, which this release does not include."
+The background watcher (`niro service install`) keeps your local folders current instead.
+<!-- source: src/commands/watch.js:130-135 -->
+
+### Can I use local and hosted Niro together?
+Not yet established. This guide will say when it is.

package/docs/how-the-graph-works.md

@@ -0,0 +1,47 @@
+# How the graph works
+
+**The graph is a map of your code made of things and links.** The things are parts of your code, such as methods, classes, files, routes, tables and events. The links say how they relate: this method calls that one, this class extends that one, this method writes to that table.
+
+**An everyday comparison:** a family tree, but for code. You can start from any person and walk to their parents, their children, or their cousins.
+
+## What is in it
+
+| Things (nodes) | Links (edges) |
+|---|---|
+| Methods and constructors, classes, interfaces, enums, files (modules), outside libraries, outbound HTTP calls, data stores (tables, collections, queues), events | Calls; has-method; imports; uses-type; returns; extends; implements; overrides; reads-from, writes-to, deletes-from (data); calls-HTTP; handled-by (a route to the method that serves it); triggers-event and event-handled-by |
+<!-- source: get_index_status on a built folder (niro-local, 2026-11-10): node labels METHOD, MODULE, CLASS, EXTERNAL_MODULE, HTTPCALL, CONSTRUCTOR, DATA_RESOURCE, INTERFACE, EVENT, ENUM; edge types CALLS, HAS_METHOD, IMPORTS, USES_TYPE, EXPORTS, RETURNS, READS_FROM, CALLS_HTTP, WRITES_TO, EXTENDS, HANDLED_BY, DELETES_FROM, TRIGGERS_EVENT, REGISTERS_HANDLER, OVERRIDES, CALLS_HTTP_CANDIDATE, EVENT_HANDLED_BY, IMPLEMENTS -->
+
+**What is not in it: your source code.** The graph keeps names, places (file and line) and links. When a tool shows you code, it reads the file from disk at that moment.
+<!-- source: niro-local src/niro_local/mcp/freshness.py:305-308 (of upstream Niro: "its source tools read the graph's stored copy and ours do not") -->
+
+## How it is built
+
+1. Niro reads each source file and works out its structure. This step is called parsing.
+2. It then matches every name used to the thing it names, across the whole project. This step is called resolving. For example, it finds which `send` method a call to `send()` reaches.
+3. It recognises routes, outbound calls, data access and events from tables of known libraries and frameworks.
+<!-- source: niro-local CLAUDE.md "Three stores" and P4 (profile data); src/niro_local/profiles/ -->
+
+Building and keeping it current: [builds-and-updates.md](builds-and-updates.md).
+
+## How to read an answer
+
+- **"confidence: partial"** means Niro listed everything it could place, and found some calls it could not. It says how many, and where to look. A common cause is a call made on a value whose type the code does not state.
+<!-- source: niro-local src/niro_local/mcp/chains.py:1945-1947, :2053; src/niro_local/mcp/impact.py:1060 -->
+- **"has_more: true"** means the answer was cut to a page. Ask again with `offset` or a narrower question.
+<!-- source: niro-local src/niro_local/mcp/impact.py:1064 -->
+- **`[possible]`** marks a caller that might reach the method, but not certainly.
+- **"inferred, target unconfirmed"** marks an HTTP link where Niro could not work out the address being called. It is listed separately, and not counted in the risk.
+<!-- source: niro-local src/niro_local/mcp/chains.py:377; src/niro_local/mcp/impact.py:1018-1022, :1140 -->
+- **A stand-in** is a placeholder for code the graph could not place, for example a method of an outside library. A call that lands on a stand-in is real, but Niro did not find its target in your project.
+- **"No code in the project calls it: it is called by its framework"** means a framework calls the method for you, for example a web route handler.
+<!-- source: niro-local src/niro_local/mcp/chains.py:2075 -->
+
+## What it cannot see
+
+- **Routes and calls built while the program runs**, from values computed at that time.
+<!-- source: niro-local src/niro_local/mcp/server.py:3876-3881, :3924 -->
+- **Files over 2 MB, and files that take more than 20 seconds to read.** Both limits can be raised.
+<!-- source: niro-local src/niro_local/walk.py:79; src/niro_local/build/parse_time_limit.py:44-57 -->
+- **Languages it has no reader for.** See [supported-overview.md](supported-overview.md).
+
+The known gaps, by kind, are in [faq-wrong-or-missing-answers.md](faq-wrong-or-missing-answers.md).

package/docs/index.md

@@ -0,0 +1,157 @@
+# Niro documentation
+
+**Niro builds a map of your code on your own computer.** The map is called the code graph. It records which method calls which, which web addresses (routes) your services answer, which other services they call, and which tables and message topics they read and write. Coding agents ask the graph instead of searching through files, and you can ask it from the terminal.
+<!-- source: README.md (user guide); src/lib/release.js:33 (cloud: false, so everything is answered on this machine); src/mcp/server.js:359 -->
+
+This documentation ships inside the `@niroai/niro` package, so it is on your computer even when you are offline.
+<!-- source: package.json "files" (docs/*.md) -->
+
+## Start here
+
+```
+npm install -g @niroai/niro
+cd your-project
+niro start
+```
+
+`niro start` runs five steps:
+
+1. It checks this computer.
+2. It signs you in.
+3. It installs the local engine (the program that builds and answers from the graph).
+4. It builds the graph for the folder you are in.
+5. It connects your coding agents.
+
+If a step stops, run `niro start` again: it carries on from the first step that did not finish.
+<!-- source: src/commands/start.js:1-27, :61 (steps machine, sign-in, engine, build, assistant) -->
+
+## Find what you need
+
+| You want to | Read |
+|---|---|
+| See where Niro helps in how you build software | [lifecycle-overview.md](lifecycle-overview.md) |
+| Debug, change, review or test code, step by step | the playbooks, listed in [lifecycle-overview.md](lifecycle-overview.md) |
+| See how Niro's savings are measured, and check them yourself | [tokens-speed-and-accuracy.md](tokens-speed-and-accuracy.md), [evaluate-what-niro-did.md](evaluate-what-niro-did.md) |
+| Connect a coding agent, or use Niro from the terminal | [connect-overview.md](connect-overview.md) |
+| Fix an error message | [troubleshooting.md](troubleshooting.md), then [reference-messages.md](reference-messages.md) |
+| Know what leaves your computer | [what-leaves-your-machine.md](what-leaves-your-machine.md) |
+| Check whether your language or framework is supported | [supported-overview.md](supported-overview.md) |
+| Look up a command, a tool, a setting or a limit | [reference-cli.md](reference-cli.md), [reference-mcp-tools.md](reference-mcp-tools.md), [reference-environment-variables.md](reference-environment-variables.md), [reference-limits.md](reference-limits.md) |
+| Understand plans and the line limit | [licence-and-plans.md](licence-and-plans.md) |
+| Remove Niro | [uninstall.md](uninstall.md) |
+| Get pull request review or root cause analysis | [hosted-only.md](hosted-only.md) |
+
+## All pages
+
+**Where Niro fits:**
+- [lifecycle-overview.md](lifecycle-overview.md)
+- [lifecycle-plan-and-design.md](lifecycle-plan-and-design.md)
+- [lifecycle-write-code.md](lifecycle-write-code.md)
+- [lifecycle-review.md](lifecycle-review.md)
+- [lifecycle-test.md](lifecycle-test.md)
+- [lifecycle-debug.md](lifecycle-debug.md)
+- [lifecycle-onboarding.md](lifecycle-onboarding.md)
+- [lifecycle-security-and-privacy.md](lifecycle-security-and-privacy.md)
+- Playbooks:
+  - [debug an error message or a stack trace](playbook-debug-exception.md)
+  - [debug a wrong value](playbook-debug-wrong-value.md)
+  - [debug a failing call between services](playbook-debug-failing-service-call.md)
+  - ["it broke after my change"](playbook-debug-after-a-change.md)
+  - [debug config and environment](playbook-debug-config.md)
+  - [debug a slow path](playbook-debug-slow-path.md)
+  - [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)
+- [answer-shapes.md](answer-shapes.md): ask for less with `answer`
+- [tokens-speed-and-accuracy.md](tokens-speed-and-accuracy.md)
+- [evaluate-what-niro-did.md](evaluate-what-niro-did.md)
+
+**Ways in:**
+- [connect-overview.md](connect-overview.md)
+- [connect-terminal.md](connect-terminal.md)
+- [connect-your-ai-assistant.md](connect-your-ai-assistant.md)
+- [connect-review-bots.md](connect-review-bots.md)
+- [connect-web-agents.md](connect-web-agents.md)
+- [connect-ci.md](connect-ci.md)
+- [connect-team-server.md](connect-team-server.md)
+- One page per agent:
+  - [agent-claude-code.md](agent-claude-code.md)
+  - [agent-codex.md](agent-codex.md)
+  - [agent-claude-desktop.md](agent-claude-desktop.md)
+  - [agent-cursor.md](agent-cursor.md)
+  - [agent-windsurf.md](agent-windsurf.md)
+  - [agent-vscode.md](agent-vscode.md)
+  - [agent-gemini-cli.md](agent-gemini-cli.md)
+  - [agent-copilot-cli.md](agent-copilot-cli.md)
+  - [agent-factory.md](agent-factory.md)
+  - [agent-goose.md](agent-goose.md)
+  - [agent-opencode.md](agent-opencode.md)
+  - [agent-cline.md](agent-cline.md)
+  - [agent-kiro.md](agent-kiro.md)
+  - [agent-antigravity.md](agent-antigravity.md)
+
+**How it works:**
+- [how-the-graph-works.md](how-the-graph-works.md)
+- [builds-and-updates.md](builds-and-updates.md)
+- [worktrees-and-branches.md](worktrees-and-branches.md)
+- [where-things-are-stored.md](where-things-are-stored.md)
+- [what-leaves-your-machine.md](what-leaves-your-machine.md)
+- [secrets-and-masking.md](secrets-and-masking.md)
+- [licence-and-plans.md](licence-and-plans.md)
+- [coverage-audit-and-consent.md](coverage-audit-and-consent.md)
+- [configuring-a-folder.md](configuring-a-folder.md)
+- [uninstall.md](uninstall.md)
+
+**What is supported:**
+- [supported-overview.md](supported-overview.md)
+- One page per language:
+  - [C](supported-c.md)
+  - [C++](supported-cpp.md)
+  - [C#](supported-csharp.md)
+  - [Go](supported-go.md)
+  - [Java](supported-java.md)
+  - [JavaScript](supported-javascript.md)
+  - [Kotlin](supported-kotlin.md)
+  - [PHP](supported-php.md)
+  - [Python](supported-python.md)
+  - [Ruby](supported-ruby.md)
+  - [Rust](supported-rust.md)
+  - [Swift](supported-swift.md)
+  - [TypeScript](supported-typescript.md)
+
+**Reference:**
+- [reference-cli.md](reference-cli.md)
+- [reference-engine-commands.md](reference-engine-commands.md)
+- [reference-mcp-tools.md](reference-mcp-tools.md)
+- [reference-environment-variables.md](reference-environment-variables.md)
+- [reference-config-files.md](reference-config-files.md)
+- [reference-exit-codes.md](reference-exit-codes.md)
+- [reference-messages.md](reference-messages.md)
+- [reference-limits.md](reference-limits.md)
+
+**Help:**
+- [troubleshooting.md](troubleshooting.md)
+- FAQ pages:
+  - [install and setup](faq-install-and-setup.md)
+  - [login and account](faq-login-and-account.md)
+  - [licence and plans](faq-licence-and-plans.md)
+  - [indexing](faq-indexing.md)
+  - [wrong or missing answers](faq-wrong-or-missing-answers.md)
+  - [assistants and MCP](faq-assistants-and-mcp.md)
+  - [worktrees and branches](faq-worktrees-and-branches.md)
+  - [privacy and security](faq-privacy-and-security.md)
+  - [performance](faq-performance.md)
+  - [updates](faq-updates.md)
+  - [uninstall](faq-uninstall.md)
+  - [offline use](faq-offline.md)
+  - [feedback and receipts](faq-feedback-and-receipts.md)
+
+**Hosted Niro:**
+- [hosted-only.md](hosted-only.md)
+
+**For agents:**
+- `llms.txt` is a short index of these pages.
+- `llms-full.txt` is every page in one file.

package/docs/licence-and-plans.md

@@ -0,0 +1,72 @@
+# Licence and plans
+
+**Niro runs on your computer, but it needs a Niro account.** The account carries your plan, and the plan sets how many lines of code you can index. You sign up at **console.niroai.dev**.
+<!-- source: sign-up at console.niroai.dev: Niraj, 2026-11-10; src/lib/planUsage.js:90-92 (console address) -->
+
+## The plans
+
+| Plan | Lines you can index |
+|---|---|
+| **Free** | 500,000 lines |
+| **Free, with code sharing on** | No line limit |
+| **Pro trial** | 30 days |
+<!-- source: Free 500,000 lines, unlimited when sharing code, 30-day Pro trial: Niraj, 2026-11-10. The CLI reads the limit from the licence, as max_lines, and a missing max_lines means no limit: src/lib/planUsage.js:53-66 -->
+
+`niro plan` shows your plan, the lines used, and the folders using them. The limit itself comes from your account, not from the `niro` command.
+<!-- source: src/commands/plan.js:57-86; src/commands/plan.js:57-61 -->
+
+### What "code sharing" means
+
+**Code sharing is a switch on your account.** It is called "Share redacted code" and lives in the console, at **Settings, Privacy** (`console.niroai.dev/settings?tab=privacy`). It is not the same as the coverage audit, which is sent on every plan (see [coverage-audit-and-consent.md](coverage-audit-and-consent.md)).
+<!-- source: src/commands/plan.js:63-67 (option text and the settings?tab=privacy address); src/lib/auditUpload.js:27-30 (the audit is sent on every plan) -->
+
+With sharing on:
+
+- **On the Free plan, there is no line limit.** `niro plan` shows "no line limit while you share".
+- **The background watcher shares your code by itself.** Every 5 minutes it sends the files Niro indexes in each folder on your computer: the source files it parses and the config, build and text files it reads, never a gitignored file, a real `.env`, a key or `node_modules`. Secrets are masked and author and company names removed on your computer first. The first time, a folder's whole indexed set goes; after that, only files that changed. Turning sharing off in the console stops it: nothing more is sent after the next check.
+- **You can keep a folder out** while sharing stays on: `niro share exclude <folder>` (and every folder inside it). `niro share` lists the folders kept out, `niro share include <folder>` shares one again, and `niro plan` lists them too.
+- **You may also send one folder at once**, with `niro audit-push-repo`, and answer yes. It sends the same files with the same redaction, and refuses a folder you excluded.
+<!-- source: src/lib/planUsage.js:53-66; src/lib/shareCode.js (background sharing), src/lib/shareFiles.js (which files, redaction), src/lib/shareExclusions.js and src/commands/share.js (exclusions); src/lib/repoPush.js -->
+
+`niro plan` shows the switch in its "Help improve Niro" block.
+<!-- source: src/lib/planUsage.js sharingBlock -->
+
+## How lines are counted
+
+- **Every line of every file Niro reads counts,** blank lines and comments included.
+- **Two copies of the same repository count once,** by the larger. So branches and worktrees do not use up your plan.
+- **Different repositories add up.**
+- **A folder inside another indexed folder is counted once.**
+<!-- source: niro-local src/niro_local/licence/limit.py:9-60; src/lib/planUsage.js:1-21; src/commands/plan.js:57 -->
+
+## At the limit
+
+1. **The build that crosses the limit finishes.**
+2. **After that, a new folder is refused.** You see "Not built: this machine already holds N lines of code, over the M line limit", and a page in the console opens to help you choose what to do.
+3. **Folders already indexed keep rebuilding.** So do new branches and worktrees of them.
+<!-- source: src/lib/planUsage.js:71-87; src/commands/initLocal.js:59-62; src/commands/start.js:305-318 -->
+
+Your three ways forward, as `niro plan` lists them:
+
+1. **Turn on "Share redacted code"** in the console, for no line limit on the Free plan.
+2. **Ask for a Pro free trial** at `console.niroai.dev/request?plan=pro`.
+3. **Stay under the limit.** Stop indexing a folder with `niro plan remove <folder>`.
+<!-- source: src/commands/plan.js:63-67, :76-86 -->
+
+## How the licence works
+
+**Every time the engine starts, niro-cli asks Niro's billing service for a short-lived licence (a lease).** It hands the licence to the engine directly, without writing it to disk, and renews it before it runs out.
+<!-- source: src/lib/lease.js:9-25, :55-57, :136-148 -->
+
+- **Offline:** if the service cannot be reached, the engine keeps working for up to a day. You see "Could not renew the local engine's licence: ... It keeps working offline for up to a day."
+<!-- source: src/lib/lease.js:282-286; niro-local src/niro_local/licence/report.py:122 -->
+- **Refused:** if the service refuses (for example, the account is closed), the engine stops at once, with "Niro will not license the local engine: <reason>".
+<!-- source: src/lib/lease.js:271-276 -->
+- **Typed by hand:** this is why `niro-local build` typed by hand is refused, and `niro build` is the command to use. The engine gets its licence only from niro-cli.
+<!-- source: src/lib/release.js:25-31; niro-local src/niro_local/commands.py:1-72 -->
+
+## Your account
+
+- **Sign up:** console.niroai.dev.
+- **Delete your account:** email help@niro.ai.
+<!-- source: Niraj, 2026-11-10 -->

package/docs/lifecycle-debug.md

@@ -0,0 +1,48 @@
+# Debug with Niro
+
+**When something fails, you want facts about the code around the failure:** where an error comes from and who catches it, who writes a wrong value, which service answers a failing call, what a change reached, which setting a call depends on, and what a slow method does. Niro answers each of these from the code. The graph answers are the same every time on the same graph; a text search (`code_grep`) can stop early on a busy machine, and then says PARTIAL and how to carry on. An exception is an error a method throws, which a caller further up may catch.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md entry "2026-11-10: code_grep counts change with machine load ..." (OPEN, committed f1a9fe59); claim check round 1 reruns (59 of 59 graph answers byte-identical) -->
+
+## Pick the playbook by symptom
+
+| What you see | First tools (with the short `answer` form) | Playbook |
+|---|---|---|
+| An error message or a stack trace | `code_grep` for the message (`answer=locations`), `get_source_code`, `get_exception_flow` both ways | [playbook-debug-exception.md](playbook-debug-exception.md) |
+| A wrong value in a table or a response | `get_data_resource_usage`, `code_grep` for the setter (`answer=names`), `get_impact_analysis` (`answer=names`) | [playbook-debug-wrong-value.md](playbook-debug-wrong-value.md) |
+| A call to another service fails | `find_outbound_http_calls`, `find_handler`, `get_service_topology`, `niro route-rule unconnected` | [playbook-debug-failing-service-call.md](playbook-debug-failing-service-call.md) |
+| It broke after a change | `get_blast_radius` with `method_fqns` (`answer=count`, then `names`) | [playbook-debug-after-a-change.md](playbook-debug-after-a-change.md) |
+| It works here and not there | `niro env list`, `code_grep` over config files, `niro route-rule unconnected` | [playbook-debug-config.md](playbook-debug-config.md) |
+| A path is slow | `get_call_chain direction=callees` (`answer=count`, then full), `get_data_resource_usage` | [playbook-debug-slow-path.md](playbook-debug-slow-path.md) |
+| A message was sent and nothing happened | `get_event_producers_and_handlers`, `find_orphaned_events` | [playbook-data-and-events.md](playbook-data-and-events.md) |
+<!-- source: the playbook pages linked, each run on Keycloak or the synthetic java-mono corpus with niro-local 43cce717 (2026-11-10) -->
+
+Every playbook shows the real answers, says why they are complete or where they are not, and compares them with grep and file reads.
+
+
+## How
+
+```
+niro ask get_exception_flow method_fqn=PaymentService.charge
+niro ask get_exception_flow method_fqn=PaymentService.charge direction=upstream exception_type=TimeoutException
+```
+
+- **Downstream** (the default) lists the exceptions that can leave the method, and where each is thrown and caught, 3 levels deep by default and 5 at most.
+- **Upstream** lists which callers must handle a given exception. It needs `exception_type`. Without it, the answer is "Error: direction=upstream needs 'exception_type'".
+<!-- source: niro-local src/niro_local/mcp/server.py:1754 (inputs), :2694 (the upstream error); src/niro_local/mcp/queries.py:2537-2538 (depth 3, max 5) -->
+
+Two other tools help while debugging:
+
+- `get_call_chain` with `purpose=DEBUG` adds the source code of the method you ask about.
+- `find_handler` tells you which code answers a call to another service.
+<!-- source: niro-local src/niro_local/mcp/purpose.py:41 (DEBUG turns source on); src/niro_local/mcp/server.py:1870 -->
+
+## Known limits
+
+- An exception that is caught and wrapped in another can still be listed as escaping.
+- A catch is matched only by the exact exception name.
+<!-- source: niro-local docs/NIRO-LOCAL-ISSUES.md:1560, :3230 (open) -->
+
+## Root cause analysis
+
+**Root cause analysis from your alerts (for example from Sentry, Slack or Jira) is a hosted Niro feature.** The local graph does not answer it. See [hosted-only.md](hosted-only.md).
+<!-- source: src/commands/takeover.js:43-46; docs/cloud-README.md:37-38 -->