@zenera/cli 1.1.15 → 1.1.17

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

@@ -1,4 +1,4 @@
-# Projects — `init`, `list`, `open`, `version`
+# Projects - `init`, `list`, `open`, `version`
 
 ## `zen init`
 
@@ -19,28 +19,45 @@ What it writes:
 
 ```
 zenera.json                     { version, name }
-INSTRUCTIONS.md                 house rules
 agents.yaml                     the configuration
+agents/instructions.md          house rules, prepended to every agent
+agents/memory-instructions.md   more of them, about the memory store
 agents/prompts/default.md       the default agent's prompt
 agents/skills/                  empty, for skills
 assets/README.md
 sandbox/Dockerfile              the image the sandbox builds
 sessions/                       empty
+.env                            this project's environment, git-ignored
 .gitignore
 .vscode/settings.json           editor files
 .github/                        copilot instructions, prompts, this skill
 ```
 
-The project's own files are never overwritten — `--force` is what allows
+More house rules can be added by hand: any `agents/<topic>-instructions.md` is
+read too, in filename order, and prepended to every agent. A capability that
+needs standing rules - memory, say - gets its own file rather than another
+section of `agents/instructions.md`. Memory's are not written from scratch:
+`agents/memory-instructions.md` is the same file as
+`.github/skills/zen-memory/references/memory-instructions.md`, which init puts
+in the project as well, so a copy that was lost or went stale is restored rather
+than rewritten - `.github/skills/zen-memory/scripts/check-instructions.sh` says
+which of the two it is, and `… fix` does the copy.
+
+The project's own files are never overwritten - `--force` is what allows
 writing into an occupied directory, and the files already there stay. The
 editor files are the exception: `.vscode/settings.json` and the `.github/` tree
 are ours and are replaced on every `init` and every `zen open`, so edits to them
 do not survive.
 
 The default agent gets the file tools and a sandboxed shell, plus `exa:*` when
-the keyring holds an Exa key.
-
-**Choosing the model.** Without `--model`, the keyring is asked — not counted.
+the keyring holds an Exa key. It also gets memory: the store is scaffolded in
+`memory/`, the agent is bound to it with `memory: true`, and it is vectorised by
+the chosen provider's embedding model. A provider that publishes none -
+Anthropic - gets the store without an `embeddings:` entry, and recall ranks by
+term overlap until one is added; an entry naming a provider with no embeddings
+API is a project that fails to load, not one that degrades.
+
+**Choosing the model.** Without `--model`, the keyring is asked - not counted.
 Stored credentials are probed, because holding a key is not the same as holding
 a working one, and the model is picked from a provider that answers. A key from
 the environment is taken at its word. Each provider has its own scaffolded

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

@@ -1,14 +1,14 @@
-# API search — `zen rag`
+# API search - `zen rag`
 
 ```
 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
+Provided by `@zenera/rag` - `npm i -g @zenera/rag` if `zen rag` says it is not
 installed.
 
-Reads an OpenAPI/Swagger document as a **graph** — operations, schemas and the
-fields inside them, joined by the `$ref`s between them — and makes it
+Reads an OpenAPI/Swagger document as a **graph** - operations, schemas and the
+fields inside them, joined by the `$ref`s between them - and makes it
 searchable. The answer to a search is not a list of matches but the connected
 piece of the API that matched: the operations, the schemas they carry and the
 fields inside them, printed as text, a diagram, or TypeScript that compiles.
@@ -24,18 +24,18 @@ 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 |
+| `--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                                                 |
+| `--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
 ```
 
 Unlike the faker, `$ref`s are **bundled, not dereferenced**: component names are
-the node ids and the cycles between them are the edges. `discriminator` is kept —
+the node ids and the cycles between them are the edges. `discriminator` is kept -
 it is what turns a `oneOf` into a tagged union a compiler can narrow.
 
 What lands in `<out>`:
@@ -56,14 +56,14 @@ search with a different model is refused rather than quietly returning nonsense.
 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
+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`
+is refused rather than guessed at - name one with `-d`, or set `ZEN_SCHEMA_DB`
 once and stop typing it.
 
 ## `search`
@@ -80,7 +80,7 @@ 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
+### Terms - repeatable, and the field is the point
 
 | Term                    | Searches                                 |
 | ----------------------- | ---------------------------------------- |
@@ -103,22 +103,22 @@ search good. A request field belongs in `--input-property`, a response field in
 
 | Flag                        | Default     | Meaning                                                 |
 | --------------------------- | ----------- | ------------------------------------------------------- |
-| `-d`, `--dir <dir>`         | found       | Which index — see "Which index gets read"               |
+| `-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                        |
+| `--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                                            |
+| `--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
@@ -130,7 +130,7 @@ The exclusions are what turn one search into a session: pass back the ids of
 what you have already been shown to be shown something else instead of the same
 thing again.
 
-`--format ts` emits TypeScript closed over its own `$ref`s — everything named is
+`--format ts` emits TypeScript closed over its own `$ref`s - everything named is
 also declared, so the output compiles on its own.
 
 ### `--interactive`
@@ -157,7 +157,7 @@ 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
+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                                      |
@@ -176,13 +176,13 @@ read `graph.json` directly, with no embedder, no credential and no network.
 | `--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.
+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". On
+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:
 
@@ -203,7 +203,7 @@ 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
+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.
 
@@ -219,7 +219,7 @@ zen rag schema trace <pattern|id...> [-d <dir>] [--kind <k>] [--direction <d>]
 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.
+between. Also a plain graph read - no embedder, no credential.
 
 ```
 zen rag schema trace city
@@ -233,7 +233,7 @@ Property: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
+`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
@@ -245,14 +245,14 @@ there and are certain.
 | `--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
+| `--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.
@@ -263,7 +263,7 @@ 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
+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`
@@ -275,13 +275,13 @@ zen rag schema show [id...] [-d <dir>] [--format <f>] [--exact]
 ```
 
 Prints named nodes with no search in between. Needs no embedder and no
-credential — it is a read of the graph.
+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
+named instead of the neighbourhood around it - with `--format openapi` that is
 a valid, self-contained slice of the specification. Without it the neighbours
 are stitched in, up to `--max-nodes`.
 
@@ -315,9 +315,9 @@ 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_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` | 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
@@ -328,7 +328,7 @@ 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:`.
 
-# Document search — `zen rag docs`
+# Document search - `zen rag docs`
 
 ```
 zen rag docs <index|search|list|grep|show|stats> [args...]
@@ -347,17 +347,17 @@ zen rag docs index <path...> [--embedding <ref>] [-o <dir>] [--chunk-tokens <n>]
 
 | Flag                 | Default     | Meaning                                                      |
 | -------------------- | ----------- | ------------------------------------------------------------ |
-| `--embedding <ref>`  | —           | Which embedder makes the vectors. Omit it to see the choices |
+| `--embedding <ref>`  | -           | Which embedder makes the vectors. Omit it to see the choices |
 | `-o`, `--out <dir>`  | `./docs-db` | Where the index goes; `$ZEN_DOCS_DB` if set                  |
 | `--batch <n>`        | `96`        | Texts per embedding request                                  |
 | `--chunk-tokens <n>` | `384`       | Target chunk size                                            |
-| `--quiet`            | —           | No narration                                                 |
+| `--quiet`            | -           | No narration                                                 |
 
 Paths may be files, directories or globs. `.md`, `.markdown`, `.txt` and
 `.text` are read; hidden directories and `node_modules` are not.
 
 Every document is **copied into the index**, and every quoted line is read back
-out of that copy — so the index is one portable thing and what it quotes is the
+out of that copy - so the index is one portable thing and what it quotes is the
 document rather than a reconstruction of it. Each document is named by its path
 relative to the common root of everything indexed, which is what keeps
 `acme_4.1.0/api/routing.md` and `acme_4.2.0/api/routing.md` apart.
@@ -378,17 +378,19 @@ zen rag docs search [text...] [-f <pattern>] [-s <section>] [--kind <k>]
 
 | Flag                     | Default  | Meaning                                              |
 | ------------------------ | -------- | ---------------------------------------------------- |
-| `-f`, `--file <pattern>` | —        | Only documents whose name matches. Repeatable        |
-| `--exclude-file <p>`     | —        | Drop documents whose name matches                    |
-| `-s`, `--section <name>` | —        | Only under this heading, and what nests in it        |
-| `--kind <k>`             | —        | `paragraph`, `list`, `table`, `table_row`, `code`, … |
+| `-f`, `--file <pattern>` | -        | Only documents whose name matches. Repeatable        |
+| `--exclude-file <p>`     | -        | Drop documents whose name matches                    |
+| `-s`, `--section <name>` | -        | Only under this heading, and what nests in it        |
+| `--kind <k>`             | -        | `paragraph`, `list`, `table`, `table_row`, `code`, … |
 | `--mode <m>`             | `hybrid` | `hybrid`, `vector` or `text` for exact wording       |
+| `--text-query <text>`    | -        | Wording for the full-text leg, instead of `[text]`   |
+| `--vector-query <text>`  | -        | Wording for the vector leg, instead of `[text]`      |
 | `--limit <n>`            | `8`      | Passages kept                                        |
 | `-B`, `-A <n>`           | `0`      | Extra lines quoted before and after each passage     |
 | `--max-lines <n>`        | `400`    | A ceiling on the whole answer                        |
-| `--exclude-id <id>`      | —        | Drop a passage already seen. Repeatable              |
-| `--hits`                 | —        | One line per passage instead of the text             |
-| `--interactive`          | —        | Prompt, search, narrow, search again                 |
+| `--exclude-id <id>`      | -        | Drop a passage already seen. Repeatable              |
+| `--hits`                 | -        | One line per passage instead of the text             |
+| `--interactive`          | -        | Prompt, search, narrow, search again                 |
 
 **Narrowing is the interface.** Nobody finds the right paragraph on the first
 ask; the second call is the same question inside one part of the tree.
@@ -403,7 +405,114 @@ zen rag docs search --mode text "X-RateLimit-Remaining"
 A `--file` pattern with `*` or `?` is a glob over the whole document name and
 a substring otherwise.
 
-## `list`, `grep`, `show` — no embedder, no credential
+### Limiting the search scope
+
+`--file` selects the documents that are allowed to contribute passages. Repeat
+it to include multiple document families; use `--exclude-file` to subtract a
+family. Both are applied before ranking, so a returned passage cannot come from
+a document outside the selected set. Start with `list files` when the corpus
+names are unknown:
+
+```sh
+zen rag docs list files -d <index-dir>
+zen rag docs search -d <index-dir> --file "manual-*/**" "<question>"
+zen rag docs search -d <index-dir> --file "guide-*/**" --file "reference-*/**" \
+  --exclude-file "*-archive/**" "<question>"
+```
+
+`--section` narrows the selected documents again, retaining a named heading and
+all headings below it. It accepts a heading title, structure id, or structure
+path printed by `list sections`. Combine it with `--file` when the same heading
+exists in more than one document. `--kind` scopes by content shape: use `table`
+or `table_row` for limits and matrices, and `code` for commands or examples.
+
+```sh
+zen rag docs list sections -d <index-dir> --file "manual-*/**"
+zen rag docs search -d <index-dir> --file "manual-*/**" --section "Operations" \
+  --kind table_row "<question about a limit>"
+```
+
+### Search strategy
+
+### How retrieval modes work
+
+Search has two independent retrieval legs, followed by reciprocal-rank fusion
+and a diversity pass. It does **not** run full-text search and then use a vector
+model to rerank those same results.
+
+| Mode     | What runs                                | Best for                                                      | Caution                                               |
+| -------- | ---------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------- |
+| `hybrid` | Full-text and vector legs, fused by rank | Default: concepts, explanations, broad questions              | A broad corpus can still need `--file` or `--section` |
+| `text`   | Full-text only                           | Exact errors, headers, commands, identifiers, and phrases     | Literal wording only; misses paraphrases              |
+| `vector` | Vector similarity only                   | A concept whose wording is unknown or differs from the corpus | Can retrieve topical but imprecise passages           |
+
+The full-text leg rewards words present in the chunk. The vector leg embeds the
+question and retrieves similar meaning, even with different vocabulary. Hybrid
+adds a rank-based contribution from each leg, so a passage supported by both
+normally rises while a strong result from either leg can still appear. The final
+diversity pass prevents near-identical neighbouring chunks from consuming the
+whole answer.
+
+**Use hybrid first.** Ask the user-facing question as a complete sentence. It
+combines semantic similarity with the words in the corpus and is the strongest
+default for concepts, explanations, and broad operational questions:
+
+```sh
+zen rag docs search -d <index-dir> "How is a failed request retried?"
+```
+
+Treat the answer as candidates, not confirmation. Search ranks a fixed number
+of passages, so it cannot prove an exact phrase is absent and may return a
+nearby version or an incident that happens to share terms. Read the returned
+line-numbered passage; then use `show` for its surrounding section or `grep`
+for an exact existence check.
+
+**Narrow before rewriting the question.** For a corpus with releases, products,
+or repeated manuals, a broad term can retrieve a relevant-looking answer from
+the wrong part of the tree. Keep the question and progressively constrain it:
+
+```sh
+zen rag docs list files -d <index-dir>
+zen rag docs list sections -d <index-dir> --file "guide-*/**"
+zen rag docs search -d <index-dir> --file "guide-*/**" --section "Operations" \
+  "How is a failed request retried?"
+```
+
+Use `--kind table` or `--kind table_row` for a limit, entitlement, or matrix;
+use `--kind code` for a command or configuration sample. Pass returned ids to
+`--exclude-id` when the next answer must be new rather than a repeat.
+
+**Use exact lookup for exact claims.** `--mode text` is for a known error,
+header, command, identifier, or phrase. `grep` is stronger when the question is
+whether that exact string appears anywhere, because it counts every match and
+does not depend on vector ranking:
+
+```sh
+zen rag docs search -d <index-dir> --mode text "exact identifier"
+zen rag docs grep -d <index-dir> "exact identifier"
+```
+
+**Split the wording only when it is genuinely two wordings.** The text leg
+wants a distinctive string likely to occur verbatim; the vector leg wants the
+full intent. This is useful for an exact identifier plus an explanatory
+question:
+
+```sh
+zen rag docs search -d <index-dir> --text-query "exact identifier" \
+  --vector-query "what it means, its constraints, and how to use it"
+```
+
+Both flags run and fuse the two legs. One on its own runs only that leg.
+`--text-query` and `--vector-query` replace positional `[text]` and settle the
+mode themselves: do not combine them with `[text]` or `--mode`.
+
+Split search is an expert control, not a stronger default. A generic text leg
+such as a product name or common noun retrieves every incidental mention and
+can displace the more useful semantic passages. Use it only when the text leg
+is specific enough to add evidence rather than noise; otherwise stay with
+ordinary hybrid search and narrow by file or section.
+
+## `list`, `grep`, `show` - no embedder, no credential
 
 ```
 zen rag docs list <files|sections|tables> [-f <pattern>] [-s <section>]
@@ -417,6 +526,32 @@ total even when `--limit` cuts the rows, so unlike a search it can answer
 whether a string appears at all. `show` prints a document, a named section, or
 a line range, verbatim.
 
+### Reading a complete section or table
+
+Search finds relevant passages, not necessarily every row of a table. When the
+whole section or table is needed, use the exact readers instead of increasing a
+search limit.
+
+Read a heading and everything nested beneath it verbatim:
+
+```sh
+zen rag docs show -d <index-dir> "<document-name>" --section "<heading>"
+```
+
+For one complete table, list its metadata first. Each row reports the document
+name and the table's inclusive `line` and `end` range. Give that range to
+`show --lines` to print the complete table, including its header, verbatim:
+
+```sh
+zen rag docs list tables -d <index-dir> --file "<document-name>"
+zen rag docs show -d <index-dir> "<document-name>" --lines <line>-<end>
+```
+
+Narrow `list tables` with `--file` or `--section` when the corpus has many
+tables. `search --kind table` and `search --kind table_row` are useful to find
+a relevant table, but remain ranked retrieval; use the listed line span when
+the answer needs every row.
+
 ## Giving it to an agent
 
 `@zenera/rag/docs/tools` exports four tools in the group `docs`:
@@ -424,8 +559,8 @@ a line range, verbatim.
 | Tool          | For                                                             |
 | ------------- | --------------------------------------------------------------- |
 | `search_docs` | The search above, with the same narrowing parameters            |
-| `list_docs`   | The documents, their headings, or their tables — no ranking     |
-| `grep_docs`   | Every matching line, counted in full — the way to prove absence |
+| `list_docs`   | The documents, their headings, or their tables - no ranking     |
+| `grep_docs`   | Every matching line, counted in full - the way to prove absence |
 | `read_docs`   | A section or a line range, verbatim and complete                |
 
 Only `search_docs` ranks. Every answer carries line numbers and `read_docs`

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

@@ -1,4 +1,4 @@
-# Running — `zen run`
+# Running - `zen run`
 
 ```
 zen run [project] [prompt] [options]
@@ -49,8 +49,8 @@ git diff | zen run --quiet "summarise this diff"
 
 A prompt is a request for an answer, not a conversation to pick up, so it
 answers the three questions itself: **a fresh session**, **the directory you are
-in** as the workspace, and **no confirmation**. Every flag still wins —
-`--session`, `--workspace` and `--read-only` override it — and the TUI, where
+in** as the workspace, and **no confirmation**. Every flag still wins -
+`--session`, `--workspace` and `--read-only` override it - and the TUI, where
 there is someone to ask, still asks.
 
 There is no `resume`. A session continues itself, because its state is what it

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

@@ -1,4 +1,4 @@
-# The sandbox — `zen sandbox`
+# The sandbox - `zen sandbox`
 
 ```
 zen sandbox [status|up|pull|clean|disk] [options]
@@ -7,7 +7,7 @@ zen sandbox [status|up|pull|clean|disk] [options]
 Shell commands run in a container over the session workspace, never on the
 host. None of this is required: a run does all of it on its own, the first time
 an agent that can reach a shell is about to start one. These subcommands are for
-doing it deliberately — before a demo, in CI, or when diagnosing.
+doing it deliberately - before a demo, in CI, or when diagnosing.
 
 | Subcommand | What it does                                                   |
 | ---------- | -------------------------------------------------------------- |
@@ -26,14 +26,14 @@ The engine is Podman. On macOS a machine has to exist and be running; `up`
 offers to install and start one, and its size follows the project's `cpus` and
 `memory`.
 
-## Configuring it — `sandbox:` in `agents.yaml`
+## Configuring it - `sandbox:` in `agents.yaml`
 
 Top level, and again per agent, where an agent's block is merged over the base.
 
 | Key       | Meaning                                                          |
 | --------- | ---------------------------------------------------------------- |
 | `image`   | The image to run. Mutually exclusive with `build`                |
-| `build`   | `{ dockerfile, context? }` — build one instead. Excludes `image` |
+| `build`   | `{ dockerfile, context? }` - build one instead. Excludes `image` |
 | `cpus`    | CPU limit                                                        |
 | `memory`  | Memory limit, in MiB                                             |
 | `network` | Whether the container has one                                    |
@@ -47,11 +47,17 @@ Top level, and again per agent, where an agent's block is merged over the base.
 `CREDENTIAL`: the keyring has already materialised real credentials into the
 process environment, and a sandbox is the last place they should be forwarded to.
 
+The door for those is the project's `.env`, which `zen init` writes and
+`.gitignore` covers. `zen run` reads it before loading the project and forwards
+every name in it into the container **by name**, so the value never reaches an
+argv. `keys: false` and `zen run --no-keys` withhold it along with the API keys.
+The shell's environment wins over the file; the keyring fills in the rest.
+
 ## `persist: true` is usually what you want
 
 Only `/workspace` and `/home/agent` survive an ephemeral container. A
 `pip install` as root, or an `apt-get install`, lands in the image's system
-paths and is gone by the next run — so the agent silently reinstalls its
+paths and is gone by the next run - so the agent silently reinstalls its
 toolchain every single time. `zen init` scaffolds `persist: true` for that
 reason.
 
@@ -69,8 +75,8 @@ sandbox:
     persist: true
 ```
 
-The tag is content-addressed — a hash of the Dockerfile and every file in its
-context — so a changed Dockerfile is a different image and a `persist: true`
+The tag is content-addressed - a hash of the Dockerfile and every file in its
+context - so a changed Dockerfile is a different image and a `persist: true`
 container can never be left sitting on a stale rootfs. It is built only when
 that tag is absent, which is safe precisely because the tag follows the content.
 `zen sandbox pull` forces a rebuild.
@@ -87,5 +93,5 @@ prepared, and the message names the command to run for this platform. `zen check
 distinguishes the two cases: a broken Dockerfile is an error, a laptop with no
 Podman is a warning.
 
-`zen sandbox clean` removes every container this CLI created — the way out of a
+`zen sandbox clean` removes every container this CLI created - the way out of a
 container left on a bad rootfs.