@zenera/cli 1.1.45 → 1.1.47

package/dist/archive.js

@@ -67,8 +67,9 @@ export function excluded(rel, isDir, opts = {}) {
     }
     // The credentials never travel, in any form and behind no flag. What the
     // project needs is described by `.env.example`, which `export` synthesizes
-    // from the names in this file.
-    if (rel === ENV_FILE) {
+    // from the names in this file. Its variants (`.env.test`, `.env.local`, what
+    // `ZEN_ENV_FILE` names) are credentials just the same.
+    if (rel === ENV_FILE || (rel.startsWith(`${ENV_FILE}.`) && rel !== ENV_EXAMPLE)) {
         return 'env';
     }
     if (name === '.lock') {

package/dist/commands/export.js

@@ -41,8 +41,8 @@ export const pack = {
         '',
         'Leaves behind what belongs to this machine: sessions/, .tmp/, .git/,',
         'node_modules/, lock files, any *.zip at the top of the project, and',
-        `.env. The names in .env become a ${ENV_EXAMPLE} with no values, so the`,
-        'other end knows what to fill in.',
+        `.env and .env.test. Unless the project keeps its own ${ENV_EXAMPLE}, the names in .env`,
+        'become one with no values, so the other end knows what to fill in.',
         '',
         'Vectors travel by default — memory has no other source, and a rag',
         'index without its lance/ tree looks built and cannot search.',
@@ -79,7 +79,8 @@ export const pack = {
         const collected = collect(dir, { vectors, memory });
         const extra = new Map();
         const env = join(dir, ENV_FILE);
-        if (existsSync(env)) {
+        // A project's own `.env.example` is the curated one and travels as is.
+        if (existsSync(env) && !existsSync(join(dir, ENV_EXAMPLE))) {
             extra.set(ENV_EXAMPLE, envExample(readFileSync(env, 'utf8')));
         }
         const healthy = await sound(dir, found.name, ctx.json);

package/dist/scaffold.js

@@ -127,13 +127,17 @@ function modelSection(ref, options) {
  *
  * `gitignore` cannot have its dot in the repository: npm strips a `.gitignore`
  * out of a published tarball, and git would read this one as rules about
- * `packages/cli/templates/` rather than as content. `env` cannot have its dot
- * for a plainer reason — this repository ignores `.env` everywhere, as every
- * repository should, so the template would never be committed at all.
+ * `packages/cli/templates/` rather than as content. The `env` files cannot have
+ * their dot for a plainer reason — this repository ignores `.env` and `.env.*`
+ * everywhere, so the templates would never be committed at all. In the project
+ * `.env` and `.env.test` are ignored, being credentials; `.env.example` holds
+ * no values and is meant to be shared.
  */
 const DOTFILES = {
     gitignore: '.gitignore',
     env: '.env',
+    'env.example': '.env.example',
+    'env.test': '.env.test',
 };
 /** The name a template file lands under. */
 function target(name) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.45",
+    "version": "1.1.47",
     "description": "Command-line front end for @zenera/neo: agentic projects you can run, share and commit.",
     "keywords": [
         "agents",
@@ -54,9 +54,9 @@
         "@google/genai": "^2.30.0",
         "@inkjs/ui": "^2.0.0",
         "@openrouter/sdk": "^1.4.25",
-        "@zenera/engine": "^1.1.45",
-        "@zenera/neo": "^1.1.45",
-        "@zenera/view": "^1.1.45",
+        "@zenera/engine": "^1.1.47",
+        "@zenera/neo": "^1.1.47",
+        "@zenera/view": "^1.1.47",
         "google-auth-library": "^10.0.0",
         "ink": "^7.1.1",
         "openai": "^6.0.0",

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

@@ -58,11 +58,10 @@ code, `zen-topology` for `handoffs:` or `fork:` on any agent,
 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. Outside a specification-sync pass,
-this applies whatever prompted the change. During an incremental sync, load only
-skills for capabilities its changed requirements, files, keys or unresolved
-work touch. A full pass still loads every enabled capability's skill. The
-**spec-only** and **model-reference-only** tiers load no capability skill unless
-the work expands beyond their eligibility rules.
+this applies whatever prompted the change. During an incremental sync, load the
+skills the `zen-spec-sync` pass plan names for the areas its changes reach - an
+enabled capability no change reaches owes nothing new. A full pass still loads
+every enabled capability's skill.
 
 **Load `zen-instructions` before writing, editing, reviewing or deleting any
 `agents/*instructions.md`.** They are the house rules, prepended to every
@@ -1895,8 +1894,8 @@ Run it first and read what it says. Everything else below is judgement, which is
 why it is still a list. The `zen-review` skill has the detail.
 Within a specification-sync pass, reuse its final check with
 `review.sh --skip-check` instead of probing again, and apply the sync skill's
-explicit tier scope to this checklist. Use `--skip-check no-sandbox` only for an
-eligible model-reference-only pass. Independent reviews still cover the whole
+pass plan to this checklist. Use `--skip-check no-sandbox` only when that plan
+does not reach the sandbox image. Independent reviews still cover the whole
 checklist.
 
 Before finishing any change here:

package/templates/editor/.github/skills/spec-edit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-edit
-description: Change SPECIFICATION.md as the request given with the command asks - written in the specification's own structure and voice, checked against what the runtime can actually do - and nothing else. Never explores the project or the environment; discovering how things work is /spec-sync-project's job.
+description: Change SPECIFICATION.md as the request given with the command asks - written in the specification's own structure and voice, checked against what the runtime can actually do - and nothing else. SPECIFICATION.md is the only file it may edit (plus a throwaway temp file when a computation needs one). Never explores the project or the environment; discovering how things work is /spec-sync-project's job.
 argument-hint: 'what to add, change or remove in the specification'
 disable-model-invocation: true
 ---
@@ -10,8 +10,14 @@ specification is the intent of the project; you are changing the intent, not
 the implementation. Making the project match it is `/spec-sync-project`, which
 runs after this.
 
-You change one file: `SPECIFICATION.md`. Not `agents.yaml`, not a prompt, not a
-skill, not `SPECIFICATION-FEEDBACK.md`.
+**The only file you may edit is `SPECIFICATION.md`.** Do not create, edit,
+rename, move or delete any other file in the project - not `agents.yaml`, not a
+prompt, not a skill, not a script, not `sandbox/`, not
+`SPECIFICATION-FEEDBACK.md`, not a new notes or draft file. The one exception:
+when a computation genuinely needs scratch space, you may use a temporary file
+outside the project (created with `mktemp` in the system temp directory), and
+you delete it before you finish. Anything else the request seems to need
+changed goes into the report for `/spec-sync-project`, never into the project.
 
 ## 0. Size the edit, then read only what it needs
 
@@ -84,7 +90,8 @@ project beyond the files above. Do not open, list or search anything else in
 the project: not `agents/`, `scripts/`, `sandbox/`, `resources/`, `assets/`,
 `gym/`, examples, code or data, and not the skills' own `references/` beyond
 the models reference. Do not run any command other than the `zen models` ones
-above, and do not inspect environment variables, the network, running
+above and, when a computation needs it, commands that touch only your own
+temporary file; do not inspect environment variables, the network, running
 processes or installed tools. A path the request names is written into the
 specification as named; you do not read it to find out what is in it.
 
@@ -316,6 +323,8 @@ In the chat:
 - anything you did not write because the runtime cannot do it
 - every value written by role or env-var name that only the reader has, and
   anything you would have wanted to look up but did not (§0)
+- every change outside `SPECIFICATION.md` the request implies, left for
+  `/spec-sync-project` rather than made
 - then, in one line: send `/spec-sync-project` to make the project match.
 
 ## 5. The request

package/templates/editor/.github/skills/spec-sync-project/SKILL.md

@@ -22,31 +22,16 @@ because this pass has to make the first. Then, from the project root:
 ```
 
 `status` answers `full`, `incremental` or `tampered`. Say which in the chat
-before reading anything, and on an incremental pass state the scope you drew
-from the diffs - the skill says how. `full` and `tampered` both mean the whole
-prompt as written below, from nothing.
-
-The diff covers both sides. `SPECIFICATION.md` and `SPECIFICATION-FEEDBACK.md`
-say what has been **asked for** since the last pass; `agents.yaml` and every
-file under `agents/` say what has been **built or hand-edited** since then. The
-first narrows the pass to the work nobody has done; the second only widens it,
-because a prompt or skill someone changed outside a pass still has to be
-accounted for against the specification.
-Generated house-rule copies print as `maintenance:` and do not alone widen
-the pass; their diffs remain visible and `zen check --fix` owns their repair.
-
-The scope decides what you **read and edit**. It never decides what you
-**verify** outside the skill's explicit tiers: **spec-only** and
-**model-reference-only** narrow verification under the conditions the skill
-sets. Choose the tier before loading capability skills. In a normal incremental
-pass, load only skills for capabilities the diff or unresolved work reaches;
-in a full pass, load every enabled capability's skill.
-
-When inputs disagree - a ticked answer against a later specification edit, the
-specification against `zen --version` - use the order of precedence in the
-skill. The user's own message comes first. Do not use session history, file
-timestamps or `git log` to work out why something changed. Whatever the order
-does not settle becomes a question in `SPECIFICATION-FEEDBACK.md`.
+before reading anything. `full` and `tampered` mean everything below as
+written, from nothing: read the whole tree, load every enabled capability's
+skill, run setup in full and run the full check.
+
+On an incremental pass, the skill owns everything that makes the pass smaller:
+the scope drawn from the diffs, precedence when inputs disagree, and the pass
+plan that decides which capability skills to load, which setup proof and which
+check to run. Post the scope and the plan before reading the project. Wherever a
+section below says **the plan**, it means that plan; on a full pass, read it as
+"everything".
 
 ## 1. Read before changing anything
 
@@ -65,9 +50,7 @@ Read, in this order, and do not edit until all of it is read:
 Never read `.tmp/logs/meta.*` - those are other runs of this command, not
 evidence - nor anything of `zen`'s own (copilot instructions §0.2).
 
-On an incremental pass this list narrows to the artefacts the scope implicates,
-and to the changed hunks of the specification rather than all of it. The
-narrowing is a claim: name what you skipped and why the diff does not reach it.
+On an incremental pass this list narrows to what the plan reaches.
 
 If an initial diagnostic is needed, run
 `zen check --no-models --no-sandbox` and record what it said. A project that
@@ -111,13 +94,8 @@ forward pass can see:
 These are bugs whatever the specification says: fix them in place and report each
 one. An extra that is merely unspecified is reported under `➕`, not removed.
 
-On an incremental pass this reverse reading covers every project-owned file this pass touched
-plus every file the implementation diff in §0 named - an edit made in this
-session, or made by hand since the last pass, is exactly where a fresh
-contradiction comes from. On a full pass it is the whole tree, as above.
-Generated house-rule copies and the editor tree are maintained by `zen check`,
-not audited line by line against the specification. Preserve any project policy
-discovered in their maintenance diffs in a project-owned topic file.
+On an incremental pass the skill says which files this reverse reading covers.
+Generated house-rule copies and the editor tree are never read this way.
 
 ## 3. Change the smallest thing that closes the gap
 
@@ -146,6 +124,8 @@ the model to compute or remember. Specifically:
 
 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.
+Leave it where it is, too: a line you write for a specified item does not
+mention an extra, so removing it later stays a removal of its own lines.
 
 Do not invent a value the specification does not state - a model id, a limit, a
 retry count, a file path. That is an entry in `SPECIFICATION-FEEDBACK.md`, not a
@@ -397,24 +377,13 @@ Append to the existing file rather than rewriting it, keeping the numbering and
 the contents list in step. Numbers are never reused: a struck question's number
 retires with it.
 
-Read the feedback diff from §0 before writing: a question the human answered
-since the last pass is work to close, not a question to ask again. If a question
-has a box marked `[x]`, or one answer left under it, and no `✅` entry, the
-reader answered it and never ran `/spec-apply-feedback` - implement that
-answer, fold its text into `SPECIFICATION.md` yourself, and say so in the chat.
-Do this unless the specification has since been edited on the same point. In
-that case the edit supersedes the answer: strike the question, naming the line
-that replaced it, and leave the newer text alone.
+A question the human answered since the last pass is work to close, not a
+question to ask again; the skill says how to implement or supersede it.
 
 ## 6. Run `scripts/_setup.sh` and watch it finish
 
-After `zen check` passes, run `scripts/_setup.sh` yourself. A pass is not done
-until it has run to completion in this session. The exceptions are a spec-only
-or model-reference-only pass, as the `zen-spec-sync` skill defines them:
-there `scripts/_setup.sh --check`
-reporting every step `skipped` is enough, and anything else sends you back to
-the full run below. For any tier, when `STEPS` is empty, one successful
-`scripts/_setup.sh --check` is sufficient; do not run it twice to prove nothing.
+Run setup to the proof the plan names. When it names a full run, a pass is not
+done until `scripts/_setup.sh` has run to completion in this session, as below.
 
 It is slow - embedding a large corpus is hours, and the progress line says how
 many - so start it in the background and follow the logs instead of waiting
@@ -452,18 +421,14 @@ blind:
 
 ## 7. Verify and report
 
-After the final edit and setup, run
-`.github/skills/zen-review/scripts/review.sh check full --fix` and fix whatever
-it names rather than working around it. The model-reference-only tier may use
-`check no-sandbox` under the skill's unchanged-sandbox conditions. A pin repair
-requires the full sandbox check. This is the final expensive check, not an
-instruction to repeat an already valid one. Use
-`.github/skills/zen-review/scripts/review.sh --skip-check` (with `no-sandbox`
-only for that eligible tier) for the mechanical review, which verifies the
-receipt instead of probing again. Edits after a check invalidate reuse.
-It validates structure and says nothing about the prose, so work §9 of the
+After the final edit and setup, re-plan, then run the check the final plan names
+(`.github/skills/zen-review/scripts/review.sh check full --fix` on a full pass)
+and fix whatever it names rather than working around it. Run it once; edits
+after it invalidate it. Then run `review.sh --skip-check` in the same mode for
+the mechanical review, which reuses the receipt instead of probing again.
+That validates structure and says nothing about the prose, so work §9 of the
 copilot instructions as a checklist afterwards and report each group pass or
-fail, narrowed only by the skill's tier rules. Then report in the chat:
+fail, narrowed only by the plan. Then report in the chat:
 
 - what changed, file by file, and which specification item each change closes
 - every prompt or skill line that served no specification item, and what became
@@ -474,24 +439,11 @@ fail, narrowed only by the skill's tier rules. Then report in the chat:
 
 ## 8. Record the pass
 
-Last, and only once §6 and §7 have actually passed. Use `snapshot.sh record`
-with explicit scope, changes, feedback, unresolved items and check outcomes
-(see the `zen-spec-sync` skill), or write
-`.spec-sync/history/<stamp>.md` in the format the `zen-spec-sync` skill gives -
-including `Still open`, which is the only place the next pass learns that an
-unchanged specification line is not yet implemented - and then:
-
-```sh
-.github/skills/zen-spec-sync/scripts/snapshot.sh commit
-```
-
-In that order, never the other way. Moving the baseline before the pass has
-finished records a specification as applied that was not: the next pass diffs
-against it, sees nothing to do, and the work is never done by anybody. A pass
-that fails with the baseline unmoved costs one repeat.
-
-A pass that changed nothing still writes a history file and still commits. Say
-in the chat which history file you wrote and that the baseline moved.
+Last, and only once §6 and §7 have actually passed: write the history entry
+with `snapshot.sh record`, including both plans and `Still open`, then
+`snapshot.sh commit`. Never the other way round; the skill says why and how.
+A pass that changed nothing still records and commits. Say in the chat which
+history file you wrote and that the baseline moved.
 
 Do not report a specification item as done unless the file that implements it
-exists, `zen check` passes, and setup satisfies the selected tier's proof.
+exists, `zen check` passes, and setup satisfies the plan's proof.

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

@@ -66,8 +66,8 @@ changing credentials, environment variables, external files, ignored scratch
 inputs or remote resources: those are not certified by the receipt. Run a fresh
 check instead. Only use reuse for a self-contained project's stable inputs.
 
-`check no-sandbox` and `--skip-check no-sandbox` are for the spec-sync skill's
-eligible model-reference-only pass. They still probe models. `check fast` and
+`check no-sandbox` and `--skip-check no-sandbox` are for a spec-sync pass whose
+plan does not reach the sandbox image. They still probe models. `check fast` and
 `--skip-check fast` omit both expensive probes and are for iteration only.
 A full receipt covers either partial mode, but a partial receipt cannot stand
 in for a full one. If a partial check repairs or otherwise changes files, no

package/templates/editor/.github/skills/zen-spec-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zen-spec-sync
-description: Running `/spec-sync-project` incrementally - the committed `.spec-sync` baseline, scope and precedence, spec-only and model-reference-only verification tiers, affected capability skills, generated-rule maintenance, reusable validation, explicit history recording and why the baseline moves last. Load before every `/spec-sync-project`, including a project's first pass.
+description: Running `/spec-sync-project` incrementally - the committed `.spec-sync` baseline, scope and precedence, the pass plan that maps changed areas to capability skills and checks, spec-only and model-reference-only verification tiers, generated-rule maintenance, reusable validation, explicit history recording and why the baseline moves last. Load before every `/spec-sync-project`, including a project's first pass.
 user-invocable: false
 ---
 
@@ -14,8 +14,9 @@ one already made, and re-raises questions someone has already answered.
 A pass is worth repeating cheaply, so it keeps a record of **what it applied**.
 The next pass diffs the specification against that record and works the
 difference. What it must not do is confuse a narrow diff with a narrow
-obligation: the record scopes what you _read and edit_. The tiers below also
-scope verification, with explicit escalation when the work reaches further.
+obligation: the record scopes what you _read and edit_. The pass plan below
+also scopes which skills you load and which checks you run, from the areas the
+changes reach, and grows when the work reaches further.
 
 ## What this owns
 
@@ -168,14 +169,93 @@ answers:
 That is the whole of the work. A version mismatch is not a reason to look for
 anything else.
 
-## Choose a verification tier before loading capability skills
-
-Use `full` for a missing or untrusted baseline. On an incremental pass, first
-read the diffs and the applied entry's `Still open`, then choose `spec-only`,
-`model-reference-only`, or the normal incremental checks below. Unresolved
-items or feedback requiring other work disqualify a narrow tier. Say the tier,
-its scope and the omitted work in the chat. Escalate as soon as the actual work
-exceeds that scope; a small original diff is not permission to skip new work.
+## Plan the pass before loading anything
+
+On an incremental pass, after `snapshot.sh diff` and before reading the
+project, post a plan in the chat. Derive it from **what changed**, not from
+what the project has turned on: a capability that is enabled and untouched owes
+nothing it did not already owe when the last pass verified it.
+
+1. **Classify every input into areas**, using the list below: every `changed:`
+   path, every changed top-level key in `agents.yaml`, every `SPECIFICATION.md`
+   hunk, every answered feedback question and every `Still open` item. A hunk
+   counts by what it asks for, not by the section it sits in: a _Scope_ line
+   that introduces writing scripts reaches **code**.
+2. **Take the union** of the skills and checks those areas name. Load those
+   skills and no others. Name each skill and expensive check left out, with
+   the reason: `zen-sandbox - no sandbox/, sandbox: or pin change`. Reading
+   narrows the same way, to the files the areas reach and the changed hunks of
+   the specification. That narrowing is a claim too: name what you skip
+   reading and why no change reaches it.
+3. **Re-plan before verifying.** After the last edit and before the final
+   check, classify again, now including this pass's own edits -
+   `snapshot.sh diff` compares the baseline with the working tree, so it shows
+   them. Run the checks the final plan names. An edit that reaches a new area
+   adds that area's skill, loaded before the edit, and its checks. A plan only
+   grows during a pass; it never drops an area it has named.
+
+A full or tampered pass reaches every area.
+
+### Areas
+
+- **specification** - wording in `SPECIFICATION.md` or
+  `SPECIFICATION-FEEDBACK.md` that asks for nothing in the areas below. Skill:
+  none. Checks: baseline.
+- **prompts and grants** - `agents/prompts/**`, `agents/skills/**`, and the
+  `tools:` and `skills:` lists of an agent. Skill: none of its own; the content
+  may reach another area. A `sandbox:*` or `files:*` grant is a tool grant, not
+  a sandbox change. Checks: baseline.
+- **house rules** - a project-owned `agents/*instructions.md`. Skill:
+  `zen-instructions`. Checks: baseline.
+- **memory** - a `memory:` block, a project-owned memory topic file, or what
+  agents commit to or recall from memory. Skill: `zen-memory`. Checks:
+  baseline.
+- **code** - an agent that writes or runs code, its coding skill, or a script
+  shipped under a skill folder. Skill: `zen-code-python`. Checks: baseline.
+- **topology** - `handoffs:`, `fork:`, or an agent added, removed or given a
+  different job. Skill: `zen-topology`. Checks: baseline.
+- **models** - a chat model reference or `providers:`. Skill: none. Checks:
+  baseline, whose check already probes models.
+- **index** - an embedding reference, `assets/**`, or an index the project
+  builds or searches. Skill: `zen-rag-docs` or `zen-rag-schema`. Checks:
+  setup run.
+- **setup** - `scripts/**`. Skill: `zen-cli` when a step's commands change.
+  Checks: setup run.
+- **sandbox image** - `sandbox/**`, the `sandbox:` block, the `@zenera/*` pin,
+  a setup step that writes into the build context, or any `sandbox.pin.*` or
+  `rules.stale` finding. Skill: `zen-sandbox`, except for a pin or
+  `rules.stale` repair alone. Checks: sandbox.
+
+### Checks
+
+- **baseline** - every incremental pass: after the last edit and setup,
+  `review.sh check no-sandbox`; `scripts/_setup.sh --check` reporting every
+  step `skipped` (one run when `STEPS` is empty); then
+  `review.sh --skip-check no-sandbox`.
+- **setup run** - replaces the setup part of baseline with §6 of the prompt:
+  `scripts/_setup.sh` to completion, again to prove every step `skipped`,
+  `--check`, and `zen rag docs ready` for each index the project builds.
+- **sandbox** - replaces `no-sandbox` with `full --fix` on the check and `full`
+  on the review.
+
+Results add areas. `--check` reporting anything but `skipped` adds **setup**.
+A check finding `rules.stale` or a sandbox pin, or one that would repair any
+file, adds **sandbox image**: run `review.sh check full --fix`, because a
+partial check that changes files issues no reusable receipt. `--no-sandbox` is
+allowed only once git confirms the sandbox configuration, Dockerfile and build
+context are unchanged and no setup step writes into them; if that cannot be
+established, the pass reaches **sandbox image**.
+
+## Choose a verification tier
+
+The plan is the tier. Use `full` for a missing or untrusted baseline. A plan
+whose only area is **specification** is the spec-only pass; one whose only
+area is **models**, through a chat model reference, is the
+model-reference-only pass. Both carry the extra conditions below. Every other
+plan runs the normal incremental checks. Unresolved items or feedback requiring
+other work disqualify a narrow tier. Say the tier, its scope and the omitted
+work in the chat. Escalate as soon as the actual work exceeds that scope; a
+small original diff is not permission to skip new work.
 
 ### The model-reference-only pass
 
@@ -224,24 +304,23 @@ re-entrancy and repeat the final check. Finish all builds before recording.
 
 Outside the two narrow tiers:
 
-1. **`zen check` passes after the last edit and setup.** Use
-   `review.sh check full --fix` to repair generated copies and pins before
-   validating. When an initial diagnostic is needed, use
-   `zen check --no-models --no-sandbox`; do not repeat expensive probes before
-   and after editing. Reuse the final receipt with `review.sh --skip-check`
-   rather than invoking a third check during review.
-2. **`scripts/_setup.sh` has run to completion in this session, and re-runs
-   clean.** A one-line specification change can still break a setup step, and a
-   pass that did not run it does not know. Then `scripts/_setup.sh --check` must
-   report every step `skipped`: it makes each step's own readiness test without
-   doing the work, which is what tells a real `skipped` from a step that only
-   looked done. A step that tests for a committed `manifest.json` skips on a
-   fresh clone whose git-ignored `lance/` vectors are missing, and the project
-   cannot search. When `STEPS` is empty, one successful `--check` is sufficient;
-   there is no execution or re-entrancy work to prove.
+1. **`zen check` passes after the last edit and setup**, in the mode the final
+   plan names: `review.sh check no-sandbox` unless the plan reaches **sandbox
+   image**, then `review.sh check full --fix`. When an initial diagnostic is
+   needed, use `zen check --no-models --no-sandbox`; do not repeat expensive
+   probes before and after editing. Reuse the final receipt with
+   `review.sh --skip-check` in the same mode rather than invoking a third check
+   during review.
+2. **Setup satisfies the plan.** `scripts/_setup.sh --check` must report every
+   step `skipped`: it makes each step's own readiness test without doing the
+   work, which is what tells a real `skipped` from a step that only looked done.
+   When the plan reaches **setup** or **index**, run `scripts/_setup.sh` to
+   completion in this session and re-run it clean first: a step that tests for a
+   committed `manifest.json` skips on a fresh clone whose git-ignored `lance/`
+   vectors are missing, and the project cannot search. When `STEPS` is empty,
+   one successful `--check` is sufficient.
 3. **§9 of the copilot instructions, worked as a checklist**, group by group.
-4. **The capability obligations in §0.1.** Load a capability skill only when
-   changed requirements, files, keys or unresolved work reach that capability.
+4. **The capability obligations in §0.1**, through the skills the plan names.
    For a full pass, every enabled capability is in scope. `zen check` must
    still report no `rules.stale`, whether or not its capability was in scope.
 5. **`zen-instructions` is loaded before editing a project-owned house rule.** A pass
@@ -330,7 +409,7 @@ claims supplied to it. Run `commit` separately, only after verification.
 ## Scope
 
 What drove the pass: the diff hunks, the feedback entries, what the last pass
-left open. `full` if it was a full pass.
+left open, and the first and final plans. `full` if it was a full pass.
 
 ## Changed
 

package/templates/project/env

@@ -14,15 +14,12 @@
 # It is in .gitignore, and should stay there. Everything else in the project is
 # meant to be read, copied and shared; this is the one file that is not.
 #
+# ZEN_ENV_FILE, set in the shell, names another file to read instead of this
+# one — `.env.test`, say — relative to the project.
+#
 # A credential *file* — GOOGLE_APPLICATION_CREDENTIALS — may be named by a path
 # relative to this directory. It is mounted into the sandbox where the agent
 # can read it, which is worth knowing before you point at one.
 
-# OPENAI_API_KEY=
 # ACME_API_TOKEN=
 # ACME_BASE_URL=https://api.example.test
-
-# Which model `zen meta` runs the meta agent on, for this project only. A zen
-# ref — `vertex/gemini-3.8-flash`, `openai/gpt-5.6-sol` — not a provider's wire
-# name. `zen meta model` shows where the answer came from.
-# ZENERA_META_MODEL=

package/templates/project/env.example

@@ -0,0 +1,12 @@
+# The names this project's environment needs, with no values.
+#
+# Copy it to .env and fill it in:
+#
+#     cp .env.example .env
+#
+# .env is git-ignored and holds the real values; this file is committed, so it
+# says which variables a clone has to supply without saying what they are. Add
+# a name here whenever you add one to .env or .env.test.
+
+# ACME_API_TOKEN=
+# ACME_BASE_URL=

package/templates/project/env.test

@@ -0,0 +1,12 @@
+# This project's environment for test chats: the Test tab in Zenera Lite.
+#
+# Read instead of .env, not on top of it: Zenera Lite runs test chats with
+# ZEN_ENV_FILE=.env.test, and only one file is ever read. So everything a test
+# chat needs goes here — a sandbox account's token, a staging or mock base url.
+# Edits reach the next test chat turn; nothing has to be restarted.
+#
+# It is in .gitignore, like .env: a test credential is still a credential.
+# Name any variable you add here in .env.example as well.
+
+# ACME_API_TOKEN=
+# ACME_BASE_URL=https://staging.example.test

package/templates/project/gitignore

@@ -14,8 +14,9 @@ memory/.lock
 # Scratch, inside the workspace so the sandbox can reach it.
 .tmp/
 
-# Credentials.
+# Credentials, and the ones test chats use instead.
 .env
+.env.test
 
 # A rag index commits everything except its vectors: they are binary, they are
 # large, and `zen rag <subject> restore` rebuilds them from the copies of the