@zenera/cli 1.1.15 → 1.1.17

package/dist/banner.d.ts

@@ -6,8 +6,12 @@ export interface BannerText {
     /** the line underneath, dim */
     subtitle: string;
 }
+export interface PrintBannerOptions {
+    /** Render the block face even when the terminal is narrower than it. */
+    readonly full?: boolean;
+}
 export declare const NEO_BANNER: BannerText;
 export declare function bannerLines(text: BannerText, columns?: number): string[];
 /** Narration, and only for someone watching. */
-export declare function printBanner(text: BannerText): void;
+export declare function printBanner(text: BannerText, options?: PrintBannerOptions): void;
 //# sourceMappingURL=banner.d.ts.map

package/dist/banner.js

@@ -112,12 +112,12 @@ export function bannerLines(text, columns = process.stderr.columns || 80) {
     return lines;
 }
 /** Narration, and only for someone watching. */
-export function printBanner(text) {
+export function printBanner(text, options = {}) {
     if (!process.stderr.isTTY) {
         return;
     }
     note('');
-    for (const line of bannerLines(text)) {
+    for (const line of bannerLines(text, options.full ? Infinity : undefined)) {
         note(line);
     }
     note('');

package/dist/catalog.js

@@ -38,29 +38,28 @@ const CATALOG_VERSION = 1;
  */
 export const CURATED = {
     openai: [
-        { id: 'gpt-4o-mini', roles: ['chat'], contextLength: 128_000 },
-        { id: 'gpt-4o', roles: ['chat'], contextLength: 128_000 },
+        { id: 'gpt-5.6-luna', roles: ['chat'], contextLength: 1_050_000 },
+        { id: 'gpt-5.6-terra', roles: ['chat'], contextLength: 1_050_000 },
         { id: 'text-embedding-3-small', roles: ['embedding'], dimensions: 1536 },
         { id: 'text-embedding-3-large', roles: ['embedding'], dimensions: 3072 },
     ],
     anthropic: [
-        { id: 'claude-haiku-4-5', roles: ['chat'], contextLength: 200_000 },
-        { id: 'claude-sonnet-4-5', roles: ['chat'], contextLength: 200_000 },
+        { id: 'claude-sonnet-5', roles: ['chat'], contextLength: 1_000_000 },
+        { id: 'claude-opus-5', roles: ['chat'], contextLength: 1_000_000 },
     ],
     google: [
-        { id: 'gemini-2.5-flash', roles: ['chat'], contextLength: 1_048_576 },
-        { id: 'gemini-2.5-pro', roles: ['chat'], contextLength: 1_048_576 },
-        { id: 'gemini-embedding-001', roles: ['embedding'], dimensions: 3072 },
+        { id: 'gemini-3.5-flash-lite', roles: ['chat'], contextLength: 1_048_576 },
+        { id: 'gemini-3.8-flash', roles: ['chat'], contextLength: 1_048_576 },
+        { id: 'gemini-embedding-2', roles: ['embedding'] },
     ],
     vertex: [
-        { id: 'gemini-2.5-flash', roles: ['chat'], contextLength: 1_048_576 },
-        { id: 'gemini-2.5-pro', roles: ['chat'], contextLength: 1_048_576 },
-        { id: 'gemini-embedding-001', roles: ['embedding'], dimensions: 3072 },
-        { id: 'text-embedding-005', roles: ['embedding'], dimensions: 768 },
+        { id: 'gemini-3.5-flash-lite', roles: ['chat'], contextLength: 1_048_576 },
+        { id: 'gemini-3.8-flash', roles: ['chat'], contextLength: 1_048_576 },
+        { id: 'gemini-embedding-2', roles: ['embedding'] },
     ],
     openrouter: [
-        { id: 'openai/gpt-4o-mini', roles: ['chat'] },
-        { id: 'anthropic/claude-haiku-4.5', roles: ['chat'] },
+        { id: 'openai/gpt-5.6-luna', roles: ['chat'], contextLength: 1_050_000 },
+        { id: 'anthropic/claude-sonnet-5', roles: ['chat'], contextLength: 1_000_000 },
         { id: 'openai/text-embedding-3-small', roles: ['embedding'], dimensions: 1536 },
     ],
 };
@@ -73,23 +72,23 @@ export const CURATED = {
  */
 export const PREFERRED = {
     openai: {
-        chat: ['gpt-4o-mini', 'gpt-4o'],
+        chat: ['gpt-5.6-luna', 'gpt-5.6-terra'],
         embedding: ['text-embedding-3-small', 'text-embedding-3-large'],
     },
     anthropic: {
-        chat: ['claude-haiku-4-5', 'claude-sonnet-4-5'],
+        chat: ['claude-sonnet-5', 'claude-opus-5'],
         embedding: [],
     },
     google: {
-        chat: ['gemini-2.5-flash', 'gemini-2.5-pro'],
-        embedding: ['gemini-embedding-001'],
+        chat: ['gemini-3.5-flash-lite', 'gemini-3.5-flash'],
+        embedding: ['gemini-embedding-2'],
     },
     vertex: {
-        chat: ['gemini-2.5-flash', 'gemini-2.5-pro'],
-        embedding: ['text-embedding-005', 'gemini-embedding-001'],
+        chat: ['gemini-3.5-flash-lite', 'gemini-3.5-flash'],
+        embedding: ['gemini-embedding-2'],
     },
     openrouter: {
-        chat: ['openai/gpt-4o-mini', 'anthropic/claude-haiku-4.5'],
+        chat: ['openai/gpt-5.6-luna', 'anthropic/claude-sonnet-5'],
         embedding: ['openai/text-embedding-3-small'],
     },
 };

package/dist/command.d.ts

@@ -9,6 +9,11 @@ export interface Command {
     readonly usage: string;
     /** lines printed under the usage line by `zen help <command>` */
     readonly details?: readonly string[];
+    /**
+     * Answers `--help` itself, for a command whose arguments select a page the
+     * frame cannot see. Without it the frame prints this command's own page.
+     */
+    help?(ctx: Context): Promise<void> | void;
     run(ctx: Context): Promise<void>;
 }
 //# sourceMappingURL=command.d.ts.map

package/dist/commands/check.js

@@ -1,6 +1,7 @@
 import { existsSync, statSync } from 'node:fs';
 import { basename, dirname, resolve } from 'node:path';
 import { one, parse } from "../args.js";
+import { loadProjectEnv } from "../env.js";
 import { KeyStore } from "../keys.js";
 import { duration } from "../narrate.js";
 import { Registry } from "../projects.js";
@@ -75,7 +76,10 @@ export const check = {
         const name = entry?.name ?? basename(dir);
         // Materialised first, so the credential verdicts are the ones a run
         // would reach: a key in the environment and a key in the keyring are
-        // the same key by the time the library asks.
+        // the same key by the time the library asks. The project's own `.env`
+        // goes first for the same reason — `zen run` reads it, so a check that
+        // did not would report a missing credential for a project that runs.
+        loadProjectEnv(dir);
         const keys = await KeyStore.open();
         keys.materialize();
         const bar = progress();

package/dist/commands/init.js

@@ -2,6 +2,7 @@ import { readProjectConfig } from '@zenera/neo';
 import { existsSync, readdirSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
 import { one, parse } from "../args.js";
+import { PREFERRED } from "../catalog.js";
 import { ensureHome } from "../home.js";
 import { resolveBuild } from "../image.js";
 import { envNames, isProvider, keyId, KeyStore, PROVIDERS } from "../keys.js";
@@ -43,6 +44,36 @@ const DEFAULT_MODEL = {
     vertex: { ref: 'vertex:gemini-3.5-flash' },
     openrouter: { ref: 'openrouter:inclusionai/ling-3.0-flash-fin:free' },
 };
+/**
+ * What vectorises the project's memory, given the provider it ends up on.
+ *
+ * Taken from the same table `zen models pick` ranks by rather than written out
+ * again here, so the scaffold cannot drift from what the catalogue calls
+ * current. Anthropic publishes no embeddings API, and a `--model` naming a
+ * provider we do not ship gives nothing to guess from; both scaffold without
+ * one, and memory still works by ranking recall on term overlap. An
+ * `embeddings:` entry pointing at a provider that has none is not a degraded
+ * project, it is one that fails to load.
+ */
+function defaultEmbedding(provider) {
+    if (provider === undefined) {
+        return undefined;
+    }
+    const id = PREFERRED[provider].embedding[0];
+    return id === undefined ? undefined : `${provider}:${id}`;
+}
+/**
+ * The provider a model ref names, when it names one we know.
+ *
+ * Every ref the scaffold writes carries its provider, so this is how the
+ * memory store ends up on the same credential as the chat model — including
+ * for an explicit `--model`, where nothing else says which vendor was meant.
+ */
+function providerOf(ref) {
+    const colon = ref.indexOf(':');
+    const head = colon < 0 ? '' : ref.slice(0, colon);
+    return isProvider(head) ? head : undefined;
+}
 /**
  * The provider this machine can actually reach.
  *
@@ -96,10 +127,11 @@ export const init = {
     summary: 'Create a project here, or in <dir>, and register it.',
     usage: USAGE,
     details: [
-        'Writes SPECIFICATION.md, INSTRUCTIONS.md, agents.yaml, agents/ and',
-        'scripts/, then records the directory so `zen list` and `zen open` can',
-        'find it by name. Editor files (.vscode/settings.json and the .github/',
-        'tree) are written alongside, replacing any already there.',
+        'Writes SPECIFICATION.md, agents.yaml, agents/ (house rules, the memory',
+        'rules and one role prompt) and scripts/, then records the directory so',
+        '`zen list` and `zen open` can find it by name. Editor files',
+        '(.vscode/settings.json and the .github/ tree) are written alongside,',
+        'replacing any already there.',
         '',
         'A directory that is already a project is adopted rather than rebuilt:',
         'it is registered under its own name, and nothing in it is touched.',
@@ -111,7 +143,9 @@ export const init = {
         'there, then run /sync-with-spec in your editor to make the rest match.',
         '',
         'The default agent gets the file tools and a sandboxed shell, plus',
-        '`exa:*` when the keyring holds an Exa key. Without --model, the',
+        '`exa:*` when the keyring holds an Exa key. It keeps a memory of its',
+        'own work in memory/, vectorised by the same provider as the model',
+        'when that provider publishes embeddings. Without --model, the',
         'keyring is checked and the model is picked from a credential the',
         'provider accepts.',
         '',
@@ -143,7 +177,8 @@ export const init = {
             : DEFAULT_MODEL[provider ?? 'openai'];
         const model = choice.ref;
         const web = hasExa(store);
-        const written = scaffold({ dir, model, modelOptions: choice.options, web });
+        const embedding = defaultEmbedding(providerOf(model));
+        const written = scaffold({ dir, model, modelOptions: choice.options, web, embedding });
         const registry = await Registry.open();
         registry.add(name, dir);
         registry.save();

package/dist/commands/run.js

@@ -29,6 +29,10 @@ export const run = {
         'The first word is the project when it names one, as in `zen run acme`,',
         'and the first word of the prompt when it does not. --project settles it.',
         '',
+        "The project's .env is read before it loads, and every name in it is",
+        'forwarded into the sandbox. Your shell wins over the file, and the',
+        'keyring fills in the rest; --no-keys withholds all of it.',
+        '',
         'The prompt comes from the argument, or stdin, or the TUI. There is no',
         '`resume`: a session continues itself, because its state is what it is.',
         '',

package/dist/engine.js

@@ -3,6 +3,7 @@ import { existsSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { auditModels, describeIssue } from "./audit.js";
+import { loadProjectEnv } from "./env.js";
 import { readJson, writeJson } from "./home.js";
 import { KeyStore, assertUsable } from "./keys.js";
 import { projectMounts } from "./projects.js";
@@ -15,6 +16,10 @@ import { CliError, EXIT, invalidError, warn } from "./term.js";
  * and the whole conversation, its memory and its blobs travel with it.
  */
 export async function open(opts) {
+    // Before the keyring, so the project's own file wins over the machine's
+    // keys, and before the load, so `${VAR}` in agents.yaml can name anything
+    // in it. The real environment still beats both.
+    const env = loadProjectEnv(opts.project.dir);
     const keys = await KeyStore.open();
     keys.materialize();
     assertUsable(keys);
@@ -47,6 +52,7 @@ export async function open(opts) {
             readOnly: opts.readOnly,
             image: opts.image,
             keys: opts.keys,
+            env: env?.names,
             mounts,
         });
         const workspaceOptions = {

package/dist/env.d.ts

@@ -0,0 +1,20 @@
+/** The file, relative to the project directory. */
+export declare const ENV_FILE = ".env";
+export interface ProjectEnv {
+    /** the file it was read from */
+    path: string;
+    /** every name the file declares, whether or not its value won */
+    names: string[];
+}
+/**
+ * Reads `<dir>/.env` into `process.env`, without overwriting anything already
+ * set, and returns the names it found. A project with no such file is not a
+ * problem to report — most have none — so the answer is simply `undefined`.
+ *
+ * The names are returned in full, including the ones the environment already
+ * answered: the variable is in play either way, and the sandbox forwards by
+ * name, so what it needs to know is which names matter and not which of the
+ * two sources supplied them.
+ */
+export declare function loadProjectEnv(dir: string): ProjectEnv | undefined;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.js

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { parseEnv } from 'node:util';
+import { FILE_ENVS } from "./keys.js";
+// ---------------------------------------------------------------------------
+// The project's `.env`
+//
+// A project is a directory, and some of what it needs to run is particular to
+// it: the token for the service it talks to, the base url of the environment
+// it talks to it in. The keyring answers "what can this machine pay for"; this
+// answers "what does this project need", and the two are different questions
+// often enough to be worth two places.
+//
+// Precedence is the same one everything else here uses — the real environment
+// always wins. What is already set in the shell is left alone, this file fills
+// the gaps, and the keyring fills whatever is still missing after that. So a
+// variable exported for one command still overrides the file, which is the
+// behaviour anybody typing `FOO=bar zen run` is expecting.
+//
+// The names, not the values, are what leaves this module: they are what the
+// sandbox forwards, and forwarding by name is what keeps a secret out of an
+// argv. See `forwarded()` in sandbox.ts for the rest of that story.
+// ---------------------------------------------------------------------------
+/** The file, relative to the project directory. */
+export const ENV_FILE = '.env';
+/**
+ * Reads `<dir>/.env` into `process.env`, without overwriting anything already
+ * set, and returns the names it found. A project with no such file is not a
+ * problem to report — most have none — so the answer is simply `undefined`.
+ *
+ * The names are returned in full, including the ones the environment already
+ * answered: the variable is in play either way, and the sandbox forwards by
+ * name, so what it needs to know is which names matter and not which of the
+ * two sources supplied them.
+ */
+export function loadProjectEnv(dir) {
+    const path = join(dir, ENV_FILE);
+    if (!existsSync(path)) {
+        return undefined;
+    }
+    const names = [];
+    for (const [name, value] of Object.entries(parseEnv(readFileSync(path, 'utf8')))) {
+        if (value === undefined) {
+            continue;
+        }
+        names.push(name);
+        // An empty string is not an answer: tools test for absence, and a
+        // commented-out line someone half-filled in should not shadow a key
+        // the keyring has.
+        if (!process.env[name]) {
+            process.env[name] = located(dir, name, value);
+        }
+    }
+    return { path, names };
+}
+/**
+ * A service-account file is normally kept beside the `.env` that names it, so
+ * a relative path there means relative to the *project* — not to wherever the
+ * command happened to be run, which is what both the Google SDK and podman's
+ * bind mount would otherwise make of it.
+ */
+function located(dir, name, value) {
+    return FILE_ENVS.includes(name) && !isAbsolute(value) ? resolve(dir, value) : value;
+}
+//# sourceMappingURL=env.js.map

package/dist/keys.d.ts

@@ -58,6 +58,8 @@ export declare const SHAPES: Record<KeyOwner, ProviderShape>;
 export declare function form(provider: KeyOwner): CredentialForm;
 /** Every variable a provider's credential could arrive in, usual one first. */
 export declare function envNames(provider: KeyOwner): string[];
+/** Variables that name a credential *file* rather than carrying the secret. */
+export declare const FILE_ENVS: string[];
 /** The variable this particular credential occupies. */
 export declare function envOf(entry: Pick<KeyEntry, 'provider' | 'holds' | 'env'>): string;
 export declare function isProvider(name: string): name is Provider;

package/dist/keys.js

@@ -127,6 +127,8 @@ export function form(provider) {
 export function envNames(provider) {
     return SHAPES[provider].forms.map((f) => f.env);
 }
+/** Variables that name a credential *file* rather than carrying the secret. */
+export const FILE_ENVS = OWNERS.flatMap((owner) => SHAPES[owner].forms.filter((f) => f.holds === 'file').map((f) => f.env));
 /** The variable this particular credential occupies. */
 export function envOf(entry) {
     if (entry.env) {

package/dist/main.js

@@ -57,9 +57,11 @@ async function main(argv) {
     // Narration, so `--json` and every pipe are untouched by it. A command
     // living in another package brings its own brand, but only once it is
     // actually there — a banner over "not installed" is a claim about nothing.
-    if (!json) {
+    const ragSearch = name === 'rag' && ['docs', 'schema'].includes(rest[0]) && rest[1] === 'search';
+    const interactive = rest.includes('--interactive');
+    if (!json && (!ragSearch || interactive)) {
         const brand = external && hasExternal(external) ? external.banner : undefined;
-        printBanner(brand ?? NEO_BANNER);
+        printBanner(brand ?? NEO_BANNER, { full: ragSearch && interactive });
     }
     if (parts.name === 'help') {
         await usage(rest[0]);
@@ -73,15 +75,17 @@ async function main(argv) {
         fail(`unknown command "${parts.name}"`, `run ${bold(`${NAME} --help`)} for the list`);
         return EXIT.usage;
     }
-    if (values.help) {
-        await usage(name);
-        return EXIT.ok;
-    }
     // `-C` is consumed here so no command ever reads `process.cwd()` itself,
     // and every relative path in every command means the same thing.
     const cwd = resolve(values.directory ?? process.cwd());
     try {
         const one = command ?? (await loadExternal(name, external));
+        if (values.help) {
+            // A command that nests its own pages answers for them; the frame
+            // only knows the one page it printed the command's name on.
+            await (one.help ? one.help({ args: rest, json, cwd }) : usage(name));
+            return EXIT.ok;
+        }
         await one.run({ args: rest, json, cwd });
         return EXIT.ok;
     }

package/dist/sandbox.d.ts

@@ -28,6 +28,15 @@ export interface SandboxInputs {
     image?: string;
     /** `--no-keys`: refuse to forward credentials, whatever the config says */
     keys?: boolean;
+    /**
+     * Names from the project's `.env`, forwarded into the container the same
+     * way a credential is — by name, so the value stays out of the argv.
+     *
+     * They travel with the keys rather than beside them: a `.env` is where an
+     * api token lives, so `--no-keys` has to withhold it too or the flag is a
+     * promise it does not keep.
+     */
+    env?: readonly string[];
 }
 export declare function buildSandbox(opts: SandboxInputs): SandboxSetup;
 /**

package/dist/sandbox.js

@@ -82,7 +82,7 @@ export function buildSandbox(opts) {
     // read-only directory fails on writing its own `__pycache__` — a confusing
     // error about a file nobody asked for.
     const extra = { HOME, PYTHONDONTWRITEBYTECODE: '1', ...(keys?.env ?? {}) };
-    const spec = toSpec(base, extra, keys?.secrets);
+    const spec = toSpec(base, extra, secretsOf(keys?.secrets, opts.env));
     const agents = {};
     for (const agent of opts.config.agents) {
         if (agent.sandbox) {
@@ -92,7 +92,7 @@ export function buildSandbox(opts) {
             // so the variable is what actually decides, and without it the file
             // sitting there is not a credential anything will look for.
             const own = merged.keys === false ? undefined : keys;
-            agents[agent.name] = toSpec(merged, { HOME, PYTHONDONTWRITEBYTECODE: '1', ...(own?.env ?? {}) }, own?.secrets);
+            agents[agent.name] = toSpec(merged, { HOME, PYTHONDONTWRITEBYTECODE: '1', ...(own?.env ?? {}) }, own && secretsOf(own.secrets, opts.env));
         }
     }
     const pool = new SandboxPool({
@@ -121,10 +121,30 @@ function merge(base, agent) {
     }
     return merged;
 }
+/**
+ * The two sources of forwarded names, as one list: the credentials the keyring
+ * selected, and whatever the project's `.env` declares. Deduped, because the
+ * same variable named twice is the same `--env` twice.
+ *
+ * `undefined` in means keys are withheld, and the file goes with them.
+ */
+function secretsOf(secrets, env) {
+    if (!secrets) {
+        return undefined;
+    }
+    return [...new Set([...secrets, ...(env ?? [])])];
+}
 /**
  * Config names a variable; this reads it. A name that is not set on this host
  * is simply not forwarded — an empty string in the container is a different
  * thing from an absent one, and tools test for absence.
+ *
+ * A name that has already been answered with a value drops off the forwarded
+ * list: `--env NAME=value` and `--env NAME` are the same variable twice, and
+ * the one that carries a value is the one that was resolved on purpose. That
+ * matters for `GOOGLE_APPLICATION_CREDENTIALS`, which is rewritten here to
+ * where the key file was mounted — a `.env` naming it must not put the host's
+ * path back, since that path does not exist inside the container.
  */
 function toSpec(config, extra, secrets) {
     const env = { ...extra };
@@ -144,7 +164,7 @@ function toSpec(config, extra, secrets) {
         user: config.user,
         persist: config.persist,
         env,
-        secrets,
+        secrets: secrets?.filter((name) => !(name in env)),
     };
 }
 /**

package/dist/scaffold.d.ts

@@ -14,6 +14,12 @@ export interface ScaffoldOptions {
     modelOptions?: string;
     /** give the default agent `exa:*` — set when a key for it is on hand */
     web?: boolean;
+    /**
+     * What vectorises the memory graph, as a provider-prefixed ref. Left out
+     * when the project's provider publishes no embeddings API — memory still
+     * works, ranking recall by term overlap instead of by meaning.
+     */
+    embedding?: string;
 }
 export interface Scaffolded {
     /** the project's own files, in the order they were written */

package/dist/scaffold.js

@@ -1,5 +1,5 @@
-import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from 'node:fs';
-import { join } from 'node:path';
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 // ---------------------------------------------------------------------------
 // Scaffolding
@@ -18,6 +18,7 @@ import { fileURLToPath } from 'node:url';
 //
 // The trees are copied whole and nothing enumerates them, so adding a file to
 // a new project is adding a file to `templates/project/` and nothing else.
+// `MEMORY_RULES` is the single exception, and it is named below.
 //
 // What is there is deliberately close to empty: a template full of
 // commented-out options is a template nobody reads and everybody deletes. The
@@ -32,6 +33,10 @@ import { fileURLToPath } from 'node:url';
 const TEMPLATES = fileURLToPath(new URL('../templates', import.meta.url));
 /** The suffix on a file with `{{...}}` in it, dropped when the file lands. */
 const TEMPLATE = '.tmpl';
+/** How to use the memory graph: a house rules file, landing under `agents/`. */
+const MEMORY_RULES = join('agents', 'memory-instructions.md');
+/** The same bytes, kept in the `zen-memory` skill to restore or diff against. */
+const MEMORY_REFERENCE = join('.github', 'skills', 'zen-memory', 'references', 'memory-instructions.md');
 /**
  * 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.
@@ -98,17 +103,24 @@ function modelSection(ref, options) {
     });
 }
 /**
- * The name a template file lands under.
+ * Template files that land under a name they cannot be stored under.
  *
- * `gitignore` gains its dot here because it cannot have one in the repository:
- * npm strips a `.gitignore` out of a published tarball, and git would read this
- * one as rules about `packages/cli/templates/` rather than as content.
+ * `gitignore` cannot have its dot in the repository: npm strips a `.gitignore`
+ * out of a published tarball, and git would read this one as rules about
+ * `packages/cli/templates/` rather than as content. `env` cannot have its dot
+ * for a plainer reason — this repository ignores `.env` everywhere, as every
+ * repository should, so the template would never be committed at all.
  */
+const DOTFILES = {
+    gitignore: '.gitignore',
+    env: '.env',
+};
+/** The name a template file lands under. */
 function target(name) {
     if (name.endsWith(TEMPLATE)) {
         return name.slice(0, -TEMPLATE.length);
     }
-    return name === 'gitignore' ? '.gitignore' : name;
+    return DOTFILES[name] ?? name;
 }
 /**
  * Copies one template directory into `dir` at `rel`, depth first, sorted so the
@@ -145,13 +157,19 @@ function copyTree(from, dir, rel, opts) {
 // ---------------------------------------------------------------------------
 // Telling the editor which instructions are not for it
 //
-// The project's house rules are `INSTRUCTIONS.md`, deliberately not
+// The project's house rules are `agents/instructions.md`, deliberately not
 // `AGENTS.md`: every coding assistant now reads that name out of an open
 // folder and feeds it to itself as always-on instructions, and `zen open`
 // opens exactly this directory. A name nobody else claims means the two are
 // never confused, and `chat.useAgentsMdFile` no longer has to be switched off
 // to keep them apart.
 //
+// They sit under `agents/` because there is rarely only one of them. Anything
+// named `agents/<topic>-instructions.md` is read too, in filename order, so a
+// subject that is true for every agent but is about one capability — memory,
+// say — gets its own document instead of another section in a file that keeps
+// growing.
+//
 // `chat.useNestedAgentsMdFiles` is still written. It is already false by
 // default, but it is opt-in globally, and this is a directory the agent itself
 // writes into — someone who turned it on would otherwise have the editor pick
@@ -159,12 +177,12 @@ function copyTree(from, dir, rel, opts) {
 // setting, so it applies only in a trusted workspace; that is the right way
 // round, since an untrusted folder is not one to run agents in either.
 //
-// `INSTRUCTIONS.md` addresses the *project's* agents. The editor's assistant
-// still needs a brief of its own, and what it needs to know is how this kind
-// of project is put together — the file formats, how a prompt is written, when
-// to add a skill rather than an agent. That is what the `.github/` tree is: the
-// standing brief, plus the prompt files and skills the editor picks up from the
-// same place.
+// `agents/instructions.md` addresses the *project's* agents. The editor's
+// assistant still needs a brief of its own, and what it needs to know is how
+// this kind of project is put together — the file formats, how a prompt is
+// written, when to add a skill rather than an agent. That is what the
+// `.github/` tree is: the standing brief, plus the prompt files and skills the
+// editor picks up from the same place.
 // ---------------------------------------------------------------------------
 /**
  * Writes the editor's files under `dir`, replacing what is there. They are
@@ -174,7 +192,21 @@ function copyTree(from, dir, rel, opts) {
  * none. Returns the relative paths written.
  */
 export function editorFiles(dir) {
-    return copyTree(join(TEMPLATES, 'editor'), dir, '', {});
+    const written = copyTree(join(TEMPLATES, 'editor'), dir, '', {});
+    // The one file that belongs to both trees. It is a project file first —
+    // house rules prepended to every agent that can see the graph — and it is
+    // written once and edited from then on, like every other project file. But
+    // a project whose copy drifted, or that deleted it and turned memory back
+    // on later, needs somewhere to get the current text from, and the editor
+    // tree is replaced on every `init` and `open`. Copying the same bytes into
+    // the skill's references is what makes `diff` between the two mean
+    // something, and what stops a second copy of these rules existing in the
+    // repository to fall out of step with the first.
+    const reference = join(dir, MEMORY_REFERENCE);
+    mkdirSync(dirname(reference), { recursive: true });
+    copyFileSync(join(TEMPLATES, 'project', MEMORY_RULES), reference);
+    written.push(MEMORY_REFERENCE);
+    return written;
 }
 /**
  * Writes a project. Never overwrites the project's own files — a second `init`
@@ -198,6 +230,9 @@ export function scaffold(opts) {
             // different readers — and a tool nothing says to use is not one.
             web: opts.web ? part('exa.spec.md') : '',
             webPrompt: opts.web ? part('exa.prompt.md') : '',
+            memory: opts.embedding
+                ? part('memory.yaml', { embedding: opts.embedding })
+                : part('memory-terms.yaml'),
             version: ownVersion(),
         },
     });
@@ -209,6 +244,12 @@ export function scaffold(opts) {
     mkdirSync(join(opts.dir, 'agents', 'skills'), { recursive: true });
     mkdirSync(join(opts.dir, 'sessions'), { recursive: true });
     mkdirSync(join(opts.dir, '.tmp'), { recursive: true });
+    // Where `/sync-with-spec` records what it applied, so the next pass works
+    // the difference rather than the whole specification again. Empty here, and
+    // git does not carry an empty directory: what says a pass has completed is
+    // `baseline/manifest.txt`, never the directory itself.
+    mkdirSync(join(opts.dir, '.spec-sync', 'baseline'), { recursive: true });
+    mkdirSync(join(opts.dir, '.spec-sync', 'history'), { recursive: true });
     // The project directory is what `zen open` opens, so this is where the
     // editor actually reads them.
     return { files, editor: editorFiles(opts.dir) };