@zenera/cli 1.1.23 → 1.1.25

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

@@ -0,0 +1,61 @@
+# `zen meta` - the meta agent, on this project
+
+```
+zen meta run [project] "<question>"        ask it something
+zen meta run [project] /<name> [words]     run .github/prompts/<name>.prompt.md
+zen meta prompts [project]                 list the stored prompts
+zen meta resume [project] [session]        carry on a run that stopped
+zen meta model [ref]                       show or set the model it uses
+zen meta dataset <verb>                    see dataset.md
+```
+
+`zen meta --help` has every option.
+
+## `--json`
+
+`zen meta run --json` prints ONE object on stdout when the run ends:
+
+```json
+{
+    "project": "/path/to/project",
+    "provider": "vertex",
+    "model": "vertex/gemini-3.8-flash",
+    "sessionId": "…",
+    "exitCode": 0,
+    "resumes": 0,
+    "usage": {},
+    "tokens": {
+        "calls": 12,
+        "inputTokens": 0,
+        "cachedInputTokens": 0,
+        "outputTokens": 0,
+        "reasoningTokens": 0
+    },
+    "answer": "the final answer, as markdown",
+    "answerFile": "/path/to/project/.tmp/logs/meta.<when>.md"
+}
+```
+
+`tokens` is summed over every model call of the run; `usage` is the meta
+agent's own end-of-session summary, passed through as it came, and may be absent.
+
+- Progress goes to stderr as plain lines: no box, no animation, no status row.
+  stdout carries the object and nothing else, so redirect it to keep it:
+
+    ```
+    zen meta run acme /analyze --json > analyze.json
+    zen meta run acme /analyze --json > analyze.json 2> analyze.log
+    ```
+
+- Nothing is asked. A `run` with no question, no `/<name>` and nothing piped
+  in is a usage error (exit 2) that lists the prompts, not a menu.
+- A run the meta agent ends in failure still prints the object, then exits 1.
+  Check `exitCode`; `sessionId` is what `zen meta resume` takes. A run that
+  never starts (no key, bad model) prints no object, only the error.
+- `--dry-run --json` gives `{project, provider, model, from, command, env}`,
+  secrets masked, and runs nothing.
+- `zen meta prompts --json` gives `[{name, description, path}]`;
+  `zen meta model --json` gives `{model, from, sources}`.
+
+The answer is also saved as markdown on every run, with or without `--json`;
+`answerFile` is its path.

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

@@ -1,7 +1,7 @@
 # Models - `zen models`
 
 ```
-zen models <providers|ls|search|show|test|pick> [ref] [options]
+zen models <providers|ls|search|show|test|pick|browse> [ref] [options]
 ```
 
 Alias: `model`.
@@ -21,6 +21,7 @@ but a credential.
 | `zen models show <ref>`     | One model, every field the vendor gave                 |
 | `zen models test <ref> …`   | One real minimal call per ref, and a verdict           |
 | `zen models pick`           | The first ref that answers, printed on stdout          |
+| `zen models browse`         | Interactive TUI for a person; needs a terminal         |
 
 Filters, on `ls` and `search`: `--chat`, `--embeddings`, `--images`, `--audio`,
 `--tools`, `--vision`, `--free`, `--min-context <n>`, `--provider <name>`,
@@ -28,6 +29,9 @@ Filters, on `ls` and `search`: `--chat`, `--embeddings`, `--images`, `--audio`,
 
 `pick` requires `--chat` or `--embedding`, and takes `--provider` and `--limit`.
 
+`browse` is for a person at a terminal and refuses without one (exit 2). An
+agent wants `ls --json`, `search` or `pick` instead.
+
 ## Where the lists come from
 
 The providers themselves, cached for a day in `~/.zenera/neo/catalog`. When a
@@ -71,7 +75,7 @@ This is what the command is for.
 ```
 $ zen models test vertex:gemini-embedding-001
 vertex:gemini-embedding-001  blocked  Vertex AI API has not been used in project my-proj …
-vertex:gemini-embedding-001: gcloud services enable aiplatform.googleapis.com --project my-proj
+fix vertex:gemini-embedding-001 gcloud services enable aiplatform.googleapis.com --project my-proj
 error 1 of 1 did not answer
         find one that does: zen models pick --embedding
 ```

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

@@ -81,16 +81,23 @@ the first segment as a **provider name**, not a vendor, so a bare
 ## `zen list`
 
 ```
-zen list [--sessions] [--prune]
+zen list [--sessions] [--runs] [--limit <n>] [--prune]
 ```
 
 Every known project: its sessions, the last run, and whether one is live right
 now.
 
-| Flag         | Meaning                                      |
-| ------------ | -------------------------------------------- |
-| `--sessions` | Expand each project into its sessions        |
-| `--prune`    | Forget entries whose directory has gone away |
+| Flag          | Meaning                                                  |
+| ------------- | -------------------------------------------------------- |
+| `--sessions`  | Expand each project into its sessions                    |
+| `--runs`      | The most recent runs, newest first, across every project |
+| `--limit <n>` | Runs to list. Default 20                                 |
+| `--prune`     | Forget entries whose directory has gone away             |
+
+`--runs` answers "what ran last", which is not a question about one project, so
+on its own it replaces the table rather than following it; each row names the
+project and session it belongs to, and `--json` gives the run directory too —
+which is what `zen inspect --dir` takes.
 
 The registry is an index, not the truth. An entry pointing at a directory that
 no longer exists is shown dimmed rather than hidden, because a moved project is

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

@@ -558,6 +558,7 @@ ordinary hybrid search and narrow by file or section.
 zen rag docs list <files|sections|tables> [-f <pattern>] [-s <section>]
 zen rag docs grep <pattern> [-f <pattern>] [--regex] [--case-sensitive]
 zen rag docs show <file> [--section <name>] [--lines <from-to>]
+zen rag docs show <target>... [--max-lines <n>]
 ```
 
 `list sections` gives every heading with the lines it spans, which is how a
@@ -566,6 +567,23 @@ total even when `--limit` cuts the rows, so unlike a search it can answer
 whether a string appears at all. `show` prints a document, a named section, or
 a line range, verbatim.
 
+### Reading several passages in one call
+
+Name every passage you will read or cite in **one** `show`, as
+`<document>:<a>-<b>`, `<document>:<a>` or `<document>#<heading>` - the form a
+citation is written in, so a citation pastes back unchanged:
+
+```sh
+zen rag docs show -d <index-dir> "<doc-1>:24-60" "<doc-2>:25-40" "<doc-3>#<heading>"
+```
+
+Each target prints under a header that is itself a target, in the order given;
+overlapping ranges in one document print once. A missing document or heading is
+reported in place and the rest still print (exit 1 only when none could be
+read). `--max-lines` (default 400) is shared fairly between targets, and a cut
+block ends with the target that continues it. `--json` returns
+`{results, printed, failed}`. `--section` and `--lines` read one document only.
+
 ### Reading a complete section or table
 
 Search finds relevant passages, not necessarily every row of a table. When the
@@ -596,12 +614,12 @@ the answer needs every row.
 
 `@zenera/rag/docs/tools` exports four tools in the group `docs`:
 
-| Tool          | For                                                             |
-| ------------- | --------------------------------------------------------------- |
-| `search_docs` | The search above, with the same narrowing parameters            |
-| `list_docs`   | The documents, their headings, or their tables - no ranking     |
-| `grep_docs`   | Every matching line, counted in full - the way to prove absence |
-| `read_docs`   | A section or a line range, verbatim and complete                |
+| Tool          | For                                                              |
+| ------------- | ---------------------------------------------------------------- |
+| `search_docs` | The search above, with the same narrowing parameters             |
+| `list_docs`   | The documents, their headings, or their tables - no ranking      |
+| `grep_docs`   | Every matching line, counted in full - the way to prove absence  |
+| `read_docs`   | A section or a line range, verbatim; several at once via `reads` |
 
 Only `search_docs` ranks. Every answer carries line numbers and `read_docs`
 takes them, which is the loop the subject exists for: find the passage, read

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

@@ -14,14 +14,18 @@ answers once on stdout and exits.
 | `--project <name\|dir>` | Which project. Inferred from the directory otherwise     |
 | `--session <id>`        | Continue a particular session                            |
 | `--new`                 | Start a new session rather than continuing one           |
+| `--input <file>`        | Read the whole request from JSON; `-` is stdin           |
 | `--workspace <dir>`     | What the agent may read and write                        |
 | `--memory <dir>`        | Where the agents remember into, instead of the project's |
+| `--memory-read-only`    | Recall from it; write nothing back                       |
 | `--model <ref>`         | Override the default model for this run                  |
 | `--image <ref>`         | Override the container image commands run in             |
 | `--read-only`           | Withhold every tool that can write                       |
 | `--plain`               | Never open the TUI; a prompt is then required            |
 | `--theme <dark\|light>` | Palette for the TUI; `auto` detects. `$ZENERA_THEME`     |
 | `--out <file>`          | Put the answer in this file instead of on stdout         |
+| `--batch-dir <dir>`     | Where a batch's runs live. `<project>/batches/<stamp>`   |
+| `--concurrency <n>`     | How many of a batch run at once. Default 16, most 32     |
 | `--yes`                 | Say yes to the workspace and install questions           |
 
 Flags always beat the file: the repository states intent, the invocation
@@ -38,6 +42,7 @@ the file is the only place it lands.
 zen run "what changed?" > out.md              answer in the file, progress on screen
 zen run "what changed?" > out.md 2>/dev/null  ... and nothing on screen at all
 zen run --out out.md "what changed?"          the same file, stdout left empty
+zen run --json --out run.json "what changed?" the whole envelope, in a file
 ```
 
 There is no `--quiet`. Narration is on stderr already, so a redirect is enough;
@@ -46,7 +51,9 @@ There is no `--quiet`. Narration is on stderr already, so a redirect is enough;
 `--json` answers with the paths as well as the answer: the session and run
 directories, every file the run left behind, and every tree the agent could see,
 with the path it had on this machine beside the path it had inside the
-container.
+container. `--out` takes that envelope off stdout the same way it takes the
+prose — with `--json` the envelope _is_ the answer, so the file holds all of it
+and stdout is left empty.
 
 ```json
 {
@@ -58,7 +65,8 @@ container.
         "output": ".../output.md",
         "state": ".../state.json",
         "meta": ".../meta.json",
-        "report": ".../report.html"
+        "report": ".../report.html",
+        "graph": ".../graph.mmd"
     },
     "mounts": [
         { "host": "...", "at": "/workspace", "readOnly": false },
@@ -76,11 +84,198 @@ container.
 `mounts` also lists the container's `$HOME` and, when keys are forwarded, the
 credential files mounted under `/run/zenera/keys`.
 
+## A request in a file
+
+`--input <file.json>` is the whole invocation written down. It is the only way
+to ask about a picture - a command line cannot carry one - and it is what makes
+a run reproducible: a case is a file, so it can be checked in, diffed and re-run.
+
+```json
+{
+    "project": "acme",
+    "input": [{ "text": "what is in this picture?" }, { "image": "./shot.png" }],
+    "workspace": "./ws",
+    "memory": "./mem"
+}
+```
+
+Only `input` is required, and it may be a plain string instead of an array. Each
+part is a bare string, `{ "text": "…" }`, one of `{ "image" | "audio" | "video" |
+"file": "…" }`, or the canonical `{ "type", "url", "mimeType" }` - the same shapes
+the library's `Input` accepts, because the file is a JSON projection of it.
+
+Three rules, and they are the whole of the format:
+
+- **Paths are relative to the file**, not to the directory you ran from, so a
+  case travels with the images beside it. With `--input -` there is no file, so
+  they are relative to the cwd. A bare `project` is a registered name and is
+  left alone; one starting with `.` or `/` is a directory.
+- **The file wins** over the same flag on the command line. A field it leaves
+  out falls through to the flag, then to the usual default. This is the one
+  place the rule above the options table is reversed - the file _is_ the
+  invocation, not a repository's standing intent.
+- **A local media path is inlined** as a `data:` url, so the state a run resumes
+  from carries the picture rather than a path that meant something elsewhere.
+  `http(s):` and `data:` urls are passed through untouched. The bytes land in
+  `state.json` and are rewritten on every later turn of that session, so there
+  is a 20 MB ceiling and a warning well before it.
+
+A request never opens the TUI and never asks about the workspace, exactly like a
+prompt on the command line. Giving both a prompt and `--input` is an error.
+
+```
+zen run --input case.json --json | jq -r .output
+cat case.json | zen run --input - --json
+zen run --input case.json --json --out result.json          everything, in a file
+zen run --input case.json --session 20260825-143012-a7f3   continue, don't start
+```
+
 `--plain` never opens the TUI. The TUI is the only thing that can ask for a
 prompt, so with `--plain` the prompt has to be there already - in the argument
 or on stdin - and `zen run --plain` with neither is an error instead of a
 window. Say it in a script that must not meet one.
 
+## Many at once - `zen run batch`
+
+```
+zen run batch --input cases.json [--batch-dir <dir>] [--concurrency 16]
+              [--memory <dir>] [--memory-read-only] [--out <file>] [--json]
+```
+
+The same file, pluralised. One project, many questions, sixteen at a time by
+default:
+
+```json
+{
+    "batch": [
+        { "id": "vat", "input": "what is the VAT threshold?" },
+        { "input": [{ "text": "what is this?" }, { "image": "./shot.png" }] },
+        { "id": "ws", "input": "read the notes", "workspace": "./cases/ws" }
+    ]
+}
+```
+
+An item takes `input`, an optional `id` and an optional `workspace`, and nothing
+else. `project` and `memory` belong to the batch rather than to an item, so they
+are flags: a file that names either is refused rather than half-honoured. An
+`id` names a directory, so it has to be one - letters, digits, dot, dash and
+underscore - and it defaults to the item's index. Two items may not share an
+`id` or a `workspace`, because they run at the same time.
+
+Everything refusable is refused before the first model call. A batch pays for a
+mistake once per item.
+
+### What it leaves behind
+
+```
+<batch-dir>/
+    README.md           a live dashboard, rewritten every second
+    batch.json          the index: every item, whether it worked, where it is
+    <id>/
+        workspace/      what that item could read and write
+        memory/         its own copy, in the copying mode only
+        output.json     exactly what `zen run --json` prints for one run
+```
+
+`README.md` is where the progress of a batch lives. Sixteen agents narrating at
+once would be noise, so instead the file is rewritten once a second: a
+fixed-height panel showing every worker - what it is running, the tail of what
+it is thinking or writing, its turns and its tokens - over a `Tokens by model`
+table, a table of the finished ones and a list of the ones still waiting. The
+panel keeps its height while there is work left to start, so nothing jumps
+between ticks. Watch it in an editor preview, or `watch -n1 cat "$DIR/README.md"`.
+When the batch ends the same file is the report.
+
+Tokens are reported **per model**: agents may each use a different one, so one
+total belongs to none of them. Every model id gets a row with its calls and its
+input, cached, output and thinking tokens, and the rows always add up to the
+batch total. Tokens spent summarising, which no node attributes to a model, are
+shown as `(compaction)`.
+
+Each `output.json` is written the moment its item finishes, so a batch stopped
+half way still has every answer it managed to get. `batch.json` is an index, not
+a second copy - it points at the files:
+
+```json
+{
+    "batch": {
+        "dir": "...",
+        "items": 3,
+        "ok": 2,
+        "failed": 1,
+        "concurrency": 16,
+        "memory": { "source": "...", "mode": "read-only" },
+        "usage": {
+            "inputTokens": 0,
+            "cachedInputTokens": 0,
+            "outputTokens": 0,
+            "reasoningTokens": 0
+        },
+        "models": [{ "model": "gemini-3-flash", "calls": 12, "usage": {} }],
+        "durationMs": 0
+    },
+    "batch_results": [
+        { "index": 0, "id": "vat", "ok": true, "input": "…", "output": ".../vat/output.json" },
+        {
+            "index": 1,
+            "id": "1",
+            "ok": false,
+            "input": "…",
+            "output": "...",
+            "error": { "message": "…" }
+        }
+    ]
+}
+```
+
+A failure is data. One item that cannot be answered costs one answer, not the
+other ninety-nine; the exit code says how many failed, and it is set after
+everything is written.
+
+stdout is the batch directory and nothing else, so `ls "$(zen run batch --input
+cases.json)"` works. `--json` prints the index there instead. Progress is in
+`<batch-dir>/README.md` either way. `--out` puts the index in a second file as
+well.
+
+### Memory, in two modes
+
+A memory is a locked directory, so sixteen runs cannot hold one. Which leaves
+two honest arrangements, and the flag picks between them:
+
+| Mode                 | What happens                                                       |
+| -------------------- | ------------------------------------------------------------------ |
+| `--memory-read-only` | Every item recalls from the one graph. Nothing is written, no lock |
+| default              | Each item gets a copy under `<batch-dir>/<id>/memory`              |
+
+In the copying mode the project's own memory is never touched. Fold what the
+items learned back in afterwards, having read it:
+
+```
+zen memory merge <batch-dir>/*/memory
+```
+
+An item that committed nothing leaves no `memory/` behind, so that line never
+names a directory `merge` would refuse.
+
+`--memory <dir>` names the source in both modes; without it the source is the
+project's own memory, and a project with none runs the batch with none. A
+source that does not exist yet is not an error in the copying mode: a project
+declares its memory directory and the first run makes it, so every item simply
+starts from an empty graph. That is how a cold project is warmed, and pointing
+`--memory` at a directory that is not there is how you ask for it deliberately.
+A batch refuses to start while another run holds that memory's lock.
+
+`--memory-read-only` works on a single `zen run` too. It is how you ask a
+question of what the agents know without changing what they know.
+
+### What means nothing in a batch
+
+`--session`, `--new`, `--workspace`, `--plain` and `--theme` are refused by
+name rather than ignored. Every item is a new session of its own, they cannot
+share a workspace, and a batch never draws the TUI.
+
+For a project or a prompt actually called "batch", say `--project batch`.
+
 ## Which word is the project
 
 The first positional is read as a project when it names one, and as the first
@@ -138,7 +333,7 @@ run history. Ids look like `20260825-143012-a7f3`.
 ```
 <project>/sessions/<id>/
     workspace/          what the agent sees, unless --workspace said otherwise
-    runs/<run-id>/      input.md, output.md, state.json, report.html, meta.json
+    runs/<run-id>/      input.md, output.md, state.json, report.html, graph.mmd, meta.json
     .data/
         state.json      the live, resumable state, rewritten after every run
         session.json    when it was made, and the workspace it is rooted at
@@ -162,4 +357,6 @@ definition and is taken over.
 ## Afterwards
 
 Each run writes a `report.html` next to its state; the run prints a
-`file://` link to it. See [inspect.md](inspect.md).
+`file://` link to it. It writes a `graph.mmd` beside it too - the same
+trajectory as one Mermaid flowchart, which is what `zen inspect graph` prints.
+See [inspect.md](inspect.md).

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

@@ -119,7 +119,16 @@ distinguishes the two cases: a broken Dockerfile is an error, a laptop with no
 Podman is a warning.
 
 `zen sandbox clean` removes every container this CLI created - the way out of a
-container left on a bad rootfs.
+container left on a bad rootfs. `--idle` removes only what no live run is using:
+stopped containers, and running ones whose run was killed before stopping them
+(`zen sandbox status` marks those `orphaned`).
+
+`could not create container … exceeded num_locks (2048)` means the engine is out
+of locks: every container holds one, stopped ones included, and `persist: true`
+leaves one stopped per session. `zen run` and `zen run batch` check this before
+the first model call and exit `5` when the engine cannot hold them (a batch needs
+one per item it runs at once). `zen sandbox status` shows a `locks` row when few
+are left; `zen sandbox clean --idle` frees them.
 
 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-code-python/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: zen-code-python
+description: Code an agent writes must be a reusable tool that can be remembered and re-run, never a one-off. Holds the coding rules (`references/code_python.md`) and decides where they go in the target project - a section of a dedicated code agent's system prompt, or a coding skill for generic agents that sometimes run code - how to adapt them, and what a prompt or skill for a code-writing agent must never say. Load before writing, editing or reviewing any agent prompt, skill or house rule for an agent that writes or runs code - any agent holding `sandbox:*` or `run_command` - and before shipping a script inside a skill.
+---
+
+# Code an agent writes is a tool
+
+A script an agent writes is worth more than the answer it printed. Written
+generically - every changing value an argument, a name that says what it does -
+it can be committed to memory as a `file` node and found again by the next
+similar question, which runs it instead of writing it again. Written as a
+one-off - this customer's id, this month, this path, as literals - it can only
+ever answer the question that produced it, and memory fills up with near-copies
+that never fold together.
+
+Nothing in the runtime enforces this, and `zen check` does not report it. The
+rules reach an agent only through what you write into the target project.
+
+## The reference
+
+`references/code_python.md` is the rule set, in wording that has been tested on
+models. It is a source to build from, not a file to copy. Start from its
+sentences - copying and then editing them works; rewriting them from scratch in
+your own words loses the mechanical phrasing that makes them obeyed.
+
+**Keep in substance, and never soften:**
+
+- every value that would change for the next similar question is a named
+  argument, never a literal
+- the file is named for what it does, and describes itself through `--help`
+- the result goes to stdout, a produced file to an `--output` path
+- the script is written to a file and the file is run - no `python -c`, no
+  heredoc
+- before using the output, the script is checked against a different question
+  of the same kind
+- with memory: search before writing, commit the working script after
+
+**Adapt to the project:**
+
+- the interpreter and language, if the sandbox image runs something other than
+  Python
+- where scripts are written - `/workspace/scripts/` unless the project already
+  has a place
+- libraries the image carries and the agent should prefer, and the output
+  format the project expects (JSON, CSV, a table)
+- an example invocation from this project's own domain, values passed as
+  arguments
+- the memory steps: keep them when the agent holds `memory_search` /
+  `memory_commit`, drop them when it never will. In a skill several agents may
+  load, keep them gated on the tool, as the reference does
+
+## Decide where the rules go
+
+List the agents that hold `sandbox:*` or `run_command`, and read each one's
+prompt for what its job is. Then:
+
+| The project has                                                                          | Write                                                                                                          |
+| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| A **dedicated code agent** - a runner, an executor, an analyst whose answers are scripts | A `## Writing code` section in that agent's `agents/prompts/<name>.md`                                         |
+| **No dedicated code agent** - generic agents that sometimes run code                     | A coding skill, `agents/skills/code_python/SKILL.md`                                                           |
+| Both                                                                                     | The prompt section, and the generic agents hand the code work to that agent rather than writing it - see below |
+| No agent that writes or runs code                                                        | Nothing                                                                                                        |
+
+**A dedicated code agent gets the rules in its system prompt.** It writes code
+on nearly every turn, so the rules are part of its job description: a skill
+would cost a load on every case, and preloading one is the same text in the
+prefix with an extra file to keep in step. Put the section after the agent's
+identity and procedure, before its prohibitions.
+
+**Generic agents get a skill.** Most of their turns write no code, so the rules
+should cost nothing until one does. The `description` is the routing key - name
+the condition, not the topic:
+
+```yaml
+description: Before writing, changing or running any Python script - how to write it as a reusable tool rather than a one-off.
+```
+
+Leave it in the agent's index; do not preload it. If `allow` is used, add
+`code_python` to it for every agent holding `sandbox:*`.
+
+**With both, one copy.** Generic agents that can reach a code agent should
+`fork:` to it for an answer, or hand off to it, rather than writing code
+themselves - then the rules have one home and the scripts one author. Grant
+them no `sandbox:*` for code work. If they must keep a shell of their own, they
+need the skill too, and its rules are the same sentences as the prompt section:
+a second wording is how one copy ends up softer than the other, and the softer
+one is the one obeyed.
+
+Run `zen check` after any change to `agents.yaml` or a skill.
+
+## Writing anything else around it
+
+- **One home per agent.** Once an agent has the rules - in its prompt or in its
+  skill - no house rule, other skill or prompt line restates them. A prompt that
+  needs to point at the skill names it: _"Follow `code_python` for every
+  script."_
+- **Never add an exemption.** _"Hard-coding is fine for a quick one-off check"_
+  is a permission: every probe is a one-off by construction, so the exception
+  admits exactly what the rule forbids. The same goes for `python -c`.
+- **Never show a one-off as an example.** A prompt or skill that shows
+  `python -c "..."`, or a script with a literal id, date or path in its body,
+  teaches the shape the rule forbids. Every example invocation passes its values
+  as named arguments:
+  `python /workspace/scripts/list_overdue_invoices.py --customer-id 42`.
+- **Scripts shipped inside a skill** (`agents/skills/<name>/scripts/`, §3.4.1 of
+  the copilot instructions) follow the same rules: named arguments, a `--help`,
+  the result on stdout, an `--output` path under `/workspace` for any file,
+  since `/skills` is read-only.
+- **Memory is what makes the reuse happen.** A code-writing agent without
+  memory still writes reusable scripts, but cannot find them in a later session.
+  Say so if the project expects reuse and that agent has no `memory:`.
+
+## Review
+
+- [ ] Every agent that writes or runs code has the rules - a prompt section for
+      a dedicated code agent, the `code_python` skill reachable for the others
+- [ ] Every rule under _Keep in substance_ is there, none softened, and the
+      memory steps match whether the agent holds the memory tools
+- [ ] Generic agents beside a dedicated code agent hand code work to it, or
+      carry the same wording - not a second paraphrase
+- [ ] No other prompt, skill or house rule restates the rules, adds an
+      exemption, or shows `python -c` or a script with literal values
+- [ ] Every script shipped in a skill takes its values as named arguments

package/templates/editor/.github/skills/zen-code-python/references/code_python.md

@@ -0,0 +1,48 @@
+# Writing Python scripts
+
+Every script you write is a tool for the next question like this one, not an
+answer to this one. Write it once, generically, so it can be remembered and run
+again unchanged.
+
+## Before writing
+
+If you hold `memory_search`, search for a script that already answers this kind
+of question, and load the best match with `memory_load`. If it fits, run it with
+this question's arguments and write nothing new. If it needs a change, change
+it the way the rest of this skill says - usually by adding an argument - and
+commit the new version as superseding the old one.
+
+## Writing
+
+1. **Solve the kind of question, not this one.** Anything that would differ the
+   next time - inputs, ids, names, paths, urls, dates and date ranges, filters,
+   thresholds, limits, the output path - is a named `argparse` argument such as
+   `--resource-id`, never a literal in the code. A default is allowed only for a
+   value that is the same for every question.
+2. **Name the file for what it does**, verb first: `list_overdue_invoices.py`,
+   `compare_quarterly_revenue.py`. Never `script.py`, `test.py`, `tmp.py` or a
+   name that only makes sense in this conversation.
+3. **Describe it.** Line one is a docstring saying what question it answers. The
+   same sentence is the `argparse` description, and every argument has a
+   `help=`, so `--help` is all a later reader needs.
+4. **Print the result to stdout** and anything else to stderr. Exit non-zero
+   with a message saying what failed when it cannot answer. A file it produces
+   goes to the path given by `--output`.
+5. **Take credentials from environment variables by name.** Never write a key,
+   token or password into the code or an argument default.
+6. **Use only what the sandbox image already has.** Do not `pip install` from
+   the script or before running it.
+7. **Write it to a file and run the file**:
+   `python /workspace/scripts/<name>.py --resource-id 42`. Never run Python
+   with `python -c` or a heredoc.
+
+## Before using its output
+
+- Run it, and fix the script - not the output - when it fails or prints
+  something wrong.
+- Read your own code against a different question of the same kind. If
+  answering it would mean editing the script rather than passing other
+  arguments, a value is still hard-coded: make it an argument and run again.
+- If you hold `memory_commit`, commit the working script as a `file` node. Its
+  text says what kind of question it answers and names its arguments, so that a
+  later search for a similar question finds it.