@zenera/cli 1.1.34 → 1.1.35

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.34",
+    "version": "1.1.35",
     "description": "Command-line front end for @zenera/neo: agentic projects you can run, share and commit.",
     "keywords": [
         "agents",
@@ -54,8 +54,8 @@
         "@google/genai": "^2.30.0",
         "@inkjs/ui": "^2.0.0",
         "@openrouter/sdk": "^1.4.25",
-        "@zenera/neo": "^1.1.34",
-        "@zenera/view": "^1.1.34",
+        "@zenera/neo": "^1.1.35",
+        "@zenera/view": "^1.1.35",
         "google-auth-library": "^10.0.0",
         "ink": "^7.1.1",
         "openai": "^6.0.0",

package/templates/editor/.github/copilot-instructions.md

@@ -139,6 +139,26 @@ not do, and a `.spec-sync/baseline/` whose `manifest.txt` no longer matches its
 files. Both are reported, not quietly repaired - rewriting the manifest asserts
 a pass that never happened.
 
+### 0.2 `zen` is a black box
+
+`zen` is the tool you drive, not the code you are working on. What it does is
+what the `zen-cli` skill and its own output say it does. So:
+
+- Never read, list or search `zen`'s installed code or data: the `@zenera/*`
+  packages under `$(npm root -g)`, and `~/.zenera`.
+- Never read `.tmp/logs/meta.*`. Those are other runs of the meta agent -
+  earlier ones, or one still going - not evidence about this project.
+- Never probe a model provider or gateway yourself: no `curl` at its endpoint,
+  no `node -e` against an SDK, no throughput test. `zen models test <ref>` is
+  the probe.
+- A slow command is not a failed one. It has failed when it exits non-zero, or
+  when its log has not grown for 10 minutes. Embedding a large corpus takes
+  hours, and the progress line says how many.
+- When a `zen` command fails, or does something its skill does not describe,
+  quote the command and the line it printed in your answer - and in
+  `SPECIFICATION-FEEDBACK.md` during a `/spec-sync-project` pass - then go on
+  with the next step. Do not look for the cause.
+
 ---
 
 ## 1. Mental model

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

@@ -48,6 +48,9 @@ Read, in this order, and do not edit until all of it is read:
 6. `SPECIFICATION-FEEDBACK.md`, if it exists - do not re-raise something already
    open there.
 
+Never read `.tmp/logs/meta.*` - those are other runs of this prompt, not
+evidence - nor anything of `zen`'s own (copilot instructions §0.2).
+
 On an incremental pass this list narrows to the artefacts the scope implicates,
 and to the changed hunks of the specification rather than all of it. The
 narrowing is a claim: name what you skipped and why the diff does not reach it.
@@ -382,10 +385,14 @@ answer, fold its text into `SPECIFICATION.md` yourself, and say so in the chat.
 After `zen check` passes, run `scripts/_setup.sh` yourself. A pass is not done
 until it has run to completion in this session.
 
-It is slow - an embedding index is minutes, not seconds - so start it in the
-background and follow the logs instead of waiting blind:
+It is slow - embedding a large corpus is hours, and the progress line says how
+many - so start it in the background and follow the logs instead of waiting
+blind:
 
 - Tail `.tmp/logs/setup-*.log` and check the output artefact is still growing.
+- **Slow is not failed.** A step has failed when it exits non-zero, or when its
+  log has not grown for 10 minutes. A long estimate is the answer to how long
+  the step takes, not a problem to investigate.
 - **Wait in a loop, never in one long sleep.** Sleep at most 30 seconds at a
   time, then check the log and say what it shows, and repeat until the step
   finishes. A single long block makes the run unwatchable and hides a failure
@@ -397,6 +404,10 @@ background and follow the logs instead of waiting blind:
 - On failure, read that step's log, fix the cause, and run `scripts/_setup.sh`
   again - re-running is the fix path, not a reset. If the same step fails twice
   for the same reason, stop and raise it in `SPECIFICATION-FEEDBACK.md`.
+- The cause you fix is in the project: the step's script, its inputs,
+  `agents.yaml`. When the log points inside `zen` itself, do not go looking -
+  quote the command and the line in `SPECIFICATION-FEEDBACK.md`, report the step
+  as failed, and go on to §7.
 - Prove re-entrancy: once it has succeeded, run `scripts/_setup.sh` once more and
   check that every step reports `skipped` rather than rebuilding.
 - Prove the dry run: `scripts/_setup.sh --check` must then report every step

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

@@ -26,7 +26,7 @@ zen rag schema index <spec...> [--embedding <ref>] [-o <dir>] [--batch <n>]
 | ------------------- | ------------- | ------------------------------------------------------------ |
 | `--embedding <ref>` | -             | Which embedder makes the vectors. Omit it to see the choices |
 | `-o`, `--out <dir>` | `./schema-db` | Where the index goes; `$ZEN_SCHEMA_DB` if set                |
-| `--batch <n>`       | `96`          | Texts per embedding request, and how often progress prints   |
+| `--batch <n>`       | model's own   | Texts per embedding request. `gemini-embedding-*` takes 1    |
 | `--no-sources`      | -             | Keep no copy of the documents in the index                   |
 | `--quiet`           | -             | No narration                                                 |
 
@@ -385,7 +385,7 @@ zen rag docs index <path...> [--embedding <ref>] [-o <dir>] [--chunk-tokens <n>]
 | -------------------- | ----------- | ------------------------------------------------------------ |
 | `--embedding <ref>`  | -           | Which embedder makes the vectors. Omit it to see the choices |
 | `-o`, `--out <dir>`  | `./docs-db` | Where the index goes; `$ZEN_DOCS_DB` if set                  |
-| `--batch <n>`        | `96`        | Texts per embedding request                                  |
+| `--batch <n>`        | model's own | Texts per embedding request. `gemini-embedding-*` takes 1    |
 | `--chunk-tokens <n>` | `384`       | Target chunk size                                            |
 | `--quiet`            | -           | No narration                                                 |
 

package/templates/editor/.github/skills/zen-rag-docs/SKILL.md

@@ -22,16 +22,16 @@ hits for `limit` are not an answer; the eight lines around one of them are.
 zen rag docs <index|restore|ready|search|list|grep|show|stats> [path...]
 ```
 
-| Command   | Answers                                    | Embedder? | Typical |
-| --------- | ------------------------------------------ | --------- | ------- |
-| `index`   | builds the thing                           | yes       | minutes |
-| `restore` | _put the vectors back_                     | **yes**   | minutes |
-| `ready`   | _can this index answer at all?_            | no        | instant |
-| `search`  | _where does this corpus talk about X?_     | **yes**   | seconds |
-| `list`    | _what documents/headings/tables are here?_ | no        | instant |
-| `grep`    | _does the string X appear anywhere?_       | no        | instant |
-| `show`    | _print this section, verbatim_             | no        | instant |
-| `stats`   | _what is in this index?_                   | no        | instant |
+| Command   | Answers                                    | Embedder? | Typical          |
+| --------- | ------------------------------------------ | --------- | ---------------- |
+| `index`   | builds the thing                           | yes       | minutes to hours |
+| `restore` | _put the vectors back_                     | **yes**   | minutes to hours |
+| `ready`   | _can this index answer at all?_            | no        | instant          |
+| `search`  | _where does this corpus talk about X?_     | **yes**   | seconds          |
+| `list`    | _what documents/headings/tables are here?_ | no        | instant          |
+| `grep`    | _does the string X appear anywhere?_       | no        | instant          |
+| `show`    | _print this section, verbatim_             | no        | instant          |
+| `stats`   | _what is in this index?_                   | no        | instant          |
 
 Only `search` ranks, and only `search` costs a network round trip - it embeds
 the query before it can compare anything. The other four read `outline.json`
@@ -199,7 +199,7 @@ would land on the same name are deduped rather than merged.
 | -------------------- | ----------- | ------------------------------------------------------------ |
 | `--embedding <ref>`  | -           | Which embedder makes the vectors. Omit it to see the choices |
 | `-o`, `--out <dir>`  | `./docs-db` | Where the index goes; `$ZEN_DOCS_DB` if that is set          |
-| `--batch <n>`        | `96`        | Texts per embedding request, and how often progress prints   |
+| `--batch <n>`        | model's own | Texts per embedding request. `gemini-embedding-*` takes 1    |
 | `--chunk-tokens <n>` | `384`       | Target chunk size. Leave it alone unless you have a reason   |
 | `--quiet`            | -           | No narration                                                 |
 
@@ -210,9 +210,13 @@ a real environment variable always wins.
 ### What it prints
 
 A per-document table (lines, sections, tables, chunks) with a total row, a line
-per skipped file with the reason, then a progress line per batch. **stdout is
-the output directory and nothing else**, so `DIR=$(zen rag docs index …)` works;
-everything else is stderr.
+per skipped file with the reason, then a progress line every few seconds:
+`embedded 22416/242175 · 9% · 8m50s · ~1h26m left`. **That estimate is how
+long the build takes, not a sign that it is stuck.** Time is chunks divided by
+throughput, and a `gemini-embedding-*` model takes one text per request, so a
+corpus of a few hundred thousand chunks is hours. **stdout is the output
+directory and nothing else**, so `DIR=$(zen rag docs index …)` works; everything
+else is stderr.
 
 This is the one command here that spends money and time: it embeds every chunk.
 While it runs, the output directory narrates itself - `README.md` is a live

package/templates/editor/.github/skills/zen-rag-schema/SKILL.md

@@ -21,17 +21,17 @@ word "password" appears in forty places that are not the one you want.
 zen rag schema <index|restore|ready|search|list|grep|trace|show|stats> [spec...]
 ```
 
-| Command   | Answers                                | Embedder? | Typical |
-| --------- | -------------------------------------- | --------- | ------- |
-| `index`   | builds the thing                       | yes       | minutes |
-| `restore` | _put the vectors back_                 | **yes**   | minutes |
-| `ready`   | _can this index answer at all?_        | no        | instant |
-| `search`  | _what is this API's way to do X?_      | **yes**   | seconds |
-| `list`    | _what methods/types/fields are there?_ | no        | instant |
-| `grep`    | _does the string X appear anywhere?_   | no        | instant |
-| `trace`   | _which call can reach this field?_     | no        | instant |
-| `show`    | _print exactly these things_           | no        | instant |
-| `stats`   | _what is in this index?_               | no        | instant |
+| Command   | Answers                                | Embedder? | Typical          |
+| --------- | -------------------------------------- | --------- | ---------------- |
+| `index`   | builds the thing                       | yes       | minutes to hours |
+| `restore` | _put the vectors back_                 | **yes**   | minutes to hours |
+| `ready`   | _can this index answer at all?_        | no        | instant          |
+| `search`  | _what is this API's way to do X?_      | **yes**   | seconds          |
+| `list`    | _what methods/types/fields are there?_ | no        | instant          |
+| `grep`    | _does the string X appear anywhere?_   | no        | instant          |
+| `trace`   | _which call can reach this field?_     | no        | instant          |
+| `show`    | _print exactly these things_           | no        | instant          |
+| `stats`   | _what is in this index?_               | no        | instant          |
 
 Only `search` ranks, and only `search` costs a network round trip - it embeds
 the query before it can compare anything. The other five read `graph.json` off
@@ -163,7 +163,7 @@ zen rag schema index <spec...> [--embedding <ref>] [-o <dir>] [--batch <n>]
 | ------------------- | ------------- | ---------------------------------------------------------------------------------------------- |
 | `--embedding <ref>` | -             | Which embedder makes the vectors. Omit it to see the choices                                   |
 | `-o`, `--out <dir>` | `./schema-db` | Where the index goes; `$ZEN_SCHEMA_DB` if that is set                                          |
-| `--batch <n>`       | `96`          | Texts per embedding request, and how often progress prints                                     |
+| `--batch <n>`       | model's own   | Texts per embedding request. `gemini-embedding-*` takes 1                                      |
 | `--no-sources`      | -             | Keep no copy of the documents; `show --source` rebuilds them, and `restore` becomes impossible |
 | `--quiet`           | -             | No narration                                                                                   |