@zenera/cli 1.1.3 → 1.1.4

package/dist/home.d.ts

@@ -5,6 +5,8 @@ export declare const paths: {
     keys: () => string;
     keyDir: () => string;
     faker: () => string;
+    /** cached model listings, one file per provider — public data, not secrets */
+    catalog: () => string;
 };
 /** Creates a directory owner-only, and leaves an existing one's mode alone. */
 export declare function ensureDir(dir: string, mode?: number): string;

package/dist/home.js

@@ -26,6 +26,8 @@ export const paths = {
     keys: () => join(home(), 'keys.json'),
     keyDir: () => join(home(), 'keys'),
     faker: () => join(home(), 'faker'),
+    /** cached model listings, one file per provider — public data, not secrets */
+    catalog: () => join(home(), 'catalog'),
 };
 /** Creates a directory owner-only, and leaves an existing one's mode alone. */
 export function ensureDir(dir, mode = DIR_MODE) {

package/dist/keys.d.ts

@@ -63,12 +63,20 @@ export declare function envOf(entry: Pick<KeyEntry, 'provider' | 'holds' | 'env'
 export declare function isProvider(name: string): name is Provider;
 export declare function isOwner(name: string): name is KeyOwner;
 export declare function assertOwner(name: string): KeyOwner;
-export type Liveness = 'live' | 'dead' | 'unknown';
+/**
+ * `blocked` is the credential being fine and the *account* not: an api switched
+ * off in the project, a spent balance, a model this key was never granted. It
+ * is split out of `dead` because the two want opposite actions — rotating a key
+ * that authenticated perfectly is the wrong afternoon.
+ */
+export type Liveness = 'live' | 'dead' | 'blocked' | 'unknown';
 export interface KeyCheck {
     state: Liveness;
     at: string;
     /** the provider's own words when it said no, or ours when we could not ask */
     detail?: string;
+    /** what to actually do about it, when the refusal implies something specific */
+    fix?: string;
 }
 export interface KeyEntry {
     provider: KeyOwner;

package/dist/lib.d.ts

@@ -1,5 +1,6 @@
 export { extract, invokedAs, one, parse, split, type Parsed, type Split } from './args.ts';
 export { printBanner, type BannerText } from './banner.ts';
+export { CATALOG_TTL_MS, CURATED, fetchCatalog, loadCatalog, loadCatalogs, matches, PREFERRED, type Catalog, type CatalogEntry, type CatalogOptions, type Filters, type Role, } from './catalog.ts';
 export type { Command, Context } from './command.ts';
 export { assertPrivate, ensureDir, ensureHome, home, paths, readJson, writeJson } from './home.ts';
 export { assertNotEmpty, assertOwner, assertUsable, describe, envNames, envOf, form, isOwner, isProvider, keyId, KeyStore, mask, OWNERS, parseRef, PROVIDERS, SERVICES, SHAPES, type CredentialForm, type KeyCheck, type KeyEntry, type KeyOwner, type Liveness, type Provider, type Service, } from './keys.ts';

package/dist/lib.js

@@ -23,6 +23,7 @@
 // ---------------------------------------------------------------------------
 export { extract, invokedAs, one, parse, split } from "./args.js";
 export { printBanner } from "./banner.js";
+export { CATALOG_TTL_MS, CURATED, fetchCatalog, loadCatalog, loadCatalogs, matches, PREFERRED, } from "./catalog.js";
 export { assertPrivate, ensureDir, ensureHome, home, paths, readJson, writeJson } from "./home.js";
 export { assertNotEmpty, assertOwner, assertUsable, describe, envNames, envOf, form, isOwner, isProvider, keyId, KeyStore, mask, OWNERS, parseRef, PROVIDERS, SERVICES, SHAPES, } from "./keys.js";
 export { probe, probeAll } from "./liveness.js";

package/dist/liveness.d.ts

@@ -1,4 +1,6 @@
+import { type Embedder, type Model } from '@zenera/neo';
 import { type KeyCheck, type KeyEntry, type KeyStore } from './keys.ts';
+export declare function classify(err: unknown): KeyCheck;
 /**
  * The cheapest authenticated call each SDK has. Nothing here reads a model or
  * spends a token: the question is only whether the credential is accepted.
@@ -30,4 +32,34 @@ export declare function probe(store: KeyStore, entry: KeyEntry): Promise<KeyChec
  * un-joined again.
  */
 export declare function probeAll(store: KeyStore, entries: readonly KeyEntry[], onProbe?: (entry: KeyEntry, done: number, total: number) => void): Promise<[KeyEntry, KeyCheck][]>;
+/** What the project calls a model, and the thing that call resolved to. */
+export type ModelTarget = {
+    ref: string;
+    kind: 'model';
+    model: Model;
+} | {
+    ref: string;
+    kind: 'embedding';
+    embedder: Embedder;
+};
+export interface ModelProbe {
+    /** the reference as the config writes it — an alias, or a full ref */
+    ref: string;
+    /** the id that goes on the wire */
+    id: string;
+    kind: 'model' | 'embedding';
+    check: KeyCheck;
+    /** how long the round trip took, for the one that is merely slow */
+    ms: number;
+    /** embeddings only: the width the model actually returned */
+    dimensions?: number;
+}
+export declare function probeModel(target: ModelTarget): Promise<ModelProbe>;
+/**
+ * One round trip per model, run together — they are independent questions, and
+ * a project with four models should not take four deadlines to answer. Nothing
+ * here touches `process.env`, so unlike the credential probes there is no case
+ * that has to go alone.
+ */
+export declare function probeModels(targets: readonly ModelTarget[], onProbe?: (target: ModelTarget, done: number, total: number) => void): Promise<ModelProbe[]>;
 //# sourceMappingURL=liveness.d.ts.map

package/dist/liveness.js

@@ -1,4 +1,4 @@
-import { EXA_BASE_URL, ModelRegistry } from '@zenera/neo';
+import { EXA_BASE_URL, ModelRegistry, text, } from '@zenera/neo';
 import { envOf, SHAPES, } from "./keys.js";
 // ---------------------------------------------------------------------------
 // Liveness
@@ -7,6 +7,11 @@ import { envOf, SHAPES, } from "./keys.js";
 // the credential and said no — versus *unknown* — we could not ask. Collapsing
 // them into one red mark is the classic way to send someone hunting for the
 // wrong bug: rotating a perfectly good key because the office wifi was down.
+//
+// *blocked* is the third: the credential authenticated and the account then
+// refused. A disabled api, an empty balance, a model this key was never granted
+// — all arrive as a 403 alongside genuine rejections, and all of them are made
+// worse by rotating the key.
 // ---------------------------------------------------------------------------
 /** Words a provider uses when the credential itself is the problem. */
 const REJECTED = [
@@ -33,7 +38,38 @@ const UNREACHED = [
     'timeout',
     'socket hang up',
 ];
-function classify(err) {
+/** Words for an api the account has switched off, or never switched on. */
+const DISABLED = [
+    'service_disabled',
+    'accessnotconfigured',
+    'has not been used in project',
+    'is disabled',
+    'api is not enabled',
+];
+/** Words for an account that authenticated and then declined to serve. */
+const UNFUNDED = [
+    'insufficient_quota',
+    'billing',
+    'credit balance is too low',
+    'exceeded your current quota',
+    'quota exceeded',
+    'resource_exhausted',
+    'payment required',
+];
+/**
+ * Google names both the api and the project in its refusal, and buries them in
+ * a console url. Digging them back out turns a paragraph into the one command
+ * that fixes it.
+ */
+function enablement(message) {
+    const service = /apis\/api\/([a-z0-9.-]+\.googleapis\.com)/i.exec(message)?.[1];
+    if (!service) {
+        return undefined;
+    }
+    const project = /[?&]project=([a-z0-9-]+)/i.exec(message)?.[1];
+    return `gcloud services enable ${service}${project ? ` --project ${project}` : ''}`;
+}
+export function classify(err) {
     const at = new Date().toISOString();
     // OpenAI, Anthropic and the GenAI SDK all say `status`; OpenRouter's says
     // `statusCode`. Reading only the first would classify a revoked key as
@@ -42,6 +78,26 @@ function classify(err) {
     const status = e?.status ?? e?.statusCode;
     const message = err instanceof Error ? err.message : String(err);
     const haystack = `${status ?? ''} ${message}`.toLowerCase();
+    // Ahead of the 401/403 arm, because both of these arrive as a 403 and both
+    // are about the account rather than the key.
+    if (DISABLED.some((needle) => haystack.includes(needle))) {
+        return {
+            state: 'blocked',
+            at,
+            detail: firstLine(message),
+            fix: enablement(message) ?? 'enable the api for this project in the vendor console',
+        };
+    }
+    // A 429 is this minute's rate limit, not an empty account, and the two
+    // share vocabulary — so a status that says "slow down" wins.
+    if (status !== 429 && UNFUNDED.some((needle) => haystack.includes(needle))) {
+        return {
+            state: 'blocked',
+            at,
+            detail: firstLine(message),
+            fix: 'add credit or raise the quota in the vendor console',
+        };
+    }
     if (status === 401 || status === 403) {
         return { state: 'dead', at, detail: `${status} ${firstLine(message)}` };
     }
@@ -58,7 +114,29 @@ function classify(err) {
     }
     return { state: 'unknown', at, detail: firstLine(message) };
 }
-const firstLine = (s) => s.split('\n')[0].slice(0, 160);
+/**
+ * The one sentence worth showing.
+ *
+ * Google's SDK throws with the whole JSON error body as the message, and a
+ * table cell holding `{"error":{"code":403,"message":"…` is a cell nobody
+ * reads. The sentence inside it is the part a person or an agent acts on, so
+ * that is what comes out when there is one.
+ */
+const firstLine = (s) => {
+    const start = s.indexOf('{');
+    if (start !== -1) {
+        try {
+            const body = JSON.parse(s.slice(start));
+            if (typeof body.error?.message === 'string') {
+                return body.error.message.split('\n')[0].slice(0, 200);
+            }
+        }
+        catch {
+            // Not JSON, or truncated JSON. The raw line is still better than nothing.
+        }
+    }
+    return s.split('\n')[0].slice(0, 200);
+};
 // ---------------------------------------------------------------------------
 // Deadline
 //
@@ -69,15 +147,20 @@ const firstLine = (s) => s.split('\n')[0].slice(0, 160);
 // been answered by now, the honest answer is *unknown*.
 // ---------------------------------------------------------------------------
 const DEADLINE_MS = 15_000;
+/**
+ * A model is asked to think, not merely to authenticate, so it is given longer
+ * — a reasoning model can spend half a minute on one word and still be working.
+ */
+const MODEL_DEADLINE_MS = 90_000;
 class Deadline extends Error {
 }
-async function within(work) {
+async function within(work, ms = DEADLINE_MS) {
     let timer;
     try {
         return await Promise.race([
             work,
             new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new Deadline()), DEADLINE_MS);
+                timer = setTimeout(() => reject(new Deadline()), ms);
                 // The abandoned request must not keep the process alive.
                 timer.unref?.();
             }),
@@ -269,4 +352,110 @@ export async function probeAll(store, entries, onProbe) {
     // the network, and a list that reshuffles itself between runs is unreadable.
     return entries.map((entry) => [entry, results.get(entry)]);
 }
+// ---------------------------------------------------------------------------
+// Models
+//
+// A credential that authenticates says nothing about the model id it is spent
+// on: `gemini-3.5-flash` with an OpenAI key, a deprecated snapshot, a model the
+// account was never granted — all of them pass every check this file otherwise
+// performs and then fail on the first turn of a real run. The only thing that
+// answers the question is asking the model itself, so this asks it: one word
+// in, one word out, per distinct model the project would use.
+// ---------------------------------------------------------------------------
+/** Words a vendor uses when the credential was fine and the model id was not. */
+const UNSERVED = [
+    'model_not_found',
+    'does not exist',
+    'not found',
+    'unknown model',
+    'invalid model',
+    'no endpoints found',
+    'is not supported',
+    'not supported',
+    'no access',
+];
+const targetId = (target) => target.kind === 'model' ? target.model.id : target.embedder.id;
+/**
+ * Refused by the provider, unreachable, or served.
+ *
+ * A model this account cannot use is `blocked`, not `dead`: the credential was
+ * accepted and the id was the thing refused, so the fix is another model rather
+ * than another key. `dead` is left to mean the credential itself was rejected.
+ */
+function classifyModel(err, target) {
+    const at = new Date().toISOString();
+    const message = err instanceof Error ? err.message : String(err);
+    const e = err;
+    const haystack = `${e?.status ?? e?.statusCode ?? ''} ${message}`.toLowerCase();
+    if (err instanceof Deadline || e?.name === 'AbortError' || e?.name === 'TimeoutError') {
+        return { state: 'unknown', at, detail: `no answer in ${MODEL_DEADLINE_MS / 1000}s` };
+    }
+    if (UNSERVED.some((needle) => haystack.includes(needle))) {
+        return { state: 'blocked', at, detail: firstLine(message), fix: instead(target) };
+    }
+    const check = classify(err);
+    return check.state === 'blocked' && !check.fix ? { ...check, fix: instead(target) } : check;
+}
+/** The command that finds something this account can actually use. */
+function instead(target) {
+    const provider = target.ref.includes(':') ? target.ref.split(':')[0] : undefined;
+    return provider
+        ? `zen models ls ${provider}`
+        : `zen models pick --${target.kind === 'embedding' ? 'embedding' : 'chat'}`;
+}
+/**
+ * The smallest real call the model can be asked for. It costs a handful of
+ * tokens, which is the point: anything cheaper than a completion does not
+ * exercise the thing that breaks.
+ *
+ * An embedding answers with its width, which is worth carrying back: a model
+ * that serves the wrong number of dimensions is not interchangeable with the
+ * one an index was built on.
+ */
+async function askModel(target, signal) {
+    if (target.kind === 'embedding') {
+        const res = await target.embedder.embed({ input: ['ping'], signal });
+        return res.dimensions;
+    }
+    await target.model.generate({
+        system: 'Reply with the single word: ok',
+        messages: [{ role: 'user', content: [text('ping')] }],
+        tools: [],
+        signal,
+    });
+    return undefined;
+}
+export async function probeModel(target) {
+    const started = Date.now();
+    const common = { ref: target.ref, id: targetId(target), kind: target.kind };
+    try {
+        // The signal cancels the request; the deadline a little behind it is
+        // the answer for an SDK that decides to ignore the signal.
+        const work = askModel(target, AbortSignal.timeout(MODEL_DEADLINE_MS));
+        const dimensions = await within(work, MODEL_DEADLINE_MS + 5_000);
+        return {
+            ...common,
+            check: { state: 'live', at: new Date().toISOString() },
+            ms: Date.now() - started,
+            ...(dimensions === undefined ? {} : { dimensions }),
+        };
+    }
+    catch (err) {
+        return { ...common, check: classifyModel(err, target), ms: Date.now() - started };
+    }
+}
+/**
+ * One round trip per model, run together — they are independent questions, and
+ * a project with four models should not take four deadlines to answer. Nothing
+ * here touches `process.env`, so unlike the credential probes there is no case
+ * that has to go alone.
+ */
+export async function probeModels(targets, onProbe) {
+    let done = 0;
+    return await Promise.all(targets.map(async (target) => {
+        const result = await probeModel(target);
+        onProbe?.(target, ++done, targets.length);
+        return result;
+    }));
+}
 //# sourceMappingURL=liveness.js.map

package/dist/validate.d.ts

@@ -1,6 +1,6 @@
 import { type AnyTool, type ProjectConfig, type Runner } from '@zenera/neo';
 import { type DeclaredRole } from './audit.ts';
-import { type KeyStore } from './keys.ts';
+import { type KeyStore, type Liveness } from './keys.ts';
 /**
  * `error` — the project will not load, or will not run.
  * `warning` — it loads, and something about it is probably not what was meant.
@@ -82,6 +82,13 @@ export interface ModelReport {
     env?: string;
     credential: 'present' | 'missing' | 'rejected' | 'unknown';
     detail?: string;
+    /** the provider's own answer, when the model was actually asked */
+    check?: {
+        state: Liveness;
+        detail?: string;
+        fix?: string;
+        ms: number;
+    };
     /** agents that would use it */
     usedBy: string[];
 }
@@ -156,6 +163,15 @@ export interface ValidateOptions {
         /** called with each slow step, so the caller can narrate one */
         onProgress?: (what: string) => void;
     };
+    /**
+     * Whether to ask each model that has a credential to answer once. Costs a
+     * few tokens apiece and needs the network, so like the sandbox it is named
+     * separately. Without `keys` there is nothing to ask with and it is skipped.
+     */
+    models?: {
+        enabled: boolean;
+        onProgress?: (what: string) => void;
+    };
 }
 export declare function validateProject(opts: ValidateOptions): Promise<Report>;
 export declare function availableTools(root: string, config: ProjectConfig): AnyTool<unknown>[];

package/dist/validate.js

@@ -5,6 +5,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:pat
 import { auditModels, credentialFor } from "./audit.js";
 import { resolveBuild } from "./image.js";
 import { SHAPES, envNames, form } from "./keys.js";
+import { probeModels } from "./liveness.js";
 import { BuildError, ensurePodmanReady } from "./podman.js";
 // Mirrors the loader's own constants (`packages/neo/src/project/load.ts`).
 // Duplicated rather than exported, because a check that agreed with the loader
@@ -198,18 +199,80 @@ export async function validateProject(opts) {
     // -----------------------------------------------------------------------
     // Models and credentials
     // -----------------------------------------------------------------------
-    const resolved = checkModels(root, config, opts.keys, add);
+    // Nothing to ask with is the same as not asking: the missing credential is
+    // already a finding, and a call that cannot be made teaches nothing twice.
+    const asking = opts.models?.enabled && opts.keys ? opts.models : undefined;
+    const resolved = checkModels(root, config, opts.keys, add, Boolean(asking));
     providers = resolved.providers;
     models.push(...resolved.models);
     checkServices(agents, available, opts.keys, add);
-    // Last, because it is the only step that starts anything: everything a
-    // reading of the files can tell you is already on the report by now, so an
-    // interrupted check is still a useful one.
+    // Last, and in this order, because these are the two steps that leave the
+    // machine: everything a reading of the files can tell you is already on the
+    // report by now, so an interrupted check is still a useful one.
+    if (asking && resolved.targets.length) {
+        await askModels(resolved.targets, asking, add);
+    }
     if (opts.sandbox?.enabled && sandboxSummary(config, agents).used) {
         probed = await probeSandbox(config, build, opts.sandbox, add);
     }
     return done();
 }
+/**
+ * One round trip per model, and a verdict per model.
+ *
+ * A refusal is an error: the provider looked at this reference and said no, and
+ * every run of this project will meet the same answer. Silence is a warning —
+ * it is the network's problem, not the project's, and a report that failed
+ * because a train went into a tunnel would teach the wrong lesson.
+ *
+ * A *blocked* model is an error too, but a different one: the credential was
+ * accepted and the account then refused, so the fix is the vendor's own —
+ * enabling an api, adding credit, choosing a model this account is granted.
+ * Telling someone to check their spelling there costs them an afternoon.
+ */
+async function askModels(targets, opts, add) {
+    opts.onProgress?.(`asking ${targets.length} model${targets.length === 1 ? '' : 's'}`);
+    const probes = await probeModels(targets.map(([, target]) => target), (target, done, total) => opts.onProgress?.(`asked ${target.ref} … ${done}/${total}`));
+    probes.forEach((probe, i) => {
+        const [report] = targets[i];
+        report.check = {
+            state: probe.check.state,
+            ...(probe.check.detail ? { detail: probe.check.detail } : {}),
+            ...(probe.check.fix ? { fix: probe.check.fix } : {}),
+            ms: probe.ms,
+        };
+        if (probe.check.state === 'live') {
+            return;
+        }
+        const where = `${report.role} "${report.name}"${report.provider ? ` (${report.provider})` : ''}`;
+        if (probe.check.state === 'blocked') {
+            const pick = report.role === 'embedding' ? '--embedding' : '--chat';
+            add({
+                severity: 'error',
+                code: `${report.role}.blocked`,
+                where,
+                message: `the credential was accepted and then refused: ${probe.check.detail ?? 'no reason given'}`,
+                fix: `${probe.check.fix ?? 'resolve it in the vendor console'}, or find one that works: zen models pick ${pick}`,
+            });
+            return;
+        }
+        add(probe.check.state === 'dead'
+            ? {
+                severity: 'error',
+                code: `${report.role}.refused`,
+                where,
+                message: `the provider refused it: ${probe.check.detail ?? 'no reason given'}`,
+                fix: `check that ${probe.id} is spelt right, still served, and granted to this account`,
+            }
+            : {
+                severity: 'warning',
+                code: `${report.role}.unreachable`,
+                where,
+                message: `it could not be asked: ${probe.check.detail ?? 'no answer'}`,
+                fix: 'try again, or pass --no-models to skip this',
+            });
+    });
+}
 /**
  * A tool that needs a key of its own is invisible to the model audit, which
  * walks `models:` and finds nothing to say about `web_search`. The project is
@@ -1039,7 +1102,7 @@ function siblings(skillFile) {
 // ---------------------------------------------------------------------------
 // Models
 // ---------------------------------------------------------------------------
-function checkModels(root, config, keys, add) {
+function checkModels(root, config, keys, add, probe = false) {
     let registry;
     try {
         registry = projectRegistry(config);
@@ -1052,7 +1115,7 @@ function checkModels(root, config, keys, add) {
             message: err instanceof Error ? err.message : String(err),
             fix: 'see the `providers:` section of docs/agents-yaml.md',
         });
-        return { providers: [], models: [] };
+        return { providers: [], models: [], targets: [] };
     }
     // Declared under an alias first, so an alias keeps its own name in the
     // report and a `model:` that names one collapses onto it. Mirrors the
@@ -1103,6 +1166,7 @@ function checkModels(root, config, keys, add) {
         }
     }
     const models = [];
+    const targets = [];
     const describe = (role, name, ref, usedBy) => {
         const report = {
             name,
@@ -1153,6 +1217,32 @@ function checkModels(root, config, keys, add) {
             });
         }
         models.push(report);
+        // Only what there is something to ask with. Constructing the client is
+        // what reads the credential, so a model with none cannot be built, let
+        // alone asked — and the missing key is already a finding of its own.
+        if (probe && report.credential === 'present') {
+            try {
+                targets.push([
+                    report,
+                    role === 'model'
+                        ? { ref: name, kind: 'model', model: registry.model(ref) }
+                        : {
+                            ref: name,
+                            kind: 'embedding',
+                            embedder: registry.embedder(ref),
+                        },
+                ]);
+            }
+            catch (err) {
+                add({
+                    severity: 'error',
+                    code: `${role}.unusable`,
+                    where: whereFor(config, role, name, usedBy),
+                    message: err instanceof Error ? err.message : String(err),
+                    fix: 'the provider is declared but cannot be built — see `providers:`',
+                });
+            }
+        }
     };
     for (const [name, { ref, usedBy }] of declared) {
         describe('model', name, ref, usedBy);
@@ -1165,7 +1255,7 @@ function checkModels(root, config, keys, add) {
     if (config.embedding && !config.embeddings?.[config.embedding]) {
         describe('embedding', config.embedding, config.embedding, []);
     }
-    return { providers: registry.names(), models };
+    return { providers: registry.names(), models, targets };
 }
 /** The config key a bad reference was written under. */
 function whereFor(config, role, name, usedBy) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.3",
+    "version": "1.1.4",
     "description": "Command-line front end for @zenera/neo: agentic projects you can run, share and commit.",
     "keywords": [
         "agents",
@@ -51,7 +51,7 @@
         "@inkjs/ui": "^2.0.0",
         "ink": "^7.1.1",
         "react": "^19.2.8",
-        "@zenera/neo": "^1.1.3",
+        "@zenera/neo": "^1.1.4",
         "@anthropic-ai/sdk": "^0.120.0",
         "@google/genai": "^2.18.0",
         "@openrouter/sdk": "^1.2.80",

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

@@ -382,8 +382,8 @@ Google's `embedContent` takes one document per request for every
 hide that. `maxBatch` therefore defaults to `1`; raise it only for a
 `text-embedding-*` model, which accepts more.
 
-`zen check` and `zen models` report every declared embedding beside the models,
-with the credential each one would need.
+`zen check` reports every declared embedding beside the models, with the
+credential each one would need.
 
 ### 3.2 `INSTRUCTIONS.md`
 
@@ -1540,8 +1540,34 @@ There is no compiler for prose. Substitutes, in order of value:
    credential resolves, not that the route serves images or honours `tools`; on a
    gateway that gap is a request-time 404 (§7.5).
 
+### When a model or embedder will not answer
+
+`zen check` names the model and the verdict. Act on the verdict, not on the
+first thing that looks like a credential problem:
+
+```sh
+zen models test <ref>          # one real call, one verdict
+```
+
+- **refused** — the credential was rejected. `zen key check <provider>`.
+- **blocked** — the credential was _accepted_ and the account said no: an API
+  switched off, an empty balance, a model this key was never granted. **Do not
+  rotate the key** — a new one is refused identically. The fix is printed under
+  the verdict; for a disabled Google API it is the exact `gcloud services
+enable …` line.
+- **no answer** — the network. Try again.
+
+Either run the printed fix, or take a model that works and put the ref it prints
+into `agents.yaml`:
+
+```sh
+zen models pick --embedding    # or --chat; the ref goes to stdout, alone
+```
+
+Then re-run `zen check`.
+
 CLI (`zen --help` for the authoritative list): `zen init`, `zen run`, `zen check`,
-`zen inspect`, `zen models`, `zen key`, `zen list`. **stdout is the answer, stderr
+`zen inspect`, `zen key`, `zen models`, `zen list`. **stdout is the answer, stderr
 is the narration**; every command takes `--json`. Exit codes: `0` ok, `1` failed,
 `2` usage, `3` invalid project, `4` no usable credential.
 
@@ -1631,6 +1657,7 @@ Before finishing any change here:
 | Answers from stale knowledge of the world  | Grant `web_search` + `web_read`, and say when — §3.8                |
 | Cites a page it only saw the excerpt of    | A prompt line: `web_read` before quoting — §3.8                     |
 | Every web call refuses                     | No Exa key: `zen key add exa` — `zen check` warns — §3.8            |
+| A model or embedder refuses every call     | `zen models test <ref>` — if `blocked`, `zen models pick` — §8      |
 | Answers instead of routing                 | Router prompt prohibition; check `handoffs:`                        |
 | Routes to the wrong specialist             | The target agents' `description:` fields                            |
 | Loses a detail after a handoff             | Say it in the handoff; check the collapse policy                    |

package/templates/editor/.github/skills/zen-cli/SKILL.md

@@ -21,8 +21,8 @@ zen list     [--sessions] [--prune]
 zen run      [project] [prompt] [options]
 zen open     [project] [--editor <cmd>] [--wait]
 zen key      <ls|add|use|check|rm|show|env> [ref] [options]
-zen models   [--project <name|dir>]
-zen check    [name|dir] [--project <name|dir>] [--no-sandbox] [--strict] [--quiet]
+zen models   <providers|ls|search|show|test|pick> [ref] [options]
+zen check    [name|dir] [--project <name|dir>] [--no-sandbox] [--no-models] [--strict] [--quiet]
 zen inspect  [run] [--session <id>] [--open] [--rebuild] [--serve [port]]
 zen sandbox  [status|up|pull|clean|disk] [options]
 zen version
@@ -42,8 +42,9 @@ guess a flag, and do not read them all.
 | Global flags, `--json`, exit codes, environment, where files live   | [frame.md](./references/frame.md)       |
 | Creating, finding or opening a project                              | [projects.md](./references/projects.md) |
 | Running: the TUI, one-shot answers, sessions, workspaces, overrides | [run.md](./references/run.md)           |
-| Validating: `zen check`, `zen models`, what they can and cannot see | [check.md](./references/check.md)       |
+| Validating: `zen check`, what it can and cannot see                 | [check.md](./references/check.md)       |
 | API keys, providers, the keyring, "no credential" errors            | [keys.md](./references/keys.md)         |
+| Which models exist, whether one works, recovering from a refusal    | [models.md](./references/models.md)     |
 | The container shell commands run in, images, `persist`              | [sandbox.md](./references/sandbox.md)   |
 | Run reports, trajectories, what a session directory holds           | [inspect.md](./references/inspect.md)   |
 | `zen faker` — a mock API from an OpenAPI/Swagger document           | [faker.md](./references/faker.md)       |
@@ -58,6 +59,8 @@ zen run                               the TUI
 zen run "what changed?"               one answer, this directory as the workspace
 zen inspect --open                    what the model was actually given
 zen key ls --check                    which credentials still work
+zen models test <ref>                 whether one model actually answers
+zen models pick --embedding           the first embedder that does, on stdout
 ```
 
 Run `zen check` after any edit to `agents.yaml`, a prompt or a skill: it reads