@zenera/cli 1.1.17 → 1.1.19

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

@@ -59,8 +59,9 @@ schema index it is expected to consult all count. When it does, also load the
 
 Then create or maintain `agents/skills/rag_search/SKILL.md` in the target
 project. Its description must say when an agent should load it. Its body must
-name the target's actual RAG surface and index location, state which agents may
-use it, and give an executable retrieval procedure:
+name the target's actual RAG surface and index location, open by stating what an
+agent needs to follow it and what to do without that, and give an executable
+retrieval procedure:
 
 1. Discover document and section names with the exact listing command or tool.
 2. Start with hybrid search for a complete natural-language question.
@@ -72,6 +73,16 @@ use it, and give an executable retrieval procedure:
 5. Retrieve a complete section verbatim, or list a table and read its inclusive
    line range when every row is needed.
 
+**State the prerequisite, not the audience.** `skills.allow` restricts loading
+and `zen check` validates it; a list of agent names in the body is a second copy
+of that binding with nothing keeping the two in step, and it is stale the first
+time an agent is renamed (§4.2, rule 10). What a reader can act on is what the
+procedure needs - the RAG tools, or `sandbox:*` and the index at its path - and
+what to do without them: _"say so and stop; do not answer from memory"_ (§4.2,
+rule 6). Put it in the first lines of the body, because the catalog is mounted
+whole at `/skills` before any binding applies (§3.4.1), so an agent that was
+never granted this skill can still read the file and start following it.
+
 Keep this as runtime guidance, not a pointer to this editor reference: a target
 agent cannot read `.github/` or this project layout while it runs. Include only
 the commands, tools, paths, and corpus-specific constraints that exist in the
@@ -106,7 +117,7 @@ without losing anything. Never paraphrase the reference into prose of your own.
 See §5.3.
 
 A project with a `SPECIFICATION.md` carries one more: **`.spec-sync/` records
-what the last `/sync-with-spec` pass applied**, and the `zen-spec-sync` skill is
+what the last `/spec-sync-project` pass applied**, and the `zen-spec-sync` skill is
 loaded before running that prompt, whether or not a baseline exists yet. The
 state is committed, because a record only the last machine has is not a record.
 Two things to watch for, neither of which `zen check` reports: a baseline that
@@ -207,11 +218,12 @@ my-project/
 │   ├── prompts/*.prompt.md       tasks you invoke by name
 │   └── skills/*/SKILL.md         reference the editor loads on demand
 ├── .env                          this project's environment - NEVER committed
-├── .spec-sync/                   what the last /sync-with-spec applied - §0.1
+├── .spec-sync/                   what the last /spec-sync-project applied - §0.1
 ├── agents.yaml                   who exists, what they may reach for
 ├── agents/
 │   ├── instructions.md            house rules, prepended to every agent
 │   ├── memory-instructions.md     more of them - any `<topic>-instructions.md`
+│   ├── tools-instructions.md      and more - how tools are called
 │   ├── prompts/
 │   │   ├── intake.md             one agent's own brief
 │   │   └── adjuster.md
@@ -236,8 +248,7 @@ The config is found by name, in order: `agents.yaml`, `agents.yml`,
 
 The house rules are `agents/instructions.md` plus every
 `agents/<topic>-instructions.md`, read in filename order and prepended to every
-agent (§3.2). A project written before the move keeps its `INSTRUCTIONS.md` in
-the root; that still loads, and `zen check` says to move it.
+agent (§3.2).
 
 ### 2.2 Variants
 
@@ -767,10 +778,18 @@ groups - the workspace tools (§3.6), the sandbox tools (§3.7) and the web tool
 the machine, so `tools:` is the whole permission model: an agent that does not
 name a tool cannot use it, whatever its prompt says.
 
-Two rules follow:
+Three rules follow:
 
 - **Grant the narrowest set the job needs.** An agent that only reviews should
   not be holding the tools that overwrite files.
+- **Grant by group, then subtract.** Write `workspace:*` and take away what this
+  agent must not have - not a hand-picked list of names. The tools in a group are
+  designed to be used together, and a list assembled one name at a time leaves out
+  the companion the model reaches for next: `write_file` without `apply_patch`
+  turns every one-line edit into a whole-file rewrite, and `read_file` without
+  `list_dir` and `find_files` leaves it guessing at paths. A group also tracks the
+  runtime - a tool added to it later reaches the agent, where an enumerated list
+  silently stays behind.
 - **Say in the prompt when to reach for what.** A granted tool the prompt never
   mentions is used at the model's discretion, which is not the same as never.
 
@@ -830,6 +849,13 @@ refuses the file. `workspace:*` needs no quoting. There is no name globbing -
 `read_*` is an unknown tool, because a selector should track a declared set, not
 a naming habit.
 
+Both agents above are written the way to write them: **the group, minus the
+exceptions**. `tools: [read_file, write_file]` is the shape to avoid - it reads
+as a considered decision and is usually an incomplete one, since the tool that
+makes the granted one usable is the tool that was left out. Subtracting says
+which capability is being withheld, which is the thing a reviewer needs to check
+and the thing the next tool added to the group will not quietly defeat.
+
 `zen run --read-only` withholds the four mutating tools whatever `agents.yaml`
 asks for: the deployment overriding the repository, as everywhere else.
 
@@ -1075,6 +1101,7 @@ zen run                         open the entry agent on this project
 zen run "what changed?"         one shot; stdout is the answer
 zen run --session <id>          continue a session
 zen run --workspace ./repo      what the agent may read and write
+zen run --memory ./mem          where the agents remember into, instead of memory/
 zen run --model careful         override the default model for this run
 zen run --image <ref>           override the sandbox image for this run, ignoring build:
 zen run --read-only             withhold every tool that can write
@@ -1095,11 +1122,17 @@ OPENAI_API_KEY=...
 ANTHROPIC_API_KEY=...
 GOOGLE_APPLICATION_CREDENTIALS=./.keys/vertex.json
 EXA_API_KEY=...
+ZENERA_META_MODEL=vertex/gemini-3.8-flash
 ```
 
 Never commit. Never inline a key into `agents.yaml` - use `${VAR}`. Never print a
 key in a log line, a test fixture, or a chat message.
 
+`ZENERA_META_MODEL` is the exception that is not a credential: it names the model
+`zen meta` runs the meta agent on in this project, as a zen ref. It is here
+rather than in `agents.yaml` because it is a choice about a tool, not about the
+project's own agents. `zen meta model` prints where the answer came from.
+
 ### 3.11 `assets/`
 
 `assets/` next to `agents.yaml` - or `assets: <path>` - is reference material
@@ -1915,10 +1948,17 @@ candidates; these are the judgements to make about each one)**
 - [ ] Catalog >~30 entries → `discovery: search`
 - [ ] A skill that ships a script writes its `/skills/<name>/...` path, the agent
       holds `sandbox:*`, and the sandbox image already has the interpreter
+- [ ] A skill whose procedure needs particular tools, an index or a mounted file
+      opens by naming them and says what to do without them - rather than naming
+      the agents allowed to load it, which `agents.yaml` already decides - §0.1
 
 **Tools**
 
 - [ ] Every agent holds the narrowest set its job needs
+- [ ] Every `tools:` list is a group selector minus its exceptions, not an
+      enumeration of individual names - §3.5
+- [ ] No agent holds `write_file` without `apply_patch`, or `read_file` without
+      `list_dir` and `find_files`
 - [ ] An agent that only reads is not holding `write_file`, `apply_patch`,
       `move_file` or `delete_file` - subtract them from `workspace:*`
 - [ ] `sandbox:*` is granted only where a shell is actually needed
@@ -2062,3 +2102,17 @@ Update it when:
 
 Do not let it grow without pruning. When a section is only true of one agent, it
 belongs in that agent's prompt, not here.
+---
+
+## 13. Function calling rules
+
+Before every tool call, write **one line** saying what you are about to do and
+why. One line per call, in front of it - not a plan for the whole turn, and not
+a summary afterwards.
+
+- Say the intent and the reason, not the tool's name or its arguments:
+  _"Reading `agents.yaml` to see which agents hold `sandbox:*`."_
+- When several calls go out together, write one line covering the batch.
+- Keep it to a sentence. If it needs two, the call needs splitting, not the
+  sentence.
+- Do not narrate the result in the same line - the tool answers that.

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

@@ -1,5 +1,4 @@
 ---
-mode: agent
 description: Review the project against the checklist before committing.
 ---
 

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

@@ -12,7 +12,7 @@ answered.
 You change two files and no others: `SPECIFICATION.md` and
 `SPECIFICATION-FEEDBACK.md`. You implement nothing - not a prompt, not a skill,
 not `agents.yaml`. Making the project match the specification is
-`/sync-with-spec`, which runs after this.
+`/spec-sync-project`, which runs after this.
 
 ## 1. Read both files before editing either
 
@@ -83,7 +83,7 @@ put it where the line above the block says it goes.
   edits rather than trusting the line numbers you read at the start.
 
 Nothing outside `SPECIFICATION.md` changes here. If an answer's text implies an
-agent, a tool grant, a script or a skill, that is the next `/sync-with-spec`
+agent, a tool grant, a script or a skill, that is the next `/spec-sync-project`
 pass's work, and saying so is all you do about it.
 
 ## 4. Mark the question answered
@@ -108,7 +108,7 @@ order:
   the specification to be true again, or `Nothing - the project already does
 this.`
 
-That last line is what the next `/sync-with-spec` works from, so write it as
+That last line is what the next `/spec-sync-project` works from, so write it as
 work, not as a summary.
 
 Then bring the top of the file back into step: the opening paragraph's count of
@@ -124,7 +124,7 @@ answer you think is wrong is still the answer; say why in the chat and leave the
 text alone.
 
 Do not run `zen check`, `scripts/_setup.sh` or anything under `.spec-sync/`. The
-baseline moves at the end of a `/sync-with-spec` pass and nowhere else -
+baseline moves at the end of a `/spec-sync-project` pass and nowhere else -
 committing it here would record a specification as applied that nothing has
 implemented yet.
 
@@ -138,5 +138,5 @@ In the chat:
 - what is still open, split into: more than one answer left, more than one box
   marked, every answer rejected, and could not be applied because the place it
   names is gone
-- then, in one line: send `/sync-with-spec` to make the project match the
+- then, in one line: send `/spec-sync-project` to make the project match the
   specification you have just changed.

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

@@ -172,7 +172,7 @@ nothing to raise, say so in the chat and do not create the file.
 **It is a questionnaire, and answering it must take one gesture.** Every
 question carries two to four written-out answers, each with a `[ ]` box in its
 heading. The reader marks the box of the one they want - `[x]` - and deletes the
-others, then sends `/update-spec-from-feedback`, which folds what survived into
+others, then sends `/spec-apply-feedback`, which folds what survived into
 `SPECIFICATION.md`. Either gesture alone is enough, and the file says so in
 every question.
 
@@ -190,7 +190,7 @@ Two rules that come before everything else in this section:
 The file opens with one short paragraph: how many questions are open, and how to
 answer them - put an `x` in the box of the answer you want, delete the answers
 you do not want, or replace them all with a sentence of your own, then send
-`/update-spec-from-feedback`. Then a contents list, one line per question: its
+`/spec-apply-feedback`. Then a contents list, one line per question: its
 number as an anchor link, the question in under ten words, and what is built in
 the meantime. Then the questions, grouped under these headings, omitting any
 heading with no questions. The file is scanned before it is read, so keep the
@@ -212,7 +212,7 @@ emoji on every heading:
 ## ✅ Answered - folded into the specification
 ```
 
-`✅` is written by `/update-spec-from-feedback`, not by you. Leave what is there
+`✅` is written by `/spec-apply-feedback`, not by you. Leave what is there
 alone except to strike an entry this pass has actually implemented, and say in
 the chat which ones you closed.
 
@@ -329,7 +329,7 @@ retires with it.
 Read the feedback diff from §0 before writing: a question the human answered
 since the last pass is work to close, not a question to ask again. If a question
 has a box marked `[x]`, or one answer left under it, and no `✅` entry, the
-reader answered it and never ran `/update-spec-from-feedback` - implement that
+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.
 
 ## 6. Run `scripts/_setup.sh` and watch it finish

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

@@ -33,8 +33,6 @@ checked too. A word that is neither is a usage error (exit 2), not a report.
   rather than ignored.
 - Every file the configuration names is on disk and non-empty: the house rules
   under `agents/`, each agent's prompt, each skill's `SKILL.md`, each asset glob.
-  A root `INSTRUCTIONS.md` is still read, and reported as something to move to
-  `agents/instructions.md`.
 - Hand-offs and forks name agents that exist, and no agent hands off to itself.
 - Tool selectors resolve against the real tool set, including a skill's own
   `tools:` frontmatter.

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

@@ -7,12 +7,13 @@ zen inspect [run] [--session <id>] [--open] [--rebuild] [--serve [port]]
 Alias: `report`.
 
 Renders the trajectory of a run: every message, tool call, skill activation and
-hand-off, in order, with what each one cost. With no arguments it takes the
-newest run of the newest session.
+hand-off, in order, with what each one cost. With no arguments it asks which
+session and which run; where there is nothing to ask on — a script, `--json`,
+an agent — it takes the newest run of the newest session that has one.
 
 | Flag             | Meaning                                                 |
 | ---------------- | ------------------------------------------------------- |
-| `[run]`          | A run id. The newest otherwise                          |
+| `[run]`          | A run id, in whichever session holds it                 |
 | `--session <id>` | Which session the run belongs to                        |
 | `--open`         | Open the report in a browser                            |
 | `--rebuild`      | Rebuild `report.html` from the recorded state           |

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

@@ -29,6 +29,7 @@ skill.
 | Flag                    | Meaning                                      |
 | ----------------------- | -------------------------------------------- |
 | `--project <name\|dir>` | Which project. Inferred from the directory   |
+| `--dir <dir>`           | Read this memory directory instead           |
 | `--kind <name>`         | Only this kind of node                       |
 | `--audience <name>`     | Only nodes committed under this label        |
 | `--files`               | Only nodes that remember a file              |
@@ -38,6 +39,19 @@ skill.
 | `--open`                | Open the exported page                       |
 | `--yes`                 | Do not ask before removing                   |
 
+## A graph that is not the project's
+
+`--dir` opens a memory directory as it stands, and skips project resolution
+entirely: there need be no `agents.yaml` anywhere above it. That is what to use
+for a graph a run was pointed at with `zen run --memory <dir>`, and for a copy
+taken out of a running session - copy the directory, delete its `.lock`, and
+read the copy while the run continues.
+
+```
+zen run --memory .tmp/mem "…"     remember into .tmp/mem for this run
+zen memory --dir .tmp/mem stats   then read that graph, from anywhere
+```
+
 ## It reads unmasked, on purpose
 
 Memory is masked per agent: a node's `audience` decides who can see it. Recall

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

@@ -22,6 +22,7 @@ zenera.json                     { version, name }
 agents.yaml                     the configuration
 agents/instructions.md          house rules, prepended to every agent
 agents/memory-instructions.md   more of them, about the memory store
+agents/tools-instructions.md    more of them, about how tools are called
 agents/prompts/default.md       the default agent's prompt
 agents/skills/                  empty, for skills
 assets/README.md

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

@@ -9,24 +9,78 @@ answers once on stdout and exits.
 
 ## Options
 
-| Flag                    | What it does                                           |
-| ----------------------- | ------------------------------------------------------ |
-| `--project <name\|dir>` | Which project. Inferred from the directory otherwise   |
-| `--session <id>`        | Continue a particular session                          |
-| `--new`                 | Start a fresh one                                      |
-| `--workspace <dir>`     | What the agent may read and write                      |
-| `--model <ref>`         | Override the default model for this run                |
-| `--image <ref>`         | Override the container image commands run in           |
-| `--read-only`           | Withhold every tool that can write                     |
-| `--quiet`               | The answer only; no narration                          |
-| `--plain`               | One shot, even on a terminal                           |
-| `--theme <dark\|light>` | Force the palette. Detected otherwise; `$ZENERA_THEME` |
-| `--out <file>`          | Write the answer to a file as well as to stdout        |
-| `--yes`                 | Accept the questions it would otherwise ask            |
+| Flag                    | What it does                                             |
+| ----------------------- | -------------------------------------------------------- |
+| `--project <name\|dir>` | Which project. Inferred from the directory otherwise     |
+| `--session <id>`        | Continue a particular session                            |
+| `--new`                 | Start a new session rather than continuing one           |
+| `--workspace <dir>`     | What the agent may read and write                        |
+| `--memory <dir>`        | Where the agents remember into, instead of the project's |
+| `--model <ref>`         | Override the default model for this run                  |
+| `--image <ref>`         | Override the container image commands run in             |
+| `--read-only`           | Withhold every tool that can write                       |
+| `--plain`               | Never open the TUI; a prompt is then required            |
+| `--theme <dark\|light>` | Palette for the TUI; `auto` detects. `$ZENERA_THEME`     |
+| `--out <file>`          | Put the answer in this file instead of on stdout         |
+| `--yes`                 | Say yes to the workspace and install questions           |
 
 Flags always beat the file: the repository states intent, the invocation
 overrides it.
 
+## Where the answer goes
+
+The answer goes to stdout and the progress to stderr, so `zen run "…" >
+answer.md` leaves a file with the answer in it and nothing else, watched or not.
+`--out` is a destination rather than a copy: it takes the answer off stdout, so
+the file is the only place it lands.
+
+```
+zen run "what changed?" > out.md              answer in the file, progress on screen
+zen run "what changed?" > out.md 2>/dev/null  ... and nothing on screen at all
+zen run --out out.md "what changed?"          the same file, stdout left empty
+```
+
+There is no `--quiet`. Narration is on stderr already, so a redirect is enough;
+`--json` silences it for machine use.
+
+`--json` answers with the paths as well as the answer: the session and run
+directories, every file the run left behind, and every tree the agent could see,
+with the path it had on this machine beside the path it had inside the
+container.
+
+```json
+{
+    "session": { "id": "...", "dir": "<project>/sessions/<id>" },
+    "run": {
+        "id": "...",
+        "dir": "<project>/sessions/<id>/runs/<run-id>",
+        "input": ".../input.md",
+        "output": ".../output.md",
+        "state": ".../state.json",
+        "meta": ".../meta.json",
+        "report": ".../report.html"
+    },
+    "mounts": [
+        { "host": "...", "at": "/workspace", "readOnly": false },
+        { "host": "...", "at": "/assets", "readOnly": true },
+        { "host": "...", "at": "/skills/<name>", "readOnly": true }
+    ],
+    "agent": "...",
+    "stopReason": "final",
+    "durationMs": 0,
+    "usage": {},
+    "output": "the answer"
+}
+```
+
+`mounts` also lists the container's `$HOME` and, when keys are forwarded, the
+credential files mounted under `/run/zenera/keys`.
+
+`--plain` never opens the TUI. The TUI is the only thing that can ask for a
+prompt, so with `--plain` the prompt has to be there already - in the argument
+or on stdin - and `zen run --plain` with neither is an error instead of a
+window. Say it in a script that must not meet one.
+
 ## Which word is the project
 
 The first positional is read as a project when it names one, and as the first
@@ -42,7 +96,7 @@ zen run --project why "why?"     when the project is called "why"
 The prompt comes from the argument, or from stdin, or from the TUI:
 
 ```
-git diff | zen run --quiet "summarise this diff"
+git diff | zen run "summarise this diff"
 ```
 
 ## What a prompt on the command line implies
@@ -56,10 +110,15 @@ there is someone to ask, still asks.
 There is no `resume`. A session continues itself, because its state is what it
 is; `--session <id>` picks which one.
 
+`--new` only matters when there is no prompt. A prompt on the command line
+already starts a new session, so `zen run --new "what changed?"` is the same as
+`zen run "what changed?"`. Without a prompt the TUI asks which session to
+continue, and `--new` is how you skip that question. It contradicts `--session`.
+
 ## The TUI
 
 Drawn only when there is a terminal on both stdin and stdout, no prompt,
-no `--plain`, no `--quiet` and no `--json`. It streams the answer, shows
+no `--plain` and no `--json`. It streams the answer, shows
 reasoning as it arrives, and reports per-turn and per-session token usage in the
 footer.
 

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

@@ -197,8 +197,9 @@ below.
 └── .lock           held while a run is writing; a dead pid's lock is stale
 ```
 
-It is project state, not source, and it is not committed. The directory is
-mounted **read-only** at `/memory` in the agent's namespace.
+It is committed with the project - everything but `.lock`, which is runtime
+state. The directory is mounted **read-only** at `/memory` in the agent's
+namespace.
 
 ## Designing a memory strategy
 
@@ -363,6 +364,40 @@ lands at `<project>/memory/files/<id>.<ext>` and appears to the agent as:
 | Mount     | `/memory`, **read-only**                                         |
 | Extension | preserved, because it decides how the file runs and renders      |
 
+### The agent has to be able to write the file first
+
+`memory_commit` **copies** a file that already exists. It is not an upload
+channel and it cannot create one. So everything too big for a node's `text` - a
+script, a config, an assembled passage - depends on the agent having a tool that
+puts bytes in the **workspace**, and an agent with none can only ever commit
+text no matter how much the memory design leans on `file` nodes.
+
+| The agent's `tools:`         | Can it commit a `file`?                                                 |
+| ---------------------------- | ----------------------------------------------------------------------- |
+| `write_file` / `apply_patch` | Yes. Write it, then name the same path                                  |
+| `run_command` only           | Yes, but only under `/workspace` - a heredoc into `/tmp` is unreachable |
+| Neither                      | No. Everything worth keeping has to fit on one line of `text`           |
+
+The workspace is the only tree that round-trips, because it is the only
+writable one. `/assets`, `/skills` and `/memory` resolve as well - they are
+mounts the file tools know by name - but they are **read-only**, so nothing can
+be put there to be remembered. Every other absolute path is real to
+`run_command` and outside the workspace root, so a file written to `/tmp` comes
+back as:
+
+```
+error: outside the workspace: /tmp/report.py
+```
+
+A bare error carrying none of the `hint` the other memory refusals do, because
+containment is a workspace answer rather than a memory one.
+
+This is the trap in a `tools:` list trimmed to `run_command` alone: the shell
+can create the file, so `file` nodes look supported, but nothing in the agent's
+context ever uses workspace vocabulary and the model has no reason to prefer
+`/workspace` over `/tmp`. Either give it the file tools, or say in its prompt
+that work it means to keep goes in `/workspace`.
+
 Reusing one is the point of keeping it:
 
 ```
@@ -552,9 +587,17 @@ so inspection is free and offline.
 | Why was that recalled?                   | `zen memory show <id>`           |
 | That should never have been written down | `zen memory forget <id>`         |
 
+The directory is not fixed. `zen run --memory <dir>` sends one run's memory
+somewhere else - a scratch graph for a trial, one per branch, or a shared one
+outside the repository - and `zen memory --dir <dir>` reads any such directory
+with no project around it. Together they are also how you read a graph while a
+run holds its `.lock`: copy the directory, delete the copy's `.lock`, and point
+`--dir` at the copy.
+
 `zen inspect` answers the other half: a run report shows the recollection block
 exactly as the model received it, which is how you tell "memory had nothing"
-apart from "memory had it and the model ignored it".
+apart from "memory had it and the model ignored it". A run given `--memory`
+wants `zen inspect --memory <dir>` to rebuild its report against the same graph.
 
 ## A worked configuration
 
@@ -597,6 +640,9 @@ agents:
 - [ ] Every agent that should learn has a `memory:` binding - the top-level
       block alone enables nothing.
 - [ ] `access: full` appears at most once.
+- [ ] Any agent the design expects to commit `file` nodes can write to the
+      workspace - `write_file`/`apply_patch`, or `run_command` with `/workspace`
+      named in its prompt. Nothing else round-trips.
 - [ ] `sees`/`writes` exist because an agent would be **misled** by the other
       slice, not merely because it does not need it.
 - [ ] `autoRecall: false` on any agent whose user message is a payload.
@@ -612,7 +658,7 @@ agents:
 | The `memory_*` tools are missing                    | No `memory:` on the agent. They come from the binding, never from `tools:`                                 |
 | `zen memory` says the project has none              | Neither a `memory:` block nor an agent binding - nothing is opened and no directory is made                |
 | Recall finds a memory only when reworded            | No embedder. `zen memory stats` says `embedding none`                                                      |
-| Recall finds nothing after changing the embedder    | Refused rather than mixed - a manifest records the model. Re-embed or change it back                       |
+| Recall finds nothing after changing the embedder    | Refused rather than mixed - a manifest records the model. Change it back, or start a new memory            |
 | Vectors fewer than nodes                            | Some nodes were committed with no embedder; they are only reachable by term overlap                        |
 | The graph fills with restated requests              | The commit rule is not in a prompt or skill. State the "would a later run redo this" test                  |
 | An agent greps `/memory` or reads `graph.json`      | The house-rules block is missing from `agents/memory-instructions.md` - the system prompt never forbids it |
@@ -621,6 +667,8 @@ agents:
 | A wrong memory keeps coming back                    | It was edited instead of superseded, or superseded in the wrong direction - the **new** node is the source |
 | An agent cannot see a node you can                  | Its `audience` is not in that agent's `sees`. Invisible and missing are the same thing, on purpose         |
 | "this agent cannot remember files"                  | The agent has no workspace, so a path cannot be resolved. Commit without `file`                            |
+| `error: outside the workspace: /tmp/…`              | The file is real to the shell and outside the only tree memory reads. Write it under `/workspace`          |
+| Long content arrives as `text`, never as a `file`   | The agent has no tool that writes to the workspace, so it has no path to name                              |
 | A remembered file will not run                      | It is not self-contained - it referenced the workspace it was written in                                   |
 | Recollections are large and unhelpful               | `autoRecall.limit` is too high, or node texts describe answers rather than questions                       |
 | The model recalls a route the API no longer has     | Nothing re-checks memory against a rebuilt index. Supersede, and require verification                      |

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

@@ -1,6 +1,6 @@
 ---
 name: zen-review
-description: Checking a project before committing - the four mechanical checks `/review-project` makes before any judgement (`zen check`, the §2.5 path sweep, the memory house-rules copy, the spec-sync record), what each one owns, what their exit codes mean, and what deliberately has no check because no tool can make it. Load before running `/review-project`, before saying a project is ready, and whenever a review finding needs verifying rather than restating.
+description: Checking a project before committing - the four mechanical checks `/project-review` makes before any judgement (`zen check`, the §2.5 path sweep, the memory house-rules copy, the spec-sync record), what each one owns, what their exit codes mean, and what deliberately has no check because no tool can make it. Load before running `/project-review`, before saying a project is ready, and whenever a review finding needs verifying rather than restating.
 ---
 
 # Reviewing a project
@@ -104,7 +104,7 @@ Not because it would be hard, but because the answer would be wrong:
 - **Whether the newest spec-sync history entry is honest.** A pass can claim
   anything; only reading the diff says whether it did it.
 
-That list is `/review-project`, and §9 of the copilot instructions is the long
+That list is `/project-review`, and §9 of the copilot instructions is the long
 form. Run the script first so the prompt is spent on this.
 
 ## Where these scripts live, and why edits to them vanish

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

@@ -7,7 +7,7 @@
 #
 # What it prints is findings. What it cannot see — whether an agent has one job,
 # whether a description is a condition, whether a fact belongs in a skill — is
-# the rest of /review-project, and the reason that prompt still exists.
+# the rest of /project-review, and the reason that prompt still exists.
 #
 # Every step runs even when an earlier one fails: a review that stops at the
 # first problem is one somebody has to run four times. The exit code is 1 if

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

@@ -1,6 +1,6 @@
 ---
 name: zen-spec-sync
-description: Running `/sync-with-spec` 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 four checks a narrow pass may never skip, the iteration history format, and why the baseline is written last. Load before every `/sync-with-spec`, 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, the four checks a narrow pass may never skip, 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
@@ -84,7 +84,7 @@ editing anything, and report it in the chat as the pass's scope.
 2. **The `SPECIFICATION-FEEDBACK.md` diff.** The file is a questionnaire the
    human answers by ticking one answer's `[ ]` box or deleting the answers they
    do not want. A question that has moved under `✅ Answered` was folded into the
-   specification by `/update-spec-from-feedback`, and its **Still to implement**
+   specification by `/spec-apply-feedback`, and its **Still to implement**
    line is the work. A question with a box marked `[x]`, or one answer left
    under it, and no `✅` entry was answered and never folded in - implement it,
    put its text into `SPECIFICATION.md`, and say so. A new question someone else

package/templates/editor/.github/skills/zen-spec-sync/scripts/snapshot.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 #
-# The committed record of what the last completed /sync-with-spec pass applied.
+# The committed record of what the last completed /spec-sync-project pass applied.
 #
 #   snapshot.sh status    full | incremental | tampered, and what differs
 #   snapshot.sh diff      the difference the next pass has to work

package/templates/project/SPECIFICATION.md.tmpl

@@ -13,6 +13,22 @@ something in it — and report what was done in enough detail to be checked.
 - One request at a time, in one workspace, with the person who asked it present.
 - No schedule, no queue, nothing that outlives the session it was asked in.
 
+## Models
+
+- `{{modelRef}}` — one model for the whole project, used by every agent.
+- Named once in `agents.yaml` so it can be swapped in one place. Nothing here
+  depends on which model it is; a project that later needs a cheaper model for
+  one job adds a second alias rather than scattering the choice.
+
+## Setup
+
+- Run once, before any session: whatever has to exist before work can start —
+  an index built, a document fetched, a file generated.
+- `scripts/_setup.sh` is the one command that does it, and `scripts/<name>.sh`
+  are the steps it runs in order. A step is safe to run twice and reports
+  `skipped` the second time.
+- Currently: no steps. Nothing has to be prepared before a run.
+
 ## Agents
 
 - `default` — the entry point and the only agent; nobody to hand work to.
@@ -34,13 +50,20 @@ something in it — and report what was done in enough detail to be checked.
 
 ## Environment
 
-- Model: `{{modelRef}}`, one for the whole project.
 - Memory: `memory/`, kept with the project and committed except for its
   vectors, which are derived.
 - Sandbox: built from `sandbox/Dockerfile`, persists between runs, and can
   reach the network. What the work always needs belongs in the image, not in an
   instruction that reinstalls it on every run.
-- Setup: none. `scripts/_setup.sh` is where a step would go, and it has none.
+
+## Testing
+
+- `zen check` passes: the project loads, and every model, tool and skill an
+  agent is given resolves. It says nothing about whether the prose is right.
+- `scripts/_setup.sh` run twice in a row reports every step `skipped` the
+  second time.
+- A run against a real request: the workspace holds the change described, and
+  the reply's account of it matches what is on disk.
 
 ## Done means
 

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

@@ -0,0 +1,8 @@
+# Tool calls
+
+These rules are about _how_ tools are called, and hold for every agent.
+
+- Say what you are about to do in one sentence before each tool call, so the
+  run reads as an account of the work rather than a list of results.
+- Make independent calls together. Only wait for a result when the next call
+  needs it.