@zenera/cli 1.1.0

package/dist/banner.js

@@ -0,0 +1,103 @@
+import { styleText } from 'node:util';
+import { dim, note } from "./term.js";
+// ---------------------------------------------------------------------------
+// The banner
+//
+// The one piece of output that exists to be looked at rather than read. It goes
+// to **stderr**, like every other piece of narration, and only when stderr is a
+// terminal — a pipeline asking for the answer gets the answer, and a CI log is
+// not decorated with block letters.
+//
+// The font is here rather than pulled in as a dependency because it is a
+// kilobyte of constant and the whole CLI is otherwise Node's own. Two things
+// about its shape are deliberate: the stroke is **two cells wide**, because a
+// one-cell stem in a dotted fill reads as noise rather than as a letter, and
+// the ink is the dotted block (U+2592) rather than a solid one, which makes a
+// thick stroke a screen-print instead of a slab.
+//
+// A terminal too narrow for the art gets the wordmark on one line. A banner
+// that wraps is worse than no banner.
+// ---------------------------------------------------------------------------
+const HEIGHT = 5;
+const WIDTH = 6;
+const FONT = {
+    A: [' ▒▒▒▒ ', '▒▒  ▒▒', '▒▒▒▒▒▒', '▒▒  ▒▒', '▒▒  ▒▒'],
+    B: ['▒▒▒▒▒ ', '▒▒  ▒▒', '▒▒▒▒▒ ', '▒▒  ▒▒', '▒▒▒▒▒ '],
+    C: [' ▒▒▒▒▒', '▒▒    ', '▒▒    ', '▒▒    ', ' ▒▒▒▒▒'],
+    D: ['▒▒▒▒▒ ', '▒▒  ▒▒', '▒▒  ▒▒', '▒▒  ▒▒', '▒▒▒▒▒ '],
+    E: ['▒▒▒▒▒▒', '▒▒    ', '▒▒▒▒▒ ', '▒▒    ', '▒▒▒▒▒▒'],
+    F: ['▒▒▒▒▒▒', '▒▒    ', '▒▒▒▒▒ ', '▒▒    ', '▒▒    '],
+    G: [' ▒▒▒▒▒', '▒▒    ', '▒▒ ▒▒▒', '▒▒  ▒▒', ' ▒▒▒▒▒'],
+    H: ['▒▒  ▒▒', '▒▒  ▒▒', '▒▒▒▒▒▒', '▒▒  ▒▒', '▒▒  ▒▒'],
+    I: ['▒▒▒▒▒▒', '  ▒▒  ', '  ▒▒  ', '  ▒▒  ', '▒▒▒▒▒▒'],
+    J: ['▒▒▒▒▒▒', '   ▒▒ ', '   ▒▒ ', '▒▒ ▒▒ ', ' ▒▒▒  '],
+    K: ['▒▒  ▒▒', '▒▒ ▒▒ ', '▒▒▒▒  ', '▒▒ ▒▒ ', '▒▒  ▒▒'],
+    L: ['▒▒    ', '▒▒    ', '▒▒    ', '▒▒    ', '▒▒▒▒▒▒'],
+    M: ['▒▒  ▒▒', '▒▒▒▒▒▒', '▒▒▒▒▒▒', '▒▒  ▒▒', '▒▒  ▒▒'],
+    N: ['▒▒  ▒▒', '▒▒▒ ▒▒', '▒▒▒▒▒▒', '▒▒ ▒▒▒', '▒▒  ▒▒'],
+    O: [' ▒▒▒▒ ', '▒▒  ▒▒', '▒▒  ▒▒', '▒▒  ▒▒', ' ▒▒▒▒ '],
+    P: ['▒▒▒▒▒ ', '▒▒  ▒▒', '▒▒▒▒▒ ', '▒▒    ', '▒▒    '],
+    Q: [' ▒▒▒▒ ', '▒▒  ▒▒', '▒▒  ▒▒', '▒▒ ▒▒ ', ' ▒▒ ▒▒'],
+    R: ['▒▒▒▒▒ ', '▒▒  ▒▒', '▒▒▒▒▒ ', '▒▒ ▒▒ ', '▒▒  ▒▒'],
+    S: [' ▒▒▒▒▒', '▒▒    ', ' ▒▒▒▒ ', '    ▒▒', '▒▒▒▒▒ '],
+    T: ['▒▒▒▒▒▒', '  ▒▒  ', '  ▒▒  ', '  ▒▒  ', '  ▒▒  '],
+    U: ['▒▒  ▒▒', '▒▒  ▒▒', '▒▒  ▒▒', '▒▒  ▒▒', ' ▒▒▒▒ '],
+    V: ['▒▒  ▒▒', '▒▒  ▒▒', '▒▒  ▒▒', ' ▒▒▒▒ ', '  ▒▒  '],
+    W: ['▒▒  ▒▒', '▒▒  ▒▒', '▒▒▒▒▒▒', '▒▒▒▒▒▒', '▒▒  ▒▒'],
+    X: ['▒▒  ▒▒', ' ▒▒▒▒ ', '  ▒▒  ', ' ▒▒▒▒ ', '▒▒  ▒▒'],
+    Y: ['▒▒  ▒▒', ' ▒▒▒▒ ', '  ▒▒  ', '  ▒▒  ', '  ▒▒  '],
+    Z: ['▒▒▒▒▒▒', '   ▒▒ ', '  ▒▒  ', ' ▒▒   ', '▒▒▒▒▒▒'],
+};
+const BLANK = ' '.repeat(WIDTH);
+/** One word as five rows of equal length — so two words line up when joined. */
+function big(word) {
+    const rows = new Array(HEIGHT).fill('');
+    for (const ch of word.toUpperCase()) {
+        const glyph = FONT[ch];
+        for (let r = 0; r < HEIGHT; r++) {
+            rows[r] += `${glyph?.[r] ?? BLANK} `;
+        }
+    }
+    return rows;
+}
+/** A wordmark rather than a sentence, so the letters are set apart. */
+const spaced = (s) => [...s.toUpperCase()].join(' ');
+/** The name, in the brightest thing the terminal has. */
+const bright = (s) => styleText(['bold', 'whiteBright'], s);
+/** The half that carries the colour. */
+const neon = (s) => styleText(['bold', 'magentaBright'], s);
+export const NEO_BANNER = {
+    head: 'Zenera',
+    accent: 'Neo',
+    subtitle: 'Agentic Runtime',
+};
+export function bannerLines(text, columns = process.stderr.columns || 80) {
+    const head = big(text.head);
+    // 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 width = 2 + head[0].length + Math.max(...accent.map((row) => row.length));
+    const foot = `  ${dim(spaced(text.subtitle))}`;
+    if (width > columns) {
+        return [` ${bright(text.head.toUpperCase())} ${neon(text.accent.toUpperCase())}`, foot];
+    }
+    const lines = [];
+    for (let r = 0; r < HEIGHT; r++) {
+        lines.push(` ${bright(head[r])} ${neon(accent[r])}`);
+    }
+    lines.push('');
+    lines.push(foot);
+    return lines;
+}
+/** Narration, and only for someone watching. */
+export function printBanner(text) {
+    if (!process.stderr.isTTY) {
+        return;
+    }
+    note('');
+    for (const line of bannerLines(text)) {
+        note(line);
+    }
+    note('');
+}
+//# sourceMappingURL=banner.js.map

package/dist/command.d.ts

@@ -0,0 +1,14 @@
+export interface Context {
+    readonly args: readonly string[];
+    readonly json: boolean;
+    /** honours `-C <dir>`, so nothing below reads `process.cwd()` directly */
+    readonly cwd: string;
+}
+export interface Command {
+    readonly summary: string;
+    readonly usage: string;
+    /** lines printed under the usage line by `zen help <command>` */
+    readonly details?: readonly string[];
+    run(ctx: Context): Promise<void>;
+}
+//# sourceMappingURL=command.d.ts.map

package/dist/command.js

@@ -0,0 +1,12 @@
+// ---------------------------------------------------------------------------
+// The command contract
+//
+// A command receives its own arguments, already stripped of the name, and the
+// two things the frame settled before dispatching: whether output should be
+// machine-readable, and which directory the whole invocation is relative to.
+//
+// It returns nothing. Success is the absence of a throw; every failure worth
+// distinguishing is a `CliError` carrying its exit code.
+// ---------------------------------------------------------------------------
+export {};
+//# sourceMappingURL=command.js.map

package/dist/commands/check.d.ts

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

package/dist/commands/check.js

@@ -0,0 +1,287 @@
+import { basename, resolve } from 'node:path';
+import { one, parse } from "../args.js";
+import { KeyStore } from "../keys.js";
+import { Registry } from "../projects.js";
+import { project as resolveProject } from "../resolve.js";
+import { bold, count, cyan, dim, green, invalidError, json, red, table, write, writeAll, yellow, } from "../term.js";
+import { validateProject, } from "../validate.js";
+const USAGE = 'zen check [dir] [--project <name|dir>] [--strict] [--quiet]';
+// ---------------------------------------------------------------------------
+// zen check
+//
+// Written to be read by a program as much as by a person, because the program
+// reading it is usually a model: an agent asked to fix a project needs to know
+// what is wrong, where, and what would fix it, without opening six files to
+// find out. So every section names its files by path, every finding carries a
+// stable code and a fix, and the whole thing goes to stdout — it is the answer,
+// not narration.
+//
+// Nothing here is contacted, started or paid for. That is the point: the check
+// has to work on the machine that is not set up yet, which is the machine that
+// most needs it.
+// ---------------------------------------------------------------------------
+export const check = {
+    summary: 'Validate agents.yaml and every file it names, and report in full.',
+    usage: USAGE,
+    details: [
+        'Checks the whole project without running anything: the configuration',
+        'parses and satisfies the schema, every prompt, skill and catalog it',
+        'names is on disk, hand-offs and forks name agents that exist, tool',
+        'selectors resolve, skills bind to a catalog that holds them, and the',
+        'models it declares have a credential on this machine.',
+        '',
+        'Unlike a run, it does not stop at the first problem — the report lists',
+        'everything it found, each with a code and the fix for it.',
+        '',
+        'Exit codes: 0 nothing wrong, 3 at least one error (or, with --strict,',
+        'at least one warning). --quiet prints the findings and nothing else.',
+    ],
+    run: async (ctx) => {
+        const { values, positionals } = parse(ctx.args, {
+            project: { type: 'string' },
+            strict: { type: 'boolean' },
+            quiet: { type: 'boolean' },
+        }, USAGE);
+        // A bare directory is accepted so an unregistered folder — a checkout,
+        // a scaffold in progress — can be checked at all. `--project` goes
+        // through the registry, like everywhere else.
+        const here = one(positionals, 'directory', USAGE);
+        const dir = here
+            ? resolve(ctx.cwd, here)
+            : await resolveProject({ cwd: ctx.cwd, project: values.project }).then((p) => p.dir);
+        // Being listed is the registry's answer, not the directory's, so it is
+        // read here and handed to the check rather than looked up inside it.
+        const entry = (await Registry.open()).findPath(dir);
+        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.
+        const keys = await KeyStore.open();
+        keys.materialize();
+        const report = await validateProject({
+            dir,
+            name,
+            registered: entry !== undefined,
+            keys,
+        });
+        if (ctx.json) {
+            json(report);
+        }
+        else if (values.quiet) {
+            writeAll(findingLines(report.findings));
+            write(verdict(report, Boolean(values.strict)));
+        }
+        else {
+            writeAll(render(report));
+        }
+        const failed = report.counts.errors > 0 || (Boolean(values.strict) && report.counts.warnings > 0);
+        if (failed) {
+            throw invalidError(`${name}: ${count(report.counts.errors, 'error')}` +
+                (values.strict ? `, ${count(report.counts.warnings, 'warning')}` : ''), 'the report above says what to change');
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+function render(report) {
+    const out = [];
+    const push = (...lines) => {
+        out.push(...lines);
+    };
+    push(`${bold('Project')} ${report.project.name ?? dim('(unregistered)')}`);
+    push(...table([
+        ['  root', report.project.root],
+        ['  config', report.project.config ?? red('none found')],
+        [
+            '  schema version',
+            report.project.version === null ? dim('—') : String(report.project.version),
+        ],
+        ['  entry agent', report.project.entry ?? red('undecided')],
+        ['  registered', report.project.registered ? green('yes') : yellow('not in zen list')],
+    ]));
+    if (report.project.shadowed.length) {
+        push(`  ${yellow('also present')} ${dim(report.project.shadowed.join(', '))}`);
+    }
+    // Files -----------------------------------------------------------------
+    push('', `${bold('Files')} ${dim(`${report.files.length} checked`)}`);
+    push(...table(report.files.map((f) => [
+        `  ${f.exists ? green('ok') : f.required ? red('MISSING') : yellow('absent')}`,
+        f.path + (f.kind === 'directory' ? '/' : ''),
+        dim(f.exists && f.bytes !== undefined ? size(f.bytes) : ''),
+        dim(f.from ? `${f.role} — named by ${f.from}` : f.role),
+    ])));
+    // Agents ----------------------------------------------------------------
+    push('', `${bold('Agents')} ${dim(`${report.agents.length} declared, entry is ${report.project.entry ?? '—'}`)}`);
+    for (const agent of report.agents) {
+        push(...agentBlock(agent));
+    }
+    // Skills ----------------------------------------------------------------
+    push('', `${bold('Skills')} ${dim(report.skills.dirs.length
+        ? `${count(report.skills.entries.length, 'skill')} in ${report.skills.dirs.join(', ')}`
+        : 'no catalog')}`);
+    if (report.skills.entries.length) {
+        push(...table(report.skills.entries.map((s) => [
+            `  ${s.name}`,
+            dim(s.path),
+            dim(s.tools?.length ? `unlocks ${s.tools.join(' ')}` : ''),
+            dim(s.usedBy.length ? `used by ${s.usedBy.join(', ')}` : 'unused'),
+        ])));
+    }
+    // Models ----------------------------------------------------------------
+    push('', bold('Models'));
+    if (report.models.length) {
+        push(...table(report.models.map((m) => [
+            `  ${m.name}`,
+            dim(m.provider ? `${m.provider} (${m.kind})` : red('unresolved')),
+            dim(m.env ?? ''),
+            credential(m.credential),
+            // Nothing consumes an embedding yet, so `usedBy` would
+            // always read "declared, unused" and say the wrong thing.
+            dim(m.role === 'embedding'
+                ? 'embedding'
+                : m.usedBy.length
+                    ? `used by ${m.usedBy.join(', ')}`
+                    : 'declared, unused'),
+        ])));
+    }
+    else {
+        push(`  ${dim('none declared')}`);
+    }
+    if (report.providers.length) {
+        push(`  ${dim(`providers: ${report.providers.join(', ')}`)}`);
+    }
+    // Sandbox ---------------------------------------------------------------
+    if (report.sandbox.used || report.sandbox.declared) {
+        push('', bold('Sandbox'));
+        push(...table([
+            ['  image', report.sandbox.image ?? dim('the default image')],
+            [
+                '  reached by',
+                report.sandbox.used
+                    ? 'at least one agent has the shell tools'
+                    : dim('nothing — the block is declared but no agent can run a command'),
+            ],
+            ['  requires', dim('podman on this machine: zen sandbox status')],
+        ]));
+    }
+    // Findings --------------------------------------------------------------
+    push('', `${bold('Findings')} ${dim(tallyLine(report))}`);
+    const lines = findingLines(report.findings);
+    push(...(lines.length ? lines : [`  ${green('nothing to report')}`]));
+    push('', verdict(report, false));
+    return out;
+}
+function agentBlock(agent) {
+    const head = `  ${bold(agent.name)}${agent.entry ? ` ${green('(entry)')}` : ''}`;
+    const rows = [];
+    if (agent.description) {
+        rows.push(['    description', agent.description]);
+    }
+    rows.push([
+        '    model',
+        agent.model
+            ? `${cyan(agent.model)} ${dim(`(${agent.modelSource === 'project' ? 'inherited from the project' : 'pinned here'})`)}`
+            : yellow('none — needs `model:` or --model'),
+    ]);
+    rows.push([
+        '    instructions',
+        agent.instructions.length ? agent.instructions.join(' + ') : yellow('none'),
+    ]);
+    rows.push([
+        '    tools',
+        agent.toolSelectors.length
+            ? `${agent.toolSelectors.join(' ')} ${dim(`→ ${agent.tools.length}: ${agent.tools.join(' ') || 'nothing'}`)}`
+            : dim('none'),
+    ]);
+    if (agent.handoffs.length) {
+        rows.push(['    handoffs', `→ ${agent.handoffs.join(', ')}`]);
+    }
+    if (agent.skills) {
+        const bits = [`provider "${agent.skills.provider}"`, `discovery ${agent.skills.discovery}`];
+        if (agent.skills.allow) {
+            bits.push(`allow: ${agent.skills.allow.join(', ')}`);
+        }
+        if (agent.skills.preload) {
+            bits.push(`preload: ${agent.skills.preload.join(', ')}`);
+        }
+        rows.push(['    skills', bits.join(', ')]);
+    }
+    if (agent.fork) {
+        const bits = [
+            agent.fork.agents ? `branches run ${agent.fork.agents.join(', ')}` : 'any agent',
+        ];
+        if (agent.fork.maxBranches) {
+            bits.push(`at most ${agent.fork.maxBranches}`);
+        }
+        rows.push(['    fork', bits.join(', ')]);
+    }
+    if (agent.ownSandbox) {
+        rows.push(['    sandbox', 'overrides the project container']);
+    }
+    return [head, ...table(rows)];
+}
+/**
+ * One finding, three lines at most: what and where, then why, then the fix.
+ * The code is printed because it is the part a script — or a model asked to
+ * fix this — can match on without parsing prose.
+ */
+function findingLines(findings) {
+    const out = [];
+    for (const f of order(findings)) {
+        out.push(`  ${label(f.severity)} ${bold(f.where)} ${dim(`[${f.code}]`)}`);
+        out.push(`          ${f.message}`);
+        if (f.fix) {
+            out.push(`          ${dim(`fix: ${f.fix}`)}`);
+        }
+    }
+    return out;
+}
+const RANK = { error: 0, warning: 1, note: 2 };
+function order(findings) {
+    return [...findings].sort((a, b) => RANK[a.severity] - RANK[b.severity]);
+}
+function label(severity) {
+    if (severity === 'error') {
+        return red('error  ');
+    }
+    return severity === 'warning' ? yellow('warning') : dim('note   ');
+}
+function credential(state) {
+    if (state === 'present') {
+        return green('present');
+    }
+    if (state === 'missing') {
+        return red('missing');
+    }
+    return state === 'rejected' ? red('rejected') : dim('unchecked');
+}
+function tallyLine(report) {
+    const { errors, warnings, notes } = report.counts;
+    return `${count(errors, 'error')}, ${count(warnings, 'warning')}, ${count(notes, 'note')}`;
+}
+/** The one line a caller that reads nothing else should read. */
+function verdict(report, strict) {
+    if (report.counts.errors > 0) {
+        return red(`${count(report.counts.errors, 'error')} — this project will not load. ` +
+            'Fix them and run `zen check` again.');
+    }
+    if (strict && report.counts.warnings > 0) {
+        return yellow(`${count(report.counts.warnings, 'warning')} — the project loads, but --strict ` +
+            'treats these as failures.');
+    }
+    if (report.counts.warnings > 0) {
+        return yellow(`The project loads. ${count(report.counts.warnings, 'warning')} worth reading above.`);
+    }
+    return green('The project loads, and nothing about it looks wrong.');
+}
+function size(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+    if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    }
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+//# sourceMappingURL=check.js.map

package/dist/commands/index.d.ts

@@ -0,0 +1,22 @@
+import type { BannerText } from '../banner.ts';
+import type { Command } from '../command.ts';
+/**
+ * Insertion order is the order help prints in, and it is deliberate: the four
+ * a new user needs first, then the two about credentials and models, then the
+ * two that are only ever run on purpose.
+ */
+export declare const COMMANDS: Record<string, Command>;
+/** Names that are not listed in help but still work. */
+export declare const ALIASES: Record<string, string>;
+export interface External {
+    /** the package to import `<pkg>/command` from */
+    readonly package: string;
+    readonly summary: string;
+    readonly usage: string;
+    /** what to tell someone who has not got it */
+    readonly install: string;
+    /** printed instead of the `zen` banner, so the sub-brand shows through */
+    readonly banner?: BannerText;
+}
+export declare const EXTERNAL: Record<string, External>;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/index.js

@@ -0,0 +1,56 @@
+import { check } from "./check.js";
+import { init } from "./init.js";
+import { inspect } from "./inspect.js";
+import { key } from "./key.js";
+import { list } from "./list.js";
+import { models } from "./models.js";
+import { open } from "./open.js";
+import { run } from "./run.js";
+import { sandbox } from "./sandbox.js";
+import { version } from "./version.js";
+/**
+ * Insertion order is the order help prints in, and it is deliberate: the four
+ * a new user needs first, then the two about credentials and models, then the
+ * two that are only ever run on purpose.
+ */
+export const COMMANDS = {
+    init,
+    list,
+    run,
+    open,
+    key,
+    models,
+    check,
+    inspect,
+    sandbox,
+    version,
+};
+/** Names that are not listed in help but still work. */
+export const ALIASES = {
+    ls: 'list',
+    new: 'init',
+    keys: 'key',
+    validate: 'check',
+    doctor: 'check',
+    report: 'inspect',
+    edit: 'open',
+    code: 'open',
+    mock: 'faker',
+};
+export const EXTERNAL = {
+    faker: {
+        package: '@zenera/faker',
+        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' },
+    },
+    rag: {
+        package: '@zenera/rag',
+        summary: 'Search an openapi/swagger document as a graph.',
+        usage: 'zen rag schema <index|search|show|stats> [spec...]',
+        install: 'npm i -g @zenera/rag',
+        banner: { head: 'Zenera', accent: 'Rag', subtitle: 'Api Retrieval' },
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/commands/init.d.ts

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

package/dist/commands/init.js

@@ -0,0 +1,157 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { one, parse } from "../args.js";
+import { ensureHome } from "../home.js";
+import { isProvider, keyId, KeyStore, PROVIDERS, SHAPES } from "../keys.js";
+import { probeAll } from "../liveness.js";
+import { isProjectDir, Registry } from "../projects.js";
+import { scaffold } from "../scaffold.js";
+import { bold, cyan, dim, green, invalidError, json, note, progress, usageError, write, yellow, } from "../term.js";
+const USAGE = 'zen init [dir] [--name <name>] [--model <ref>] [--force]';
+/**
+ * The model each provider gets scaffolded with, when it is the one chosen.
+ *
+ * Every ref names its provider. A bare id is not a vendor hint — the shorthand
+ * reads the first segment as a *provider name*, so an unprefixed
+ * `gemini-3.5-flash` resolves to the default provider and the project asks
+ * OpenAI for a Google model.
+ *
+ * Only OpenAI carries options, because it is the only vendor whose reasoning is
+ * silent unless asked for: Gemini's `includeThoughts` is on by default and
+ * Anthropic streams nothing to summarise. Without them a gpt-5 project sits
+ * there showing no progress while the model thinks, which reads as a hang.
+ */
+const DEFAULT_MODEL = {
+    openai: {
+        ref: 'openai:gpt-5.4-mini',
+        options: [
+            '# Reasoning and tools only meet on the responses API — chat',
+            '# completions, which is the default, rejects the two together.',
+            'api: responses',
+            '# gpt-5 models reason whether or not you ask. `reasoningSummary` is',
+            '# what makes that visible while it happens; drop it for silence, or',
+            '# lower the effort for shorter, cheaper turns.',
+            'reasoningEffort: medium',
+            'reasoningSummary: auto',
+        ].join('\n'),
+    },
+    anthropic: { ref: 'anthropic:claude-sonnet-4-5' },
+    google: { ref: 'google:gemini-3.5-flash' },
+    vertex: { ref: 'vertex:gemini-3.5-flash' },
+    openrouter: { ref: 'openrouter:inclusionai/ling-3.0-flash-fin:free' },
+};
+/**
+ * The provider this machine can actually reach.
+ *
+ * Holding a key is not the same as holding a working one, so stored
+ * credentials are asked rather than counted: guessing OpenAI when only a
+ * revoked OpenAI key exists produces a project that scaffolds cleanly and
+ * fails on its first run, which is the worst possible moment to find out. A
+ * key that came from the environment is taken at its word — the user set it
+ * deliberately, and there is no entry to record a verdict against.
+ *
+ * `dead` is a verdict; `unknown` only means the provider could not be asked, so
+ * it is still worth scaffolding around rather than refusing to choose because
+ * the wifi is down.
+ */
+async function reachableProvider(store) {
+    const fromEnv = PROVIDERS.find((p) => process.env[SHAPES[p].env]);
+    if (fromEnv) {
+        return fromEnv;
+    }
+    const active = PROVIDERS.map((p) => store.active(p)).filter((e) => e !== undefined);
+    if (active.length === 0) {
+        return undefined;
+    }
+    const bar = progress();
+    const checks = await probeAll(store, active, (entry, index, total) => bar.update(dim(`checking ${keyId(entry)} … ${index + 1}/${total}`)));
+    bar.done();
+    for (const [entry, check] of checks) {
+        store.record(entry, check);
+    }
+    store.save();
+    const chosen = checks.find(([, c]) => c.state === 'live') ?? checks.find(([, c]) => c.state === 'unknown');
+    // `active` was built from PROVIDERS, so this only ever holds a model
+    // provider; the guard says so to the type system rather than a cast
+    // asserting it, which would survive `SERVICES` growing into this list.
+    const provider = chosen?.[0].provider;
+    return provider !== undefined && isProvider(provider) ? provider : undefined;
+}
+/**
+ * Whether this machine can reach the web tools.
+ *
+ * Presence, not liveness: unlike the model, nothing about the project depends
+ * on the key working — an agent with a dead Exa key is an agent one tool call
+ * poorer, not one that cannot run — so it is not worth a round trip during
+ * `init`.
+ */
+function hasExa(store) {
+    return Boolean(process.env[SHAPES.exa.env]) || store.active('exa') !== undefined;
+}
+export const init = {
+    summary: 'Create a project here, or in <dir>, and register it.',
+    usage: USAGE,
+    details: [
+        'Writes INSTRUCTIONS.md, agents.yaml and agents/, 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.',
+        '',
+        'The default agent gets the file tools and a sandboxed shell, plus',
+        '`exa:*` when the keyring holds an Exa key. Without --model, the',
+        'keyring is checked and the model is picked from a credential the',
+        'provider accepts.',
+    ],
+    run: async (ctx) => {
+        const { values, positionals } = parse(ctx.args, {
+            name: { type: 'string' },
+            model: { type: 'string' },
+            force: { type: 'boolean' },
+        }, USAGE);
+        const dir = resolve(ctx.cwd, one(positionals, 'directory', USAGE) ?? '.');
+        const name = values.name ?? basename(dir);
+        if (isProjectDir(dir)) {
+            throw invalidError(`${dir} is already a project`);
+        }
+        if (existsSync(dir) && readdirSync(dir).length > 0 && !values.force) {
+            throw usageError(`${dir} is not empty`, 'pass --force to write into it anyway');
+        }
+        ensureHome();
+        const store = await KeyStore.open();
+        const provider = values.model ? undefined : await reachableProvider(store);
+        // An explicit --model is taken as written, options and all: guessing at
+        // knobs for a model nobody here has heard of is how a scaffold breaks.
+        const choice = values.model
+            ? { ref: values.model }
+            : DEFAULT_MODEL[provider ?? 'openai'];
+        const model = choice.ref;
+        const web = hasExa(store);
+        const files = scaffold({ dir, model, modelOptions: choice.options, web });
+        const registry = await Registry.open();
+        registry.add(name, dir);
+        registry.save();
+        if (ctx.json) {
+            json({ name, path: dir, model, files, credential: provider ?? null, web });
+            return;
+        }
+        note(`${green('created')} ${bold(name)} ${dim(dir)}`);
+        for (const file of files) {
+            note(`  ${dim(file)}`);
+        }
+        note();
+        if (web) {
+            note(`${green('exa key found')} ${dim('— the default agent gets web search')}`);
+            note();
+        }
+        // Said once, here, rather than left for the first run to discover: the
+        // project names a model, and nothing on this machine can pay for it.
+        if (!values.model && !provider) {
+            note(`${yellow('no working key')} ${dim(`— ${model} will not run yet`)}`);
+            note(`  ${cyan('zen key add openai')} ${dim('(or anthropic, google, vertex)')}`);
+            note();
+        }
+        note(`Next: ${cyan(`cd ${dir}`)} then ${cyan('zen run')}`);
+        write(dir);
+    },
+};
+//# sourceMappingURL=init.js.map

package/dist/commands/inspect.d.ts

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