@zenera/cli 1.1.6 → 1.1.9

package/dist/commands/index.js

@@ -48,8 +48,8 @@ export const EXTERNAL = {
     },
     rag: {
         package: '@zenera/rag',
-        summary: 'Search an openapi/swagger document as a graph.',
-        usage: 'zen rag schema <index|search|list|grep|show|stats> [spec...]',
+        summary: 'Retrieval over a corpus: index it, then ask it something.',
+        usage: 'zen rag <subject> <command> [args...]',
         install: 'npm i -g @zenera/rag',
         banner: { head: 'Zenera', accent: 'Rag', subtitle: 'Api Retrieval' },
     },

package/dist/podman.d.ts

@@ -34,15 +34,6 @@ export interface PodmanStatus {
     imagePresent?: boolean;
 }
 export declare function ensurePodmanReady(opts?: PodmanOptions): Promise<void>;
-/**
- * Builds the project's Dockerfile under its tag.
- *
- * Run every time rather than skipped when the tag already exists, because the
- * tag is a hash of the Dockerfile and its context and the engine's layer cache
- * is a hash of the same thing plus the base image. Asking it is cheap, and it
- * is the only thing that notices when `FROM node:24` starts meaning a different
- * node:24.
- */
 /**
  * A build that ran and failed, rather than a host that could not be asked.
  *

package/dist/podman.js

@@ -167,15 +167,6 @@ function parseMachines(stdout) {
 // ---------------------------------------------------------------------------
 // The image
 // ---------------------------------------------------------------------------
-/**
- * Builds the project's Dockerfile under its tag.
- *
- * Run every time rather than skipped when the tag already exists, because the
- * tag is a hash of the Dockerfile and its context and the engine's layer cache
- * is a hash of the same thing plus the base image. Asking it is cheap, and it
- * is the only thing that notices when `FROM node:24` starts meaning a different
- * node:24.
- */
 /**
  * A build that ran and failed, rather than a host that could not be asked.
  *
@@ -204,7 +195,9 @@ async function build(engine, spec, run, force = false) {
             return;
         }
     }
-    note(dim(`building ${spec.tag} from ${spec.dockerfile}`));
+    note(dim(`${force ? 'rebuilding' : 'building'} the sandbox image from ${spec.dockerfile}`));
+    note(dim('  the agent runs its commands inside a container, so the image is needed first'));
+    note(dim('  this takes a few minutes; later runs reuse it until the Dockerfile changes'));
     const built = await stream(engine, ['build', '--tag', spec.tag, '--file', spec.dockerfile, spec.context], run, BUILD_MS);
     if (built.code !== 0) {
         throw new BuildError(`could not build ${spec.dockerfile}`, EXIT.sandbox, last(built) || 'run the build by hand to see what the engine says');

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.6",
+    "version": "1.1.9",
     "description": "Command-line front end for @zenera/neo: agentic projects you can run, share and commit.",
     "keywords": [
         "agents",
@@ -51,7 +51,7 @@
         "@inkjs/ui": "^2.0.0",
         "ink": "^7.1.1",
         "react": "^19.2.8",
-        "@zenera/neo": "^1.1.6",
+        "@zenera/neo": "^1.1.9",
         "@anthropic-ai/sdk": "^0.120.0",
         "@google/genai": "^2.18.0",
         "@openrouter/sdk": "^1.2.80",

package/templates/editor/.github/skills/api-schema-index/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: api-schema-index
-description: What a schema index is, how it finds the right call inside a large OpenAPI/Swagger document, and how to build and query one with `zen rag schema` (or `npx @zenera/cli`) — searching it by meaning, listing and grepping it exactly instead of reaching for shell `grep`/`rg`, and giving it to an agent as tools.
+description: What a schema index is, how it finds the right call inside a large OpenAPI/Swagger document, and how to build and query one with `zen rag schema` (or `npx @zenera/cli`) — searching it by meaning, listing and grepping it exactly instead of reaching for shell `grep`/`rg`, tracing a field up to the operations that carry it, giving it to an agent as tools, and writing the project skill that a wired-in index requires.
 ---
 
 # The schema index
 
 A schema index is an OpenAPI/Swagger description turned into something that can
 be **asked a question**. It is built once, on disk, and answered from without a
-model: `zen rag schema index` writes it, and five commands read it.
+model: `zen rag schema index` writes it, and six commands read it.
 
 It exists because a real specification does not fit in a context window, and
 grepping it does not help. The parts that answer "how do I reset a password?"
@@ -18,7 +18,7 @@ word "password" appears in forty places that are not the one you want.
 ## The commands
 
 ```
-zen rag schema <index|search|list|grep|show|stats> [spec...]
+zen rag schema <index|search|list|grep|trace|show|stats> [spec...]
 ```
 
 | Command  | Answers                                | Embedder? | Typical |
@@ -27,15 +27,16 @@ zen rag schema <index|search|list|grep|show|stats> [spec...]
 | `search` | _what is this API's way to do X?_      | **yes**   | seconds |
 | `list`   | _what methods/types/fields are there?_ | no        | instant |
 | `grep`   | _does the string X appear anywhere?_   | no        | instant |
+| `trace`  | _which call can reach this field?_     | no        | instant |
 | `show`   | _print exactly these things_           | no        | instant |
 | `stats`  | _what is in this index?_               | no        | instant |
 
 Only `search` ranks, and only `search` costs a network round trip — it embeds
-the query before it can compare anything. The other four read `graph.json` off
+the query before it can compare anything. The other five read `graph.json` off
 the disk and answer in milliseconds, so reach for `search` when the question is
-vague and for `list`/`grep` when it is precise. If a search feels slow, it is
-that one embedding call, not the index: near-zero CPU for several seconds is
-the tell.
+vague and for `list`/`grep`/`trace` when it is precise. If a search feels slow,
+it is that one embedding call, not the index: near-zero CPU for several seconds
+is the tell.
 
 > **`search` takes bare words as the query, not as a subcommand.**
 > `zen rag schema search list methods` does not list anything — it runs a
@@ -138,6 +139,7 @@ zen rag schema index <spec...> [--embedding <ref>] [-o <dir>] [--batch <n>]
 | `--embedding <ref>` | —             | Which embedder makes the vectors. Omit it to see the choices |
 | `-o`, `--out <dir>` | `./schema-db` | Where the index goes; `$ZEN_SCHEMA_DB` if that is set        |
 | `--batch <n>`       | `96`          | Texts per embedding request, and how often progress prints   |
+| `--no-sources`      | —             | Keep no copy of the documents; `show --source` rebuilds them |
 | `--quiet`           | —             | No narration                                                 |
 
 ```sh
@@ -316,6 +318,7 @@ think it is?".
 | ------------------------------------------------ | ---------------------------------------- |
 | "how do I reset a password with this API?"       | `search --method "reset a password"`     |
 | _anything you would have run `grep` for_         | `grep` / `list` — never the shell        |
+| "which call can reach this field?"               | `trace <field>`                          |
 | "what does the create-user request look like?"   | `search --input-type "create user"`      |
 | "what operations exist under /users?"            | `list methods --path "*/users*"`         |
 | "how many operations are there at all?"          | `list methods` (or `--json` for `found`) |
@@ -325,9 +328,9 @@ think it is?".
 | "is this index the right one?"                   | `stats`                                  |
 
 The rule: **a question about meaning is a `search`; a question about presence,
-count or spelling is a `list` or a `grep`.** Search cannot answer the second
-kind, because a ranking always returns its best guesses whether or not any of
-them are right.
+count or spelling is a `list` or a `grep`; a question about reachability is a
+`trace`.** Search cannot answer the last two, because a ranking always returns
+its best guesses whether or not any of them are right.
 
 ### Exact matching, when the question is whether something exists
 
@@ -344,7 +347,7 @@ zen rag schema grep <pattern> [-d <dir>] [filters…]
 | ------------------- | ------ | ---------------------------------------------- |
 | `--name <p>`        | both   | Match the name. Repeatable                     |
 | `--path <p>`        | both   | Match the route it sits on. Repeatable         |
-| `--regex`           | both   | Read every pattern as a regular expression     |
+| `--regex`           | both   | Read the patterns as regular expressions       |
 | `--case-sensitive`  | both   | Stop ignoring case                             |
 | `--source <name>`   | both   | Only one document, as `stats` names it         |
 | `--show-source`     | both   | Print which document each row came from        |
@@ -375,12 +378,15 @@ so the two agree on what the API says. A pattern with `*` or `?` is a glob
 matched against the whole string; a plain word is a substring, so `--name
 password` finds `ResetPasswordPayload` and `--name "Password*"` finds nothing.
 
-**`--regex` applies to both commands and to every pattern**, which is the only
-way to say "one of these" — a glob has no alternation:
+**`--regex` is the only way to say "one of these"** — a glob has no alternation.
+On `list` it turns every pattern into a regular expression. On `grep` it turns
+the **pattern** into one; `--name` and `--path` stay globs-or-substrings there,
+because they are always names:
 
 ```sh
 zen rag schema list methods --regex --path "^/(users|teams)/"
 zen rag schema list types --regex --name "(Request|Response)$"
+zen rag schema grep "pass(word|phrase)" --regex --path "*/users*"
 ```
 
 `--name` and `--path` are constraints on `grep` as well, which is what makes a
@@ -404,6 +410,63 @@ whole point of them.
 zen rag schema grep token --ids-only | xargs zen rag schema show --format ts
 ```
 
+### Upwards, from a field to the calls that carry it
+
+Finding the field is half the job. The other half — which operation can
+actually reach it — is a walk up the `$ref`s.
+
+`search` does part of it: it stitches its seeds into one connected piece and
+prints what each operation accepts and returns, so a lucky search does show the
+call. But it joins only what **ranked**, only within `--max-hops` (3 by
+default), and it never names the chain — and the call almost never repeats the
+word, so `GET /users/{userId}` and `city` have nothing in common except the
+edges between them. `trace` follows those edges instead of guessing at them:
+exhaustive, and certain.
+
+```
+zen rag schema trace <pattern|id...> [-d <dir>] [filters…]
+```
+
+```sh
+zen rag schema trace city
+```
+
+```
+Property:Address.city
+    GET /users/{userId}  getUser  output  PublicUserProfile.address → Address.city
+```
+
+One command instead of three lookups and a guess: find the field, find what
+holds `Address`, find what accepts _that_, and hope you followed every branch.
+The last column is the whole route, so the shape of the call can be read off
+the answer.
+
+| Flag              | Default            | Meaning                                              |
+| ----------------- | ------------------ | ---------------------------------------------------- |
+| `--kind <k>`      | types + properties | `method`, `type` or `property`. Repeatable           |
+| `--direction <d>` | `any`              | Only the calls that accept it, or that return it     |
+| `--max-hops <n>`  | `8`                | How far up to walk                                   |
+| `--limit <n>`     | —                  | Trace at most n matching nodes                       |
+| `--routes <n>`    | —                  | Operations printed per node; `found` counts them all |
+| `--ids-only`      | —                  | Bare operation ids, one per line, for piping         |
+| `--regex`         | —                  | Read the pattern as a regex; `--case-sensitive` too  |
+| `--source <name>` | —                  | Only nodes from one document                         |
+| `--show-source`   | —                  | Print which document each operation came from        |
+
+A bare word matches the way `list --name` does — a substring, or a glob when it
+has `*` or `?`. A node id (`Type:User`) is taken as that node rather than as a
+pattern. Operations are left out of a name match on purpose: they are where a
+trace ends, not where one starts.
+
+```sh
+zen rag schema trace password --direction input
+zen rag schema trace "*Settings" --kind type
+zen rag schema trace mfa_secret --ids-only | xargs zen rag schema show --format openapi
+```
+
+`no operation reaches it` is a real answer, and one worth having: the schema is
+unreachable in this document, so no request will ever carry it.
+
 ### Instead of the shell
 
 Every reflex that reaches for a shell tool has a command here that answers the
@@ -456,7 +519,7 @@ client or a mock payload from.
 
 ## Giving it to an agent
 
-The same engine, as five tools in the group `schema`. An agent takes them all
+The same engine, as six tools in the group `schema`. An agent takes them all
 with `schema:*` in its `tools:`.
 
 ```ts
@@ -477,14 +540,17 @@ const project = await loadProject('./my-project', { tools: schemaTools(index) })
 | `find_types_with_property` | every schema with a field of this name — exact lookup, no searching |
 | `list_api`                 | methods, types or fields by name — complete, and counted in full    |
 | `grep_api`                 | every literal occurrence of a string — the way to prove absence     |
+| `trace_api`                | up from a field or schema to the operations that carry it           |
 
-Only `search_api` ranks; the other four are exact. `find_types_with_property`
+Only `search_api` ranks; the other five are exact. `find_types_with_property`
 is the one for the repair loop. When `tsc` says `'password' does not exist in
 type 'PublicUserProfile'`, the model does not need the word explained again —
 it needs the list of types that _do_ have one, and embedding the word will only
 rank the guess it already made near the top. `grep_api` is the same instinct
 widened: it is how a model checks that a search returning nothing really means
-there is nothing.
+there is nothing. `trace_api` is the step after either of them: a field is of
+no use until the call that carries it is known, and no ranking will find that
+call — the operation and the field share no words, only edges.
 
 `list_api` and `grep_api` take `name`, `path`, `regex` and `source`, so a
 common word can be narrowed to one route or one document rather than read out
@@ -495,6 +561,82 @@ together, which one answered is part of the answer.
 Tell the agent in its prompt to search before it writes a call, and to put the
 intent in the narrow field. A model left to itself puts everything in `all`.
 
+## Wiring it into a project means writing the project a skill
+
+**Whenever an index is used by a Zenera project — as `schema:*` tools, or as
+`zen rag` reachable from the agent's sandbox — write a skill for it in that
+project.** Not optional, and not the same thing as passing the tools in.
+
+Wiring alone leaves the model to infer everything that matters. A tool
+description says what `grep_api` does; it cannot say that this index holds the
+NSX policy API, that names are `snake_case`, that every route is under
+`/policy/api/v1`, or that `list_api` is the right first move here because the
+API has three hundred operations and search will hand back five. That is
+project knowledge, and project knowledge belongs in a skill — where it is
+loaded only when the model is actually working on this API, instead of sitting
+in the system prompt of every run.
+
+```
+<project>/agents/skills/<api>-api/SKILL.md
+```
+
+Frontmatter is `name` and `description`; the description is what the model
+reads when choosing, so it must name the API and the questions it answers.
+Add `tools: [search_api, list_api, grep_api, trace_api, describe_types,
+find_types_with_property]` if the skill should be what unlocks them.
+
+### What the skill has to say
+
+| Section         | Because                                                                                                            |
+| --------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Which API       | The name, the version, and the document it was built from                                                          |
+| Where the index | `ZEN_SCHEMA_DB`, or the `-d` to pass — an agent cannot guess a path                                                |
+| Which command   | Meaning → `search`; presence, spelling or a count → `list`/`grep`; which endpoint carries a field → `trace`        |
+| Never the shell | State it outright. `grep`/`rg`/`jq` on the spec is the default reflex                                              |
+| The conventions | Auth, base path, pagination, casing, error envelope — none of it is in the graph                                   |
+| Worked examples | Two or three, with **real operation and schema names from this index**                                             |
+| The repair loop | Compiler said the field is not on the type → `find_types_with_property`, then `trace` for the call that carries it |
+
+Best practice, in order of how often it is got wrong:
+
+1. **Use real names.** `list_api types --name "*Policy*"` with output the model
+   will actually see beats a generic `<TypeName>` placeholder, because the
+   names are the anchors it steers by.
+2. **Say which command answers which question**, and say that a ranking cannot
+   prove absence. Left alone a model searches for everything, gets five ranked
+   guesses, and writes a call against the best of them.
+3. **Keep it short.** A skill is prompt. One screen of routing rules and
+   conventions beats a transcription of this document — link to `zen rag
+schema --help` for the flags.
+4. **Re-index, then re-read the skill.** Both go stale against the same
+   change, and a skill quoting operations that no longer exist is worse than
+   none.
+5. **One skill per API**, named after it. Two APIs in one skill and the model
+   mixes their conventions.
+
+```md
+---
+name: billing-api
+description: How to find the right call in the Acme Billing API (v2) — which schema
+    carries which field, and which endpoint accepts it. Use before writing any request.
+---
+
+# The Billing API
+
+Indexed at `/assets/schema-db` (already in `$ZEN_SCHEMA_DB`). 214 operations,
+all under `/v2`. Bearer token in `Authorization`; cursors, never page numbers.
+
+- Vague question ("how do I cancel a subscription?") → `search_api`, intent in
+  the narrowest field: `methods`, not `all`.
+- Does X exist, how is it spelled, how many are there → `list_api` / `grep_api`.
+  These are complete; a search is not, and cannot prove absence.
+- Which endpoint carries this field → `trace_api`. Never guess the owner.
+- Never `grep`/`rg`/`jq` the spec — the tools above are local and exact.
+
+Worked: the invoice total is `Invoice.amount_due` (minor units), returned by
+`GetInvoice` and `ListInvoices`; `trace_api of: amount_due` shows both.
+```
+
 ## When it goes wrong
 
 | Symptom                                          | Cause                                                                               |

package/templates/editor/.github/skills/zen-cli/SKILL.md

@@ -28,7 +28,7 @@ zen sandbox  [status|up|pull|clean|disk] [options]
 zen version
 
 zen faker    <serve|build|cache> [spec...]
-zen rag      schema <index|search|list|grep|show|stats> [spec...]
+zen rag      schema <index|search|list|grep|trace|show|stats> [spec...]
 ```
 
 ## Read the reference before answering

package/templates/editor/.github/skills/zen-cli/references/rag.md

@@ -1,7 +1,7 @@
 # API search — `zen rag`
 
 ```
-zen rag schema <index|search|list|grep|show|stats> [spec...]
+zen rag schema <index|search|list|grep|trace|show|stats> [spec...]
 ```
 
 Provided by `@zenera/rag` — `npm i -g @zenera/rag` if `zen rag` says it is not
@@ -27,6 +27,8 @@ zen rag schema index <spec...> [--embedding <ref>] [-o <dir>] [--batch <n>]
 | `--embedding <ref>` | —             | Which embedder makes the vectors. Omit it to see the choices |
 | `-o`, `--out <dir>` | `./schema-db` | Where the index goes; `$ZEN_SCHEMA_DB` if set                |
 | `--batch <n>`       | `96`          | Texts per embedding request, and how often progress prints   |
+| `--no-sources`      | —             | Keep no copy of the documents in the index                   |
+| `--quiet`           | —             | No narration                                                 |
 
 ```
 zen rag schema index openapi.yaml --embedding openai:text-embedding-3-small
@@ -162,7 +164,7 @@ read `graph.json` directly, with no embedder, no credential and no network.
 | ------------------- | ------ | -------------------------------------------- |
 | `--name <p>`        | both   | Match the name. Repeatable                   |
 | `--path <p>`        | both   | Match the route it sits on. Repeatable       |
-| `--regex`           | both   | Read every pattern as a regular expression   |
+| `--regex`           | both   | Read the patterns as regular expressions     |
 | `--case-sensitive`  | both   | Stop ignoring case                           |
 | `--source <name>`   | both   | Only nodes from one document                 |
 | `--show-source`     | both   | Print which document each row came from      |
@@ -171,11 +173,18 @@ read `graph.json` directly, with no embedder, no credential and no network.
 | `--kind <k>`        | `grep` | `method`, `type` or `property`. Repeatable   |
 | `--ids-only`        | `grep` | Just the ids, one per line, for piping       |
 | `--limit <n>`       | both   | Rows to print. `found` still counts them all |
+| `--quiet`           | both   | No narration                                 |
+
+Under `--json`: `{found, truncated, rows}` from `list`, `{found, truncated,
+matches}` from `grep`. `grep` takes **one** pattern — quote it if it has
+spaces — and `list` **one** subject.
 
 A pattern with `*` or `?` is a glob matched against the whole string; a plain
 word is a substring. So `--name password` finds `ResetPasswordPayload`, and
 `--name "Password*"` finds nothing, because nothing starts with it. `--regex`
-makes it a regular expression instead — the only way to say "one of these":
+makes it a regular expression instead — the only way to say "one of these". On
+`list` it applies to every pattern; on `grep` it applies to the pattern, while
+`--name` and `--path` stay globs-or-substrings:
 
 ```
 zen rag schema list methods --regex --path "^/(users|teams)/"
@@ -198,12 +207,71 @@ No match exits 0 with nothing on stdout — that is the answer, and unlike an
 empty search it is a reliable one. Under `--limit`, `found` is still the true
 total, so a shortened answer never misreports how much there is.
 
+## `trace`
+
+```
+zen rag schema trace <pattern|id...> [-d <dir>] [--kind <k>] [--direction <d>]
+                     [--max-hops <n>] [--limit <n>] [--routes <n>]
+                     [--ids-only] [--regex] [--case-sensitive] [--source <name>]
+                     [--show-source]
+```
+
+The question `list` and `grep` leave you holding: you have found the field, so
+**which call can reach it?** `trace` walks up the `$ref`s from every node of
+that name to the operations that accept or return it, and prints the chain in
+between. Also a plain graph read — no embedder, no credential.
+
+```
+zen rag schema trace city
+```
+
+```
+Property:Address.city
+    GET /users/{userId}  getUser  output  PublicUserProfile.address → Address.city
+```
+
+By hand that is three lookups and a guess: find the field, find what holds
+`Address`, find what accepts _that_, and hope you followed every branch.
+
+`search` does some of this already — it stitches its seeds into one connected
+piece and prints what each operation accepts and returns. But it links only
+what **ranked**, only within `--max-hops`, and it never names the chain; and
+`getUser` and `city` share no word, so the field has to rank on its own and the
+call has to land near it. `trace` follows the edges instead, which are already
+there and are certain.
+
+| Flag              | Default            | Meaning                                              |
+| ----------------- | ------------------ | ---------------------------------------------------- |
+| `--kind <k>`      | types + properties | `method`, `type` or `property`. Repeatable           |
+| `--direction <d>` | `any`              | Keep only the calls that accept it, or return it     |
+| `--max-hops <n>`  | `8`                | How far up to walk                                   |
+| `--limit <n>`     | —                  | Trace at most n matching nodes                       |
+| `--routes <n>`    | —                  | Operations printed per node; `found` counts them all |
+| `--ids-only`      | —                  | Bare operation ids, one per line, for piping         |
+| `--regex`         | —                  | Read the pattern as a regex; `--case-sensitive` too  |
+| `--source <name>` | —                  | Only nodes from one document                         |
+| `--show-source`   | —                  | Print which document each operation came from        |
+
+A bare word is matched the way `list --name` matches it — substring, or a glob
+when it has `*` or `?`. A node id (`Type:User`) is taken as that node and not
+as a pattern. Operations are left out of a name match on purpose: they are
+where a trace ends.
+
+```
+zen rag schema trace password --direction input
+zen rag schema trace "*Settings" --kind type
+zen rag schema trace mfa_secret --ids-only | xargs zen rag schema show --format openapi
+```
+
+A node nothing carries prints `no operation reaches it` — a real answer, and
+one worth having: it means the schema is unreachable in this document.
+
 ## `show`
 
 ```
-zen rag schema show [id...] [-d <dir>] [--format <f>]
+zen rag schema show [id...] [-d <dir>] [--format <f>] [--exact]
                     [--method <name>] [--type <name>] [--source <name>]
-                    [--show-source] [--exact]
+                    [--show-source] [--max-nodes <n>] [--no-docs] [--quiet]
 ```
 
 Prints named nodes with no search in between. Needs no embedder and no
@@ -214,7 +282,16 @@ usually what you have. A bare name means exactly that name; add `*` to select
 more than one. `--source <name>` takes a whole document, and `--show-source`
 tags each node with the document it came from. `--exact` prints only what was
 named instead of the neighbourhood around it — with `--format openapi` that is
-a valid, self-contained slice of the specification.
+a valid, self-contained slice of the specification. Without it the neighbours
+are stitched in, up to `--max-nodes`.
+
+`--source <name> --format openapi` with nothing else named prints the
+**verbatim** document as it was indexed, unless the index was built
+`--no-sources`, in which case it is rebuilt from the graph and says so.
+
+A name that matches nothing is an **error**, not an empty answer: naming
+something is a claim that it is there, and `list --name` is the command for
+asking whether it is.
 
 ```
 zen rag schema show --method GetCurrentUserInfo --format openapi --exact
@@ -241,10 +318,12 @@ documents it came from. Also needs no embedder.
 | `find_types_with_property` | Every schema with a field of this name — exact lookup, no searching |
 | `list_api`                 | Methods, types or fields by name — complete, and counted in full    |
 | `grep_api`                 | Every literal occurrence of a string — the way to prove absence     |
+| `trace_api`                | Up from a field or schema to the operations that carry it           |
 
 Only `search_api` ranks. Reach for the others whenever the question is whether
 something exists, because a search that returns nothing and a thing that is not
-there look exactly the same.
+there look exactly the same. `trace_api` is the one for after a field has been
+found and the endpoint to call is what is actually wanted.
 
 They share the group `schema`, so an agent takes them with `schema:*` in its
 `tools:`.