@zenera/cli 1.1.17 → 1.1.18

package/README.md

@@ -125,7 +125,7 @@ In the editor, describe the job in `SPECIFICATION.md`, then send this in the
 agent chat:
 
 ```
-/sync-with-spec
+/spec-sync-project
 ```
 
 It creates the specialists, responsibilities, tool access and handoffs the job
@@ -145,7 +145,7 @@ zen run my-project              # no prompt given: opens a full-screen terminal
 zen check my-project            # validate the project and every file it names
 zen inspect                     # open the last run's report.html
 zen list --sessions             # every project, its sessions and last run
-echo "triage this" | zen run my-project --quiet | jq
+echo "triage this" | zen run my-project --json | jq
 ```
 
 Standing inside the project, the name is optional: a bare `zen run`, `zen check`
@@ -156,7 +156,7 @@ session and uses the current directory as the workspace, with write access.
 `--session`, `--workspace` and `--read-only` override that.
 
 To change what the system does, update `SPECIFICATION.md` and send
-`/sync-with-spec` again. The next section explains that workflow in detail.
+`/spec-sync-project` again. The next section explains that workflow in detail.
 
 ## You write the specification; a coding agent writes the system
 
@@ -202,15 +202,15 @@ In the window that opens:
 
 1. **Edit `SPECIFICATION.md`** - what the system is for, which agents exist,
    what each may reach for, and what _done_ means.
-2. **Open the chat panel and send `/sync-with-spec`.** It reads the
+2. **Open the chat panel and send `/spec-sync-project`.** 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. **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.
+4. **Send `/spec-apply-feedback`.** It folds the answers you chose into
+   `SPECIFICATION.md` - never into a prompt - and then `/spec-sync-project` again.
 
 Back in the terminal: `zen check`, then `zen run`.
 
@@ -221,16 +221,16 @@ 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.      |
-| `/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 chat                | Does                                                             |
+| ---------------------- | ---------------------------------------------------------------- |
+| `/spec-sync-project`   | Makes every file match `SPECIFICATION.md`, both directions.      |
+| `/spec-apply-feedback` | Folds your answers in `SPECIFICATION-FEEDBACK.md` into the spec. |
+| `/project-review`      | 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
+`.github/prompts/spec-sync-project.prompt.md` into its chat instead - it is only a
 prompt. Alongside them, `.github/copilot-instructions.md` is the standing brief
 that explains this runtime to whatever agent is reading, and
 `.github/skills/zen-cli/` is the CLI's own reference for it.
@@ -240,7 +240,7 @@ that explains this runtime to whatever agent is reading, and
 ### The self-improving loop
 
 ```
-edit SPECIFICATION.md → /sync-with-spec → zen check → zen run
+edit SPECIFICATION.md → /spec-sync-project → zen check → zen run
         ↑                                                  ↓
         └───── refine the spec <-──── zen inspect <-───────┘
 ```
@@ -299,7 +299,7 @@ Read a codebase and leave a short written note about it in the workspace.
 - Every claim in it comes from a file that was actually read.
 ```
 
-Send `/sync-with-spec` in the editor's chat. It writes `agents.yaml` - who
+Send `/spec-sync-project` in the editor's chat. It writes `agents.yaml` - who
 exists, and what each may reach for:
 
 ```yaml
@@ -465,6 +465,7 @@ remove resources beyond the current project.
 | `key`     | The credential keyring - add, check, switch, remove.                 |
 | `models`  | What this machine can use - list, search, test, pick.                |
 | `run`     | Runs the project - the TUI on a terminal, a single answer otherwise. |
+| `meta`    | Runs the meta agent over the project - the one that edits it.        |
 | `inspect` | Opens or rebuilds a run's `report.html`.                             |
 | `memory`  | What the agents remember - size, listing, one node, or a whole page. |
 | `check`   | Validates the project and every file it names, and asks the models.  |
@@ -539,6 +540,88 @@ an accident.
 | `4`       | no usable credential |
 | `5`       | sandbox unavailable  |
 
+## The meta agent - the agent that works on the project
+
+`zen run` runs the agents your project describes. `zen meta` runs an agent _over_
+the project: a coding agent rooted at the project directory, which reads
+`SPECIFICATION.md`, changes `agents.yaml`, the prompts and the skills, and runs
+whatever commands it needs to check itself - on the keys already in your
+keyring, and not on anybody's subscription. It is the loop your editor's chat
+panel drives, as a command you can put in a script.
+
+```sh
+zen meta run "what does this project do?"
+zen meta run acme "review the last commit"
+zen meta prompts                             # which /<name> prompts this project has
+zen meta run /project-review                 # .github/prompts/project-review.prompt.md
+zen meta run acme /spec-sync-project agents/triage.md
+git diff | zen meta run "what broke?" --allow-tool read
+zen meta run --dry-run "hello"               # what would run, secrets masked
+```
+
+Every prompt goes through `run`, whether you typed it or it is a file: the
+alternative was a verb that appeared only sometimes, and a bare word after
+`zen meta` that was a subcommand on Tuesdays and a question on Wednesdays.
+
+It uses every tool without asking. The prompts it runs were written for an
+editor, where reading files, writing them and running commands is the whole
+point, and a `-p` run has nobody sitting there to answer the question - so the
+alternative is not a safer run but a stalled one. `--allow-tool read`,
+`--allow-tool 'shell(git:*)'` narrow it to what a particular run needs, and
+`--ask` puts the question back. It is your own checkout and your own key either
+way, so treat it as you would `git push`: fine on a project you own, worth
+narrowing on one you do not.
+
+The answer goes to stdout and the progress to stderr, like everything else here,
+so `zen meta run "…" > out.md` keeps the answer alone.
+
+Progress is a small window that rewrites itself rather than a transcript
+scrolling past, because only the last few steps say what it is doing now. The
+whole of it - the prompt, every tool call, the answer - is written as it happens
+to `.tmp/logs/meta.<when>.log`, whose path is printed before the run starts, so
+`tail -f` in another terminal follows a run already going. The answer alone is
+kept beside it as `.tmp/logs/meta.<when>.md`, named again once it has printed -
+a terminal turns that into something you click.
+
+`zen meta run /<name>` is the part an editor cannot do for you from a script.
+The prompts under `.github/prompts/` - `/spec-sync-project`, `/project-review` -
+are what a chat panel offers as slash commands, and nothing outside an editor
+reads them. zen reads one, drops the frontmatter and sends the body - so the
+same prompt runs from the editor, from a terminal and from CI.
+
+A terminal has no menu dropping down as you type a slash, so
+`zen meta prompts` lists what this project holds, each with its description.
+`zen meta run` with nothing to say asks the same question interactively.
+
+### Which model it runs on
+
+```sh
+zen meta model                            # the whole chain, with the winner marked
+zen meta model vertex/gemini-3.8-flash    # for every project on this machine
+zen meta model --local openai/gpt-5.6-sol # for this project only, via its .env
+zen meta model --pick                     # choose from providers you hold a key for
+```
+
+Highest first: `--model`, `ZENERA_META_MODEL` in the shell, the same variable in
+the project's `.env`, `zen meta model`, then the project's `agents.yaml`
+`model:`. When none of them answers, a key does: the best model zen knows of
+for the first provider you hold one for, named on stderr as it starts, so a
+fresh machine needs a key and nothing else.
+The store is separate from `agents.yaml` on purpose - the model a coding agent
+runs on is a personal choice about a tool, like a key, where `agents.yaml` is a
+committed decision about the project's own agents.
+
+Not every model works. The meta agent declares its tools in a form only the
+reasoning APIs accept, so use a reasoning model - `gpt-5.6-sol`,
+`claude-opus-5`, `gemini-3.8-flash`. Those three are also what it falls back
+to, and what `zen meta model --pick` offers.
+
+Setting one asks it a one-word question before storing it, so a model that will
+not answer is refused with the provider's own words rather than at the start of
+the next run. A typed prefix that names no provider - `vertes/...` - is caught
+before that, because it would otherwise be sent whole to a vendor you never
+named. `--force` stores a ref without asking.
+
 ## Credentials
 
 One keyring serves every provider, and a key goes in the same way whatever it

package/dist/banner.d.ts

@@ -1,3 +1,19 @@
+/** One per sub-brand, so two of them are told apart before the word is read. */
+declare const ACCENTS: {
+    readonly orange: {
+        readonly face: "\u001B[1;38;5;208m";
+        readonly shade: "\u001B[0;38;5;130m";
+    };
+    readonly cyan: {
+        readonly face: "\u001B[1;38;5;51m";
+        readonly shade: "\u001B[0;38;5;37m";
+    };
+    readonly mint: {
+        readonly face: "\u001B[1;38;5;121m";
+        readonly shade: "\u001B[0;38;5;78m";
+    };
+};
+export type Hue = keyof typeof ACCENTS;
 export interface BannerText {
     /** drawn white */
     head: string;
@@ -5,6 +21,8 @@ export interface BannerText {
     accent: string;
     /** the line underneath, dim */
     subtitle: string;
+    /** which neon to use. Default: orange, the `zen` mark. */
+    hue?: Hue;
 }
 export interface PrintBannerOptions {
     /** Render the block face even when the terminal is narrower than it. */
@@ -14,4 +32,5 @@ 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, options?: PrintBannerOptions): void;
+export {};
 //# sourceMappingURL=banner.d.ts.map

package/dist/banner.js

@@ -1,5 +1,4 @@
-import { styleText } from 'node:util';
-import { dim, note } from "./term.js";
+import { dim, note, styled } from "./term.js";
 // ---------------------------------------------------------------------------
 // The banner
 //
@@ -65,11 +64,14 @@ function big(word) {
 }
 /** A wordmark rather than a sentence, so the letters are set apart. */
 const spaced = (s) => [...s.toUpperCase()].join(' ');
-/** Whether anything should be coloured at all — `styleText`'s own answer. */
-const styling = () => styleText('dim', '.') !== '.';
 const RESET = '\u001b[0m';
 const HEAD = { face: '\u001b[1;38;5;231m', shade: '\u001b[0;38;5;244m' };
-const ACCENT = { face: '\u001b[1;38;5;208m', shade: '\u001b[0;38;5;130m' };
+/** One per sub-brand, so two of them are told apart before the word is read. */
+const ACCENTS = {
+    orange: { face: '\u001b[1;38;5;208m', shade: '\u001b[0;38;5;130m' },
+    cyan: { face: '\u001b[1;38;5;51m', shade: '\u001b[0;38;5;37m' },
+    mint: { face: '\u001b[1;38;5;121m', shade: '\u001b[0;38;5;78m' },
+};
 /** Runs of stroke and runs of bevel, alternating; spaces stay unstyled. */
 const RUNS = /[█▀▄]+|[^█▀▄ ]+/g;
 const isStroke = (run) => /[█▀▄]/.test(run);
@@ -77,11 +79,11 @@ const isStroke = (run) => /[█▀▄]/.test(run);
  * Two tones per word — without the darker bevel the letter is a flat outline
  * and the shadow reads as part of the stroke.
  */
-const paint = (text, tone) => styling()
+const paint = (text, tone) => styled()
     ? text.replace(RUNS, (run) => `${isStroke(run) ? tone.face : tone.shade}${run}${RESET}`)
     : text;
 /** The wordmark has no bevel to shade, so it is all face. */
-const flat = (text, tone) => styling() ? `${tone.face}${text}${RESET}` : text;
+const flat = (text, tone) => styled() ? `${tone.face}${text}${RESET}` : text;
 export const NEO_BANNER = {
     head: 'Zenera',
     accent: 'Neo',
@@ -92,17 +94,18 @@ export function bannerLines(text, columns = process.stderr.columns || 80) {
     // Trimmed: the widest accent row is the banner's right edge, and a pad left
     // inside a styled string cannot be trimmed away later.
     const accent = big(text.accent).map((row) => row.trimEnd());
+    const tone = ACCENTS[text.hue ?? 'orange'];
     const margin = ' '.repeat(INDENT);
     const width = INDENT + head[0].length + GAP + Math.max(...accent.map((row) => row.length));
     if (width > columns) {
         return [
-            `${margin}${flat(text.head.toUpperCase(), HEAD)} ${flat(text.accent.toUpperCase(), ACCENT)}`,
+            `${margin}${flat(text.head.toUpperCase(), HEAD)} ${flat(text.accent.toUpperCase(), tone)}`,
             `${margin}${dim(spaced(text.subtitle))}`,
         ];
     }
     const lines = [];
     for (let r = 0; r < HEIGHT; r++) {
-        lines.push(`${margin}${paint(head[r], HEAD)}${' '.repeat(GAP)}${paint(accent[r], ACCENT)}`);
+        lines.push(`${margin}${paint(head[r], HEAD)}${' '.repeat(GAP)}${paint(accent[r], tone)}`);
     }
     // Rules on both sides, centred under the art: the subtitle is a caption,
     // and without them a short line of spaced capitals floats.

package/dist/command.d.ts

@@ -1,3 +1,4 @@
+import type { BannerText } from './banner.ts';
 export interface Context {
     readonly args: readonly string[];
     readonly json: boolean;
@@ -9,6 +10,8 @@ export interface Command {
     readonly usage: string;
     /** lines printed under the usage line by `zen help <command>` */
     readonly details?: readonly string[];
+    /** printed instead of the `zen` banner, so the sub-brand shows through */
+    readonly banner?: BannerText;
     /**
      * 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.

package/dist/commands/index.js

@@ -5,6 +5,7 @@ import { inspect } from "./inspect.js";
 import { key } from "./key.js";
 import { list } from "./list.js";
 import { memory } from "./memory.js";
+import { meta } from "./meta.js";
 import { models } from "./models.js";
 import { open } from "./open.js";
 import { run } from "./run.js";
@@ -19,6 +20,7 @@ export const COMMANDS = {
     init,
     list,
     run,
+    meta,
     open,
     key,
     models,
@@ -37,6 +39,7 @@ export const ALIASES = {
     model: 'models',
     validate: 'check',
     doctor: 'check',
+    copilot: 'meta',
     report: 'inspect',
     mem: 'memory',
     edit: 'open',
@@ -49,7 +52,7 @@ export const EXTERNAL = {
         summary: 'A mock API from an openapi/swagger document.',
         usage: 'zen faker <serve|build|cache> [spec...]',
         install: 'npm i -g @zenera/faker',
-        banner: { head: 'Zenera', accent: 'Faker', subtitle: 'Mock API Server' },
+        banner: { head: 'Zenera', accent: 'Faker', subtitle: 'Mock API Server', hue: 'mint' },
     },
     rag: {
         package: '@zenera/rag',

package/dist/commands/init.js

@@ -140,7 +140,7 @@ export const init = {
         '',
         'SPECIFICATION.md states what the project is for and what it may do,',
         'and describes the one that was just written. Say what you are building',
-        'there, then run /sync-with-spec in your editor to make the rest match.',
+        'there, then run /spec-sync-project 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. It keeps a memory of its',

package/dist/commands/inspect.js

@@ -5,31 +5,39 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import { extname, join, normalize, resolve, sep } from 'node:path';
 import { parse } from "../args.js";
+import { sessionIds } from "../projects.js";
 import { project as resolveProject } from "../resolve.js";
-import { display, newestRun, newestSession, requireSession, runPaths, sessionPaths, } from "../session.js";
-import { bold, cyan, dim, invalidError, json, note, write } from "../term.js";
+import { display, listRuns, listSessions, newestRun, requireSession, runPaths, sessionPaths, } from "../session.js";
+import { ago, bold, choose, cyan, dim, invalidError, isInteractive, json, note, write, } from "../term.js";
 const USAGE = 'zen inspect [run] [--session <id>] [--open] [--rebuild] [--serve [port]]';
 export const inspect = {
     summary: "Open or rebuild a run's report.html.",
     usage: USAGE,
     details: [
-        'With no arguments: the newest run of the newest session.',
+        'With no arguments: asks which session and run, or takes the newest of',
+        'each when there is nothing to ask on.',
         '--serve starts a local server, which the report needs for its assets.',
+        '--memory <dir> reads that memory instead of the project’s, for a run',
+        'that was given `zen run --memory`.',
     ],
     run: async (ctx) => {
         const { values, positionals } = parse(ctx.args, {
             project: { type: 'string' },
             session: { type: 'string' },
+            memory: { type: 'string' },
             open: { type: 'boolean' },
             rebuild: { type: 'boolean' },
             serve: { type: 'string' },
         }, USAGE);
         const found = await resolveProject({ cwd: ctx.cwd, project: values.project });
         const dir = found.dir;
-        const session = pickSession(dir, values.session);
-        const run = pickRun(session, positionals[0]);
+        // Asking is only possible at a terminal, and only honest when the
+        // answer is not being parsed by something.
+        const asking = isInteractive() && !ctx.json;
+        const session = await pickSession(dir, values.session, positionals[0], asking);
+        const run = await pickRun(session, positionals[0], asking);
         if (values.rebuild || !existsSync(run.report)) {
-            await rebuild(session, run, await memory(dir));
+            await rebuild(session, run, await memory(dir, values.memory, ctx.cwd));
         }
         if (ctx.json) {
             json({ session: session.id, run: run.id, report: run.report });
@@ -52,17 +60,73 @@ export const inspect = {
 // ---------------------------------------------------------------------------
 // Choosing what to show
 // ---------------------------------------------------------------------------
-function pickSession(dir, asked) {
+/**
+ * Which session to read. With nothing named and a terminal to ask on, the
+ * person picks: "the newest" is a guess about which of a dozen runs they meant,
+ * and a wrong guess looks the same as a broken command.
+ */
+async function pickSession(dir, asked, run, asking) {
     if (asked) {
         return requireSession(dir, asked);
     }
-    const newest = newestSession(dir);
-    if (!newest) {
+    if (sessionIds(dir).length === 0) {
         throw invalidError('nothing has been run here yet', 'start one: zen run');
     }
-    return sessionPaths(dir, newest);
+    // A named run answers the question itself: it is in whichever session holds it.
+    if (!asking || run) {
+        return newestWorked(dir, run);
+    }
+    const worked = (await listSessions(dir)).filter((s) => s.runs > 0);
+    if (worked.length === 0) {
+        throw invalidError('no runs yet — every session is empty', 'start one: zen run');
+    }
+    return await choose('Which session?', worked.map((s) => ({
+        label: s.id,
+        detail: [
+            s.title,
+            `${s.runs} run${s.runs === 1 ? '' : 's'}`,
+            ago(s.lastRunAt ?? s.createdAt),
+            s.busy ? 'running' : '',
+        ]
+            .filter(Boolean)
+            .join('  '),
+        value: sessionPaths(dir, s.id),
+    })));
 }
-function pickRun(session, asked) {
+/**
+ * The newest session that has a report to show — not simply the newest. A
+ * session exists before its first run and outlives one that never recorded
+ * anything, so the newest is routinely empty and picking it blindly answers
+ * "has no runs" about a project full of them.
+ */
+function newestWorked(dir, run) {
+    for (const id of sessionIds(dir).reverse()) {
+        const session = sessionPaths(dir, id);
+        if (run ? existsSync(runPaths(session, run).dir) : newestRun(session)) {
+            return session;
+        }
+    }
+    throw invalidError(run ? `no run ${run} in any session` : 'no runs yet — every session is empty', run ? 'see: zen list --sessions' : 'start one: zen run');
+}
+async function pickRun(session, asked, asking) {
+    if (!asked && asking) {
+        const runs = await listRuns(session);
+        if (runs.length === 0) {
+            throw invalidError(`session ${session.id} has no runs`);
+        }
+        // One run is not a question.
+        return await choose(`Which run of ${session.id}?`, runs.map((r) => ({
+            label: r.id,
+            detail: [
+                r.agent,
+                r.error ? 'failed' : r.stopReason,
+                ago(r.finishedAt ?? r.startedAt),
+            ]
+                .filter(Boolean)
+                .join('  '),
+            value: runPaths(session, r.id),
+        })));
+    }
     const id = asked ?? newestRun(session);
     if (!id) {
         throw invalidError(`session ${session.id} has no runs`);
@@ -98,9 +162,9 @@ async function rebuild(session, run, store) {
  * has the shape of what the run recalled but not a word of it; a run that
  * never touched memory pays nothing, because the report asks for no node.
  */
-async function memory(dir) {
+async function memory(dir, override, cwd) {
     const { config } = readProjectConfig(dir);
-    const at = memoryDir(dir, config);
+    const at = memoryDir(dir, config, override && resolve(cwd, override));
     if (!at || !existsSync(join(at, 'manifest.json'))) {
         return undefined;
     }

package/dist/commands/key.js

@@ -454,10 +454,57 @@ const env = async (ctx, args) => {
 function shellQuote(value) {
     return `'${value.replaceAll("'", `'\\''`)}'`;
 }
+/**
+ * One credential on stdout, alone, for a tool that wants a fresh one before
+ * every request rather than an export that goes stale — `zen meta` hands this
+ * to copilot as `COPILOT_PROVIDER_API_KEY_COMMAND`.
+ *
+ * A stored secret is simply printed. A service-account file is exchanged for
+ * an OAuth access token, which is the part worth having a command for: those
+ * last an hour, and a session does not.
+ */
+const token = async (ctx, args) => {
+    const { positionals } = parse(args, {}, 'zen key token <provider>[/name]');
+    const { provider, name } = parseRef(positionals[0] ?? 'vertex');
+    const store = await KeyStore.open();
+    const entry = name ? store.find(provider, name) : store.active(provider);
+    if (!entry) {
+        throw credentialError(`no ${provider} key`, `add one: zen key add ${provider}`);
+    }
+    if (entry.holds === 'secret') {
+        write(store.reveal(entry));
+        return;
+    }
+    const { GoogleAuth } = await import('google-auth-library');
+    const auth = new GoogleAuth({
+        keyFile: store.fileOf(entry),
+        scopes: ['https://www.googleapis.com/auth/cloud-platform'],
+    });
+    const access = await (await auth.getClient()).getAccessToken();
+    if (!access.token) {
+        throw credentialError(`${keyId(entry)} minted no token`, 'check the service account is still enabled');
+    }
+    if (ctx.json) {
+        json({ key: keyId(entry), token: access.token });
+        return;
+    }
+    write(access.token);
+};
 // ---------------------------------------------------------------------------
 // Dispatch
 // ---------------------------------------------------------------------------
-const SUBS = { ls, list: ls, add, use, check, rm, remove: rm, show, env };
+const SUBS = {
+    ls,
+    list: ls,
+    add,
+    use,
+    check,
+    rm,
+    remove: rm,
+    show,
+    env,
+    token,
+};
 export const key = {
     summary: 'The credential store: add, choose, verify and export API keys.',
     usage: USAGE,
@@ -480,6 +527,7 @@ export const key = {
         '  zen key rm <provider>/<name>      Forget one.',
         '  zen key show <ref> [--reveal]     Masked by default.',
         '  zen key env [provider …]          Shell exports, for other tools.',
+        '  zen key token [ref]               One credential on stdout, minted now.',
     ],
     run: async (ctx) => {
         const [name, ...rest] = ctx.args;

package/dist/commands/memory.js

@@ -2,7 +2,7 @@ import { ALL_AGENTS, buildMemoryReport, hostPath, memoryDir, MemoryIndex, Memory
 import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
-import { isAbsolute, join, resolve } from 'node:path';
+import { basename, isAbsolute, join, 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";
@@ -39,6 +39,7 @@ export const memory = {
         '  forget <id...>         Remove nodes, their vectors and their files.',
         '',
         '  --project <name|dir>   Which project. Defaults to the one you are in.',
+        '  --dir <dir>            Read this memory directory instead of the project’s.',
         '  --kind <name>          Only this kind of node.',
         '  --audience <name>      Only nodes committed under this label.',
         '  --files                Only nodes that remember a file.',
@@ -59,6 +60,7 @@ export const memory = {
     run: async (ctx) => {
         const { values, positionals } = parse(ctx.args, {
             project: { type: 'string' },
+            dir: { type: 'string' },
             kind: { type: 'string' },
             audience: { type: 'string' },
             files: { type: 'boolean' },
@@ -73,7 +75,7 @@ export const memory = {
             throw usageError(`unknown subcommand: ${what}`, USAGE);
         }
         const rest = positionals.slice(1);
-        const opened = await open(ctx.cwd, values.project);
+        const opened = await open(ctx.cwd, values.project, values.dir);
         try {
             switch (what) {
                 case 'stats':
@@ -98,8 +100,19 @@ export const memory = {
  * project would resolve models and read every prompt file to inspect a graph
  * that needs none of it — and would fail on a project whose credentials are
  * missing, which is exactly when someone is debugging.
+ *
+ * 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.
  */
-async function open(cwd, want) {
+async function open(cwd, want, at) {
+    if (at) {
+        const dir = resolve(cwd, at);
+        if (!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) };
+    }
     const project = await resolveProject({ cwd, project: want });
     const { config } = readProjectConfig(project.dir);
     const dir = memoryDir(project.dir, config);

package/dist/commands/meta.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from '../command.ts';
+export declare const meta: Command;
+//# sourceMappingURL=meta.d.ts.map