@zenera/cli 1.1.20 → 1.1.22

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

@@ -20,6 +20,13 @@
 #   - 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.
+#
 # Running this twice has to be safe, and the second run is what proves it: every
 # step should report `skipped`.
 
@@ -45,15 +52,23 @@ 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
+#   # 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=""