@niroai/niro 0.16.0 → 0.18.0

package/docs/playbook-debug-exception.md

@@ -0,0 +1,124 @@
+# Playbook: debug an error message or a stack trace
+
+**The question, in the user's words:** "Our server logs `Multiple users with email 'x' exist in Keycloak.` Where does that come from, what leads to it, and who catches it?"
+
+**What you get at the end:** the method that throws it, the exception type, every method that calls the thrower, and which callers catch it or turn it into an HTTP error. Every step below was run on Keycloak, a public Java project, with the release engine.
+<!-- source: every output on this page: niro-local 43cce717 (the engine niro-cli installs), run as `niro-local ask` from /home/niraj/projects/github/keycloak at 968726fe66, scratch home, 2026-11-10; `niro ask` passes the same words to the same engine command (src/commands/engineRoutes.js:28, :90-101). Saved answers: scratchpad niro-cli-task-playbooks/runs/exc-*.txt -->
+
+Words used on this page: an **exception** is an error a method throws; a **caller** is a method that calls another; a **stack trace** is the list of calls that were running when the error happened.
+
+## The steps
+
+### 1. Find the line that writes the message
+
+```
+niro ask code_grep pattern="exist in Keycloak" path_pattern=model/ answer=locations
+
+1 matching line in 1 file
+model/jpa/src/main/java/org/keycloak/models/jpa/JpaUserProvider.java:1183  org.keycloak.models.jpa.JpaUserProvider.ensureEmailConstraint_NbykxN
+[shown all 1 matching line; ask without answer= for the whole lines]
+```
+<!-- source: runs/exc-10-msg.txt (239 characters) -->
+
+`answer=locations` gives the place and the exact id of the method that holds it, which the next step takes as it is. Use the fixed part of the message ("exist in Keycloak"), not the part that changes ("x").
+
+**If you have a stack trace instead,** its top line already names the method and the line (`at ...JpaUserProvider.ensureEmailConstraint(JpaUserProvider.java:1183)`). Skip to step 2 with that name.
+
+### 2. Read only that method
+
+```
+niro ask get_source_code fqn=org.keycloak.models.jpa.JpaUserProvider.ensureEmailConstraint
+
+1177:     protected void ensureEmailConstraint(List<UserEntity> users, RealmModel realm) {
+1178:         UserEntity user = users.get(0);
+1180:         if (users.size() > 1) {
+1183:             throw new ModelDuplicateException("Multiple users with email '" + user.getEmail() + "' exist in Keycloak.");
+...
+1196:     }
+```
+<!-- source: runs/exc-09-src.txt (20 lines, 1,035 characters); the file is 1,369 lines and 63,528 characters (wc on JpaUserProvider.java) -->
+
+So the exception type is `ModelDuplicateException`, thrown when more than one user row has that email.
+
+### 3. Who calls the thrower, and does anyone catch it on the way?
+
+```
+niro ask get_exception_flow method_fqn=org.keycloak.models.jpa.JpaUserProvider.ensureEmailConstraint direction=upstream exception_type=ModelDuplicateException
+
+Callers of JpaUserProvider.ensureEmailConstraint reached while tracing ModelDuplicateException — 1 caller, 0 catch it.
+...
+  JpaUserProvider.getUserByEmail (line 704)
+```
+<!-- source: runs/exc-08-upstream.txt (764 characters) -->
+
+### 4. Who calls `getUserByEmail`?
+
+Ask for the callers as places, not as full entries:
+
+```
+niro ask get_reverse_call_chain method_fqn=org.keycloak.models.UserProvider.getUserByEmail answer=locations
+
+UserProvider.getUserByEmail has 17 callers.
+confidence: complete | has_more: false — this is the COMPLETE caller chain. Use it directly.
+services/src/main/java/org/keycloak/userprofile/validator/DuplicateEmailValidator.java:71  ...DuplicateEmailValidator.validate_NwtfyN
+services/src/main/java/org/keycloak/partialimport/UsersPartialImport.java:82  ...UsersPartialImport.userEmailExists_NuvfpN
+server-spi-private/src/main/java/org/keycloak/models/utils/KeycloakModelUtils.java:331  ...KeycloakModelUtils.findUserByNameOrEmail_Nh6f5N
+... 14 more
+[shown all 17 callers; ask without answer= for signatures and code]
+```
+<!-- source: runs/chg-07-iface-loc.txt (17 callers, 3,244 characters) -->
+
+**Ask the name the callers use.** The callers write `session.users().getUserByEmail(...)`, and `users()` returns the `UserProvider` interface. In this release, asking the JPA class (`JpaUserProvider.getUserByEmail`) answers "0 callers", because the method is declared on a parent interface of `UserProvider`. This is a known problem, see [faq-wrong-or-missing-answers.md](faq-wrong-or-missing-answers.md).
+<!-- source: runs/chg-03-impl-full.txt ("has 0 callers"), runs/chg-06-decl-count.txt; 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); keycloak server-spi/.../UserProvider.java:33-37 (extends UserLookupProvider) -->
+
+### 5. Where is it turned into an HTTP error?
+
+For a REST method you suspect, ask what escapes it and what it catches:
+
+```
+niro ask get_exception_flow method_fqn=org.keycloak.services.resources.admin.UsersResource.createUser
+
+Exceptions escaping UsersResource.createUser - 3 types, 2 swallow candidates, 6 wrapped.
+...
+Wrapped (caught and thrown on as a new exception of another type ...):
+  ModelDuplicateException
+      caught at UsersResource.createUser
+...
+requires_runtime: yes - treat the escaping set as "at least these", never as "exactly these".
+```
+<!-- source: runs/exc-04-flow.txt (3,682 characters) -->
+
+The code at that catch is `throw ErrorResponse.exists("User exists with same username or email");`, which a `code_grep` for the message confirms at `UsersResource.java:180`.
+<!-- source: runs/exc-02-grep-loc.txt (UsersResource.java:180 createUser); keycloak services/.../UsersResource.java:179-180 -->
+
+## Why the answer is complete, and where it is not
+
+- **The caller lists are complete for calls the code states.** "confidence: complete" means every call to that name in indexed code was placed. Calls made through reflection or built at run time are not in any list.
+<!-- source: docs/how-the-graph-works.md "What it cannot see"; niro-local src/niro_local/mcp/chains.py:1945-1947 -->
+- **The exception list is a floor, and says so.** It sees `throw new` and declared `throws` in your code. It does not see what a library throws, so the answer says "requires_runtime: yes".
+<!-- source: runs/exc-04-flow.txt ("scope: declared throws plus `throw new` ... which is a FLOOR") -->
+- **The graph calls in steps 3, 4 and 5 give the same answer every time** on the same graph, because they are read from it, not guessed. The `code_grep` check of the catch line in step 5 is a text search with a time limit, so on a busy machine follow its `continue_from`. A few answers can change between two builds of the same code (a known problem).
+- **The text search in step 1 can stop early on a busy machine.** `code_grep` has a time limit, and then says PARTIAL with a `continue_from` to carry on. Follow it before you decide a message is not in the code.
+<!-- source: 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) -->
+<!-- source: docs/faq-wrong-or-missing-answers.md "Answers changed between two builds of the same code" (niro-local docs/NIRO-LOCAL-ISSUES.md entry "2026-10-30, three answers change between two builds of the same code", OPEN) -->
+
+## What grep and file reads would do instead
+
+| Step | With grep | What it misses or costs |
+|---|---|---|
+| 1 | `grep -rn "exist in Keycloak"` finds the line too | nothing: a plain text search is the right tool here |
+| 3 to 4 | `grep -rn "getUserByEmail("` gives 46 lines in 35 files | at least 15 of those lines are other classes' own `getUserByEmail` methods, not calls. grep cannot tell which `getUserByEmail` a call reaches, because the call site names only `session.users()` |
+| 5 | `grep -rn "catch (ModelDuplicateException"` gives 34 lines in 29 files | it cannot say which of them are on the path from the thrower, so each must be read |
+<!-- source: grep counts on Keycloak 968726fe66, 2026-11-10: `grep -rn --include=*.java "getUserByEmail(" .` 46 lines (35 files); `"public UserModel getUserByEmail("` 15 lines; `"catch (ModelDuplicateException"` 34 lines in 29 files -->
+
+**An everyday comparison:** grep is like searching a phone book for everyone called "Smith". The graph is like asking the exchange who actually rang this number.
+
+## 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
+
+- Exceptions in general, and the `get_exception_flow` limits: [lifecycle-debug.md](lifecycle-debug.md).
+- Asking for short answers: [answer-shapes.md](answer-shapes.md).
+- Other debugging playbooks: [a wrong value](playbook-debug-wrong-value.md), [a failing call between services](playbook-debug-failing-service-call.md), [it broke after my change](playbook-debug-after-a-change.md), [config and environment](playbook-debug-config.md), [a slow path](playbook-debug-slow-path.md).

package/docs/playbook-debug-failing-service-call.md

@@ -0,0 +1,119 @@
+# Playbook: debug a failing call between services
+
+**The question, in the user's words:** "The POST to `/api/shipments` from our main service is failing. Which code makes the call, which service is meant to answer it, and why does Niro think so?"
+
+**What you get at the end:** the calling method, the service folder and method that handle the route, and what in the repository ties the address to that folder. Then, for a call that two services could answer, how to settle which one.
+<!-- source: every output on this page: niro-local 43cce717, run as `niro-local ask` from /home/niraj/projects/github/niro-coverage-corpus/java-mono, scratch home, 2026-11-10 (scratchpad niro-cli-task-playbooks/runs/xs-*.txt); the corpus is synthetic (niro-coverage-corpus/README.md); `niro ask` runs the same engine command (src/commands/engineRoutes.js:28) -->
+
+Words used on this page: a **route** is a web address a service answers, such as `POST /api/shipments`; a **handler** is the method that answers it; an **outbound call** is a call your code makes to another service's route.
+
+## The steps
+
+### 1. Find the call
+
+```
+niro ask find_outbound_http_calls path_pattern=/api/shipments
+
+Found 2 outbound HTTP calls matching '/api/shipments'.
+1. POST /api/shipments -> com.example.shop.shipping.ShippingMain.a_f_Ng3hlN
+   caller: ApacheHttpClient5Calls.createShipment
+   source: .../java-mono/main/src/main/java/com/example/shop/main/http/ApacheHttpClient5Calls.java
+2. GET /api/shipments/{param} -> com.example.shop.shipping.ShippingMain.shipment_Np2ojN
+   caller: ApacheHttpClient5Calls.shipment
+confidence: complete - this is the COMPLETE list.
+```
+<!-- source: runs/xs-02-out.txt (651 characters) -->
+
+Each line already says where the call lands. `a_f_...` is a function written in place: here a lambda, `(req, res) -> res.status(201).send()`.
+<!-- source: java-mono services/helidon-se/.../ShippingMain.java:19-20 -->
+
+### 2. Who answers it?
+
+```
+niro ask find_handler fqn=ApacheHttpClient5Calls.createShipment
+
+Found 1 handler for 'ApacheHttpClient5Calls.createShipment'.
+confidence: complete | has_more: false — this is the complete list.
+1. ShippingMain.a_f [helidon-se]
+   source: services/helidon-se/src/main/java/com/example/shop/shipping/ShippingMain.java
+```
+<!-- source: runs/xs-04-handler.txt (254 characters) -->
+
+### 3. Why that service?
+
+The caller dials `http://shipping-api:8109/api/shipments`. Nothing in the Java code says that `shipping-api` is the `helidon-se` folder. The deploy file does:
+
+```
+# docker-compose.yml
+  shipping-api:
+    build: ./services/helidon-se
+    ports: ["8109:8109"]
+```
+<!-- source: java-mono main/.../ApacheHttpClient5Calls.java:19; java-mono docker-compose.yml:45-47 -->
+
+Niro reads deploy files like this one to give each folder its address, then joins the call to the route. See [configuring-a-folder.md](configuring-a-folder.md) to set an address by hand.
+<!-- source: docs/configuring-a-folder.md (base address); niro-local src/niro_local/modules/compose_address.py:1-3 ("The address a compose file gives a module: `http://<service name>:<container port>`") -->
+
+### 4. The whole map, when you do not know where to start
+
+```
+niro ask get_service_topology
+
+18 link(s) between parts of this project:
+  main -> helidon-se  (2 route(s))
+      GET /api/shipments/{param}
+      POST /api/shipments
+  main -> javalin  (3 route(s))
+      GET /api/stock/{param}   (not confirmed)
+      ...
+```
+<!-- source: runs/xs-01-topo.txt (2,624 characters) -->
+
+### 5. When two services declare the same route
+
+"(not confirmed)" means the call was matched by its path alone, and more than one service declares that path. The engine lists every such call and the command that settles it:
+
+```
+niro route-rule unconnected
+
+1 call(s) joined only as candidates: more than one route could be meant ...
+  java-mono/main GET /api/stock/{param}: 2 services declare it (java-mono/services/javalin, java-mono/services/sparkjava)
+      niro-local route-rule add '/api/stock/{param}' --from java-mono/main --to java-mono/services/javalin
+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
+  ...
+```
+<!-- source: `niro-local route-rule unconnected` in java-mono, 2026-11-10 (run before the rule below was added); `niro route-rule` passes to the engine (src/commands/engineRoutes.js:32) -->
+
+Before the rule, `StockRetrofitApi.stock` was listed twice, once for each service, both "(one of several routes with this path, not confirmed)". After `niro route-rule add ...` and `niro build`, it is listed once, to the service named:
+
+```
+Before:  4. GET /api/stock/{param} -> ...stockspark.StockSparkApp.a_f_N657yN  (one of several routes with this path, not confirmed)
+         5. GET /api/stock/{param} -> ...stock.StockApp.a_f_Nes1yN  (one of several routes with this path, not confirmed)
+After:   3. GET /api/stock/{param} -> com.example.shop.stock.StockApp.a_f_Nes1yN
+```
+<!-- source: runs/xs-10-before.txt and runs/xs-11-after.txt (find_outbound_http_calls path_pattern=/api/stock), 2026-11-10; the rule was saved with "1 rule(s) saved. The next `niro-local build` applies them, with no reindexing." -->
+
+**"No service here answers"** usually means the service lives in another repository that is not indexed, or its address is wrong. Check the address with `niro base-url` in the service's folder.
+<!-- source: docs/configuring-a-folder.md; src/commands/engineRoutes.js:31 (base-url) -->
+
+## Why the answer is deterministic
+
+The link between a call and a handler comes from three things Niro read: the call's method and path, the route a framework declares, and the address of each folder. The same files always give the same links. Where the path alone matched and two routes fit, the answer says "not confirmed" and keeps it out of the risk counts, rather than guessing.
+<!-- source: docs/how-the-graph-works.md ("inferred, target unconfirmed" is listed separately and not counted in the risk); runs/xs-01-topo.txt note on 'not confirmed' -->
+
+## What grep would do instead
+
+- **grep finds the caller's URL string,** `http://shipping-api:8109/api/shipments`: the host name is in 3 lines, all in one file of main (two calls and a comment).
+- **It does not find the handler by that string.** The handler file has only `"/api/shipments"` next to a lambda, and the host name `shipping-api` is in the compose file, not in any Java file of helidon-se. So the agent has to read the compose file and match the name itself. An agent using Niro can miss that line too, so when a call names a host, check the compose file as well.
+- **It cannot tell which of two services answers `/api/stock/{id}`.** Both declare it; only an address or a rule settles it.
+- **For routes declared by folder names it finds nothing.** In the TypeScript corpus, `GET /api/bookings/{param}` comes from the folder path `src/app/api/bookings/[bookingId]/route.ts`. `grep -rn "api/bookings"` finds 0 lines; `find_api_endpoints path_pattern=/api/bookings` finds 2 routes.
+<!-- source: `grep -rn "shipping-api" java-mono --include=*.java` = 3 lines, all in main/.../ApacheHttpClient5Calls.java (:10 comment, :15, :19); docker-compose.yml:45; `grep -rn "api/bookings" typescript-mono --include=*.ts --include=*.tsx` = 0 lines; runs/ts-01-routes.txt (2 endpoints), typescript-mono built 2026-11-10 -->
+
+## 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-config.md](playbook-debug-config.md) (addresses that come from configuration), [playbook-onboard.md](playbook-onboard.md).

package/docs/playbook-debug-slow-path.md

@@ -0,0 +1,80 @@
+# Playbook: debug a slow path
+
+**The question, in the user's words:** "Adding a credential to a user is slow. What does that code do, and where does it go to the database?"
+
+**What you get at the end:** what the slow method calls, a few levels down, which of those touch a data store, and the few methods worth reading. Niro does not time anything: it tells you where to look, and a profiler tells you how long it takes.
+<!-- 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/slow-*.txt, data-02-usage.txt, exc-09-src.txt); `niro ask` runs the same engine command (src/commands/engineRoutes.js:28) -->
+
+Words used on this page:
+- a **callee** is a method that another method calls;
+- a **profiler** is a tool that measures where a running program spends its time;
+- a **named query** is a database query written once on a JPA entity class and run by its name (JPA is Java's standard library that maps classes to tables).
+
+## The steps
+
+### 1. How much does the method reach?
+
+```
+niro ask get_call_chain method_fqn=org.keycloak.models.jpa.JpaUserCredentialStore.createCredentialEntity direction=callees scope=transitive transitive_depth=2 answer=count
+
+18 callees
+confidence: complete | has_more: false — this is the COMPLETE call chain. Use it directly.
+```
+<!-- source: runs/slow-01-count.txt (152 characters) -->
+
+### 2. Which callees, and where is each called?
+
+The full answer gives the line of every call, which matters for a slow path: a call inside a loop, or the same query twice.
+
+```
+niro ask get_call_chain method_fqn=org.keycloak.models.jpa.JpaUserCredentialStore.createCredentialEntity direction=callees
+
+JpaUserCredentialStore.createCredentialEntity has 17 callees.
+  1. JpaUserCredentialStore.validateDuplicateCredential(RealmModel, UserModel, String, String, String) (line 147) private — called at line 162 — .../JpaUserCredentialStore.java:147-159
+  ...
+  16. JpaUserCredentialStore.getStoredCredentialEntities(RealmModel, UserModel) (line 123) private — called at line 175 — .../JpaUserCredentialStore.java:123-128
+  17. CredentialEntity.setPriority(int) (line 144) public — called at line 177 — ...
+```
+<!-- source: runs/slow-03-full.txt (3,890 characters) -->
+
+Most of the 17 are getters and setters. Two are worth reading: `validateDuplicateCredential` and `getStoredCredentialEntities`.
+
+### 3. Read the two, and only the two
+
+```
+niro ask get_source_code fqn=org.keycloak.models.jpa.JpaUserCredentialStore.getStoredCredentialEntities
+```
+
+`getStoredCredentialEntities` runs the named query `credentialByUser`, which loads every credential of the user. `validateDuplicateCredential` calls it when the new credential has a label (line 149), and `createCredentialEntity` calls it again at line 175 to work out the priority. So adding a labelled credential loads the user's whole credential list twice.
+<!-- source: keycloak model/jpa/.../JpaUserCredentialStore.java:123-128 (createNamedQuery("credentialByUser")), :147-159 (validateDuplicateCredential calls getStoredCredentialEntities at :149), :175; runs/slow-03-full.txt (called at line 175) -->
+
+That is a lead, not a measurement. Confirm it with a profiler, or by logging the SQL the query runs.
+
+### 4. Which stores does the path touch?
+
+```
+niro ask get_data_resource_usage resource_fqn=CREDENTIAL
+```
+
+In this release the answer lists the `em.persist` and `em.find` calls but not the named query, so `getStoredCredentialEntities` is missing from its readers. That is a known gap; step 3 found the read by reading the method.
+<!-- source: runs/data-02-usage.txt (no getStoredCredentialEntities); 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) -->
+
+## Why the answer is complete, and where it is not
+
+- **The callee list is complete for calls the code states,** with the line of each call. Library calls (`em.persist`) are not listed as callees of your code, because the library is not indexed.
+- **Niro holds no timings.** A slow path found here is a place to measure, not a measured fact.
+- **The `answer=names` form of a deeper walk can show a direct callee at depth 2** when another direct callee also calls it (a known display problem). The count is right; use the full answer when the depth matters.
+<!-- source: runs/slow-02-names.txt (getStoredCredentialEntities "(depth 2)") against runs/slow-03-full.txt ("called at line 175", a direct callee); 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) -->
+
+## What grep would do instead
+
+To list what a method calls, grep has nothing to search for: the callees are inside the method. The by-hand route is to read the method, then each method it calls. Here that is the 21-line method plus two private methods in the same file, which is cheap. The graph pays off when the path crosses files and interfaces, as in [playbook-change-safely.md](playbook-change-safely.md).
+<!-- source: runs/slow-03-full.txt (createCredentialEntity :161-181, validateDuplicateCredential :147-159, getStoredCredentialEntities :123-128, all in one file) -->
+
+## Cost
+
+For a short method, reading the whole method by hand can cost less than asking Niro. This playbook is about finding the methods worth a closer look, not about tokens. 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-data-and-events.md](playbook-data-and-events.md).

package/docs/playbook-debug-wrong-value.md

@@ -0,0 +1,137 @@
+# Playbook: debug a wrong value
+
+**The question, in the user's words:** "A user's credentials come back in the wrong order. The `PRIORITY` column of the `CREDENTIAL` table looks wrong. What writes it?"
+
+**What you get at the end:** every method that reads, writes or deletes the table, the methods that set the field, and the routes and callers that reach them. Then, for a value that arrives as a message, who publishes it and who handles it.
+<!-- source: every Keycloak output on this page: niro-local 43cce717, run as `niro-local ask` from /home/niraj/projects/github/keycloak at 968726fe66, scratch home, 2026-11-10 (scratchpad niro-cli-task-playbooks/runs/data-*.txt, wv-*.txt); `niro ask` runs the same engine command (src/commands/engineRoutes.js:28) -->
+
+Words used on this page:
+- a **data store** is a table, collection, cache or queue;
+- an **ORM** is a library that maps classes to tables, so the code saves an object and never writes the table's name;
+- **JPA** is Java's standard ORM, and its **EntityManager** is the object code calls to load, save and delete rows (`em.find`, `em.persist`, `em.remove`);
+- a **loaded entity** is an object JPA has read from a row: changing its fields changes the row when the **transaction** (the unit of work JPA saves in one go) ends, with no further call;
+- a **named query** is a query written once on the entity class and run by its name (`em.createNamedQuery("credentialByUser", ...)`).
+
+## The steps
+
+### 1. Which stores does the code use?
+
+```
+niro ask list_data_resources limit=15
+
+67 data resource(s):
+  sql          table       USER_ENTITY                  20 use(s)
+  sql          table       REALM                        10 use(s)
+  ...
+  sql          table       CREDENTIAL                   7 use(s)
+```
+<!-- source: runs/data-01-list.txt -->
+
+### 2. Who reads, writes and deletes that table?
+
+```
+niro ask get_data_resource_usage resource_fqn=CREDENTIAL
+
+sql:table:CREDENTIAL
+  read by (5):
+    JpaUserCredentialStore.getStoredCredentialById
+    JpaUserCredentialStore.removeCredentialEntity
+    JpaUserCredentialStore.updateCredential
+    CredentialModelTest.testCredentialUpdateWithDuplicateLabel
+    PasswordHashingTest.testPasswordRehashedOnAlgorithmChangedWithMigratedSalt
+  written by (1):
+    JpaUserCredentialStore.createCredentialEntity
+  deleted by (1):
+    JpaUserCredentialStore.removeCredentialEntity
+```
+<!-- source: runs/data-02-usage.txt (460 characters) -->
+
+The listed write is `em.persist(entity)` on a `CredentialEntity`, and the table name appears only once in the code, in `@Table(name="CREDENTIAL")` on the entity class. Niro joins the two.
+
+**This list is not complete, and here is what it leaves out.** The answer key for this same question (A/B task p-04) has four methods that write the table, and step 2 shows one insert and one delete:
+- `updateCredential` loads a row with `em.find` and changes its fields, so it writes the row; Niro lists it only under "read by".
+- `moveCredentialTo` changes the priority of rows it loaded earlier, and is not listed at all.
+- `getStoredCredentialEntities` reads the table through a named query, and is not listed either.
+
+Both kinds of gap are known problems in this release: see [faq-wrong-or-missing-answers.md](faq-wrong-or-missing-answers.md). Use step 3 to find them.
+<!-- source: keycloak model/jpa/.../JpaUserCredentialStore.java:179 (em.persist), :63-75 (updateCredential: em.find then setters), :245 (moveCredentialTo sets priority), :123-128 (getStoredCredentialEntities, createNamedQuery); model/jpa/.../entities/CredentialEntity.java:43 (@Table); scratchpad niro-cli-task-playbooks/ab/tasks.yaml p-04 (4 writers); 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) -->
+
+### 3. Who sets the field?
+
+The graph records which methods touch a table, not which fields they change. So search for the setter, and ask for the methods that hold it:
+<!-- source: niro-local server instructions: "SQL no query call runs, config and reads or writes of a field are not" (src/niro_local/mcp/server.py, the instructions text) -->
+
+```
+niro ask code_grep pattern="setPriority(" path_pattern=model/jpa/ answer=names
+
+18 matching lines in 9 files
+JpaUserCredentialStore.createCredentialEntity(RealmModel, UserModel, CredentialModel)
+JpaUserCredentialStore.removeCredentialEntity(RealmModel, UserModel, String)
+JpaUserCredentialStore.moveCredentialTo(RealmModel, UserModel, String, String)
+RealmAdapter.entityToModel(AuthenticationExecutionEntity)
+...
+[shown 17 names from the first 5 hits a file; raise max_matches_per_file (up to 50) for more hits a file]
+```
+<!-- source: runs/wv-01-setprio.txt (1,424 characters) -->
+
+Three methods of `JpaUserCredentialStore` set a credential's priority. `moveCredentialTo` is not in step 2's list, and `updateCredential` is listed only as a reader. Both change loaded entities, and the database update happens when the transaction ends. That kind of write has no call Niro can see.
+<!-- source: runs/data-02-usage.txt (moveCredentialTo absent, updateCredential under read by); keycloak JpaUserCredentialStore.java:63-75, (credential.setPriority(expectedPriority) inside moveCredentialTo) -->
+
+### 4. What reaches the suspect method?
+
+```
+niro ask get_impact_analysis method_fqn=org.keycloak.models.jpa.JpaUserCredentialStore.moveCredentialTo depth=5 answer=names
+
+Impact analysis for JpaUserCredentialStore.moveCredentialTo — 5 affected functions, risk: medium (+2 in tests, not counted in risk) (upstream 7)
+upstream:
+  JpaUserProvider.moveCredentialTo (depth 1)
+  UserCredentialManager.moveStoredCredentialTo (depth 2)
+  SubjectCredentialManagerCacheAdapter.moveStoredCredentialTo (depth 3)
+  UserResource.moveCredentialAfter (depth 4)
+  UserResource.moveCredentialToFirst (depth 5)
+  CredentialModelTest.testCredentialCRUD [test] (depth 4)
+  UserStorageTest.testCredentialCRUD [test] (depth 4)
+```
+<!-- source: runs/wv-03-impact.txt (1,058 characters) -->
+
+So the admin REST methods `UserResource.moveCredentialAfter` and `moveCredentialToFirst` reorder credentials, and two existing tests already reach the code. The path goes through `SubjectCredentialManagerCacheAdapter`, a class that implements an interface: the call site names only the interface.
+
+### 5. When the value arrives as a message
+
+If the wrong value comes from another service, ask who sends and who receives it. From the synthetic java-mono corpus (68 small Java services and a `main` that calls them):
+<!-- source: /home/niraj/projects/github/niro-coverage-corpus/README.md (synthetic code, made-up names); java-mono built with niro-local 43cce717, 2026-11-10 -->
+
+```
+niro ask get_event_producers_and_handlers name=price-changes
+
+redis-pubsub:price-changes   [jedis]
+  published by (1):
+      BrokerClients.priceChanged
+  handled by (1):
+      PriceWatch.listen
+```
+<!-- source: runs/wv-10-ev.txt -->
+
+Then `get_blast_radius event_fqn=price-changes answer=names` lists what the handler goes on to call. For events in general, see [playbook-data-and-events.md](playbook-data-and-events.md).
+<!-- source: runs/wv-11-evblast.txt -->
+
+## Why the answer is complete, and where it is not
+
+- **Step 2 lists the calls Niro recognises** (here `em.persist`, `em.find` and `em.remove`), including access through an ORM where the table is never named. It is not complete: writes made by changing a loaded entity, and reads through a named query, are missing in this release.
+- **It does not hold field writes, or SQL that no call runs.** Step 3 fills the field gap with a text search, which is the right tool for a setter name.
+- **An event's two sides are matched by the topic name.** A consumer in a form Niro does not read yet is missing. See the known gaps in [faq-wrong-or-missing-answers.md](faq-wrong-or-missing-answers.md).
+<!-- source: niro-local server instructions (tables reached through a recognised data-access library are in the graph; field reads and writes are not); docs/how-the-graph-works.md -->
+
+## What grep would do instead
+
+- **Searching for the table name finds one line:** `grep -rnw CREDENTIAL --include=*.java` in Keycloak prints only the `@Table` annotation. Every read and write goes through `em.persist`, `em.find` and named queries on the entity class.
+- **Searching for the entity class finds 13 files,** and grep cannot tell which of them write and which only read.
+<!-- source: `grep -rn --include=*.java -w "CREDENTIAL" .` = 1 line (CredentialEntity.java:43); `grep -rln --include=*.java "CredentialEntity" .` = 13 files (Keycloak 968726fe66, 2026-11-10) -->
+
+## 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-exception.md](playbook-debug-exception.md), [playbook-data-and-events.md](playbook-data-and-events.md), [answer-shapes.md](answer-shapes.md).

package/docs/playbook-onboard.md

@@ -0,0 +1,95 @@
+# Playbook: learn a new codebase
+
+**The question, in the user's words:** "I am new to this repository. What services are in it, how do they talk to each other, what routes do they serve, and what do they store?"
+
+**What you get at the end:** the shape of the repository in a handful of answers, each small, before you open a file. Then the one or two areas to read, chosen from those answers.
+<!-- source: Keycloak outputs: niro-local 43cce717 from /home/niraj/projects/github/keycloak at 968726fe66; java-mono outputs from /home/niraj/projects/github/niro-coverage-corpus/java-mono (synthetic); scratch home, 2026-11-10 (scratchpad niro-cli-task-playbooks/runs/onb-*.txt, xs-01-topo.txt, data-01-list.txt, de-01-events.txt) -->
+
+In recorded agent sessions (these recordings are mostly Niro's own development, labelled by hand by one agent, about plus or minus 10%), understanding existing code was the most common use of Niro: 329 of 794 calls (41%), almost all of them `code_grep` (207) and `get_source_code` (93). The structure tools below were rarely used, although they answer the first questions with less reading.
+<!-- source: scratchpad niro-cli-task-playbooks/TASKS.md (hand labels of 794 recorded calls, about plus or minus 10%) -->
+
+## The steps
+
+### 1. How is the repository split?
+
+```
+niro modules
+
+/home/niraj/projects/github/keycloak holds 51 modules:
+   0.6  dockerfile           .
+   0.5  entrypoint           authz/policy/common
+   0.9  depended_on_library  authzen/services
+   ...
+```
+<!-- source: `niro-local modules` in Keycloak, 2026-11-10 (51 modules); `niro modules` passes to the engine (src/commands/engineRoutes.js:33) -->
+
+Each line is a folder Niro treats as its own unit, and the kind of signal that made it one: here a Dockerfile, a runnable entry point, or a library other modules depend on.
+
+### 2. Which service calls which?
+
+```
+niro ask get_service_topology
+
+18 link(s) between parts of this project:
+  main -> armeria  (3 route(s))
+      GET /api/prices/{param}
+      POST /api/prices/recalculate
+      POST /shop.pricing.v1.PricingDesk/Quote (grpc)
+  main -> helidon-se  (2 route(s))
+  ...
+```
+<!-- source: runs/xs-01-topo.txt (java-mono, 2,624 characters) -->
+
+Keycloak is mostly one server, and its topology has one link, from a test. That is an answer too: there is little to learn here about calls between services.
+<!-- source: runs/onb-01-topo.txt ("1 link(s) between parts of this project, 1 only from tests") -->
+
+### 3. What does it serve?
+
+```
+niro ask find_api_endpoints limit=10
+Found 938 HTTP endpoints.
+```
+
+Narrow it with `path_pattern=/admin` or `service_filter=<folder>`. In Keycloak, 938 routes is too many to read: pick the area you will work on.
+<!-- source: runs/onb-02-ep.txt (Keycloak, "Found 938 HTTP endpoints."); docs/reference-mcp-tools.md (find_api_endpoints inputs) -->
+
+### 4. What does it store, and what messages does it send?
+
+```
+niro ask list_data_resources limit=15     # Keycloak: 67 stores, USER_ENTITY used 20 times, REALM 10, ...
+niro ask list_events limit=12             # java-mono: 34 events, with how many publish and handle each
+```
+<!-- source: runs/data-01-list.txt (67 data resources); runs/de-01-events.txt (34 events) -->
+
+### 5. What types are there?
+
+```
+niro ask list_types limit=50
+11220 type(s):
+```
+
+Use it to find a class by name. For one class, `get_class_structure answer=count` gives its size and how many subtypes it has.
+<!-- source: `niro-local ask list_types limit=3` in Keycloak ("11220 type(s):"), 2026-11-10; runs/feat-01-count.txt -->
+
+### 6. See it in a browser
+
+`niro ui` draws the graph on a page served only on this computer. See [lifecycle-onboarding.md](lifecycle-onboarding.md).
+
+## Why the answer is trustworthy, and where it is not
+
+- **Modules, routes, stores and events come from the code and its build and deploy files,** read by tables of known frameworks and libraries. A framework Niro has no table for is missing from these lists. See [supported-overview.md](supported-overview.md).
+- **If services are joined wrongly,** tell Niro where they live: [configuring-a-folder.md](configuring-a-folder.md).
+<!-- source: docs/how-the-graph-works.md ("It recognises routes, outbound calls, data access and events from tables of known libraries and frameworks") -->
+
+## What grep would do instead
+
+grep can list files, but it has no idea of a service, a route declared by a folder name, or a store reached through an ORM. For example, in the TypeScript corpus `find_api_endpoints path_pattern=/api/bookings` finds 2 routes declared only by folder names, where `grep -rn "api/bookings"` finds 0 lines.
+<!-- source: runs/ts-01-routes.txt; `grep -rn "api/bookings" typescript-mono --include=*.ts --include=*.tsx` = 0 lines (2026-11-10) -->
+
+## 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
+
+[lifecycle-onboarding.md](lifecycle-onboarding.md), [how-the-graph-works.md](how-the-graph-works.md), [playbook-data-and-events.md](playbook-data-and-events.md).

package/docs/playbook-review-a-change.md

@@ -0,0 +1,72 @@
+# Playbook: review a change
+
+**The question, in the user's words:** "This branch changes two credential methods. Before I approve it: what does it reach, which routes and services are affected, and is it tested?"
+
+**What you get at the end:** for the changed methods together, the size of the change, its callers by name, the routes and other services on the way, and the tests that reach it. Run it from the branch's own folder: a new branch of an indexed folder gets its own copy of the graph.
+<!-- source: Keycloak outputs: 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); docs/worktrees-and-branches.md (temporary projects); `niro ask` runs the same engine command (src/commands/engineRoutes.js:28) -->
+
+## The steps
+
+### 1. List the changed methods, from the diff
+
+Take the method names from `git diff --stat` and the diff itself. Niro does not read git history; it answers about the code as it is on disk.
+<!-- source: niro-local CLAUDE.md ("There is no git access at all: change detection reads the filesystem") -->
+
+### 2. One call for the whole change, then the names
+
+```
+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)
+```
+
+```
+niro ask get_blast_radius method_fqns='[...same two...]' direction=upstream answer=names
+
+upstream:
+  ...
+  PasswordCredentialProvider.deleteCredential (depth 3)
+  UserResource.removeCredential (depth 3)
+  CredentialModelTest.testCredentialCRUD [test] (depth 3)
+  ...
+[shown all 27 entries; ask without answer= for signatures and code]
+```
+<!-- source: runs/brk-01-multi.txt, runs/brk-02-names.txt -->
+
+What to look for in review: a REST method on the list (`UserResource.removeCredential` is the admin API), entries marked "over HTTP" (another service calls it), and whether `[test]` entries cover both changed methods. Here the six tests sit on the `createCredentialEntity` side (two of them reach it only in the code as written, not at run time: see [playbook-test-a-change.md](playbook-test-a-change.md)). For the other method, ask it alone one level further: `get_reverse_call_chain method_fqn=...removeCredentialEntity depth=4 answer=locations` lists 3 tests at depth 4, among them `CredentialModelTest.testCredentialCRUD`. The same run-time check applies: the third, at `UserStorageTest.java:1017`, is inside `UserStorageTest.testCredentialCRUD`, which uses the federated user, so at run time it does not reach this method either.
+<!-- source: runs/brk-02-names.txt; runs/rev-01-remove.txt (3 [test] callers at depth 4: CredentialModelTest.java:136, :205, UserStorageTest.java:1017); keycloak UserStorageTest.java:914 (testCredentialCRUD starts), :923-924 (thor, not local storage) -->
+
+### 3. Did a route change?
+
+Compare the routes of the branch with the main branch, each from its own folder:
+
+```
+niro ask find_api_endpoints path_pattern=/credentials
+```
+
+Run it in both folders and compare the two lists. A route that disappears is a breaking change for every caller.
+<!-- source: docs/lifecycle-review.md ("Whether a route was removed or changed: find_api_endpoints, compared with the main branch's folder") -->
+
+### 4. Did a call to another service change?
+
+`find_outbound_http_calls` in both folders, compared the same way. For a monorepo, `get_service_topology` shows the links between its services.
+<!-- source: docs/lifecycle-review.md; runs/xs-01-topo.txt -->
+
+## Why the answer is deterministic
+
+The reviewer and the author get the same list for the same code, because it is read from the graph rather than from whatever each of them thought to search. The answer says when it stopped at a depth, and how many entries were cut there.
+<!-- source: runs/brk-01-multi.txt ("22 node(s) marked '[+N more beyond depth]'") -->
+
+## What it does not do
+
+- **It is not a pull request review product.** Automatic review is hosted Niro only, and review bots cannot reach the local engine. See [connect-review-bots.md](connect-review-bots.md) and [hosted-only.md](hosted-only.md).
+- **It does not judge whether the change is right,** only what it reaches.
+<!-- source: docs/lifecycle-review.md ("Review bots ... cannot use the local graph in this release"; "Automatic pull request review is a hosted Niro feature") -->
+
+## 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
+
+[lifecycle-review.md](lifecycle-review.md), [playbook-debug-after-a-change.md](playbook-debug-after-a-change.md), [playbook-test-a-change.md](playbook-test-a-change.md).