@zenera/cli 1.1.21 → 1.1.23

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

@@ -0,0 +1,86 @@
+---
+requires: [files]
+---
+
+# Working with files
+
+These rules govern how files are discovered, inspected, and modified. If file tools
+are not among your tools, you cannot read or change files directly.
+
+## Access modes
+
+Check which tools you actually have:
+
+- If `write_file` or `apply_patch` is not among your tools, your access is **read-only**.
+  Inspect files, search directories, and report conclusions, but attempt no edits.
+- If `write_file` and `apply_patch` are available, you may create and edit files
+  under `/workspace`.
+
+## Discovery before assumption
+
+Never guess a file's name, location, or contents.
+
+- Use `list_dir` to see directory contents and formats before opening files.
+- Use `find_files` to locate files by substring when the layout is unfamiliar.
+- Check whether a target file already exists before writing to it.
+
+## Reading files
+
+- Use `read_file` to read text files.
+- For files longer than a few dozen lines, pass `start_line` and `end_line` (1-based, inclusive)
+  to read only the relevant section.
+- When `read_file` returns `truncated: true`, the read hit the size limit or range boundary.
+  Resume reading from `end_line + 1` if you need the remainder.
+- Non-text files (images, binaries, archives) cannot be read as text; `list_dir` reports
+  their format.
+
+## Modifying files
+
+### Modifying existing files: `apply_patch`
+
+Always use `apply_patch` to edit existing files. It makes surgical, verifiable changes
+and validates the entire patch before writing any file to disk.
+
+1. **Read before patching**: Read the target file first to obtain exact context lines.
+   An outdated or imagined context line fails the patch.
+2. **Provide context**: Include at least 3 unchanged context lines (prefixed with a space)
+   before and after each change.
+3. **No line numbers**: Patches match on context text, never on line numbers.
+4. **Always close the patch**: Every patch must begin with `*** Begin Patch` and end
+   with `*** End Patch`. Omitting `*** End Patch` is an error.
+
+Example patch:
+
+```
+*** Begin Patch
+*** Update File: /workspace/src/config.ts
+@@ port configuration
+ export interface Config {
+     host: string;
+-    port: 80;
++    port: 8080;
+     timeoutMs: number;
+ }
+*** End Patch
+```
+
+### Creating new files: `write_file`
+
+Use `write_file` only to create a **new** file or to overwrite a small file completely.
+Never use `write_file` to update an existing file when only a few lines need to change.
+
+### Moving and deleting
+
+- Use `move_file` to rename or relocate a file or directory. It creates parent directories
+  as needed. Set `overwrite: true` only when intentionally replacing an existing destination.
+- Use `delete_file` to remove a file. Removing a directory requires `recursive: true`.
+
+## Mounts and containment
+
+All file operations are confined to mounted trees:
+
+- `/workspace`: The primary writable directory for the project. Paths inside the workspace
+  (such as `/workspace/src/main.ts`) are where project files reside.
+- `/assets`, `/skills`, `/memory`: Read-only mounts. You may read, list, and search them,
+  but you cannot write, move, or delete files inside them.
+- Any attempt to reach outside these mounts fails with an containment error.

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

@@ -28,6 +28,23 @@ exploration down a path that may go nowhere. **Several branches are a fan-out**:
 independent parts of one task, worked at the same time, merged by you. It is the
 same call either way; the number of branches is the only difference.
 
+Every `fork` call takes an array under `branches`, even for a single branch:
+
+```json
+{
+    "branches": [
+        {
+            "name": "audit-auth",
+            "agent": "security",
+            "instructions": "Audit /workspace/src/auth/** for bypasses. Return the count and worst finding."
+        }
+    ]
+}
+```
+
+Never pass branch fields (`name`, `instructions`, `agent`) at the top level of
+the tool call.
+
 Do not fork a sequence. Branches run at once and can exchange nothing, so a step
 that needs the step before it has to stay in this conversation.
 

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

@@ -248,6 +248,23 @@ for it, or a fact with nothing that acts on it, is a memory nobody can use. Refs
 resolve only within a single `memory_commit`, so a subgraph split across calls
 arrives without its links.
 
+**Use `ref` (not `id`) for new nodes.** A new node uses `ref` as its local name
+(for example, `"ask"`, `"script"`), and edges connect them using those refs:
+
+```json
+{
+    "nodes": [
+        { "ref": "ask", "kind": "task", "text": "audit firewall rules for risky ports" },
+        { "ref": "script", "kind": "file", "text": "risk report generator", "file": "report.py" }
+    ],
+    "edges": [{ "from": "ask", "to": "script", "relation": "PRODUCED" }]
+}
+```
+
+Use `id` only when updating an existing node that is already in memory from a
+previous search or load. Never pass `id` when creating a new node, and do not
+pass both `ref` and `id` on the same node.
+
 **Do not re-commit what a search already returned.** A node that says what one
 already in memory says is folded into it, and its existing id comes back under
 your ref - so the links you asked for still land, on the memory that was already
@@ -285,6 +302,26 @@ costs nothing until a `memory_load` asks for it, and comes back at
 `/memory/<id>.<ext>` to be read or run. Commit a node with no file only when the
 whole of what you know is one line long.
 
+**The file must exist in the workspace first.** `memory_commit` copies an
+existing file from the workspace; it is not an upload channel and does not
+write file contents from raw arguments. Write the file to the workspace first
+(using `write_file`, `apply_patch`, or a command saving under `/workspace`),
+then pass its workspace path (e.g. `"file": "report.py"` or
+`"file": "/workspace/report.py"`).
+
+| Which files to commit  | What belongs in them                                                       |
+| ---------------------- | -------------------------------------------------------------------------- |
+| Working scripts        | A script, query or invocation that can be re-run directly                  |
+| Configurations & specs | Self-contained config files, schemas or request templates                  |
+| Rendered findings      | A table of findings or structured report produced by an investigation      |
+| Pinned reference text  | Verbatim passages from released specs or versioned docs that cannot change |
+| Assembled answers      | Synthesised conclusions from multiple sources with a provenance header     |
+| Specimen responses     | An API response shape to reproduce against (never raw secrets)             |
+
+Do not commit files from the living codebase (use a pointer with file and line
+ranges instead - copies go stale silently), raw ephemeral command logs, or
+anything outside the workspace.
+
 **Name the sources inside the file as well as in the text.** The two halves
 arrive separately - a recollection shows the text, and only a later
 `memory_load` opens the file - so a file read on its own is an assertion with

package/templates/project/agents.yaml.tmpl

@@ -44,14 +44,14 @@ agents:
       # store at all.
       memory: true
       #
-      # workspace:* is every file tool at once, sandbox:* is the shell. Name
-      # them one by one to be narrower, or subtract: [workspace:*, -delete_file]
+      # files:* (alias: workspace:*) is every file tool at once, sandbox:* is
+      # the shell. Name them one by one to be narrower, or subtract: [files:*, -delete_file]
       #
       # sandbox:* runs commands in a container, not on this machine, so it
       # needs podman — `zen run` installs and starts what it can on its own,
       # and `zen sandbox status` says where that got to. Drop the line if you
       # would rather this agent never reached a shell.
       tools:
-          - workspace:*
+          - files:*
           - sandbox:*
           {{exa}}

package/templates/project/gitignore

@@ -12,4 +12,15 @@ memory/.lock
 .tmp/
 
 # Credentials.
-.env
+.env
+
+# A rag index commits everything except its vectors: they are binary, they are
+# large, and `zen rag <subject> restore` rebuilds them from the copies of the
+# documents the index already carries — which is why this is safe to ignore and
+# `memory/` above is not. A clone therefore holds an index that looks built and
+# cannot search until a setup step restores it. `zen rag <subject> ready` is the
+# test for that; `[ -f manifest.json ]` is not, because the manifest is here.
+assets/**/lance/
+
+.DS_Store
+**/.DS_Store

package/templates/project/scripts/_setup.sh

@@ -4,6 +4,7 @@
 #
 #   scripts/_setup.sh            do whatever is not done yet
 #   scripts/_setup.sh --force    do all of it again
+#   scripts/_setup.sh --check    say what is not done, and do none of it
 #
 # 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
@@ -17,9 +18,25 @@
 #   - 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
+#   - under $CHECK, does none of the work: it runs the same "already done" test,
+#     exits 3 when the answer is yes, and otherwise says what is missing and
+#     exits 4. A check must not assume an earlier step has run — a missing
+#     prerequisite is a 4 of its own, not a hard failure, or one unbuilt thing
+#     hides the rest of the list
 #   - writes under .tmp/ and moves the result into place, so an interrupted run
 #     never leaves half an artefact behind
 #
+# A step decides it has nothing to do by testing for something that SURVIVES A
+# CLONE. Files that are git-ignored do not: a vector index commits its manifest
+# and ignores `lance/`, so `[ -f .../manifest.json ]` is true on a fresh
+# checkout that cannot search at all, and every step reports `skipped` until the
+# first search fails for a reason nobody connects to setup. Ask the tool instead
+# of guessing at files — `zen rag docs ready` answers exactly that question.
+#
+# That test is the whole of `--check`, which is why this is one script and not
+# two: the steps already know what "done" means, and a second script asking the
+# same question would be a second answer to keep in step with this one.
+#
 # Running this twice has to be safe, and the second run is what proves it: every
 # step should report `skipped`.
 
@@ -27,10 +44,17 @@ set -eu
 cd "$(dirname "$0")/.."
 
 FORCE=0
-if [ "${1:-}" = "--force" ]; then
-    FORCE=1
-fi
-export FORCE
+CHECK=0
+case "${1:-}" in
+    '') ;;
+    --force) FORCE=1 ;;
+    --check) CHECK=1 ;;
+    *)
+        echo "usage: scripts/_setup.sh [--force|--check]" >&2
+        exit 2
+        ;;
+esac
+export FORCE CHECK
 
 LOGS=.tmp/logs
 
@@ -45,15 +69,29 @@ LOGS=.tmp/logs
 #
 #   set -eu
 #   cd "$(dirname "$0")/.."
-#   if [ "${FORCE:-0}" = 0 ] && [ -f assets/docs-db/manifest.json ]; then
-#       echo "assets/docs-db is already built"
+#   OUT=assets/docs-db
+#
+#   if [ "${FORCE:-0}" = 0 ] && zen rag docs ready --dir "$OUT" --quiet; then
+#       echo "$OUT is already built"
 #       exit 3
 #   fi
+#   if [ "${CHECK:-0}" = 1 ]; then
+#       # Without --quiet it names what is missing and the command that fixes
+#       # it; `|| true` because not-ready is the exit code we came for.
+#       zen rag docs ready --dir "$OUT" || true
+#       exit 4
+#   fi
+#   # Committed index, git-ignored vectors: re-embed from the copies the index
+#   # already holds rather than indexing the documents over again.
+#   if [ "${FORCE:-0}" = 0 ] && [ -f "$OUT/manifest.json" ]; then
+#       zen rag docs restore --dir "$OUT"
+#       exit 0
+#   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
+#   rm -rf "$OUT"
+#   mv .tmp/docs-db "$OUT"
 #
 STEPS=""
 
@@ -65,9 +103,16 @@ fi
 mkdir -p "$LOGS"
 summary=""
 failed=0
+pending=0
 
 for name in $STEPS; do
-    log="$LOGS/setup-$name.log"
+    # A dry run keeps its own log: overwriting the build's would lose the
+    # record of the build to a question about it.
+    if [ "$CHECK" = 1 ]; then
+        log="$LOGS/check-$name.log"
+    else
+        log="$LOGS/setup-$name.log"
+    fi
     echo
     echo "-- $name  $(date '+%H:%M:%S')  ($log)"
 
@@ -81,6 +126,10 @@ for name in $STEPS; do
     case "$code" in
         0) word=ok ;;
         3) word=skipped ;;
+        4)
+            word="needs setup"
+            pending=1
+            ;;
         *)
             word="failed ($code)"
             failed=1
@@ -90,12 +139,20 @@ for name in $STEPS; do
 "
     # Later steps depend on earlier ones, so a failure stops rather than
     # producing a second failure that is only a consequence of the first.
+    # `needs setup` does not stop it: the point of asking is the whole list.
     if [ "$failed" = 1 ]; then
         break
     fi
 done
 
 echo
-echo "setup:"
+if [ "$CHECK" = 1 ]; then
+    echo "setup check:"
+else
+    echo "setup:"
+fi
 printf '%s' "$summary"
-exit "$failed"
+if [ "$failed" = 1 ] || [ "$pending" = 1 ]; then
+    exit 1
+fi
+exit 0