@niroai/niro 0.16.0 → 0.18.0

package/docs/llms.txt

@@ -0,0 +1,126 @@
+# Niro (niro-cli with the local engine)
+
+> Niro builds a code graph on the developer's own computer, and serves it to coding agents over MCP and to the developer through `niro ask`. These pages ship inside the @niroai/niro package. Pull request review and root cause analysis are features of hosted Niro, not of this package.
+
+How an agent should use this index:
+
+1. Read this file once.
+2. Open only the page that matches the question.
+3. When the user pastes an error message, open reference-messages.md first.
+4. Never run `niro start`, `niro login` or `niro uninstall` on the user's behalf. Ask before `niro plan remove`.
+5. Every factual sentence in these pages has its source in an HTML comment beside it.
+
+llms-full.txt holds every page below in one file.
+
+## Reference and help (most used)
+
+- [reference-messages.md](reference-messages.md): every user-visible message with an answer, linked to its explanation
+- [troubleshooting.md](troubleshooting.md): the first three checks, and where each kind of problem is answered
+- [reference-mcp-tools.md](reference-mcp-tools.md): every MCP tool and its inputs, as the engine serves them
+- [reference-cli.md](reference-cli.md): every niro command and option
+- [reference-engine-commands.md](reference-engine-commands.md): the commands niro passes to the engine (ask, ui, env, route-rule and others)
+- [reference-environment-variables.md](reference-environment-variables.md): every environment variable and its default
+- [reference-config-files.md](reference-config-files.md): settings files and keys
+- [reference-exit-codes.md](reference-exit-codes.md): what each exit code means
+- [reference-limits.md](reference-limits.md): every size, time and count limit
+
+## FAQ
+
+- [faq-install-and-setup.md](faq-install-and-setup.md): installing, the engine, the background watcher
+- [faq-login-and-account.md](faq-login-and-account.md): signing in, accounts
+- [faq-licence-and-plans.md](faq-licence-and-plans.md): line limits, the licence
+- [faq-indexing.md](faq-indexing.md): a folder not added yet, building the graph, files left out
+- [faq-wrong-or-missing-answers.md](faq-wrong-or-missing-answers.md): known gaps in answers, by kind and by language
+- [faq-assistants-and-mcp.md](faq-assistants-and-mcp.md): connecting agents, agents not using Niro
+- [faq-worktrees-and-branches.md](faq-worktrees-and-branches.md): branches, worktrees, temporary projects
+- [faq-privacy-and-security.md](faq-privacy-and-security.md): what is sent, masking, files never read
+- [faq-performance.md](faq-performance.md): slow builds and answers, disk
+- [faq-updates.md](faq-updates.md): upgrading
+- [faq-uninstall.md](faq-uninstall.md): removing Niro from this computer: common questions
+- [faq-offline.md](faq-offline.md): working without a network
+- [faq-feedback-and-receipts.md](faq-feedback-and-receipts.md): the end-of-task line, feedback
+
+## Ways in
+
+- [connect-overview.md](connect-overview.md): which ways of using Niro work today: coding agents, the terminal, review bots, CI, a shared server
+- [connect-terminal.md](connect-terminal.md): niro ask, niro ui and other terminal use
+- [connect-your-ai-assistant.md](connect-your-ai-assistant.md): connecting coding agents over MCP
+- [connect-review-bots.md](connect-review-bots.md): review bots (not supported locally)
+- [connect-web-agents.md](connect-web-agents.md): browser agents (not in a release yet; use hosted Niro)
+- [connect-ci.md](connect-ci.md): build machines (partial)
+- [connect-team-server.md](connect-team-server.md): a shared server (not in a release yet)
+- [agent-claude-code.md](agent-claude-code.md): Claude Code
+- [agent-codex.md](agent-codex.md): Codex
+- [agent-claude-desktop.md](agent-claude-desktop.md): Claude Desktop
+- [agent-cursor.md](agent-cursor.md): Cursor
+- [agent-windsurf.md](agent-windsurf.md): Windsurf
+- [agent-vscode.md](agent-vscode.md): VS Code (GitHub Copilot)
+- [agent-gemini-cli.md](agent-gemini-cli.md): Gemini CLI
+- [agent-copilot-cli.md](agent-copilot-cli.md): GitHub Copilot CLI
+- [agent-factory.md](agent-factory.md): Factory (droid)
+- [agent-goose.md](agent-goose.md): Goose
+- [agent-opencode.md](agent-opencode.md): OpenCode
+- [agent-cline.md](agent-cline.md): Cline
+- [agent-kiro.md](agent-kiro.md): Kiro
+- [agent-antigravity.md](agent-antigravity.md): Antigravity
+
+## How it works
+
+- [how-the-graph-works.md](how-the-graph-works.md): what the graph holds, and how to read an answer
+- [builds-and-updates.md](builds-and-updates.md): adding another folder (`niro init`), rebuilding a graph, the background watcher, files left out
+- [worktrees-and-branches.md](worktrees-and-branches.md): one graph per folder and branch, temporary projects, clean-up
+- [where-things-are-stored.md](where-things-are-stored.md): every file Niro writes
+- [what-leaves-your-machine.md](what-leaves-your-machine.md): every upload, and the Data Processing Agreement in short
+- [secrets-and-masking.md](secrets-and-masking.md): masking, files never opened
+- [licence-and-plans.md](licence-and-plans.md): plans, line counting, the licence
+- [coverage-audit-and-consent.md](coverage-audit-and-consent.md): the coverage audit and code sharing
+- [configuring-a-folder.md](configuring-a-folder.md): telling Niro what the code does not say: env values, a service's address, route rules that connect calls between services
+- [uninstall.md](uninstall.md): removing Niro from this computer, or only one folder or one coding agent
+
+## Where Niro fits
+
+- [lifecycle-overview.md](lifecycle-overview.md): where Niro helps at each stage of work on code: plan, write, review, test, debug
+- [lifecycle-plan-and-design.md](lifecycle-plan-and-design.md): blast radius before a change
+- [lifecycle-write-code.md](lifecycle-write-code.md): agents asking the graph while coding
+- [lifecycle-review.md](lifecycle-review.md): reviewing a branch
+- [lifecycle-test.md](lifecycle-test.md): what a change reaches, which tests reach it
+- [lifecycle-debug.md](lifecycle-debug.md): debugging with Niro: from an error to the code that throws it, its callers and its catches
+- [lifecycle-onboarding.md](lifecycle-onboarding.md): learning a codebase
+- [lifecycle-security-and-privacy.md](lifecycle-security-and-privacy.md): security review with Niro
+- [playbook-debug-exception.md](playbook-debug-exception.md): an error message or stack trace to its thrower, callers and catches
+- [playbook-debug-wrong-value.md](playbook-debug-wrong-value.md): who writes a table or field, which event delivered a value
+- [playbook-debug-failing-service-call.md](playbook-debug-failing-service-call.md): caller, handler, address, two services on one route
+- [playbook-debug-after-a-change.md](playbook-debug-after-a-change.md): what a change reaches, tests first
+- [playbook-debug-config.md](playbook-debug-config.md): settings the code reads, where they are set, calls with no address
+- [playbook-debug-slow-path.md](playbook-debug-slow-path.md): what a slow method calls and where it reads the database
+- [playbook-change-safely.md](playbook-change-safely.md): callers before an edit, overloads, static imports
+- [playbook-add-a-feature.md](playbook-add-a-feature.md): the interface to implement and existing implementations
+- [playbook-review-a-change.md](playbook-review-a-change.md): one blast-radius call for a whole change
+- [playbook-test-a-change.md](playbook-test-a-change.md): the tests that reach a change
+- [playbook-onboard.md](playbook-onboard.md): services, routes, stores, events, types
+- [playbook-data-and-events.md](playbook-data-and-events.md): readers and writers of a table, publishers and handlers of a topic
+- [answer-shapes.md](answer-shapes.md): shorter tool answers: the `answer` input (exists, count, locations, names, match)
+- [tokens-speed-and-accuracy.md](tokens-speed-and-accuracy.md): how tokens, speed and accuracy are measured, and how to measure them on your own work
+- [evaluate-what-niro-did.md](evaluate-what-niro-did.md): the end-of-task line, the call record, `niro impact` over 7 and 30 days, a do-it-yourself A/B
+
+## What is supported
+
+- [supported-overview.md](supported-overview.md): computers, languages, and library counts per language
+- [supported-c.md](supported-c.md)
+- [supported-cpp.md](supported-cpp.md)
+- [supported-csharp.md](supported-csharp.md)
+- [supported-go.md](supported-go.md)
+- [supported-java.md](supported-java.md)
+- [supported-javascript.md](supported-javascript.md)
+- [supported-kotlin.md](supported-kotlin.md)
+- [supported-php.md](supported-php.md)
+- [supported-python.md](supported-python.md)
+- [supported-ruby.md](supported-ruby.md)
+- [supported-rust.md](supported-rust.md)
+- [supported-swift.md](supported-swift.md)
+- [supported-typescript.md](supported-typescript.md)
+
+## Other
+
+- [index.md](index.md): the start page for people
+- [hosted-only.md](hosted-only.md): pull request review and root cause analysis (hosted Niro)

package/docs/playbook-add-a-feature.md

@@ -0,0 +1,108 @@
+# Playbook: add a feature
+
+**The question, in the user's words:** "I want to add a new required action (a step a user must complete after login). What do I implement, and which existing classes can I copy?"
+
+**What you get at the end:** the interface to implement, its methods (with overloads), every existing implementation to copy from, the matching factory interface, and a yes or no on whether a pattern you expect already exists.
+<!-- source: outputs on this page: niro-local 43cce717 as `niro-local ask` from /home/niraj/projects/github/keycloak at 968726fe66, scratch home, 2026-11-10 (scratchpad niro-cli-task-playbooks/runs/feat-*.txt); `niro ask` runs the same engine command (src/commands/engineRoutes.js:28) -->
+
+Words used on this page:
+- an **interface** is a list of methods a class promises to have;
+- an **implementation** is a class that keeps that promise;
+- a **subtype** is a class or interface below another one;
+- an **overload** is one of several methods with the same name and different parameters;
+- a **default method** is an interface method that already has a body, so a class need not write it.
+
+## The steps
+
+### 1. How big is the interface?
+
+```
+niro ask get_class_structure class_fqn=org.keycloak.authentication.RequiredActionProvider answer=count
+
+INTERFACE org.keycloak.authentication.RequiredActionProvider: 7 methods
+extends org.keycloak.provider.Provider
+15 subtypes below it; ask without answer= for them
+```
+<!-- source: runs/feat-01-count.txt (210 characters) -->
+
+### 2. Its methods
+
+```
+niro ask get_class_structure class_fqn=org.keycloak.authentication.RequiredActionProvider answer=names
+
+methods:
+  evaluateTriggers(RequiredActionContext)
+  getMaxAuthAge()
+  getMaxAuthAge(KeycloakSession)
+  initiatedActionCanceled(KeycloakSession, AuthenticationSessionModel)
+  initiatedActionSupport()
+  processAction(RequiredActionContext)
+  requiredActionChallenge(RequiredActionContext)
+```
+<!-- source: runs/feat-02-names.txt (517 characters) -->
+
+Note the two `getMaxAuthAge` overloads. Four of the seven are `default` methods, so a new class must write only `evaluateTriggers`, `requiredActionChallenge` and `processAction`.
+<!-- source: keycloak server-spi-private/.../RequiredActionProvider.java:46, :58, :96, :104 (default), :70, :79, :86 (abstract) -->
+
+### 3. Existing implementations to copy
+
+The full answer (no `answer`) lists the 15 subtypes with their files, and which methods each one implements:
+
+```
+niro ask get_class_structure class_fqn=org.keycloak.authentication.RequiredActionProvider
+
+  extended or implemented by (15, up to 3 levels down):
+    org.keycloak.authentication.requiredactions.DeleteAccount  (implements RequiredActionProvider)  services/.../DeleteAccount.java:52
+    org.keycloak.authentication.requiredactions.UpdatePassword  (implements RequiredActionProvider)  services/.../UpdatePassword.java:60
+    org.keycloak.authentication.requiredactions.VerifyEmail  (implements RequiredActionProvider)  services/.../VerifyEmail.java:68
+    ...
+  methods implemented or overridden elsewhere (56 implementations):
+```
+<!-- source: runs/feat-03-full.txt (15,214 characters) -->
+
+This answer is large. Ask for it once, when you are choosing what to copy.
+
+### 4. The factory that goes with it
+
+```
+niro ask get_class_structure class_fqn=org.keycloak.authentication.RequiredActionFactory answer=count
+
+INTERFACE org.keycloak.authentication.RequiredActionFactory: 7 methods
+extends org.keycloak.provider.ProviderFactory
+19 subtypes below it; ask without answer= for them
+```
+<!-- source: runs/feat-05-factory.txt (216 characters) -->
+
+### 5. Does the pattern you expect already exist?
+
+`answer=exists` answers yes or no with a count:
+
+```
+niro ask code_grep pattern="implements RequiredActionProvider, RequiredActionFactory" answer=exists
+
+yes: 12 matching lines in 12 files in the files searched so far
+PARTIAL: the search stopped at its 1.5 s limit after 9653 of 11045 file(s) ...
+```
+<!-- source: runs/feat-04-exists.txt -->
+
+So one class often plays both roles. "In the files searched so far" and the PARTIAL line say the count is a floor. To search the rest, call again with the `continue_from` the answer gives, or pass a folder such as `path_pattern=services/`. Until an answer comes back without PARTIAL, treat the count as "at least".
+<!-- source: runs/feat-04-exists.txt ("Call again with continue_from=9653"); niro-local docs/NIRO-LOCAL-ISSUES.md entry "2026-11-10: code_grep counts change with machine load, and a busy machine can give '0 matching lines ... PARTIAL'" (OPEN, committed f1a9fe59); scratchpad niro-cli-task-playbooks-check/reruns (claim check round 1: 59 of 59 graph-tool reruns byte-identical, 7 code_grep reruns differed under load 17 to 30) -->
+
+## Why the answer is complete, and where it is not
+
+- **Subtypes are listed up to 3 levels down,** by the `extends` and `implements` the code declares.
+- **Finding code by what it does** ("is there already a rate limiter") is not in this release: `find_reusable_code` is off. Search by name with `code_grep` and `list_types`.
+<!-- source: runs/feat-03-full.txt ("up to 3 levels down"); docs/reference-mcp-tools.md ("Two tools are off in this release: find_reusable_code and find_known_issues") -->
+
+## What grep would do instead
+
+`grep -rln "implements.*RequiredActionProvider"` finds 13 files. The graph lists 15 subtypes. The two extra are `VerifyUserProfile` (extends `UpdateProfile`) and `WebAuthnPasswordlessRegister` (extends `WebAuthnRegister`): they implement the interface through a parent class, so no line in their files names it.
+<!-- source: `grep -rln --include=*.java "implements.*RequiredActionProvider\b\|implements RequiredActionProvider" .` = 13 files (Keycloak 968726fe66, 2026-11-10); runs/feat-03-full.txt (15 subtypes; VerifyUserProfile.java:45 and WebAuthnPasswordlessRegister.java:34 marked "extends") -->
+
+## Cost
+
+What these steps cost depends on your code and your question. How Niro counts the size of its answers, and how to measure the cost on your own tasks, is in [tokens-speed-and-accuracy.md](tokens-speed-and-accuracy.md).
+
+## Related
+
+[playbook-change-safely.md](playbook-change-safely.md), [playbook-onboard.md](playbook-onboard.md), [lifecycle-write-code.md](lifecycle-write-code.md).

package/docs/playbook-change-safely.md

@@ -0,0 +1,93 @@
+# Playbook: change code safely
+
+**The question, in the user's words:** "I want to change `KeycloakModelUtils.findUserByNameOrEmail` so it stops falling back to a username lookup. What depends on it?"
+
+**What you get at the end:** how big the change is, every caller up to three levels, the places to check, and which callers are tests. This is the check to run before an edit; [playbook-debug-after-a-change.md](playbook-debug-after-a-change.md) is the same check after one.
+<!-- source: outputs on this page: niro-local 43cce717 as `niro-local ask` from /home/niraj/projects/github/keycloak at 968726fe66, scratch home, 2026-11-10 (scratchpad niro-cli-task-playbooks/runs/chg-*.txt); `niro ask` runs the same engine command (src/commands/engineRoutes.js:28) -->
+
+Words used on this page:
+- the **blast radius** of a change is everything it can affect: what calls the changed code (upstream) and what it calls (downstream);
+- an **overload** is one of several methods with the same name and different parameters;
+- a **static import** lets a Java file call another class's static method with no class name in front, as `findUserByNameOrEmail(...)`.
+
+In recorded agent sessions, this was the second most common use of Niro: 144 of 794 calls (18%) mapped callers before an edit (these recordings are mostly Niro's own development, labelled by hand by one agent, about plus or minus 10%).
+<!-- source: scratchpad niro-cli-task-playbooks/TASKS.md (hand labels of 794 recorded calls; one labeller, about plus or minus 10%) -->
+
+## The steps
+
+### 1. How big is it?
+
+```
+niro ask get_blast_radius method_fqn=org.keycloak.models.utils.KeycloakModelUtils.findUserByNameOrEmail answer=count
+
+Blast radius for KeycloakModelUtils.findUserByNameOrEmail — 163 affected functions, risk: high (+4 in tests, not counted in risk) (upstream 30, downstream 137)
+```
+<!-- source: runs/chg-10-count.txt (668 characters) -->
+
+Upstream (what calls it) is what your change can break: 30 entries. Downstream (what it calls) is 137, but a change to this method's own behaviour does not change what those callees do.
+
+### 2. The callers, by name and depth
+
+```
+niro ask get_blast_radius method_fqn=org.keycloak.models.utils.KeycloakModelUtils.findUserByNameOrEmail direction=upstream answer=names
+
+upstream:
+  AbstractUsernameFormAuthenticator.getUserFromForm (depth 1)
+  AbstractUsernameFormAuthenticator.getUser (depth 2)
+  ...
+  ValidateUsername.authenticate (depth 1)
+  OrganizationAuthenticator.resolveUser (depth 1)
+  DefaultCIBALoginUserResolver.getUserFromLoginHint (depth 1)
+  BackchannelAuthenticationEndpoint.authorizeClient (depth 3)
+  AuthenticationManager.lookupUserForBruteForceLog (depth 1)
+  ResourceOwnerPasswordCredentialsGrantType.process (depth 3)
+  PassThroughAuthenticator.authenticate [test] (depth 1)
+  UsernameOnlyAuthenticator.authenticate [test] (depth 1)
+[shown all 30 entries; ask without answer= for signatures and code]
+```
+<!-- source: runs/chg-11-names.txt (2,403 characters, 30 entries) -->
+
+So the change reaches the browser login form, direct grant (password) logins, X.509 logins, organization logins and CIBA (backchannel) logins. Those are the flows to test.
+
+### 3. The places, to open one by one
+
+`answer=locations` gives `file:line` and the exact id of each caller, which `get_source_code` takes as it is. For the direct callers only, use `get_reverse_call_chain` (it lists direct callers and, with `depth`, the levels above).
+<!-- source: docs/answer-shapes.md; docs/reference-mcp-tools.md (get_reverse_call_chain) -->
+
+### 4. Overloads are answered one by one
+
+A short name that matches several methods is answered once per match when you give `answer`:
+
+```
+niro ask get_reverse_call_chain method_fqn=ErrorResponse.error answer=count
+
+## ErrorResponse.error(String, Response.Status)  (overload 1 of 2)
+ErrorResponse.error has 100 callers.
+## ErrorResponse.error(String, Object[], Response.Status)  (overload 2 of 2)
+ErrorResponse.error has 3 callers.
+```
+<!-- source: runs/chg-20-overloads.txt (667 characters) -->
+
+## Why the answer is complete, and where it is not
+
+- **All direct callers are listed, including a bare call through a static import.** `OrganizationAuthenticator.resolveUser` calls `findUserByNameOrEmail(session, realm, username)` with no class name in front.
+<!-- source: keycloak services/.../OrganizationAuthenticator.java:353 (bare call); runs/chg-11-names.txt (listed at depth 1) -->
+- **"confidence: PARTIAL" on step 1** means the walk stopped at depth 3 with more callers beyond; it says how many entries were cut there. Ask `depth=4` or `depth=5` if the far end matters.
+<!-- source: runs/chg-10-count.txt ("128 node(s) marked '[+N more beyond depth]'"); niro-local src/niro_local/mcp/impact.py:40-41 -->
+- **Known gap: methods declared on a parent interface.** Asking about an implementation, or the declaring interface, can answer "0 callers" when callers use a child interface's name. Ask the name the callers use. See [faq-wrong-or-missing-answers.md](faq-wrong-or-missing-answers.md).
+<!-- 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); runs/chg-03-impl-full.txt and runs/chg-07-iface-loc.txt -->
+
+## What grep would do instead
+
+- **Level 1 works:** `grep -rn "findUserByNameOrEmail("` gives 10 lines in 9 files: the declaration, 7 production calls and 2 test-provider calls. But `grep "KeycloakModelUtils.findUserByNameOrEmail"`, the obvious search, finds `OrganizationAuthenticator` only through its `import static` line (68), not the call itself (353), which has no class name in front.
+- **Level 2 and 3 do not scale.** The level-1 callers include `authenticate`, `getUser` and `action`. In Keycloak, `grep -F "getUser("` matches 560 lines in 237 files, and `grep -F "action("` 827 lines in 205 files, most of them unrelated methods of the same name.
+- **Overloads look the same to grep.** `grep "ErrorResponse.error("` gives 184 lines in 47 files with no way to split them by overload. The graph's caller files for the two overloads together are the same 47 files, so the lists agree, and the graph adds which overload each one calls.
+<!-- source: Keycloak 968726fe66, 2026-11-10: `grep -rn --include=*.java "findUserByNameOrEmail(" .` (10 lines, 9 files; OrganizationAuthenticator.java:353 has no class prefix, :68 is `import static org.keycloak.models.utils.KeycloakModelUtils.findUserByNameOrEmail`); `grep -F` counts ("getUser(" 560 lines, 237 files; "action(" 827 lines, 205 files); `grep -rn --include=*.java "ErrorResponse.error(" .` 184 lines in 47 files; caller files from runs/eval-01-loc.txt and runs/eval-02-loc-all.txt = 47, `comm` of the two sorted lists empty both ways -->
+
+## Cost
+
+What these steps cost depends on your code and your question. How Niro counts the size of its answers, and how to measure the cost on your own tasks, is in [tokens-speed-and-accuracy.md](tokens-speed-and-accuracy.md).
+
+## Related
+
+[playbook-debug-after-a-change.md](playbook-debug-after-a-change.md), [playbook-test-a-change.md](playbook-test-a-change.md), [lifecycle-plan-and-design.md](lifecycle-plan-and-design.md).

package/docs/playbook-data-and-events.md

@@ -0,0 +1,107 @@
+# Playbook: data stores and events
+
+**The questions, in the user's words:** "We are renaming a column of the `orders` table: what reads or writes it, in which services?" and "I am changing the payload of the `orders.placed` topic: who publishes it, and who consumes it?"
+
+**What you get at the end:** every method that reads, writes or deletes a store, across services and through ORM repositories; and for a message topic, its publishers and handlers, plus the events that have only one side.
+<!-- source: outputs on this page: niro-local 43cce717 from /home/niraj/projects/github/niro-coverage-corpus/java-mono (68 synthetic services and a main that calls them; niro-coverage-corpus/README.md), scratch home, 2026-11-10 (scratchpad niro-cli-task-playbooks/runs/data-10-orders.txt, de-*.txt); `niro ask` runs the same engine command (src/commands/engineRoutes.js:28) -->
+
+Words used on this page: an **event** is a message one piece of code publishes on a named **topic** (or queue) and other code handles; a **broker** is the server that carries it (Kafka, RabbitMQ, Redis and others).
+
+In recorded agent sessions (mostly Niro's own development, labelled by hand by one agent, about plus or minus 10%), agents asked data and event questions with text search: 10 of 21 calls were `code_grep` and 1 was `list_data_resources`. The tools below answer these directly.
+<!-- source: scratchpad niro-cli-task-playbooks/TASKS.md (hand labels of 794 recorded calls) -->
+
+## A table across services
+
+```
+niro ask get_data_resource_usage resource_fqn=orders
+
+sql:table:orders
+  read by (4):
+    LedgerDao.openOrders
+    OrderRepository.findByStatus
+    OrderRepository.findLate
+    OrderStoreService.open
+  written by (2):
+    SharedTables.createOrder
+    OrderStoreService.save
+  deleted by (1):
+    OrderStoreService.remove
+```
+<!-- source: runs/data-10-orders.txt (268 characters) -->
+
+These are in three services: `main` (`SharedTables`, plain SQL), `jdbc` (`LedgerDao`, plain SQL) and `spring-data-jpa` (`OrderRepository` and `OrderStoreService`, through Spring Data). `findByStatus` is a derived query: its SQL comes from the method's name and the entity's `@Table(name = "orders")`, and no line of code names the table.
+<!-- source: java-mono main/.../SharedTables.java:23 (INSERT INTO orders); services/jdbc/.../LedgerDao.java:54 (SELECT ... FROM orders); services/spring-data-jpa/.../OrderEntity.java:8 (@Table(name = "orders")), OrderRepository.java:10 (findByStatus), OrderStoreService.java:12-16; services/spring-data-jpa/EXPECTED.json (same five spring-data-jpa uses) -->
+
+Then, for each method, `get_blast_radius method_fqn=... direction=upstream answer=names` gives what calls it.
+
+**What grep would do instead:** `grep -rniw orders` prints 53 lines in the Java files, mostly route paths (`/api/orders`), host names (`orders-api`) and topic names. The SQL lines are in there, but `OrderStoreService.save` and `remove` are not: they call `repository.save(order)` and `repository.deleteById(id)`.
+<!-- source: `grep -rniw "orders" java-mono --include=*.java | wc -l` = 53 (2026-11-10); OrderStoreService.java:14, :16 -->
+
+## A topic: who publishes and who handles
+
+```
+niro ask get_event_producers_and_handlers name=invoices.created
+
+rabbitmq:invoices.created   [spring-amqp]
+  published by (1):
+      EventPublishers.invoiceCreated
+  handled by (1):
+      InvoiceListener.onInvoice
+```
+<!-- source: runs/de-03-ph.txt (149 characters) -->
+
+The publisher is in `main` (`rabbitTemplate.convertAndSend("invoices.created", ...)`) and the handler in `spring-amqp` (`@RabbitListener(queues = "invoices.created")`).
+<!-- source: java-mono main/.../EventPublishers.java:55; services/spring-amqp/.../InvoiceListener.java:14 -->
+
+### A trap a text search shows you
+
+```
+niro ask get_event_producers_and_handlers name=orders.placed
+
+kafka:orders.placed   [kafka-clients]
+  published by (1):
+      EventPublishers.orderPlaced
+  handled by (1):
+      OrderAuditConsumer.run
+```
+<!-- source: runs/de-05-orders.txt -->
+
+A text search shows a second line that looks like a publish: `TrapCaller.run` calls `outbox.send("orders.placed", "x")`. But `outbox` is a class of the project's own that happens to be called `KafkaTemplate`, not Spring's Kafka client. Niro recognises a publish by the type the call is made on, so it leaves this one out. An agent with only a text search has to read the class to rule it out; in the A/B (task p-07), the shell-only agents did, in both runs.
+<!-- source: java-mono main/.../traps/TrapCaller.java:12, :20 ("Must not become a publish to orders.placed"); runs/ts-02-out.txt note ("A call is recognised by the TYPE of the thing it is called on"); scratchpad niro-cli-task-playbooks/ab/judged-p1/p-07-a.json and judged-p2/p-07-a.json (TrapCaller item FOUND) -->
+
+### And where Niro misses, today
+
+The same topic has two more consumers that this release does not read: a Kafka Streams topology (`builder.stream("orders.placed")`) and a Camel route (`from("kafka:orders.placed?...")`). Both are recorded gaps. A text search for the topic name finds them, so for a payload change, run `code_grep pattern=orders.placed answer=locations` as well.
+<!-- source: java-mono services/kafka-clients/.../OrderEnrichmentTopology.java:9; services/camel/.../BillingRoutes.java:11; niro-coverage-corpus/catalog/java.json rows java.messaging.kafka-streams.builder and java.messaging.camel.route-uris (status pending, measured missed) -->
+
+## Events with one side
+
+```
+niro ask find_orphaned_events limit=8
+
+20 event(s) with only one side:
+  carts.recovered   [MESSAGE_QUEUE, nats]
+      handled here, nothing publishes it
+  giftcards.issued   [MESSAGE_PUBLISH, spring-kafka]
+      published here, nothing handles it
+  ...
+```
+<!-- source: runs/de-02-orphans.txt -->
+
+One side missing means one of three things, and the answer says so: the other side is outside this project, its library is not recognised, or the two sides name the event differently.
+<!-- source: runs/de-02-orphans.txt (the explanatory paragraph) -->
+
+## Why the answer is complete, and where it is not
+
+- **Stores and events are read from known libraries and forms.** Each language page lists them, see [supported-overview.md](supported-overview.md). A form not listed (like the two consumers above) is missing without a warning.
+- **Topics are matched by name.** A topic name built at run time, or read from a setting Niro has no value for, cannot be matched.
+- **An in-process event** (a framework's own event bus) never leaves its service, and the answer marks it so.
+<!-- source: runs/de-01-events.txt ("An event marked in-process never leaves the program that sends it"); docs/how-the-graph-works.md -->
+
+## Cost
+
+What these steps cost depends on your code and your question. How Niro counts the size of its answers, and how to measure the cost on your own tasks, is in [tokens-speed-and-accuracy.md](tokens-speed-and-accuracy.md).
+
+## Related
+
+[playbook-debug-wrong-value.md](playbook-debug-wrong-value.md), [playbook-onboard.md](playbook-onboard.md), [faq-wrong-or-missing-answers.md](faq-wrong-or-missing-answers.md).

package/docs/playbook-debug-after-a-change.md

@@ -0,0 +1,96 @@
+# Playbook: "it broke after my change"
+
+**The question, in the user's words:** "I changed how credentials are created and removed, and now something else fails. What does my change reach?"
+
+**What you get at the end:** everything that calls the changed methods (up to the depth you ask), which of those are tests, the routes and other services on the way, and what the changed methods call in turn.
+<!-- source: Keycloak outputs on this page: niro-local 43cce717 as `niro-local ask` from /home/niraj/projects/github/keycloak at 968726fe66, scratch home, 2026-11-10 (scratchpad niro-cli-task-playbooks/runs/brk-*.txt); java-mono outputs from niro-coverage-corpus/java-mono (runs/xs-05-blast.txt); `niro ask` runs the same engine command (src/commands/engineRoutes.js:28) -->
+
+Words used on this page: the **blast radius** of a change is everything it can affect: the methods that call the changed code (**upstream**) and the methods it calls (**downstream**).
+
+## The steps
+
+### 1. Name every method you changed, in one call
+
+`method_fqns` takes a list, and treats it as one change. Start with the count, to see how big it is:
+
+```
+niro ask get_blast_radius method_fqns='["org.keycloak.models.jpa.JpaUserCredentialStore.createCredentialEntity","org.keycloak.models.jpa.JpaUserCredentialStore.removeCredentialEntity"]' answer=count
+
+Blast radius for 2 methods — 46 affected functions, risk: high (+6 in tests, not counted in risk) (upstream 27, downstream 25)
+confidence: PARTIAL | has_more: true — ... What is cut is only the far end of the chain: 22 node(s) marked "[+N more beyond depth]" have callers further out that were not walked.
+[counts only; ask without answer= for the list]
+```
+<!-- source: runs/brk-01-multi.txt (634 characters); method_fqns "Several methods analysed as ONE change, in one call" (docs/reference-mcp-tools.md, get_blast_radius) -->
+
+"PARTIAL" here means the walk stopped at the depth you asked (3 by default), not that something was missed inside it.
+<!-- source: runs/brk-01-multi.txt ("What is listed is correct. Every DIRECT dependent is listed"); niro-local src/niro_local/mcp/impact.py:40-41 (depth 1 to 5) -->
+
+### 2. List the names, upstream only
+
+```
+niro ask get_blast_radius method_fqns='[...same two...]' direction=upstream answer=names
+
+Blast radius for 2 methods — 21 affected functions, risk: high (+6 in tests, not counted in risk) (upstream 27)
+upstream:
+  JpaUserCredentialStore.createCredential (depth 1)
+  UserCredentialManager.createStoredCredential (depth 2)
+  SubjectCredentialManagerCacheAdapter.createStoredCredential (depth 3)
+  PasswordCredentialProvider.createCredential (depth 3)
+  ...
+  CredentialModelTest.testCredentialCRUD [test] (depth 3)
+  ...
+  ResetOTP.authenticate (depth 3)
+  UserResource.removeCredential (depth 3)
+  JpaUserProvider.removeStoredCredential (depth 1)
+[shown all 27 entries; ask without answer= for signatures and code]
+```
+<!-- source: runs/brk-02-names.txt (2,231 characters, 27 entries) -->
+
+This is the list to check against the failure. Entries marked `[test]` are the tests that already reach the change: run those first. `UserResource.removeCredential` is an admin REST method, so the change reaches the admin API.
+
+### 3. When the changed code is a route, other services count too
+
+From the synthetic java-mono corpus, after a change to the `GET /api/shipments/{id}` handler:
+
+```
+niro ask get_blast_radius method_fqn=com.example.shop.shipping.ShippingMain.shipment answer=names
+
+Blast radius for ShippingMain.shipment — 3 affected functions, risk: low (upstream 3)
+upstream:
+  ShippingMain.routing (depth 1)
+  ShippingMain.main (depth 2)
+  ApacheHttpClient5Calls.shipment over HTTP (depth 1)
+```
+<!-- source: runs/xs-05-blast.txt (371 characters) -->
+
+"over HTTP" marks a caller in another service: here `main`, which calls the route by its address. `get_impact_analysis http_path=/api/shipments/{param}` gives the same list starting from the route.
+<!-- source: runs/xs-06-impact.txt -->
+
+### 4. Read only what the list points at
+
+Each full entry carries `file:start-end`, so `get_source_code` or a ranged file read opens exactly that method. Ask for `answer=locations` when you want the places without the code.
+<!-- source: runs/chg-03-impl-full.txt ("Layout: each method's line carries its <file>:<start>-<end>"); docs/answer-shapes.md -->
+
+## Why the answer is complete, and where it is not
+
+- **Every direct caller is listed, and every caller up to the depth.** The calls through an interface are followed: `SubjectCredentialManagerCacheAdapter` is reached although the tests only name `credentialManager()`, an interface.
+<!-- source: runs/brk-02-names.txt; keycloak tests/base/.../CredentialModelTest.java:56 (`user.credentialManager().createStoredCredential(otp2)`) -->
+- **Callers through a value whose type the code does not state** are counted as "Not listed" and named, so you can read them.
+<!-- source: docs/faq-wrong-or-missing-answers.md "Not listed: N call(s) ... on a receiver of unknown type" -->
+- **A method declared on a parent interface** can show fewer callers than it has, in this release. See [faq-wrong-or-missing-answers.md](faq-wrong-or-missing-answers.md).
+<!-- 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) -->
+
+## What grep would do instead
+
+- **One level costs one search per name.** `createCredentialEntity` has 2 direct callers; each of those has callers; at depth 3 there are 27 entries to find, so a grep route needs a search for each name it meets.
+- **Common names explode.** Level 3 here includes `authenticate`, `action` and `createCredential`. In Keycloak, `grep -F "authenticate("` matches 108 lines in 79 files and `grep -F "action("` 827 lines in 205 files.
+- **Interface calls do not name the class that runs.** In one of our Keycloak A/B sets, every item the shell-only agent missed was an implementation reached through an interface.
+<!-- source: grep -rn --include=*.java -F counts on Keycloak 968726fe66, 2026-11-10 ("authenticate(" 108 lines in 79 files, "action(" 827 lines in 205 files); scratchpad niro-local-receipt-recheck/NATIVE-CHOICES.md ("Every one of the 21 c4 misses is 'Implementations of <Interface>.<method>'") -->
+
+## Cost
+
+Full entries are much larger than names, so ask for names first and the full entries only where you need them. What these steps cost depends on your code and your question. How Niro counts the size of its answers, and how to measure the cost on your own tasks, is in [tokens-speed-and-accuracy.md](tokens-speed-and-accuracy.md).
+
+## Related
+
+[playbook-change-safely.md](playbook-change-safely.md) (the same check before you edit), [playbook-test-a-change.md](playbook-test-a-change.md), [playbook-review-a-change.md](playbook-review-a-change.md).

package/docs/playbook-debug-config.md

@@ -0,0 +1,95 @@
+# Playbook: debug config and environment
+
+**The question, in the user's words:** "This call works on my machine and fails in staging. Where does its address come from, which settings does this service read, and does Niro know their values?"
+
+**What you get at the end:** every setting a folder's code reads, where each is read, whether Niro has a value for it, and the lines in config files that set it, with secrets masked.
+<!-- source: outputs on this page: niro-local 43cce717 from /home/niraj/projects/github/niro-coverage-corpus/java-mono (synthetic, placeholder credentials only: niro-coverage-corpus/README.md), scratch home, 2026-11-10 (scratchpad niro-cli-task-playbooks/runs/cfg-*.txt); `niro env`, `niro ask` and `niro route-rule` pass to the engine (src/commands/engineRoutes.js:28-33) -->
+
+Words used on this page: a **setting** is a named value the code reads at run time, from an environment variable or a config file; a **base address** is the `scheme://host:port` a service is reached at.
+
+## The steps
+
+### 1. Which settings does the code read?
+
+```
+niro env list --path main
+
+  BASE_URL              http://localhost:8100  computed
+  shop.orders.base-url  no value  main/src/main/java/com/example/shop/main/http/RestTemplateCalls.java:15
+```
+<!-- source: `niro-local env list --path main` in java-mono, 2026-11-10 -->
+
+Each line is a setting, its value, and who set it ("computed" means Niro worked it out). `shop.orders.base-url` is read by `@Value("${shop.orders.base-url}")` at line 15, and Niro holds no value for it.
+<!-- source: java-mono main/.../RestTemplateCalls.java:15; `niro env --help` ("list: name, where found, value, and who set it") -->
+
+### 2. Where is it set?
+
+`code_grep` also searches config, build and deploy files, with values masked:
+
+```
+niro ask code_grep pattern="base-url" answer=locations
+
+4 matching lines in 3 files
+main/src/main/java/com/example/shop/main/http/RestTemplateCalls.java:15
+main/EXPECTED.json:112
+main/EXPECTED.json:168
+main/src/main/resources/application.yml:5
+```
+<!-- source: runs/cfg-10-key.txt (258 characters) -->
+
+Reading the config lines themselves shows the value, and masks what looks like a secret:
+
+```
+niro ask code_grep pattern="base-url|password" path_pattern=main/src/main/resources/ match_mode=regex
+
+[{"file":".../main/src/main/resources/application.yml","matches":[
+  {"line":5,"text":"    base-url: http://orders-api:8101"},
+  {"line":15,"text":"    password: <MASK_SECRET_002>"}],"truncated":false}]
+```
+<!-- source: runs/cfg-11-yml.txt; masking: docs/secrets-and-masking.md -->
+
+In this run `application.yml` sets the value, but `niro env list` still said "no value". Give Niro the value for the environment you are debugging, so its links follow that environment:
+
+```
+niro env set shop.orders.base-url=http://orders-api:8101
+niro build
+```
+<!-- source: runs/cfg-10-key.txt and `niro-local env list --path main` (2026-11-10, value in application.yml:5 not shown by env list); `niro env --help` ("set: add or change values: KEY=VALUE, repeatable"; "Passwords and tokens are refused and never stored") -->
+
+Niro refuses to store passwords and tokens: a graph needs addresses and names, not secrets.
+<!-- source: `niro-local env --help` first line ("Passwords and tokens are refused and never stored: a graph needs addresses and names.") -->
+
+### 3. Which calls have no address, or two possible targets?
+
+```
+niro route-rule unconnected
+
+5 address(es) dialled that no service here answers on:
+  http://gift-cards-api:8113: 1 call(s) from java-mono/main; no service here declares their paths
+  ...
+1 call(s) name no address in the source, and no service here declares their path.
+  java-mono/main GET /{param}
+```
+<!-- source: `niro-local route-rule unconnected` in java-mono, 2026-11-10 -->
+
+"No service here answers" means the address points outside the indexed code, or the address is wrong. "Name no address" means the URL is built from a setting or a variable Niro has no value for. The failing-call playbook shows how one rule settles a route two services declare: [playbook-debug-failing-service-call.md](playbook-debug-failing-service-call.md).
+
+## Why the answer is complete, and where it is not
+
+- **`niro env list` lists every setting the engine found the code reading.** It is the place to start, because it also says where each is read.
+- **A value can be missing even when a config file sets it,** as above. Treat "no value" as "Niro has no value", not "nothing sets it", and check with `code_grep`.
+- **Settings read through a name built at run time are not found.** The graph sees what the code states.
+<!-- source: the run above; docs/how-the-graph-works.md "What it cannot see" -->
+
+## What grep would do instead
+
+grep finds `shop.orders.base-url` too. It does not say which calls use it, whether two services answer the path, or which addresses no service answers, and it prints `password: CHANGEME` in plain text, where `code_grep` prints `<MASK_SECRET_002>`.
+<!-- source: java-mono main/src/main/resources/application.yml:15 (placeholder CHANGEME); runs/cfg-11-yml.txt -->
+
+## Cost
+
+The value of this playbook is the lists grep cannot make (unconnected calls, values Niro holds), not token savings. What these steps cost depends on your code and your question. How Niro counts the size of its answers, and how to measure the cost on your own tasks, is in [tokens-speed-and-accuracy.md](tokens-speed-and-accuracy.md).
+
+## Related
+
+[configuring-a-folder.md](configuring-a-folder.md) (env values, base address, route rules), [secrets-and-masking.md](secrets-and-masking.md), [reference-engine-commands.md](reference-engine-commands.md).