@zenera/cli 1.1.16 → 1.1.17

package/README.md

@@ -205,9 +205,12 @@ In the window that opens:
 2. **Open the chat panel and send `/sync-with-spec`.** It reads the
    specification and every file implementing it, works out the difference in
    both directions, and changes the smallest thing that closes each gap.
-3. **Read `SPECIFICATION-FEEDBACK.md`**, which it writes for anything it could
-   not do without guessing. Answer its questions by editing `SPECIFICATION.md`
-    - not by editing prompts - and send `/sync-with-spec` again.
+3. **Answer `SPECIFICATION-FEEDBACK.md`**, which it writes for anything it could
+   not do without guessing. Every question carries two to four written-out
+   answers, each with a `[ ]` box: tick one, delete the ones you do not want, or
+   write your own in their place.
+4. **Send `/update-spec-from-feedback`.** It folds the answers you chose into
+   `SPECIFICATION.md` - never into a prompt - and then `/sync-with-spec` again.
 
 Back in the terminal: `zen check`, then `zen run`.
 
@@ -218,12 +221,13 @@ They are prompt files under `.github/prompts/`, which VS Code and its forks
 offer as chat slash-commands. Both `zen init` and `zen open` write them fresh,
 so they never go stale - and edits to them do not survive.
 
-| In chat           | Does                                                        |
-| ----------------- | ----------------------------------------------------------- |
-| `/sync-with-spec` | Makes every file match `SPECIFICATION.md`, both directions. |
-| `/review-project` | Reads the project as a reviewer would, and reports.         |
-| `/new-agent`      | Adds an agent - prompt, wiring and hand-offs.               |
-| `/new-skill`      | Adds a skill under `agents/skills/`.                        |
+| In chat                      | Does                                                             |
+| ---------------------------- | ---------------------------------------------------------------- |
+| `/sync-with-spec`            | Makes every file match `SPECIFICATION.md`, both directions.      |
+| `/update-spec-from-feedback` | Folds your answers in `SPECIFICATION-FEEDBACK.md` into the spec. |
+| `/review-project`            | Reads the project as a reviewer would, and reports.              |
+| `/new-agent`                 | Adds an agent - prompt, wiring and hand-offs.                    |
+| `/new-skill`                 | Adds a skill under `agents/skills/`.                             |
 
 In an editor that does not support prompt files, paste the contents of
 `.github/prompts/sync-with-spec.prompt.md` into its chat instead - it is only a
@@ -378,20 +382,24 @@ is a command on their machine too.
 Prompts, agent wiring, skills and tool selections are all files - Markdown and
 YAML - rather than code buried inside an application. So the folder can be
 committed, copied to another machine, reviewed in a pull request, and handed to
-someone else who runs it with one command. Credentials live in `$HOME`, never in
-the project, so there is no secret to strip before sharing it.
+someone else who runs it with one command. Model credentials live in `$HOME`,
+never in the project, and anything the project itself needs goes in a
+git-ignored `.env` - so there is no secret to strip before sharing it.
 
 ```
 my-project/
     SPECIFICATION.md             what this is for - the intent
-    INSTRUCTIONS.md              house rules, prepended to every agent
     agents.yaml                  who exists, what they may reach for
     agents/
+        instructions.md          house rules, prepended to every agent
+        <topic>-instructions.md  more of them, one subject at a time
         prompts/<name>.md        each agent's own brief
         skills/<name>/           knowledge loaded on demand, not always-on
     assets/                      reference material, read-only at /assets
     sandbox/Dockerfile           the container commands run in
     scripts/_setup.sh            the one command that initialises the project
+    .spec-sync/                  what the last sync with the spec applied
+    .env                         this project's environment - git-ignored
     sessions/                    one workspace, memory and trajectory each
         <id>/
             workspace/           what the agents can read and write

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/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/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) };