@zenera/cli 1.1.41 → 1.1.43

package/README.md

@@ -115,7 +115,7 @@ in line with it, validate the setup, and run it:
 ```sh
 zen meta run my-project /spec-sync-project
 zen check my-project
-zen run my-project "Summarize this repository and write NOTES.md"
+zen run my-project --here "Summarize this repository and write NOTES.md"
 zen inspect
 ```
 
@@ -127,13 +127,15 @@ than silently guessing. After you answer, apply that feedback with
 ## Run it your way
 
 With no prompt, `zen run` opens the terminal UI. Provide a prompt for a
-one-shot run, or use JSON and batch mode to integrate with other tools:
+one-shot run, or use JSON and batch mode to integrate with other tools. A
+one-shot run works in a fresh directory inside its session; `--here` points it
+at the directory you are in instead:
 
 ```sh
 zen run my-project                         # interactive terminal UI
-zen run my-project "Review the latest changes"
+zen run my-project --here "Review the latest changes"
 git diff | zen run my-project
-zen run my-project "Summarize the changes" --read-only
+zen run my-project --here "Summarize the changes" --read-only
 zen run my-project "Triage these alerts" --json | jq
 zen run batch --input cases.json           # run a set of requests
 ```

package/dist/commands/check.js

@@ -6,7 +6,7 @@ import { duration } from "../narrate.js";
 import { project as resolveProject } from "../resolve.js";
 import { refreshShared } from "../scaffold.js";
 import { bold, count, cyan, dim, green, invalidError, json, progress, red, table, usageError, write, writeAll, yellow, } from "../term.js";
-import { validateProject, } from "../validate.js";
+import { repinDockerfile, validateProject, } from "../validate.js";
 const USAGE = 'zen check [name|dir] [--project <name|dir>] [--fix] [--no-sandbox] [--no-models] [--strict] [--quiet]';
 // ---------------------------------------------------------------------------
 // zen check
@@ -57,8 +57,10 @@ export const check = {
         '(.vscode/ and .github/). They restate how this version of zen behaves,',
         'so a copy left behind by an upgrade is worse than none — they are',
         'replaced whether or not they were edited, and the report that follows is',
-        'of the project as repaired. Nothing else is touched: agents.yaml, the',
-        'prompts, the specification and agents/instructions.md are yours.',
+        'of the project as repaired. It also pins the @zenera/* installs in the',
+        'sandbox Dockerfile to this zen\u2019s version, changing nothing else in it.',
+        'Nothing else is touched: agents.yaml, the prompts, the specification and',
+        'agents/instructions.md are yours.',
         '',
         'The argument is a directory if one is there and a registered project',
         'name otherwise; with neither, the project you are standing in.',
@@ -87,7 +89,7 @@ export const check = {
         // the files that are there now and the exit code answers the repaired
         // project. A fix that left an error behind in the output would be read
         // as a fix that failed.
-        const fixed = values.fix ? refreshShared(dir) : [];
+        const fixed = values.fix ? [...refreshShared(dir), ...repinDockerfile(dir)] : [];
         // Materialised first, so the credential verdicts are the ones a run
         // would reach: a key in the environment and a key in the keyring are
         // the same key by the time the library asks. The project's own `.env`
@@ -329,7 +331,7 @@ function fixedLines(fixed) {
         return [];
     }
     return [
-        `${bold('Replaced')} ${dim(`${count(fixed.length, 'file')} \u2014 ours, not the project's`)}`,
+        `${bold('Fixed')} ${dim(count(fixed.length, 'file'))}`,
         ...fixed.map((f) => `  ${green('wrote')} ${f}`),
         '',
     ];

package/dist/commands/run.js

@@ -33,6 +33,8 @@ export const run = {
         '  --new                  Start a new session without asking which one.',
         '  --input <file>         Read the whole request from JSON. `-` is stdin.',
         '  --workspace <dir>      Directory the agent can read and write.',
+        '                         Default: a fresh one inside the new session.',
+        '  --here                 Same as --workspace with the directory you are in.',
         '  --memory <dir>         Directory the agents remember into.',
         '  --memory-read-only     Recall from it, write nothing back.',
         '  --model <ref>          Use this model instead of the default.',
@@ -59,7 +61,9 @@ export const run = {
         'the answer alone and `2>/dev/null` hides the progress.',
         '',
         'A prompt always starts a new session, so --new is for the TUI, where the',
-        'alternative is being asked which session to continue.',
+        'alternative is being asked which session to continue. Its workspace is a',
+        'fresh, empty directory inside that session; to ask about the files where',
+        'you are, say --here.',
         '',
         '--input names a file holding the whole request - project, input, workspace,',
         'memory - and what it says wins over the same flag on the line. Its paths are',
@@ -98,6 +102,7 @@ export const run = {
         '  zen run                               open the TUI in this project',
         '  zen run acme                          open the TUI in the acme project',
         '  zen run "what changed?"               ask that, print the answer, exit',
+        '  zen run --here "what changed?"        ... about the files in this directory',
         '  git diff | zen run                    take the prompt from stdin',
         '  zen run "what changed?" > out.md      redirect the answer into a file',
         '  zen run --out out.md "what changed?"  write the answer to out.md only',
@@ -118,6 +123,7 @@ export const run = {
             new: { type: 'boolean' },
             input: { type: 'string' },
             workspace: { type: 'string' },
+            here: { type: 'boolean' },
             memory: { type: 'string' },
             'memory-read-only': { type: 'boolean' },
             model: { type: 'string' },
@@ -155,16 +161,20 @@ export const run = {
         if (values.theme !== undefined && !parseChoice(values.theme)) {
             throw usageError(`unknown theme: ${values.theme}`, 'dark, light or auto');
         }
+        if (values.here && values.workspace !== undefined) {
+            throw usageError('--here and --workspace both name the workspace', 'keep one');
+        }
         // With `--input -` the pipe carries the request, not the prompt, so it
         // is read here and never looked at again below.
         const request = values.input ? await readRequest(values.input, ctx.cwd, piped) : undefined;
         const prompt = typed || (request ? '' : (piped ?? ''));
         // A prompt on the command line is a request for an answer, not a
         // conversation to pick up. So it answers the three questions itself:
-        // a fresh session, the directory it was typed in as the workspace,
-        // and no confirmation for it — `zen run acme "what changed?"` should
-        // read the code that is right there. Every flag still wins, and the
-        // TUI, where there is someone to ask, still asks.
+        // a fresh session, a fresh directory inside it as the workspace, and
+        // no confirmation for any of it. Reading the files where it was typed
+        // takes --here: an agent that can write should not land in whatever
+        // directory the shell happened to be in. Every flag still wins, and
+        // the TUI, where there is someone to ask, still asks.
         const input = request ? request.input : prompt;
         const shot = Boolean(prompt) || Boolean(request);
         if (values.events && !shot) {
@@ -175,7 +185,8 @@ export const run = {
             project: request?.project ?? values.project ?? (named ? head : undefined),
             session: values.session,
             fresh: values.new || (shot && !values.session),
-            workspace: request?.workspace ?? values.workspace ?? (shot ? ctx.cwd : undefined),
+            workspace: request?.workspace ?? values.workspace ?? (values.here ? ctx.cwd : undefined),
+            ask: !shot,
             yes: values.yes || shot,
         });
         const engine = await Engine.open({
@@ -234,6 +245,7 @@ const NOT_IN_A_BATCH = [
     ['session', 'every item is a new session of its own'],
     ['new', 'every item is new already'],
     ['workspace', 'they cannot share one; each item gets its own, or names one in the file'],
+    ['here', 'they cannot share one; each item gets its own, or names one in the file'],
     ['plain', 'a batch never draws the TUI'],
     ['theme', 'a batch never draws the TUI'],
     ['events', 'each item already has its own output.json'],

package/dist/resolve.d.ts

@@ -5,6 +5,8 @@ export interface Wanted {
     session?: string;
     fresh?: boolean;
     workspace?: string;
+    /** false to take the session's own workspace without offering a choice */
+    ask?: boolean;
     yes?: boolean;
     cwd: string;
 }

package/dist/resolve.js

@@ -137,7 +137,7 @@ export async function chooseWorkspace(session, want) {
         await approve(at, session, want);
         return at;
     }
-    if (!term.isInteractive()) {
+    if (want.ask === false || !term.isInteractive()) {
         return own;
     }
     const chosen = await term.choose('Workspace — what the agent can read and write', [

package/dist/validate.d.ts

@@ -176,4 +176,15 @@ export interface ValidateOptions {
 }
 export declare function validateProject(opts: ValidateOptions): Promise<Report>;
 export declare function availableTools(root: string, config: ProjectConfig): AnyTool<unknown>[];
+/**
+ * Pins every `@zenera/*` install in the project's Dockerfile to this `zen`,
+ * which is what `zen check --fix` does about `sandbox.pin.stale` and
+ * `sandbox.pin.absent`. Only the version after each name is touched, and only
+ * on lines `checkPin` reads, so whatever else the file holds is left alone.
+ *
+ * Returns the project-relative path when the file was rewritten, and nothing
+ * when there is no Dockerfile, it resolves outside the project, or it already
+ * pins this version — a project that does not load is the report's to explain.
+ */
+export declare function repinDockerfile(root: string): string[];
 //# sourceMappingURL=validate.d.ts.map

package/dist/validate.js

@@ -1,8 +1,8 @@
 import { SHAPES, auditModels, credentialFor, envNames, form, resolveBuild, } from '@zenera/engine';
 import { EXA_GROUP, FileSkillProvider, SANDBOX_MOUNT, Sandbox, exaTools, fileTools, frontmatter, projectRegistry, readProjectConfig, sandboxTools, selectTools, toList, } from '@zenera/neo';
-import { existsSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, } from 'node:fs';
+import { existsSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { probeModels } from "./liveness.js";
 import { BuildError, ensurePodmanReady } from "./podman.js";
 import { ownVersion, staleShared } from "./scaffold.js";
@@ -1315,7 +1315,7 @@ function checkPin(path, rel, add) {
             }
         }
     }
-    const fix = `pin them to ${mine}, the version \`zen --version\` reports`;
+    const fix = `pin them to ${mine}, the version \`zen --version\` reports — \`zen check --fix\` does it`;
     if (stale.size > 0) {
         add({
             severity: 'warning',
@@ -1337,6 +1337,49 @@ function checkPin(path, rel, add) {
         });
     }
 }
+/**
+ * Pins every `@zenera/*` install in the project's Dockerfile to this `zen`,
+ * which is what `zen check --fix` does about `sandbox.pin.stale` and
+ * `sandbox.pin.absent`. Only the version after each name is touched, and only
+ * on lines `checkPin` reads, so whatever else the file holds is left alone.
+ *
+ * Returns the project-relative path when the file was rewritten, and nothing
+ * when there is no Dockerfile, it resolves outside the project, or it already
+ * pins this version — a project that does not load is the report's to explain.
+ */
+export function repinDockerfile(root) {
+    let rel;
+    try {
+        const ref = readProjectConfig(root).config.sandbox?.build?.dockerfile;
+        rel = ref === undefined ? undefined : normalise(root, ref);
+    }
+    catch {
+        return [];
+    }
+    if (rel === undefined) {
+        return [];
+    }
+    const path = join(root, rel);
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const mine = ownVersion();
+    const next = text
+        .split('\n')
+        .map((line) => /^\s*#/.test(line)
+        ? line
+        : line.replace(ZENERA_INSTALL, (_, name) => `@zenera/${name}@${mine}`))
+        .join('\n');
+    if (next === text) {
+        return [];
+    }
+    writeFileSync(path, next);
+    return [rel.split(sep).join('/')];
+}
 /** Written by the smoke test and read back, to prove the mount is real. */
 const SMOKE = 'zen-check';
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.41",
+    "version": "1.1.43",
     "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.41",
-        "@zenera/neo": "^1.1.41",
-        "@zenera/view": "^1.1.41",
+        "@zenera/engine": "^1.1.43",
+        "@zenera/neo": "^1.1.43",
+        "@zenera/view": "^1.1.43",
         "google-auth-library": "^10.0.0",
         "ink": "^7.1.1",
         "openai": "^6.0.0",

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

@@ -55,7 +55,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. This applies whatever prompted the
-change - a task scoped to `SPECIFICATION.md` does not narrow it.
+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.
 
 **Load `zen-instructions` before writing, editing, reviewing or deleting any
 `agents/*instructions.md`.** They are the house rules, prepended to every
@@ -1990,8 +1993,9 @@ candidates; these are the judgements to make about each one)**
       and says so honestly - an unchanged specification line is not evidence
       that anything implements it
 - [ ] No question in `SPECIFICATION-FEEDBACK.md` has a box marked `[x]`, or
-      exactly one answer left under it, without a matching `✅ Answered` entry -
-      that is an answer given and never folded into the specification
+      exactly one answer left under it, without a matching `✅ Answered` entry
+      or a strike naming the specification line that superseded it - that is
+      an answer given and never folded into the specification
 - [ ] `.spec-sync/` is committed and `.tmp/` is not
 
 ---

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

@@ -32,7 +32,14 @@ accounted for against the specification.
 
 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.
+pass, however small the diff. The one exception is the skill's **spec-only
+pass**, and only under the conditions the skill sets.
+
+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`.
 
 ## 1. Read before changing anything
 
@@ -120,8 +127,10 @@ 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.
+  `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.
 
 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.
@@ -379,11 +388,17 @@ 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.
 
 ## 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.
+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`
+reporting every step `skipped` is enough, and anything else sends you back to
+the full run 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

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

@@ -70,7 +70,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

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/run.md

@@ -16,6 +16,7 @@ answers once on stdout and exits.
 | `--new`                 | Start a new session rather than continuing one           |
 | `--input <file>`        | Read the whole request from JSON; `-` is stdin           |
 | `--workspace <dir>`     | What the agent may read and write                        |
+| `--here`                | `--workspace` with the directory you are in              |
 | `--memory <dir>`        | Where the agents remember into, instead of the project's |
 | `--memory-read-only`    | Recall from it; write nothing back                       |
 | `--model <ref>`         | Override the default model for this run                  |
@@ -270,7 +271,7 @@ question of what the agents know without changing what they know.
 
 ### What means nothing in a batch
 
-`--session`, `--new`, `--workspace`, `--plain` and `--theme` are refused by
+`--session`, `--new`, `--workspace`, `--here`, `--plain` and `--theme` are refused by
 name rather than ignored. Every item is a new session of its own, they cannot
 share a workspace, and a batch never draws the TUI.
 
@@ -297,11 +298,18 @@ git diff | zen run "summarise this diff"
 ## What a prompt on the command line implies
 
 A prompt is a request for an answer, not a conversation to pick up, so it
-answers the three questions itself: **a fresh session**, **the directory you are
-in** as the workspace, and **no confirmation**. Every flag still wins -
-`--session`, `--workspace` and `--read-only` override it - and the TUI, where
+answers the three questions itself: **a fresh session**, **a fresh, empty
+directory inside it** (`<session>/workspace/`) as the workspace, and **no
+confirmation**. To have it read and write the directory you are in, say
+`--here` (the same as `--workspace .`). Every flag still wins - `--session`,
+`--workspace`, `--here` and `--read-only` override it - and the TUI, where
 there is someone to ask, still asks.
 
+```
+zen run "draft a release note"            works in sessions/<id>/workspace/
+zen run --here "what changed?"            reads and writes the directory you are in
+```
+
 There is no `resume`. A session continues itself, because its state is what it
 is; `--session <id>` picks which one.
 

package/templates/editor/.github/skills/zen-review/scripts/check-paths.sh

@@ -36,8 +36,12 @@ NOISE='^(and/or|he/she|his/her|input/output|read/write|w/o|n/a|N/A|24/7|km/h)$|^
 # A url, stripped before tokenising rather than filtered after it — the token
 # regex reads `https://acme.dev/docs` as `//acme.dev` *and* `/docs`, and the
 # second half is indistinguishable from a real absolute path once it is alone.
+#
+# A meta agent command, `zen meta run /spec-edit`, goes the same way: its
+# `/<name>` is a stored prompt, not a file the running agent is told to open.
 strip_urls() {
-    sed -E 's#[a-zA-Z][a-zA-Z0-9+.-]*://[^][ )"'"'"'`>]*##g' "$1"
+    sed -E -e 's#[a-zA-Z][a-zA-Z0-9+.-]*://[^][ )"'"'"'`>]*##g' \
+        -e 's#(zen meta run( [A-Za-z0-9_.-]+)?) /[A-Za-z0-9_-]+#\1#g' "$1"
 }
 
 # The three trees §2.5 names, prose only: a skill's own script is code the

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

@@ -1,6 +1,6 @@
 ---
 name: zen-spec-sync
-description: Running `/spec-sync-project` as an incremental pass - the committed `.spec-sync` baseline of what the last pass applied, how to scope a pass from the specification and feedback diffs and from what moved in the project itself, the five checks a narrow pass may never skip, which skills a pass must load before editing (`zen-instructions` for any house rule it touches), the iteration history format, and why the baseline is written last. Load before every `/spec-sync-project`, including the first one on a project that has no baseline yet.
+description: Running `/spec-sync-project` as an incremental pass - the committed `.spec-sync` baseline of what the last pass applied, how to scope a pass from the specification and feedback diffs and from what moved in the project itself, which input wins when they disagree, the five checks a narrow pass may never skip, which skills a pass must load before editing (`zen-instructions` for any house rule it touches), the iteration history format, and why the baseline is written last. Load before every `/spec-sync-project`, including the first one on a project that has no baseline yet.
 ---
 
 # Syncing a project with its specification, one change at a time
@@ -103,9 +103,64 @@ editing anything, and report it in the chat as the pass's scope.
    covers it, and you say which line, or it does not, and it is an **extra**
    reported under `➕`.
 
+## When the inputs disagree
+
+Two inputs can ask for different things - a ticked answer and a later edit to
+the same specification line, say. Decide by this order, highest first, and do
+not weigh them again:
+
+1. **The user's message that started this pass**, where it says more than the
+   command name. It is the newest and most direct statement of intent there is.
+2. **`SPECIFICATION.md` as it stands now.** An edit to the specification is
+   made on purpose and after the questions were written, so it outranks them.
+3. **An answer ticked in `SPECIFICATION-FEEDBACK.md`** and not yet folded in.
+4. **What the last pass left open.**
+
+A ticked answer that the current specification text contradicts was
+**superseded**, not ignored: do not fold its text back in over the newer line.
+Strike the question with one line naming the specification line that replaced
+it, and say in the chat that you did.
+
+Facts outrank all four. `zen --version` decides the sandbox pin (below); a
+specification line asking for something impossible is a question, not an order.
+Where the order above does not decide, build what the higher-ranked input asks
+for, write **one** question in `SPECIFICATION-FEEDBACK.md`, and carry on.
+
+### Do not reconstruct intent
+
+The diffs say what changed. The order above says what wins. A feedback question
+covers whatever is left. Do not use anything else to work out _why_ somebody
+changed something: no session history or chat transcripts, no file timestamps,
+no `git log` or `git blame`, no older history entries beyond the one `applied:`
+names. If a pass catches itself guessing at what the human meant, that guess is
+the text of a question, and the pass moves on.
+
+### The `zen` version in the specification
+
+The `@zenera/cli` and `@zenera/rag` pin in `sandbox/Dockerfile` always follows
+`zen --version` - `zen check` warns on any other number, older or newer. Nothing
+outranks that, not a specification line and not the user's message: the image
+cannot hold a `zen` other than the one building it. If a version was asked for
+that is not the one in hand, say so in the chat - `zen` has to be upgraded on the
+host first.
+
+When `SPECIFICATION.md` names an exact version other than `zen --version`, pin
+the Dockerfile to `zen --version` and keep **one** `✏️` question open for that
+line. If one is already open, update it instead of adding another. Offer these
+answers:
+
+- State the pin without a number - "pinned to the `zen` version that builds the
+  image" - so the next upgrade does not raise the question again
+  _(recommended)_.
+- Replace the number with the one `zen --version` reports.
+- Keep the number, upgrade `zen` on the host to it, and run the pass again.
+
+That is the whole of the work. A version mismatch is not a reason to look for
+anything else.
+
 ## The five checks a narrow pass may never skip
 
-However small the diff:
+However small the diff - with the one narrowing for a spec-only pass below:
 
 1. **`zen check` passes.** Run it before the first edit and again after the
    last.
@@ -131,6 +186,28 @@ However small the diff:
    it, the history entry claims it, and the baseline records it as applied.
    Specification-driven rules go in a topic file of the project's own beside it.
 
+### The spec-only pass
+
+A pass qualifies when **all** of the following hold:
+
+- the implementation diff (input 4) is empty
+- the pass edits nothing except `SPECIFICATION.md`, `SPECIFICATION-FEEDBACK.md`
+  and the `@zenera/*` pin in `sandbox/Dockerfile`
+- no changed specification hunk names an agent, tool, model, embedding, skill,
+  house rule, handoff, memory, index, asset or setup step
+
+A pass like that changes nothing an agent reads, so it has no capability
+obligation to re-check. Checks 4 and 5 drop out: load no capability skill and no
+`zen-instructions`. `zen check` still runs before and after, and it still
+reports `rules.stale`. Check 2 shrinks to `scripts/_setup.sh --check`, which
+must report every step `skipped`. If it reports anything else, run
+`scripts/_setup.sh` in full as written. Check 3 shrinks to the §9
+**Specification** group and the groups covering any file the pass edited.
+
+Decide this before loading anything, and say it in the chat - "spec-only pass:"
+followed by the reason. If any edit turns out to reach further, the pass is no
+longer spec-only: run all five checks.
+
 A narrow diff narrows reading and editing. It does not narrow verification.
 
 ## What else an incremental pass still owes

package/templates/project/agents/memory-instructions.md

@@ -26,6 +26,20 @@ Search before starting work that costs more than one cheap read or call:
 Do not repeat the same search in different words. Search again only when the
 question has changed.
 
+When a request involves several distinct subjects, search for all of them in
+parallel: send one `memory_search` per subject in the same turn rather than one
+after another. Likewise, load every node you need in the same turn. Parallel
+searches must ask different questions, not rephrase one.
+
+### Call memory tools silently
+
+You MUST NOT write any text before a `memory_*` call. Do not announce, explain,
+or summarize memory calls, such as "I'm going to check for prior work". The
+tool call is shown to the user on its own. This overrides the general rule to
+say what you are about to do before tool calls: when a turn contains only
+`memory_*` calls, write nothing; when it mixes them with other tools, describe
+only the other calls.
+
 ### Choose the retrieval tool
 
 | Need                                           | Tool            |

package/templates/project/agents/prompts/default.md.tmpl

@@ -17,3 +17,63 @@ Anything under `/assets` is reference material: read it, search it, and do not
 try to change it.
 
 Say what you changed.
+
+<!-- ===== BEGIN: unconfigured-agent disclaimer (delete this block once the agent is configured) ===== -->
+
+## This agent is not configured yet
+
+This agent has not been set up for any specific task yet. It only has the
+generic defaults above, so it is not expected to do anything particularly
+useful on its own.
+
+When the user greets you ("hi", "hello"), asks what you can do, asks who you
+are, or asks how to get started, tell them plainly:
+
+- This agent is not configured yet to do anything useful.
+- To teach it specific tasks, they should use the **Zenera Meta Agent**,
+  which can configure this agent's prompts, tools, knowledge and workflows.
+  It ships with the `zen` CLI:
+  - What it is and how it works:
+    https://github.com/zenera-ai/ZeneraNeo#what-is-the-meta-agent
+  - The CLI and its commands:
+    https://github.com/zenera-ai/ZeneraNeo/tree/main/packages/cli
+  - The project home: https://zenera.ai
+
+Then give them these steps to get started. The commands run in a terminal on
+their machine, from the project directory, not here:
+
+1. Pick the model the meta agent uses (once per machine):
+   `zen meta model --pick`
+2. Describe what this agent should do in `SPECIFICATION.md`: its purpose,
+   models, agents, tools, knowledge and memory. Edit the file by hand, or have
+   the meta agent write it from a plain request:
+   `zen meta run /spec-edit "<what to add, change or remove>"`
+3. Have the meta agent build the system from the specification:
+   `zen meta run /spec-sync-project`
+4. If the meta agent has questions, it writes them to
+   `SPECIFICATION-FEEDBACK.md`. Answer them there, then apply the answers:
+   `zen meta run /spec-apply-feedback`
+5. Validate the project and try it: `zen check`, then `zen run "<request>"`.
+   Review a run with `zen inspect`.
+
+To find out more, `--help` works on every command and subcommand:
+
+- `zen meta --help` lists everything the meta agent can do: `run`,
+  `prompts`, `resume`, `model`, `dataset` and `finetune`, with examples.
+- `zen meta run --help` lists the options for a run and the stored prompts,
+  the `/<name>` commands used above.
+  `zen meta prompts` lists the stored prompts on their own.
+- `zen meta dataset --help` and `zen meta finetune --help` cover building an
+  evaluation dataset and tuning the project against it.
+- `zen meta run "<question>"` asks the meta agent anything about the project,
+  for example `zen meta run "what does this project do?"`.
+
+For teams that need more, mention **ZeneraLab**, Zenera's enterprise-grade
+platform (https://zenera.ai). It has all of this built into a UI, where users
+can build enterprise-grade agentic solutions, integrate them with any legacy
+system, and train, fine-tune, optimize, test and monitor their agents.
+
+Keep that answer short and friendly. You can still help with simple requests
+in the workspace if asked directly.
+
+<!-- ===== END: unconfigured-agent disclaimer ===== -->