@zenera/cli 1.1.3 → 1.1.4

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

@@ -1,12 +1,12 @@
-# Validating — `zen check` and `zen models`
+# Validating — `zen check`
 
-Both answer without calling a model, so they cost nothing and can be run after
-every edit.
+It reads the project without running it, and spends a few tokens asking each
+model to answer once; `--no-models` gives an answer that costs nothing at all.
 
 ## `zen check`
 
 ```
-zen check [name|dir] [--project <name|dir>] [--no-sandbox] [--strict] [--quiet]
+zen check [name|dir] [--project <name|dir>] [--no-sandbox] [--no-models] [--strict] [--quiet]
 ```
 
 Aliases: `validate`, `doctor`.
@@ -19,6 +19,7 @@ with a code, a location and the fix for it.
 | ----------------------- | --------------------------------------------------- |
 | `--project <name\|dir>` | Which project                                       |
 | `--no-sandbox`          | Skip building and smoke-testing the container image |
+| `--no-models`           | Skip asking each model to answer                    |
 | `--strict`              | Warnings count as failure                           |
 | `--quiet`               | The findings and nothing else                       |
 
@@ -39,10 +40,16 @@ checked too. A word that is neither is a usage error (exit 2), not a report.
   reachable from some agent.
 - Every declared model and embedding resolves to a provider, and that provider
   has a credential on this machine.
+- Unless `--no-models`, every model that has a credential is **asked to answer**
+  once. A key that authenticates says nothing about the id it is spent on, so
+  this is the only way to catch a misspelt, retired or ungranted model. A refusal
+  is an error (`model.refused`, `embedding.refused`); a model that never answered
+  is a warning (`.unreachable`), because that is the network's problem and not
+  the project's.
 - The sandbox: paths stay inside the project, the Dockerfile and its context
   exist, and — unless `--no-sandbox` — the image **builds** and one command runs
-  in it, against a temporary directory rather than your workspace. That is the
-  only thing it starts. No container engine at all is a warning, not an error.
+  in it, against a temporary directory rather than your workspace. No container
+  engine at all is a warning, not an error.
 
 ### Findings
 
@@ -59,6 +66,8 @@ skills.no-catalog     skills.unreachable     skill.unused
 assets.missing        assets.overbroad       sandbox.dockerfile.missing
 sandbox.build         sandbox.smoke          sandbox.start / .unchecked
 provider.invalid      model.none             model.unresolvable
+model.refused         model.unreachable      model.unusable
+embedding.refused     embedding.unreachable  embedding.unusable
 credential.*          service.credential
 ```
 
@@ -77,16 +86,3 @@ model with `reasoningEffort` and tools on the default chat-completions API is a
 valid configuration that fails at runtime with _"Function tools with
 reasoning_effort are not supported … in /v1/chat/completions"_. Set
 `api: responses` alongside it.
-
-## `zen models`
-
-```
-zen models [--project <name|dir>]
-```
-
-The narrower question: what each agent would actually talk to. It resolves every
-provider, model and embedding the project declares, says which credential each
-one needs and whether it is present, and calls nothing.
-
-Reach for `zen models` when a run says a model has no credential and for
-`zen check` when something structural is wrong.

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

@@ -97,6 +97,11 @@ the verdict:
 - **live** — authenticated. A rate-limited answer counts as live, because it
   proves the credential.
 - **dead** — the provider rejected it. A verdict.
+- **blocked** — the credential was accepted and the **account** refused: an API
+  switched off in the project, an empty balance, a model this key was never
+  granted. Do not rotate the key; a new one is refused identically. The check
+  carries a `fix` — for a disabled Google API, the exact
+  `gcloud services enable <api> --project <id>`.
 - **unknown** — the provider could not be asked. Says nothing about the key;
   usually the network.
 

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

@@ -0,0 +1,108 @@
+# Models — `zen models`
+
+```
+zen models <providers|ls|search|show|test|pick> [ref] [options]
+```
+
+Alias: `model`.
+
+Answers **what can I use**. `zen check` answers the other question — whether one
+particular project works — and needs a project to do it. This one needs nothing
+but a credential.
+
+## Subcommands
+
+| Command                     | What it does                                           |
+| --------------------------- | ------------------------------------------------------ |
+| `zen models`                | Providers, credential source, how many models, how old |
+| `zen models <provider>`     | Short for `ls <provider>`                              |
+| `zen models ls [provider]`  | Everything it serves                                   |
+| `zen models search <query>` | Narrow it                                              |
+| `zen models show <ref>`     | One model, every field the vendor gave                 |
+| `zen models test <ref> …`   | One real minimal call per ref, and a verdict           |
+| `zen models pick`           | The first ref that answers, printed on stdout          |
+
+Filters, on `ls` and `search`: `--chat`, `--embeddings`, `--images`, `--audio`,
+`--tools`, `--vision`, `--free`, `--min-context <n>`, `--provider <name>`,
+`--limit <n>`, `--all`, `--refresh`.
+
+`pick` requires `--chat` or `--embedding`, and takes `--provider` and `--limit`.
+
+## Where the lists come from
+
+The providers themselves, cached for a day in `~/.zenera/neo/catalog`. When a
+provider cannot be asked, the last listing is used and reported as stale; only
+if there was never one does a short built-in list stand in. Every row says which
+it was — `--json` carries `source` per model and `origin` per provider.
+
+`--refresh` bypasses the cache. It is the only thing that does.
+
+`zen models` on its own does **not** go to the network. `ls` and `search` do.
+
+## Testing a model
+
+```
+zen models test openai:gpt-4o-mini
+zen models test vertex:gemini-embedding-001 --embedding
+```
+
+The role is taken from the flag, else from what the provider says the model is
+for, else from the id. One minimal call: `ok` for a chat model, one short vector
+for an embedder — the embedding's width is reported, which matters because a
+model serving a different number of dimensions is not interchangeable with the
+one an index was built on.
+
+Four verdicts, and they want four different actions:
+
+| Verdict     | Means                                        | Do                         |
+| ----------- | -------------------------------------------- | -------------------------- |
+| `answers`   | it works                                     | nothing                    |
+| `refused`   | the credential was rejected                  | `zen key check <provider>` |
+| `blocked`   | the credential was fine, the account said no | the `fix` printed under it |
+| `no answer` | it could not be reached                      | try again                  |
+
+Exit `0` when every ref answered, `4` when any did not, `2` for a ref that does
+not parse.
+
+## Recovering from a blocked model
+
+This is what the command is for.
+
+```
+$ zen models test vertex:gemini-embedding-001
+vertex:gemini-embedding-001  blocked  Vertex AI API has not been used in project my-proj …
+vertex:gemini-embedding-001: gcloud services enable aiplatform.googleapis.com --project my-proj
+error 1 of 1 did not answer
+        find one that does: zen models pick --embedding
+```
+
+Two ways out. Run the `gcloud` line, or take a different model:
+
+```
+$ zen models pick --embedding
+openai:text-embedding-3-small
+```
+
+`pick` tries a short ordered list one at a time and stops at the first that
+works. Sequential on purpose — the goal is one working ref, not a survey. The
+ref goes to **stdout alone and unstyled**, so it substitutes directly:
+
+```sh
+zen rag schema index --embedding "$(zen models pick --embedding)" ./specs/*.yaml
+```
+
+`zen models pick --embedding --json` gives `{ref, provider, model, role,
+dimensions, ms, tried}` — `tried` lists every candidate and why it was passed
+over, so a caller can see _why_ a provider was skipped rather than only that it
+was.
+
+When nothing answers, exit `4` and the table of everything tried.
+
+## What it will not do
+
+There is no `test --all`. A sweep across every model on the machine is a bill,
+not a diagnostic — name the refs you care about, or use `pick`.
+
+There is no ranking. The candidate order in `pick` is cheapest-and-fastest
+first, which is about how quickly an answer arrives, not about which model is
+better.

package/templates/project/sandbox/Dockerfile

@@ -18,4 +18,4 @@ COPY --from=node /usr/local/lib/node_modules /usr/local/lib/node_modules
 RUN ln -s /usr/local/lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm \
     && ln -s /usr/local/lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx
 
-RUN npm install -g @zenera/cli @zenera/rag @google/genai
+RUN npm install -g @zenera/cli @zenera/rag