@zenera/cli 1.1.24 → 1.1.26

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

@@ -31,6 +31,8 @@ zen import   <file.zip> [dir] [--name <name>] [--force] [--no-register]
 zen sandbox  [status|up|pull|clean|disk] [options]
 zen version
 
+zen meta     <run|prompts|resume|model|dataset> [project] [args]
+
 zen faker    <serve|build|cache> [spec...]
 zen rag      schema <index|restore|ready|search|list|grep|trace|show|stats> [spec...]
 zen rag      docs <index|restore|ready|search|list|grep|show|stats> [path...]
@@ -55,6 +57,9 @@ guess a flag, and do not read them all.
 | Run reports, trajectories, what a session directory holds           | [inspect.md](./references/inspect.md)                           |
 | Reading a run yourself: the node graph, opening a node by id        | [inspect.md](./references/inspect.md) (and `zen-inspect` skill) |
 | What the agents remember, why something was recalled, forgetting    | [memory.md](./references/memory.md)                             |
+| The meta agent: `zen meta run`, stored prompts, its `--json` object | [meta.md](./references/meta.md)                                 |
+| The evaluation dataset: cases, drift, notes, drawing a sample       | [dataset.md](./references/dataset.md) (and `zen-dataset` skill) |
+| Tuning the prose on the dataset: workers, applies, STATUS.md        | [finetune.md](./references/finetune.md)                         |
 | Sharing a project: archives, what travels, importing one safely     | [export.md](./references/export.md)                             |
 | `zen faker` - a mock API from an OpenAPI/Swagger document           | [faker.md](./references/faker.md)                               |
 | `zen rag` - searching an API description, or a pile of markdown     | [rag.md](./references/rag.md)                                   |
@@ -76,6 +81,7 @@ zen import a.zip                      unpack one somebody sent, run nothing in i
 zen key ls --check                    which credentials still work
 zen models test <ref>                 whether one model actually answers
 zen models pick --embedding           the first embedder that does, on stdout
+zen meta run acme /analyze --json > analyze.json   a stored prompt, the result as JSON
 ```
 
 ## Searching documents without help
@@ -92,11 +98,13 @@ zen rag docs search -d <index-dir> "<question in natural language>"
 zen rag docs search -d <index-dir> --file "<path-pattern>" --section "<heading>" "<question>"
 zen rag docs grep -d <index-dir> "<exact string>" --file "<path-pattern>"
 zen rag docs show -d <index-dir> "<file>" --section "<heading>"
+zen rag docs show -d <index-dir> "<doc-1>:<a>-<b>" "<doc-2>#<heading>"   # several in one call
 ```
 
 Start with one ordinary hybrid question. It is the best default for concepts and
 open questions. Search returns candidates, not proof: read the quoted lines,
-then use `show` or `grep` before claiming a fact is present or absent.
+then use `show` or `grep` before claiming a fact is present or absent. Read
+every passage you will cite with ONE `show` naming them all, not one call each.
 
 When the first answer is from the wrong product area, version, file, or heading,
 ask the same question again with `--file` and then `--section`. A bare `--file`

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

@@ -0,0 +1,34 @@
+# `zen meta dataset` - the cases a project is evaluated on
+
+The project's dataset lives in `dataset/` and only this command writes it. The
+rules for reading cases out of a source, anchors, drift and sampling are in the
+**zen-dataset** skill; this page is the command surface.
+
+```sh
+zen meta dataset [status]                    # revision, counts, drift summary
+zen meta dataset ls [filters]                # one row per case
+zen meta dataset show <id>[@rev]...          # whole cases, now or at a revision
+zen meta dataset log [id...]                 # changes and notes, with their sessions
+zen meta dataset drift [--all]               # cases whose source section moved
+zen meta dataset apply <file> --why "…"      # write a proposal; --partial, --dry-run
+zen meta dataset update <id> --why "…"       # --set k=v, --rubric-add/-edit/-drop, --tag-add/-drop, --override
+zen meta dataset retire|restore <id>... --why "…"
+zen meta dataset reanchor <id> --why "…"     # --file, --heading "A > B", --pointer /x/0
+zen meta dataset ignore <file> --why "…"     # --heading or --pointer; --drop to undo
+zen meta dataset note <id>... -m "…"         # --kind, --run, --verdict, --rubric r1=pass,...
+zen meta dataset sample [filters]            # -n, --seed, --by, --weight, --order, --format, -o
+zen meta dataset export [id...] [filters]    # --format cases|batch, -o
+```
+
+- The project is the one you are in, `--project <name|dir>`, or
+  `zen meta <project> dataset …`.
+- Every verb takes the global `--json`. `sample --format json` is the record
+  that reproduces a draw.
+- Writes take `dataset/.lock` and need `--why`. Reads and notes take no lock.
+- `sample --format batch -o <file>` is `zen run batch` input, never with a
+  rubric. Media paths are written relative to `-o`.
+- Exit codes: 2 for a wrong invocation (an unknown verb, flag or class),
+  3 for a proposal or anchor that cannot be applied - and then nothing is written.
+- Changes and notes are stamped with the `zen meta` session and prompt that ran
+  them (`ZENERA_META_SESSION`, `ZENERA_META_PROMPT`); `log` prints how to
+  resume each session this machine still holds.

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

@@ -0,0 +1,137 @@
+# `zen meta finetune` - tuning the project, one case at a time
+
+Trains the project's prose - prompts, skills, house rules - on every case of
+its dataset (`zen meta dataset`). Nothing here touches model weights.
+
+```sh
+zen meta finetune start [-N 4] [-M 4] [--tries 4] [--mem-tries 3] [--merge-every 3] [--seed 1] \
+    [--recheck 3] [--budget 1500] [--max-growth 50] \
+    [--skill-cap 12000] [--max-skills 10] \
+    [--class <c>] [--id <glob>] [--rubric yes|no] [--limit <n>] [--more <n>] [--force]
+zen meta finetune [status]
+zen meta finetune stop
+zen meta finetune session <case>
+zen meta finetune gate <apply dir>   # would this apply pass? run by the apply agent
+```
+
+## What one case goes through
+
+```
+without memory, up to --tries times:
+    zen run (empty memory)  ->  /analyze  ->  done? go on : park until the next apply
+with memory, up to --mem-tries times, from the memory the passing run wrote:
+    zen run  ->  /analyze  ->  done? completed : park until the next apply
+tries used up  ->  difficult
+```
+
+- **N workers**, each training one case at a time. Cases come in the dataset's
+  own order: classes taking turns, cases with a rubric first, then seeded
+  random. Cases added to the dataset are picked up as it goes.
+- **A parked case gives its worker back**, so another case runs while it waits
+  for an apply; once woken, it takes a worker before any new case does.
+- **Applies are batched.** Parked cases' improvement requests are applied
+  together by `/finetune-apply` once **M** cases are parked, or once nothing is
+  running and no case is left to start. `-M` is at least 2 (`-M 1` needs
+  `--force`): one case is an anecdote. No run starts during an apply; runs in
+  flight finish first. Each apply gets its own `applies/<NNN>/APPLY.md`: every
+  request and improvement, what was decided for each, the apply agent's account
+  of what it changed and why, every file changed with its diff, and the gates.
+- **An apply passes two gates, or is undone.** `zen check` must pass. What
+  every call reads - house rules, prompts, preloaded skills, the skill index,
+  summed over the agents - may grow by at most `--budget` bytes, and by nothing
+  once it is `--max-growth` percent over the start; no skill may pass
+  `--skill-cap` and no agent see more than `--max-skills`. A failed gate undoes
+  the edit and the agent tries once more, told why. A second `zen check`
+  failure stops the tuning; a second budget failure only undoes the apply, and
+  the parked cases carry on on the prose they had. `gate <apply dir>` runs both
+  gates on an apply in progress, against the same numbers, so the agent can cut
+  before it finishes.
+- **An apply tidies up after itself.** Every file it touches loses its
+  duplicates, contradictions and stacked exceptions in the same edit; the
+  bytes that frees count against its budget. `growth.json` tells it which
+  files grew most since the tuning began.
+- **Then `--recheck` completed cases run again on the new version** - without
+  memory, as ordinary work on a worker, ahead of new cases; nothing waits for
+  them. One that fails both of its two tries has regressed: its feedback
+  (`<case>@recheck-<apply>`) joins the improvement queue, the next apply
+  repairs it, and the case is rechecked first after that. Nothing is undone.
+  A case sends at most two such requests; after that a regression is only
+  reported, so the tuning ends.
+- **One case adds nothing.** A new rule, or a procedure moved into a skill,
+  needs two cases asking for it. With one, the apply may only edit, move or
+  delete without growing the prose; anything else is `deferred` and offered to
+  every later apply (`deferred.json`) until a second case asks.
+- **Prose cannot fix everything.** When all an apply could say of a request is
+  `structural` - a tool, a skill binding, the dataset - the case is difficult
+  at once, reason `structural: ...`, instead of trying again on the same prose.
+- **A broken rubric is the dataset's to fix.** The analysis grades a line
+  `invalid` when it says how one implementation did it rather than what is
+  right, with a `specification` improvement saying how it should read. No
+  apply sees those, an `invalid` line never keeps a case from completing, and
+  a case whose only findings are `specification` is difficult at once, reason
+  `specification: ...`. STATUS.md lists them under **Rubric problems**.
+- **A skill must be loaded.** When an apply makes or changes a skill for a
+  case, the case's next run must load it. If it does not, the run says so
+  (`missedSkills`), the analysis is told (`missed-skills=`), and the next apply
+  fixes the skill's description.
+- **No run shares a memory.** Every try runs on its own private directory:
+  empty without memory, a copy of the case's passing memory with it. A case
+  whose with-memory run passes keeps a copy in `memories/submitted/`; every
+  `--merge-every` kept memories are merged, with the last merge, into
+  `memories/merged/mNN/` - numbered, never rewritten, each listing the cases it
+  holds. Whatever is left is merged when the tuning ends.
+- **Each analysis starts from a brief.** The loop runs what every analysis
+  reads - the case, the graph, the run's files, the prose, the earlier tries
+  and the diff since the last one - writes it to the try's `brief.md`, and
+  hands it to `/analyze` in the prompt (`zen meta run --prompt-file`). Each try
+  is analyzed in a session of its own; `session <case>` prints the command to
+  resume the latest one.
+- **So does each apply.** Its `brief.md` holds the requests and held-back
+  improvements grouped by the file they name, the editor skills to load, the
+  earlier tries of the same cases with their decisions, the budget, and the
+  files to edit. An attempt that ends without a decision for every
+  improvement is undone (`missing.md`) and tried once more.
+- **Stop and resume freely.** `stop` (or Ctrl-C once) lets the steps in flight
+  finish, then exits; Ctrl-C twice kills them. `start` again carries on: every
+  step's result is on disk, and nothing finished is repeated.
+- **`--limit` and `--more` are for one start**, never kept in `loop.json`.
+  `--limit <n>` cuts the order to its first n cases: once those have a result,
+  that start ends. `--more <n>` takes at most n cases of any kind - new,
+  part-way or failed - in the order, so `start --more 4` again takes the next
+  four.
+- `start` refuses a dataset that has drifted from its sources - run `/dataset`
+  first, or pass `--force`.
+
+## What it leaves
+
+```
+finetune/
+    STATUS.md            the whole tuning: summary (spend per phase, tuning and memory
+                         effect), workers and what each is doing now, queue, applies,
+                         cases - generated, rewritten every second while it runs
+    loop.json            the settings; flags on start update it
+    events.jsonl         every step, in order
+    cases/<id>/
+        FEEDBACK.md      that case: rubric, latest analysis, decisions, history, metrics
+                         of every try and how they moved - generated
+        r<rev>/result.json            completed or difficult, once it ends
+        r<rev>/<NN>-<nomem|mem>/      one try: request.json, run.json, memory/,
+                                      brief.md, session, feedback.json, analysis.md,
+                                      run.log, analyze.log
+    applies/<NNN>/       APPLY.md (generated), inputs.json, deferred.json, budget.json,
+                         growth.json, gate.json, brief.md, apply.log, check.log,
+                         changes.md, decisions.json, diff.patch, cost.md; budget.md
+                         or missing.md when an attempt was undone
+    rechecks.json        every recheck: case, apply, state, tries, the request it sent
+    rechecks/<NNN>/<id>/<NN>-nomem/   one recheck try, as a case's try
+    baseline.json        what the agents read when the tuning began
+    memories/            submissions.jsonl, merges.jsonl, submitted/<case>@r<rev>/, merged/mNN/
+    systems/             systems.jsonl + a copy of agents.yaml and agents/ per version
+```
+
+Open `STATUS.md` first; every row links to the detail behind it. Its Summary
+says whether the tuning is working: the fixes, as a case's first try without
+memory against its passing one, and memory, as the passing try without memory
+against the passing try with it - tokens, calls, tool errors and time, totalled
+over the same cases. A case's `FEEDBACK.md` has the same metrics per try and per
+model, each try against the one before it in its phase.

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

@@ -13,7 +13,8 @@ Four ways to read one run, for two different readers.
 | `report`              | you     | `report.html` - every message, payload and cost |
 | `graph`               | a model | the whole trajectory as one Mermaid flowchart   |
 | `node <id...>`        | a model | those nodes in full, payloads resolved          |
-| `ask <id> <question>` | you     | that call replayed to a model, with a question  |
+| `ask <id> <question>` | a model | one replayed answer on stdout; never prompts    |
+| `ask [<id>]`          | you     | a conversation with that call, at a terminal    |
 
 `report` is the default, so `zen inspect` on its own is unchanged.
 
@@ -26,8 +27,10 @@ Four ways to read one run, for two different readers.
 | `--dir <dir>`           | all           | A run directory, as `zen run --json` reports it      |
 | `--memory <dir>`        | report, graph | Read this memory instead of the one the run recorded |
 | `--model <ref>`         | ask           | Answer with this model instead of the run's own      |
+| `--question-file <f>`   | ask           | Read the question from a file; `-` is stdin          |
 | `--part <name>`         | node          | Print this part in full. Repeatable, prefix-matched  |
 | `--full`                | node          | Print every part, the recorded `request` included    |
+| `--raw`                 | node          | One `--part` of one node, unframed - for a pipe      |
 | `--open`                | report        | Open the report in a browser                         |
 | `--rebuild`             | report        | Rebuild `report.html` from the recorded state        |
 | `--no-timing`           | graph         | Leave the clock off the graph                        |
@@ -39,10 +42,13 @@ session that has one. "Newest" means the newest session that actually recorded a
 run, not simply the newest session: a session exists before its first run, so
 the latest one is routinely empty.
 
-**Neither `node` nor `ask` has room for a run.** Every positional `node` takes is
-a node id, and `ask` takes one id and then your question, so name the run with
-`--run`, `--session` or `--dir` - `zen inspect node <run> n13` reads the run id
-as an id and fails.
+**Neither `node` nor `ask` has room for a positional run.** Every positional
+`node` takes is a node id, and every positional `ask` takes is the id followed
+by the question, so name the run with `--run`, `--session` or `--dir`.
+`zen inspect node <run> n13` reads the run id as an id and fails. `ask`
+without a question is the interactive mode (below) and needs a terminal; a
+script, `--json` call or agent passes the id and the question and never sees a
+prompt.
 
 For `report` and `graph` the positional is a run id unless it contains a `/`, in
 which case it is read as a run directory. A run id is a stamp and never has a
@@ -100,13 +106,13 @@ zen inspect graph --dir "$(zen run --json 'fix the tests' | jq -r .run.dir)"
 %%   n24 joins docs (researcher, ok), tests (researcher, ok)
 %% compacted 3 nodes are marked "hidden by" a later summary
 %%           they still ran; the model simply stopped seeing them
-%%
+%% ---
 %% reading   nN is a node id · t+ counts from the start of the turn
 %%           dotted edges are fork/join and calls answered out of order
 %%           nodes are declared in run order; every edge is in one block below
 %% detail    zen inspect node n1 n2 n5..n9 --dir <run dir>
 %% why       zen inspect ask n5 "why did you do that?" --dir <run dir>
-%%
+%% ---
 flowchart TD
     n11["n11 llm claude-opus-5 · 4.2k in 310 out · calls run_command · t+32.7s"]
     n12["n12 run_command npm test -- --run · t+34.7s · took 3.0s"]
@@ -181,10 +187,23 @@ zen inspect node n11 --full --dir <run dir>
 ```
 
 `--part` matches a prefix, so `--part call` catches a part named
-`call run_command (toolu_01A…)` without your typing the id. Naming a part the
-node does not carry is an error listing the ones it does - nothing is ever
+`call run_command (toolu_01A…)` without your typing the id. A name no node
+carries is reported in a `#` line under the header; when none of the names
+matches it is an error listing the parts the nodes do carry - nothing is ever
 elided in silence.
 
+An `llm_call` also carries two parts read out of its request and held back the
+same way: `tools`, the names of the tools that call was offered, and
+`messages`, the conversation it saw, one clipped line per message with its tool
+calls indented under it. `--raw` prints one part of one node and nothing else -
+no `#` header, no frame - so it pipes:
+
+```
+zen inspect node n11 --part tools --dir <run dir>
+zen inspect node n11 --part messages --dir <run dir>
+zen inspect node n11 --part request --raw --dir <run dir> | jq '.tools[].name'
+```
+
 Two `#` lines come first - which run, how many of its nodes you asked for, and
 a reminder of what part text is. Then each node is framed, and each payload
 inside it is framed with its own byte count:
@@ -214,10 +233,43 @@ ready to paste.
 
 `node` shows what a model was given. `ask` asks the model what it made of it.
 
+`ask` has two modes, and which one runs is decided by one thing: whether the
+question is given.
+
+| Mode        | Trigger                                                | For                    | Behaviour                                                                                        |
+| ----------- | ------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------ |
+| One-shot    | a question on the line, `--question-file`, or `--json` | a script or a model    | no banner, no prompt, no picker; one model call, the raw answer on stdout and nothing else, exit |
+| Interactive | no question                                            | a person at a terminal | asks for whatever is not named - session, run, `llm_call` - then the question; a conversation    |
+
+One-shot never reads the terminal, even when there is one: an unnamed run is
+the newest, not a picker, so name it with `--dir`, `--run` or `--session`.
+Interactive without a terminal is a usage error, never a wait.
+
 ```sh
 zen inspect ask n11 "why run python -c when the skill says npm test?" --dir <run dir>
 ```
 
+In the interactive mode only calls with a recorded request appear in the node
+list. Each question and Markdown answer is drawn in its own labelled panel, with
+the model and token counts on stderr. It keeps asking on the same node,
+retaining earlier exchanges as context, until an empty question is submitted.
+
+```sh
+zen inspect ask                       # pick everything
+zen inspect ask n11 --dir <run dir>   # straight to the questions
+```
+
+A question with quotes, apostrophes, backticks, `$` or more than one line goes
+in a file, so no shell parses it. The file is the whole question; `-` reads it
+from stdin. Words on the line as well are an error.
+
+```sh
+zen inspect ask n11 --question-file .tmp/ask/<run-id>/n11-tests.md --dir <run dir>
+```
+
+Do not build the question with `"$(cat <<'EOF' ... )"`: macOS `/bin/bash` 3.2
+misparses a heredoc inside `$( )` when its body holds an apostrophe.
+
 The `llm_call` node named by the id is replayed: its recorded system prompt, its
 messages and its tool schemas, exactly as the provider received them, with the
 answer it gave put back as its own turn and your question as one more after
@@ -247,8 +299,8 @@ command says so on stderr, because an answer from a different model is a second
 opinion rather than the model examining itself. Either way the run's full system
 prompt goes to that provider.
 
-`graph`, `node` and `ask` print no banner. Their stdout is the answer, whole and
-ready to paste.
+`graph`, `node` and non-interactive `ask` print no banner. Their stdout is the
+answer, whole and ready to paste.
 
 ## Where it comes from
 

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

@@ -18,16 +18,21 @@ skill.
 
 ## Subcommands
 
-| Command                   | What it does                                |
-| ------------------------- | ------------------------------------------- |
-| `zen memory stats`        | Size, vocabulary, whether it is embedded    |
-| `zen memory ls`           | Nodes, newest first. Changes nothing        |
-| `zen memory search <q>`   | Recall it, the way an agent does. Ranked    |
-| `zen memory grep <pat>`   | Every node containing it, with the lines    |
-| `zen memory show <id>`    | One node in full, with what it links to     |
-| `zen memory export [f]`   | The whole graph as one HTML page            |
-| `zen memory merge <dir…>` | Fold other memories into this one           |
-| `zen memory forget <id…>` | Remove nodes, their vectors and their files |
+| Command                   | What it does                                        |
+| ------------------------- | --------------------------------------------------- |
+| `zen memory stats`        | Size, vocabulary, whether it is embedded            |
+| `zen memory ls`           | Nodes, newest first: kind, audience, revision, text |
+| `zen memory search <q>`   | Recall it, the way an agent does. Ranked            |
+| `zen memory grep <pat>`   | Every node containing it, with the lines            |
+| `zen memory show <id>`    | One node in full, with what it links to             |
+| `zen memory diff <base>`  | What this memory holds that `<base>` did not        |
+| `zen memory export [f]`   | The whole graph as one HTML page                    |
+| `zen memory merge <dir…>` | Fold other memories into this one                   |
+| `zen memory forget <id…>` | Remove nodes, their vectors and their files         |
+
+`ls` cuts the text to the terminal's width; piped, or run by an agent, it prints
+all of it. Never read `graph.json` directly - `ls --json` is the same nodes in a
+shape that does not change under you.
 
 | Flag                          | Meaning                                        |
 | ----------------------------- | ---------------------------------------------- |
@@ -99,6 +104,24 @@ remembered file it could not read - too big, binary, missing - is named rather
 than silently skipped, because a file that went unsearched must not pass for one
 with no match.
 
+## `diff` says what a run did to a copy
+
+A run started from a copy of a memory leaves the whole copy behind, so `ls` on
+it shows everything the base held too. `diff` shows only what changed:
+
+```sh
+zen memory diff <candidate> --dir <batch-dir>/<id>/memory
+```
+
+- **added** - each with the nearest node `<base>` held and its score. One
+  `merge` would fold onto it is marked a twin: the run said again what the
+  memory already held.
+- **revised** - same id, new revision.
+- **used** - nodes `memory_load` returned, and how often: what the run read.
+- **removed**, and new `SUPERSEDES` edges.
+
+It reads both sides without the lock, so it works on a memory a run is writing.
+
 Superseded nodes are left out unless you ask: `--all` includes them marked, and
 `--stale` narrows to them alone.
 

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

@@ -0,0 +1,61 @@
+# `zen meta` - the meta agent, on this project
+
+```
+zen meta run [project] "<question>"        ask it something
+zen meta run [project] /<name> [words]     run .github/prompts/<name>.prompt.md
+zen meta prompts [project]                 list the stored prompts
+zen meta resume [project] [session]        carry on a run that stopped
+zen meta model [ref]                       show or set the model it uses
+zen meta dataset <verb>                    see dataset.md
+```
+
+`zen meta --help` has every option.
+
+## `--json`
+
+`zen meta run --json` prints ONE object on stdout when the run ends:
+
+```json
+{
+    "project": "/path/to/project",
+    "provider": "vertex",
+    "model": "vertex/gemini-3.8-flash",
+    "sessionId": "…",
+    "exitCode": 0,
+    "resumes": 0,
+    "usage": {},
+    "tokens": {
+        "calls": 12,
+        "inputTokens": 0,
+        "cachedInputTokens": 0,
+        "outputTokens": 0,
+        "reasoningTokens": 0
+    },
+    "answer": "the final answer, as markdown",
+    "answerFile": "/path/to/project/.tmp/logs/meta.<when>.md"
+}
+```
+
+`tokens` is summed over every model call of the run; `usage` is the meta
+agent's own end-of-session summary, passed through as it came, and may be absent.
+
+- Progress goes to stderr as plain lines: no box, no animation, no status row.
+  stdout carries the object and nothing else, so redirect it to keep it:
+
+    ```
+    zen meta run acme /analyze --json > analyze.json
+    zen meta run acme /analyze --json > analyze.json 2> analyze.log
+    ```
+
+- Nothing is asked. A `run` with no question, no `/<name>` and nothing piped
+  in is a usage error (exit 2) that lists the prompts, not a menu.
+- A run the meta agent ends in failure still prints the object, then exits 1.
+  Check `exitCode`; `sessionId` is what `zen meta resume` takes. A run that
+  never starts (no key, bad model) prints no object, only the error.
+- `--dry-run --json` gives `{project, provider, model, from, command, env}`,
+  secrets masked, and runs nothing.
+- `zen meta prompts --json` gives `[{name, description, path}]`;
+  `zen meta model --json` gives `{model, from, sources}`.
+
+The answer is also saved as markdown on every run, with or without `--json`;
+`answerFile` is its path.

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

@@ -1,7 +1,7 @@
 # Models - `zen models`
 
 ```
-zen models <providers|ls|search|show|test|pick> [ref] [options]
+zen models <providers|ls|search|show|test|pick|browse> [ref] [options]
 ```
 
 Alias: `model`.
@@ -21,6 +21,7 @@ but a credential.
 | `zen models show <ref>`     | One model, every field the vendor gave                 |
 | `zen models test <ref> …`   | One real minimal call per ref, and a verdict           |
 | `zen models pick`           | The first ref that answers, printed on stdout          |
+| `zen models browse`         | Interactive TUI for a person; needs a terminal         |
 
 Filters, on `ls` and `search`: `--chat`, `--embeddings`, `--images`, `--audio`,
 `--tools`, `--vision`, `--free`, `--min-context <n>`, `--provider <name>`,
@@ -28,6 +29,9 @@ Filters, on `ls` and `search`: `--chat`, `--embeddings`, `--images`, `--audio`,
 
 `pick` requires `--chat` or `--embedding`, and takes `--provider` and `--limit`.
 
+`browse` is for a person at a terminal and refuses without one (exit 2). An
+agent wants `ls --json`, `search` or `pick` instead.
+
 ## Where the lists come from
 
 The providers themselves, cached for a day in `~/.zenera/neo/catalog`. When a

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

@@ -42,12 +42,10 @@ read too, in filename order, and prepended to every agent - or, with
 `requires: [<capability>]` in its frontmatter, to every agent that has the
 capability it is about. 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.
+Memory's are not written from scratch: `agents/memory-instructions.md` is
+shipped by `zen`, so a copy that was lost or went stale is restored rather than
+rewritten - `zen check` reports it (`memory.uninstructed`, `rules.stale`) and
+`zen check --fix` writes it back.
 
 The project's own files are never overwritten - `--force` is what allows
 writing into an occupied directory, and the files already there stay. The

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

@@ -558,6 +558,7 @@ ordinary hybrid search and narrow by file or section.
 zen rag docs list <files|sections|tables> [-f <pattern>] [-s <section>]
 zen rag docs grep <pattern> [-f <pattern>] [--regex] [--case-sensitive]
 zen rag docs show <file> [--section <name>] [--lines <from-to>]
+zen rag docs show <target>... [--max-lines <n>]
 ```
 
 `list sections` gives every heading with the lines it spans, which is how a
@@ -566,6 +567,23 @@ 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 several passages in one call
+
+Name every passage you will read or cite in **one** `show`, as
+`<document>:<a>-<b>`, `<document>:<a>` or `<document>#<heading>` - the form a
+citation is written in, so a citation pastes back unchanged:
+
+```sh
+zen rag docs show -d <index-dir> "<doc-1>:24-60" "<doc-2>:25-40" "<doc-3>#<heading>"
+```
+
+Each target prints under a header that is itself a target, in the order given;
+overlapping ranges in one document print once. A missing document or heading is
+reported in place and the rest still print (exit 1 only when none could be
+read). `--max-lines` (default 400) is shared fairly between targets, and a cut
+block ends with the target that continues it. `--json` returns
+`{results, printed, failed}`. `--section` and `--lines` read one document only.
+
 ### Reading a complete section or table
 
 Search finds relevant passages, not necessarily every row of a table. When the
@@ -596,12 +614,12 @@ the answer needs every row.
 
 `@zenera/rag/docs/tools` exports four tools in the group `docs`:
 
-| 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 |
-| `read_docs`   | A section or a line range, verbatim and complete                |
+| 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  |
+| `read_docs`   | A section or a line range, verbatim; several at once via `reads` |
 
 Only `search_docs` ranks. Every answer carries line numbers and `read_docs`
 takes them, which is the loop the subject exists for: find the passage, read

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

@@ -1,7 +1,7 @@
 # The sandbox - `zen sandbox`
 
 ```
-zen sandbox [status|up|pull|clean|disk] [options]
+zen sandbox [status|top|up|pull|clean|disk] [options]
 ```
 
 Shell commands run in a container over the session workspace, never on the
@@ -9,18 +9,30 @@ 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.
 
-| Subcommand | What it does                                                   |
-| ---------- | -------------------------------------------------------------- |
-| `status`   | What is installed, running and pulled. Changes nothing         |
-| `up`       | Install if asked, start the machine, pull or build the image   |
-| `pull`     | Just the image: pulled, or built from the project's Dockerfile |
-| `clean`    | Remove every container this CLI created                        |
-| `disk`     | What the engine and every known project occupy                 |
-
-| Flag                    | Meaning                                 |
-| ----------------------- | --------------------------------------- |
-| `--project <name\|dir>` | Which project the image comes from      |
-| `--image <ref>`         | Use this image instead of the project's |
+| Subcommand | What it does                                                        |
+| ---------- | ------------------------------------------------------------------- |
+| `status`   | What is installed, running and pulled. Changes nothing              |
+| `top`      | Memory and cpu: this computer, the machine, every running container |
+| `up`       | Install if asked, start the machine, pull or build the image        |
+| `pull`     | Just the image: pulled, or built from the project's Dockerfile      |
+| `clean`    | Remove every container this CLI created                             |
+| `disk`     | What the engine and every known project occupy                      |
+
+| Flag                    | Meaning                                                    |
+| ----------------------- | ---------------------------------------------------------- |
+| `--project <name\|dir>` | Which project the image comes from                         |
+| `--image <ref>`         | Use this image instead of the project's                    |
+| `--once`                | `top`: print one report instead of the live screen         |
+| `--interval <seconds>`  | `top`: how often the live screen refreshes (default 2)     |
+| `--brief`               | `top`: the figures without the notes saying what they mean |
+
+`top` draws a live screen only when a person is at a terminal. From an agent,
+a script or with `--json` it measures twice a second apart (cpu needs an
+interval) and prints once, so `zen sandbox top --json` is the form to read:
+`host.vm` is what the machine costs the computer (`footprint` is Activity
+Monitor's figure on macOS), `machine` is Linux's own split into `used`, `cache`
+and `free`, `containers[]` carries `cpu` (percent of one core), `memory`,
+`limit` and `orphaned`, and `hints[]` says what to do about it.
 
 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
@@ -119,7 +131,16 @@ 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
-container left on a bad rootfs.
+container left on a bad rootfs. `--idle` removes only what no live run is using:
+stopped containers, and running ones whose run was killed before stopping them
+(`zen sandbox status` marks those `orphaned`).
+
+`could not create container … exceeded num_locks (2048)` means the engine is out
+of locks: every container holds one, stopped ones included, and `persist: true`
+leaves one stopped per session. `zen run` and `zen run batch` check this before
+the first model call and exit `5` when the engine cannot hold them (a batch needs
+one per item it runs at once). `zen sandbox status` shows a `locks` row when few
+are left; `zen sandbox clean --idle` frees them.
 
 For complete container architecture, the `sandbox:*` tools, mount rules, and
 hardening details, load the `zen-sandbox` skill (`.github/skills/zen-sandbox/SKILL.md`).