@zenera/cli 1.1.28 → 1.1.29

package/templates/completions/zen.zsh

@@ -0,0 +1,28 @@
+# zen completion for zsh. Add to ~/.zshrc:
+#
+#     eval "$(zen completion zsh)"
+#
+# Everything it offers comes from `zen __complete`; when that has nothing to
+# say, file names are completed instead.
+_zen() {
+    local line
+    local -a items
+    for line in "${(@f)$("${words[1]}" __complete "${(@)words[2,CURRENT]}" 2>/dev/null)}"; do
+        [[ -n $line ]] || continue
+        if [[ $line == *$'\t'* ]]; then
+            items+=("${${line%%$'\t'*}//:/\\:}:${line#*$'\t'}")
+        else
+            items+=("${line//:/\\:}")
+        fi
+    done
+    if (( $#items )); then
+        _describe -t zen-words 'zen' items
+    else
+        _files
+    fi
+}
+
+if (( ! $+functions[compdef] )); then
+    autoload -Uz compinit && compinit
+fi
+compdef _zen zen zn zenera

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

@@ -1834,11 +1834,12 @@ zen models test <ref>          # one real call, one verdict
 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`:
+Either run the printed fix, or take a model that works and put its ref into
+`agents.yaml`:
 
 ```sh
-zen models pick --embedding    # or --chat; the ref goes to stdout, alone
+zen models ls --embeddings     # or --chat; what this account is served
+zen models test <ref>          # the one you chose actually answers
 ```
 
 Then re-run `zen check`.
@@ -1996,7 +1997,7 @@ candidates; these are the judgements to make about each one)**
 | 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      |
+| A model or embedder refuses every call        | `zen models test <ref>` - if `blocked`, `zen models ls` - §8        |
 | Answers instead of routing                    | Router prompt prohibition; check `handoffs:`                        |
 | Routes to the wrong specialist                | The target agents' `description:` fields                            |
 | Gets stuck in the agent it routed to          | The target needs a handoff back - §6.3                              |

package/templates/editor/.github/prompts/spec-edit.prompt.md

@@ -0,0 +1,250 @@
+---
+description: Change SPECIFICATION.md as the request after the command asks - written in the specification's own structure and voice, checked against what the runtime can actually do - and nothing else.
+argument-hint: what to add, change or remove in the specification
+---
+
+Edit `SPECIFICATION.md` the way the request after this command asks. The
+specification is the intent of the project; you are changing the intent, not
+the implementation. Making the project match it is `/spec-sync-project`, which
+runs after this.
+
+You change one file: `SPECIFICATION.md`. Not `agents.yaml`, not a prompt, not a
+skill, not `SPECIFICATION-FEEDBACK.md`.
+
+## 0. Everything you need is already attached
+
+These files are attached to this prompt so the work starts without a round of
+reads. Use them as they are; do not read them again with a tool.
+
+The project:
+
+- [SPECIFICATION.md](../../SPECIFICATION.md) - the file you are editing.
+- [SPECIFICATION-FEEDBACK.md](../../SPECIFICATION-FEEDBACK.md) - the questions
+  still open against it, and the ones already answered. It may not exist; that
+  only means nothing is open.
+
+What the runtime can do, so that what you write is something it can build:
+
+- [zen-cli](../skills/zen-cli/SKILL.md) - every `zen` command, and
+  [its models reference](../skills/zen-cli/references/models.md) - how to find
+  which models this machine can actually use.
+- [zen-instructions](../skills/zen-instructions/SKILL.md) - house rules: what
+  every agent is told, and what belongs there rather than in a prompt.
+- [zen-topology](../skills/zen-topology/SKILL.md) - one agent or several,
+  hand-off or fork, and what each costs.
+- [zen-memory](../skills/zen-memory/SKILL.md) - what memory is, who may read and
+  write it, and what a strategy for it has to say.
+- [zen-rag-docs](../skills/zen-rag-docs/SKILL.md) - an index over a folder of
+  markdown documents.
+- [zen-rag-schema](../skills/zen-rag-schema/SKILL.md) - an index over an OpenAPI
+  description.
+- [zen-sandbox](../skills/zen-sandbox/SKILL.md) - the container: what it mounts,
+  what it can reach, what persists.
+- [zen-code-python](../skills/zen-code-python/SKILL.md) - reusable scripts as
+  tools, where they live, and which agents own them.
+
+If any of these did not arrive attached - your editor does not resolve links in
+prompt files - read all of them in **one** batch of parallel reads before doing
+anything else, `SPECIFICATION-FEEDBACK.md` included if it exists. Never one at a
+time, and never skip one because the request seems not to need it: a request
+about an agent's job can still decide what that agent may remember.
+
+In the same first step, run once from the project root and keep the output:
+
+```sh
+zen models && zen models ls --chat && zen models ls --embeddings
+```
+
+That is the list of models with a credential on this machine - the only ones a
+**Models** line may name. A model the request names that is not in it: run
+`zen models search <name>` once; if it is still absent, say so in the chat and
+do not write it.
+
+If there is no request after the command, ask what to change and stop.
+
+## 1. Understand the request against what is there
+
+Before writing a line, work out:
+
+- **Whether this is defining the project from the initial scaffold or editing an
+  existing domain specification.** A freshly initialised `SPECIFICATION.md` is a
+  generic placeholder ("Carry out work inside a workspace on request…",
+  "Currently: no steps", "the only agent; nobody to hand work to") written as
+  meta-commentary about what each section does. When the request asks to make or
+  define a specification for a project or domain on top of that scaffold, it
+  reaches **every** section: replace all generic template sentences and
+  meta-explanations with a complete, concrete specification for that domain.
+  When `SPECIFICATION.md` already describes a real domain project and the
+  request asks for a specific change, keep the pass narrow and touch only the
+  sections the change implicates.
+- **Which sections the request touches.** Usually more than the one it names: a
+  new agent changes **Agents**, **Tools and boundaries** and **Done means**; an
+  index changes **Setup**, **Knowledge** and **Environment**.
+- **What it contradicts.** A sentence already in the specification that the
+  request makes false is part of the edit - change it too, and report it.
+- **What it settles in the feedback file.** An open question the request
+  answers, or an answered one it reverses. Do not edit the feedback file; say
+  which questions in the chat.
+- **Whether the runtime can do it.** Check the request against the skills above.
+  Something no tool, agent setting or script can provide is not written into the
+  specification as if it could be: say so in the chat, offer the nearest thing
+  the runtime does do, and write that only if the request leaves no doubt it is
+  wanted.
+
+## 2. The structure of a specification
+
+Keep the sections the file already has, in its order. Add a section only when
+the request needs one, at its place in this order, and leave out any section
+that would be empty:
+
+```markdown
+# Specification
+
+## Purpose
+
+## Scope
+
+## Models
+
+## Setup
+
+## Agents
+
+## Tools and boundaries
+
+## Knowledge
+
+## Memory
+
+## Environment
+
+## Testing
+
+## Done means
+
+## Out of scope
+```
+
+What each one answers:
+
+- **Purpose** - what the system produces, and for whom, in one paragraph.
+- **Scope** - what one request covers, what is in and what is not, hard numeric
+  bounds (when a request is refused with a count rather than truncated), and
+  what has to happen before the system acts.
+- **Models** - every chat and embedding model by its full id from `zen models`,
+  and which agent or job uses which. Keep the chat model already in
+  `SPECIFICATION.md` unless the request asks to change it; add an embedding
+  model from `zen models ls --embeddings` whenever the specification uses
+  `memory/`, `assets/docs-db`, or `assets/schema-db`.
+- **Setup** - what has to exist before a run: OpenAPI specs or reference
+  documents fetched, a `zen rag schema` index built in `assets/schema-db`, a
+  `zen rag docs` index built in `assets/docs-db`, or reference files generated.
+  Each is a named step `scripts/_setup.sh` runs in order; say what it produces,
+  from what inputs, and where it lands.
+- **Agents** - one entry per agent: its name, its one job, who it hands to or
+  forks, and the behaviours that are specific to it. Use **zen-topology** to
+  choose the right shape: split into focused agents (for example, a lead
+  coordinator/analyst, a dedicated quantitative/code agent, and a read-only
+  research agent) when tasks have distinct tool boundaries or heavy code
+  execution (**zen-code-python**), and specify `fork` (`context: none`) when a
+  request compares multiple independent items or runs independent research
+  tracks in parallel.
+- **Tools and boundaries** - what each agent may reach for (files, shell,
+  reusable scripts in `/workspace/scripts/`, web search/read, memory, indexes,
+  external APIs), what is read-only, how transient network/API errors are
+  retried and fallen back from, and what nothing may reach. Every capability
+  named here has an agent that holds it.
+- **Knowledge** - each index (`assets/schema-db`, `assets/docs-db`), each skill
+  under `agents/skills/` (naming the skill and the concrete procedure, formulas,
+  API conventions, or `rag_search` rules it holds), and the concrete external
+  APIs or data sources the project queries (naming specific zero-key primary
+  APIs and endpoints, required headers and rate limits, optional free-tier
+  keyed APIs, and fallback order).
+- **Memory** - what is worth remembering (reusable scripts as `file` nodes,
+  verified identifiers/mappings, API schemas, workflows) and what is not (or
+  how time-sensitive facts are bounded), who may read and write, and when an
+  agent recalls before working and commits after it - see **zen-memory**.
+- **Environment** - the sandbox (`sandbox/Dockerfile`, persistence, network),
+  the exact languages, CLI tools, and libraries pre-installed in the image so
+  agents never install packages at run time, where scripts and data outputs
+  live under `/workspace`, and optional environment variables or credentials by
+  name - see **zen-sandbox**.
+- **Testing** - how a change to the project is checked: `zen check`,
+  `scripts/_setup.sh --check`, `scripts/_setup.sh` run twice in a row reporting
+  `skipped` the second time, and a concrete verification request the project
+  must handle end-to-end.
+- **Done means** - how a finished job is told from an unfinished one, written as
+  concrete acceptance tests in prose that a reviewer could check against a run
+  (exact attribution fields, script-computed numbers, verified page reads,
+  reusable script paths, and required sections).
+- **Out of scope** - what the runtime could do that this project deliberately
+  does not, so nobody adds it because it seemed useful.
+
+## 3. How to write it
+
+- **Replace scaffold boilerplate on a greenfield request; change the smallest
+  thing on an incremental edit.** When `SPECIFICATION.md` is still the initial
+  `zen init` scaffold or the request asks to make a specification for a new
+  project, rewrite every section for that domain and remove the scaffold's
+  generic meta-commentary ("What the work always needs belongs in the image…",
+  "Currently: no steps…", "The reply names what changed, file by file…"). When
+  editing an already-written domain specification, leave every sentence the
+  request does not reach as it is.
+- **Write in a direct, declarative voice.** Match the clean heading and list
+  structure of the specification, stating concrete project rules rather than
+  abstract explanations of how Zenera works.
+- **Say what and why, never raw config syntax.** The specification is not
+  `agents.yaml` in prose. Name the agents, skills, setup steps, indexes, APIs,
+  packages, paths, and behavioural rules clearly, without pasting raw YAML
+  snippets or shell implementation internals that `/spec-sync-project` derives.
+- **Turn high-level domain requests into concrete architectural choices.** When
+  a request asks to design a project in broad terms (for example, "make a
+  specification for financial analytics using open APIs"), do not repeat vague
+  phrases like "open APIs" or "packages for data analysis". Make the concrete
+  domain choices upfront so `/spec-sync-project` can build a working system
+  without guessing:
+    - Name specific, working zero-key public APIs and endpoints as primary
+      sources (with required headers such as `User-Agent` and rate limits),
+      optional keyed free-tier APIs as secondary sources with clean zero-key
+      fallback when keys are absent, and `web_search` / `web_read` rules.
+    - Name the concrete setup steps (`scripts/<name>.sh`), indexes
+      (`assets/schema-db`, `assets/docs-db`), and domain skills under
+      `agents/skills/`.
+    - Name the exact Python/system libraries to pre-install in
+      `sandbox/Dockerfile` and the `/workspace/scripts/` and `/workspace/data/`
+      conventions from **zen-code-python**.
+    - State explicit numeric limits (such as the maximum entities/tickers per
+      request before refusing with a count), retry/fallback rules, and required
+      citation fields.
+- **Be specific where a reader could decide either way.** A limit is a number,
+  a model is an id, a failure has a stated outcome. "Handles large inputs" is
+  not implementable; "a request over 25 tickers is refused with a count, never
+  truncated" is.
+- **Never invent a model id or a user-owned secret.** Keep the model already in
+  `SPECIFICATION.md` unless the request asks to change it, and take any new
+  chat or embedding model strictly from the `zen models` output on this machine,
+  never from memory. Ask before editing only when a required value belongs
+  exclusively to the user (such as a private server URL or proprietary rule)
+  and cannot be satisfied by a standard public default.
+- **Make it checkable.** Every behaviour the request adds gets a line under
+  **Done means** that a reviewer could verify against a recorded run.
+- **Name what is now excluded.** When the request narrows the system, the thing
+  it rules out goes under **Out of scope**.
+- **Say it once.** If the rule already lives in another section, change it
+  there rather than stating it a second time somewhere new.
+
+## 4. Report
+
+In the chat:
+
+- every section you changed, with each new or changed line quoted
+- every edit the request did not name but made necessary, and why
+- every open question in `SPECIFICATION-FEEDBACK.md` the change settles or
+  reopens, by number
+- anything you did not write because the runtime cannot do it, or because it
+  needs a value only the reader has
+- then, in one line: send `/spec-sync-project` to make the project match.
+
+## 5. User Request:
+
+Following is the user request that the specification should address (if any):

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

@@ -22,7 +22,7 @@ zen run      [project] [prompt] [options]
 zen run      batch --input <file> [--batch-dir <dir>] [--concurrency <n>] [--memory-read-only]
 zen open     [project] [--editor <cmd>] [--wait]
 zen key      <ls|add|use|check|rm|show|env> [ref] [options]
-zen models   <providers|ls|search|show|test|pick> [ref] [options]
+zen models   <providers|ls|search|show|test|browse> [ref] [options]
 zen check    [name|dir] [--project <name|dir>] [--no-sandbox] [--no-models] [--strict] [--quiet]
 zen inspect  [report|graph|node|ask] [run] [--dir <run dir>] [--part <name>] [--full] [--open]
 zen memory   [stats|ls|search|grep|show|export|merge|forget] [args] [options]
@@ -80,7 +80,7 @@ zen export                            the project as a zip you can send
 zen import a.zip                      unpack one somebody sent, run nothing in it
 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
+zen models ls --embeddings            the embedders this machine can reach
 zen meta run acme /analyze --json > analyze.json   a stored prompt, the result as JSON
 ```
 

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

@@ -1,7 +1,7 @@
 # Credentials - `zen key`
 
 ```
-zen key <ls|add|use|check|rm|show|env> [ref] [options]
+zen key <ls|add|use|mode|check|rm|show|env> [ref] [options]
 ```
 
 Alias: `keys`.
@@ -20,6 +20,7 @@ keys; one of them is active.
 | `zen key ls [--check]`            | Everything stored, and its state        |
 | `zen key add <provider>[/name]`   | Read a key from stdin, or ask for it    |
 | `zen key use <provider>/<name>`   | Choose which one a run uses             |
+| `zen key mode [direct\|bifrost]`  | Call vendors directly, or via a gateway |
 | `zen key check [provider[/name]]` | Ask the provider whether it still works |
 | `zen key rm <provider>/<name>`    | Forget one                              |
 | `zen key show <ref> [--reveal]`   | Masked by default                       |
@@ -49,8 +50,32 @@ echo-off prompt and from nowhere else.
 | `vertex`     | `VERTEX_API_KEY`                 | secret | an express-mode key from GCP        |
 | `openrouter` | `OPENROUTER_API_KEY`             | secret | openrouter.ai/settings/keys         |
 | `exa`        | `EXA_API_KEY`                    | secret | dashboard.exa.ai/api-keys           |
+| `bifrost`    | `BIFROST_API_KEY`                | secret | a virtual key from your Bifrost     |
 
-`exa` is a service the tools call, not a model provider.
+`exa` is a service the tools call, not a model provider. `bifrost` is a
+gateway: see below.
+
+### Gateway mode - every model through Bifrost
+
+```
+zen key add bifrost --url https://bifrost.example.com   # the virtual key, prompted
+zen key mode bifrost                                   # from now on, every run
+zen key mode direct                                    # back to vendor keys
+```
+
+In `bifrost` mode a run exports `BIFROST_API_KEY` and `BIFROST_BASE_URL` and
+**withholds every vendor key**. The runtime then sends every model and every
+embedding through the gateway, each in its own vendor's protocol, and
+`agents.yaml` does not change: `vertex:gemini-3.5-flash` reaches
+`<url>/genai` as `vertex/gemini-3.5-flash`, `anthropic:*` reaches
+`<url>/anthropic`, `openai:*` and `openrouter:*` reach `<url>/openai`.
+Declared providers are rerouted too. `zen check` then reports
+`BIFROST_API_KEY`, not the vendor variables, as the credential in use.
+
+The switch is `BIFROST_BASE_URL` itself, so exporting it in a shell or a `.env`
+turns gateway mode on without the keyring. In this mode `zen models` lists only
+what the gateway serves - see `models.md`. The full guide is
+[docs/gateway.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/gateway.md).
 
 ### Vertex takes either shape
 

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

@@ -1,7 +1,7 @@
 # Models - `zen models`
 
 ```
-zen models <providers|ls|search|show|test|pick|browse> [ref] [options]
+zen models <providers|ls|search|show|test|browse> [ref] [options]
 ```
 
 Alias: `model`.
@@ -20,17 +20,14 @@ but a credential.
 | `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          |
 | `zen models browse`         | Interactive TUI for a person; needs a terminal         |
 
 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`.
-
 `browse` is for a person at a terminal and refuses without one (exit 2). An
-agent wants `ls --json`, `search` or `pick` instead.
+agent wants `ls --json` or `search` instead.
 
 ## Where the lists come from
 
@@ -43,6 +40,19 @@ it was - `--json` carries `source` per model and `origin` per provider.
 
 `zen models` on its own does **not** go to the network. `ls` and `search` do.
 
+### In gateway mode
+
+After `zen key mode bifrost`, every listing is **what the gateway serves**,
+not what the vendors do: one `GET <url>/v1/models`, split by its
+`<upstream>/<id>` names back into refs (`vertex/gemini-3.5-flash` lists as
+`vertex:gemini-3.5-flash`). Upstreams no zen provider names (bedrock, groq, ...)
+are left out, and there is no built-in fallback list. Each command says so on
+stderr with a `⇄ bifrost mode` line, `browse` carries the same badge on every
+screen, and `--json` adds a `gateway` field. `zen models` then does go to the
+network, since one request covers every provider; `test` asks through the
+gateway too. The full guide is
+[docs/gateway.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/gateway.md).
+
 ## Testing a model
 
 ```
@@ -77,30 +87,19 @@ $ 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
 ```
 
-Two ways out. Run the `gcloud` line, or take a different model:
+Two ways out. Run the `gcloud` line, or take a different model: list what the
+account serves, test the one you want, and put its ref where the old one was.
 
 ```
-$ zen models pick --embedding
-openai:text-embedding-3-small
+$ zen models ls --embeddings
+$ zen models test openai:text-embedding-3-small
+openai:text-embedding-3-small  answers 412ms  1536 dims
 ```
 
-`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.
+Test one model, not the whole list - each test is a billable call.
 
 ## What it will not do