@zenera/cli 1.1.4 → 1.1.5

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.5",
     "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.5",
         "@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, 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,33 @@ 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`.
+
 ## Why it is a graph and not a search box
 
 Two structures, kept together, because neither answers alone:
@@ -236,7 +263,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 +276,96 @@ 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"`     |
+| "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>`        | `list` | Match the name. Repeatable                     |
+| `--path <p>`        | `list` | Match the route (methods). Repeatable          |
+| `--method-type <t>` | `list` | `read_only`, `read_write` or `any`             |
+| `--direction <d>`   | `list` | `input`, `output` or `any`                     |
+| `--regex`           | `grep` | Read the pattern as a regular expression       |
+| `--case-sensitive`  | `grep` | Stop ignoring case                             |
+| `--kind <k>`        | `grep` | `method`, `type` or `property`. Repeatable     |
+| `--ids-only`        | `grep` | Bare ids, one per line, for piping             |
+| `--source <name>`   | both   | Only one document, as `stats` names it         |
+| `--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
+```
+
+`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.
+
+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
+```
+
+### 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
+```
+
+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.
+`--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 +384,16 @@ 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       |
+| `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     |
 
-`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.
+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.
 
 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 +409,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
@@ -58,6 +58,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                                 |
@@ -126,15 +131,67 @@ 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>] [--regex] [--kind <k>] [--ids-only]
+```
+
+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>`        | `list` | Match the name. Repeatable                   |
+| `--path <p>`        | `list` | Match the route. Repeatable                  |
+| `--source <name>`   | both   | Only nodes from one document                 |
+| `--method-type <t>` | `list` | `read_only`, `read_write` or `any`           |
+| `--direction <d>`   | `list` | `input`, `output` or `any`                   |
+| `--regex`           | `grep` | Read the pattern as a regular expression     |
+| `--case-sensitive`  | `grep` | Stop ignoring case                           |
+| `--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.
+
+```
+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 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>] [--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. `--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 +210,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}}