@zenera/cli 1.1.16 → 1.1.17

package/templates/editor/.github/prompts/review-project.prompt.md

@@ -4,32 +4,71 @@ description: Review the project against the checklist before committing.
 ---
 
 Review this project the way a maintainer would, then report. Read
-`agents.yaml`, `INSTRUCTIONS.md`, every file under `agents/prompts/` and the
-skill descriptions under `agents/skills/` before saying anything.
+`agents.yaml`, every `agents/*instructions.md`, every file under
+`agents/prompts/` and the skill descriptions under `agents/skills/` before
+saying anything.
 
-Work the checklist in §9 of the copilot instructions. In particular:
+**Run the mechanical checks first, and report what they say:**
+
+```sh
+.github/skills/zen-review/scripts/review.sh
+```
+
+That is `zen check`, the §2.5 path sweep, the memory house-rules copy and the
+spec-sync record, in the order they matter. Load the `zen-review` skill for what
+each one owns and how to read its output. Do not re-verify by hand anything it
+already decided, and do not go further while `zen check` fails - nothing below
+matters until it passes.
+
+**Then list the capabilities this project turns on** — a `memory:` block, a
+`zen rag` index, a sandbox, a `SPECIFICATION.md` — and load the editor skill
+for each before judging it. The obligations live in the skill, not in
+`agents.yaml`, and `zen check` reports none of them. A capability that is
+already configured and already passing is exactly the case that looks finished
+and is not.
+
+Everything that follows is what no tool can see:
 
-- **Loads.** Run `zen check`. Nothing else in this review matters if it fails.
 - **One job each.** Can you state every agent's job in one sentence? If not,
   say which agent and what the two jobs are.
 - **Prompts.** Second person, imperative, failure paths stated, no hedging, no
-  politeness padding, no meta-talk about the runtime. Nothing in
-  `INSTRUCTIONS.md` that is true of only one agent.
+  politeness padding, no meta-talk about the runtime. Nothing in the house rules
+  that is true of only one agent, and nothing in `agents/instructions.md` that
+  belongs in a `<topic>-instructions.md` of its own because it only applies when
+  one capability is on.
 - **Facts.** Any number, threshold, fee or date living in a prompt is in the
   wrong file. Name it and say which skill it belongs in.
-- **Paths.** Work the checklist in §2.5 over `INSTRUCTIONS.md`,
-  `agents/prompts/*.md` and `agents/skills/*/SKILL.md`. Every absolute path must
-  be under `/workspace`, `/assets`, `/skills` or `/memory`; nothing may name a
-  project file the agent cannot open, and nothing may assume the workspace is
-  this directory.
+- **Paths.** For each candidate `check-paths.sh` printed: is it a path the
+  agent cannot open, or noise? Say which, and for a real one say what it should
+  have been. Judge the rest of the §2.5 checklist yourself — that no instruction
+  assumes the workspace is this directory, that every `/assets/…` and
+  `/skills/<name>/…` names a committed file, and that the agent holding the
+  prompt has the tool the path implies.
+- **Memory.** Anything this project decides for itself belongs in
+  `agents/memory-policy-instructions.md`, not in the copy — and it should say
+  something. Audiences that exist because an agent would be _misled_ by the
+  other slice, not merely because it does not need it.
 - **Skill descriptions.** Each one a condition, not a title; no two overlapping.
+  Every skill a folder with a `SKILL.md`, and a skill that ships a script writes
+  its `/skills/<name>/…` path.
 - **Tools.** Every grant justified by the agent's job; nothing mutating held by
-  an agent that only reads; every granted tool mentioned by the prompt.
-- **Routing.** Handoff targets have descriptions written for the model. No
-  ping-pong edges. No router that answers.
+  an agent that only reads; every granted tool mentioned by the prompt. An agent
+  with no `skills:` key indexes the whole catalog - check that every agent can
+  actually follow the skills it is offered.
+- **Sandbox.** `persist: true` unless a throwaway rootfs is wanted on purpose.
+  What the work always needs is in the image, not installed by a prompt on every
+  run.
+- **Control flow.** Whichever this project uses. A handoff moves the
+  conversation and must have a path back; a fork returns by itself and condenses
+  to one result, so whatever the caller needs must be in the branch's answer.
+  Wanting one lookup and spending the conversation on it is a fork, not a
+  handoff. No router that answers.
 - **Models.** Each agent on the cheapest tier that is right, not the safest.
 - **Cache.** Nothing volatile - dates, ids, counts - in the stable prefix.
 - **Secrets.** No key inlined anywhere; `.env` ignored, `sessions/` ignored.
+- **Specification.** Where a `SPECIFICATION.md` exists, `review.sh` reported the
+  record's mode. Judge the rest: the newest history entry's "Still open" is
+  honest, its baseline names that entry, and `.spec-sync/` is committed.
 
 Report as a list of findings, each naming the file and the line, ordered by how
 much it will cost to leave. Say plainly if you find nothing worth changing.

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

@@ -7,6 +7,33 @@ the files are the implementation. Where they disagree, the specification wins -
 except where it is ambiguous, contradictory or impossible, which is what
 `SPECIFICATION-FEEDBACK.md` is for.
 
+## 0. Decide the size of this pass
+
+Load the `zen-spec-sync` skill first, before anything else and whatever state
+the project is in - a project with no baseline is the one that needs it most,
+because this pass has to make the first. Then, from the project root:
+
+```sh
+.github/skills/zen-spec-sync/scripts/snapshot.sh status
+.github/skills/zen-spec-sync/scripts/snapshot.sh diff
+```
+
+`status` answers `full`, `incremental` or `tampered`. Say which in the chat
+before reading anything, and on an incremental pass state the scope you drew
+from the diffs - the skill says how. `full` and `tampered` both mean the whole
+prompt as written below, from nothing.
+
+The diff covers both sides. `SPECIFICATION.md` and `SPECIFICATION-FEEDBACK.md`
+say what has been **asked for** since the last pass; `agents.yaml` and every
+file under `agents/` say what has been **built or hand-edited** since then. The
+first narrows the pass to the work nobody has done; the second only widens it,
+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
+pass, however small the diff.
+
 ## 1. Read before changing anything
 
 Read, in this order, and do not edit until all of it is read:
@@ -14,13 +41,17 @@ Read, in this order, and do not edit until all of it is read:
 1. `SPECIFICATION.md` - what the system is meant to be.
 2. `agents.yaml` - providers, models, embeddings, agents, tools, handoffs,
    skills, sandbox.
-3. `INSTRUCTIONS.md` and every file under `agents/prompts/`.
+3. Every `agents/*instructions.md` and every file under `agents/prompts/`.
 4. Every `agents/skills/*/SKILL.md`, plus what each skill folder ships.
 5. `assets/`, `sandbox/Dockerfile` and every script under `scripts/`, starting
    with `scripts/_setup.sh`.
 6. `SPECIFICATION-FEEDBACK.md`, if it exists - do not re-raise something already
    open there.
 
+On an incremental pass this list narrows to the artefacts the scope implicates,
+and to the changed hunks of the specification rather than all of it. The
+narrowing is a claim: name what you skipped and why the diff does not reach it.
+
 Run `zen check` first and record what it said. A project that does not load is
 the first thing to fix.
 
@@ -41,14 +72,15 @@ handoff edges and fork permissions; the tools each agent holds; every skill the
 specification implies; and every setup step, index or asset it depends on.
 
 Then build the difference the other way, because the list above can only find
-what the specification asked for and nothing implements. Read `INSTRUCTIONS.md`,
-each `agents/prompts/*.md` and each `SKILL.md` **line by line**, and for every
-line name the specification item it serves. A line serving none is an **extra** -
-the category covers a single sentence in a prompt, not only a whole file. Three
-things to look for while reading, none of which the forward pass can see:
+what the specification asked for and nothing implements. Read every
+`agents/*instructions.md`, each `agents/prompts/*.md` and each `SKILL.md` **line
+by line**, and for every line name the specification item it serves. A line
+serving none is an **extra** - the category covers a single sentence in a prompt,
+not only a whole file. Three things to look for while reading, none of which the
+forward pass can see:
 
 - **A line that contradicts another file.** One prompt against another, a prompt
-  against `INSTRUCTIONS.md`, or a prompt against `agents.yaml` - an instruction
+  against the house rules, or a prompt against `agents.yaml` - an instruction
   to use a tool the agent does not hold, to hand to an agent that is not in its
   `handoffs:`, or to load a skill outside its `allow:`.
 - **A line that asks for something the system already supplies.** A question put
@@ -60,6 +92,11 @@ things to look for while reading, none of which the forward pass can see:
 These are bugs whatever the specification says: fix them in place and report each
 one. An extra that is merely unspecified is reported under `➕`, not removed.
 
+On an incremental pass this reverse reading covers every file this pass touched
+plus every file the implementation diff in §0 named - an edit made in this
+session, or made by hand since the last pass, is exactly where a fresh
+contradiction comes from. On a full pass it is the whole tree, as above.
+
 ## 3. Change the smallest thing that closes the gap
 
 Apply the fixes in the order the copilot instructions prefer: a prompt or skill
@@ -132,8 +169,32 @@ anything in the
 specification is unclear, contradictory, impossible, or wrong. If there is
 nothing to raise, say so in the chat and do not create the file.
 
-Group entries under these headings, and omit a heading that has no entries.
-The file is scanned before it is read, so keep the emoji on every heading:
+**It is a questionnaire, and answering it must take one gesture.** Every
+question carries two to four written-out answers, each with a `[ ]` box in its
+heading. The reader marks the box of the one they want - `[x]` - and deletes the
+others, then sends `/update-spec-from-feedback`, which folds what survived into
+`SPECIFICATION.md`. Either gesture alone is enough, and the file says so in
+every question.
+
+Two rules that come before everything else in this section:
+
+- **No markdown tables anywhere in this file.** A table is unreadable the moment
+  a pane is narrow or a cell wraps, and this is a file people read in a side
+  panel. Every list is a list.
+- **Never write a question the reader has to do work to answer.** No paragraph
+  ending in "is that what you meant?", nothing that requires reading the
+  implementation, and no answer phrased as a decision still to be made. If you
+  cannot write two answers a reader could pick between, you have not understood
+  the problem well enough to ask about it yet.
+
+The file opens with one short paragraph: how many questions are open, and how to
+answer them - put an `x` in the box of the answer you want, delete the answers
+you do not want, or replace them all with a sentence of your own, then send
+`/update-spec-from-feedback`. Then a contents list, one line per question: its
+number as an anchor link, the question in under ten words, and what is built in
+the meantime. Then the questions, grouped under these headings, omitting any
+heading with no questions. The file is scanned before it is read, so keep the
+emoji on every heading:
 
 ```markdown
 # Feedback on SPECIFICATION.md
@@ -147,22 +208,129 @@ The file is scanned before it is read, so keep the emoji on every heading:
 ## ✏️ Errors and typos
 
 ## ➕ Out of scope - implemented but unspecified
+
+## ✅ Answered - folded into the specification
+```
+
+`✅` is written by `/update-spec-from-feedback`, not by you. Leave what is there
+alone except to strike an entry this pass has actually implemented, and say in
+the chat which ones you closed.
+
+### The shape of one question
+
+Each question is its own `###` heading - the emoji of its section, `Q` and a
+number, then the question itself, ending in a question mark. Under it, in this
+order:
+
+- **Where it comes from** - the specification text quoted as a blockquote,
+  introduced by a link to the exact line,
+  `[SPECIFICATION.md#L66](SPECIFICATION.md#L66)`, plus the section name. Link
+  every line you quote; a reader must reach it in one click. For a question
+  about something the specification does not say at all, link the section it
+  would belong to and say that it is silent there.
+- **Why it is a problem** - two or three sentences on what goes wrong, in terms
+  of behaviour: what an agent does, what a run produces, what breaks. Not
+  "unclear" or "ambiguous", which describe the sentence rather than the damage.
+- **Built in the meantime** - what the implementation does now, and the one fact
+  that made it the default. Or "Nothing - blocked."
+- **To answer** - the same sentence on every question, word for word: put an `x`
+  in one box below and delete the other answers, either one is enough.
+
+Then two to four answers, each its own `####` heading of the form
+`#### [ ] A. <the answer in one line, as the reader would say it>`. The one that
+is implemented comes first and is marked `_(built)_`, so the file reads as "this
+is what happens if you change nothing"; mark one `_(recommended)_` where it is
+better for a reason the reader can check. Under each answer heading:
+
+- **What it changes** - one or two sentences on the consequence of choosing it:
+  what the system would then do differently, and what it costs.
+- **The specification text**, in a fenced block, introduced by where it goes -
+  "replace line 66", "add after line 21", "delete lines 30-32". Written in the
+  specification's own voice and format so it can be pasted without editing.
+
+Every answer carries its own box and its own text. They are alternatives that
+will be read alone, so nothing may be shared between them and nothing may refer
+to a sibling ("as above", "same as A"). Where an answer needs a value only the
+reader has, put a `<placeholder>` in the block and say in **What it changes**
+what to substitute.
+
+Two rules on the answers themselves:
+
+- **An answer is a real alternative**, not a restatement of the question or a
+  hedge. "Decide later" is not an answer; "leave it unspecified, and the
+  reviewer keeps using whatever the default agent uses" is.
+- **Never write only one answer.** A question with nothing to choose between is
+  not a question. Even an `✏️` typo has two: the correction, and leaving it as
+  written with a line saying what stays wrong.
+
+Under `➕` the two answers are fixed: keep it, whose block is the specification
+text that would cover what was built, and remove it, whose **What it changes**
+says what removing it would cost and which files would go.
+
+### One question, written out
+
+Copy this shape exactly - the outer fence is four backticks only so the example
+can contain its own:
+
+````markdown
+### ❓ Q4. Do the three agents share one memory, or keep their own?
+
+**Where it comes from** - [SPECIFICATION.md#L14](SPECIFICATION.md#L14), _Common
+memory strategies_:
+
+> use memory to save plans of answering what was delegated to what
+
+**Why it is a problem** - the specification says what each agent writes and
+never says who may read it. Memory is one graph with an audience on every node,
+so this decides whether the orchestrator can plan from what a specialist
+resolved last week, or re-derives it every time.
+
+**Built in the meantime** - one shared slice: `memory: true` on all three, so
+anything one agent writes, another can recall. Chosen because nothing in the
+specification separates them.
+
+**To answer** - put an `x` in one box below and delete the other answers. Either
+one is enough.
+
+#### [ ] A. All three agents share one memory _(built)_
+
+**What it changes** - a lookup is paid for once for the whole system, and every
+agent's recall competes with every other agent's notes for the same few slots.
+
+Add under _Common memory strategies_, after line 17:
+
+```markdown
+All three agents read and write one shared memory: whatever one of them
+discovers is recallable by the others.
 ```
 
-Each entry is one bullet, opening with the emoji of the heading it sits under,
-then four parts in this order:
+#### [ ] B. Each agent keeps its own memory
 
-- **What the specification says**, quoted, with the section it is in.
-- **Why it cannot be implemented as written** - the specific gap, not "unclear".
-- **What was done in the meantime**, or "nothing - blocked".
-- **The question**, phrased so a one-line answer unblocks it.
+**What it changes** - recall gets sharper and cheaper because an agent only ever
+sees its own kind of note, and the same lookup is repeated by whoever did not do
+it first.
 
-Use no other emoji anywhere in the file - one per entry is what makes them
-scannable. Keep entries factual and short. Do not editorialise about the
-specification's quality, do not restate the runtime, and do not copy the whole
-section in.
-Append to the existing file rather than rewriting it; strike an entry only when
-this pass has actually resolved it, and say in the chat which ones you closed.
+Add under _Common memory strategies_, after line 17:
+
+```markdown
+Each agent reads and writes only its own memory. A finding one agent needs from
+another travels as part of the hand-off, not through the store.
+```
+````
+
+Use no emoji except the one on each heading. Keep the prose short. Do not
+editorialise about the specification's quality, do not restate the runtime, and
+do not copy a whole section in.
+
+Append to the existing file rather than rewriting it, keeping the numbering and
+the contents list in step. Numbers are never reused: a struck question's number
+retires with it.
+
+Read the feedback diff from §0 before writing: a question the human answered
+since the last pass is work to close, not a question to ask again. If a question
+has a box marked `[x]`, or one answer left under it, and no `✅` entry, the
+reader answered it and never ran `/update-spec-from-feedback` - implement that
+answer, fold its text into `SPECIFICATION.md` yourself, and say so in the chat.
 
 ## 6. Run `scripts/_setup.sh` and watch it finish
 
@@ -201,5 +369,24 @@ fail. Then report in the chat:
 - what is still open, with a pointer to its `SPECIFICATION-FEEDBACK.md` entry
 - anything you found that the specification does not cover at all
 
+## 8. Record the pass
+
+Last, and only once §6 and §7 have actually passed. Write
+`.spec-sync/history/<stamp>.md` in the format the `zen-spec-sync` skill gives -
+including `Still open`, which is the only place the next pass learns that an
+unchanged specification line is not yet implemented - and then:
+
+```sh
+.github/skills/zen-spec-sync/scripts/snapshot.sh commit
+```
+
+In that order, never the other way. Moving the baseline before the pass has
+finished records a specification as applied that was not: the next pass diffs
+against it, sees nothing to do, and the work is never done by anybody. A pass
+that fails with the baseline unmoved costs one repeat.
+
+A pass that changed nothing still writes a history file and still commits. Say
+in the chat which history file you wrote and that the baseline moved.
+
 Do not report a specification item as done unless the file that implements it
 exists, `zen check` passes, and `scripts/_setup.sh` completed every step it owns.

package/templates/editor/.github/prompts/update-spec-from-feedback.prompt.md

@@ -0,0 +1,142 @@
+---
+description: Fold the answers left in SPECIFICATION-FEEDBACK.md back into SPECIFICATION.md, and mark each answered question as answered.
+---
+
+`SPECIFICATION-FEEDBACK.md` is a questionnaire. Each question carries two to
+four written-out answers, each with a `[ ]` box in its heading, and the reader
+answers by **marking one box `[x]`, deleting the answers they do not want, or
+both**. Your job is to take the answer they chose under each question, put its
+text into `SPECIFICATION.md` where it says it goes, and mark the question
+answered.
+
+You change two files and no others: `SPECIFICATION.md` and
+`SPECIFICATION-FEEDBACK.md`. You implement nothing - not a prompt, not a skill,
+not `agents.yaml`. Making the project match the specification is
+`/sync-with-spec`, which runs after this.
+
+## 1. Read both files before editing either
+
+Read `SPECIFICATION-FEEDBACK.md` end to end, then `SPECIFICATION.md` end to end,
+and only then edit. The second read is what tells you whether an answer's text
+still fits where it is going.
+
+If there is no `SPECIFICATION-FEEDBACK.md`, say so in the chat and stop - there
+is nothing to fold in.
+
+## 2. Decide the state of every question
+
+Go through the questions in order and sort each into one of these, by what is
+left under it. Say in the chat how many fell into each before you edit anything.
+
+**Answered** - apply it:
+
+- exactly one answer has its box marked `[x]`, whatever else is still there
+- exactly one `####` answer is left, box marked or not
+- the reader wrote prose of their own in place of the answers, or edited the
+  answer they kept - then apply what they wrote, word for word
+
+**Open** - leave it exactly as it is:
+
+- two or more answers are left and none is marked
+- two or more boxes are marked `[x]` - that is not a choice, and the chat report
+  is where you say so
+
+**Rejected** - leave it, and ask in the chat:
+
+- no answers at all are left under the question
+
+**Done** - leave it alone:
+
+- it is already under `✅`
+
+A question with every answer deleted is the reader saying none of them fit.
+**Do not invent a fifth.** Say in the chat which question it was and ask what
+would fit; if they tell you, write their words in under the question as the
+answer and apply it in this same pass.
+
+A question with two or more answers still standing and no box marked is **not
+answered**. Never choose between them, never pick the `_(built)_` one because it
+is already true, and never break a tie by reading the implementation.
+
+## 3. Put the text into `SPECIFICATION.md`
+
+For each answered question, take the fenced block under its surviving answer and
+put it where the line above the block says it goes.
+
+- **The line number is a hint, not an address.** Every paste moves every line
+  below it, and the reader has been editing too. Anchor on the text quoted under
+  **Where it comes from**; if that text is gone, use the section it names. If
+  neither is there any more, do not guess: leave the question open and report it
+  as not applied, with what you looked for.
+- **Paste it verbatim.** Do not reword it, do not improve it, do not reflow it
+  to your own idea of the line width. The block was written in the
+  specification's voice for exactly this.
+- **A `<placeholder>` is filled in only with a value the reader supplied** - in
+  the block, in prose next to it, or in the chat. An unfilled placeholder means
+  the question is not answered yet; leave it open and say so.
+- **Keep the document consistent around the paste.** Heading level, list style,
+  tense and the words the specification already uses for things. If the new text
+  makes a neighbouring sentence false, or contradicts another section, fix that
+  too - and report each such edit on its own line, because it is a change no
+  answer asked for.
+- Work one question at a time, top to bottom, and re-read the file between
+  edits rather than trusting the line numbers you read at the start.
+
+Nothing outside `SPECIFICATION.md` changes here. If an answer's text implies an
+agent, a tool grant, a script or a skill, that is the next `/sync-with-spec`
+pass's work, and saying so is all you do about it.
+
+## 4. Mark the question answered
+
+Move the whole `###` block of each answered question to the end of the file,
+under:
+
+```markdown
+## ✅ Answered - folded into the specification
+```
+
+Keep its number and its original emoji, so a link to it still resolves and the
+number is never reused. Replace everything under the heading with, in this
+order:
+
+- **Answered** - the chosen answer's line, verbatim, without its `[ ]` box, or
+  the reader's own words where they wrote their own.
+- **In the specification** - a link to the line it now occupies,
+  `[SPECIFICATION.md#L66](SPECIFICATION.md#L66)`, and the new text quoted as a
+  blockquote.
+- **Still to implement** - one line saying what has to change in the project for
+  the specification to be true again, or `Nothing - the project already does
+this.`
+
+That last line is what the next `/sync-with-spec` works from, so write it as
+work, not as a summary.
+
+Then bring the top of the file back into step: the opening paragraph's count of
+open questions, and the contents list - an answered line keeps its link and
+shows the answer that won in place of what was built. Drop a heading that has no
+questions left under it, and add no markdown tables to this file.
+
+## 5. You are the typist, not the reader
+
+Do not answer a question yourself, do not soften a chosen answer because you
+would have chosen another, and do not add a requirement nobody asked for. An
+answer you think is wrong is still the answer; say why in the chat and leave the
+text alone.
+
+Do not run `zen check`, `scripts/_setup.sh` or anything under `.spec-sync/`. The
+baseline moves at the end of a `/sync-with-spec` pass and nowhere else -
+committing it here would record a specification as applied that nothing has
+implemented yet.
+
+## 6. Report
+
+In the chat:
+
+- each question you answered, and which answer won
+- every line of `SPECIFICATION.md` that changed, and what it says now
+- every edit you made that no answer asked for, and what made it necessary
+- what is still open, split into: more than one answer left, more than one box
+  marked, every answer rejected, and could not be applied because the place it
+  names is gone
+- then, in one line: send `/sync-with-spec` to make the project match the
+  specification you have just changed.

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

@@ -31,15 +31,18 @@ checked too. A word that is neither is a usage error (exit 2), not a report.
 
 - `agents.yaml` parses and satisfies the schema, with unknown keys reported
   rather than ignored.
-- Every file the configuration names is on disk and non-empty: `INSTRUCTIONS.md`,
-  each agent's prompt, each skill's `SKILL.md`, each asset glob.
+- Every file the configuration names is on disk and non-empty: the house rules
+  under `agents/`, each agent's prompt, each skill's `SKILL.md`, each asset glob.
+  A root `INSTRUCTIONS.md` is still read, and reported as something to move to
+  `agents/instructions.md`.
 - Hand-offs and forks name agents that exist, and no agent hands off to itself.
 - Tool selectors resolve against the real tool set, including a skill's own
   `tools:` frontmatter.
 - Skills bind to a catalog that holds them, and every declared skill is
   reachable from some agent.
 - Every declared model and embedding resolves to a provider, and that provider
-  has a credential on this machine.
+  has a credential on this machine. The project's `.env` is read first, exactly
+  as `zen run` reads it, so the verdict is the one a run would reach.
 - Unless `--no-models`, every model that has a credential is **asked to answer**
   once. A key that authenticates says nothing about the id it is spent on, so
   this is the only way to catch a misspelt, retired or ungranted model. A refusal

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

@@ -107,10 +107,12 @@ A real environment variable always beats the keyring.
 
 <project>/
     zenera.json           { version, name }
-    INSTRUCTIONS.md       house rules, prepended to every agent's prompt
     agents.yaml           the configuration
-    agents/prompts/       one .md per agent
-    agents/skills/        one directory per skill, each with SKILL.md
+    agents/
+        instructions.md   house rules, prepended to every agent's prompt
+        *-instructions.md more house rules, in filename order
+        prompts/          one .md per agent
+        skills/           one directory per skill, each with SKILL.md
     sandbox/Dockerfile    the image commands run in, when the project builds one
     sessions/             run state, memory, blobs, reports - never committed
 ```

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

@@ -19,18 +19,30 @@ What it writes:
 
 ```
 zenera.json                     { version, name }
-INSTRUCTIONS.md                 house rules
 agents.yaml                     the configuration
+agents/instructions.md          house rules, prepended to every agent
+agents/memory-instructions.md   more of them, about the memory store
 agents/prompts/default.md       the default agent's prompt
 agents/skills/                  empty, for skills
 assets/README.md
 sandbox/Dockerfile              the image the sandbox builds
 sessions/                       empty
+.env                            this project's environment, git-ignored
 .gitignore
 .vscode/settings.json           editor files
 .github/                        copilot instructions, prompts, this skill
 ```
 
+More house rules can be added by hand: any `agents/<topic>-instructions.md` is
+read too, in filename order, and prepended to every agent. A capability that
+needs standing rules - memory, say - gets its own file rather than another
+section of `agents/instructions.md`. Memory's are not written from scratch:
+`agents/memory-instructions.md` is the same file as
+`.github/skills/zen-memory/references/memory-instructions.md`, which init puts
+in the project as well, so a copy that was lost or went stale is restored rather
+than rewritten - `.github/skills/zen-memory/scripts/check-instructions.sh` says
+which of the two it is, and `… fix` does the copy.
+
 The project's own files are never overwritten - `--force` is what allows
 writing into an occupied directory, and the files already there stay. The
 editor files are the exception: `.vscode/settings.json` and the `.github/` tree
@@ -38,7 +50,12 @@ are ours and are replaced on every `init` and every `zen open`, so edits to them
 do not survive.
 
 The default agent gets the file tools and a sandboxed shell, plus `exa:*` when
-the keyring holds an Exa key.
+the keyring holds an Exa key. It also gets memory: the store is scaffolded in
+`memory/`, the agent is bound to it with `memory: true`, and it is vectorised by
+the chosen provider's embedding model. A provider that publishes none -
+Anthropic - gets the store without an `embeddings:` entry, and recall ranks by
+term overlap until one is added; an entry naming a provider with no embeddings
+API is a project that fails to load, not one that degrades.
 
 **Choosing the model.** Without `--model`, the keyring is asked - not counted.
 Stored credentials are probed, because holding a key is not the same as holding

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

@@ -47,6 +47,12 @@ Top level, and again per agent, where an agent's block is merged over the base.
 `CREDENTIAL`: the keyring has already materialised real credentials into the
 process environment, and a sandbox is the last place they should be forwarded to.
 
+The door for those is the project's `.env`, which `zen init` writes and
+`.gitignore` covers. `zen run` reads it before loading the project and forwards
+every name in it into the container **by name**, so the value never reaches an
+argv. `keys: false` and `zen run --no-keys` withhold it along with the API keys.
+The shell's environment wins over the file; the keyring fills in the rest.
+
 ## `persist: true` is usually what you want
 
 Only `/workspace` and `/home/agent` survive an ephemeral container. A