@zenera/cli 1.1.31 → 1.1.33

package/README.md

@@ -14,6 +14,9 @@
 [![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)
 [![Node](https://img.shields.io/badge/node-%E2%89%A524-brightgreen.svg)](https://nodejs.org)
+[![CI](https://github.com/andreyryabov/ZeneraNeo/actions/workflows/ci.yml/badge.svg)](https://github.com/andreyryabov/ZeneraNeo/actions/workflows/ci.yml)
+
+[Install](#install) · [Quickstart](#quickstart) · [Commands](#commands) · [Documentation](#documentation) · [Family](#the-rest-of-the-family) · [License](#license)
 
 </div>
 
@@ -732,7 +735,8 @@ Highest first: `--model`, `ZENERA_META_MODEL` in the shell, the same variable in
 the project's `.env`, `zen meta model`, then the project's `agents.yaml`
 `model:`. When none of them answers, a key does: the best model zen knows of
 for the first provider you hold one for, named on stderr as it starts, so a
-fresh machine needs a key and nothing else.
+fresh machine needs a key and nothing else. Through a gateway it is the best
+chat model the gateway serves instead, as `zen models ls --chat --best` ranks it.
 The store is separate from `agents.yaml` on purpose - the model a coding agent
 runs on is a personal choice about a tool, like a key, where `agents.yaml` is a
 committed decision about the project's own agents.
@@ -740,7 +744,8 @@ committed decision about the project's own agents.
 Not every model works. The meta agent declares its tools in a form only the
 reasoning APIs accept, so use a reasoning model - `gpt-5.6-sol`,
 `claude-opus-5`, `gemini-3.8-flash`. Those three are also what it falls back
-to, and what `zen meta model --pick` offers.
+to, and what `zen meta model --pick` offers. `zen meta model` refuses the ones
+that cannot (gpt-4o and older) before asking them anything.
 
 Setting one asks it a one-word question before storing it, so a model that will
 not answer is refused with the provider's own words rather than at the start of
@@ -1125,6 +1130,16 @@ terminal:
 - [docs/gateway.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/gateway.md)
     - every model through a Bifrost gateway, with one virtual key.
 
+## The rest of the family
+
+| Package                                                                                         | What it is                                                    |
+| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| **`@zenera/cli`**                                                                               | `zen` - agent projects on the command line                    |
+| [`@zenera/neo`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/neo/README.md)     | the runtime - agents, models, tools, skills, memory           |
+| [`@zenera/faker`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/faker/README.md) | `zen faker` - a mock API from an openapi/swagger document     |
+| [`@zenera/rag`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/rag/README.md)     | `zen rag` - indexing and search for documents and API schemas |
+| [`@zenera/view`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/view/README.md)   | `zen view` - a live local viewer for a folder                 |
+
 ## License
 
 Early days and moving fast - issues, questions and pull requests are welcome.

package/dist/catalog.d.ts

@@ -142,8 +142,13 @@ export declare function matches(row: CatalogEntry, query: string, filters?: Filt
 export declare const catalogProviders: () => readonly Provider[];
 /** Resold on Vertex rather than made by Google. */
 export declare const isPartner: (e: CatalogEntry) => boolean;
-/** Provider, then Google's own models, then each partner's together. */
+/** Provider, then Google's own models, then each partner's together; best first within each. */
 export declare function byGroup(a: CatalogEntry, b: CatalogEntry): number;
-/** The heading a row is listed under, when its provider resells other makers' models. */
-export declare function groupOf(e: CatalogEntry): string | undefined;
+/** The heading a row is listed under: its provider, split by maker where the provider resells. */
+export declare function groupOf(e: CatalogEntry): string;
+/**
+ * At most `limit` rows, shared evenly between providers and kept in order, so a
+ * long first listing does not push the others off a truncated screen.
+ */
+export declare function sampleByProvider(rows: readonly CatalogEntry[], limit: number): CatalogEntry[];
 //# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.js

@@ -6,9 +6,9 @@
 //
 // Note what is *not* here: any judgement about which model is good. The lists
 // below are ordered by how likely a call is to succeed and how little it costs
-// to find out, not by quality — a recovery path, not a recommender. The moment
-// a file like this starts ranking intelligence it becomes a thing that has to
-// be argued about every quarter, and the argument is not what anyone came for.
+// to find out, not by quality — a recovery path, not a recommender. The one
+// judgement the CLI does make lives in `rank.ts`, read off the ids a listing
+// returns, so that no table here has to be argued about every quarter.
 //
 // Nor is there a single hard-coded table of every model. Vendors ship models
 // faster than a release cycle, so the shipped table is a *fallback* and the
@@ -20,6 +20,7 @@ import { GATEWAY_KEY_HEADER, GATEWAY_NAME, GATEWAY_UPSTREAMS, gatewayOf, ModelRe
 import { Cache, cacheKey } from "./cache.js";
 import { PROVIDERS } from "./keys.js";
 import { classify } from "./liveness.js";
+import { compareModels } from "./rank.js";
 /** A day. Model lists change on the scale of weeks; a stale row costs a retry. */
 export const CATALOG_TTL_MS = 24 * 60 * 60 * 1000;
 export const CATALOG_KIND = 'catalog';
@@ -419,7 +420,13 @@ async function fetchGatewayListing(at) {
     return by;
 }
 function publisherOf(id) {
-    return /^claude-/.test(id) ? 'anthropic' : id.includes('/') ? id.split('/')[0] : 'google';
+    if (/^claude-/.test(id)) {
+        return 'anthropic';
+    }
+    if (/^(mistral|codestral)-/.test(id)) {
+        return 'mistral';
+    }
+    return id.includes('/') ? id.split('/')[0] : 'google';
 }
 /** What the gateway serves under one provider's name, enriched like a vendor listing. */
 export async function fetchGatewayCatalog(provider, at) {
@@ -669,20 +676,53 @@ export const catalogProviders = () => PROVIDERS;
 // ---------------------------------------------------------------------------
 /** Resold on Vertex rather than made by Google. */
 export const isPartner = (e) => e.publisher !== undefined && e.publisher !== 'google';
-/** Provider, then Google's own models, then each partner's together. */
+/** The order listings are shown in: the vendors in rank order, then the resellers. */
+const GROUP_ORDER = ['anthropic', 'openai', 'google', 'vertex', 'openrouter'];
+/** Provider, then Google's own models, then each partner's together; best first within each. */
 export function byGroup(a, b) {
-    return (a.provider.localeCompare(b.provider) ||
+    return (GROUP_ORDER.indexOf(a.provider) - GROUP_ORDER.indexOf(b.provider) ||
         Number(isPartner(a)) - Number(isPartner(b)) ||
         (a.publisher ?? '').localeCompare(b.publisher ?? '') ||
-        a.id.localeCompare(b.id));
+        compareModels(a, b));
 }
-/** The heading a row is listed under, when its provider resells other makers' models. */
+/** The heading a row is listed under: its provider, split by maker where the provider resells. */
 export function groupOf(e) {
     if (!e.publisher) {
-        return undefined;
+        return e.provider;
     }
     return isPartner(e)
         ? `${e.provider} · partner · ${e.publisher}`
         : `${e.provider} · Google (Gemini, Gemma, Imagen, Veo)`;
 }
+/**
+ * At most `limit` rows, shared evenly between providers and kept in order, so a
+ * long first listing does not push the others off a truncated screen.
+ */
+export function sampleByProvider(rows, limit) {
+    if (rows.length <= limit) {
+        return [...rows];
+    }
+    const counts = new Map();
+    for (const row of rows) {
+        const c = counts.get(row.provider) ?? { total: 0, take: 0 };
+        c.total++;
+        counts.set(row.provider, c);
+    }
+    for (let left = limit, gave = true; left > 0 && gave;) {
+        gave = false;
+        for (const c of counts.values()) {
+            if (left > 0 && c.take < c.total) {
+                c.take++;
+                left--;
+                gave = true;
+            }
+        }
+    }
+    const seen = new Map();
+    return rows.filter((row) => {
+        const n = (seen.get(row.provider) ?? 0) + 1;
+        seen.set(row.provider, n);
+        return n <= counts.get(row.provider).take;
+    });
+}
 //# sourceMappingURL=catalog.js.map

package/dist/commands/meta.js

@@ -1,4 +1,4 @@
-import { readProjectConfig } from '@zenera/neo';
+import { gatewayOf, readProjectConfig } from '@zenera/neo';
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
@@ -11,7 +11,7 @@ import { copilotEventLog } from "../eventlog.js";
 import { ensureHome } from "../home.js";
 import { assertOwner, isProvider, 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, 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, editorFiles, fallbackRef, FINETUNE_DETAILS, FINETUNE_SUMMARY, FINETUNE_USAGE, finetuneProjectFlag, lastSession, launch, listPrompts, loadPrompt, locate, masked, metaCompatible, 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, wireGateway, writeMeta, } from "../meta/index.js";
 import { splitRef } from "../modelref.js";
 import { duration } from "../narrate.js";
 import * as Projects from "../projects.js";
@@ -169,10 +169,13 @@ export const meta = {
         'The model is looked for in this order: --model, ZENERA_META_MODEL in the',
         "shell, ZENERA_META_MODEL in the project's .env, `zen meta model`, then",
         'agents.yaml. With none of them set it uses the best model it knows of for',
-        'a provider you hold a key for, and says which on stderr.',
+        'a provider you hold a key for, and says which on stderr. Through a gateway',
+        'it asks what the gateway serves and takes the best of that, as ranked by',
+        '`zen models ls --chat --best`.',
         '',
         'Setting one asks the provider a one-word question first, so a model that',
-        'will not answer is never stored. --force skips that.',
+        "will not answer is never stored. A model whose API rejects copilot's tools",
+        '(gpt-4o and older) is refused before that. --force skips both.',
         '',
         '`zen meta model --pick` browses every model your keys reach: / filters,',
         't asks one a question, p takes it.',
@@ -554,15 +557,17 @@ async function go(ctx, values, project, prompt, promptName) {
     ensureHome();
     const store = await KeyStore.open();
     store.materialize();
+    // After materialize: a keyring in bifrost mode is what sets the url.
+    const gateway = gatewayOf();
     const only = values.provider ? asProvider(values.provider) : undefined;
+    // The fallback can cost a gateway listing, so it is only looked up when nothing else answers.
     const chosen = chooseModel({
         flag: values.model,
         shell,
         env: process.env[MODEL_ENV],
         stored: (await readMeta()).model,
         project: projectModel(project.dir),
-        fallback: defaultRef(store, only),
-    });
+    }) ?? chooseModel({ fallback: await fallbackRef(store, only, gateway !== undefined) });
     if (!chosen) {
         if (only) {
             throw credentialError(`no ${only} key`, `add one: zen key add ${only}`);
@@ -577,11 +582,11 @@ async function go(ctx, values, project, prompt, promptName) {
     if (meant && !only) {
         warn(`${chosen.ref} names no provider — did you mean ${meant}/${id}?`);
     }
-    const entry = store.active(owner);
-    if (!entry) {
+    const entry = gateway ? undefined : store.active(owner);
+    if (!gateway && !entry) {
         throw credentialError(`no ${owner} key`, `add one: zen key add ${owner}`);
     }
-    const wiring = wire(store, entry, id);
+    const wiring = gateway ? wireGateway(gateway, owner, id) : wire(store, entry, id);
     const binary = locate();
     // Copilot cannot carry a session to another model: the resume fails on the first call.
     const ran = values.resume ? sessionModel(values.resume) : undefined;
@@ -621,7 +626,10 @@ async function go(ctx, values, project, prompt, promptName) {
         warn(competing);
     }
     if (chosen.from === 'default') {
-        note(dim(`no model set — using ${chosen.ref}, the best ${owner} model zen knows of`));
+        const what = gateway
+            ? 'the best model the gateway serves'
+            : `the best ${owner} model zen knows of`;
+        note(dim(`no model set — using ${chosen.ref}, ${what}`));
         note(dim('set another: zen meta model <provider>/<id>'));
     }
     note(cyan(`${owner} · ${wiring.model} · ${project.name}`));
@@ -920,13 +928,15 @@ async function model(ctx, values, args) {
     if (ref) {
         return set(ctx, values, project, ref);
     }
+    const store = await KeyStore.open();
+    store.materialize();
     const sources = {
         flag: undefined,
         shell,
         env: process.env[MODEL_ENV],
         stored: (await readMeta()).model,
         project: project ? projectModel(project.dir) : undefined,
-        fallback: defaultRef(await KeyStore.open()),
+        fallback: await fallbackRef(store, undefined, gatewayOf() !== undefined),
     };
     const chosen = chooseModel(sources);
     const at = {
@@ -998,11 +1008,14 @@ async function vet(ctx, ref) {
     }
     const { provider, id } = splitRef(ref);
     const owner = provider ?? 'openai';
+    if (!metaCompatible(owner, id)) {
+        throw usageError(`${owner}/${id} cannot run the meta agent: its API rejects copilot's tools`, 'pick a reasoning model, e.g. from: zen models ls --chat --best');
+    }
     const store = await KeyStore.open();
-    if (!store.active(owner)) {
+    store.materialize();
+    if (!gatewayOf() && !store.active(owner)) {
         throw credentialError(`no ${owner} key to try ${id} with`, `add one: zen key add ${owner}`);
     }
-    store.materialize();
     const bar = ctx.json ? undefined : progress();
     bar?.update(dim(`asking ${owner} about ${id} …`));
     const probe = await probeModel({
@@ -1058,13 +1071,12 @@ async function pickModel(ctx) {
         throw usageError('--pick needs a terminal', 'name the model instead');
     }
     const store = await KeyStore.open();
-    const known = store.entries
-        .filter((e) => e.provider !== 'exa')
-        .map((e) => e.provider);
-    if (known.length === 0) {
+    store.materialize();
+    const known = store.entries.map((e) => e.provider).filter(isProvider);
+    if (known.length === 0 && !gatewayOf()) {
         throw credentialError('no keys to choose from', 'add one: zen key add openai');
     }
-    const held = [...new Set(known)];
+    const held = gatewayOf() ? [] : [...new Set(known)];
     const { browseModels } = await import("./models.js");
     const chosen = await browseModels({
         initial: held.length === 1 ? held[0] : undefined,

package/dist/commands/models.js

@@ -13,11 +13,12 @@
 // ---------------------------------------------------------------------------
 import { createEmbedder, GATEWAY_NAME, gatewayOf, ModelRegistry } from '@zenera/neo';
 import { parse } from "../args.js";
-import { byGroup, groupOf, isPartner, loadCatalog, loadCatalogs, matches, routerBalance, } from "../catalog.js";
+import { byGroup, groupOf, isPartner, loadCatalog, loadCatalogs, matches, routerBalance, sampleByProvider, } from "../catalog.js";
 import { ensureHome } from "../home.js";
 import { envNames, form, isProvider, KeyStore, PROVIDERS } from "../keys.js";
 import { probeChat, probeModel } from "../liveness.js";
-import { ago, bold, CliError, credentialError, cyan, dim, EXIT, green, isInteractive, json, note, progress, red, table, usageError, write, writeAll, yellow, } from "../term.js";
+import { compareModels } from "../rank.js";
+import { ago, bold, CliError, credentialError, cut, cyan, dim, EXIT, green, isInteractive, json, note, plain, progress, red, table, usageError, write, writeAll, yellow, } from "../term.js";
 const USAGE = 'zen models <providers|ls|search|show|test|browse> [ref] [options]';
 /**
  * The keyring is materialised here, and only here.
@@ -142,18 +143,54 @@ function row(entry) {
         dim(entry.name ?? ''),
     ];
 }
-/** The table, with a heading wherever a reseller's rows change maker. */
-function grouped(entries) {
-    const lines = table(entries.map(row));
+/** Drops every column no row has anything in, so a blank one costs no gap. */
+function filled(rows) {
+    const keep = (rows[0] ?? []).map((_, c) => rows.some((r) => plain(r[c] ?? '') !== ''));
+    return rows.map((r) => r.filter((_, c) => keep[c]));
+}
+/**
+ * One section per provider (and per maker, where a provider resells), each
+ * headed by how much of it is on screen and how fresh it is. The maker is in
+ * the heading, so it is not repeated as a column. Columns line up across
+ * sections, so the eye can run down them past a heading.
+ */
+function sections(shown, all, cats) {
+    const totals = new Map();
+    for (const e of all) {
+        totals.set(groupOf(e), (totals.get(groupOf(e)) ?? 0) + 1);
+    }
+    const counts = new Map();
+    for (const e of shown) {
+        counts.set(groupOf(e), (counts.get(groupOf(e)) ?? 0) + 1);
+    }
+    const fresh = new Map(cats.map((c) => [c.provider, c]));
+    // An empty cell stays unstyled: style codes around nothing defeat the table's trimEnd.
+    const faint = (s) => (s ? dim(s) : '');
+    const lines = table(filled(shown.map((e) => [
+        cyan(e.ref),
+        faint(roleMark(e)),
+        faint(tokens(e.contextLength)),
+        faint(e.pricing?.free ? 'free' : ''),
+        // A gateway names a model by its id, which the ref already says.
+        faint(e.name && e.name !== e.id ? e.name : ''),
+    ])));
     const out = [];
+    const headed = new Set();
+    // A wrapped row reads as two models; a piped listing keeps every character.
+    const fit = (line) => process.stdout.isTTY && process.stdout.columns ? cut(line, process.stdout.columns) : line;
     let last;
-    entries.forEach((e, i) => {
+    shown.forEach((e, i) => {
         const group = groupOf(e);
-        if (group && group !== last) {
-            out.push(...(out.length > 0 ? [''] : []), bold(group));
+        if (group !== last) {
+            const total = totals.get(group);
+            const on = counts.get(group);
+            const size = on < total ? `${on} of ${total}` : String(total);
+            const cat = headed.has(e.provider) ? undefined : fresh.get(e.provider);
+            headed.add(e.provider);
+            out.push(...(out.length > 0 ? [''] : []), `${bold(group)}  ${dim(size)}${cat ? `  ${freshness(cat)}` : ''}`);
         }
         last = group;
-        out.push(lines[i]);
+        out.push(fit(`  ${lines[i]}`));
     });
     return out;
 }
@@ -162,10 +199,19 @@ function grouped(entries) {
  * on stderr, because it is narration about the answer rather than the answer.
  */
 function explain(cats) {
+    // Through a gateway every provider shares one request, so one failure is said once.
+    const said = new Set();
     for (const cat of cats) {
         if (cat.problem) {
-            note(`${yellow(cat.provider)} could not be listed: ${cat.problem.detail ?? 'no reason given'} ` +
-                dim(`(showing the ${cat.origin} list)`));
+            const who = cat.via ? cat.via.name : cat.provider;
+            const detail = cat.problem.detail ?? 'no reason given';
+            if (said.has(`${who}\0${detail}`)) {
+                continue;
+            }
+            said.add(`${who}\0${detail}`);
+            // A gateway has no built-in list to fall back on.
+            const shown = cat.via ? 'nothing listed' : `showing the ${cat.origin} list`;
+            note(`${yellow(who)} could not be listed: ${detail} ` + dim(`(${shown})`));
             if (cat.problem.fix) {
                 note(dim(`  ${cat.problem.fix}`));
             }
@@ -225,7 +271,8 @@ const ls = async (ctx, args) => {
         refresh: { type: 'boolean' },
         limit: { type: 'string' },
         all: { type: 'boolean' },
-    }, 'zen models ls [provider] [--chat] [--embeddings] [--refresh] [--limit N] [--all]');
+        best: { type: 'boolean' },
+    }, 'zen models ls [provider] [--chat] [--embeddings] [--best] [--refresh] [--limit N] [--all]');
     const where = await credentials();
     const targets = scope(where, positionals[0]);
     const roles = rolesFrom(values);
@@ -237,7 +284,7 @@ const ls = async (ctx, args) => {
     const all = cats
         .flatMap((c) => c.entries)
         .filter((e) => matches(e, '', { roles }))
-        .sort(byGroup);
+        .sort(values.best ? compareModels : byGroup);
     if (ctx.json) {
         json({
             models: all,
@@ -253,14 +300,20 @@ const ls = async (ctx, args) => {
     announce(ctx, where);
     explain(cats);
     if (all.length === 0) {
-        note(dim('nothing matched — try: zen models ls --refresh'));
+        if (!cats.every((c) => c.problem)) {
+            note(dim('nothing matched — try: zen models ls --refresh'));
+        }
         return;
     }
-    writeAll(grouped(all.slice(0, limit)));
-    if (all.length > limit) {
-        note(dim(`${all.length - limit} more — narrow with \`zen models search\`, or pass --all`));
+    // A ranking keeps its top; a grouped listing shows some of every provider.
+    const shown = values.best ? all.slice(0, limit) : sampleByProvider(all, limit);
+    writeAll(values.best ? table(shown.map(row)) : sections(shown, all, cats));
+    if (all.length > shown.length) {
+        const one = targets.length === 1 ? targets[0] : '<provider>';
+        note('');
+        note(dim(`showing ${shown.length} of ${all.length} — zen models ls ${one} --all, or zen models search <words>`));
     }
-    if (!where.gateway && all.some(isPartner)) {
+    if (!where.gateway && shown.some(isPartner)) {
         note(dim('partner models are billed through Vertex and must be enabled in Model Garden first: https://console.cloud.google.com/vertex-ai/model-garden'));
     }
 };
@@ -277,7 +330,8 @@ const search = async (ctx, args) => {
         'min-context': { type: 'string' },
         limit: { type: 'string' },
         refresh: { type: 'boolean' },
-    }, 'zen models search <query> [--provider p] [--embeddings] [--tools] [--vision] [--free] [--min-context N] [--limit N]');
+        best: { type: 'boolean' },
+    }, 'zen models search <query> [--provider p] [--embeddings] [--tools] [--vision] [--free] [--min-context N] [--best] [--limit N]');
     const query = positionals.join(' ').trim();
     const where = await credentials();
     const targets = scope(where, values.provider);
@@ -298,8 +352,10 @@ const search = async (ctx, args) => {
         .filter((e) => matches(e, query, filters))
         // Cheapest first when price is known: search is usually the step before
         // picking one, and the free ones are what most people are looking for.
-        .sort((a, b) => Number(b.pricing?.free ?? false) - Number(a.pricing?.free ?? false) ||
-        byGroup(a, b));
+        .sort(values.best
+        ? compareModels
+        : (a, b) => Number(b.pricing?.free ?? false) - Number(a.pricing?.free ?? false) ||
+            byGroup(a, b));
     if (ctx.json) {
         json({ query, matched: hits.length, models: hits.slice(0, limit) });
         return;
@@ -622,6 +678,11 @@ export const models = {
         '  zen models test <ref> …          Ask it one real question.',
         '  zen models browse [provider]     Walk providers and models with the',
         '                                   arrow keys; t asks one, p prints its ref.',
+        '',
+        'Listings are grouped by provider, best model first in each. `ls --best`',
+        'and `search --best` drop the groups for one list, best first: Anthropic,',
+        'OpenAI, Google, then the rest; newer generations and higher tiers ahead;',
+        'mini, nano, lite and haiku last. A heuristic read off the ids, not a benchmark.',
     ],
     run: async (ctx) => {
         const [name, ...rest] = ctx.args;

package/dist/keys.d.ts

@@ -202,7 +202,12 @@ export declare class KeyStore {
      * since its url alone is what switches the library over.
      */
     environment(only?: KeyOwner[]): Record<string, string>;
-    /** Applies `environment()` to this process. Returns what it set. */
+    /**
+     * Copies the keyring's active credentials into `process.env`, the only
+     * place the library looks. Must run before anything that reads them —
+     * in `bifrost` mode this is what sets `BIFROST_BASE_URL`, so `gatewayOf()`
+     * returns undefined until it has. Returns what it set.
+     */
     materialize(only?: KeyOwner[]): Record<string, string>;
 }
 /**

package/dist/keys.js

@@ -482,7 +482,12 @@ export class KeyStore {
         }
         return env;
     }
-    /** Applies `environment()` to this process. Returns what it set. */
+    /**
+     * Copies the keyring's active credentials into `process.env`, the only
+     * place the library looks. Must run before anything that reads them —
+     * in `bifrost` mode this is what sets `BIFROST_BASE_URL`, so `gatewayOf()`
+     * returns undefined until it has. Returns what it set.
+     */
     materialize(only) {
         const env = this.environment(only);
         Object.assign(process.env, env);

package/dist/meta/host.d.ts

@@ -1,9 +1,11 @@
 export { invokedAs, parse } from '../args.ts';
+export { loadCatalogs } from '../catalog.ts';
 export type { EventLine } from '../eventlog.ts';
 export { paths, readJson, writeJson } from '../home.ts';
-export { envOf, type KeyEntry, type KeyStore, type Provider } from '../keys.ts';
+export { envOf, PROVIDERS, type KeyEntry, type KeyStore, type Provider } from '../keys.ts';
 export { PROVIDER_NAMES, splitRef } from '../modelref.ts';
 export { duration } from '../narrate.ts';
+export { rankModels } from '../rank.ts';
 export { copyTree, SHARED_RULES, TEMPLATES } from '../scaffold.ts';
 export { bold, CliError, confirm, credentialError, cut, cyan, dim, EXIT, green, invalidError, json, note, pad, plain, red, styled, table, usageError, write, writeAll, yellow, } from '../term.ts';
 export { safe } from '../trace.ts';

package/dist/meta/host.js

@@ -6,10 +6,12 @@
 // a dependency. `test/meta-boundary.test.ts` holds the line.
 // ---------------------------------------------------------------------------
 export { invokedAs, parse } from "../args.js";
+export { loadCatalogs } from "../catalog.js";
 export { paths, readJson, writeJson } from "../home.js";
-export { envOf } from "../keys.js";
+export { envOf, PROVIDERS } from "../keys.js";
 export { PROVIDER_NAMES, splitRef } from "../modelref.js";
 export { duration } from "../narrate.js";
+export { rankModels } from "../rank.js";
 export { copyTree, SHARED_RULES, TEMPLATES } from "../scaffold.js";
 export { bold, CliError, confirm, credentialError, cut, cyan, dim, EXIT, green, invalidError, json, note, pad, plain, red, styled, table, usageError, write, writeAll, yellow, } from "../term.js";
 export { safe } from "../trace.js";

package/dist/meta/model.d.ts

@@ -21,12 +21,29 @@ export interface ModelSources {
 }
 /** Where the answer is looked for, best first. */
 export declare const ORDER: readonly ModelSource[];
+/**
+ * Decides which model `zen meta` runs copilot on, when it can be named in six
+ * places at once. The source comes back too, so a surprising pick can be traced
+ * ("from agents.yaml model:") instead of guessed at.
+ */
 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 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;
+/**
+ * The model `zen meta` falls back to when nothing names one, so a machine with
+ * just a key (or just a gateway, which reaches every provider) still runs.
+ * `only` is `--provider`: the recommendation for that provider, if it is held.
+ */
+export declare function defaultRef(store: KeyStore, only?: Provider, gateway?: boolean): string | undefined;
+/**
+ * The best chat model a gateway actually serves, by `rank.ts`: a vendor
+ * recommendation it does not carry would fail on the first call. The store must
+ * already be materialized, since that is what puts the gateway in the environment.
+ */
+export declare function gatewayDefaultRef(only?: Provider): Promise<string | undefined>;
+/** The last resort: through a gateway, what it serves; otherwise what a held key recommends. */
+export declare function fallbackRef(store: KeyStore, only?: Provider, gateway?: boolean): Promise<string | undefined>;
 export interface MetaFile {
     version: 1;
     model?: string;

package/dist/meta/model.js

@@ -1,4 +1,5 @@
-import { paths, PROVIDER_NAMES, readJson, writeJson, } from "./host.js";
+import { loadCatalogs, paths, PROVIDER_NAMES, PROVIDERS, rankModels, readJson, writeJson, } from "./host.js";
+import { metaCompatible } from "./wire.js";
 // ---------------------------------------------------------------------------
 // The model
 // ---------------------------------------------------------------------------
@@ -13,6 +14,11 @@ export const ORDER = [
     'project',
     'default',
 ];
+/**
+ * Decides which model `zen meta` runs copilot on, when it can be named in six
+ * places at once. The source comes back too, so a surprising pick can be traced
+ * ("from agents.yaml model:") instead of guessed at.
+ */
 export function chooseModel(sources) {
     const at = {
         flag: sources.flag,
@@ -57,16 +63,37 @@ export const RECOMMENDED = {
 };
 /** Which provider is tried first when several are held. */
 const PREFERENCE = ['anthropic', 'openai', 'vertex', 'google', 'openrouter'];
-/** The recommended ref for the first provider with a key, or for `only`. */
-export function defaultRef(store, only) {
+/**
+ * The model `zen meta` falls back to when nothing names one, so a machine with
+ * just a key (or just a gateway, which reaches every provider) still runs.
+ * `only` is `--provider`: the recommendation for that provider, if it is held.
+ */
+export function defaultRef(store, only, gateway = false) {
     for (const provider of only ? [only] : PREFERENCE) {
         const id = RECOMMENDED[provider]?.[0];
-        if (id && store.active(provider)) {
+        if (id && (gateway || store.active(provider))) {
             return `${provider}/${id}`;
         }
     }
     return undefined;
 }
+/**
+ * The best chat model a gateway actually serves, by `rank.ts`: a vendor
+ * recommendation it does not carry would fail on the first call. The store must
+ * already be materialized, since that is what puts the gateway in the environment.
+ */
+export async function gatewayDefaultRef(only) {
+    const cats = await loadCatalogs(only ? [only] : PROVIDERS);
+    const usable = cats
+        .flatMap((c) => c.entries)
+        .filter((e) => e.roles.includes('chat') && metaCompatible(e.provider, e.id));
+    const best = rankModels(usable)[0];
+    return best ? `${best.provider}/${best.id}` : undefined;
+}
+/** The last resort: through a gateway, what it serves; otherwise what a held key recommends. */
+export async function fallbackRef(store, only, gateway = false) {
+    return ((gateway ? await gatewayDefaultRef(only) : undefined) ?? defaultRef(store, only, gateway));
+}
 const EMPTY = { version: 1 };
 export const readMeta = () => readJson(paths.meta(), EMPTY);
 export function writeMeta(file) {

package/dist/meta/wire.d.ts

@@ -1,3 +1,4 @@
+import { type Gateway } from '@zenera/neo';
 import { type KeyEntry, type KeyStore, type Provider } from './host.ts';
 /**
  * Copilot offers its tools as OpenAI *custom* tools, which the completions API
@@ -7,6 +8,8 @@ import { type KeyEntry, type KeyStore, type Provider } from './host.ts';
  * listed rather than newer ones, so each new generation works without a release.
  */
 export declare function wireApi(provider: Provider, id: string): string | undefined;
+/** Whether copilot's tools survive the model: OpenAI's completions-only models refuse them. */
+export declare function metaCompatible(provider: Provider, id: string): boolean;
 export interface Wiring {
     provider: Provider;
     /** what the model is called on the wire */
@@ -35,6 +38,12 @@ export declare const RELAY_URL = "http://127.0.0.1:<relay>";
  * through a GitHub account we are deliberately not using.
  */
 export declare function wire(store: KeyStore, entry: KeyEntry, id: string): Wiring;
+/**
+ * Through a gateway: one virtual key, and Bifrost's OpenAI or Anthropic drop-in,
+ * which routes on an `<upstream>/<id>` wire model. Claude speaks Anthropic
+ * wherever it is hosted; everything else goes through the OpenAI one.
+ */
+export declare function wireGateway(at: Gateway, provider: Provider, id: string): Wiring;
 /** Values a `--dry-run` may print. A key is four characters and an apology. */
 export declare function masked(env: Record<string, string>, secret: readonly string[]): string[];
 /** Non-fatal, said once, because a competing file is a silent override. */

package/dist/meta/wire.js

@@ -1,3 +1,4 @@
+import { GATEWAY_UPSTREAMS } from '@zenera/neo';
 import { randomBytes } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { credentialError, envOf, invokedAs, yellow, } from "./host.js";
@@ -26,6 +27,10 @@ export function wireApi(provider, id) {
         ? 'responses'
         : undefined;
 }
+/** Whether copilot's tools survive the model: OpenAI's completions-only models refuse them. */
+export function metaCompatible(provider, id) {
+    return provider !== 'openai' || wireApi(provider, id) !== undefined;
+}
 /** Where the relay's url goes once it is listening. */
 export const RELAY_URL = 'http://127.0.0.1:<relay>';
 const vertexClaude = (id) => /^(anthropic\/)?claude-/.test(id);
@@ -112,6 +117,31 @@ export function wire(store, entry, id) {
     }
     return { provider, model: env.COPILOT_PROVIDER_WIRE_MODEL ?? id, env, secret, warnings };
 }
+/**
+ * Through a gateway: one virtual key, and Bifrost's OpenAI or Anthropic drop-in,
+ * which routes on an `<upstream>/<id>` wire model. Claude speaks Anthropic
+ * wherever it is hosted; everything else goes through the OpenAI one.
+ */
+export function wireGateway(at, provider, id) {
+    const claude = provider === 'anthropic' || (provider === 'vertex' && vertexClaude(id));
+    const model = provider === 'vertex' ? id.replace(/^anthropic\//, '') : id;
+    const env = {
+        COPILOT_PROVIDER_TYPE: claude ? 'anthropic' : 'openai',
+        COPILOT_PROVIDER_BASE_URL: `${at.baseURL}${claude ? '/anthropic' : '/openai/v1'}`,
+        COPILOT_PROVIDER_MODEL_ID: model.replace(/^google\//, ''),
+        COPILOT_PROVIDER_WIRE_MODEL: `${GATEWAY_UPSTREAMS[provider]}/${model}`,
+    };
+    const api = wireApi(provider, model);
+    if (api) {
+        env.COPILOT_PROVIDER_WIRE_API = api;
+    }
+    const secret = [];
+    if (at.apiKey) {
+        env.COPILOT_PROVIDER_API_KEY = at.apiKey;
+        secret.push('COPILOT_PROVIDER_API_KEY');
+    }
+    return { provider, model: env.COPILOT_PROVIDER_WIRE_MODEL, env, secret, warnings: [] };
+}
 /** Values a `--dry-run` may print. A key is four characters and an apology. */
 export function masked(env, secret) {
     return Object.entries(env)

package/dist/rank.d.ts

@@ -0,0 +1,24 @@
+export type Maker = 'anthropic' | 'openai' | 'google' | 'other';
+export type Tier = 'top' | 'mid' | 'small';
+export interface ModelTraits {
+    maker: Maker;
+    /** `[5, 6]` for `gpt-5.6-sol`; empty when the id carries none */
+    version: number[];
+    tier: Tier;
+    /** built for one job: codex, search, audio, image… */
+    special: boolean;
+    preview: boolean;
+    /** a dated snapshot, as `YYYYMMDD` or the vendor's shorter `MMDD` */
+    date?: string;
+}
+/** What a listing row needs to be ranked: the provider routing it and its id. */
+export interface Ranked {
+    provider: string;
+    id: string;
+}
+export declare function parseModel(id: string): ModelTraits;
+/** Best first. Usable as a sort comparator on any listing row. */
+export declare function compareModels(a: Ranked, b: Ranked): number;
+/** A sorted copy, best first. */
+export declare function rankModels<T extends Ranked>(rows: readonly T[]): T[];
+//# sourceMappingURL=rank.d.ts.map

package/dist/rank.js

@@ -0,0 +1,153 @@
+// ---------------------------------------------------------------------------
+// Ranking models
+//
+// A heuristic read off the id alone, not a benchmark. Vendors name models by
+// generation and tier, so both can be parsed and compared without a table
+// that goes stale with every release: `gpt-6-sol` outranks `gpt-5.6-sol` the
+// day it is listed.
+//
+// Best first: general models before specialised ones and small tiers last;
+// then Anthropic, OpenAI, Google, everyone else; then the newer generation;
+// then the higher tier; then the rest of the version.
+// ---------------------------------------------------------------------------
+const MAKERS = ['anthropic', 'openai', 'google', 'other'];
+const TIERS = ['top', 'mid', 'small'];
+const SMALL = new Set(['haiku', 'luna', 'mini', 'nano', 'lite', 'small', 'tiny']);
+const TOP = new Set(['opus', 'sol', 'pro', 'ultra', 'argon', 'max']);
+const PREVIEW = new Set(['preview', 'exp', 'experimental', 'beta', 'alpha']);
+// Not `instruct`: open-weight chat models carry it (`qwen3-…-instruct`) as their general release.
+const SPECIAL = /codex|search|audio|realtime|image|tts|transcribe|computer-use|embedding|research|(^|-)live(-|$)/;
+function makerOf(name) {
+    if (name.startsWith('claude')) {
+        return 'anthropic';
+    }
+    // Open weights under OpenAI's name, served by others.
+    if (name.startsWith('gpt-oss')) {
+        return 'other';
+    }
+    if (/^(gpt|chatgpt|o\d)/.test(name)) {
+        return 'openai';
+    }
+    return name.startsWith('gemini') ? 'google' : 'other';
+}
+const parts = (text) => text.split('.').map(Number);
+export function parseModel(id) {
+    // Routed ids carry their maker (`anthropic/claude-opus-5`) and OpenRouter a variant (`:free`).
+    const routed = (id.toLowerCase().split('/').pop() ?? '').replace(/:.*$/, '');
+    // Vertex dates Claude with an at sign: `claude-opus-4-5@20251101`.
+    const [name = '', at] = routed.split('@');
+    const maker = makerOf(name);
+    const words = name.split('-');
+    const traits = {
+        maker,
+        version: [],
+        tier: 'mid',
+        special: SPECIAL.test(name),
+        preview: false,
+        ...(at && /^\d{8}$/.test(at) ? { date: at } : {}),
+    };
+    let ended = false;
+    for (let i = 0; i < words.length; i++) {
+        const word = words[i];
+        if (/^\d{8}$/.test(word)) {
+            traits.date = word;
+            continue;
+        }
+        if (/^20\d\d$/.test(word) &&
+            /^\d\d$/.test(words[i + 1] ?? '') &&
+            /^\d\d$/.test(words[i + 2] ?? '')) {
+            traits.date = word + words[i + 1] + words[i + 2];
+            i += 2;
+            continue;
+        }
+        // `gpt-4-0613`, `gpt-3.5-turbo-0125`
+        if (/^\d{4}$/.test(word) && traits.version.length > 0) {
+            traits.date = word;
+            continue;
+        }
+        if (PREVIEW.has(word)) {
+            traits.preview = true;
+        }
+        if (SMALL.has(word)) {
+            traits.tier = 'small';
+        }
+        else if (TOP.has(word) && traits.tier !== 'small') {
+            traits.tier = 'top';
+        }
+        if (ended) {
+            continue;
+        }
+        // OpenAI's o-series came between GPT-4 and GPT-5.
+        const series = i === 0 && maker === 'openai' ? /^o(\d+)$/.exec(word) : null;
+        if (series) {
+            traits.version = [4, Number(series[1])];
+            ended = true;
+            continue;
+        }
+        // `qwen3`, `llama4`: the generation glued to the family name.
+        const glued = i === 0 ? /^[a-z]+(\d+(?:\.\d+)*)$/.exec(word) : null;
+        if (glued) {
+            traits.version = parts(glued[1]);
+            ended = true;
+            continue;
+        }
+        // `5.6`, `4o`, `v3`, or the `4`, `5` of `opus-4-5`; sizes like `120b` are not versions.
+        const number = /^v?(\d{1,2}(?:\.\d+)*)o?$/.exec(word);
+        if (number) {
+            const next = parts(number[1]);
+            traits.version = traits.version.length > 0 ? [...traits.version, next[0]] : next;
+            if (word.endsWith('o')) {
+                ended = true;
+            }
+            continue;
+        }
+        if (traits.version.length > 0) {
+            ended = true;
+        }
+    }
+    return traits;
+}
+/** The vendor's own endpoint first, then the resellers. */
+function routeRank(provider, maker) {
+    if (provider === maker) {
+        return 0;
+    }
+    return provider === 'vertex' ? 1 : provider === 'openrouter' ? 2 : 3;
+}
+const bucket = (t) => (t.tier === 'small' ? 2 : t.special ? 1 : 0);
+function compareTraits(a, b) {
+    const majorA = a.version[0] ?? -1;
+    const majorB = b.version[0] ?? -1;
+    return (bucket(a) - bucket(b) ||
+        MAKERS.indexOf(a.maker) - MAKERS.indexOf(b.maker) ||
+        majorB - majorA ||
+        TIERS.indexOf(a.tier) - TIERS.indexOf(b.tier) ||
+        compareRest(b.version, a.version) ||
+        Number(a.preview) - Number(b.preview) ||
+        // The alias that follows the newest snapshot, then the newest snapshot.
+        Number(a.date !== undefined) - Number(b.date !== undefined) ||
+        (b.date ?? '').localeCompare(a.date ?? ''));
+}
+function compareRest(a, b) {
+    for (let i = 1; i < Math.max(a.length, b.length); i++) {
+        const diff = (a[i] ?? 0) - (b[i] ?? 0);
+        if (diff !== 0) {
+            return diff;
+        }
+    }
+    return 0;
+}
+/** Best first. Usable as a sort comparator on any listing row. */
+export function compareModels(a, b) {
+    const ta = parseModel(a.id);
+    const tb = parseModel(b.id);
+    return (compareTraits(ta, tb) ||
+        routeRank(a.provider, ta.maker) - routeRank(b.provider, tb.maker) ||
+        a.id.localeCompare(b.id) ||
+        a.provider.localeCompare(b.provider));
+}
+/** A sorted copy, best first. */
+export function rankModels(rows) {
+    return [...rows].sort(compareModels);
+}
+//# sourceMappingURL=rank.js.map

package/package.json

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

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

@@ -26,6 +26,13 @@ Filters, on `ls` and `search`: `--chat`, `--embeddings`, `--images`, `--audio`,
 `--tools`, `--vision`, `--free`, `--min-context <n>`, `--provider <name>`,
 `--limit <n>`, `--all`, `--refresh`.
 
+Listings are grouped by provider (Anthropic, OpenAI, Google, Vertex,
+OpenRouter), best model first in each. `--best` drops the groups for one list,
+best first, `--json` included: Anthropic, OpenAI, Google, then the rest; newer
+generation, then higher tier; mini, nano, lite and haiku last. It is a heuristic
+read off the ids, not a benchmark. `zen models ls --chat --best --json` is the
+list to pick a default from.
+
 `browse` is for a person at a terminal and refuses without one (exit 2). An
 agent wants `ls --json` or `search` instead.