@zenera/cli 1.1.15 → 1.1.17

package/templates/editor/.github/prompts/update-spec-from-feedback.prompt.md

@@ -0,0 +1,142 @@
+---
+description: Fold the answers left in SPECIFICATION-FEEDBACK.md back into SPECIFICATION.md, and mark each answered question as answered.
+---
+
+`SPECIFICATION-FEEDBACK.md` is a questionnaire. Each question carries two to
+four written-out answers, each with a `[ ]` box in its heading, and the reader
+answers by **marking one box `[x]`, deleting the answers they do not want, or
+both**. Your job is to take the answer they chose under each question, put its
+text into `SPECIFICATION.md` where it says it goes, and mark the question
+answered.
+
+You change two files and no others: `SPECIFICATION.md` and
+`SPECIFICATION-FEEDBACK.md`. You implement nothing - not a prompt, not a skill,
+not `agents.yaml`. Making the project match the specification is
+`/sync-with-spec`, which runs after this.
+
+## 1. Read both files before editing either
+
+Read `SPECIFICATION-FEEDBACK.md` end to end, then `SPECIFICATION.md` end to end,
+and only then edit. The second read is what tells you whether an answer's text
+still fits where it is going.
+
+If there is no `SPECIFICATION-FEEDBACK.md`, say so in the chat and stop - there
+is nothing to fold in.
+
+## 2. Decide the state of every question
+
+Go through the questions in order and sort each into one of these, by what is
+left under it. Say in the chat how many fell into each before you edit anything.
+
+**Answered** - apply it:
+
+- exactly one answer has its box marked `[x]`, whatever else is still there
+- exactly one `####` answer is left, box marked or not
+- the reader wrote prose of their own in place of the answers, or edited the
+  answer they kept - then apply what they wrote, word for word
+
+**Open** - leave it exactly as it is:
+
+- two or more answers are left and none is marked
+- two or more boxes are marked `[x]` - that is not a choice, and the chat report
+  is where you say so
+
+**Rejected** - leave it, and ask in the chat:
+
+- no answers at all are left under the question
+
+**Done** - leave it alone:
+
+- it is already under `✅`
+
+A question with every answer deleted is the reader saying none of them fit.
+**Do not invent a fifth.** Say in the chat which question it was and ask what
+would fit; if they tell you, write their words in under the question as the
+answer and apply it in this same pass.
+
+A question with two or more answers still standing and no box marked is **not
+answered**. Never choose between them, never pick the `_(built)_` one because it
+is already true, and never break a tie by reading the implementation.
+
+## 3. Put the text into `SPECIFICATION.md`
+
+For each answered question, take the fenced block under its surviving answer and
+put it where the line above the block says it goes.
+
+- **The line number is a hint, not an address.** Every paste moves every line
+  below it, and the reader has been editing too. Anchor on the text quoted under
+  **Where it comes from**; if that text is gone, use the section it names. If
+  neither is there any more, do not guess: leave the question open and report it
+  as not applied, with what you looked for.
+- **Paste it verbatim.** Do not reword it, do not improve it, do not reflow it
+  to your own idea of the line width. The block was written in the
+  specification's voice for exactly this.
+- **A `<placeholder>` is filled in only with a value the reader supplied** - in
+  the block, in prose next to it, or in the chat. An unfilled placeholder means
+  the question is not answered yet; leave it open and say so.
+- **Keep the document consistent around the paste.** Heading level, list style,
+  tense and the words the specification already uses for things. If the new text
+  makes a neighbouring sentence false, or contradicts another section, fix that
+  too - and report each such edit on its own line, because it is a change no
+  answer asked for.
+- Work one question at a time, top to bottom, and re-read the file between
+  edits rather than trusting the line numbers you read at the start.
+
+Nothing outside `SPECIFICATION.md` changes here. If an answer's text implies an
+agent, a tool grant, a script or a skill, that is the next `/sync-with-spec`
+pass's work, and saying so is all you do about it.
+
+## 4. Mark the question answered
+
+Move the whole `###` block of each answered question to the end of the file,
+under:
+
+```markdown
+## ✅ Answered - folded into the specification
+```
+
+Keep its number and its original emoji, so a link to it still resolves and the
+number is never reused. Replace everything under the heading with, in this
+order:
+
+- **Answered** - the chosen answer's line, verbatim, without its `[ ]` box, or
+  the reader's own words where they wrote their own.
+- **In the specification** - a link to the line it now occupies,
+  `[SPECIFICATION.md#L66](SPECIFICATION.md#L66)`, and the new text quoted as a
+  blockquote.
+- **Still to implement** - one line saying what has to change in the project for
+  the specification to be true again, or `Nothing - the project already does
+this.`
+
+That last line is what the next `/sync-with-spec` works from, so write it as
+work, not as a summary.
+
+Then bring the top of the file back into step: the opening paragraph's count of
+open questions, and the contents list - an answered line keeps its link and
+shows the answer that won in place of what was built. Drop a heading that has no
+questions left under it, and add no markdown tables to this file.
+
+## 5. You are the typist, not the reader
+
+Do not answer a question yourself, do not soften a chosen answer because you
+would have chosen another, and do not add a requirement nobody asked for. An
+answer you think is wrong is still the answer; say why in the chat and leave the
+text alone.
+
+Do not run `zen check`, `scripts/_setup.sh` or anything under `.spec-sync/`. The
+baseline moves at the end of a `/sync-with-spec` pass and nowhere else -
+committing it here would record a specification as applied that nothing has
+implemented yet.
+
+## 6. Report
+
+In the chat:
+
+- each question you answered, and which answer won
+- every line of `SPECIFICATION.md` that changed, and what it says now
+- every edit you made that no answer asked for, and what made it necessary
+- what is still open, split into: more than one answer left, more than one box
+  marked, every answer rejected, and could not be applied because the place it
+  names is gone
+- then, in one line: send `/sync-with-spec` to make the project match the
+  specification you have just changed.

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

@@ -1,6 +1,6 @@
 ---
 name: zen-cli
-description: How to drive this project from the terminal with `zen` — running it, validating it, credentials, the sandbox, run reports, and the `faker` and `rag` modules.
+description: How to drive this project from the terminal with `zen` - running it, validating it, credentials, the sandbox, run reports, and the `faker` and `rag` modules.
 ---
 
 # The `zen` command line
@@ -36,7 +36,7 @@ zen rag      docs <index|search|list|grep|show|stats> [path...]
 ## Read the reference before answering
 
 The full reference lives next to this file, one document per part of the command
-line. **Read the one that covers the question before answering it** — do not
+line. **Read the one that covers the question before answering it** - do not
 guess a flag, and do not read them all.
 
 | The question is about                                               | Read                                    |
@@ -50,8 +50,8 @@ guess a flag, and do not read them all.
 | 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)   |
 | What the agents remember, why something was recalled, forgetting    | [memory.md](./references/memory.md)     |
-| `zen faker` — a mock API from an OpenAPI/Swagger document           | [faker.md](./references/faker.md)       |
-| `zen rag` — searching an API description, or a pile of markdown     | [rag.md](./references/rag.md)           |
+| `zen faker` - a mock API from an OpenAPI/Swagger document           | [faker.md](./references/faker.md)       |
+| `zen rag` - searching an API description, or a pile of markdown     | [rag.md](./references/rag.md)           |
 
 ## The short version
 
@@ -67,6 +67,62 @@ zen models test <ref>                 whether one model actually answers
 zen models pick --embedding           the first embedder that does, on stdout
 ```
 
+## Searching documents without help
+
+Use `zen rag docs` for a directory of Markdown or text, and put the index path
+in `-d <index-dir>` when it is not beside the working directory. These commands
+are enough to discover the corpus and retrieve evidence; do not spend a turn on
+`--help` first:
+
+```sh
+zen rag docs list files -d <index-dir>
+zen rag docs list sections -d <index-dir> --file "<path-pattern>"
+zen rag docs search -d <index-dir> "<question in natural language>"
+zen rag docs search -d <index-dir> --file "<path-pattern>" --section "<heading>" "<question>"
+zen rag docs grep -d <index-dir> "<exact string>" --file "<path-pattern>"
+zen rag docs show -d <index-dir> "<file>" --section "<heading>"
+```
+
+Start with one ordinary hybrid question. It is the best default for concepts and
+open questions. Search returns candidates, not proof: read the quoted lines,
+then use `show` or `grep` before claiming a fact is present or absent.
+
+When the first answer is from the wrong product area, version, file, or heading,
+ask the same question again with `--file` and then `--section`. A bare `--file`
+value is a substring; `*` and `?` make it a glob. Use `--kind table` or
+`--kind table_row` for limits and matrices, `--mode text` for a known exact
+phrase, and `--exclude-id <id>` to continue past an already-read passage.
+
+`--file` is the primary scope control: repeat it to admit several document
+families, and use `--exclude-file` to remove a noisy family. Both are resolved
+before ranking, so a result cannot come from an excluded document. `--section`
+then keeps only a matching heading and its nested headings within those files.
+For example, search two manual families but exclude archived releases:
+
+```sh
+zen rag docs search -d <index-dir> --file "manual-*/**" --file "guide-*/**" \
+	--exclude-file "*-archive/**" --section "Operations" "<question>"
+```
+
+Hybrid is not a vector reranker. It retrieves a candidate list from full-text
+search and another from vector similarity, then fuses their ranks. Full-text
+finds literal terms; vector search finds passages with the same meaning even
+when their wording differs. `--mode text` or `--mode vector` runs only one leg;
+ordinary hybrid runs both and is normally the right choice.
+
+Use `--text-query` with `--vector-query` only when one wording cannot serve both
+retrievers: a distinctive corpus term or command for the text leg, and the full
+question for the vector leg. For example:
+
+```sh
+zen rag docs search -d <index-dir> --text-query "exact identifier" \
+	--vector-query "what it means and how to use it"
+```
+
+This is not a general upgrade over hybrid search. Generic product names and
+common nouns make weak text legs that can displace better semantic results. The
+two flags replace positional text and `--mode`; give neither alongside them.
+
 Run `zen check` after any edit to `agents.yaml`, a prompt or a skill: it reads
 the project the way a run does, reports everything wrong at once, and calls no
 model. It is the cheapest possible test.
@@ -75,7 +131,7 @@ When behaviour is wrong and the prompt looks right, open the run report. It
 shows what the model was actually given, which is rarely what you assumed.
 
 Flags always beat the file: the repository states intent, the invocation
-overrides it. Failure messages name the offending key or file — a load error
-names the exact path, as in `agents.yaml: agents[1].skills.discovery — …` — so
+overrides it. Failure messages name the offending key or file - a load error
+names the exact path, as in `agents.yaml: agents[1].skills.discovery - …` - so
 read it rather than guessing. The loader is strict on purpose, and an unknown
 key is an error rather than a value quietly ignored.

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

@@ -1,4 +1,4 @@
-# Validating — `zen check`
+# Validating - `zen check`
 
 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.
@@ -31,15 +31,18 @@ checked too. A word that is neither is a usage error (exit 2), not a report.
 
 - `agents.yaml` parses and satisfies the schema, with unknown keys reported
   rather than ignored.
-- Every file the configuration names is on disk and non-empty: `INSTRUCTIONS.md`,
-  each agent's prompt, each skill's `SKILL.md`, each asset glob.
+- Every file the configuration names is on disk and non-empty: the house rules
+  under `agents/`, each agent's prompt, each skill's `SKILL.md`, each asset glob.
+  A root `INSTRUCTIONS.md` is still read, and reported as something to move to
+  `agents/instructions.md`.
 - Hand-offs and forks name agents that exist, and no agent hands off to itself.
 - Tool selectors resolve against the real tool set, including a skill's own
   `tools:` frontmatter.
 - Skills bind to a catalog that holds them, and every declared skill is
   reachable from some agent.
 - Every declared model and embedding resolves to a provider, and that provider
-  has a credential on this machine.
+  has a credential on this machine. The project's `.env` is read first, exactly
+  as `zen run` reads it, so the verdict is the one a run would reach.
 - 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
@@ -47,7 +50,7 @@ checked too. A word that is neither is a usage error (exit 2), not a report.
   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
+  exist, and - unless `--no-sandbox` - the image **builds** and one command runs
   in it, against a temporary directory rather than your workspace. No container
   engine at all is a warning, not an error.
 
@@ -71,7 +74,7 @@ embedding.refused     embedding.unreachable  embedding.unusable
 credential.*          service.credential
 ```
 
-The report goes to **stdout** — it is the answer. `--json` gives the same
+The report goes to **stdout** - it is the answer. `--json` gives the same
 findings as data.
 
 Exit codes: `0` nothing wrong, `3` at least one error, or with `--strict` at

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

@@ -1,10 +1,10 @@
-# Mock APIs — `zen faker`
+# Mock APIs - `zen faker`
 
 ```
 zen faker <serve|build|cache> [spec...]
 ```
 
-Alias: `zen mock`. Provided by `@zenera/faker` — `npm i -g @zenera/faker` if
+Alias: `zen mock`. Provided by `@zenera/faker` - `npm i -g @zenera/faker` if
 `zen faker` says it is not installed.
 
 Serves a mock API from one or more OpenAPI/Swagger documents. For each
@@ -39,16 +39,16 @@ front and exits non-zero, with a table, if any could not be written.
 | `--model <ref>`     | project default       | Which model writes the generators               |
 | `--image <ref>`     | a baked image         | Skip the baked image and use this one           |
 | `--cache <dir>`     | `~/.zenera/neo/faker` | Where generators live                           |
-| `--seed <n>`        | —                     | Answer the same request the same way every time |
+| `--seed <n>`        | -                     | Answer the same request the same way every time |
 | `--attempts <n>`    | `3`                   | Tries per generator before giving up            |
 | `--concurrency <n>` | `4`                   | Generators written at once                      |
 | `--timeout <s>`     | `30`                  | Seconds one generator may take                  |
 | `--max-body <n>`    | 1 MB                  | Largest request body accepted, in bytes         |
-| `--rebuild`         | —                     | Ignore what is cached and write it again        |
-| `--no-cache`        | —                     | Do not record what is written                   |
-| `--quiet`           | —                     | No narration                                    |
+| `--rebuild`         | -                     | Ignore what is cached and write it again        |
+| `--no-cache`        | -                     | Do not record what is written                   |
+| `--quiet`           | -                     | No narration                                    |
 
-Credentials come from the `zen` keyring — see [keys.md](keys.md).
+Credentials come from the `zen` keyring - see [keys.md](keys.md).
 
 ## Serving
 
@@ -66,19 +66,19 @@ Response headers:
 | Header              | Meaning                                               |
 | ------------------- | ----------------------------------------------------- |
 | `x-faker-operation` | The `operationId` that answered                       |
-| `x-faker-cache`     | `hit` or `miss` — whether this call cost a model turn |
+| `x-faker-cache`     | `hit` or `miss` - whether this call cost a model turn |
 
 Incoming headers are filtered: `authorization`, `cookie` and anything matching
 `key|token|secret|password|credential` never reach a generator.
 
 `--seed` makes each request's seed a hash of the seed, the operation and the
-parameters, so the same request answers identically across restarts — which is
+parameters, so the same request answers identically across restarts - which is
 what makes a mock usable in a test.
 
 ## What "correct" means here
 
 A generator is judged on two synthetic probes: the body validates against the
-response schema, **and** it obeys the **echo rule** — a value given in the path
+response schema, **and** it obeys the **echo rule** - a value given in the path
 comes back in the answer. `GET /users/12324` must return `user_id: 12324`. A body
 can validate perfectly and still be about the wrong entity, which is exactly the
 mock that wastes an afternoon.
@@ -87,16 +87,16 @@ Query parameters are deliberately not enforced: `?source=realtime`, `?page_size`
 and `?cursor` are controls, and their names collide with unrelated response
 fields.
 
-Probes are synthetic on purpose — real request bodies never reach a prompt.
+Probes are synthetic on purpose - real request bodies never reach a prompt.
 
 ## The cache
 
 Generators live in the machine's shared cache, `~/.zenera/neo/cache/faker-generator/`,
-keyed by the operation's shape — so the same spec served from two directories is
+keyed by the operation's shape - so the same spec served from two directories is
 written once, and a spec edit produces a new key rather than a stale answer. A
 generator that a model gave up on is remembered for the life of the process, so
-a hopeless operation is not re-asked on every request; a _transient_ failure — a
-429, a dropped socket — is not, because it is about this minute rather than this
+a hopeless operation is not re-asked on every request; a _transient_ failure - a
+429, a dropped socket - is not, because it is about this minute rather than this
 operation.
 
 `~/.zenera/neo/faker/` is the container's workspace, and scratch: a cache hit is

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

@@ -48,7 +48,7 @@ Progress, banners, warnings and the spinner go to stderr. So
 
 `--json` applies to every command and prints one machine-readable document on
 stdout in place of the rendered form. Under `--json` nothing is asked
-interactively — the questions a run would ask are taken as answered.
+interactively - the questions a run would ask are taken as answered.
 
 The banner is drawn only when stderr is a terminal, so a piped invocation never
 sees it.
@@ -60,13 +60,13 @@ sees it.
 | 0    | ok          | It worked                                                  |
 | 1    | failed      | It ran and did not succeed                                 |
 | 2    | usage       | The command line was wrong                                 |
-| 3    | invalid     | The project is not valid — bad `agents.yaml`, missing file |
+| 3    | invalid     | The project is not valid - bad `agents.yaml`, missing file |
 | 4    | credentials | No usable credential for what was asked                    |
 | 5    | sandbox     | No container engine, or the image could not be prepared    |
 
 A wrong invocation and a wrong answer are deliberately not the same code, which
 is what a script needs. Failure messages name the offending key or file; a load
-error names the exact path, as in `agents.yaml: agents[1].skills.discovery — …`.
+error names the exact path, as in `agents.yaml: agents[1].skills.discovery - …`.
 Read it rather than guessing: the loader is strict on purpose and an unknown key
 is an error, not a value quietly ignored.
 
@@ -74,7 +74,7 @@ is an error, not a value quietly ignored.
 
 Most commands operate on a project directory, resolved in this order:
 
-1. `--project <name|dir>` — a registry name or a path.
+1. `--project <name|dir>` - a registry name or a path.
 2. The working directory, if it is a project (or is inside one).
 3. For `zen run`, a bare first word that names a registered project.
 
@@ -92,7 +92,7 @@ unregistered directory can still be validated.
 | `ZENERA_DEBUG`     | Print a stack trace when something unexpected escapes |
 | `VISUAL`, `EDITOR` | Consulted by `zen open` after `ZENERA_EDITOR`         |
 | `COLORFGBG`        | Read as a hint when the palette is being detected     |
-| Provider keys      | `OPENAI_API_KEY` and friends — see [keys.md](keys.md) |
+| Provider keys      | `OPENAI_API_KEY` and friends - see [keys.md](keys.md) |
 
 A real environment variable always beats the keyring.
 
@@ -107,12 +107,14 @@ A real environment variable always beats the keyring.
 
 <project>/
     zenera.json           { version, name }
-    INSTRUCTIONS.md       house rules, prepended to every agent's prompt
     agents.yaml           the configuration
-    agents/prompts/       one .md per agent
-    agents/skills/        one directory per skill, each with SKILL.md
+    agents/
+        instructions.md   house rules, prepended to every agent's prompt
+        *-instructions.md more house rules, in filename order
+        prompts/          one .md per agent
+        skills/           one directory per skill, each with SKILL.md
     sandbox/Dockerfile    the image commands run in, when the project builds one
-    sessions/             run state, memory, blobs, reports — never committed
+    sessions/             run state, memory, blobs, reports - never committed
 ```
 
 Credential files are refused if anyone but the owner can read them, the way

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

@@ -1,4 +1,4 @@
-# Reports — `zen inspect`
+# Reports - `zen inspect`
 
 ```
 zen inspect [run] [--session <id>] [--open] [--rebuild] [--serve [port]]
@@ -29,7 +29,7 @@ was assembled differently from how it looks in the repository: a skill that did
 not activate, a hand-off that fired early, a tool that was withheld, an asset
 that was not attached.
 
-The report also draws the architecture — agents, their tools, their hand-offs —
+The report also draws the architecture - agents, their tools, their hand-offs -
 and falls back to reconstructing the wiring from the trajectory when the run
 did not record it.
 
@@ -52,7 +52,7 @@ resolves them back.
 
 ## What it prints
 
-The path to `report.html` on stdout — it is the answer, so it pipes. `--json`
+The path to `report.html` on stdout - it is the answer, so it pipes. `--json`
 gives `{ session, run, report }` instead. A report that is missing is built
 before either; `--rebuild` builds one that already exists again, which is always
 safe because the report is derived and `state.json` is the truth. That is also

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

@@ -1,4 +1,4 @@
-# Credentials — `zen key`
+# Credentials - `zen key`
 
 ```
 zen key <ls|add|use|check|rm|show|env> [ref] [options]
@@ -85,7 +85,7 @@ behind, marked `~` and named for the variable rather than for a key:
 ~ vertex/adc               …/application_default_credentials.json
 ```
 
-These can be listed and checked, not chosen or forgotten — there is nothing to
+These can be listed and checked, not chosen or forgotten - there is nothing to
 choose between, and nothing of ours to remove. Unset the variable, or
 `gcloud auth application-default revoke`.
 
@@ -94,15 +94,15 @@ choose between, and nothing of ours to remove. Unset the variable, or
 `zen key check` and `zen key ls --check` do one round trip per key and record
 the verdict:
 
-- **live** — authenticated. A rate-limited answer counts as live, because it
+- **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
+- **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
+  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;
+- **unknown** - the provider could not be asked. Says nothing about the key;
   usually the network.
 
 `zen init` uses the same probe to pick which provider to scaffold with, so a
@@ -110,9 +110,9 @@ project is not built around a revoked key.
 
 ## When a run says there is no credential
 
-The frame does **not** materialise the keyring for you — each command that needs
+The frame does **not** materialise the keyring for you - each command that needs
 a credential opens the store itself. If `zen key ls` shows a key as live and a
-command still says `provider "openai": no api key — set OPENAI_API_KEY`, the
+command still says `provider "openai": no api key - set OPENAI_API_KEY`, the
 credential is fine and the command is at fault. Everything that runs a model
 (`run`, `check`, `models`, `faker`, `rag`) already does this.
 

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

@@ -1,4 +1,4 @@
-# Memory — `zen memory`
+# Memory - `zen memory`
 
 ```
 zen memory [stats|ls|show|export|forget] [args] [options]
@@ -45,7 +45,7 @@ is masked, ranked and truncated as well, so what an agent gets is never the
 whole picture.
 
 This command ignores all of that. When the mask is the thing that is wrong, the
-part that was hidden is exactly the part you need — and this is a person at a
+part that was hidden is exactly the part you need - and this is a person at a
 terminal in the project directory, not an agent inside a run.
 
 It also contacts no model. The store is opened without an embedder, so
@@ -60,12 +60,12 @@ zen memory export --open
 
 One self-contained HTML file, three panes:
 
-- **left** — every node, with a search box and filters for kind, audience,
+- **left** - every node, with a search box and filters for kind, audience,
   files, superseded and unlinked
-- **middle** — the graph as a Mermaid diagram, coloured by kind, with pan,
+- **middle** - the graph as a Mermaid diagram, coloured by kind, with pan,
   zoom, and a hop-focus selector for following one node's neighbourhood
-- **right** — whatever you clicked, in full: the text, the metadata, the links,
-  and **the remembered file's actual content** — rendered as an image when it is
+- **right** - whatever you clicked, in full: the text, the metadata, the links,
+  and **the remembered file's actual content** - rendered as an image when it is
   one, and as text otherwise
 
 Clicking a node in either the list or the diagram selects it in both. Above 300
@@ -83,15 +83,15 @@ zen memory forget 01M1YPN0C8QRQS5BCZ03ABQ1G0
 ```
 
 Asks first, unless `--yes`, and refuses outright when there is no terminal to
-ask at. A node, its vector row and its remembered file bytes go together —
+ask at. A node, its vector row and its remembered file bytes go together -
 there is one implementation of that, shared with the agent-facing tool, so the
 three cannot drift apart.
 
 **Forgetting is rarely the right correction.** The agents' own way to fix a
 wrong memory is to commit the corrected node and supersede the old one, which
 keeps the record of having been wrong. `zen memory ls --stale` lists what has
-been superseded that way. Use `forget` for what should never have been stored —
-a secret, a mistake, a pile of noise — not for what merely became untrue.
+been superseded that way. Use `forget` for what should never have been stored -
+a secret, a mistake, a pile of noise - not for what merely became untrue.
 
 ## Reading `stats`
 
@@ -100,8 +100,8 @@ nodes       7
 edges       6
 superseded  1
 files       1 · 640 B
-embedding   none — recall falls back to term overlap
-vectors     —
+embedding   none - recall falls back to term overlap
+vectors     -
 ```
 
 `embedding none` is worth noticing: without an embedder, recall matches on

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

@@ -1,4 +1,4 @@
-# Models — `zen models`
+# Models - `zen models`
 
 ```
 zen models <providers|ls|search|show|test|pick> [ref] [options]
@@ -6,8 +6,8 @@ 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
+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
@@ -33,7 +33,7 @@ Filters, on `ls` and `search`: `--chat`, `--embeddings`, `--images`, `--audio`,
 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.
+it was - `--json` carries `source` per model and `origin` per provider.
 
 `--refresh` bypasses the cache. It is the only thing that does.
 
@@ -48,7 +48,7 @@ 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
+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.
 
@@ -84,7 +84,7 @@ 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
+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
@@ -92,7 +92,7 @@ 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
+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.
 
@@ -101,7 +101,7 @@ 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`.
+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