@zenera/cli 1.1.19 → 1.1.21

package/dist/validate.js

@@ -1,5 +1,5 @@
-import { EXA_GROUP, FileSkillProvider, SANDBOX_MOUNT, Sandbox, exaTools, projectRegistry, readProjectConfig, sandboxTools, selectTools, workspaceTools, } from '@zenera/neo';
-import { existsSync, mkdtempSync, readdirSync, realpathSync, rmSync, statSync } from 'node:fs';
+import { EXA_GROUP, FileSkillProvider, SANDBOX_MOUNT, Sandbox, exaTools, frontmatter, projectRegistry, readProjectConfig, sandboxTools, selectTools, toList, workspaceTools, } from '@zenera/neo';
+import { existsSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { auditModels, credentialFor } from "./audit.js";
@@ -7,6 +7,7 @@ import { resolveBuild } from "./image.js";
 import { SHAPES, envNames, form } from "./keys.js";
 import { probeModels } from "./liveness.js";
 import { BuildError, ensurePodmanReady } from "./podman.js";
+import { staleShared } from "./scaffold.js";
 // Mirrors the loader's own constants (`packages/neo/src/project/load.ts`).
 // Duplicated rather than exported, because a check that agreed with the loader
 // by construction could not report that the two had diverged.
@@ -14,23 +15,39 @@ const CONFIG_NAMES = ['agents.yaml', 'agents.yml', 'agents/agents.yaml', 'agents
 const AGENTS_DIR = 'agents';
 const HOUSE_RULES = 'agents/instructions.md';
 const INSTRUCTIONS_SUFFIX = '-instructions.md';
+/** The only place memory is explained to a model; the runtime composes none of it. */
+const MEMORY_RULES = 'agents/memory-instructions.md';
+/** The only place forking is explained to a model; the same holds. */
+const FORK_RULES = 'agents/fork-instructions.md';
+/** The conditioned documents `zen` ships, which land whether or not they apply. */
+const OURS = new Set([MEMORY_RULES, FORK_RULES]);
 const PROMPTS_DIR = 'agents/prompts';
 const SKILLS_DIR = 'agents/skills';
 const SKILL_FILE = 'SKILL.md';
 const ASSETS_DIR = 'assets';
 /** What `allow:` and `preload:` accept, so a skill outside it cannot be named. */
 const REFERABLE = /^[a-z0-9]+(?:[-_][a-z0-9]+)*$/;
+/** What `requires:` may name. Mirrors `CAPABILITIES` in the loader. */
+const CAPABILITIES = {
+    fork: (spec) => Boolean(spec.fork),
+    memory: (spec) => Boolean(spec.memory),
+    'memory-write': (spec) => spec.memory?.access === 'read-write' || spec.memory?.access === 'full',
+    'memory-forget': (spec) => spec.memory?.access === 'full',
+};
 /**
  * Mirrors `readHouseRules` in the loader, in the same order:
  * `agents/instructions.md`, then every `agents/<topic>-instructions.md` by
- * filename.
+ * filename — each with the `requires:` its frontmatter declared.
  */
 function houseRules(root) {
     const found = [];
     const take = (rel) => {
-        if (existsSync(join(root, rel))) {
-            found.push(rel);
+        const path = join(root, rel);
+        if (!existsSync(path)) {
+            return;
         }
+        const { data } = frontmatter(readFileSync(path, 'utf8'));
+        found.push({ rel, requires: toList(data.requires) });
     };
     take(HOUSE_RULES);
     const dir = join(root, AGENTS_DIR);
@@ -46,6 +63,15 @@ function houseRules(root) {
     }
     return found;
 }
+/**
+ * The documents this agent's prompt actually gets. Unknown capabilities are
+ * reported once, against the file, rather than silently excluding every agent.
+ */
+function rulesFor(rules, spec) {
+    return rules
+        .filter((r) => r.requires.every((cap) => CAPABILITIES[cap]?.(spec) ?? true))
+        .map((r) => r.rel);
+}
 export async function validateProject(opts) {
     const root = resolve(opts.dir);
     const findings = [];
@@ -169,7 +195,7 @@ export async function validateProject(opts) {
     // Files the config and the conventions name
     // -----------------------------------------------------------------------
     const rules = houseRules(root);
-    for (const rel of rules) {
+    for (const { rel, requires } of rules) {
         record(rel, 'house rules — prepended to every agent prompt', 'file', false);
         if (empty(join(root, rel))) {
             add({
@@ -180,6 +206,31 @@ export async function validateProject(opts) {
                 fix: 'write the rules that hold whichever agent is answering, or delete it',
             });
         }
+        for (const cap of requires) {
+            if (!(cap in CAPABILITIES)) {
+                add({
+                    severity: 'error',
+                    code: 'rules.requires.unknown',
+                    where: rel,
+                    message: `\`requires: ${cap}\` names no capability, so the loader refuses the ` +
+                        'project',
+                    fix: `use one of: ${Object.keys(CAPABILITIES).join(', ')}`,
+                });
+            }
+        }
+        // Ours are copied into every project whether or not it uses the
+        // capability, so an inert one says nothing about the project. One the
+        // project wrote is different: it was written to be read.
+        const reached = config.agents.some((a) => rulesFor([{ rel, requires }], a).length > 0);
+        if (requires.length && !reached && !OURS.has(rel)) {
+            add({
+                severity: 'note',
+                code: 'rules.unreached',
+                where: rel,
+                message: `no agent has ${requires.join(' and ')}, so this document reaches no prompt`,
+                fix: 'relax `requires:`, or give an agent the capability it is written for',
+            });
+        }
     }
     if (rules.length === 0) {
         record(HOUSE_RULES, 'house rules — prepended to every agent prompt', 'file', false);
@@ -191,6 +242,61 @@ export async function validateProject(opts) {
                 'prompt alone, with nothing shared between them',
         });
     }
+    // The runtime composes the preference block and nothing else, so this file
+    // is the whole of what an agent is told about memory. Without it the tools
+    // are still granted and still callable, with only their schemas to go on -
+    // which is not a project that works less well, it is one that will write
+    // the graph wrong and cannot be told otherwise.
+    if (config.agents.some((a) => a.memory) || config.memory) {
+        const path = join(root, MEMORY_RULES);
+        if (!existsSync(path) || empty(path)) {
+            add({
+                severity: 'error',
+                code: 'memory.uninstructed',
+                where: MEMORY_RULES,
+                message: 'memory is on, but nothing tells an agent how to use it — the memory_* ' +
+                    'tools are granted with only their schemas to explain them',
+                fix: 'zen check --fix, which writes the current rules back',
+            });
+        }
+    }
+    // The same again for forking, and for the same reason: the runtime used to
+    // compose this block and no longer does, so the file is the whole of what
+    // an agent is told about what survives a join.
+    if (config.agents.some((a) => a.fork)) {
+        const path = join(root, FORK_RULES);
+        if (!existsSync(path) || empty(path)) {
+            add({
+                severity: 'error',
+                code: 'fork.uninstructed',
+                where: FORK_RULES,
+                message: 'an agent can fork, but nothing tells it what a branch can and cannot do — ' +
+                    'the fork tool is granted with only its schema to explain it',
+                fix: 'zen check --fix, which writes the current rules back',
+            });
+        }
+    }
+    // Present is not the same as current. These three files are copies of ours
+    // and nobody is meant to be maintaining them, so bytes that differ are an
+    // older `zen`'s — prose about a runtime that has since moved, which reads
+    // exactly as authoritative as the version that is true. The frontmatter
+    // that conditions them arrived this way: every project scaffolded before it
+    // carries a copy that reaches every agent, memory or no memory.
+    for (const rel of staleShared(root)) {
+        // An empty one is already reported, as missing or as empty.
+        if (empty(join(root, rel))) {
+            continue;
+        }
+        add({
+            severity: 'warning',
+            code: 'rules.stale',
+            where: rel,
+            message: `${rel} is not the copy this \`zen\` ships — it came from an older version, ` +
+                'or was edited in place, and either way it describes behaviour that may no ' +
+                'longer be the behaviour',
+            fix: 'zen check --fix, which replaces it; rules of your own belong in a topic file beside it',
+        });
+    }
     // -----------------------------------------------------------------------
     // Agents
     // -----------------------------------------------------------------------
@@ -211,7 +317,7 @@ export async function validateProject(opts) {
     // against the real set rather than a list written down twice.
     const available = availableTools(root, config);
     for (const spec of config.agents) {
-        agents.push(checkAgent(root, config, spec, entry, available, record, add));
+        agents.push(checkAgent(root, config, spec, entry, available, rules, record, add));
     }
     checkReturnPaths(config, add);
     // -----------------------------------------------------------------------
@@ -430,9 +536,9 @@ export function availableTools(root, config) {
         ...exaTools(),
     ];
 }
-function checkAgent(root, config, spec, entry, available, record, add) {
+function checkAgent(root, config, spec, entry, available, rules, record, add) {
     const where = `agents.${spec.name}`;
-    const instructions = [...houseRules(root)];
+    const instructions = rulesFor(rules, spec);
     // The role prompt: named by `system:`, or found by convention. A named one
     // that is not there is an error — the loader says so too. An absent
     // conventional one is not, because a project may keep everything it has to

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.19",
+    "version": "1.1.21",
     "description": "Command-line front end for @zenera/neo: agentic projects you can run, share and commit.",
     "keywords": [
         "agents",
@@ -51,7 +51,7 @@
         "@inkjs/ui": "^2.0.0",
         "ink": "^7.1.1",
         "react": "^19.2.8",
-        "@zenera/neo": "^1.1.19",
+        "@zenera/neo": "^1.1.21",
         "@anthropic-ai/sdk": "^0.120.0",
         "@google/genai": "^2.18.0",
         "@openrouter/sdk": "^1.2.80",

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

@@ -222,7 +222,8 @@ my-project/
 ├── 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`
+│   ├── fork-instructions.md       more of them - any `<topic>-instructions.md`
+│   ├── memory-instructions.md     and more - how the graph is used
 │   ├── tools-instructions.md      and more - how tools are called
 │   ├── prompts/
 │   │   ├── intake.md             one agent's own brief
@@ -588,6 +589,21 @@ 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.
 
+A document about one capability can say so in frontmatter, and then reaches only
+the agents that have it:
+
+```markdown
+---
+requires: [fork]
+---
+```
+
+All of the list has to hold. The vocabulary is closed - `fork`, `memory`,
+`memory-write`, `memory-forget` - and anything else is a load error. There is no
+`not`: a rule for agents _without_ a capability is a rule about the rest of the
+project, which is what `agents/instructions.md` is for. No frontmatter means
+unconditional, which is the usual case.
+
 Put in them only what is true for **every** agent:
 
 - identity and domain ("You work the property claims desk")
@@ -1299,7 +1315,8 @@ 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.
+with it - and it carries `requires: [memory]`, so an agent without the store
+never reads a word of 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
@@ -1483,11 +1500,15 @@ agent's prompt which one this work wants:
   lookups.
 
 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.
+survives the join is in `agents/fork-instructions.md`, which carries
+`requires: [fork]` and so reaches exactly the agents holding the key. That file
+is `zen`'s, not yours - `zen check --fix` replaces it, editing it or carrying an
+older copy is reported as `rules.stale`, and deleting it leaves your forking
+agents with the tool schema alone (`fork.uninstructed`). 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. Project
+policy on forking goes in a topic file of your own beside it.
 
 ### 6.5 Termination
 
@@ -1918,7 +1939,10 @@ Before finishing any change here:
       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
+      of every agent it reaches - `requires:` if it is about one of them
+- [ ] If any agent has `fork:`, `agents/fork-instructions.md` is present - §6.4
+- [ ] No `rules.stale`: the three files that are `zen`'s rather than yours say
+      what this version of the runtime does, and `zen check --fix` replaces them
 - [ ] 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
@@ -2031,6 +2055,7 @@ candidates; these are the judgements to make about each one)**
 | 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                     |
 | Forks when the steps actually depend          | Prompt line: branches cannot see each other                         |
+| Forks a sequence, or loses a branch's working | `agents/fork-instructions.md` is missing or empty - §6.4            |
 | 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                             |

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

@@ -21,7 +21,8 @@ What it writes:
 zenera.json                     { version, name }
 agents.yaml                     the configuration
 agents/instructions.md          house rules, prepended to every agent
-agents/memory-instructions.md   more of them, about the memory store
+agents/fork-instructions.md     more of them, for agents that can fork
+agents/memory-instructions.md   more of them, for agents with the memory store
 agents/tools-instructions.md    more of them, about how tools are called
 agents/prompts/default.md       the default agent's prompt
 agents/skills/                  empty, for skills
@@ -31,13 +32,16 @@ sessions/                       empty
 .env                            this project's environment, git-ignored
 .gitignore
 .vscode/settings.json           editor files
+.vscode/agents.schema.json      what validates agents.yaml as you type it
 .github/                        copilot instructions, prompts, this skill
 ```
 
 More house rules can be added by hand: any `agents/<topic>-instructions.md` is
-read too, in filename order, and prepended to every agent. A capability that
-needs standing rules - memory, say - gets its own file rather than another
-section of `agents/instructions.md`. Memory's are not written from scratch:
+read too, in filename order, and prepended to every agent - or, with
+`requires: [<capability>]` in its frontmatter, to every agent that has the
+capability it is about. A capability that needs standing rules - memory, say -
+gets its own file rather than another section of `agents/instructions.md`.
+Memory's are not written from scratch:
 `agents/memory-instructions.md` is the same file as
 `.github/skills/zen-memory/references/memory-instructions.md`, which init puts
 in the project as well, so a copy that was lost or went stale is restored rather
@@ -46,9 +50,16 @@ which of the two it is, and `… fix` does the copy.
 
 The project's own files are never overwritten - `--force` is what allows
 writing into an occupied directory, and the files already there stay. The
-editor files are the exception: `.vscode/settings.json` and the `.github/` tree
-are ours and are replaced on every `init` and every `zen open`, so edits to them
-do not survive.
+editor files are the exception: `.vscode/` and the `.github/` tree are ours and
+are replaced on every `init` and every `zen open`, so edits to them do not
+survive.
+
+`.vscode/agents.schema.json` describes `agents.yaml` to the editor, so an
+unknown key is underlined where it is typed and every key carries its
+documentation on hover. It needs the `redhat.vscode-yaml` extension, which
+`.vscode/extensions.json` recommends. It is an editor aid and nothing else: it
+is rewritten from the version of `zen` in hand, and `zen check` is still what
+says whether a project loads.
 
 The default agent gets the file tools and a sandboxed shell, plus `exa:*` when
 the keyring holds an Exa key. It also gets memory: the store is scaffolded in
@@ -102,7 +113,7 @@ The editor is chosen in this order: `--editor`, `$ZENERA_EDITOR`, the editor
 this terminal belongs to, `$VISUAL` or `$EDITOR`, a known editor on `PATH` or
 installed, then the platform opener.
 
-Opening refreshes the editor files (`.vscode/settings.json` and the `.github/`
+Opening refreshes the editor files (`.vscode/` and the `.github/`
 tree) in the directory being opened. VS Code and its forks are launched with
 `--disable-workspace-trust`, so the settings written there apply to the new
 window immediately rather than after a prompt.

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

@@ -1,6 +1,6 @@
 ---
 name: zen-memory
-description: How agent memory is organised and how to configure it in `agents.yaml` - the `memory:` block, per-agent `access`/`sees`/`writes`/`autoRecall`, the four `memory_*` tools, kinds and relations, how recall ranks and stitches a subgraph, and how to design a memory strategy for a project. Includes the usage rules every memory-enabled project must carry in `agents/memory-instructions.md` (references/memory-instructions.md) and the script that says whether that copy is still current (scripts/check-instructions.sh), what to commit and what never to, how to keep a working file under `/memory` and re-run it later, and how to put memory in front of a `zen rag schema` or `zen rag docs` index so a search that already succeeded once is not paid for again.
+description: How agent memory is organised and how to configure it in `agents.yaml` - the `memory:` block, per-agent `access`/`sees`/`writes`/`autoRecall`, the four `memory_*` tools, kinds and relations, how recall ranks and stitches a subgraph, and how to design a memory strategy for a project. Includes the default usage rules every memory-enabled project must carry in `agents/memory-instructions.md` (references/memory-instructions.md), the script that says whether that copy is still current (scripts/check-instructions.sh), where a project's own customisations go instead (`agents/memory-policy-instructions.md`, under `requires: [memory]`), what to commit and what never to, how to keep a working file under `/memory` and re-run it later, and how to put memory in front of a `zen rag schema` or `zen rag docs` index so a search that already succeeded once is not paid for again.
 ---
 
 # Memory
@@ -112,10 +112,14 @@ asked for; counting that as use would poison recency ranking. Commit is one
 call because a remembered thing is a subgraph, and building it with three calls
 leaves the graph half-formed when the model stops early.
 
-The system prompt already explains all of this to the agent - how to read a
-recollection, when committing is worthwhile, why correction is a new node. That
-text is **derived from `access`**, so an agent that cannot write is never told
-how to. Do not restate it in a prompt; state project-specific policy instead.
+`agents/memory-instructions.md` already explains all of this to the agent - how
+to read a recollection, when committing is worthwhile, why correction is a new
+node. It is house rules under `requires: [memory]`, so it reaches exactly the
+agents that have the store and no others, and it gates its own advice on the
+tools the reader actually holds. The runtime adds the preference block and
+nothing else. Do not restate any of it in a prompt; state project-specific
+policy instead, and keep the copy byte-identical to the reference so
+`check-instructions.sh` stays meaningful.
 
 ## How it is organised
 
@@ -328,6 +332,13 @@ Commit one only when the user's own words generalise: "always", "from now on",
 instruction, and a graph full of false preferences is a system prompt nobody
 wrote.
 
+What the user states about themselves is the same kind of node, for the same
+reason - the name to address them by, their role, their timezone, which of
+several environments is theirs. Asking again next run is exactly what the block
+exists to prevent. Credentials and secrets are not preferences, however they
+were offered; `agents/memory-policy-instructions.md` is where a project says so
+in its own terms.
+
 ## Remembering files, and running them again
 
 The workspace is disposable - it may be a container about to be discarded - so a
@@ -501,8 +512,8 @@ An index used by a project needs a skill in that project describing it - see
 index** belongs in that skill, because it is the same subject and it is read at
 the moment the index is. Policy that holds whatever the agent is doing -
 audiences, what must never be written down - goes in
-`agents/memory-policy-instructions.md` instead, which every agent gets whether
-it loads the skill or not.
+`agents/memory-policy-instructions.md` instead, which every agent with the store
+gets whether it loads the skill or not.
 
 ```md
 - Recalled routes are a shortcut, not authority. Confirm with `list_api --name`
@@ -559,11 +570,42 @@ prepended to every agent, in filename order, so this belongs in its own document
 rather than as another section of `agents/instructions.md` - it arrives with
 memory and it leaves with it.
 
-**Keep that file a pure copy.** Project-specific policy - audiences, what must
-never be written down, what an agent commits at the end of a job - goes in
-`agents/memory-policy-instructions.md`, which filename order puts directly after
-it. Then keeping up with a changed reference is the same one command again,
-rather than a hand-patch around prose that has to be preserved.
+### Two files, and which is which
+
+| File                                   | Is                                                                 | Owned by    |
+| -------------------------------------- | ------------------------------------------------------------------ | ----------- |
+| `agents/memory-instructions.md`        | the DEFAULT rules - how the store works, and how any agent uses it | this skill  |
+| `agents/memory-policy-instructions.md` | this PROJECT's customisations on top of them                       | the project |
+
+**Keep the first a pure copy.** It is predefined: it describes this version of
+the runtime, not this project, and `check-instructions.sh` compares it byte for
+byte. Anything edited into it is lost the next time the reference changes.
+
+Everything a project decides for itself goes in the second - audiences, what
+must never be written down, what an agent commits at the end of a job, which
+index a recalled route is checked against. Filename order puts it directly
+after the defaults, so it reads as the exceptions to them. Then keeping up with
+a changed reference is the same one command again, rather than a hand-patch
+around prose that has to be preserved.
+
+**It must open with the same frontmatter**, or it is prepended to every agent in
+the project, including the ones with no store to apply it to:
+
+```md
+---
+requires: [memory]
+---
+
+# Memory policy
+
+- Never commit a customer name or an account id; a `fact` says which tenant
+  shape it was, never whose.
+- ...
+```
+
+`requires: [memory]` is what delivers a topic file on the capability it is
+about. Use `requires: [memory, memory-write]` for a rule only a committing agent
+can act on.
 
 ## Inspecting and repairing it
 
@@ -635,7 +677,8 @@ agents:
 
 - [ ] `.github/skills/zen-memory/scripts/check-instructions.sh` exits zero, so
       `agents/memory-instructions.md` is the reference byte for byte - and
-      project policy lives in `agents/memory-policy-instructions.md`.
+      project policy lives in `agents/memory-policy-instructions.md`, opening
+      with `requires: [memory]`.
 - [ ] `memory.embedding` is set, and was set before the graph had content.
 - [ ] Every agent that should learn has a `memory:` binding - the top-level
       block alone enables nothing.
@@ -653,23 +696,24 @@ agents:
 
 ## When it goes wrong
 
-| Symptom                                             | Cause                                                                                                      |
-| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| The `memory_*` tools are missing                    | No `memory:` on the agent. They come from the binding, never from `tools:`                                 |
-| `zen memory` says the project has none              | Neither a `memory:` block nor an agent binding - nothing is opened and no directory is made                |
-| Recall finds a memory only when reworded            | No embedder. `zen memory stats` says `embedding none`                                                      |
-| Recall finds nothing after changing the embedder    | Refused rather than mixed - a manifest records the model. Change it back, or start a new memory            |
-| Vectors fewer than nodes                            | Some nodes were committed with no embedder; they are only reachable by term overlap                        |
-| The graph fills with restated requests              | The commit rule is not in a prompt or skill. State the "would a later run redo this" test                  |
-| An agent greps `/memory` or reads `graph.json`      | The house-rules block is missing from `agents/memory-instructions.md` - the system prompt never forbids it |
-| A recalled fact cannot be checked or continued      | Nodes were committed with no provenance. The block's "say where it came from" rule is what prevents it     |
-| Recall returns pointers and the run re-reads it all | Content was committed as `text` alone. A node's text describes and locates; the content belongs in a file  |
-| A wrong memory keeps coming back                    | It was edited instead of superseded, or superseded in the wrong direction - the **new** node is the source |
-| An agent cannot see a node you can                  | Its `audience` is not in that agent's `sees`. Invisible and missing are the same thing, on purpose         |
-| "this agent cannot remember files"                  | The agent has no workspace, so a path cannot be resolved. Commit without `file`                            |
-| `error: outside the workspace: /tmp/…`              | The file is real to the shell and outside the only tree memory reads. Write it under `/workspace`          |
-| Long content arrives as `text`, never as a `file`   | The agent has no tool that writes to the workspace, so it has no path to name                              |
-| A remembered file will not run                      | It is not self-contained - it referenced the workspace it was written in                                   |
-| Recollections are large and unhelpful               | `autoRecall.limit` is too high, or node texts describe answers rather than questions                       |
-| The model recalls a route the API no longer has     | Nothing re-checks memory against a rebuilt index. Supersede, and require verification                      |
-| A second run of the same project refuses to start   | The directory lock. A lock whose process is gone is stale and is taken over                                |
+| Symptom                                             | Cause                                                                                                                           |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| The `memory_*` tools are missing                    | No `memory:` on the agent. They come from the binding, never from `tools:`                                                      |
+| `zen memory` says the project has none              | Neither a `memory:` block nor an agent binding - nothing is opened and no directory is made                                     |
+| Recall finds a memory only when reworded            | No embedder. `zen memory stats` says `embedding none`                                                                           |
+| Recall finds nothing after changing the embedder    | Refused rather than mixed - a manifest records the model. Change it back, or start a new memory                                 |
+| Vectors fewer than nodes                            | Some nodes were committed with no embedder; they are only reachable by term overlap                                             |
+| The graph fills with restated requests              | The commit rule is not in a prompt or skill. State the "would a later run redo this" test                                       |
+| Runs do real work and the graph stays empty         | The agent is bound `read`, or nothing names the moments: empty recall then work, before an answer, a handoff or a fork's return |
+| An agent greps `/memory` or reads `graph.json`      | The house-rules block is missing from `agents/memory-instructions.md` - the system prompt never forbids it                      |
+| A recalled fact cannot be checked or continued      | Nodes were committed with no provenance. The block's "say where it came from" rule is what prevents it                          |
+| Recall returns pointers and the run re-reads it all | Content was committed as `text` alone. A node's text describes and locates; the content belongs in a file                       |
+| A wrong memory keeps coming back                    | It was edited instead of superseded, or superseded in the wrong direction - the **new** node is the source                      |
+| An agent cannot see a node you can                  | Its `audience` is not in that agent's `sees`. Invisible and missing are the same thing, on purpose                              |
+| "this agent cannot remember files"                  | The agent has no workspace, so a path cannot be resolved. Commit without `file`                                                 |
+| `error: outside the workspace: /tmp/…`              | The file is real to the shell and outside the only tree memory reads. Write it under `/workspace`                               |
+| Long content arrives as `text`, never as a `file`   | The agent has no tool that writes to the workspace, so it has no path to name                                                   |
+| A remembered file will not run                      | It is not self-contained - it referenced the workspace it was written in                                                        |
+| Recollections are large and unhelpful               | `autoRecall.limit` is too high, or node texts describe answers rather than questions                                            |
+| The model recalls a route the API no longer has     | Nothing re-checks memory against a rebuilt index. Supersede, and require verification                                           |
+| A second run of the same project refuses to start   | The directory lock. A lock whose process is gone is stale and is taken over                                                     |

package/templates/editor/.github/skills/zen-memory/scripts/check-instructions.sh

@@ -101,7 +101,8 @@ show_diff() {
 fix() {
     cp "$REFERENCE" "$COPY"
     echo "wrote: $COPY"
-    echo "note: project policy belongs in agents/memory-policy-instructions.md"
+    echo "note: project policy belongs in agents/memory-policy-instructions.md,"
+    echo "      which must open with '---' / 'requires: [memory]' / '---'"
 }
 
 case "${1:-status}" in