@zenera/cli 1.1.11 → 1.1.14

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

@@ -147,7 +147,7 @@ documentation tree is what makes "which release says this?" answerable at all.
 
 ```sh
 zen rag docs index ./docs ./README.md ./packages/*/README.md --embedding openai:text-embedding-3-small
-zen rag docs index "releases/nsx_4.*/**/*.md" --embedding google:gemini-embedding-001 -o .index/nsx
+zen rag docs index "releases/acme_4.*/**/*.md" --embedding google:gemini-embedding-001 -o .index/acme
 ```
 
 ### The name is the identity
@@ -157,8 +157,8 @@ everything you named. Nothing anywhere records where the file was on the machine
 that built the index.
 
 That name is what `--file` patterns match, so it is worth arranging on purpose.
-Indexing two release trees at once keeps `nsx_4.1.0/api/routing.md` and
-`nsx_4.2.0/api/routing.md` apart, and a search can be pinned to one of them.
+Indexing two release trees at once keeps `acme_4.1.0/api/routing.md` and
+`acme_4.2.0/api/routing.md` apart, and a search can be pinned to one of them.
 Indexing one tree from inside it gives you `api/routing.md`. Two files that
 would land on the same name are deduped rather than merged.
 
@@ -229,7 +229,7 @@ zen rag docs search "how are rate limits counted"
 The answer is the corpus quoting itself:
 
 ```
-## nsx_4.2.0/api/routing.md — 9 of 148 lines
+## acme_4.2.0/api/routing.md — 9 of 148 lines
 
   5 | ## Rate limits
   7 | Requests are counted per tenant and rejected past the limit.
@@ -259,14 +259,14 @@ question with a narrowing on it — not a different command.
 | `--exclude-id <id>`      | a passage already seen. Repeatable                                                   |
 
 ```sh
-zen rag docs search --file "nsx_4.2.*/api/**" "rate limit for the users route"
+zen rag docs search --file "acme_4.2.*/api/**" "rate limit for the users route"
 zen rag docs search --section "Rate limits" --kind table "requests per minute"
 zen rag docs search --mode text "X-RateLimit-Remaining"
 ```
 
 A `--file` pattern with `*` or `?` is a glob matched against the whole document
 name; a plain word is a substring. So `--file routing` finds
-`nsx_4.2.0/api/routing.md` and `--file "routing*"` finds nothing.
+`acme_4.2.0/api/routing.md` and `--file "routing*"` finds nothing.
 
 `--section` takes a heading title, a structure id, or the structure path an
 earlier answer printed. A title that appears in four documents becomes four
@@ -397,7 +397,7 @@ think it is?".
 | "what is the shape of this manual?"               | `list sections --depth 2`                       |
 | "where is the table of per-route limits?"         | `list tables --file "api/**"`                   |
 | "the exact error string, not something like it"   | `search --mode text "connection reset by peer"` |
-| "same question, but only the 4.2 docs"            | `search --file "nsx_4.2*/**" "…"`               |
+| "same question, but only the 4.2 docs"            | `search --file "acme_4.2*/**" "…"`              |
 | "is this index the right one?"                    | `stats`                                         |
 
 The rule: **a question about meaning is a `search`; a question about presence,
@@ -461,7 +461,7 @@ list, so an empty answer and an absent thing look identical. `grep_docs` is how
 
 `search_docs` is shaped for the **second** call rather than the first. The first
 is always a sentence and always returns some of the wrong tree; the second is
-the same sentence with `files: ["nsx_4.2*/api/**"]`, or `section: "Rate limits"`,
+the same sentence with `files: ["acme_4.2*/api/**"]`, or `section: "Rate limits"`,
 or `kind: ["table"]`. Those are parameters and not separate tools, so narrowing
 costs one call instead of three. `exclude_ids` takes the ids from an earlier
 answer, so asking again moves on instead of repeating itself.
@@ -482,7 +482,7 @@ project.** Not optional, and not the same thing as passing the tools in.
 
 Wiring alone leaves the model to infer everything that matters. A tool
 description says what `grep_docs` does; it cannot say that this index holds the
-NSX 4.1 and 4.2 manuals side by side, that every answer must be pinned to a
+ACME 4.1 and 4.2 manuals side by side, that every answer must be pinned to a
 release with `files`, that the API reference lives under `*/api/**` and the
 task guides under `*/guides/**`, or that the numbers anybody actually wants are
 in tables and so `kind: ["table_row"]` is the right first move. That is project
@@ -530,19 +530,19 @@ Best practice, in order of how often it is got wrong:
 
 ```md
 ---
-name: nsx-docs
-description: How to find an answer in the NSX 4.1 and 4.2 manuals — which document says it,
+name: acme-docs
+description: How to find an answer in the ACME 4.1 and 4.2 manuals — which document says it,
     what it says verbatim, and which release it is true of. Use before answering anything
-    about NSX behaviour, limits or API routes.
+    about ACME behaviour, limits or API routes.
 ---
 
-# The NSX manuals
+# The ACME manuals
 
 Indexed at `/assets/docs-db` (already in `$ZEN_DOCS_DB`). Two releases side by
-side; document names begin `nsx_4.1.0/` or `nsx_4.2.0/`, then `api/` for the
+side; document names begin `acme_4.1.0/` or `acme_4.2.0/`, then `api/` for the
 reference and `guides/` for the task documentation.
 
-- Always pin the release: `files: ["nsx_4.2.0/**"]`. An unpinned search mixes them.
+- Always pin the release: `files: ["acme_4.2.0/**"]`. An unpinned search mixes them.
 - Vague question ("how does edge failover work?") → `search_docs`, then ask again
   with `section` or `files` once you can see which half of the tree it is in.
 - Does X exist, how is it spelled, how many are there → `grep_docs`. It is
@@ -553,7 +553,7 @@ reference and `guides/` for the task documentation.
 - Never `grep`/`rg`/`cat` the tree — the tools above are local and exact.
 
 Worked: per-route rate limits are the table under "Rate limits" in
-`nsx_4.2.0/api/routing.md` (lines 24-31); the retry envelope is described two
+`acme_4.2.0/api/routing.md` (lines 24-31); the retry envelope is described two
 sections down. Cite the document name and the line numbers.
 ```
 

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

@@ -577,8 +577,8 @@ project.** Not optional, and not the same thing as passing the tools in.
 
 Wiring alone leaves the model to infer everything that matters. A tool
 description says what `grep_api` does; it cannot say that this index holds the
-NSX policy API, that names are `snake_case`, that every route is under
-`/policy/api/v1`, or that `list_api` is the right first move here because the
+ACME policy API, that names are `snake_case`, that every route is under
+`/api/v1/policy`, or that `list_api` is the right first move here because the
 API has three hundred operations and search will hand back five. That is
 project knowledge, and project knowledge belongs in a skill — where it is
 loaded only when the model is actually working on this API, instead of sitting

package/templates/editor/.vscode/settings.json

@@ -1,6 +1,8 @@
 {
     "chat.useNestedAgentsMdFiles": false,
-    "chat.tools.terminal.autoApprove": {
-        "*": true
+    "chat.tools.terminal.enableAutoApprove": true,
+    "chat.tools.terminal.ignoreDefaultAutoApproveRules": true,
+    "chat.tools.edits.autoApprove": {
+        "**": true
     }
 }

package/templates/parts/exa.prompt.md.tmpl

@@ -0,0 +1,4 @@
+
+You can also search the web and read a page from it. Prefer the workspace when
+both could answer, and when an answer comes from the web, say which page it
+came from.

package/templates/parts/exa.spec.md.tmpl

@@ -0,0 +1,2 @@
+- Web — search and read a page. Anything taken from one is attributed to the
+  page it came from.

package/templates/project/INSTRUCTIONS.md

@@ -5,3 +5,11 @@ place for the things that are true regardless of who is answering: tone,
 constraints, what to do when the answer is not knowable.
 
 Replace this with yours.
+
+## Reporting
+
+Say what you did, file by file, and say what you deliberately did not do.
+
+Every claim about what a command did has to be one you can make because you ran
+it and read the output. When something cannot be established, say so and say
+what would settle it — a guess offered as an answer is worse than no answer.

package/templates/project/SPECIFICATION.md.tmpl

@@ -0,0 +1,47 @@
+# Specification
+
+What this project is for. The files around it are the implementation; where the
+two disagree, this one wins.
+
+## Purpose
+
+Carry out work inside a workspace on request — read it, change it, run
+something in it — and report what was done in enough detail to be checked.
+
+## Scope
+
+- One request at a time, in one workspace, with the person who asked it present.
+- No schedule, no queue, nothing that outlives the session it was asked in.
+
+## Agents
+
+- `default` — the entry point and the only agent; nobody to hand work to.
+    - Establishes what it is looking at before it acts: reads a file before
+      changing it, runs a command rather than predicting its output.
+
+## Tools and boundaries
+
+- Files — read, search, create, edit, move, delete. The workspace is the only
+  writable thing, symlinks included.
+- Shell — commands run in the container, on that same workspace.
+- `assets/` is reference material, and read-only.
+{{web}}
+
+## Environment
+
+- Model: `{{modelRef}}`, one for the whole project.
+- Sandbox: built from `sandbox/Dockerfile`, persists between runs, and can
+  reach the network. What the work always needs belongs in the image, not in an
+  instruction that reinstalls it on every run.
+- Setup: none. `scripts/_setup.sh` is where a step would go, and it has none.
+
+## Done means
+
+- The change asked for is in the workspace, or the question is answered from
+  what is actually in it.
+- Every claim about a command is one that was run and whose output was read.
+- The reply names what changed, file by file, and says what it deliberately did
+  not do.
+- An answer that cannot be produced honestly is a refusal with the reason.
+
+

package/templates/project/agents/prompts/{default.md → default.md.tmpl}

@@ -7,9 +7,13 @@ You can also run shell commands. They run in a container over the same
 workspace, not on the user's machine, so a command that fails there has cost
 them nothing — but it is still their work in the directory, so read before you
 overwrite and say what you ran.
+{{webPrompt}}
 
 Read a file before you change it: `apply_patch` matches the surrounding text
 exactly, so a patch written from memory will not apply. Use `apply_patch` to
 change part of a file and `write_file` only for a new one.
 
+Anything under `/assets` is reference material: read it, search it, and do not
+try to change it.
+
 Say what you changed.

package/templates/project/agents.yaml.tmpl

@@ -1,5 +1,9 @@
 # Who exists, and what they may reach for.
 #
+# This implements the Agents, Tools and boundaries, and Environment sections of
+# SPECIFICATION.md. Change what the system does there first, then bring this
+# file to match it — `/sync-with-spec` in your editor does exactly that.
+#
 version: 1
 
 {{model}}

package/templates/project/gitignore

@@ -1,7 +1,13 @@
-# Sessions hold run state, memory, blobs and whatever the agent wrote.
+# Sessions hold run state, blobs and whatever the agent wrote.
 # None of it is source.
 sessions/
 
+# Memory is worth keeping: `graph.json` and `files/` are what the agents
+# learned, and they diff. The vectors are not — they are derived from the
+# graph and can be rebuilt with `zen memory reembed`.
+memory/vectors.*
+memory/.lock
+
 # Scratch, inside the workspace so the sandbox can reach it.
 .tmp/
 

package/templates/project/scripts/_setup.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+#
+# The one command that initialises this project.
+#
+#   scripts/_setup.sh            do whatever is not done yet
+#   scripts/_setup.sh --force    do all of it again
+#
+# Anything that has to be in place before a run — an index built, a document
+# fetched, a file generated — is a script in this directory rather than a
+# paragraph somebody is meant to follow. The leading underscore is what
+# separates the runner from the steps it runs.
+#
+# Each step is `scripts/<name>.sh`, named below in the order they depend on
+# each other. A step:
+#
+#   - starts `set -eu` and `cd "$(dirname "$0")/.."`, so it works from anywhere
+#   - takes no arguments, and reads $FORCE to know whether to redo finished work
+#   - exits 0 when it did the work, 3 when there was nothing to do, non-zero
+#     when it failed
+#   - writes under .tmp/ and moves the result into place, so an interrupted run
+#     never leaves half an artefact behind
+#
+# Running this twice has to be safe, and the second run is what proves it: every
+# step should report `skipped`.
+
+set -eu
+cd "$(dirname "$0")/.."
+
+FORCE=0
+if [ "${1:-}" = "--force" ]; then
+    FORCE=1
+fi
+export FORCE
+
+LOGS=.tmp/logs
+
+# The steps, in order. Nothing here yet — a project with nothing to build
+# before it runs is a project with no steps, and that is a real answer.
+#
+# An example of what one looks like, for when there is something to build:
+#
+#   STEPS="docs_index"
+#
+# with scripts/docs_index.sh holding
+#
+#   set -eu
+#   cd "$(dirname "$0")/.."
+#   if [ "${FORCE:-0}" = 0 ] && [ -f assets/docs-db/manifest.json ]; then
+#       echo "assets/docs-db is already built"
+#       exit 3
+#   fi
+#   rm -rf .tmp/docs-db
+#   zen rag docs index assets/docs \
+#       --embedding openai:text-embedding-3-small --out .tmp/docs-db
+#   rm -rf assets/docs-db
+#   mv .tmp/docs-db assets/docs-db
+#
+STEPS=""
+
+if [ -z "$STEPS" ]; then
+    echo "nothing to set up — this project builds nothing before it runs"
+    exit 0
+fi
+
+mkdir -p "$LOGS"
+summary=""
+failed=0
+
+for name in $STEPS; do
+    log="$LOGS/setup-$name.log"
+    echo
+    echo "-- $name  $(date '+%H:%M:%S')  ($log)"
+
+    # Watched rather than waited on: the output goes to the screen and to its
+    # own log at once, so a long step can be followed from either.
+    set +e
+    "scripts/$name.sh" 2>&1 | tee "$log"
+    code=${PIPESTATUS[0]}
+    set -e
+
+    case "$code" in
+        0) word=ok ;;
+        3) word=skipped ;;
+        *)
+            word="failed ($code)"
+            failed=1
+            ;;
+    esac
+    summary="${summary}  ${name}: ${word}
+"
+    # Later steps depend on earlier ones, so a failure stops rather than
+    # producing a second failure that is only a consequence of the first.
+    if [ "$failed" = 1 ]; then
+        break
+    fi
+done
+
+echo
+echo "setup:"
+printf '%s' "$summary"
+exit "$failed"

package/templates/project/SPECIFICATION.md

@@ -1,6 +0,0 @@
-# Specification
-
-What the project is meant to produce, the constraints it has to hold to, and
-how to tell a finished job from an unfinished one.
-
-Anything written here is the specification; while it is empty there is none.