@zenera/cli 1.1.42 → 1.1.44

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

@@ -1,7 +1,7 @@
 # Copilot instructions - agent projects
 
 > Written by `zen init` into `.github/copilot-instructions.md`, alongside the
-> prompt files and skills in the same tree (§2.4). VS Code loads it
+> skills and commands in the same tree (§2.4). VS Code loads it
 > automatically for every request in this folder, so it is the standing brief
 > for anyone - human or agent - editing this project.
 >
@@ -35,12 +35,15 @@ programmed: what an agent knows, which model answers, and which of the tools
 6. Every change must still load: `agents.yaml` is validated strictly at load,
    and `zen check` says so before a model is ever called.
 
-### 0.1 Copilot is the meta-agent: load the skill for every capability in use
+### 0.1 Copilot is the meta-agent: load skills for the capabilities in scope
 
 Copilot is always the meta-agent that creates and changes target projects. Load
 the editor's `zen-cli` skill before deciding how a target project should run,
 be validated, or use command-line capabilities. It is the command contract; do
 not reconstruct `zen` arguments from memory or call `--help` to discover them.
+When the task is to bring a project into compliance with `SPECIFICATION.md`,
+load `zen-spec-sync` first; its narrow tiers contain the exact validation
+commands and do not require loading `zen-cli` as well.
 
 **Every runtime capability a project turns on carries obligations that are not
 visible in `agents.yaml` and that `zen check` does not report.** Before
@@ -54,20 +57,23 @@ code, `zen-topology` for `handoffs:` or `fork:` on any agent,
 `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
-change - a task scoped to `SPECIFICATION.md` does not narrow it. There is one
-exception: a `/spec-sync-project` pass that the `zen-spec-sync` skill classes as
-**spec-only**. It touches no agent, prompt, skill or wiring, so there is no
-obligation for it to meet.
+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.
 
 **Load `zen-instructions` before writing, editing, reviewing or deleting any
 `agents/*instructions.md`.** They are the house rules, prepended to every
-agent's prompt, and three of them are `zen`'s own copies rather than the
+agent's prompt, and four of them are `zen`'s own copies rather than the
 project's: an edit made inside one is lost at the next `zen check --fix`, `zen
 init` or `zen open`, with no diff to show for it. The skill is what says which
-three those are, where a project's own rules on the same subjects go instead,
+four those are, where a project's own rules on the same subjects go instead,
 how `requires:` conditions a document, and what filename order decides. None of
 that is visible in the file being edited.
+Replacing generated copies with `zen check --fix` is maintenance, not manual
+house-rule editing, and does not by itself require loading `zen-instructions`.
 
 **Load `zen-code-python` before writing, editing or reviewing any prompt, skill
 or house rule for an agent that writes or runs code** - any agent holding
@@ -251,8 +257,7 @@ Two consequences that drive nearly every design rule in this document:
 my-project/
 ├── .github/                      the editor's brief - §2.4
 │   ├── copilot-instructions.md   this file
-│   ├── prompts/*.prompt.md       tasks you invoke by name
-│   └── skills/*/SKILL.md         reference the editor loads on demand
+│   └── skills/*/SKILL.md         zen-* reference loaded on demand; the rest /commands
 ├── .env                          this project's environment - NEVER committed
 ├── .spec-sync/                   what the last /spec-sync-project applied - §0.1
 ├── agents.yaml                   who exists, what they may reach for
@@ -349,15 +354,18 @@ agents do, for the same reason - it is a prefix somebody pays for:
 
 - **`copilot-instructions.md`** is always on. Everything in it is loaded for
   every request in this folder, so it holds only what is true of every task.
-- **`.github/skills/<name>/SKILL.md`** is reference the editor loads when its
-  `description` matches what you asked. Put long, occasional material here -
-  a command surface, a vendor's quirks, a format spec - not in the file above.
-  The `description` is the routing key; §3.4 applies to these as much as to the
-  project's own skills.
-- **`.github/prompts/<name>.prompt.md`** is a task you invoke by name (`/name`),
-  with `mode: agent` and a `description` in its frontmatter. Write one when a
-  job is done repeatedly and has a right order - adding an agent, adding a
-  skill, reviewing before a commit.
+- **`.github/skills/zen-<name>/SKILL.md`** is reference the editor loads when
+  its `description` matches what you asked. Put long, occasional material here
+    - a command surface, a vendor's quirks, a format spec - not in the file above.
+      The `description` is the routing key; §3.4 applies to these as much as to the
+      project's own skills. `user-invocable: false` keeps them out of the `/` menu.
+- **`.github/skills/<name>/SKILL.md`** without the `zen-` prefix is a command
+  you invoke by name (`/name`, or `zen meta run /name`), with
+  `disable-model-invocation: true` so the model never starts one on a hunch,
+  and an `argument-hint` when it takes words. Write one when a job is done
+  repeatedly and has a right order - adding an agent, adding a skill, reviewing
+  before a commit. It holds the order of the work and loads the `zen-*` skills
+  that hold the rules.
 
 `zen init` and `zen open` rewrite this whole tree from the version of `zen` in
 hand, so **edits inside `.github/` do not survive**. Project-specific conventions
@@ -1885,6 +1893,11 @@ the spec-sync record, in that order:
 
 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
+checklist.
 
 Before finishing any change here:
 
@@ -2086,8 +2099,8 @@ install` is an `image:` that was never set - §3.7.
 
 This file is loaded on every request in this repository, so it is subject to its
 own rules: stable, factual, no hedging. Before adding a section, ask whether it
-is true of every task - if it is not, it is a skill under `.github/skills/`, or
-a prompt file under `.github/prompts/` if it is a procedure (§2.4).
+is true of every task - if it is not, it is a `zen-*` skill under
+`.github/skills/`, or a command skill there if it is a procedure (§2.4).
 
 Update it when:
 

package/templates/editor/.github/{prompts/analyze.prompt.md → skills/analyze/SKILL.md}

@@ -1,5 +1,8 @@
 ---
+name: analyze
 description: Analyze one recorded run of this project - its health, what it wasted, and what to change in the instructions. Name the run (directory or id) after the command, or get the most recent one.
+argument-hint: '[run directory or run id]'
+disable-model-invocation: true
 ---
 
 Load the **zen-analyze-run** skill and follow it to analyze one run of this
@@ -10,10 +13,10 @@ audit cannot be graded without it.
 
 ## Which run
 
-The line after this prompt may name the run - a run directory or a run id.
-If it does, use it. Words after it like `case=<id> ... feedback=<file>` mean
+The words given with the command may name the run - a run directory or a run
+id. If they do, use it. Words after it like `case=<id> ... feedback=<file>` mean
 the tuning loop sent you: follow section 7 of the skill and write that file.
-A `## The brief` section below that line is what the loop already ran for
+A `## The brief` section below them is what the loop already ran for
 you: section 1 of the skill says how to use it.
 
 If it does not, list this project's most recent runs, newest first:

package/templates/editor/.github/{prompts/dataset.prompt.md → skills/dataset/SKILL.md}

@@ -1,17 +1,20 @@
 ---
+name: dataset
 description: Build or refresh this project's dataset - every case read from its sources with a class, complexity, tags, a verbatim rubric and an anchor - re-reading only the sections that changed since the last revision. Name a source after the command to add it, `rebuild` to read everything again, or a case and what to fix.
+argument-hint: '[source file | rebuild | <case id> <what to fix>]'
+disable-model-invocation: true
 ---
 
 Keep `dataset/` in step with its sources. **Load the `zen-dataset` skill before
 anything else**, and `zen-cli` for the command reference. The skill holds the
-extraction rules and every verb; this prompt is the order of the work. If
+extraction rules and every verb; this command is the order of the work. If
 loading a skill fails, read `.github/skills/<name>/SKILL.md` with your file tool
 before going on.
 
 You never run cases, never edit `agents/`, and never edit a source. Only
 `zen meta dataset` writes `dataset/` - never a file tool, never a script.
 
-This prompt is **reentrant**: the state on disk says what to do, so running it
+This command is **reentrant**: the state on disk says what to do, so running it
 twice in a row does nothing the second time.
 
 ## 1. Where things stand
@@ -27,7 +30,7 @@ sections are `changed`, `gone` or `uncovered`.
 
 ## 2. What to do
 
-The last line of this prompt may hold words. Then read the table top down and
+Words may be given with the command. Then read the table top down and
 take the first row that fits:
 
 | State                                    | Do                                                                    |

package/templates/editor/.github/{prompts/finetune.prompt.md → skills/finetune/SKILL.md}

@@ -1,5 +1,8 @@
 ---
+name: finetune
 description: Fine-tune this project against a training set, a batch at a time - every batch first with no memory, fixing the instructions, then with the memory it just built, making the same work cheaper - starting from a 3-case smoke test and doubling each smooth batch, until every case is used and no difficult case is open.
+argument-hint: '[training set] [limit]'
+disable-model-invocation: true
 ---
 
 Tune this project against real queries. Nothing here touches model weights: what
@@ -9,7 +12,7 @@ queries produce.
 
 **Load the `zen-finetune` skill before anything else**, and load `zen-inspect`,
 `zen-analyze-run`, `zen-topology` and `zen-inspect-ask` before you grade, and
-`zen-instructions` before you write a policy file. This prompt is the order of the work; the skill
+`zen-instructions` before you write a policy file. This command 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. If
 loading a skill fails, read `.github/skills/<name>/SKILL.md` with your file tool
 before going on - never carry on without it.
@@ -28,7 +31,7 @@ command:
 | one memory node in full                      | `zen memory show <node-id> --dir "$RUN/batch/<id>/memory"`        |
 | a whole memory, or what one added to another | `zen memory ls --dir <dir>`, `zen memory diff <base> --dir <dir>` |
 
-This prompt is **reentrant**. Tuning is long and gets interrupted - a run dies, a
+This command is **reentrant**. Tuning is long and gets interrupted - a run dies, a
 session ends, I stop you mid-batch. Every step leaves its result on disk under
 `finetune/`, so a second invocation does not start over: it reads that state,
 works out where the work stopped, says so, and carries on from there unless I
@@ -199,7 +202,7 @@ in your reports instead of re-typing it.
 
 ## Where you are - work this out before anything else
 
-Do this every time this prompt runs, including the first:
+Do this every time this command runs, including the first:
 
 ```sh
 .github/skills/zen-finetune/scripts/next.mjs
@@ -208,7 +211,7 @@ Do this every time this prompt runs, including the first:
 ```
 
 `next.mjs` reads the whole `finetune/` tree and prints the next step. Do not
-re-derive the state from an `ls`. Map what it says onto this prompt:
+re-derive the state from an `ls`. Map what it says onto this command:
 
 | What `next.mjs` says                                             | Go to                                                                             |
 | ---------------------------------------------------------------- | --------------------------------------------------------------------------------- |

package/templates/editor/.github/{prompts/new-agent.prompt.md → skills/new-agent/SKILL.md}

@@ -1,6 +1,8 @@
 ---
-mode: agent
+name: new-agent
 description: Add an agent to agents.yaml, with its prompt, tools and handoffs.
+argument-hint: "[the agent's job in one sentence]"
+disable-model-invocation: true
 ---
 
 Add an agent to this project. Ask for the one sentence that states its job

package/templates/editor/.github/{prompts/new-skill.prompt.md → skills/new-skill/SKILL.md}

@@ -1,6 +1,8 @@
 ---
-mode: agent
+name: new-skill
 description: Add a skill under agents/skills, with a description that routes.
+argument-hint: '[what the skill says and when it applies]'
+disable-model-invocation: true
 ---
 
 Add a skill to this project. A skill is curated instruction content - and

package/templates/editor/.github/{prompts/project-review.prompt.md → skills/project-review/SKILL.md}

@@ -1,5 +1,7 @@
 ---
+name: project-review
 description: Review the project against the checklist before committing.
+disable-model-invocation: true
 ---
 
 Review this project the way a maintainer would, then report. Read
@@ -18,6 +20,10 @@ spec-sync record, in the order they matter. Load the `zen-review` skill for what
 each one owns and how to read its output. Do not re-verify by hand anything it
 already decided, and do not go further while `zen check` fails - nothing below
 matters until it passes.
+If `review.sh check` already passed in this conversation and nothing has been
+edited since, run `review.sh --skip-check` instead: it verifies that receipt
+rather than probing again, and fails if the project changed. Reusing the check
+does not narrow the review - everything below still covers the whole project.
 
 **Then list the capabilities this project turns on** — a `memory:` block, a
 `zen rag` index, a sandbox, an agent that writes code (`zen-code-python`), a

package/templates/editor/.github/{prompts/spec-apply-feedback.prompt.md → skills/spec-apply-feedback/SKILL.md}

@@ -1,5 +1,7 @@
 ---
+name: spec-apply-feedback
 description: Fold the answers left in SPECIFICATION-FEEDBACK.md back into SPECIFICATION.md, and mark each answered question as answered.
+disable-model-invocation: true
 ---
 
 `SPECIFICATION-FEEDBACK.md` is a questionnaire. Each question carries two to

package/templates/editor/.github/{prompts/spec-edit.prompt.md → skills/spec-edit/SKILL.md}

@@ -1,9 +1,11 @@
 ---
-description: Change SPECIFICATION.md as the request after the command asks - written in the specification's own structure and voice, checked against what the runtime can actually do - and nothing else.
-argument-hint: what to add, change or remove in the specification
+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.
+argument-hint: 'what to add, change or remove in the specification'
+disable-model-invocation: true
 ---
 
-Edit `SPECIFICATION.md` the way the request after this command asks. The
+Edit `SPECIFICATION.md` the way the request given with this command asks. The
 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.
@@ -11,41 +13,41 @@ runs after this.
 You change one file: `SPECIFICATION.md`. Not `agents.yaml`, not a prompt, not a
 skill, not `SPECIFICATION-FEEDBACK.md`.
 
-## 0. Everything you need is already attached
+## 0. Read everything you need first
 
-These files are attached to this prompt so the work starts without a round of
-reads. Use them as they are; do not read them again with a tool.
+These are the files the work depends on. Read them before anything else, so
+the work starts from all of them rather than from a round of reads later.
 
 The project:
 
-- [SPECIFICATION.md](../../SPECIFICATION.md) - the file you are editing.
-- [SPECIFICATION-FEEDBACK.md](../../SPECIFICATION-FEEDBACK.md) - the questions
+- [SPECIFICATION.md](../../../SPECIFICATION.md) - the file you are editing.
+- [SPECIFICATION-FEEDBACK.md](../../../SPECIFICATION-FEEDBACK.md) - the questions
   still open against it, and the ones already answered. It may not exist; that
   only means nothing is open.
 
 What the runtime can do, so that what you write is something it can build:
 
-- [zen-cli](../skills/zen-cli/SKILL.md) - every `zen` command, and
-  [its models reference](../skills/zen-cli/references/models.md) - how to find
+- [zen-cli](../zen-cli/SKILL.md) - every `zen` command, and
+  [its models reference](../zen-cli/references/models.md) - how to find
   which models this machine can actually use.
-- [zen-instructions](../skills/zen-instructions/SKILL.md) - house rules: what
+- [zen-instructions](../zen-instructions/SKILL.md) - house rules: what
   every agent is told, and what belongs there rather than in a prompt.
-- [zen-topology](../skills/zen-topology/SKILL.md) - one agent or several,
+- [zen-topology](../zen-topology/SKILL.md) - one agent or several,
   hand-off or fork, and what each costs.
-- [zen-memory](../skills/zen-memory/SKILL.md) - what memory is, who may read and
+- [zen-memory](../zen-memory/SKILL.md) - what memory is, who may read and
   write it, and what a strategy for it has to say.
-- [zen-rag-docs](../skills/zen-rag-docs/SKILL.md) - an index over a folder of
+- [zen-rag-docs](../zen-rag-docs/SKILL.md) - an index over a folder of
   markdown documents.
-- [zen-rag-schema](../skills/zen-rag-schema/SKILL.md) - an index over an OpenAPI
+- [zen-rag-schema](../zen-rag-schema/SKILL.md) - an index over an OpenAPI
   description.
-- [zen-sandbox](../skills/zen-sandbox/SKILL.md) - the container: what it mounts,
+- [zen-sandbox](../zen-sandbox/SKILL.md) - the container: what it mounts,
   what it can reach, what persists.
-- [zen-code-python](../skills/zen-code-python/SKILL.md) - reusable scripts as
+- [zen-code-python](../zen-code-python/SKILL.md) - reusable scripts as
   tools, where they live, and which agents own them.
 
-If any of these did not arrive attached - your editor does not resolve links in
-prompt files - read all of them in **one** batch of parallel reads before doing
-anything else, `SPECIFICATION-FEEDBACK.md` included if it exists. Never one at a
+Any of these already in your context - attached, or loaded as a skill - you
+need not read again. Read the rest in **one** batch of parallel reads before
+doing anything else, `SPECIFICATION-FEEDBACK.md` included if it exists. Never one at a
 time, and never skip one because the request seems not to need it: a request
 about an agent's job can still decide what that agent may remember.
 
@@ -60,7 +62,7 @@ That is the list of models with a credential on this machine - the only ones a
 `zen models search <name>` once; if it is still absent, say so in the chat and
 do not write it.
 
-If there is no request after the command, ask what to change and stop.
+If no request was given with the command, ask what to change and stop.
 
 ## 1. Understand the request against what is there
 
@@ -245,6 +247,7 @@ In the chat:
   needs a value only the reader has
 - then, in one line: send `/spec-sync-project` to make the project match.
 
-## 5. User Request:
+## 5. The request
 
-Following is the user request that the specification should address (if any):
+The words given with the command are the request the specification should
+address. Without them, ask what to change and stop (§0).

package/templates/editor/.github/{prompts/spec-sync-project.prompt.md → skills/spec-sync-project/SKILL.md}

@@ -1,5 +1,8 @@
 ---
+name: spec-sync-project
 description: Bring the project into compliance with SPECIFICATION.md, and record every open question in SPECIFICATION-FEEDBACK.md.
+argument-hint: '[file or area to focus on]'
+disable-model-invocation: true
 ---
 
 Make this project match `SPECIFICATION.md`. The specification is the intent;
@@ -29,11 +32,15 @@ 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**: §6, §7 and the five checks in the skill run at full size on every
-pass, however small the diff. The one exception is the skill's **spec-only
-pass**, and only under the conditions the skill sets.
+**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
@@ -55,15 +62,17 @@ Read, in this order, and do not edit until all of it is read:
 6. `SPECIFICATION-FEEDBACK.md`, if it exists - do not re-raise something already
    open there.
 
-Never read `.tmp/logs/meta.*` - those are other runs of this prompt, not
+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.
 
-Run `zen check` first and record what it said. A project that does not load is
-the first thing to fix.
+If an initial diagnostic is needed, run
+`zen check --no-models --no-sandbox` and record what it said. A project that
+does not load is the first thing to fix. Do not run expensive model or sandbox
+probes both before and after a narrow edit; the final check covers them.
 
 ## 2. Build the difference
 
@@ -102,10 +111,13 @@ 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 file this pass touched
+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.
 
 ## 3. Change the smallest thing that closes the gap
 
@@ -127,8 +139,8 @@ the model to compute or remember. Specifically:
   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 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. The pin
+  `sandbox.pin.absent` and `sandbox.pin.stale`, and `zen check --fix` repairs
+  both by rewriting only the version after each `@zenera/*` name. The pin
   follows `zen --version` even when `SPECIFICATION.md` names another number.
   The `zen-spec-sync` skill gives the one question to raise in that case.
 
@@ -395,10 +407,12 @@ that replaced it, and leave the newer text alone.
 ## 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 exception is a spec-only
-pass, as the `zen-spec-sync` skill defines it: there `scripts/_setup.sh --check`
+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.
+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.
 
 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
@@ -436,10 +450,18 @@ blind:
 
 ## 7. Verify and report
 
-Run `zen check` again and fix whatever it names rather than working around it.
+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
 copilot instructions as a checklist afterwards and report each group pass or
-fail. Then report in the chat:
+fail, narrowed only by the skill's tier rules. 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
@@ -450,7 +472,9 @@ fail. Then report in the chat:
 
 ## 8. Record the pass
 
-Last, and only once §6 and §7 have actually passed. Write
+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:
@@ -468,4 +492,4 @@ 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.
 
 Do not report a specification item as done unless the file that implements it
-exists, `zen check` passes, and `scripts/_setup.sh` completed every step it owns.
+exists, `zen check` passes, and setup satisfies the selected tier's proof.

package/templates/editor/.github/skills/zen-analyze-run/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: zen-analyze-run
 description: 'Use when asked to analyze, audit or review one recorded Zenera run as a whole - how healthy it was, whether memory was used and saved correctly, whether delegation and forking were right, where tools were misused and time or tokens wasted - and which sentence in the prompts, skills, house rules or tool descriptions to change so the next run does better. Needs a run directory or run id.'
+user-invocable: false
 ---
 
 # Analyze a run

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

@@ -1,6 +1,7 @@
 ---
 name: zen-cli
 description: How to drive this project from the terminal with `zen` - running it, validating it, credentials, the sandbox, run reports, and the `gym` and `rag` modules.
+user-invocable: false
 ---
 
 # The `zen` command line
@@ -44,25 +45,25 @@ The full reference lives next to this file, one document per part of the command
 line. **Read the one that covers the question before answering it** - do not
 guess a flag, and do not read them all.
 
-| The question is about                                               | Read                                                            |
-| ------------------------------------------------------------------- | --------------------------------------------------------------- |
-| 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)                             |
-| 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 gym` - a mock API from an OpenAPI/Swagger document             | [gym.md](./references/gym.md)                                   |
-| `zen rag` - searching an API description, or a pile of markdown     | [rag.md](./references/rag.md)                                   |
+| The question is about                                                | Read                                                            |
+| -------------------------------------------------------------------- | --------------------------------------------------------------- |
+| 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)                             |
+| The meta agent: `zen meta run`, its `/commands`, 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 gym` - a mock API from an OpenAPI/Swagger document              | [gym.md](./references/gym.md)                                   |
+| `zen rag` - searching an API description, or a pile of markdown      | [rag.md](./references/rag.md)                                   |
 
 ## The short version
 
@@ -70,7 +71,8 @@ guess a flag, and do not read them all.
 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 "what changed?"               one answer, in a fresh session directory
+zen run --here "what changed?"        ... about the files in this directory
 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
@@ -81,7 +83,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 ls --embeddings            the embedders this machine can reach
-zen meta run acme /analyze --json > analyze.json   a stored prompt, the result as JSON
+zen meta run acme /analyze --json > analyze.json   a command, the result as JSON
 ```
 
 ## Searching documents without help

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

@@ -55,7 +55,8 @@ checked too. A word that is neither is a usage error (exit 2), not a report.
   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.
+  is reported with `--no-sandbox` too. `--fix` rewrites the pins to this `zen`'s
+  version and touches nothing else in the Dockerfile.
 
 ### Findings
 

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

@@ -30,7 +30,7 @@ tries used up  ->  difficult
 - **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
+  together by `/zen-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

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

@@ -2,8 +2,8 @@
 
 ```
 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 run [project] /<name> [words]     run the command .github/skills/<name>/SKILL.md
+zen meta prompts [project]                 list the commands (skills without zen-)
 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