@zenera/cli 1.1.10 → 1.1.12

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

@@ -141,8 +141,9 @@ my-project/
 │           ├── SKILL.md
 │           └── scripts/calculate.py   run at /skills/refund_policy/scripts — §3.4.1
 ├── assets/                       reference material, read-only at /assets
+├── memory/                       the graph agents remember into — §5.3
 ├── sandbox/Dockerfile            the image commands run in — §3.7
-└── sessions/                     run state, memory, whatever the agent wrote
+└── sessions/                     run state, whatever the agent wrote
 ```
 
 Only `agents.yaml` is required, and only `agents:` is required inside it.
@@ -224,6 +225,81 @@ agents do, for the same reason — it is a prefix somebody pays for:
 hand, so **edits inside `.github/` do not survive**. Project-specific conventions
 belong in `INSTRUCTIONS.md` and the agent prompts, which are never overwritten.
 
+### 2.5 What a running agent can actually see
+
+The tree in §2.1 is the **author's** view. A running agent sees almost none of
+it. Its entire world is the tools it was granted (§3.5) and four paths:
+
+| Path         | Is                                        | Access                                                 |
+| ------------ | ----------------------------------------- | ------------------------------------------------------ |
+| `/workspace` | the session's workspace — the work itself | read/write; `zen run --read-only` withholds the writes |
+| `/assets`    | `assets/`, reference material — §3.11     | read-only                                              |
+| `/skills`    | the whole skill catalog — §3.4.1          | read-only                                              |
+| `/memory`    | files carried by remembered nodes — §5.3  | read-only, and only when `memory:` is configured       |
+
+Commands run inside the container `sandbox:` describes (§3.7): the same
+`/workspace`, and whatever the image ships.
+
+Everything else in the project directory is **invisible at run time** —
+`agents.yaml`, `INSTRUCTIONS.md`, `agents/prompts/`, `agents/skills/` under that
+name, `sandbox/Dockerfile`, `.env`, `.github/`, `sessions/`, and the project
+root itself. `zen` reads them to build the run; they are never a path an agent
+can open.
+
+Two consequences:
+
+- **The workspace is not the project.** It defaults to the session's own empty
+  folder, and is usually some other repository entirely — `--workspace`, or the
+  directory the user was standing in. A prompt saying "read `agents.yaml`" or
+  "the rules are in `agents/skills/`" names a file that is not there.
+- **Write the mount path, never the repository path.**
+  `/skills/refund_policy/rates.csv`, not
+  `agents/skills/refund_policy/rates.csv`; `/assets/handbook.md`, not
+  `assets/handbook.md`. A relative path resolves against `/workspace`, which is
+  the one place the file is not.
+
+An agent that must know something about its own configuration is **told it in
+prose**, in the prompt — never sent to read the file that configured it.
+
+#### Checklist — no path an agent cannot open
+
+Run this over `INSTRUCTIONS.md`, every `agents/prompts/*.md` and every
+`agents/skills/*/SKILL.md` after editing any of them. Every path-shaped token in
+those files is read by a model as an instruction to open something:
+
+- [ ] Every absolute path begins `/workspace`, `/assets`, `/skills` or
+      `/memory`. Nothing else exists.
+- [ ] No project file is named: `agents.yaml`, `INSTRUCTIONS.md`,
+      `agents/prompts/…`, `agents/skills/…`, `sandbox/Dockerfile`, `.env`,
+      `.github/…`, `sessions/…`, `SPECIFICATION.md`, `README.md`, `docs/…`.
+- [ ] Nothing escapes a mount: no `../`, no `~`, no host path (`/Users/…`,
+      `/home/<someone>`), no `/etc`, `/var` or `/tmp` expected to hold anything
+      the project put there.
+- [ ] Each `/assets/…` and `/skills/<name>/…` path names a file that is actually
+      committed there — `zen check` lists what every skill folder ships (§3.4.1).
+- [ ] A skill referring to its own sibling file writes the full
+      `/skills/<name>/` prefix, not `./rates.csv`: the body is rendered into a
+      prompt, not executed from its folder.
+- [ ] `/memory` is named only in prompts for agents that have `memory:` (§5.3),
+      and `/assets` only where an `assets/` directory exists.
+- [ ] The agent holding the prompt has the tool the path implies — `read_file`
+      to open one, `sandbox:*` to run one (§3.4.1).
+- [ ] Every instruction that opens a file states what to do when it is not there
+      (§4.2, rule 6). Workspaces differ between runs; absence is normal.
+- [ ] Relative paths appear only where `/workspace`-relative is what was meant.
+
+Finding the candidates, from the project root — every path-shaped token in the
+three trees, minus the ones under a mount:
+
+```sh
+grep -Eohr '[~.]?/?[A-Za-z0-9_.-]*/[A-Za-z0-9_.*-]+' \
+     INSTRUCTIONS.md agents/prompts agents/skills \
+  | sort -u | grep -Ev '^/(workspace|assets|skills|memory)(/|$)'
+```
+
+Everything it prints is either a false positive (a url, a `path/to` in a
+sentence, `and/or`) or a path the agent cannot open. There is no third case.
+
 ---
 
 ## 3. File formats
@@ -307,6 +383,9 @@ wrong provider (§7.3), and any combination of knobs the vendor rejects at reque
 time, such as OpenAI reasoning on chat completions (§7.6). Both surface on the
 first call, so read §7 before writing a `models:` entry.
 
+**Caught by `zen check`, not by the loader** — a handoff with no path back
+(`handoff.one-way`, §6.3). The project runs; it just cannot return.
+
 **Comments in `agents.yaml`** — this file is the architecture diagram of the
 project, and its comments are read by whoever has to change it next. Write them
 at that level:
@@ -1028,22 +1107,38 @@ agents:
 
 ### 5.3 Memory
 
-Memory is the read-write twin of skills: written by the run, not authored. A
-**scope** is a namespace string; agents bound to the same scope share what is
-in it, and the default scope is the agent's own — so memory is private until
-something says otherwise. Recall is automatic: matches for the current input
-are injected before each call, which is what makes memory work without the
-model remembering to look, and an agent with write access also gets tools to
-search, add, update and delete entries.
+Memory is the read-write twin of skills: written by the run, not authored. It is
+a **graph** — a node is one thing worth keeping, an edge says how one led to
+another — so recall returns the connected piece rather than a ranked list, and a
+remembered script arrives with the request that asked for it.
 
-It is a session-level facility rather than an `agents.yaml` key: `zen run`
-binds each session's store under `sessions/`, so memory travels with the
-session and is not part of this repository.
+It is configured in `agents.yaml`: a top-level `memory:` block says where the
+graph lives and what vectorises it, and `agents[].memory` says what each agent
+may do with it. It lives with the **project**, not the session — a memory that
+died with the session would be a cache. Recall is automatic on turns that follow
+new user input, which is what makes memory work without the model remembering to
+look.
+
+```yaml
+memory:
+    embedding: main # without one, recall falls back to term overlap
+agents:
+    - name: auditor
+      memory: true # read, write, and recall before each new question
+```
+
+Every node carries an **audience**, and an agent's `sees` is the set it reads:
+one graph, masked per agent, never one graph each. The four `memory_*` tools are
+derived from `access` and are never listed in `tools:`.
 
 Do not treat memory as a database. It is for things learned that should
 persist. Anything authoritative — a rate, a policy clause, a procedure — belongs
 in a skill, where it is versioned and reviewable.
 
+The full treatment — kinds and relations, how ranking and stitching spend their
+budget, remembered files under `/memory`, audience design, and how to put memory
+in front of a `zen rag` index — is in the `zen-memory` skill.
+
 ### 5.4 Cache discipline
 
 Rules that follow directly from "stable prefix = cache hit":
@@ -1086,18 +1181,20 @@ Do **not** split because:
 
 **Router + specialists.** A cheap, fast agent whose only job is classification
 and handoff. Its prompt is short, it holds few tools, and it must be forbidden
-from answering. Specialists never hand back to it.
+from answering. Every specialist hands back to it — a handoff does not return on
+its own, so without that edge the first routed question is the last one routed.
 
 ```yaml
 agents:
     - { name: intake, model: router, handoffs: [billing, technical, escalation] }
-    - { name: billing, model: balanced, skills: { allow: [refund_policy, invoicing] } }
-    - { name: technical, model: balanced, tools: [search_logs, restart_service] }
-    - { name: escalation, model: careful }
+    - { name: billing, model: balanced, handoffs: [intake], skills: { allow: [refund_policy] } }
+    - { name: technical, model: balanced, handoffs: [intake], tools: [search_logs] }
+    - { name: escalation, model: careful, handoffs: [intake] }
 ```
 
 **Pipeline.** Fixed stages, each handing to the next; only the last answers the
-user. Encode the order in `handoffs:` so a stage cannot skip ahead.
+user. Encode the order in `handoffs:` so a stage cannot skip ahead — and close
+the loop, by handing back from the last stage to the first.
 
 **Fan-out / join.** For independent parallel work — ten regions, four review
 lenses, six candidate suppliers — declare `fork:` on the agent that owns the
@@ -1113,12 +1210,39 @@ multi-agent instinct suggests.
   Write it as a routing condition: _"Applies the written peril policies to a
   claim and explains the outcome."_ — not _"The adjuster agent."_
 - Handoffs are bare name strings; there is no per-edge configuration.
-- Self-handoff is a load error. Cycles are legal but usually a bug — a router in
-  the `handoffs` of its own specialists produces ping-pong.
+- Self-handoff is a load error.
+- **Every handoff must be returnable.** For every `A → B` there must be a path
+  from `B` back to `A`. Indirect counts — `B → C → A` is a way home — so the
+  rule is that every handoff edge lies on a cycle. `zen check` warns
+  (`handoff.one-way`) on any edge that does not.
 - Handoff collapses history by policy: the receiving agent sees a selection, not
   the full transcript. Do not assume it saw a detail three turns back; if it
   matters, put it in the handoff.
 
+**Why the return edge is not optional.** A handoff is a one-way door: control
+moves and stays moved. Nothing hands it back, so an agent reached by a dead-end
+edge owns the conversation for the rest of the session — the next question,
+whatever it is about, is answered by the specialist the router sent the user to.
+The drawn architecture holds for one turn and then quietly stops being the
+architecture.
+
+**Forks are the exception, and the alternative.** A branch runs, answers, and
+control returns to the agent that forked it; the return is the mechanism, not an
+edge anyone has to declare. So there are two shapes and they are not
+interchangeable:
+
+- The other agent should **own the conversation from here** → `handoffs:`, and
+  something on the far side has to lead back.
+- This agent needs **an answer and then carries on** → `fork:`. Never a handoff:
+  a handoff spends the conversation to get the answer.
+
+But the return is **condensed**: `A → fork → B` rejoins as one tool result
+holding B's answer, so A never sees the steps B took — no tool calls, no files
+read, no intermediate reasoning. That is what makes fanning out cheap, and it is
+what to design around: whatever A will need must be _in_ the answer, so say so in
+B's prompt. Work whose value is the trace rather than the conclusion does not
+survive a fork.
+
 ### 6.4 Forking (fan-out / join)
 
 Forking is **opt-in per agent**. Without the key the agent is never offered the
@@ -1158,7 +1282,9 @@ Rules worth knowing before you write the key:
 - Nesting is capped by the run's `maxForkDepth` (2 by default), so a branch may
   fork again but not without bound.
 - Fork vs handoff: a handoff is _one_ conversation changing owner; a fork is the
-  _same_ question asked N times at once and merged.
+  _same_ question asked N times at once and merged. **A fork returns; a handoff
+  does not** — which is why a handoff needs a return path (§6.3) and a fork
+  needs nothing.
 
 Choose `context:` deliberately — the model sets it per call, so say in the
 agent's prompt which one this work wants:
@@ -1237,8 +1363,8 @@ model: balanced # fallback for agents that do not pin their own
 
 agents:
     - { name: intake, model: router, handoffs: [adjuster] }
-    - { name: adjuster, model: balanced, handoffs: [escalation] }
-    - { name: escalation, model: careful }
+    - { name: adjuster, model: balanced, handoffs: [escalation, intake] }
+    - { name: escalation, model: careful, handoffs: [intake] }
 ```
 
 ### 7.3 Shorthand
@@ -1567,9 +1693,9 @@ zen models pick --embedding    # or --chat; the ref goes to stdout, alone
 Then re-run `zen check`.
 
 CLI (`zen --help` for the authoritative list): `zen init`, `zen run`, `zen check`,
-`zen inspect`, `zen key`, `zen models`, `zen list`. **stdout is the answer, stderr
-is the narration**; every command takes `--json`. Exit codes: `0` ok, `1` failed,
-`2` usage, `3` invalid project, `4` no usable credential.
+`zen inspect`, `zen memory`, `zen key`, `zen models`, `zen list`. **stdout is the
+answer, stderr is the narration**; every command takes `--json`. Exit codes: `0`
+ok, `1` failed, `2` usage, `3` invalid project, `4` no usable credential.
 
 ---
 
@@ -1582,7 +1708,7 @@ Before finishing any change here:
 - [ ] `agents.yaml` still loads; no unknown keys, no dangling names
 - [ ] Top-level `default:` names the entry agent explicitly
 - [ ] Every agent has a `description:` written as a routing condition
-- [ ] No self-handoff; no accidental cycle back to the router
+- [ ] No self-handoff; every handoff has a path back (`zen check` warns if not)
 - [ ] Names match `^[a-z0-9]+(?:[-_][a-z0-9]+)*$`
 - [ ] An agent expected to fan out has `fork:`, and its prompt says when to use it
 - [ ] Comments explain the design, not the runtime or the key they sit above
@@ -1596,6 +1722,16 @@ Before finishing any change here:
 - [ ] No facts, rates or figures embedded in a prompt
 - [ ] No hedging, no meta-talk about the runtime
 
+**Paths (§2.5 — run its checklist over the three trees)**
+
+- [ ] Every absolute path in `INSTRUCTIONS.md`, `agents/prompts/*.md` and
+      `agents/skills/*/SKILL.md` is under `/workspace`, `/assets`, `/skills` or
+      `/memory`
+- [ ] No prompt or skill names a project file — `agents.yaml`, a prompt path, a
+      skill's repository path, `sandbox/Dockerfile`, `.env`, `sessions/`
+- [ ] No `../`, `~`, or host path; nothing assumes the workspace is the project
+- [ ] Every `/assets/…` and `/skills/<name>/…` path names a committed file
+
 **Skills**
 
 - [ ] Every skill is `<name>/SKILL.md` — no bare `<name>.md` in the catalog
@@ -1640,34 +1776,37 @@ Before finishing any change here:
 
 ## 10. Where to change what
 
-| Symptom                                    | Change this                                                         |
-| ------------------------------------------ | ------------------------------------------------------------------- |
-| Wrong tone, wrong format, wrong length     | `INSTRUCTIONS.md` (all agents) or the agent prompt                  |
-| Says something forbidden                   | `INSTRUCTIONS.md` prohibition, stated specifically                  |
-| Ignores a rule that only applies sometimes | Move the rule into a skill with a sharp description                 |
-| Never loads the skill it should            | The skill's `description`; or `preload` it                          |
-| Loads too much, answers slowly             | `allow:`, `maxIndexEntries:`, or `discovery: search`                |
-| Invents a number                           | A skill holding the figure, or a script that computes it — §3.4.1   |
-| A skill in the catalog is never offered    | It is a bare `<name>.md`; move it to `<name>/SKILL.md` — §3.4       |
-| Cannot find a file its own skill names     | Absolute `/skills/<name>/…` path, and `sandbox:*` — §3.4.1          |
-| Rewrites a whole file to change one line   | A prompt line preferring `apply_patch` — §3.6                       |
-| Edits files it should only be reading      | Subtract the mutating tools, or `zen run --read-only`               |
-| Cannot run the build or the tests          | Grant `sandbox:*`; add the toolchain to `sandbox/Dockerfile`        |
-| Installs the same packages on every run    | Put them in `sandbox/Dockerfile`, or `sandbox.persist: true` — §3.7 |
-| Answers from stale knowledge of the world  | Grant `web_search` + `web_read`, and say when — §3.8                |
-| Cites a page it only saw the excerpt of    | A prompt line: `web_read` before quoting — §3.8                     |
-| Every web call refuses                     | No Exa key: `zen key add exa` — `zen check` warns — §3.8            |
-| A model or embedder refuses every call     | `zen models test <ref>` — if `blocked`, `zen models pick` — §8      |
-| Answers instead of routing                 | Router prompt prohibition; check `handoffs:`                        |
-| Routes to the wrong specialist             | The target agents' `description:` fields                            |
-| 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                         |
-| 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                             |
-| Forgets across conversations               | Continue the session rather than starting a new one                 |
-| Breaks at load with a named path           | Read the message — it names the exact key                           |
+| Symptom                                       | Change this                                                         |
+| --------------------------------------------- | ------------------------------------------------------------------- |
+| Wrong tone, wrong format, wrong length        | `INSTRUCTIONS.md` (all agents) or the agent prompt                  |
+| Says something forbidden                      | `INSTRUCTIONS.md` prohibition, stated specifically                  |
+| Ignores a rule that only applies sometimes    | Move the rule into a skill with a sharp description                 |
+| Never loads the skill it should               | The skill's `description`; or `preload` it                          |
+| Loads too much, answers slowly                | `allow:`, `maxIndexEntries:`, or `discovery: search`                |
+| Invents a number                              | A skill holding the figure, or a script that computes it — §3.4.1   |
+| A skill in the catalog is never offered       | It is a bare `<name>.md`; move it to `<name>/SKILL.md` — §3.4       |
+| Cannot find a file its own skill names        | Absolute `/skills/<name>/…` path, and `sandbox:*` — §3.4.1          |
+| Tries to open `agents.yaml` or its own prompt | The prompt names a file no agent can see — §2.5                     |
+| Says a file is missing that is in the project | The workspace is not the project directory — §2.5                   |
+| Rewrites a whole file to change one line      | A prompt line preferring `apply_patch` — §3.6                       |
+| Edits files it should only be reading         | Subtract the mutating tools, or `zen run --read-only`               |
+| Cannot run the build or the tests             | Grant `sandbox:*`; add the toolchain to `sandbox/Dockerfile`        |
+| Installs the same packages on every run       | Put them in `sandbox/Dockerfile`, or `sandbox.persist: true` — §3.7 |
+| Answers from stale knowledge of the world     | Grant `web_search` + `web_read`, and say when — §3.8                |
+| Cites a page it only saw the excerpt of       | A prompt line: `web_read` before quoting — §3.8                     |
+| Every web call refuses                        | No Exa key: `zen key add exa` — `zen check` warns — §3.8            |
+| A model or embedder refuses every call        | `zen models test <ref>` — if `blocked`, `zen models pick` — §8      |
+| Answers instead of routing                    | Router prompt prohibition; check `handoffs:`                        |
+| Routes to the wrong specialist                | The target agents' `description:` fields                            |
+| Gets stuck in the agent it routed to          | The target needs a handoff back — §6.3                              |
+| 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                         |
+| 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                             |
+| Forgets across conversations                  | Continue the session rather than starting a new one                 |
+| Breaks at load with a named path              | Read the message — it names the exact key                           |
 
 ---
 
@@ -1680,6 +1819,10 @@ Before finishing any change here:
   versioned, cannot be shared, and is paid for on every call.
 - **The bare skill file.** `agents/skills/<name>.md` instead of a folder. It can
   never grow the table or script the next revision of the rule will want — §3.4.
+- **Pointing an agent at the project.** A prompt or skill naming `agents.yaml`,
+  `INSTRUCTIONS.md`, `agents/skills/<name>/…` or `sandbox/Dockerfile`. None of
+  them are on any path the agent can open, so the instruction fails on the turn
+  that follows it — §2.5.
 - **Arithmetic in prose.** A skill that walks the model through a calculation it
   will get wrong, in a folder that could have held the script — §3.4.1.
 - **Politeness padding.** "Please try your best to be helpful." Costs tokens,
@@ -1689,8 +1832,10 @@ Before finishing any change here:
 - **Fixing prompts with models.** See §4.4.
 - **The chatty router.** A router that answers before handing off, because its
   prompt never forbade it.
-- **Ping-pong handoffs.** Specialists that hand back to the router, which hands
-  back to a specialist.
+- **The one-way handoff.** A specialist with no way back, so the router routes
+  once and then never sees the conversation again — §6.3.
+- **Handing off for an answer.** Wanting one lookup and spending the whole
+  conversation on it. That is a `fork:`, which returns by itself — §6.4.
 - **Forking a chain.** Branches never see each other, so a fork whose second
   branch needs the first branch's answer is a sequence wearing a fork's clothes.
 - **Installing the toolchain every run.** A prompt that begins with `apt-get

package/templates/editor/.github/prompts/new-agent.prompt.md

@@ -29,8 +29,11 @@ If it is warranted:
 3. Add the `agents.yaml` entry. `description:` is written **for the model** — it
    is the whole of what a sibling sees when deciding to hand off. Grant the
    narrowest `tools:` the job needs.
-4. Wire the handoffs in both directions only if both directions are real.
-   Specialists handing back to a router is ping-pong; prefer terminating.
+4. Wire the return edge. A handoff does not come back on its own, so every
+   `A → B` needs a path from B back to A — directly, or through another agent.
+   `zen check` warns on an edge that has none. If what this agent really wants
+   is an _answer_ rather than to give up the conversation, declare `fork:`
+   instead: a branch returns by itself.
 5. Add a one-line comment above the entry saying why this agent exists — its
    job or its tier, not what the keys mean.
 

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

@@ -17,6 +17,11 @@ Work the checklist in §9 of the copilot instructions. In particular:
   `INSTRUCTIONS.md` that is true of only one agent.
 - **Facts.** Any number, threshold, fee or date living in a prompt is in the
   wrong file. Name it and say which skill it belongs in.
+- **Paths.** Work the checklist in §2.5 over `INSTRUCTIONS.md`,
+  `agents/prompts/*.md` and `agents/skills/*/SKILL.md`. Every absolute path must
+  be under `/workspace`, `/assets`, `/skills` or `/memory`; nothing may name a
+  project file the agent cannot open, and nothing may assume the workspace is
+  this directory.
 - **Skill descriptions.** Each one a condition, not a title; no two overlapping.
 - **Tools.** Every grant justified by the agent's job; nothing mutating held by
   an agent that only reads; every granted tool mentioned by the prompt.

package/templates/editor/.github/prompts/sync-with-spec.prompt.md

@@ -98,16 +98,19 @@ not a paragraph of instructions for a human.
 - `scripts/_setup.sh` is the **only** entry point — the leading underscore is
   what separates the runner from the steps it runs. It runs the steps in the
   order they depend on each other and is the single command that initialises the
-  project. Consolidate any setup script that lives elsewhere into this shape,
-  including one left at the project root.
+  project. `zen init` writes it; adding a step is adding `scripts/<name>.sh` and
+  its name to the `STEPS` list at the top of it. Consolidate any setup script
+  that lives elsewhere into this shape, including one left at the project root.
 - Every script starts `set -eu`, works from any working directory
   (`cd "$(dirname "$0")/.."` first), needs no arguments, and exits non-zero on
   failure so `scripts/_setup.sh` stops rather than continuing on a broken step.
 - **Re-entrancy is required.** Running `scripts/_setup.sh` a second time must be
   safe. A step whose output is present and newer than its inputs prints that it
-  is up to date and returns 0; otherwise it redoes the work idempotently, writing
+  is up to date and exits **3**, which is how the runner tells `skipped` from
+  `ok`; otherwise it redoes the work idempotently, writing
   to a temporary path and moving it into place so an interrupted run never leaves
-  a half-built artefact behind. `scripts/_setup.sh --force` redoes everything.
+  a half-built artefact behind. `scripts/_setup.sh --force` redoes everything,
+  and reaches each step as `$FORCE=1`.
 - **It must be watchable.** `scripts/_setup.sh` tees each step's output to
   `.tmp/logs/setup-<step>.log`, prints a heartbeat line while a long step runs,
   and finishes with one line per step: `ok`, `skipped`, or `failed`.
@@ -170,6 +173,10 @@ It is slow — an embedding index is minutes, not seconds — so start it in the
 background and follow the logs instead of waiting blind:
 
 - Tail `.tmp/logs/setup-*.log` and check the output artefact is still growing.
+- **Wait in a loop, never in one long sleep.** Sleep at most 30 seconds at a
+  time, then check the log and say what it shows, and repeat until the step
+  finishes. A single long block makes the run unwatchable and hides a failure
+  that happened in the first ten seconds.
 - Report progress as you go: which step is running, how long it has been going,
   what the last log line said.
 - Do not kill a quiet step. Confirm the process is dead or the log and the

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

@@ -24,6 +24,7 @@ zen key      <ls|add|use|check|rm|show|env> [ref] [options]
 zen models   <providers|ls|search|show|test|pick> [ref] [options]
 zen check    [name|dir] [--project <name|dir>] [--no-sandbox] [--no-models] [--strict] [--quiet]
 zen inspect  [run] [--session <id>] [--open] [--rebuild] [--serve [port]]
+zen memory   [stats|ls|show|export|forget] [args] [options]
 zen sandbox  [status|up|pull|clean|disk] [options]
 zen version
 
@@ -48,6 +49,7 @@ guess a flag, and do not read them all.
 | Which models exist, whether one works, recovering from a refusal    | [models.md](./references/models.md)     |
 | The container shell commands run in, images, `persist`              | [sandbox.md](./references/sandbox.md)   |
 | Run reports, trajectories, what a session directory holds           | [inspect.md](./references/inspect.md)   |
+| What the agents remember, why something was recalled, forgetting    | [memory.md](./references/memory.md)     |
 | `zen faker` — a mock API from an OpenAPI/Swagger document           | [faker.md](./references/faker.md)       |
 | `zen rag` — searching an API description, or a pile of markdown     | [rag.md](./references/rag.md)           |
 
@@ -59,6 +61,7 @@ zen check                             validate everything before spending a turn
 zen run                               the TUI
 zen run "what changed?"               one answer, this directory as the workspace
 zen inspect --open                    what the model was actually given
+zen memory export --open              the whole memory graph, as a page
 zen key ls --check                    which credentials still work
 zen models test <ref>                 whether one model actually answers
 zen models pick --embedding           the first embedder that does, on stdout

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

@@ -91,17 +91,27 @@ Probes are synthetic on purpose — real request bodies never reach a prompt.
 
 ## The cache
 
-Under `~/.zenera/neo/faker/generators/<key>/`, one directory per operation. A
-generator that a model gave up on is remembered, so a hopeless operation is not
-re-asked on every request; a _transient_ failure — a 429, a dropped socket — is
-not, because it is about this minute rather than this operation.
-
-`zen faker cache clear` removes the generators and the container together. They
-have to go together: the container's name is a hash of its configuration, so
-deleting the directory alone would leave a stopped container bind-mounted onto a
+Generators live in the machine's shared cache, `~/.zenera/neo/cache/faker-generator/`,
+keyed by the operation's shape — so the same spec served from two directories is
+written once, and a spec edit produces a new key rather than a stale answer. A
+generator that a model gave up on is remembered for the life of the process, so
+a hopeless operation is not re-asked on every request; a _transient_ failure — a
+429, a dropped socket — is not, because it is about this minute rather than this
+operation.
+
+`~/.zenera/neo/faker/` is the container's workspace, and scratch: a cache hit is
+copied into it, because the container can only run what is under its mount.
+
+`zen faker cache ls` lists what has been generated. `zen faker cache clear`
+removes the generators, the workspace and the container together. They have to
+go together: the container's name is a hash of its configuration, so deleting
+the workspace alone would leave a stopped container bind-mounted onto a
 directory that no longer exists, and every generator would fail with
 `python3: can't open file '/workspace/generators/…/gen.py'`.
 
+`zen cache ls --kind faker-generator` reaches the same entries from the other
+side, along with everything else this machine has cached.
+
 ## Documents it accepts
 
 Swagger 2 and OpenAPI 3.0/3.1, JSON or YAML, `$ref`s resolved. Several documents

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

@@ -25,8 +25,8 @@ keys; one of them is active.
 | `zen key show <ref> [--reveal]`   | Masked by default                       |
 | `zen key env [provider …]`        | Shell exports, for other tools          |
 
-`zen key add` also takes `--project` and `--location`, for a Vertex service
-account.
+`zen key add` also takes `--gcp-project` and `--gcp-location`, for a Vertex
+service account.
 
 ```
 zen key add openai                    # prompts, echo off
@@ -56,18 +56,18 @@ echo-off prompt and from nowhere else.
 
 A **service-account file** is absorbed into `~/.zenera/neo/keys/` and
 `GOOGLE_APPLICATION_CREDENTIALS` points at it. It wants a project too, from
-`--project`, or `GOOGLE_CLOUD_PROJECT`, or the `project_id` inside the file, and
-a region from `--location` (`global` otherwise). Application Default
+`--gcp-project`, or `GOOGLE_CLOUD_PROJECT`, or the `project_id` inside the file,
+and a region from `--gcp-location` (`global` otherwise). Application Default
 Credentials from `gcloud auth application-default login` work with no entry at
 all.
 
 An **express-mode key** is an ordinary secret under `VERTEX_API_KEY`, and
 addresses no project: a key and a project are alternatives, and sending both
-gets a `403` that mentions neither. `--project` and `--location` are therefore
-refused alongside a key.
+gets a `403` that mentions neither. `--gcp-project` and `--gcp-location` are
+therefore refused alongside a key.
 
 ```
-zen key add vertex --project acme-prod --location europe-west4
+zen key add vertex --gcp-project acme-prod --gcp-location europe-west4
 # paste a path  → the file shape
 # paste a key   → the express shape
 ```