@niroai/niro 0.17.0 → 1.0.0

package/docs/reference-mcp-tools.md

@@ -0,0 +1,326 @@
+# MCP tools reference
+
+<!-- GENERATED by scripts/gen-mcp-tools-doc.js from the engine's own tools/list answer. Do not edit by hand: run the script again. -->
+<!-- source: niro-local MCP server tools/list, answered by niro-local source at a38ac9c6, run from that source; tools registered in src/niro_local/mcp/server.py build_server -->
+
+These are the tools a coding agent sees when it is connected to Niro. The list below is copied from what the engine itself serves, so it matches what your agent gets. Each tool's description is quoted exactly as the engine gives it to agents, so its wording is the engine's own.
+
+**A few things that hold for every tool:**
+
+- **Answers are text.** They are written for an agent to read, not as JSON fields.
+- **Every answer starts with a line saying where it came from:** "Answered from the local graph on this machine (niro-local)."
+<!-- source: niro-cli src/mcp/localBackend.js:189 -->
+- **The tools answer for one folder:** the one your agent's session started in. To ask about another folder, run `niro ask` from that folder.
+<!-- source: niro-cli src/mcp/localMode.js:61-64 -->
+- **`purpose` changes the shape of an answer.** Many tools take it. The values are LOCATE, ORIENT, COMPREHEND, TRACE, DEBUG, PROPAGATE, ASSESS_RISK, VERIFY, IMPLEMENT, AUDIT and SCOUT:
+  - VERIFY gives names only;
+  - ASSESS_RISK gives counts;
+  - COMPREHEND and DEBUG add the source code of the method asked about.
+<!-- source: niro-local src/niro_local/mcp/purpose.py:26-58 -->
+- **Two tools are off in this release:** `find_reusable_code` and `find_known_issues`. They need LLM documentation, which this release does not include, so they are not in the list.
+<!-- source: niro-local src/niro_local/reuse/__init__.py:37-40 (IN_THIS_RELEASE = False) -->
+- **The engine offers no MCP resources or prompts,** only these tools.
+<!-- source: niro-local src/niro_local/mcp (no resource or prompt registration) -->
+- **While a full build rewrites the graph,** only `get_index_status`, `code_grep` and `get_source_code` answer. The others say a build is running.
+<!-- source: niro-local src/niro_local/mcp/freshness.py:309 (GATE_EXEMPT) -->
+
+You can try any tool from the terminal: `niro ask <tool> key=value`. With no tool named, `niro ask` lists them.
+<!-- source: niro-cli src/commands/engineRoutes.js:28 -->
+
+For the limits on answer sizes and page sizes, see [reference-limits.md](reference-limits.md).
+
+## The tools
+
+- [`resolve_name`](#resolve_name)
+- [`get_call_chain`](#get_call_chain)
+- [`get_reverse_call_chain`](#get_reverse_call_chain)
+- [`get_blast_radius`](#get_blast_radius)
+- [`get_impact_analysis`](#get_impact_analysis)
+- [`get_class_structure`](#get_class_structure)
+- [`list_types`](#list_types)
+- [`find_api_endpoints`](#find_api_endpoints)
+- [`get_exception_flow`](#get_exception_flow)
+- [`list_events`](#list_events)
+- [`get_event_producers_and_handlers`](#get_event_producers_and_handlers)
+- [`find_orphaned_events`](#find_orphaned_events)
+- [`find_outbound_http_calls`](#find_outbound_http_calls)
+- [`get_service_topology`](#get_service_topology)
+- [`find_handler`](#find_handler)
+- [`list_data_resources`](#list_data_resources)
+- [`get_data_resource_usage`](#get_data_resource_usage)
+- [`get_index_status`](#get_index_status)
+- [`code_grep`](#code_grep)
+- [`get_source_code`](#get_source_code)
+- [`mark_task_complete`](#mark_task_complete)
+
+### resolve_name
+
+List what a name matches in the graph, at most 25. Not a step before other tools: they take a short name themselves and say when it matched several things. Use this to choose among matches.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `entity_fqn` | string | yes |  |
+
+### get_call_chain
+
+Returns the call chain (callers, callees, or both) for a method. Accepts method_fqn (partial auto-resolves) or http_path. direction is both (default), callers or callees; scope='direct' (default) is one level, scope='transitive' with transitive_depth 2 or 3 goes further.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `method_fqn` | string | no |  |
+| `http_path` | string | no |  |
+| `direction` | string | no |  |
+| `scope` | string | no |  |
+| `transitive_depth` | integer | no |  |
+| `max_depth` | integer | no |  |
+| `depth` | integer | no |  |
+| `include_all` | boolean | no |  |
+| `from_line` | integer | no |  |
+| `purpose` | string | no | Why you are asking, which picks the answer's shape: VERIFY names only, ASSESS_RISK counts, PROPAGATE a flat list with file:line, ORIENT a summary (class structure), COMPREHEND or DEBUG adds source. Also accepted: LOCATE, TRACE, IMPLEMENT, AUDIT, SCOUT. Default: TRACE. |
+| `include_source_code` | boolean | no | When true, the answer carries the numbered source of the method asked about, whole up to 150 lines (a longer one is marked as cut); listed methods carry their file and line only. On by default for purpose COMPREHEND or DEBUG; false turns it off. |
+| `answer` | string | no | A shorter answer: exists (yes or no, with the total), count (numbers only), locations (file:line and exact id per entry, no code), names (one name per line). Use it when that is all you need; leave it out for the full answer. |
+
+### get_reverse_call_chain
+
+Returns all callers (upstream) for a method or class. Accepts method_fqn, class_fqn, or http_path. For class-level impact use class_fqn — finds callers of all callable methods in one call. Up to 300 callers per answer; limit and offset page them.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `method_fqn` | string | no |  |
+| `http_path` | string | no |  |
+| `scope` | string | no |  |
+| `transitive_depth` | integer | no |  |
+| `max_depth` | integer | no |  |
+| `depth` | integer | no |  |
+| `include_all` | boolean | no |  |
+| `limit` | integer | no |  |
+| `offset` | integer | no |  |
+| `from_line` | integer | no |  |
+| `purpose` | string | no | Why you are asking, which picks the answer's shape: VERIFY names only, ASSESS_RISK counts, PROPAGATE a flat list with file:line, ORIENT a summary (class structure), COMPREHEND or DEBUG adds source. Also accepted: LOCATE, TRACE, IMPLEMENT, AUDIT, SCOUT. Default: PROPAGATE. |
+| `include_source_code` | boolean | no | When true, the answer carries the numbered source of the method asked about, whole up to 150 lines (a longer one is marked as cut); listed methods carry their file and line only. On by default for purpose COMPREHEND or DEBUG; false turns it off. |
+| `answer` | string | no | A shorter answer: exists (yes or no, with the total), count (numbers only), locations (file:line and exact id per entry, no code), names (one name per line). Use it when that is all you need; leave it out for the full answer. |
+
+### get_blast_radius
+
+Returns the full blast radius for a code change: both upstream callers that break AND downstream callees that receive different input. Seeds can be a method, class, HTTP endpoint, or event. Default direction='both', depth 3. For coupling through a shared data resource use get_data_resource_usage. Single call, no chaining needed.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `method_fqn` | string | no |  |
+| `method_fqns` | list of string | no | Several methods analysed as ONE change, in one call. |
+| `class_fqn` | string | no |  |
+| `http_path` | string | no |  |
+| `event_fqn` | string | no | Event name, event_source or topic; seeds every method that triggers, handles or registers for it. |
+| `depth` | integer | no | Levels to walk, 1 to 5. Default 3. |
+| `direction` | string | no | both (default), upstream (callers), downstream (callees). |
+| `from_line` | integer | no |  |
+| `purpose` | string | no | Why you are asking, which picks the answer's shape: VERIFY names only, ASSESS_RISK counts, PROPAGATE a flat list with file:line, ORIENT a summary (class structure), COMPREHEND or DEBUG adds source. Also accepted: LOCATE, TRACE, IMPLEMENT, AUDIT, SCOUT. Default: ASSESS_RISK. |
+| `include_source_code` | boolean | no | When true, the answer carries the source (numbered lines: the whole of the method asked about up to 150 lines, the first 12 of each other method; a longer method is marked as cut) of the method asked about and of up to 20 of the methods that depend on it or that it depends on. Purpose COMPREHEND or DEBUG alone adds only the method's own source. |
+| `data_resource_fqn` | string | no |  |
+| `include_data_coupling` | boolean | no |  |
+| `include_http_candidates` | boolean | no | Also include CALLS_HTTP_CANDIDATE callers/callees — HTTP calls whose target base URL could not be resolved, so the method is one of several plausible targets rather than a confirmed one. Always shown in a separate section labeled inferred, never mixed into the confirmed cross-service list. Default true. |
+| `answer` | string | no | A shorter answer: exists (yes or no, with the total), count (numbers only), locations (file:line and exact id per entry, no code), names (one name per line). Use it when that is all you need; leave it out for the full answer. |
+
+### get_impact_analysis
+
+Analyzes what breaks if you change a method, class, HTTP endpoint, or event. Returns upstream callers across service boundaries (HTTP/events). Default direction='upstream'. For a data resource (firestore collection, SQL table, S3 bucket) use get_data_resource_usage. Single call — no chaining needed.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `method_fqn` | string | no |  |
+| `method_fqns` | list of string | no | Several methods analysed as ONE change, in one call. |
+| `class_fqn` | string | no |  |
+| `http_path` | string | no |  |
+| `event_fqn` | string | no | Event name, event_source or topic; seeds every method that triggers, handles or registers for it. |
+| `depth` | integer | no | Levels to walk, 1 to 5. Default 3. |
+| `direction` | string | no | upstream (default, callers), downstream (callees), both. |
+| `from_line` | integer | no |  |
+| `purpose` | string | no | Why you are asking, which picks the answer's shape: VERIFY names only, ASSESS_RISK counts, PROPAGATE a flat list with file:line, ORIENT a summary (class structure), COMPREHEND or DEBUG adds source. Also accepted: LOCATE, TRACE, IMPLEMENT, AUDIT, SCOUT. Default: ASSESS_RISK. |
+| `include_source_code` | boolean | no | When true, the answer carries the source (numbered lines: the whole of the method asked about up to 150 lines, the first 12 of each other method; a longer method is marked as cut) of the method asked about and of up to 20 of the methods that depend on it or that it depends on. Purpose COMPREHEND or DEBUG alone adds only the method's own source. |
+| `data_resource_fqn` | string | no |  |
+| `include_data_coupling` | boolean | no |  |
+| `include_http_candidates` | boolean | no | Also include CALLS_HTTP_CANDIDATE callers/callees — HTTP calls whose target base URL could not be resolved, so the method is one of several plausible targets rather than a confirmed one. Always shown in a separate section labeled inferred, never mixed into the confirmed cross-service list. Default true. |
+| `answer` | string | no | A shorter answer: exists (yes or no, with the total), count (numbers only), locations (file:line and exact id per entry, no code), names (one name per line). Use it when that is all you need; leave it out for the full answer. |
+
+### get_class_structure
+
+One type's methods, constructors, fields, constants, and what it extends or implements.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `class_fqn` | string | yes |  |
+| `from_line` | integer | no |  |
+| `purpose` | string | no | Why you are asking, which picks the answer's shape: VERIFY names only, ASSESS_RISK counts, PROPAGATE a flat list with file:line, ORIENT a summary (class structure), COMPREHEND or DEBUG adds source. Also accepted: LOCATE, TRACE, IMPLEMENT, AUDIT, SCOUT. Default: COMPREHEND. |
+| `answer` | string | no | A shorter answer: exists (yes or no, with the total), count (members by kind), locations (file:line and exact id per member), names (one member per line). Leave it out for the full answer. |
+
+### list_types
+
+Every class, interface and enum in this project, by name, with the file each lives in. Use it to see what the codebase contains before asking about anything in particular.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `kind` | string | no |  |
+| `limit` | integer | no |  |
+| `offset` | integer | no |  |
+
+### find_api_endpoints
+
+Returns the HTTP endpoints (REST APIs) this project declares and exposes. Use '/' as path_pattern for all of them, or a substring of a path to narrow it. Remote methods and sockets that are not plain HTTP (gRPC, WebSocket, XML-RPC, Go net/rpc, SignalR) are listed too, each marked with its protocol.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `path_pattern` | string | no |  |
+| `service_filter` | string | no | Optional: filter by service name (e.g., 'billing-svc'). Keeps a route only when the path of the file of the method that HANDLES it, or that method's repository id, contains this text, ignoring case: it names the service that serves the route. |
+| `limit` | integer | no |  |
+| `offset` | integer | no |  |
+| `protocol` | string | no | Optional: keep only one protocol: 'http' (plain HTTP), or 'grpc', 'websocket', 'xmlrpc', 'netrpc', 'signalr'. Leave it out for every protocol; a line that is not plain HTTP ends with its protocol in brackets, and a remote method call shows the method in place of the path (RPC shipping.quote). |
+
+### get_exception_flow
+
+Which exceptions can escape a method, and where they are thrown and caught. Reach for it before writing a caller's error handling, or to find who would have to handle a new checked exception.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `method_fqn` | string | yes |  |
+| `depth` | integer | no |  |
+| `direction` | string | no | 'downstream' (default): what escapes this method. 'upstream': which callers must handle or declare exception_type. |
+| `exception_type` | string | no | For direction=upstream: the exception type (simple or qualified name) to trace up the callers. |
+| `from_line` | integer | no |  |
+| `purpose` | string | no | Why you are asking, which picks the answer's shape: VERIFY names only, ASSESS_RISK counts, PROPAGATE a flat list with file:line, ORIENT a summary (class structure), COMPREHEND or DEBUG adds source. Also accepted: LOCATE, TRACE, IMPLEMENT, AUDIT, SCOUT. Default: COMPREHEND. |
+| `include_source_code` | boolean | no | When true, the answer ends with the method's own source (numbered lines: the whole of the method asked about up to 150 lines, the first 12 of each other method; a longer method is marked as cut). On by default for purpose COMPREHEND or DEBUG; false turns it off. |
+
+### list_events
+
+Every event this project publishes or subscribes to, with how many places do each. Use it to see what moves through the system without a direct call.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `event_source_pattern` | string | no |  |
+| `event_type` | string | no |  |
+| `limit` | integer | no |  |
+| `offset` | integer | no |  |
+
+### get_event_producers_and_handlers
+
+For one event, named by its topic or its full name, who publishes it and who handles it. Use it before changing either side.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `name` | string | no |  |
+| `type` | string | no |  |
+| `from_line` | integer | no |  |
+
+### find_orphaned_events
+
+Events with only one side: published and nothing listens, or listened for and nothing publishes. Each is either a real gap or a name that does not match.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `limit` | integer | no |  |
+| `offset` | integer | no |  |
+
+### find_outbound_http_calls
+
+Returns the outbound HTTP calls this project makes to other services, and where they land when the address could be worked out. Use it to see what a folder depends on over the network before changing either end. Calls that are not plain HTTP (gRPC, WebSocket, XML-RPC, Go net/rpc, SignalR) are listed too, each marked with its protocol.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `path_pattern` | string | no |  |
+| `service_filter` | string | no | Optional: filter by calling service name (e.g., 'orders-svc'). Keeps a call only when the path of the file that MAKES it contains this text (case-sensitive), so it names the calling service, never the service called. To find calls into a service, leave it out and look at where each call lands. |
+| `limit` | integer | no |  |
+| `offset` | integer | no |  |
+| `protocol` | string | no | Optional: keep only one protocol: 'http' (plain HTTP), or 'grpc', 'websocket', 'xmlrpc', 'netrpc', 'signalr'. Leave it out for every protocol; a line that is not plain HTTP ends with its protocol in brackets, and a remote method call shows the method in place of the path (RPC shipping.quote). |
+
+### get_service_topology
+
+Shows which folder of this project calls which, over HTTP, with the routes involved. Use it to get the shape of the system before looking at any one part of it.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `from_line` | integer | no |  |
+
+### find_handler
+
+Given a method, shows what answers the HTTP calls it makes. Use it when a call leaves the code you are reading and you need the code at the other end.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `fqn` | string | no |  |
+| `from_line` | integer | no |  |
+| `relationship_type` | string | no | Filter by edge type (e.g., CALLS_HTTP, CALLS_HTTP_CANDIDATE, TRIGGERS_EVENT, CALLS). Omit to return all handler relationships. |
+| `include_http_candidates` | boolean | no | Also return CALLS_HTTP_CANDIDATE handlers: HTTP calls whose target base URL could not be resolved. Always labeled inferred and listed separately. Default true. |
+| `purpose` | string | no | Why you are asking, which picks the answer's shape: VERIFY names only, ASSESS_RISK counts, PROPAGATE a flat list with file:line, ORIENT a summary (class structure), COMPREHEND or DEBUG adds source. Also accepted: LOCATE, TRACE, IMPLEMENT, AUDIT, SCOUT. Default: LOCATE. |
+| `fqns` | list of string | no | Array of method FQNs for batch handler lookup. |
+
+### list_data_resources
+
+Every database, cache or queue this project touches, with how many places touch each. Use it to see what the code stores before asking about any one of them. A cache key the code builds at run time is listed under its fixed start, marked (rest at run time). A stored procedure the code calls is listed with the kind procedure.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `limit` | integer | no |  |
+| `offset` | integer | no |  |
+
+### get_data_resource_usage
+
+What reads, writes or deletes one store. Give the plain name, such as 'orders', or the full 'mongodb:collection:orders'. Use it before changing a table or collection, to see who depends on it. A cache key built at run time is named by its fixed start, such as 'stock:'. A method whose SQL is in its annotation (@Query, @SqlQuery) is listed itself.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `resource_fqn` | string | yes |  |
+| `from_line` | integer | no |  |
+
+### get_index_status
+
+What is indexed for this folder, by kind. Use it when an answer looks empty or out of date, or to learn whether a folder that is not indexed can be.
+
+It takes no inputs.
+
+### code_grep
+
+Regex/literal search inside source file contents (lines, not file names). Supports match_mode (exact\|regex), case_sensitive, single or batch patterns. Returns matching file paths and line numbers. For multiple terms use 'patterns' array or regex alternation (foo\|bar). Each match also names the method_fqn and class_fqn that enclose it when the graph knows the line: pass method_fqn straight to get_blast_radius before changing that code, no second lookup needed. For class declarations by name use get_class_structure, not this tool. Searches the files the build reads plus config, build and text files (.yml, .json, .properties, .xml, .sql, .md, Dockerfile, .tf and the like), with secrets in those masked, source first. A PARTIAL answer gives continue_from to search the rest. 50 files per page by default: use limit and offset for more.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `pattern` | string | no |  |
+| `patterns` | list of string | no |  |
+| `path_pattern` | string | no |  |
+| `max_matches_per_file` | integer | no |  |
+| `match_mode` | string | no |  |
+| `case_sensitive` | boolean | no |  |
+| `limit` | integer | no |  |
+| `offset` | integer | no |  |
+| `continue_from` | integer | no |  |
+| `answer` | string | no | A shorter answer: exists (yes or no, with the total), count (numbers only), locations (file:line and enclosing method fqn per hit), names (the methods holding a hit), match (only the text the pattern matched). Leave it out for the full answer. |
+
+### get_source_code
+
+Read source code for one or more files. Single mode: pass source_id with optional line range, or fqn for a method or class. Batch mode: pass 'sources' array to fetch multiple snippets in one call, much more efficient than separate calls when tracing execution paths. Accepts full paths or partial file names. Only files inside this worktree that the build reads, plus the config, build and text files code_grep searches, with secrets masked.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `source_id` | string | no |  |
+| `fqn` | string | no |  |
+| `target` | string | no |  |
+| `start_line` | integer | no |  |
+| `end_line` | integer | no |  |
+| `sources` | list of object or string | no |  |
+| `entity_fqns` | list of string | no |  |
+
+### mark_task_complete
+
+BEFORE YOU CALL THIS after changing code: for every method the task changed, and every MyBatis mapper statement it changed (a statement in mapper XML is its mapper interface method of the same id), call get_blast_radius on that method and check each caller it lists against the change: does the caller still get what it expects, and does it read a value the change now blanks, drops or reshapes? Do this even when the change looks local. Signal the end of a task and get back a one-line receipt saying what niro-local answered and what that replaced. Call it once at the end of every turn in which you either asked niro-local anything, or read, searched or edited this project's source with your own tools. A turn where you never asked it matters just as much to report: set searched_code_natively to true in that case. SHOW THE RECEIPT: when the answer is a line starting with '[NIRO-CLI]', reproduce it as the very last line of your reply, on its own line, wrapped in single backticks so it reads as a message from the tool rather than as your own prose. The backticks are the only thing you may add: the text between them must be character for character what came back. Do not reword it, expand it, or add your own commentary about how useful it was. If nothing comes back, print nothing. A reply without the line is unfinished: it is how the person sees what these tools did. Never write the line yourself: its numbers are measured by this server, so yours would be false. niro_helpfulness says whether niro-local's answers helped: helpful, partial, not_helpful, or not_used when you never asked it. task_outcome says whether the work itself finished: succeeded, partial or failed. A turn where it let you down is the most useful one to report. niro_did and without_niro_extra_tool_calls are required: the first is what the person reads, the second is the 'instead of ~N searches' part of the line, and 0 is a valid answer.
+
+| Input | Type | Required | What it is |
+|---|---|---|---|
+| `niro_did` | string | yes | DISPLAY ONLY: this is the line the DEVELOPER sees at the end of the task. Write it in niro-local's voice, not yours. One clause, MAXIMUM 70 CHARACTERS, starting with a past-tense verb, saying what niro-local found for the user this turn and what finding it with grep and file reads would have taken. Name concrete things the tools actually returned: counts of callers, files, services, endpoints, events. Add the contrast only when it is factual, e.g. 'that a grep would have missed', 'across 8 files', 'in 3 services'. FORBIDDEN: adjectives of value (powerful, invaluable, huge, quickly); any claim about time or money saved; any claim about how good niro-local is; tool names; source code; file paths; praise. State the finding and let the reader draw the conclusion. GOOD: 'Mapped 29 callers across 8 files that a grep would have missed' \| 'Found 2 cross-service HTTP callers behind an unresolved base URL' \| 'Traced the write path to 3 services sharing one collection' \| 'Confirmed the 29-caller list was complete' BAD: 'niro-local brilliantly uncovered hidden dependencies' (praise) \| 'Saved you 20 minutes' (time claim) \| 'get_blast_radius returned 29 callers' (tool name) \| 'Would have missed the callers' (passive, and it is the assistant's voice). IF NIRO-LOCAL DID NOT HELP THIS TURN, SAY SO: 'Returned nothing useful here'. Do not invent a win. Those turns are the ones most worth seeing, and the line is dropped rather than shown when you answer this way. Kept to about 1,000 characters, cut at the last full sentence that fits, so write it short. Secrets in it are masked on this machine before it is stored. |
+| `without_niro_extra_tool_calls` | integer | yes | Estimated ADDITIONAL native tool calls (Read, Grep, Bash, WebFetch, subagent delegations, etc.) you would have needed to reach the same answer if niro-local's tools did not exist this turn. HOW TO DERIVE IT: go through each niro-local tool call you actually made this turn and ask 'what native call(s) would I have substituted for this one, and how many?', e.g. one get_blast_radius call might substitute for roughly 6 grep/read calls across the caller graph; one get_call_chain might substitute for 3-4 dead-end file reads. Sum those substitutions across all the niro-local calls you made this turn. 0 is a valid and expected answer when you made no niro-local tool calls this turn, or niro-local made no material difference. This is a separate hypothetical total for the without-niro-local scenario: do not confuse it with total_tool_calls. |
+| `searched_code_natively` | boolean | no |  |
+| `niro_helpfulness` | one of `helpful`, `partial`, `not_helpful`, `not_used` | no |  |
+| `helpfulness_reason` | string | no | Why niro-local's answers helped or did not. Kept to about 1,000 characters, cut at the last full sentence that fits, so write it short. Secrets in it are masked on this machine before it is stored. |
+| `task_outcome` | one of `succeeded`, `partial`, `failed` | no |  |
+| `total_tool_calls` | integer | no |  |
+| `subagent_tool_calls` | integer | no |  |
+| `without_niro_gap` | string | no | What finding the same thing without niro-local would have taken. Kept to about 1,000 characters, cut at the last full sentence that fits, so write it short. Secrets in it are masked on this machine before it is stored. |
+| `without_niro_call_types` | list of one of `grep_search`, `file_read`, `bash_exec`, `web_search`, `subagent_delegation`, `other` | no |  |
+| `summary` | string | no | What the task was and what was done, in plain words. Kept to about 1,000 characters, cut at the last full sentence that fits, so write it short. Secrets in it are masked on this machine before it is stored. |

package/docs/reference-messages.md

@@ -0,0 +1,180 @@
+# Messages you may see
+
+<!-- GENERATED by scripts/gen-messages-doc.js from the headings of docs/faq-*.md. Do not edit by hand: add or change the FAQ entry, then run the script again. -->
+
+**Paste the start of a message into your search, or look for it below.** Each message links to the page that explains it, and each explanation cites the code that prints the message. Parts in angle brackets, such as `<folder>`, stand for the value in your message.
+
+## FAQ: coding agents and MCP
+
+See [faq-assistants-and-mcp.md](faq-assistants-and-mcp.md).
+
+- "Unknown client: X"
+- "Failed to register MCP server. Is the Codex CLI installed?" (or the same for Gemini, Copilot, droid or Claude Code)
+- "Failed to write config ... Manually add to <path>" or "No config path known for <client>."
+- What does "Answered from the local graph on this machine (niro-local)." mean?
+- "The local engine could not answer: <message>"
+- "the local engine did not answer <method> within Nms" or "Niro MCP request timed out"
+- My agent says "THIS FOLDER IS NOT INDEXED" and offers to index it.
+- Claude Code shows "Niro impact check, before you edit this file". How do I turn it off?
+- "Niro is not set up in any AI assistant on this machine, so there is nothing to remove."
+- "Invalid --url" or "Refusing to use MCP server URL ..."
+- "MCP <label> wizard exited with code N"
+
+## FAQ: feedback and receipts
+
+See [faq-feedback-and-receipts.md](faq-feedback-and-receipts.md).
+
+- What is the "[NIRO-CLI]" line at the end of a task?
+- "Nothing to report: no niro-local call answered this turn."
+- "The end-of-task Niro line is switched off on this machine"
+
+## FAQ: indexing and builds
+
+See [faq-indexing.md](faq-indexing.md).
+
+- "This folder is not added yet. Run niro init to add it and build it."
+- "Two folders were given (<a> and --path <b>). Give one."
+- "This folder is not indexed on this machine. Run niro start here to set it up."
+- A file is listed as one "whose parse passed the 20 s time limit".
+- "SKIPPED: N source file(s) larger than 2 MB ... were not indexed"
+- "another niro-local was writing the graph, and this gave up (it waits at most 120 s ...)"
+- The watcher's log says "Could not rebuild <folder>: ... Edits are not reaching the graph."
+- An answer says "NOTE FROM niro-local: ACTION REQUIRED. The following file(s) were modified after the last index build".
+- An answer says "niro-local is rewriting this folder's code graph right now".
+- "the graph at <path> is damaged ... It is rebuilt from what was indexed."
+- "the graph was written by an older major version of niro-local; run niro build"
+- "the graph ... was written by a newer major version of niro-local"
+- "The niro-local home ... was last used by a newer niro-local ... Upgrade with: niro upgrade"
+
+## FAQ: install and setup
+
+See [faq-install-and-setup.md](faq-install-and-setup.md).
+
+- I am on Windows. Setup says "Niro Local runs on macOS and Linux. On Windows, use WSL 2."
+- "Node vX. Niro needs Node 18 or newer."
+- "N GB free. A large repository's graph may need more."
+- "`niro start` is interactive and there is no terminal to prompt on."
+- "Global install failed. Install it yourself, then run niro start"
+- "<folder> is your home folder ... Niro will not index it."
+- "<folder> does not exist." or "<folder> is a file, not a folder."
+- "Nothing that looks like a project in <folder>."
+- "It holds more than 60 repositories, too many to index as one folder."
+- "It holds no source file niro-local can read."
+- "The local engine is not installed. Run `niro start` once to set up this machine."
+- "Downloading the local engine failed: HTTP n" or "The engine manifest came back incomplete."
+- "The local engine that arrived is not the one Niro published, so it was not installed."
+- "Another process has been downloading the local engine for too long."
+- "There is no local engine for <platform> <arch>."
+- The engine install ended with "Nothing was installed."
+- "The local engine cannot open its graph on this machine" or "Make that folder writable, or set NIRO_LOCAL_HOME"
+- "PM2 is not installed." / "PM2 install failed" / "PM2 was installed but [is not] runnable from this shell"
+- "Could not set niro-watch to start on login"
+- `niro status` says the background updates are "stopped", "not installed" or "OFF".
+
+## FAQ: licence and plans
+
+See [faq-licence-and-plans.md](faq-licence-and-plans.md).
+
+- "Not built: this machine already holds N lines of code, over the M line limit."
+- "No room left under the limit, so a new folder will not be indexed. Folders already indexed still rebuild."
+- "Not indexing: this machine already holds N lines ..." with a list ending "removing it frees nothing"
+- What does "no line limit while you share" mean, and what is shared?
+- "Could not read your plan from Niro. Check your connection, then run niro plan again."
+- "Niro will not license the local engine: <reason>"
+- "Could not renew the local engine's licence ... It keeps working offline for up to a day."
+- "Working on an expired licence: N hours of offline allowance left"
+- "Not indexing: ..." followed by "Reason given: ..."
+- "The Niro CLI has not handed this engine its licence yet."
+- A page opened in my browser by itself, at ".../limit".
+
+## FAQ: login and account
+
+See [faq-login-and-account.md](faq-login-and-account.md).
+
+- "Login timed out. Run niro login to try again."
+- "You are on the list. We will email you when you are in."
+- "Request sent. We reply within one business day."
+- "This account cannot sign in to Niro."
+- "The sign-in was not completed. Run niro start again to get a new code."
+- "Not logged in", "Session expired" or "Token refresh failed"
+- "Credentials rejected by server (401). Run niro login to refresh."
+- I signed in with `--api-key` or `--password`, and `niro mcp install` says "Not signed in. Run niro login".
+- A command says "`--api-url` ..." is not accepted.
+- "Device flow not available on this server, falling back to API key login."
+- "Invalid API key." or "Server did not return a token."
+
+## FAQ: offline use
+
+See [faq-offline.md](faq-offline.md).
+
+- "Network error calling <method> <path>"
+
+## FAQ: privacy and security
+
+See [faq-privacy-and-security.md](faq-privacy-and-security.md).
+
+- "N item(s) not sent: the local engine is too old to mask secrets. Run `niro upgrade`."
+- What does "Share redacted code" send?
+- "the Niro service cannot yet promise to delete this code when sharing is switched off, so nothing was sent"
+- "Passwords and tokens are refused and never stored"
+- "That is not a form of this command, and it is not repeated here in case it holds a secret."
+
+## FAQ: uninstall
+
+See [faq-uninstall.md](faq-uninstall.md).
+
+- "Nothing removed: there is no terminal to confirm on. Pass --yes to go ahead."
+- "Niro is partly removed; see the problems above."
+- "Could not send the waiting usage and audit records"
+- "Niro is not installed on this machine, so there is nothing to remove."
+
+## FAQ: updates
+
+See [faq-updates.md](faq-updates.md).
+
+- "npm could not replace the package. The usual cause is that your npm global folder needs root"
+- "Not upgrading: niro is npm-linked to a working copy" or "you are not running the globally installed niro"
+- "npm reported success, but there is no niro in your npm global folder."
+- "The version just installed does not support `niro upgrade --finish`"
+- "N of M refreshed, K failed."
+- "The local engine was not upgraded: <message>. Try again with niro engine install."
+- "Heads up: you are not signed in, so each client's installer will stop without refreshing it."
+- "Folders from Niro web: N folder(s) were set up with Niro web on this machine."
+
+## FAQ: worktrees and branches
+
+See [faq-worktrees-and-branches.md](faq-worktrees-and-branches.md).
+
+- "This folder is now on <branch>, which niro-local has not indexed."
+- "this folder's index was copied from project P and has not been built from this folder's files yet"
+- "A project's folders must all be on one branch."
+- "This folder is on no named branch"
+- "Gave up building <folder> after N tries; run `niro build` there to see why."
+- A folder that came back still shows its old "missing since" date.
+- "<path> is now on X; its part of this answer describes Y"
+
+## FAQ: wrong or missing answers
+
+See [faq-wrong-or-missing-answers.md](faq-wrong-or-missing-answers.md).
+
+- "Nothing in the graph is called '<name>'."
+- "N files in this folder are not in the graph because they are larger than 2 MB ... rebuilding does not change that"
+- What do "confidence: partial" and "has_more: true" mean?
+- What do `[possible]`, `[test]` and "inferred, target unconfirmed" mean?
+- "Not listed: N call(s) with this method's name on a receiver of unknown type"
+- An implementation, or the interface that declares the method, shows "0 callers" when its callers use a child interface.
+- A call goes to a "stand-in" instead of my code.
+- "(no handler method)" or "(no handler in this project serves it)"
+- An outbound call says "address not stated", or has no address.
+- Any `.send("text")` is listed as a Kafka event.
+- What does `find_orphaned_events` mean by "one side missing"?
+- "Error: direction=upstream needs 'exception_type'"
+- "Error: Unrecognised direction"
+- Class structure gives a member count but no names, or says "no members".
+- "WARNING: <path> has changed since the last build"
+- "PARTIAL: the search stopped at its 1.5 s limit ... Call again with continue_from=N"
+- "Refused: '<x>' is outside this worktree" or "leads outside this worktree through a symlink"
+- "<tool> is not answered for this folder: it is indexed locally by niro-local, whose graph holds structure and not source text or documentation"
+- "Nothing in this folder's graph serves <path>, so the question was not answered"
+- "The first 10 of N names are answered above."
+- A question about another folder gets "Nothing in the graph".

package/docs/secrets-and-masking.md

@@ -0,0 +1,48 @@
+# Secrets and masking
+
+**Niro hides secret values before it shows or sends anything.** Masking means replacing a value with a placeholder, such as `<MASK_PASSWORD_001>`. The name stays, so you can still see that `DB_PASSWORD` is set, but not to what.
+<!-- source: niro-local src/niro_local/redact/mask.py:1-75 (placeholders <MASK_KIND_NNN>, the variable name is kept) -->
+
+## Where masking happens
+
+- **In answers to your agent.** When `code_grep` or `get_source_code` reads a config, build or text file, every line is masked first. In a file of `key = value` lines, any value that is not clearly harmless is masked. Examples of such files: `.yml`, `.json`, `.properties`, `Dockerfile`, `go.mod`, `.tf`, `.md`.
+<!-- source: niro-local src/niro_local/mcp/text_files.py; niro-local CLAUDE.md (2026-11-07 amendment) -->
+- **Before anything is sent.** The coverage audit, the tool-usage record and a whole-repository push are all masked on your computer first.
+<!-- source: niro-local src/niro_local/redact/mask.py:3-6; src/niro_local/redact/files.py -->
+- **Names of people and companies.** In audit snippets, copyright holders, your email's company and the owner of the git remote become `<author>` and `<company>`.
+<!-- source: src/lib/redact.js:1-18 -->
+
+The masking rules are the same ones Niro's own service uses before anything reaches an AI model. The current rules are version 6.
+<!-- source: niro-local src/niro_local/redact/mask.py:898 (MASKER_VERSION = "6"); profiles/data/masking/llm-gateway-rules.json -->
+
+If your engine is too old to mask, nothing is sent. Items wait until you run `niro upgrade`.
+<!-- source: src/commands/auditSend.js; src/lib/journalUpload.js ("the local engine is too old to mask secrets") -->
+
+## Files Niro never opens
+
+| Kind | Examples |
+|---|---|
+| Environment files | `.env`, `.env.local`, `.env.production`. Only `.env.example`, `.env.sample` and `.env.template` are read |
+| Private keys and key stores | `.pem`, `.key`, `.p12`, `.pfx`, `.jks`, `.keystore`, `.p8`, `.ppk`, and files named `id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519` |
+| Tool credential files | `.npmrc`, `.pypirc`, `.netrc`, `.pgpass`, `.git-credentials`, `.htpasswd`, `.yarnrc`, `.dockercfg` |
+| Config and text files named as secrets | `credentials`, `secrets`, `secret`, `client_secret` (with any ending), for example `secrets.yaml` |
+| Config and text files that `.gitignore` covers | Any config or text file your `.gitignore` names |
+<!-- source: niro-local src/niro_local/mcp/text_files.py:186-202 (secret_named: the name rules are for config and text files); src/niro_local/mcp/source_tools.py:825-850 -->
+
+**Source code is treated differently.** A source file the build reads is read whatever its name: `secrets.py` and `Credentials.java` are searched like any other code. And a source file that git tracks is read even when `.gitignore` names it, the way git itself treats it.
+<!-- source: niro-local src/niro_local/mcp/text_files.py:191-193 ("`Credentials.java` and `secrets.py` are searched exactly as before"); niro-local CLAUDE.md, amendment of 2026-11-07 (a `.gitignore` rule does not apply to a file git tracks) -->
+
+## Seeing real config values on your own computer
+
+If you need your agent to see real values in config files (not in `.env` files, which are never read), turn masking off for one folder. This setting belongs to the engine, and `niro` does not pass it on yet, so run the engine itself:
+
+1. Run `niro engine status`. The `engine` line shows where the engine program is.
+2. In the folder, run that program with `config set show-config-values on`.
+
+Every answer then starts with a note saying values are not masked, and how to turn it back off (`config set show-config-values off`). This never changes what is sent. No tool argument can turn it on, but a coding agent may run the command through its shell, just as you can.
+<!-- source: niro-local src/niro_local/folder_settings.py:1-59, :3-4 and :13-14 ("no MCP argument turns it on. Only the command does, run by a person or by an assistant through its shell"), :43-46; src/niro_local/config_cli.py:20-37; src/commands/engine.js:81-118 (engine status prints the engine path); src/commands/engineRoutes.js:27-46 (config is not a routed command) -->
+
+## Settings that hold secrets
+
+`niro env` stores the addresses your code reads (for example `ORDERS_URL`), so the graph can link services. It refuses passwords and tokens, and never stores them. If you type a form of a command it does not know, it does not repeat what you typed, "in case it holds a secret".
+<!-- source: niro-local src/niro_local/env_args.py:34, :76-88 -->