@zenera/cli 1.1.27 → 1.1.29

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)
@@ -110,6 +117,28 @@ Or without installing anything:
 npx @zenera/cli --help
 ```
 
+Tab completion for zsh, bash and fish - commands, projects, stored prompts - is
+set up automatically by the global npm install. It appends a guarded loader to
+your current shell's startup file, once. **Open a new terminal** to activate it;
+the installer cannot update the terminal where you ran npm.
+
+Setup respects `ZDOTDIR` for zsh and `XDG_CONFIG_HOME` for fish. For Bash on
+macOS it covers both login shells (the active `.bash_profile`, `.bash_login` or
+`.profile`) and non-login shells (`.bashrc`). The loader does nothing when `zen`
+is no longer installed.
+
+Local installs and `npx` do not change shell files. Automatic setup is skipped
+under root/sudo, in CI, on Windows, or when `$SHELL` is missing or unsupported.
+Disabling lifecycle scripts with `--ignore-scripts` also disables setup.
+If automatic setup is skipped or fails, or to enable another shell, run:
+
+```sh
+zen completion --install            # the shell you are in; --yes to skip the question
+zen completion fish --install       # or name one
+```
+
+Or add it yourself: `eval "$(zen completion zsh)"` in `~/.zshrc`.
+
 ## Quickstart
 
 From nothing to a specialized agent system:
@@ -121,16 +150,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 +198,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 +230,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 +242,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 +273,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 +282,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 +292,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 +313,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 +324,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 +370,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
@@ -553,24 +579,25 @@ The commands to run next are printed for you to read and type.
 
 ## Commands
 
-| Command   | Does                                                                 |
-| --------- | -------------------------------------------------------------------- |
-| `init`    | Creates a project here, or in `<dir>`, and registers it.             |
-| `list`    | Every known project: sessions, last run, whether one is live.        |
-| `open`    | Opens a project in your editor.                                      |
-| `key`     | The credential keyring - add, check, switch, remove.                 |
-| `models`  | What this machine can use - list, search, test, pick.                |
-| `run`     | Runs the project - the TUI on a terminal, a single answer otherwise. |
-| `meta`    | Runs the meta agent over the project - the one that edits it.        |
-| `inspect` | Opens or rebuilds a run's `report.html`.                             |
-| `view`    | Shows a folder in the browser, redrawn live as its files change.     |
-| `memory`  | What the agents remember - size, listing, one node, or a whole page. |
-| `check`   | Validates the project and every file it names, and asks the models.  |
-| `export`  | Writes the project to a shareable zip archive.                       |
-| `import`  | Unpacks one, registers it, and runs nothing in it.                   |
-| `sandbox` | Checks and prepares the container that command-line tools run in.    |
-| `cache`   | What work has been kept, and getting rid of it.                      |
-| `version` | CLI, library and Node versions.                                      |
+| Command      | Does                                                                 |
+| ------------ | -------------------------------------------------------------------- |
+| `init`       | Creates a project here, or in `<dir>`, and registers it.             |
+| `list`       | Every known project: sessions, last run, whether one is live.        |
+| `open`       | Opens a project in your editor.                                      |
+| `key`        | The credential keyring - add, check, switch, remove.                 |
+| `models`     | What this machine can use - list, search, test, pick.                |
+| `run`        | Runs the project - the TUI on a terminal, a single answer otherwise. |
+| `meta`       | Runs the meta agent over the project - the one that edits it.        |
+| `inspect`    | Opens or rebuilds a run's `report.html`.                             |
+| `view`       | Shows a folder in the browser, redrawn live as its files change.     |
+| `memory`     | What the agents remember - size, listing, one node, or a whole page. |
+| `check`      | Validates the project and every file it names, and asks the models.  |
+| `export`     | Writes the project to a shareable zip archive.                       |
+| `import`     | Unpacks one, registers it, and runs nothing in it.                   |
+| `sandbox`    | Checks and prepares the container that command-line tools run in.    |
+| `cache`      | What work has been kept, and getting rid of it.                      |
+| `completion` | Tab completion for zsh, bash and fish - printed, or installed.       |
+| `version`    | CLI, library and Node versions.                                      |
 
 ### Commands from other packages
 
@@ -645,8 +672,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 +690,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 +710,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.
@@ -757,6 +783,9 @@ fixes and the memory are making runs cheaper; each case has its own
 every try. `start` prints a local address that shows those pages in a browser,
 with their diagrams drawn, updated in place as the tuning writes them.
 
+The whole method, with how to write a rubric that tunes the right thing:
+[docs/finetuning.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/finetuning.md).
+
 ## Credentials
 
 One keyring serves every provider, and a key goes in the same way whatever it
@@ -813,7 +842,6 @@ zen models openai                           # everything OpenAI serves this acco
 zen models search haiku --tools --free      # narrow it
 zen models show openrouter:anthropic/claude-haiku-4.5
 zen models test vertex:gemini-embedding-001 # one real call, one verdict
-zen models pick --embedding                 # the first ref that answers, on stdout
 zen models browse                           # walk providers and models with the arrow keys
 ```
 
@@ -837,15 +865,15 @@ $ zen models test vertex:gemini-embedding-001
 vertex:gemini-embedding-001  blocked  Vertex AI API has not been used in project my-proj …
 fix 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
+        see what else there is: zen models ls --embeddings
 ```
 
-`zen models pick` tries a short list of candidates one at a time, stops at the
-first that works, and prints the bare reference on stdout. So recovering from
-the above is a single substitution, whether a person or an agent is doing it:
+To take another model instead, list what the account serves, test one, and put
+its ref in `agents.yaml` or the flag that needs it:
 
 ```sh
-zen rag schema index --embedding "$(zen models pick --embedding)" ./specs/*.yaml
+zen models ls --embeddings
+zen models test openai:text-embedding-3-small
 ```
 
 `zen models browse [provider]` is the interactive way in: arrow keys through
@@ -1023,6 +1051,26 @@ clear where a working provider actually comes from.
 
 </details>
 
+<details>
+<summary><strong>Every model through a Bifrost gateway</strong></summary>
+
+With one virtual key in place of every vendor key:
+
+```sh
+zen key add bifrost --url https://bifrost.example.com
+zen key mode bifrost            # every run goes through the gateway
+zen key mode direct             # back to the vendor keys
+```
+
+`agents.yaml` does not change. Each model keeps its own vendor's protocol and
+is sent to the gateway's matching endpoint - `vertex:gemini-3.5-flash` reaches
+`/genai` as `vertex/gemini-3.5-flash` - so thinking and cache accounting
+survive the trip. The whole story - variables, the sandbox, `zen models`, known
+limits - is in
+[docs/gateway.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/gateway.md).
+
+</details>
+
 ## Cache - work you have already paid for
 
 Embedding a paragraph, parsing a document, asking a provider what it serves: all
@@ -1072,6 +1120,10 @@ terminal:
     - making an API description searchable and mockable.
 - [docs/memory.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/memory.md)
     - what agents keep between sessions.
+- [docs/finetuning.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/finetuning.md)
+    - building a dataset, writing rubrics, and tuning the project on them.
+- [docs/gateway.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/gateway.md)
+    - every model through a Bifrost gateway, with one virtual key.
 
 ## License
 

package/dist/audit.d.ts

@@ -1,5 +1,5 @@
 import { type ModelRequirement } from '@zenera/neo';
-import { type KeyStore, type Provider } from './keys.ts';
+import { type KeyOwner, type KeyStore } from './keys.ts';
 /** Which key of the config named a reference: `model:`/`models:` or `embedding:`/`embeddings:`. */
 export type DeclaredRole = 'model' | 'embedding';
 export interface ModelIssue {
@@ -19,7 +19,7 @@ export interface ModelIssue {
     /** what to do about a refusal that a new key would not fix */
     fix?: string;
     /** the keyring provider the fix names, when the kind is one of them */
-    add?: Provider;
+    add?: KeyOwner;
 }
 /**
  * Whether a requirement is actually met, and under which variable.

package/dist/audit.js

@@ -1,5 +1,5 @@
 import { projectRegistry, readProjectConfig, } from '@zenera/neo';
-import { envNames, form, gcloudAdc, isProvider, SHAPES, } from "./keys.js";
+import { envNames, form, gcloudAdc, isOwner, isProvider, SHAPES, } from "./keys.js";
 import { bold, dim } from "./term.js";
 /**
  * Every model the project names, keyed by how one would refer to it.
@@ -48,6 +48,9 @@ function declared(config) {
  * such answer, so it names the form the provider is usually reached by.
  */
 export function credentialFor(need) {
+    if (need.gateway) {
+        return { env: need.apiKeyEnv, present: need.satisfied };
+    }
     const provider = isProvider(need.kind) ? need.kind : undefined;
     // A provider with a file form can authenticate without an api key, which is
     // the only thing `satisfied` knows how to look for.
@@ -86,7 +89,11 @@ export function auditModels(projectDir, store) {
                 continue;
             }
             const { env, present } = credentialFor(need);
-            const provider = isProvider(need.kind) ? need.kind : undefined;
+            const provider = need.gateway && isOwner(need.gateway)
+                ? need.gateway
+                : isProvider(need.kind)
+                    ? need.kind
+                    : undefined;
             if (!present) {
                 issues.push({
                     name,
@@ -132,8 +139,8 @@ export function describeIssue(issue) {
     }
     const why = issue.detail ? `: ${issue.detail}` : '';
     if (issue.reason === 'blocked') {
-        const pick = `zen models pick --${issue.role === 'embedding' ? 'embedding' : 'chat'}`;
-        return `${what} authenticated and was then refused${why} — ${dim(issue.fix ?? pick)}`;
+        const list = `zen models ls --${issue.role === 'embedding' ? 'embeddings' : 'chat'}`;
+        return `${what} authenticated and was then refused${why} — ${dim(issue.fix ?? list)}`;
     }
     const fix = `zen key check ${issue.add ?? ''}`.trim();
     return `${what} was rejected when last checked${why} — ${dim(fix)}`;

package/dist/candidates.d.ts

@@ -0,0 +1,9 @@
+export interface Candidate {
+    value: string;
+    description?: string;
+}
+/** Candidates the word being typed is a prefix of. */
+export declare const matching: (found: readonly Candidate[], prefix: string) => Candidate[];
+/** Registered projects whose directory is still there. */
+export declare function projectNames(): Promise<Candidate[]>;
+//# sourceMappingURL=candidates.d.ts.map

package/dist/candidates.js

@@ -0,0 +1,17 @@
+import { existsSync } from 'node:fs';
+import * as Projects from "./projects.js";
+/** Candidates the word being typed is a prefix of. */
+export const matching = (found, prefix) => found.filter((c) => c.value.startsWith(prefix));
+/** Registered projects whose directory is still there. */
+export async function projectNames() {
+    try {
+        const registry = await Projects.Registry.open();
+        return registry.entries
+            .filter((e) => existsSync(e.path))
+            .map((e) => ({ value: e.name, description: e.path }));
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=candidates.js.map

package/dist/catalog.d.ts

@@ -1,3 +1,4 @@
+import { type Gateway } from '@zenera/neo';
 import { type KeyCheck, type Provider } from './keys.ts';
 /**
  * What a model is *for*. A model can hold more than one — Gemini's embedding
@@ -50,6 +51,11 @@ export interface Catalog {
     fetchedAt: string;
     /** why the live call was not used, when it was tried and failed */
     problem?: KeyCheck;
+    /** the gateway it was listed through, when the keyring is in a gateway mode */
+    via?: {
+        name: string;
+        url: string;
+    };
 }
 /** A day. Model lists change on the scale of weeks; a stale row costs a retry. */
 export declare const CATALOG_TTL_MS: number;
@@ -64,11 +70,8 @@ export declare const CATALOG_KIND = "catalog";
  */
 export declare const CURATED: Record<Provider, readonly Omit<CatalogEntry, 'ref' | 'provider' | 'source'>[]>;
 /**
- * The order `zen models pick` walks, per provider and per role.
- *
- * Cheap and fast first. `pick` exists to answer "give me something that works"
- * in one round trip where it can, and the small models answer soonest and cost
- * least when the answer is thrown away — which it always is.
+ * The cheap, fast models per provider and role, best first. `zen init` takes
+ * its default embedder from here.
  */
 export declare const PREFERRED: Record<Provider, {
     chat: readonly string[];
@@ -85,6 +88,8 @@ export declare function fromVertexPartners(): Promise<CatalogEntry[]>;
  * `partners` is the same seam for Vertex's second listing.
  */
 export declare function fetchCatalog(provider: Provider, client?: unknown, partners?: () => Promise<CatalogEntry[]>): Promise<CatalogEntry[]>;
+/** What the gateway serves under one provider's name, enriched like a vendor listing. */
+export declare function fetchGatewayCatalog(provider: Provider, at: Gateway): Promise<CatalogEntry[]>;
 /** The key one provider's listing is filed under, version and all. */
 export declare const catalogKey: (provider: Provider) => string;
 export interface CatalogOptions {