@zenera/cli 1.1.16 → 1.1.18

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

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

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

@@ -19,18 +19,30 @@ What it writes:
 
 ```
 zenera.json                     { version, name }
-INSTRUCTIONS.md                 house rules
 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/prompts/default.md       the default agent's prompt
 agents/skills/                  empty, for skills
 assets/README.md
 sandbox/Dockerfile              the image the sandbox builds
 sessions/                       empty
+.env                            this project's environment, git-ignored
 .gitignore
 .vscode/settings.json           editor files
 .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:
+`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
+than rewritten - `.github/skills/zen-memory/scripts/check-instructions.sh` says
+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
@@ -38,7 +50,12 @@ are ours and are replaced on every `init` and every `zen open`, so edits to them
 do not survive.
 
 The default agent gets the file tools and a sandboxed shell, plus `exa:*` when
-the keyring holds an Exa key.
+the keyring holds an Exa key. It also gets memory: the store is scaffolded in
+`memory/`, the agent is bound to it with `memory: true`, and it is vectorised by
+the chosen provider's embedding model. A provider that publishes none -
+Anthropic - gets the store without an `embeddings:` entry, and recall ranks by
+term overlap until one is added; an entry naming a provider with no embeddings
+API is a project that fails to load, not one that degrades.
 
 **Choosing the model.** Without `--model`, the keyring is asked - not counted.
 Stored credentials are probed, because holding a key is not the same as holding

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

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

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

@@ -47,6 +47,12 @@ Top level, and again per agent, where an agent's block is merged over the base.
 `CREDENTIAL`: the keyring has already materialised real credentials into the
 process environment, and a sandbox is the last place they should be forwarded to.
 
+The door for those is the project's `.env`, which `zen init` writes and
+`.gitignore` covers. `zen run` reads it before loading the project and forwards
+every name in it into the container **by name**, so the value never reaches an
+argv. `keys: false` and `zen run --no-keys` withhold it along with the API keys.
+The shell's environment wins over the file; the keyring fills in the rest.
+
 ## `persist: true` is usually what you want
 
 Only `/workspace` and `/home/agent` survive an ephemeral container. A

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 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 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.
 ---
 
 # Memory
@@ -197,8 +197,9 @@ below.
 └── .lock           held while a run is writing; a dead pid's lock is stale
 ```
 
-It is project state, not source, and it is not committed. The directory is
-mounted **read-only** at `/memory` in the agent's namespace.
+It is committed with the project - everything but `.lock`, which is runtime
+state. The directory is mounted **read-only** at `/memory` in the agent's
+namespace.
 
 ## Designing a memory strategy
 
@@ -363,6 +364,40 @@ lands at `<project>/memory/files/<id>.<ext>` and appears to the agent as:
 | Mount     | `/memory`, **read-only**                                         |
 | Extension | preserved, because it decides how the file runs and renders      |
 
+### The agent has to be able to write the file first
+
+`memory_commit` **copies** a file that already exists. It is not an upload
+channel and it cannot create one. So everything too big for a node's `text` - a
+script, a config, an assembled passage - depends on the agent having a tool that
+puts bytes in the **workspace**, and an agent with none can only ever commit
+text no matter how much the memory design leans on `file` nodes.
+
+| The agent's `tools:`         | Can it commit a `file`?                                                 |
+| ---------------------------- | ----------------------------------------------------------------------- |
+| `write_file` / `apply_patch` | Yes. Write it, then name the same path                                  |
+| `run_command` only           | Yes, but only under `/workspace` - a heredoc into `/tmp` is unreachable |
+| Neither                      | No. Everything worth keeping has to fit on one line of `text`           |
+
+The workspace is the only tree that round-trips, because it is the only
+writable one. `/assets`, `/skills` and `/memory` resolve as well - they are
+mounts the file tools know by name - but they are **read-only**, so nothing can
+be put there to be remembered. Every other absolute path is real to
+`run_command` and outside the workspace root, so a file written to `/tmp` comes
+back as:
+
+```
+error: outside the workspace: /tmp/report.py
+```
+
+A bare error carrying none of the `hint` the other memory refusals do, because
+containment is a workspace answer rather than a memory one.
+
+This is the trap in a `tools:` list trimmed to `run_command` alone: the shell
+can create the file, so `file` nodes look supported, but nothing in the agent's
+context ever uses workspace vocabulary and the model has no reason to prefer
+`/workspace` over `/tmp`. Either give it the file tools, or say in its prompt
+that work it means to keep goes in `/workspace`.
+
 Reusing one is the point of keeping it:
 
 ```
@@ -379,11 +414,14 @@ node explaining what it is and the graph cannot acquire orphans. To change a
 remembered file: copy it into the workspace, edit it there, commit the new one
 and link it with `SUPERSEDES` to the old.
 
-| Commit as | When                                                                      |
-| --------- | ------------------------------------------------------------------------- |
-| `file`    | It is runnable, or it is the artifact itself: a script, a config, a query |
-| `snippet` | It is a few lines that only make sense read: a request body, a fragment   |
-| `fact`    | It is a sentence. A file containing one sentence is a fact in a costume   |
+The node text describes and locates; the file carries the content. Reach for a
+node with no file only when the whole of what you know fits on one line.
+
+| Commit as | When                                                                        |
+| --------- | --------------------------------------------------------------------------- |
+| `file`    | It is content - a script, a config, a query, a passage, an assembled answer |
+| `snippet` | It is a few lines that only make sense read, and nothing will ever run them |
+| `fact`    | It is one line. A file containing one sentence is a fact in a costume       |
 
 ## Memory in front of a `zen rag` index
 
@@ -400,18 +438,26 @@ it is entirely a matter of **what you commit**.
 | Freshness       | as fresh as the last `index`                                    | as stale as it was allowed to get |
 | Cost of a query | one embedding round trip (`search`), or nothing (`list`/`grep`) | already in the prompt             |
 
-So: **never copy index content into memory.** A schema pasted into a node goes
-stale silently and the index already answers in milliseconds; a documentation
-passage quoted into a node outlives the release it was true for and will look
-exactly as authoritative when it is wrong.
+So: **never copy content out of an index that still changes.** A schema pasted
+into a node goes stale silently and the index already answers in milliseconds; a
+documentation passage quoted into a node outlives the release it was true for
+and will look exactly as authoritative when it is wrong.
+
+A **pinned** index is the exception, and a real one. Docs indexed from a
+released version or a versioned reference tree cannot change under the memory,
+so a passage taken out of one stays true as long as the project stays on that
+version. Keep it as a `file` node whose text names the documents and line ranges
+and says which version it was. That is as well as the route, never instead of
+it.
 
-What memory should hold is the **route** - the resolution, not the source:
+What memory should hold first is the **route** - the resolution, not the source:
 
 | Commit                                                                            | Kind               | Because                                                                           |
 | --------------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------- |
 | The endpoint that turned out to be the answer, and its shape                      | `operation`        | A `search_api` costs a round trip and returns five ranked guesses; this names one |
 | The sequence of calls that was necessary                                          | `plan`             | No ranking finds an ordering. It is not in the document                           |
 | Where the answer lives in the docs - document name, heading, line range           | `fact`             | `zen rag docs show` reads it back verbatim and current                            |
+| The passage itself, when the index is pinned to a released version                | `file`             | It cannot change under you, and the pointer alone makes the next run re-read it   |
 | A convention the index cannot state - auth, casing, base path, the error envelope | `fact`             | It is not in the graph, and it is wrong to re-derive it every run                 |
 | Where the index itself is                                                         | `fact`             | `-d` or `$ZEN_SCHEMA_DB`. An agent cannot guess a path                            |
 | A working request body, or a script that drives the API                           | `snippet` / `file` | The thing you would otherwise write again                                         |
@@ -451,8 +497,12 @@ cheap and settles it.
 ### The project skill is where this is written down
 
 An index used by a project needs a skill in that project describing it - see
-`zen-rag-schema` and `zen-rag-docs`. Memory policy belongs in the same skill,
-because it is the same subject:
+`zen-rag-schema` and `zen-rag-docs`. The memory policy that is **about the
+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.
 
 ```md
 - Recalled routes are a shortcut, not authority. Confirm with `list_api --name`
@@ -460,10 +510,61 @@ because it is the same subject:
 - After solving something the index made you work for, commit it: the
   `operation` you ended on, linked to the `task` that asked and any `fact` you
   had to discover. Phrase the text as the question, not as the operation id.
-- Never commit schema text or documentation passages. Commit the pointer -
-  document, heading, line range - and read it back with `zen rag docs show`.
+- Never commit schema text or documentation passages copied out of a document
+  that still changes. Commit the pointer - document, heading, line range -
+  alongside what you concluded from it, and read the passage back with
+  `zen rag docs show` to check the conclusion still holds.
+- Our docs are indexed from the pinned 1.4 tree, so a passage out of them is
+  safe to keep whole: commit it as a `file` node headed with the documents and
+  line ranges, next to the pointer and the conclusion.
+```
+
+## The house rules
+
+**Every project that enables memory carries `references/memory-instructions.md`
+in its own `agents/memory-instructions.md`**, as part of turning memory on. That
+file is how the agent is told to use the store: read and search it only through
+the tools, never through `/memory` itself, and what a node must carry to still be
+worth having.
+
+`zen init` writes it, because the projects it scaffolds have memory on from the
+first run. Two cases are left to check by hand: a project that turned memory on
+afterwards, and one whose copy has drifted from the reference or was deleted.
+
+Neither is checked by eye. The skill ships the check, and it is one command:
+
+```sh
+.github/skills/zen-memory/scripts/check-instructions.sh        # the verdict
+.github/skills/zen-memory/scripts/check-instructions.sh diff   # every differing line
+.github/skills/zen-memory/scripts/check-instructions.sh fix    # copy the reference over
+```
+
+It says whether this project turns memory on at all, exits non-zero on a copy
+that is missing or stale, and prints the `cp` that repairs it. When the only
+difference is trailing whitespace it says so - that is the usual drift, it is
+invisible on screen, and it is the reason reading the two files side by side
+never caught it.
+
+It is a copy, not a transcription - this reference already sits in the project,
+because `zen init` and `zen open` write the whole `.github/` tree, and they write
+it from the same file the project's copy came from. What `fix` runs, from the
+project root, is exactly:
+
+```sh
+cp .github/skills/zen-memory/references/memory-instructions.md agents/memory-instructions.md
 ```
 
+Everything the project keeps under `agents/` named `<topic>-instructions.md` is
+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.
+
 ## Inspecting and repairing it
 
 ```
@@ -486,9 +587,17 @@ so inspection is free and offline.
 | Why was that recalled?                   | `zen memory show <id>`           |
 | That should never have been written down | `zen memory forget <id>`         |
 
+The directory is not fixed. `zen run --memory <dir>` sends one run's memory
+somewhere else - a scratch graph for a trial, one per branch, or a shared one
+outside the repository - and `zen memory --dir <dir>` reads any such directory
+with no project around it. Together they are also how you read a graph while a
+run holds its `.lock`: copy the directory, delete the copy's `.lock`, and point
+`--dir` at the copy.
+
 `zen inspect` answers the other half: a run report shows the recollection block
 exactly as the model received it, which is how you tell "memory had nothing"
-apart from "memory had it and the model ignored it".
+apart from "memory had it and the model ignored it". A run given `--memory`
+wants `zen inspect --memory <dir>` to rebuild its report against the same graph.
 
 ## A worked configuration
 
@@ -524,10 +633,16 @@ agents:
 
 ## Review checklist
 
+- [ ] `.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`.
 - [ ] `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.
 - [ ] `access: full` appears at most once.
+- [ ] Any agent the design expects to commit `file` nodes can write to the
+      workspace - `write_file`/`apply_patch`, or `run_command` with `/workspace`
+      named in its prompt. Nothing else round-trips.
 - [ ] `sees`/`writes` exist because an agent would be **misled** by the other
       slice, not merely because it does not need it.
 - [ ] `autoRecall: false` on any agent whose user message is a payload.
@@ -538,18 +653,23 @@ 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. Re-embed or change it back                       |
-| 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                  |
-| 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`                            |
-| 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                  |
+| 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

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+#
+# Whether this project's memory house rules are still the rules.
+#
+#   check-instructions.sh          diff the copy against the reference
+#   check-instructions.sh diff     the same, showing every differing line
+#   check-instructions.sh fix      overwrite the copy from the reference
+#
+# `agents/memory-instructions.md` is a *copy* of the `zen-memory` skill's
+# `references/memory-instructions.md`, and the reference is rewritten by every
+# `zen init` and `zen open`. So the copy goes stale silently, and it drifts by
+# trailing whitespace inside tables, which no one can see by reading. That is
+# the whole reason this is a script and not a checklist line.
+#
+# Run it from anywhere; it finds the project root from its own location.
+
+set -eu
+cd "$(dirname "$0")/../../../.."
+
+COPY=agents/memory-instructions.md
+REFERENCE=.github/skills/zen-memory/references/memory-instructions.md
+REMEDY="cp $REFERENCE $COPY"
+
+if [ ! -f "$REFERENCE" ]; then
+    echo "check-instructions.sh: no $REFERENCE in $PWD" >&2
+    echo "check-instructions.sh: run \`zen open\` to rewrite the .github tree" >&2
+    exit 2
+fi
+
+# The project turns memory on when something declares it — the top-level block
+# or an agent's binding — so any `memory:` key in the configuration counts.
+# The config is found by name, in the order a run finds it.
+config() {
+    for file in agents.yaml agents.yml agents/agents.yaml agents/agents.yml; do
+        if [ -f "$file" ]; then
+            echo "$file"
+            return 0
+        fi
+    done
+}
+
+uses_memory() {
+    # `|| true` because no configuration at all is an answer, not a failure.
+    conf="$(config || true)"
+    if [ -z "$conf" ]; then
+        return 1
+    fi
+    grep -Eq '^[[:space:]]*(-[[:space:]]+)?memory:' "$conf"
+}
+
+# The file with every line's trailing whitespace removed. Two of these being
+# equal is the drift nobody can see by reading, named as such.
+trimmed() {
+    sed 's/[[:space:]]*$//' "$1"
+}
+
+report() {
+    if uses_memory; then
+        echo "memory: on"
+    else
+        echo "memory: off"
+    fi
+
+    if [ ! -f "$COPY" ]; then
+        if uses_memory; then
+            echo "missing: $COPY"
+            echo "remedy: $REMEDY"
+            return 1
+        fi
+        echo "ok: no copy, and nothing needs one"
+        return 0
+    fi
+
+    if cmp -s "$REFERENCE" "$COPY"; then
+        if ! uses_memory; then
+            # Harmless, but it is rules for a capability nothing turned on.
+            echo "note: the copy is current, but no agent has a memory: binding"
+        fi
+        echo "ok: $COPY is the reference, byte for byte"
+        return 0
+    fi
+
+    echo "drift: $COPY differs from the reference"
+    # Said out loud because it is invisible on screen, and is the usual cause:
+    # a trailing space inside a table, or a lost final newline.
+    if [ "$(trimmed "$REFERENCE")" = "$(trimmed "$COPY")" ]; then
+        echo "drift: trailing whitespace only — nothing you could have seen"
+    fi
+    echo "remedy: $REMEDY"
+    return 1
+}
+
+show_diff() {
+    report || true
+    # `-L` names the two sides, since both files are called the same thing.
+    diff -u -L reference -L "$COPY" "$REFERENCE" "$COPY" || true
+    # The report's verdict, not the diff's.
+    report >/dev/null
+}
+
+fix() {
+    cp "$REFERENCE" "$COPY"
+    echo "wrote: $COPY"
+    echo "note: project policy belongs in agents/memory-policy-instructions.md"
+}
+
+case "${1:-status}" in
+    status) report ;;
+    diff) show_diff ;;
+    fix) fix ;;
+    *)
+        echo "usage: check-instructions.sh [status|diff|fix]" >&2
+        exit 2
+        ;;
+esac