@zenera/cli 1.1.24 → 1.1.25

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

@@ -1,20 +1,30 @@
 ---
 name: zen-inspect
-description: Diagnosing a run you did not watch - the `zen inspect graph` → read → `zen inspect node` loop, how to name the run (`--dir`, `--run`, `--session`, and why `node` takes ids only), how to read every part of the graph format (the `%%` header rows and what each count is evidence of, the anatomy of a node line, the label each node kind produces, shapes and colours, the `flow`/`branches`/`calls` edge blocks, branch subgraphs, and what `hidden by` and `ERROR` mean), how to open individual nodes by id or range and read the `===`/`--- part` framing, which payload parts and facts each kind carries, how `zen inspect ask` replays one `llm_call` to a model with a question when reading the node did not settle why it acted, and recipes for the usual faults - a loop, a failing tool, a prompt that was assembled differently from how it reads, a hand-off that fired early, a skill that never activated, a branch that failed, tokens spent where you did not expect. Load before reading any run trajectory, before answering "why did the agent do that", and whenever a run directory is all you have.
+description: 'Use when an LLM agent must diagnose a recorded Zenera run non-interactively: read `zen inspect graph`, open selected nodes, replay an `llm_call` with `zen inspect ask`, identify loops, failed tools, wrong prompts, missed skills, early hand-offs, failed branches, compaction, latency, or token waste. Requires explicit run, node, and question arguments so commands remain deterministic and never prompt.'
 ---
 
-# Reading a run
+# Diagnose a run non-interactively
 
 A run leaves behind everything it did, and that is the problem: a trajectory of
 a few hundred nodes is far too big to read and far too repetitive to need to.
 `zen inspect` answers it in two halves.
 
-| Command                 | For     | Gives                                           |
-| ----------------------- | ------- | ----------------------------------------------- |
-| `zen inspect report`    | a human | `report.html` - every message, payload and cost |
-| `zen inspect graph`     | you     | the whole run as one Mermaid flowchart          |
-| `zen inspect node <id>` | you     | those nodes in full, payloads resolved          |
-| `zen inspect ask <id>`  | you     | that call replayed to a model, with a question  |
+This skill is for an agent process without a TTY. Every invocation must be
+fully specified. Never run bare `zen inspect` or `zen inspect node`: without a
+run named they read whichever run is newest. Never run `zen inspect ask`
+without a question: that is the interactive mode, for a person, and it fails
+without a terminal. With a question it is one-shot - no banner, no prompt,
+only the answer on stdout.
+
+For a whole-run audit - health, memory, delegation, forking, tool use, and
+what to change in the instructions - load **zen-analyze-run**, which drives
+this skill end to end.
+
+| Command                                                    | Gives                                         |
+| ---------------------------------------------------------- | --------------------------------------------- |
+| `zen inspect graph --dir <run-dir>`                        | the whole run as one model-readable flowchart |
+| `zen inspect node <id...> --dir <run-dir>`                 | selected nodes, payloads resolved             |
+| `zen inspect ask <id> --question-file <f> --dir <run-dir>` | one replay answer on stdout, then exit        |
 
 **`graph` and `node` are the pair you use.** The graph is an index: one line per
 node, short sequential ids, the whole run in a few hundred lines. `node` is the
@@ -26,8 +36,26 @@ pay for what you open.
 run's own model why it did what it did. Open the node first - most questions are
 answered by reading what it was given.
 
-`report` is for a person with a browser. Print its path and hand it over; do not
-try to read the HTML.
+To get one answer without prompts, pass all three inputs:
+
+```sh
+zen inspect ask <llm-node-id> --question-file <question file> --dir <run-dir>
+```
+
+- `<llm-node-id>` is an `nN` id from `zen inspect graph` whose label starts
+  with `llm`.
+- `<question file>` holds the complete question, written with your
+  file-editing tool to `.tmp/ask/<run-id>/<node>-<topic>.md`. The shell never
+  parses it, so quotes, backticks and `$` arrive as written. Never pass the
+  question as a quoted argument, a heredoc or `$(cat ...)`, and never wrap
+  `zen` in a script.
+- `--dir <run-dir>` identifies the run. Instead, a caller may use `--run
+<run-id>` with `--session <session-id>` and, when outside the project,
+  `--project <name-or-dir>`.
+
+Exactly one raw Markdown answer is written to stdout, then the command exits.
+Omit `--model` to use the model that made the recorded call; pass `--model
+<ref>` only for a second opinion.
 
 ## The loop
 
@@ -39,7 +67,8 @@ zen inspect graph --dir <run dir>
 zen inspect node n13 n17..n19 --dir <run dir>
 
 # 3. only if reading them did not settle it, ask the model itself
-zen inspect ask n17 "why run python -c when the skill says npm test?" --dir <run dir>
+#    (.tmp/ask/<run-id>/n17-tests.md: "Why run python -c when the skill says npm test?")
+zen inspect ask n17 --question-file .tmp/ask/<run-id>/n17-tests.md --dir <run dir>
 ```
 
 That is the whole method. Never start by opening nodes - without the header
@@ -48,26 +77,26 @@ at a time is the failure the graph exists to prevent.
 
 ### Naming the run
 
-| You have                | Use                                                    |
-| ----------------------- | ------------------------------------------------------ |
-| a run directory         | `--dir <dir>` - the handle a program holds             |
-| `zen run --json` output | `--dir "$(… \| jq -r .run.dir)"`                       |
-| a run id                | `zen inspect graph <run-id>` or `--run <id>`           |
-| nothing                 | omit everything: the newest run that actually recorded |
-| a session               | `--session <id>`, listed by `zen list --sessions`      |
+| You have                | Use                                               |
+| ----------------------- | ------------------------------------------------- |
+| a run directory         | `--dir <dir>` - the handle a program holds        |
+| `zen run --json` output | `--dir "$(… \| jq -r .run.dir)"`                  |
+| a run id                | `zen inspect graph <run-id>` or `--run <id>`      |
+| a session               | `--session <id>`, listed by `zen list --sessions` |
+
+Always identify the run. Prefer `--dir`, because `zen run --json` returns it
+without requiring the caller to reconstruct project, session and run ids. If
+the task supplies no run handle, obtain one before inspecting; do not rely on
+the newest run implicitly.
 
 **`node` has no room for a run.** Every positional it takes is a node id, so
 name the run with `--dir`, `--run` or `--session`. `zen inspect node <run-id> n13`
-reads the run id as an id and fails. `ask` is the same: one node id, then the
-question.
+reads the run id as an id and fails. Explicit `ask` arguments are the same: one
+node id, then the question.
 
 For `graph` the positional is a run id unless it contains a `/`, in which case
 it is a directory - a run id is a stamp and never has a separator.
 
-With nothing to ask on - a script, `--json`, an agent - `zen inspect` takes the
-newest run of the newest session **that recorded one**. A session exists before
-its first run, so the literally newest session is routinely empty.
-
 ### Reading it cheaply
 
 `--no-style` drops the colour statements and `--no-timing` drops the clock;
@@ -121,6 +150,8 @@ diagram would make you count by eye.
 | `dir`       | the run directory                                    | paste into `--dir`, no reconstruction needed              |
 | `workspace` | the files the run worked on                          | where to go and check what actually changed               |
 | `memory`    | the memory graph the run read                        | absent when the run read none                             |
+|             | recall · search · grep · load · commit, zeros kept   | `commit 0` is nothing saved, whatever the answer says     |
+|             | `nothing committed after N workspace file writes`    | a script or file that worked and was not kept             |
 | `agent`     | the agent it ended on · the one it started as        | two different names means a hand-off happened             |
 | `phase`     | `done`, or the phase and the error                   | an error here is the verdict; the graph is the story      |
 | `nodes`     | total · llm · tool calls · forks                     | the shape and the size of what follows                    |
@@ -304,7 +335,7 @@ bug in the node.
 ## Asking the model
 
 ```sh
-zen inspect ask n17 "which instruction made you avoid the test command?" --dir <run dir>
+zen inspect ask n17 --question-file .tmp/ask/<run-id>/n17-tests.md --dir <run dir>
 ```
 
 One `llm_call`, replayed: its recorded system prompt, its messages and its tool
@@ -331,6 +362,10 @@ The questions it is good at are the ones about intent, where the node shows what
 happened but not why: which of two instructions won, why a skill that was
 loaded was not followed, why a tool was used the way it was.
 
+Before writing the question, load skill **zen-inspect-ask**: which node to ask, what
+to rule out first, and how to word a "why did you not..." question so the answer
+quotes the instruction that blocked the better behaviour.
+
 ## Diagnosing
 
 Match the symptom to the row of the header, then open the two or three nodes

package/templates/editor/.github/skills/zen-inspect-ask/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: zen-inspect-ask
+description: 'Use when formulating a question for `zen inspect ask` about an `llm_call` node of a recorded Zenera run - especially a "why did you NOT do X" question (why no `memory_search` first, why no `fork` for independent research branches, why no skill, why no test run). Covers choosing the node, ruling out missing tools before asking, wording the counterfactual so the answer quotes the instruction that blocked the better behaviour, and verifying that quote against the recorded request.'
+---
+
+# Asking a run why it did not do the better thing
+
+`zen inspect ask` replays one recorded `llm_call` - its system prompt, messages
+and tool schemas, byte for byte - with tool calling off and a preamble that
+permits the model to quote its own instructions. Load **zen-inspect** for the
+mechanics (graph, node, flags). This skill is about the one thing that decides
+whether the call is worth its cost: **the question**.
+
+The goal of every question here is the same: **find the sentence in the
+assembled prompt that prevented the good behaviour**, or prove that no sentence
+asked for it. That sentence is what you are about to edit. An answer that does
+not name one is a wasted call.
+
+Non-interactive rule, as in zen-inspect: always pass the node, the question and
+the run. The question is always a file (section 3):
+
+```sh
+zen inspect ask <llm-node-id> --question-file <question file> --dir <run-dir>
+```
+
+Each non-interactive call is a **fresh replay**. It does not remember your
+previous question. A follow-up must restate what it builds on.
+
+## 1. Rule out the cheap causes first
+
+A "why didn't you" question is only about instructions if the model could have
+done it. Check these from the graph and the node before spending a model call -
+each one is a finding on its own, and asking the model about it produces an
+invented rationale.
+
+| Check                                  | How                                                                                     | If it fails, the cause is                          |
+| -------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| The tool was offered on that call      | grep the recorded request for its schema (below)                                        | `agents.yaml` - tool not granted, or depth cap hit |
+| The instruction file was in the prompt | the `system_prompt` label lists files: `fork-instructions.md`, `memory-instructions.md` | missing file, or its `requires:` not met           |
+| The skill was loaded                   | a `load_skills` node naming it, or the skill index in `request`                         | binding in `agents.yaml` (`skills:`)               |
+| Memory was already recalled for it     | a `memory_recall` node before the call; `recall 0 nodes`                                | memory content, not behaviour                      |
+| The context still held what it needed  | no `compaction` before the node, or the item is not `hidden by` one                     | compaction, not instructions                       |
+
+```sh
+zen inspect node n9 --part request --dir <run-dir> | grep -oE '"name": *"(fork|memory_search|memory_grep)"' | sort -u
+```
+
+Only when every row passes is the question "which instruction stopped you".
+
+## 2. Pick the node where the decision was made
+
+The replay ends at the chosen node: the model sees everything up to and
+including that call's own answer, and **nothing after it**. So ask the call that
+made the choice, not the one where the consequence showed up.
+
+| Missing behaviour               | Ask the `llm_call` that...                                                          |
+| ------------------------------- | ----------------------------------------------------------------------------------- |
+| never searched memory           | issued the first tool call of the task (usually the first `llm` after `user input`) |
+| ran independent work in series  | issued the **first** of the sequential calls - it already had the whole plan        |
+| never loaded / followed a skill | chose the substitute action (the `python -c`, the hand-rolled grep)                 |
+| handed off too early            | carries `calls transfer_to_<name>`                                                  |
+| gave up / answered too early    | the last `llm` before `final output`                                                |
+| repeated a failed call          | the one right after the first `ERROR` result                                        |
+
+If the choice repeated (four serial searches), ask **once**, not per step. Ask
+the first call when the question is why it started that way - it already had
+the whole plan. Ask the last call of the sequence when the question is about
+the sequence as a whole - its replay holds every step. Never ask a middle one:
+that gets "I was continuing the pattern I had started", which names no
+instruction.
+
+## 3. Formulate the question
+
+### What the replayed model can see
+
+The model you are asking sees **only its own raw context** at that call: the
+system prompt, the messages up to that point, the tool descriptions, and the
+answer it gave - its text and its tool calls. That is all. So:
+
+- **No node ids, no graph words.** `n7`, `llm_call`, `tool_result`, "branch
+  n12" are your index, not its world. Name what it did by its content: "you
+  ran `grep -rn invoice /workspace/src`", "your first tool call was
+  `read_file` on `src/export.ts`".
+- **Refer to earlier steps by what they were**, as it saw them in its
+  messages: "after `memory_search` returned the export node", "after the
+  third `run_command` failed with exit code 1".
+- **Describe anything after the call yourself, in plain words.** The replay
+  ends at that call; it cannot see what followed. "You then searched three
+  more topics one after another" is something it can only learn from you.
+
+### What the preamble already does
+
+`ask` puts a preamble in front of the replayed system prompt, and it already
+makes the model do the following:
+
+- cite every reason as `[<kind>: <name> › <heading or parameter>] "<verbatim quote>"`,
+  where kind is system prompt, skill, tool description or message
+- trace the decision: the options it could see, which one it took, and which
+  text tipped it
+- say which instruction it followed, which it missed, which two conflicted, and
+  any exception it judged to apply
+- write "no instruction — my own default" instead of making up a source
+- use the answer format the question asks for
+
+**Do not restate any of that in the question.** Asking again for verbatim
+quotes or sources adds a second, differently worded copy of the rule, and the
+model follows whichever it read last.
+
+### The three parts
+
+The question supplies only what the preamble cannot know. Leave a part out and
+the answer drifts to a generic apology.
+
+1. **What it did, by content.** The action as it appears in its own answer,
+   stated as a fact, not an accusation.
+2. **Why not the better action - asked directly.** "Why didn't you use
+   `memory_search` to look up the invoice export first?" Name the action
+   concretely - the tool as it appears in its tool list, and the arguments or
+   branches it could have used - and say it was available. Never ask "did you
+   consider...": its own answer already shows it did not take that path, and
+   the question invites a yes that explains nothing.
+3. **A fixed answer shape.** So answers can be compared across calls and
+   runs, and so an answer without a citation is visibly empty. The shape uses
+   the preamble's citation form.
+
+Write the question to a file with your file-editing tool, then hand `zen` the
+file. The shell never parses the question, so quotes, apostrophes, backticks and
+`$` arrive as written. End the file with this shape, verbatim:
+
+```text
+<the question>
+
+Answer in this shape:
+options: <what you could see at that point, and which one you took>
+steered-by: [<kind>: <name> › <heading or parameter>] "<quote>"   (one per line, or: no instruction — my own default)
+should-have-applied: [<kind>: <name> › <heading or parameter>] "<quote>"   (or: none found)
+exception: [<kind>: <name> › <heading or parameter>] "<quote>"   (or: none)
+conflict: <the two citations that pulled in different directions, or: none>
+missing: <the sentence that, added where, would have made you do it>
+```
+
+```sh
+zen inspect ask n9 --question-file .tmp/ask/<run-id>/n9-memory.md --dir <run-dir>
+```
+
+- One file per question, at `.tmp/ask/<run-id>/<node>-<topic>.md`. `.tmp/` is
+  the project's git-ignored scratch.
+- `--question-file` is the only way the question reaches `zen`. Never a quoted
+  argument, a heredoc, `$(cat ...)`, or a Python or Node script around `zen`.
+- A retry (section 5, step 1) or a second opinion (step 4) reuses the same
+  file: add `--model <ref>` and change nothing else.
+
+### Wording rules
+
+- **Ask why not, directly.** "Why didn't you fork the four lookups?" - not
+  "did you consider forking?", not "would forking have been better?".
+- **Do not lead.** "Didn't fork-instructions tell you to parallelise?" gets
+  "yes, I should have" - agreement, not a cause. Name the action, never the
+  instruction you suspect.
+- **Do not ask what it should have done.** That produces a lecture on best
+  practice written from general knowledge, not from its prompt.
+- **One behaviour per question.** Memory and forking in one question get one
+  shallow answer each. Ask twice.
+- **Name the alternative as an action, not a virtue.** "Why didn't you
+  `memory_search` for 'invoice export endpoint'?" - not "why weren't you more
+  efficient?".
+- **Keep the exception line.** A rule with an escape hatch ("unless...", "only
+  when...", "for simple tasks...") is the most common blocker. The preamble asks
+  for exceptions, but a model will not volunteer that it granted itself one
+  unless an empty `exception:` line is waiting for it.
+
+## 4. Templates
+
+The question bodies below replace `<the question>` in the file of section 3.
+Replace every command, tool argument and topic with the run's own. None of them
+mentions a node id: the id goes on the command line, never in the question.
+
+### Did not use memory
+
+```text
+Your first step for this task was run_command `grep -rn 'export' /workspace/src`.
+Why didn't you use memory_search or memory_grep to look up the invoice export
+endpoint first? Both are in your tool list, and an earlier run may already have
+worked it out. What in your instructions, or missing from them, made the
+workspace the first place to look?
+```
+
+### Recalled memory, then redid the work
+
+```text
+memory_search returned a node describing the invoice export endpoint and where
+it is implemented. Your next step was to grep the workspace for the same
+endpoint. Why didn't you use what memory returned, or memory_load that node to
+read it whole? What made the recalled text not enough?
+```
+
+### Did not save what it learned
+
+```text
+To answer this you read eleven files and ran four commands, and your answer
+names facts a later run would need again. memory_commit is in your tool list.
+Why didn't you commit what you worked out before answering?
+```
+
+### Did not fork independent research
+
+```text
+From this point you researched four things one after another: (A) the auth
+flow, (B) the billing schema, (C) the retry policy, (D) the webhook format.
+None of the later lookups used an earlier result. Why didn't you call fork once
+with a branch for each of A-D? fork is in your tool list.
+```
+
+### Did not follow a loaded skill
+
+```text
+You called run_command with `python3 -c` to check the output. The skill
+run-tests is in your context and says to run `npm test`. Why didn't you run
+`npm test`? What made the inline script look acceptable here?
+```
+
+### Misused a tool
+
+```text
+You called memory_commit three times with a `refs` array naming nodes from an
+earlier commit, and each call failed. Why did you expect refs to reach nodes
+committed earlier? Which words in the memory_commit description led you there,
+or what was missing from it?
+```
+
+The same skeleton covers any missing behaviour: **what it did, by content ->
+why not the better action, available -> shape.** The preamble does the rest.
+
+## 5. Verify the answer
+
+The answer is testimony. It is useful because it points at a sentence; it is
+only a finding once the sentence is confirmed.
+
+1. **Grep each quote in the recorded request** - the text between the double
+   quotes of each `[...] "..."` citation.
+    ```sh
+    zen inspect node n9 --part request --dir <run-dir> | grep -F 'Do not fork a sequence'
+    ```
+    A quote that is not there is invented - discard the answer, not just the
+    quote. Ask once more; if it invents again, ask another model (step 4).
+2. **Find every copy.** The blocker often exists twice - once in a house rule,
+   once in a skill with a softer tail. Grep the whole request for a distinctive
+   phrase of it, then grep the project's `agents/` tree for the file to edit.
+3. **Check it is the project's file.** `fork-instructions.md`,
+   `memory-instructions.md`, `tools-instructions.md` are zen's own copies; load
+   **zen-instructions** before changing where that rule lives.
+4. **Second opinion when the self-report is thin.** The model that made the
+   call rationalises; another model reading the same replay often names the
+   conflict more plainly: `--model <ref>`. Ask the identical question: the same
+   question file.
+5. **Reproduce.** After the edit, rerun the case and check the graph: the
+   `tools` header row shows `fork x1` or `memory_search x1` where it did not
+   before. The answer predicted a fix; the graph confirms it.
+
+## 6. Reading the answer
+
+| Answer says                                                | Means                                       | Fix                                                               |
+| ---------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------- |
+| `should-have-applied: none found`                          | nothing asked for it                        | add a mechanical rule at the point of decision                    |
+| `steered-by: no instruction — my own default`              | the model's habit filled a gap              | add a mechanical rule at the point of decision                    |
+| a rule quoted as `should-have-applied`, nothing against it | the rule is there but not reachable in time | move it earlier, or into the skill loaded for that task           |
+| a `steered-by` quote that argues against the better action | an instruction argued against it            | narrow or remove the blocker, do not add a counter-rule beside it |
+| `conflict:` names two rules                                | two instructions disagree                   | delete one; two copies of a rule is how drift starts              |
+| an exception is quoted as applying                         | a self-judged escape hatch                  | remove the hatch or make its condition checkable                  |
+| no citation at all, general reasoning only                 | the question was too open, or led           | rewrite with the three parts; do not act on it                    |

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

@@ -648,20 +648,24 @@ ranker, the same walk, the same block a model would have been given, scores and
 all. It is the only one that embeds, and the only one that can distinguish a
 memory that is missing from a memory that is merely ranked sixth.
 
-| Question                                 | Command                              |
-| ---------------------------------------- | ------------------------------------ |
-| Is memory even on, and is it embedded?   | `zen memory stats`                   |
-| What has this project learned?           | `zen memory export --open`           |
-| Is this host/flag/path in there at all?  | `zen memory grep <pattern>`          |
-| Everywhere a thing is mentioned          | `zen memory grep <pattern> --all`    |
-| What would an agent recall for this?     | `zen memory search <query>`          |
-| Why did it _not_ recall that?            | `zen memory search <q> --audience a` |
-| What is in one private slice?            | `zen memory ls --audience audit`     |
-| What has been corrected?                 | `zen memory ls --stale`              |
-| What files are being kept?               | `zen memory ls --files`              |
-| One node in full, with what it links to  | `zen memory show <id>`               |
-| Fold parallel warmup graphs into one     | `zen memory merge <dir...>`          |
-| That should never have been written down | `zen memory forget <id>`             |
+| Question                                 | Command                               |
+| ---------------------------------------- | ------------------------------------- |
+| Is memory even on, and is it embedded?   | `zen memory stats`                    |
+| What has this project learned?           | `zen memory export --open`            |
+| Is this host/flag/path in there at all?  | `zen memory grep <pattern>`           |
+| Everywhere a thing is mentioned          | `zen memory grep <pattern> --all`     |
+| What would an agent recall for this?     | `zen memory search <query>`           |
+| Why did it _not_ recall that?            | `zen memory search <q> --audience a`  |
+| What is in one private slice?            | `zen memory ls --audience audit`      |
+| What has been corrected?                 | `zen memory ls --stale`               |
+| What files are being kept?               | `zen memory ls --files`               |
+| One node in full, with what it links to  | `zen memory show <id>`                |
+| What did a run add to its copy, or read? | `zen memory diff <base> --dir <copy>` |
+| Fold parallel warmup graphs into one     | `zen memory merge <dir...>`           |
+| That should never have been written down | `zen memory forget <id>`              |
+
+Never read a memory's `graph.json` or `manifest.json` with code: every question
+above has a command, and `--json` on any of them is the stable shape.
 
 The directory is not fixed. `zen run --memory <dir>` sends one run's memory
 somewhere else - a scratch graph for a trial, one per branch, or a shared one

package/templates/editor/.github/skills/zen-rag-docs/SKILL.md

@@ -387,6 +387,7 @@ outline and the copies on disk.
 zen rag docs list <files|sections|tables> [-d <dir>] [filters…]
 zen rag docs grep <pattern> [-d <dir>] [filters…]
 zen rag docs show <file> [--section <name>] [--lines <from-to>]
+zen rag docs show <target>... [--max-lines <n>]
 zen rag docs stats
 ```
 
@@ -411,6 +412,7 @@ zen rag docs grep "Retry-After"               # every matching line, and its sec
 zen rag docs grep "X-RateLimit-\w+" --regex --file "api/**"
 zen rag docs show api/routing.md --section "Rate limits"
 zen rag docs show api/routing.md --lines 40-80
+zen rag docs show "api/routing.md:24-31" "api/errors.md#Retries"   # several, one call
 zen rag docs stats
 ```
 
@@ -431,6 +433,14 @@ the whole point of it.
 line-number gutter (`--no-numbers` to drop it). It is the natural follow-up to
 every search: find the passage, then read what is actually around it.
 
+**Read every passage you will cite in one `show`.** It takes any number of
+targets written the way a citation is - `<document>:<a>-<b>`, `<document>:<a>`,
+`<document>#<heading>`, or a bare name - and prints each under a header that is
+itself a target, in the order given. Overlapping ranges print once; a missing
+document or heading is reported in place while the rest still print. The
+`--max-lines` budget (default 400) is shared fairly, and a cut block ends with
+the target that continues it. One call per passage costs a whole turn each.
+
 `stats` says what is in an index and what built it - the documents, the counts,
 the embedding model. It is the fastest way to answer "is this index the one I
 think it is?".
@@ -443,6 +453,7 @@ think it is?".
 | _anything you would have run `grep` for_          | `grep` / `list` - never the shell               |
 | "does `X-Request-Id` appear anywhere?"            | `grep X-Request-Id`                             |
 | "what does the rate-limits section actually say?" | `show <file> --section "Rate limits"`           |
+| "read the four passages the search turned up"     | `show <doc>:<a>-<b> <doc>:<a>-<b> ...` - once   |
 | "which documents are even in here?"               | `list files`                                    |
 | "what is the shape of this manual?"               | `list sections --depth 2`                       |
 | "where is the table of per-route limits?"         | `list tables --file "api/**"`                   |
@@ -470,6 +481,7 @@ Add `-d <dir>` when the index is not the nearest one, or name it once with
 | `grep '^#' file.md`                 | `zen rag docs list sections --file file.md`           |
 | `sed -n '40,80p' file.md`           | `zen rag docs show file.md --lines 40-80`             |
 | `cat file.md` (to find one section) | `zen rag docs show file.md --section "Rate limits"`   |
+| a `sed`/`show` per passage          | `zen rag docs show a.md:40-80 b.md:12-30`             |
 | `ls` the index directory            | `zen rag docs stats`                                  |
 
 ```sh
@@ -497,12 +509,12 @@ const index = await docs.DocsIndex.open(
 const project = await loadProject('./my-project', { tools: docs.docsTools(index) });
 ```
 
-| Tool          | For                                                          |
-| ------------- | ------------------------------------------------------------ |
-| `search_docs` | the passages that match, quoted with their line numbers      |
-| `list_docs`   | the documents, their headings, or their tables - no search   |
-| `grep_docs`   | every matching line, counted in full - no search             |
-| `read_docs`   | a section or a line range, verbatim and with nothing omitted |
+| Tool          | For                                                                                        |
+| ------------- | ------------------------------------------------------------------------------------------ |
+| `search_docs` | the passages that match, quoted with their line numbers                                    |
+| `list_docs`   | the documents, their headings, or their tables - no search                                 |
+| `grep_docs`   | every matching line, counted in full - no search                                           |
+| `read_docs`   | a section or a line range, verbatim and with nothing omitted; several at once with `reads` |
 
 Only `search_docs` ranks; the other three are exact, because a model told "no
 results" by a vector search has learned nothing - a ranking returns the top of a
@@ -602,8 +614,8 @@ reference and `guides/` for the task documentation.
 - Does X exist, how is it spelled, how many are there → `grep_docs`. It is
   complete; a search is not, and cannot prove absence.
 - Limits and defaults are in tables → add `kind: ["table_row"]`.
-- Then `read_docs` the lines around the hit before answering. Never answer from
-  the excerpt alone.
+- Then `read_docs` the lines around every hit before answering, all of them in
+  one call with `reads`. Never answer from the excerpt alone.
 - Never `grep`/`rg`/`cat` the tree - the tools above are local and exact.
 
 Worked: per-route rate limits are the table under "Rate limits" in

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

@@ -58,9 +58,11 @@ to open a file that is not there.
 
 It exits `1` whenever it prints a candidate, because the list is meant to be
 emptied or explained rather than skimmed. It strips urls before tokenising, skips
-a handful of English constructions that contain a slash, and leaves
-`agents/memory-instructions.md` out entirely - that file is worked examples by
-design, and `check-instructions.sh` is the check it actually needs.
+a handful of English constructions that contain a slash, and leaves the four
+copies `zen` ships (`agents/{files,fork,memory,tools}-instructions.md`) out
+entirely - they are worked examples by design, `zen check` keeps them
+byte-identical (`rules.stale`), and `check-instructions.sh` is the check memory
+actually needs.
 
 Everything it does print is either noise the script has not learned yet or a
 real finding. There is no third case. A candidate that is genuinely noise is a

package/templates/editor/.github/skills/zen-review/scripts/check-paths.sh

@@ -43,9 +43,10 @@ strip_urls() {
 # The three trees §2.5 names, prose only: a skill's own script is code the
 # sandbox runs, not text rendered into a prompt, and its paths are its own.
 #
-# `agents/memory-instructions.md` is left out on purpose. It is a copy of the
-# reference, full of worked examples, so it fails this sweep by design and
-# every run of it — and it has a check of its own that a sweep cannot make:
+# The four copies `zen` ships (files-, fork-, memory-, tools-instructions.md)
+# are left out on purpose. They are full of worked examples, so they fail this
+# sweep by design, and the project cannot edit them anyway: `zen check` reports
+# any byte that differs as `rules.stale`. Memory has a check of its own too:
 # .github/skills/zen-memory/scripts/check-instructions.sh
 files() {
     {
@@ -54,7 +55,7 @@ files() {
         for file in agents/*instructions.md; do
             if [ -f "$file" ]; then echo "$file"; fi
         done
-    } | grep -v '^agents/memory-instructions\.md$' | sort -u
+    } | grep -Ev '^agents/(files|fork|memory|tools)-instructions\.md$' | sort -u
 }
 
 # Every token in those files, urls removed first, and a sentence's full stop

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

@@ -195,7 +195,8 @@ an exit 124 that looks like a slow index.
 One container is rarely the problem. Before running several at once — a
 `zen run batch` with `--concurrency` above 1 — load **zen-sandbox-capacity** and
 run its `preflight_sandbox.sh`, which measures the VM, the container cap and the
-index and says whether the arithmetic fits.
+index and says whether the arithmetic fits. A `zen-finetune` run is the
+exception: it starts at `min(maxBatch + recheck, 16)` and halves on OOM instead.
 
 ---
 
@@ -261,7 +262,8 @@ Use the `zen sandbox` commands via terminal to inspect and manage container stat
 zen sandbox status          # Check podman version, machine status, and active containers
 zen sandbox up              # Start VM (macOS) and pull or build the required image
 zen sandbox pull            # Re-pull base image or force build of sandbox/Dockerfile
-zen sandbox clean           # Force remove all zn-* containers created by this project
+zen sandbox clean           # Force remove all zn-* containers created by this CLI
+zen sandbox clean --idle    # Only what no live run uses: stopped and orphaned ones
 zen sandbox disk            # Inspect disk space consumed by images, containers, and volumes
 ```
 
@@ -273,4 +275,6 @@ zen sandbox disk            # Inspect disk space consumed by images, containers,
 - **Permission Denied in `/workspace`:**
     - In `strict` mode without `user:`, rootless Podman uses `keep-id` to preserve host UID. If using custom `user:`, verify host directory permissions allow that UID.
 - **Disk Space Pressure:**
-    - Run `zen sandbox clean` to prune stopped session containers.
+    - Run `zen sandbox clean --idle` to prune stopped and orphaned session containers.
+- **`could not create container … exceeded num_locks`:**
+    - Every container holds one engine lock (2048 by default), stopped ones included. Run `zen sandbox clean --idle`.

package/templates/editor/.github/skills/zen-sandbox-capacity/SKILL.md

@@ -240,14 +240,14 @@ do with the machine.
 
 ## A machine spec is part of a round
 
-Record it into the round directory, next to the findings:
+Record it into the run directory, next to the findings:
 
 ```sh
 {
     echo "host      $(($(sysctl -n hw.memsize) / 1073741824)) GiB"
     podman info --format json | jq -r '.host | "vm        \(.memTotal / 1073741824 | floor) GiB · swap \(.swapTotal) · \(.cpus) cpus"'
     echo "batch     --concurrency 8"
-} > .finetune/rounds/r5/machine.txt
+} > finetune/runs/batch01-nomem-run1/machine.txt
 ```
 
 The consequence is not bookkeeping, it is validity: **token counts and