@zenera/cli 1.1.14 → 1.1.16

package/templates/editor/.github/prompts/new-agent.prompt.md

@@ -14,8 +14,8 @@ true, and you should say which:
 - its instructions **contradict** an existing agent's rather than extend them
 - it is a **parallel branch** target for a `fork:`
 
-If none holds, propose the smaller change instead — a skill, a prompt line, a
-tool grant — and stop. Adding an agent to solve a prompt problem is the failure
+If none holds, propose the smaller change instead - a skill, a prompt line, a
+tool grant - and stop. Adding an agent to solve a prompt problem is the failure
 mode this project cares most about.
 
 If it is warranted:
@@ -23,18 +23,18 @@ If it is warranted:
 1. Pick a name matching `^[a-z0-9]+(?:[-_][a-z0-9]+)*$`. It reaches the model as
    `transfer_to_<name>`, so the name is part of the routing surface.
 2. Write `agents/prompts/<name>.md`: one sentence of identity, a short procedure
-   or three to five rules, then what it must **not** do — especially the
+   or three to five rules, then what it must **not** do - especially the
    neighbouring agent's job. Second person, imperative, failure paths stated.
    No frontmatter, no meta-talk about the runtime.
-3. Add the `agents.yaml` entry. `description:` is written **for the model** — it
+3. Add the `agents.yaml` entry. `description:` is written **for the model** - it
    is the whole of what a sibling sees when deciding to hand off. Grant the
    narrowest `tools:` the job needs.
 4. Wire the return edge. A handoff does not come back on its own, so every
-   `A → B` needs a path from B back to A — directly, or through another agent.
+   `A → B` needs a path from B back to A - directly, or through another agent.
    `zen check` warns on an edge that has none. If what this agent really wants
    is an _answer_ rather than to give up the conversation, declare `fork:`
    instead: a branch returns by itself.
-5. Add a one-line comment above the entry saying why this agent exists — its
+5. Add a one-line comment above the entry saying why this agent exists - its
    job or its tier, not what the keys mean.
 
 Then run `zen check` and report what it said. If it fails, fix the file it

package/templates/editor/.github/prompts/new-skill.prompt.md

@@ -3,29 +3,29 @@ mode: agent
 description: Add a skill under agents/skills, with a description that routes.
 ---
 
-Add a skill to this project. A skill is curated instruction content — and
-optionally tools — loaded on demand instead of sitting in every system prompt.
+Add a skill to this project. A skill is curated instruction content - and
+optionally tools - loaded on demand instead of sitting in every system prompt.
 Reach for one whenever a rule applies only sometimes, or holds a fact that will
 change without the prompt changing.
 
 Ask what the skill must say and when it applies, if I have not already said.
 
 1. Create `agents/skills/<name>/SKILL.md`. That is the only skill layout there
-   is — a bare `agents/skills/<name>.md` fails `zen check` — and the folder is
+   is - a bare `agents/skills/<name>.md` fails `zen check` - and the folder is
    what lets the skill carry companions later: a rate table, an example letter,
    a schema, a script.
 2. Write the `description`. This is the routing key and the only thing the model
    sees before deciding to load the skill, so write it as **the condition under
    which the skill is needed**, not as a title. `Water policy` is a title;
-   `Escape of water from plumbing and tanks — and the freezing exclusion` is a
+   `Escape of water from plumbing and tanks - and the freezing exclusion` is a
    condition. If two skills could both match a case, sharpen both until they
    cannot.
 3. Write the body as instructions the model can act on: thresholds, exact
    wording, the boundaries of the rule, and what to do when the case falls
-   outside it. Put the facts here rather than in a prompt — that is the point of
+   outside it. Put the facts here rather than in a prompt - that is the point of
    the file.
 4. Put anything the rule computes or looks up in a file beside `SKILL.md` and
-   name it from the body by its absolute path — `python
+   name it from the body by its absolute path - `python
 /skills/<name>/scripts/calculate.py <id>`, not `scripts/calculate.py`. The
    folder is mounted read-only at `/skills/<name>/`, so the script writes
    nothing there; the agent needs `sandbox:*` to run it, and the interpreter has
@@ -37,7 +37,7 @@ Ask what the skill must say and when it applies, if I have not already said.
 6. Leave `name` out unless it must differ from the folder name, and leave
    `version`/`tags` out unless something uses them.
 
-Do not `preload:` it unless every case genuinely needs it — a preloaded skill is
+Do not `preload:` it unless every case genuinely needs it - a preloaded skill is
 a longer prompt, paid for on every call. Bind it under `agents[].skills.allow`
 if the agent's catalog is restricted.
 

package/templates/editor/.github/prompts/review-project.prompt.md

@@ -28,7 +28,7 @@ Work the checklist in §9 of the copilot instructions. In particular:
 - **Routing.** Handoff targets have descriptions written for the model. No
   ping-pong edges. No router that answers.
 - **Models.** Each agent on the cheapest tier that is right, not the safest.
-- **Cache.** Nothing volatile — dates, ids, counts — in the stable prefix.
+- **Cache.** Nothing volatile - dates, ids, counts - in the stable prefix.
 - **Secrets.** No key inlined anywhere; `.env` ignored, `sessions/` ignored.
 
 Report as a list of findings, each naming the file and the line, ordered by how

package/templates/editor/.github/prompts/sync-with-spec.prompt.md

@@ -3,7 +3,7 @@ description: Bring the project into compliance with SPECIFICATION.md, and record
 ---
 
 Make this project match `SPECIFICATION.md`. The specification is the intent;
-the files are the implementation. Where they disagree, the specification wins —
+the files are the implementation. Where they disagree, the specification wins -
 except where it is ambiguous, contradictory or impossible, which is what
 `SPECIFICATION-FEEDBACK.md` is for.
 
@@ -11,14 +11,14 @@ except where it is ambiguous, contradictory or impossible, which is what
 
 Read, in this order, and do not edit until all of it is read:
 
-1. `SPECIFICATION.md` — what the system is meant to be.
-2. `agents.yaml` — providers, models, embeddings, agents, tools, handoffs,
+1. `SPECIFICATION.md` - what the system is meant to be.
+2. `agents.yaml` - providers, models, embeddings, agents, tools, handoffs,
    skills, sandbox.
 3. `INSTRUCTIONS.md` and every file under `agents/prompts/`.
 4. Every `agents/skills/*/SKILL.md`, plus what each skill folder ships.
 5. `assets/`, `sandbox/Dockerfile` and every script under `scripts/`, starting
    with `scripts/_setup.sh`.
-6. `SPECIFICATION-FEEDBACK.md`, if it exists — do not re-raise something already
+6. `SPECIFICATION-FEEDBACK.md`, if it exists - do not re-raise something already
    open there.
 
 Run `zen check` first and record what it said. A project that does not load is
@@ -29,11 +29,11 @@ the first thing to fix.
 Produce a difference list before touching a file. For every item in the
 specification, decide which of these it is:
 
-- **present and correct** — leave it alone
-- **missing** — the specification asks for it and nothing implements it
-- **divergent** — implemented, but not as specified
-- **extra** — implemented, and the specification does not ask for it
-- **unclear** — the specification does not say enough to implement it
+- **present and correct** - leave it alone
+- **missing** - the specification asks for it and nothing implements it
+- **divergent** - implemented, but not as specified
+- **extra** - implemented, and the specification does not ask for it
+- **unclear** - the specification does not say enough to implement it
 
 Check at least: the model and embedding ids and which agent uses which; that
 every agent named in the specification exists with that job and no second job;
@@ -43,18 +43,18 @@ specification implies; and every setup step, index or asset it depends on.
 Then build the difference the other way, because the list above can only find
 what the specification asked for and nothing implements. Read `INSTRUCTIONS.md`,
 each `agents/prompts/*.md` and each `SKILL.md` **line by line**, and for every
-line name the specification item it serves. A line serving none is an **extra** —
+line name the specification item it serves. A line serving none is an **extra** -
 the category covers a single sentence in a prompt, not only a whole file. Three
 things to look for while reading, none of which the forward pass can see:
 
 - **A line that contradicts another file.** One prompt against another, a prompt
-  against `INSTRUCTIONS.md`, or a prompt against `agents.yaml` — an instruction
+  against `INSTRUCTIONS.md`, or a prompt against `agents.yaml` - an instruction
   to use a tool the agent does not hold, to hand to an agent that is not in its
   `handoffs:`, or to load a skill outside its `allow:`.
 - **A line that asks for something the system already supplies.** A question put
   to the user about a value that arrives from the environment, a file or an
   earlier step is unanswerable, and the answer would be discarded.
-- **A line the agent cannot carry out** — naming a path it cannot reach, a tool
+- **A line the agent cannot carry out** - naming a path it cannot reach, a tool
   it was not granted, or an agent it cannot transfer to.
 
 These are bugs whatever the specification says: fix them in place and report each
@@ -83,19 +83,19 @@ the model to compute or remember. Specifically:
 Never delete an **extra** without saying so. Report it, say why the
 specification does not cover it, and leave it unless I tell you to remove it.
 
-Do not invent a value the specification does not state — a model id, a limit, a
+Do not invent a value the specification does not state - a model id, a limit, a
 retry count, a file path. That is an entry in `SPECIFICATION-FEEDBACK.md`, not a
 guess.
 
 ## 4. Every setup step is a script
 
-Anything the project needs done before it can run — building an index, fetching
-a document, generating a file, warming the sandbox image — is a shell script,
+Anything the project needs done before it can run - building an index, fetching
+a document, generating a file, warming the sandbox image - is a shell script,
 not a paragraph of instructions for a human.
 
 - One step per file, under `scripts/`, named after the step:
   `scripts/build-schema-index.sh`, `scripts/fetch-api-docs.sh`.
-- `scripts/_setup.sh` is the **only** entry point — the leading underscore is
+- `scripts/_setup.sh` is the **only** entry point - the leading underscore is
   what separates the runner from the steps it runs. It runs the steps in the
   order they depend on each other and is the single command that initialises the
   project. `zen init` writes it; adding a step is adding `scripts/<name>.sh` and
@@ -114,7 +114,7 @@ not a paragraph of instructions for a human.
 - **It must be watchable.** `scripts/_setup.sh` tees each step's output to
   `.tmp/logs/setup-<step>.log`, prints a heartbeat line while a long step runs,
   and finishes with one line per step: `ok`, `skipped`, or `failed`.
-- **Everything transient goes under `.tmp/`** — logs, scratch files, downloads,
+- **Everything transient goes under `.tmp/`** - logs, scratch files, downloads,
   test output, and the temporary path a step writes to before moving its
   artefact into place. Nothing else in the tree is a scratch directory, and
   `.tmp/` is git-ignored: add it to `.gitignore` if it is not there already.
@@ -138,26 +138,26 @@ The file is scanned before it is read, so keep the emoji on every heading:
 ```markdown
 # Feedback on SPECIFICATION.md
 
-## 🛑 Blocking — cannot implement without an answer
+## 🛑 Blocking - cannot implement without an answer
 
-## ❓ Ambiguous — implemented one way, confirm the choice
+## ❓ Ambiguous - implemented one way, confirm the choice
 
 ## ⚡ Contradictions
 
 ## ✏️ Errors and typos
 
-## ➕ Out of scope — implemented but unspecified
+## ➕ Out of scope - implemented but unspecified
 ```
 
 Each entry is one bullet, opening with the emoji of the heading it sits under,
 then four parts in this order:
 
 - **What the specification says**, quoted, with the section it is in.
-- **Why it cannot be implemented as written** — the specific gap, not "unclear".
-- **What was done in the meantime**, or "nothing — blocked".
+- **Why it cannot be implemented as written** - the specific gap, not "unclear".
+- **What was done in the meantime**, or "nothing - blocked".
 - **The question**, phrased so a one-line answer unblocks it.
 
-Use no other emoji anywhere in the file — one per entry is what makes them
+Use no other emoji anywhere in the file - one per entry is what makes them
 scannable. Keep entries factual and short. Do not editorialise about the
 specification's quality, do not restate the runtime, and do not copy the whole
 section in.
@@ -169,7 +169,7 @@ this pass has actually resolved it, and say in the chat which ones you closed.
 After `zen check` passes, run `scripts/_setup.sh` yourself. A pass is not done
 until it has run to completion in this session.
 
-It is slow — an embedding index is minutes, not seconds — so start it in the
+It is slow - an embedding index is minutes, not seconds - so start it in the
 background and follow the logs instead of waiting blind:
 
 - Tail `.tmp/logs/setup-*.log` and check the output artefact is still growing.
@@ -182,7 +182,7 @@ background and follow the logs instead of waiting blind:
 - Do not kill a quiet step. Confirm the process is dead or the log and the
   output have both stopped growing before calling it stuck.
 - On failure, read that step's log, fix the cause, and run `scripts/_setup.sh`
-  again — re-running is the fix path, not a reset. If the same step fails twice
+  again - re-running is the fix path, not a reset. If the same step fails twice
   for the same reason, stop and raise it in `SPECIFICATION-FEEDBACK.md`.
 - Prove re-entrancy: once it has succeeded, run `scripts/_setup.sh` once more and
   check that every step reports `skipped` rather than rebuilding.
@@ -196,7 +196,7 @@ fail. Then report in the chat:
 
 - what changed, file by file, and which specification item each change closes
 - every prompt or skill line that served no specification item, and what became
-  of it — corrected, or reported and left alone
+  of it - corrected, or reported and left alone
 - the outcome of every `scripts/_setup.sh` step, and what each one produced
 - what is still open, with a pointer to its `SPECIFICATION-FEEDBACK.md` entry
 - anything you found that the specification does not cover at all

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.
@@ -47,7 +47,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 +71,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.
 
@@ -112,7 +112,7 @@ A real environment variable always beats the keyring.
     agents/prompts/       one .md per agent
     agents/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