@zenera/cli 1.1.20 → 1.1.22

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

@@ -31,7 +31,7 @@ because a prompt or skill someone changed outside a pass still has to be
 accounted for against the specification.
 
 The scope decides what you **read and edit**. It never decides what you
-**verify**: §6, §7 and the four checks in the skill run at full size on every
+**verify**: §6, §7 and the five checks in the skill run at full size on every
 pass, however small the diff.
 
 ## 1. Read before changing anything
@@ -148,6 +148,31 @@ not a paragraph of instructions for a human.
   to a temporary path and moving it into place so an interrupted run never leaves
   a half-built artefact behind. `scripts/_setup.sh --force` redoes everything,
   and reaches each step as `$FORCE=1`.
+- **A step's "already done" test must name something that survives a clone.**
+  Git-ignored output does not. A rag index commits its `manifest.json` and
+  ignores `lance/`, so `[ -f "$OUT/manifest.json" ]` is true on a fresh checkout
+  that cannot search at all - every step reports `skipped` and the failure
+  surfaces much later, as a search error nobody connects to setup. Ask the tool
+  rather than guessing at files: `zen rag docs ready --dir "$OUT" --quiet` exits
+  0 when the index can answer and 3 when it cannot, and
+  `zen rag docs restore --dir "$OUT"` re-embeds it from the copies it already
+  holds instead of indexing the documents again. A step that builds an index
+  looks like this:
+
+    ```sh
+    if [ "${FORCE:-0}" = 0 ] && zen rag docs ready --dir "$OUT" --quiet; then
+        echo "$OUT is already built"
+        exit 3
+    fi
+    if [ "${FORCE:-0}" = 0 ] && [ -f "$OUT/manifest.json" ]; then
+        zen rag docs restore --dir "$OUT"   # committed index, ignored vectors
+        exit 0
+    fi
+    rm -rf .tmp/docs-db
+    zen rag docs index assets/docs --embedding <ref> --out .tmp/docs-db
+    rm -rf "$OUT" && mv .tmp/docs-db "$OUT"
+    ```
+
 - **It must be watchable.** `scripts/_setup.sh` tees each step's output to
   `.tmp/logs/setup-<step>.log`, prints a heartbeat line while a long step runs,
   and finishes with one line per step: `ok`, `skipped`, or `failed`.
@@ -354,6 +379,11 @@ background and follow the logs instead of waiting blind:
   for the same reason, stop and raise it in `SPECIFICATION-FEEDBACK.md`.
 - Prove re-entrancy: once it has succeeded, run `scripts/_setup.sh` once more and
   check that every step reports `skipped` rather than rebuilding.
+- **`skipped` on a machine that has never built it is a bug, not a pass.** A
+  step that tests for a committed file skips on a fresh clone and leaves the
+  project unusable. For every index the project builds, check it can actually
+  answer - `zen rag docs ready --dir <dir>` - and fix the step's test if the
+  answer disagrees with what setup reported.
 
 ## 7. Verify and report
 

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

@@ -29,8 +29,8 @@ zen sandbox  [status|up|pull|clean|disk] [options]
 zen version
 
 zen faker    <serve|build|cache> [spec...]
-zen rag      schema <index|search|list|grep|trace|show|stats> [spec...]
-zen rag      docs <index|search|list|grep|show|stats> [path...]
+zen rag      schema <index|restore|ready|search|list|grep|trace|show|stats> [spec...]
+zen rag      docs <index|restore|ready|search|list|grep|show|stats> [path...]
 ```
 
 ## Read the reference before answering
@@ -39,19 +39,19 @@ The full reference lives next to this file, one document per part of the command
 line. **Read the one that covers the question before answering it** - do not
 guess a flag, and do not read them all.
 
-| The question is about                                               | Read                                    |
-| ------------------------------------------------------------------- | --------------------------------------- |
-| Global flags, `--json`, exit codes, environment, where files live   | [frame.md](./references/frame.md)       |
-| Creating, finding or opening a project                              | [projects.md](./references/projects.md) |
-| Running: the TUI, one-shot answers, sessions, workspaces, overrides | [run.md](./references/run.md)           |
-| Validating: `zen check`, what it can and cannot see                 | [check.md](./references/check.md)       |
-| API keys, providers, the keyring, "no credential" errors            | [keys.md](./references/keys.md)         |
-| Which models exist, whether one works, recovering from a refusal    | [models.md](./references/models.md)     |
-| The container shell commands run in, images, `persist`              | [sandbox.md](./references/sandbox.md)   |
-| Run reports, trajectories, what a session directory holds           | [inspect.md](./references/inspect.md)   |
-| What the agents remember, why something was recalled, forgetting    | [memory.md](./references/memory.md)     |
-| `zen faker` - a mock API from an OpenAPI/Swagger document           | [faker.md](./references/faker.md)       |
-| `zen rag` - searching an API description, or a pile of markdown     | [rag.md](./references/rag.md)           |
+| The question is about                                               | Read                                                            |
+| ------------------------------------------------------------------- | --------------------------------------------------------------- |
+| Global flags, `--json`, exit codes, environment, where files live   | [frame.md](./references/frame.md)                               |
+| Creating, finding or opening a project                              | [projects.md](./references/projects.md)                         |
+| Running: the TUI, one-shot answers, sessions, workspaces, overrides | [run.md](./references/run.md)                                   |
+| Validating: `zen check`, what it can and cannot see                 | [check.md](./references/check.md)                               |
+| API keys, providers, the keyring, "no credential" errors            | [keys.md](./references/keys.md)                                 |
+| Which models exist, whether one works, recovering from a refusal    | [models.md](./references/models.md)                             |
+| The container shell commands run in, images, `persist`              | [sandbox.md](./references/sandbox.md) (and `zen-sandbox` skill) |
+| Run reports, trajectories, what a session directory holds           | [inspect.md](./references/inspect.md)                           |
+| What the agents remember, why something was recalled, forgetting    | [memory.md](./references/memory.md)                             |
+| `zen faker` - a mock API from an OpenAPI/Swagger document           | [faker.md](./references/faker.md)                               |
+| `zen rag` - searching an API description, or a pile of markdown     | [rag.md](./references/rag.md)                                   |
 
 ## The short version
 

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

@@ -21,6 +21,7 @@ What it writes:
 zenera.json                     { version, name }
 agents.yaml                     the configuration
 agents/instructions.md          house rules, prepended to every agent
+agents/files-instructions.md     more of them, for agents that work with files
 agents/fork-instructions.md     more of them, for agents that can fork
 agents/memory-instructions.md   more of them, for agents with the memory store
 agents/tools-instructions.md    more of them, about how tools are called

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

@@ -1,7 +1,7 @@
 # API search - `zen rag`
 
 ```
-zen rag schema <index|search|list|grep|trace|show|stats> [spec...]
+zen rag schema <index|restore|ready|search|list|grep|trace|show|stats> [spec...]
 ```
 
 Provided by `@zenera/rag` - `npm i -g @zenera/rag` if `zen rag` says it is not
@@ -51,6 +51,36 @@ lance/            the vector and full-text indexes
 The manifest records the embedding ref **and** the embedder's own id, so a
 search with a different model is refused rather than quietly returning nonsense.
 
+## `ready` and `restore`
+
+```
+zen rag <docs|schema> ready   [-d <dir>] [--quiet] [--json]
+zen rag <docs|schema> restore [-d <dir>] [--embedding <ref>] [--dimensions <n>]
+```
+
+`lance/` is binary and rebuildable, so a project commits the index and
+git-ignores the vectors. A clone then holds an index that looks built and cannot
+search. `ready` is the question "can this answer", and the answer is the **exit
+code**: 0 searchable, 3 absent or missing its vectors. It needs no embedder and
+no credential.
+
+`restore` re-embeds the index from the copies in its own `sources/`, so nothing
+has to be fetched or found again. It is also how an index changes model:
+`--embedding <ref>` re-embeds everything and rewrites the manifest. The rebuild
+is staged beside the index and renamed into place, so a failure leaves the old
+one intact - and needs room for both meanwhile. A schema index built with
+`--no-sources` has nothing to restore from and is refused.
+
+In a setup step, in this order:
+
+```sh
+if [ "${FORCE:-0}" = 0 ] && zen rag docs ready --dir "$OUT" --quiet; then exit 3; fi
+if [ "${FORCE:-0}" = 0 ] && [ -f "$OUT/manifest.json" ]; then
+    zen rag docs restore --dir "$OUT"; exit 0
+fi
+# … otherwise index it from the documents
+```
+
 ## Which index gets read
 
 Every reading command takes `-d`, `--dir`. Without one:
@@ -331,7 +361,7 @@ They share the group `schema`, so an agent takes them with `schema:*` in its
 # Document search - `zen rag docs`
 
 ```
-zen rag docs <index|search|list|grep|show|stats> [args...]
+zen rag docs <index|restore|ready|search|list|grep|show|stats> [args...]
 ```
 
 The second subject of the same command. Where `schema` reads an API description
@@ -364,12 +394,16 @@ relative to the common root of everything indexed, which is what keeps
 
 ```
 docs-db/
-manifest.json     written last; its presence means the index is complete
+manifest.json     written last; its presence means the build finished
 outline.json      every heading and table, with the lines they cover
 sources/          the documents, verbatim
 lance/            one row per chunk: two texts, one vector, the filter columns
 ```
 
+The manifest means the build finished, not that the index can answer here:
+`lance/` is usually git-ignored. `ready` and `restore` above are the pair that
+closes the difference, for both subjects.
+
 ## `search`
 
 ```

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

@@ -83,8 +83,33 @@ that tag is absent, which is safe precisely because the tag follows the content.
 
 ## Hardening
 
-`no-new-privileges`, an init process, a pid limit, no restart policy. Not
-`--cap-drop=ALL` (it breaks `apt` and `pip`) and never `--privileged`.
+Every container gets the same floor: `no-new-privileges`, an init process, a
+pid limit of 1024, resource limits (`cpus: 4`, `memory: 4096`), no restart
+policy, podman's own seccomp profile (never turned off), and never
+`--privileged`.
+
+`hardening: standard` (the default) stops there. `--cap-drop=ALL` breaks `apt`
+and `pip`, and installing a package is the ordinary use of a shell - so the
+container is the boundary and nothing inside it is taken away.
+
+```yaml
+sandbox:
+    hardening: strict
+```
+
+`strict` is for running code nobody has read. It drops every capability,
+mounts the root filesystem read-only with `/tmp` as a 64 MiB
+`noexec,nosuid,nodev` tmpfs, runs as your own unprivileged uid via
+`--userns keep-id`, and defaults `network` to `none` and `cpus`/`memory` to
+`2`/`2048`. Name any of those keys yourself and your value wins.
+
+Two consequences: nothing can be installed at run time, so a strict project
+bakes its dependencies into the image with `build:`; and it needs rootless
+podman, which is also what makes an escape land on an unprivileged host
+account. Set `user:` explicitly to opt out of `keep-id`.
+
+`/workspace` stays writable either way - `strict` shrinks what a command can
+reach, not what the agent is there to edit.
 
 ## When it goes wrong
 
@@ -95,3 +120,6 @@ Podman is a warning.
 
 `zen sandbox clean` removes every container this CLI created - the way out of a
 container left on a bad rootfs.
+
+For complete container architecture, the `sandbox:*` tools, mount rules, and
+hardening details, load the `zen-sandbox` skill (`.github/skills/zen-sandbox/SKILL.md`).

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

@@ -0,0 +1,232 @@
+---
+name: zen-instructions
+description: The house rules - `agents/instructions.md` and every `agents/<topic>-instructions.md` prepended to every agent's system prompt. How the set is discovered and ordered, the `requires:` frontmatter and its closed vocabulary (`files`, `files-write`, `fork`, `memory`, `memory-write`, `memory-forget`), which four documents are `zen`'s own and are replaced by `zen check --fix`, how a project writes its own customisable topic prompts beside them (`files-policy-instructions.md`, `memory-policy-instructions.md`, `fork-<topic>-instructions.md`, `tools-<topic>-instructions.md`) without losing the copy, what belongs in a house rule as against an agent prompt or a skill, and every `zen check` finding these files can produce. Load before creating, editing, reviewing or deleting any `agents/*instructions.md`, before adding a capability whose rules arrive as one, and whenever `rules.stale`, `rules.unreached`, `files.uninstructed`, `memory.uninstructed` or `fork.uninstructed` is reported.
+---
+
+# House rules
+
+An agent's prompt is assembled, not written. The house rules are the part every
+agent gets, whoever is answering:
+
+```
+1. agents/instructions.md            the project's own, unconditional
+2. agents/<topic>-instructions.md    every one of them, in filename order
+3. agents/prompts/<name>.md          the agent's own job, or `system:`
+```
+
+Each document arrives as its own block tagged with the file it came from -
+`<house_rules src="agents/memory-instructions.md">` - so the model can tell one
+from the next and a report can say which file a rule was in. The documents are
+read **once** and the same objects are given to every agent, which is why
+`zen inspect` says "one document, five prompts" instead of showing five
+identical blobs.
+
+They are also the stable head of the cached prefix. A line here is paid for on
+every call by every agent, and a line added here invalidates that prefix for all
+of them. Change them rarely and deliberately.
+
+## The set is a glob, not a list
+
+There is **no key in `agents.yaml`** naming these files and no per-agent subset.
+The loader takes `agents/instructions.md` first, then every file in `agents/`
+whose name ends `-instructions.md`, sorted by filename. Directly inside
+`agents/` only - `agents/prompts/style-instructions.md` is not one - and all of
+it is optional: a one-agent project whose whole prompt is its role file needs
+none of them.
+
+Two consequences worth holding on to:
+
+- **Adding a file is the whole wiring.** Nothing else has to be edited, and
+  nothing reports a file you meant to add and did not.
+- **Order is the filename's**, because it is the only order that is the same on
+  every machine and is visible without opening anything. `agents/instructions.md`
+  does not end in `-instructions.md`, so it can never be counted twice.
+
+## Conditioning a document: `requires:`
+
+A document about one capability says so in its own frontmatter, and then reaches
+only the agents that have it:
+
+```markdown
+---
+requires: [memory]
+---
+
+# Memory
+
+...
+```
+
+The condition lives on the document rather than in `agents.yaml` because the
+condition and the prose it guards are one edit.
+
+| Capability      | Reaches an agent when                                          |
+| --------------- | -------------------------------------------------------------- |
+| `files`         | it declares file tools (`files:*` or individual file tools)    |
+| `files-write`   | it declares file write tools (`apply_patch`, `write_file`, …)  |
+| `fork`          | it declares `fork:` - and, at run time, is under the depth cap |
+| `memory`        | it declares `memory:` in any form                              |
+| `memory-write`  | its memory `access` is `read-write` or `full`                  |
+| `memory-forget` | its memory `access` is `full`                                  |
+
+Legacy aliases `workspace` and `workspace-write` match `files` and `files-write`.
+
+The vocabulary is **closed**. A name outside it is a load error
+(`rules.requires.unknown`), not a rule that silently never fires. A list means
+_all of it_ has to hold. There is no `not`: a rule for agents _without_ a
+capability is a rule about the rest of the project, which is what
+`agents/instructions.md` is for. No frontmatter means unconditional, which is
+the usual case.
+
+`fork` carries a run-time half as well - the tool is withdrawn at the fork depth
+cap, and a rule about a tool the model does not have is a rule it can only be
+confused by.
+
+## Two owners, in the same directory
+
+| File                                    | Whose     | `requires:` | Is                                                        |
+| --------------------------------------- | --------- | ----------- | --------------------------------------------------------- |
+| `agents/instructions.md`                | project's | -           | identity, shared model of the system, global constraints  |
+| `agents/tools-instructions.md`          | **ours**  | -           | how tools are called: narrate, batch the independent ones |
+| `agents/files-instructions.md`          | **ours**  | `files`     | how files are read, searched and patched; safety, mounts  |
+| `agents/memory-instructions.md`         | **ours**  | `memory`    | how the graph is reached, what to commit, how to correct  |
+| `agents/fork-instructions.md`           | **ours**  | `fork`      | what a branch is, what returns, when it is worth it       |
+| `agents/tools-<topic>-instructions.md`  | project's | yours       | **this project's** tool policy                            |
+| `agents/files-<topic>-instructions.md`  | project's | `files`     | **this project's** file policy                            |
+| `agents/memory-<topic>-instructions.md` | project's | `memory`    | **this project's** memory policy                          |
+| `agents/fork-<topic>-instructions.md`   | project's | `fork`      | **this project's** forking policy                         |
+
+The four marked **ours** describe _this version of `zen`_ - how the memory
+graph works, how its tools are called, what survives a join, how files are safely
+handled. They land under `agents/` only because that is where a document has to
+be to reach a prompt. They are not the project's to maintain:
+
+- `zen check --fix` **replaces all four** with the bytes this `zen` ships.
+- A copy that differs - edited in place, or scaffolded by an older `zen` - is
+  reported as `rules.stale`, because prose about a runtime that has since moved
+  reads exactly as authoritative as the version that is true.
+- So an edit made in one of them is lost at the next `--fix`, and a rule that
+  mattered is gone without a diff to show for it.
+
+They arrive whether or not the project uses the capability; their `requires:` is
+what keeps an inert one out of every prompt.
+
+## The project's own topic prompts
+
+This is the customisation point, and it is a **file beside**, never an edit
+inside. Anything this project decides for itself on a subject one of ours
+covers - which audience holds what, what must never be written down, how wide a
+fan-out may go, which tools are off limits here - is its own document:
+
+| Instead of editing       | Write                                  |
+| ------------------------ | -------------------------------------- |
+| `files-instructions.md`  | `agents/files-policy-instructions.md`  |
+| `memory-instructions.md` | `agents/memory-policy-instructions.md` |
+| `fork-instructions.md`   | `agents/fork-policy-instructions.md`   |
+| `tools-instructions.md`  | `agents/tools-policy-instructions.md`  |
+
+`<topic>` is yours; `policy` is the convention and needs no explaining. Then a
+`zen check --fix`, a `zen init` or a `zen open` refreshes our copy and takes
+nothing of yours with it.
+
+Three things to get right:
+
+1. **`requires:` is not inherited.** A `memory-policy-instructions.md` with no
+   frontmatter reaches every agent, including ones with no store. Copy the
+   condition from the document it qualifies - usually the same line.
+2. **Filename order decides what qualifies what.** A policy meant to be read
+   after our rules needs a topic word that sorts after `instructions`:
+   `memory-policy-…` lands after `memory-instructions.md` (`p` > `i`), and
+   `memory-audience-…` lands **before** it (`a` < `i`), qualifying prose the
+   model has not read yet.
+3. **It is a prompt, not a note.** Second person, imperative, failure paths
+   stated. Everything §4.2 of the copilot instructions says applies in full.
+
+## What belongs in a house rule
+
+Only what is true for **every** agent the document reaches:
+
+- identity and domain - _"You work the property claims desk"_
+- non-negotiable prohibitions: regulatory, legal, safety
+- global format and tone constraints
+- domain vocabulary and identifier formats
+- the shared model of the system: what the agents are collectively for, and how
+  work moves between them, in terms they can act on - _"the adjuster owns
+  coverage decisions; you do not"_ - not in terms of files or YAML keys
+
+Not here:
+
+| That                                          | Goes in                           |
+| --------------------------------------------- | --------------------------------- |
+| Anything one agent needs and another does not | `agents/prompts/<name>.md`        |
+| Long reference data, procedures, tables       | a skill, loaded when it is needed |
+| Anything that changes weekly                  | a skill, or `assets/`             |
+| A tour of the codebase                        | nowhere - it is not a README      |
+
+If you find yourself writing _"if you are the router…"_, you are in the wrong
+file. Target 20-60 lines per document; past ~100, split the stable half into a
+preloaded skill.
+
+Split a topic out of `agents/instructions.md` when it is true for every agent
+but belongs to **one capability** - it then arrives when the capability is
+turned on and is deleted when it is turned off, which is a whole file rather
+than a section somebody has to find. Do not split by author, by date, or to keep
+a file short.
+
+## Paths
+
+Every path-shaped token in these files is read by a model as an instruction to
+open something, and a running agent sees four: `/workspace`, `/assets`,
+`/skills`, `/memory`. The sweep is in the `zen-review` skill:
+
+```sh
+.github/skills/zen-review/scripts/check-paths.sh
+```
+
+It reads `agents/*instructions.md` and exits `1` on any candidate.
+`agents/memory-instructions.md` is exempt: it is worked examples by design, and
+`check-instructions.sh` is the check it actually needs.
+
+## What `zen check` reports
+
+| Finding                  | Severity | Means                                                            |
+| ------------------------ | -------- | ---------------------------------------------------------------- |
+| `rules.requires.unknown` | error    | `requires:` names no capability - the loader refuses the project |
+| `files.uninstructed`     | error    | an agent has file tools and `files-instructions.md` is absent    |
+| `memory.uninstructed`    | error    | memory is on and `memory-instructions.md` is missing or empty    |
+| `fork.uninstructed`      | error    | an agent can fork and `fork-instructions.md` is missing or empty |
+| `rules.stale`            | warning  | one of ours is not the copy this `zen` ships                     |
+| `house-rules.empty`      | warning  | a document contributes nothing but a prompt section              |
+| `rules.unreached`        | note     | a document of **yours** whose `requires:` no agent satisfies     |
+| `house-rules.missing`    | note     | no house rules at all, which is allowed                          |
+
+`zen check --fix` answers the first five between them: it rewrites all four of
+ours and the whole `.github/` tree, then validates, so the report and its exit
+code describe the repaired project.
+
+Two silences to know about. **There is no `tools.uninstructed`** - that document
+is unconditional and its absence is not reported, so a project that deleted it
+is quietly a project whose agents were never told how to call a tool. And
+`rules.unreached` deliberately never fires for ours, because they land in every
+project whether the capability is used or not.
+
+The memory copy has a check of its own, byte for byte, because the two files
+drift by trailing whitespace inside tables and that is invisible on screen:
+
+```sh
+.github/skills/zen-memory/scripts/check-instructions.sh        # the verdict
+.github/skills/zen-memory/scripts/check-instructions.sh diff   # every differing line
+.github/skills/zen-memory/scripts/check-instructions.sh fix    # copy the reference over
+```
+
+Never read the two against each other by eye, and never paraphrase the reference
+into prose of your own.
+
+## Related
+
+- `zen-memory` - what `memory-instructions.md` says, and how to design a policy
+  to put beside it
+- `zen-review` - the path sweep and the rest of the mechanical review
+- `zen-cli` - `zen check`, `zen check --fix`, `zen init`, `zen open`
+- §3.2 and §5.3 of `.github/copilot-instructions.md` - the short form of all of
+  the above