@zenera/cli 1.1.43 → 1.1.45

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/skills/spec-edit/SKILL.md

@@ -0,0 +1,324 @@
+---
+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.
+argument-hint: 'what to add, change or remove in the specification'
+disable-model-invocation: true
+---
+
+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.
+
+You change one file: `SPECIFICATION.md`. Not `agents.yaml`, not a prompt, not a
+skill, not `SPECIFICATION-FEEDBACK.md`.
+
+## 0. Size the edit, then read only what it needs
+
+If no request was given with the command, ask what to change and stop.
+
+### Decide the kind of edit first
+
+From the request and `SPECIFICATION.md` alone, before reading anything else:
+
+- **Greenfield** - `SPECIFICATION.md` is still the `zen init` scaffold (generic
+  placeholders such as "Carry out work inside a workspace on request…",
+  "Currently: no steps", "the only agent; nobody to hand work to"), or the
+  request asks to define or make a specification for a project or domain.
+- **Incremental** - anything else: the specification already describes a real
+  project and the request asks for a specific change.
+
+Then decide which sections the request touches (§1), because that decides
+which skills you read.
+
+### Read in one batch
+
+Always:
+
+- [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. On
+a **greenfield** edit read all of them. On an **incremental** edit read only the
+ones for the sections the request touches; when unsure whether a section is
+touched, read its skill:
+
+| Section touched                                             | Skill                                                                                                                                               |
+| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Agents** (split, hand-off, fork)                          | [zen-topology](../zen-topology/SKILL.md) - one agent or several, hand-off or fork, and what each costs                                              |
+| **Tools and boundaries** (scripts, writing or running code) | [zen-code-python](../zen-code-python/SKILL.md) - reusable scripts as tools, where they live, and which agents own them                              |
+| **Knowledge** / **Setup** (index over OpenAPI)              | [zen-rag-schema](../zen-rag-schema/SKILL.md) - an index over an OpenAPI description                                                                 |
+| **Knowledge** / **Setup** (index over documents)            | [zen-rag-docs](../zen-rag-docs/SKILL.md) - an index over a folder of markdown documents                                                             |
+| **Memory**                                                  | [zen-memory](../zen-memory/SKILL.md) - what memory is, who may read and write it, and what a strategy for it has to say                             |
+| **Environment** (image, packages, network, persistence)     | [zen-sandbox](../zen-sandbox/SKILL.md) - the container: what it mounts, what it can reach, what persists                                            |
+| Rules every agent is told                                   | [zen-instructions](../zen-instructions/SKILL.md) - house rules, and what belongs there rather than in a prompt                                      |
+| **Models**                                                  | [zen-cli](../zen-cli/SKILL.md) and [its models reference](../zen-cli/references/models.md) - how to find which models this machine can actually use |
+
+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, never
+one at a time.
+
+### Models
+
+Run this once from the project root, in the same batch, only when the edit is
+greenfield, the request names or changes a model, or the specification will use
+`memory/`, `assets/docs-db` or `assets/schema-db` and **Models** has no
+embedding model yet:
+
+```sh
+zen models && zen models ls --chat && zen models ls --embeddings
+```
+
+That is the list of models with a credential on this machine - the only ones a
+new **Models** line may name. A model the request names that is not in it: run
+`zen models search <name>` once; if it is still absent, say so in the chat and
+do not write it. A model already in `SPECIFICATION.md` that the request does not
+mention is kept as it is and not checked.
+
+### What you never read
+
+This command changes intent, not implementation, so it needs nothing from the
+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
+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.
+
+What you would have looked up - an endpoint, an auth scheme, a base URL, a
+file layout, how an existing script works - is either stated by role in the
+specification (§3, "Unknowns are named, not researched") or settled later by
+`/spec-sync-project`, which reads the project.
+
+### Then edit
+
+Once that one batch is read, your next action is the edit to
+`SPECIFICATION.md`. If you feel the need to read something more, do not: put it
+in the report as an open question instead.
+
+## 1. Understand the request against what is there
+
+Before writing a line, work out - from the request, `SPECIFICATION.md`, the
+feedback file and the skills you read, nothing else:
+
+- **How far the edit reaches.** A **greenfield** edit (§0) reaches **every**
+  section: replace all generic template sentences and meta-explanations with a
+  complete, concrete specification for that domain. An **incremental** edit
+  stays narrow: touch only the sections the change implicates.
+- **Which sections the request touches.** Usually more than the one it names: a
+  new agent changes **Agents**, **Tools and boundaries** and **Done means**; an
+  index changes **Setup**, **Knowledge** and **Environment**.
+- **What it contradicts.** A sentence already in the specification that the
+  request makes false is part of the edit - change it too, and report it.
+- **What it settles in the feedback file.** An open question the request
+  answers, or an answered one it reverses. Do not edit the feedback file; say
+  which questions in the chat.
+- **Whether the runtime can do it.** Check the request against the skills you
+  read. Something no tool, agent setting or script can provide is not written
+  into the specification as if it could be: say so in the chat, offer the
+  nearest thing the runtime does do, and write that only if the request leaves
+  no doubt it is wanted.
+
+### Example: a narrow incremental request
+
+Request: _"let the agent write code against our appliance's REST API, index the
+API specs in `resources/apis/*.yaml`, and add a skill on how to write code for
+that API"_, on a specification that already describes the project.
+
+- Kind: incremental.
+- Sections: **Agents** (which agent writes and runs the code), **Tools and
+  boundaries** (scripts in `/workspace/scripts/`, the API it may call, what
+  stays read-only), **Setup** and **Knowledge** (a `zen rag schema` index over
+  `resources/apis/*.yaml` in `assets/schema-db`, and the new skill under
+  `agents/skills/` with what it holds), **Environment** (the libraries and the
+  network access the code needs, credentials by env-var name), **Models** only
+  if no embedding model is listed yet, **Done means** (one checkable line per
+  new behaviour).
+- Skills read: zen-topology, zen-code-python, zen-rag-schema, zen-sandbox -
+  plus zen-cli only if an embedding model has to be added.
+- Not read: the API spec files, existing scripts, agents, examples, the
+  environment.
+- In the report: the base URL, auth scheme and any other value only the reader
+  has, written into the specification by role and env-var name.
+
+Once these are worked out, your next action is the edit.
+
+## 2. The structure of a specification
+
+Keep the sections the file already has, in its order. Add a section only when
+the request needs one, at its place in this order, and leave out any section
+that would be empty:
+
+```markdown
+# Specification
+
+## Purpose
+
+## Scope
+
+## Models
+
+## Setup
+
+## Agents
+
+## Tools and boundaries
+
+## Knowledge
+
+## Memory
+
+## Environment
+
+## Testing
+
+## Done means
+
+## Out of scope
+```
+
+What each one answers:
+
+- **Purpose** - what the system produces, and for whom, in one paragraph.
+- **Scope** - what one request covers, what is in and what is not, hard numeric
+  bounds (when a request is refused with a count rather than truncated), and
+  what has to happen before the system acts.
+- **Models** - every chat and embedding model by its full id from `zen models`,
+  and which agent or job uses which. Keep the chat model already in
+  `SPECIFICATION.md` unless the request asks to change it; add an embedding
+  model from `zen models ls --embeddings` whenever the specification uses
+  `memory/`, `assets/docs-db`, or `assets/schema-db`.
+- **Setup** - what has to exist before a run: OpenAPI specs or reference
+  documents fetched, a `zen rag schema` index built in `assets/schema-db`, a
+  `zen rag docs` index built in `assets/docs-db`, or reference files generated.
+  Each is a named step `scripts/_setup.sh` runs in order; say what it produces,
+  from what inputs, and where it lands.
+- **Agents** - one entry per agent: its name, its one job, who it hands to or
+  forks, and the behaviours that are specific to it. Use **zen-topology** to
+  choose the right shape: split into focused agents (for example, a lead
+  coordinator/analyst, a dedicated quantitative/code agent, and a read-only
+  research agent) when tasks have distinct tool boundaries or heavy code
+  execution (**zen-code-python**), and specify `fork` (`context: none`) when a
+  request compares multiple independent items or runs independent research
+  tracks in parallel.
+- **Tools and boundaries** - what each agent may reach for (files, shell,
+  reusable scripts in `/workspace/scripts/`, web search/read, memory, indexes,
+  external APIs), what is read-only, how transient network/API errors are
+  retried and fallen back from, and what nothing may reach. Every capability
+  named here has an agent that holds it.
+- **Knowledge** - each index (`assets/schema-db`, `assets/docs-db`), each skill
+  under `agents/skills/` (naming the skill and the concrete procedure, formulas,
+  API conventions, or `rag_search` rules it holds), and the concrete external
+  APIs or data sources the project queries (naming specific zero-key primary
+  APIs and endpoints, required headers and rate limits, optional free-tier
+  keyed APIs, and fallback order).
+- **Memory** - what is worth remembering (reusable scripts as `file` nodes,
+  verified identifiers/mappings, API schemas, workflows) and what is not (or
+  how time-sensitive facts are bounded), who may read and write, and when an
+  agent recalls before working and commits after it - see **zen-memory**.
+- **Environment** - the sandbox (`sandbox/Dockerfile`, persistence, network),
+  the exact languages, CLI tools, and libraries pre-installed in the image so
+  agents never install packages at run time, where scripts and data outputs
+  live under `/workspace`, and the environment variables or credentials the
+  project itself needs (an external API, a service) by name - see
+  **zen-sandbox**. Never the credentials of chat or embedding models (§3).
+- **Testing** - how a change to the project is checked: `zen check`,
+  `scripts/_setup.sh --check`, `scripts/_setup.sh` run twice in a row reporting
+  `skipped` the second time, and a concrete verification request the project
+  must handle end-to-end.
+- **Done means** - how a finished job is told from an unfinished one, written as
+  concrete acceptance tests in prose that a reviewer could check against a run
+  (exact attribution fields, script-computed numbers, verified page reads,
+  reusable script paths, and required sections).
+- **Out of scope** - what the runtime could do that this project deliberately
+  does not, so nobody adds it because it seemed useful.
+
+## 3. How to write it
+
+- **Replace scaffold boilerplate on a greenfield request; change the smallest
+  thing on an incremental edit.** When `SPECIFICATION.md` is still the initial
+  `zen init` scaffold or the request asks to make a specification for a new
+  project, rewrite every section for that domain and remove the scaffold's
+  generic meta-commentary ("What the work always needs belongs in the image…",
+  "Currently: no steps…", "The reply names what changed, file by file…"). When
+  editing an already-written domain specification, leave every sentence the
+  request does not reach as it is.
+- **Write in a direct, declarative voice.** Match the clean heading and list
+  structure of the specification, stating concrete project rules rather than
+  abstract explanations of how Zenera works.
+- **Say what and why, never raw config syntax.** The specification is not
+  `agents.yaml` in prose. Name the agents, skills, setup steps, indexes, APIs,
+  packages, paths, and behavioural rules clearly, without pasting raw YAML
+  snippets or shell implementation internals that `/spec-sync-project` derives.
+- **On a greenfield request, turn high-level domain requests into concrete
+  architectural choices.** When a request asks to design a project in broad
+  terms (for example, "make a specification for financial analytics using open
+  APIs"), do not repeat vague phrases like "open APIs" or "packages for data
+  analysis". Make the concrete domain choices upfront, from what you know of
+  public APIs and libraries and from the skills you read, so
+  `/spec-sync-project` can build a working system without guessing:
+    - Name specific, working zero-key public APIs and endpoints as primary
+      sources (with required headers such as `User-Agent` and rate limits),
+      optional keyed free-tier APIs as secondary sources with clean zero-key
+      fallback when keys are absent, and `web_search` / `web_read` rules.
+    - Name the concrete setup steps (`scripts/<name>.sh`), indexes
+      (`assets/schema-db`, `assets/docs-db`), and domain skills under
+      `agents/skills/`.
+    - Name the exact Python/system libraries to pre-install in
+      `sandbox/Dockerfile` and the `/workspace/scripts/` and `/workspace/data/`
+      conventions from **zen-code-python**.
+    - State explicit numeric limits (such as the maximum entities/tickers per
+      request before refusing with a count), retry/fallback rules, and required
+      citation fields.
+- **On an incremental request, write what the request states.** Add what it
+  asks for, plus the changes it forces in other sections (§1), in the same
+  level of detail the specification already uses. Do not design beyond it.
+- **Unknowns are named, not researched.** A value the request and the
+  specification do not give - an endpoint, a base URL, an auth scheme, a
+  credential, a file layout - is written by role and env-var name (for example
+  "the appliance base URL from `APPLIANCE_URL`, credentials from
+  `APPLIANCE_USER` and `APPLIANCE_PASSWORD`") and listed in the report as a
+  value only the reader has. Never look for it in the project or the
+  environment, and do not stop to ask for it.
+- **Be specific where a reader could decide either way.** A limit is a number,
+  a model is an id, a failure has a stated outcome. "Handles large inputs" is
+  not implementable; "a request over 25 tickers is refused with a count, never
+  truncated" is.
+- **Never invent a model id or a user-owned secret.** Keep the model already in
+  `SPECIFICATION.md` unless the request asks to change it, and take any new
+  chat or embedding model strictly from the `zen models` output on this machine,
+  never from memory.
+- **Never name a model provider's credential.** `OPENAI_API_KEY`,
+  `ANTHROPIC_API_KEY`, `GOOGLE_APPLICATION_CREDENTIALS` and the like live in
+  the zen keyring and reach every run, setup step and sandbox without the
+  specification saying so. A **Models** line names the model id, not the key
+  behind it; **Environment** and the report list only the credentials of
+  external services the project calls. If `SPECIFICATION.md` already names a
+  model key, remove it as part of any edit to that section.
+- **Make it checkable.** Every behaviour the request adds gets a line under
+  **Done means** that a reviewer could verify against a recorded run.
+- **Name what is now excluded.** When the request narrows the system, the thing
+  it rules out goes under **Out of scope**.
+- **Say it once.** If the rule already lives in another section, change it
+  there rather than stating it a second time somewhere new.
+
+## 4. Report
+
+In the chat:
+
+- every section you changed, with each new or changed line quoted
+- every edit the request did not name but made necessary, and why
+- every open question in `SPECIFICATION-FEEDBACK.md` the change settles or
+  reopens, by number
+- 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)
+- then, in one line: send `/spec-sync-project` to make the project match.
+
+## 5. The request
+
+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
 
@@ -215,7 +227,9 @@ not a paragraph of instructions for a human.
   Deleting `.tmp/` must leave the project runnable and `scripts/_setup.sh`
   re-runnable.
 - Steps that need credentials run on the host, not in the sandbox. Read keys
-  from the environment or `.env`; never inline one into a script.
+  from the environment or `.env`; never inline one into a script. Model
+  provider keys are not among them: `zen` supplies those from its keyring, so
+  no step checks for, requires or documents one.
 - Anything the sandbox always needs belongs in `sandbox/Dockerfile`, not in a
   setup script that installs it again on every run.
 
@@ -395,10 +409,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 +452,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 +474,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 +494,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
 
@@ -82,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/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

package/templates/editor/.github/skills/zen-code-python/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: zen-code-python
 description: Code an agent writes must be a reusable tool that can be remembered and re-run, never a one-off. Holds the coding rules (`references/code_python.md`) and decides where they go in the target project - a section of a dedicated code agent's system prompt, or a coding skill for generic agents that sometimes run code - how to adapt them, and what a prompt or skill for a code-writing agent must never say. Load before writing, editing or reviewing any agent prompt, skill or house rule for an agent that writes or runs code - any agent holding `sandbox:*` or `run_command` - and before shipping a script inside a skill.
+user-invocable: false
 ---
 
 # Code an agent writes is a tool

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

@@ -1,6 +1,7 @@
 ---
 name: zen-dataset
 description: Keep a project's evaluation dataset in `dataset/` with `zen meta dataset` - every case read from its sources with a class, a complexity, tags, a verbatim rubric and an anchor to the section it came from. Covers extracting a training set of any shape into a proposal, applying it as a revision, finding which cases their sources moved under (drift) and re-reading only those sections, settling gone and uncovered sections, overriding a field by hand, leaving notes and verdicts on a case, reading a case's history and the sessions that touched it, and drawing samples by criteria (class, complexity, tag, rubric, revision, verdict, note kind, source, text) stratified, weighted and seeded. Load before building or refreshing a dataset, before running /dataset, before choosing which cases to run, and before writing a note or verdict on a case.
+user-invocable: false
 ---
 
 # The dataset

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

@@ -1,6 +1,7 @@
 ---
 name: zen-finetune
-description: Fine-tune an agent project against a training set, a batch at a time, and every batch twice over — first with NO memory, then WITH the memory it just built. Read the whole training set, in any format, into a classified, complexity-rated dataset with rubrics; choose up to a limit of cases from it evenly by class, rubric and complex cases first. Batch 1 is a smoke test of 3 cases; each batch that goes smoothly doubles the next, up to a maximum, and each is built when it is needed from new cases plus rechecks of earlier ones — difficult ones first, then complex ones. Each batch runs with an empty memory via `zen run batch`; every trajectory is graded with `zen inspect graph`, `node` and `ask` for rubric compliance, llm-call count, fork use, assumptions, what it committed to memory and delegation; the proposals of every case are merged into edits of prompts, skills, house rules and `agents/<topic>-policy-instructions.md` files, and the same cases run again until they pass. Then what the passing run's cases committed is merged with the last good memory into a candidate, every case runs again from its own copy of it, recall and re-commits are graded the same way, the memory policy is tuned until recall makes the work dramatically cheaper without changing a verdict or re-committing what memory already held — and only then does the candidate become the last good memory and the next batch start. Cases that cause the most trouble go on a difficult list and keep coming back until they are fixed or declared stuck. The agent writes `finetune/README.md` — the plan, a mermaid map of every step, and the progress — before the first run and patches it after every step; `scripts/next.mjs` reads the state off disk so an interrupted session can resume. Load before evaluating an agent project against example queries, before acting on "it gets this wrong", when asked to improve prompts or instructions from evidence rather than taste, when building an eval or regression set out of a specification, when optimising memory use or run cost, or whenever a batch of runs has to be graded rather than merely executed.
+description: Fine-tune an agent project's prose - prompts, skills, house rules, policy files - against a training set, a batch at a time, each batch first with NO memory and then WITH the memory it built. Batch 1 is a 3-case smoke test, each smooth batch doubles the next, and earlier difficult and complex cases come back as rechecks. Trajectories are graded with `zen inspect`, proposals merged into edits, and runs repeated until they pass; then the committed memory becomes a candidate and the memory policy is tuned until recall makes the work cheaper. `finetune/README.md` and `scripts/next.mjs` keep the state on disk so an interrupted session resumes. Load before evaluating a project against example queries, acting on "it gets this wrong", improving instructions from evidence, building a regression set from a specification, optimising memory use or run cost, or grading a batch of runs.
+user-invocable: false
 ---
 
 # Fine-tuning an agent project

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

@@ -1,10 +1,13 @@
 ---
-description: Apply a batch of improvement requests from the tuning loop to the project's prose - merge them into patterns, edit prompts, skills and policy files, tidy up every file touched, and record what was done with each. Run by `zen meta finetune`; the line after the prompt names the apply directory, and a brief follows it.
+name: zen-finetune-apply
+description: Apply a batch of improvement requests from the tuning loop to the project's prose - merge them into patterns, edit prompts, skills and policy files, tidy up every file touched, and record what was done with each. Run only by `zen meta finetune`, never by hand; the words given with it name the apply directory, and a brief follows them.
+user-invocable: false
+disable-model-invocation: true
 ---
 
 The tuning loop has collected improvement requests from several cases and
-wants them applied **together**. The line after this prompt names the apply
-directory.
+wants them applied **together**. The words given with this skill name the
+apply directory.
 
 Every sentence you add is read by every later call of every agent that loads
 it, so prose has a price even when it fixes the case in front of you. The loop
@@ -14,7 +17,7 @@ your edit; one it broke comes back to the next apply as a request.
 
 ## What you are given
 
-A `## The brief` section after that line is what the loop already read and
+A `## The brief` section after them is what the loop already read and
 worked out for you, from the files below. Work from it:
 
 - Do not read a file the brief shows, and do not run a command it shows -