@zenera/cli 1.1.40 → 1.1.42

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

@@ -33,7 +33,7 @@ zen version
 
 zen meta     <run|prompts|resume|model|dataset> [project] [args]
 
-zen gym      <serve|build|cache|model> [spec...]
+zen gym      <serve|build|cache|world|model> [spec...]
 zen rag      schema <index|restore|ready|search|list|grep|trace|show|stats> [spec...]
 zen rag      docs <index|restore|ready|search|list|grep|show|stats> [path...]
 ```

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

@@ -103,7 +103,7 @@ A real environment variable always beats the keyring.
     projects.json         the registry: name -> directory
     keys.json             credentials (0600)
     keys/                 key files, for providers that hold a file
-    gym/                generator cache for `zen gym`
+    gym/                handlers, worlds, docs indexes and agent reports for `zen gym`
 
 <project>/
     zenera.json           { version, name }

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

@@ -1,126 +1,155 @@
 # Agent API environments - `zen gym`
 
 ```
-zen gym <serve|build|cache|model> [spec...]
+zen gym <serve|build|cache|world|model> [spec...]
 ```
 
 Provided by `@zenera/gym` - `npm i -g @zenera/gym` if
 `zen gym` 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.
+Serves a mock API from OpenAPI/Swagger documents, backed by a **stateful
+world**. For each operation an agent writes a **TypeScript handler** (the
+mechanics: which type, which filter, what a write changes), judged before it is
+cached. Content comes from a second agent that fills the world on first read,
+following an optional **story** (`--story`) and drawing on **reference
+documents** (`--docs`). Lists and gets agree, writes are seen by later reads,
+and several `zen gym` processes given the same story share one world. No
+container engine is needed.
+
+## Inputs
+
+Each is a file, a directory or a quoted pattern, and each is repeatable.
+
+| Input               | What it is                                                            | How agents get it           |
+| ------------------- | --------------------------------------------------------------------- | --------------------------- |
+| `spec…`, `--schema` | API documents: `.yaml`/`.yml`/`.json` declaring `swagger:`/`openapi:` | API graph and types         |
+| `--story`           | the state of the world: people, what is happening, what is not        | quoted whole in prompts     |
+| `--docs`            | reference material: knowledge base, guides, runbooks                  | searched (indexed at start) |
+
+A directory given as `--schema` is walked and only real API documents are kept,
+so a folder of mixed JSON — or an API index somebody built — works. A Markdown
+file given as a schema is refused with a hint; so is an API document given as
+`--story` or `--docs`. Quote globs (`--docs 'kb/*.md'`) so the shell leaves them
+to gym.
 
 ## 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                  |
-| `model [ref]`     | Show or set the model; `--clear` forgets the stored choice |
+| Command               | What it does                                                    |
+| --------------------- | --------------------------------------------------------------- |
+| `serve [spec...]`     | Index everything, then serve. Handlers are written on first use |
+| `build [spec...]`     | Index everything and write every handler, then exit             |
+| `cache ls\|clear`     | Handlers, bindings and indexes; `clear` keeps worlds            |
+| `world ls\|rm <name>` | List worlds, or delete one                                      |
+| `model [ref]`         | Show or set the chat model; `--embedding <ref\|none\|clear>`    |
 
 ```
 zen gym serve openapi.yaml
-zen gym serve api/*.yaml --port 9000 --seed 7
-zen gym build openapi.yaml --concurrency 8
-zen gym cache clear
+zen gym serve --schema specs/ --story world.md --docs kb/
+zen gym serve specs/mail.yaml     --story world.md --port 8787
+zen gym serve specs/calendar.yaml --story world.md --port 8788   # same world as above
+zen gym serve api.yaml --world demo --reset                      # a named world, emptied
+zen gym build --schema 'api/*.yaml' --story world.md --docs kb/ --concurrency 8
+zen gym world ls
 ```
 
-`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.
+`build` is the one to run in CI or before a demo: it pays for every handler up
+front and exits non-zero, with a table, if any could not be written. Content is
+still made lazily, on first read.
 
 ## 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/gym` | 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                                    |
+| Flag                    | Default             | Meaning                                                  |
+| ----------------------- | ------------------- | -------------------------------------------------------- |
+| `--schema <path>`       | -                   | API documents, in addition to bare arguments             |
+| `--story <path>`        | -                   | The state of the world                                   |
+| `--docs <path>`         | -                   | Reference material                                       |
+| `--world <name\|file>`  | one per story       | Which world; a name is under `<cache>/worlds/`           |
+| `--reset`               | -                   | Start from an empty world                                |
+| `--model <ref>`         | recommended         | Which model writes handlers and content                  |
+| `--embedding <on\|ref>` | off (wording)       | Also search `--docs` by meaning; `on` = configured model |
+| `--port <n>`            | `8787`              | Port to listen on                                        |
+| `--host <h>`            | `127.0.0.1`         | Anything else is reachable off-machine                   |
+| `--cache <dir>`         | `~/.zenera/neo/gym` | Handlers, worlds, indexes, reports                       |
+| `--seed <n>`            | -                   | Same request, same randomness                            |
+| `--attempts <n>`        | `5`                 | Failed tests per handler before giving up                |
+| `--concurrency <n>`     | `4`                 | Handlers written at once                                 |
+| `--timeout <s>`         | `30`                | Seconds a handler may run, agent time aside              |
+| `--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).
-Model selection: `--model`, `ZENERA_GYM_MODEL`, `~/.zenera/neo/gym.json`,
-then the best model the available keys support.
+Chat model: `--model`, `ZENERA_GYM_MODEL`, `zen gym model <ref>`, then the best
+model the available keys support. It must call tools; for OpenAI reasoning
+models use the Responses API, `openai/responses:<id>`. Embedding model: off by
+default, so `--docs` are searched by wording (full-text). `--embedding <ref>`
+searches by meaning too with that model; `--embedding on` takes
+`ZENERA_GYM_EMBEDDING`, then `zen gym model --embedding <ref>`, then the first
+provider with a key that offers one. Without the flag those settings do nothing.
 
 ## 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.
+Binds the loopback address by default. On start it prints a table per document,
+then the model, story, docs (and how they are searched) and the world file.
 
-| Endpoint        | Answers                   |
-| --------------- | ------------------------- |
-| `/__gym/routes` | Every route it will serve |
-| `/__gym/health` | Whether it is up          |
+| Endpoint        | Answers                                      |
+| --------------- | -------------------------------------------- |
+| `/`             | Contents page, with a Run form per operation |
+| `/__gym/routes` | Every route it will serve                    |
+| `/__gym/health` | Whether it is up                             |
 
 Response headers:
 
 | Header            | Meaning                                               |
 | ----------------- | ----------------------------------------------------- |
 | `x-gym-operation` | The `operationId` that answered                       |
-| `x-gym-cache`     | `hit` or `miss` - whether this call cost a model turn |
+| `x-gym-cache`     | `hit`, `miss` or `regenerated` - the handler's origin |
 
 Gym provides simulation, not task scoring, rewards, or a training loop.
 
 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.
+`key|token|secret|password|credential` never reach a handler.
 
 ## What "correct" means here
 
-A generator is judged on two synthetic probes: the body validates against the
+A handler is judged by `test_handler` on synthetic probes, in a throwaway copy
+of the world with schema-sampled content: 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.
+comes back in the answer (`GET /users/12324` must return `user_id: 12324`).
+Paged operations are walked: the cursor must advance and end. And every record
+type the handler touches must live where earlier handlers put it.
 
-Query parameters are deliberately not enforced: `?source=realtime`, `?page_size`
-and `?cursor` are controls, and their names collide with unrelated response
-fields.
+## Bindings: where each type lives
 
-Probes are synthetic on purpose - real request bodies never reach a prompt.
+Handlers name records by schema type (`ctx.lookup('Message', id)`). The first
+handler to use a type binds it to a collection and id field; later handlers are
+told the binding and held to it, so every operation on a resource reads the same
+records. Bindings are add-only and machine-wide, keyed by the documents' types;
+`cache clear` forgets them.
 
-## The cache
+## The cache, the world, the reports
 
-Generators live in the machine's shared cache, `~/.zenera/neo/cache/gym-generator/`,
-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
-operation.
+Handlers live in the machine's shared cache, `~/.zenera/neo/cache/gym-handler/`,
+keyed by the operation's shape (descriptions and examples excluded) - not by the
+story, since a handler holds no content. A cached handler whose bindings no
+longer hold is rebuilt. Two processes needing the same handler build it once.
 
-`~/.zenera/neo/gym/` is the container's workspace, and scratch: a cache hit is
-copied into it, because the container can only run what is under its mount.
+Worlds live in `<cache>/worlds/`. With a story and no `--world`, the world is
+named after the story's content, so editing the story starts a new world (gym
+says so). `cache clear` never touches worlds; `world rm` and `serve --reset` do.
 
-`zen gym cache ls` lists what has been generated. `zen gym cache clear`
-removes the generators, the workspace and the container together. They have to
-go together: the container's name is a hash of its configuration, so deleting
-the workspace 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'`.
+The docs index lives in `<cache>/indexes/`, keyed by the docs' content and the
+embedding model; a restart reuses it.
 
-`zen cache ls --kind gym-generator` reaches the same entries from the other
-side, along with everything else this machine has cached.
+Every agent run leaves an HTML report in `<cache>/reports/`; failed builds
+leave a markdown report in `<cache>/builds/`.
 
 ## 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.
+can be served at once, as long as no two define the same route (two versions of
+one API: serve them from two processes with the same `--world`). 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.

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

@@ -32,6 +32,16 @@ dereference: having seen the shape and spotted the loop, you open the three
 nodes that explain it, whole and untruncated. The index is cheap and you only
 pay for what you open.
 
+For a whole-run audit, follow **zen-analyze-run**: reuse the graph, begin with
+the outcome, batch selected evidence nodes, and expand backwards only for a
+specific unresolved criterion or anomaly. Labels locate evidence; exact
+arguments, returned facts and success claims require the relevant payload.
+Stop when the evidence is sufficient, not after opening every node.
+Start with supporting or contradicting results; select decision nodes only
+after identifying a remaining evidence gap or material attribution question.
+Keep each retrieved node part and its output location, and search that copy
+for all quotations rather than fetching it once per phrase.
+
 `ask` is the last resort, not the first move: it spends a model call to ask the
 run's own model why it did what it did. Open the node first - most questions are
 answered by reading what it was given.
@@ -278,6 +288,11 @@ zen inspect node n11 --part thinking --part text --dir <run dir>
 zen inspect node n11 --full --dir <run dir>
 ```
 
+Those are explicit deep-inspection options, not whole-run audit defaults.
+Prefer `--part call` for LLM tool arguments and `--part text` for its public
+answer. Open `thinking` only when unresolved attribution would change a
+recommendation; self-explanations do not prove causation.
+
 An `llm_call` carries two more parts read out of its request, held back the
 same way: `tools`, the tool names that call was offered, one per line, and
 `messages`, the conversation it saw, one clipped line per message with its

package/templates/editor/.github/skills/zen-inspect-ask/SKILL.md

@@ -26,6 +26,12 @@ zen inspect ask <llm-node-id> --question-file <question file> --dir <run-dir>
 Each non-interactive call is a **fresh replay**. It does not remember your
 previous question. A follow-up must restate what it builds on.
 
+For a whole-run audit, **zen-analyze-run** owns the replay budget: default
+zero, at most two invocations including retries and second opinions. Its
+budget and uncertainty gate take precedence over the retry suggestions below.
+Do not replay a healthy run or ask about a cause already established by
+recorded evidence.
+
 ## 1. Rule out the cheap causes first
 
 A "why didn't you" question is only about instructions if the model could have
@@ -242,18 +248,21 @@ only a finding once the sentence is confirmed.
     ```sh
     zen inspect node n9 --part request --dir <run-dir> | grep -F 'Do not fork a sequence'
     ```
+    Reuse a request already retrieved; fetch it once and check all quotes
+    against that copy. A match in a project file alone does not prove delivery.
     A quote that is not there is invented - discard the answer, not just the
-    quote. Ask once more; if it invents again, ask another model (step 4).
+    quote. Retry only within the caller's budget; otherwise report that
+    attribution remains unresolved.
 2. **Find every copy.** The blocker often exists twice - once in a house rule,
    once in a skill with a softer tail. Grep the whole request for a distinctive
    phrase of it, then grep the project's `agents/` tree for the file to edit.
 3. **Check it is the project's file.** `fork-instructions.md`,
    `memory-instructions.md`, `tools-instructions.md` are zen's own copies; load
    **zen-instructions** before changing where that rule lives.
-4. **Second opinion when the self-report is thin.** The model that made the
-   call rationalises; another model reading the same replay often names the
-   conflict more plainly: `--model <ref>`. Ask the identical question: the same
-   question file.
+4. **Second opinion only when justified.** A thin answer or `no instruction -
+my own default` does not itself justify more replay. In a whole-run audit,
+   use a second opinion only after an invented quote, and within the two-call
+   total budget: `--model <ref>`, the identical question file.
 5. **Reproduce.** After the edit, rerun the case and check the graph: the
    `tools` header row shows `fork x1` or `memory_search x1` where it did not
    before. The answer predicted a fix; the graph confirms it.

package/templates/editor/.github/skills/zen-review/scripts/check-paths.sh

@@ -36,8 +36,12 @@ NOISE='^(and/or|he/she|his/her|input/output|read/write|w/o|n/a|N/A|24/7|km/h)$|^
 # A url, stripped before tokenising rather than filtered after it — the token
 # regex reads `https://acme.dev/docs` as `//acme.dev` *and* `/docs`, and the
 # second half is indistinguishable from a real absolute path once it is alone.
+#
+# A meta agent command, `zen meta run /spec-edit`, goes the same way: its
+# `/<name>` is a stored prompt, not a file the running agent is told to open.
 strip_urls() {
-    sed -E 's#[a-zA-Z][a-zA-Z0-9+.-]*://[^][ )"'"'"'`>]*##g' "$1"
+    sed -E -e 's#[a-zA-Z][a-zA-Z0-9+.-]*://[^][ )"'"'"'`>]*##g' \
+        -e 's#(zen meta run( [A-Za-z0-9_.-]+)?) /[A-Za-z0-9_-]+#\1#g' "$1"
 }
 
 # The three trees §2.5 names, prose only: a skill's own script is code the

package/templates/editor/.github/skills/zen-spec-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zen-spec-sync
-description: Running `/spec-sync-project` as an incremental pass - the committed `.spec-sync` baseline of what the last pass applied, how to scope a pass from the specification and feedback diffs and from what moved in the project itself, the five checks a narrow pass may never skip, which skills a pass must load before editing (`zen-instructions` for any house rule it touches), the iteration history format, and why the baseline is written last. Load before every `/spec-sync-project`, including the first one on a project that has no baseline yet.
+description: Running `/spec-sync-project` as an incremental pass - the committed `.spec-sync` baseline of what the last pass applied, how to scope a pass from the specification and feedback diffs and from what moved in the project itself, which input wins when they disagree, the five checks a narrow pass may never skip, which skills a pass must load before editing (`zen-instructions` for any house rule it touches), the iteration history format, and why the baseline is written last. Load before every `/spec-sync-project`, including the first one on a project that has no baseline yet.
 ---
 
 # Syncing a project with its specification, one change at a time
@@ -103,9 +103,64 @@ editing anything, and report it in the chat as the pass's scope.
    covers it, and you say which line, or it does not, and it is an **extra**
    reported under `➕`.
 
+## When the inputs disagree
+
+Two inputs can ask for different things - a ticked answer and a later edit to
+the same specification line, say. Decide by this order, highest first, and do
+not weigh them again:
+
+1. **The user's message that started this pass**, where it says more than the
+   command name. It is the newest and most direct statement of intent there is.
+2. **`SPECIFICATION.md` as it stands now.** An edit to the specification is
+   made on purpose and after the questions were written, so it outranks them.
+3. **An answer ticked in `SPECIFICATION-FEEDBACK.md`** and not yet folded in.
+4. **What the last pass left open.**
+
+A ticked answer that the current specification text contradicts was
+**superseded**, not ignored: do not fold its text back in over the newer line.
+Strike the question with one line naming the specification line that replaced
+it, and say in the chat that you did.
+
+Facts outrank all four. `zen --version` decides the sandbox pin (below); a
+specification line asking for something impossible is a question, not an order.
+Where the order above does not decide, build what the higher-ranked input asks
+for, write **one** question in `SPECIFICATION-FEEDBACK.md`, and carry on.
+
+### Do not reconstruct intent
+
+The diffs say what changed. The order above says what wins. A feedback question
+covers whatever is left. Do not use anything else to work out _why_ somebody
+changed something: no session history or chat transcripts, no file timestamps,
+no `git log` or `git blame`, no older history entries beyond the one `applied:`
+names. If a pass catches itself guessing at what the human meant, that guess is
+the text of a question, and the pass moves on.
+
+### The `zen` version in the specification
+
+The `@zenera/cli` and `@zenera/rag` pin in `sandbox/Dockerfile` always follows
+`zen --version` - `zen check` warns on any other number, older or newer. Nothing
+outranks that, not a specification line and not the user's message: the image
+cannot hold a `zen` other than the one building it. If a version was asked for
+that is not the one in hand, say so in the chat - `zen` has to be upgraded on the
+host first.
+
+When `SPECIFICATION.md` names an exact version other than `zen --version`, pin
+the Dockerfile to `zen --version` and keep **one** `✏️` question open for that
+line. If one is already open, update it instead of adding another. Offer these
+answers:
+
+- State the pin without a number - "pinned to the `zen` version that builds the
+  image" - so the next upgrade does not raise the question again
+  _(recommended)_.
+- Replace the number with the one `zen --version` reports.
+- Keep the number, upgrade `zen` on the host to it, and run the pass again.
+
+That is the whole of the work. A version mismatch is not a reason to look for
+anything else.
+
 ## The five checks a narrow pass may never skip
 
-However small the diff:
+However small the diff - with the one narrowing for a spec-only pass below:
 
 1. **`zen check` passes.** Run it before the first edit and again after the
    last.
@@ -131,6 +186,28 @@ However small the diff:
    it, the history entry claims it, and the baseline records it as applied.
    Specification-driven rules go in a topic file of the project's own beside it.
 
+### The spec-only pass
+
+A pass qualifies when **all** of the following hold:
+
+- the implementation diff (input 4) is empty
+- the pass edits nothing except `SPECIFICATION.md`, `SPECIFICATION-FEEDBACK.md`
+  and the `@zenera/*` pin in `sandbox/Dockerfile`
+- no changed specification hunk names an agent, tool, model, embedding, skill,
+  house rule, handoff, memory, index, asset or setup step
+
+A pass like that changes nothing an agent reads, so it has no capability
+obligation to re-check. Checks 4 and 5 drop out: load no capability skill and no
+`zen-instructions`. `zen check` still runs before and after, and it still
+reports `rules.stale`. Check 2 shrinks to `scripts/_setup.sh --check`, which
+must report every step `skipped`. If it reports anything else, run
+`scripts/_setup.sh` in full as written. Check 3 shrinks to the §9
+**Specification** group and the groups covering any file the pass edited.
+
+Decide this before loading anything, and say it in the chat - "spec-only pass:"
+followed by the reason. If any edit turns out to reach further, the pass is no
+longer spec-only: run all five checks.
+
 A narrow diff narrows reading and editing. It does not narrow verification.
 
 ## What else an incremental pass still owes

package/templates/project/agents/memory-instructions.md

@@ -26,6 +26,20 @@ Search before starting work that costs more than one cheap read or call:
 Do not repeat the same search in different words. Search again only when the
 question has changed.
 
+When a request involves several distinct subjects, search for all of them in
+parallel: send one `memory_search` per subject in the same turn rather than one
+after another. Likewise, load every node you need in the same turn. Parallel
+searches must ask different questions, not rephrase one.
+
+### Call memory tools silently
+
+You MUST NOT write any text before a `memory_*` call. Do not announce, explain,
+or summarize memory calls, such as "I'm going to check for prior work". The
+tool call is shown to the user on its own. This overrides the general rule to
+say what you are about to do before tool calls: when a turn contains only
+`memory_*` calls, write nothing; when it mixes them with other tools, describe
+only the other calls.
+
 ### Choose the retrieval tool
 
 | Need                                           | Tool            |

package/templates/project/agents/prompts/default.md.tmpl

@@ -17,3 +17,63 @@ Anything under `/assets` is reference material: read it, search it, and do not
 try to change it.
 
 Say what you changed.
+
+<!-- ===== BEGIN: unconfigured-agent disclaimer (delete this block once the agent is configured) ===== -->
+
+## This agent is not configured yet
+
+This agent has not been set up for any specific task yet. It only has the
+generic defaults above, so it is not expected to do anything particularly
+useful on its own.
+
+When the user greets you ("hi", "hello"), asks what you can do, asks who you
+are, or asks how to get started, tell them plainly:
+
+- This agent is not configured yet to do anything useful.
+- To teach it specific tasks, they should use the **Zenera Meta Agent**,
+  which can configure this agent's prompts, tools, knowledge and workflows.
+  It ships with the `zen` CLI:
+  - What it is and how it works:
+    https://github.com/zenera-ai/ZeneraNeo#what-is-the-meta-agent
+  - The CLI and its commands:
+    https://github.com/zenera-ai/ZeneraNeo/tree/main/packages/cli
+  - The project home: https://zenera.ai
+
+Then give them these steps to get started. The commands run in a terminal on
+their machine, from the project directory, not here:
+
+1. Pick the model the meta agent uses (once per machine):
+   `zen meta model --pick`
+2. Describe what this agent should do in `SPECIFICATION.md`: its purpose,
+   models, agents, tools, knowledge and memory. Edit the file by hand, or have
+   the meta agent write it from a plain request:
+   `zen meta run /spec-edit "<what to add, change or remove>"`
+3. Have the meta agent build the system from the specification:
+   `zen meta run /spec-sync-project`
+4. If the meta agent has questions, it writes them to
+   `SPECIFICATION-FEEDBACK.md`. Answer them there, then apply the answers:
+   `zen meta run /spec-apply-feedback`
+5. Validate the project and try it: `zen check`, then `zen run "<request>"`.
+   Review a run with `zen inspect`.
+
+To find out more, `--help` works on every command and subcommand:
+
+- `zen meta --help` lists everything the meta agent can do: `run`,
+  `prompts`, `resume`, `model`, `dataset` and `finetune`, with examples.
+- `zen meta run --help` lists the options for a run and the stored prompts,
+  the `/<name>` commands used above.
+  `zen meta prompts` lists the stored prompts on their own.
+- `zen meta dataset --help` and `zen meta finetune --help` cover building an
+  evaluation dataset and tuning the project against it.
+- `zen meta run "<question>"` asks the meta agent anything about the project,
+  for example `zen meta run "what does this project do?"`.
+
+For teams that need more, mention **ZeneraLab**, Zenera's enterprise-grade
+platform (https://zenera.ai). It has all of this built into a UI, where users
+can build enterprise-grade agentic solutions, integrate them with any legacy
+system, and train, fine-tune, optimize, test and monitor their agents.
+
+Keep that answer short and friendly. You can still help with simple requests
+in the workspace if asked directly.
+
+<!-- ===== END: unconfigured-agent disclaimer ===== -->