@zenera/cli 1.1.17 → 1.1.18

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

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

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

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

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

@@ -197,8 +197,9 @@ below.
 └── .lock           held while a run is writing; a dead pid's lock is stale
 ```
 
-It is project state, not source, and it is not committed. The directory is
-mounted **read-only** at `/memory` in the agent's namespace.
+It is committed with the project - everything but `.lock`, which is runtime
+state. The directory is mounted **read-only** at `/memory` in the agent's
+namespace.
 
 ## Designing a memory strategy
 
@@ -363,6 +364,40 @@ lands at `<project>/memory/files/<id>.<ext>` and appears to the agent as:
 | Mount     | `/memory`, **read-only**                                         |
 | Extension | preserved, because it decides how the file runs and renders      |
 
+### The agent has to be able to write the file first
+
+`memory_commit` **copies** a file that already exists. It is not an upload
+channel and it cannot create one. So everything too big for a node's `text` - a
+script, a config, an assembled passage - depends on the agent having a tool that
+puts bytes in the **workspace**, and an agent with none can only ever commit
+text no matter how much the memory design leans on `file` nodes.
+
+| The agent's `tools:`         | Can it commit a `file`?                                                 |
+| ---------------------------- | ----------------------------------------------------------------------- |
+| `write_file` / `apply_patch` | Yes. Write it, then name the same path                                  |
+| `run_command` only           | Yes, but only under `/workspace` - a heredoc into `/tmp` is unreachable |
+| Neither                      | No. Everything worth keeping has to fit on one line of `text`           |
+
+The workspace is the only tree that round-trips, because it is the only
+writable one. `/assets`, `/skills` and `/memory` resolve as well - they are
+mounts the file tools know by name - but they are **read-only**, so nothing can
+be put there to be remembered. Every other absolute path is real to
+`run_command` and outside the workspace root, so a file written to `/tmp` comes
+back as:
+
+```
+error: outside the workspace: /tmp/report.py
+```
+
+A bare error carrying none of the `hint` the other memory refusals do, because
+containment is a workspace answer rather than a memory one.
+
+This is the trap in a `tools:` list trimmed to `run_command` alone: the shell
+can create the file, so `file` nodes look supported, but nothing in the agent's
+context ever uses workspace vocabulary and the model has no reason to prefer
+`/workspace` over `/tmp`. Either give it the file tools, or say in its prompt
+that work it means to keep goes in `/workspace`.
+
 Reusing one is the point of keeping it:
 
 ```
@@ -552,9 +587,17 @@ so inspection is free and offline.
 | Why was that recalled?                   | `zen memory show <id>`           |
 | That should never have been written down | `zen memory forget <id>`         |
 
+The directory is not fixed. `zen run --memory <dir>` sends one run's memory
+somewhere else - a scratch graph for a trial, one per branch, or a shared one
+outside the repository - and `zen memory --dir <dir>` reads any such directory
+with no project around it. Together they are also how you read a graph while a
+run holds its `.lock`: copy the directory, delete the copy's `.lock`, and point
+`--dir` at the copy.
+
 `zen inspect` answers the other half: a run report shows the recollection block
 exactly as the model received it, which is how you tell "memory had nothing"
-apart from "memory had it and the model ignored it".
+apart from "memory had it and the model ignored it". A run given `--memory`
+wants `zen inspect --memory <dir>` to rebuild its report against the same graph.
 
 ## A worked configuration
 
@@ -597,6 +640,9 @@ agents:
 - [ ] Every agent that should learn has a `memory:` binding - the top-level
       block alone enables nothing.
 - [ ] `access: full` appears at most once.
+- [ ] Any agent the design expects to commit `file` nodes can write to the
+      workspace - `write_file`/`apply_patch`, or `run_command` with `/workspace`
+      named in its prompt. Nothing else round-trips.
 - [ ] `sees`/`writes` exist because an agent would be **misled** by the other
       slice, not merely because it does not need it.
 - [ ] `autoRecall: false` on any agent whose user message is a payload.
@@ -612,7 +658,7 @@ agents:
 | The `memory_*` tools are missing                    | No `memory:` on the agent. They come from the binding, never from `tools:`                                 |
 | `zen memory` says the project has none              | Neither a `memory:` block nor an agent binding - nothing is opened and no directory is made                |
 | Recall finds a memory only when reworded            | No embedder. `zen memory stats` says `embedding none`                                                      |
-| Recall finds nothing after changing the embedder    | Refused rather than mixed - a manifest records the model. Re-embed or change it back                       |
+| Recall finds nothing after changing the embedder    | Refused rather than mixed - a manifest records the model. Change it back, or start a new memory            |
 | Vectors fewer than nodes                            | Some nodes were committed with no embedder; they are only reachable by term overlap                        |
 | The graph fills with restated requests              | The commit rule is not in a prompt or skill. State the "would a later run redo this" test                  |
 | An agent greps `/memory` or reads `graph.json`      | The house-rules block is missing from `agents/memory-instructions.md` - the system prompt never forbids it |
@@ -621,6 +667,8 @@ agents:
 | A wrong memory keeps coming back                    | It was edited instead of superseded, or superseded in the wrong direction - the **new** node is the source |
 | An agent cannot see a node you can                  | Its `audience` is not in that agent's `sees`. Invisible and missing are the same thing, on purpose         |
 | "this agent cannot remember files"                  | The agent has no workspace, so a path cannot be resolved. Commit without `file`                            |
+| `error: outside the workspace: /tmp/…`              | The file is real to the shell and outside the only tree memory reads. Write it under `/workspace`          |
+| Long content arrives as `text`, never as a `file`   | The agent has no tool that writes to the workspace, so it has no path to name                              |
 | A remembered file will not run                      | It is not self-contained - it referenced the workspace it was written in                                   |
 | Recollections are large and unhelpful               | `autoRecall.limit` is too high, or node texts describe answers rather than questions                       |
 | The model recalls a route the API no longer has     | Nothing re-checks memory against a rebuilt index. Supersede, and require verification                      |

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

@@ -1,6 +1,6 @@
 ---
 name: zen-review
-description: Checking a project before committing - the four mechanical checks `/review-project` makes before any judgement (`zen check`, the §2.5 path sweep, the memory house-rules copy, the spec-sync record), what each one owns, what their exit codes mean, and what deliberately has no check because no tool can make it. Load before running `/review-project`, before saying a project is ready, and whenever a review finding needs verifying rather than restating.
+description: Checking a project before committing - the four mechanical checks `/project-review` makes before any judgement (`zen check`, the §2.5 path sweep, the memory house-rules copy, the spec-sync record), what each one owns, what their exit codes mean, and what deliberately has no check because no tool can make it. Load before running `/project-review`, before saying a project is ready, and whenever a review finding needs verifying rather than restating.
 ---
 
 # Reviewing a project
@@ -104,7 +104,7 @@ Not because it would be hard, but because the answer would be wrong:
 - **Whether the newest spec-sync history entry is honest.** A pass can claim
   anything; only reading the diff says whether it did it.
 
-That list is `/review-project`, and §9 of the copilot instructions is the long
+That list is `/project-review`, and §9 of the copilot instructions is the long
 form. Run the script first so the prompt is spent on this.
 
 ## Where these scripts live, and why edits to them vanish

package/templates/editor/.github/skills/zen-review/scripts/review.sh

@@ -7,7 +7,7 @@
 #
 # What it prints is findings. What it cannot see — whether an agent has one job,
 # whether a description is a condition, whether a fact belongs in a skill — is
-# the rest of /review-project, and the reason that prompt still exists.
+# the rest of /project-review, and the reason that prompt still exists.
 #
 # Every step runs even when an earlier one fails: a review that stops at the
 # first problem is one somebody has to run four times. The exit code is 1 if

package/templates/editor/.github/skills/zen-spec-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zen-spec-sync
-description: Running `/sync-with-spec` as an incremental pass - the committed `.spec-sync` baseline of what the last pass applied, how to scope a pass from the specification and feedback diffs and from what moved in the project itself, the four checks a narrow pass may never skip, the iteration history format, and why the baseline is written last. Load before every `/sync-with-spec`, including the first one on a project that has no baseline yet.
+description: Running `/spec-sync-project` as an incremental pass - the committed `.spec-sync` baseline of what the last pass applied, how to scope a pass from the specification and feedback diffs and from what moved in the project itself, the four checks a narrow pass may never skip, the iteration history format, and why the baseline is written last. Load before every `/spec-sync-project`, including the first one on a project that has no baseline yet.
 ---
 
 # Syncing a project with its specification, one change at a time
@@ -84,7 +84,7 @@ editing anything, and report it in the chat as the pass's scope.
 2. **The `SPECIFICATION-FEEDBACK.md` diff.** The file is a questionnaire the
    human answers by ticking one answer's `[ ]` box or deleting the answers they
    do not want. A question that has moved under `✅ Answered` was folded into the
-   specification by `/update-spec-from-feedback`, and its **Still to implement**
+   specification by `/spec-apply-feedback`, and its **Still to implement**
    line is the work. A question with a box marked `[x]`, or one answer left
    under it, and no `✅` entry was answered and never folded in - implement it,
    put its text into `SPECIFICATION.md`, and say so. A new question someone else

package/templates/editor/.github/skills/zen-spec-sync/scripts/snapshot.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 #
-# The committed record of what the last completed /sync-with-spec pass applied.
+# The committed record of what the last completed /spec-sync-project pass applied.
 #
 #   snapshot.sh status    full | incremental | tampered, and what differs
 #   snapshot.sh diff      the difference the next pass has to work

package/templates/project/SPECIFICATION.md.tmpl

@@ -13,6 +13,22 @@ something in it — and report what was done in enough detail to be checked.
 - One request at a time, in one workspace, with the person who asked it present.
 - No schedule, no queue, nothing that outlives the session it was asked in.
 
+## Models
+
+- `{{modelRef}}` — one model for the whole project, used by every agent.
+- Named once in `agents.yaml` so it can be swapped in one place. Nothing here
+  depends on which model it is; a project that later needs a cheaper model for
+  one job adds a second alias rather than scattering the choice.
+
+## Setup
+
+- Run once, before any session: whatever has to exist before work can start —
+  an index built, a document fetched, a file generated.
+- `scripts/_setup.sh` is the one command that does it, and `scripts/<name>.sh`
+  are the steps it runs in order. A step is safe to run twice and reports
+  `skipped` the second time.
+- Currently: no steps. Nothing has to be prepared before a run.
+
 ## Agents
 
 - `default` — the entry point and the only agent; nobody to hand work to.
@@ -34,13 +50,20 @@ something in it — and report what was done in enough detail to be checked.
 
 ## Environment
 
-- Model: `{{modelRef}}`, one for the whole project.
 - Memory: `memory/`, kept with the project and committed except for its
   vectors, which are derived.
 - Sandbox: built from `sandbox/Dockerfile`, persists between runs, and can
   reach the network. What the work always needs belongs in the image, not in an
   instruction that reinstalls it on every run.
-- Setup: none. `scripts/_setup.sh` is where a step would go, and it has none.
+
+## Testing
+
+- `zen check` passes: the project loads, and every model, tool and skill an
+  agent is given resolves. It says nothing about whether the prose is right.
+- `scripts/_setup.sh` run twice in a row reports every step `skipped` the
+  second time.
+- A run against a real request: the workspace holds the change described, and
+  the reply's account of it matches what is on disk.
 
 ## Done means
 

package/templates/project/agents.yaml.tmpl

@@ -1,8 +1,8 @@
 # Who exists, and what they may reach for.
 #
-# This implements the Agents, Tools and boundaries, and Environment sections of
-# SPECIFICATION.md. Change what the system does there first, then bring this
-# file to match it — `/sync-with-spec` in your editor does exactly that.
+# This implements the Models, Agents, Tools and boundaries, and Environment
+# sections of SPECIFICATION.md. Change what the system does there first, then bring this
+# file to match it — `/spec-sync-project` in your editor does exactly that.
 #
 version: 1
 

package/templates/project/env

@@ -3,7 +3,8 @@
 # `zen run` reads this file before it loads the project, and forwards every
 # name in it into the sandbox — so a command the agent runs sees the same
 # variables the run does. Values are forwarded by name, never written onto a
-# command line, and `--no-keys` withholds the whole file.
+# command line, and `--no-keys` withholds the whole file. `zen meta` reads it
+# too, for the one variable below that is addressed to it.
 #
 # Precedence: what is already set in your shell wins, then this file, then the
 # keyring (`zen key add`). So this is the place for what belongs to *this*
@@ -20,3 +21,8 @@
 # OPENAI_API_KEY=
 # ACME_API_TOKEN=
 # ACME_BASE_URL=https://api.example.test
+
+# Which model `zen meta` runs the meta agent on, for this project only. A zen
+# ref — `vertex/gemini-3.8-flash`, `openai/gpt-5.6-sol` — not a provider's wire
+# name. `zen meta model` shows where the answer came from.
+# ZENERA_META_MODEL=

package/templates/project/gitignore

@@ -2,10 +2,10 @@
 # None of it is source.
 sessions/
 
-# Memory is worth keeping: `graph.json` and `files/` are what the agents
-# learned, and they diff. The vectors are not — they are derived from the
-# graph and can be rebuilt with `zen memory reembed`.
-memory/vectors.*
+# Memory is worth keeping: `graph.json`, `files/` and the vectors are what the
+# agents learned. The vectors are binary, but nothing rebuilds them from the
+# graph, so a clone without them recalls by term overlap until every node is
+# written again. Only the lock is runtime state.
 memory/.lock
 
 # Scratch, inside the workspace so the sandbox can reach it.