@zenera/cli 1.1.17 → 1.1.18

package/dist/podman.js

@@ -1,5 +1,5 @@
 import { runProcess, SandboxError } from '@zenera/neo';
-import { readdirSync, statSync } from 'node:fs';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
 import { CliError, confirm, dim, EXIT, isInteractive, note, progress } from "./term.js";
@@ -111,9 +111,71 @@ function instructions() {
         case 'win32':
             return 'install it with: winget install RedHat.Podman';
         default:
-            return 'install it with your package manager, e.g. apt install podman';
+            return linuxInstructions();
     }
 }
+/**
+ * How podman gets installed, by distribution — podman.io/docs/installation,
+ * which is where any of these should be checked against.
+ *
+ * "Install it with your package manager" is advice nobody needs and everybody
+ * has to translate; the host already says which one it has, so the message may
+ * as well be the line to paste. It stops at the line: `sudo` wants a terminal
+ * to ask for a password on and `runProcess` gives it a pipe, so running this
+ * for the user would hang rather than help.
+ */
+const LINUX_INSTALL = {
+    alpine: 'install it with: sudo apk add podman',
+    arch: 'install it with: sudo pacman -S podman',
+    centos: 'install it with: sudo dnf -y install podman',
+    debian: 'install it with: sudo apt-get -y install podman',
+    fedora: 'install it with: sudo dnf -y install podman',
+    gentoo: 'install it with: sudo emerge app-containers/podman',
+    // Nix installs nothing imperatively worth keeping: the podman that works
+    // rootless is the one the module turns on.
+    nixos: 'enable it with: virtualisation.podman.enable = true; then: sudo nixos-rebuild switch',
+    opensuse: 'install it with: sudo zypper install podman',
+    rhel: 'install it with: sudo dnf -y install podman',
+    sles: 'install it with: sudo zypper install podman',
+    suse: 'install it with: sudo zypper install podman',
+    ubuntu: 'install it with: sudo apt-get update && sudo apt-get -y install podman',
+    void: 'install it with: sudo xbps-install -S podman',
+};
+function linuxInstructions() {
+    for (const id of osRelease()) {
+        // `opensuse-leap` and `rhel-9` name the same package manager as their
+        // family does, so a miss on the whole id is worth one on its stem.
+        const how = LINUX_INSTALL[id] ?? LINUX_INSTALL[id.split(/[-.]/)[0] ?? ''];
+        if (how) {
+            return how;
+        }
+    }
+    return 'install it with your package manager, e.g. apt-get install podman';
+}
+/**
+ * `ID` first, then `ID_LIKE` — the distribution's own name, then the families
+ * it claims to behave like, which is how Rocky, Alma and Mint get answered
+ * without being listed.
+ */
+function osRelease() {
+    let text;
+    try {
+        text = readFileSync('/etc/os-release', 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const read = (key) => {
+        const line = new RegExp(`^${key}=(.*)$`, 'm').exec(text)?.[1] ?? '';
+        return line
+            .trim()
+            .replace(/^["']|["']$/g, '')
+            .toLowerCase()
+            .split(/\s+/)
+            .filter(Boolean);
+    };
+    return [...read('ID'), ...read('ID_LIKE')];
+}
 // ---------------------------------------------------------------------------
 // The machine
 // ---------------------------------------------------------------------------

package/dist/projects.d.ts

@@ -16,7 +16,7 @@ export interface Project {
  * and does not edit — and the paths are resolved, because the podman machine on
  * macOS shares the real path or nothing.
  */
-export declare function projectMounts(root: string, config: ProjectConfig): SandboxMount[];
+export declare function projectMounts(root: string, config: ProjectConfig, memoryAt?: string): SandboxMount[];
 /** Walks up from `start` looking for a project configuration. */
 export declare function findUp(start: string): Promise<Project | undefined>;
 export declare function openDir(dir: string): Promise<Project>;
@@ -70,6 +70,14 @@ export declare const sessionsDir: (projectDir: string) => string;
 /** Session ids, oldest first. Only well-formed stamps count as sessions. */
 export declare function sessionIds(projectDir: string): string[];
 export declare function runIds(sessionDir: string): string[];
+/**
+ * When this project was last worked in, as a stamp, or `undefined` for one
+ * that never has been. Session and run ids are stamps in the same format, so
+ * the newest of either compares directly — and reading directory NAMES is what
+ * keeps this cheap enough to ask of every registered project before drawing a
+ * chooser.
+ */
+export declare function lastUsedAt(projectDir: string): string | undefined;
 /**
  * What a tree occupies, in allocated blocks rather than in bytes, because a
  * sparse file costs what it was given and not what it claims. Symlinks are

package/dist/projects.js

@@ -35,7 +35,7 @@ export function isProjectDir(dir) {
  * and does not edit — and the paths are resolved, because the podman machine on
  * macOS shares the real path or nothing.
  */
-export function projectMounts(root, config) {
+export function projectMounts(root, config, memoryAt) {
     const mounts = [];
     const assets = assetsDir(root, config);
     if (assets) {
@@ -47,7 +47,7 @@ export function projectMounts(root, config) {
     for (const dir of skillMounts(skillDirs(root, config), SKILLS_MOUNT)) {
         mounts.push({ host: realpathSync(dir.path), at: dir.at, readOnly: true });
     }
-    const memory = memoryDir(root, config);
+    const memory = memoryDir(root, config, memoryAt);
     if (memory) {
         // Created here because the mount is decided before the project is
         // loaded, and podman would refuse a source that does not exist yet.
@@ -224,6 +224,23 @@ export function sessionIds(projectDir) {
 export function runIds(sessionDir) {
     return stampedChildren(join(sessionDir, 'runs'));
 }
+/**
+ * When this project was last worked in, as a stamp, or `undefined` for one
+ * that never has been. Session and run ids are stamps in the same format, so
+ * the newest of either compares directly — and reading directory NAMES is what
+ * keeps this cheap enough to ask of every registered project before drawing a
+ * chooser.
+ */
+export function lastUsedAt(projectDir) {
+    let last;
+    for (const id of sessionIds(projectDir)) {
+        const newest = runIds(join(sessionsDir(projectDir), id)).at(-1) ?? id;
+        if (!last || newest > last) {
+            last = newest;
+        }
+    }
+    return last;
+}
 function stampedChildren(dir) {
     if (!existsSync(dir)) {
         return [];

package/dist/resolve.js

@@ -23,7 +23,13 @@ export async function project(want) {
     if (!isInteractive()) {
         throw usageError('not inside a project', 'name one with --project');
     }
-    const chosen = await choose('Which project?', known.map((e) => ({ label: e.name, detail: e.path, value: e })));
+    // Most recently worked in first: the answer to "which project" is nearly
+    // always the one from last time, and registration order is nothing to a
+    // person. A project never run sorts last, by name.
+    const ranked = known
+        .map((entry) => ({ entry, used: Projects.lastUsedAt(entry.path) ?? '' }))
+        .sort((a, b) => b.used.localeCompare(a.used) || a.entry.name.localeCompare(b.entry.name));
+    const chosen = await choose('Which project?', ranked.map(({ entry }) => ({ label: entry.name, detail: entry.path, value: entry })));
     return Projects.openDir(chosen.path);
 }
 // ---------------------------------------------------------------------------

package/dist/sandbox.d.ts

@@ -10,6 +10,8 @@ export interface SandboxSetup {
     build?: ResolvedBuild;
     /** host side of the container's `$HOME`, created only if it is ever needed */
     home: string;
+    /** every tree bound into the container besides the workspace itself */
+    mounts: readonly SandboxMount[];
 }
 export interface SandboxInputs {
     config: ProjectConfig;

package/dist/sandbox.js

@@ -103,7 +103,7 @@ export function buildSandbox(opts) {
         readOnly: opts.readOnly,
         mounts,
     });
-    return { pool, spec, image: spec.image ?? DEFAULT_SANDBOX_IMAGE, build, home };
+    return { pool, spec, image: spec.image ?? DEFAULT_SANDBOX_IMAGE, build, home, mounts };
 }
 /**
  * An agent's overrides on the project's block. `image` and `build` answer the

package/dist/scaffold.js

@@ -244,7 +244,7 @@ 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
+    // Where `/spec-sync-project` 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.

package/dist/session.d.ts

@@ -71,6 +71,16 @@ export interface RunMeta {
     error?: string;
 }
 export declare function writeRunMeta(p: RunPaths, meta: RunMeta): void;
+export interface RunSummary {
+    id: string;
+    startedAt?: string;
+    finishedAt?: string;
+    agent?: string;
+    stopReason?: string;
+    error?: string;
+}
+/** Newest first — the order a picker wants. */
+export declare function listRuns(session: SessionPaths): Promise<RunSummary[]>;
 export declare function newestRun(session: SessionPaths): string | undefined;
 /** A path to show a human: relative when that is shorter, absolute otherwise. */
 export declare function display(path: string, from?: string): string;

package/dist/session.js

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node
 import { hostname } from 'node:os';
 import { join, relative, resolve } from 'node:path';
 import { readJson, writeJson } from "./home.js";
-import { isStamp, stamp } from "./ids.js";
+import { isStamp, stamp, stampInstant } from "./ids.js";
 import { alive, isBusy, runIds, sessionIds, sessionsDir } from "./projects.js";
 import { CliError, EXIT, invalidError, usageError } from "./term.js";
 export function sessionPaths(projectDir, id) {
@@ -145,6 +145,24 @@ export function createRun(session) {
 export function writeRunMeta(p, meta) {
     writeJson(p.meta, meta, 0o644);
 }
+/** Newest first — the order a picker wants. */
+export async function listRuns(session) {
+    const out = [];
+    for (const id of runIds(session.dir).reverse()) {
+        // A run killed before it recorded anything still has an id, and the id
+        // says when it started, so it is listable without its meta.
+        const meta = await readJson(runPaths(session, id).meta, {});
+        out.push({
+            id,
+            startedAt: meta.startedAt ?? stampInstant(id),
+            finishedAt: meta.finishedAt,
+            agent: meta.agent,
+            stopReason: meta.stopReason,
+            error: meta.error,
+        });
+    }
+    return out;
+}
 export function newestRun(session) {
     return runIds(session.dir).at(-1);
 }

package/dist/term.d.ts

@@ -26,6 +26,13 @@ export declare const red: (s: string) => string;
 export declare const green: (s: string) => string;
 export declare const yellow: (s: string) => string;
 export declare const cyan: (s: string) => string;
+/**
+ * Whether anything should be coloured at all — `styleText`'s own answer, asked
+ * by the places that write escape codes directly and so cannot inherit it.
+ */
+export declare const styled: () => boolean;
+/** The text as it reads without styling, which is what a file wants. */
+export declare const plain: (s: string) => string;
 export declare function pad(s: string, to: number): string;
 /** Column-aligned rows. Trailing whitespace is trimmed so `diff` stays quiet. */
 export declare function table(rows: readonly (readonly string[])[], gap?: number): string[];

package/dist/term.js

@@ -45,10 +45,17 @@ export const red = (s) => styleText('red', s);
 export const green = (s) => styleText('green', s);
 export const yellow = (s) => styleText('yellow', s);
 export const cyan = (s) => styleText('cyan', s);
+/**
+ * Whether anything should be coloured at all — `styleText`'s own answer, asked
+ * by the places that write escape codes directly and so cannot inherit it.
+ */
+export const styled = () => styleText('dim', '.') !== '.';
 /** Visible width — style codes must not count towards column alignment. */
 // eslint-disable-next-line no-control-regex
 const ANSI = /\u001b\[[0-9;]*m/g;
-const width = (s) => s.replace(ANSI, '');
+/** The text as it reads without styling, which is what a file wants. */
+export const plain = (s) => s.replace(ANSI, '');
+const width = plain;
 export function pad(s, to) {
     return s + ' '.repeat(Math.max(0, to - width(s).length));
 }

package/dist/tui/app.js

@@ -43,7 +43,7 @@ function Answer({ text }) {
     const { stdout } = useStdout();
     const width = answerWidth(stdout?.columns ?? 80);
     const segments = segmentsOf(text);
-    // Bounded, like every answer in `examples/`: prose that runs the width of a
+    // Bounded, like every answer in `examples/sdk/`: prose that runs the width of a
     // wide terminal is a worse read than prose that stops, and the box is also
     // what separates the answer from the machinery that produced it.
     return (_jsx(Box, { flexDirection: "column", width: width, borderStyle: "round", borderDimColor: true, paddingX: 1, marginY: 1, children: segments.map((s, i) => s.code ? (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: `\u250c\u2500${s.title ? ` ${s.title}` : ''}` }), s.lines.map((l, j) => (_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { dimColor: true, children: '\u2502 ' }), _jsx(Text, { wrap: "truncate-end", children: l || ' ' })] }, j))), _jsx(Text, { dimColor: true, children: '\u2514\u2500' })] }, i)) : (_jsx(Text, { children: s.lines.join('\n') }, i))) }));
@@ -431,7 +431,7 @@ function App({ engine, options, theme }) {
             recall(1);
         }
     });
-    return (_jsx(ThemeContext.Provider, { value: theme, children: _jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: [BANNER, ...lines], children: (item) => isBanner(item) ? (_jsx(Header, { engine: engine, readOnly: options.readOnly, started: options.started }, item.key)) : (_jsx(Row, { line: item }, item.key)) }), _jsxs(Box, { flexDirection: "column", justifyContent: "flex-end", height: busy ? grown.current : undefined, overflow: "hidden", children: [_jsx(Branches, { boxes: fitted.boxes, spin: spin, columns: columns }), _jsx(Activity, { rows: fitted.trunk, hidden: fitted.hidden }), thinking && budget.thinking ? (_jsx(Thinking, { text: thinking, columns: columns, rows: budget.thinking, spin: spin, live: streaming })) : null, live ? _jsx(Live, { text: live, columns: columns, rows: budget.live }) : null] }), _jsx(Footer, { agent: agent, busy: busy, spin: spin, running: mine, forked: branches.current.size, step: step, model: model, stats: stats, inflight: inflight, reasoning: streaming, columns: columns }), busy ? null : (_jsxs(Box, { children: [_jsx(Text, { color: theme.accent, children: "\u203A " }), _jsx(TextInput, { defaultValue: draft, placeholder: "Ask something\u2026 (\u2191 for history, /help for commands)", onChange: remember, onSubmit: submit }, generation)] }))] }) }));
+    return (_jsx(ThemeContext.Provider, { value: theme, children: _jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: [BANNER, ...lines], children: (item) => isBanner(item) ? (_jsx(Header, { engine: engine, readOnly: options.readOnly, started: options.started }, item.key)) : (_jsx(Row, { line: item }, item.key)) }), _jsxs(Box, { flexDirection: "column", justifyContent: "flex-end", height: busy ? grown.current : undefined, overflow: "hidden", children: [_jsx(Branches, { boxes: fitted.boxes, spin: spin, columns: columns }), _jsx(Activity, { rows: fitted.trunk, hidden: fitted.hidden }), thinking && budget.thinking ? (_jsx(Thinking, { text: thinking, columns: columns, rows: budget.thinking, spin: spin, live: streaming })) : null, live ? _jsx(Live, { text: live, columns: columns, rows: budget.live }) : null] }), _jsx(Footer, { agent: agent, busy: busy, spin: spin, frame: frame, running: mine, forked: branches.current.size, step: step, model: model, stats: stats, inflight: inflight, reasoning: streaming, columns: columns }), busy ? null : (_jsxs(Box, { children: [_jsx(Text, { color: theme.accent, children: "\u203A " }), _jsx(TextInput, { defaultValue: draft, placeholder: "Ask something\u2026 (\u2191 for history, /help for commands)", onChange: remember, onSubmit: submit }, generation)] }))] }) }));
 }
 function Header({ engine, readOnly, started, }) {
     const theme = useTheme();
@@ -467,7 +467,7 @@ const GUTTER = 2;
 /**
  * A fan-out, demultiplexed into one box per branch. Interleaving eight
  * branches' calls into a single list is not a picture of parallel work, it is
- * eight pictures shuffled together; a box per branch is what `examples/board.ts`
+ * eight pictures shuffled together; a box per branch is what `examples/sdk/board.ts`
  * gets right and what makes the shape of the fork legible at a glance.
  *
  * A box shows the last few calls the branch made and whatever it has in flight,
@@ -655,7 +655,35 @@ function Live({ text, columns, rows }) {
 }
 /** The label column the two number rows line up behind. */
 const LABEL = 10;
-function Footer({ agent, busy, spin, running, forked, step, model, stats, inflight, reasoning, columns, }) {
+/** Frames the crest spends past the end, so a sweep reads as a pass, not a loop. */
+const SWEEP_GAP = 6;
+/**
+ * A crest of weight travelling through a word, left to right.
+ *
+ * The spinner is proof the process is alive, but it is chrome and the eye
+ * reads the word beside it — a word that never moves is what a hung run looks
+ * like. The wave is weight rather than hue because the theme has no ramp to
+ * spend: dim at rest, the terminal's own weight at the crest, and the word
+ * keeps whatever colour its role gave it.
+ */
+function Shimmer({ text, frame, color, }) {
+    const chars = [...text];
+    // A new word is a new thing to say, so the sweep starts over on it rather
+    // than picking the crest up wherever the last word had got to.
+    const begun = useRef(frame);
+    const said = useRef(text);
+    if (said.current !== text) {
+        said.current = text;
+        begun.current = frame;
+    }
+    const head = (frame - begun.current) % (chars.length + SWEEP_GAP);
+    return (_jsx(Text, { children: chars.map((ch, i) => {
+            // The crest sits on the head and the tail drags behind it.
+            const behind = head - i;
+            return (_jsx(Text, { color: color, bold: behind === 0, dimColor: behind < 0 || behind > 2, children: ch }, i));
+        }) }));
+}
+function Footer({ agent, busy, spin, frame, running, forked, step, model, stats, inflight, reasoning, columns, }) {
     const theme = useTheme();
     // Who before what. The agent is the subject of the sentence, and in a
     // handoff it is the thing that changed.
@@ -687,7 +715,7 @@ function Footer({ agent, busy, spin, running, forked, step, model, stats, inflig
     // Nothing of its own in flight means the word above is about reasoning, so
     // it takes the same hue the reasoning block does.
     const musing = !running.length && !forked;
-    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { children: [_jsx(Text, { color: theme.accent, children: agent }), busy ? (_jsxs(Text, { color: musing ? theme.thinking.color : theme.warn, children: ['  ', spin, " ", status] })) : null, busy ? _jsx(Text, { dimColor: true, children: `  ${aside}` }) : null] }), inflight ? (_jsxs(Text, { dimColor: true, children: ['this turn'.padEnd(LABEL), tokens(inflight.usage), ` · ${secs(inflight.durationMs)}`] })) : (_jsxs(_Fragment, { children: [stats.turn ? (_jsxs(Text, { dimColor: true, children: ['last turn'.padEnd(LABEL), tokens(stats.turn), stats.durationMs === undefined
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { children: [_jsx(Text, { color: theme.accent, children: agent }), busy ? (_jsxs(Text, { color: musing ? theme.thinking.color : theme.warn, children: ['  ', spin, ' ', _jsx(Shimmer, { text: status, frame: frame, color: musing ? theme.thinking.color : theme.warn })] })) : null, busy ? _jsx(Text, { dimColor: true, children: `  ${aside}` }) : null] }), inflight ? (_jsxs(Text, { dimColor: true, children: ['this turn'.padEnd(LABEL), tokens(inflight.usage), ` · ${secs(inflight.durationMs)}`] })) : (_jsxs(_Fragment, { children: [stats.turn ? (_jsxs(Text, { dimColor: true, children: ['last turn'.padEnd(LABEL), tokens(stats.turn), stats.durationMs === undefined
                                 ? ''
                                 : ` · ${durationOf(stats.durationMs) ?? ''}`] })) : null, _jsxs(Text, { dimColor: true, children: ['session'.padEnd(LABEL), tokens(stats.session), stats.calls
                                 ? ` · ${stats.calls} ${stats.calls === 1 ? 'call' : 'calls'}`

package/dist/tui/wrap.d.ts

@@ -71,7 +71,7 @@ export declare function branchRows(count: number, allowance: number): number;
 /**
  * How wide the answer is drawn. A line of prose spanning a 200-column terminal
  * is measurably harder to read than one that stops, which is why every demo in
- * `examples/` puts its answer in a box of bounded width — the terminal is the
+ * `examples/sdk/` puts its answer in a box of bounded width — the terminal is the
  * page, not the paragraph.
  */
 export declare function answerWidth(columns: number): number;

package/dist/tui/wrap.js

@@ -138,7 +138,7 @@ export function branchRows(count, allowance) {
 /**
  * How wide the answer is drawn. A line of prose spanning a 200-column terminal
  * is measurably harder to read than one that stops, which is why every demo in
- * `examples/` puts its answer in a box of bounded width — the terminal is the
+ * `examples/sdk/` puts its answer in a box of bounded width — the terminal is the
  * page, not the paragraph.
  */
 export function answerWidth(columns) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.17",
+    "version": "1.1.18",
     "description": "Command-line front end for @zenera/neo: agentic projects you can run, share and commit.",
     "keywords": [
         "agents",
@@ -51,10 +51,11 @@
         "@inkjs/ui": "^2.0.0",
         "ink": "^7.1.1",
         "react": "^19.2.8",
-        "@zenera/neo": "^1.1.17",
+        "@zenera/neo": "^1.1.18",
         "@anthropic-ai/sdk": "^0.120.0",
         "@google/genai": "^2.18.0",
         "@openrouter/sdk": "^1.2.80",
+        "google-auth-library": "^10.0.0",
         "openai": "^6.0.0"
     }
 }

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

@@ -59,8 +59,9 @@ schema index it is expected to consult all count. When it does, also load the
 
 Then create or maintain `agents/skills/rag_search/SKILL.md` in the target
 project. Its description must say when an agent should load it. Its body must
-name the target's actual RAG surface and index location, state which agents may
-use it, and give an executable retrieval procedure:
+name the target's actual RAG surface and index location, open by stating what an
+agent needs to follow it and what to do without that, and give an executable
+retrieval procedure:
 
 1. Discover document and section names with the exact listing command or tool.
 2. Start with hybrid search for a complete natural-language question.
@@ -72,6 +73,16 @@ use it, and give an executable retrieval procedure:
 5. Retrieve a complete section verbatim, or list a table and read its inclusive
    line range when every row is needed.
 
+**State the prerequisite, not the audience.** `skills.allow` restricts loading
+and `zen check` validates it; a list of agent names in the body is a second copy
+of that binding with nothing keeping the two in step, and it is stale the first
+time an agent is renamed (§4.2, rule 10). What a reader can act on is what the
+procedure needs - the RAG tools, or `sandbox:*` and the index at its path - and
+what to do without them: _"say so and stop; do not answer from memory"_ (§4.2,
+rule 6). Put it in the first lines of the body, because the catalog is mounted
+whole at `/skills` before any binding applies (§3.4.1), so an agent that was
+never granted this skill can still read the file and start following it.
+
 Keep this as runtime guidance, not a pointer to this editor reference: a target
 agent cannot read `.github/` or this project layout while it runs. Include only
 the commands, tools, paths, and corpus-specific constraints that exist in the
@@ -106,7 +117,7 @@ without losing anything. Never paraphrase the reference into prose of your own.
 See §5.3.
 
 A project with a `SPECIFICATION.md` carries one more: **`.spec-sync/` records
-what the last `/sync-with-spec` pass applied**, and the `zen-spec-sync` skill is
+what the last `/spec-sync-project` pass applied**, and the `zen-spec-sync` skill is
 loaded before running that prompt, whether or not a baseline exists yet. The
 state is committed, because a record only the last machine has is not a record.
 Two things to watch for, neither of which `zen check` reports: a baseline that
@@ -207,7 +218,7 @@ my-project/
 │   ├── prompts/*.prompt.md       tasks you invoke by name
 │   └── skills/*/SKILL.md         reference the editor loads on demand
 ├── .env                          this project's environment - NEVER committed
-├── .spec-sync/                   what the last /sync-with-spec applied - §0.1
+├── .spec-sync/                   what the last /spec-sync-project applied - §0.1
 ├── agents.yaml                   who exists, what they may reach for
 ├── agents/
 │   ├── instructions.md            house rules, prepended to every agent
@@ -767,10 +778,18 @@ groups - the workspace tools (§3.6), the sandbox tools (§3.7) and the web tool
 the machine, so `tools:` is the whole permission model: an agent that does not
 name a tool cannot use it, whatever its prompt says.
 
-Two rules follow:
+Three rules follow:
 
 - **Grant the narrowest set the job needs.** An agent that only reviews should
   not be holding the tools that overwrite files.
+- **Grant by group, then subtract.** Write `workspace:*` and take away what this
+  agent must not have - not a hand-picked list of names. The tools in a group are
+  designed to be used together, and a list assembled one name at a time leaves out
+  the companion the model reaches for next: `write_file` without `apply_patch`
+  turns every one-line edit into a whole-file rewrite, and `read_file` without
+  `list_dir` and `find_files` leaves it guessing at paths. A group also tracks the
+  runtime - a tool added to it later reaches the agent, where an enumerated list
+  silently stays behind.
 - **Say in the prompt when to reach for what.** A granted tool the prompt never
   mentions is used at the model's discretion, which is not the same as never.
 
@@ -830,6 +849,13 @@ refuses the file. `workspace:*` needs no quoting. There is no name globbing -
 `read_*` is an unknown tool, because a selector should track a declared set, not
 a naming habit.
 
+Both agents above are written the way to write them: **the group, minus the
+exceptions**. `tools: [read_file, write_file]` is the shape to avoid - it reads
+as a considered decision and is usually an incomplete one, since the tool that
+makes the granted one usable is the tool that was left out. Subtracting says
+which capability is being withheld, which is the thing a reviewer needs to check
+and the thing the next tool added to the group will not quietly defeat.
+
 `zen run --read-only` withholds the four mutating tools whatever `agents.yaml`
 asks for: the deployment overriding the repository, as everywhere else.
 
@@ -1075,6 +1101,7 @@ zen run                         open the entry agent on this project
 zen run "what changed?"         one shot; stdout is the answer
 zen run --session <id>          continue a session
 zen run --workspace ./repo      what the agent may read and write
+zen run --memory ./mem          where the agents remember into, instead of memory/
 zen run --model careful         override the default model for this run
 zen run --image <ref>           override the sandbox image for this run, ignoring build:
 zen run --read-only             withhold every tool that can write
@@ -1095,11 +1122,17 @@ OPENAI_API_KEY=...
 ANTHROPIC_API_KEY=...
 GOOGLE_APPLICATION_CREDENTIALS=./.keys/vertex.json
 EXA_API_KEY=...
+ZENERA_META_MODEL=vertex/gemini-3.8-flash
 ```
 
 Never commit. Never inline a key into `agents.yaml` - use `${VAR}`. Never print a
 key in a log line, a test fixture, or a chat message.
 
+`ZENERA_META_MODEL` is the exception that is not a credential: it names the model
+`zen meta` runs the meta agent on in this project, as a zen ref. It is here
+rather than in `agents.yaml` because it is a choice about a tool, not about the
+project's own agents. `zen meta model` prints where the answer came from.
+
 ### 3.11 `assets/`
 
 `assets/` next to `agents.yaml` - or `assets: <path>` - is reference material
@@ -1915,10 +1948,17 @@ candidates; these are the judgements to make about each one)**
 - [ ] Catalog >~30 entries → `discovery: search`
 - [ ] A skill that ships a script writes its `/skills/<name>/...` path, the agent
       holds `sandbox:*`, and the sandbox image already has the interpreter
+- [ ] A skill whose procedure needs particular tools, an index or a mounted file
+      opens by naming them and says what to do without them - rather than naming
+      the agents allowed to load it, which `agents.yaml` already decides - §0.1
 
 **Tools**
 
 - [ ] Every agent holds the narrowest set its job needs
+- [ ] Every `tools:` list is a group selector minus its exceptions, not an
+      enumeration of individual names - §3.5
+- [ ] No agent holds `write_file` without `apply_patch`, or `read_file` without
+      `list_dir` and `find_files`
 - [ ] An agent that only reads is not holding `write_file`, `apply_patch`,
       `move_file` or `delete_file` - subtract them from `workspace:*`
 - [ ] `sandbox:*` is granted only where a shell is actually needed
@@ -2062,3 +2102,17 @@ Update it when:
 
 Do not let it grow without pruning. When a section is only true of one agent, it
 belongs in that agent's prompt, not here.
+---
+
+## 13. Function calling rules
+
+Before every tool call, write **one line** saying what you are about to do and
+why. One line per call, in front of it - not a plan for the whole turn, and not
+a summary afterwards.
+
+- Say the intent and the reason, not the tool's name or its arguments:
+  _"Reading `agents.yaml` to see which agents hold `sandbox:*`."_
+- When several calls go out together, write one line covering the batch.
+- Keep it to a sentence. If it needs two, the call needs splitting, not the
+  sentence.
+- Do not narrate the result in the same line - the tool answers that.

package/templates/editor/.github/prompts/{review-project.prompt.md → project-review.prompt.md}

@@ -1,5 +1,4 @@
 ---
-mode: agent
 description: Review the project against the checklist before committing.
 ---
 

package/templates/editor/.github/prompts/{update-spec-from-feedback.prompt.md → spec-apply-feedback.prompt.md}

@@ -12,7 +12,7 @@ answered.
 You change two files and no others: `SPECIFICATION.md` and
 `SPECIFICATION-FEEDBACK.md`. You implement nothing - not a prompt, not a skill,
 not `agents.yaml`. Making the project match the specification is
-`/sync-with-spec`, which runs after this.
+`/spec-sync-project`, which runs after this.
 
 ## 1. Read both files before editing either
 
@@ -83,7 +83,7 @@ put it where the line above the block says it goes.
   edits rather than trusting the line numbers you read at the start.
 
 Nothing outside `SPECIFICATION.md` changes here. If an answer's text implies an
-agent, a tool grant, a script or a skill, that is the next `/sync-with-spec`
+agent, a tool grant, a script or a skill, that is the next `/spec-sync-project`
 pass's work, and saying so is all you do about it.
 
 ## 4. Mark the question answered
@@ -108,7 +108,7 @@ order:
   the specification to be true again, or `Nothing - the project already does
 this.`
 
-That last line is what the next `/sync-with-spec` works from, so write it as
+That last line is what the next `/spec-sync-project` works from, so write it as
 work, not as a summary.
 
 Then bring the top of the file back into step: the opening paragraph's count of
@@ -124,7 +124,7 @@ answer you think is wrong is still the answer; say why in the chat and leave the
 text alone.
 
 Do not run `zen check`, `scripts/_setup.sh` or anything under `.spec-sync/`. The
-baseline moves at the end of a `/sync-with-spec` pass and nowhere else -
+baseline moves at the end of a `/spec-sync-project` pass and nowhere else -
 committing it here would record a specification as applied that nothing has
 implemented yet.
 
@@ -138,5 +138,5 @@ In the chat:
 - what is still open, split into: more than one answer left, more than one box
   marked, every answer rejected, and could not be applied because the place it
   names is gone
-- then, in one line: send `/sync-with-spec` to make the project match the
+- then, in one line: send `/spec-sync-project` to make the project match the
   specification you have just changed.

package/templates/editor/.github/prompts/{sync-with-spec.prompt.md → spec-sync-project.prompt.md}

@@ -172,7 +172,7 @@ nothing to raise, say so in the chat and do not create the file.
 **It is a questionnaire, and answering it must take one gesture.** Every
 question carries two to four written-out answers, each with a `[ ]` box in its
 heading. The reader marks the box of the one they want - `[x]` - and deletes the
-others, then sends `/update-spec-from-feedback`, which folds what survived into
+others, then sends `/spec-apply-feedback`, which folds what survived into
 `SPECIFICATION.md`. Either gesture alone is enough, and the file says so in
 every question.
 
@@ -190,7 +190,7 @@ Two rules that come before everything else in this section:
 The file opens with one short paragraph: how many questions are open, and how to
 answer them - put an `x` in the box of the answer you want, delete the answers
 you do not want, or replace them all with a sentence of your own, then send
-`/update-spec-from-feedback`. Then a contents list, one line per question: its
+`/spec-apply-feedback`. Then a contents list, one line per question: its
 number as an anchor link, the question in under ten words, and what is built in
 the meantime. Then the questions, grouped under these headings, omitting any
 heading with no questions. The file is scanned before it is read, so keep the
@@ -212,7 +212,7 @@ emoji on every heading:
 ## ✅ Answered - folded into the specification
 ```
 
-`✅` is written by `/update-spec-from-feedback`, not by you. Leave what is there
+`✅` is written by `/spec-apply-feedback`, not by you. Leave what is there
 alone except to strike an entry this pass has actually implemented, and say in
 the chat which ones you closed.
 
@@ -329,7 +329,7 @@ retires with it.
 Read the feedback diff from §0 before writing: a question the human answered
 since the last pass is work to close, not a question to ask again. If a question
 has a box marked `[x]`, or one answer left under it, and no `✅` entry, the
-reader answered it and never ran `/update-spec-from-feedback` - implement that
+reader answered it and never ran `/spec-apply-feedback` - implement that
 answer, fold its text into `SPECIFICATION.md` yourself, and say so in the chat.
 
 ## 6. Run `scripts/_setup.sh` and watch it finish

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

@@ -7,12 +7,13 @@ zen inspect [run] [--session <id>] [--open] [--rebuild] [--serve [port]]
 Alias: `report`.
 
 Renders the trajectory of a run: every message, tool call, skill activation and
-hand-off, in order, with what each one cost. With no arguments it takes the
-newest run of the newest session.
+hand-off, in order, with what each one cost. With no arguments it asks which
+session and which run; where there is nothing to ask on — a script, `--json`,
+an agent — it takes the newest run of the newest session that has one.
 
 | Flag             | Meaning                                                 |
 | ---------------- | ------------------------------------------------------- |
-| `[run]`          | A run id. The newest otherwise                          |
+| `[run]`          | A run id, in whichever session holds it                 |
 | `--session <id>` | Which session the run belongs to                        |
 | `--open`         | Open the report in a browser                            |
 | `--rebuild`      | Rebuild `report.html` from the recorded state           |