@zenera/cli 1.1.20 → 1.1.22

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

@@ -18,18 +18,20 @@ word "password" appears in forty places that are not the one you want.
 ## The commands
 
 ```
-zen rag schema <index|search|list|grep|trace|show|stats> [spec...]
+zen rag schema <index|restore|ready|search|list|grep|trace|show|stats> [spec...]
 ```
 
-| Command  | Answers                                | Embedder? | Typical |
-| -------- | -------------------------------------- | --------- | ------- |
-| `index`  | builds the thing                       | yes       | minutes |
-| `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 |
+| `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 |
 
 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
@@ -108,6 +110,29 @@ schema-db/
 `manifest.json` records **which embedder made the vectors**, so a search with a
 different model is refused rather than answered with noise.
 
+### What survives a clone
+
+`lance/` is binary, large, and rebuildable, so a project commits the index and
+git-ignores the vectors. What a fresh checkout holds is therefore an index that
+**looks built and cannot answer**: the manifest is there, the graph is there,
+and the first search fails with `holds no searchable table`.
+
+```sh
+zen rag schema ready --dir assets/schema-db      # exit 0 searchable, exit 3 not
+zen rag schema restore --dir assets/schema-db    # re-embed from sources/
+```
+
+`ready` answers with its **exit code**, so a setup step branches on it without
+parsing anything. `restore` rebuilds from the bundled copies in `sources/` and
+renames the result into place, so a failure leaves the old index untouched -
+which means an index built with `--no-sources` cannot be restored at all, and
+says so. `--embedding <ref>` is how an index moves to another model: everything
+is re-embedded and the manifest rewritten.
+
+> **Never test for a built index with `[ -f .../manifest.json ]`.** The manifest
+> is committed and the vectors are not, so that test is true on exactly the
+> machine where it is wrong. `zen rag schema ready` is the test.
+
 ## Installing
 
 `zen rag` ships in `@zenera/rag`, a sibling of the CLI. It has no binary of its
@@ -134,13 +159,13 @@ have not installed globally.
 zen rag schema index <spec...> [--embedding <ref>] [-o <dir>] [--batch <n>]
 ```
 
-| Flag                | Default       | Meaning                                                      |
-| ------------------- | ------------- | ------------------------------------------------------------ |
-| `--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   |
-| `--no-sources`      | -             | Keep no copy of the documents; `show --source` rebuilds them |
-| `--quiet`           | -             | No narration                                                 |
+| Flag                | Default       | Meaning                                                                                        |
+| ------------------- | ------------- | ---------------------------------------------------------------------------------------------- |
+| `--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                                     |
+| `--no-sources`      | -             | Keep no copy of the documents; `show --source` rebuilds them, and `restore` becomes impossible |
+| `--quiet`           | -             | No narration                                                                                   |
 
 ```sh
 zen rag schema index openapi.yaml --embedding openai:text-embedding-3-small
@@ -647,14 +672,16 @@ Worked: the invoice total is `Invoice.amount_due` (minor units), returned by
 
 ## When it goes wrong
 
-| Symptom                                          | Cause                                                                               |
-| ------------------------------------------------ | ----------------------------------------------------------------------------------- |
-| "not installed"                                  | `@zenera/rag` is not resolvable - install it, or use the two-`--package` npx form   |
-| Refused for a different embedding                | The index records the model that built it; re-index or pass the right `--embedding` |
-| No manifest / not an index                       | A build that did not finish. `manifest.json` is written last on purpose             |
-| `provider "openai": no api key`                  | `zen key ls` - the keyring, or a real environment variable                          |
-| A usage error before any credential is asked for | Deliberate: everything about the invocation is checked first, so a typo is a typo   |
-| Nothing matched                                  | Exit 0 with an empty answer. Try fewer words, or `--all` instead of a narrow field  |
-| Answers about the wrong version of the API       | Nothing watches the document. Re-index after it changes                             |
-| A search took ten seconds, using no CPU          | One embedding round trip, not the index. `list`/`grep` make none                    |
-| `search <word> <word>` gave ranked nonsense      | Bare words after `search` are the QUERY, not a subcommand. You meant `list`/`grep`  |
+| Symptom                                          | Cause                                                                                                          |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| "not installed"                                  | `@zenera/rag` is not resolvable - install it, or use the two-`--package` npx form                              |
+| Refused for a different embedding                | The index records the model that built it; pass the right `--embedding`, or move it with `restore --embedding` |
+| No manifest / not an index                       | A build that did not finish. `manifest.json` is written last on purpose                                        |
+| `holds no searchable table`                      | A manifest with no vectors - a clone, since `lance/` is git-ignored. `restore` it                              |
+| A step reported `skipped` but nothing can search | The step tested for `manifest.json` instead of asking `ready`                                                  |
+| `provider "openai": no api key`                  | `zen key ls` - the keyring, or a real environment variable                                                     |
+| A usage error before any credential is asked for | Deliberate: everything about the invocation is checked first, so a typo is a typo                              |
+| Nothing matched                                  | Exit 0 with an empty answer. Try fewer words, or `--all` instead of a narrow field                             |
+| Answers about the wrong version of the API       | Nothing watches the document. Re-index after it changes                                                        |
+| A search took ten seconds, using no CPU          | One embedding round trip, not the index. `list`/`grep` make none                                               |
+| `search <word> <word>` gave ranked nonsense      | Bare words after `search` are the QUERY, not a subcommand. You meant `list`/`grep`                             |

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

@@ -1,6 +1,6 @@
 ---
 name: zen-review
-description: Checking a project before committing - the four mechanical checks `/project-review` makes before any judgement (`zen check`, the §2.5 path sweep, the memory house-rules copy, the spec-sync record), what each one owns, what their exit codes mean, and what deliberately has no check because no tool can make it. Load before running `/project-review`, before saying a project is ready, and whenever a review finding needs verifying rather than restating.
+description: Checking a project before committing - the four mechanical checks `/project-review` makes before any judgement (`zen check`, the §2.5 path sweep, the memory house-rules copy, the spec-sync record), what each one owns, what their exit codes mean, which findings hand off to `zen-instructions`, and what deliberately has no check because no tool can make it. Load before running `/project-review`, before saying a project is ready, and whenever a review finding needs verifying rather than restating.
 ---
 
 # Reviewing a project
@@ -92,6 +92,22 @@ cause and the least believable finding.
 `agents/memory-policy-instructions.md`, which filename order puts directly after
 the copy - see the `zen-memory` skill.
 
+## Findings that are not yours to fix in place
+
+`zen check` reports `rules.stale`, `files.uninstructed`, `memory.uninstructed`,
+`fork.uninstructed`, `rules.requires.unknown` or `rules.unreached` against a
+file under `agents/`, and the obvious repair - open it and edit it - is wrong for
+four of those files. `tools-instructions.md`, `files-instructions.md`,
+`memory-instructions.md` and `fork-instructions.md` are `zen`'s copies:
+`zen check --fix` replaces them, so an edit made inside one is gone at the next
+fix, `init` or `open`.
+
+**Load `zen-instructions` before acting on any of those findings**, and before
+judging a house rule at all. It owns which documents belong to whom, where a
+project's own rules on the same subject go instead, what `requires:` does, and
+what filename order decides. A review that fixes one of ours in place has
+undone itself by the next `zen open` and left nothing behind to say so.
+
 ## What has no check, on purpose
 
 Not because it would be hard, but because the answer would be wrong:

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

@@ -0,0 +1,257 @@
+---
+name: zen-sandbox
+description: How the container sandbox works, when and how to configure it in `agents.yaml` (`sandbox:` and `agents[].sandbox`), the four `sandbox:*` tools, mount layout (/workspace, $HOME, /tmp, /run/zenera/keys), lifecycle and persistence (`persist: true`), credential forwarding by name, resource ceilings (cpus, memory, pids), standard vs strict hardening profiles, path rules, and debugging container issues with `zen sandbox`. Refers to `zen-cli` (`.github/skills/zen-cli/references/sandbox.md`).
+---
+
+# The Container Sandbox
+
+A shell, and a boundary around it. The boundary is a Linux container: the
+agent's commands run against an image the project chose, with the session's
+workspace bind-mounted at `/workspace` and nothing else of the host machine in
+reach.
+
+The container is the boundary rather than any parsing or filtering of what the
+model wrote. On the host side, every process is spawned with `shell: false` and
+arguments assembled as an array; command text travels exclusively down **stdin**
+into `/bin/sh -s` inside the container. There is no host shell to inject into,
+and no argv length to overflow.
+
+The container engine is **Podman** (rootless by default).
+
+For the CLI subcommands (`zen sandbox status`, `up`, `pull`, `clean`, `disk`)
+and command-line options, see the [zen-cli skill](../zen-cli/SKILL.md) and its
+dedicated reference document [sandbox.md](../zen-cli/references/sandbox.md).
+
+---
+
+## 1. The Sandbox Tools (`sandbox:*`)
+
+When an agent is granted sandbox tools in `agents.yaml`, it receives up to four
+tools from the `sandbox` group:
+
+| Tool                     | Type       | Description                                                           |
+| ------------------------ | ---------- | --------------------------------------------------------------------- |
+| `run_command`            | foreground | Runs a shell command under `/bin/sh`, waits for exit, captures output |
+| `run_command_background` | background | Starts a detached command (server, watcher) and returns a `job_id`    |
+| `read_command_output`    | inspection | Reads a window of log lines from a background job and checks status   |
+| `stop_command`           | control    | Signals and terminates a background job process group                 |
+
+### `run_command`
+
+- **Parameters:**
+    - `command` (string, required): the shell command string, interpreted by `/bin/sh` inside the container.
+    - `cwd` (string, optional): working directory relative to `/workspace`. Defaults to `/workspace`.
+    - `timeout` (integer, optional): seconds before SIGTERM/SIGKILL. Defaults to 120 s; capped at 3600 s.
+- **Output:** returns `exit_code`, `stdout`, `stderr`, `duration_ms`. Combined output is capped at 64 KiB (`truncated: true` when exceeded).
+
+### `run_command_background`
+
+- **Parameters:** `command` (string, required), `cwd` (string, optional).
+- **Execution:** written to `/tmp/zenera-jobs/<job_id>.sh` and started in a separate session via `setsid`. Output and exit status stream to `/tmp/zenera-jobs/<job_id>.log` and `<job_id>.exit`.
+- **Returns:** `{ job_id, started: true }`.
+
+### `read_command_output`
+
+- **Parameters:** `job_id` (string, required), `start_line` (integer, optional, 1-based).
+- **Returns:** `{ job_id, running: boolean, exit_code?: number, output: string, start_line, end_line, lines }`. Displays up to 400 lines per call.
+
+### `stop_command`
+
+- **Parameters:** `job_id` (string, required).
+- **Behaviour:** sends SIGTERM to the job's entire process group (`-$pid`), waits 1 s grace period, then sends SIGKILL.
+
+---
+
+## 2. Tool Selection in `agents.yaml`
+
+Agents select tools through `tools:` using exact names, group wildcards, or subtraction:
+
+```yaml
+agents:
+    - name: developer
+      tools: [files:*, sandbox:*] # all file and shell tools
+
+    - name: reviewer
+      tools: [files:*, sandbox:run_command] # foreground only, no background servers
+
+    - name: tester
+      tools: [sandbox:*, -stop_command] # sandbox tools without stop_command
+
+    - name: analyst
+      tools: [files:*] # no shell tools; container is never started
+```
+
+An agent with no `sandbox:*` tools never triggers an image pull, container creation, or VM startup.
+
+---
+
+## 3. Filesystem and Mount Layout
+
+Inside the container, paths are isolated to designated mount points:
+
+| Path inside container | Host Source               | Mode        | Lifecycle / Purpose                                    |
+| --------------------- | ------------------------- | ----------- | ------------------------------------------------------ |
+| `/workspace`          | Session workspace         | read-write* | The work itself. Changes survive session completion.   |
+| `/home/agent`         | `.data/sandbox/home`      | read-write  | User home (`$HOME`). Persists across sessions.         |
+| `/tmp`                | In-memory / host tmpfs    | read-write  | Ephemeral scratch; holds `/tmp/zenera-jobs`.           |
+| `/memory`             | Session memory directory  | read-only   | Generated memory files (when `memory:` is enabled).    |
+| `/assets`             | Project assets directory  | read-only   | Reference assets declared in `SPECIFICATION.md`.       |
+| `/skills`             | Project skills directory  | read-only   | Custom skill files available to agents.                |
+| `/run/zenera/keys`    | Keychain / temp directory | read-only   | Forwarded file credentials (e.g. Vertex service keys). |
+
+_\*Mounted read-only if the session or project was opened in read-only mode._
+
+### Path Rules
+
+- All relative paths and `cwd` arguments resolve against `/workspace`.
+- Lexical escapes outside `/workspace` (`../../etc`, absolute `/etc`, null bytes `\0`) are **strictly rejected** by the runtime and return an actionable error to the model.
+- Path resolution inside the container never resolves against host symlinks.
+
+---
+
+## 4. Lifecycle, Container Naming, and Persistence
+
+### Lazy Initialization
+
+Containers are started on-demand. If an agent never invokes a `sandbox:*` tool, no image is pulled and no container runs. Concurrent tool calls in the same turn await a single startup promise without racing.
+
+### Deterministic Container Naming
+
+Container names follow the pattern:
+
+```
+zn-<key>-<digest>
+```
+
+- `<key>` is derived from the session identifier or project key.
+- `<digest>` is the first 10 hex characters of the SHA-256 hash of the configuration:
+  `[root, image, hashCpus, hashMemory, network, workdir, user, readOnly, mounts, env, secrets, hardening]`
+
+### The Persistence Rule (`persist: true` vs `persist: false`)
+
+- **`persist: false` (ephemeral):** when the session finishes, the container is deleted (`podman rm --force --volumes`). Changes made to `/workspace` and `/home/agent` survive on the host; changes made to the root filesystem (such as `apt-get` or root `pip install`) are discarded.
+- **`persist: true` (recommended for development):** the container is stopped (`podman stop --time 2`) rather than removed. System packages and global caches survive between runs.
+- **Caveat:** because the container name depends on its configuration, **any edit to `sandbox:` in `agents.yaml` generates a new container name**, abandoning the persisted container rootfs. When dependencies must be permanent across config changes, bake them into the image using `sandbox.build`.
+
+---
+
+## 5. Configuring `sandbox:` in `agents.yaml`
+
+Configured at the top level and optionally overridden per agent under `agents[].sandbox`:
+
+```yaml
+sandbox:
+    persist: true
+    image: docker.io/library/python:3.14-slim-bookworm
+    cpus: 4
+    memory: 4096
+    network: bridge
+    timeout: 120
+    hardening: standard
+    env: [HTTPS_PROXY, NO_PROXY]
+    keys: true
+
+agents:
+    - name: builder
+      # Inherits base sandbox configuration
+
+    - name: isolated-runner
+      sandbox:
+          hardening: strict
+          network: none
+```
+
+### Configuration Fields
+
+| Field       | Type                   | Default                                       | Meaning                                                 |
+| ----------- | ---------------------- | --------------------------------------------- | ------------------------------------------------------- |
+| `image`     | string                 | `docker.io/library/python:3.14-slim-bookworm` | Base image to run. Mutually exclusive with `build`.     |
+| `build`     | object                 | none                                          | `{ dockerfile, context? }`. Builds a local Dockerfile.  |
+| `cpus`      | number                 | `4` (`2` in `strict`)                         | Fractional CPU limit (`--cpus`). `0` for unconstrained. |
+| `memory`    | integer (MiB)          | `4096` (`2048` in `strict`)                   | Memory limit (`--memory`). `0` for unconstrained.       |
+| `network`   | `bridge`/`none`/`host` | `bridge` (`none` in `strict`)                 | Network connectivity mode.                              |
+| `workdir`   | absolute path          | `/workspace`                                  | Working directory and workspace mount destination.      |
+| `timeout`   | integer (seconds)      | `120`                                         | Default per-command execution timeout.                  |
+| `hardening` | `standard`/`strict`    | `standard`                                    | Security posture (see §6).                              |
+| `user`      | string                 | image user                                    | `uid`, `name`, or `uid:gid` inside the container.       |
+| `persist`   | boolean                | `false`                                       | Keep container filesystem between runs.                 |
+| `env`       | string[]               | `[]`                                          | Host environment variables to pass by name.             |
+| `keys`      | boolean                | `true`                                        | Forward model credentials to the container.             |
+
+---
+
+## 6. Hardening Postures: `standard` vs `strict`
+
+Every container runs with baseline safety controls:
+
+- `--security-opt no-new-privileges` prevents setuid escalation.
+- `--init` provides a dedicated init process (catatonit) to reap zombie background processes.
+- `--pids-limit 1024` halts fork bombs.
+- `--restart no` prevents runaway resurrection.
+- Never `--privileged`.
+- Podman's default seccomp filter is always enabled.
+
+### Comparison
+
+| Security Dimension   | `standard` (default)                        | `strict`                                          |
+| -------------------- | ------------------------------------------- | ------------------------------------------------- |
+| **Intended Use**     | General development, testing, builds        | Executing unreviewed or untrusted code            |
+| **Kernel Caps**      | Default set kept (allows `apt`, `pip`)      | `--cap-drop ALL` (all capabilities dropped)       |
+| **Root Filesystem**  | Writable                                    | `--read-only` (immutable rootfs)                  |
+| **Temporary Space**  | Standard `/tmp`                             | `--tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m`    |
+| **User Namespace**   | Rootless default (uid 0 inside = host user) | `--userns keep-id` (host uid inside, owns mounts) |
+| **Default Network**  | `bridge`                                    | `none`                                            |
+| **Default Ceilings** | `cpus: 4`, `memory: 4096`                   | `cpus: 2`, `memory: 2048`                         |
+| **Package Installs** | Allowed (`apt-get`, `pip`, `npm`)           | Refused (must pre-bake into Dockerfile)           |
+| **Workspace**        | `/workspace` is read-write                  | `/workspace` is read-write                        |
+
+### Key Strict Mode Nuances
+
+1. **Pre-baked dependencies:** because `/` is read-only and caps are dropped, dynamic package installations fail. Dependencies must be defined in `sandbox/Dockerfile` using `sandbox.build`.
+2. **`keep-id` user mapping:** under rootless Podman, `--userns keep-id` maps your host UID to the container UID. Files written to `/workspace` remain owned by you on the host, and the container user cannot access root-only files inside the image. If an explicit `user:` is specified in config, `keep-id` is omitted.
+3. **`noexec` on `/tmp`:** prevents running downloaded binaries directly from scratch space. Interpreted scripts (`/bin/sh /tmp/script.sh` or `python /tmp/test.py`) remain functional because the interpreter executable lives in the read-only root.
+
+---
+
+## 7. Credentials and Secret Forwarding
+
+1. **Forwarded by Name, Never by Value:**
+   Host environment variables and credentials are passed using Podman's `--env NAME` syntax (without an `=value`). Podman pulls values from its own environment at execution time. Secrets never appear on command-line arguments, in process lists (`ps`), or in `podman inspect`.
+2. **Env Name Blacklist:**
+   The `env:` array in `agents.yaml` strictly refuses variables named `KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `PASSWD`, or `CREDENTIAL` to prevent accidental credential leakage into uninspected scripts.
+3. **File-Shaped Credentials:**
+   Key files (such as Google Vertex service account keys) are mounted read-only to `/run/zenera/keys/` and their environment variables (e.g. `GOOGLE_APPLICATION_CREDENTIALS`) are automatically rewritten to point to the in-container path.
+4. **Disabling Forwarding:**
+   Set `keys: false` in `agents.yaml` or launch runs with `zen run --no-keys` to prevent any model API keys or service credentials from reaching the container.
+
+---
+
+## 8. Multi-Agent Sandboxes (`SandboxPool`)
+
+- Two agents with identical sandbox configurations share the **same container**.
+- Two agents with different images or configurations receive separate containers.
+- The `sandbox:*` tool definitions remain uniform across the session; when an agent calls a tool, the pool routes the call to that specific agent's container at invocation time.
+
+---
+
+## 9. Diagnostics and Troubleshooting (`zen sandbox`)
+
+Use the `zen sandbox` commands via terminal to inspect and manage container state:
+
+```sh
+zen sandbox status          # Check podman version, machine status, and active containers
+zen sandbox up              # Start VM (macOS) and pull or build the required image
+zen sandbox pull            # Re-pull base image or force build of sandbox/Dockerfile
+zen sandbox clean           # Force remove all zn-* containers created by this project
+zen sandbox disk            # Inspect disk space consumed by images, containers, and volumes
+```
+
+### Exit Codes and Common Issues
+
+- **Exit Code 5:** Container engine failed or image build failed.
+    - On macOS: ensure Podman machine is running (`zen sandbox up` or `podman machine start`).
+    - On Linux: verify rootless subuid/subgid mapping is configured (`/etc/subuid`).
+- **Permission Denied in `/workspace`:**
+    - In `strict` mode without `user:`, rootless Podman uses `keep-id` to preserve host UID. If using custom `user:`, verify host directory permissions allow that UID.
+- **Disk Space Pressure:**
+    - Run `zen sandbox clean` to prune stopped session containers.

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 four checks a narrow pass may never skip, 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, 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,7 +103,7 @@ 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 `➕`.
 
-## The four checks a narrow pass may never skip
+## The five checks a narrow pass may never skip
 
 However small the diff:
 
@@ -111,7 +111,11 @@ However small the diff:
    last.
 2. **`scripts/_setup.sh` has run to completion in this session, and re-runs
    clean.** A one-line specification change can still break a setup step, and a
-   pass that did not run it does not know.
+   pass that did not run it does not know. `skipped` is only a pass if the
+   artefact really is usable: for every index the project builds, check
+   `zen rag <subject> ready --dir <dir>` agrees. A step that tests for a
+   committed `manifest.json` skips on a fresh clone whose git-ignored `lance/`
+   vectors are missing, and the project cannot search.
 3. **§9 of the copilot instructions, worked as a checklist**, group by group.
 4. **The capability obligations in §0.1.** For every capability the project has
    turned on, load that capability's skill and re-check what it requires - in
@@ -119,6 +123,14 @@ However small the diff:
    `.github/skills/zen-memory/references/memory-instructions.md`. `zen init` and
    `zen open` rewrite the reference, so this drifts without anybody editing the
    project.
+5. **`zen-instructions` is loaded before any house rule is touched.** A pass
+   whose scope reaches `agents/*instructions.md` - and input 4 puts it there
+   whenever one of them moved - has to know that `tools-instructions.md`,
+   `files-instructions.md`, `memory-instructions.md` and `fork-instructions.md`
+   are `zen`'s and are replaced by `zen check --fix`. A pass that writes a
+   requirement into one of them has implemented nothing: the next `open` reverts
+   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.
 
 A narrow diff narrows reading and editing. It does not narrow verification.
 

package/templates/editor/.vscode/agents.schema.json

@@ -527,6 +527,11 @@
                     "type": "integer",
                     "exclusiveMinimum": 0
                 },
+                "hardening": {
+                    "description": "How much of the host the container may be. `standard` keeps the root filesystem writable and capabilities intact so package managers work. `strict` drops every capability, mounts the root filesystem read-only, restricts /tmp to a 64 MiB noexec tmpfs, and defaults network to none.",
+                    "type": "string",
+                    "enum": ["standard", "strict"]
+                },
                 "user": {
                     "description": "uid, name or `uid:gid`. Unset means the image's own user.",
                     "type": "string",
@@ -572,12 +577,12 @@
                     "$ref": "#/$defs/modelRef"
                 },
                 "tools": {
-                    "description": "Tool names and selectors: `workspace:*` is every file tool, `sandbox:*` the shell, `exa:*` web search and page reading. Subtract from a group with a leading `-`.",
+                    "description": "Tool names and selectors: `files:*` (alias `workspace:*`) is every file tool, `sandbox:*` the shell, `exa:*` web search and page reading. Subtract from a group with a leading `-`.",
                     "type": "array",
                     "items": { "type": "string", "minLength": 1 },
                     "examples": [
-                        ["workspace:*", "sandbox:*"],
-                        ["workspace:*", "-delete_file"]
+                        ["files:*", "sandbox:*"],
+                        ["files:*", "-delete_file"]
                     ]
                 },
                 "handoffs": {

package/templates/project/SPECIFICATION.md.tmpl

@@ -26,7 +26,8 @@ something in it — and report what was done in enough detail to be checked.
   an index built, a document fetched, a file generated.
 - `scripts/_setup.sh` is the one command that does it, and `scripts/<name>.sh`
   are the steps it runs in order. A step is safe to run twice and reports
-  `skipped` the second time.
+  `skipped` the second time — testing for something that survives a clone, not
+  for a file `.gitignore` excludes.
 - Currently: no steps. Nothing has to be prepared before a run.
 
 ## Agents

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.