@zenera/cli 1.1.15 → 1.1.17

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

@@ -1,22 +1,23 @@
-# Copilot instructions — agent projects
+# Copilot instructions - agent projects
 
 > Written by `zen init` into `.github/copilot-instructions.md`, alongside the
 > prompt files and skills in the same tree (§2.4). VS Code loads it
 > automatically for every request in this folder, so it is the standing brief
-> for anyone — human or agent — editing this project.
+> for anyone - human or agent - editing this project.
 >
 > It describes the Zenera Neo runtime, not this particular project, and `zen`
-> rewrites the whole tree on `init` and `open` — so put this project's own
-> conventions in `INSTRUCTIONS.md`, where they will survive. The runtime's own
-> reference is `docs/agents-yaml.md`, `docs/projects.md` and `DESIGN.md` in the
-> @zenera/neo repository — where they disagree with this file, they win.
+> rewrites the whole tree on `init` and `open` - so put this project's own
+> conventions in `agents/instructions.md`, where they will survive. The
+> runtime's own reference is `docs/agents-yaml.md`, `docs/projects.md` and
+> `DESIGN.md` in the @zenera/neo repository - where they disagree with this
+> file, they win.
 
 ---
 
 ## 0. What this repository is
 
 This is **not a normal application repository**. There is no application code
-here. It is a folder of declarative artefacts — YAML and Markdown — that
+here. It is a folder of declarative artefacts - YAML and Markdown - that
 assemble into a running multi-agent system, driven by the `zen` CLI.
 
 The centre of gravity is **prose**. Every valuable change here is an edit to a
@@ -34,6 +35,86 @@ programmed: what an agent knows, which model answers, and which of the tools
 6. Every change must still load: `agents.yaml` is validated strictly at load,
    and `zen check` says so before a model is ever called.
 
+### 0.1 Copilot is the meta-agent: load the skill for every capability in use
+
+Copilot is always the meta-agent that creates and changes target projects. Load
+the editor's `zen-cli` skill before deciding how a target project should run,
+be validated, or use command-line capabilities. It is the command contract; do
+not reconstruct `zen` arguments from memory or call `--help` to discover them.
+
+**Every runtime capability a project turns on carries obligations that are not
+visible in `agents.yaml` and that `zen check` does not report.** Before
+reviewing or changing a project, list the capabilities it has turned on and load
+the editor skill for each one - `zen-memory` for a `memory:` block, `zen-rag-
+schema` or `zen-rag-docs` for an index, `zen-cli` always. A capability that is
+already configured and already passing `zen check` is exactly the case that
+looks finished and is not: the obligation lives in the skill, so a review that
+never opens the skill cannot find what is missing. This applies whatever
+prompted the change - a task scoped to `SPECIFICATION.md` does not narrow it.
+
+First determine whether the target project uses RAG: a `zen rag` command in an
+agent prompt or skill, RAG tools supplied by its host, or a documentation or
+schema index it is expected to consult all count. When it does, also load the
+`zen-cli` skill's `references/rag.md` before writing the target's instructions.
+
+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:
+
+1. Discover document and section names with the exact listing command or tool.
+2. Start with hybrid search for a complete natural-language question.
+3. Narrow by document, section, and content kind before repeatedly rewording a
+   query; verify facts with exact lookup or a verbatim read.
+4. Use full-text search for a known literal term, vector search for unknown
+   wording, and split text/vector queries only when the exact term is
+   distinctive enough to improve the semantic question.
+5. Retrieve a complete section verbatim, or list a table and read its inclusive
+   line range when every row is needed.
+
+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
+target project. Grant the agents that need CLI RAG the necessary `sandbox:*`
+tool access; give tool-based RAG users the configured RAG tools instead. Run
+`zen check` after adding or changing the skill.
+
+Memory has one such obligation and it is absolute: **a project with a `memory:`
+block carries the `zen-memory` skill's `references/memory-instructions.md` in its
+own `agents/memory-instructions.md`.** `zen init` writes both, since it scaffolds
+memory on; what needs watching is a project that deleted the file, or one whose
+copy has fallen behind the reference. Do not read the two files against each
+other - they drift by trailing whitespace inside tables, which is invisible.
+The skill ships the check:
+
+```sh
+.github/skills/zen-memory/scripts/check-instructions.sh       # the verdict
+.github/skills/zen-memory/scripts/check-instructions.sh fix   # copy the reference over
+```
+
+It is a copy, never a transcription - the reference ships inside the project,
+because `zen init` and `zen open` write this whole `.github/` tree, so `fix` is
+just `cp` from one to the other.
+
+Nothing else tells a running agent how the store works, so without it nothing
+forbids an agent from pointing `grep` or `cat` at `/memory` - a read that
+bypasses the audience mask and serves superseded nodes as current. Keep the copy
+byte-identical and put this project's own memory policy in a second topic file,
+`agents/memory-policy-instructions.md`, which is read straight after it: then the
+copy can be re-run after any `zen init` or `zen open` refreshes the reference,
+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
+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
+moved without a history entry to match it, which is a pass claiming work it did
+not do, and a `.spec-sync/baseline/` whose `manifest.txt` no longer matches its
+files. Both are reported, not quietly repaired - rewriting the manifest asserts
+a pass that never happened.
+
 ---
 
 ## 1. Mental model
@@ -42,15 +123,16 @@ programmed: what an agent knows, which model answers, and which of the tools
 
 An agent is four things and nothing more:
 
-| Part            | Where it lives                                 | What it decides               |
-| --------------- | ---------------------------------------------- | ----------------------------- |
-| **Instruction** | `INSTRUCTIONS.md` + `agents/prompts/<name>.md` | How it behaves                |
-| **Model**       | `agents.yaml` → `model:`                       | How well and how expensively  |
-| **Tools**       | `agents.yaml` → `tools:`                       | What it can _do_              |
-| **Knowledge**   | `agents/skills/*` + memory                     | What it can _know_, on demand |
+| Part            | Where it lives                                         | What it decides               |
+| --------------- | ------------------------------------------------------ | ----------------------------- |
+| **Instruction** | `agents/*instructions.md` + `agents/prompts/<name>.md` | How it behaves                |
+| **Model**       | `agents.yaml` → `model:`                               | How well and how expensively  |
+| **Tools**       | `agents.yaml` → `tools:`                               | What it can _do_              |
+| **Knowledge**   | `agents/skills/*` + memory                             | What it can _know_, on demand |
+
+Plus two relations: **handoffs** - which other agents it may transfer control to
 
-Plus two relations: **handoffs** — which other agents it may transfer control to
-— and **fork** — whether it may split into parallel branches at all (§6.4).
+- and **fork** - whether it may split into parallel branches at all (§6.4).
 
 There is no hidden orchestration layer. If behaviour is wrong, one of those six
 things is wrong.
@@ -81,7 +163,7 @@ is deciding **what is in that sequence and in what order**.
 ```
 ┌─────────────────────────────────────────────┐
 │ tool schemas          fixed at load         │  ← stable, cacheable
-│ INSTRUCTIONS.md       shared by all agents  │  ← stable, cacheable
+│ agents/*instructions  shared by all agents  │  ← stable, cacheable
 │ agent prompt          this agent's brief    │  ← stable per agent
 │ skill index           names + descriptions  │  ← stable per agent
 │ preloaded skills      activated turn 0      │  ← stable, in the cached prefix
@@ -93,8 +175,8 @@ is deciding **what is in that sequence and in what order**.
 Two consequences that drive nearly every design rule in this document:
 
 - **Stable prefix = cache hit.** Providers cache by prefix. Anything appended
-  mid-run _after_ the first reply — a tool schema, an instruction, a late skill
-  activation — invalidates the cache from that point on. This is why tool schemas
+  mid-run _after_ the first reply - a tool schema, an instruction, a late skill
+  activation - invalidates the cache from that point on. This is why tool schemas
   are fixed at load and skill-owned tools are declared from turn 0 and merely
   _gated_ at call time.
 - **Everything in the prefix is paid for on every call.** A 4 000-token prompt
@@ -110,7 +192,7 @@ Two consequences that drive nearly every design rule in this document:
   a number.
 - Numbers come from tools; the model narrates, it does not compute.
 - The failure mode of every instruction is stated ("if X is absent, say so and
-  stop") — an unstated failure mode is an invented one.
+  stop") - an unstated failure mode is an invented one.
 
 ---
 
@@ -120,14 +202,16 @@ Two consequences that drive nearly every design rule in this document:
 
 ```
 my-project/
-├── .github/                      the editor's brief — §2.4
+├── .github/                      the editor's brief - §2.4
 │   ├── copilot-instructions.md   this file
 │   ├── prompts/*.prompt.md       tasks you invoke by name
 │   └── skills/*/SKILL.md         reference the editor loads on demand
-├── .env                          credentials — NEVER committed
-├── INSTRUCTIONS.md               house rules, prepended to every agent
+├── .env                          this project's environment - NEVER committed
+├── .spec-sync/                   what the last /sync-with-spec 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`
 │   ├── prompts/
 │   │   ├── intake.md             one agent's own brief
 │   │   └── adjuster.md
@@ -139,10 +223,10 @@ my-project/
 │       │   └── SKILL.md
 │       └── refund_policy/
 │           ├── SKILL.md
-│           └── scripts/calculate.py   run at /skills/refund_policy/scripts — §3.4.1
+│           └── scripts/calculate.py   run at /skills/refund_policy/scripts - §3.4.1
 ├── assets/                       reference material, read-only at /assets
-├── memory/                       the graph agents remember into — §5.3
-├── sandbox/Dockerfile            the image commands run in — §3.7
+├── memory/                       the graph agents remember into - §5.3
+├── sandbox/Dockerfile            the image commands run in - §3.7
 └── sessions/                     run state, whatever the agent wrote
 ```
 
@@ -150,28 +234,33 @@ Only `agents.yaml` is required, and only `agents:` is required inside it.
 The config is found by name, in order: `agents.yaml`, `agents.yml`,
 `agents/agents.yaml`, `agents/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.
+
 ### 2.2 Variants
 
-**Single agent, knowledge-heavy** — the most under-used shape. One agent, one
+**Single agent, knowledge-heavy** - the most under-used shape. One agent, one
 prompt, a large skill catalog. Prefer this until routing is genuinely needed.
 
 ```
-INSTRUCTIONS.md · agents.yaml · agents/prompts/assistant.md · agents/skills/**  (20 skills)
+agents.yaml · agents/instructions.md · agents/prompts/assistant.md · agents/skills/**  (20 skills)
 ```
 
-**Router + specialists** — a cheap intake agent that classifies and hands off.
+**Router + specialists** - a cheap intake agent that classifies and hands off.
 
 ```
 agents/prompts/{intake,billing,technical,escalation}.md
 ```
 
-**Pipeline** — fixed stages, each handing to the next; the last one answers.
+**Pipeline** - fixed stages, each handing to the next; the last one answers.
 
 ```
 research → draft → review
 ```
 
-**Shared skills across projects** — `skills:` accepts a list, merged into one
+**Shared skills across projects** - `skills:` accepts a list, merged into one
 catalog:
 
 ```yaml
@@ -181,7 +270,7 @@ skills:
 ```
 
 Paths may not escape the project root unless the root is set to the common
-ancestor. Several directories become **one** provider (id `project`) — "which
+ancestor. Several directories become **one** provider (id `project`) - "which
 folder is this skill in?" is not a question an author should have to answer.
 
 ### 2.3 Naming rules (enforced)
@@ -201,29 +290,30 @@ dots.
 There are two sets of instructions in this repository and they are not for the
 same reader. Keeping them apart is the single easiest thing to get wrong.
 
-| Tree                         | Read by                                    | About                               |
-| ---------------------------- | ------------------------------------------ | ----------------------------------- |
-| `INSTRUCTIONS.md`, `agents/` | the **project's** agents, at run time      | the domain this system works in     |
-| `.github/`                   | the **editor's** assistant, while you edit | how a project of this kind is built |
+| Tree                     | Read by                                    | About                               |
+| ------------------------ | ------------------------------------------ | ----------------------------------- |
+| `agents.yaml`, `agents/` | the **project's** agents, at run time      | the domain this system works in     |
+| `.github/`               | the **editor's** assistant, while you edit | how a project of this kind is built |
 
 The `.github/` tree follows the same progressive-disclosure discipline the
-agents do, for the same reason — it is a prefix somebody pays for:
+agents do, for the same reason - it is a prefix somebody pays for:
 
 - **`copilot-instructions.md`** is always on. Everything in it is loaded for
   every request in this folder, so it holds only what is true of every task.
 - **`.github/skills/<name>/SKILL.md`** is reference the editor loads when its
-  `description` matches what you asked. Put long, occasional material here —
-  a command surface, a vendor's quirks, a format spec — not in the file above.
+  `description` matches what you asked. Put long, occasional material here -
+  a command surface, a vendor's quirks, a format spec - not in the file above.
   The `description` is the routing key; §3.4 applies to these as much as to the
   project's own skills.
 - **`.github/prompts/<name>.prompt.md`** is a task you invoke by name (`/name`),
   with `mode: agent` and a `description` in its frontmatter. Write one when a
-  job is done repeatedly and has a right order — adding an agent, adding a
+  job is done repeatedly and has a right order - adding an agent, adding a
   skill, reviewing before a commit.
 
 `zen init` and `zen open` rewrite this whole tree from the version of `zen` in
 hand, so **edits inside `.github/` do not survive**. Project-specific conventions
-belong in `INSTRUCTIONS.md` and the agent prompts, which are never overwritten.
+belong in `agents/instructions.md` and the agent prompts, which are never
+overwritten.
 
 ### 2.5 What a running agent can actually see
 
@@ -232,24 +322,24 @@ it. Its entire world is the tools it was granted (§3.5) and four paths:
 
 | Path         | Is                                        | Access                                                 |
 | ------------ | ----------------------------------------- | ------------------------------------------------------ |
-| `/workspace` | the session's workspace — the work itself | read/write; `zen run --read-only` withholds the writes |
-| `/assets`    | `assets/`, reference material — §3.11     | read-only                                              |
-| `/skills`    | the whole skill catalog — §3.4.1          | read-only                                              |
-| `/memory`    | files carried by remembered nodes — §5.3  | read-only, and only when `memory:` is configured       |
+| `/workspace` | the session's workspace - the work itself | read/write; `zen run --read-only` withholds the writes |
+| `/assets`    | `assets/`, reference material - §3.11     | read-only                                              |
+| `/skills`    | the whole skill catalog - §3.4.1          | read-only                                              |
+| `/memory`    | files carried by remembered nodes - §5.3  | read-only, and only when `memory:` is configured       |
 
 Commands run inside the container `sandbox:` describes (§3.7): the same
 `/workspace`, and whatever the image ships.
 
-Everything else in the project directory is **invisible at run time** —
-`agents.yaml`, `INSTRUCTIONS.md`, `agents/prompts/`, `agents/skills/` under that
-name, `sandbox/Dockerfile`, `.env`, `.github/`, `sessions/`, and the project
-root itself. `zen` reads them to build the run; they are never a path an agent
-can open.
+Everything else in the project directory is **invisible at run time** -
+`agents.yaml`, `agents/instructions.md`, `agents/prompts/`, `agents/skills/`
+under that name, `sandbox/Dockerfile`, `.env`, `.github/`, `sessions/`, and the
+project root itself. `zen` reads them to build the run; they are never a path an
+agent can open.
 
 Two consequences:
 
 - **The workspace is not the project.** It defaults to the session's own empty
-  folder, and is usually some other repository entirely — `--workspace`, or the
+  folder, and is usually some other repository entirely - `--workspace`, or the
   directory the user was standing in. A prompt saying "read `agents.yaml`" or
   "the rules are in `agents/skills/`" names a file that is not there.
 - **Write the mount path, never the repository path.**
@@ -259,46 +349,50 @@ Two consequences:
   the one place the file is not.
 
 An agent that must know something about its own configuration is **told it in
-prose**, in the prompt — never sent to read the file that configured it.
+prose**, in the prompt - never sent to read the file that configured it.
 
-#### Checklist — no path an agent cannot open
+#### Checklist - no path an agent cannot open
 
-Run this over `INSTRUCTIONS.md`, every `agents/prompts/*.md` and every
-`agents/skills/*/SKILL.md` after editing any of them. Every path-shaped token in
-those files is read by a model as an instruction to open something:
+Run this over every `agents/*instructions.md`, every `agents/prompts/*.md` and
+every `agents/skills/*/SKILL.md` after editing any of them. Every path-shaped
+token in those files is read by a model as an instruction to open something:
 
 - [ ] Every absolute path begins `/workspace`, `/assets`, `/skills` or
       `/memory`. Nothing else exists.
-- [ ] No project file is named: `agents.yaml`, `INSTRUCTIONS.md`,
+- [ ] No project file is named: `agents.yaml`, `agents/instructions.md`,
       `agents/prompts/…`, `agents/skills/…`, `sandbox/Dockerfile`, `.env`,
       `.github/…`, `sessions/…`, `SPECIFICATION.md`, `README.md`, `docs/…`.
 - [ ] Nothing escapes a mount: no `../`, no `~`, no host path (`/Users/…`,
       `/home/<someone>`), no `/etc`, `/var` or `/tmp` expected to hold anything
       the project put there.
 - [ ] Each `/assets/…` and `/skills/<name>/…` path names a file that is actually
-      committed there — `zen check` lists what every skill folder ships (§3.4.1).
+      committed there - `zen check` lists what every skill folder ships (§3.4.1).
 - [ ] A skill referring to its own sibling file writes the full
       `/skills/<name>/` prefix, not `./rates.csv`: the body is rendered into a
       prompt, not executed from its folder.
 - [ ] `/memory` is named only in prompts for agents that have `memory:` (§5.3),
       and `/assets` only where an `assets/` directory exists.
-- [ ] The agent holding the prompt has the tool the path implies — `read_file`
+- [ ] The agent holding the prompt has the tool the path implies - `read_file`
       to open one, `sandbox:*` to run one (§3.4.1).
 - [ ] Every instruction that opens a file states what to do when it is not there
       (§4.2, rule 6). Workspaces differ between runs; absence is normal.
 - [ ] Relative paths appear only where `/workspace`-relative is what was meant.
 
-Finding the candidates, from the project root — every path-shaped token in the
+Finding the candidates, from the project root - every path-shaped token in the
 three trees, minus the ones under a mount:
 
 ```sh
-grep -Eohr '[~.]?/?[A-Za-z0-9_.-]*/[A-Za-z0-9_.*-]+' \
-     INSTRUCTIONS.md agents/prompts agents/skills \
-  | sort -u | grep -Ev '^/(workspace|assets|skills|memory)(/|$)'
+.github/skills/zen-review/scripts/check-paths.sh
 ```
 
-Everything it prints is either a false positive (a url, a `path/to` in a
-sentence, `and/or`) or a path the agent cannot open. There is no third case.
+It prints each candidate with the file and line it is on, and exits non-zero
+while any remain. Everything it prints is either a path the agent cannot open or
+noise the script has not learned yet - a url, a `path/to` in a sentence, an
+`and/or` - and there is no third case. It strips the noise it does know about,
+so a candidate that survives is one to explain or fix rather than one to skim
+past. `check-paths.sh raw` is the sweep with nothing filtered, for when the
+filter itself is the suspect. The `zen-review` skill says what it covers and
+what it cannot.
 
 ---
 
@@ -307,20 +401,20 @@ sentence, `and/or`) or a path the agent cannot open. There is no third case.
 ### 3.1 `agents.yaml`
 
 The schema is **strict**: an unknown key is a load error, not a value silently
-ignored. Errors name the path — `agents.yaml: agents[1].skills.discovery — …`.
+ignored. Errors name the path - `agents.yaml: agents[1].skills.discovery - …`.
 
 ```yaml
 version: 1 # schema version, defaults to 1
 default: intake # entry agent; wins over any `default: true`
 
 providers: {} # named connections (credentials + endpoint)
-provider: openai # the provider an unprefixed model id belongs to — §7.3
+provider: openai # the provider an unprefixed model id belongs to - §7.3
 models: {} # named model configurations
 model: fast # fallback for agents that do not pin their own
-embeddings: {} # named vectorisers — §3.1.1
+embeddings: {} # named vectorisers - §3.1.1
 embedding: small # the one `AgentProject.embedder()` returns when asked for no name
 skills: agents/skills # one directory, or a list
-assets: assets # reference material, read-only at /assets — §3.11
+assets: assets # reference material, read-only at /assets - §3.11
 
 agents: # the only required key; at least one entry
     - name: intake
@@ -339,13 +433,13 @@ agents: # the only required key; at least one entry
 | `description` | What a sibling's `transfer_to_<name>` tool tells the model. Write it _for the model_ |
 | `system`      | Prompt path, relative to root. Defaults to `agents/prompts/<name>.md` if present     |
 | `model`       | A `models:` alias or shorthand. Falls back to top-level `model:`                     |
-| `tools`       | Selectors over the tools `zen run` provides — see §3.6                               |
+| `tools`       | Selectors over the tools `zen run` provides - see §3.6                               |
 | `handoffs`    | Agent names this one may transfer to. Bare strings; no per-edge config               |
-| `skills`      | Skill binding — see §5.2                                                             |
-| `fork`        | `true`, or `{ agents, maxBranches }` — opt-in to parallel branches; see §6.4         |
+| `skills`      | Skill binding - see §5.2                                                             |
+| `fork`        | `true`, or `{ agents, maxBranches }` - opt-in to parallel branches; see §6.4         |
 | `default`     | `true` marks the entry point when no top-level `default:`                            |
 
-**Providers** — a provider is a _connection_, not a model. One client is built
+**Providers** - a provider is a _connection_, not a model. One client is built
 per name and shared, so five agents on one key open one connection pool.
 
 | Field                     | Meaning                                                                                                   |
@@ -353,20 +447,20 @@ per name and shared, so five agents on one key open one connection pool.
 | `kind`                    | `openai` \| `google` \| `vertex` \| `anthropic` \| `openrouter` \| `openai-compatible` (default `openai`) |
 | `apiKey` / `apiKeyEnv`    | Literal, `${VAR}`, or the name of the env var holding it                                                  |
 | `baseURL` / `baseURLEnv`  | For gateways and compatible endpoints                                                                     |
-| `project` / `location`    | **vertex only** — GCP project id and region (or `global`)                                                 |
+| `project` / `location`    | **vertex only** - GCP project id and region (or `global`)                                                 |
 | `headers`                 | Sent on every request: routing, attribution, api versions                                                 |
 | `timeoutMs`, `maxRetries` | Per-request timeout and retry count                                                                       |
 
 `openai`, `google`, `vertex`, `anthropic`, `openrouter` and `openai-compatible`
 are usable as provider _names_ with no declaration at all. Declare a
-`providers:` entry only when it says something the default does not — a second
+`providers:` entry only when it says something the default does not - a second
 key, a region, a base url.
 
 `${VAR}` and `${VAR:-fallback}` expand from the environment, compose inside
 longer values (`https://${GATEWAY}/v1`), and are **lazy**: a declared-but-unused
 provider with a missing key does not fail loading.
 
-**Errors caught at load** — rely on these instead of defensive checks:
+**Errors caught at load** - rely on these instead of defensive checks:
 
 - any unknown key; any name breaking the pattern
 - `models.<alias>.provider` naming an undeclared provider
@@ -375,27 +469,27 @@ provider with a missing key does not fail loading.
 - `agents[].handoffs` naming an unknown agent, or the agent itself
 - `agents[].skills.provider` / `.allow` / `.preload` naming something absent
 - a `preload:` entry missing from `allow:`
-- `agents[].fork.agents` naming an unknown agent, or being empty; `maxBranches` below 2
+- `agents[].fork.agents` naming an unknown agent, or being empty; `maxBranches` below 1
 - `system:` pointing at a missing file, or outside the project root
 
-**Not caught at load** — a model id whose prefix is missing and so resolves to the
+**Not caught at load** - a model id whose prefix is missing and so resolves to the
 wrong provider (§7.3), and any combination of knobs the vendor rejects at request
 time, such as OpenAI reasoning on chat completions (§7.6). Both surface on the
 first call, so read §7 before writing a `models:` entry.
 
-**Caught by `zen check`, not by the loader** — a handoff with no path back
+**Caught by `zen check`, not by the loader** - a handoff with no path back
 (`handoff.one-way`, §6.3). The project runs; it just cannot return.
 
-**Comments in `agents.yaml`** — this file is the architecture diagram of the
+**Comments in `agents.yaml`** - this file is the architecture diagram of the
 project, and its comments are read by whoever has to change it next. Write them
 at that level:
 
 - Say **what a block is for** and **why it exists**: what this agent owns, why
   this one is on the deep tier, why this handoff edge is there.
-- Keep them **short** — one line above a block, a few words at the end of a line.
+- Keep them **short** - one line above a block, a few words at the end of a line.
   A comment longer than the thing it describes is a design doc in the wrong file.
 - Do **not** restate the runtime. How skills are discovered, how the trajectory
-  is appended, how prompt caching works, what the loader validates — none of that
+  is appended, how prompt caching works, what the loader validates - none of that
   belongs here. It is documented in this file and in `docs/agents-yaml.md`.
 - Do **not** restate the key. `# the model this agent uses` above `model:` is
   noise; `# cheap: it only classifies` is not.
@@ -404,7 +498,7 @@ at that level:
 ```yaml
 # Intake classifies and routes; it never answers.
 - name: intake
-  model: router # cheap tier — one sentence in, one handoff out
+  model: router # cheap tier - one sentence in, one handoff out
   handoffs: [adjuster, escalation]
 ```
 
@@ -432,12 +526,12 @@ embedding: small
 | Field                    | Meaning                                                                  |
 | ------------------------ | ------------------------------------------------------------------------ |
 | `provider`               | A `providers:` name or a built-in kind. Defaults to the default provider |
-| `model`                  | **Required.** The bare id — the object form never re-parses a shorthand  |
+| `model`                  | **Required.** The bare id - the object form never re-parses a shorthand  |
 | `dimensions`             | Truncate to this width, where the model supports it                      |
 | `apiKey` / `baseURL` / … | The same credential fields a provider takes, for a one-off connection    |
-| `title`                  | **gemini only** — a document title the retrieval task type weighs        |
-| `maxBatch`               | **gemini only** — texts per request; see below                           |
-| `routing`                | **openrouter only** — which upstream provider serves the request         |
+| `title`                  | **gemini only** - a document title the retrieval task type weighs        |
+| `maxBatch`               | **gemini only** - texts per request; see below                           |
+| `routing`                | **openrouter only** - which upstream provider serves the request         |
 
 Four things differ from `models:` and are worth knowing before you write one:
 
@@ -445,14 +539,14 @@ Four things differ from `models:` and are worth knowing before you write one:
   api means nothing on any protocol. The shorthand is `[provider:]model`.
 - **`kind: anthropic` has no embeddings API at all.** Anthropic publishes none
   and points at third parties; an `embeddings:` entry on an Anthropic provider
-  fails at load. Use another provider — the connection need not be the one the
+  fails at load. Use another provider - the connection need not be the one the
   agents talk through.
 - **Not a per-agent key.** Nothing in the runtime consumes a vectoriser yet, so
   there is no `agents[].embedding:`. A TypeScript host reaches one with
   `project.embedder()` for the default, or `project.embedder('large')` by name.
 - **Vectors come back unit length**, so cosine and dot product agree. This is a
   guarantee of the runtime, not of the vendor: truncating with `dimensions:` is a
-  raw slice and only some models rescale afterwards — `gemini-embedding-2` does,
+  raw slice and only some models rescale afterwards - `gemini-embedding-2` does,
   `gemini-embedding-001` returns |v| ≈ 0.58 at 768 of its 3072. Pass
   `normalize: false` on a call to see what the model actually said.
 
@@ -464,14 +558,26 @@ hide that. `maxBatch` therefore defaults to `1`; raise it only for a
 `zen check` reports every declared embedding beside the models, with the
 credential each one would need.
 
-### 3.2 `INSTRUCTIONS.md`
+### 3.2 `agents/instructions.md` and friends
 
-House rules, read **once** and prepended to every agent's system prompt. It is
-the stable head of the cached prefix, so it should change rarely. The name is
-deliberately not `AGENTS.md` — that one belongs to the coding assistant reading
+House rules, read **once** and prepended to every agent's system prompt. They are
+the stable head of the cached prefix, so they should change rarely. The name is
+deliberately not `AGENTS.md` - that one belongs to the coding assistant reading
 this file, and these rules address the project's own agents.
 
-Put here only what is true for **every** agent:
+There may be more than one. `agents/instructions.md` is the base; every
+`agents/<topic>-instructions.md` is read after it, in filename order, and every
+agent gets all of them. Each arrives as its own block tagged with the file it
+came from - `<house_rules src="agents/memory-instructions.md">` - so the model
+can tell one document from the next.
+
+Split a topic out when it is true for every agent but belongs to **one
+capability**: the memory usage rules (§5.3) are the standard case - they arrive
+when `memory:` is turned on and are deleted when it is turned off, which is a
+whole file rather than a section somebody has to find. Do not split by author,
+by date, or to keep a file short; that is what a skill is for.
+
+Put in them only what is true for **every** agent:
 
 - identity and domain ("You work the property claims desk")
 - non-negotiable prohibitions (regulatory, legal, safety)
@@ -482,11 +588,11 @@ Do **not** put here: anything one agent needs and another does not; anything tha
 changes weekly; long reference data (that is a skill).
 
 **When writing it, remember what it is: a prefix on every agent's system prompt.**
-It is not a README and not a design document — every line is paid for on every
+It is not a README and not a design document - every line is paid for on every
 call, by every agent, and each one is an instruction the model will try to
 follow. So:
 
-- It is a **prompt**: §4.2 applies in full — second person, imperative, no
+- It is a **prompt**: §4.2 applies in full - second person, imperative, no
   hedging, no meta-talk about the runtime, failure paths stated.
 - Carry the **shared model of the project**: what this system is, what the agents
   are collectively for, how the work flows between them, and the vocabulary and
@@ -498,13 +604,13 @@ follow. So:
 - Anything only one agent needs goes in that agent's prompt instead. If you find
   yourself writing "if you are the router…", you are in the wrong file.
 
-Target 20–60 lines. If it exceeds ~100, split the stable half out into a
+Target 20–60 lines each. If one exceeds ~100, split the stable half out into a
 preloaded skill.
 
 ### 3.3 `agents/prompts/<name>.md`
 
 Plain Markdown, no frontmatter. This is the agent's _job description_, appended
-after `INSTRUCTIONS.md`.
+after the house rules.
 
 Structure that works:
 
@@ -513,7 +619,7 @@ Structure that works:
 
 <what it does, as a short numbered procedure or 3–5 rules>
 
-<what it must NOT do — especially the neighbouring agent's job>
+<what it must NOT do - especially the neighbouring agent's job>
 
 <how to finish: the shape of the answer, or which handoff ends the turn>
 ```
@@ -530,7 +636,7 @@ Your job is small and you should finish it fast:
    and see what it covers.
 3. Hand the case to the `adjuster` agent, which owns the peril policies.
 
-Do not quote coverage rules yourself — you do not have them. Do not ask the
+Do not quote coverage rules yourself - you do not have them. Do not ask the
 claimant for anything the message already contains.
 ```
 
@@ -538,9 +644,9 @@ Note what makes it work: it is 9 lines; it names the tool and the handoff
 literally; it states the boundary ("you do not have them") with the _reason_; it
 forbids the specific failure that agent actually exhibits.
 
-Write it as a prompt, under the rules in §4.2 — **instructive and concise**. It
-tells one agent what to do; it never explains the system (`INSTRUCTIONS.md`
-already did, §3.2), never repeats a house rule, and never describes the runtime.
+Write it as a prompt, under the rules in §4.2 - **instructive and concise**. It
+tells one agent what to do; it never explains the system (the house rules
+already did, §3.2), never repeats one of them, and never describes the runtime.
 Every line should be an instruction the model can act on or a boundary it can
 check itself against.
 
@@ -549,8 +655,8 @@ yet.
 
 ### 3.4 Skills
 
-A skill is curated, reusable instruction content — plus the files and tools it
-needs — loaded **on demand** instead of permanently occupying the system prompt.
+A skill is curated, reusable instruction content - plus the files and tools it
+needs - loaded **on demand** instead of permanently occupying the system prompt.
 One layout, and only one:
 
 ```
@@ -564,7 +670,7 @@ to move it to `refund_policy/SKILL.md`. A skill with nowhere to put a table, an
 example or a script can only ever be prose, which is the half of the idea that
 does not need a file.
 
-Frontmatter is a deliberately small subset of YAML — `key: value`, plus `[a, b]`
+Frontmatter is a deliberately small subset of YAML - `key: value`, plus `[a, b]`
 flow lists for `tags` and `tools`. **Every key is optional**: `name` defaults to
 the folder name, `description` to the first non-empty line of the body.
 
@@ -579,9 +685,9 @@ tools: [issue_refund]
 
 A parcel counts as late once it passes its promised delivery date by 48 hours.
 
-- **48h to 7 days late** — apologise, confirm the parcel is still moving, and
+- **48h to 7 days late** - apologise, confirm the parcel is still moving, and
   refund the shipping fee. Do not refund the goods.
-- **More than 7 days late** — treat the parcel as lost. Offer a replacement at
+- **More than 7 days late** - treat the parcel as lost. Offer a replacement at
   no cost, or a full refund, whichever the customer prefers.
 
 Never give a new delivery date. Say "still in transit" instead.
@@ -594,7 +700,7 @@ skill is needed_, not as a title:
 | Bad                         | Good                                                                                 |
 | --------------------------- | ------------------------------------------------------------------------------------ |
 | `description: Refunds`      | `description: When a refund is owed, and how much.`                                  |
-| `description: Water policy` | `description: Escape of water from plumbing and tanks — and the freezing exclusion.` |
+| `description: Water policy` | `description: Escape of water from plumbing and tanks - and the freezing exclusion.` |
 
 **`tools:` in frontmatter** names skill-owned tools. They are declared to the
 provider from turn 0 (the schema never changes) but **refuse to execute** until
@@ -635,7 +741,7 @@ Rules that follow from the mount:
 - The agent needs `sandbox:*` to run the script and `read_file` to open a data
   file. Grant them, or the skill's own instructions cannot be followed (§3.5).
 - **The interpreter must already be in the sandbox image.** A skill whose
-  script needs `pandas` is a `sandbox/Dockerfile` line that was never written —
+  script needs `pandas` is a `sandbox/Dockerfile` line that was never written -
   not a first line that runs `pip install` on every turn (§3.7).
 - **`/skills` is read-only.** A script that produces a file must take an output
   path and write it under `/workspace`.
@@ -644,7 +750,7 @@ Rules that follow from the mount:
   directory is `/workspace`.
 - Say what to do when the script fails, as with any other instruction (§4.2).
 - With several `skills:` directories, one catalog is the whole of `/skills` and
-  several take `/skills/<folder>` each — check the rendered path before writing
+  several take `/skills/<folder>` each - check the rendered path before writing
   it into the body.
 - The mount is created before anything is loaded, so `allow:` limits what an
   agent can **load**, not what it can **read**. Do not put anything in the
@@ -656,8 +762,8 @@ committed shows up as a skill with no files.
 ### 3.5 Tools
 
 A tool is what an agent can _do_ rather than say. `zen run` provides three
-groups — the workspace tools (§3.6), the sandbox tools (§3.7) and the web tools
-(§3.8) — and `agents.yaml` decides which agent holds which. Nothing else reaches
+groups - the workspace tools (§3.6), the sandbox tools (§3.7) and the web tools
+(§3.8) - and `agents.yaml` decides which agent holds which. Nothing else reaches
 the machine, so `tools:` is the whole permission model: an agent that does not
 name a tool cannot use it, whatever its prompt says.
 
@@ -668,7 +774,7 @@ Two rules follow:
 - **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.
 
-Skills can own tools too — `tools:` in a skill's frontmatter (§3.4) names tools
+Skills can own tools too - `tools:` in a skill's frontmatter (§3.4) names tools
 that refuse to run until that skill is active.
 
 ### 3.6 The workspace tools (`workspace:*`)
@@ -687,12 +793,12 @@ them cannot see a file at all.
 | `move_file`   | Moves or renames; refuses to clobber without `overwrite`                                 |
 | `delete_file` | Deletes; a directory needs `recursive`                                                   |
 
-Every path is resolved through one containment gate — symlinks followed, then
-checked — so nothing outside the workspace root is reachable. Reads are capped
+Every path is resolved through one containment gate - symlinks followed, then
+checked - so nothing outside the workspace root is reachable. Reads are capped
 and listings bounded, so no single call can flood the context.
 
-Paths are written relative to the root, and `/workspace/...` — the name the same
-directory has inside the sandbox (§3.7) — is accepted as well, so a path copied
+Paths are written relative to the root, and `/workspace/...` - the name the same
+directory has inside the sandbox (§3.7) - is accepted as well, so a path copied
 out of a command's output does not have to be translated first. When a mount is
 configured the tools also _report_ that name, so the two toolsets speak one
 vocabulary and a path can be passed from either to the other unchanged; with no
@@ -720,7 +826,7 @@ agents:
 
 Selectors apply in the order written, so a `-` line reads as an exception to the
 line above it. Quote a lone `'*'`: unquoted, YAML reads it as an alias and
-refuses the file. `workspace:*` needs no quoting. There is no name globbing —
+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.
 
@@ -730,7 +836,7 @@ asks for: the deployment overriding the repository, as everywhere else.
 **Prompting for them.** Three lines earn their place in any prompt that grants
 this group:
 
-- Read before editing — `apply_patch` matches on exact text, so a patch built
+- Read before editing - `apply_patch` matches on exact text, so a patch built
   from memory fails.
 - Prefer `apply_patch` to `write_file` for an existing file. Rewriting a file to
   change one line costs the whole file in output tokens and loses everything the
@@ -751,7 +857,7 @@ build, test, install and inspect rather than only read and write.
 | `read_command_output`    | A window of a job's output from `start_line`, plus whether it still runs |
 | `stop_command`           | Signals a job's process group                                            |
 
-The container is the boundary. Nothing inspects the command — there is no
+The container is the boundary. Nothing inspects the command - there is no
 allow-list of binaries and no pattern matching on what the model wrote, because
 both are trivially defeated and neither survives a shell. What holds is that
 only the workspace and the session's `/home/agent` are mounted, the container
@@ -759,12 +865,12 @@ is removed at the end of the session, and the command is never a shell argument
 on the host: it travels on stdin to `/bin/sh` inside.
 
 **Configuring it.** A top-level `sandbox:` block in `agents.yaml` describes the
-container. Every field has a default, so the block is optional — write only the
+container. Every field has a default, so the block is optional - write only the
 lines that differ:
 
 ```yaml
 sandbox:
-    persist: true # recommended — see below
+    persist: true # recommended - see below
     image: docker.io/library/python:3.14-slim-bookworm # the default
     cpus: 4 # fractional cores
     memory: 4096 # MiB
@@ -773,25 +879,36 @@ sandbox:
     env: [HTTPS_PROXY, NO_PROXY] # host variables to forward, by NAME
 ```
 
-| Field     | Default                                       | Meaning                                      |
-| --------- | --------------------------------------------- | -------------------------------------------- |
-| `image`   | `docker.io/library/python:3.14-slim-bookworm` | The base image commands run in               |
-| `build`   | none                                          | A Dockerfile to build instead                |
-| `cpus`    | the host's                                    | Fractional cores                             |
-| `memory`  | the host's                                    | MiB                                          |
-| `network` | `bridge`                                      | `bridge` / `none` / `host`                   |
-| `workdir` | `/workspace`                                  | Mount point and default cwd                  |
-| `timeout` | `120`                                         | Seconds per command                          |
-| `user`    | the image's                                   | uid, name, or `uid:gid`                      |
-| `persist` | `false` — **set it to `true`**                | Keep the container between runs of a session |
-| `env`     | none                                          | Host variables to forward, **names**         |
-
-`env:` takes **names, never values** — a value here would be a secret in the
-repository — and anything credential-shaped (`KEY`, `TOKEN`, `SECRET`,
+| Field     | Default                                       | Meaning                                       |
+| --------- | --------------------------------------------- | --------------------------------------------- |
+| `image`   | `docker.io/library/python:3.14-slim-bookworm` | The base image commands run in                |
+| `build`   | none                                          | A Dockerfile to build instead                 |
+| `cpus`    | the host's                                    | Fractional cores                              |
+| `memory`  | the host's                                    | MiB                                           |
+| `network` | `bridge`                                      | `bridge` / `none` / `host`                    |
+| `workdir` | `/workspace`                                  | Mount point and default cwd                   |
+| `timeout` | `120`                                         | Seconds per command                           |
+| `user`    | the image's                                   | uid, name, or `uid:gid`                       |
+| `persist` | `false` - **set it to `true`**                | Keep the container between runs of a session  |
+| `env`     | none                                          | Host variables to forward, **names**          |
+| `keys`    | `true`                                        | Whether model credentials reach the container |
+
+`env:` takes **names, never values** - a value here would be a secret in the
+repository - and anything credential-shaped (`KEY`, `TOKEN`, `SECRET`,
 `PASSWORD`, `CREDENTIAL`) is refused at load.
 
+**Model credentials are already inside the container** (`keys:`, default
+`true`). Every provider key the run holds is forwarded by name, and a Vertex
+service-account file is bind-mounted read-only at `/run/zenera/keys` with
+`GOOGLE_APPLICATION_CREDENTIALS` rewritten to point there - wherever it sits on
+the host, keyring included. So a `zen` command that embeds (`zen rag … search`)
+works in the sandbox: do not assume otherwise, do not route around it, and
+never copy a key file into the project to "reach" the container. Only
+`keys: false` / `zen run --no-keys` withholds them, and `network: none` is what
+stops the call going out.
+
 **`build:`, when no published image fits.** A project that needs two runtimes,
-or a pinned toolchain, names a Dockerfile instead of an image — `zen init`
+or a pinned toolchain, names a Dockerfile instead of an image - `zen init`
 writes one at `sandbox/Dockerfile` with Python and Node in it:
 
 ```yaml
@@ -802,7 +919,7 @@ sandbox:
         # context: .   # what the build may COPY from; the Dockerfile's folder by default
 ```
 
-`image:` and `build:` cannot both be set — a Dockerfile names its own base in
+`image:` and `build:` cannot both be set - a Dockerfile names its own base in
 its `FROM` line. The tag is a hash of the Dockerfile and its context, so
 editing it produces a new image and, like any other change here, a new
 container. `zen check` builds it and runs a command in it, so a Dockerfile that
@@ -834,12 +951,12 @@ agents:
 
 **Write `persist: true` unless you have a reason not to.** By default the
 container is _removed_ when the session closes, and only two paths survive it:
-`/workspace`, and `/home/agent` — which is `$HOME` inside, backed by the session
+`/workspace`, and `/home/agent` - which is `$HOME` inside, backed by the session
 directory. That covers `pip install --user`, `npm config` and `~/.cache`, but it
 does **not** cover the ordinary thing an agent actually does: `pip install X` or
 `apt-get install X` as root writes to the container's system paths, and those
 are gone on the next `zen run`. The agent then reinstalls, silently, every
-single time — and usually does not realise it has, because the previous run's
+single time - and usually does not realise it has, because the previous run's
 transcript says it succeeded.
 
 ```yaml
@@ -857,7 +974,7 @@ Changing any field renames the container, so bumping the image gets a fresh one
 rather than an old one quietly persisting with the wrong contents. That is also
 the one sharp edge of `persist: true`: a config change abandons the old
 container with whatever was installed in it, so a long-lived setup still belongs
-in `image:` — or in `sandbox/Dockerfile` — rather than in an accumulated rootfs.
+in `image:` - or in `sandbox/Dockerfile` - rather than in an accumulated rootfs.
 
 Granting the group is what makes the project need Podman: `zen run` checks the
 engine before the first turn and exits `5` with an install command if it is
@@ -867,15 +984,15 @@ reference: `docs/agents-yaml.md`.
 **Prompting for them.** Two lines earn their place:
 
 - The workspace is at `/workspace` and is the same directory the file tools
-  see — an edit made with `apply_patch` is what a command will compile, and a
+  see - an edit made with `apply_patch` is what a command will compile, and a
   path from either side works on both.
-- Anything that does not return, returns — use `run_command_background` for a
+- Anything that does not return, returns - use `run_command_background` for a
   server, not `run_command` with a large timeout.
 
 ### 3.8 The web tools (`exa:*`)
 
 The third group `zen run` builds. These reach the live web through
-[Exa](https://exa.ai) — a search index built for models rather than for people,
+[Exa](https://exa.ai) - a search index built for models rather than for people,
 so a query is a sentence describing what is wanted, not a bag of keywords.
 
 | Tool         | What it does                                                                    |
@@ -886,7 +1003,7 @@ so a query is a sentence describing what is wanted, not a bag of keywords.
 
 The three are meant to be used in that order: **search to find, read to quote.**
 An excerpt is enough to judge which source to trust and never enough to cite
-from — `web_search` returns the sentences that made a page match, not the page.
+from - `web_search` returns the sentences that made a page match, not the page.
 `web_answer` runs a search _and_ a model on the other side, so it is the slowest
 and dearest of the three; it earns its cost when the answer is a fact spread
 over several pages, and wastes it when a specific document is wanted.
@@ -903,7 +1020,7 @@ agents:
 
 **The key.** All three read `$EXA_API_KEY` **when they are called**, not when the
 project loads. So a project naming `exa:*` still loads on a machine that has no
-key — the tools simply refuse, on the turn that tried, saying which variable is
+key - the tools simply refuse, on the turn that tried, saying which variable is
 missing. Get a key from <https://dashboard.exa.ai/api-keys> and hold it in
 either place:
 
@@ -922,14 +1039,14 @@ project is still valid, it just cannot search yet.
 | Argument                                   | On           | Why it exists                                                                   |
 | ------------------------------------------ | ------------ | ------------------------------------------------------------------------------- |
 | `num_results`                              | `web_search` | 8 by default, 25 at most                                                        |
-| `include_domains` / `exclude_domains`      | `web_search` | The replacement for `site:` — operators in the query text do not work here      |
+| `include_domains` / `exclude_domains`      | `web_search` | The replacement for `site:` - operators in the query text do not work here      |
 | `start_published_date` / `end_published_…` | `web_search` | ISO 8601. The only reliable way to exclude a stale answer                       |
 | `category`                                 | `web_search` | `company`, `publication`, `news`, `personal site`, `financial report`, `people` |
 | `max_characters`                           | `web_read`   | 4 000 by default, 10 000 at most; `truncated` says when a page was cut          |
 | `max_age_hours`                            | `web_read`   | `0` forces a live crawl. Omit it unless the page changes by the hour            |
 
-Every reply is bounded — pages are cut at the cap and the whole call at 128 KiB
-of text — so one call cannot flood the context. Each carries `cost_usd`, which
+Every reply is bounded - pages are cut at the cap and the whole call at 128 KiB
+of text - so one call cannot flood the context. Each carries `cost_usd`, which
 is what the vendor charged for that call.
 
 A failure is **reported, not raised**: a refused key, an exhausted balance, a
@@ -940,7 +1057,7 @@ did load, so one bad link does not lose the rest.
 **Prompting for them.** Three lines earn their place in any prompt granting this
 group:
 
-- Search with a sentence, not keywords — the query is read by a model.
+- Search with a sentence, not keywords - the query is read by a model.
 - Never quote an excerpt. `web_search` says which page to open; `web_read` says
   what it contains.
 - Say when the web is allowed to override what the model already believes, and
@@ -965,7 +1082,7 @@ zen run --read-only             withhold every tool that can write
 
 The project is read **once, up front**: a missing prompt, an unknown tool name,
 a handoff to nobody all fail before the first call, with the offending key
-named. Flags always win over the file — the repository states intent, the
+named. Flags always win over the file - the repository states intent, the
 invocation overrides it.
 
 A session owns a workspace, a trajectory, memory and whatever the agent wrote,
@@ -980,17 +1097,17 @@ GOOGLE_APPLICATION_CREDENTIALS=./.keys/vertex.json
 EXA_API_KEY=...
 ```
 
-Never commit. Never inline a key into `agents.yaml` — use `${VAR}`. Never print a
+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.
 
 ### 3.11 `assets/`
 
-`assets/` next to `agents.yaml` — or `assets: <path>` — is reference material
+`assets/` next to `agents.yaml` - or `assets: <path>` - is reference material
 every agent can read and none can write. It is mounted at `/assets`: the file
 tools read, list and search it, `run_command` sees it bind-mounted read-only,
 and every tool that would change it refuses.
 
-Put a handbook, a specification, a schema or a style guide there — what agents
+Put a handbook, a specification, a schema or a style guide there - what agents
 consult while working, as opposed to the workspace, which is the work. Do not
 point `assets:` at the project root: that hands every agent the `sessions/`
 directory, every transcript of every run, including the one reading it.
@@ -1006,13 +1123,14 @@ is a different project, not a different key.
 ### 4.1 Composition order
 
 ```
-1. INSTRUCTIONS.md        (shared, once, all agents)
-2. agents/prompts/<n>.md  (this agent)
-3. skill index            (rendered by the runtime — do not hand-write it)
-4. preloaded skills       (activated before the first call)
+1. agents/instructions.md       (shared, once, all agents)
+2. agents/*-instructions.md     (shared too, filename order)
+3. agents/prompts/<n>.md        (this agent)
+4. skill index                  (rendered by the runtime - do not hand-write it)
+5. preloaded skills             (activated before the first call)
 ```
 
-Never duplicate `INSTRUCTIONS.md` content into an agent prompt; never hand-render
+Never duplicate house-rules content into an agent prompt; never hand-render
 a list of skills into a prompt (the runtime does it, and a hand-written one goes
 stale silently).
 
@@ -1022,7 +1140,7 @@ stale silently).
    reference." Not "The agent should be able to look up policies."
 2. **Name things literally.** Tools in backticks by their exact name; agents by
    their exact `name:`. The model matches strings.
-3. **State the boundary and the reason.** "Do not quote coverage rules — you do
+3. **State the boundary and the reason.** "Do not quote coverage rules - you do
    not have them." A prohibition without a reason gets rationalised away.
 4. **Prefer prohibitions that are specific.** "Never say 'approved'" beats "be
    careful about commitments".
@@ -1045,7 +1163,7 @@ stale silently).
 
 Write like a competent colleague briefing a new hire on their first day: short
 sentences, concrete nouns, the reason behind each rule. The model mirrors the
-register it is given — a prompt written in bureaucratic hedging produces
+register it is given - a prompt written in bureaucratic hedging produces
 bureaucratic hedging.
 
 ### 4.4 Debugging a prompt
@@ -1054,8 +1172,8 @@ When behaviour is wrong, in this order:
 
 1. **Read the actual assembled prompt**, not the file. Use the inspect report.
 2. Is the instruction _present_? (Missed skill load, wrong agent, compaction.)
-3. Is it _contradicted_ by `INSTRUCTIONS.md` or a skill? Adjacent contradictions
-   win over distant ones; later text usually wins over earlier.
+3. Is it _contradicted_ by a house-rules file or a skill? Adjacent
+   contradictions win over distant ones; later text usually wins over earlier.
 4. Is it _specific enough to be checkable_? Rewrite as a testable assertion.
 5. Only then consider a stronger model.
 
@@ -1070,15 +1188,15 @@ it forever.
 
 The decision for every piece of knowledge:
 
-| Where               | Cost                    | Use when                                              |
-| ------------------- | ----------------------- | ----------------------------------------------------- |
-| `INSTRUCTIONS.md`   | every call, every agent | true always, for everyone                             |
-| agent prompt        | every call, one agent   | true always, for this job                             |
-| **preloaded skill** | every call, one agent   | always needed, but versioned/shared separately        |
-| **indexed skill**   | one line until loaded   | needed _sometimes_, model can tell when from one line |
-| **searched skill**  | nothing until searched  | catalog too large to index (>~30 entries)             |
-| **tool**            | schema only             | needs live data, exact arithmetic, or a side effect   |
-| **memory**          | recall block when hit   | learned across runs, not authored                     |
+| Where                     | Cost                    | Use when                                              |
+| ------------------------- | ----------------------- | ----------------------------------------------------- |
+| `agents/*instructions.md` | every call, every agent | true always, for everyone                             |
+| agent prompt              | every call, one agent   | true always, for this job                             |
+| **preloaded skill**       | every call, one agent   | always needed, but versioned/shared separately        |
+| **indexed skill**         | one line until loaded   | needed _sometimes_, model can tell when from one line |
+| **searched skill**        | nothing until searched  | catalog too large to index (>~30 entries)             |
+| **tool**                  | schema only             | needs live data, exact arithmetic, or a side effect   |
+| **memory**                | recall block when hit   | learned across runs, not authored                     |
 
 ### 5.2 Skill bindings
 
@@ -1093,28 +1211,28 @@ agents:
           maxIndexEntries: 20 # cap the rendered index
 ```
 
-- **`index`** — names and descriptions rendered into the system prompt. The
+- **`index`** - names and descriptions rendered into the system prompt. The
   default and right answer for most catalogs.
-- **`search`** — no index, only a `skill_search` tool. For catalogs too large to
+- **`search`** - no index, only a `skill_search` tool. For catalogs too large to
   render.
-- **`none`** — preloads only.
-- **`preload`** — for content there is no case for the model to decline: house
+- **`none`** - preloads only.
+- **`preload`** - for content there is no case for the model to decline: house
   tone, a formatting contract. Making it choose is a wasted round trip.
   Preloaded skills are filtered _out_ of the rendered index, and their activation
   lands at the head of the transcript, inside the cached prefix.
-- **`allow`** — how one catalog serves several agents without each seeing all of
+- **`allow`** - how one catalog serves several agents without each seeing all of
   it. A `preload` entry must also be in `allow`.
 
 ### 5.3 Memory
 
 Memory is the read-write twin of skills: written by the run, not authored. It is
-a **graph** — a node is one thing worth keeping, an edge says how one led to
-another — so recall returns the connected piece rather than a ranked list, and a
+a **graph** - a node is one thing worth keeping, an edge says how one led to
+another - so recall returns the connected piece rather than a ranked list, and a
 remembered script arrives with the request that asked for it.
 
 It is configured in `agents.yaml`: a top-level `memory:` block says where the
 graph lives and what vectorises it, and `agents[].memory` says what each agent
-may do with it. It lives with the **project**, not the session — a memory that
+may do with it. It lives with the **project**, not the session - a memory that
 died with the session would be a cache. Recall is automatic on turns that follow
 new user input, which is what makes memory work without the model remembering to
 look.
@@ -1131,25 +1249,58 @@ Every node carries an **audience**, and an agent's `sees` is the set it reads:
 one graph, masked per agent, never one graph each. The four `memory_*` tools are
 derived from `access` and are never listed in `tools:`.
 
+**Memory comes on.** `zen init` writes the block above, `memory: true` on the
+default agent, and the half nobody would guess was part of it:
+`agents/memory-instructions.md`, a copy of the `zen-memory` skill's
+`references/memory-instructions.md`, which the project already holds. Adding
+memory to a project that has none is both of those edits, and a copy that was
+lost or went stale is one command:
+
+```sh
+.github/skills/zen-memory/scripts/check-instructions.sh fix
+```
+
+It is what tells the agent that the store is reached only through the tools, that
+`memory_search` clips a node's text and `memory_load` reads it whole, that a
+remembered file's path comes from `memory_load` and not from listing `/memory`,
+what a node must carry to be worth having, and that a correction is a
+`SUPERSEDES` edge rather than an edit. It is its own file rather than a section of
+`agents/instructions.md` because it arrives with the `memory:` block and leaves
+with it.
+
+**Leave that file as a pure copy.** Anything this project decides for itself -
+which audience holds what, what must never be written down, what an agent is
+expected to commit at the end of a job - goes in
+`agents/memory-policy-instructions.md`. Topic files are read in filename order,
+so the policy lands directly after the rules it qualifies, and the copy stays
+re-runnable: the reference is rewritten by every `zen init` and `zen open`, and
+keeping up with it is then the same one-line command rather than a hand-patch.
+
+`zen check` validates the `memory:` block and says nothing about the rules'
+absence, so this is checked every time, by
+`.github/skills/zen-memory/scripts/check-instructions.sh` and never by reading
+the two files against each other: they drift by trailing whitespace inside a
+table, and the script is what can see that.
+
 Do not treat memory as a database. It is for things learned that should
-persist. Anything authoritative — a rate, a policy clause, a procedure — belongs
+persist. Anything authoritative - a rate, a policy clause, a procedure - belongs
 in a skill, where it is versioned and reviewable.
 
-The full treatment — kinds and relations, how ranking and stitching spend their
+The full treatment - kinds and relations, how ranking and stitching spend their
 budget, remembered files under `/memory`, audience design, and how to put memory
-in front of a `zen rag` index — is in the `zen-memory` skill.
+in front of a `zen rag` index - is in the `zen-memory` skill.
 
 ### 5.4 Cache discipline
 
 Rules that follow directly from "stable prefix = cache hit":
 
-- Do not reorder `agents.yaml` for cosmetic reasons — tool order is prompt order.
-- Do not put timestamps, run ids, or "today is …" in `INSTRUCTIONS.md` or a
+- Do not reorder `agents.yaml` for cosmetic reasons - tool order is prompt order.
+- Do not put timestamps, run ids, or "today is …" in a house-rules file or a
   prompt. A changing prefix is a permanent cache miss. Put volatile facts in a
   tool result.
 - Prefer `preload` over an instruction telling the model to load a skill first.
 - Keep the volatile half of an instruction in the agent prompt and the stable
-  half in `INSTRUCTIONS.md`, not the reverse.
+  half in the house rules, not the reverse.
 
 ---
 
@@ -1169,10 +1320,10 @@ Split into a second agent when at least one is true:
 
 Do **not** split because:
 
-- The prompt got long — split it into skills instead.
-- It feels tidier — every handoff costs a full re-render of the system prompt and
+- The prompt got long - split it into skills instead.
+- It feels tidier - every handoff costs a full re-render of the system prompt and
   a fresh cache prefix.
-- You want "a planner and an executor" with no distinct tools or models — that is
+- You want "a planner and an executor" with no distinct tools or models - that is
   one agent with a numbered procedure.
 
 **Start with one agent. Add the second when a specific case forces it.**
@@ -1181,7 +1332,7 @@ Do **not** split because:
 
 **Router + specialists.** A cheap, fast agent whose only job is classification
 and handoff. Its prompt is short, it holds few tools, and it must be forbidden
-from answering. Every specialist hands back to it — a handoff does not return on
+from answering. Every specialist hands back to it - a handoff does not return on
 its own, so without that edge the first routed question is the last one routed.
 
 ```yaml
@@ -1193,11 +1344,11 @@ agents:
 ```
 
 **Pipeline.** Fixed stages, each handing to the next; only the last answers the
-user. Encode the order in `handoffs:` so a stage cannot skip ahead — and close
+user. Encode the order in `handoffs:` so a stage cannot skip ahead - and close
 the loop, by handing back from the last stage to the first.
 
-**Fan-out / join.** For independent parallel work — ten regions, four review
-lenses, six candidate suppliers — declare `fork:` on the agent that owns the
+**Fan-out / join.** For independent parallel work - ten regions, four review
+lenses, six candidate suppliers - declare `fork:` on the agent that owns the
 work and let the model split it. See §6.4.
 
 **Single agent + rich catalog.** One agent, `discovery: index`, twenty skills.
@@ -1208,11 +1359,11 @@ multi-agent instinct suggests.
 
 - `description:` on the target agent is what the model reads when deciding.
   Write it as a routing condition: _"Applies the written peril policies to a
-  claim and explains the outcome."_ — not _"The adjuster agent."_
+  claim and explains the outcome."_ - not _"The adjuster agent."_
 - Handoffs are bare name strings; there is no per-edge configuration.
 - Self-handoff is a load error.
 - **Every handoff must be returnable.** For every `A → B` there must be a path
-  from `B` back to `A`. Indirect counts — `B → C → A` is a way home — so the
+  from `B` back to `A`. Indirect counts - `B → C → A` is a way home - so the
   rule is that every handoff edge lies on a cycle. `zen check` warns
   (`handoff.one-way`) on any edge that does not.
 - Handoff collapses history by policy: the receiving agent sees a selection, not
@@ -1221,7 +1372,7 @@ multi-agent instinct suggests.
 
 **Why the return edge is not optional.** A handoff is a one-way door: control
 moves and stays moved. Nothing hands it back, so an agent reached by a dead-end
-edge owns the conversation for the rest of the session — the next question,
+edge owns the conversation for the rest of the session - the next question,
 whatever it is about, is answered by the specialist the router sent the user to.
 The drawn architecture holds for one turn and then quietly stops being the
 architecture.
@@ -1234,10 +1385,11 @@ interchangeable:
 - The other agent should **own the conversation from here** → `handoffs:`, and
   something on the far side has to lead back.
 - This agent needs **an answer and then carries on** → `fork:`. Never a handoff:
-  a handoff spends the conversation to get the answer.
+  a handoff spends the conversation to get the answer. One branch is enough -
+  a fork of one is exactly "ask the specialist and continue".
 
 But the return is **condensed**: `A → fork → B` rejoins as one tool result
-holding B's answer, so A never sees the steps B took — no tool calls, no files
+holding B's answer, so A never sees the steps B took - no tool calls, no files
 read, no intermediate reasoning. That is what makes fanning out cheap, and it is
 what to design around: whatever A will need must be _in_ the answer, so say so in
 B's prompt. Work whose value is the trace rather than the conclusion does not
@@ -1262,47 +1414,51 @@ agents:
 | Field         | Default              | Meaning                               |
 | ------------- | -------------------- | ------------------------------------- |
 | `agents`      | every declared agent | Which agents a branch may run         |
-| `maxBranches` | unlimited            | Cap on branches per call; minimum `2` |
+| `maxBranches` | unlimited            | Cap on branches per call; minimum `1` |
 
 The **model** decides the split: it names N branches, each with self-contained
 instructions. They run truly concurrently and rejoin as **one tool call and one
-tool result** in the parent's history — so N branches cost the parent
+tool result** in the parent's history - so N branches cost the parent
 O(N × summary), not O(N × full history).
 
 Rules worth knowing before you write the key:
 
-- `agents:` **may include the forking agent itself** — unlike `handoffs:`, that
+- `agents:` **may include the forking agent itself** - unlike `handoffs:`, that
   is not an error, and one role fanned out over ten items is the common shape.
   The list reaches the model as an `enum`, so a name outside it cannot even be
   decoded.
-- A fork always needs **at least two** branches. A one-branch call is refused
-  with a message telling the model to do the work itself instead.
+- A fork of **one** branch is delegation, and it is valid: one assignment run
+  elsewhere, its conclusion returned, its transcript left out of this
+  conversation. Use it when another agent suits the job better, or when the job
+  would fill the caller's context with material it has no use for afterwards.
 - **Branches cannot talk to each other.** If branch B needs branch A's answer,
-  it is a sequence, not a fork — keep it in one conversation.
+  it is a sequence, not a fork - keep it in one conversation.
 - Nesting is capped by the run's `maxForkDepth` (2 by default), so a branch may
   fork again but not without bound.
 - Fork vs handoff: a handoff is _one_ conversation changing owner; a fork is the
   _same_ question asked N times at once and merged. **A fork returns; a handoff
-  does not** — which is why a handoff needs a return path (§6.3) and a fork
+  does not** - which is why a handoff needs a return path (§6.3) and a fork
   needs nothing.
 
-Choose `context:` deliberately — the model sets it per call, so say in the
+Choose `context:` deliberately - the model sets it per call, so say in the
 agent's prompt which one this work wants:
 
-- `inherit` — branch gets the full prefix. For work that depends on the case.
-- `compact` — prefix minus tool calls, tool results and recalls: _what was
+- `inherit` - branch gets the full prefix. For work that depends on the case.
+- `compact` - prefix minus tool calls, tool results and recalls: _what was
   decided_, not the raw noise. **The default for wide fan-outs.**
-- `none` — system prompt plus instructions only. Cheapest; for independent
+- `none` - system prompt plus instructions only. Cheapest; for independent
   lookups.
 
-Declaring `fork:` only makes the tool available. Say in the agent's prompt when
-to reach for it, in the terms of this domain — _"When the request covers more
-than one region, fork one branch per region and merge their findings"_ — or a
-weaker model will work through the list serially and never call it.
+Declaring `fork:` only makes the tool available. What a fork costs and what
+survives the join is explained to the model by the runtime, in the system prompt
+of every agent holding the key. What is left to you is _when_, in the terms of
+this domain - _"When the request covers more than one region, fork one branch
+per region and merge their findings"_ - or a weaker model will work through the
+list serially and never call it.
 
 ### 6.5 Termination
 
-A turn ends when the model replies with no tool calls — that text is the answer.
+A turn ends when the model replies with no tool calls - that text is the answer.
 There is no turn limit, so an agent that must stop somewhere needs a prompt that
 says where: what "done" looks like, and what to do when it cannot get there.
 
@@ -1315,7 +1471,7 @@ should contain. An agent with no stated finish keeps working the problem.
 
 ### 7.1 Tiers
 
-Think in three tiers, and give them **role names, not vendor names** — so the
+Think in three tiers, and give them **role names, not vendor names** - so the
 mapping changes in one place.
 
 | Alias      | Role                                                        | Reasoning      |
@@ -1379,7 +1535,7 @@ Only the **first** colon separates, so a fine-tuned id must name its provider:
 `openai:ft:gpt-4o:acme::a1b2`.
 
 **Always write the prefix.** The first segment is a provider _name_, not a vendor
-hint — nothing reads `gemini-3.5-flash` and infers Google. An unprefixed id goes
+hint - nothing reads `gemini-3.5-flash` and infers Google. An unprefixed id goes
 to the default provider, which is `openai` unless a top-level `provider:` says
 otherwise, so a bare `gemini-3.5-flash` asks OpenAI for a Google model and fails
 with `OPENAI_API_KEY is not set`. The message names the provider it resolved to;
@@ -1398,26 +1554,26 @@ over one connection.
 
 | Field                   | Applies to                    | Notes                                                                                                      |
 | ----------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `reasoningEffort`       | openai, openrouter            | Free string on purpose — the API is the authority on validity. On openai **needs `api: responses`** — §7.6 |
-| `reasoningSummary`      | openai, openrouter            | `auto` \| `concise` \| `detailed`. On openai **needs `api: responses`** — §7.6                             |
+| `reasoningEffort`       | openai, openrouter            | Free string on purpose - the API is the authority on validity. On openai **needs `api: responses`** - §7.6 |
+| `reasoningSummary`      | openai, openrouter            | `auto` \| `concise` \| `detailed`. On openai **needs `api: responses`** - §7.6                             |
 | `maxTokens`             | anthropic, gemini, openrouter | Cap on **output** tokens, not context. Anthropic requires one (default 8192)                               |
 | `thinkingBudgetTokens`  | anthropic                     | Extended thinking budget                                                                                   |
 | `thinkingBudget`        | gemini 2.5                    | Tokens: `0` off, `-1` auto                                                                                 |
 | `thinkingLevel`         | gemini 3                      | `minimal` \| `low` \| `medium` \| `high`                                                                   |
 | `includeThoughts`       | gemini                        | Thought summaries; default `true`                                                                          |
-| `routing` / `fallbacks` | openrouter                    | Upstream provider preferences, and models to fall back to — §7.5                                           |
+| `routing` / `fallbacks` | openrouter                    | Upstream provider preferences, and models to fall back to - §7.5                                           |
 
 Knobs that do not apply to the chosen vendor are ignored, not rejected.
-`api:` exists only for the OpenAI protocol — naming it on a Gemini or Anthropic
+`api:` exists only for the OpenAI protocol - naming it on a Gemini or Anthropic
 model is an error.
 
 Each vendor's own SDK is used rather than its OpenAI-compatible endpoint, because
 those endpoints drop exactly what this runtime is built on: thinking budgets,
-thought signatures, cache accounting. `openai-compatible` is the shim kind — vLLM,
+thought signatures, cache accounting. `openai-compatible` is the shim kind - vLLM,
 a self-hosted gateway. `openrouter` used to be that shim with its base url
 (`https://openrouter.ai/api/v1`) and key env (`OPENROUTER_API_KEY`) filled in; it
 now has its own SDK, which is what makes provider routing and fallback chains
-available — §7.5.
+available - §7.5.
 
 ### 7.5 OpenRouter
 
@@ -1425,7 +1581,7 @@ A gateway: one key and one endpoint in front of several hundred models from
 every vendor. Useful when a project wants to compare families without holding
 four accounts, and when a cheap tier should be swappable by editing one id.
 
-The whole declaration is the kind — `baseURL` and `OPENROUTER_API_KEY` are its
+The whole declaration is the kind - `baseURL` and `OPENROUTER_API_KEY` are its
 defaults, and built-in kinds are usable as provider names, so a `providers:`
 entry is only worth writing when it adds something:
 
@@ -1435,7 +1591,7 @@ agents:
       model: openrouter:anthropic/claude-sonnet-4.5
 ```
 
-**Model ids** are `vendor/model` and may carry a variant suffix after a colon —
+**Model ids** are `vendor/model` and may carry a variant suffix after a colon -
 `:free`, `:nitro` (throughput-routed), `:floor` (price-routed), `:online` (web
 search). Both survive the shorthand, because only the _first_ colon separates:
 
@@ -1458,7 +1614,7 @@ the destination model understands.
 the upstream provider (OpenRouter's `provider` field, renamed because `provider:`
 already means the connection); `fallbacks` lists other _models_ to try when none
 can serve it (its `models` field). `allowFallbacks`, below, is a third thing
-again — whether the gateway may look past `order`:
+again - whether the gateway may look past `order`:
 
 ```yaml
 models:
@@ -1478,9 +1634,9 @@ there is a load error.
 
 | Key                 | Value                                                                        |
 | ------------------- | ---------------------------------------------------------------------------- |
-| `order`             | Providers to try first — a _preference_, not a restriction                   |
+| `order`             | Providers to try first - a _preference_, not a restriction                   |
 | `only` / `ignore`   | Restrict serving to, or away from, these                                     |
-| `allowFallbacks`    | May the gateway go beyond `order` — **on** unless set `false`                |
+| `allowFallbacks`    | May the gateway go beyond `order` - **on** unless set `false`                |
 | `sort`              | `price`, `throughput`, `latency`, `exacto`                                   |
 | `requireParameters` | Skip a provider that would drop a parameter rather than serve it             |
 | `dataCollection`    | `allow` \| `deny`                                                            |
@@ -1491,12 +1647,12 @@ there is a load error.
 sits alongside `routing`, not inside it.
 
 **A typo in `order` is invisible.** Provider names and `sort` are free strings
-for the same reason `reasoningEffort` is — the gateway's list moves faster than a
-schema would — so nothing local rejects them, and since `allowFallbacks` defaults
+for the same reason `reasoningEffort` is - the gateway's list moves faster than a
+schema would - so nothing local rejects them, and since `allowFallbacks` defaults
 on, an unknown name is skipped and the request quietly succeeds somewhere else.
 What _is_ checked is checked by the API rather than at load: a bad `sort` or
 `quantizations` returns `400 provider.sort: Invalid input`. Use `only`, or
-`allowFallbacks: false`, when the constraint is meant to bind — an unroutable
+`allowFallbacks: false`, when the constraint is meant to bind - an unroutable
 request is then a 404 instead of a silent reroute.
 
 **Attribution** goes in `headers:`; there is no dedicated field because that one
@@ -1527,11 +1683,11 @@ curl -s https://openrouter.ai/api/v1/models | jq -r '
 `supported_parameters` decides whether `tools`, `tool_choice` and
 `reasoning_effort` are honoured. An agent with tools needs `tools` in that list.
 
-**Not modelled yet:** `transforms`, `usage.include`, and per-call cost — the
+**Not modelled yet:** `transforms`, `usage.include`, and per-call cost - the
 gateway reports a price on every response, but it is not surfaced in the token
 accounting. `plugins` exists in code only. Four `provider` fields the SDK accepts
-have no yaml spelling either — `maxPrice`, `preferredMaxLatency`,
-`preferredMinThroughput`, `enforceDistillableText` — and `sort` takes the string
+have no yaml spelling either - `maxPrice`, `preferredMaxLatency`,
+`preferredMinThroughput`, `enforceDistillableText` - and `sort` takes the string
 form only, not the `{ by, partition }` object. `models:` entries are strict, so
 writing any of these is a load error rather than a key that is silently dropped.
 
@@ -1545,27 +1701,27 @@ in place. `timeoutMs` and `headers` behave normally.
 
 Ask two separate questions: does the model **reason**, and does it **say what it
 reasoned**. They are different knobs, and the second is off by default on every
-vendor except Gemini — which is why a reasoning model can burn thousands of
+vendor except Gemini - which is why a reasoning model can burn thousands of
 thinking tokens while the CLI shows no progress at all.
 
-**OpenAI** — reasoning text only exists on the **responses** API, and only as a
+**OpenAI** - reasoning text only exists on the **responses** API, and only as a
 summary. `api: responses` is not optional here, and not only for visibility:
 chat completions is the default, and it **refuses `reasoningEffort` together with
-function tools** — `400 Function tools with reasoning_effort are not supported
+function tools** - `400 Function tools with reasoning_effort are not supported
 for <model> in /v1/chat/completions`. So any OpenAI agent that both reasons and
-holds tools — which is nearly all of them — must name the api.
+holds tools - which is nearly all of them - must name the api.
 
 ```yaml
 models:
     default:
         provider: openai
-        api: responses # required — chat completions refuses tools + reasoning
+        api: responses # required - chat completions refuses tools + reasoning
         model: gpt-5.4-nano
         reasoningEffort: medium # how hard it thinks
         reasoningSummary: auto # whether you get to see it
 ```
 
-**Anthropic** — `thinkingBudgetTokens` turns extended thinking on, and it is spent
+**Anthropic** - `thinkingBudgetTokens` turns extended thinking on, and it is spent
 _out of_ `maxTokens`, so raise that too or the answer has no room left after the
 thinking. The runtime keeps 1024 tokens of headroom whatever you write, so a cap
 below the budget is corrected rather than rejected. Read §7.7 first: this
@@ -1580,7 +1736,7 @@ models:
         thinkingBudgetTokens: 8000
 ```
 
-**Gemini** — thought summaries are on by default (`includeThoughts: true`); what
+**Gemini** - thought summaries are on by default (`includeThoughts: true`); what
 varies is the budget. Gemini 3 takes `thinkingLevel`, Gemini 2.5 takes
 `thinkingBudget` in tokens.
 
@@ -1597,19 +1753,19 @@ running tail above the answer, and the one-shot path prints it under `--live`.
 The full chain is kept in the trajectory either way and is in the inspect report,
 so turning summaries off costs visibility, not the audit trail.
 
-The cost is real — a summary is extra output tokens on every call — so leave it
+The cost is real - a summary is extra output tokens on every call - so leave it
 on where someone is watching and reach for a cheaper tier before turning effort
 up (§7.8).
 
 ### 7.7 Known traps
 
-- **A model id with no provider prefix** — `gemini-3.5-flash` resolves to the
+- **A model id with no provider prefix** - `gemini-3.5-flash` resolves to the
   default provider, not to Google, and the failure reads as a missing OpenAI key.
-  Write `google:gemini-3.5-flash` — §7.3.
-- **OpenAI reasoning without `api: responses`** — chat completions rejects
+  Write `google:gemini-3.5-flash` - §7.3.
+- **OpenAI reasoning without `api: responses`** - chat completions rejects
   `reasoningEffort` alongside function tools with a `400`, and exposes no
-  reasoning summary even without tools — §7.6.
-- **Anthropic + `thinkingBudgetTokens` + multi-turn tool use** — thinking-block
+  reasoning summary even without tools - §7.6.
+- **Anthropic + `thinkingBudgetTokens` + multi-turn tool use** - thinking-block
   signatures are not replayed, and the API rejects the follow-up. Leave extended
   thinking off for tool-using agents.
 - **`reasoningEffort: minimal`** is rejected by the `gpt-5.4-*` family; use `low`.
@@ -1617,16 +1773,16 @@ up (§7.8).
   → the `project_id` inside the key file named by `GOOGLE_APPLICATION_CREDENTIALS`.
   gcloud user credentials and metadata-server credentials carry no project id, so
   those deployments must set the variable.
-- **OpenRouter + a capability the route does not have** — a valid id and a valid
+- **OpenRouter + a capability the route does not have** - a valid id and a valid
   key still fail at the first request (`404 No endpoints found that support image
 input`, or tools quietly unused). This is not a config error and `zen check`
   cannot see it: check the catalog (§7.5). Cheap `:free` tiers are the usual
-  offenders — they are frequently text-only.
+  offenders - they are frequently text-only.
 - **Swapping an OpenRouter id is not a like-for-like change.** Two models behind
   one gateway differ in modalities, tool support and reasoning; re-run the case
   that uses the capability, not just any case.
 - **An `embeddings:` entry on an Anthropic provider** fails at load: that vendor
-  publishes no embeddings API. Point it at another provider — §3.1.1.
+  publishes no embeddings API. Point it at another provider - §3.1.1.
 - **Changing `dimensions:` on an embedding invalidates every stored vector.**
   Widths are not comparable, so anything already indexed has to be re-embedded.
 
@@ -1634,7 +1790,7 @@ input`, or tools quietly unused). This is not a config error and `zen check`
 
 1. Start every agent on `balanced`.
 2. Demote to `router` any agent whose job is classification, extraction, or a
-   fixed handoff — measure, do not guess.
+   fixed handoff - measure, do not guess.
 3. Promote to `careful` only after seeing a concrete failure that a stronger
    model actually fixes.
 4. Never fix an instruction-following bug with a model upgrade (§4.4).
@@ -1650,18 +1806,18 @@ There is no compiler for prose. Substitutes, in order of value:
 1. **`zen check`.** Most structural mistakes are load errors, and this is the
    fastest way to see all of them: it validates `agents.yaml`, checks that every
    prompt, skill and catalog it names is on disk, that hand-offs and tool
-   selectors resolve, and that the models have credentials — without stopping at
+   selectors resolve, and that the models have credentials - without stopping at
    the first problem and without calling anything. `zen check --json` if you are
    parsing it.
 2. **Run the case that motivated the change**, plus one that must _not_ change.
-3. **Read the inspect report** — it shows the assembled prompt, every request and
+3. **Read the inspect report** - it shows the assembled prompt, every request and
    response, tool calls, skill activations and cost. Behaviour questions are
    answered there, not by re-reading the YAML.
 4. **Re-run `zen check` after any rename.** It is what catches the handoff, the
    skill or the prompt path that a rename silently unlinked.
 5. **Watch the token accounting.** A change that doubles prefix size is a
    regression even if the answer improved.
-6. **After changing a model id, exercise the capability it was chosen for** —
+6. **After changing a model id, exercise the capability it was chosen for** -
    send an image, force a tool call, ask for reasoning. `zen check` proves the
    credential resolves, not that the route serves images or honours `tools`; on a
    gateway that gap is a request-time 404 (§7.5).
@@ -1675,13 +1831,13 @@ first thing that looks like a credential problem:
 zen models test <ref>          # one real call, one verdict
 ```
 
-- **refused** — the credential was rejected. `zen key check <provider>`.
-- **blocked** — the credential was _accepted_ and the account said no: an API
+- **refused** - the credential was rejected. `zen key check <provider>`.
+- **blocked** - the credential was _accepted_ and the account said no: an API
   switched off, an empty balance, a model this key was never granted. **Do not
-  rotate the key** — a new one is refused identically. The fix is printed under
+  rotate the key** - a new one is refused identically. The fix is printed under
   the verdict; for a disabled Google API it is the exact `gcloud services
 enable …` line.
-- **no answer** — the network. Try again.
+- **no answer** - the network. Try again.
 
 Either run the printed fix, or take a model that works and put the ref it prints
 into `agents.yaml`:
@@ -1701,6 +1857,16 @@ ok, `1` failed, `2` usage, `3` invalid project, `4` no usable credential.
 
 ## 9. Review checklist
 
+Four of these are decidable, and are one command - `zen check`, the path sweep,
+the memory copy, the spec-sync record, in that order:
+
+```sh
+.github/skills/zen-review/scripts/review.sh
+```
+
+Run it first and read what it says. Everything else below is judgement, which is
+why it is still a list. The `zen-review` skill has the detail.
+
 Before finishing any change here:
 
 **Structure**
@@ -1715,26 +1881,34 @@ Before finishing any change here:
 
 **Prompts**
 
-- [ ] `INSTRUCTIONS.md` carries the shared architecture and nothing agent-specific
-- [ ] Nothing duplicated between `INSTRUCTIONS.md` and an agent prompt
+- [ ] `agents/instructions.md` carries the shared architecture and nothing
+      agent-specific
+- [ ] Nothing duplicated between a house-rules file and an agent prompt
+- [ ] Each `agents/<topic>-instructions.md` is about one capability, and is true
+      of every agent
 - [ ] Every tool and agent referenced by its exact name
 - [ ] Failure paths stated for every instruction that can fail
 - [ ] No facts, rates or figures embedded in a prompt
 - [ ] No hedging, no meta-talk about the runtime
+- [ ] If any agent has `memory:`,
+      `.github/skills/zen-memory/scripts/check-instructions.sh` exits zero -
+      `agents/memory-instructions.md` is the reference byte for byte - and
+      anything project-specific is in `agents/memory-policy-instructions.md` - §5.3
 
-**Paths (§2.5 — run its checklist over the three trees)**
+**Paths (§2.5 - `.github/skills/zen-review/scripts/check-paths.sh` finds the
+candidates; these are the judgements to make about each one)**
 
-- [ ] Every absolute path in `INSTRUCTIONS.md`, `agents/prompts/*.md` and
+- [ ] Every absolute path in `agents/*instructions.md`, `agents/prompts/*.md` and
       `agents/skills/*/SKILL.md` is under `/workspace`, `/assets`, `/skills` or
       `/memory`
-- [ ] No prompt or skill names a project file — `agents.yaml`, a prompt path, a
+- [ ] No prompt or skill names a project file - `agents.yaml`, a prompt path, a
       skill's repository path, `sandbox/Dockerfile`, `.env`, `sessions/`
 - [ ] No `../`, `~`, or host path; nothing assumes the workspace is the project
 - [ ] Every `/assets/…` and `/skills/<name>/…` path names a committed file
 
 **Skills**
 
-- [ ] Every skill is `<name>/SKILL.md` — no bare `<name>.md` in the catalog
+- [ ] Every skill is `<name>/SKILL.md` - no bare `<name>.md` in the catalog
 - [ ] Every skill has a `description` that says _when it is needed_
 - [ ] `preload` is reserved for content the model would never decline
 - [ ] `preload` entries also appear in `allow` where `allow` is used
@@ -1746,11 +1920,11 @@ Before finishing any change here:
 
 - [ ] Every agent holds the narrowest set its job needs
 - [ ] An agent that only reads is not holding `write_file`, `apply_patch`,
-      `move_file` or `delete_file` — subtract them from `workspace:*`
+      `move_file` or `delete_file` - subtract them from `workspace:*`
 - [ ] `sandbox:*` is granted only where a shell is actually needed
 - [ ] `sandbox.persist: true`, unless a throwaway rootfs is wanted on purpose
 - [ ] The `sandbox:` image carries what the work needs, rather than the prompt
-      installing it every run — add it to `sandbox/Dockerfile` if `build:` is used
+      installing it every run - add it to `sandbox/Dockerfile` if `build:` is used
 - [ ] `sandbox.env` lists names only, and nothing credential-shaped
 - [ ] `exa:*` is granted only where the live web is actually needed, and the
       prompt says when to trust it over what the model already believes
@@ -1769,44 +1943,61 @@ Before finishing any change here:
 
 **Secrets**
 
-- [ ] No key literal in YAML, prompt, skill or log — `${VAR}` only
+- [ ] No key literal in YAML, prompt, skill or log - `${VAR}` only
 - [ ] `.env` is git-ignored
 
+**Specification** (only where the project has a `SPECIFICATION.md`)
+
+- [ ] `.github/skills/zen-spec-sync/scripts/snapshot.sh status` does not say
+      `tampered` - the baseline matches its own `manifest.txt`
+- [ ] `.spec-sync/baseline/applied.txt` names the newest file in
+      `.spec-sync/history/`; a baseline ahead of the history is a pass that
+      claimed work it did not finish
+- [ ] The newest history entry's `Still open` is what the next pass will trust,
+      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
+- [ ] `.spec-sync/` is committed and `.tmp/` is not
+
 ---
 
 ## 10. Where to change what
 
 | Symptom                                       | Change this                                                         |
 | --------------------------------------------- | ------------------------------------------------------------------- |
-| Wrong tone, wrong format, wrong length        | `INSTRUCTIONS.md` (all agents) or the agent prompt                  |
-| Says something forbidden                      | `INSTRUCTIONS.md` prohibition, stated specifically                  |
+| Wrong tone, wrong format, wrong length        | The house rules (all agents) or the agent prompt                    |
+| Says something forbidden                      | A house-rules prohibition, stated specifically                      |
 | Ignores a rule that only applies sometimes    | Move the rule into a skill with a sharp description                 |
 | Never loads the skill it should               | The skill's `description`; or `preload` it                          |
 | Loads too much, answers slowly                | `allow:`, `maxIndexEntries:`, or `discovery: search`                |
-| Invents a number                              | A skill holding the figure, or a script that computes it — §3.4.1   |
-| A skill in the catalog is never offered       | It is a bare `<name>.md`; move it to `<name>/SKILL.md` — §3.4       |
-| Cannot find a file its own skill names        | Absolute `/skills/<name>/…` path, and `sandbox:*` — §3.4.1          |
-| Tries to open `agents.yaml` or its own prompt | The prompt names a file no agent can see — §2.5                     |
-| Says a file is missing that is in the project | The workspace is not the project directory — §2.5                   |
-| Rewrites a whole file to change one line      | A prompt line preferring `apply_patch` — §3.6                       |
+| Invents a number                              | A skill holding the figure, or a script that computes it - §3.4.1   |
+| A skill in the catalog is never offered       | It is a bare `<name>.md`; move it to `<name>/SKILL.md` - §3.4       |
+| Cannot find a file its own skill names        | Absolute `/skills/<name>/…` path, and `sandbox:*` - §3.4.1          |
+| Tries to open `agents.yaml` or its own prompt | The prompt names a file no agent can see - §2.5                     |
+| Says a file is missing that is in the project | The workspace is not the project directory - §2.5                   |
+| Rewrites a whole file to change one line      | A prompt line preferring `apply_patch` - §3.6                       |
 | Edits files it should only be reading         | Subtract the mutating tools, or `zen run --read-only`               |
 | Cannot run the build or the tests             | Grant `sandbox:*`; add the toolchain to `sandbox/Dockerfile`        |
-| Installs the same packages on every run       | Put them in `sandbox/Dockerfile`, or `sandbox.persist: true` — §3.7 |
-| Answers from stale knowledge of the world     | Grant `web_search` + `web_read`, and say when — §3.8                |
-| Cites a page it only saw the excerpt of       | A prompt line: `web_read` before quoting — §3.8                     |
-| Every web call refuses                        | No Exa key: `zen key add exa` — `zen check` warns — §3.8            |
-| A model or embedder refuses every call        | `zen models test <ref>` — if `blocked`, `zen models pick` — §8      |
+| Installs the same packages on every run       | Put them in `sandbox/Dockerfile`, or `sandbox.persist: true` - §3.7 |
+| Answers from stale knowledge of the world     | Grant `web_search` + `web_read`, and say when - §3.8                |
+| Cites a page it only saw the excerpt of       | A prompt line: `web_read` before quoting - §3.8                     |
+| Every web call refuses                        | No Exa key: `zen key add exa` - `zen check` warns - §3.8            |
+| A model or embedder refuses every call        | `zen models test <ref>` - if `blocked`, `zen models pick` - §8      |
 | Answers instead of routing                    | Router prompt prohibition; check `handoffs:`                        |
 | Routes to the wrong specialist                | The target agents' `description:` fields                            |
-| Gets stuck in the agent it routed to          | The target needs a handoff back — §6.3                              |
+| Gets stuck in the agent it routed to          | The target needs a handoff back - §6.3                              |
 | Loses a detail after a handoff                | Say it in the handoff; check the collapse policy                    |
-| Works through N independent items serially    | `fork:` on that agent, and a prompt line — §6.4                     |
+| Works through N independent items serially    | `fork:` on that agent, and a prompt line - §6.4                     |
 | Forks when the steps actually depend          | Prompt line: branches cannot see each other                         |
 | Slow and expensive on trivial cases           | Demote that agent's model tier / reasoning effort                   |
 | Fails only on genuinely hard cases            | Promote that agent's tier, or split the hard path out               |
-| Shows no reasoning while it works             | Turn summaries on for that model — §7.6                             |
+| Shows no reasoning while it works             | Turn summaries on for that model - §7.6                             |
 | Forgets across conversations                  | Continue the session rather than starting a new one                 |
-| Breaks at load with a named path              | Read the message — it names the exact key                           |
+| Greps `/memory` or reads `graph.json`         | `agents/memory-instructions.md` is missing the block - §5.3         |
+| Recalls a note it cannot check or continue    | Same block: it is what requires provenance on every node - §5.3     |
+| Breaks at load with a named path              | Read the message - it names the exact key                           |
 
 ---
 
@@ -1815,32 +2006,39 @@ Before finishing any change here:
 - **The mega-prompt.** 300 lines covering twelve scenarios. Split into skills.
 - **Agent sprawl.** Eight agents that share one model, one tool set and one
   prompt style. Collapse into one with a catalog.
-- **Facts in prompts.** A fee schedule inside `INSTRUCTIONS.md`. It cannot be
-  versioned, cannot be shared, and is paid for on every call.
+- **Facts in prompts.** A fee schedule inside `agents/instructions.md`. It cannot
+  be versioned, cannot be shared, and is paid for on every call.
 - **The bare skill file.** `agents/skills/<name>.md` instead of a folder. It can
-  never grow the table or script the next revision of the rule will want — §3.4.
+  never grow the table or script the next revision of the rule will want - §3.4.
 - **Pointing an agent at the project.** A prompt or skill naming `agents.yaml`,
-  `INSTRUCTIONS.md`, `agents/skills/<name>/…` or `sandbox/Dockerfile`. None of
-  them are on any path the agent can open, so the instruction fails on the turn
-  that follows it — §2.5.
+  `agents/instructions.md`, `agents/skills/<name>/…` or `sandbox/Dockerfile`.
+  None of them are on any path the agent can open, so the instruction fails on
+  the turn that follows it - §2.5.
 - **Arithmetic in prose.** A skill that walks the model through a calculation it
-  will get wrong, in a folder that could have held the script — §3.4.1.
+  will get wrong, in a folder that could have held the script - §3.4.1.
+- **The unguarded store.** `memory:` turned on and the skill's
+  `references/memory-instructions.md` never copied to
+  `agents/memory-instructions.md`, so nothing tells the agent the store is
+  reached only through the tools - and `zen check` passes throughout - §5.3.
+- **Reviewing a capability without its skill.** A project whose memory, index or
+  sandbox was configured by an earlier pass looks finished because it loads. The
+  obligations are in the editor skill, not in `agents.yaml` - §0.1.
 - **Politeness padding.** "Please try your best to be helpful." Costs tokens,
   changes nothing.
 - **Commented implementation notes.** `agents.yaml` explaining how skill
-  discovery or prompt caching works. That is this file's job — §3.1.
+  discovery or prompt caching works. That is this file's job - §3.1.
 - **Fixing prompts with models.** See §4.4.
 - **The chatty router.** A router that answers before handing off, because its
   prompt never forbade it.
 - **The one-way handoff.** A specialist with no way back, so the router routes
-  once and then never sees the conversation again — §6.3.
+  once and then never sees the conversation again - §6.3.
 - **Handing off for an answer.** Wanting one lookup and spending the whole
-  conversation on it. That is a `fork:`, which returns by itself — §6.4.
+  conversation on it. That is a `fork:`, which returns by itself - §6.4.
 - **Forking a chain.** Branches never see each other, so a fork whose second
   branch needs the first branch's answer is a sequence wearing a fork's clothes.
 - **Installing the toolchain every run.** A prompt that begins with `apt-get
-install` is an `image:` that was never set — §3.7.
-- **Volatile prefix.** "Current date: …" in `INSTRUCTIONS.md`. Permanent cache
+install` is an `image:` that was never set - §3.7.
+- **Volatile prefix.** "Current date: …" in the house rules. Permanent cache
   miss.
 
 ---
@@ -1849,16 +2047,18 @@ install` is an `image:` that was never set — §3.7.
 
 This file is loaded on every request in this repository, so it is subject to its
 own rules: stable, factual, no hedging. Before adding a section, ask whether it
-is true of every task — if it is not, it is a skill under `.github/skills/`, or
+is true of every task - if it is not, it is a skill under `.github/skills/`, or
 a prompt file under `.github/prompts/` if it is a procedure (§2.4).
 
 Update it when:
 
 - the layout changes (a new directory, a moved catalog)
-- a model alias is added, retired or repointed — §7.2 must match `agents.yaml`
-- a vendor trap is discovered — add it to §7.7
-- a recurring review comment appears twice — turn it into a checklist line in §9
-- a runtime capability is added — describe it here, or it will not be used
+- a model alias is added, retired or repointed - §7.2 must match `agents.yaml`
+- a vendor trap is discovered - add it to §7.7
+- a recurring review comment appears twice - turn it into a checklist line in §9
+- a runtime capability is added - describe it here, or it will not be used
+- an editor skill starts requiring a block in the target project - name the
+  requirement in §0.1 and the check for it in §9, or it will be missed
 
 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.