@zenera/cli 1.1.23 → 1.1.25

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

@@ -0,0 +1,283 @@
+---
+name: zen-topology
+description: 'Use when designing, reviewing or auditing how a Zenera project divides work between agents - whether to hand off, fork one branch to delegate, fan out several branches, or keep the work in one conversation; which fork `context` to pick; what each choice costs in tokens, prompt cache and elapsed time; and how to read a recorded run for topology mistakes (missed fan-out, a forked sequence, an early or looping hand-off, a delegation that cost more than it saved). Load before adding or changing `handoffs:` or `fork:` in agents.yaml, before writing a prompt line that says when to delegate, and before grading Delegation or Forking in a run audit.'
+---
+
+# Agent topology
+
+Work moves between agents in exactly two ways, and both are tools the model
+calls: a **hand-off** (`transfer_to_<name>`) gives the conversation away, a
+**fork** (`fork`) sends work out and gets answers back. Everything else is one
+agent working in its own conversation. Both are opt-in per agent in
+`agents.yaml` - `handoffs:` and `fork:`, described key by key in §8.
+
+Whether a second agent should exist at all is copilot-instructions §6.1 - this
+skill starts once it does. The rules an agent reads at run time about forking
+are zen's own `agents/fork-instructions.md`; this skill is for whoever designs
+the project or judges a run against it, and never repeats that file's prose.
+
+## 1. The four shapes
+
+| Shape          | Control                      | The other side sees                      | Comes back                    | Use it when                                                                 |
+| -------------- | ---------------------------- | ---------------------------------------- | ----------------------------- | --------------------------------------------------------------------------- |
+| Keep it here   | stays                        | -                                        | -                             | steps depend on each other, one call does it, or you want to steer the work |
+| Hand-off       | moves, and **stays moved**   | the whole transcript                     | nothing, unless it hands back | another agent should own the conversation from now on                       |
+| Fork, 1 branch | returns to the forking agent | what `context` gives it + its assignment | that branch's answer only     | you want an answer from someone better suited, or to keep noise out         |
+| Fork, N        | returns to the forking agent | the same, per branch                     | N answers in one tool result  | N independent parts of one task, done at the same time                      |
+
+## 2. What a hand-off carries
+
+When the model calls `transfer_to_<name>`, the kernel records a `handoff` node
+(`from`, `to`, the optional `reason` argument), switches the current agent,
+appends a fresh `system_prompt` for the target, and rebuilds the tool list for
+it - its own tools, its hand-offs, its memory and skill tools, its `fork`.
+
+- **The target sees the entire transcript**, every tool call and result the
+  previous agent made included. The runtime can collapse the outgoing agent's
+  turns with a hand-off policy, but `zen` sets none, so nothing is summarised.
+  Do not write a prompt that assumes the target starts clean.
+- Only the newest system prompt is sent. The previous agent's role and house
+  rules are gone from the request; its words are not.
+- The target's `description:` is the whole of what the caller reads when
+  deciding, so it is a routing condition, not a title.
+- **Auto-recall fires again** for the target, with its own memory mask, against
+  the last user input - not against the `reason`.
+- Preloaded skills are applied for the target; the outgoing agent's skill tools
+  are not the target's.
+- **Nothing hands control back.** The target answers every later turn until it
+  hands off itself, which is why `zen check` warns `handoff.one-way` on any edge
+  with no path home.
+- A memory commit is due from the agent that did the work, **before** its
+  hand-off. The target holds only the transcript of it - see **zen-memory**.
+
+## 3. What a fork carries
+
+The model calls `fork` with `branches: [{name, instructions, agent?}]` and one
+`context` for the whole call. The agent must declare `fork:`; `fork.agents`
+reaches the model as an `enum`, and `fork.maxBranches` caps the array.
+
+**What a branch starts from:**
+
+| `context`           | The branch begins with                                                      |
+| ------------------- | --------------------------------------------------------------------------- |
+| `inherit` (default) | the parent's visible history up to the fork call, then its assignment       |
+| `compact`           | the same minus every `tool_call`, `tool_result` and `memory_recall`         |
+| `none`              | nothing: its agent's system prompt, then its instructions as a user message |
+
+Under `inherit` and `compact` the assignment arrives as the result of the
+inherited `fork` call, opening `You are branch "<name>" of the fork above`,
+naming its siblings. Skills another agent loaded are dropped from an inherited
+prefix, so a branch never reads instructions for tools it does not hold.
+
+**What comes back:** one tool result, holding each branch's final answer and
+status in declared order, never completion order. The branch's own steps are
+kept inside the `join` node for audit and are never shown to the parent. A
+failed branch is a row with `status: error`, not a failed run.
+
+**What outlives the branch:** files it wrote (branches share the workspace with
+the parent and each other) and anything it committed to memory. Nothing else.
+
+**Depth:** a branch may fork again while under the run's `maxForkDepth` (2 by
+default). At the cap the `fork` tool is withdrawn and so is
+`agents/fork-instructions.md`.
+
+## 4. What it costs - tokens, cache, time
+
+A provider caches the longest **repeated prefix** of a request - tool schemas,
+system prompt, then messages - and bills a cached token below an uncached one.
+The runtime keeps that prefix still: house rules first, the role file second,
+the tool array fixed for the agent's life, preloads at the head, auto-recall
+only at the start of a turn. So the question for every shape is: **are the
+first bytes the same as a request the provider has already seen?**
+
+| Shape                        | Tokens sent                                             | Prompt cache                                                                                       | Elapsed              |
+| ---------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------- |
+| Keep it here                 | the transcript, growing every call                      | hits on all of it but the newest tail                                                              | the sum of the steps |
+| Hand-off                     | the whole transcript, on every call the target makes    | **misses on the target's first call** - new system prompt and tools, so nothing after them matches | serial               |
+| Hand-off back                | the same                                                | the original agent's prefix up to its hand-off may still hit, within the provider's cache lifetime | serial               |
+| Fork, `inherit`, same agent  | per branch: the parent's history + brief + its own work | the inherited prefix is byte-identical up to the fork call, so it can hit                          | the slowest branch   |
+| Fork, `inherit`, other agent | the same                                                | misses: a different system prompt, so the whole history is paid uncached, once per branch          | the slowest branch   |
+| Fork, `compact`              | less history: decisions without tool traffic            | same agent: hits only up to the first dropped tool call; other agent: misses                       | the slowest branch   |
+| Fork, `none`                 | its agent's prompt + instructions + its own work        | nothing to share with the parent; same-agent branches share the system prompt with each other      | the slowest branch   |
+| The parent after a join      | two messages more: the call and one result              | unchanged - declared order makes the join deterministic                                            | -                    |
+
+What follows from the table:
+
+- **A fan-out buys time, not tokens.** N branches together usually send more
+  than doing the N parts in series, because every branch pays its own start.
+  The saving is the elapsed time of all but the slowest branch, and the
+  parent's context staying N answers long instead of N transcripts.
+- **A one-branch fork costs a whole conversation's start** to save the caller
+  some context. Worth it for a long, noisy job with a short verdict; a loss for
+  one read, one search or one command.
+- **Agents passing the conversation back and forth pay a cache miss on every
+  switch**, plus a recall each time, on a transcript that only grows.
+- **`inherit` versus `compact` is a trade, not a rule.** `compact` sends less;
+  `inherit` on the same agent can be served from cache. When most of the
+  history is tool traffic, `compact` wins; when it is mostly decided
+  conversation, `inherit` on the same agent can be cheaper. On a different
+  agent there is no cache to win, so the smaller prefix wins.
+- **Cached tokens are not shown in the run graph.** `zen inspect`'s `tokens`
+  row and each `llm` node's `in` count cached tokens as input. Reason about the
+  cache from the structure above; never report a hit or a miss as measured.
+
+## 5. Choosing - in this order
+
+Ask each question of the piece of work in front of you and stop at the first
+yes.
+
+1. **Does any part need another part's result?** Keep that sequence here. A
+   branch cannot see its siblings, cannot ask, and cannot be steered.
+2. **Is it one call, or one call that takes a list?** Keep it here. Pass the
+   list.
+3. **Should another agent answer the user from now on** - over several turns,
+   on its own model or tools? Hand off, and make sure a path leads back.
+4. **Do you want an answer and then carry on?** Fork one branch on the agent
+   that suits the job. Never a hand-off: that spends the conversation to get
+   the answer.
+5. **Are there N independent parts?** Fork N branches - one per item, or one
+   per trade, each on the agent that fits.
+
+Then pick `context`, cheapest first:
+
+1. `none`, when everything the branch needs can be written into its
+   instructions - paths included. Write it in and take `none`.
+2. `compact`, when it needs the plan and the decisions but not how they were
+   found, or when the branch runs a **different** agent.
+3. `inherit`, when it must see the work as it stands - reviewing what was just
+   written, continuing an investigation - and preferably on the **same** agent.
+
+## 6. Where each rule goes
+
+| Rule                                                              | Goes in                                                           |
+| ----------------------------------------------------------------- | ----------------------------------------------------------------- |
+| who may hand off to whom; who may fork, to which agents, how wide | `agents.yaml` - `handoffs:`, `fork: { agents, maxBranches }` (§8) |
+| what a hand-off target is for                                     | `agents.yaml` - the target's `description:`, as a condition       |
+| **when** to fork or hand off, in this domain's terms              | the deciding agent's prompt                                       |
+| which `context` this work wants                                   | the deciding agent's prompt                                       |
+| what a branch must return, and in which file                      | the forking agent's prompt, so it writes it into `instructions`   |
+| which hand-off ends a specialist's turn                           | the specialist's prompt                                           |
+| a forking policy for the whole project                            | `agents/fork-<topic>-instructions.md` - load **zen-instructions** |
+
+The domain-terms line is the one most often missing, and without it a weaker
+model works through a list serially and never calls `fork`: _"When the request
+covers more than one region, fork one branch per region with `context: none`,
+and tell each branch to return the region, the total and the top three
+findings."_
+
+Never edit `agents/fork-instructions.md` - it is zen's copy, `zen check --fix`
+replaces it, and an edit there is reported as `rules.stale`.
+
+## 7. Reading a run for topology
+
+Where the topology shows in `zen inspect graph` (load **zen-inspect** for the
+format):
+
+- `%% agent <last> · started as <first>` - a hand-off happened.
+- `@<agent>` on a node - the first node that agent owns.
+- `handoff <from> to <to>` - open it for `reason`.
+- `fork (<context> context) <branch>, <branch>` - the mode it chose.
+- the branch subgraphs, one marked `slowest`, and `join <branch>=ok, ...`.
+- `%% branches` - which join waited for which branches, with status.
+- `%% tools` - `fork xN` and how many research calls ran around it.
+
+| The graph shows                                                                     | Finding                                           | Fix goes in                                               | Next run should show                         |
+| ----------------------------------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------- |
+| research calls in series, none using an earlier result, `fork` in the agent's tools | missed fan-out                                    | the agent's prompt: the domain trigger of §6              | one `fork` with a branch per item            |
+| the same, `fork` not in the agent's tools                                           | missed fan-out                                    | `agents.yaml`: `fork:` on that agent                      | the same                                     |
+| a branch's instructions name a sibling's result, or read a file a sibling writes    | a sequence was forked                             | the forking agent's prompt                                | those steps in the trunk                     |
+| a one-branch fork whose branch made one or two calls                                | delegation that cost more than it saved           | the forking agent's prompt                                | the call made in the trunk                   |
+| after the join, the parent repeats calls a branch already made                      | the branch was not told what to return            | the forking agent's prompt: what each branch must return  | no repeat after the join                     |
+| a branch not `ok`                                                                   | an assignment missing a fact it could not ask for | the forking agent's prompt                                | that branch `ok`                             |
+| `slowest` far behind its siblings                                                   | an uneven division                                | the forking agent's prompt: split that part               | branch durations close together              |
+| two branches with the same calls on the same subjects                               | overlap, paid for twice                           | the forking agent's prompt: divide by subject             | disjoint subjects                            |
+| a wide fan-out to **another** agent with `inherit` and a long history               | the history paid uncached, once per branch        | the forking agent's prompt: `compact` or `none`           | `fork (compact context)` or `(none context)` |
+| a `handoff` before the agent's own part was done                                    | an early hand-off                                 | the outgoing agent's prompt                               | its own calls, then the hand-off             |
+| `handoff` A to B, then B to A, then A to B                                          | a loop - two prompts claim the same job           | both prompts, so one owns it                              | one hand-off, or none                        |
+| a hand-off for one question, then the target writes the final answer                | wanted an answer, spent the conversation          | the outgoing agent's prompt, and `fork:` in `agents.yaml` | a one-branch `fork` to that agent            |
+| a specialist exists in `agents.yaml`, and the agent did that job inline             | the prompt never said when to delegate            | the deciding agent's prompt                               | a `fork` or `handoff` to the specialist      |
+
+Price each finding honestly. A missed fan-out costs the elapsed time of every
+branch but the slowest - not tokens, which a fork usually raises. A forked
+sequence or an overlap costs the duplicated calls and their tokens. A
+needless hand-off or one-branch fork costs one conversation's start, uncached.
+
+To learn **why** the model chose the shape, ask the `llm` node that carries
+`calls transfer_to_<name>` or `calls fork`, or the first call of a serial run -
+load **zen-inspect-ask** for how to word it. First rule out the cheap causes:
+`fork` not in that call's tools (depth cap, or no `fork:`),
+`fork-instructions.md` not in its `system_prompt`, a specialist not in its
+`enum`.
+
+## 8. The keys in `agents.yaml`
+
+Both keys are per agent, and both only make a tool available. When the model
+uses it is the prompt's business (§6).
+
+### `handoffs:`
+
+```yaml
+agents:
+    - name: intake
+      description: Takes the first message and routes the case to the right desk.
+      handoffs: [billing, technical]
+    - name: billing
+      description: Answers invoice and refund questions from the written policy.
+      handoffs: [intake] # the way home
+    - name: technical
+      description: Diagnoses faults from the logs and says what to do next.
+      handoffs: [intake]
+```
+
+- A list of bare agent names. There is no object form and no per-edge
+  configuration.
+- Each name becomes one tool on this agent, `transfer_to_<name>`, described by
+  the **target's** `description:`. With none, the model gets a generic sentence
+  and `zen check` warns `agent.no-description`. Write it as a routing
+  condition, not a title: _"Applies the written peril policies to a claim and
+  explains the outcome"_, never _"The adjuster agent"_.
+- `handoff.unknown` (an agent not declared) and `handoff.self` are load errors.
+- `handoff.one-way` is a warning: an edge `A → B` with no path from B back to
+  A. Indirect counts - `B → C → A` is a way home - so every edge must lie on a
+  cycle. Without one, the first routed question is the last one routed.
+
+### `fork:`
+
+```yaml
+agents:
+    - name: trunk
+      fork: true # any declared agent, any number of branches
+
+    - name: sweep
+      fork:
+          agents: [sweep, prober] # who a branch may run - itself included
+          maxBranches: 6
+
+    - name: asker
+      fork: { agents: [prober], maxBranches: 1 } # delegation, never a fan-out
+```
+
+| Written            | Means                                                                                                                |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| absent, or `false` | no `fork` tool, and `agents/fork-instructions.md` never reaches this agent                                           |
+| `true`, or `{}`    | the tool, any declared agent, no cap                                                                                 |
+| `agents: [a, b]`   | a branch may run only these. The list is an `enum` on each branch's `agent` field, so another name cannot be decoded |
+| `maxBranches: n`   | at most `n` branches per call. `1` allows delegation and refuses fan-out                                             |
+
+- `agents` **may name the forking agent itself** - one role fanned out over
+  many items is the common shape, and unlike `handoffs:` it is not an error.
+- A branch that leaves `agent` out runs the forking agent - but only when the
+  forking agent is in `agents`. When it is not, the model must name one.
+- **A branch runs as its agent**: that agent's prompt, tools, memory binding,
+  skills, hand-offs and its own `fork:`. A hand-off inside a branch moves the
+  branch's conversation, never the parent's.
+- Depth is not a key here. `maxForkDepth` (2 by default) is a run option; at
+  the cap the `fork` tool is withdrawn, and `agents/fork-instructions.md` with
+  it.
+- Refused at load: `agents: []`, `maxBranches: 0`, and an `agents` entry not
+  declared (`fork.unknown`).
+- `fork.uninstructed` is an error: an agent can fork and
+  `agents/fork-instructions.md` is missing or empty. `zen check --fix` writes it
+  back. That file is zen's - an edit in it is reported as `rules.stale` and lost
+  at the next `--fix`; project policy on forking goes in
+  `agents/fork-<topic>-instructions.md` (load **zen-instructions**).

package/templates/editor/.vscode/agents.schema.json

@@ -429,7 +429,7 @@
                                     "description": "How many seeds a recall starts from.",
                                     "type": "integer",
                                     "exclusiveMinimum": 0,
-                                    "default": 5
+                                    "default": 10
                                 }
                             }
                         }

package/templates/editor/.vscode/settings.json

@@ -1,5 +1,7 @@
 {
     "chat.useNestedAgentsMdFiles": false,
+    "chat.agent.maxRequests": 250,
+    "terminal.integrated.tabs.description": "Agent",
     "yaml.schemas": {
         "./.vscode/agents.schema.json": [
             "agents.yaml",

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

@@ -16,23 +16,35 @@ Check which tools you actually have:
 - If `write_file` and `apply_patch` are available, you may create and edit files
   under `/workspace`.
 
-## Discovery before assumption
+## Finding files
 
-Never guess a file's name, location, or contents.
+Never guess a file's name, location, or contents. Pick the tool by what you know:
 
-- Use `list_dir` to see directory contents and formats before opening files.
-- Use `find_files` to locate files by substring when the layout is unfamiliar.
-- Check whether a target file already exists before writing to it.
+- **The directory** → `list_dir { path }`. One level, not recursive. Each file shows
+  `format`, `bytes` and, for text, `lines`, so you can decide what to read and how much
+  without opening it. Omit `path` (or give `/`) to list the mounted trees.
+- **Part of the path** → `find_files { pattern, path? }`. `pattern` is **required**: a
+  plain, case-insensitive substring, never a glob or regex (`*.ts` matches nothing; write
+  `.ts`). It is matched against the path with its mount name (`/workspace`, `/assets`, …)
+  removed: `/workspace/src/a.ts` is matched as `src/a.ts`, so `src/` matches and
+  `/workspace/src` does not. To limit the search to one tree, pass it as `path`. Matches
+  come back as absolute paths.
+- **Neither** → `list_dir` the root, then descend.
+
+`find_files` matches paths, not contents. Both tools stop at 500 results and set
+`truncated`: narrow the `pattern` or `path` rather than repeating the call.
 
 ## Reading files
 
-- Use `read_file` to read text files.
-- For files longer than a few dozen lines, pass `start_line` and `end_line` (1-based, inclusive)
-  to read only the relevant section.
-- When `read_file` returns `truncated: true`, the read hit the size limit or range boundary.
-  Resume reading from `end_line + 1` if you need the remainder.
-- Non-text files (images, binaries, archives) cannot be read as text; `list_dir` reports
-  their format.
+- `read_file { path, start_line?, end_line? }`; lines are 1-based and inclusive. Read a
+  short file whole; for a long one (see `lines` from `list_dir`), read the range you need.
+- The result gives the file's total `lines` and the `start_line`/`end_line` returned.
+  `truncated: true` means more follows `end_line` (your range or the 256 KB cap); continue
+  from `end_line + 1` only if you need it.
+- A non-text file fails with its `format`. Do not retry; `copy_file` can still copy it.
+- Check whether a target exists before writing to it.
+
+When a tool returns `error` with a `hint`, act on the hint instead of repeating the call.
 
 ## Modifying files
 
@@ -69,6 +81,16 @@ Example patch:
 Use `write_file` only to create a **new** file or to overwrite a small file completely.
 Never use `write_file` to update an existing file when only a few lines need to change.
 
+### Copying: `copy_file`
+
+Use `copy_file` to duplicate a file, never `read_file` + `write_file`. The bytes skip the
+conversation, so there is no size cap and binaries arrive intact.
+
+- The source may be in a read-only mount; only the destination must be writable.
+  This is how something under `/assets`, `/skills` or `/memory` reaches `/workspace`.
+- Set `overwrite: true` only when intentionally replacing an existing destination.
+- Copying a directory and its contents requires `recursive: true`.
+
 ### Moving and deleting
 
 - Use `move_file` to rename or relocate a file or directory. It creates parent directories
@@ -83,4 +105,4 @@ All file operations are confined to mounted trees:
   (such as `/workspace/src/main.ts`) are where project files reside.
 - `/assets`, `/skills`, `/memory`: Read-only mounts. You may read, list, and search them,
   but you cannot write, move, or delete files inside them.
-- Any attempt to reach outside these mounts fails with an containment error.
+- Any attempt to reach outside these mounts fails with a containment error.

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

@@ -48,6 +48,31 @@ the tool call.
 Do not fork a sequence. Branches run at once and can exchange nothing, so a step
 that needs the step before it has to stay in this conversation.
 
+## When the assignment is yours
+
+These rules reach a branch as well as the agent that forked it, and a branch
+arrives in the middle of someone else's sentence. Your assignment comes to you
+as the result of a `fork` call, because that is how the runtime delivers it —
+and that is indistinguishable, in a transcript, from a fork you made yourself
+coming back with an answer.
+
+It is not one. When a message begins "You are branch ... of the fork above", you
+are that branch and that text is your assignment:
+
+- **Nothing has run yet.** There is no result in it and nothing to verify. The
+  fork it names is above in the conversation you were forked out of, which is
+  not the one you are in — yours begins with that message.
+- **Do the work yourself.** Never fork a branch to carry out the assignment you
+  were handed: that branch is you one level down holding the same instructions,
+  it will read them the same way, and each level spends a whole system prompt to
+  arrive back where it started. At the depth cap the tool is withdrawn and the
+  work comes back undone.
+- **Do not go looking for proof it was already done.** An empty workspace is
+  what an unstarted job looks like, not a sign that something failed upstream.
+
+Fork from inside a branch only for work that is genuinely divisible further and
+that you were not handed already divided.
+
 ## When it is worth it
 
 One question decides it: **could this be finished by someone who cannot ask you
@@ -63,6 +88,8 @@ no, the work stays here.
 | Find the config, then change it, then test it                                                | Not a fork. Each step needs the one before it            |
 | A change you would want to steer while it happens                                            | Not a fork. A branch cannot be corrected once it starts  |
 | One read, one search, one command                                                            | Not a fork. A whole conversation to save yourself a line |
+| Twenty items one call already takes as a list                                                | Not a fork. Pass the list                                |
+| The assignment you were handed, whole                                                        | Not a fork. It is yours — see above                      |
 | Two jobs that would write the same file                                                      | Not a fork until they write different files — see below  |
 
 ## Fanning out

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

@@ -7,7 +7,8 @@ requires: [memory]
 This project has a memory: a graph of what earlier runs worked out, kept with
 the project rather than with the session, and shared with every other agent that
 can see it. It is reached **only** through the `memory_*` tools - `memory_search`
-to find, `memory_load` to read.
+to find by meaning, `memory_grep` to find an exact string, `memory_load` to
+read.
 
 Not every agent may write to it. Read what follows against the tools you
 actually have: if `memory_commit` is not among them, everything under
@@ -99,8 +100,9 @@ its own source.
 ## Reading it
 
 `memory_search` hands back an outline of a subgraph with each node's text cut to
-160 characters. `memory_load` is what reads a node whole, by id - load anything
-you are going to rely on.
+160 characters. `memory_grep` hands back the nodes containing an exact string,
+with the lines it matched on. `memory_load` is what reads a node whole, by id -
+load anything you are going to rely on.
 
 ### The shape of a recollection
 
@@ -133,20 +135,52 @@ at that path through `memory_load`, never by looking around in the directory.
 `vectors.json` and `manifest.json` - its internal format. Do not open, list,
 grep, `cat` or `find` them, and do not point a shell command at that directory:
 
-- it is ranked by **meaning**, so substring matching misses the hits;
 - `graph.json` is every node ever committed, as one line;
 - a raw read bypasses the audience mask and serves **superseded** nodes -
   corrections that were withdrawn - as if they were current;
 - it records no use, so the ranking that decides what gets recalled next decays;
 - another run may be writing, and the manifest is written last.
 
+**`memory_grep` is that search, done properly.** It reads every node exactly -
+the text, the metadata and the bytes of remembered files - and hands back the
+matching lines with the node they belong to. It applies the mask, it leaves out
+what has been superseded unless you ask for it, and it names any file it could
+not read, so a file that went unsearched never passes for one with no match.
+
 A memory is a record, not an authority - but checking one is not the same as
-redoing it. Every node names where its content came from, so confirm the
-recollection there: the named lines still say what the node says, the route
-still resolves, the command still exists. Work it out from nothing only when
-that check fails, when the source is one that changes under you, or when being
-wrong is expensive. A check that costs what the original investigation cost is
-not a check - it is the investigation again, and the memory bought nothing.
+redoing it, and how you check depends on where its content came from.
+**Pinned** - a released spec, a versioned document: its content cannot have
+moved, so use what the node says and check only that the route still resolves.
+**Living** - code, an API, anything that changes: confirm the named lines still
+say what the node says, the route still resolves, the command still exists.
+Work it out from nothing only when that check fails, or when being wrong is
+expensive. A check that costs what the original investigation cost is not a
+check - it is the investigation again, and the memory bought nothing.
+
+### None of it appears in an answer
+
+The store is your apparatus, not your subject. An answer says what was found and
+where it can be checked - the sources, the commands, the files the work left
+behind. It never says that a recollection was what put you on to them.
+
+Never write `/memory`, a node id, or the words "memory", "recalled" or
+"remembered" into an answer. Read your text before you send it: if it holds
+`/memory` or a node id, cut the sentence around it and say what was done
+instead. "Loaded the script from memory (`/memory/01J….py`) and ran it" is
+"ran `<path>`" with your working left in by mistake.
+
+Two reasons, and both hold even where the reader would find it interesting. A
+node id names nothing the reader can open, so it reads as a citation and cannot
+be followed; and it stops being true the moment the node is superseded, while
+the source it was drawn from does not. Cite the source, never the memory of it.
+
+This binds on a branch's answer exactly as it binds on the final one. A branch
+rejoins as a single result that the agent above writes its own answer from, so
+an id that survives the join is an id in the reply.
+
+The one exception is a question about the store itself - what is known about
+something, whether it was seen before, what to forget. Then it is the subject,
+and ids are what the reader needs.
 
 ## Searching it
 
@@ -177,8 +211,34 @@ would use - node texts are written to be found that way. Narrow with `kinds`,
 `newer_than`, `limit`, `max_hops` and `max_nodes` when a recollection comes back
 broad rather than wrong.
 
+### Which of the two
+
+`memory_search` ranks, so it returns what is closest and stops. That makes it
+right for a question and wrong for a fact about the store itself - whether one
+exact name, path or command was ever written down. An empty search on a
+question is still the answer to that question: it matched by meaning, so other
+wordings of the same question were covered. Do not follow it with a
+`memory_grep` for words taken from the question.
+
+`memory_grep` is exact and complete. Reach for it when the thing you are looking
+for is a **string** rather than a subject, and when the answer has to be all of
+them:
+
+| Looking for                                                     | Use             |
+| --------------------------------------------------------------- | --------------- |
+| what was learned about a subject, however it was phrased        | `memory_search` |
+| a name, path, id, host, flag or command, spelled exactly        | `memory_grep`   |
+| whether an exact name, path or command was written down at all  | `memory_grep`   |
+| everywhere a thing is mentioned, before changing or retiring it | `memory_grep`   |
+| a starting point, when you do not yet know the vocabulary       | `memory_search` |
+
+Either way, ids from one are ids for the other: grep a name, then `memory_load`
+what it turned up.
+
 Recalling nothing is not proof of anything: work it out normally, then commit
-the result so the next run does not repeat it.
+the result so the next run does not repeat it. A `memory_grep` that found
+nothing is stronger - it means the string is not there - but it says nothing
+about the subject under another name.
 
 ## Updating it
 
@@ -199,6 +259,12 @@ five paths.
 | The passage itself, when its source cannot change under you       | A passage quoted out of something that can                          |
 | A proven absence - looked here and here, it is not there          | Anything not actually verified                                      |
 
+A restatement is not merely wasted space. Recall seeds on text alone, so a run
+that commits its own request as a task, a plan and a result has committed three
+near-copies of one sentence - and on the next similar question those three take
+the seed slots between them. Everything actually learned then ranks below them
+and is never reached.
+
 A search over a schema or a documentation index costs a round trip and comes
 back ranked, so it is the thing most worth not paying for twice. Commit what it
 **resolved to** - the operation and its shape, or the document, heading and line
@@ -210,7 +276,8 @@ When the index is over something pinned - a released spec, a versioned reference
 tree - go one further and carry the passage itself in a `file` node, headed with
 the documents and line ranges it was taken from. The pointer says where to look
 and the conclusion says what it meant, but only the passage saves the next run
-from opening the sources to find out what they actually said.
+from opening the sources to find out what they actually said. Say in the node's
+text which kind of source it was, so a later run can see why a copy was allowed.
 
 ### When to commit
 
@@ -270,6 +337,25 @@ already in memory says is folded into it, and its existing id comes back under
 your ref - so the links you asked for still land, on the memory that was already
 there.
 
+**Take the task text you were handed.** When your instructions give you the
+task text, commit that text verbatim as your `task` node and look nothing up for
+it. Agents that commit at the same moment cannot see each other; identical
+wording is what folds their nodes into one.
+
+**Grep for an entity before minting a node for it.** An endpoint, a command, a
+host, a tool, a file - anything that recurs across runs is one node the rest of
+the graph hangs off, and folding by similarity will not catch a second copy
+worded differently. `memory_grep` the exact string first, and attach your edges
+to what comes back. One grep per entity you are about to mint, for its exact
+string. A sentence describing the subject is not an entity, and neither is a
+task's text: a literal phrase misses every other wording of it, and a
+near-duplicate is folded anyway.
+
+A duplicated hub is worse than a missing one. It splits the graph into islands:
+the question reaches one copy, the artifact that answers it hangs off another,
+and the walk out from a seed cannot cross between them - so a memory that is
+present returns nothing, and nothing in the recollection says it happened.
+
 **Say where the content came from.** This is what lets an incomplete
 recollection be continued instead of believed:
 
@@ -305,18 +391,11 @@ whole of what you know is one line long.
 **The file must exist in the workspace first.** `memory_commit` copies an
 existing file from the workspace; it is not an upload channel and does not
 write file contents from raw arguments. Write the file to the workspace first
-(using `write_file`, `apply_patch`, or a command saving under `/workspace`),
-then pass its workspace path (e.g. `"file": "report.py"` or
-`"file": "/workspace/report.py"`).
-
-| Which files to commit  | What belongs in them                                                       |
-| ---------------------- | -------------------------------------------------------------------------- |
-| Working scripts        | A script, query or invocation that can be re-run directly                  |
-| Configurations & specs | Self-contained config files, schemas or request templates                  |
-| Rendered findings      | A table of findings or structured report produced by an investigation      |
-| Pinned reference text  | Verbatim passages from released specs or versioned docs that cannot change |
-| Assembled answers      | Synthesised conclusions from multiple sources with a provenance header     |
-| Specimen responses     | An API response shape to reproduce against (never raw secrets)             |
+(using `write_file`, `apply_patch`, `copy_file`, or a command saving under
+`/workspace`), then pass its workspace path (e.g. `"file": "report.py"` or
+`"file": "/workspace/report.py"`). Write it with its provenance header (below)
+the first time: adding the header in a second write pays for the whole file
+twice.
 
 Do not commit files from the living codebase (use a pointer with file and line
 ranges instead - copies go stale silently), raw ephemeral command logs, or
@@ -371,16 +450,9 @@ the point; the rows it emitted do not.
 
 Two things fall outside that. An answer you assembled from several sources is a
 copy of none of them and exists nowhere in the project, so commit it, with a
-pointer node per source `INFORMED`ing it. And a source that cannot change under
-you (a released specification, a pinned dependency, a versioned reference tree)
-does not go stale silently, so the finding may be kept whole.
-
-When it is kept whole, keep it as a `file` node rather than as a longer `text`:
-the text says what the passage establishes and names the documents it came from,
-the file carries the whole block behind its provenance header. Say in the text
-which kind of source it was, so a later run can see why a copy was allowed. A
-pointer alone, with nothing of what the source said, makes the next run open all
-of it again - which is the reading the memory was supposed to buy.
+pointer node per source `INFORMED`ing it. And a passage from a pinned source
+does not go stale silently, so it may be kept whole, as described for indexes
+above.
 
 A body or a result set may still be worth keeping as a SPECIMEN - a shape to
 write against, a case to reproduce. Commit it as a `file` node whose text says