@zenera/cli 1.1.22 → 1.1.23

package/dist/commands/memory.js

@@ -1,13 +1,13 @@
-import { ALL_AGENTS, buildMemoryReport, hostPath, memoryDir, MemoryIndex, MemoryStore, readProjectConfig, renderMemoryHtml, } from '@zenera/neo';
+import { ALL_AGENTS, buildMemoryReport, hostPath, memoryDir, MemoryIndex, MemoryStore, MergeConflicts, mergeMemories, readProjectConfig, renderMemoryHtml, } from '@zenera/neo';
 import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
-import { basename, isAbsolute, join, resolve } from 'node:path';
+import { basename, isAbsolute, join, relative, resolve } from 'node:path';
 import { parse } from "../args.js";
 import { project as resolveProject } from "../resolve.js";
-import { ago, bold, bytes, confirm, count, cyan, dim, green, isInteractive, json, note, table, usageError, write, writeAll, yellow, } from "../term.js";
-const USAGE = 'zen memory [stats|ls|show|export|forget] [args] [options]';
-const SUBCOMMANDS = ['stats', 'ls', 'show', 'export', 'forget'];
+import { ago, bold, bytes, CliError, confirm, count, cyan, dim, EXIT, green, isInteractive, json, note, table, usageError, write, writeAll, yellow, } from "../term.js";
+const USAGE = 'zen memory [stats|ls|show|export|merge|forget] [args] [options]';
+const SUBCOMMANDS = ['stats', 'ls', 'show', 'export', 'merge', 'forget'];
 /** Enough to see the shape of it; the rest is a number. */
 const LISTED = 30;
 // ---------------------------------------------------------------------------
@@ -37,6 +37,7 @@ export const memory = {
         '  ls                     Nodes, newest first. Changes nothing.',
         '  show <id>              One node in full, with what it links to.',
         '  export [file]          The whole graph as one HTML page.',
+        '  merge <dir...>         Fold other memories into this one.',
         '  forget <id...>         Remove nodes, their vectors and their files.',
         '',
         '  --project <name|dir>   Which project. Defaults to the one you are in.',
@@ -48,7 +49,10 @@ export const memory = {
         '  --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.',
+        '  --dry-run              Say what `merge` would do, and stop.',
+        '  --no-dedupe            Keep memories `merge` would otherwise fold together.',
+        '  --force                Let `merge` pick a winner where two copies disagree.',
+        '  --yes                  Do not ask before removing or merging.',
         '',
         'Everything here reads the graph *unmasked* — every audience, including',
         'what no agent can see. That is the point: when a mask is the thing',
@@ -57,6 +61,11 @@ export const memory = {
         '`export` is the one to reach for. It writes a single self-contained',
         'page: the node list on the left, the graph in the middle, and whatever',
         'you click on the right, file contents and all.',
+        '',
+        '`merge` is for warming a memory in parallel. The lock is per directory,',
+        'so N runs write N memories; this folds them back into one:',
+        '',
+        '  zen memory merge .tmp/warmup-*/memory',
     ],
     run: async (ctx) => {
         const { values, positionals } = parse(ctx.args, {
@@ -70,13 +79,18 @@ export const memory = {
             out: { type: 'string' },
             open: { type: 'boolean' },
             yes: { type: 'boolean' },
+            force: { type: 'boolean' },
+            'dry-run': { type: 'boolean' },
+            'no-dedupe': { type: 'boolean' },
         }, USAGE);
         const what = positionals[0] ?? 'stats';
         if (!SUBCOMMANDS.includes(what)) {
             throw usageError(`unknown subcommand: ${what}`, USAGE);
         }
         const rest = positionals.slice(1);
-        const opened = await open(ctx.cwd, values.project, values.dir);
+        // `merge` is the one subcommand that may write a memory into existence;
+        // every other one is an inspector and a missing manifest is a mistake.
+        const opened = await open(ctx.cwd, values.project, values.dir, what === 'merge');
         try {
             switch (what) {
                 case 'stats':
@@ -87,6 +101,8 @@ export const memory = {
                     return show(opened, rest, ctx.json);
                 case 'export':
                     return await write_(opened, rest, values, ctx.cwd, ctx.json);
+                case 'merge':
+                    return await merge(opened, rest, values, ctx.cwd, ctx.json);
                 default:
                     return await forget(opened, rest, values, ctx.json);
             }
@@ -105,11 +121,15 @@ export const memory = {
  * A named directory is opened as it stands, project or no project: a graph
  * copied out of a running session is the one most worth looking at, and it
  * should not have to be given an `agents.yaml` first.
+ *
+ * `create` drops the requirement that anything be there yet, for `merge`,
+ * which has somewhere to put what it reads even when the destination is a name
+ * nothing has written to.
  */
-async function open(cwd, want, at) {
+async function open(cwd, want, at, create = false) {
     if (at) {
         const dir = resolve(cwd, at);
-        if (!existsSync(join(dir, 'manifest.json'))) {
+        if (!create && !existsSync(join(dir, 'manifest.json'))) {
             throw usageError(`${dir} is not a memory`, 'no manifest.json in it');
         }
         return { store: await MemoryStore.open(dir), dir, project: basename(dir) };
@@ -120,7 +140,7 @@ async function open(cwd, want, at) {
     if (!dir) {
         throw usageError(`${project.name} has no memory`, 'give an agent `memory: true` in agents.yaml, or add a `memory:` block');
     }
-    if (!existsSync(join(dir, 'manifest.json'))) {
+    if (!create && !existsSync(join(dir, 'manifest.json'))) {
         throw usageError(`${project.name} has a memory configured but nothing in it yet`, 'it is written the first time an agent commits something');
     }
     return { store: await MemoryStore.open(dir), dir, project: project.name };
@@ -336,6 +356,88 @@ function reveal(target) {
     spawn(command, [target], { stdio: 'ignore', detached: true }).unref();
 }
 // ---------------------------------------------------------------------------
+// merge
+// ---------------------------------------------------------------------------
+/**
+ * Warming a memory is parallel work, and the lock is per directory, so N runs
+ * produce N memories rather than one. This is the other half of that: it folds
+ * them back together, offline and without a model.
+ *
+ * Divergence refuses rather than guesses. Two copies of the same memory that
+ * disagree are a question about which piece of work was right, and answering
+ * it silently is how a merge loses the answer.
+ */
+async function merge(o, dirs, flags, cwd, asJson) {
+    if (!dirs.length) {
+        throw usageError('merge takes at least one memory directory', 'zen memory merge <dir...> [--dir <into>]');
+    }
+    const dryRun = flags['dry-run'] === true;
+    const held = o.store.graph.order;
+    if (held && !dryRun && !flags.yes) {
+        if (!isInteractive()) {
+            throw usageError(`${o.project} already remembers ${count(held, 'node')}`, 'pass --yes, or --dry-run to see what would change first');
+        }
+        note(`${count(dirs.length, 'memory', 'memories')} into ${bold(o.dir)} ` +
+            dim(`· ${count(held, 'node')} already there`));
+        if (!(await confirm('Merge?'))) {
+            note('nothing merged');
+            return;
+        }
+    }
+    let report;
+    try {
+        report = await mergeMemories(o.store, dirs.map((d) => resolve(cwd, d)), { dedupe: !flags['no-dedupe'], force: flags.force, dryRun });
+    }
+    catch (err) {
+        if (err instanceof MergeConflicts) {
+            throw diverged(err, cwd, asJson);
+        }
+        throw err;
+    }
+    if (asJson) {
+        json(report);
+        return;
+    }
+    writeAll(table([
+        [dim('memory'), dim('nodes'), dim('new'), dim('shared'), dim('folded'), dim('files')],
+        ...report.sources.map((s) => [
+            near(s.dir, cwd),
+            String(s.nodes),
+            s.added ? green(String(s.added)) : '0',
+            String(s.shared),
+            s.twins ? yellow(String(s.twins)) : '0',
+            String(s.files),
+        ]),
+    ]));
+    write();
+    const summary = [
+        count(report.added, 'node'),
+        `${count(report.edges, 'edge')}`,
+        `${report.twins} folded`,
+    ].join(', ');
+    note(dryRun ? `${yellow('would add')} ${summary}` : `${green('merged')} ${summary}`);
+}
+/**
+ * A refusal with the ids to look at. It is deliberately not a summary: the
+ * point of stopping is that a person decides, and they cannot decide from a
+ * count.
+ */
+function diverged(err, cwd, asJson) {
+    if (asJson) {
+        json({ error: err.message, conflicts: err.conflicts });
+    }
+    else {
+        writeAll(table(err.conflicts.map((c) => [
+            cyan(c.id),
+            dim(`r${c.mine} ↔ r${c.theirs}`),
+            clip(c.text, 48),
+            dim(near(c.dir, cwd)),
+        ])));
+        write();
+    }
+    return new CliError(err.message, EXIT.failed, err.hint);
+}
+// ---------------------------------------------------------------------------
 // forget
 // ---------------------------------------------------------------------------
 /**
@@ -386,4 +488,9 @@ function clip(text, n) {
     const one = text.replace(/\s+/g, ' ').trim();
     return one.length > n ? one.slice(0, n - 1) + '…' : one;
 }
+/** A path as it was probably typed: relative when it is below here, absolute when it is not. */
+function near(dir, cwd) {
+    const rel = relative(cwd, dir);
+    return rel && !rel.startsWith('..') ? rel : dir;
+}
 //# sourceMappingURL=memory.js.map

package/dist/scaffold.d.ts

@@ -11,6 +11,14 @@
  * own beside them.
  */
 export declare const SHARED_RULES: readonly string[];
+/**
+ * This `zen`'s own version, which the scaffold pins the sandbox's tools to.
+ * The publishable packages move in lockstep, so one number covers them all.
+ *
+ * Exported so the check that reports a drifted pin reads the same number the
+ * scaffold wrote, rather than a second definition of "this version".
+ */
+export declare function ownVersion(): string;
 /**
  * Writes the editor's files under `dir`, replacing what is there. They are
  * ours: they say how the editor is to treat a directory the agents write into,

package/dist/scaffold.js

@@ -59,8 +59,11 @@ const MEMORY_REFERENCE = join('.github', 'skills', 'zen-memory', 'references', '
 /**
  * This `zen`'s own version, which the scaffold pins the sandbox's tools to.
  * The publishable packages move in lockstep, so one number covers them all.
+ *
+ * Exported so the check that reports a drifted pin reads the same number the
+ * scaffold wrote, rather than a second definition of "this version".
  */
-function ownVersion() {
+export function ownVersion() {
     const manifest = fileURLToPath(new URL('../package.json', import.meta.url));
     return JSON.parse(readFileSync(manifest, 'utf8')).version;
 }

package/dist/validate.js

@@ -7,7 +7,7 @@ import { resolveBuild } from "./image.js";
 import { SHAPES, envNames, form } from "./keys.js";
 import { probeModels } from "./liveness.js";
 import { BuildError, ensurePodmanReady } from "./podman.js";
-import { staleShared } from "./scaffold.js";
+import { ownVersion, staleShared } from "./scaffold.js";
 // Mirrors the loader's own constants (`packages/neo/src/project/load.ts`).
 // Duplicated rather than exported, because a check that agreed with the loader
 // by construction could not report that the two had diverged.
@@ -1252,6 +1252,7 @@ function checkSandbox(root, config, record, add) {
     if (!ok) {
         return undefined;
     }
+    checkPin(join(root, file), file, add);
     try {
         return resolveBuild(root, config.sandbox);
     }
@@ -1265,6 +1266,72 @@ function checkSandbox(root, config, record, add) {
         return undefined;
     }
 }
+/** `@zenera/cli`, and the version after it when the line pins one. */
+const ZENERA_INSTALL = /@zenera\/([a-z0-9-]+)(?:@([^\s\\'"]+))?/g;
+/**
+ * Whether the Dockerfile's `@zenera/*` installs name this `zen`.
+ *
+ * `zen init` writes the version it was run by and never rewrites the file
+ * again — the scaffold keeps what the project already has — so the pin is fixed
+ * at creation and falls behind the host on the next upgrade. Nothing else
+ * notices: the file parses, the image builds, and the container simply holds a
+ * different `zen` than the session outside it, which is a mismatch that shows
+ * up as a tool behaving unlike its documentation.
+ *
+ * Read rather than run, so it is true on the laptop with no container engine —
+ * the one `--no-sandbox` leaves with no other word on the subject.
+ */
+function checkPin(path, rel, add) {
+    let text;
+    try {
+        // Existence is already a finding; an unreadable file is not worth a
+        // second one, and a throw here would cost every check after it.
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        return;
+    }
+    const mine = ownVersion();
+    const stale = new Set();
+    const loose = new Set();
+    for (const line of text.split('\n')) {
+        // A comment naming the package is prose about the pin, not the pin.
+        if (/^\s*#/.test(line)) {
+            continue;
+        }
+        for (const match of line.matchAll(ZENERA_INSTALL)) {
+            const name = `@zenera/${match[1]}`;
+            const pinned = match[2];
+            if (pinned === undefined) {
+                loose.add(name);
+            }
+            else if (pinned !== mine) {
+                stale.add(`${name}@${pinned}`);
+            }
+        }
+    }
+    const fix = `pin them to ${mine}, the version \`zen --version\` reports`;
+    if (stale.size > 0) {
+        add({
+            severity: 'warning',
+            code: 'sandbox.pin.stale',
+            where: rel,
+            message: `installs ${[...stale].join(', ')}, but this \`zen\` is ${mine} — the CLI an ` +
+                'agent runs inside the container is not the one that built the session',
+            fix,
+        });
+    }
+    if (loose.size > 0) {
+        add({
+            severity: 'warning',
+            code: 'sandbox.pin.absent',
+            where: rel,
+            message: `installs ${[...loose].join(', ')} unpinned, so the next image build takes ` +
+                'whatever is current and drifts away from the host without saying so',
+            fix,
+        });
+    }
+}
 /** Written by the smoke test and read back, to prove the mount is real. */
 const SMOKE = 'zen-check';
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.22",
+    "version": "1.1.23",
     "description": "Command-line front end for @zenera/neo: agentic projects you can run, share and commit.",
     "keywords": [
         "agents",
@@ -48,14 +48,20 @@
         "prepack": "tsc -b"
     },
     "dependencies": {
-        "@inkjs/ui": "^2.0.0",
-        "ink": "^7.1.1",
-        "react": "^19.2.8",
-        "@zenera/neo": "^1.1.22",
         "@anthropic-ai/sdk": "^0.120.0",
         "@google/genai": "^2.18.0",
+        "@inkjs/ui": "^2.0.0",
         "@openrouter/sdk": "^1.2.80",
+        "@zenera/neo": "^1.1.23",
         "google-auth-library": "^10.0.0",
-        "openai": "^6.0.0"
+        "ink": "^7.1.1",
+        "openai": "^6.0.0",
+        "react": "^19.2.8",
+        "yauzl": "^3.4.0",
+        "yazl": "^3.3.1"
+    },
+    "devDependencies": {
+        "@types/yauzl": "^3.4.0",
+        "@types/yazl": "^3.3.1"
     }
 }

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

@@ -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,6 +151,18 @@ 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
@@ -164,6 +179,10 @@ not a paragraph of instructions for a human.
         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
@@ -175,7 +194,8 @@ not a paragraph of instructions for a human.
 
 - **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
@@ -379,6 +399,9 @@ 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

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

@@ -24,7 +24,9 @@ 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
 
@@ -50,6 +52,7 @@ guess a flag, and do not read them all.
 | 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)                                   |
 
@@ -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