@zenera/cli 1.1.15 → 1.1.17

package/README.md

@@ -1,7 +1,7 @@
 <div align="center">
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/andreyryabov/ZeneraNeo/main/docs/imgs/banner-neo-dark.svg">
-  <img src="https://raw.githubusercontent.com/andreyryabov/ZeneraNeo/main/docs/imgs/banner-neo-light.svg" alt="ZENERA NEO" width="720">
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/andreyryabov/ZeneraNeo/main/docs/imgs/banner-cli-dark.svg">
+  <img src="https://raw.githubusercontent.com/andreyryabov/ZeneraNeo/main/docs/imgs/banner-cli-light.svg" alt="ZENERA CLI" width="720">
 </picture>
 
 [![npm](https://img.shields.io/npm/v/@zenera/cli.svg)](https://www.npmjs.com/package/@zenera/cli)
@@ -12,23 +12,27 @@
 
 # @zenera/cli
 
-**`zen` — build specialist agents. Share them. Run them from the command line.**
+**`zen` - build specialist agents. Share them. Run them from the command line.**
 
-Not one general assistant that is passable at everything — a team built for the
+`@zenera/cli` is the command-line package in the
+[ZeneraNeo](https://github.com/andreyryabov/ZeneraNeo) toolkit. It creates,
+runs, tests and improves the specialized agent systems defined by a project.
+
+Not one general assistant that is passable at everything - a team built for the
 work you actually keep doing, under a name you can type:
 
 ```sh
-zen run accountant "Q3 — match the receipts drawer to the ledger, then update the return"
-zen run accountant "this MSA against our playbook — redlines, and what I must not sign"
-zen run analyst    "why churn doubled in the EU accounts — the exports are in this folder"
+zen run accountant "Q3 - match the receipts drawer to the ledger, then update the return"
+zen run accountant "this MSA against our playbook - redlines, and what I must not sign"
+zen run analyst    "why churn doubled in the EU accounts - the exports are in this folder"
 zen run analyst    "what changed in EU battery regulation this year, with sources"
-zen run devops     "this week's advisories — which of them actually reach our code"
-zen run devops     "the 03:12 outage — timeline, contributing factors, owners"
+zen run devops     "this week's advisories - which of them actually reach our code"
+zen run devops     "the 03:12 outage - timeline, contributing factors, owners"
 ```
 
 Three agents there, six things asked of them: an agent you have built is not a
 script with one job, it is a specialist you keep going back to. And it is work
-that comes back — every quarter, every sprint, every deal — which is exactly the
+that comes back - every quarter, every sprint, every deal - which is exactly the
 work nobody has shipped you a product for.
 
 Once the agent exists it is a command: it works on the files you are standing
@@ -37,25 +41,25 @@ records every token it spent doing it.
 
 Getting there is three beats:
 
-1. **Describe it.** You write `SPECIFICATION.md` — what the system is for,
+1. **Describe it.** You write `SPECIFICATION.md` - what the system is for,
    which specialists it needs, what each may reach for, what _done_ means. The
    rest of the folder is built to implement it.
 2. **Test it.** `zen check` validates the project and every file it names,
    `zen run` exercises it for real, `zen inspect` opens the record of what it
    actually did. When it comes out wrong you fix the specification, not the
    prompts, and go round again.
-3. **Share it.** It is a folder — commit it, review it in a pull request, send
+3. **Share it.** It is a folder - commit it, review it in a pull request, send
    it. One `zen init <dir>` on a project that arrived by clone registers it
    without touching a thing, and it is their command now too.
 
 > Part of [ZeneraNeo](https://github.com/andreyryabov/ZeneraNeo). This is an
-> open-source side project for experimentation and chore work — **not** the
+> open-source side project for experimentation and chore work - **not** the
 > official Zenera AI Platform. It carries no support or stability promises.
 
 ## What you build
 
 Half a page of specification turns into a system like one of these. Nothing here
-ships with the CLI — each is a folder somebody wrote, and could send you.
+ships with the CLI - each is a folder somebody wrote, and could send you.
 
 | Project        | The team inside it                                                                                                                                                                                                                                                                                                              |
 | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -63,37 +67,37 @@ ships with the CLI — each is a folder somebody wrote, and could send you.
 | **analyst**    | A planner that splits the question into branches; researchers that run in parallel over your files and the web; a statistician that writes and runs Python in the sandbox; an editor that joins it into one answer where every claim carries its source.                                                                        |
 | **devops**     | A gatherer that pulls advisories, logs, alerts and deploys into one picture; a tracer that works out whether a vulnerable path is reachable at all, or which change actually broke it; an engineer that plans the fix, applies it a step at a time, and stops the moment a check fails.                                         |
 
-Build one, commit it, and it runs the same on anyone else's machine — on
+Build one, commit it, and it runs the same on anyone else's machine - on
 whichever models they prefer, and without carrying your keys.
 
 ## What makes it different
 
-A coding agent with custom instructions can already play several roles, and a
-framework can already wire agents together. What neither gives you:
-
-- **A system that outlives the session.** Custom instructions and subagents live
-  in a chat that ends. Here the system is a directory — versioned, reviewable,
-  diffable, sendable. Improving it is a commit, not a paste.
-- **A specification that is enforced, not decorative.** `SPECIFICATION.md` is
-  the source; where it and the files disagree, it wins. `/sync-with-spec`
-  reconciles the two in both directions and `zen check` fails the project when
-  they drift — with a code, a location and a fix per finding. A prose document
-  nobody checks is a README; this one is checked.
-- **No application to build.** Frameworks hand you a library and leave you
-  owning a program: graph code, state plumbing, retries, transport. Here an
-  agent is an instruction, a model, tools, skills, who it may hand work to, and
-  how it fans out. That is the whole list, and it is YAML. There is no glue code
-  to maintain because there is no glue.
-- **A complete record, by default.** Every run writes its input, output and
-  state, plus a self-contained `report.html` — the graph, every request, every
-  token, every cost. Not a tracing vendor you sign up for; a file in the folder.
-- **Your keys stay yours.** They live in `~/.zenera`, never in the project. What
-  you share is the system; the recipient runs it on their own credentials and
-  their own choice of vendor.
+Most tools give you one agent, or a framework and an empty file. This is a
+factory: it designs the system for you, then keeps it honest.
+
+- **You state the problem; a meta-agent designs the system.** Specialists,
+  prompts, tool grants, hand-offs, where it fans out - all of it drawn from what
+  you wrote, and checked before it ever runs.
+- **A self-improving loop, not a one-off build.** Build, run, read the record,
+  change what was wrong, run again - and the system can drive that loop on
+  itself. Failures come back as findings with a cause and a fix, so the next
+  version is written rather than debugged.
+- **It watches itself work.** Every run is recorded against the architecture it
+  declared - the agent nobody called, the skill that never fired, where the
+  tokens went. Nothing to instrument, nothing to sign up for.
+- **Customisable all the way down.** Live in the specification and never look
+  lower. Or set the model, tools and memory of a single agent. Or take the
+  kernel itself and manage the trajectory turn by turn. No layer is sealed.
+- **Your documents, searchable.** Hybrid retrieval over your files and your API
+  descriptions, plus a memory that is a graph rather than a bucket of rows - so
+  what an agent learned in March is still there in September.
+- **Integrations it writes itself.** No MCP server to find, no connector to wait
+  for. If it has to reach your ERP, your database or a twenty-year-old SOAP
+  endpoint, it writes the call and runs it in a sandbox.
 
 ## Install
 
-Node.js 24+. One command — the OpenAI, Anthropic, Google and OpenRouter SDKs
+Node.js 24+. One command - the OpenAI, Anthropic, Google and OpenRouter SDKs
 all ship with the CLI, so any provider works out of the box.
 
 ```sh
@@ -108,19 +112,28 @@ npx @zenera/cli --help
 
 ## Quickstart
 
-Four commands, from nothing to an answer:
+From nothing to a specialized agent system:
 
 ```sh
 npm i -g @zenera/cli         # every vendor SDK comes with it
 zen key add openai           # asks for the key without showing it; stored in ~/.zenera
 zen init my-project          # scaffolds a project and registers it
-zen run my-project "introduce yourself"
+zen open my-project          # open the specification and project in your editor
+```
+
+In the editor, describe the job in `SPECIFICATION.md`, then send this in the
+agent chat:
+
+```
+/sync-with-spec
 ```
 
-The name works from anywhere after that, and the directory you are standing in
-is what it works on:
+It creates the specialists, responsibilities, tool access and handoffs the job
+needs. Back in the terminal, validate the generated system and run it against a
+real workspace:
 
 ```sh
+zen check my-project
 cd ~/code/some-repo
 zen run my-project "summarise this repo and write NOTES.md"
 ```
@@ -142,9 +155,8 @@ Giving a prompt on the command line skips every question: it starts a fresh
 session and uses the current directory as the workspace, with write access.
 `--session`, `--workspace` and `--read-only` override that.
 
-To change what the system does, open the project in your editor with
-`zen open`, edit `SPECIFICATION.md` to say what you actually want built, and
-send `/sync-with-spec` in the editor's chat. That is the next section.
+To change what the system does, update `SPECIFICATION.md` and send
+`/sync-with-spec` again. The next section explains that workflow in detail.
 
 ## You write the specification; a coding agent writes the system
 
@@ -152,7 +164,7 @@ send `/sync-with-spec` in the editor's chat. That is the next section.
 implements it. Where the two disagree the specification wins, so a change to
 what the system does starts there and not in `agents.yaml`.
 
-The one `zen init` writes is not a heading list — it is a true specification of
+The one `zen init` writes is not a heading list - it is a true specification of
 the project just scaffolded, so you can read it against the files beside it
 before changing a word:
 
@@ -166,7 +178,7 @@ nobody to hand work to, because there is no second job to hand on.
 
 - The change asked for is in the workspace, or the question is answered from
   what is actually in it.
-- Everything the agent claims a command did, that command actually did — it was
+- Everything the agent claims a command did, that command actually did - it was
   run, and its output was read.
 - The reply names what changed, file by file, and says what it deliberately did
   not do.
@@ -174,7 +186,7 @@ nobody to hand work to, because there is no second job to hand on.
 
 ### How you actually edit it
 
-`SPECIFICATION.md` is ordinary Markdown, so any editor will do — but the loop is
+`SPECIFICATION.md` is ordinary Markdown, so any editor will do - but the loop is
 meant to be driven from a coding agent's chat, and `zen init` installs the
 prompts that make each step a single command:
 
@@ -188,14 +200,17 @@ or IntelliJ it can find. `--editor <cmd>` names one outright.
 
 In the window that opens:
 
-1. **Edit `SPECIFICATION.md`** — what the system is for, which agents exist,
+1. **Edit `SPECIFICATION.md`** - what the system is for, which agents exist,
    what each may reach for, and what _done_ means.
 2. **Open the chat panel and send `/sync-with-spec`.** It reads the
    specification and every file implementing it, works out the difference in
    both directions, and changes the smallest thing that closes each gap.
-3. **Read `SPECIFICATION-FEEDBACK.md`**, which it writes for anything it could
-   not do without guessing. Answer its questions by editing `SPECIFICATION.md`
-   — not by editing prompts — and send `/sync-with-spec` again.
+3. **Answer `SPECIFICATION-FEEDBACK.md`**, which it writes for anything it could
+   not do without guessing. Every question carries two to four written-out
+   answers, each with a `[ ]` box: tick one, delete the ones you do not want, or
+   write your own in their place.
+4. **Send `/update-spec-from-feedback`.** It folds the answers you chose into
+   `SPECIFICATION.md` - never into a prompt - and then `/sync-with-spec` again.
 
 Back in the terminal: `zen check`, then `zen run`.
 
@@ -204,40 +219,53 @@ Back in the terminal: `zen check`, then `zen run`.
 
 They are prompt files under `.github/prompts/`, which VS Code and its forks
 offer as chat slash-commands. Both `zen init` and `zen open` write them fresh,
-so they never go stale — and edits to them do not survive.
+so they never go stale - and edits to them do not survive.
 
-| In chat           | Does                                                        |
-| ----------------- | ----------------------------------------------------------- |
-| `/sync-with-spec` | Makes every file match `SPECIFICATION.md`, both directions. |
-| `/review-project` | Reads the project as a reviewer would, and reports.         |
-| `/new-agent`      | Adds an agent — prompt, wiring and hand-offs.               |
-| `/new-skill`      | Adds a skill under `agents/skills/`.                        |
+| In chat                      | Does                                                             |
+| ---------------------------- | ---------------------------------------------------------------- |
+| `/sync-with-spec`            | Makes every file match `SPECIFICATION.md`, both directions.      |
+| `/update-spec-from-feedback` | Folds your answers in `SPECIFICATION-FEEDBACK.md` into the spec. |
+| `/review-project`            | Reads the project as a reviewer would, and reports.              |
+| `/new-agent`                 | Adds an agent - prompt, wiring and hand-offs.                    |
+| `/new-skill`                 | Adds a skill under `agents/skills/`.                             |
 
 In an editor that does not support prompt files, paste the contents of
-`.github/prompts/sync-with-spec.prompt.md` into its chat instead — it is only a
+`.github/prompts/sync-with-spec.prompt.md` into its chat instead - it is only a
 prompt. Alongside them, `.github/copilot-instructions.md` is the standing brief
 that explains this runtime to whatever agent is reading, and
 `.github/skills/zen-cli/` is the CLI's own reference for it.
 
 </details>
 
-### The loop
+### The self-improving loop
 
 ```
-edit SPECIFICATION.md → /sync-with-spec → zen check → scripts/_setup.sh
-        ↑                                                        ↓
-        └──────────────── read the report ←──────── zen run ─────┘
+edit SPECIFICATION.md → /sync-with-spec → zen check → zen run
+        ↑                                                  ↓
+        └───── refine the spec <-──── zen inspect <-───────┘
 ```
 
-The last turn is the one that matters. When a run comes out wrong, the fix is
-the sentence that was missing from the specification; the prompt edit follows
+`zen inspect` makes the record visible: the run trace, timing and token
+statistics, agent architecture, and memory used during the run.
+
+![Run inspection: trace, agent architecture, and memory](https://raw.githubusercontent.com/andreyryabov/ZeneraNeo/main/docs/imgs/0910_480.gif)
+
+Every step is a command, and everything each one reads or writes is a plain
+file: the specification, the findings `zen check` prints with a code, a location
+and a fix, the record `zen inspect` renders of what the run actually did. So the
+loop does not need you standing in it. Hand the whole cycle to the agent in your
+editor and it runs on the system it just built - test it, read the failure,
+change the sentence in the specification that caused it, rebuild, run again.
+"Fix my project" is one instruction. (The first time round, `scripts/_setup.sh`
+prepares the container the tools run in.)
+
+The last turn is the one that matters. When a run comes out wrong the fix is the
+sentence that was missing from the specification, and the prompt edit follows
 from that. Prompts patched directly drift away from the document meant to
 describe them, and a project whose specification is no longer true is a project
 with no specification.
 
-You are not expected to hand-author any of this. `zen check` is written to be
-read by a model as much as by a person — every finding carries a code, a
-location and its fix — so "fix my project" is one instruction. Full guide:
+Full guide:
 [docs/specification.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/specification.md).
 
 ## A worked example
@@ -249,7 +277,7 @@ zen init repo-notes && cd repo-notes
 zen open                      # opens this folder in your editor
 ```
 
-Replace `SPECIFICATION.md` with what you want. This is the whole input — no
+Replace `SPECIFICATION.md` with what you want. This is the whole input - no
 YAML, no prompt files:
 
 ```markdown
@@ -261,9 +289,9 @@ Read a codebase and leave a short written note about it in the workspace.
 
 ## Agents
 
-- `reader` — explores the workspace and forms a picture of it. May read files
+- `reader` - explores the workspace and forms a picture of it. May read files
   and list directories, and nothing else. Hands off to `writer`.
-- `writer` — turns that picture into `NOTES.md`. May write to the workspace.
+- `writer` - turns that picture into `NOTES.md`. May write to the workspace.
 
 ## Done means
 
@@ -271,7 +299,7 @@ Read a codebase and leave a short written note about it in the workspace.
 - Every claim in it comes from a file that was actually read.
 ```
 
-Send `/sync-with-spec` in the editor's chat. It writes `agents.yaml` — who
+Send `/sync-with-spec` in the editor's chat. It writes `agents.yaml` - who
 exists, and what each may reach for:
 
 ```yaml
@@ -292,7 +320,7 @@ agents:
       handoffs: [reader] # a hand-off does not return by itself; give it a way back
 ```
 
-— and one prompt file per agent.
+- and one prompt file per agent.
 
 <details>
 <summary>The prompt files it writes</summary>
@@ -320,15 +348,15 @@ lines. Then say where you put it and stop.
 | Key           | Is                                                                    |
 | ------------- | --------------------------------------------------------------------- |
 | `name`        | how everything else refers to this agent                              |
-| `description` | what it is for — read by the _other_ agents when deciding to hand off |
+| `description` | what it is for - read by the _other_ agents when deciding to hand off |
 | `system`      | its own brief, in prose, at `agents/prompts/<name>.md`                |
 | `model`       | this agent's model; the top-level one otherwise                       |
-| `tools`       | what it may reach for — `workspace:*`, `sandbox:*`, a named tool      |
+| `tools`       | what it may reach for - `workspace:*`, `sandbox:*`, a named tool      |
 | `handoffs`    | who it may pass the work to                                           |
 | `skills`      | knowledge pulled in mid-run instead of carried in every prompt        |
 
 The file is validated strictly at load: an unknown tool, a handoff to nobody, a
-missing prompt file — each fails immediately, naming the offending key, rather
+missing prompt file - each fails immediately, naming the offending key, rather
 than surfacing three turns into a run as a confused model. Full reference:
 [docs/agents-yaml.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/agents-yaml.md).
 
@@ -345,29 +373,33 @@ zen inspect --project repo-notes --open    # what it actually did
 
 That is the end of it: `repo-notes` is now a command like any other, in any
 directory, for as long as the folder exists. Commit the folder and whoever
-clones it types `zen init repo-notes` once — a directory that is already a
-project is registered, not rebuilt, and nothing in it is touched — and the name
+clones it types `zen init repo-notes` once - a directory that is already a
+project is registered, not rebuilt, and nothing in it is touched - and the name
 is a command on their machine too.
 
 ## A project is a folder
 
-Prompts, agent wiring, skills and tool selections are all files — Markdown and
-YAML — rather than code buried inside an application. So the folder can be
+Prompts, agent wiring, skills and tool selections are all files - Markdown and
+YAML - rather than code buried inside an application. So the folder can be
 committed, copied to another machine, reviewed in a pull request, and handed to
-someone else who runs it with one command. Credentials live in `$HOME`, never in
-the project, so there is no secret to strip before sharing it.
+someone else who runs it with one command. Model credentials live in `$HOME`,
+never in the project, and anything the project itself needs goes in a
+git-ignored `.env` - so there is no secret to strip before sharing it.
 
 ```
 my-project/
-    SPECIFICATION.md             what this is for — the intent
-    INSTRUCTIONS.md              house rules, prepended to every agent
+    SPECIFICATION.md             what this is for - the intent
     agents.yaml                  who exists, what they may reach for
     agents/
+        instructions.md          house rules, prepended to every agent
+        <topic>-instructions.md  more of them, one subject at a time
         prompts/<name>.md        each agent's own brief
         skills/<name>/           knowledge loaded on demand, not always-on
     assets/                      reference material, read-only at /assets
     sandbox/Dockerfile           the container commands run in
     scripts/_setup.sh            the one command that initialises the project
+    .spec-sync/                  what the last sync with the spec applied
+    .env                         this project's environment - git-ignored
     sessions/                    one workspace, memory and trajectory each
         <id>/
             workspace/           what the agents can read and write
@@ -379,29 +411,50 @@ happened when it ran. Nothing here is tied to the machine it was written on,
 which is the point of the CLI: it makes agentic systems shareable the way
 repositories are shareable.
 
-`zen init` also writes `.vscode/` and a `.github/` tree — a standing brief that
+`zen init` also writes `.vscode/` and a `.github/` tree - a standing brief that
 explains this runtime to whatever coding agent you open the folder with, plus
 the prompts and skills it needs to keep the project matching its specification.
 
 ## Concepts
 
-- **Project** — a named directory holding a complete agent definition and the
+- **Project** - a named directory holding a complete agent definition and the
   sessions that have run against it. It is self-describing: `agents.yaml` is
   what makes a directory a project, so moving or cloning it loses nothing.
-- **Session** — a context that persists across runs: one workspace, one memory,
+- **Session** - a context that persists across runs: one workspace, one memory,
   one store for large files, and a record of everything that happened, added to
   as it goes. Resumable.
-- **Run** — one prompt in, one answer out, inside a session. Recorded in full,
+- **Run** - one prompt in, one answer out, inside a session. Recorded in full,
   whether or not you were watching.
-- **Workspace** — the directory the agents may read and write. A prompt given on
+- **Workspace** - the directory the agents may read and write. A prompt given on
   the command line uses the current directory; the TUI offers the session's own
   empty folder instead, and asks before using anything outside it.
-- **Keyring** — `~/.zenera/neo`, readable only by you. See
+- **Keyring** - `~/.zenera/neo`, readable only by you. See
   [Credentials](#credentials).
-- **Cache** — `~/.zenera/neo/cache`, one place for work already done: vectors,
+- **Cache** - `~/.zenera/neo/cache`, one place for work already done: vectors,
   parses, model listings, generated mocks. Shared by every project on the
   machine, and never emptied by anything but you. See [Cache](#cache--work-you-have-already-paid-for).
 
+## Sandbox commands
+
+Agents use an isolated container when a project grants them command-line tools.
+`zen run` prepares it automatically before the first command, but these commands
+make setup, diagnostics and cleanup explicit - useful on a new machine or when
+you want to validate a project's execution environment before a run.
+
+```sh
+zen sandbox status                    # engine, project image and active containers
+zen sandbox up                        # prepare the execution environment for this project
+zen sandbox pull                      # pull or build this project's image only
+zen sandbox status --project my-app   # inspect a named project from anywhere
+zen sandbox disk                      # storage used by the engine and known projects
+zen sandbox clean                     # remove containers created by zen
+```
+
+`status`, `up` and `pull` use the project in the current directory, or accept
+`--project <name|dir>`. `--image <ref>` selects an image explicitly. `clean` and
+`disk` are machine-wide operations, so use them when you mean to inspect or
+remove resources beyond the current project.
+
 ## Commands
 
 | Command   | Does                                                                 |
@@ -409,11 +462,11 @@ the prompts and skills it needs to keep the project matching its specification.
 | `init`    | Creates a project here, or in `<dir>`, and registers it.             |
 | `list`    | Every known project: sessions, last run, whether one is live.        |
 | `open`    | Opens a project in your editor.                                      |
-| `key`     | The credential keyring — add, check, switch, remove.                 |
-| `models`  | What this machine can use — list, search, test, pick.                |
-| `run`     | Runs the project — the TUI on a terminal, a single answer otherwise. |
+| `key`     | The credential keyring - add, check, switch, remove.                 |
+| `models`  | What this machine can use - list, search, test, pick.                |
+| `run`     | Runs the project - the TUI on a terminal, a single answer otherwise. |
 | `inspect` | Opens or rebuilds a run's `report.html`.                             |
-| `memory`  | What the agents remember — size, listing, one node, or a whole page. |
+| `memory`  | What the agents remember - size, listing, one node, or a whole page. |
 | `check`   | Validates the project and every file it names, and asks the models.  |
 | `sandbox` | Checks and prepares the container that command-line tools run in.    |
 | `cache`   | What work has been kept, and getting rid of it.                      |
@@ -433,17 +486,36 @@ an installed one costs nothing until it is used.
 | `faker` | `@zenera/faker` | A mock API from an openapi/swagger document.   |
 | `rag`   | `@zenera/rag`   | Search an openapi/swagger document as a graph. |
 
+**`zen faker`** turns an OpenAPI or Swagger description into a working mock
+server. It generates behavior for each route, checks the result against the
+response contract, and reuses the generated implementation on later requests.
+
 ```sh
 npm i -g @zenera/faker
 zen faker serve api/openapi.yaml --port 8787   # a working mock, bodies written by a model
 
+curl -s localhost:8787/users/12324
+# { "user_id": 12324, "email": "brooke.hoffman@example.org", … }
+```
+
+**`zen rag`** adds advanced retrieval for the knowledge an agent needs to work
+from: documentation and API schemas. Document indexes support semantic,
+full-text and hybrid search with passages returned alongside their source lines.
+Schema indexes add graph-aware retrieval across operations, types, fields,
+requests and responses, so an answer can include the connected API context
+rather than an isolated match.
+
+```sh
 npm i -g @zenera/rag
 zen rag schema index --embedding openai:text-embedding-3-small ./specs/*.yaml
 zen rag schema search --output-property "user billing history" --format ts
+
+zen rag docs index ./handbook --embedding openai:text-embedding-3-small
+zen rag docs search "how does failover work when the primary is unreachable"
 ```
 
-They use this keyring and these credentials, so there is nothing new to
-configure. Details:
+Use [@zenera/rag](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/rag/README.md)
+for its complete retrieval capabilities and examples. Details:
 [@zenera/faker](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/faker/README.md)
 ·
 [@zenera/rag](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/rag/README.md).
@@ -455,7 +527,7 @@ The binary is installed under three names: `zen`, `zn` and `zenera`.
 Global flags: `-h/--help`, `-v/--version`, `--json`, `-C <dir>`.
 
 `stdout` carries the answer and `stderr` carries the narration, and `--json`
-works on every command — so `zen run … | jq` is a supported way to use this, not
+works on every command - so `zen run … | jq` is a supported way to use this, not
 an accident.
 
 | Exit code | Meaning              |
@@ -479,7 +551,7 @@ zen key add <provider> < key.txt    # or pipe it in
 
 The value is never passed as an argument. A command line is visible to anyone
 listing running processes, is saved in your shell history and is captured in CI
-logs — so the hidden prompt and piping it in are the only two ways.
+logs - so the hidden prompt and piping it in are the only two ways.
 
 Entries live in `~/.zenera/neo/keys.json`, in a file only you can read. They are
 copied into the environment just before a run, which has two consequences worth
@@ -490,14 +562,14 @@ checked out on a machine without `zen` still runs.
 | ------------ | ------------------------------------- | -------------------------------- |
 | `openai`     | a secret                              | `OPENAI_API_KEY`                 |
 | `anthropic`  | a secret                              | `ANTHROPIC_API_KEY`              |
-| `google`     | a secret — AI Studio                  | `GEMINI_API_KEY`                 |
+| `google`     | a secret - AI Studio                  | `GEMINI_API_KEY`                 |
 | `vertex`     | a path to a service-account JSON file | `GOOGLE_APPLICATION_CREDENTIALS` |
 | `openrouter` | a secret                              | `OPENROUTER_API_KEY`             |
-| `exa`        | a secret — for the search tool        | `EXA_API_KEY`                    |
+| `exa`        | a secret - for the search tool        | `EXA_API_KEY`                    |
 
 `zen key add` verifies the credential against the provider before it finishes,
-but stores it either way: a key that cannot be checked right now — offline,
-behind a proxy — is not a key that is wrong. `--no-check` skips the call.
+but stores it either way: a key that cannot be checked right now - offline,
+behind a proxy - is not a key that is wrong. `--no-check` skips the call.
 
 ### Which key a model uses
 
@@ -533,12 +605,12 @@ been one does a short built-in list stand in.
 `zen models test` separates three kinds of failure, because each calls for a
 different action:
 
-- **refused** — the provider rejected the credential. Fix or replace the key.
-- **blocked** — the credential was accepted and the account then said no: an API
+- **refused** - the provider rejected the credential. Fix or replace the key.
+- **blocked** - the credential was accepted and the account then said no: an API
   switched off, an empty balance, a model this key was never granted. The key is
   fine; the account needs changing, and the command that changes it is printed
   with the error.
-- **unknown** — the question never arrived (offline, proxy, timeout). Nothing is
+- **unknown** - the question never arrived (offline, proxy, timeout). Nothing is
   wrong with the key; try again.
 
 ```
@@ -559,11 +631,11 @@ zen rag schema index --embedding "$(zen models pick --embedding)" ./specs/*.yaml
 
 ### Setting up each provider
 
-The shape is the same everywhere — `zen key add <provider>`, then answer the
+The shape is the same everywhere - `zen key add <provider>`, then answer the
 prompt. Open the one you need for its specifics.
 
 <details>
-<summary><strong>OpenAI</strong> — one secret, exported as <code>OPENAI_API_KEY</code></summary>
+<summary><strong>OpenAI</strong> - one secret, exported as <code>OPENAI_API_KEY</code></summary>
 
 ```sh
 zen key add openai
@@ -575,7 +647,7 @@ zen key add openai
 </details>
 
 <details>
-<summary><strong>Anthropic</strong> — one secret, exported as <code>ANTHROPIC_API_KEY</code></summary>
+<summary><strong>Anthropic</strong> - one secret, exported as <code>ANTHROPIC_API_KEY</code></summary>
 
 ```sh
 zen key add anthropic
@@ -585,7 +657,7 @@ zen run --model anthropic:claude-sonnet-4-5 "summarise this repo"
 </details>
 
 <details>
-<summary><strong>OpenRouter</strong> — one secret, exported as <code>OPENROUTER_API_KEY</code></summary>
+<summary><strong>OpenRouter</strong> - one secret, exported as <code>OPENROUTER_API_KEY</code></summary>
 
 One credential for many vendors' models. The model id keeps its own vendor
 prefix, after the `openrouter:` one:
@@ -599,7 +671,7 @@ zen run --model openrouter:anthropic/claude-haiku-4.5 "summarise this repo"
 </details>
 
 <details>
-<summary><strong>Google AI Studio</strong> — one secret, exported as <code>GEMINI_API_KEY</code></summary>
+<summary><strong>Google AI Studio</strong> - one secret, exported as <code>GEMINI_API_KEY</code></summary>
 
 One key and nothing else to configure: the shortest way to a working Gemini
 model.
@@ -610,7 +682,7 @@ zen check                         # google:gemini-3.5-flash now resolves
 ```
 
 The same Gemini models are also served by Vertex AI, under a different
-credential. Both can be configured at once — they are separate entries for
+credential. Both can be configured at once - they are separate entries for
 separate services, and the prefix on the model reference decides which is used:
 
 ```sh
@@ -621,12 +693,12 @@ zen run --model vertex:gemini-3.5-flash "summarise this repo"
 </details>
 
 <details>
-<summary><strong>Vertex AI</strong> — a service-account file, or an express-mode key</summary>
+<summary><strong>Vertex AI</strong> - a service-account file, or an express-mode key</summary>
 
 Vertex accepts two kinds of credential, and you never declare which one you are
 giving: if the value is a path to a file that exists it is treated as a
 service-account key, otherwise as an API key. The name you give the entry has no
-bearing on this — `vertex/express` is just an entry called `express`, exactly as
+bearing on this - `vertex/express` is just an entry called `express`, exactly as
 `vertex/prod` is one called `prod`, and either name can hold either kind.
 
 **A service-account JSON file** is the usual one, and what production normally
@@ -638,7 +710,7 @@ zen key add vertex --gcp-location us-central1
 # Paste the key, or a path to the file: /Users/you/keys/vertex-sa.json
 ```
 
-The prompt is read by `zen`, not by your shell, so give a full path there — `~`
+The prompt is read by `zen`, not by your shell, so give a full path there - `~`
 is not expanded. In a script, pipe the path in instead:
 
 ```sh
@@ -657,7 +729,7 @@ moving or cleaning up the original later cannot break it.
 - Which models a location serves varies per model and is not guessable. In one
   project, `gemini-embedding-2` answered at `us` but 404'd at `us-central1`,
   while `gemini-2.5-flash` did the opposite. New models often reach `global`,
-  `us` and `eu` first. `zen models test vertex:<model>` is what settles it —
+  `us` and `eu` first. `zen models test vertex:<model>` is what settles it -
   `zen key add` only establishes that the credential itself works.
 - `--gcp-project <id>` is only needed when the `project_id` inside the file is
   not the project you want to bill:
@@ -686,7 +758,7 @@ keyring, so it is always visible which credential a run will actually use.
 </details>
 
 <details>
-<summary><strong>Exa</strong> — one secret, exported as <code>EXA_API_KEY</code></summary>
+<summary><strong>Exa</strong> - one secret, exported as <code>EXA_API_KEY</code></summary>
 
 Not a model provider: this is what backs the search tool an agent reaches for
 when it has to look something up on the web.
@@ -706,7 +778,7 @@ Entries are named, so a provider can hold several, one of which is active:
 zen key add openai/work         # a second entry
 zen key use openai/work         # the one that runs will use
 zen key ls --check              # everything stored, and whether it still works
-zen key show vertex/default     # masked — --reveal prints the secret
+zen key show vertex/default     # masked - --reveal prints the secret
 zen key env openai              # shell exports, for other tools
 zen key rm openai/work
 ```
@@ -722,12 +794,12 @@ zen key use vertex/dev          # which one the next run uses
 ```
 
 `zen key ls` marks the active entry with `*`, and anything it found outside the
-keyring — in your environment, or in a `gcloud` login — with `~`, so it is always
+keyring - in your environment, or in a `gcloud` login - with `~`, so it is always
 clear where a working provider actually comes from.
 
 </details>
 
-## Cache — work you have already paid for
+## Cache - work you have already paid for
 
 Embedding a paragraph, parsing a document, asking a provider what it serves: all
 of these are slow or costly, and all of them give the same answer every time. So
@@ -756,7 +828,7 @@ time.
 ## The library underneath
 
 This is a shell over
-[`@zenera/neo`](https://www.npmjs.com/package/@zenera/neo) — agents, models,
+[`@zenera/neo`](https://www.npmjs.com/package/@zenera/neo) - agents, models,
 tools, skills, memory and a running record of everything that happened. Use it
 directly when you want the runtime inside your own application rather than on a
 terminal:
@@ -765,19 +837,19 @@ terminal:
 ## Documentation
 
 - [docs/specification.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/specification.md)
-  — writing the specification the project implements.
+    - writing the specification the project implements.
 - [docs/projects.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/projects.md)
-  — what the project folder contains, file by file.
+    - what the project folder contains, file by file.
 - [docs/agents-yaml.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/agents-yaml.md)
-  — every key in the configuration file.
+    - every key in the configuration file.
 - [docs/knowledge.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/knowledge.md)
-  — building a searchable document index.
+    - building a searchable document index.
 - [docs/integrations.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/integrations.md)
-  — making an API description searchable and mockable.
+    - making an API description searchable and mockable.
 - [docs/memory.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/memory.md)
-  — what agents keep between sessions.
+    - what agents keep between sessions.
 
 ## License
 
-Early days and moving fast — issues, questions and pull requests are welcome.
+Early days and moving fast - issues, questions and pull requests are welcome.
 [MIT](LICENSE).