@zenera/cli 1.1.11 → 1.1.14

package/dist/tui/app.js

@@ -35,9 +35,9 @@ function Row({ line }) {
     const style = useTheme().line[line.kind];
     return (_jsxs(Box, { flexDirection: "row", marginTop: line.kind === 'you' ? 1 : 0, children: [_jsxs(Text, { color: style.color, dimColor: style.dim, children: [MARK[line.kind], ' '] }), _jsxs(Box, { flexDirection: "column", children: [line.kind === 'agent' ? (_jsx(Answer, { text: line.text })) : (
                     // The lead is what the eye scans for down the left edge, so
-                    // it keeps the row's colour without its dimming. Nested
+                    // it carries the weight the row's text does not. Nested
                     // rather than one string: Ink dims a whole Text or none of it.
-                    _jsxs(Text, { children: [line.lead ? _jsx(Text, { color: style.color, children: `${line.lead} ` }) : null, _jsx(Text, { color: style.color, dimColor: style.dim, bold: line.kind === 'you', children: line.text })] })), line.detail ? _jsx(Text, { dimColor: true, children: line.detail }) : null] })] }));
+                    _jsxs(Text, { children: [line.lead ? _jsx(Text, { color: style.color, bold: true, children: `${line.lead} ` }) : null, _jsx(Text, { color: style.color, dimColor: style.dim, bold: line.kind === 'you', children: line.text })] })), line.detail ? _jsx(Text, { dimColor: true, children: line.detail }) : null] })] }));
 }
 function Answer({ text }) {
     const { stdout } = useStdout();
@@ -511,11 +511,13 @@ function branchBoxesOf(tools, branches, now, width, lane, share) {
             }),
             // Between the calls it made and the one it is making: the reasoning
             // is what got it from one to the other.
-            ...(gist ? [{ key: `g:${b.name}`, label: `… ${gist}`, detail: '', past: true }] : []),
+            ...(gist
+                ? [{ key: `g:${b.name}`, label: `… ${gist}`, detail: '', thinking: true }]
+                : []),
             ...live,
         ];
         if (!rows.length) {
-            rows.push({ key: `w:${b.name}`, label: 'thinking…', detail: '', past: false });
+            rows.push({ key: `w:${b.name}`, label: 'thinking…', detail: '', thinking: true });
         }
         boxes.push({
             name: b.name,
@@ -572,18 +574,19 @@ function fitActivity(boxes, trunk, allowance) {
     };
 }
 function Branches({ boxes, spin, columns, }) {
+    const theme = useTheme();
     return (_jsx(Box, { flexDirection: "column", children: boxes.map((b) => {
             // Ink truncates rather than wraps, so an over-wide rule clips
             // instead of costing the box a row it was not given.
             const used = 3 + b.title.length + 2 + 2 + b.stats.length + 1;
-            return (_jsxs(Box, { flexDirection: "column", height: BOX_CHROME + b.rows.length, children: [_jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { dimColor: true, children: '╭─ ' }), _jsx(Text, { color: b.color, children: b.title }), _jsx(Text, { color: b.color, children: ` ${spin}` }), _jsx(Text, { dimColor: true, children: `  ${b.stats} ` }), _jsx(Text, { dimColor: true, children: '─'.repeat(Math.max(0, columns - used)) })] }), b.rows.map((r) => (_jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { color: b.color, children: '│ ' }), _jsx(Text, { dimColor: true, children: r.label }), _jsx(Text, { dimColor: true, children: r.detail })] }, r.key))), _jsx(Text, { dimColor: true, children: '╰─' })] }, b.name));
+            return (_jsxs(Box, { flexDirection: "column", height: BOX_CHROME + b.rows.length, children: [_jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { dimColor: true, children: '╭─ ' }), _jsx(Text, { color: b.color, children: b.title }), _jsx(Text, { color: b.color, children: ` ${spin}` }), _jsx(Text, { dimColor: true, children: `  ${b.stats} ` }), _jsx(Text, { dimColor: true, children: '─'.repeat(Math.max(0, columns - used)) })] }), b.rows.map((r) => (_jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { color: b.color, children: '│ ' }), _jsx(Text, { color: r.thinking ? theme.thinking.color : undefined, dimColor: r.thinking ? theme.thinking.dim : undefined, children: r.label }), _jsx(Text, { dimColor: true, children: r.detail })] }, r.key))), _jsx(Text, { dimColor: true, children: '╰─' })] }, b.name));
         }) }));
 }
 function Activity({ rows, hidden, }) {
     if (!rows.length && !hidden) {
         return null;
     }
-    return (_jsxs(Box, { flexDirection: "column", height: rows.length + (hidden ? 1 : 0), overflow: "hidden", children: [rows.map((r) => (_jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { dimColor: true, children: '  ' }), _jsx(Text, { color: r.color, dimColor: r.color === undefined, children: r.label }), _jsx(Text, { dimColor: true, children: r.detail })] }, r.key))), hidden ? (_jsx(Text, { dimColor: true, children: `  + ${hidden} more ${hidden === 1 ? 'branch' : 'branches'}` })) : null] }));
+    return (_jsxs(Box, { flexDirection: "column", height: rows.length + (hidden ? 1 : 0), overflow: "hidden", children: [rows.map((r) => (_jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { dimColor: true, children: '  ' }), _jsx(Text, { color: r.color, children: r.label }), _jsx(Text, { dimColor: true, children: r.detail })] }, r.key))), hidden ? (_jsx(Text, { dimColor: true, children: `  + ${hidden} more ${hidden === 1 ? 'branch' : 'branches'}` })) : null] }));
 }
 /**
  * A stable colour per branch, handed out in order of first sight. Held in a ref
@@ -635,11 +638,13 @@ function Thinking({ text, columns, rows, spin, live, }) {
     // Ink truncates rather than wraps, so an over-wide rule clips instead of
     // costing the block a row it was not given.
     const dashes = Math.max(0, columns - TITLE.length - (live ? 6 : 4));
-    return (_jsxs(Box, { flexDirection: "column", height: shown.length + THINKING_CHROME, overflow: "hidden", children: [_jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { dimColor: true, children: '╭─ ' }), _jsx(Text, { dimColor: true, children: TITLE }), live ? _jsx(Text, { color: theme.warn, children: ` ${spin}` }) : null, _jsx(Text, { dimColor: true, children: ` ${'─'.repeat(dashes)}` })] }), shown.map((row, i) => {
-                // Not italic: dim italic on a dark terminal is the least
-                // legible thing available, and this is meant to be read.
+    const { color, dim } = theme.thinking;
+    return (_jsxs(Box, { flexDirection: "column", height: shown.length + THINKING_CHROME, overflow: "hidden", children: [_jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { dimColor: true, children: '╭─ ' }), _jsx(Text, { color: color, children: TITLE }), live ? _jsx(Text, { color: color, children: ` ${spin}` }) : null, _jsx(Text, { dimColor: true, children: ` ${'─'.repeat(dashes)}` })] }), shown.map((row, i) => {
+                // Not italic, and not dim: dim italic on a dark terminal is the
+                // least legible thing available, and this is meant to be read.
+                // Its own hue is what separates it from the tool rows instead.
                 const head = HEADING.exec(row);
-                return (_jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { dimColor: true, children: '│ ' }), _jsx(Text, { dimColor: true, bold: head !== null, children: head ? head[1] : row })] }, i));
+                return (_jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { color: color, children: '│ ' }), _jsx(Text, { color: color, dimColor: dim, bold: head !== null, children: head ? head[1] : row })] }, i));
             }), _jsx(Text, { dimColor: true, children: '╰─' })] }));
 }
 function Live({ text, columns, rows }) {
@@ -679,7 +684,10 @@ function Footer({ agent, busy, spin, running, forked, step, model, stats, inflig
                     : 'thinking';
     // A clip has already ended it with one.
     const status = what.endsWith('…') ? what : `${what}…`;
-    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { children: [_jsx(Text, { color: theme.accent, dimColor: true, children: agent }), busy ? (_jsxs(Text, { color: theme.warn, children: ['  ', spin, " ", status] })) : null, busy ? _jsx(Text, { dimColor: true, children: `  ${aside}` }) : null] }), inflight ? (_jsxs(Text, { dimColor: true, children: ['this turn'.padEnd(LABEL), tokens(inflight.usage), ` · ${secs(inflight.durationMs)}`] })) : (_jsxs(_Fragment, { children: [stats.turn ? (_jsxs(Text, { dimColor: true, children: ['last turn'.padEnd(LABEL), tokens(stats.turn), stats.durationMs === undefined
+    // Nothing of its own in flight means the word above is about reasoning, so
+    // it takes the same hue the reasoning block does.
+    const musing = !running.length && !forked;
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { children: [_jsx(Text, { color: theme.accent, children: agent }), busy ? (_jsxs(Text, { color: musing ? theme.thinking.color : theme.warn, children: ['  ', spin, " ", status] })) : null, busy ? _jsx(Text, { dimColor: true, children: `  ${aside}` }) : null] }), inflight ? (_jsxs(Text, { dimColor: true, children: ['this turn'.padEnd(LABEL), tokens(inflight.usage), ` · ${secs(inflight.durationMs)}`] })) : (_jsxs(_Fragment, { children: [stats.turn ? (_jsxs(Text, { dimColor: true, children: ['last turn'.padEnd(LABEL), tokens(stats.turn), stats.durationMs === undefined
                                 ? ''
                                 : ` · ${durationOf(stats.durationMs) ?? ''}`] })) : null, _jsxs(Text, { dimColor: true, children: ['session'.padEnd(LABEL), tokens(stats.session), stats.calls
                                 ? ` · ${stats.calls} ${stats.calls === 1 ? 'call' : 'calls'}`

package/dist/tui/theme.d.ts

@@ -13,6 +13,13 @@ export interface Theme {
     readonly accent: string;
     /** Read-only badge, busy label. */
     readonly warn: string;
+    /**
+     * Reasoning. It is not a tool call and it is not the answer, and drawn in
+     * the same dim foreground as the rows around it there was nothing to say
+     * which — a wall of one weight reads as one thing. Its own hue is what
+     * separates the model's thinking from the work it went on to do.
+     */
+    readonly thinking: LineStyle;
     /**
      * Branch colours, cycled in order of first sight. A fan-out is the one
      * place where colour carries information rather than decoration: eight

package/dist/tui/theme.js

@@ -4,8 +4,8 @@
 // A terminal already has a colour scheme, and it is not ours to replace. The
 // rule here is to name as few colours as possible and to name them by role:
 // the answer is drawn in the terminal's *own* foreground (no colour at all),
-// asides are drawn dim, and only the few things that must stand out —
-// the person's own turn, the agent name, a warning, an error — take a colour.
+// and only the few things that must stand out — the person's own turn, the
+// agent name, what it is reasoning about, a warning, an error — take a colour.
 //
 // That alone fixes most of it. `white` was the bug: it is legible on exactly
 // one kind of background, and half the world runs the other kind. `gray` was
@@ -13,6 +13,11 @@
 // unreadable on dark and invisible on paper. What is left is the handful of
 // accents that ANSI *does* let a light theme get wrong, so those swap.
 //
+// Dim is spent on *chrome* — box rules, clocks, the footer's numbers — and no
+// longer on content. Tool rows are most of what is on screen, and dimming them
+// put the bulk of the transcript one step from unreadable: the whole thing read
+// as too dark. They are content, so they get the foreground like content does.
+//
 // Note what is *not* here: no hex, no 256-colour ramps, no attempt at a brand.
 // A palette that ignores the user's scheme is worse on both schemes than one
 // that mostly defers to it.
@@ -22,16 +27,17 @@ const DARK = {
     line: {
         you: { color: 'cyan' },
         agent: {},
-        // Dim alone, never dim *and* `gray`: bright black is already the
-        // faintest colour a terminal has, and dimming it again puts the bulk
-        // of the transcript a step from unreadable.
-        tool: { dim: true },
-        note: { color: 'cyan', dim: true },
+        // Never dim, and never `gray`: bright black is already the faintest
+        // colour a terminal has, and either one puts the bulk of the
+        // transcript a step from unreadable.
+        tool: {},
+        note: { color: 'cyan' },
         error: { color: 'red' },
     },
     accent: 'cyan',
     warn: 'yellow',
-    lanes: ['magenta', 'cyan', 'green', 'yellow', 'blue', 'red'],
+    thinking: { color: 'magenta' },
+    lanes: ['cyan', 'green', 'yellow', 'blue', 'red', 'magenta'],
 };
 // On a light background `cyan` and `yellow` are barely darker than the paper.
 // Dimmed default foreground and `blue`/`magenta` are the same information,
@@ -41,14 +47,15 @@ const LIGHT = {
     line: {
         you: { color: 'blue' },
         agent: {},
-        tool: { dim: true },
-        note: { color: 'blue', dim: true },
+        tool: {},
+        note: { color: 'blue' },
         error: { color: 'red' },
     },
     accent: 'blue',
     warn: 'magenta',
+    thinking: { color: 'magenta' },
     // No cyan or yellow: on paper they are barely darker than the paper.
-    lanes: ['magenta', 'blue', 'green', 'red'],
+    lanes: ['blue', 'green', 'red', 'magenta'],
 };
 export const THEMES = { dark: DARK, light: LIGHT };
 export function parseChoice(value) {

package/package.json

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

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
@@ -1031,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":
@@ -1601,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.
 
 ---
 
@@ -1630,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
@@ -1674,35 +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                            |
-| 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                           |
+| 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                           |
 
 ---
 
@@ -1715,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,

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`.

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/memory.md

@@ -0,0 +1,113 @@
+# Memory — `zen memory`
+
+```
+zen memory [stats|ls|show|export|forget] [args] [options]
+```
+
+Alias: `mem`.
+
+The memory graph from outside the agents. It exists to answer the question
+memory always eventually raises: **why did it recall that?**
+
+Only projects that enable memory have one, and the commands say so rather than
+inventing an empty graph. Turning it on is the `memory:` block in `agents.yaml`.
+
+This document is the command. For how the graph is organised, how to configure
+it, and how to decide what an agent should remember, read the `zen-memory`
+skill.
+
+## Subcommands
+
+| Command                   | What it does                                |
+| ------------------------- | ------------------------------------------- |
+| `zen memory stats`        | Size, vocabulary, whether it is embedded    |
+| `zen memory ls`           | Nodes, newest first. Changes nothing        |
+| `zen memory show <id>`    | One node in full, with what it links to     |
+| `zen memory export [f]`   | The whole graph as one HTML page            |
+| `zen memory forget <id…>` | Remove nodes, their vectors and their files |
+
+| Flag                    | Meaning                                      |
+| ----------------------- | -------------------------------------------- |
+| `--project <name\|dir>` | Which project. Inferred from the directory   |
+| `--kind <name>`         | Only this kind of node                       |
+| `--audience <name>`     | Only nodes committed under this label        |
+| `--files`               | Only nodes that remember a file              |
+| `--stale`               | Only nodes something has superseded          |
+| `--limit <n>`           | Rows to list. Default 30                     |
+| `--out <file>`          | Where `export` writes. Default `memory.html` |
+| `--open`                | Open the exported page                       |
+| `--yes`                 | Do not ask before removing                   |
+
+## It reads unmasked, on purpose
+
+Memory is masked per agent: a node's `audience` decides who can see it. Recall
+is masked, ranked and truncated as well, so what an agent gets is never the
+whole picture.
+
+This command ignores all of that. When the mask is the thing that is wrong, the
+part that was hidden is exactly the part you need — and this is a person at a
+terminal in the project directory, not an agent inside a run.
+
+It also contacts no model. The store is opened without an embedder, so
+inspection is free and works offline; the price is that `ls` filters by text
+rather than by meaning.
+
+## `export` is the one to reach for
+
+```sh
+zen memory export --open
+```
+
+One self-contained HTML file, three panes:
+
+- **left** — every node, with a search box and filters for kind, audience,
+  files, superseded and unlinked
+- **middle** — the graph as a Mermaid diagram, coloured by kind, with pan,
+  zoom, and a hop-focus selector for following one node's neighbourhood
+- **right** — whatever you clicked, in full: the text, the metadata, the links,
+  and **the remembered file's actual content** — rendered as an image when it is
+  one, and as text otherwise
+
+Clicking a node in either the list or the diagram selects it in both. Above 300
+drawn nodes the diagram asks you to narrow it with the filters, because a
+Mermaid graph that large is not a picture of anything.
+
+It is a single file with no server behind it, so it attaches to a bug report.
+The only network it does is fetching Mermaid; without that it degrades to a
+working list and detail view.
+
+## Forgetting
+
+```sh
+zen memory forget 01M1YPN0C8QRQS5BCZ03ABQ1G0
+```
+
+Asks first, unless `--yes`, and refuses outright when there is no terminal to
+ask at. A node, its vector row and its remembered file bytes go together —
+there is one implementation of that, shared with the agent-facing tool, so the
+three cannot drift apart.
+
+**Forgetting is rarely the right correction.** The agents' own way to fix a
+wrong memory is to commit the corrected node and supersede the old one, which
+keeps the record of having been wrong. `zen memory ls --stale` lists what has
+been superseded that way. Use `forget` for what should never have been stored —
+a secret, a mistake, a pile of noise — not for what merely became untrue.
+
+## Reading `stats`
+
+```
+nodes       7
+edges       6
+superseded  1
+files       1 · 640 B
+embedding   none — recall falls back to term overlap
+vectors     —
+```
+
+`embedding none` is worth noticing: without an embedder, recall matches on
+shared terms rather than on meaning, which works but is much blunter. Set
+`memory.embedding` in `agents.yaml` to change it.
+
+A vector count lower than the node count means some nodes were committed while
+no embedder was configured, and they will only ever be found by term overlap
+until they are re-embedded.