@zenera/cli 1.1.4 → 1.1.6

package/dist/commands/index.js

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

package/dist/scaffold.js

@@ -26,6 +26,14 @@ import { fileURLToPath } from 'node:url';
 const TEMPLATES = fileURLToPath(new URL('../templates', import.meta.url));
 /** The suffix on a file with `{{...}}` in it, dropped when the file lands. */
 const TEMPLATE = '.tmpl';
+/**
+ * This `zen`'s own version, which the scaffold pins the sandbox's tools to.
+ * The publishable packages move in lockstep, so one number covers them all.
+ */
+function ownVersion() {
+    const manifest = fileURLToPath(new URL('../package.json', import.meta.url));
+    return JSON.parse(readFileSync(manifest, 'utf8')).version;
+}
 /**
  * Fills the `{{name}}` in a template, in the two shapes templates use.
  *
@@ -169,6 +177,7 @@ export function scaffold(opts) {
         vars: {
             model: modelSection(opts.model, opts.modelOptions),
             exa: opts.web ? part('exa.yaml') : '',
+            version: ownVersion(),
         },
     });
     // The directories with no file to put in them: a skill is a folder someone

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.4",
+    "version": "1.1.6",
     "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.4",
+        "@zenera/neo": "^1.1.6",
         "@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`) — including 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`, and giving it to an agent as tools.
 ---
 
 # 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, `zen rag schema search` queries it.
+model: `zen rag schema index` writes it, and five 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?"
@@ -15,6 +15,45 @@ are scattered on purpose: the field is on a schema, the schema is a request
 body, the request body belongs to one operation out of three hundred, and the
 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...]
+```
+
+| Command  | Answers                                | Embedder? | Typical |
+| -------- | -------------------------------------- | --------- | ------- |
+| `index`  | builds the thing                       | yes       | minutes |
+| `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 |
+| `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 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.
+
+> **`search` takes bare words as the query, not as a subcommand.**
+> `zen rag schema search list methods` does not list anything — it runs a
+> semantic search for the phrase _"list methods"_ and returns ten ranked
+> guesses. The listing command is `zen rag schema list methods`.
+
+> **Never reach for shell `grep`, `rg`, `find`, `cat` or `jq` here.**
+> Not on the specification, not on `graph.json`, not on anything under the
+> index directory. `zen rag schema grep` and `zen rag schema list` are the
+> exact-matching commands, they are local, they need no credential, and they
+> answer in milliseconds. Shell tools on the same files are strictly worse:
+> they match raw YAML/JSON lines rather than nodes, so they cannot tell a
+> field from a `$ref` from a description, cannot say which operation a hit
+> belongs to, cannot filter by kind or direction, and they miss every name
+> the index normalised. A `grep -r password openapi.yaml` returns forty lines
+> of text; `zen rag schema grep password` returns the nodes, with their ids,
+> ready to hand back to `show`.
+
 ## Why it is a graph and not a search box
 
 Two structures, kept together, because neither answers alone:
@@ -97,7 +136,7 @@ zen rag schema index <spec...> [--embedding <ref>] [-o <dir>] [--batch <n>]
 | Flag                | Default       | Meaning                                                      |
 | ------------------- | ------------- | ------------------------------------------------------------ |
 | `--embedding <ref>` | —             | Which embedder makes the vectors. Omit it to see the choices |
-| `-o`, `--out <dir>` | `./schema-db` | Where the index goes                                         |
+| `-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   |
 | `--quiet`           | —             | No narration                                                 |
 
@@ -122,6 +161,27 @@ a real environment variable always wins.
 Rebuild the index when the specification changes. Nothing watches it, and a
 stale index is a confident wrong answer.
 
+## Which index gets read
+
+Every reading command takes `-d`, `--dir`. Without one:
+
+1. `$ZEN_SCHEMA_DB`, if it is set. **Set this once** instead of typing `-d` on
+   every command — `export ZEN_SCHEMA_DB=/assets/schema-db`.
+2. Otherwise the **nearest index** to the working directory: here, then a short
+   way down into it, then up a level and again, stopping at your home
+   directory. The one chosen is named on stderr as it is used, so an answer is
+   never anonymous.
+3. Otherwise `./schema-db`, which is only so the error names the directory you
+   were expecting.
+
+What is looked for is a `manifest.json` — an index is self-describing, so
+nothing searches for a directory _called_ `schema-db` and one called anything
+else is found the same way. `schema-db` is just the name a new one is given.
+
+Two indexes the same distance away is refused rather than guessed at: the wrong
+index does not fail, it answers confidently about a different API. Name one
+with `-d`, or set `ZEN_SCHEMA_DB`.
+
 ## Searching it
 
 ```
@@ -154,23 +214,24 @@ response field in `--output-property`, an action in `--method`.
 
 ### Shaping the answer
 
-| Flag                        | Default       | Meaning                                                 |
-| --------------------------- | ------------- | ------------------------------------------------------- |
-| `-d`, `--dir <dir>`         | `./schema-db` | Which index                                             |
-| `--embedding <ref>`         | the index's   | Must be the one the index was built with                |
-| `--direction <d>`           | `any`         | `input`, `output` or `any`                              |
-| `--method-type <t>`         | `any`         | `read_only` (GET/HEAD/OPTIONS) or `read_write`          |
-| `--exclude-id <id>`         | —             | Drop a node. Repeatable                                 |
-| `--exclude-method <name>`   | —             | Drop an operation by name. Repeatable                   |
-| `--exclude-type <name>`     | —             | Drop a schema by name. Repeatable                       |
-| `--exclude-property <name>` | —             | Drop a field by name. Repeatable                        |
-| `--limit <n>`               | `5`           | Seeds kept per term                                     |
-| `--max-hops <n>`            | `3`           | How far apart two hits may be and still join            |
-| `--max-nodes <n>`           | `200`         | Nodes per result                                        |
-| `--format <f>`              | `text`        | `text`, `mermaid`, `mermaid-flowchart`, `ts`, `openapi` |
-| `--no-docs`                 | —             | Leave the descriptions out                              |
-| `--interactive`             | —             | Prompt, search, refine. Needs a terminal                |
-| `--quiet`                   | —             | No narration                                            |
+| Flag                        | Default     | Meaning                                                 |
+| --------------------------- | ----------- | ------------------------------------------------------- |
+| `-d`, `--dir <dir>`         | found       | Which index — see "Which index gets read"               |
+| `--embedding <ref>`         | the index's | Must be the one the index was built with                |
+| `--direction <d>`           | `any`       | `input`, `output` or `any`                              |
+| `--method-type <t>`         | `any`       | `read_only` (GET/HEAD/OPTIONS) or `read_write`          |
+| `--exclude-id <id>`         | —           | Drop a node. Repeatable                                 |
+| `--exclude-method <name>`   | —           | Drop an operation by name. Repeatable                   |
+| `--exclude-type <name>`     | —           | Drop a schema by name. Repeatable                       |
+| `--exclude-property <name>` | —           | Drop a field by name. Repeatable                        |
+| `--limit <n>`               | `5`         | Seeds kept per term                                     |
+| `--max-hops <n>`            | `3`         | How far apart two hits may be and still join            |
+| `--max-nodes <n>`           | `200`       | Nodes per result                                        |
+| `--format <f>`              | `text`      | `text`, `mermaid`, `mermaid-flowchart`, `ts`, `openapi` |
+| `--show-source`             | —           | Tag each operation and schema with its document         |
+| `--no-docs`                 | —           | Leave the descriptions out                              |
+| `--interactive`             | —           | Prompt, search, refine. Needs a terminal                |
+| `--quiet`                   | —           | No narration                                            |
 
 ```sh
 zen rag schema search --method "reset a user password" --format ts
@@ -236,7 +297,8 @@ quit
 
 ## Reading it without searching
 
-Both need no embedder and no credential — they are plain reads.
+None of these need an embedder or a credential — they are plain reads of the
+graph on disk.
 
 ```sh
 zen rag schema show Type:Invoice Method:listInvoices --format ts
@@ -248,9 +310,153 @@ an index and what built it — counts by kind, the embedding model, the document
 it came from. `stats` is the fastest way to answer "is this index the one I
 think it is?".
 
+### Which one to reach for
+
+| The question                                     | The command                              |
+| ------------------------------------------------ | ---------------------------------------- |
+| "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        |
+| "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`) |
+| "is there a field called `mfa_secret` anywhere?" | `grep mfa_secret`                        |
+| "which schemas mention tenancy?"                 | `grep tenancy --kind type`               |
+| "give me `GetUser` as OpenAPI"                   | `show --method GetUser --format openapi` |
+| "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.
+
+### Exact matching, when the question is whether something exists
+
+Search **ranks**. A ranking returns the top of a list, which means it can never
+tell you that something is absent — "no results" and "not there" look the same.
+When that is the actual question, do not search:
+
+```
+zen rag schema list <methods|types|properties> [-d <dir>] [filters…]
+zen rag schema grep <pattern> [-d <dir>] [filters…]
+```
+
+| Flag                | For    | Meaning                                        |
+| ------------------- | ------ | ---------------------------------------------- |
+| `--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     |
+| `--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        |
+| `--method-type <t>` | `list` | `read_only`, `read_write` or `any`             |
+| `--direction <d>`   | `list` | `input`, `output` or `any`                     |
+| `--kind <k>`        | `grep` | `method`, `type` or `property`. Repeatable     |
+| `--ids-only`        | `grep` | Bare ids, one per line, for piping             |
+| `--limit <n>`       | both   | Print at most n; `found` still counts them all |
+| `--json`            | both   | `{found, truncated, rows}` / `…, matches}`     |
+| `--quiet`           | both   | No narration                                   |
+
+```sh
+zen rag schema list methods                      # all of them, sorted by route
+zen rag schema list methods --path "*/users*"    # every route under /users
+zen rag schema list methods --method-type read_only
+zen rag schema list types --name "*Password*"    # every schema so named
+zen rag schema list types --direction output     # everything a call can return
+zen rag schema list properties --name password   # every field so named
+zen rag schema grep password                     # every literal occurrence
+zen rag schema grep "pass(word|phrase)" --regex
+zen rag schema grep password --kind type --ids-only
+zen rag schema grep status --path "/invoices/*"   # the word, in one corner
+```
+
+`list` walks one kind of node and matches its structured fields; `grep` matches
+the text of every node in the index — the same text the search was built from,
+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:
+
+```sh
+zen rag schema list methods --regex --path "^/(users|teams)/"
+zen rag schema list types --regex --name "(Request|Response)$"
+```
+
+`--name` and `--path` are constraints on `grep` as well, which is what makes a
+common word usable: `grep status` across a whole API is unreadable,
+`grep status --path "/invoices/*" --kind property` is an answer. On `list
+properties` and on `grep`, `--path` matches the route a parameter's operation
+sits on; a schema belongs to no one route, so `--path` never selects one.
+
+When an index holds several documents, `--show-source` puts
+`[source: billing_api_v2]` on every row, so which document answered does not
+have to be recovered from `--json`.
+
+Both report `found` as the true total even when `--limit` shortens what is
+printed, so a cut answer never misreports how much there is. Nothing matching
+exits 0 with empty stdout — and that emptiness is trustworthy, which is the
+whole point of them.
+
+`grep --ids-only` composes:
+
+```sh
+zen rag schema grep token --ids-only | xargs zen rag schema show --format ts
+```
+
+### Instead of the shell
+
+Every reflex that reaches for a shell tool has a command here that answers the
+same question better. Add `-d <dir>` when the index is not the nearest one, or
+name it once with `ZEN_SCHEMA_DB`.
+
+| The reflex                              | The command                                           |
+| --------------------------------------- | ----------------------------------------------------- |
+| `grep -ri password spec.yaml`           | `zen rag schema grep password`                        |
+| `grep -r password` \| _only in schemas_ | `zen rag schema grep password --kind type`            |
+| `grep -E "pass(word\|phrase)"`          | `zen rag schema grep "pass(word\|phrase)" --regex`    |
+| `grep password` (case matters)          | `zen rag schema grep password --case-sensitive`       |
+| `grep -c` / `wc -l`                     | `--json`, and read `found` — it counts past `--limit` |
+| `grep -l` / `grep -o` for piping        | `zen rag schema grep password --ids-only`             |
+| `grep "/users" spec.yaml`               | `zen rag schema list methods --path "*/users*"`       |
+| `grep -i "updateuser"`                  | `zen rag schema list methods --name "*Update*"`       |
+| `grep "UserSettings"`                   | `zen rag schema list types --name "*UserSettings*"`   |
+| `grep -A5 password` for the field       | `zen rag schema list properties --name "*password*"`  |
+| `grep -rl password specs/` (which one?) | `zen rag schema grep password --show-source`          |
+| `cat`/`yq` a schema out of the document | `zen rag schema show --type UserSettings --format ts` |
+| `ls` the index directory                | `zen rag schema stats`                                |
+
+```sh
+export ZEN_SCHEMA_DB=/assets/schema-db   # once, then never again
+zen rag schema grep "password" --limit 10
+zen rag schema list methods --path "*user*"
+zen rag schema list types --name "*UserSettings*"
+zen rag schema list properties --name "*password*" --show-source
+```
+
+If none of these fits the question, the question is about meaning, and the
+answer is `search` — still not the shell.
+
+### Naming what you want in `show`
+
+```sh
+zen rag schema show --method GetCurrentUserInfo --format openapi --exact
+zen rag schema show --type "*Invoice*" --format ts
+zen rag schema show --source billing-api --format openapi
+zen rag schema show --type "*Invoice*" --show-source
+```
+
+Ids are one way in, but `--method` and `--type` take the names you already
+have. A bare name means exactly that name; add `*` to take more than one.
+`--show-source` names the document each node came from, which is the quick way
+to tell two versions of the same API apart. `--exact` prints only what was
+named instead of the neighbourhood around it, which with `--format openapi`
+gives a valid self-contained slice of the specification — enough to generate a
+client or a mock payload from.
+
 ## Giving it to an agent
 
-The same engine, as four tools in the group `schema`. An agent takes them all
+The same engine, as five tools in the group `schema`. An agent takes them all
 with `schema:*` in its `tools:`.
 
 ```ts
@@ -269,12 +475,22 @@ const project = await loadProject('./my-project', { tools: schemaTools(index) })
 | `search_api`               | the search above, with the same fields                              |
 | `describe_types`           | named schemas as TypeScript, closed over what they refer to         |
 | `find_types_with_property` | every schema with a field of this name — exact lookup, no searching |
-| `list_methods`             | operations by path, to see the shape of the API before asking       |
-
-`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.
+| `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     |
+
+Only `search_api` ranks; the other four 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.
+
+`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
+in full. When an index holds more than one document, both tools name the source
+of every row without being asked — with two versions of the same API indexed
+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`.
@@ -290,3 +506,5 @@ intent in the narrow field. A model left to itself puts everything in `all`.
 | A usage error before any credential is asked for | Deliberate: everything about the invocation is checked first, so a typo is a typo   |
 | Nothing matched                                  | Exit 0 with an empty answer. Try fewer words, or `--all` instead of a narrow field  |
 | Answers about the wrong version of the API       | Nothing watches the document. Re-index after it changes                             |
+| A search took ten seconds, using no CPU          | One embedding round trip, not the index. `list`/`grep` make none                    |
+| `search <word> <word>` gave ranked nonsense      | Bare words after `search` are the QUERY, not a subcommand. You meant `list`/`grep`  |

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|show|stats> [spec...]
+zen rag      schema <index|search|list|grep|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|show|stats> [spec...]
+zen rag schema <index|search|list|grep|show|stats> [spec...]
 ```
 
 Provided by `@zenera/rag` — `npm i -g @zenera/rag` if `zen rag` says it is not
@@ -25,7 +25,7 @@ zen rag schema index <spec...> [--embedding <ref>] [-o <dir>] [--batch <n>]
 | Flag                | Default       | Meaning                                                      |
 | ------------------- | ------------- | ------------------------------------------------------------ |
 | `--embedding <ref>` | —             | Which embedder makes the vectors. Omit it to see the choices |
-| `-o`, `--out <dir>` | `./schema-db` | Where the index goes                                         |
+| `-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   |
 
 ```
@@ -49,6 +49,21 @@ lance/            the vector and full-text indexes
 The manifest records the embedding ref **and** the embedder's own id, so a
 search with a different model is refused rather than quietly returning nonsense.
 
+## Which index gets read
+
+Every reading command takes `-d`, `--dir`. Without one:
+
+1. `$ZEN_SCHEMA_DB`, if it is set.
+2. Otherwise the **nearest index** to the working directory — here, then a
+   short way down, then up a level and again, stopping at your home directory.
+   The one used is named on stderr.
+3. Otherwise `./schema-db`, so the error names the directory you expected.
+
+What is looked for is a `manifest.json`, not a directory called `schema-db`, so
+an index called anything else is found the same way. Two the same distance away
+is refused rather than guessed at — name one with `-d`, or set `ZEN_SCHEMA_DB`
+once and stop typing it.
+
 ## `search`
 
 ```
@@ -58,6 +73,11 @@ zen rag schema search [terms…] [filters…]
 Every argument is validated before an embedder is constructed, so a typo is a
 usage error rather than a credential error.
 
+**Bare words are the query, not a subcommand.** `zen rag schema search list
+methods` searches for the phrase _"list methods"_ and returns ranked guesses;
+`zen rag schema list methods` is the listing. `search` is also the only read
+command that embeds, so it is the only slow one.
+
 ### Terms — repeatable, and the field is the point
 
 | Term                    | Searches                                 |
@@ -79,23 +99,24 @@ search good. A request field belongs in `--input-property`, a response field in
 
 ### Filters and shape
 
-| Flag                        | Default       | Meaning                                                 |
-| --------------------------- | ------------- | ------------------------------------------------------- |
-| `-d`, `--dir <dir>`         | `./schema-db` | Which index                                             |
-| `--embedding <ref>`         | the index's   | Must be the one the index was built with                |
-| `--direction <d>`           | `any`         | `input`, `output` or `any`                              |
-| `--method-type <t>`         | `any`         | `read_only`, `read_write` or `any`                      |
-| `--exclude-id <id>`         | —             | Drop a node. Repeatable                                 |
-| `--exclude-method <name>`   | —             | Drop an operation by name. Repeatable                   |
-| `--exclude-type <name>`     | —             | Drop a schema by name. Repeatable                       |
-| `--exclude-property <name>` | —             | Drop a field by name. Repeatable                        |
-| `--limit <n>`               | `5`           | Seeds kept per term                                     |
-| `--max-hops <n>`            | `3`           | How far apart two hits may be                           |
-| `--max-nodes <n>`           | `200`         | Nodes per result                                        |
-| `--format <f>`              | `text`        | `text`, `mermaid`, `mermaid-flowchart`, `ts`, `openapi` |
-| `--no-docs`                 | —             | Leave the descriptions out                              |
-| `--interactive`             | —             | Prompt, search, refine. Needs a terminal                |
-| `--quiet`                   | —             | No narration                                            |
+| Flag                        | Default     | Meaning                                                 |
+| --------------------------- | ----------- | ------------------------------------------------------- |
+| `-d`, `--dir <dir>`         | found       | Which index — see "Which index gets read"               |
+| `--embedding <ref>`         | the index's | Must be the one the index was built with                |
+| `--direction <d>`           | `any`       | `input`, `output` or `any`                              |
+| `--method-type <t>`         | `any`       | `read_only`, `read_write` or `any`                      |
+| `--exclude-id <id>`         | —           | Drop a node. Repeatable                                 |
+| `--exclude-method <name>`   | —           | Drop an operation by name. Repeatable                   |
+| `--exclude-type <name>`     | —           | Drop a schema by name. Repeatable                       |
+| `--exclude-property <name>` | —           | Drop a field by name. Repeatable                        |
+| `--limit <n>`               | `5`         | Seeds kept per term                                     |
+| `--max-hops <n>`            | `3`         | How far apart two hits may be                           |
+| `--max-nodes <n>`           | `200`       | Nodes per result                                        |
+| `--format <f>`              | `text`      | `text`, `mermaid`, `mermaid-flowchart`, `ts`, `openapi` |
+| `--show-source`             | —           | Tag each operation and schema with its document         |
+| `--no-docs`                 | —           | Leave the descriptions out                              |
+| `--interactive`             | —           | Prompt, search, refine. Needs a terminal                |
+| `--quiet`                   | —           | No narration                                            |
 
 ```
 zen rag schema search --method "reset a user password" --format ts
@@ -126,15 +147,80 @@ reset                   forget it, exclusions included
 quit
 ```
 
+## `list` and `grep`
+
+```
+zen rag schema list <methods|types|properties> [-d <dir>] [--name <p>] [--path <p>]
+zen rag schema grep <pattern> [-d <dir>] [--name <p>] [--path <p>] [--kind <k>]
+```
+
+Exact, and therefore complete. `search` ranks, so it can only hand back the top
+of a list — it cannot tell you that something is _not_ there. These can: they
+read `graph.json` directly, with no embedder, no credential and no network.
+
+| Flag                | For    | Meaning                                      |
+| ------------------- | ------ | -------------------------------------------- |
+| `--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   |
+| `--case-sensitive`  | both   | Stop ignoring case                           |
+| `--source <name>`   | both   | Only nodes from one document                 |
+| `--show-source`     | both   | Print which document each row came from      |
+| `--method-type <t>` | `list` | `read_only`, `read_write` or `any`           |
+| `--direction <d>`   | `list` | `input`, `output` or `any`                   |
+| `--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 |
+
+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":
+
+```
+zen rag schema list methods --regex --path "^/(users|teams)/"
+```
+
+`--path` selects on the route an operation sits on, and on the route a
+parameter's operation sits on. A schema belongs to no one route, so `--path`
+never selects one.
+
+```
+zen rag schema list methods --path "*/users*"
+zen rag schema list types --name "*Password*"
+zen rag schema grep password
+zen rag schema grep "pass(word|phrase)" --regex
+zen rag schema grep status --path "/invoices/*" --kind property
+zen rag schema grep token --ids-only | xargs zen rag schema show --format ts
+```
+
+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.
+
 ## `show`
 
 ```
-zen rag schema show <id...> [-d <dir>] [--format <f>]
+zen rag schema show [id...] [-d <dir>] [--format <f>]
+                    [--method <name>] [--type <name>] [--source <name>]
+                    [--show-source] [--exact]
 ```
 
 Prints named nodes with no search in between. Needs no embedder and no
 credential — it is a read of the graph.
 
+Ids are one way in; `--method` and `--type` name things directly, which is
+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.
+
+```
+zen rag schema show --method GetCurrentUserInfo --format openapi --exact
+zen rag schema show --type "*Invoice*" --format ts
+```
+
 ## `stats`
 
 ```
@@ -153,7 +239,12 @@ documents it came from. Also needs no embedder.
 | `search_api`               | The search above, with the same fields                              |
 | `describe_types`           | Named schemas as TypeScript, closed over what they refer to         |
 | `find_types_with_property` | Every schema with a field of this name — exact lookup, no searching |
-| `list_methods`             | Operations by path, to see the shape of the API before asking       |
+| `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     |
+
+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.
 
 They share the group `schema`, so an agent takes them with `schema:*` in its
 `tools:`.

package/templates/project/sandbox/{Dockerfile → Dockerfile.tmpl}

@@ -18,4 +18,6 @@ COPY --from=node /usr/local/lib/node_modules /usr/local/lib/node_modules
 RUN ln -s /usr/local/lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm \
     && ln -s /usr/local/lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx
 
-RUN npm install -g @zenera/cli @zenera/rag
+# Pinned to the `zen` that wrote this file, so the tools in the container are
+# the ones the session outside it was built by. Bump both together.
+RUN npm install -g @zenera/cli@{{version}} @zenera/rag@{{version}}