@zenera/cli 1.1.24 → 1.1.25

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

@@ -0,0 +1,77 @@
+# `zen meta finetune` - tuning the project, one case at a time
+
+Trains the project's prose - prompts, skills, house rules - on every case of
+its dataset (`zen meta dataset`). Nothing here touches model weights.
+
+```sh
+zen meta finetune start [-N 4] [-M 4] [--tries 4] [--mem-tries 3] [--merge-every 3] [--seed 1] \
+    [--class <c>] [--id <glob>] [--rubric yes|no] [--limit <n>] [--force]
+zen meta finetune [status]
+zen meta finetune stop
+zen meta finetune session <case>
+```
+
+## What one case goes through
+
+```
+without memory, up to --tries times:
+    zen run (empty memory)  ->  /analyze  ->  done? go on : park until the next apply
+with memory, up to --mem-tries times, from the memory the passing run wrote:
+    zen run  ->  /analyze  ->  done? completed : park until the next apply
+tries used up  ->  difficult
+```
+
+- **N workers**, each training one case at a time. Cases come in the dataset's
+  own order: classes taking turns, cases with a rubric first, then seeded
+  random. Cases added to the dataset are picked up as it goes.
+- **A parked case gives its worker back**, so another case runs while it waits
+  for an apply; once woken, it takes a worker before any new case does.
+- **Applies are batched.** Parked cases' improvement requests are applied
+  together by `/finetune-apply` once **M** cases are parked, or once nothing is
+  running and no case is left to start. No run starts during an apply; runs in flight finish
+  first. `zen check` must pass afterwards, or the edit is undone and tried once
+  more; a second failure stops the tuning. Each apply gets its own
+  `applies/<NNN>/APPLY.md`: every request and improvement, what was decided for
+  each, the apply agent's account of what it changed and why, every file
+  changed with its diff, and the `zen check` result.
+- **No run shares a memory.** Every try runs on its own private directory:
+  empty without memory, a copy of the case's passing memory with it. A case
+  whose with-memory run passes keeps a copy in `memories/submitted/`; every
+  `--merge-every` kept memories are merged, with the last merge, into
+  `memories/merged/mNN/` - numbered, never rewritten, each listing the cases it
+  holds. Whatever is left is merged when the tuning ends.
+- **Each case keeps one analyze session**, so every analysis of it remembers
+  the earlier tries. `session <case>` prints the command to resume it.
+- **Stop and resume freely.** `stop` (or Ctrl-C once) lets the steps in flight
+  finish, then exits; Ctrl-C twice kills them. `start` again carries on: every
+  step's result is on disk, and nothing finished is repeated.
+- `start` refuses a dataset that has drifted from its sources - run `/dataset`
+  first, or pass `--force`.
+
+## What it leaves
+
+```
+finetune/
+    STATUS.md            the whole tuning: summary (spend per phase, tuning and memory
+                         effect), workers, queue, applies, cases - generated
+    loop.json            the settings; flags on start update it
+    events.jsonl         every step, in order
+    cases/<id>/
+        FEEDBACK.md      that case: rubric, latest analysis, decisions, history, metrics
+                         of every try and how they moved - generated
+        r<rev>/session   its analyze session
+        r<rev>/result.json            completed or difficult, once it ends
+        r<rev>/<NN>-<nomem|mem>/      one try: request.json, run.json, memory/,
+                                      feedback.json, analysis.md, run.log, analyze.log
+    applies/<NNN>/       APPLY.md (generated), inputs.json, apply.log, check.log, changes.md,
+                         decisions.json, diff.patch
+    memories/            submissions.jsonl, merges.jsonl, submitted/<case>@r<rev>/, merged/mNN/
+    systems/             systems.jsonl + a copy of agents.yaml and agents/ per version
+```
+
+Open `STATUS.md` first; every row links to the detail behind it. Its Summary
+says whether the tuning is working: the fixes, as a case's first try without
+memory against its passing one, and memory, as the passing try without memory
+against the passing try with it - tokens, calls, tool errors and time, totalled
+over the same cases. A case's `FEEDBACK.md` has the same metrics per try and per
+model, each try against the one before it in its phase.

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

@@ -13,7 +13,8 @@ Four ways to read one run, for two different readers.
 | `report`              | you     | `report.html` - every message, payload and cost |
 | `graph`               | a model | the whole trajectory as one Mermaid flowchart   |
 | `node <id...>`        | a model | those nodes in full, payloads resolved          |
-| `ask <id> <question>` | you     | that call replayed to a model, with a question  |
+| `ask <id> <question>` | a model | one replayed answer on stdout; never prompts    |
+| `ask [<id>]`          | you     | a conversation with that call, at a terminal    |
 
 `report` is the default, so `zen inspect` on its own is unchanged.
 
@@ -26,6 +27,7 @@ Four ways to read one run, for two different readers.
 | `--dir <dir>`           | all           | A run directory, as `zen run --json` reports it      |
 | `--memory <dir>`        | report, graph | Read this memory instead of the one the run recorded |
 | `--model <ref>`         | ask           | Answer with this model instead of the run's own      |
+| `--question-file <f>`   | ask           | Read the question from a file; `-` is stdin          |
 | `--part <name>`         | node          | Print this part in full. Repeatable, prefix-matched  |
 | `--full`                | node          | Print every part, the recorded `request` included    |
 | `--open`                | report        | Open the report in a browser                         |
@@ -39,10 +41,13 @@ session that has one. "Newest" means the newest session that actually recorded a
 run, not simply the newest session: a session exists before its first run, so
 the latest one is routinely empty.
 
-**Neither `node` nor `ask` has room for a run.** Every positional `node` takes is
-a node id, and `ask` takes one id and then your question, so name the run with
-`--run`, `--session` or `--dir` - `zen inspect node <run> n13` reads the run id
-as an id and fails.
+**Neither `node` nor `ask` has room for a positional run.** Every positional
+`node` takes is a node id, and every positional `ask` takes is the id followed
+by the question, so name the run with `--run`, `--session` or `--dir`.
+`zen inspect node <run> n13` reads the run id as an id and fails. `ask`
+without a question is the interactive mode (below) and needs a terminal; a
+script, `--json` call or agent passes the id and the question and never sees a
+prompt.
 
 For `report` and `graph` the positional is a run id unless it contains a `/`, in
 which case it is read as a run directory. A run id is a stamp and never has a
@@ -100,13 +105,13 @@ zen inspect graph --dir "$(zen run --json 'fix the tests' | jq -r .run.dir)"
 %%   n24 joins docs (researcher, ok), tests (researcher, ok)
 %% compacted 3 nodes are marked "hidden by" a later summary
 %%           they still ran; the model simply stopped seeing them
-%%
+%% ---
 %% reading   nN is a node id · t+ counts from the start of the turn
 %%           dotted edges are fork/join and calls answered out of order
 %%           nodes are declared in run order; every edge is in one block below
 %% detail    zen inspect node n1 n2 n5..n9 --dir <run dir>
 %% why       zen inspect ask n5 "why did you do that?" --dir <run dir>
-%%
+%% ---
 flowchart TD
     n11["n11 llm claude-opus-5 · 4.2k in 310 out · calls run_command · t+32.7s"]
     n12["n12 run_command npm test -- --run · t+34.7s · took 3.0s"]
@@ -214,10 +219,43 @@ ready to paste.
 
 `node` shows what a model was given. `ask` asks the model what it made of it.
 
+`ask` has two modes, and which one runs is decided by one thing: whether the
+question is given.
+
+| Mode        | Trigger                                                | For                    | Behaviour                                                                                        |
+| ----------- | ------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------ |
+| One-shot    | a question on the line, `--question-file`, or `--json` | a script or a model    | no banner, no prompt, no picker; one model call, the raw answer on stdout and nothing else, exit |
+| Interactive | no question                                            | a person at a terminal | asks for whatever is not named - session, run, `llm_call` - then the question; a conversation    |
+
+One-shot never reads the terminal, even when there is one: an unnamed run is
+the newest, not a picker, so name it with `--dir`, `--run` or `--session`.
+Interactive without a terminal is a usage error, never a wait.
+
 ```sh
 zen inspect ask n11 "why run python -c when the skill says npm test?" --dir <run dir>
 ```
 
+In the interactive mode only calls with a recorded request appear in the node
+list. Each question and Markdown answer is drawn in its own labelled panel, with
+the model and token counts on stderr. It keeps asking on the same node,
+retaining earlier exchanges as context, until an empty question is submitted.
+
+```sh
+zen inspect ask                       # pick everything
+zen inspect ask n11 --dir <run dir>   # straight to the questions
+```
+
+A question with quotes, apostrophes, backticks, `$` or more than one line goes
+in a file, so no shell parses it. The file is the whole question; `-` reads it
+from stdin. Words on the line as well are an error.
+
+```sh
+zen inspect ask n11 --question-file .tmp/ask/<run-id>/n11-tests.md --dir <run dir>
+```
+
+Do not build the question with `"$(cat <<'EOF' ... )"`: macOS `/bin/bash` 3.2
+misparses a heredoc inside `$( )` when its body holds an apostrophe.
+
 The `llm_call` node named by the id is replayed: its recorded system prompt, its
 messages and its tool schemas, exactly as the provider received them, with the
 answer it gave put back as its own turn and your question as one more after
@@ -247,8 +285,8 @@ command says so on stderr, because an answer from a different model is a second
 opinion rather than the model examining itself. Either way the run's full system
 prompt goes to that provider.
 
-`graph`, `node` and `ask` print no banner. Their stdout is the answer, whole and
-ready to paste.
+`graph`, `node` and non-interactive `ask` print no banner. Their stdout is the
+answer, whole and ready to paste.
 
 ## Where it comes from
 

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

@@ -18,16 +18,21 @@ skill.
 
 ## Subcommands
 
-| Command                   | What it does                                |
-| ------------------------- | ------------------------------------------- |
-| `zen memory stats`        | Size, vocabulary, whether it is embedded    |
-| `zen memory ls`           | Nodes, newest first. Changes nothing        |
-| `zen memory search <q>`   | Recall it, the way an agent does. Ranked    |
-| `zen memory grep <pat>`   | Every node containing it, with the lines    |
-| `zen memory show <id>`    | One node in full, with what it links to     |
-| `zen memory export [f]`   | The whole graph as one HTML page            |
-| `zen memory merge <dir…>` | Fold other memories into this one           |
-| `zen memory forget <id…>` | Remove nodes, their vectors and their files |
+| Command                   | What it does                                        |
+| ------------------------- | --------------------------------------------------- |
+| `zen memory stats`        | Size, vocabulary, whether it is embedded            |
+| `zen memory ls`           | Nodes, newest first: kind, audience, revision, text |
+| `zen memory search <q>`   | Recall it, the way an agent does. Ranked            |
+| `zen memory grep <pat>`   | Every node containing it, with the lines            |
+| `zen memory show <id>`    | One node in full, with what it links to             |
+| `zen memory diff <base>`  | What this memory holds that `<base>` did not        |
+| `zen memory export [f]`   | The whole graph as one HTML page                    |
+| `zen memory merge <dir…>` | Fold other memories into this one                   |
+| `zen memory forget <id…>` | Remove nodes, their vectors and their files         |
+
+`ls` cuts the text to the terminal's width; piped, or run by an agent, it prints
+all of it. Never read `graph.json` directly - `ls --json` is the same nodes in a
+shape that does not change under you.
 
 | Flag                          | Meaning                                        |
 | ----------------------------- | ---------------------------------------------- |
@@ -99,6 +104,24 @@ remembered file it could not read - too big, binary, missing - is named rather
 than silently skipped, because a file that went unsearched must not pass for one
 with no match.
 
+## `diff` says what a run did to a copy
+
+A run started from a copy of a memory leaves the whole copy behind, so `ls` on
+it shows everything the base held too. `diff` shows only what changed:
+
+```sh
+zen memory diff <candidate> --dir <batch-dir>/<id>/memory
+```
+
+- **added** - each with the nearest node `<base>` held and its score. One
+  `merge` would fold onto it is marked a twin: the run said again what the
+  memory already held.
+- **revised** - same id, new revision.
+- **used** - nodes `memory_load` returned, and how often: what the run read.
+- **removed**, and new `SUPERSEDES` edges.
+
+It reads both sides without the lock, so it works on a memory a run is writing.
+
 Superseded nodes are left out unless you ask: `--all` includes them marked, and
 `--stale` narrows to them alone.
 

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

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/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.