@zenera/cli 1.1.27 → 1.1.28

package/README.md

@@ -1,8 +1,15 @@
+<div align="center"> 
+  <img
+    src="https://raw.githubusercontent.com/andreyryabov/ZeneraNeo/main/docs/imgs/zenera-logo-with-media-queries.svg"
+    alt="Zenera Logo"
+    width="20"
+  />
+  <div>Powered By Zenera</div>
+</div>
+<br>
+
 <div align="center">
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/andreyryabov/ZeneraNeo/main/docs/imgs/banner-cli-dark.svg">
-  <img src="https://raw.githubusercontent.com/andreyryabov/ZeneraNeo/main/docs/imgs/banner-cli-light.svg" alt="ZENERA CLI" width="720">
-</picture>
+  <img src="https://raw.githubusercontent.com/andreyryabov/ZeneraNeo/main/docs/imgs/banner-cli-with-media-queries.svg" alt="ZENERA CLI"  width="720">
 
 [![npm](https://img.shields.io/npm/v/@zenera/cli.svg)](https://www.npmjs.com/package/@zenera/cli)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/andreyryabov/ZeneraNeo/blob/main/LICENSE)
@@ -121,16 +128,15 @@ zen init my-project          # scaffolds a project and registers it
 zen open my-project          # open the specification and project in your editor
 ```
 
-In the editor, describe the job in `SPECIFICATION.md`, then send this in the
-agent chat:
+In the editor, describe the job in `SPECIFICATION.md`. Then, back in the
+terminal, let the meta agent build the system from it:
 
-```
-/spec-sync-project
+```sh
+zen meta run my-project /spec-sync-project
 ```
 
 It creates the specialists, responsibilities, tool access and handoffs the job
-needs. Back in the terminal, validate the generated system and run it against a
-real workspace:
+needs. Validate the generated system and run it against a real workspace:
 
 ```sh
 zen check my-project
@@ -170,10 +176,11 @@ dashboard rewritten every second: what each item is doing right now, what the
 finished ones cost - per model, since agents may each use a different one - and
 what is still queued.
 
-To change what the system does, update `SPECIFICATION.md` and send
-`/spec-sync-project` again. The next section explains that workflow in detail.
+To change what the system does, update `SPECIFICATION.md` and run
+`zen meta run /spec-sync-project` again. The next section explains that workflow
+in detail.
 
-## You write the specification; a coding agent writes the system
+## You write the specification; the meta agent writes the system
 
 `zen init` writes `SPECIFICATION.md` first, and everything else in the folder
 implements it. Where the two disagree the specification wins, so a change to
@@ -201,9 +208,9 @@ nobody to hand work to, because there is no second job to hand on.
 
 ### How you actually edit it
 
-`SPECIFICATION.md` is ordinary Markdown, so any editor will do - but the loop is
-meant to be driven from a coding agent's chat, and `zen init` installs the
-prompts that make each step a single command:
+`SPECIFICATION.md` is ordinary Markdown, so any editor will do. `zen init`
+installs the prompts that make each step of the loop a single `zen meta run`
+command:
 
 ```sh
 zen open my-project      # or, standing in the folder: zen open
@@ -213,30 +220,29 @@ That launches the editor you already use: the one this terminal belongs to, or
 `$ZENERA_EDITOR`, or the first of VS Code, Cursor, Windsurf, Zed, Sublime Text
 or IntelliJ it can find. `--editor <cmd>` names one outright.
 
-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 `/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.
+2. **Run `zen meta run /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 `/spec-apply-feedback`.** It folds the answers you chose into
-   `SPECIFICATION.md` - never into a prompt - and then `/spec-sync-project` again.
+4. **Run `zen meta run /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`.
+Then: `zen check`, then `zen run`.
 
 <details>
-<summary>The chat commands <code>zen init</code> installs</summary>
+<summary>The prompts <code>zen init</code> installs</summary>
 
-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.
+They are prompt files under `.github/prompts/`, and `zen meta run /<name>` runs
+one (`zen meta prompts` lists them). Both `zen init` and `zen open` write them
+fresh, so they never go stale - and edits to them do not survive.
 
-| In chat                | Does                                                             |
+| Prompt                 | 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. |
@@ -245,10 +251,8 @@ so they never go stale - and edits to them do not survive.
 | `/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/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
+Alongside them, `.github/copilot-instructions.md` is the standing brief that
+explains this runtime to whatever coding agent opens the folder, and
 `.github/skills/zen-cli/` is the CLI's own reference for it.
 
 </details>
@@ -256,9 +260,9 @@ that explains this runtime to whatever agent is reading, and
 ### The self-improving loop
 
 ```
-edit SPECIFICATION.md → /spec-sync-project → zen check → zen run
-        ↑                                                  ↓
-        └───── refine the spec <-──── zen inspect <-───────┘
+edit SPECIFICATION.md → zen meta run /spec-sync-project → zen check → zen run
+        ↑                                                              ↓
+        └─────────── refine the spec <-──── zen inspect <-─────────────┘
 ```
 
 `zen inspect` makes the record visible: the run trace, timing and token
@@ -266,7 +270,7 @@ statistics, agent architecture, and memory used during the run.
 
 ![Run inspection: trace, agent architecture, and memory](https://raw.githubusercontent.com/andreyryabov/ZeneraNeo/main/docs/imgs/0910_480.gif)
 
-The agent in your editor can close the same loop without the page. `zen inspect
+The meta agent can close the same loop without the page. `zen inspect
 graph` writes the whole run as one Mermaid flowchart - a line per node, short
 sequential ids, the tools counted in a header - which is small enough to read
 whole. Having spotted the loop or the branch that failed, it opens the two or
@@ -287,7 +291,7 @@ prompt that reads correctly and behaves wrongly explains itself.
 `ask` has two modes, decided by whether the question is given:
 
 - **One-shot** - a question on the line, in `--question-file`, or `--json`.
-  For a script or the agent in your editor: no banner, no prompt, no picker.
+  For a script or the meta agent: no banner, no prompt, no picker.
   stdout is the answer and nothing else, and the command exits.
 - **Interactive** - no question. For you, at a terminal: `zen inspect ask`
   walks through the session, run and recorded LLM call (whichever are not
@@ -298,8 +302,8 @@ prompt that reads correctly and behaves wrongly explains itself.
 Every step is a command, and everything each one reads or writes is a plain
 file: the specification, the findings `zen check` prints with a code, a location
 and a fix, the record `zen inspect` renders of what the run actually did. So the
-loop does not need you standing in it. Hand the whole cycle to the agent in your
-editor and it runs on the system it just built - test it, read the failure,
+loop does not need you standing in it. Hand the whole cycle to the meta agent
+and it runs on the system it just built - test it, read the failure,
 change the sentence in the specification that caused it, rebuild, run again.
 "Fix my project" is one instruction. (The first time round, `scripts/_setup.sh`
 prepares the container the tools run in.)
@@ -344,7 +348,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 `/spec-sync-project` in the editor's chat. It writes `agents.yaml` - who
+Run `zen meta run /spec-sync-project`. It writes `agents.yaml` - who
 exists, and what each may reach for:
 
 ```yaml
@@ -645,8 +649,8 @@ an accident.
 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.
+keyring, and not on anybody's subscription. It is the spec-to-system loop as a
+command you can put in a script.
 
 ```sh
 zen meta run "what does this project do?"
@@ -663,9 +667,9 @@ 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
+It uses every tool without asking. The prompts it runs rely on reading files,
+writing them and running commands, 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
@@ -683,11 +687,10 @@ to `.tmp/logs/meta.<when>.log`, whose path is printed before the run starts, so
 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.
+`zen meta run /<name>` runs a prompt file. The prompts under
+`.github/prompts/` - `/spec-sync-project`, `/project-review` - are plain
+Markdown with frontmatter. zen reads one, drops the frontmatter and sends the
+body - so the same prompt runs from a terminal, a script and 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.

package/dist/commands/meta.js

@@ -10,12 +10,14 @@ import { copilotEventLog } from "../eventlog.js";
 import { ensureHome } from "../home.js";
 import { assertOwner, KeyStore, PROVIDERS } from "../keys.js";
 import { probeChat, probeModel } from "../liveness.js";
-import { answerBox, chooseModel, DATASET_DETAILS, DATASET_SUMMARY, DATASET_USAGE, datasetProjectFlag, DEFAULT_RESUMES, defaultRef, editorFiles, FINETUNE_DETAILS, FINETUNE_SUMMARY, FINETUNE_USAGE, finetuneProjectFlag, lastSession, launch, listPrompts, loadPrompt, locate, masked, misspelledProvider, MODEL_ENV, openLog, ORDER, PROMPT_DIR, providersWarning, readMeta, RECOMMENDED, recordSession, RESUME_PROMPT, resumeDelayMs, runDataset, runFinetune, sameModel, sessionModel, sessionTotals, SOURCE_LABELS, startVertexRelay, tailSpans, Tally, terminalSink, transient, wire, writeMeta, } from "../meta/index.js";
+import { answerBox, chooseModel, DATASET_DETAILS, DATASET_SUMMARY, DATASET_USAGE, datasetProjectFlag, DEFAULT_RESUMES, defaultRef, editorFiles, FINETUNE_DETAILS, FINETUNE_SUMMARY, FINETUNE_USAGE, finetuneProjectFlag, lastSession, launch, listPrompts, loadPrompt, locate, masked, misspelledProvider, MODEL_ENV, openLog, ORDER, PROMPT_DIR, providersWarning, readMeta, recordSession, RESUME_PROMPT, resumeDelayMs, runDataset, runFinetune, sameModel, sessionModel, sessionTotals, SOURCE_LABELS, startVertexRelay, tailSpans, Tally, terminalSink, transient, wire, writeMeta, } from "../meta/index.js";
 import { splitRef } from "../modelref.js";
 import { duration } from "../narrate.js";
 import * as Projects from "../projects.js";
 import { project as resolveProject } from "../resolve.js";
-import { bold, choose, CliError, credentialError, cyan, dim, EXIT, green, isInteractive, json, note, progress, readStdin, table, usageError, warn, write, writeAll, } from "../term.js";
+import { TEMPLATES } from "../scaffold.js";
+import { bold, choose, CliError, credentialError, cyan, dim, EXIT, green, isInteractive, json, note, pad, progress, readStdin, table, usageError, warn, write, writeAll, } from "../term.js";
+import { wrap } from "../tui/wrap.js";
 import { appendUsage, LEDGER_ENV, ledgerPath, META_PROMPT_ENV, META_SESSION_ENV, } from "../usage.js";
 const USAGE = 'zen meta run [project] [prompt] [options]';
 const VERBS = new Set(['model', 'run', 'prompts', 'resume', 'dataset', 'finetune']);
@@ -55,15 +57,46 @@ function page(p) {
         write(line ? `  ${line}` : '');
     }
 }
+const RUN_FORMS = [
+    '  zen meta run [project] "<question>"      ask it something',
+    '  zen meta run [project] /<name> [words]   run a stored prompt',
+    '  zen meta run [project]                   pick one of its stored prompts',
+];
+const RUN_ARGUMENTS = [
+    'Arguments:',
+    '  [project]   Name of a project. Default: the one you are in.',
+    '  [prompt]    Your question, in quotes. Also --prompt, or piped in.',
+    '  /<name>     A prompt file in .github/prompts/<name>.prompt.md.',
+    '  [words]     Appended to that prompt as a final line.',
+];
+const RUN_OPTIONS = [
+    'Options:',
+    '  --project <name|dir>   Which project to work in. The agent is rooted there.',
+    '  --model <ref>          Model for this run, e.g. vertex/gemini-3.8-flash.',
+    '  --provider <name>      Force the key to use. Default: the model ref says.',
+    '  --prompt-file <file>   Append this file to the prompt, after any words.',
+    '  --agent <name>         A .github/agents/<name>.agent.md.',
+    '  --effort <level>       none, minimal, low, medium, high, xhigh or max.',
+    '  --allow-tool <list>    Only these: read, shell(git:*), write(README.md).',
+    '  --ask                  Have it ask before each tool. Default: it does not.',
+    '  --add-dir <dir>        Another directory it may touch. Repeatable.',
+    '  --resume <id>          Continue a copilot session. --continue takes the last.',
+    '  --session-id <uuid>    Start a new session under this id. Default: a random one.',
+    `  --retries <n>          Resume after a rate limit or outage. Default ${DEFAULT_RESUMES}, 0 = off.`,
+    '  --share <file>         Write the transcript to a markdown file.',
+    '  --events <file>        Append what the agent does to this file as it does it:',
+    '                         one JSON line per model call, tool call and message.',
+    '  --dry-run              Print what would run, secrets masked, and stop.',
+    '  --no-refresh           Leave the editor files as they are (parallel runs).',
+    '  --json                 Print one object: answer, answerFile, sessionId, exitCode, tokens.',
+];
 export const meta = {
     summary: 'Run the meta agent over this project, on your own keys.',
     usage: USAGE,
     banner: { head: 'Zenera', accent: 'Meta', subtitle: 'Meta Agent', hue: 'cyan' },
     details: [
         'Forms:',
-        '  zen meta run [project] "<question>"      ask it something',
-        '  zen meta run [project] /<name> [words]   run a stored prompt',
-        '  zen meta run [project]                   pick one of its stored prompts',
+        ...RUN_FORMS,
         '  zen meta prompts [project]               list the stored prompts',
         '  zen meta resume [project] [session]      carry on a run that stopped',
         '  zen meta model [ref]                     show or set the model it uses',
@@ -71,33 +104,12 @@ export const meta = {
         '  zen meta finetune <verb>                 tune the project on those cases',
         '',
         'The project may come before the verb instead: `zen meta acme run`.',
-        '`zen meta dataset --help` and `zen meta finetune --help` have their own pages.',
+        '`zen meta dataset --help`, `zen meta finetune --help` and `zen meta run --help`',
+        'have their own pages; the last lists the stored prompts.',
         '',
-        'Arguments:',
-        '  [project]   Name of a project. Default: the one you are in.',
-        '  [prompt]    Your question, in quotes. Also --prompt, or piped in.',
-        '  /<name>     A prompt file in .github/prompts/<name>.prompt.md.',
-        '  [words]     Appended to that prompt as a final line.',
+        ...RUN_ARGUMENTS,
         '',
-        'Options:',
-        '  --project <name|dir>   Which project to work in. The agent is rooted there.',
-        '  --model <ref>          Model for this run, e.g. vertex/gemini-3.8-flash.',
-        '  --provider <name>      Force the key to use. Default: the model ref says.',
-        '  --prompt-file <file>   Append this file to the prompt, after any words.',
-        '  --agent <name>         A .github/agents/<name>.agent.md.',
-        '  --effort <level>       none, minimal, low, medium, high, xhigh or max.',
-        '  --allow-tool <list>    Only these: read, shell(git:*), write(README.md).',
-        '  --ask                  Have it ask before each tool. Default: it does not.',
-        '  --add-dir <dir>        Another directory it may touch. Repeatable.',
-        '  --resume <id>          Continue a copilot session. --continue takes the last.',
-        '  --session-id <uuid>    Start a new session under this id. Default: a random one.',
-        `  --retries <n>          Resume after a rate limit or outage. Default ${DEFAULT_RESUMES}, 0 = off.`,
-        '  --share <file>         Write the transcript to a markdown file.',
-        '  --events <file>        Append what the agent does to this file as it does it:',
-        '                         one JSON line per model call, tool call and message.',
-        '  --dry-run              Print what would run, secrets masked, and stop.',
-        '  --no-refresh           Leave the editor files as they are (parallel runs).',
-        '  --json                 Print one object: answer, answerFile, sessionId, exitCode, tokens.',
+        ...RUN_OPTIONS,
         '',
         'It always uses your own keys — `zen key add` — and never a coding-agent',
         'subscription. The answer goes to stdout and the progress to stderr, so',
@@ -131,6 +143,9 @@ export const meta = {
         'Setting one asks the provider a one-word question first, so a model that',
         'will not answer is never stored. --force skips that.',
         '',
+        '`zen meta model --pick` browses every model your keys reach: / filters,',
+        't asks one a question, p takes it.',
+        '',
         'Examples:',
         '  zen meta run "what does this project do?"',
         '  zen meta run acme "review the last commit"',
@@ -144,9 +159,16 @@ export const meta = {
         '  zen meta model --pick',
         '  zen meta run --dry-run "hello"',
     ],
-    help: (ctx) => {
+    help: async (ctx) => {
         const sub = subcommand(ctx.args);
-        page(sub ? SUBCOMMANDS[sub.name].page : { ...meta, details: meta.details ?? [] });
+        if (sub) {
+            return page(SUBCOMMANDS[sub.name].page);
+        }
+        const words = ctx.args.filter((a) => !a.startsWith('-'));
+        if (words[0] === 'run' || words[1] === 'run') {
+            return await runHelp(ctx, words);
+        }
+        page({ ...meta, details: meta.details ?? [] });
     },
     run: async (ctx) => {
         // These own their flags, so they are routed before the meta agent's are parsed.
@@ -216,6 +238,45 @@ export const meta = {
         throw usageError(first === undefined ? 'nothing to run' : 'a prompt goes through `run`', `try: zen meta run ${positionals.map(requote).join(' ') || '"what does this project do?"'}`);
     },
 };
+// ---------------------------------------------------------------------------
+// zen meta run --help
+//
+// The prompts are the reason to type `run`, so its page names them. The
+// shipped ones come from the templates, which `run` refreshes into the project
+// first; a project's own additions are read from the project.
+// ---------------------------------------------------------------------------
+async function runHelp(ctx, words) {
+    const at = ctx.args.indexOf('--project');
+    const flag = ctx.args.find((a) => a.startsWith('--project='))?.slice('--project='.length) ??
+        (at >= 0 ? ctx.args[at + 1] : undefined);
+    const named = flag ?? (words[1] === 'run' ? words[0] : words[1]);
+    const project = (named && !named.startsWith('/') ? await Projects.find(named) : undefined) ??
+        (await Projects.current(ctx.cwd));
+    const shipped = join(TEMPLATES, 'editor');
+    const ours = new Set(await listPrompts(shipped));
+    const theirs = project ? await listPrompts(project.dir) : [];
+    const names = [...new Set([...ours, ...theirs])].sort();
+    const found = await Promise.all(names.map((n) => loadPrompt(ours.has(n) ? shipped : project.dir, n)));
+    const lines = [
+        'Forms:',
+        ...RUN_FORMS,
+        '',
+        project ? `Prompts in ${project.name}:` : 'Prompts:',
+    ];
+    const nameWidth = Math.max(...found.map((p) => p.name.length + 1));
+    const room = Math.max(30, Math.min(process.stdout.columns ?? 80, 100) - nameWidth - 6);
+    for (const p of found) {
+        const [first = '', ...more] = wrap(p.description ?? '', room);
+        lines.push(`  ${pad(`/${p.name}`, nameWidth)}  ${first}`.trimEnd());
+        lines.push(...more.map((l) => `  ${' '.repeat(nameWidth)}  ${l}`));
+    }
+    lines.push('', ...RUN_ARGUMENTS, '', ...RUN_OPTIONS, '', 'Examples:', '  zen meta run "what does this project do?"', '  zen meta run acme /project-review', '  zen meta run acme /spec-sync-project agents/triage.md', '  zen meta run acme /analyze --json');
+    page({
+        usage: 'zen meta run [project] [/<name> [words] | "<question>"] [options]',
+        summary: 'Ask the meta agent a question, or run one of the stored prompts.',
+        details: lines,
+    });
+}
 /** Words the shell would have split are shown back the way they were typed. */
 const requote = (s) => (/\s/.test(s) ? JSON.stringify(s) : s);
 // ---------------------------------------------------------------------------
@@ -898,8 +959,15 @@ async function pickModel(ctx) {
     if (known.length === 0) {
         throw credentialError('no keys to choose from', 'add one: zen key add openai');
     }
-    const suggestions = [...new Set(known)].flatMap((p) => (RECOMMENDED[p] ?? []).map((id) => `${p}/${id}`));
-    note(dim(bold('Models zen knows how to wire, for providers you hold a key for')));
-    return await choose('Which model?', suggestions.map((ref) => ({ label: ref, value: ref })));
+    const held = [...new Set(known)];
+    const { browseModels } = await import("./models.js");
+    const chosen = await browseModels({
+        initial: held.length === 1 ? held[0] : undefined,
+        role: 'chat',
+    });
+    if (!chosen) {
+        throw usageError('nothing picked', 'name the model instead: zen meta model <provider>/<id>');
+    }
+    return `${chosen.provider}/${chosen.id}`;
 }
 //# sourceMappingURL=meta.js.map

package/dist/commands/models.d.ts

@@ -1,3 +1,15 @@
+import { type CatalogEntry, type Role } from '../catalog.ts';
 import type { Command } from '../command.ts';
+import { type Provider } from '../keys.ts';
+export interface BrowseRequest {
+    /** opens straight into this provider's listing */
+    initial?: Provider;
+    /** the role filter each listing opens on; tab still cycles */
+    role?: Role;
+    refresh?: boolean;
+    theme?: string;
+}
+/** The browser, for any command that wants a person to pick a model. */
+export declare function browseModels(request?: BrowseRequest): Promise<CatalogEntry | undefined>;
 export declare const models: Command;
 //# sourceMappingURL=models.d.ts.map

package/dist/commands/models.js

@@ -573,12 +573,29 @@ const browse = async (ctx, args) => {
     if (ctx.json || !isInteractive()) {
         throw usageError('browsing needs a person at a terminal', 'from a script: zen models ls --json, or zen models pick --chat');
     }
+    const chosen = await browseModels({
+        initial,
+        theme: values.theme,
+        refresh: values.refresh,
+    });
+    if (!chosen) {
+        // Leaving is a fine way to end a browse, but not an answer to a
+        // substitution that was waiting for one.
+        if (!process.stdout.isTTY) {
+            throw new CliError('nothing picked', EXIT.failed);
+        }
+        return;
+    }
+    write(chosen.ref);
+};
+/** The browser, for any command that wants a person to pick a model. */
+export async function browseModels(request = {}) {
     const where = await credentials();
     // Offline, like `providers`: the overview should not cost five listings.
     // A provider is fetched when it is opened.
     const cats = await loadCatalogs(PROVIDERS, { offline: true });
     const { browse: draw } = await import("../tui/models.js");
-    const chosen = await draw({
+    return await draw({
         providers: cats.map((c) => ({
             provider: c.provider,
             credential: source(where, c.provider),
@@ -586,9 +603,10 @@ const browse = async (ctx, args) => {
             origin: c.origin,
             fetchedAt: c.fetchedAt,
         })),
-        initial,
-        theme: values.theme,
-        load: (provider, refresh) => loadCatalog(provider, { refresh: refresh || values.refresh }),
+        initial: request.initial,
+        role: request.role,
+        theme: request.theme,
+        load: (provider, refresh) => loadCatalog(provider, { refresh: refresh || request.refresh }),
         balance: async (provider) => provider === 'openrouter' && source(where, provider) ? routerBalance() : undefined,
         test: async (entry) => {
             const role = entry.roles.includes('chat')
@@ -606,16 +624,7 @@ const browse = async (ctx, args) => {
             };
         },
     });
-    if (!chosen) {
-        // Leaving is a fine way to end a browse, but not an answer to a
-        // substitution that was waiting for one.
-        if (!process.stdout.isTTY) {
-            throw new CliError('nothing picked', EXIT.failed);
-        }
-        return;
-    }
-    write(chosen.ref);
-};
+}
 // ---------------------------------------------------------------------------
 // Dispatch
 // ---------------------------------------------------------------------------

package/dist/meta/model.d.ts

@@ -23,7 +23,7 @@ export interface ModelSources {
 export declare const ORDER: readonly ModelSource[];
 export declare function chooseModel(sources: ModelSources): ModelChoice | undefined;
 export declare const SOURCE_LABELS: Record<ModelSource, string>;
-/** First of each row is the default; the rest are what `--pick` offers beside it. */
+/** First of each row is the default; the rest are the next best. */
 export declare const RECOMMENDED: Partial<Record<Provider, readonly string[]>>;
 /** The recommended ref for the first provider with a key, or for `only`. */
 export declare function defaultRef(store: KeyStore, only?: Provider): string | undefined;

package/dist/meta/model.js

@@ -47,7 +47,7 @@ export const SOURCE_LABELS = {
 // error. Deep tier deliberately: this agent is pointed at the project itself,
 // and a cheap model reading a specification is a false economy.
 // ---------------------------------------------------------------------------
-/** First of each row is the default; the rest are what `--pick` offers beside it. */
+/** First of each row is the default; the rest are the next best. */
 export const RECOMMENDED = {
     openai: ['gpt-5.6-sol', 'gpt-5.6-terra'],
     anthropic: ['claude-opus-5', 'claude-sonnet-5'],

package/dist/tui/models.d.ts

@@ -1,4 +1,4 @@
-import { type Balance, type Catalog, type CatalogEntry } from '../catalog.ts';
+import { type Balance, type Catalog, type CatalogEntry, type Role } from '../catalog.ts';
 import type { Provider } from '../keys.ts';
 export interface ProviderRow {
     provider: Provider;
@@ -21,6 +21,8 @@ export interface BrowseOptions {
     providers: readonly ProviderRow[];
     /** opens straight into this provider's listing */
     initial?: Provider;
+    /** the role filter a listing opens on, when it has any such model */
+    role?: Role;
     theme?: string;
     load(provider: Provider, refresh: boolean): Promise<Catalog>;
     /** what the account has left to spend, for providers that say */

package/dist/tui/models.js

@@ -103,7 +103,7 @@ function Browser({ options, theme, onPick }) {
     const [failure, setFailure] = useState();
     const [query, setQuery] = useState('');
     const [typing, setTyping] = useState(false);
-    const [role, setRole] = useState(0);
+    const [role, setRole] = useState(options.role);
     const [selected, setSelected] = useState(0);
     const [verdicts, setVerdicts] = useState(new Map());
     const [balances, setBalances] = useState(new Map());
@@ -147,7 +147,7 @@ function Browser({ options, theme, onPick }) {
         undefined,
         ...ROLES.filter((r) => catalog?.entries.some((e) => e.roles.includes(r))),
     ], [catalog]);
-    const only = present[role % present.length];
+    const only = present.includes(role) ? role : undefined;
     const rows = useMemo(() => (catalog?.entries ?? [])
         .filter((e) => matches(e, query, { roles: only ? [only] : [] }))
         .sort(byGroup), [catalog, query, only]);
@@ -159,7 +159,7 @@ function Browser({ options, theme, onPick }) {
         setScreen('models');
         setQuery('');
         setTyping(false);
-        setRole(0);
+        setRole(options.role);
         setSelected(0);
         top.current = 0;
         if (!catalogs.has(p)) {
@@ -287,7 +287,7 @@ function Browser({ options, theme, onPick }) {
             setSelected(0);
         }
         else if (key.tab) {
-            setRole((r) => (r + 1) % present.length);
+            setRole(present[(present.indexOf(only) + 1) % present.length]);
             setSelected(0);
         }
         else if ((key.return || key.rightArrow || input === 'l') && current) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.27",
+    "version": "1.1.28",
     "description": "Command-line front end for @zenera/neo: agentic projects you can run, share and commit.",
     "keywords": [
         "agents",
@@ -52,8 +52,8 @@
         "@google/genai": "^2.18.0",
         "@inkjs/ui": "^2.0.0",
         "@openrouter/sdk": "^1.2.80",
-        "@zenera/neo": "^1.1.27",
-        "@zenera/view": "^1.1.27",
+        "@zenera/neo": "^1.1.28",
+        "@zenera/view": "^1.1.28",
         "google-auth-library": "^10.0.0",
         "ink": "^7.1.1",
         "openai": "^6.0.0",

package/templates/editor/.github/skills/zen-analyze-run/SKILL.md

@@ -61,6 +61,11 @@ standard above using its nodes. So, during an analysis:
 - The only commands that reach outside the run are `zen memory search`,
   `zen rag docs search` and `zen rag schema search` - to check whether
   something the run needed was findable.
+- You run on the host, in the project root - not in the run's sandbox. A path
+  the run used as `/assets/<x>` is `assets/<x>` here (or under the folder
+  `assets:` names in `agents.yaml`). So call
+  `zen rag docs search -d assets/<x> "<query>"`, never `-d /assets/...`, and
+  always pass `-d`: `$ZEN_DOCS_DB` / `$ZEN_SCHEMA_DB` may name the sandbox path.
 - Never run `python3`, `node`, `curl`, `wget` or anything under the run's
   `workspace/`, never call the project's APIs or services, never run
   `zen run`, and never read the project's `resources/` or reference

package/dist/meta/finetune/guard.d.ts

@@ -1,29 +0,0 @@
-import type { Case } from './dataset/types.ts';
-import { type Tuning } from './tuning.ts';
-export interface GuardTry {
-    dir: string;
-    verdict: string;
-    passed: boolean;
-    summary?: string;
-}
-export interface GuardResult {
-    case: string;
-    tries: GuardTry[];
-    broken: boolean;
-}
-/** A guard case as the live view and the status page show it, updated as it goes. */
-export interface GuardSeat {
-    case: string;
-    try: number;
-    step: 'run' | 'analyze' | 'passed' | 'broken';
-    /** the try's directory */
-    dir: string;
-    since: number;
-}
-/** A case is broken only after failing this many tries in a row. */
-export declare const GUARD_TRIES = 2;
-/** Completed cases outside `exclude`, in an order fixed by the seed and the apply. */
-export declare function guardCases(t: Tuning, apply: string, exclude: Set<string>): Case[];
-/** Runs the guard for one attempt of an apply; `patch` is that attempt's diff. */
-export declare function guard(t: Tuning, dir: string, attempt: number, exclude: Set<string>, patch: string): Promise<GuardResult[]>;
-//# sourceMappingURL=guard.d.ts.map