@zenera/cli 1.1.22 → 1.1.24

package/dist/validate.js

@@ -1,4 +1,4 @@
-import { EXA_GROUP, FileSkillProvider, SANDBOX_MOUNT, Sandbox, exaTools, frontmatter, projectRegistry, readProjectConfig, sandboxTools, selectTools, toList, workspaceTools, } from '@zenera/neo';
+import { EXA_GROUP, FileSkillProvider, SANDBOX_MOUNT, Sandbox, exaTools, fileTools, frontmatter, projectRegistry, readProjectConfig, sandboxTools, selectTools, toList, } from '@zenera/neo';
 import { existsSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
@@ -7,7 +7,7 @@ import { resolveBuild } from "./image.js";
 import { SHAPES, envNames, form } from "./keys.js";
 import { probeModels } from "./liveness.js";
 import { BuildError, ensurePodmanReady } from "./podman.js";
-import { staleShared } from "./scaffold.js";
+import { ownVersion, staleShared } from "./scaffold.js";
 // Mirrors the loader's own constants (`packages/neo/src/project/load.ts`).
 // Duplicated rather than exported, because a check that agreed with the loader
 // by construction could not report that the two had diverged.
@@ -35,10 +35,17 @@ const FILE_TOOLS = [
     'find_files',
     'write_file',
     'apply_patch',
+    'copy_file',
     'move_file',
     'delete_file',
 ];
-const FILE_WRITE_TOOLS = new Set(['write_file', 'apply_patch', 'move_file', 'delete_file']);
+const FILE_WRITE_TOOLS = new Set([
+    'write_file',
+    'apply_patch',
+    'copy_file',
+    'move_file',
+    'delete_file',
+]);
 function activeFileTools(selectors) {
     const active = new Set();
     if (!selectors?.length) {
@@ -607,7 +614,7 @@ export function availableTools(root, config) {
     // Constructed, not started: a pool creates its container on the first
     // command, so naming one here costs nothing and needs no container engine.
     return [
-        ...workspaceTools({
+        ...fileTools({
             root,
             mount: config.sandbox?.workdir ?? SANDBOX_MOUNT,
         }),
@@ -1252,6 +1259,7 @@ function checkSandbox(root, config, record, add) {
     if (!ok) {
         return undefined;
     }
+    checkPin(join(root, file), file, add);
     try {
         return resolveBuild(root, config.sandbox);
     }
@@ -1265,6 +1273,72 @@ function checkSandbox(root, config, record, add) {
         return undefined;
     }
 }
+/** `@zenera/cli`, and the version after it when the line pins one. */
+const ZENERA_INSTALL = /@zenera\/([a-z0-9-]+)(?:@([^\s\\'"]+))?/g;
+/**
+ * Whether the Dockerfile's `@zenera/*` installs name this `zen`.
+ *
+ * `zen init` writes the version it was run by and never rewrites the file
+ * again — the scaffold keeps what the project already has — so the pin is fixed
+ * at creation and falls behind the host on the next upgrade. Nothing else
+ * notices: the file parses, the image builds, and the container simply holds a
+ * different `zen` than the session outside it, which is a mismatch that shows
+ * up as a tool behaving unlike its documentation.
+ *
+ * Read rather than run, so it is true on the laptop with no container engine —
+ * the one `--no-sandbox` leaves with no other word on the subject.
+ */
+function checkPin(path, rel, add) {
+    let text;
+    try {
+        // Existence is already a finding; an unreadable file is not worth a
+        // second one, and a throw here would cost every check after it.
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        return;
+    }
+    const mine = ownVersion();
+    const stale = new Set();
+    const loose = new Set();
+    for (const line of text.split('\n')) {
+        // A comment naming the package is prose about the pin, not the pin.
+        if (/^\s*#/.test(line)) {
+            continue;
+        }
+        for (const match of line.matchAll(ZENERA_INSTALL)) {
+            const name = `@zenera/${match[1]}`;
+            const pinned = match[2];
+            if (pinned === undefined) {
+                loose.add(name);
+            }
+            else if (pinned !== mine) {
+                stale.add(`${name}@${pinned}`);
+            }
+        }
+    }
+    const fix = `pin them to ${mine}, the version \`zen --version\` reports`;
+    if (stale.size > 0) {
+        add({
+            severity: 'warning',
+            code: 'sandbox.pin.stale',
+            where: rel,
+            message: `installs ${[...stale].join(', ')}, but this \`zen\` is ${mine} — the CLI an ` +
+                'agent runs inside the container is not the one that built the session',
+            fix,
+        });
+    }
+    if (loose.size > 0) {
+        add({
+            severity: 'warning',
+            code: 'sandbox.pin.absent',
+            where: rel,
+            message: `installs ${[...loose].join(', ')} unpinned, so the next image build takes ` +
+                'whatever is current and drifts away from the host without saying so',
+            fix,
+        });
+    }
+}
 /** Written by the smoke test and read back, to prove the mount is real. */
 const SMOKE = 'zen-check';
 /**
@@ -1476,6 +1550,21 @@ function checkModels(root, config, keys, add, probe = false) {
             if (resolved !== name) {
                 report.ref = resolved;
             }
+            // Reported here rather than left to the probe below: a knob for the
+            // wrong vendor is a config mistake that wants naming whether or not
+            // there is a credential to build the model with.
+            if (role === 'model') {
+                for (const stray of registry.knobs(ref)) {
+                    add({
+                        severity: 'error',
+                        code: 'model.knob',
+                        where: whereFor(config, role, name, usedBy),
+                        message: `\`${stray.knob}\` means nothing to a ${stray.target} model — ` +
+                            'it would never reach the request',
+                        fix: `this model takes: ${stray.supported.join(', ')}`,
+                    });
+                }
+            }
         }
         catch (err) {
             add({

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.22",
+    "version": "1.1.24",
     "description": "Command-line front end for @zenera/neo: agentic projects you can run, share and commit.",
     "keywords": [
         "agents",
@@ -48,14 +48,20 @@
         "prepack": "tsc -b"
     },
     "dependencies": {
-        "@inkjs/ui": "^2.0.0",
-        "ink": "^7.1.1",
-        "react": "^19.2.8",
-        "@zenera/neo": "^1.1.22",
         "@anthropic-ai/sdk": "^0.120.0",
         "@google/genai": "^2.18.0",
+        "@inkjs/ui": "^2.0.0",
         "@openrouter/sdk": "^1.2.80",
+        "@zenera/neo": "^1.1.24",
         "google-auth-library": "^10.0.0",
-        "openai": "^6.0.0"
+        "ink": "^7.1.1",
+        "openai": "^6.0.0",
+        "react": "^19.2.8",
+        "yauzl": "^3.4.0",
+        "yazl": "^3.3.1"
+    },
+    "devDependencies": {
+        "@types/yauzl": "^3.4.0",
+        "@types/yazl": "^3.3.1"
     }
 }

package/templates/editor/.github/copilot-instructions.md

@@ -47,7 +47,8 @@ visible in `agents.yaml` and that `zen check` does not report.** Before
 reviewing or changing a project, list the capabilities it has turned on and load
 the editor skill for each one - `zen-memory` for a `memory:` block,
 `zen-sandbox` for sandbox configuration or shell tools, `zen-rag-schema` or
-`zen-rag-docs` for an index, `zen-cli` always. A capability that is already
+`zen-rag-docs` for an index, `zen-sandbox-capacity` before any `zen run batch`,
+`zen-cli` always. A capability that is already
 configured and already passing `zen check` is exactly the case that looks
 finished and is not: the obligation lives in the skill, so a review that never
 opens the skill cannot find what is missing. This applies whatever prompted the
@@ -810,7 +811,7 @@ committed shows up as a skill with no files.
 ### 3.5 Tools
 
 A tool is what an agent can _do_ rather than say. `zen run` provides three
-groups - the workspace tools (§3.6), the sandbox tools (§3.7) and the web tools
+groups - the file tools (§3.6), the sandbox tools (§3.7) and the web tools
 (§3.8) - and `agents.yaml` decides which agent holds which. Nothing else reaches
 the machine, so `tools:` is the whole permission model: an agent that does not
 name a tool cannot use it, whatever its prompt says.
@@ -846,6 +847,7 @@ them cannot see a file at all.
 | `find_files`  | Paths containing a substring, case-insensitive                                           |
 | `write_file`  | Creates or overwrites a whole file, making parent directories                            |
 | `apply_patch` | Edits by surrounding context rather than line numbers; several files atomically          |
+| `copy_file`   | Copies, bytes never touching the context; the source may be a read-only mount            |
 | `move_file`   | Moves or renames; refuses to clobber without `overwrite`                                 |
 | `delete_file` | Deletes; a directory needs `recursive`                                                   |
 
@@ -876,8 +878,8 @@ agents:
       tools: [files:*]
 
     - name: reviewer
-      # Everything except the four that can change something.
-      tools: [files:*, -write_file, -apply_patch, -move_file, -delete_file]
+      # Everything except the five that can change something.
+      tools: [files:*, -write_file, -apply_patch, -copy_file, -move_file, -delete_file]
 ```
 
 Selectors apply in the order written, so a `-` line reads as an exception to the
@@ -1638,7 +1640,9 @@ over one connection.
 | `includeThoughts`       | gemini                        | Thought summaries; default `true`                                                                          |
 | `routing` / `fallbacks` | openrouter                    | Upstream provider preferences, and models to fall back to - §7.5                                           |
 
-Knobs that do not apply to the chosen vendor are ignored, not rejected.
+Knobs that do not apply to the chosen vendor are rejected, not dropped: the
+schema accepts every one on every model, and building it fails with `does not
+read "<knob>"`. `zen check` reports the same thing as `model.knob`.
 `api:` exists only for the OpenAI protocol - naming it on a Gemini or Anthropic
 model is an error.
 
@@ -2012,7 +2016,8 @@ candidates; these are the judgements to make about each one)**
 - [ ] No agent holds `write_file` without `apply_patch`, or `read_file` without
       `list_dir` and `find_files`
 - [ ] An agent that only reads is not holding `write_file`, `apply_patch`,
-      `move_file` or `delete_file` - subtract them from `files:*` (or `workspace:*`)
+      `copy_file`, `move_file` or `delete_file` - subtract them from `files:*`
+      (or `workspace:*`)
 - [ ] `sandbox:*` is granted only where a shell is actually needed
 - [ ] `sandbox.persist: true`, unless a throwaway rootfs is wanted on purpose
 - [ ] The `sandbox:` image carries what the work needs, rather than the prompt

package/templates/editor/.github/prompts/finetune.prompt.md

@@ -0,0 +1,251 @@
+---
+description: Fine-tune this project against a training set in two stages - first without memory, tuning the prose; then with memory, tuning recall for speed.
+---
+
+Tune this project against real queries. Nothing here touches model weights: the
+parameters are the agent prompts, the skills and the house rules under `agents/`,
+and the evidence is the trajectories the queries produce.
+
+**Load the `zen-finetune` skill before anything else**, and load `zen-inspect`
+before you grade, `zen-instructions` before you write a policy file, and
+`zen-sandbox-capacity` if a batch dies at 137 or 124. This prompt is the order of
+the work; the skill is how each step is done, and it holds the rules that are
+easy to get wrong.
+
+This prompt is **reentrant**. Tuning is long and gets interrupted - a batch dies,
+a session ends, I stop you mid-round. Every step leaves its result on disk under
+`.finetune/`, so a second invocation does not start over: it reads that state,
+works out which stage and which step the work stopped at, says so, and carries
+on from there unless I tell you otherwise.
+
+## The two stages
+
+This is two stages, run in order, never interleaved. Say which stage you are in
+at the top of every report.
+
+**Stage 1 - without memory.** Every batch runs against an empty memory, so every
+run starts from nothing and the result is attributable to the prose. Here you
+tune agent prompts, `agents/instructions.md`, and the project's skills - creating
+or updating them. The runs still _write_ memory, into their own throwaway graphs,
+and what they write is graded too: the commits have to be generalisable, durable
+facts, not cached live readings. Stage 1 optimises **correctness**.
+
+**Stage 2 - with memory.** Only once stage 1 is stable and well behaved. The
+prompts, skills and house rules are now frozen; the merged memory from the last
+good cold batch is copied to every item, which reads it and writes into its own
+copy, and the only file you edit is `agents/memory-policy-instructions.md`.
+Stage 2 optimises **memory use and memory correctness**, and the expected result
+is a dramatic drop in tokens and wall clock through reuse, with no verdict
+changed.
+
+Do not start stage 2 while any sample still fails cold. Memory will hide the
+defect and it will come back the day the graph is rebuilt.
+
+## Where you are - work this out before anything else
+
+Do this every time this prompt runs, including the first - on a project that has
+never been tuned it costs one `ls` and tells you to start at section 0.
+
+```sh
+ls .finetune/dataset.json .finetune/rounds 2>/dev/null
+for r in .finetune/rounds/*/; do
+    printf '%s ' "$r"
+    for f in cases.json batch/batch.json findings.md changes.md; do
+        [ -e "$r$f" ] && printf '%s ' "$f"
+    done
+    echo
+done
+```
+
+The rounds are ordered by name, so the last one is the live one. Read its
+`findings.md` heading for the stage - it says `COLD` or `WARM` - and its
+`changes.md` for what was already applied. Then resume by the artefacts the round
+is missing:
+
+| State of the last round                 | Where the work stopped              | Resume at                                                                  |
+| --------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------- |
+| no `.finetune/` at all                  | nothing has been done               | section 0, then 1                                                          |
+| `dataset.json`, no `rounds/`            | dataset built, never sampled        | section 2 (stage 1)                                                        |
+| `cases.json` only                       | sampled, batch never started        | preflight, then run the batch into this same round                         |
+| `batch/` present, no `batch/batch.json` | the batch was interrupted or killed | the round is **void** - see below, then re-run it                          |
+| `batch/batch.json`, no `findings.md`    | the batch finished, nothing graded  | section 3 - `collect.sh oom` first                                         |
+| `findings.md`, no `changes.md`          | graded, nothing applied yet         | section 4                                                                  |
+| `findings.md` and `changes.md`          | edits applied, never measured       | re-run the same cases into a **new** round: section 5 cold, section 6 warm |
+| the last round's heading says `WARM`    | stage 2 is in progress              | the same rows, read against section 6                                      |
+
+Two things the table does not see, so check them by hand:
+
+- **Uncommitted edits under `agents/` with no `changes.md` to explain them.** An
+  apply was interrupted part-way. Read `git status --short agents/` and the diff,
+  finish writing `changes.md` from what is actually on disk, then re-run - do not
+  layer new edits on top of edits you have not recorded.
+- **`zen check` before you resume anything.** A project left broken mid-edit
+  fails every item identically and looks like a catastrophic regression.
+
+A round whose batch never wrote `batch.json` produced no evidence. Move it aside
+rather than grading it or deleting it - `mv .finetune/rounds/rN/batch
+.finetune/rounds/rN/batch.partial` - and re-run that round from the same
+`cases.json`. The same applies to a round `collect.sh oom` calls void.
+
+Resuming never re-samples and never re-merges. Re-use the first round's
+`cases.json` and, in stage 2, the merged graph already sitting in the stage's
+round directory - an interruption is not a reason to change the thing every
+earlier round was measured against. Re-derive nothing from memory of the last
+session either: `findings.md` and `changes.md` are the record, so read them.
+
+Then tell me, in three lines before you do any work: which stage, which round and
+step you are resuming at, and what you are about to run. Continue without waiting
+for me up to the next natural checkpoint - the end of a round's report - because
+that is where this prompt already stops and asks. If I named a stage or a round,
+do that instead of what the state says.
+
+**If nothing is left to do** - the last round is WARM, it met the stage-2 exit
+criteria, and no prose or policy edit has landed since - do not start another
+tuning round. Run one confirmation round instead: the same `cases.json`, the same
+merged graph, the same flags, the same machine, into
+`.finetune/rounds/rN-verify/`. Grade it, write `findings.md` with the heading
+`VERIFIED` if no verdict regressed and the saving still holds, and change nothing.
+If something did regress, that is a real finding: report it and re-open the stage
+it belongs to.
+
+## 0. Before the first round
+
+Name the training set. If I have not given you one, ask - a specification
+section, a file of examples, a transcript, a CSV. Fewer than about eight queries
+is a debugging session, not a tuning loop; say so and read the runs singly
+instead.
+
+Then run the mechanical checks and report what they say:
+
+```sh
+zen check
+.github/skills/zen-review/scripts/check-paths.sh
+```
+
+A project that does not load fails every item for one reason. Do not start a
+round until `zen check` passes.
+
+## 1. Dataset
+
+Build `.finetune/dataset.json` if it is not there, and read it if it is. Read the
+source yourself and write the structure out - do not write a parser. Rubrics are
+copied **verbatim**, one entry per bullet. Classify only the distinctions the
+source already makes, and rate complexity by the trajectory the query demands,
+not by the length of the sentence. Keep ids stable across re-extractions.
+
+## 2. Stage 1: sample, preflight, run cold
+
+```sh
+.github/skills/zen-finetune/scripts/sample.sh -n 16 --seed 1 -o .finetune/rounds/r1/cases.json
+.github/skills/zen-sandbox-capacity/scripts/preflight_sandbox.sh --concurrency 8
+zen run batch --input .finetune/rounds/r1/cases.json \
+    --batch-dir .finetune/rounds/r1/batch --memory .finetune/empty --concurrency 8
+```
+
+Every stage-1 round is cold and every round re-uses the first round's
+`cases.json`. A warm graph lets a run succeed by recall instead of by
+instruction, and a re-sampled batch means a moved score has two causes and you
+cannot tell which.
+
+## 3. Stage 1: grade
+
+`collect.sh oom` first - a round with any exit 137 is void, is not graded, and
+its tokens are compared to nothing. Then read the graphs before the numbers.
+Grade every item against all eight criteria in the skill: rubric compliance,
+optimality, memory hygiene, fork, delegation, tools and skills, grounding,
+failure handling. **Cite a node id for every finding.** A finding you cannot
+point at in the graph did not happen.
+
+Grade the memory each item _wrote_ as seriously as the answer it gave. Read
+`<id>/memory/` across the batch: every commit should be an operation, a pointer,
+a shape or a rule that is still true next week. A cached live reading poisons
+every future run, and committing nothing after learning something durable throws
+the round away. Commit policy is fixed here, cold, while the cause is still
+attributable - not in stage 2.
+
+Write `.finetune/rounds/rN/findings.md`: the verdict block first - `PROGRESS`,
+`NO CHANGE`, `REGRESSION`, `MIXED` or `VOID`, the `memory:` and `machine:` lines
+as printed, and the `compare` table - then the per-sample grading. The heading
+says `COLD` or `WARM`.
+
+## 4. Stage 1: generalise, then apply
+
+Collect every finding into one table before writing a word of instruction. The
+unit of change is a pattern across findings, not a finding: three items missing
+the same beat is a rule, one item is a note in `findings.md`. Write the rule one
+level up from the sample that produced it - a rule that names the dataset's own
+endpoints makes the eval pass and the product fail. Prefer mechanical wording,
+and remember that a prohibition with a self-judged exemption is a permission.
+
+Route each rule by what kind of thing it is: one agent's behaviour to its prompt,
+a fact or a procedure to a skill - update an existing one or create a new one, a
+standing rule to `agents/instructions.md`, a rule about one capability to a new
+`agents/<topic>-policy-instructions.md`.
+
+You may edit prompts, skills, house rules and new policy files. You may not edit
+`agents/memory-instructions.md`, `agents/fork-instructions.md`,
+`agents/tools-instructions.md` or `agents/files-instructions.md` - `zen check
+--fix` overwrites them. You may not change a rubric to make a run pass. Tell me
+before you change `agents.yaml`; that finding is structural.
+
+Record every edit and the finding numbers behind it in
+`.finetune/rounds/rN/changes.md`, then run `zen check` again.
+
+## 5. Stage 1: loop, and leave the stage
+
+Re-run the same cases into a new round directory and compare per sample and on
+the aggregate. The verdict column decides, not the token column. A sample that
+passed and now fails is the most valuable result in the round and is almost
+always the new instruction. If the instruction files grew by a third and the
+score moved by one sample, revert and say so.
+
+Report to me after each round and wait: the verdict block, what you changed, and
+what you propose to change next. Stop when a round produces no generalisable
+pattern - that is the remaining failure being the model's rather than the prose's.
+
+Stage 1 ends when, on one cold round, **every sample holds** and **what the runs
+wrote to memory is worth keeping**. Tell me both before proposing stage 2.
+
+## 6. Stage 2: memory
+
+Freeze the prompts, the skills and the house rules. Merge the last good cold
+round's memory into one graph, read `zen memory stats`, and run the same cases
+against it with the same flags the cold round used - `--memory <merged graph>`
+and nothing else. Each item copies that graph, recalls from the copy and writes
+back into the copy, so every item starts from the same memory and the source is
+left untouched. Do not use `--memory-read-only`: it removes the commit tool and
+changes the memory prose, which would make the warm round differ from its cold
+baseline in two ways instead of one.
+
+Compare against the cold round the memory came from.
+
+The target is reuse: recall should replace the discovery the cold runs repeated
+every time, so the warm batch is dramatically cheaper in tokens, calls and wall
+clock with no verdict changed. A warm round that costs about the same, or more,
+means memory was carried and not used - that is a recall-timing finding, not a
+reason for more memory. A warm round that is much cheaper still needs one
+trajectory opened to confirm the saving is recall replacing _discovery_ and not
+recall replacing a _live reading_.
+
+Grade what the warm items committed as well as what they recalled - this is the
+one place it can be seen. A node that duplicates something the same run just
+recalled is waste, and a correction committed without `SUPERSEDES` beside the
+stale node it contradicts is worse than waste.
+
+In stage 2 the only file you edit is `agents/memory-policy-instructions.md`. Keep
+the merged graph byte-identical for the whole stage: do not re-merge between
+rounds, and never merge a warm round's own copies back into it - either changes
+the memory and the prose at once. If a finding cannot be written as a recall or
+re-commit rule, it is a stage-1 finding that escaped - tell me, and we re-open
+stage 1.
+
+Stage 2 ends when no verdict regressed, the saving is obvious next to the noise
+floor, every large saving is explained, and nothing was committed that memory
+already held.
+
+Commit `dataset.json`, `cases.json`, `findings.md` and `changes.md` - they are
+the eval history, and they are what a resumed session reads to find out where it
+got to. Write each of them as its step ends rather than at the end of the round,
+so an interruption never costs more than the step it lands in. Add
+`.finetune/rounds/*/batch/` and `.finetune/empty/` to `.gitignore` - the batch
+directories are large and may hold live API responses.

package/templates/editor/.github/prompts/spec-sync-project.prompt.md

@@ -115,7 +115,10 @@ the model to compute or remember. Specifically:
   in it to the version of `zen` in hand. Read that version with `zen --version`
   and write it into the `npm install -g` line, so the CLI an agent runs inside
   the container is the same one that built it. An unpinned name drifts away from
-  the host on the next image build; a stale pin is a mismatch nothing reports.
+  the host on the next image build; a stale pin leaves the container holding an
+  older `zen` than the session outside it. `zen check` reports both, as
+  `sandbox.pin.absent` and `sandbox.pin.stale`, but will not repair either - the
+  Dockerfile is the project's file, so this edit is yours to make.
 
 Never delete an **extra** without saying so. Report it, say why the
 specification does not cover it, and leave it unless I tell you to remove it.
@@ -148,6 +151,18 @@ not a paragraph of instructions for a human.
   to a temporary path and moving it into place so an interrupted run never leaves
   a half-built artefact behind. `scripts/_setup.sh --force` redoes everything,
   and reaches each step as `$FORCE=1`.
+- **Every step answers a dry run.** `scripts/_setup.sh --check` reaches each step
+  as `$CHECK=1` and means: make the same "already done" test, then do none of the
+  work. Exit **3** when the answer is yes, otherwise say what is missing and exit
+  **4**, which the runner reports as `needs setup`. This is the one command that
+  says whether the project can run without spending the download and the
+  embedding to find out, so the line a step prints under `$CHECK` is the whole
+  value of it: name the artefact and the command that produces it. Pass a tool's
+  own words through rather than writing a second opinion: `zen rag docs ready`
+  without `--quiet` already prints what is wrong and the `restore` or `index`
+  that fixes it. A check must not assume an earlier step has run: a missing
+  prerequisite is a 4 of its own, not a failure, or the first unbuilt thing
+  hides everything after it.
 - **A step's "already done" test must name something that survives a clone.**
   Git-ignored output does not. A rag index commits its `manifest.json` and
   ignores `lance/`, so `[ -f "$OUT/manifest.json" ]` is true on a fresh checkout
@@ -164,6 +179,10 @@ not a paragraph of instructions for a human.
         echo "$OUT is already built"
         exit 3
     fi
+    if [ "${CHECK:-0}" = 1 ]; then
+        zen rag docs ready --dir "$OUT" || true   # its reason and its fix
+        exit 4
+    fi
     if [ "${FORCE:-0}" = 0 ] && [ -f "$OUT/manifest.json" ]; then
         zen rag docs restore --dir "$OUT"   # committed index, ignored vectors
         exit 0
@@ -175,7 +194,8 @@ not a paragraph of instructions for a human.
 
 - **It must be watchable.** `scripts/_setup.sh` tees each step's output to
   `.tmp/logs/setup-<step>.log`, prints a heartbeat line while a long step runs,
-  and finishes with one line per step: `ok`, `skipped`, or `failed`.
+  and finishes with one line per step: `ok`, `skipped`, `needs setup`, or
+  `failed`.
 - **Everything transient goes under `.tmp/`** - logs, scratch files, downloads,
   test output, and the temporary path a step writes to before moving its
   artefact into place. Nothing else in the tree is a scratch directory, and
@@ -379,6 +399,9 @@ background and follow the logs instead of waiting blind:
   for the same reason, stop and raise it in `SPECIFICATION-FEEDBACK.md`.
 - Prove re-entrancy: once it has succeeded, run `scripts/_setup.sh` once more and
   check that every step reports `skipped` rather than rebuilding.
+- Prove the dry run: `scripts/_setup.sh --check` must then report every step
+  `skipped` and exit 0. `needs setup` for something setup has just built means
+  the step's two tests disagree, and one of them is wrong.
 - **`skipped` on a machine that has never built it is a bug, not a pass.** A
   step that tests for a committed file skips on a fresh clone and leaves the
   project unusable. For every index the project builds, check it can actually

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

@@ -17,14 +17,17 @@ failed, `2` usage, `3` invalid project, `4` no usable credential, `5` sandbox.
 
 ```
 zen init     [dir] [--name <name>] [--model <ref>] [--force]
-zen list     [--sessions] [--prune]
+zen list     [--sessions] [--runs] [--limit <n>] [--prune]
 zen run      [project] [prompt] [options]
+zen run      batch --input <file> [--batch-dir <dir>] [--concurrency <n>] [--memory-read-only]
 zen open     [project] [--editor <cmd>] [--wait]
 zen key      <ls|add|use|check|rm|show|env> [ref] [options]
 zen models   <providers|ls|search|show|test|pick> [ref] [options]
 zen check    [name|dir] [--project <name|dir>] [--no-sandbox] [--no-models] [--strict] [--quiet]
-zen inspect  [run] [--session <id>] [--open] [--rebuild] [--serve [port]]
-zen memory   [stats|ls|show|export|forget] [args] [options]
+zen inspect  [report|graph|node|ask] [run] [--dir <run dir>] [--part <name>] [--full] [--open]
+zen memory   [stats|ls|search|grep|show|export|merge|forget] [args] [options]
+zen export   [project] [--out <file>] [--no-vectors] [--no-memory] [--force]
+zen import   <file.zip> [dir] [--name <name>] [--force] [--no-register]
 zen sandbox  [status|up|pull|clean|disk] [options]
 zen version
 
@@ -44,12 +47,15 @@ guess a flag, and do not read them all.
 | Global flags, `--json`, exit codes, environment, where files live   | [frame.md](./references/frame.md)                               |
 | Creating, finding or opening a project                              | [projects.md](./references/projects.md)                         |
 | Running: the TUI, one-shot answers, sessions, workspaces, overrides | [run.md](./references/run.md)                                   |
+| Many questions at once: `zen run batch`, its file, where answers go | [run.md](./references/run.md)                                   |
 | Validating: `zen check`, what it can and cannot see                 | [check.md](./references/check.md)                               |
 | API keys, providers, the keyring, "no credential" errors            | [keys.md](./references/keys.md)                                 |
 | Which models exist, whether one works, recovering from a refusal    | [models.md](./references/models.md)                             |
 | The container shell commands run in, images, `persist`              | [sandbox.md](./references/sandbox.md) (and `zen-sandbox` skill) |
 | 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)                             |
+| 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)                                   |
 
@@ -60,8 +66,13 @@ zen init                              scaffold a project here, pick a model
 zen check                             validate everything before spending a turn
 zen run                               the TUI
 zen run "what changed?"               one answer, this directory as the workspace
+zen run batch --input cases.json      many questions at once, each isolated
 zen inspect --open                    what the model was actually given
+zen inspect graph --dir <run dir>     the same run as a graph you can read
+zen inspect node n14..n20 --dir <d>   the nodes behind the ids, in full
 zen memory export --open              the whole memory graph, as a page
+zen export                            the project as a zip you can send
+zen import a.zip                      unpack one somebody sent, run nothing in it
 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

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

@@ -51,6 +51,11 @@ checked too. A word that is neither is a usage error (exit 2), not a report.
   exist, and - unless `--no-sandbox` - the image **builds** and one command runs
   in it, against a temporary directory rather than your workspace. No container
   engine at all is a warning, not an error.
+- The `@zenera/*` the Dockerfile installs are pinned to **this** `zen`. The pin
+  is written once, by `zen init`, and nothing rewrites it afterwards, so it falls
+  behind the host on the next upgrade and the container ends up holding a
+  different `zen` than the session outside it. Read rather than run, so this one
+  is reported with `--no-sandbox` too.
 
 ### Findings
 
@@ -66,10 +71,11 @@ fork.unknown          skills.missing         skill.unloadable / .no-skill-md
 skills.no-catalog     skills.unreachable     skill.unused
 assets.missing        assets.overbroad       sandbox.dockerfile.missing
 sandbox.build         sandbox.smoke          sandbox.start / .unchecked
+sandbox.pin.stale     sandbox.pin.absent
 provider.invalid      model.none             model.unresolvable
-model.refused         model.unreachable      model.unusable
-embedding.refused     embedding.unreachable  embedding.unusable
-credential.*          service.credential
+model.knob            model.refused          model.unreachable
+model.unusable        embedding.refused      embedding.unreachable
+embedding.unusable    credential.*           service.credential
 ```
 
 The report goes to **stdout** - it is the answer. `--json` gives the same
@@ -81,8 +87,10 @@ required it.
 
 ### What it cannot catch
 
-Combinations that are only rejected by the provider at the first call. The
-known one: **OpenAI reasoning and tools only meet on the responses API.** A
+Combinations that are only rejected by the provider at the first call. A knob
+written for the wrong vendor is no longer one of them - `model.knob` names it,
+and building the model refuses outright. The known one that remains:
+**OpenAI reasoning and tools only meet on the responses API.** A
 model with `reasoningEffort` and tools on the default chat-completions API is a
 valid configuration that fails at runtime with _"Function tools with
 reasoning_effort are not supported … in /v1/chat/completions"_. Set