@zenera/cli 1.1.21 → 1.1.23

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

@@ -45,12 +45,22 @@ not reconstruct `zen` arguments from memory or call `--help` to discover them.
 **Every runtime capability a project turns on carries obligations that are not
 visible in `agents.yaml` and that `zen check` does not report.** Before
 reviewing or changing a project, list the capabilities it has turned on and load
-the editor skill for each one - `zen-memory` for a `memory:` block, `zen-rag-
-schema` or `zen-rag-docs` for an index, `zen-cli` always. A capability that is
-already configured and already passing `zen check` is exactly the case that
-looks finished and is not: the obligation lives in the skill, so a review that
-never opens the skill cannot find what is missing. This applies whatever
-prompted the change - a task scoped to `SPECIFICATION.md` does not narrow it.
+the editor skill for each one - `zen-memory` for a `memory:` block,
+`zen-sandbox` for sandbox configuration or shell tools, `zen-rag-schema` or
+`zen-rag-docs` for an index, `zen-cli` always. A capability that is already
+configured and already passing `zen check` is exactly the case that looks
+finished and is not: the obligation lives in the skill, so a review that never
+opens the skill cannot find what is missing. This applies whatever prompted the
+change - a task scoped to `SPECIFICATION.md` does not narrow it.
+
+**Load `zen-instructions` before writing, editing, reviewing or deleting any
+`agents/*instructions.md`.** They are the house rules, prepended to every
+agent's prompt, and three of them are `zen`'s own copies rather than the
+project's: an edit made inside one is lost at the next `zen check --fix`, `zen
+init` or `zen open`, with no diff to show for it. The skill is what says which
+three those are, where a project's own rules on the same subjects go instead,
+how `requires:` conditions a document, and what filename order decides. None of
+that is visible in the file being edited.
 
 First determine whether the target project uses RAG: a `zen rag` command in an
 agent prompt or skill, RAG tools supplied by its host, or a documentation or
@@ -222,6 +232,7 @@ my-project/
 ├── agents.yaml                   who exists, what they may reach for
 ├── agents/
 │   ├── instructions.md            house rules, prepended to every agent
+│   ├── files-instructions.md      and more - how files are handled
 │   ├── fork-instructions.md       more of them - any `<topic>-instructions.md`
 │   ├── memory-instructions.md     and more - how the graph is used
 │   ├── tools-instructions.md      and more - how tools are called
@@ -631,9 +642,19 @@ follow. So:
 - Anything only one agent needs goes in that agent's prompt instead. If you find
   yourself writing "if you are the router…", you are in the wrong file.
 
-Target 20–60 lines each. If one exceeds ~100, split the stable half out into a
+Target 20-60 lines each. If one exceeds ~100, split the stable half out into a
 preloaded skill.
 
+Four of these documents are **`zen`'s, not the project's** -
+`tools-instructions.md`, `files-instructions.md`, `memory-instructions.md` and
+`fork-instructions.md`. They are replaced by `zen check --fix`, and a copy that
+differs is reported as `rules.stale`. This project's own rules on any of those
+subjects go in a topic file beside them - `agents/files-policy-instructions.md`,
+`agents/memory-policy-instructions.md` and the like, carrying the same
+`requires:`. The `zen-instructions` skill is the full treatment: the two owners,
+the naming and ordering that keeps a policy after the rules it qualifies, and
+every finding these files can produce. Load it before touching one.
+
 ### 3.3 `agents/prompts/<name>.md`
 
 Plain Markdown, no frontmatter. This is the agent's _job description_, appended
@@ -644,7 +665,7 @@ Structure that works:
 ```markdown
 <one sentence: who this agent is and what it owns>
 
-<what it does, as a short numbered procedure or 3–5 rules>
+<what it does, as a short numbered procedure or 3-5 rules>
 
 <what it must NOT do - especially the neighbouring agent's job>
 
@@ -677,7 +698,7 @@ already did, §3.2), never repeats one of them, and never describes the runtime.
 Every line should be an instruction the model can act on or a boundary it can
 check itself against.
 
-Target 10–40 lines. A 200-line prompt is a skill catalog that has not been split
+Target 10-40 lines. A 200-line prompt is a skill catalog that has not been split
 yet.
 
 ### 3.4 Skills
@@ -798,21 +819,21 @@ Three rules follow:
 
 - **Grant the narrowest set the job needs.** An agent that only reviews should
   not be holding the tools that overwrite files.
-- **Grant by group, then subtract.** Write `workspace:*` and take away what this
-  agent must not have - not a hand-picked list of names. The tools in a group are
-  designed to be used together, and a list assembled one name at a time leaves out
-  the companion the model reaches for next: `write_file` without `apply_patch`
-  turns every one-line edit into a whole-file rewrite, and `read_file` without
-  `list_dir` and `find_files` leaves it guessing at paths. A group also tracks the
-  runtime - a tool added to it later reaches the agent, where an enumerated list
-  silently stays behind.
+- **Grant by group, then subtract.** Write `files:*` (or `workspace:*`) and take
+  away what this agent must not have - not a hand-picked list of names. The tools
+  in a group are designed to be used together, and a list assembled one name at
+  a time leaves out the companion the model reaches for next: `write_file`
+  without `apply_patch` turns every one-line edit into a whole-file rewrite, and
+  `read_file` without `list_dir` and `find_files` leaves it guessing at paths. A
+  group also tracks the runtime - a tool added to it later reaches the agent,
+  where an enumerated list silently stays behind.
 - **Say in the prompt when to reach for what.** A granted tool the prompt never
   mentions is used at the model's discretion, which is not the same as never.
 
 Skills can own tools too - `tools:` in a skill's frontmatter (§3.4) names tools
 that refuse to run until that skill is active.
 
-### 3.6 The workspace tools (`workspace:*`)
+### 3.6 The file tools (`files:*`, alias `workspace:*`)
 
 `zen run` builds this set for you, rooted at the session's workspace directory.
 Nothing else reaches the file system, so an agent whose `tools:` does not name
@@ -841,27 +862,27 @@ container involved there is no second name and everything stays relative.
 
 **Selecting them.** A `tools:` entry is a selector, not only a name:
 
-| Selector              | Selects                                           |
-| --------------------- | ------------------------------------------------- |
-| `read_file`           | that one tool                                     |
-| `workspace:read_file` | the same tool, written out in full                |
-| `workspace:*`         | every tool in the group                           |
-| `'*'`                 | every tool the runtime provides                   |
-| `-<any>`              | removes what it matches from the selection so far |
+| Selector                        | Selects                                           |
+| ------------------------------- | ------------------------------------------------- |
+| `read_file`                     | that one tool                                     |
+| `files:read_file`               | the same tool, written out in full                |
+| `files:*` (alias `workspace:*`) | every tool in the group                           |
+| `'*'`                           | every tool the runtime provides                   |
+| `-<any>`                        | removes what it matches from the selection so far |
 
 ```yaml
 agents:
     - name: editor
-      tools: [workspace:*]
+      tools: [files:*]
 
     - name: reviewer
       # Everything except the four that can change something.
-      tools: [workspace:*, -write_file, -apply_patch, -move_file, -delete_file]
+      tools: [files:*, -write_file, -apply_patch, -move_file, -delete_file]
 ```
 
 Selectors apply in the order written, so a `-` line reads as an exception to the
 line above it. Quote a lone `'*'`: unquoted, YAML reads it as an alias and
-refuses the file. `workspace:*` needs no quoting. There is no name globbing -
+refuses the file. `files:*` (and `workspace:*`) needs no quoting. There is no name globbing -
 `read_*` is an unknown tool, because a selector should track a declared set, not
 a naming habit.
 
@@ -983,12 +1004,12 @@ sandbox:
 
 agents:
     - name: builder
-      tools: [workspace:*, sandbox:*]
+      tools: [files:*, sandbox:*]
       sandbox:
           image: docker.io/library/node:22-bookworm-slim
           memory: 8192
     - name: analyst
-      tools: [workspace:*, sandbox:*] # shares the project's container
+      tools: [files:*, sandbox:*] # shares the project's container
 ```
 
 **Write `persist: true` unless you have a reason not to.** By default the
@@ -1053,7 +1074,7 @@ over several pages, and wastes it when a specific document is wanted.
 ```yaml
 agents:
     - name: researcher
-      tools: [exa:*, workspace:*]
+      tools: [exa:*, files:*]
 
     - name: fact-checker
       # Find and read, but never let a model on the far side do the reasoning.
@@ -1839,6 +1860,9 @@ input`, or tools quietly unused). This is not a config error and `zen check`
   publishes no embeddings API. Point it at another provider - §3.1.1.
 - **Changing `dimensions:` on an embedding invalidates every stored vector.**
   Widths are not comparable, so anything already indexed has to be re-embedded.
+  For a `zen rag` index that is `zen rag <subject> restore --dimensions <n>`,
+  which rebuilds from the copies the index already holds rather than from the
+  documents; the same command with `--embedding <ref>` moves it to another model.
 
 ### 7.8 How to choose, in practice
 
@@ -1940,9 +1964,13 @@ Before finishing any change here:
 - [ ] Nothing duplicated between a house-rules file and an agent prompt
 - [ ] Each `agents/<topic>-instructions.md` is about one capability, and is true
       of every agent it reaches - `requires:` if it is about one of them
+- [ ] If any agent has file tools, `agents/files-instructions.md` is present - §3.6
 - [ ] If any agent has `fork:`, `agents/fork-instructions.md` is present - §6.4
-- [ ] No `rules.stale`: the three files that are `zen`'s rather than yours say
+- [ ] No `rules.stale`: the four files that are `zen`'s rather than yours say
       what this version of the runtime does, and `zen check --fix` replaces them
+- [ ] Any change to an `agents/*instructions.md` was made with the
+      `zen-instructions` skill loaded, and nothing of this project's was written
+      into one of `zen`'s - §3.2
 - [ ] Every tool and agent referenced by its exact name
 - [ ] Failure paths stated for every instruction that can fail
 - [ ] No facts, rates or figures embedded in a prompt
@@ -1984,7 +2012,7 @@ candidates; these are the judgements to make about each one)**
 - [ ] No agent holds `write_file` without `apply_patch`, or `read_file` without
       `list_dir` and `find_files`
 - [ ] An agent that only reads is not holding `write_file`, `apply_patch`,
-      `move_file` or `delete_file` - subtract them from `workspace:*`
+      `move_file` or `delete_file` - subtract them from `files:*` (or `workspace:*`)
 - [ ] `sandbox:*` is granted only where a shell is actually needed
 - [ ] `sandbox.persist: true`, unless a throwaway rootfs is wanted on purpose
 - [ ] The `sandbox:` image carries what the work needs, rather than the prompt
@@ -2056,6 +2084,7 @@ candidates; these are the judgements to make about each one)**
 | 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                         |
 | Forks a sequence, or loses a branch's working | `agents/fork-instructions.md` is missing or empty - §6.4            |
+| Edits files blindly or breaks patches         | `agents/files-instructions.md` is missing or empty - §3.6           |
 | 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                             |

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

@@ -31,7 +31,7 @@ because a prompt or skill someone changed outside a pass still has to be
 accounted for against the specification.
 
 The scope decides what you **read and edit**. It never decides what you
-**verify**: §6, §7 and the four checks in the skill run at full size on every
+**verify**: §6, §7 and the five checks in the skill run at full size on every
 pass, however small the diff.
 
 ## 1. Read before changing anything
@@ -115,7 +115,10 @@ the model to compute or remember. Specifically:
   in it to the version of `zen` in hand. Read that version with `zen --version`
   and write it into the `npm install -g` line, so the CLI an agent runs inside
   the container is the same one that built it. An unpinned name drifts away from
-  the host on the next image build; a stale pin is a mismatch nothing reports.
+  the host on the next image build; a stale pin leaves the container holding an
+  older `zen` than the session outside it. `zen check` reports both, as
+  `sandbox.pin.absent` and `sandbox.pin.stale`, but will not repair either - the
+  Dockerfile is the project's file, so this edit is yours to make.
 
 Never delete an **extra** without saying so. Report it, say why the
 specification does not cover it, and leave it unless I tell you to remove it.
@@ -148,9 +151,51 @@ not a paragraph of instructions for a human.
   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,
   and reaches each step as `$FORCE=1`.
+- **Every step answers a dry run.** `scripts/_setup.sh --check` reaches each step
+  as `$CHECK=1` and means: make the same "already done" test, then do none of the
+  work. Exit **3** when the answer is yes, otherwise say what is missing and exit
+  **4**, which the runner reports as `needs setup`. This is the one command that
+  says whether the project can run without spending the download and the
+  embedding to find out, so the line a step prints under `$CHECK` is the whole
+  value of it: name the artefact and the command that produces it. Pass a tool's
+  own words through rather than writing a second opinion: `zen rag docs ready`
+  without `--quiet` already prints what is wrong and the `restore` or `index`
+  that fixes it. A check must not assume an earlier step has run: a missing
+  prerequisite is a 4 of its own, not a failure, or the first unbuilt thing
+  hides everything after it.
+- **A step's "already done" test must name something that survives a clone.**
+  Git-ignored output does not. A rag index commits its `manifest.json` and
+  ignores `lance/`, so `[ -f "$OUT/manifest.json" ]` is true on a fresh checkout
+  that cannot search at all - every step reports `skipped` and the failure
+  surfaces much later, as a search error nobody connects to setup. Ask the tool
+  rather than guessing at files: `zen rag docs ready --dir "$OUT" --quiet` exits
+  0 when the index can answer and 3 when it cannot, and
+  `zen rag docs restore --dir "$OUT"` re-embeds it from the copies it already
+  holds instead of indexing the documents again. A step that builds an index
+  looks like this:
+
+    ```sh
+    if [ "${FORCE:-0}" = 0 ] && zen rag docs ready --dir "$OUT" --quiet; then
+        echo "$OUT is already built"
+        exit 3
+    fi
+    if [ "${CHECK:-0}" = 1 ]; then
+        zen rag docs ready --dir "$OUT" || true   # its reason and its fix
+        exit 4
+    fi
+    if [ "${FORCE:-0}" = 0 ] && [ -f "$OUT/manifest.json" ]; then
+        zen rag docs restore --dir "$OUT"   # committed index, ignored vectors
+        exit 0
+    fi
+    rm -rf .tmp/docs-db
+    zen rag docs index assets/docs --embedding <ref> --out .tmp/docs-db
+    rm -rf "$OUT" && mv .tmp/docs-db "$OUT"
+    ```
+
 - **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`.
+  and finishes with one line per step: `ok`, `skipped`, `needs setup`, or
+  `failed`.
 - **Everything transient goes under `.tmp/`** - logs, scratch files, downloads,
   test output, and the temporary path a step writes to before moving its
   artefact into place. Nothing else in the tree is a scratch directory, and
@@ -354,6 +399,14 @@ background and follow the logs instead of waiting blind:
   for the same reason, stop and raise it in `SPECIFICATION-FEEDBACK.md`.
 - Prove re-entrancy: once it has succeeded, run `scripts/_setup.sh` once more and
   check that every step reports `skipped` rather than rebuilding.
+- Prove the dry run: `scripts/_setup.sh --check` must then report every step
+  `skipped` and exit 0. `needs setup` for something setup has just built means
+  the step's two tests disagree, and one of them is wrong.
+- **`skipped` on a machine that has never built it is a bug, not a pass.** A
+  step that tests for a committed file skips on a fresh clone and leaves the
+  project unusable. For every index the project builds, check it can actually
+  answer - `zen rag docs ready --dir <dir>` - and fix the step's test if the
+  answer disagrees with what setup reported.
 
 ## 7. Verify and report
 

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

@@ -24,13 +24,15 @@ 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 memory   [stats|ls|show|export|merge|forget] [args] [options]
+zen export   [project] [--out <file>] [--no-vectors] [--no-memory] [--force]
+zen import   <file.zip> [dir] [--name <name>] [--force] [--no-register]
 zen sandbox  [status|up|pull|clean|disk] [options]
 zen version
 
 zen faker    <serve|build|cache> [spec...]
-zen rag      schema <index|search|list|grep|trace|show|stats> [spec...]
-zen rag      docs <index|search|list|grep|show|stats> [path...]
+zen rag      schema <index|restore|ready|search|list|grep|trace|show|stats> [spec...]
+zen rag      docs <index|restore|ready|search|list|grep|show|stats> [path...]
 ```
 
 ## Read the reference before answering
@@ -39,19 +41,20 @@ The full reference lives next to this file, one document per part of the command
 line. **Read the one that covers the question before answering it** - do not
 guess a flag, and do not read them all.
 
-| The question is about                                               | Read                                    |
-| ------------------------------------------------------------------- | --------------------------------------- |
-| Global flags, `--json`, exit codes, environment, where files live   | [frame.md](./references/frame.md)       |
-| Creating, finding or opening a project                              | [projects.md](./references/projects.md) |
-| Running: the TUI, one-shot answers, sessions, workspaces, overrides | [run.md](./references/run.md)           |
-| Validating: `zen check`, what it can and cannot see                 | [check.md](./references/check.md)       |
-| API keys, providers, the keyring, "no credential" errors            | [keys.md](./references/keys.md)         |
-| 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)           |
+| The question is about                                               | Read                                                            |
+| ------------------------------------------------------------------- | --------------------------------------------------------------- |
+| Global flags, `--json`, exit codes, environment, where files live   | [frame.md](./references/frame.md)                               |
+| Creating, finding or opening a project                              | [projects.md](./references/projects.md)                         |
+| Running: the TUI, one-shot answers, sessions, workspaces, overrides | [run.md](./references/run.md)                                   |
+| Validating: `zen check`, what it can and cannot see                 | [check.md](./references/check.md)                               |
+| API keys, providers, the keyring, "no credential" errors            | [keys.md](./references/keys.md)                                 |
+| 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) (and `zen-sandbox` skill) |
+| 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)                             |
+| Sharing a project: archives, what travels, importing one safely     | [export.md](./references/export.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)                                   |
 
 ## The short version
 
@@ -62,6 +65,8 @@ 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 export                            the project as a zip you can send
+zen import a.zip                      unpack one somebody sent, run nothing in it
 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/check.md

@@ -51,6 +51,11 @@ checked too. A word that is neither is a usage error (exit 2), not a report.
   exist, and - unless `--no-sandbox` - the image **builds** and one command runs
   in it, against a temporary directory rather than your workspace. No container
   engine at all is a warning, not an error.
+- The `@zenera/*` the Dockerfile installs are pinned to **this** `zen`. The pin
+  is written once, by `zen init`, and nothing rewrites it afterwards, so it falls
+  behind the host on the next upgrade and the container ends up holding a
+  different `zen` than the session outside it. Read rather than run, so this one
+  is reported with `--no-sandbox` too.
 
 ### Findings
 
@@ -66,6 +71,7 @@ fork.unknown          skills.missing         skill.unloadable / .no-skill-md
 skills.no-catalog     skills.unreachable     skill.unused
 assets.missing        assets.overbroad       sandbox.dockerfile.missing
 sandbox.build         sandbox.smoke          sandbox.start / .unchecked
+sandbox.pin.stale     sandbox.pin.absent
 provider.invalid      model.none             model.unresolvable
 model.refused         model.unreachable      model.unusable
 embedding.refused     embedding.unreachable  embedding.unusable

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

@@ -0,0 +1,107 @@
+# Sharing a project - `zen export` and `zen import`
+
+A project is a directory, so moving one is a zip - except that half of the
+directory belongs to that machine rather than to the project. These two write
+and read the other half.
+
+## `zen export`
+
+```
+zen export [project] [--out <file>] [--no-vectors] [--no-memory] [--force]
+```
+
+Aliases: `pack`, `archive`, `share`.
+
+Writes `./<project>-<stamp>.zip` in the working directory unless `--out` names
+somewhere else. The stamp means two exports in one afternoon are two files, not
+one silently replaced; an `--out` that already exists is a usage error until
+`--force`.
+
+| Flag           | Meaning                                                      |
+| -------------- | ------------------------------------------------------------ |
+| `--out <file>` | Where the archive goes                                       |
+| `--no-vectors` | Leave out `assets/**/lance/` - much smaller, needs a restore |
+| `--no-memory`  | Leave out `memory/` entirely                                 |
+| `--force`      | Overwrite the target, and export past a held memory lock     |
+
+### What travels
+
+Everything that is the project: `agents.yaml`, the `agents/` tree,
+`SPECIFICATION.md` and its feedback, `assets/`, `memory/`, `sandbox/`,
+`scripts/`, and the editor files (`.github/`, `.vscode/`).
+
+What does not: `sessions/`, `.tmp/`, `.git/`, `node_modules/`, lock files,
+`.DS_Store`, any `*.zip` at the top of the project (the default destination
+puts one there, and a second export must not pack the first), and `.env`.
+Symbolic links are counted and never followed. A zip that is genuine project
+material lives under `assets/`, where this rule does not look.
+
+**The values in `.env` never travel, behind no flag.** The names do, as a
+`.env.example` with every value blank and every comment kept - so the other end
+knows which credentials to supply without being handed any.
+
+### The vectors travel by default
+
+This is the decision the command is built around. A rag index without its
+`lance/` tree looks built and cannot search, and memory has no fallback at all:
+a graph without `vectors.f32` recalls by term overlap until every node is
+written again. So the default archive works when it is opened.
+
+`--no-vectors` makes a much smaller one for someone who will run
+`zen rag <subject> restore` on arrival. The manifest records the choice and
+`zen import` prints the restore step when it was taken.
+
+### What it refuses
+
+Only one thing: memory held by a live run, because a graph copied mid-write is
+an archive that opens and is wrong. `--force` overrides it, and
+`--no-memory` sidesteps it.
+
+A project that fails `zen check` is exported anyway, with a warning. Sending
+someone a broken project to ask for help is a legitimate reason to export one.
+
+`--json` prints `{file, bytes, files, project, root, vectors, memory, skipped, ok}`.
+
+## `zen import`
+
+```
+zen import <file.zip> [dir] [--name <name>] [--force] [--no-register]
+```
+
+Aliases: `unpack`.
+
+Unpacks into `./<project>` unless a directory is named, and registers it so
+`zen list` and `zen open` find it by name. A target directory with anything in
+it is refused until `--force`.
+
+| Flag            | Meaning                                             |
+| --------------- | --------------------------------------------------- |
+| `--name <name>` | Register under this name - use it when one is taken |
+| `--force`       | Write into a directory that is not empty            |
+| `--no-register` | Unpack and leave the registry alone                 |
+
+A zip without `zenera-export.json` at its root is a usage error: only an archive
+`zen export` wrote can be imported.
+
+### It treats the archive as hostile
+
+Every path, size and mode in a zip is a claim made by whoever sent it. So:
+entry paths that are absolute, contain `..`, or fall outside the single
+directory the manifest names are refused; an entry claiming to be a symbolic
+link is refused; the entry count and unpacked size are bounded; and file modes
+are replaced rather than honoured (`0644`, and `0755` for `*.sh` only).
+
+**Nothing in the archive is executed** - not `scripts/_setup.sh`, not the
+Dockerfile, not a line of the `.github/` tree. The commands to run next are
+printed instead, so they can be read before they are typed.
+
+### After importing
+
+```sh
+cp .env.example .env     # and fill in the credentials; they were not in the archive
+zen check <name>         # what this machine is still missing
+zen rag <subject> restore  # only when the archive was made with --no-vectors
+zen open <name>
+```
+
+`--json` prints `{dir, name, files, bytes, registered, from, vectors, memory}`.

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

@@ -1,7 +1,7 @@
 # Memory - `zen memory`
 
 ```
-zen memory [stats|ls|show|export|forget] [args] [options]
+zen memory [stats|ls|show|export|merge|forget] [args] [options]
 ```
 
 Alias: `mem`.
@@ -24,20 +24,24 @@ skill.
 | `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 merge <dir…>` | Fold other memories into this one           |
 | `zen memory forget <id…>` | Remove nodes, their vectors and their files |
 
-| 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              |
-| `--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                   |
+| 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               |
+| `--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                        |
+| `--dry-run`             | Say what `merge` would do, and stop           |
+| `--no-dedupe`           | Keep memories `merge` would otherwise fold    |
+| `--force`               | Let `merge` pick a winner where copies differ |
+| `--yes`                 | Do not ask before removing or merging         |
 
 ## A graph that is not the project's
 
@@ -90,6 +94,40 @@ 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.
 
+## Merging
+
+The lock is per directory, so two runs cannot warm the same memory at once.
+They each warm their own, and `merge` puts the results back together:
+
+```sh
+zen memory merge .tmp/warmup-*/memory                    into the project’s
+zen memory merge a/memory b/memory --dir merged/memory   into a named one
+```
+
+Sources are positional and the target is `--dir`, or the project you are in —
+the same shape as everywhere else here. The shell expands the glob, so a
+twelve-way fan-out is still one word. `merge` is the one subcommand that will
+write a memory into existence: a target that is not there yet is created.
+
+It is offline and contacts no model, which is why every side has to have been
+embedded with the same model already. Node ids are kept, so the interesting
+case is the same id on both sides:
+
+- **Same revision, same content** — a shared ancestor, because the runs started
+  from a copy of the same memory. Use counts and timestamps reconcile to the
+  larger of the two, never the sum, so merging a source twice changes nothing.
+- **Anything else** — a divergence. The whole merge is refused, nothing is
+  written, and every conflicting id is listed with both revisions. `--force`
+  takes the highest revision instead.
+
+Memories that are not the same node but say the same thing fold together on the
+same rule a commit uses for duplicates — near-identical by cosine, same kind,
+same audience, never one that remembers a file. `--no-dedupe` turns that off.
+Edges follow whatever their ends folded onto, and an edge whose ends both
+landed on the same memory is dropped.
+
+`--dry-run` reports all of it and writes nothing.
+
 ## Forgetting
 
 ```sh

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

@@ -21,6 +21,7 @@ What it writes:
 zenera.json                     { version, name }
 agents.yaml                     the configuration
 agents/instructions.md          house rules, prepended to every agent
+agents/files-instructions.md     more of them, for agents that work with files
 agents/fork-instructions.md     more of them, for agents that can fork
 agents/memory-instructions.md   more of them, for agents with the memory store
 agents/tools-instructions.md    more of them, about how tools are called