@zenera/cli 1.1.2 → 1.1.4

package/templates/{.github → editor/.github}/copilot-instructions.md

@@ -382,8 +382,8 @@ Google's `embedContent` takes one document per request for every
 hide that. `maxBatch` therefore defaults to `1`; raise it only for a
 `text-embedding-*` model, which accepts more.
 
-`zen check` and `zen models` report every declared embedding beside the models,
-with the credential each one would need.
+`zen check` reports every declared embedding beside the models, with the
+credential each one would need.
 
 ### 3.2 `INSTRUCTIONS.md`
 
@@ -621,12 +621,13 @@ container involved there is no second name and everything stays relative.
 
 **Selecting them.** A `tools:` entry is a selector, not only a name:
 
-| Selector      | Selects                                           |
-| ------------- | ------------------------------------------------- |
-| `read_file`   | that one tool                                     |
-| `workspace:*` | every tool in the group                           |
-| `'*'`         | every tool the runtime provides                   |
-| `-<any>`      | removes what it matches from the selection so far |
+| Selector              | Selects                                           |
+| --------------------- | ------------------------------------------------- |
+| `read_file`           | that one tool                                     |
+| `workspace:read_file` | the same tool, written out in full                |
+| `workspace:*`         | every tool in the group                           |
+| `'*'`                 | every tool the runtime provides                   |
+| `-<any>`              | removes what it matches from the selection so far |
 
 ```yaml
 agents:
@@ -1539,8 +1540,34 @@ There is no compiler for prose. Substitutes, in order of value:
    credential resolves, not that the route serves images or honours `tools`; on a
    gateway that gap is a request-time 404 (§7.5).
 
+### When a model or embedder will not answer
+
+`zen check` names the model and the verdict. Act on the verdict, not on the
+first thing that looks like a credential problem:
+
+```sh
+zen models test <ref>          # one real call, one verdict
+```
+
+- **refused** — the credential was rejected. `zen key check <provider>`.
+- **blocked** — the credential was _accepted_ and the account said no: an API
+  switched off, an empty balance, a model this key was never granted. **Do not
+  rotate the key** — a new one is refused identically. The fix is printed under
+  the verdict; for a disabled Google API it is the exact `gcloud services
+enable …` line.
+- **no answer** — the network. Try again.
+
+Either run the printed fix, or take a model that works and put the ref it prints
+into `agents.yaml`:
+
+```sh
+zen models pick --embedding    # or --chat; the ref goes to stdout, alone
+```
+
+Then re-run `zen check`.
+
 CLI (`zen --help` for the authoritative list): `zen init`, `zen run`, `zen check`,
-`zen inspect`, `zen models`, `zen key`, `zen list`. **stdout is the answer, stderr
+`zen inspect`, `zen key`, `zen models`, `zen list`. **stdout is the answer, stderr
 is the narration**; every command takes `--json`. Exit codes: `0` ok, `1` failed,
 `2` usage, `3` invalid project, `4` no usable credential.
 
@@ -1630,6 +1657,7 @@ Before finishing any change here:
 | Answers from stale knowledge of the world  | Grant `web_search` + `web_read`, and say when — §3.8                |
 | Cites a page it only saw the excerpt of    | A prompt line: `web_read` before quoting — §3.8                     |
 | Every web call refuses                     | No Exa key: `zen key add exa` — `zen check` warns — §3.8            |
+| A model or embedder refuses every call     | `zen models test <ref>` — if `blocked`, `zen models pick` — §8      |
 | Answers instead of routing                 | Router prompt prohibition; check `handoffs:`                        |
 | Routes to the wrong specialist             | The target agents' `description:` fields                            |
 | Loses a detail after a handoff             | Say it in the handoff; check the collapse policy                    |

package/templates/editor/.github/skills/api-schema-index/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: api-schema-index
+description: What a schema index is, how it finds the right call inside a large OpenAPI/Swagger document, and how to build and query one with `zen rag schema` (or `npx @zenera/cli`) — including giving it to an agent as tools.
+---
+
+# The schema index
+
+A schema index is an OpenAPI/Swagger description turned into something that can
+be **asked a question**. It is built once, on disk, and answered from without a
+model: `zen rag schema index` writes it, `zen rag schema search` queries it.
+
+It exists because a real specification does not fit in a context window, and
+grepping it does not help. The parts that answer "how do I reset a password?"
+are scattered on purpose: the field is on a schema, the schema is a request
+body, the request body belongs to one operation out of three hundred, and the
+word "password" appears in forty places that are not the one you want.
+
+## Why it is a graph and not a search box
+
+Two structures, kept together, because neither answers alone:
+
+| Structure                            | Answers                            |
+| ------------------------------------ | ---------------------------------- |
+| A vector + full-text index (LanceDB) | _where is `password` in this API?_ |
+| A graph (graphology)                 | _what is `password` connected to?_ |
+
+Finding the field is retrieval. Getting from the field to `POST
+/auth/reset-password` and the exact shape of its body is traversal. So a search
+does both: it seeds on the vector hits, walks the graph outward from them, and
+answers with **the connected piece of the API that matched** — the operations,
+the schemas they carry and the fields inside them — rather than a ranked list of
+fragments naming types nobody printed.
+
+## What is in one
+
+Three kinds of node, joined by the `$ref`s between them. Documents are
+**bundled, not dereferenced**: `#/components/schemas/User` stays an edge and
+`User` is a node id.
+
+| Kind       | Id                           | Is                                |
+| ---------- | ---------------------------- | --------------------------------- |
+| `method`   | `Method:resetUserPassword`   | an operation                      |
+| `type`     | `Type:ResetPasswordPayload`  | a schema                          |
+| `property` | `Type:User.email` (a field)  | a field on a schema               |
+| `property` | `Method:listUsers#page_size` | a query/path/header **parameter** |
+
+A parameter is a property like any other, deliberately. Nobody should have to
+know in advance whether `page_size` lives in a query string or a body — that is
+the thing they came here to find out.
+
+Every node carries a **direction** — `input`, `output` or `both` — propagated
+from the operations down through composition, so a DTO used on both sides is
+honestly both rather than whichever side was read last. That is what makes
+"a field in a **response**" a filter and not a hope.
+
+`discriminator` is kept: it is what turns a `oneOf` into a tagged union a
+TypeScript compiler can narrow.
+
+```
+schema-db/
+├── manifest.json     written LAST — its absence means "not indexed"
+├── graph.json        topology, read whole
+├── schemas.json      the raw schemas, read on first hydrate
+├── operations.json   likewise
+└── lance/            one row per node: one text column, one vector
+```
+
+`manifest.json` records **which embedder made the vectors**, so a search with a
+different model is refused rather than answered with noise.
+
+## Installing
+
+`zen rag` ships in `@zenera/rag`, a sibling of the CLI. It has no binary of its
+own — installing it adds the `rag` subcommand to `zen`, which is also where the
+credentials already live.
+
+```sh
+npm i -g @zenera/cli @zenera/rag       # then: zen rag schema …
+```
+
+For a one-off, without installing anything, **both** packages must be in the
+same temporary install or `zen` will report `rag` as not installed:
+
+```sh
+npx --package @zenera/cli --package @zenera/rag -- zen rag schema index openapi.yaml --embedding openai:text-embedding-3-small
+```
+
+Every example below is spelled `zen …`; prefix it with that `npx` form if you
+have not installed globally.
+
+## Building an index
+
+```
+zen rag schema index <spec...> [--embedding <ref>] [-o <dir>] [--batch <n>]
+```
+
+| Flag                | Default       | Meaning                                                      |
+| ------------------- | ------------- | ------------------------------------------------------------ |
+| `--embedding <ref>` | —             | Which embedder makes the vectors. Omit it to see the choices |
+| `-o`, `--out <dir>` | `./schema-db` | Where the index goes                                         |
+| `--batch <n>`       | `96`          | Texts per embedding request, and how often progress prints   |
+| `--quiet`           | —             | No narration                                                 |
+
+```sh
+zen rag schema index openapi.yaml --embedding openai:text-embedding-3-small
+zen rag schema index specs/*.yaml --embedding google:gemini-embedding-001 -o .index/api
+```
+
+Several documents can go into one index; they share a graph, which is usually
+what you want when an API is split across files. Swagger 2.0 and OpenAPI
+3.0/3.1, JSON or YAML, are all converted to JSON Schema 2020-12 on the way in.
+
+This is the one command here that spends money and time: it embeds every
+operation, schema and field. It prints a per-document table (paths, operations,
+schemas, fields) and a progress line per batch, and **stdout is the output
+directory and nothing else** — so `DIR=$(zen rag schema index …)` works.
+
+The embedding reference names a provider first: `openai:text-embedding-3-small`,
+not a bare model id. Credentials come from the `zen` keyring (`zen key ls`), and
+a real environment variable always wins.
+
+Rebuild the index when the specification changes. Nothing watches it, and a
+stale index is a confident wrong answer.
+
+## Searching it
+
+```
+zen rag schema search [terms…] [filters…]
+```
+
+### The field is the point
+
+A query is not one string. It is a handful of **fields**, and the field a phrase
+arrives in decides the filter it runs under — `--output-property "invoice total"`
+means _kind=property, on the response side_, and none of that has to be said
+twice.
+
+| Term                    | Searches                                          |
+| ----------------------- | ------------------------------------------------- |
+| `<text>`                | Everything — the same as `--all`                  |
+| `--all <q>`             | Everything, unfiltered                            |
+| `--method <q>`          | Operations                                        |
+| `--type <q>`            | Schemas, on the side `--direction` names          |
+| `--input-type <q>`      | Schemas a call accepts                            |
+| `--output-type <q>`     | Schemas a call returns                            |
+| `--property <q>`        | Fields and parameters, per `--direction`          |
+| `--input-property <q>`  | Fields, parameters and body fields a call accepts |
+| `--output-property <q>` | Fields a call returns                             |
+| `--query <json\|->`     | A whole query object; `-` reads stdin             |
+
+Every term is repeatable. **`--all` is the weakest of them** — it cannot filter,
+so put the intent where it belongs: a request field in `--input-property`, a
+response field in `--output-property`, an action in `--method`.
+
+### Shaping the answer
+
+| Flag                        | Default       | Meaning                                                 |
+| --------------------------- | ------------- | ------------------------------------------------------- |
+| `-d`, `--dir <dir>`         | `./schema-db` | Which index                                             |
+| `--embedding <ref>`         | the index's   | Must be the one the index was built with                |
+| `--direction <d>`           | `any`         | `input`, `output` or `any`                              |
+| `--method-type <t>`         | `any`         | `read_only` (GET/HEAD/OPTIONS) or `read_write`          |
+| `--exclude-id <id>`         | —             | Drop a node. Repeatable                                 |
+| `--exclude-method <name>`   | —             | Drop an operation by name. Repeatable                   |
+| `--exclude-type <name>`     | —             | Drop a schema by name. Repeatable                       |
+| `--exclude-property <name>` | —             | Drop a field by name. Repeatable                        |
+| `--limit <n>`               | `5`           | Seeds kept per term                                     |
+| `--max-hops <n>`            | `3`           | How far apart two hits may be and still join            |
+| `--max-nodes <n>`           | `200`         | Nodes per result                                        |
+| `--format <f>`              | `text`        | `text`, `mermaid`, `mermaid-flowchart`, `ts`, `openapi` |
+| `--no-docs`                 | —             | Leave the descriptions out                              |
+| `--interactive`             | —             | Prompt, search, refine. Needs a terminal                |
+| `--quiet`                   | —             | No narration                                            |
+
+```sh
+zen rag schema search --method "reset a user password" --format ts
+zen rag schema search --output-property "invoice total" --direction output
+zen rag schema search --input-property "page size" --method-type read_only
+```
+
+`--format ts` emits TypeScript closed over its own `$ref`s: everything named is
+also declared, so the output compiles on its own. `--format openapi` emits a
+standalone document holding just the matched slice — the one to hand to a code
+generator or a mock server. The Mermaid formats are for looking at.
+
+### Turning one search into a session
+
+The exclusions are the mechanism: pass back the ids you have already been shown
+and you are shown something else instead of the same thing again.
+
+```sh
+zen rag schema search --all "subscription" --exclude-type Subscription --exclude-id Method:listSubscriptions
+```
+
+### As a machine interface
+
+Non-interactive search is a tool, not an afterthought. Every field is a flag,
+the whole query can arrive as one JSON object, `--json` is a stable shape, no
+terminal is needed, and **an empty result exits 0** — a caller must never have
+to tell "nothing matched" from "the index is missing" by parsing stderr.
+
+```sh
+zen rag schema search --query - --format ts <<'JSON'
+{
+    "input_properties": ["password reset token"],
+    "method_type": "read_write",
+    "exclude_ids": ["Type:PublicUserProfile"],
+    "limit": 3
+}
+JSON
+```
+
+The JSON field names are the flag names with underscores and plurals:
+`all`, `methods`, `types`, `input_types`, `output_types`, `properties`,
+`input_properties`, `output_properties`, `direction`, `method_type`,
+`exclude_ids`, `exclude_methods`, `exclude_types`, `exclude_properties`,
+`limit`, `max_hops`, `max_nodes`. An **unknown key is an error**, because a
+silently ignored `output_propertys` looks exactly like a search that found
+nothing. Flags win over `--query` when both name the same field.
+
+### `--interactive`
+
+A prompt that keeps the query between searches:
+
+```
+<text>                  search everything
+all|method|type <text>  search one field
+input-property <text>   also: output-property, property, input-type, output-type
+direction <d>           input | output | any
+method-type <t>         read_only | read_write | any
+format <f>              text | mermaid | mermaid-flowchart | ts | openapi
+show                    the query as it stands
+reset                   forget it, exclusions included
+quit
+```
+
+## Reading it without searching
+
+Both need no embedder and no credential — they are plain reads.
+
+```sh
+zen rag schema show Type:Invoice Method:listInvoices --format ts
+zen rag schema stats
+```
+
+`show` prints named nodes with no retrieval in between; `stats` says what is in
+an index and what built it — counts by kind, the embedding model, the documents
+it came from. `stats` is the fastest way to answer "is this index the one I
+think it is?".
+
+## Giving it to an agent
+
+The same engine, as four tools in the group `schema`. An agent takes them all
+with `schema:*` in its `tools:`.
+
+```ts
+import { createEmbedder, loadProject } from '@zenera/neo';
+import { SchemaIndex, schemaTools } from '@zenera/rag';
+
+const index = await SchemaIndex.open(
+    './schema-db',
+    createEmbedder('openai:text-embedding-3-small'),
+);
+const project = await loadProject('./my-project', { tools: schemaTools(index) });
+```
+
+| Tool                       | For                                                                 |
+| -------------------------- | ------------------------------------------------------------------- |
+| `search_api`               | the search above, with the same fields                              |
+| `describe_types`           | named schemas as TypeScript, closed over what they refer to         |
+| `find_types_with_property` | every schema with a field of this name — exact lookup, no searching |
+| `list_methods`             | operations by path, to see the shape of the API before asking       |
+
+`find_types_with_property` is the one for the repair loop. When `tsc` says
+`'password' does not exist in type 'PublicUserProfile'`, the model does not need
+the word explained again — it needs the list of types that _do_ have one, and
+embedding the word will only rank the guess it already made near the top.
+
+Tell the agent in its prompt to search before it writes a call, and to put the
+intent in the narrow field. A model left to itself puts everything in `all`.
+
+## When it goes wrong
+
+| Symptom                                          | Cause                                                                               |
+| ------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| "not installed"                                  | `@zenera/rag` is not resolvable — install it, or use the two-`--package` npx form   |
+| Refused for a different embedding                | The index records the model that built it; re-index or pass the right `--embedding` |
+| No manifest / not an index                       | A build that did not finish. `manifest.json` is written last on purpose             |
+| `provider "openai": no api key`                  | `zen key ls` — the keyring, or a real environment variable                          |
+| A usage error before any credential is asked for | Deliberate: everything about the invocation is checked first, so a typo is a typo   |
+| Nothing matched                                  | Exit 0 with an empty answer. Try fewer words, or `--all` instead of a narrow field  |
+| Answers about the wrong version of the API       | Nothing watches the document. Re-index after it changes                             |

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

@@ -0,0 +1,77 @@
+---
+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.
+---
+
+# The `zen` command line
+
+`zen` runs agent projects from a terminal. Everything here operates on a project
+directory, resolved from the working directory, or by name from the registry
+`zen init` wrote to, or explicitly with `--project <name|dir>`. Every command
+takes `--json` and prints a machine-readable answer instead of a rendered one.
+
+**stdout is the answer, stderr is the narration.** Exit codes: `0` ok, `1`
+failed, `2` usage, `3` invalid project, `4` no usable credential, `5` sandbox.
+
+## The commands
+
+```
+zen init     [dir] [--name <name>] [--model <ref>] [--force]
+zen list     [--sessions] [--prune]
+zen run      [project] [prompt] [options]
+zen open     [project] [--editor <cmd>] [--wait]
+zen key      <ls|add|use|check|rm|show|env> [ref] [options]
+zen models   <providers|ls|search|show|test|pick> [ref] [options]
+zen check    [name|dir] [--project <name|dir>] [--no-sandbox] [--no-models] [--strict] [--quiet]
+zen inspect  [run] [--session <id>] [--open] [--rebuild] [--serve [port]]
+zen sandbox  [status|up|pull|clean|disk] [options]
+zen version
+
+zen faker    <serve|build|cache> [spec...]
+zen rag      schema <index|search|show|stats> [spec...]
+```
+
+## 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
+guess a flag, and do not read them all.
+
+| The question is about                                               | Read                                    |
+| ------------------------------------------------------------------- | --------------------------------------- |
+| Global flags, `--json`, exit codes, environment, where files live   | [frame.md](./references/frame.md)       |
+| Creating, finding or opening a project                              | [projects.md](./references/projects.md) |
+| Running: the TUI, one-shot answers, sessions, workspaces, overrides | [run.md](./references/run.md)           |
+| Validating: `zen check`, what it can and cannot see                 | [check.md](./references/check.md)       |
+| API keys, providers, the keyring, "no credential" errors            | [keys.md](./references/keys.md)         |
+| Which models exist, whether one works, recovering from a refusal    | [models.md](./references/models.md)     |
+| 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)   |
+| `zen faker` — a mock API from an OpenAPI/Swagger document           | [faker.md](./references/faker.md)       |
+| `zen rag` — searching an OpenAPI/Swagger document as a graph        | [rag.md](./references/rag.md)           |
+
+## The short version
+
+```
+zen init                              scaffold a project here, pick a model
+zen check                             validate everything before spending a turn
+zen run                               the TUI
+zen run "what changed?"               one answer, this directory as the workspace
+zen inspect --open                    what the model was actually given
+zen key ls --check                    which credentials still work
+zen models test <ref>                 whether one model actually answers
+zen models pick --embedding           the first embedder that does, on stdout
+```
+
+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.
+
+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
+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

@@ -0,0 +1,88 @@
+# 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.
+
+## `zen check`
+
+```
+zen check [name|dir] [--project <name|dir>] [--no-sandbox] [--no-models] [--strict] [--quiet]
+```
+
+Aliases: `validate`, `doctor`.
+
+Reads the project the way a run does and reports **in full**. Unlike a run it
+does not stop at the first problem: the report lists everything it found, each
+with a code, a location and the fix for it.
+
+| Flag                    | Meaning                                             |
+| ----------------------- | --------------------------------------------------- |
+| `--project <name\|dir>` | Which project                                       |
+| `--no-sandbox`          | Skip building and smoke-testing the container image |
+| `--no-models`           | Skip asking each model to answer                    |
+| `--strict`              | Warnings count as failure                           |
+| `--quiet`               | The findings and nothing else                       |
+
+The bare argument is a directory if one is there and a registered project name
+otherwise, and it needs no `zenera.json`, so an unregistered directory can be
+checked too. A word that is neither is a usage error (exit 2), not a report.
+
+### What it checks
+
+- `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.
+- 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.
+- 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
+  is an error (`model.refused`, `embedding.refused`); a model that never answered
+  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
+  in it, against a temporary directory rather than your workspace. No container
+  engine at all is a warning, not an error.
+
+### Findings
+
+Each is `severity` (error, warning, note), a `code`, a `where` and a `message`,
+with the fix alongside. Codes are namespaced by what went wrong:
+
+```
+root.missing          project.unregistered   config.missing / .invalid / .shadowed
+house-rules.missing   agent.duplicate        agent.no-instructions
+entry.unknown         entry.ambiguous        prompt.missing / .empty / .outside
+tools.unresolved      tools.empty / .none    handoff.self / .unknown
+fork.unknown          skills.missing         skill.unloadable / .no-skill-md
+skills.no-catalog     skills.unreachable     skill.unused
+assets.missing        assets.overbroad       sandbox.dockerfile.missing
+sandbox.build         sandbox.smoke          sandbox.start / .unchecked
+provider.invalid      model.none             model.unresolvable
+model.refused         model.unreachable      model.unusable
+embedding.refused     embedding.unreachable  embedding.unusable
+credential.*          service.credential
+```
+
+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
+least one warning. `5` if the container engine itself is missing when something
+required it.
+
+### What it cannot catch
+
+Combinations that are only rejected by the provider at the first call. The
+known one: **OpenAI reasoning and tools only meet on the responses API.** A
+model with `reasoningEffort` and tools on the default chat-completions API is a
+valid configuration that fails at runtime with _"Function tools with
+reasoning_effort are not supported … in /v1/chat/completions"_. Set
+`api: responses` alongside it.

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

@@ -0,0 +1,111 @@
+# Mock APIs — `zen faker`
+
+```
+zen faker <serve|build|cache> [spec...]
+```
+
+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
+operation a **model writes a Python generator**, which is self-tested inside a
+container and cached on disk. Answers are therefore schema-correct and
+plausible, not `"string"` repeated.
+
+## Subcommands
+
+| Command           | What it does                                          |
+| ----------------- | ----------------------------------------------------- |
+| `serve <spec...>` | Serve the documents. Generators are written on demand |
+| `build <spec...>` | Write every generator now and exit                    |
+| `cache ls\|clear` | What has been generated, or throw it away             |
+
+```
+zen faker serve openapi.yaml
+zen faker serve api/*.yaml --port 9000 --seed 7
+zen faker build openapi.yaml --concurrency 8
+zen faker cache clear
+```
+
+`build` is the one to run in CI or before a demo: it pays for every generator up
+front and exits non-zero, with a table, if any could not be written.
+
+## Options
+
+| Flag                | Default               | Meaning                                         |
+| ------------------- | --------------------- | ----------------------------------------------- |
+| `--port <n>`        | `8787`                | Port to listen on                               |
+| `--host <h>`        | `127.0.0.1`           | Anything else is reachable off-machine          |
+| `--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 |
+| `--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                                    |
+
+Credentials come from the `zen` keyring — see [keys.md](keys.md).
+
+## Serving
+
+Binds the loopback address by default. On start it prints a table per document:
+paths, methods, and how many operations have a response schema and therefore get
+a generator.
+
+| Endpoint          | Answers                   |
+| ----------------- | ------------------------- |
+| `/__faker/routes` | Every route it will serve |
+| `/__faker/health` | Whether it is up          |
+
+Response headers:
+
+| Header              | Meaning                                               |
+| ------------------- | ----------------------------------------------------- |
+| `x-faker-operation` | The `operationId` that answered                       |
+| `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
+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
+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.
+
+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.
+
+## The cache
+
+Under `~/.zenera/neo/faker/generators/<key>/`, one directory per operation. A
+generator that a model gave up on is remembered, 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 operation.
+
+`zen faker cache clear` removes the generators and the container together. They
+have to go together: the container's name is a hash of its configuration, so
+deleting the directory alone would leave a stopped container bind-mounted onto a
+directory that no longer exists, and every generator would fail with
+`python3: can't open file '/workspace/generators/…/gen.py'`.
+
+## Documents it accepts
+
+Swagger 2 and OpenAPI 3.0/3.1, JSON or YAML, `$ref`s resolved. Several documents
+can be served at once. OpenAPI 3.0 constructs are translated to JSON Schema
+2020-12 on the way in (`nullable`, boolean `exclusiveMinimum`, Draft-4 array
+`items`), and a `pattern` written as a JavaScript regex literal (`/^[a-z]+$/`)
+is unwrapped rather than being treated as an unsatisfiable string.