diff --git a/.claude/skills/model-family-onboarding/SKILL.md b/.claude/skills/model-family-onboarding/SKILL.md
index e88a1b11..bbaead08 100644
--- a/.claude/skills/model-family-onboarding/SKILL.md
+++ b/.claude/skills/model-family-onboarding/SKILL.md
@@ -23,7 +23,7 @@ next family gets it in an afternoon rather than a rediscovery.
   independent sources repeat it *and* nothing primary contradicts it.
 - **Model knowledge is data, never engine code.** Template JSON, stored
   prompts, a builtin's system prompt, README prose, a skill. No per-model
-  Python (proposal `docs/proposals/agent-catalog-legibility.md`, "Principle").
+  Python (proposal `docs/proposals/agent-catalog-legibility-complete.md`, "Principle").
 - **Do not transcribe a prompt format the vendor publishes.** Point at it. If
   the vendor ships an agent skill (MiniMax does) or a system-prompt constant
   inside diffusers (Lightricks does), the dw skill says "use that" and a test
diff --git a/.vscode/settings.json b/.vscode/settings.json
index 73ac4371..3f3f5857 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -7,6 +7,7 @@
         "aiohttp",
         "controlnet",
         "cuda",
+        "denoise",
         "dtype",
         "exif",
         "fullgraph",
diff --git a/CLAUDE.md b/CLAUDE.md
index 64084f75..c7066661 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -120,7 +120,7 @@ read an inferred workspace back as one the user named - `get_prompt_dir` yields
 to its older discovery (`./prompts`, then the walk up from the workflow file)
 for an inferred workspace but not for an explicit one. `--workflow-dir`,
 `--output-dir` and `--prompt-dir` each still override one folder. See
-docs/WORKSPACES.md, and docs/proposals/server-workspaces.md for the later stages
+docs/WORKSPACES.md, and docs/proposals/server-workspaces-complete.md for the later stages
 (workflow search path, run directories, `asset:`/`output:` references).
 
 ### Type System
@@ -154,6 +154,27 @@ docs/WORKSPACES.md, and docs/proposals/server-workspaces.md for the later stages
   rooted at the library rather than the workflow file. The library is `DW_PROMPT_DIR` /
   `--prompt-dir`, else `./prompts` if it exists, else found by walking up from the
   workflow file's directory
+- A step carrying `for_each` (a list, or `variable:` naming one) is expanded by
+  `expand_for_each` (`dw/for_each.py`) into one ordinary step per entry, named
+  `<step>@<entry name or index>`, immediately after `replace_variables` in
+  `Workflow.run` and, with the caller's arguments folded, in `validation_errors`.
+  Inside a member `item:` / `item:field` is the entry (any type, spliced whole);
+  a later step reads the group with `gather:<step>` (a list; splices inside a
+  list); two groups over the same list pair by key (`slice` inside `shot@x` is
+  `slice@x`). `previous_result:` naming a group is a directed error. `@` is
+  reserved in step names; entry names are validated and unique; 32 entries max;
+  `release_pipeline`/`release_models` survive on the last member only. The
+  realized workflow keeps `for_each`; the manifest names the members. An entry
+  of a list-valued variable may reference another variable
+  (`"from_file": "variable:character_a_voice"`); `resolve_variable_values`
+  (`dw/variables.py`) replaces those once, before `realize_args`, refusing a
+  cycle, and `undeclared_variable_references` walks inside list/dict variable
+  values too. The catalog derives `lists` (`list_fields`, `dw/for_each.py`):
+  the fields an entry takes are the `item:` references the steps make, `name`
+  first; an entry key no step reads is a validation warning
+  (`entry_field_warnings`). A `cost` entry may carry `per_entry`
+  (`{variable, minutes, entries}`), measured, never derived. An empty
+  `for_each` list is an error; `expanded_definition` realizes constants first.
 - Every run directory holds `workflow.json` beside its manifest: the *realized*
   workflow, with the run's arguments folded into the variable defaults, the seed
   it used, stored prompt text inlined and `output:.../latest/...` pinned to the
@@ -219,8 +240,28 @@ same reason - default setup cannot load a pack.
   literal `previous_result:` or `from_previous_result` naming no *earlier* step, with
   the JSON path it sits at. References otherwise resolve lazily per step, so a step
   renamed in one place and not another failed only when the run reached it, after
-  every step before it had generated. A reference spelled by a `variable:` is left
-  alone - what it names is not knowable before substitution
+  every step before it had generated. The definition is substituted before the check,
+  so a reference spelled by a *declared* variable is checked by its value; one spelled
+  by an undeclared variable is itself a validation error (below)
+- **`for_each` expands before the reference check** — `validation_errors` substitutes
+  (the caller's `arguments` when they are all good, else the defaults) and expands
+  first, so `gather:` and `item:` errors carry the path of the template step
+  (`steps[0].for_each[1].name`). Expansion records each expanded step's *source* index
+  (`expand_for_each(definition, source_indices)`), so a reference error always carries a
+  path in the file the author wrote, and one inside a member names the member in its
+  message. An undeclared `variable:` is a validation error at the path it sits at, not a
+  warning and not a complaint about the `for_each` list that did substitute: once a
+  `variables` block exists, `replace_variables` refuses an undeclared reference, so it is
+  a run that cannot start
+- **The two MiniMax cut templates take one `shots` list** — since the stage-2
+  rewrite (2026-09-11) `templates/minimax/dialogue-short` and `music-video`
+  have no `shot_N_*` variables; a scripted caller passes `shots` (entries
+  `{name, prompt, references, num_frames}` and `{name, prompt, start_frame}`).
+  The members are `shot@<name>` in the manifest and the gallery. This is the
+  breaking change the next release note should name. The CLI and REPL only
+  take `name=value` strings, and a string handed to a list variable is
+  comma-split - so `shots` can only be supplied over the API/MCP (a JSON
+  body); `python -m dw.run` runs the templates' default list
 - **Cartesian product explosion** — multiple `previous_result` references multiply: 4 images × 3 masks = 12 iterations
 - **Component sharing requires exact key matching** between `shared_components` and `reused_components`
 - **Built-in workflows** need explicit argument mapping: `"prompt": "variable:prompt"`
diff --git a/README.md b/README.md
index b84de269..ef382219 100644
--- a/README.md
+++ b/README.md
@@ -83,7 +83,7 @@ once; without it the run fails partway through with a 401/403 from the Hub.
 
 ## Drive it from an agent
 
-Then just ask. The agent has 50 tools covering the whole surface — the
+Then just ask. The agent has 55 tools covering the whole surface — the
 workflow catalog, the real diffusers pipeline signatures, the job queue, the
 gallery, the model cache:
 
diff --git a/docs/MCP.md b/docs/MCP.md
index 8b7cc315..68500bd9 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -187,7 +187,7 @@ Nothing in this sequence costs GPU time.
 
 ## Tool reference
 
-52 tools in six groups. Names and arguments below are transcribed from
+55 tools in six groups. Names and arguments below are transcribed from
 `dw_mcp/server.py` — nothing here is renamed or reshaped for the docs.
 
 ### Catalog (read-only)
@@ -212,8 +212,8 @@ when no single workflow covers it.
 | --- | --- | --- |
 | `list_guides()` | — | List the documentation the engine serves: each guide's name, what it covers, and its section headings. The index is the routing table - match a request's shape against a heading rather than guessing |
 | `get_guide(name, section=None)` | `name`, `section` | Get one guide whole, or one section of it. Prefer a section: a guide runs to thousands of lines. Section names match loosely, so a heading copied approximately still resolves |
-| `list_workflows(shape=None, traits=None, configures=None, include_models=False)` | `shape`, `traits`, `configures`, `include_models` | List stored workflows. Always the server's compact view: each entry carries `summary`, `shape`, `traits`, `cost`, `kinds`, `variable_names`, and `configures` only when set - `get_workflow` has the full description and definition. `shape` keeps one of `image`, `image-set`, `image-edit`, `shot`, `sequence`, `audio`, `text`, `utility`; `traits` is comma-separated and every one listed must match (`has-audio`, `chained`, `image-conditioned`, `identity-referenced`, `needs-input-media`, `composes-workflows`); an unknown value in either is a 400 listing the vocabulary. Templates only by default - `configures=<template>` lists the checkpoint configs tuned for one, `include_models=true` lists them all. The first call to make for a request an existing workflow might cover |
-| `get_workflow(name, variables_only=False)` | `name` | Get one stored workflow's full JSON definition. `variables_only=true` answers with just its variables and their defaults (long strings cut to 200 characters, the cut ones named in `truncated`) — the cheap way to confirm what a variable defaults to |
+| `list_workflows(shape=None, traits=None, configures=None, include_models=False)` | `shape`, `traits`, `configures`, `include_models` | List stored workflows. Always the server's compact view: each entry carries `summary`, `shape`, `traits`, `cost`, `kinds`, `variable_names`, `lists`, and `configures` only when set - `get_workflow` has the full description and definition. `lists`, present for a list-driven workflow, names the fields an entry of each list takes, the steps over it and the default's length; `cost` may carry `per_entry`, the measured cost of one entry so a run over a different-length list can be priced from it. `shape` keeps one of `image`, `image-set`, `image-edit`, `shot`, `sequence`, `audio`, `text`, `utility`; `traits` is comma-separated and every one listed must match (`has-audio`, `chained`, `image-conditioned`, `identity-referenced`, `needs-input-media`, `composes-workflows`); an unknown value in either is a 400 listing the vocabulary. Templates only by default - `configures=<template>` lists the checkpoint configs tuned for one, `include_models=true` lists them all. The first call to make for a request an existing workflow might cover |
+| `get_workflow(name, variables_only=False)` | `name` | Get one stored workflow's full JSON definition. `variables_only=true` answers with just its variables and their defaults (long strings cut to 200 characters, the cut ones named in `truncated`, including strings inside a list default, named like `shots[0].prompt`) — the cheap way to confirm what a variable defaults to |
 | `get_schema()` | — | Get the JSON schema every workflow definition must satisfy |
 | `list_pipelines()` | — | List every diffusers pipeline class this installation provides |
 | `get_pipeline_signature(name)` | `name` | Get a pipeline's real call arguments |
@@ -249,7 +249,7 @@ The session starts in `default` and stays there unless it is told otherwise.
 
 | Tool | Arguments | Purpose |
 | --- | --- | --- |
-| `validate_workflow(workflow=None, name=None, workspace=None, arguments=None)` | exactly one of `workflow` (inline definition) or `name` (a stored workflow, as `list_workflows` reports it), optional `workspace`, optional `arguments` | Check a workflow against the schema and against real pipeline signatures. Free and instant. Validating by name uses the workflow file's own directory as the base directory, so it sees what a run would. Returns every schema violation in `errors`, each with the JSON path it sits at, so a draft is fixed in one pass, and a `previous_result:` that names no earlier step is one of them. `workspace` names the workspace for this one call without switching the session to it - use it to pin a job whose `output:` or `asset:` references live in a workspace other than the session's. Pass the same `arguments` you will pass to `run_workflow` and they are checked too - an undeclared or renamed variable name, a value that will not coerce to the declared type, and an `asset:`, `prompt:` or `output:` reference that names nothing this workspace can reach, each reported at `arguments.<name>`. `checked_arguments` lists what was covered, so a `valid: true` about the stored defaults cannot be mistaken for one about your values. `run_workflow` makes the same check and refuses a bad argument rather than queuing a job that fails on its first step |
+| `validate_workflow(workflow=None, name=None, workspace=None, arguments=None)` | exactly one of `workflow` (inline definition) or `name` (a stored workflow, as `list_workflows` reports it), optional `workspace`, optional `arguments` | Check a workflow against the schema and against real pipeline signatures. Free and instant. Validating by name uses the workflow file's own directory as the base directory, so it sees what a run would. Returns every schema violation in `errors`, each with the JSON path it sits at, so a draft is fixed in one pass, and a `previous_result:` that names no earlier step is one of them. `warnings` covers what still runs but is probably wrong - a signature mismatch, and, for a list-driven variable, an entry key no step reads, at the entry's path. `workspace` names the workspace for this one call without switching the session to it - use it to pin a job whose `output:` or `asset:` references live in a workspace other than the session's. Pass the same `arguments` you will pass to `run_workflow` and they are checked too - an undeclared or renamed variable name, a value that will not coerce to the declared type, and an `asset:`, `prompt:` or `output:` reference that names nothing this workspace can reach, each reported at `arguments.<name>`. `checked_arguments` lists what was covered, so a `valid: true` about the stored defaults cannot be mistaken for one about your values. `run_workflow` makes the same check and refuses a bad argument rather than queuing a job that fails on its first step |
 | `list_workspaces()` | — | The server's workspaces and which one this session is using. Each has its own workflows, assets and outputs; the prompt library is shared by all of them |
 | `use_workspace(name)` | `name` | Work in that workspace for the rest of the session - every later call reads and writes there. This is how to keep your work out of another agent's namespace rather than sharing the default one. Checked against the server, so a typo fails here rather than scoping every later call to nothing |
 | `create_workspace(name, use=False)` | `name`, `use` | Create a workspace. Pass use=true to switch this session to it as well; otherwise the session stays where it was and the result says so |
@@ -283,11 +283,11 @@ references written in the same session.
 | Tool | Arguments | Purpose |
 | --- | --- | --- |
 | `run_workflow(workflow_path=None, inline_workflow=None, arguments=None, acknowledged_cost=False, workspace=None)` | exactly one of `workflow_path` (a catalog name from `list_workflows`, with or without `.json`, or a path to a workflow file on the server) or `inline_workflow`, optional `arguments`, `acknowledged_cost`, `workspace` | Queue a workflow for generation. Returns as soon as the job is queued. `workspace` names the workspace for this one call without switching the session to it - use it to pin a job whose `output:` or `asset:` references live in a workspace other than the session's |
-| `get_job(job_id)` | `job_id` | Get a job's status, warnings, output manifest, error and traceback |
+| `get_job(job_id)` | `job_id` | Get a job's status, warnings, output manifest, error and traceback. A running job also carries `progress` (below) |
 | `get_job_workflow(job_id)` | `job_id` | The workflow the job actually ran. `realized: true` means every mutable input is pinned (arguments, seed, prompts, `output:latest`); `false` means the job predates run tracking and this is the definition as submitted. Pass it to `save_workflow` to keep it under a name |
 | `export_job(job_id, overwrite=False)` | `job_id`, `overwrite` | Gather one finished job into `<workspace>/exports/<job id>/` on the server: the realized workflow, the run's manifest, the job row, a README, and copies of the assets, earlier-run inputs and outputs. Returns the directory, a zip URL, the file list with sizes and the total. The three JSON files are in the zip, not repeated here - get_job_workflow and get_job serve them individually. **The directory is on the machine running the server**, like `download_output`'s destination - fetch the zip URL and unpack it into `exports/` under the session's working directory (a deliverable, not a temp file); the archive already unpacks into one folder named after the job id |
 | `get_job_events(job_id, after=-1, limit=200)` | `job_id`, `after`, `limit` | Get a page of a job's progress events |
-| `wait_for_job(job_id, timeout_seconds=20)` | `job_id`, `timeout_seconds` | Block until a job reaches a terminal status, or `timeout_seconds` elapses. **One call blocks for at most 55 seconds** — a larger `timeout_seconds` is clamped, not honoured, because no MCP client holds a tool call open for a generation's real runtime, so budget one call per ~55s of the job. Every reply carries `waited_seconds`, `timeout_requested_seconds`, `timeout_applied_seconds` and `timeout_capped`, so a capped return is distinguishable from an elapsed one. Use instead of hand-polling `get_job`/`get_job_events` in a loop; if it returns `still_running: true`, call it again. Returns a slim job - status, warnings, error, and the manifest once finished - without the arguments; `get_job` has those |
+| `wait_for_job(job_id, timeout_seconds=20)` | `job_id`, `timeout_seconds` | Block until a job reaches a terminal status, or `timeout_seconds` elapses. **One call blocks for at most 55 seconds** — a larger `timeout_seconds` is clamped, not honoured, because no MCP client holds a tool call open for a generation's real runtime, so budget one call per ~55s of the job. Every reply carries `waited_seconds`, `timeout_requested_seconds`, `timeout_applied_seconds` and `timeout_capped`, so a capped return is distinguishable from an elapsed one. Use instead of hand-polling `get_job`/`get_job_events` in a loop; if it returns `still_running: true`, call it again. Returns a slim job - status, warnings, error, and the manifest once finished - without the arguments; `get_job` has those. A running job also carries `progress` (below) |
 | `cancel_job(job_id)` | `job_id` | Ask a queued or running job to stop |
 | `rerun_job(job_id, acknowledged_cost=False, new_seed=False)` | `job_id`, `acknowledged_cost`, `new_seed` | Queue a fresh job from a previous job's stored specification. Costs GPU time, so it passes the same gate as `run_workflow`. `new_seed=true` draws a fresh seed into the workflow's seed variable — without it a seeded workflow's rerun repeats its arguments exactly and the step cache serves the whole run from the earlier one's files (`reused: true`), generating nothing. `get_job_workflow`'s `seed_variable` says whether there is one |
 | `move_job(job_id, direction)` | `job_id`, `direction` (`up`\|`down`\|`front`\|`back`) | Reorder a queued job |
@@ -353,11 +353,28 @@ The intended loop:
    again if it comes back `still_running: true` — or
    `get_job_events(job_id)` repeatedly, passing back the previous call's
    `last_seq` as `after`, for incremental progress instead of just a
-   terminal/not-terminal status
+   terminal/not-terminal status. Each event carries `at`, seconds since the
+   job started, so where a step's time went is a subtraction between two
+   events - `step_start` to `generating` is the lead-in a reused pipeline
+   still pays, `generating` to the first `pipeline_step` the encoding
 4. `get_job(job_id)` for the finished manifest (or the error and traceback,
    if it failed)
 5. `get_output_image(name)` to look at a result image
 
+While a job runs, `get_job` and `wait_for_job` carry a `progress` block -
+the step being run, the phase (`loading`, `generating`, `decoding`,
+`saving`) with the model in `phase_detail`, `seconds_in_phase`,
+`seconds_since_event`, and `denoise_step`/`denoise_total_steps`, which are
+null until the denoise loop starts. A single-step generation is minutes of
+one phase, so two polls otherwise come back identical: read `denoise_step`
+moving (slow but healthy) against a `denoise_step` that is a number and
+stays put while `seconds_since_event` climbs (nothing is happening). A null
+`denoise_step` under `generating` is neither - it is the lead-in the
+pipeline runs before the loop, encoding the prompt and any reference image
+or audio, ~90 s on MiniMax H3 with nothing emitted, so silence there is
+expected. `cancel_job` stops at the next denoise or
+step boundary, which `denoise_step` is also the measure of.
+
 ## Security
 
 The MCP server adds no authentication of its own — it inherits the REST
diff --git a/docs/SECURITY.md b/docs/SECURITY.md
index 618c9195..21358442 100644
--- a/docs/SECURITY.md
+++ b/docs/SECURITY.md
@@ -71,8 +71,8 @@ loading (`sdnq`, `torchao`, `optimum` for optimum-quanto, `gguf`,
 `bitsandbytes`), plus `dw` itself (a workflow's `component_type` can name a
 pipeline under `dw.community_pipelines`, which ships in this repo, not a
 third party one). The refusal names exactly what triggered it and points
-back at `--trust-workflows`. The bundled examples under `workflows/` (not
-`workflows/archive/`) all stay inside this set and load untrusted; a
+back at `--trust-workflows`. The bundled examples under `workflows/` all
+stay inside this set and load untrusted; a
 workflow that needs to reach outside it - a community pipeline module from
 somewhere else, a custom scheduler package - needs `--trust-workflows`.
 
diff --git a/docs/SERVER.md b/docs/SERVER.md
index ea5bd175..bdcadc0a 100644
--- a/docs/SERVER.md
+++ b/docs/SERVER.md
@@ -138,11 +138,11 @@ from another machine:
 | --- | --- |
 | `POST /api/jobs` | Queue a run: `{"workflow_path": ...}` or an inline `{"workflow": {...}, "base_dir": ...}`, plus `arguments` for variable overrides. `workflow_path` accepts a stored workflow name as listed by `/api/workflows` (with or without `.json`, nested names included), or a relative/absolute path that still resolves under `--workflow-dir` - confined the same way the `/api/workflows` CRUD routes are; a path that names a real file outside that directory is rejected with 400, not opened. Answers with argument warnings from signature checking. |
 | `GET /api/jobs?workspace=&status=&limit=` | Queue + history summaries, oldest first, with `total` beside them. `status` narrows to one state or a comma-separated set (`queued`, `running`, `succeeded`, `failed`, `cancelled`; anything else is a 400); `limit` keeps the newest N, and `total` still reports how many matched, so a bounded answer cannot be mistaken for a complete one. No parameters means every job, which is what the web UI polls |
-| `GET /api/jobs/{id}` | Full detail: spec, events, manifest, error. A manifest entry for a step served from the step cache carries `reused: true` |
+| `GET /api/jobs/{id}` | Full detail: spec, events, manifest, error. A manifest entry for a step served from the step cache carries `reused: true`. A `for_each` step appears in the manifest as its members (`shot@wide_open`, `shot@closeup`), because the manifest records what ran; the run's `workflow.json` keeps the `for_each` form, because it records what was asked |
 | `GET /api/jobs/{id}/workflow` | The workflow the job ran: `{id, definition, realized, seed_variable}`. `seed_variable` names the variable a `new_seed` rerun would draw into (null when the workflow has none), read from the workflow as written rather than the realized copy, whose seed is pinned. `realized: true` is the copy the run itself wrote (`workflow.json` in its run directory), with arguments, seed, prompts and `output:latest` pinned; `false` falls back to the submitted definition, which is what a job from before run tracking has. 404 means neither is readable - the job itself still is |
 | `POST /api/jobs/{id}/export?workspace=&overwrite=` | Gather one finished job into `<workspace>/exports/<job id>/`: `workflow.json`, `manifest.json`, `job.json`, `README.md`, `assets/`, `inputs/`, `outputs/`. 201 with the file list, total bytes, anything it could not find, a `zip_url`, and the three JSON files inline. 404 unknown job, 409 for a job still running or an existing export without `overwrite` |
 | `GET /exports/{id}.zip?workspace=` | The same tree as one archive, built on request rather than kept as a second copy. Entries are named `<job id>/<relative path>`. Ungated exactly as `/outputs` is |
-| `GET /api/jobs/{id}/events` | Server-sent events stream; `?after=N` / `Last-Event-ID` replay missed events, so reconnects are lossless |
+| `GET /api/jobs/{id}/events` | Server-sent events stream; `?after=N` / `Last-Event-ID` replay missed events, so reconnects are lossless. Every event carries `seq` and `at` - seconds since the job started (since it was queued, for the events before that) - so a step's cost is a subtraction: `step_start` to `generating` is what a reused pipeline still pays before it runs, `generating` to the first `pipeline_step` is the prompt and reference encoding |
 | `GET /api/jobs/{id}/event-log?after=-1&limit=200` | The same events as the SSE stream, as one JSON page: `{id, status, events, last_seq, truncated, note}`. `after` is exclusive; page by passing back the previous `last_seq`. A job restored from history serves the bounded event tail persisted with it; a job that finished before events were retained returns an empty list and a `note` saying so. |
 | `POST /api/jobs/{id}/cancel` | Cooperative cancel (takes effect at the next step boundary or denoise step) |
 | `POST /api/jobs/{id}/rerun` | Re-queue a finished job's spec. Body `{"new_seed": true}` draws a fresh seed into the workflow's seed variable instead of repeating the original arguments; 400 when the workflow pins its seed to a literal or names none. A plain rerun of a seeded workflow is served whole from the step cache — the earlier run's files, republished with `reused: true`, generating nothing |
@@ -164,7 +164,7 @@ Every event in the stream carries a `seq` and an `event` name:
 | `workflow_start` | the run begins | `workflow`, `total_steps`, `steps`, `seed` |
 | `step_start` / `step_end` | each step | `step`, `index`, `total_steps`; `files` at the end. A step served from the step cache adds `reused: true` to `step_end`, and its `files` are the earlier run's files rather than newly written ones |
 | `iteration_start` | each argument combination in a step | `step`, `iteration`, `total_iterations` |
-| `pipeline_step` | each denoise step | `step`, `total_steps` |
+| `pipeline_step` | each denoise step | `step`, `total_steps`. Emitted for a pipeline that takes a `callback_on_step_end`, and for a `ModularPipeline` (H3, LTX-2, Qwen-Image), which takes none - there the denoise block's own progress bar is what reports |
 | `phase` | the step changes what it is doing | `phase`, `detail` |
 | `workflow_end` | the run finishes | `manifest` |
 
@@ -177,6 +177,29 @@ restarts), `decoding` (latents, after the last denoise step), `saving`
 (writing files, including video encode) and `task` (a task step, named in
 `detail`). Emits are a handful per step, not per denoise tick.
 
+### Progress on a running job
+
+`GET /api/jobs/{id}` carries a `progress` block while a job is running
+(`null` before it starts and once it is terminal, where the manifest is the
+better answer). It is the same information the event log holds, kept as the
+events arrive so a caller does not have to page back through a trimmed log
+to learn where a long render is:
+
+| field | |
+| --- | --- |
+| `step`, `step_index`, `total_steps` | the workflow step being run |
+| `phase`, `phase_detail` | the latest phase and what it named |
+| `seconds_in_phase` | how long it has been in it |
+| `seconds_since_event` | how long since anything at all happened - the number that separates a slow run from a stuck one |
+| `denoise_step`, `denoise_total_steps` | the denoise loop's counter, `null` until it starts |
+
+A null `denoise_step` under `generating` is the pipeline's lead-in - encoding
+the prompt and any reference image or audio - which emits nothing and runs
+well over a minute on a large video model (~90 s on MiniMax H3). The keys are
+always present so that lead-in can be told from a loop that has stopped
+advancing: `seconds_since_event` is a stall signal once `denoise_step` is a
+number, or in any phase other than `generating`.
+
 ## Introspection API
 
 The editor's forms come from these; they are just as usable from scripts:
@@ -199,7 +222,10 @@ The editor's forms come from these; they are just as usable from scripts:
   `build_dist.sh` puts under `dw/docs/`
 - `POST /api/validate` — schema validation plus signature-level argument
   warnings for pipeline and task steps (catches the typo before the model
-  loads). Accepts `workflow_path` (same resolution and confinement as
+  loads); `warnings` also names an entry key of a list-driven variable that
+  no step reads, at the entry's path (`variables.shots[0]` or, when the
+  caller's own `arguments` supplied the list, `arguments.shots[0]`).
+  Accepts `workflow_path` (same resolution and confinement as
   `/api/jobs`, above) as an alternative to inline `workflow` - exactly one
   of the two, or a 400. Every schema violation is returned in `errors`
   (`[{path, message}]`, sorted by path, capped at 25), and joined one per
@@ -229,11 +255,16 @@ The editor's forms come from these; they are just as usable from scripts:
   `identity-referenced`, `needs-input-media`, `composes-workflows`; `summary`,
   the first sentence of the description, capped at 120 characters; and `cost`,
   the maintainer-measured `{device, name, vram_gb, minutes}` runs, or `null`
-  when nobody has measured it. A `models/` entry takes its `shape` and
-  `traits` from the template it configures and keeps its own `cost`. Enough
-  to choose a workflow and know what to pass it without reading each one; the
-  variable defaults are deliberately left out, being an order of magnitude more
-  payload on a listing the UI reloads. Cached by file mtime
+  when nobody has measured it - a list-driven workflow's `cost` entry may
+  also carry a measured `per_entry` (`{variable, minutes, entries}`), the
+  cost of one entry of the list it was measured against. A `models/` entry
+  takes its `shape` and `traits` from the template it configures and keeps
+  its own `cost`. A list-driven workflow (one with a `for_each` step) also
+  carries `lists`: per list variable, the fields an entry takes, the steps
+  run over it and the default's length. Enough to choose a workflow and know
+  what to pass it without reading each one; the variable defaults are
+  deliberately left out, being an order of magnitude more payload on a
+  listing the UI reloads. Cached by file mtime
 
   Optional query params narrow and shrink it:
   `?shape=&traits=&configures=&include_models=&view=compact`. `shape` keeps
@@ -242,15 +273,18 @@ The editor's forms come from these; they are just as usable from scripts:
   vocabulary. `configures=<template>` keeps that template's model configs.
   `view=compact` is the agent's projection: it drops `description`, `origin`,
   `writable`, `prompt_refs`, `steps` and `variables`, keeps `summary`,
-  `shape`, `traits`, `cost`, `kinds` and `variable_names`, and lists templates
-  only unless `include_models=true` or a `configures` asks otherwise. With no
-  params the response is what it always was, plus the four new fields
+  `shape`, `traits`, `cost`, `kinds`, `variable_names` and `lists` (carried
+  only when the workflow has a list-driven step, like `configures`), and
+  lists templates only unless `include_models=true` or a `configures` asks
+  otherwise. With no params the response is what it always was, plus the new
+  fields
 - `GET/PUT/DELETE /api/workflows/{name}` — read, save, delete workflow files
   (confined to `--workflow-dir`)
 - `GET /api/workflows/{name:path}/download` — download a workflow file as JSON
 - `GET /api/workflows/{name:path}/variables` — a workflow's variables and what
   they default to, without the definition around them. Long string defaults are
-  cut to 200 characters and named in `truncated`; `full=true` returns them whole
+  cut to 200 characters and named in `truncated`, including strings inside a
+  list default, named like `shots[0].prompt`; `full=true` returns them whole
 - `GET /api/prompts`, `GET/PUT/DELETE /api/prompts/{name}` — the prompt
   library (confined to `--prompt-dir`, names held to what a `prompt:`
   reference can load); saves are validated against the prompt schema,
diff --git a/docs/TASKS.md b/docs/TASKS.md
index d2d63ea1..b6d31fe4 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -84,6 +84,7 @@ All accept an `image` argument with processing parameters:
 | `resize_rescale` | Resize to exact dimensions | `width`, `height` |
 | `resize_bucket` | Snap to closest model-native aspect ratio | `resolution`, `ratios`, `alignment` |
 | `crop_square` | Center crop to square | |
+| `recenter_crop` | Re-frame around a chosen point at a chosen scale, so a series of images registers on one feature; the window may run off the source | `center_x`, `center_y`, `crop`, `width`, `height`, `fill` |
 | `add_border_and_mask` | Add border with alpha mask | |
 | `add_border_and_mask_with_size` | Border with specific dimensions | `width`, `height` |
 | `strip_exif` | Remove all EXIF/metadata from image | |
diff --git a/docs/TESTING.md b/docs/TESTING.md
index c7d20603..2a2f46c9 100644
--- a/docs/TESTING.md
+++ b/docs/TESTING.md
@@ -22,7 +22,7 @@ pytest tests/ --cov=dw --cov-report=html
 
 ## Test Files
 
-Around 57 files and 1,500+ tests as of this writing (`pytest tests/ --collect-only -q` for the current count). The table below maps the core areas; newer features carry their own `test_<feature>.py` alongside them (server: `test_server.py`, events/cancellation: `test_events.py`, `test_worker_execute.py`, introspection: `test_introspection.py`, hub cache: `test_hub_cache.py`, chaining: `test_chain.py`).
+Around 120 files and 3,600+ tests as of this writing (`pytest tests/ --collect-only -q` for the current count). The table below maps the core areas; newer features carry their own `test_<feature>.py` alongside them (server: `test_server.py`, events/cancellation: `test_events.py`, `test_worker_execute.py`, introspection: `test_introspection.py`, hub cache: `test_hub_cache.py`, chaining: `test_chain.py`).
 
 | File | Area |
 | ---- | ---- |
diff --git a/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md
index 460a6de4..2c3aa3e2 100644
--- a/docs/WORKFLOW_GUIDE.md
+++ b/docs/WORKFLOW_GUIDE.md
@@ -244,8 +244,13 @@ document, which is where a draft that validates still fails.
 ### References
 
 An argument value is a reference when it begins with one of these prefixes.
-Each resolves before the step runs; a name that does not resolve fails the run,
-not validation.
+Each resolves before the step runs. `variable:` and `previous_result:` names
+are checked statically, so a bad one is a validation error at the path it
+sits at; a `constant:`, `asset:`, `prompt:` or `output:` name in the
+definition body resolves only when the step runs, and one that is missing
+fails the run - unless it arrives in the `arguments` passed to
+`validate_workflow`, which checks an `asset:`, `prompt:` or `output:` there
+for existence.
 
 - `variable:` — `variable:name` is the workflow's own `variables` entry,
   overridden by the caller's `arguments`. A variable declared `null` is optional and untyped.
@@ -271,6 +276,14 @@ not validation.
 - `prompt:` — `prompt:name` or `prompt:folder/name` is a stored prompt's
   `text`, rooted at the prompt library. That text may not itself begin with any of these
   prefixes; the engine rejects such a prompt rather than resolving twice.
+- `item:` — only inside a step that carries `for_each`: `item:` is the
+  entry the member was made for, `item:field` one field of an object entry,
+  spliced in whole whatever its type — a string, a number, a list of
+  references. See "One step per entry" below.
+- `gather:` — `gather:shot` is the result of *every* member of the
+  `for_each` step `shot`, in list order, as one list. Inside a list it splices
+  into it. It is how a step downstream of a fan-out reads the whole group;
+  `previous_result:shot` naming a `for_each` step is an error that says so.
 
 After a long inline run that is worth keeping, `get_job_workflow(job_id)`
 returns the realized workflow — the definition with the arguments, seed and
@@ -286,8 +299,10 @@ value: `"variable:base_prompt"` resolves, `"variable:base_prompt, in fog"` asks
 for a variable named `base_prompt, in fog` and fails the run. Nothing is
 interpolated around a reference. To vary a fixed prompt across steps, write
 each full prompt out, or put the shared text in a variable and let a step's
-argument override it whole. `validate_workflow` warns about a `variable:`
-reference that names nothing the workflow declares.
+argument override it whole. A `variable:` reference that names nothing the
+workflow declares is a validation error, not a warning: once a `variables`
+block exists the engine refuses an undeclared reference, so it is a run that
+cannot start.
 
 When several steps share a block of text — a character's description and voice
 repeated in every shot of a dialogue short — the answer is composition rather
@@ -329,6 +344,103 @@ pair, each referencing exactly the two things it pairs, or gather the pairs
 upstream so each is a single result. A step that seems to need a "zip" is the
 signal to restructure the workflow, not to add another reference.
 
+### One step per entry: `for_each`
+
+A step that carries `for_each` runs once per entry of a list — a shot per
+entry of `shots` — and the list is a variable the caller supplies, so a
+six-shot episode is an argument rather than a different file.
+
+```json
+{
+  "name": "shot",
+  "for_each": "variable:shots",
+  "pipeline": {
+    "arguments": {
+      "prompt": "item:prompt",
+      "references": "item:references"
+    }
+  }
+}
+```
+
+with
+
+```json
+"shots": [
+  { "name": "wide_open", "prompt": "the band walks on, wide",
+    "references": [{ "reference_type": "…", "from_previous_result": "draw_singer" }] },
+  { "name": "closeup", "prompt": "closeup on the singer",
+    "references": [{ "reference_type": "…", "from_previous_result": "draw_singer" }] }
+]
+```
+
+and downstream
+
+```json
+{ "name": "edit",
+  "task": { "command": "concat_videos", "arguments": { "videos": "gather:shot" } } }
+```
+
+Before the run starts, the engine replaces the `for_each` step with one
+ordinary step per entry, named `shot@wide_open`, `shot@closeup` — the
+entry's `name`, or its index for an entry without one. Those are the names
+the manifest, the job's events and the gallery show, and `@` is reserved
+for them: a hand-written step name may not contain it. An entry's `name`
+must be unique in its list and match `^[a-zA-Z_][a-zA-Z0-9_-]*$`. Give
+entries names: the step cache keys on the member name, so a shot inserted
+in the middle of a named list leaves every other shot cached, while an
+indexed list shifts every later shot onto a different entry and regenerates
+it.
+
+`item:field` is the whole value of that field, so an entry can carry
+anything a step argument can — including a `references` list whose length
+differs by shot, with `from_previous_result` and `asset:` strings inside
+it. Nothing is interpolated: `"item:prompt"` is the field, `"shot: item:prompt"`
+is a literal string.
+
+An entry may name another variable: `"from_file": "variable:character_a_voice"`
+inside a `references` entry is that variable's value by the time the member
+exists, so one variable sets a voice in every shot the character speaks in
+and a caller who supplies the list still writes `variable:` for the parts the
+template fixes. Those references are resolved before anything in the entry is
+loaded, and an undeclared one is a validation error at the entry's path
+(`arguments.shots[2].references[1].from_file` when the list is yours,
+`variables.shots[...]` when it is the template's). A value may not reference
+itself, directly or through another variable.
+
+Two `for_each` steps over the *same* list are paired by key — the entry's
+`name`, or its index for an entry without one: inside `shot@closeup`, a
+reference to another `for_each` step `slice` over the same `shots` list
+resolves to `slice@closeup`. That is how a shot reads the audio
+slice cut for it when slicing and generating are two steps. It is the one
+pairing the engine has; `for_each` runs over exactly one list, and there is
+no zip and no loop index.
+
+Limits: a list has at most 32 entries, and an empty list is a validation
+error — the step would run nothing. Validation realizes a `constant:`
+default before checking it, so a list defaulted to a constant validates the
+same way it will run. `release_pipeline` on a `for_each`
+step releases after the *last* member. Each entry is a full generation, so
+quote the cost before running a list-driven workflow: the listing's `lists`
+block names the fields an entry takes and the steps over it, and its `cost`
+carries `per_entry` once one entry has been measured — quote
+`minutes - per_entry.minutes × per_entry.entries + per_entry.minutes × N` for
+N entries, and without `per_entry` quote the total as the default list's. An
+entry key no step reads is a validation warning at the entry's path, so a
+misspelt field is caught before the run. Then
+`validate_workflow` with the
+`arguments` you will run with: it expands your list, not the template's
+default, resolves the variables your entries name, and reports a duplicate
+name or a missing field at the entry's path.
+
+Every error carries a path in the file you wrote, not in the expanded step
+list: a bad reference inside a member is reported at the `for_each` step's
+own path, with the member it failed in named in the message.
+
+`templates/minimax/dialogue-short` and `templates/minimax/music-video` are
+this shape: each takes one `shots` list, and `get_workflow` on either shows
+the entry an item needs.
+
 ### The loop
 
 1. `validate_workflow` — free and instant. It reports every schema error at
@@ -1016,9 +1128,11 @@ Override the default scheduler:
 }
 ```
 
-A pipeline that carries a second scheduler takes an `audio_scheduler` block with the
-same shape - MiniMax H3 steps video and audio latents down two schedules whose shifts
-are set independently.
+A scheduler block may also carry `shift`, the exponential sigma shift for
+schedulers that take one (MiniMax H3's released checkpoint: 12.0 for video,
+3.0 for audio). A pipeline that carries a second scheduler takes an
+`audio_scheduler` block with the same shape - MiniMax H3 steps video and audio
+latents down two schedules whose shifts are set independently.
 
 ## Seeds
 
diff --git a/docs/WORKSPACES.md b/docs/WORKSPACES.md
index 5496cc86..f27a9cb4 100644
--- a/docs/WORKSPACES.md
+++ b/docs/WORKSPACES.md
@@ -295,11 +295,11 @@ it. Use them to keep work apart, not to keep it private.
 ## Where this is going
 
 Workspaces were the first stage of the design in
-[proposals/server-workspaces.md](proposals/server-workspaces.md). The resolver, the workflow
+[proposals/server-workspaces-complete.md](proposals/server-workspaces-complete.md). The resolver, the workflow
 search path with writes confined to the writable root, run directories with an
 on-disk manifest, `asset:` and `output:` references, and server-side named
 workspaces are all implemented. What remains from the proposal is an MCP
 client that keeps its workspace on its own machine and mirrors it to the
 server — see
-[proposals/server-workspaces.md](proposals/server-workspaces.md) for why
+[proposals/server-workspaces-complete.md](proposals/server-workspaces-complete.md) for why
 mirroring is not currently planned.
diff --git a/docs/proposals/agent-catalog-legibility.md b/docs/proposals/agent-catalog-legibility-complete.md
similarity index 99%
rename from docs/proposals/agent-catalog-legibility.md
rename to docs/proposals/agent-catalog-legibility-complete.md
index 92fa8ae4..d9512afe 100644
--- a/docs/proposals/agent-catalog-legibility.md
+++ b/docs/proposals/agent-catalog-legibility-complete.md
@@ -7,7 +7,7 @@ actually done against each proposal. Part 3 is carried as a constraint and Part
 `catalog-shape-index.md` and `mcp-discovery-data.md` (both fully folded into
 this document and deleted — see git history for the original framing), plus
 the discovery-facing conclusion of
-[scripted-dialogue-and-tts.md](scripted-dialogue-and-tts.md), which keeps its
+[scripted-dialogue-and-tts-complete.md](scripted-dialogue-and-tts-complete.md), which keeps its
 TTS-specific design record but no longer restates the point made here.
 
 Phased and directional throughout: each part names a gap and a direction, not
@@ -318,7 +318,7 @@ way to know that a zip-shaped need (shot *i* paired with speaker *i*) isn't
 expressible this way without hitting the combinatorial-explosion gotcha
 first and reasoning backward. State the rule in `WORKFLOW_GUIDE.md`
 directly: this is the generalized form of the reasoning
-[scripted-dialogue-and-tts.md](scripted-dialogue-and-tts.md) worked out for
+[scripted-dialogue-and-tts-complete.md](scripted-dialogue-and-tts-complete.md) worked out for
 one case, made discoverable instead of living only in a design doc.
 
 ### Proposal 10: close the loop at save time
@@ -428,7 +428,7 @@ design record; the "Plugin drill" section below is the acceptance test.
 The catalog and guides answer "which existing workflow fits", and Part 2's
 primitives answer "how do I compose a new one" — but an agent will
 sometimes hit a shape or a model-specific convention that neither covers.
-[scripted-dialogue-and-tts.md](scripted-dialogue-and-tts.md) worked through
+[scripted-dialogue-and-tts-complete.md](scripted-dialogue-and-tts-complete.md) worked through
 one: turning a plain dialogue script into H3's Context-IR shot list (voice
 descriptions carried verbatim, speaker alternation driving cuts, stripping
 the reference portrait's compositional authority) is knowledge that exists
@@ -514,7 +514,7 @@ starts from the record rather than the intent. Updated as work lands.
 | 6 UI | done (plan 3, 2026-09-07) | spec plan 3 | shape select and trait chips (AND) beside the text filter, client-side over the listing the page holds, options limited to values the listing has; card shows `summary` over `description`, shape and traits as badges beside the kind icons, `cost` as `~1.4 min · 24 GB (RTX 3090)` beside the counts (first entry shown; picking the entry for the running device needs server info the page does not fetch); `templates/` groups before other folders before `models/`, root first |
 | 7 authoring guide | done (plan 2, task 6) | spec §2.3 | `## Authoring a workflow from an agent` in `WORKFLOW_GUIDE.md`, reachable as one `get_guide` section; `CLAUDE.md` points at it; a test checks every reserved prefix is explained there |
 | 8 multi-error validation | done (plan 2, tasks 4–5) | spec §2.2 | `validate_data_all` over `iter_errors`, each reduced with `best_match` so the one-error case reads exactly as before; sorted, deduplicated, capped at 25; `Workflow.validate()` joins one per line under one `Validation errors (N):` heading (the CLI/REPL count the prefix once); `/api/validate` adds `errors` beside the existing `error` — the spec's `message` name was not used because `error` is what every client already reads |
-| 9 composition rules | done (plan 2, task 6) | spec §2.3 | the cartesian rule and the one-step-per-pair form are stated in the authoring section, the general case of `scripted-dialogue-and-tts.md`'s reasoning |
+| 9 composition rules | done (plan 2, task 6) | spec §2.3 | the cartesian rule and the one-step-per-pair form are stated in the authoring section, the general case of `scripted-dialogue-and-tts-complete.md`'s reasoning |
 | 10 save-time metadata | done (task 6) | spec §1.6 | derived and returned on save; empty summary warns, never rejects |
 | Part 3 constraint | carried | spec "Principle" | derivation reads structure, never model family |
 | Part 4 packaging | done: Channel A for the generic item (2026-09-07), Channel B for model families (2026-09-08) | `WORKFLOW_GUIDE.md` authoring section; `plugins/dw/`, `.claude-plugin/marketplace.json`, `.claude/skills/model-family-onboarding` | the spoon-set drill (cold session, PR #48 merged) planned a shared seed for "identical but for colour", which draws a different object per prompt; `### Keeping a set consistent` now says which of style, object or character consistency wants prompts, an edit pass or a reference, and `templates/consistent-set.json` (declared `image-set`: derivation says `image-edit`) is the generate-then-edit shape on FLUX.1 Kontext, whose one pipeline both draws and edits; measured on lem 2026-09-07 at 11.5 warm minutes (2.2 for the base, 3.1 per edit, sequential offload) and the four mugs came out identical but for colour. A FLUX.2 draft found that the HF remote text encoder every FLUX.2 entry names now answers with an HTML page (broken on lem since 2026-08-26); `remote.py` now says so instead of raising an unpickling error, and both FLUX.2 entries load the repo's own 4-bit text encoder under model offload instead. The FLUX.2 text encoder is declared as its own component pinned to the CPU, because BitsAndBytes materializes on the accelerator and the two 4-bit models do not fit at load; the `flash_hub` backend went too, since it needs the `kernels` package no install has. models/flux2-dev measured at 3.3 warm minutes on lem. The Krea edit template moved to FLUX.1 Kontext for the same reason, and a catalog test now refuses `trust_remote_code` and `custom_pipeline` in any bundled entry or packaged builtin, so nothing dw ships asks an operator to lower `--trust-workflows`. The Florence-2 and Phi-3.5 builtins went with it: the `text_generation` task had replaced both, and `describe-and-regenerate` now composes it twice. `### Remote code is refused by default` came out of the same run: the first draft used the Krea edit template's `custom_pipeline`, which a server without `--trust-workflows` refuses at load. Superseded by plugin tasks 1-5 below: `templates/minimax/README.md` and `ltx2/README.md` are the sources the family skills derive from and link back to, so that knowledge is reached through the plugin rather than a third channel. Catalog repair task 1: the latent handoff a two-stage flow needs is proven by test (tests/test_result.py::TestLatentHandoff), no engine change. Catalog repair task 2: two-stage.json is the three-move flow (8 sigmas at 768x448, 2x latent upsample, renoise + 3 stage-two sigmas at 1536x896, audio latents carried); latents pass by name; a test holds noise_scale to STAGE_2_DISTILLED_SIGMA_VALUES[0]. Cost and the sharpness comparison await the lem run (task 7). Catalog repair task 3: the six prompts/ltx2 captions are rewritten to the trained format (one paragraph, 150-220 words, shot type/camera motion/viewpoint in prose, sound interleaved; the two I2V ones describe only what changes), intended_model ltx-2.5, four summaries say LTX-2.5; tests/test_ltx_prompt_library.py holds the shape. Catalog repair task 4: h3_context_ir names its two source guides, writes N/A for silent audio fields, numbers <Video N>/<Audio N> within their category, labels continuity modes as this engine's chaining convention (nothing in the engine emits the phrase; it is a user-message convention), adds the ref guide's dialogue-fidelity rules, drops the two unsourced lines; tests/test_h3_context_ir.py. Catalog repair task 5: both template READMEs link the files that exist, name the vendor sources and the audit, the H3 one states the canvas rules and the 5-second diffusers floor; a test resolves every README link. Lem found templates/minimax/enhance-prompt failing on master already: both enhance templates passed a stored copy of the Context-IR system prompt (prompts/prompt_enhancement/minimax_h3.json, 10096 chars) as a sub-workflow argument, which exceeded MAX_VARIABLE_VALUE_LENGTH 10000; the limit is now 20000, the stored copy is gone, and the templates run the builtin's own prompt, with a test refusing a future override. Three wordings of the N/A rule were drafted before the final review found the templates were running the stored copy, so none of them had been tested; the third, which puts the rule on each audio field's own line, is what shipped.  Catalog repair task 7, verified on lem 2026-09-08: two-stage runs at 1536x896, 8.2 warm minutes (base 1.7, refine 2.7, writing the full-size clip 3.5), latents handed by name and the refine pass served from the pipeline cache; at seed 42 the refined frame is sharp where the upsample-only frame is a soft blur. The fox and hummingbird captions ran as written (tracking shot and pull-out; hold and close-up), the hummingbird soundtrack near-silent. The silent-candle brief's three runs went through the stale stored prompt (final review), so the N/A rule's effect on the Qwen3-4B enhancer is re-verified below. Re-verified 2026-09-08 with the templates on the builtin's prompt: the framed idea the template documents (Task, Duration, Idea) gives a full integrated_multimodal_description with both audio fields N/A; a bare idea first collapsed to the two N/A lines alone, so the description field is now declared unconditional and a bare idea also gets its description (jobs 28f1d29a5b90, be94ed994ecd). The N/A rule took four wordings in all, and only the last two were ever tested. Two engine findings on the way: the step cache keys on the resolved step definition, which names a builtin by path, so editing a builtin does not invalidate a cached step (follow-up); and a cancelled H3 job runs to its next step boundary, minutes on this model. Plugin task 1: a marketplace at the repo root and the dw plugin under plugins/dw, installable with two commands the README shows; plugin.json's version is the engine's, bumped by release.sh and held by test. Plugin task 2: the minimax-h3 skill - shape decision over the family's templates, the frame and canvas rules pinned by test to the diffusers modular pipeline, prompts deferred to MiniMax's h3-prompt-writing skill and the two guides, the run-and-judge loop; the README points at it. Plugin task 3: the ltx-2.5 skill - shape decision, the schedule and size rules pinned to the LTX-2 pipeline, the trained caption spec quoted and held equal to the diffusers constant by test; the README points at it. Final review of the plugin branch: the H3 skill's LoRA coupling scoped to the text- and frame-conditioned templates (the six reference ones run no LoRA at 20 steps), both judge steps rewritten because no MCP tool shows a video frame (the agent hands over the gallery url and checks metadata), the fps rule marked as the DFR path's, tighter numeric pins. Plugin task 4: cold drill 2026-09-08 - pass; the skill fired on the bare prompt, chose templates/minimax/storyboard, wrote a Ref2VA Context-IR prompt, quoted cost and asked before an 11.6-minute run, and inspected the result, where the control ran unasked and could not download the file; the drill caught the skill overstating 20 steps for four LoRA-bearing reference templates (fixed, pinned) and gave storyboard its measured cost (10.1 warm minutes); the mould for the next family is copy a skill, follow its six sections, add the family's rules to tests/test_plugin_skills.py, cite the vendor, and run this drill (.claude/skills/model-family-onboarding). Plugin task 5 (2026-09-08, the 30-second follow-up to the drill): the H3 skill states that nothing carries between generations except a reference, gives the chain-or-cut rule, and says how a cuts piece gets one score and one voice; seven bundled prompts wrote a silent music field as None. and now write N/A, held by test. MiniMax Music 3 went through the lifecycle the same night: audited (docs/proposals/audits/2026-09-08-minimax-music3-audit.md; the ceiling rule and the 44.1 kHz result were confirmed against three primary sources, four small corrections landed: music.json's stale trim-task path, music-video's 21-second ceiling over 20.7 seconds of slices, the README's invented guillotine mechanism, and a text_encoder component the quantization docs showed that Music3 does not have), and plugins/dw/skills/minimax-music3/SKILL.md written with its caps, window, guider and output rate pinned to the diffusers modular pipeline and the caption format deferred to MiniMax's music-caption-rewriter skill, which the repo had never mentioned. Its cold drill is still to run. |
diff --git a/docs/proposals/audits/2026-09-08-minimax-music3-audit.md b/docs/proposals/audits/2026-09-08-minimax-music3-audit.md
index 2c959f9b..64c18e22 100644
--- a/docs/proposals/audits/2026-09-08-minimax-music3-audit.md
+++ b/docs/proposals/audits/2026-09-08-minimax-music3-audit.md
@@ -103,7 +103,7 @@ Failed fetches: `https://github.com/huggingface/diffusers/blob/minimax-music3-in
 
 ### Claims the task asked about that the repository does **not** make
 
-- **Maximum duration**: unstated anywhere in the templates. Vendor: **five minutes** (model card, blog 2026-08-13). Engine: `_MAX_AUDIO_FRAMES = 9_000` at 25 fps = **360 s / six minutes** (`encoders.py`, and the docstring's "Capped at 9000 frames (six minutes)"). These disagree by a minute; the engine cap is the hard stop, the vendor's five minutes is the supported/trained range. Only the internal planning docs (`docs/proposals/agent-catalog-legibility.md:649`, `docs/superpowers/plans/2026-09-07-ltx-h3-catalog-repair.md:1062`) carry the 9000/six-minute figure, and they carry it without the five-minute caveat.
+- **Maximum duration**: unstated anywhere in the templates. Vendor: **five minutes** (model card, blog 2026-08-13). Engine: `_MAX_AUDIO_FRAMES = 9_000` at 25 fps = **360 s / six minutes** (`encoders.py`, and the docstring's "Capped at 9000 frames (six minutes)"). These disagree by a minute; the engine cap is the hard stop, the vendor's five minutes is the supported/trained range. Only the internal planning docs (`docs/proposals/agent-catalog-legibility-complete.md:649`, `docs/superpowers/plans/2026-09-07-ltx-h3-catalog-repair.md:1062`) carry the 9000/six-minute figure, and they carry it without the five-minute caveat.
 - **Full structure-tag vocabulary**: UNSOURCED in the repo — it only ever shows `[verse]`/`[chorus]`.
 - **Instrumental-only**: not addressed anywhere in the repo. Vendor position (see below).
 - **Language support**: not addressed. Vendor: blog demos are Mandarin and English; the caption skill says write the *caption* in English by default; no published language list.
diff --git a/docs/proposals/list-driven-steps-complete.md b/docs/proposals/list-driven-steps-complete.md
new file mode 100644
index 00000000..1d4cce68
--- /dev/null
+++ b/docs/proposals/list-driven-steps-complete.md
@@ -0,0 +1,474 @@
+# Proposal: list-driven steps (`for_each`)
+
+Status: **stages 1, 2 and 3 implemented** (expansion pass, validation, schema,
+docs - `dw/for_each.py`; `music-video` and `dialogue-short` on a `shots`
+list; catalog `lists`, `per_entry` cost schema, entry-key warning, rulings,
+flow-view edges, 2026-09-11). `per_entry` figures for the two templates await
+a measured run. Written for MCP feedback ticket T003.
+
+## The ask, as filed
+
+> `music-video` and `dialogue-short`: each generates one step per shot. A
+> `shots: [...]` variable should fan out generation steps, one per list entry.
+> Step count is fixed in the template; adding a shot means editing the
+> template.
+
+Both templates are written the long way. `music-video` has `shot_1_wide_open`,
+`shot_2_closeup`, `shot_3_room`, `shot_4_finale`, each a near-copy of the one
+before, and `slice_1` … `slice_4` beside them cutting the audio bed into
+matching pieces. `dialogue-short` has five shot steps and two portrait steps.
+A five-shot episode is the template; a six-shot episode is a different file.
+
+The consumer side already moved this way: `assemble-and-score` takes a list,
+and `compose_text(parts=[...])` (T002) assembles text written once. What is
+missing is the generation side - a step that runs once per entry.
+
+## Why this is a proposal and not an edit
+
+Fanning a step out per list entry forces a question the ticket does not
+settle: **how does the downstream step name the group?**
+
+`previous_result:shot` today means "that step's result". A result holding N
+artifacts drives the cartesian iteration the engine already has -
+`dw/previous_results.py:get_iterations`, four images x three masks = twelve
+runs. So a fanned-out group read back through `previous_result:` would run
+the concat once *per shot* rather than once *over all of them*. Gathering and
+iterating are two different meanings and the reference syntax has one
+spelling. That, plus what the expanded steps are called, what the step cache
+keys on, and what the manifest and the realized workflow record, is more
+than a syntax addition.
+
+## The shape
+
+```json
+{
+  "name": "shot",
+  "for_each": "variable:shots",
+  "pipeline": {
+    "arguments": {
+      "prompt": "item:prompt",
+      "references": [
+        { "reference_type": "variable:image_reference_type",
+          "from_previous_result": "draw_singer" }
+      ]
+    }
+  }
+}
+```
+
+with
+
+```json
+"shots": [
+  { "name": "wide_open", "prompt": "the band walks on, wide" },
+  { "name": "closeup",   "prompt": "closeup on the singer" }
+]
+```
+
+and downstream
+
+```json
+{ "name": "edit",
+  "task": { "command": "concat_videos", "arguments": { "videos": "gather:shot" } } }
+```
+
+- `for_each` names a list - a `variable:` reference, or a literal list. One
+  step per entry, in list order.
+- `item:` inside the step is that entry: `item:prompt` is one field, bare
+  `item:` is the whole entry (a list of plain strings is the common case).
+  A field holds whatever the entry wrote there - a string, a number, a list
+  or an object - and the pass splices it in as definition text. This is not
+  optional: `dialogue-short`'s shots reference both characters in shots 1
+  and 5 and one character in shots 2-4, so a shot's `references` list has to
+  come from the entry whole (`"references": "item:references"`), and a
+  scalar-only `item:` could not write that template. An entry may therefore
+  carry `from_previous_result`, `asset:` and `prompt:` strings; they become
+  ordinary references in the expanded step and are checked as such (below).
+- **Same-key siblings.** Inside a `for_each` over a list, a
+  `previous_result:`/`from_previous_result` naming *another* `for_each` step
+  over the same list resolves to the member with the same key:
+  `"from_previous_result": "slice"` inside `shot` becomes
+  `slice@wide_open` inside `shot@wide_open`. This is the one pairing the
+  engine needs and the reason it is not a zip (below): `music-video` slices
+  the audio bed in one task step and generates the shot in a pipeline step,
+  so shot *i* reads slice *i* across two steps, and "put both in one entry"
+  cannot express it. The two groups must name the same list (the same
+  `variable:` or an identical literal); a same-key reference into a group
+  over a different list is an error.
+- `gather:shot` is the list of every member's artifacts, in order, as one
+  value. It is a *list-valued* reference, which is the distinction
+  `previous_result:` cannot make.
+
+### Recommendation: expansion is a source transform, not a runtime concept
+
+Run the expansion as a pass over the definition immediately after
+`replace_variables` in `Workflow.run` (`dw/workflow.py`), before the run id is
+computed and before the step loop starts. The pass:
+
+1. replaces each `for_each` step with N ordinary steps, named `shot@wide_open`
+   … (below);
+2. substitutes `item:` references inside each copy with that entry's values,
+   and rewrites a same-key sibling reference to the member with this key;
+3. rewrites every `gather:shot` into the explicit list of
+   `["previous_result:shot@wide_open", "previous_result:shot@closeup"]` -
+   exactly what a hand-written template contains today.
+
+After the pass the definition is an ordinary workflow. Nothing below it
+changes: no new reference kind at run time, no change to what
+`previous_result:` means, no change to the cartesian rule, and the step cache,
+the manifest, the event stream and `pipeline_reference` all keep working
+because they are looking at ordinary steps. **This is the argument for the
+whole design** - the alternative, teaching `get_previous_results` a second
+meaning, touches every consumer of a result and leaves two spellings that
+differ only by whether a group happens to be behind them.
+
+Consequences worth stating:
+
+- A `gather:` written *inside* a list splices into it
+  (`["previous_result:intro", "gather:shot"]` is one flat list), because
+  textual expansion is the natural reading. A `gather:` naming a step that is
+  not a `for_each` group is an error, not a one-element list - that is a typo
+  every time.
+- Pipeline loading is already shared: `pipeline_cache_key` hashes what a
+  pipeline *loads*, excluding arguments and seed, so N identical expanded
+  pipeline blocks hit one loaded model within the run. The expansion needs no
+  `pipeline_reference` rewriting to get the reuse the hand-written template
+  gets by hand (the templates' `pipeline_reference` shots become full
+  pipeline blocks in the expansion, and `pipeline_reference` inside a
+  `for_each` step is meaningless). `release_pipeline` on a fanned step would
+  drop the model after the first member and reload it for the second: the
+  pass carries it onto the **last member only**, and `release_models` the
+  same way.
+- `realize_args(variables)` runs on the variables *before* substitution
+  (`dw/arguments.py`, the `isinstance(v, list)` branch hands a list to
+  `resolve_path_references`). Stage 1 must confirm that an `asset:` inside an
+  entry object comes out as a path and not as loaded media, or `item:` would
+  splice a PIL object into the definition. If it loads, exempt the list a
+  `for_each` names and let the expanded step realize it as any step does.
+
+### Expanded names: the entry's own name before its index
+
+`shot@wide_open` when the entry is an object carrying a `name`, else
+`shot@0`, `shot@1`.
+
+The index alone is tempting and wrong for the cache. Entries are keyed
+`(workflow id, step name)` in `dw/step_cache.py`, so inserting a shot in the
+middle shifts every later index onto a different entry's content. The cache
+validates against the step's data as well, so the result is correct - it is a
+miss - but every shot after an insertion regenerates, which on a six-shot H3
+episode is most of an hour of GPU to add one shot in the middle. A name
+carried by the entry survives insertion, and it also makes the manifest, the
+event stream and the gallery read in shot names rather than in ordinals.
+
+`@` rather than dots, underscores or brackets: `.` is already the property
+separator in a reference (`previous_result:segment.mask`), `_` and `-`
+collide with a hand-written `shot_1`, and `:` is the reference-prefix
+separator. Brackets were the first draft and are wrong for a reason that
+only shows up later: the name lands in a filename
+(`{workflow_id}-{step_name}.{i}`, `dw/workflow.py`), and `[...]` is a shell
+glob class - `ls *shot[wide_open]*` matches one character - as well as a
+character every gallery and MCP URL would have to encode. `@` is none of
+those. A step name is otherwise an unrestricted string, so `@` has to be
+reserved - a hand-written step named `shot@0` becomes an error.
+
+**Entry names are validated.** The name reaches the filesystem and the
+step-cache key, so it must match the variable-name pattern
+(`validate_variable_name`, `^[a-zA-Z_][a-zA-Z0-9_-]*$`) and be unique within
+its list - two entries named `closeup` would otherwise expand to two steps
+with one name, one cache entry and one clobbered output file. Both are
+errors from the pass, reported with the entry's position.
+
+### Validation
+
+The static reference check shipped for T005
+(`previous_result_reference_errors`) runs on the unexpanded definition, where
+`shot@wide_open` does not exist yet. `validate_workflow` should run the same
+expansion first and check the expanded steps. It expands **the list the run
+will use**: `POST /api/validate` already takes the caller's `arguments`
+(`argument_errors` folds them the way `set_variables` does), so the
+pre-flight expands the folded list, not the declared default - otherwise it
+checks a step set the caller is not about to run. Without arguments the
+default is the list, and an empty or absent one validates as zero steps and
+a `gather:` naming nothing. Order becomes: schema -> substitute -> expand ->
+reference check. Schema validation stays where it is, against the template
+step, and the schema gains `for_each` on a step plus the `item:`/`gather:`
+prefixes wherever a reference is allowed.
+
+Two errors deserve their own message rather than the generic "names no
+earlier step": `previous_result:shot` where `shot` is a `for_each` group
+("use `gather:shot`, or a same-key reference from inside a group over the
+same list"), and `gather:` naming a step that is not a group. References an
+entry carries (`from_previous_result` inside `item:references`) are checked
+in the expanded step like any other, which is where they exist.
+
+### The realized workflow and the manifest
+
+`dw/realize.py` folds the run's arguments into the variable defaults, so a
+realized list-driven workflow carries the actual `shots` list and reproduces
+the same expansion deterministically. **Keep `for_each` in the realized file**
+rather than writing the expanded steps: it reproduces the run exactly and stays
+legible. The manifest names the expanded steps (`shot@wide_open`), because the
+manifest records what ran. That the two name steps differently is deliberate
+and should be documented where the manifest is.
+
+### Limits and cost
+
+Each entry is a full generation, so the expansion needs a ceiling of its own,
+well below `MAX_ITERATIONS = 10000`, which guards a different thing. The
+ceiling and the step cache's bound have to be stated together: the cache
+holds `DEFAULT_MAX_ENTRIES = 50` (`dw/step_cache.py`, LRU), and a run whose
+expanded steps exceed it evicts its own earlier members - the insertion case
+the naming scheme exists for stops hitting, silently. `music-video` expands
+to shots + slices + five fixed steps, so the cache is full at about twenty
+shots. Either the ceiling is set so a maximal run fits (32 entries, under
+any of the templates) or the cache bound is raised alongside it; the
+proposal picks **32 and leaves the cache alone** unless a real template
+needs more (raised to 128 in stage 3).
+
+The larger consequence is that a list-driven template's cost is set by the
+caller: `list_workflows` quotes a per-workflow figure today, and a six-entry
+`shots` list is six times the shot cost. The catalog entry should carry the
+per-entry cost and the variable it multiplies by, **and the shape of an
+entry** - which fields it takes, which are required, what `name` is for -
+because an agent composing over MCP sees only the catalog and cannot
+otherwise author the list. The MCP guidance (`docs/WORKFLOW_GUIDE.md`,
+"Authoring a workflow from an agent") should say to quote `cost x len(list)`
+before running.
+
+### What this does not do
+
+It does not give the engine a "zip". `for_each` runs over **one** list; a
+pairing - shot *i* with its audio slice *i* - is expressed by putting both in
+the same entry:
+
+```json
+{ "name": "wide_open", "prompt": "...", "start_frame": 0 }
+```
+
+That is the same answer the guide already gives for the cartesian rule
+("write it as one step per pair"), and it is why the entry should be an object
+rather than a string in any template that has more than a prompt to vary. The
+same-key sibling rule is the one place two *steps* are paired, and it pairs
+them by name over one list rather than zipping two. Two `for_each` lists on
+one step, or a `for_each` over a cartesian product, is out of scope and
+probably always should be.
+
+## Phasing
+
+1. **Expansion pass + `item:` + `gather:`** with structured `item:` values
+   and the same-key sibling rule, entry-name validation, schema, validation
+   ordering (arguments folded, the two directed errors), the 32-entry
+   ceiling, `release_pipeline`/`release_models` on the last member, and the
+   reserved `@`. No template changes. This is self-contained and testable
+   without a GPU: the pass is a pure function from definition to definition,
+   so its tests are ordinary unit tests - and the two tests that matter most
+   are the two templates rewritten by hand in the test suite and expanded
+   back to what they contain today.
+2. **`music-video` and `dialogue-short` rewritten** onto a `shots` list. Both
+   are breaking for scripted callers - the per-shot variables
+   (`shot_2_deflect`, `shot_3_react`, …) become entries in one list - and
+   T005 has already broken those names once this week, so the two should land
+   together or the second should wait for a deliberate version bump of the
+   templates. The `dw:minimax-h3` plugin skill quotes those variables and
+   `tests/test_plugin_skills.py` pins what it quotes, so both move with the
+   templates.
+3. **Cost and entry-shape reporting** for a list-driven entry, in the catalog
+   and in the plugin skills that quote it.
+
+Stage 1 is the bulk of the work and carries the risk; stages 2 and 3 are
+mechanical once it exists.
+
+## Decided at review
+
+- **No loop index inside an entry.** Nothing in the two templates needs
+  "shot 3 of 6" in a prompt. Adding `item:@index` later is compatible; making
+  it available now costs a second special name.
+- **`for_each` does not accept a number** (`"for_each": 4`). It reads well
+  and it is one line in the pass, but it gives entries no names, which is
+  exactly the cache problem above.
+- **`dialogue-short`'s two-speaker structure** (which character speaks in
+  which shot, T010's voice references) is carried by each entry's
+  `references` list, spliced whole by `item:references` - a `"speaker": "a"`
+  flag was the first idea and cannot produce a references list whose length
+  varies by shot. The template question stage 2 has to get right is how much
+  of that list the entry writes and how much the template fixes.
+
+## Notes for stage 2
+
+Observations from the stage-1 review, recorded so the template rewrite does
+not have to rediscover them:
+
+- **`pipeline_reference.reference_name` naming a `for_each` group gets no
+  directed error.** Both templates use `pipeline_reference` on their shot
+  steps, and a reference to a group's name resolves to nothing helpful - the
+  expansion only rewrites `previous_result:` and `from_previous_result`.
+  Rewriting a shot step onto `for_each` means either pointing every member's
+  `pipeline_reference` at a step outside the group, or giving that key the
+  same treatment.
+- **An entry field named `image`/`*_image`/`*_video` is realized before
+  expansion.** `realize_args` runs over the variables, so such a field is a
+  loaded PIL image or a decoded frame list by the time `item:image` splices
+  it into a member. It works, it is untested, and it is why the expansion
+  copies a leaf only inside a member and falls back to the object itself
+  when it cannot be copied.
+- **A `for_each` over an empty list expands to zero steps.** A workflow whose
+  only step is that one returns before `workflow_start`, so the run produces
+  no events and no manifest entries. Whether that is an error or an empty
+  success is a stage-2 decision.
+- **`expanded_definition` skips `realize_constants`.** A list defaulted to a
+  `constant:` name fails validation (the list arrives as the `constant:`
+  string) and then runs fine, since `Workflow.run` does realize constants. A
+  template that wants a constant default needs that pass in the validator.
+
+Resolved in stage 2: the `pipeline_reference` question went away - every
+member is the full pipeline block, and the identity-keyed pipeline cache
+reuses the loaded model exactly as the reference did (a test holds every
+member to one `pipeline_cache_key`). A group's `pipeline_reference` still
+gets no directed error; nothing bundled uses one now. Entries that name
+other variables (`variable:character_a_voice`) are resolved by
+`resolve_variable_values` before `realize_args`, which is what let the
+optional voices move into the entries. The empty-list and
+`realize_constants` questions are still open and belong to stage 3 with the
+catalog work.
+
+## Stage 3: cost and entry shape (design)
+
+Written after stage 2 merged (2026-09-11). Stage 2 left an agent composing
+over MCP with two gaps, both in what the catalog tells it: how much a
+list-driven run costs when the list is the agent's, and what an entry of
+that list has to contain. The stopgap in the skill and the guide - divide
+the listing's total by the default entry count - runs high because the
+total includes the fixed steps (portraits, the song), and nothing in the
+listing says which fields an entry takes. The rules below follow the
+catalog's standing principles: cost is measured, never derived; structure is
+derived, never declared twice.
+
+### Cost: a measured per-entry figure beside the measured total
+
+A `cost` entry gains an optional `per_entry` block:
+
+```json
+"cost": [
+  {
+    "device": "cuda", "name": "RTX 3090", "vram_gb": 24, "minutes": 42,
+    "per_entry": {"variable": "shots", "minutes": 7.2, "entries": 5}
+  }
+]
+```
+
+- `minutes` stays what it is: the measured total for the workflow as
+  shipped, so every existing consumer and test is untouched.
+- `per_entry.minutes` is the measured cost of one entry - the sum of every
+  member the entry produces (`slice@x` plus `shot@x` for music-video), taken
+  from the run's step timings, averaged over the default list.
+- `per_entry.entries` is the length of the default list the total was
+  measured with, so the fixed part is recoverable: `fixed = minutes -
+  per_entry.minutes × entries`, and a run over N entries quotes `fixed +
+  per_entry.minutes × N`. Recording `entries` rather than `fixed` keeps
+  both numbers on the file as they were measured; a later edit of the
+  default list that forgets the cost block fails a test that compares
+  `entries` to `len(variables[variable])`.
+- Schema: `per_entry` is `{variable: string, minutes: number ≥ 0, entries:
+  integer ≥ 1}`, `additionalProperties: false`; `variable` must name a
+  list-valued variable that some step's `for_each` reads (test).
+
+The listing carries `cost` through unchanged (it already does), so
+`per_entry` reaches `list_workflows` in both views with no projection
+change. The skill and the guide replace the divide-by-default stopgap with
+the formula; `tests/test_plugin_skills.py` pins that the H3 skill quotes
+`per_entry`. Both templates need a measured run on lem for the numbers -
+the step timings T021 put in the job's progress block are the source, so
+one run per template gives every figure.
+
+### Entry shape: derived from what the steps read
+
+Nothing has to be declared. A `for_each` step reads its entry through
+`item:` strings, so the fields an entry needs are exactly the set of
+`item:<field>` references across every step over that variable, plus
+`name`. `derive_catalog_metadata` gains a `lists` block:
+
+```json
+"lists": {
+  "shots": {
+    "fields": ["name", "num_frames", "prompt", "references"],
+    "steps": ["shot"],
+    "entries": 5
+  }
+}
+```
+
+- `fields`: sorted union of `item:` fields over every step whose `for_each`
+  is `variable:<name>`, with `name` first. `item:` alone (the whole entry,
+  used when entries are scalars) yields `fields: null` and the entry is a
+  value, not an object.
+- `steps`: the `for_each` steps over that list, so an agent knows
+  `shot@<name>` and `slice@<name>` are what the manifest will show.
+- `entries`: the default list's length, which is what the cost block's
+  `entries` is checked against.
+
+`lists` joins `COMPACT_FIELDS`: it is what authoring the argument needs,
+and it is small. A workflow with no `for_each` has `lists: {}` and the
+compact view drops the key when empty, so listings that never had it do
+not grow.
+
+The meaning of each field stays where meaning lives today - the
+description and the template's default entries. `GET
+/api/workflows/{name}/variables` is the call that shows those defaults,
+and its 200-character preview only cuts *string* variables; a `shots` list
+comes back whole, ten kilobytes of prompts for dialogue-short. Stage 3
+extends the preview into list and dict values (`shots[0].prompt` named in
+`truncated`), so an agent sees the shape of every entry at a glance and
+asks for `full=true` when it wants the text.
+
+### Validation: unknown entry keys
+
+A missing field is already a `ForEachError` at the entry's path. An extra
+key - `num_frame` for `num_frames` - is ignored in silence today, and the
+member then runs with the template's value for the field the caller meant
+to override. Stage 3 reports an entry key no step reads as a validation
+*warning* (not an error: a caller may carry an annotation field on
+purpose), at the entry's path, naming the fields the list takes. The
+`lists.fields` derivation is the same computation, so this is one function
+used twice.
+
+### Decisions carried from stage 2, ruled here
+
+- **An empty `for_each` list is a validation error**, not an empty success.
+  A workflow that expands to no generating step is never what a caller
+  asked for, and the run producing no manifest and no events looks like a
+  server fault. `expand_for_each` raises `ForEachError` at the step's path
+  with "for_each over an empty list would run no steps"; the schema's
+  `minItems: 1` covers the literal form.
+- **`expanded_definition` runs `realize_constants`** before substitution,
+  the way `Workflow.run` does, so a list defaulted to a `constant:` name
+  validates as it runs. It is a name lookup, no download, so the pre-flight
+  stays free.
+- **The step cache's bound has to clear a maximal run.** 32 entries over
+  two groups plus fixed steps is ~70 members; `DEFAULT_MAX_ENTRIES = 50`
+  (`dw/step_cache.py`) evicts a run's own earlier members before it ends,
+  which silently defeats the insertion case the naming scheme exists for.
+  Raised to 128 (`dw/step_cache.py`) - the proposal's original "leave it
+  alone unless a real template needs more" no longer holds once the
+  ceiling is 32.
+- **The editor's flow view draws no edges for `gather:` or `item:`**
+  (`ui/src/lib/flow.ts` maps only `previous_result:`), so both templates
+  render their editor step as an orphan. An edge from each `for_each` step
+  to the step that gathers it, and between paired groups over one list,
+  is the whole fix; it is UI-only and can ship with or after the rest.
+
+### Order of work
+
+1. `lists` derivation + `COMPACT_FIELDS` + unknown-key warning (pure
+   functions, unit-tested, no GPU).
+2. `per_entry` schema, the two catalog tests (variable named exists; entries
+   matches the default list), the variables-endpoint nested preview.
+3. Skill and guide wording, pinned by test; MCP server instructions mention
+   `lists` and `per_entry` in the `list_workflows` sentence.
+4. Empty-list error, `realize_constants` in validation, cache bound.
+5. Measure both templates on lem (one run each) and fill in `per_entry`.
+6. Flow-view edges.
+
+Steps 1-4 are self-contained and testable here; step 5 is the only one
+that needs the GPU box, and the skill's formula degrades honestly without
+it (no `per_entry` means "quote the total and say the list is the
+default's").
diff --git a/docs/proposals/list-driven-steps.md b/docs/proposals/list-driven-steps.md
deleted file mode 100644
index 4f9101b2..00000000
--- a/docs/proposals/list-driven-steps.md
+++ /dev/null
@@ -1,216 +0,0 @@
-# Proposal: list-driven steps (`for_each`)
-
-Status: **needs approval**. Written for MCP feedback ticket T003; nothing here
-is implemented.
-
-## The ask, as filed
-
-> `music-video` and `dialogue-short`: each generates one step per shot. A
-> `shots: [...]` variable should fan out generation steps, one per list entry.
-> Step count is fixed in the template; adding a shot means editing the
-> template.
-
-Both templates are written the long way. `music-video` has `shot_1_wide_open`,
-`shot_2_closeup`, `shot_3_room`, `shot_4_finale`, each a near-copy of the one
-before, and `slice_1` … `slice_4` beside them cutting the audio bed into
-matching pieces. `dialogue-short` has five shot steps and two portrait steps.
-A five-shot episode is the template; a six-shot episode is a different file.
-
-The consumer side already moved this way: `assemble-and-score` takes a list,
-and `compose_text(parts=[...])` (T002) assembles text written once. What is
-missing is the generation side - a step that runs once per entry.
-
-## Why this is a proposal and not an edit
-
-Fanning a step out per list entry forces a question the ticket does not
-settle: **how does the downstream step name the group?**
-
-`previous_result:shot` today means "that step's result". A result holding N
-artifacts drives the cartesian iteration the engine already has -
-`dw/previous_results.py:get_iterations`, four images x three masks = twelve
-runs. So a fanned-out group read back through `previous_result:` would run
-the concat once *per shot* rather than once *over all of them*. Gathering and
-iterating are two different meanings and the reference syntax has one
-spelling. That, plus what the expanded steps are called, what the step cache
-keys on, and what the manifest and the realized workflow record, is more
-than a syntax addition.
-
-## The shape
-
-```json
-{
-  "name": "shot",
-  "for_each": "variable:shots",
-  "pipeline": {
-    "arguments": {
-      "prompt": "item:prompt",
-      "references": [
-        { "reference_type": "variable:image_reference_type",
-          "from_previous_result": "draw_singer" }
-      ]
-    }
-  }
-}
-```
-
-with
-
-```json
-"shots": [
-  { "name": "wide_open", "prompt": "the band walks on, wide" },
-  { "name": "closeup",   "prompt": "closeup on the singer" }
-]
-```
-
-and downstream
-
-```json
-{ "name": "edit",
-  "task": { "command": "concat_videos", "arguments": { "videos": "gather:shot" } } }
-```
-
-- `for_each` names a list - a `variable:` reference, or a literal list. One
-  step per entry, in list order.
-- `item:` inside the step is that entry: `item:prompt` is one field, bare
-  `item:` is the whole entry (a list of plain strings is the common case).
-- `gather:shot` is the list of every member's artifacts, in order, as one
-  value. It is a *list-valued* reference, which is the distinction
-  `previous_result:` cannot make.
-
-### Recommendation: expansion is a source transform, not a runtime concept
-
-Run the expansion as a pass over the definition immediately after
-`replace_variables` in `Workflow.run` (`dw/workflow.py`), before the run id is
-computed and before the step loop starts. The pass:
-
-1. replaces each `for_each` step with N ordinary steps, named `shot[wide_open]`
-   … (below);
-2. substitutes `item:` references inside each copy with that entry's values;
-3. rewrites every `gather:shot` into the explicit list of
-   `["previous_result:shot[wide_open]", "previous_result:shot[closeup]"]` -
-   exactly what a hand-written template contains today.
-
-After the pass the definition is an ordinary workflow. Nothing below it
-changes: no new reference kind at run time, no change to what
-`previous_result:` means, no change to the cartesian rule, and the step cache,
-the manifest, the event stream and `pipeline_reference` all keep working
-because they are looking at ordinary steps. **This is the argument for the
-whole design** - the alternative, teaching `get_previous_results` a second
-meaning, touches every consumer of a result and leaves two spellings that
-differ only by whether a group happens to be behind them.
-
-Consequences worth stating:
-
-- A `gather:` written *inside* a list splices into it
-  (`["previous_result:intro", "gather:shot"]` is one flat list), because
-  textual expansion is the natural reading. A `gather:` naming a step that is
-  not a `for_each` group is an error, not a one-element list - that is a typo
-  every time.
-- Pipeline loading is already shared: `pipeline_cache_key` hashes what a
-  pipeline *loads*, excluding arguments and seed, so N identical expanded
-  pipeline blocks hit one loaded model within the run. The expansion needs no
-  `pipeline_reference` rewriting to get the reuse the hand-written template
-  gets by hand. `release_pipeline` on a fanned step is the exception: it would
-  drop the model after the first member and reload it for the second. Refuse
-  it on a `for_each` step, or honour it only on the last member.
-
-### Expanded names: the entry's own name before its index
-
-`shot[wide_open]` when the entry is an object carrying a `name`, else
-`shot[0]`, `shot[1]`.
-
-The index alone is tempting and wrong for the cache. Entries are keyed
-`(workflow id, step name)` in `dw/step_cache.py`, so inserting a shot in the
-middle shifts every later index onto a different entry's content. The cache
-validates against the step's data as well, so the result is correct - it is a
-miss - but every shot after an insertion regenerates, which on a six-shot H3
-episode is most of an hour of GPU to add one shot in the middle. A name
-carried by the entry survives insertion, and it also makes the manifest, the
-event stream and the gallery read in shot names rather than in ordinals.
-
-Brackets rather than dots or underscores: `.` is already the property
-separator in a reference (`previous_result:segment.mask`) and `_` collides
-with a hand-written `shot_1`. A step name is otherwise an unrestricted string,
-so the bracket form has to be reserved - a hand-written step named `shot[0]`
-becomes an error.
-
-### Validation
-
-The static reference check shipped for T005
-(`previous_result_reference_errors`) runs on the unexpanded definition, where
-`shot[wide_open]` does not exist yet. `validate_workflow` should run the same
-expansion first, using the variables' declared defaults, and check the
-expanded steps - which also means an empty or absent default list validates
-as zero steps and a `gather:` naming nothing. Order becomes: schema ->
-substitute -> expand -> reference check. Schema validation stays where it is,
-against the template step, and the schema gains `for_each` on a step plus the
-`item:`/`gather:` prefixes wherever a reference is allowed.
-
-### The realized workflow and the manifest
-
-`dw/realize.py` folds the run's arguments into the variable defaults, so a
-realized list-driven workflow carries the actual `shots` list and reproduces
-the same expansion deterministically. **Keep `for_each` in the realized file**
-rather than writing the expanded steps: it reproduces the run exactly and stays
-legible. The manifest names the expanded steps (`shot[wide_open]`), because the
-manifest records what ran. That the two name steps differently is deliberate
-and should be documented where the manifest is.
-
-### Limits and cost
-
-Each entry is a full generation, so the expansion needs a ceiling of its own -
-something like 64 steps, refused outright above it, well below
-`MAX_ITERATIONS = 10000`, which guards a different thing. The larger
-consequence is that a list-driven template's cost is set by the caller:
-`list_workflows` quotes a per-workflow figure today, and a six-entry `shots`
-list is six times the shot cost. The catalog entry should carry the per-entry
-cost and the variable it multiplies by, and the MCP guidance
-(`docs/WORKFLOW_GUIDE.md`, "Authoring a workflow from an agent") should say to
-quote `cost x len(list)` before running.
-
-### What this does not do
-
-It does not give the engine a "zip". `for_each` runs over **one** list; a
-pairing - shot *i* with its audio slice *i* - is expressed by putting both in
-the same entry:
-
-```json
-{ "name": "wide_open", "prompt": "...", "start_frame": 0 }
-```
-
-That is the same answer the guide already gives for the cartesian rule
-("write it as one step per pair"), and it is why the entry should be an object
-rather than a string in any template that has more than a prompt to vary. Two
-`for_each` lists on one step, or a `for_each` over a cartesian product, is out
-of scope and probably always should be.
-
-## Phasing
-
-1. **Expansion pass + `item:` + `gather:`**, schema, validation ordering, the
-   64-step ceiling, and the reserved bracket name. No template changes. This is
-   self-contained and testable without a GPU: the pass is a pure function from
-   definition to definition, so its tests are ordinary unit tests.
-2. **`music-video` and `dialogue-short` rewritten** onto a `shots` list. Both
-   are breaking for scripted callers - the per-shot variables
-   (`shot_2_deflect`, `shot_3_react`, …) become entries in one list - and
-   T005 has already broken those names once this week, so the two should land
-   together or the second should wait for a deliberate version bump of the
-   templates.
-3. **Cost reporting** for a list-driven entry, in the catalog and in the
-   plugin skills that quote it.
-
-Stage 1 is the bulk of the work and carries the risk; stages 2 and 3 are
-mechanical once it exists.
-
-## Open questions for the approval
-
-- **Is the loop index needed inside an entry?** Nothing in the two templates
-  needs "shot 3 of 6" in a prompt, so v1 exposes no index. Adding `item:@index`
-  later is compatible; making it available now costs a second special name.
-- **Should `for_each` accept a number** (`"for_each": 4`) for the case where
-  only the count varies? It reads well and it is one line in the pass, but it
-  gives entries no names, which is exactly the cache problem above.
-- **`dialogue-short`'s two-speaker structure** (which character speaks in which
-  shot, T010's voice references) becomes a field on each entry
-  (`"speaker": "a"`). That is a template question, not an engine one, but it is
-  the thing stage 2 has to get right.
diff --git a/docs/proposals/output-folders.md b/docs/proposals/output-folders.md
new file mode 100644
index 00000000..b080168a
--- /dev/null
+++ b/docs/proposals/output-folders.md
@@ -0,0 +1,268 @@
+# Proposal: folders for a job's outputs
+
+Status: **proposed, not implemented**. Written for MCP feedback ticket T016.
+
+## The ask, as filed
+
+> Jobs and workspace outputs support folders one level deep - the same
+> shape, look, and behaviour as the folder support that already exists for
+> the workflow and prompt libraries. The intent is separation of
+> intermediate outputs from final ones. Folders carry through all three
+> surfaces: MCP tools, REST API, and UI. MCP consumers are steered toward
+> using them for the intermediate/final distinction.
+>
+> Actual: everything a job produces sits at one level, so a finished episode
+> is indistinguishable from the twenty scratch files that went into it
+> without reading names.
+
+The report is accurate. A `dialogue-short` run writes its five shot videos,
+its portrait stills, its sliced audio beds and its one assembled episode
+into a single run directory, distinguished only by the step name embedded in
+each file name. The consumer of that run - an agent deciding what to show
+the user, or a person opening the gallery - has to know the workflow to know
+which file is the deliverable.
+
+## Why this is a proposal and not an edit
+
+A destination folder is a new field in the workflow schema, which means it
+is a concept every consumer has to learn and every surface has to carry. But
+the reason it is a proposal rather than an edit is narrower than that: **the
+output tree already has a layer with the meaning this wants.**
+
+A run writes to `<output root>/<workflow identity>/<run id>/`, and three
+separate things read that shape by position:
+
+- `strip_run_id` (`dw/runs.py`) turns `ltx2/Gyre/20260905-181530-a1b2c3d4/
+  still-0.png` into the gallery folder `ltx2/Gyre`, which is how a workflow
+  run fifty times is one entry in the folder filter rather than fifty.
+- `output:` references are `<workflow identity>/<run id>/<file>`, with
+  `latest` allowed in the run-id position (`resolve_output_reference`).
+- The manifest, and `workflow.json` beside it, sit at the root of the run
+  directory and describe everything in it.
+
+Adding a folder *inside* a run directory puts a segment between the run id
+and the file name, and every one of those three readers has to be told which
+segment is which. Getting that wrong is not a cosmetic bug: `strip_run_id`
+would start reporting `ltx2/Gyre/final` and `ltx2/Gyre/intermediate` as two
+unrelated workflows in the gallery filter, and an `output:` reference that
+worked yesterday would resolve to nothing. That is the part that needs
+deciding before anything is written.
+
+There is also a question the ticket settles one way and the existing code
+settles the other, covered under [Open questions](#open-questions): the
+workflow and prompt libraries do not actually enforce one level.
+
+## The shape
+
+A step's `result` block names the folder its files are written into:
+
+```json
+{
+  "name": "assemble_episode",
+  "task": { "command": "concat_videos", "arguments": { "...": "..." } },
+  "result": {
+    "content_type": "video/mp4",
+    "folder": "final"
+  }
+}
+```
+
+- `folder` is optional. Without it, files are written where they are written
+  today: at the root of the run directory. **Every existing workflow keeps
+  working unchanged, and a workflow that never sets `folder` is
+  indistinguishable from one written before this existed.**
+- The value is a relative path validated the way every other
+  workflow-supplied path segment is - through `validate_output_path` against
+  the run directory, so `../` and absolute paths are refused rather than
+  escaping into another run.
+- It may carry a `variable:` reference, so a caller can route a run's
+  outputs without editing the workflow.
+- It is per step, not per workflow: the point is that one run's steps land
+  in different places.
+
+The convention the tooling steers toward is two names, `final` and
+`intermediate` - see [Steering](#steering-consumers-toward-it). The engine
+does not know those names or treat them specially; a workflow that wants
+`shots/` and `audio/` gets them.
+
+## What each surface does with it
+
+### The run directory and the manifest
+
+```
+outputs/dialogue-short/20260911-205805-a1b2c3d4/
+  manifest.json
+  workflow.json
+  intermediate/dialogue_short-shot_a.0-0.0.mp4
+  intermediate/dialogue_short-slice_a.0-0.0.wav
+  final/dialogue_short-assemble.0-0.0.mp4
+```
+
+The manifest already records each step's files as paths relative to the run
+directory (`manifest_relative_files`), so a foldered file appears as
+`final/dialogue_short-assemble.0-0.0.mp4` with no schema change to the
+manifest at all. Each manifest entry additionally carries `folder` (the
+empty string for an unfoldered step), so a consumer can group without
+parsing paths.
+
+### `get_job` and `list_jobs`
+
+`get_job`'s manifest gains the `folder` on each entry, which is additive. On
+top of that, a finished job's reply carries:
+
+```json
+"outputs": { "final": ["final/...mp4"], "intermediate": ["intermediate/...mp4", "..."] }
+```
+
+- a grouping of the manifest's files by folder, so "what did this produce"
+  is answerable without walking the manifest. A job whose workflow uses no
+  folders reports `{"": [...]}`, which is the honest answer rather than a
+  guess at which file is the deliverable.
+
+`list_jobs` stays a listing: it gains nothing per job, because a row that
+carried file lists is what T018 just finished cutting down. The `total`/
+`truncated` shape is untouched.
+
+### The gallery listing (`GET /api/gallery`, MCP `list_gallery`)
+
+This is the surface where the decision above bites. The rule:
+
+- `folder` on a gallery entry stays **the workflow identity**, exactly as
+  today - `ltx2/Gyre`, not `ltx2/Gyre/final`. The folder filter continues to
+  group a workflow's runs, which is what it is for.
+- A new field, `group` (`final`, `intermediate`, or `""`), carries the
+  in-run folder, and `GET /api/gallery` takes an optional `?group=` filter
+  beside the existing `?folder=`.
+- `strip_run_id` is extended to drop everything after the run id rather than
+  just the file name: `ltx2/Gyre/<run>/final/x.mp4` -> `ltx2/Gyre`, and the
+  discarded segments become the `group`. Today's paths are unaffected
+  because they have nothing after the run id.
+
+This keeps the two axes separate - *which workflow* and *which part of the
+run* - rather than multiplying them into one filter list that grows by a
+factor of two for every workflow.
+
+### `asset:` and `previous_result:`
+
+- **`previous_result:` is unaffected.** It names a step, and results are
+  passed in memory between steps; where a step's files landed on disk has
+  never been part of it. A foldered step is read back exactly as it is now.
+- **`output:` gains one segment.** The name is
+  `<workflow identity>/<run id>/<file>`, where `<file>` is already allowed
+  to be a relative path - `_resolve_segments` walks segments and
+  `validate_output_reference` permits `/`. So
+  `output:dialogue-short/latest/final/episode.mp4` works with **no change to
+  the resolver**, and the `latest` search (newest run that holds the file)
+  keeps working because it is a per-run existence check on the whole
+  remainder of the path.
+- **`asset:` is unaffected.** The asset library is a separate tree and
+  already takes nested names (`asset:gyre/frames/web.mp4`).
+- **`keep_output`** takes the output's relative name, which now may contain
+  the folder, and writes into the asset library under `asset_name` as
+  before. The output's folder is not copied into the asset name - the two
+  trees mean different things, and a promoted file is by definition final.
+
+### The web UI
+
+One change, mapped onto what the gallery already has: beside the existing
+folder filter (workflow identity), a second, smaller control for `group`,
+defaulting to showing everything. A run that used no folders shows exactly
+what it shows today. The job page groups the manifest it already renders
+under the same headings.
+
+The editor's form for a `result` block gains `folder` the way it gains every
+other schema field - from the schema, with no editor-specific work.
+
+### Breaking changes
+
+**None over MCP or REST.** Everything above is additive: a new optional
+workflow field, new keys on existing replies, a new optional query
+parameter. Two things a scripted consumer should know:
+
+1. A manifest file name may now contain a `/` where it previously could not.
+   Anything that assumed a manifest entry was a bare file name - splitting
+   on `/` and taking the last part, or joining it to a directory by hand -
+   keeps working, but a consumer that wants the folder should read the
+   `folder` field rather than parsing the path.
+2. `gallery` entries gain `group`; `folder` keeps its current meaning. A
+   consumer filtering on `folder` sees no change.
+
+## Steering consumers toward it
+
+The ticket is explicit that this only pays off if the MCP consumer uses it,
+and a schema field nobody sets is worth nothing. Four places, in the order
+an agent meets them:
+
+1. **The templates.** Every multi-step template in `workflows/templates/`
+   marks its deliverable step `"folder": "final"` and its scratch steps
+   `"folder": "intermediate"`. This is the one that matters most: agents
+   compose by copying a template, so the convention propagates whether or
+   not anyone reads a description.
+2. **The authoring guide** (`docs/WORKFLOW_GUIDE.md`, the `Authoring a
+   workflow from an agent` section, and its CLAUDE.md mirror) states the
+   two-name convention and the rule: a step whose output the user will be
+   shown is `final`, everything else is `intermediate`.
+3. **Tool descriptions.** `run_workflow` says nothing new (it does not
+   author). `get_job` names the `outputs` grouping, and `save_workflow`'s
+   description states the convention for a workflow being stored for reuse.
+4. **The plugin skills** (`plugins/dw/skills/*`) each state it for their
+   family's templates, which is where a composing agent is already reading.
+
+## What this does not do
+
+- **No nesting policy for the libraries.** The workflow, prompt and asset
+  libraries are untouched.
+- **No automatic classification.** The engine does not guess which step is
+  final. A workflow that says nothing gets today's behaviour, and the
+  reports say `""` rather than inventing an answer.
+- **No retention policy.** "Prune the intermediates, keep the finals" is an
+  obvious next thing to want and is not part of this: it needs a decision
+  about what happens to an `output:` reference pointing into a pruned
+  folder, and that is its own proposal.
+- **No move-after-the-fact.** There is no "mark this output final" call on a
+  finished job. The folder is decided by the workflow, at write time.
+- **No change to file naming.** Names stay
+  `{workflow}-{step}.{i}-{j}.{k}.ext`; the folder is a prefix, not a
+  replacement for the step name in the name.
+
+## Phasing
+
+1. **The engine.** `folder` in the schema and in `Result.save`, path
+   validation against the run directory, `folder` on manifest entries,
+   `strip_run_id` extended. Tests: an unfoldered workflow writes exactly
+   what it writes today; a foldered one lands where it says; `../` is
+   refused; `output:.../latest/final/x.mp4` resolves.
+2. **The server surfaces.** `outputs` grouping on `get_job`, `group` on
+   gallery entries, `?group=` filter, MCP pass-through, docs.
+3. **The steering.** Templates marked up, guide and skills updated, the
+   catalog re-audited so `list_workflows` traits still hold.
+4. **The UI.** The group control on the gallery, grouped manifest on the job
+   page.
+
+Stages 1 and 2 are the ticket; 3 is what makes it used; 4 is what makes it
+visible to a person rather than an agent.
+
+## Open questions
+
+1. **One level, or a path?** The ticket asks for one level deep, "to stay
+   consistent with the workflow and prompt libraries". Those libraries are
+   in fact not one level deep - both walk the tree (`workflow_names`,
+   the prompt library's `prompt:folder/name`) and a name is a relative path
+   of any depth; `templates/minimax/reference-to-video` is a real catalog
+   name with two levels. So consistency with them means *not* enforcing a
+   depth limit. My recommendation: allow a path, validate it, and make the
+   *convention* one level (`final`, `intermediate`) in the templates and the
+   guide - enforcement would be a rule with nothing behind it, and it would
+   block `shots/act-1` on a workflow that wants it. This is the one place
+   where the proposal as written diverges from the ticket, and it is Don's
+   call.
+2. **Should `get_job`'s `outputs` grouping exist at all**, or is the
+   `folder` field on each manifest entry enough? The grouping is
+   redundant-but-cheap; it exists because it answers "what did this
+   produce" in one read, which is the question the ticket is actually
+   about.
+3. **`final` as a default for a one-step workflow?** A `shot`-shape
+   workflow has exactly one output and it is the deliverable. Defaulting it
+   to `final` would make the common case right for free - but it would also
+   mean the same workflow's files move on upgrade, which breaks any stored
+   `output:` reference to them. Recommendation: no default, ever.
diff --git a/docs/proposals/qwen-image-wan-onboarding.md b/docs/proposals/qwen-image-wan-onboarding.md
index 18fe8de2..f351062f 100644
--- a/docs/proposals/qwen-image-wan-onboarding.md
+++ b/docs/proposals/qwen-image-wan-onboarding.md
@@ -97,7 +97,7 @@ plugin skill:
 5. **Cold drill** — for whichever family gets a skill, the same
    plugin-installed-vs-not comparison the H3/LTX-2.5 drill used.
 6. **Ledger** — a row per family in the Part 4 ledger
-   (`docs/proposals/agent-catalog-legibility.md`), since this extends that
+   (`docs/proposals/agent-catalog-legibility-complete.md`), since this extends that
    proposal's catalog rather than opening a new one.
 
 ## What this is not
diff --git a/docs/proposals/scripted-dialogue-and-tts.md b/docs/proposals/scripted-dialogue-and-tts-complete.md
similarity index 98%
rename from docs/proposals/scripted-dialogue-and-tts.md
rename to docs/proposals/scripted-dialogue-and-tts-complete.md
index 1378ca42..83948844 100644
--- a/docs/proposals/scripted-dialogue-and-tts.md
+++ b/docs/proposals/scripted-dialogue-and-tts-complete.md
@@ -106,7 +106,7 @@ reference won.
 Whether this becomes a task, a generator, or stays documentation is decided
 below, in "What was built" — and the reasoning there is now the general case
 for closing any catalog gap like it, recorded in
-[agent-catalog-legibility.md](agent-catalog-legibility.md).
+[agent-catalog-legibility-complete.md](agent-catalog-legibility-complete.md).
 
 ## Suggested next step
 
@@ -143,4 +143,4 @@ documentation and a template workflow rather than code. Revisit a `dw.script`
 generator or an MCP tool once that shape has been used enough by hand to be sure
 of it. This case is now the worked example for the general "format-knowledge
 belongs in guides and templates, not new engine code" rule in
-[agent-catalog-legibility.md](agent-catalog-legibility.md).
+[agent-catalog-legibility-complete.md](agent-catalog-legibility-complete.md).
diff --git a/docs/proposals/server-workspaces.md b/docs/proposals/server-workspaces-complete.md
similarity index 100%
rename from docs/proposals/server-workspaces.md
rename to docs/proposals/server-workspaces-complete.md
diff --git a/docs/superpowers/plans/2026-09-06-catalog-metadata.md b/docs/superpowers/plans/2026-09-06-catalog-metadata.md
index 89e693ba..4cb684cb 100644
--- a/docs/superpowers/plans/2026-09-06-catalog-metadata.md
+++ b/docs/superpowers/plans/2026-09-06-catalog-metadata.md
@@ -12,7 +12,7 @@
 
 **Agent assignment:** each task is tagged `[model: haiku|sonnet|opus]`. Haiku for mechanical edits with exact code given, sonnet for integration work with judgement about existing code, opus for tasks that require reading real templates and deciding. The orchestrator passes the tag as the `model` parameter when dispatching.
 
-**Ledger:** `docs/proposals/agent-catalog-legibility.md` ends with a `## Ledger` table. The last step of every task updates the row(s) it lands, changing `designed` to `done (task N)` and adding anything learned to the notes column. Keep the row on one line.
+**Ledger:** `docs/proposals/agent-catalog-legibility-complete.md` ends with a `## Ledger` table. The last step of every task updates the row(s) it lands, changing `designed` to `done (task N)` and adding anything learned to the notes column. Keep the row on one line.
 
 ## Global Constraints
 
@@ -1069,7 +1069,7 @@ git commit -m "Filter /api/workflows by shape, traits and configures; add the co
 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
 ```
 
-- [ ] **Step 10: Ledger** — in `docs/proposals/agent-catalog-legibility.md`, row `1 shape vocabulary`: change `designed` to `done (tasks 1–4)`. Row `2 \`summary\``: change to `done (tasks 1, 3)`. Commit: `git commit -am "Ledger: shape and summary landed"` with the co-author trailer.
+- [ ] **Step 10: Ledger** — in `docs/proposals/agent-catalog-legibility-complete.md`, row `1 shape vocabulary`: change `designed` to `done (tasks 1–4)`. Row `2 \`summary\``: change to `done (tasks 1, 3)`. Commit: `git commit -am "Ledger: shape and summary landed"` with the co-author trailer.
 
 ---
 
diff --git a/docs/superpowers/plans/2026-09-07-dw-plugin-skills.md b/docs/superpowers/plans/2026-09-07-dw-plugin-skills.md
index bbdef8c3..4d7563eb 100644
--- a/docs/superpowers/plans/2026-09-07-dw-plugin-skills.md
+++ b/docs/superpowers/plans/2026-09-07-dw-plugin-skills.md
@@ -21,7 +21,7 @@
 - Nothing under `dw/`, `dw_mcp/`, `MANIFEST.in` or `pyproject.toml`'s package data changes.
 - Test names and docstrings state the behaviour, matching the suite's style.
 - Commit messages end with `Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>`.
-- Each task appends one sentence to the Part 4 row of the ledger table in `docs/proposals/agent-catalog-legibility.md` (the row beginning `| Part 4 packaging |`, at the end of its last cell before the closing `|`), in the same commit.
+- Each task appends one sentence to the Part 4 row of the ledger table in `docs/proposals/agent-catalog-legibility-complete.md` (the row beginning `| Part 4 packaging |`, at the end of its last cell before the closing `|`), in the same commit.
 - Work on branch `dw-plugin`, cut from `master` at or after 09e36e1.
 
 ---
@@ -40,7 +40,7 @@
 | `workflows/templates/minimax/README.md` | one line pointing at the skill | 2 |
 | `plugins/dw/skills/ltx-2.5/SKILL.md` | the LTX-2.5 composition skill | 3 |
 | `workflows/templates/ltx2/README.md` | one line pointing at the skill | 3 |
-| `docs/proposals/agent-catalog-legibility.md` | ledger row; drill result; the mould for the next family | every task, 4 |
+| `docs/proposals/agent-catalog-legibility-complete.md` | ledger row; drill result; the mould for the next family | every task, 4 |
 
 ---
 
@@ -279,7 +279,7 @@ Expected: marketplace and version tests PASS; `test_there_are_skills` still FAIL
 Append to the Part 4 ledger row: `Plugin task 1: a marketplace at the repo root and the dw plugin under plugins/dw, installable with two commands the README shows; plugin.json's version is the engine's, bumped by release.sh and held by test.`
 
 ```bash
-git add .claude-plugin plugins/dw README.md scripts/release.sh docs/RELEASING.md tests/test_plugin_skills.py docs/proposals/agent-catalog-legibility.md
+git add .claude-plugin plugins/dw README.md scripts/release.sh docs/RELEASING.md tests/test_plugin_skills.py docs/proposals/agent-catalog-legibility-complete.md
 git commit -m "dw plugin scaffold: marketplace, plugin manifest, version lock
 
 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
@@ -506,7 +506,7 @@ Expected: all PASS, including the README link test for the new relative link and
 Append to the Part 4 ledger row: `Plugin task 2: the minimax-h3 skill - shape decision over the family's templates, the frame and canvas rules pinned by test to the diffusers modular pipeline, prompts deferred to MiniMax's h3-prompt-writing skill and the two guides, the run-and-judge loop; the README points at it.`
 
 ```bash
-git add plugins/dw/skills/minimax-h3 workflows/templates/minimax/README.md tests/test_plugin_skills.py docs/proposals/agent-catalog-legibility.md
+git add plugins/dw/skills/minimax-h3 workflows/templates/minimax/README.md tests/test_plugin_skills.py docs/proposals/agent-catalog-legibility-complete.md
 git commit -m "dw plugin: the MiniMax H3 composition skill
 
 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
@@ -721,7 +721,7 @@ Expected: all PASS; both skills under 12288 bytes.
 Append to the Part 4 ledger row: `Plugin task 3: the ltx-2.5 skill - shape decision, the schedule and size rules pinned to the LTX-2 pipeline, the trained caption spec quoted and held equal to the diffusers constant by test; the README points at it.`
 
 ```bash
-git add plugins/dw/skills/ltx-2.5 workflows/templates/ltx2/README.md tests/test_plugin_skills.py docs/proposals/agent-catalog-legibility.md
+git add plugins/dw/skills/ltx-2.5 workflows/templates/ltx2/README.md tests/test_plugin_skills.py docs/proposals/agent-catalog-legibility-complete.md
 git commit -m "dw plugin: the LTX-2.5 composition skill, quoting the trained caption spec
 
 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
@@ -734,7 +734,7 @@ Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
 **Recommended model:** the controlling session, with the user - the drill needs a fresh Claude Code session on the user's machine with the plugin installed, which no subagent can start. Opus for reading the transcripts.
 
 **Files:**
-- Modify: `docs/proposals/agent-catalog-legibility.md` (the ledger row and a `### Plugin drill` section beside the cold-session probe)
+- Modify: `docs/proposals/agent-catalog-legibility-complete.md` (the ledger row and a `### Plugin drill` section beside the cold-session probe)
 
 **Interfaces:**
 - Consumes: the merged branch on lem, restarted (`git checkout master && git pull`, restart `dw.serve --mcp`).
@@ -756,7 +756,7 @@ The transcripts are under `~/.claude/projects/-Users-don-testing-scratch-1/*.jso
 Add a `### Plugin drill, <date>` section after `### Cold-session probe, 2026-09-07` in the proposal with: the two transcript paths, the tool calls in order for each run, which template each chose, whether the prompts came from vendor text, and the verdict. Append to the Part 4 ledger row: `Plugin task 4: cold drill <date> - <pass/fail and one sentence>; the mould for the next family is copy a skill, follow its six sections, add the family's rules to tests/test_plugin_skills.py, cite the vendor, and run this drill (.claude/skills/model-family-onboarding).`
 
 ```bash
-git add docs/proposals/agent-catalog-legibility.md
+git add docs/proposals/agent-catalog-legibility-complete.md
 git commit -m "Plugin drill recorded; the mould for the next model family
 
 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
diff --git a/docs/superpowers/plans/2026-09-07-guides-and-validation.md b/docs/superpowers/plans/2026-09-07-guides-and-validation.md
index fd01e4ad..43b923d1 100644
--- a/docs/superpowers/plans/2026-09-07-guides-and-validation.md
+++ b/docs/superpowers/plans/2026-09-07-guides-and-validation.md
@@ -12,7 +12,7 @@
 
 **Agent assignment:** each task is tagged `[model: haiku|sonnet|opus]`. Haiku for mechanical edits with exact code given, sonnet for integration work with judgement about existing code, opus for prose that has to be right for a reader who cannot ask. The orchestrator passes the tag as the `model` parameter when dispatching.
 
-**Ledger:** `docs/proposals/agent-catalog-legibility.md` ends with a `## Ledger` table. The last step of every task updates the row(s) it lands, changing `designed` to `done (task N)` and adding anything learned to the notes column. Keep the row on one line.
+**Ledger:** `docs/proposals/agent-catalog-legibility-complete.md` ends with a `## Ledger` table. The last step of every task updates the row(s) it lands, changing `designed` to `done (task N)` and adding anything learned to the notes column. Keep the row on one line.
 
 ## Rulings against the spec text
 
@@ -575,7 +575,7 @@ Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
 - Modify: `dw_mcp/server.py` (lines 286–304, the two guide tools)
 - Modify: `tests/test_mcp_guides.py` (replace whole file)
 - Modify: `dw_mcp/CLAUDE.md` (the `guides.py` sentences, ~lines 24–29), `docs/MCP.md` (~lines 196–203)
-- Modify: `docs/proposals/agent-catalog-legibility.md` (ledger row 4)
+- Modify: `docs/proposals/agent-catalog-legibility-complete.md` (ledger row 4)
 
 **Interfaces:**
 - Consumes: Task 2's routes.
@@ -760,7 +760,7 @@ composing one.
 
 - [ ] **Step 7: Ledger**
 
-In `docs/proposals/agent-catalog-legibility.md`, ledger row 4 becomes:
+In `docs/proposals/agent-catalog-legibility-complete.md`, ledger row 4 becomes:
 
 ```
 | 4 server-side guides | done (plan 2, tasks 1–3) | spec §2.1 | `dw/server/guides.py` owns `GUIDES`; `GET /api/guides`, `GET /api/guides/{name}?section=`; `dw_mcp/guides.py` is two proxy calls; payload keys unchanged (`guides`, `content`) so an agent's contract did not move; `dw/docs/` is a `dw.server` build product now in `MANIFEST.in`; supersedes `guides.py`'s "works with the server down" rationale |
@@ -769,7 +769,7 @@ In `docs/proposals/agent-catalog-legibility.md`, ledger row 4 becomes:
 - [ ] **Step 8: Commit**
 
 ```bash
-git add dw_mcp/guides.py dw_mcp/server.py tests/test_mcp_guides.py dw_mcp/CLAUDE.md docs/MCP.md docs/proposals/agent-catalog-legibility.md
+git add dw_mcp/guides.py dw_mcp/server.py tests/test_mcp_guides.py dw_mcp/CLAUDE.md docs/MCP.md docs/proposals/agent-catalog-legibility-complete.md
 git commit -m "mcp: list_guides and get_guide proxy the engine's /api/guides
 
 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
@@ -994,7 +994,7 @@ Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
 - Modify: `ui/src/lib/types.ts` (`ValidationResult`, line 153)
 - Modify: `docs/SERVER.md` (~line 186), `docs/MCP.md` (the `validate_workflow` row)
 - Modify: `tests/test_workflow.py` (append), `tests/test_server.py` (append), `tests/test_mcp_authoring.py` (one scripted body)
-- Modify: `docs/proposals/agent-catalog-legibility.md` (ledger row 8)
+- Modify: `docs/proposals/agent-catalog-legibility-complete.md` (ledger row 8)
 
 **Interfaces:**
 - Consumes: Task 4's `validate_data_all`, `format_validation_errors`.
@@ -1166,7 +1166,7 @@ Row 8 becomes:
 - [ ] **Step 8: Commit**
 
 ```bash
-git add dw/workflow.py dw/server/app.py dw_mcp/server.py ui/src/lib/types.ts docs/SERVER.md docs/MCP.md tests/test_workflow.py tests/test_server.py tests/test_mcp_authoring.py docs/proposals/agent-catalog-legibility.md
+git add dw/workflow.py dw/server/app.py dw_mcp/server.py ui/src/lib/types.ts docs/SERVER.md docs/MCP.md tests/test_workflow.py tests/test_server.py tests/test_mcp_authoring.py docs/proposals/agent-catalog-legibility-complete.md
 git commit -m "validate: report every schema error at once, from the CLI to /api/validate
 
 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
@@ -1180,7 +1180,7 @@ Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
 - Modify: `docs/WORKFLOW_GUIDE.md` (new top-level section, placed after `## Cross-Step Data Flow`, before `## Result Configuration`)
 - Modify: `CLAUDE.md` (one pointer line under `### Type System`)
 - Modify: `tests/test_server_guides.py` (append to `TestTheRealDocs`)
-- Modify: `docs/proposals/agent-catalog-legibility.md` (ledger rows 7 and 9)
+- Modify: `docs/proposals/agent-catalog-legibility-complete.md` (ledger rows 7 and 9)
 
 **Interfaces:**
 - Consumes: Task 1's `get_guide` over the real docs.
@@ -1272,13 +1272,13 @@ Rows 7 and 9 become:
 
 ```
 | 7 authoring guide | done (plan 2, task 6) | spec §2.3 | `## Authoring a workflow from an agent` in `WORKFLOW_GUIDE.md`, reachable as one `get_guide` section; `CLAUDE.md` points at it; a test checks every reserved prefix is explained there |
-| 9 composition rules | done (plan 2, task 6) | spec §2.3 | the cartesian rule and the one-step-per-pair form are stated in the authoring section, the general case of `scripted-dialogue-and-tts.md`'s reasoning |
+| 9 composition rules | done (plan 2, task 6) | spec §2.3 | the cartesian rule and the one-step-per-pair form are stated in the authoring section, the general case of `scripted-dialogue-and-tts-complete.md`'s reasoning |
 ```
 
 - [ ] **Step 7: Commit**
 
 ```bash
-git add docs/WORKFLOW_GUIDE.md CLAUDE.md tests/test_server_guides.py docs/proposals/agent-catalog-legibility.md
+git add docs/WORKFLOW_GUIDE.md CLAUDE.md tests/test_server_guides.py docs/proposals/agent-catalog-legibility-complete.md
 git commit -m "docs: authoring a workflow from an agent - references, types, the cartesian rule, the loop
 
 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
diff --git a/docs/superpowers/plans/2026-09-07-ltx-h3-catalog-repair.md b/docs/superpowers/plans/2026-09-07-ltx-h3-catalog-repair.md
index aab26858..7673e888 100644
--- a/docs/superpowers/plans/2026-09-07-ltx-h3-catalog-repair.md
+++ b/docs/superpowers/plans/2026-09-07-ltx-h3-catalog-repair.md
@@ -18,7 +18,7 @@
 - A template's `description` may not mention a variable or step in single quotes that the workflow does not have (`test_catalog_structure.py` drift check).
 - Every test file docstring and every test name states the behaviour, not the mechanism, matching the existing suite's style.
 - Commit messages end with `Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>`.
-- Each task appends to the Part 4 row of the ledger table in `docs/proposals/agent-catalog-legibility.md` (the row beginning `| Part 4 packaging |`), one sentence per task, in the same commit as the change.
+- Each task appends to the Part 4 row of the ledger table in `docs/proposals/agent-catalog-legibility-complete.md` (the row beginning `| Part 4 packaging |`), one sentence per task, in the same commit as the change.
 - Work on branch `catalog-repair`, cut from `master` after PR #49 has merged. Do not start it from `agent-legibility`.
 
 ---
@@ -37,7 +37,7 @@
 | `dw/workflows/h3_context_ir.json` | system prompt corrections | 4 |
 | `tests/test_h3_context_ir.py` | the corrections are present, the removed lines absent | 4 |
 | `workflows/templates/minimax/README.md`, `workflows/templates/ltx2/README.md` | links, vendor sources, model facts | 5 |
-| `docs/proposals/agent-catalog-legibility.md` | ledger row and dated follow-ups | every task, 6 |
+| `docs/proposals/agent-catalog-legibility-complete.md` | ledger row and dated follow-ups | every task, 6 |
 
 ---
 
@@ -110,7 +110,7 @@ If it FAILS: the failure names what the engine cannot do. Do not patch around it
 Append to the Part 4 ledger row: `Catalog repair task 1: the latent handoff a two-stage flow needs is proven by test (tests/test_result.py::TestLatentHandoff), no engine change.`
 
 ```bash
-git add tests/test_result.py docs/proposals/agent-catalog-legibility.md
+git add tests/test_result.py docs/proposals/agent-catalog-legibility-complete.md
 git commit -m "test: a latent pipeline output hands each tensor to the next step by name
 
 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
@@ -524,7 +524,7 @@ and in the `**Examples:**` line change `(base -> latent upsample -> mux)` to `(b
 Append to the Part 4 ledger row: `Catalog repair task 2: two-stage.json is the three-move flow (8 sigmas at 768x448, 2x latent upsample, renoise + 3 stage-two sigmas at 1536x896, audio latents carried); latents pass by name; a test holds noise_scale to STAGE_2_DISTILLED_SIGMA_VALUES[0]. Cost and the sharpness comparison await the lem run (task 7).`
 
 ```bash
-git add workflows/templates/ltx2/two-stage.json tests/test_catalog_structure.py docs/RECIPES_24GB.md docs/proposals/agent-catalog-legibility.md
+git add workflows/templates/ltx2/two-stage.json tests/test_catalog_structure.py docs/RECIPES_24GB.md docs/proposals/agent-catalog-legibility-complete.md
 git commit -m "LTX-2.5 two-stage template runs the stage-two refine pass it was missing
 
 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
@@ -661,7 +661,7 @@ Expected: all PASS.
 Append to the Part 4 ledger row: `Catalog repair task 3: the six prompts/ltx2 captions are rewritten to the trained format (one paragraph, 150-220 words, shot type/camera motion/viewpoint in prose, sound interleaved; the two I2V ones describe only what changes), intended_model ltx-2.5, four summaries say LTX-2.5; tests/test_ltx_prompt_library.py holds the shape.`
 
 ```bash
-git add prompts/ltx2 workflows/templates/ltx2 tests/test_ltx_prompt_library.py docs/proposals/agent-catalog-legibility.md
+git add prompts/ltx2 workflows/templates/ltx2 tests/test_ltx_prompt_library.py docs/proposals/agent-catalog-legibility-complete.md
 git commit -m "LTX-2.5 prompt library rewritten in the caption format the model was trained on
 
 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
@@ -840,7 +840,7 @@ Expected: the diff touches only the `system_prompt` line; validate passes; all t
 Append to the Part 4 ledger row: `Catalog repair task 4: h3_context_ir names its two source guides, writes N/A for silent audio fields, numbers <Video N>/<Audio N> within their category, labels continuity modes as this engine's chaining convention (nothing in the engine emits the phrase; it is a user-message convention), adds the ref guide's dialogue-fidelity rules, drops the two unsourced lines; tests/test_h3_context_ir.py.`
 
 ```bash
-git add dw/workflows/h3_context_ir.json tests/test_h3_context_ir.py docs/proposals/agent-catalog-legibility.md
+git add dw/workflows/h3_context_ir.json tests/test_h3_context_ir.py docs/proposals/agent-catalog-legibility-complete.md
 git commit -m "H3 Context-IR builtin corrected against MiniMax's prompt-writing guides
 
 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
@@ -999,7 +999,7 @@ Expected: PASS, including `test_every_readme_link_resolves` for both files. Also
 Append to the Part 4 ledger row: `Catalog repair task 5: both template READMEs link the files that exist, name the vendor sources and the audit, the H3 one states the canvas rules and the 5-second diffusers floor; a test resolves every README link.`
 
 ```bash
-git add workflows/templates/minimax/README.md workflows/templates/ltx2/README.md tests/test_catalog_structure.py docs/proposals/agent-catalog-legibility.md
+git add workflows/templates/minimax/README.md workflows/templates/ltx2/README.md tests/test_catalog_structure.py docs/proposals/agent-catalog-legibility-complete.md
 git commit -m "Template READMEs: links that resolve, vendor sources named, H3 canvas rules stated
 
 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
@@ -1012,7 +1012,7 @@ Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
 **Recommended model:** sonnet — a transcription from the two audits' "Missing knowledge" sections.
 
 **Files:**
-- Modify: `docs/proposals/agent-catalog-legibility.md`
+- Modify: `docs/proposals/agent-catalog-legibility-complete.md`
 
 **Interfaces:**
 - Consumes: both audits' "Missing knowledge" sections.
@@ -1065,7 +1065,7 @@ MiniMax H3 ([audit](audits/2026-09-07-minimax-h3-audit.md)):
 - [ ] **Step 2: Commit**
 
 ```bash
-git add docs/proposals/agent-catalog-legibility.md
+git add docs/proposals/agent-catalog-legibility-complete.md
 git commit -m "Ledger: dated model-knowledge follow-ups from the H3 and LTX-2.5 audits
 
 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
@@ -1078,7 +1078,7 @@ Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
 **Recommended model:** this is run by the controlling session (it needs the dw MCP connection to lem and a human go-ahead for GPU minutes), not a subagent. Opus.
 
 **Files:**
-- Modify: `workflows/templates/ltx2/two-stage.json` (`cost`), `docs/RECIPES_24GB.md` (only if the comparison supports a sharpness sentence), `docs/proposals/agent-catalog-legibility.md`
+- Modify: `workflows/templates/ltx2/two-stage.json` (`cost`), `docs/RECIPES_24GB.md` (only if the comparison supports a sharpness sentence), `docs/proposals/agent-catalog-legibility-complete.md`
 
 **Interfaces:**
 - Consumes: Tasks 2 to 5 merged into the branch; lem checked out on the branch and `dw.serve` restarted (the builtin and the JSON are read at start or per run respectively, and a restart makes both certain).
@@ -1123,7 +1123,7 @@ If the comparison in Step 2 showed the refine pass sharper, add to the RECIPES p
 Append to the Part 4 ledger row: `Catalog repair task 7: verified on lem <date>: two-stage <minutes> warm min at 1536x896 (<sharper / not sharper> than upsample-only at seed 42); fox and hummingbird captions run as written; the silent-candle brief produced N/A for both audio fields<, after N tries>.`
 
 ```bash
-git add workflows/templates/ltx2/two-stage.json docs/RECIPES_24GB.md docs/proposals/agent-catalog-legibility.md
+git add workflows/templates/ltx2/two-stage.json docs/RECIPES_24GB.md docs/proposals/agent-catalog-legibility-complete.md
 git commit -m "Two-stage cost measured on lem; lem verification of the catalog repair recorded
 
 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
diff --git a/docs/superpowers/plans/2026-09-11-list-driven-stage-3.md b/docs/superpowers/plans/2026-09-11-list-driven-stage-3.md
new file mode 100644
index 00000000..25708a89
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-11-list-driven-stage-3.md
@@ -0,0 +1,860 @@
+# List-driven steps stage 3 (cost and entry shape) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Tell an agent composing over MCP what an entry of a list-driven template must contain and what a run over its own list costs, and settle the three engine questions stage 2 left open.
+
+**Architecture:** The fields an entry needs are derived from the `item:` references the `for_each` steps make (`list_fields` in `dw/for_each.py`), and surface as a `lists` block in the catalog listing and as an unknown-key warning in validation — one computation used twice. Cost stays measured: a `cost` entry gains an optional `per_entry` block, passed through the listing unchanged; the skill and the guide quote `fixed + per_entry × N`. The variables endpoint previews inside list entries. Rulings: an empty `for_each` list is an error, `expanded_definition` realizes constants, the step cache bound rises to 128. The editor's flow view learns `gather:` and `from_previous_result` edges.
+
+**Tech Stack:** Python 3.10, pytest, JSON schema, FastAPI routes, TypeScript + vitest for `ui/`.
+
+**Spec:** `docs/proposals/list-driven-steps-complete.md` — "Stage 3: cost and entry shape (design)".
+
+## Global Constraints
+
+- Full suite green before every commit that touches `dw/`, `dw_mcp/` or `tests/`: `python -m pytest -q -x tests/` (baseline on `develop` at 9cc4e7c: 3555 passed, 5 skipped). `black --check dw dw_mcp tests` clean (CI runs it).
+- Catalog rules from `docs/superpowers/specs/2026-09-06-agent-catalog-legibility-design.md`: cost is measured, never derived; structure is derived from the raw definition, never declared twice. `derive_catalog_metadata` reads raw JSON only — no variable substitution, no type loading.
+- The catalog pins for the two templates hold unchanged (`tests/test_catalog_structure.py` `EXPECTED_SHAPES`, `COSTED`). No template gets a `per_entry` block in this plan — the numbers come from a GPU run the user makes later; the code and tests must be correct with `per_entry` absent.
+- `plugins/dw/skills/minimax-h3/SKILL.md` stays ≤ 12288 bytes (it is at 12063).
+- Security rules in CLAUDE.md. No new filesystem access outside the validators.
+- `ui/` changes pass `npm run check`, `npm run lint`, `npm run format` (prettier writes; commit the result) and `npm test` from `ui/`.
+- Commit trailer on every commit: `Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>`.
+- Docs that must move together (CLAUDE.md says so): the Type System bullets in `CLAUDE.md` and the "Authoring a workflow from an agent" section of `docs/WORKFLOW_GUIDE.md`.
+
+---
+
+### Task 1: `list_fields` and the catalog's `lists` block
+
+**Files:**
+- Modify: `dw/for_each.py` (add `list_fields`)
+- Modify: `dw/server/catalog_shape.py` (`derive_catalog_metadata` returns `lists`; `COMPACT_FIELDS` gains `"lists"`; `project_listing` drops an empty `lists` in the compact view)
+- Modify: `dw/server/app.py:194-262` (`workflow_details` carries `lists`; the fallback detail has `"lists": {}`)
+- Test: `tests/test_for_each.py`, `tests/test_catalog_shape.py`, `tests/test_server.py` (near `test_workflow_details_name_their_variables`, ~line 2997)
+
+**Interfaces:**
+- Produces: `list_fields(definition) -> dict` in `dw/for_each.py`. For every step whose `for_each` is a string `variable:<name>`, keyed by `<name>`: `{"fields": [...] | None, "steps": [step names in order]}`. `fields` is the sorted union of `<field>` over every `item:<field>` string found anywhere in those steps, with `"name"` first; when any of those steps uses bare `item:` (the whole entry) `fields` is `None`. A step whose `for_each` is a literal list is not a list argument and is skipped. Non-dict steps and a missing/malformed `steps` yield `{}`. Reads raw JSON, no substitution.
+- Produces: `derive_catalog_metadata(definition)["lists"]` — `list_fields` plus `"entries": len(default)` when `variables[name]` is a list, else `None`. Listing entries carry `lists`; compact view includes it only when non-empty.
+
+- [ ] **Step 1: Write the failing tests for `list_fields`**
+
+Append to `tests/test_for_each.py`:
+
+```python
+class TestListFields:
+    """What an entry has to carry is read off the item: references the
+    for_each steps make - the catalog and the unknown-key warning both
+    derive from this."""
+
+    def test_fields_are_the_item_references_with_name_first(self):
+        fields = list_fields(
+            definition(
+                {
+                    "name": "slice",
+                    "for_each": "variable:shots",
+                    "task": {"arguments": {"start_frame": "item:start_frame"}},
+                },
+                {
+                    "name": "shot",
+                    "for_each": "variable:shots",
+                    "pipeline": {
+                        "arguments": {
+                            "prompt": "item:prompt",
+                            "references": [{"x": "item:references"}],
+                        }
+                    },
+                },
+            )
+        )
+        assert fields == {
+            "shots": {
+                "fields": ["name", "prompt", "references", "start_frame"],
+                "steps": ["slice", "shot"],
+            }
+        }
+
+    def test_a_bare_item_means_the_entry_is_a_value(self):
+        fields = list_fields(
+            definition(
+                {"name": "say", "for_each": "variable:lines", "task": {"arguments": {"text": "item:"}}}
+            )
+        )
+        assert fields == {"lines": {"fields": None, "steps": ["say"]}}
+
+    def test_a_literal_list_is_not_an_argument(self):
+        assert list_fields(definition({"name": "s", "for_each": ["a"], "task": {}})) == {}
+
+    def test_a_step_reading_no_field_still_lists_name(self):
+        fields = list_fields(
+            definition({"name": "s", "for_each": "variable:xs", "task": {"arguments": {}}})
+        )
+        assert fields == {"xs": {"fields": ["name"], "steps": ["s"]}}
+
+    def test_malformed_definitions_yield_nothing(self):
+        assert list_fields({}) == {}
+        assert list_fields({"steps": "nope"}) == {}
+        assert list_fields({"steps": ["not a dict"]}) == {}
+```
+
+Add `list_fields` to the `from dw.for_each import (...)` at the top of the file.
+
+- [ ] **Step 2: Run to verify they fail**
+
+Run: `python -m pytest -q tests/test_for_each.py -k ListFields`
+Expected: ImportError on `list_fields`.
+
+- [ ] **Step 3: Implement `list_fields`**
+
+In `dw/for_each.py`, after `render_path`:
+
+```python
+def list_fields(definition):
+    """What an entry of each list-driven variable has to carry, read off
+    the definition: for every step whose for_each is 'variable:<name>',
+    the fields its 'item:<field>' references name.
+
+    Returns {<variable>: {"fields": [...] or None, "steps": [...]}} -
+    fields sorted with 'name' first, or None when a step splices the
+    whole entry with a bare 'item:' (the entries are values, not
+    objects). A literal for_each list is not an argument and is skipped.
+    Reads the raw definition, no substitution, so the catalog and the
+    validator derive the same answer from the file as written.
+    """
+    steps = definition.get("steps") if isinstance(definition, dict) else None
+    if not isinstance(steps, list):
+        return {}
+    found = {}
+    for step in steps:
+        if not isinstance(step, dict):
+            continue
+        target = step.get(FOR_EACH_KEY)
+        if not (isinstance(target, str) and target.startswith("variable:")):
+            continue
+        variable = target.removeprefix("variable:")
+        entry = found.setdefault(variable, {"fields": set(), "steps": []})
+        entry["steps"].append(step.get("name"))
+        for value in _strings(step):
+            if not value.startswith(ITEM_PREFIX):
+                continue
+            field = value[len(ITEM_PREFIX) :]
+            if field == "":
+                entry["fields"] = None
+            elif entry["fields"] is not None:
+                entry["fields"].add(field)
+    return {
+        variable: {
+            "fields": (
+                None
+                if entry["fields"] is None
+                else ["name"] + sorted(entry["fields"] - {"name"})
+            ),
+            "steps": entry["steps"],
+        }
+        for variable, entry in found.items()
+    }
+
+
+def _strings(value):
+    """Every string anywhere inside a JSON value, except the for_each key
+    itself."""
+    if isinstance(value, str):
+        yield value
+    elif isinstance(value, list):
+        for item in value:
+            yield from _strings(item)
+    elif isinstance(value, dict):
+        for key, item in value.items():
+            if key != FOR_EACH_KEY:
+                yield from _strings(item)
+```
+
+- [ ] **Step 4: Run the tests**
+
+Run: `python -m pytest -q tests/test_for_each.py -k ListFields`
+Expected: PASS.
+
+- [ ] **Step 5: Write the failing catalog tests**
+
+Append to `tests/test_catalog_shape.py`:
+
+```python
+def for_each_step(name, variable, arguments):
+    return {
+        "name": name,
+        "for_each": f"variable:{variable}",
+        "pipeline": {
+            "configuration": {"component_type": "{Fake}"},
+            "arguments": arguments,
+        },
+        "result": {"content_type": "video/mp4"},
+    }
+
+
+def test_lists_name_the_fields_an_entry_takes_and_the_default_length():
+    meta = derive_catalog_metadata(
+        definition(
+            for_each_step("shot", "shots", {"prompt": "item:prompt", "n": "item:num_frames"}),
+            variables={"shots": [{"name": "a", "prompt": "p", "num_frames": 1}] * 3},
+        )
+    )
+    assert meta["lists"] == {
+        "shots": {
+            "fields": ["name", "num_frames", "prompt"],
+            "steps": ["shot"],
+            "entries": 3,
+        }
+    }
+
+
+def test_lists_is_empty_without_for_each_and_entries_is_none_without_a_list_default():
+    assert derive_catalog_metadata(definition(pipeline_step("g", "image/jpeg")))["lists"] == {}
+    meta = derive_catalog_metadata(
+        definition(for_each_step("shot", "shots", {"prompt": "item:prompt"}))
+    )
+    assert meta["lists"]["shots"]["entries"] is None
+
+
+def test_compact_carries_lists_only_when_there_are_any():
+    listing = {
+        "plain": entry("image"),
+        "cut": entry(
+            "sequence",
+            lists={"shots": {"fields": ["name", "prompt"], "steps": ["shot"], "entries": 2}},
+        ),
+    }
+    compact = project_listing(listing, view="compact")
+    assert "lists" not in compact["plain"]
+    assert compact["cut"]["lists"]["shots"]["fields"] == ["name", "prompt"]
+```
+
+Change the `entry()` helper to include `"lists": {}` in its base dict, and change `test_compact_drops_prose_and_model_configs_and_keeps_user_workflows` to `assert set(compact["templates/tti"]) == set(COMPACT_FIELDS) - {"configures", "lists"}`.
+
+Append to `tests/test_server.py` next to `test_workflow_details_name_their_variables` (read that test first and reuse its fixtures; it writes a workflow into the server's workflow dir and reads `GET /api/workflows`):
+
+```python
+def test_workflow_details_describe_their_lists(server):
+    """A list-driven workflow's listing says what an entry carries, so an
+    agent can write the list without opening the definition."""
+    client, workflow_dir = server  # match the fixture shape the neighbour uses
+    write_workflow(
+        workflow_dir,
+        "cut.json",
+        {
+            "id": "cut",
+            "variables": {"shots": [{"name": "a", "prompt": "p"}, {"name": "b", "prompt": "q"}]},
+            "steps": [
+                {
+                    "name": "shot",
+                    "for_each": "variable:shots",
+                    "task": {"command": "noop", "arguments": {"text": "item:prompt"}},
+                }
+            ],
+        },
+    )
+    details = client.get("/api/workflows").json()["details"]["cut"]
+    assert details["lists"] == {
+        "shots": {"fields": ["name", "prompt"], "steps": ["shot"], "entries": 2}
+    }
+    compact = client.get("/api/workflows", params={"view": "compact"}).json()
+    assert compact["details"]["cut"]["lists"]["shots"]["entries"] == 2
+```
+
+Adapt the fixture usage and the response shape to what the neighbouring test actually does — read it before writing; the assertions above are the contract, the plumbing is the file's.
+
+- [ ] **Step 6: Run to verify they fail**
+
+Run: `python -m pytest -q tests/test_catalog_shape.py tests/test_server.py -k "lists"`
+Expected: KeyError on `lists`.
+
+- [ ] **Step 7: Implement the catalog side**
+
+`dw/server/catalog_shape.py`: import `from ..for_each import list_fields` (it is a pure function; the module docstring's "reads the raw JSON only" still holds). In `derive_catalog_metadata`, before the return:
+
+```python
+    variables = definition.get("variables")
+    variables = variables if isinstance(variables, dict) else {}
+    lists = {
+        name: {
+            **fields,
+            "entries": (
+                len(variables[name]) if isinstance(variables.get(name), list) else None
+            ),
+        }
+        for name, fields in list_fields(definition).items()
+    }
+```
+
+and add `"lists": lists` to the returned dict; update the docstring ("Returns {shape, traits, summary, summary_truncated, lists, declared}" and one sentence on `lists`).
+
+`COMPACT_FIELDS` gains `"lists"` after `"variable_names"`. In `project_listing`, replace the `configures` special case with a set:
+
+```python
+# Carried in the compact view only when set: a template has no
+# `configures`, and most workflows have no list-driven step
+_COMPACT_WHEN_SET = frozenset({"configures", "lists"})
+...
+            slim = {
+                key: detail.get(key)
+                for key in COMPACT_FIELDS
+                if key not in _COMPACT_WHEN_SET or detail.get(key)
+            }
+```
+
+`dw/server/app.py` `workflow_details`: add `"lists": metadata["lists"],` to `detail` and `"lists": {},` to the fallback detail. Also update the docstring of `workflow_details` (one clause: "and, for a list-driven workflow, what an entry of each list carries").
+
+- [ ] **Step 8: Run the tests, then the full suite**
+
+Run: `python -m pytest -q tests/test_catalog_shape.py tests/test_server.py tests/test_for_each.py tests/test_mcp_catalog.py` then `python -m pytest -q -x tests/`
+Expected: PASS. If a test elsewhere pins the exact key set of a listing entry or of `COMPACT_FIELDS`, update it to include `lists` and say so in the report.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add dw/for_each.py dw/server/catalog_shape.py dw/server/app.py tests/test_for_each.py tests/test_catalog_shape.py tests/test_server.py
+git commit -m "feat(catalog): a listing names the fields an entry of each for_each list carries
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 2: An entry key no step reads is a validation warning
+
+**Files:**
+- Modify: `dw/for_each.py` (add `entry_field_warnings`)
+- Modify: `dw/server/app.py` (the `validate_workflow` route, where `answer["warnings"]` is built, ~line 1345)
+- Test: `tests/test_for_each.py`, `tests/test_validate_arguments.py`
+
+**Interfaces:**
+- Consumes: `list_fields` (Task 1), `set_variables`, `argument_errors` (`dw/variables.py`).
+- Produces: `entry_field_warnings(definition, arguments=None) -> list[str]`. Folds good `arguments` into a copy of the declared variables (exactly as `expanded_definition` does), then for each list-driven variable whose value is a list of dicts, reports every key of every entry that is not in that list's fields (and not `name`), one warning per entry, in the style of `workflow_argument_warnings`: `"arguments.shots[1]: entry 'deflect' carries 'num_frame', which no step reads; entries of 'shots' take: name, num_frames, prompt, references"` — `arguments.` when the caller supplied that variable, `variables.` otherwise. Lists whose `fields` is `None` (value entries) produce no warnings. Never raises: a malformed value is skipped.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/test_for_each.py`:
+
+```python
+class TestEntryFieldWarnings:
+    def workflow(self):
+        return definition(
+            {
+                "name": "shot",
+                "for_each": "variable:shots",
+                "task": {"arguments": {"text": "item:prompt", "n": "item:num_frames"}},
+            },
+            variables={"shots": [{"name": "a", "prompt": "p", "num_frames": 1}]},
+        )
+
+    def test_a_key_no_step_reads_is_reported_at_the_entry(self):
+        w = self.workflow()
+        w["variables"]["shots"].append({"name": "b", "prompt": "q", "num_frame": 2})
+        assert entry_field_warnings(w) == [
+            "variables.shots[1]: entry 'b' carries 'num_frame', which no step reads; "
+            "entries of 'shots' take: name, num_frames, prompt"
+        ]
+
+    def test_a_caller_s_list_is_reported_under_arguments(self):
+        warnings = entry_field_warnings(
+            self.workflow(),
+            arguments={"shots": [{"name": "a", "prompt": "p", "num_frames": 1, "note": "x"}]},
+        )
+        assert warnings == [
+            "arguments.shots[0]: entry 'a' carries 'note', which no step reads; "
+            "entries of 'shots' take: name, num_frames, prompt"
+        ]
+
+    def test_bad_arguments_fall_back_to_the_defaults(self):
+        assert entry_field_warnings(self.workflow(), arguments={"nope": 1}) == []
+
+    def test_value_entries_and_clean_entries_warn_about_nothing(self):
+        assert entry_field_warnings(self.workflow()) == []
+        w = definition(
+            {"name": "say", "for_each": "variable:lines", "task": {"arguments": {"t": "item:"}}},
+            variables={"lines": ["a", "b"]},
+        )
+        assert entry_field_warnings(w) == []
+
+    def test_an_entry_without_a_name_is_named_by_its_index(self):
+        w = self.workflow()
+        w["variables"]["shots"] = [{"prompt": "p", "num_frames": 1, "extra": 0}]
+        assert entry_field_warnings(w)[0].startswith(
+            "variables.shots[0]: entry 0 carries 'extra'"
+        )
+```
+
+Import `entry_field_warnings` at the top.
+
+- [ ] **Step 2: Run to verify they fail**
+
+Run: `python -m pytest -q tests/test_for_each.py -k EntryFieldWarnings` — ImportError.
+
+- [ ] **Step 3: Implement**
+
+In `dw/for_each.py` after `list_fields` (import `copy` is already there; add `from .variables import argument_errors, set_variables` — `dw/variables.py` imports nothing from this module, so there is no cycle; verify with `python -c "import dw.for_each"`):
+
+```python
+def entry_field_warnings(definition, arguments=None):
+    """Every entry key of a list-driven variable that no step reads.
+
+    A caller who writes 'num_frame' for 'num_frames' gets the template's
+    value for the field they meant to set, in silence; this names the
+    key, at the entry it sits in, with the fields the list takes. A
+    warning rather than an error: an entry may carry a note on purpose.
+    Good `arguments` are folded in first, and a list the caller supplied
+    is reported under 'arguments.', where they wrote it.
+    """
+    if not isinstance(definition, dict):
+        return []
+    variables = definition.get("variables")
+    if not isinstance(variables, dict):
+        return []
+    variables = copy.deepcopy(variables)
+    supplied = set()
+    if arguments and not argument_errors(definition, arguments):
+        set_variables(arguments, variables)
+        supplied = set(arguments)
+    warnings = []
+    for variable, spec in list_fields(definition).items():
+        fields = spec["fields"]
+        entries = variables.get(variable)
+        if fields is None or not isinstance(entries, list):
+            continue
+        where = "arguments" if variable in supplied else "variables"
+        for index, entry in enumerate(entries):
+            if not isinstance(entry, dict):
+                continue
+            unknown = sorted(set(entry) - set(fields))
+            if not unknown:
+                continue
+            label = repr(entry["name"]) if isinstance(entry.get("name"), str) else index
+            warnings.append(
+                f"{where}.{variable}[{index}]: entry {label} carries "
+                f"{', '.join(repr(k) for k in unknown)}, which no step reads; "
+                f"entries of '{variable}' take: {', '.join(fields)}"
+            )
+    return warnings
+```
+
+- [ ] **Step 4: Run the tests**
+
+Run: `python -m pytest -q tests/test_for_each.py -k EntryFieldWarnings` — PASS.
+
+- [ ] **Step 5: Write the failing server test**
+
+In `tests/test_validate_arguments.py` (read its fixtures: it posts to `/api/validate` with a workflow and arguments), add:
+
+```python
+def test_an_entry_key_no_step_reads_is_a_warning_not_an_error(client_and_workspace):
+    client, _ = client_and_workspace  # adapt to the file's fixture
+    workflow = {
+        "id": "cut",
+        "variables": {"shots": [{"name": "a", "text": "p"}]},
+        "steps": [
+            {
+                "name": "shot",
+                "for_each": "variable:shots",
+                "task": {"command": "noop", "arguments": {"text": "item:text"}},
+            }
+        ],
+    }
+    response = client.post(
+        "/api/validate",
+        json={"workflow": workflow, "arguments": {"shots": [{"name": "a", "text": "p", "txt": "q"}]}},
+    )
+    body = response.json()
+    assert body["valid"] is True
+    assert any(w.startswith("arguments.shots[0]: entry 'a' carries 'txt'") for w in body["warnings"])
+```
+
+Use whatever `task` command the file's other tests use for a no-op step so the schema and the task registry accept it.
+
+- [ ] **Step 6: Hook it in**
+
+`dw/server/app.py` `validate_workflow`: import `entry_field_warnings` from `..for_each`; where `answer` is built, make it
+
+```python
+        answer = {
+            "valid": True,
+            "error": None,
+            "errors": [],
+            "warnings": workflow_argument_warnings(definition)
+            + entry_field_warnings(definition, request.arguments),
+        }
+```
+
+- [ ] **Step 7: Run tests, full suite, commit**
+
+Run: `python -m pytest -q tests/test_validate_arguments.py tests/test_for_each.py` then the full suite.
+
+```bash
+git add dw/for_each.py dw/server/app.py tests/test_for_each.py tests/test_validate_arguments.py
+git commit -m "feat(validate): an entry key no for_each step reads is a warning at the entry's path
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: `per_entry` cost and the nested variables preview
+
+**Files:**
+- Modify: `dw/workflow_schema.json` (the `cost` items schema, ~line 36-50)
+- Modify: `dw/server/app.py` (`get_workflow_variables`, ~line 1588-1630)
+- Modify: `dw_mcp/catalog.py:31-42` (docstring), `docs/MCP.md` (`get_workflow` and `list_workflows` rows, ~lines 215-216), `docs/SERVER.md` (~line 274)
+- Test: `tests/test_catalog_shape.py`, `tests/test_catalog_structure.py`, `tests/test_server.py` (`test_workflow_variables_answer_without_the_whole_definition`, ~line 1139)
+
+**Interfaces:**
+- Produces: schema — `cost[].per_entry` optional object `{variable: string, minutes: number ≥ 0, entries: integer ≥ 1}`, all three required, `additionalProperties: false`. Catalog tests — for every bundled workflow with a `per_entry`, `variable` is a key of `list_fields(definition)` and `entries == len(variables[variable])`. Variables endpoint — the 200-character preview applies to strings inside list/dict values too, `truncated` naming them as `shots[0].prompt`.
+
+- [ ] **Step 1: Write the failing tests**
+
+`tests/test_catalog_shape.py`, extend `test_the_schema_declares_the_vocabulary`:
+
+```python
+    per_entry = cost_item["properties"]["per_entry"]
+    assert set(per_entry["required"]) == {"variable", "minutes", "entries"}
+    assert per_entry["additionalProperties"] is False
+```
+
+and add:
+
+```python
+def test_a_per_entry_cost_validates_and_a_partial_one_does_not():
+    schema = load_schema("workflow")
+    base = definition(pipeline_step("g", "image/jpeg"))
+    cost = {"device": "cuda", "vram_gb": 24, "minutes": 42}
+    ok, _ = validate_data(
+        {**base, "cost": [{**cost, "per_entry": {"variable": "shots", "minutes": 7.2, "entries": 5}}]},
+        schema,
+    )
+    assert ok
+    bad, message = validate_data(
+        {**base, "cost": [{**cost, "per_entry": {"variable": "shots", "minutes": 7.2}}]}, schema
+    )
+    assert not bad and "per_entry" in message
+```
+
+`tests/test_catalog_structure.py`, next to `test_a_declared_cost_is_well_formed` (same parametrization over every bundled workflow):
+
+```python
+@pytest.mark.parametrize("path", WORKFLOWS)  # whatever name the file uses
+def test_a_per_entry_cost_names_a_list_the_steps_read(path):
+    """per_entry is measured over the default list, so the variable it
+    names must be one a for_each expands and `entries` must be that
+    list's length - an edited default that forgot the cost block fails
+    here."""
+    from dw.for_each import list_fields
+
+    definition = load(path)
+    for entry in definition.get("cost") or []:
+        per_entry = entry.get("per_entry")
+        if per_entry is None:
+            continue
+        lists = list_fields(definition)
+        assert per_entry["variable"] in lists, f"{path}: {per_entry['variable']} is not a for_each list"
+        default = (definition.get("variables") or {}).get(per_entry["variable"])
+        assert isinstance(default, list) and len(default) == per_entry["entries"], path
+```
+
+and one synthetic test in `tests/test_catalog_shape.py` or here that exercises the assertion logic on an in-memory definition with a wrong `entries` (so the test is not vacuous while no template has `per_entry`): factor the checks into a helper `per_entry_problems(definition) -> list[str]` in the test module and assert it reports the mismatch.
+
+`tests/test_server.py`, next to `test_workflow_variables_answer_without_the_whole_definition` (read it; mirror its fixture and how it writes a workflow):
+
+```python
+def test_workflow_variables_preview_inside_list_entries(server):
+    long = "x" * 500
+    # write a workflow whose variables are {"shots": [{"name": "a", "prompt": long}], "n": 1}
+    ...
+    body = client.get("/api/workflows/cut/variables").json()
+    assert body["variables"]["shots"][0]["prompt"] == "x" * 200
+    assert body["variables"]["shots"][0]["name"] == "a"
+    assert body["truncated"] == ["shots[0].prompt"]
+    full = client.get("/api/workflows/cut/variables", params={"full": "true"}).json()
+    assert full["variables"]["shots"][0]["prompt"] == long and full["truncated"] == []
+```
+
+- [ ] **Step 2: Run to verify they fail** — schema keys missing; `truncated` empty / prompt whole.
+
+- [ ] **Step 3: Implement**
+
+`dw/workflow_schema.json`, inside the `cost` items `properties`:
+
+```json
+"per_entry": {
+    "type": "object",
+    "description": "For a list-driven workflow: the measured cost of one entry of 'variable' (every member it produces), and the length of the default list 'minutes' was measured with, so a run over N entries is (minutes - per_entry.minutes * entries) + per_entry.minutes * N.",
+    "required": ["variable", "minutes", "entries"],
+    "properties": {
+        "variable": {"type": "string"},
+        "minutes": {"type": "number", "minimum": 0},
+        "entries": {"type": "integer", "minimum": 1}
+    },
+    "additionalProperties": false
+}
+```
+
+`dw/server/app.py` `get_workflow_variables`: replace the loop with a recursive preview:
+
+```python
+        def preview(value, path):
+            if isinstance(value, str) and len(value) > VARIABLE_VALUE_PREVIEW:
+                truncated.append(path)
+                return value[:VARIABLE_VALUE_PREVIEW]
+            if isinstance(value, list):
+                return [preview(item, f"{path}[{i}]") for i, item in enumerate(value)]
+            if isinstance(value, dict):
+                return {key: preview(item, f"{path}.{key}") for key, item in value.items()}
+            return value
+
+        variables = definition.get("variables") or {}
+        values, truncated = {}, []
+        for variable, value in variables.items():
+            values[variable] = value if full else preview(value, variable)
+```
+
+Update the docstring: "Long strings - a shot's prompt runs to kilobytes, and a list-driven workflow's default list holds several - are cut to their first 200 characters wherever they sit and named in `truncated` (`shots[0].prompt`)".
+
+Docs: `dw_mcp/catalog.py` `get_workflow` docstring adds "…including strings inside a list default, named like `shots[0].prompt`"; `docs/MCP.md` `get_workflow` row says the same; `docs/SERVER.md` line ~274 says the same; `docs/MCP.md` `list_workflows` row adds `lists` to the compact field list with one clause ("`lists`, present for a list-driven workflow, names the fields an entry of each list takes, the steps over it and the default's length") and says `cost` may carry `per_entry`.
+
+- [ ] **Step 4: Run tests, full suite, commit**
+
+```bash
+git add dw/workflow_schema.json dw/server/app.py dw_mcp/catalog.py docs/MCP.md docs/SERVER.md tests/test_catalog_shape.py tests/test_catalog_structure.py tests/test_server.py
+git commit -m "feat(catalog): per_entry cost on a measured entry; variables preview reaches inside list entries
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 4: Rulings — empty list, constants in validation, cache bound
+
+**Files:**
+- Modify: `dw/for_each.py` (`_entry_keys`), `dw/workflow_schema.json` (`for_each` gets `"minItems": 1`), `dw/workflow.py` (`expanded_definition`), `dw/step_cache.py` (`DEFAULT_MAX_ENTRIES`)
+- Test: `tests/test_for_each.py`, `tests/test_schema.py`, `tests/test_workflow.py`, `tests/test_step_cache.py`
+
+- [ ] **Step 1: Rewrite the two empty-list tests and add the new ones**
+
+In `tests/test_for_each.py`, replace `test_an_empty_list_expands_to_no_steps` (~line 127) with:
+
+```python
+    def test_an_empty_list_is_an_error_at_the_step(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(definition({"name": "shot", "for_each": [], "task": {}}))
+        assert e.value.path == "steps[0].for_each"
+        assert "would run no steps" in str(e.value)
+```
+
+and replace `test_gather_of_an_empty_group_is_an_empty_list` (~line 410) with a test that a `gather:` of a group that failed to expand never gets that far (the error above fires first) — or simply delete it and say so in the report, since the situation cannot arise.
+
+`tests/test_schema.py`: add a test that a step with `"for_each": []` fails schema validation with `for_each` in the message (mirror the file's existing for_each schema tests).
+
+`tests/test_workflow.py`: add
+
+```python
+def test_validation_realizes_a_constant_default_list(tmp_path):
+    """A list defaulted to a constant: name used to fail validation with the
+    string unsubstituted and then run fine, since only the run realized
+    constants."""
+    definition = _for_each_workflow()
+    definition["variables"]["shots"] = "constant:tests.test_workflow.CONSTANT_SHOTS"
+    workflow = _workflow_from(definition, tmp_path)
+    assert workflow.validation_errors() == []
+    assert [s["name"] for s in workflow.expanded_definition()["steps"]][:2] == ["shot@a", "shot@b"]
+```
+
+with `CONSTANT_SHOTS = [{"name": "a", "text": "1"}, {"name": "b", "text": "2"}]` at module level (match `_for_each_workflow`'s entry field name). `validate_constant_name` (`dw/security.py`) must accept a `tests.` module path — check its rules; if it refuses, put the constant on a module it accepts and say which.
+
+`tests/test_step_cache.py`: the cap test uses the symbol, so it needs no edit; add one assertion `assert StepCache.DEFAULT_MAX_ENTRIES >= 2 * MAX_FOR_EACH_ENTRIES + 8` with a comment: a maximal for_each run over two groups plus fixed steps must fit, or a run evicts its own earlier members.
+
+- [ ] **Step 2: Run to verify they fail** — empty list expands; schema accepts `[]`; constant default fails validation; cap assertion fails at 50.
+
+- [ ] **Step 3: Implement**
+
+`dw/for_each.py` `_entry_keys`, after the type check:
+
+```python
+    if not entries:
+        raise ForEachError(
+            render_path(path),
+            "for_each over an empty list would run no steps - a workflow that "
+            "generates nothing is never what was asked for",
+        )
+```
+
+`dw/workflow_schema.json`: `"minItems": 1` beside `"maxItems": 32`.
+
+`dw/workflow.py` `expanded_definition`: import `realize_constants` from `.arguments` and call `realize_constants(variables)` first thing inside the `if isinstance(variables, dict):` block, with a comment: the run realizes constants before folding arguments, and a list defaulted to a `constant:` name must expand here as it does there — a name lookup, no download. Update the docstring's first sentence accordingly.
+
+`dw/step_cache.py`: `DEFAULT_MAX_ENTRIES = 128`, and extend the class/module comment: sized so a maximal for_each run (32 entries over two groups plus fixed steps, ~70 members) never evicts its own members before it ends.
+
+- [ ] **Step 4: Update the prose that quoted the old numbers**
+
+`docs/proposals/list-driven-steps-complete.md`: in "Limits and cost" (~line 216-224) the sentence about `DEFAULT_MAX_ENTRIES = 50` and "leaves the cache alone" — append "(raised to 128 in stage 3)". In the stage 3 section's "Decisions carried" bullet, change "Raise the bound to 128, or make eviction skip…" to state that it was raised to 128. `CLAUDE.md` gotcha about the step cache needs no number. The stage-2 "Notes" paragraph that says the empty-list question "is a stage-2 decision" — leave; the stage 3 section rules it.
+
+- [ ] **Step 5: Run tests, full suite, commit**
+
+```bash
+git add dw/for_each.py dw/workflow_schema.json dw/workflow.py dw/step_cache.py tests/test_for_each.py tests/test_schema.py tests/test_workflow.py tests/test_step_cache.py docs/proposals/list-driven-steps-complete.md
+git commit -m "fix(for_each): an empty list is an error; validation realizes constants; step cache holds a maximal run
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 5: The skill, the guide, the MCP instructions and CLAUDE.md quote `lists` and `per_entry`
+
+**Files:**
+- Modify: `plugins/dw/skills/minimax-h3/SKILL.md` (the cost sentences in "A piece with cuts", ~lines 63-67)
+- Modify: `tests/test_plugin_skills.py` (`test_the_cuts_templates_are_described_as_list_driven`)
+- Modify: `docs/WORKFLOW_GUIDE.md` ("Limits:" paragraph of `### One step per entry: for_each`, ~line 412-420)
+- Modify: `dw_mcp/server.py` (the instructions string, ~line 75-80: "summary, shape, traits, cost and variable names")
+- Modify: `CLAUDE.md` (Type System `for_each` bullet, ~line 157-170)
+- Modify: `docs/proposals/list-driven-steps-complete.md` (status line, lines 3-6)
+
+- [ ] **Step 1: Extend the skill test**
+
+In `test_the_cuts_templates_are_described_as_list_driven`, replace the last assertion with:
+
+```python
+        # cost: the listing's per_entry block when present, the honest
+        # fallback when it is not
+        assert "`per_entry`" in text
+        assert "`lists`" in text
+```
+
+- [ ] **Step 2: Run it** — fails on `` `per_entry` ``.
+
+- [ ] **Step 3: Edit the skill**
+
+Replace the sentences from "The listing's `cost`" through "then multiply by the entries you write." with:
+
+```
+  The listing's `lists` block says what an entry carries; its `cost`
+  carries `per_entry` when one shot was measured: quote
+  `minutes - per_entry.minutes × per_entry.entries + per_entry.minutes × N`
+  for N entries. Without `per_entry`, quote the total and say it is the
+  default list's.
+```
+
+Keep the two entry-shape sentences before it. Measure with `wc -c`; stay ≤ 12288 (the replacement is shorter than what it replaces).
+
+- [ ] **Step 4: The guide, the MCP instructions, CLAUDE.md, the proposal**
+
+`docs/WORKFLOW_GUIDE.md` "Limits:" paragraph — replace the sentence from "the listing's `cost` is for the whole workflow" through "then multiply by the entries you write." with: "the listing's `lists` block names the fields an entry takes and the steps over it, and its `cost` carries `per_entry` once one entry has been measured — quote `minutes - per_entry.minutes × per_entry.entries + per_entry.minutes × N` for N entries, and without `per_entry` quote the total as the default list's. An entry key no step reads is a validation warning at the entry's path, so a misspelt field is caught before the run."
+
+`dw_mcp/server.py` instructions: "carries each workflow's summary, shape, traits, cost and variable names" → "carries each workflow's summary, shape, traits, cost (with `per_entry` for a list-driven one), variable names and, for a list-driven workflow, `lists` - what an entry of each list carries". Check `tests/test_mcp_*.py` for a pin on that sentence and update it if one exists.
+
+`CLAUDE.md` Type System `for_each` bullet: append "The catalog derives `lists` (`list_fields`, `dw/for_each.py`): the fields an entry takes are the `item:` references the steps make, `name` first; an entry key no step reads is a validation warning (`entry_field_warnings`). A `cost` entry may carry `per_entry` (`{variable, minutes, entries}`), measured, never derived. An empty `for_each` list is an error; `expanded_definition` realizes constants first."
+
+`docs/proposals/list-driven-steps-complete.md` status: "**stages 1, 2 and 3 implemented** (…; catalog `lists`, `per_entry` cost schema, entry-key warning, rulings, flow-view edges, 2026-09-11). `per_entry` figures for the two templates await a measured run."
+
+- [ ] **Step 5: Tests, suite, commit**
+
+Run: `python -m pytest -q tests/test_plugin_skills.py tests/test_server_guides.py tests/test_mcp_catalog.py` then the full suite.
+
+```bash
+git add plugins/dw/skills/minimax-h3/SKILL.md tests/test_plugin_skills.py docs/WORKFLOW_GUIDE.md dw_mcp/server.py CLAUDE.md docs/proposals/list-driven-steps-complete.md
+git commit -m "docs(for_each): the listing's lists block and per_entry cost, quoted by the skill and the guide
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 6: The editor's flow view sees `gather:` and `from_previous_result`
+
+**Files:**
+- Modify: `ui/src/lib/flow.ts` (`refTarget`, `flowGraph`, `dataFlowGraph`, `danglingReferenceDetails`)
+- Test: `ui/src/lib/flow.test.ts`
+
+**Interfaces:**
+- Produces: a reference is any of (a) a string `previous_result:<step>[.suffix]`, (b) a string `gather:<step>`, (c) the string value under a `from_previous_result` key. All three make an edge from `<step>` to the referencing step in `flowGraph` and `dataFlowGraph` (the edge's `attribute` label for (c) is the label of the path *above* the `from_previous_result` key — `references` — so it reads as the argument that carries it). `danglingReferenceDetails` reports a `gather:<step>` that names no earlier step, with the message `Step '<name>': gather:<step> - no earlier step has that name`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `ui/src/lib/flow.test.ts`:
+
+```ts
+describe('for_each references', () => {
+  const cut = {
+    steps: [
+      step('draw', {}),
+      step('slice', { audio: 'previous_result:song' }),
+      {
+        name: 'shot',
+        for_each: 'variable:shots',
+        pipeline: {
+          configuration: { component_type: 'ModularPipeline' },
+          arguments: {
+            prompt: 'item:prompt',
+            references: [
+              { reference_type: 'T', from_previous_result: 'draw' },
+              { reference_type: 'T', from_previous_result: 'slice' },
+            ],
+          },
+        },
+      },
+      step('edit', { videos: 'gather:shot' }),
+    ],
+  }
+
+  it('from_previous_result inside a reference list is an edge labeled by the list', () => {
+    const graph = dataFlowGraph(cut)
+    expect(graph.edges).toContainEqual({ from: 'draw', to: 'shot', attribute: 'references' })
+    expect(graph.edges).toContainEqual({ from: 'slice', to: 'shot', attribute: 'references' })
+    expect(graph.nodes.find((n) => n.name === 'shot')?.isEntryPoint).toBe(false)
+  })
+
+  it('gather: is an edge from the for_each step to the step that gathers it', () => {
+    const graph = dataFlowGraph(cut)
+    expect(graph.edges).toContainEqual({ from: 'shot', to: 'edit', attribute: 'videos' })
+    expect(graph.nodes.find((n) => n.name === 'edit')?.isEntryPoint).toBe(false)
+    expect(flowGraph(cut)[3].inputs).toEqual(['shot'])
+    expect(flowGraph(cut)[2].consumers).toEqual(['edit'])
+  })
+
+  it('a gather of a step that does not exist is dangling', () => {
+    const wf = { steps: [step('edit', { videos: 'gather:nope' })] }
+    expect(danglingReferenceDetails(wf)).toEqual([
+      { stepIndex: 0, message: "Step 'edit': gather:nope - no earlier step has that name" },
+    ])
+  })
+})
+```
+
+Adjust `danglingReferenceDetails`' expected shape to match what the existing test at line ~96 asserts (read it first).
+
+- [ ] **Step 2: Run** — `cd ui && npm test -- flow` — fails.
+
+- [ ] **Step 3: Implement**
+
+In `flow.ts`, generalise `refTarget` to take the value and the path:
+
+```ts
+/** The earlier step a value refers to: `previous_result:<step>[.suffix]`,
+ * `gather:<step>` (every member of a for_each step), or the string under
+ * a `from_previous_result` key inside a reference object. */
+function refTarget(s: string, path: string[] = []): string | null {
+  if (s.startsWith('previous_result:')) return s.slice('previous_result:'.length).split('.')[0]
+  if (s.startsWith('gather:')) return s.slice('gather:'.length)
+  if (path[path.length - 1] === 'from_previous_result') return s
+  return null
+}
+```
+
+`flowGraph` currently uses `scanStrings` (no path); switch it to `scanStringsWithPath` so `from_previous_result` is seen. In `dataFlowGraph`, pass `path` to `refTarget`; for the attribute label, when the path ends in `from_previous_result`, use `attributeLabel(path.slice(0, -1))` so the label is the carrying argument (`references`) — check what `attributeLabel` does with numeric indices and make sure `references.0` collapses to `references` (read lines 84-94). In `danglingReferenceDetails`, add a `gather:` branch mirroring the `previous_result:` one with the message above.
+
+- [ ] **Step 4: Run the UI checks**
+
+Run from `ui/`: `npm run check && npm run lint && npm run format && npm test`
+Expected: all pass; commit any prettier rewrites of the files you touched.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add ui/src/lib/flow.ts ui/src/lib/flow.test.ts
+git commit -m "ui(flow): edges for gather: and from_previous_result, so a list-driven workflow's editor is not an orphan
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
diff --git a/docs/superpowers/plans/2026-09-11-list-driven-steps.md b/docs/superpowers/plans/2026-09-11-list-driven-steps.md
new file mode 100644
index 00000000..e92eb789
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-11-list-driven-steps.md
@@ -0,0 +1,1632 @@
+# List-Driven Steps (`for_each`) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** A step can carry `"for_each": <list>` and expand into one ordinary step per entry before the run starts, so a template takes a `shots` list instead of one hand-written step per shot.
+
+**Architecture:** Expansion is a source transform, not a runtime concept. A new module `dw/for_each.py` holds one pure function, `expand_for_each(definition) -> definition`, that runs immediately after `replace_variables` in `Workflow.run` and, with the caller's arguments folded in, inside `Workflow.validation_errors`. After the pass the definition is an ordinary workflow: `item:` is substituted, `gather:group` is rewritten to an explicit `previous_result:` list, a same-key sibling reference is rewritten to the member with this key, and every member is named `group@key`. Nothing downstream - the step loop, the step cache, the manifest, the reference checker - learns a new reference kind.
+
+**Tech Stack:** Python 3, pytest. No new dependencies.
+
+**Spec:** `docs/proposals/list-driven-steps-complete.md` (revised 2026-09-11). This plan is stage 1 of that proposal plus the agent-facing documentation; the template rewrite (stage 2) and catalog cost/entry-shape reporting (stage 3) are a later plan.
+
+## Global Constraints
+
+- Member separator is `@`; `@` is reserved in every step name, so a hand-written step name containing `@` is an error.
+- Entry `name` must match `^[a-zA-Z_][a-zA-Z0-9_-]*$` (the `validate_variable_name` pattern in `dw/security.py`) and be unique within its list; an entry without a `name` (or a non-object entry) is keyed by its index.
+- Ceiling: `MAX_FOR_EACH_ENTRIES = 32`; a longer list is refused with an error naming the ceiling.
+- `for_each` runs over exactly one list; no index (`item:@index`), no numeric `for_each`, no zip.
+- `item:field` yields whatever the field holds - string, number, list, object - spliced in as definition text. Bare `item:` is the whole entry.
+- `gather:group` written inside a list splices into it; written as a scalar value it becomes a list. `gather:` naming a step that is not an earlier `for_each` group is an error.
+- Inside a member, `previous_result:other` / `from_previous_result: "other"` naming an *earlier* `for_each` group over the *same* list (deep-equal) rewrites to `other@<this key>`. Naming a group any other way (from outside a group, from a group over a different list, or one's own group) is an error that says to use `gather:`.
+- `release_pipeline` and `release_models` on a `for_each` step survive on the last member only.
+- The realized workflow (`dw/realize.py`) keeps `for_each`; the manifest and events name the expanded members. No change to `dw/realize.py` is needed - it works on `self.workflow_definition`, which the pass never touches.
+- Never use `eval()`, `exec()`, or `shell=True`. Errors carry a JSON path in the `steps[3].pipeline.arguments.prompt` shape `_render_path` in `dw/previous_results.py` produces.
+- Run the suite with `python -m pytest tests -q -x`; commit after each task with the trailer `Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>`.
+
+---
+
+## File structure
+
+| File | Responsibility |
+|---|---|
+| `dw/for_each.py` (create) | The pass: constants, `ForEachError`, `expand_for_each`, `for_each_errors`. Pure; no I/O, no engine imports beyond `dw.security.validate_variable_name`, `dw.step_cache.reference_resolves_to` and the two constants from `dw.arguments`. |
+| `dw/workflow.py` (modify) | Call the pass in `run` after substitution; `validation_errors(arguments=None)` substitutes, expands, then reference-checks the expanded definition. |
+| `dw/workflow_schema.json` (modify) | `for_each` on a step. |
+| `dw/server/app.py` (modify) | `validate_workflow` passes `request.arguments` into `validation_errors`. |
+| `tests/test_for_each.py` (create) | Unit tests for the pass, including the two templates expanded back to what they contain today. |
+| `tests/test_workflow.py`, `tests/test_validate_arguments.py` (modify) | Integration: run-time expansion, validation ordering. |
+| `docs/WORKFLOW_GUIDE.md`, `CLAUDE.md`, `docs/SERVER.md` (modify) | The agent-facing conventions, the CLAUDE.md mirror, the manifest naming note. |
+
+---
+
+### Task 1: The pass - names, ceiling, `item:` substitution
+
+**Files:**
+- Create: `dw/for_each.py`
+- Test: `tests/test_for_each.py`
+
+**Interfaces:**
+- Consumes: `validate_variable_name` (`dw/security.py:390`, raises `InvalidInputError`), `reference_resolves_to` (`dw/step_cache.py:58`), `FROM_PREVIOUS_RESULT_KEY`, `PREVIOUS_RESULT_PREFIX` (`dw/arguments.py:49,58`).
+- Produces: `expand_for_each(definition: dict) -> dict` (new dict, input untouched), `class ForEachError(ValueError)` with `.path: str`, constants `FOR_EACH_KEY = "for_each"`, `ITEM_PREFIX = "item:"`, `GATHER_PREFIX = "gather:"`, `MEMBER_SEPARATOR = "@"`, `MAX_FOR_EACH_ENTRIES = 32`, and `member_name(group: str, key: str) -> str`. Tasks 2 and 3 extend this module; Tasks 4-6 call it.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/test_for_each.py
+import copy
+
+import pytest
+
+from dw.for_each import (
+    MAX_FOR_EACH_ENTRIES,
+    ForEachError,
+    expand_for_each,
+    member_name,
+)
+
+
+def definition(*steps, **extra):
+    return {"id": "test", "steps": list(steps), **extra}
+
+
+class TestNaming:
+    def test_member_name_joins_with_at(self):
+        assert member_name("shot", "wide_open") == "shot@wide_open"
+
+    def test_an_object_entry_is_named_by_its_name(self):
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "shot",
+                    "for_each": [{"name": "wide_open"}, {"name": "closeup"}],
+                    "task": {"command": "x", "arguments": {}},
+                }
+            )
+        )
+        assert [s["name"] for s in expanded["steps"]] == [
+            "shot@wide_open",
+            "shot@closeup",
+        ]
+
+    def test_a_nameless_entry_is_named_by_its_index(self):
+        expanded = expand_for_each(
+            definition(
+                {"name": "shot", "for_each": ["a", "b"], "task": {"arguments": {}}}
+            )
+        )
+        assert [s["name"] for s in expanded["steps"]] == ["shot@0", "shot@1"]
+
+    def test_for_each_is_dropped_from_the_members(self):
+        expanded = expand_for_each(
+            definition({"name": "shot", "for_each": ["a"], "task": {}})
+        )
+        assert "for_each" not in expanded["steps"][0]
+
+    def test_the_input_is_not_mutated(self):
+        original = definition({"name": "shot", "for_each": ["a"], "task": {}})
+        before = copy.deepcopy(original)
+        expand_for_each(original)
+        assert original == before
+
+    def test_a_workflow_without_for_each_comes_back_equal(self):
+        original = definition({"name": "plain", "task": {"arguments": {"a": 1}}})
+        assert expand_for_each(original) == original
+
+    def test_a_hand_written_at_sign_is_an_error(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(definition({"name": "shot@0", "task": {}}))
+        assert e.value.path == "steps[0].name"
+        assert "@" in str(e.value)
+
+    def test_a_duplicate_entry_name_is_an_error(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition(
+                    {
+                        "name": "shot",
+                        "for_each": [{"name": "closeup"}, {"name": "closeup"}],
+                        "task": {},
+                    }
+                )
+            )
+        assert e.value.path == "steps[0].for_each[1].name"
+        assert "closeup" in str(e.value)
+
+    def test_an_invalid_entry_name_is_an_error(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition(
+                    {"name": "shot", "for_each": [{"name": "wide open"}], "task": {}}
+                )
+            )
+        assert e.value.path == "steps[0].for_each[0].name"
+
+    def test_a_non_list_for_each_is_an_error(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(definition({"name": "shot", "for_each": 4, "task": {}}))
+        assert e.value.path == "steps[0].for_each"
+        assert "list" in str(e.value)
+
+    def test_an_unsubstituted_variable_is_an_error_that_says_so(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition({"name": "shot", "for_each": "variable:shots", "task": {}})
+            )
+        assert "variable:shots" in str(e.value)
+
+    def test_an_empty_list_expands_to_no_steps(self):
+        expanded = expand_for_each(
+            definition(
+                {"name": "shot", "for_each": [], "task": {}},
+                {"name": "after", "task": {}},
+            )
+        )
+        assert [s["name"] for s in expanded["steps"]] == ["after"]
+
+    def test_the_ceiling_is_enforced(self):
+        entries = [{"name": f"s{i}"} for i in range(MAX_FOR_EACH_ENTRIES + 1)]
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition({"name": "shot", "for_each": entries, "task": {}})
+            )
+        assert str(MAX_FOR_EACH_ENTRIES) in str(e.value)
+
+    def test_a_list_at_the_ceiling_is_fine(self):
+        entries = [{"name": f"s{i}"} for i in range(MAX_FOR_EACH_ENTRIES)]
+        expanded = expand_for_each(
+            definition({"name": "shot", "for_each": entries, "task": {}})
+        )
+        assert len(expanded["steps"]) == MAX_FOR_EACH_ENTRIES
+
+
+class TestItemSubstitution:
+    def test_a_field_is_substituted(self):
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "shot",
+                    "for_each": [{"name": "a", "prompt": "the band walks on"}],
+                    "pipeline": {"arguments": {"prompt": "item:prompt"}},
+                }
+            )
+        )
+        assert expanded["steps"][0]["pipeline"]["arguments"]["prompt"] == (
+            "the band walks on"
+        )
+
+    def test_a_bare_item_is_the_whole_entry(self):
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "shot",
+                    "for_each": ["first prompt", "second prompt"],
+                    "pipeline": {"arguments": {"prompt": "item:"}},
+                }
+            )
+        )
+        prompts = [s["pipeline"]["arguments"]["prompt"] for s in expanded["steps"]]
+        assert prompts == ["first prompt", "second prompt"]
+
+    def test_a_structured_field_is_spliced_whole(self):
+        references = [
+            {"reference_type": "T", "from_previous_result": "draw_a"},
+            {"reference_type": "T", "from_previous_result": "draw_b"},
+        ]
+        expanded = expand_for_each(
+            definition(
+                {"name": "draw_a", "task": {}},
+                {"name": "draw_b", "task": {}},
+                {
+                    "name": "shot",
+                    "for_each": [{"name": "open", "references": references}],
+                    "pipeline": {"arguments": {"references": "item:references"}},
+                },
+            )
+        )
+        assert expanded["steps"][2]["pipeline"]["arguments"]["references"] == references
+
+    def test_a_number_keeps_its_type(self):
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "slice",
+                    "for_each": [{"name": "a", "start_frame": 124}],
+                    "task": {"arguments": {"start_frame": "item:start_frame"}},
+                }
+            )
+        )
+        assert expanded["steps"][0]["task"]["arguments"]["start_frame"] == 124
+
+    def test_item_is_substituted_at_any_depth(self):
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "shot",
+                    "for_each": [{"name": "a", "voice": "asset:a.wav"}],
+                    "pipeline": {
+                        "arguments": {"references": [{"from_file": "item:voice"}]}
+                    },
+                }
+            )
+        )
+        assert expanded["steps"][0]["pipeline"]["arguments"]["references"] == [
+            {"from_file": "asset:a.wav"}
+        ]
+
+    def test_a_missing_field_is_an_error_at_its_path(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition(
+                    {
+                        "name": "shot",
+                        "for_each": [{"name": "a"}],
+                        "pipeline": {"arguments": {"prompt": "item:prompt"}},
+                    }
+                )
+            )
+        assert e.value.path == "steps[0].pipeline.arguments.prompt"
+        assert "prompt" in str(e.value) and "a" in str(e.value)
+
+    def test_a_field_of_a_string_entry_is_an_error(self):
+        with pytest.raises(ForEachError):
+            expand_for_each(
+                definition(
+                    {
+                        "name": "shot",
+                        "for_each": ["just a prompt"],
+                        "pipeline": {"arguments": {"prompt": "item:prompt"}},
+                    }
+                )
+            )
+
+    def test_item_outside_a_for_each_step_is_an_error(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition({"name": "plain", "task": {"arguments": {"p": "item:x"}}})
+            )
+        assert e.value.path == "steps[0].task.arguments.p"
+
+    def test_members_do_not_share_mutable_values(self):
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "shot",
+                    "for_each": [{"name": "a"}, {"name": "b"}],
+                    "pipeline": {"arguments": {"references": [{"k": 1}]}},
+                }
+            )
+        )
+        first, second = expanded["steps"]
+        first["pipeline"]["arguments"]["references"][0]["k"] = 2
+        assert second["pipeline"]["arguments"]["references"][0]["k"] == 1
+
+
+class TestRelease:
+    def test_release_flags_survive_on_the_last_member_only(self):
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "shot",
+                    "for_each": [{"name": "a"}, {"name": "b"}, {"name": "c"}],
+                    "release_pipeline": True,
+                    "release_models": True,
+                    "pipeline": {},
+                }
+            )
+        )
+        flags = [
+            (s.get("release_pipeline"), s.get("release_models"))
+            for s in expanded["steps"]
+        ]
+        assert flags == [(None, None), (None, None), (True, True)]
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `python -m pytest tests/test_for_each.py -q`
+Expected: FAIL with `ModuleNotFoundError: No module named 'dw.for_each'`
+
+- [ ] **Step 3: Write the module**
+
+```python
+# dw/for_each.py
+"""Expand a step's 'for_each' list into one ordinary step per entry.
+
+A template that generates one shot per entry of a list is otherwise written
+the long way - 'shot_1', 'shot_2', ... each a near-copy of the one before -
+and a six-shot episode is a different file from a five-shot one. This pass
+runs on the definition after variable substitution and before the run id is
+computed (Workflow.run) and before the reference check (validation_errors),
+and produces a definition with no 'for_each' in it: every member is an
+ordinary step, so the step loop, the step cache, the manifest and the
+reference checker never learn a new reference kind.
+
+Inside a member:
+  - 'item:'       is the whole entry; 'item:field' one field of an object
+                  entry, spliced in whole whatever its type
+  - a reference to another for_each group over the SAME list resolves to
+    the member with the same key ('slice' inside 'shot@open' -> 'slice@open')
+Outside (or inside, for any other group):
+  - 'gather:shot' is the list of every member's result, as explicit
+    'previous_result:shot@<key>' strings; inside a list it splices
+  - 'previous_result:shot' naming a group is an error that says to gather
+
+Members are named '<group>@<key>' - the entry's own 'name' when it carries
+one, else its index - and '@' is reserved in every step name. Names rather
+than indexes because the step cache (dw/step_cache.py) keys on the step
+name: inserting a shot in the middle of a list must not shift every later
+member onto a different entry's cache line.
+"""
+
+import copy
+import re
+
+from .arguments import FROM_PREVIOUS_RESULT_KEY, PREVIOUS_RESULT_PREFIX
+from .security import InvalidInputError, validate_variable_name
+from .step_cache import reference_resolves_to
+
+FOR_EACH_KEY = "for_each"
+ITEM_PREFIX = "item:"
+GATHER_PREFIX = "gather:"
+MEMBER_SEPARATOR = "@"
+# Each entry is a full generation. Stated against the step cache's bound
+# (DEFAULT_MAX_ENTRIES = 50): a run whose expanded steps exceed the cache
+# evicts its own earlier members, so this is kept well under it
+MAX_FOR_EACH_ENTRIES = 32
+# release_pipeline / release_models would drop the model after the first
+# member and reload it for the second, so they are carried onto the last one
+_LAST_MEMBER_ONLY = ("release_pipeline", "release_models")
+
+
+class ForEachError(ValueError):
+    """A for_each step that cannot be expanded, with the JSON path at fault."""
+
+    def __init__(self, path, message):
+        super().__init__(message)
+        self.path = path
+
+
+def member_name(group, key):
+    return f"{group}{MEMBER_SEPARATOR}{key}"
+
+
+def expand_for_each(definition):
+    """The definition with every 'for_each' step replaced by its members.
+
+    Returns a new structure; `definition` is left as it was passed in.
+    Raises ForEachError for anything that cannot be expanded.
+    """
+    steps = definition.get("steps") if isinstance(definition, dict) else None
+    if not isinstance(steps, list):
+        return definition
+
+    # group name -> {"keys": [...], "entries": [...]} for every group
+    # expanded so far, in step order, so a reference can only reach an
+    # earlier group - the same rule previous_result: has always had
+    groups = {}
+    expanded = []
+    for index, step in enumerate(steps):
+        if not isinstance(step, dict):
+            expanded.append(copy.deepcopy(step))
+            continue
+        path = ("steps", index)
+        name = step.get("name")
+        if isinstance(name, str) and MEMBER_SEPARATOR in name:
+            raise ForEachError(
+                _render_path(path + ("name",)),
+                f"Step name '{name}' contains '{MEMBER_SEPARATOR}', which is "
+                f"reserved for the members of a for_each step",
+            )
+        if FOR_EACH_KEY not in step:
+            expanded.append(_rewrite(step, path, groups, member=None))
+            continue
+
+        entries = step[FOR_EACH_KEY]
+        keys = _entry_keys(entries, path + (FOR_EACH_KEY,))
+        template = {k: v for k, v in step.items() if k != FOR_EACH_KEY}
+        last = len(keys) - 1
+        for position, (key, entry) in enumerate(zip(keys, entries)):
+            member = {
+                "group": name,
+                "key": key,
+                "entry": entry,
+                "entries": entries,
+                "index": position,
+            }
+            expanded_step = _rewrite(template, path, groups, member)
+            expanded_step["name"] = member_name(name, key)
+            if position != last:
+                for flag in _LAST_MEMBER_ONLY:
+                    expanded_step.pop(flag, None)
+            expanded.append(expanded_step)
+        groups[name] = {"keys": keys, "entries": entries}
+
+    result = {k: v for k, v in definition.items() if k != "steps"}
+    result["steps"] = expanded
+    return result
+
+
+def _entry_keys(entries, path):
+    """The key of every entry - its 'name' when it is an object carrying
+    one, else its index - validated and unique."""
+    if not isinstance(entries, list):
+        if isinstance(entries, str) and entries.startswith("variable:"):
+            hint = f" - '{entries}' was not substituted; is the variable declared?"
+        else:
+            hint = ""
+        raise ForEachError(
+            _render_path(path), f"for_each must be a list, got {type(entries).__name__}{hint}"
+        )
+    if len(entries) > MAX_FOR_EACH_ENTRIES:
+        raise ForEachError(
+            _render_path(path),
+            f"for_each has {len(entries)} entries; the limit is {MAX_FOR_EACH_ENTRIES}",
+        )
+    keys = []
+    for index, entry in enumerate(entries):
+        key = str(index)
+        if isinstance(entry, dict) and "name" in entry:
+            key = entry["name"]
+            key_path = _render_path(path + (index, "name"))
+            if not isinstance(key, str):
+                raise ForEachError(key_path, "An entry's name must be a string")
+            try:
+                validate_variable_name(key)
+            except InvalidInputError as e:
+                raise ForEachError(key_path, f"Invalid entry name '{key}': {e}") from e
+            if key in keys:
+                raise ForEachError(key_path, f"Duplicate entry name '{key}'")
+        keys.append(key)
+    return keys
+
+
+def _rewrite(value, path, groups, member):
+    """Rebuild `value` with item:, gather: and group references resolved.
+
+    `member` is None outside a for_each step; inside one it carries the
+    group, key and entry of the member being built.
+    """
+    if isinstance(value, dict):
+        rebuilt = {}
+        for key, item in value.items():
+            if key == FROM_PREVIOUS_RESULT_KEY and isinstance(item, str):
+                rebuilt[key] = _rewrite_reference(item, path + (key,), groups, member)
+            else:
+                rebuilt[key] = _rewrite(item, path + (key,), groups, member)
+        return rebuilt
+    if isinstance(value, list):
+        rebuilt = []
+        for index, item in enumerate(value):
+            if isinstance(item, str) and item.startswith(GATHER_PREFIX):
+                # A gather inside a list splices into it
+                rebuilt.extend(_gather(item, path + (index,), groups))
+            else:
+                rebuilt.append(_rewrite(item, path + (index,), groups, member))
+        return rebuilt
+    if isinstance(value, str):
+        if value.startswith(GATHER_PREFIX):
+            return _gather(value, path, groups)
+        if value.startswith(ITEM_PREFIX):
+            return _item(value, path, member)
+        if value.startswith(PREVIOUS_RESULT_PREFIX):
+            reference = value[len(PREVIOUS_RESULT_PREFIX) :]
+            return PREVIOUS_RESULT_PREFIX + _rewrite_reference(
+                reference, path, groups, member
+            )
+        return value
+    return copy.deepcopy(value)
+
+
+def _item(value, path, member):
+    if member is None:
+        raise ForEachError(
+            _render_path(path), f"'{value}' is only meaningful inside a for_each step"
+        )
+    field = value[len(ITEM_PREFIX) :]
+    entry = member["entry"]
+    if field == "":
+        return copy.deepcopy(entry)
+    if not isinstance(entry, dict):
+        raise ForEachError(
+            _render_path(path),
+            f"'{value}' asks for a field of entry '{member['key']}' of "
+            f"for_each step '{member['group']}', which is not an object",
+        )
+    if field not in entry:
+        raise ForEachError(
+            _render_path(path),
+            f"'{value}' names no field of entry '{member['key']}' of for_each "
+            f"step '{member['group']}'; it has: {sorted(entry)}",
+        )
+    return copy.deepcopy(entry[field])
+
+
+def _gather(value, path, groups):
+    group = value[len(GATHER_PREFIX) :]
+    if group not in groups:
+        raise ForEachError(
+            _render_path(path),
+            f"'{value}' names no earlier for_each step. "
+            f"for_each steps available here: {sorted(groups)}",
+        )
+    return [
+        PREVIOUS_RESULT_PREFIX + member_name(group, key)
+        for key in groups[group]["keys"]
+    ]
+
+
+def _rewrite_reference(reference, path, groups, member):
+    """A previous_result reference (without its prefix) as the expanded
+    definition spells it: unchanged unless it names a for_each group."""
+    if reference.startswith("variable:"):
+        return reference
+    group = next((g for g in groups if reference_resolves_to(reference, g)), None)
+    if group is None:
+        if member is not None and reference_resolves_to(reference, member["group"]):
+            raise ForEachError(
+                _render_path(path),
+                f"'{reference}' names its own for_each step '{member['group']}'",
+            )
+        return reference
+    if member is not None and member["entries"] == groups[group]["entries"]:
+        # Same list: shot@open reads slice@open
+        return member_name(group, member["key"]) + reference[len(group) :]
+    where = (
+        f"from inside for_each step '{member['group']}', which runs over a different list"
+        if member is not None
+        else "from outside a for_each step"
+    )
+    raise ForEachError(
+        _render_path(path),
+        f"'{reference}' names the for_each step '{group}' {where}. Use "
+        f"'{GATHER_PREFIX}{group}' for every member's result, or a reference "
+        f"from a for_each step over the same list for the same-keyed member",
+    )
+
+
+def _render_path(path):
+    """'steps[3].task.arguments.videos[1]' - the same shape schema errors use."""
+    rendered = ""
+    for part in path:
+        if isinstance(part, int):
+            rendered += f"[{part}]"
+        elif rendered:
+            rendered += f".{part}"
+        else:
+            rendered = str(part)
+    return rendered
+```
+
+Note: `_render_path` duplicates `dw/previous_results.py:_render_path`; move that one here and import it from `previous_results` (`from .for_each import _render_path` would be circular the other way - `for_each` must not import `previous_results`). Do the move: delete the copy in `previous_results.py` and add `from .for_each import _render_path` there, renaming it `render_path` (public) in both places.
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `python -m pytest tests/test_for_each.py tests/test_previous_results.py -q`
+Expected: all PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/for_each.py dw/previous_results.py tests/test_for_each.py
+git commit -m "feat(for_each): expansion pass - member naming, ceiling, item: substitution
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 2: `gather:` and group references
+
+**Files:**
+- Modify: `dw/for_each.py` (already written in Task 1; this task tests the `_gather` / `_rewrite_reference` behaviour and fixes what the tests find)
+- Test: `tests/test_for_each.py`
+
+**Interfaces:**
+- Consumes: Task 1's module.
+- Produces: the same `expand_for_each`; behaviour now pinned for `gather:`, same-key siblings and the directed errors.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/test_for_each.py`:
+
+```python
+class TestGather:
+    def group(self, *extra):
+        return definition(
+            {
+                "name": "shot",
+                "for_each": [{"name": "open"}, {"name": "close"}],
+                "pipeline": {"arguments": {}},
+            },
+            *extra,
+        )
+
+    def test_a_scalar_gather_becomes_the_member_list(self):
+        expanded = expand_for_each(
+            self.group(
+                {"name": "edit", "task": {"arguments": {"videos": "gather:shot"}}}
+            )
+        )
+        assert expanded["steps"][-1]["task"]["arguments"]["videos"] == [
+            "previous_result:shot@open",
+            "previous_result:shot@close",
+        ]
+
+    def test_a_gather_inside_a_list_splices(self):
+        expanded = expand_for_each(
+            self.group(
+                {"name": "intro", "task": {}},
+                {
+                    "name": "edit",
+                    "task": {
+                        "arguments": {
+                            "videos": ["previous_result:intro", "gather:shot"]
+                        }
+                    },
+                },
+            )
+        )
+        assert expanded["steps"][-1]["task"]["arguments"]["videos"] == [
+            "previous_result:intro",
+            "previous_result:shot@open",
+            "previous_result:shot@close",
+        ]
+
+    def test_gather_of_an_empty_group_is_an_empty_list(self):
+        expanded = expand_for_each(
+            definition(
+                {"name": "shot", "for_each": [], "task": {}},
+                {"name": "edit", "task": {"arguments": {"videos": "gather:shot"}}},
+            )
+        )
+        assert expanded["steps"][-1]["task"]["arguments"]["videos"] == []
+
+    def test_gather_of_a_plain_step_is_an_error(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition(
+                    {"name": "one", "task": {}},
+                    {"name": "edit", "task": {"arguments": {"videos": "gather:one"}}},
+                )
+            )
+        assert e.value.path == "steps[1].task.arguments.videos"
+        assert "no earlier for_each step" in str(e.value)
+
+    def test_gather_of_a_later_group_is_an_error(self):
+        with pytest.raises(ForEachError):
+            expand_for_each(
+                definition(
+                    {"name": "edit", "task": {"arguments": {"videos": "gather:shot"}}},
+                    {"name": "shot", "for_each": ["a"], "task": {}},
+                )
+            )
+
+    def test_gather_in_a_sub_workflow_argument_map(self):
+        expanded = expand_for_each(
+            self.group(
+                {
+                    "name": "score",
+                    "workflow": {"path": "builtin:x.json", "arguments": {"clips": "gather:shot"}},
+                }
+            )
+        )
+        assert expanded["steps"][-1]["workflow"]["arguments"]["clips"] == [
+            "previous_result:shot@open",
+            "previous_result:shot@close",
+        ]
+
+
+class TestGroupReferences:
+    def test_previous_result_naming_a_group_says_to_gather(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition(
+                    {"name": "shot", "for_each": ["a"], "task": {}},
+                    {
+                        "name": "edit",
+                        "task": {"arguments": {"video": "previous_result:shot"}},
+                    },
+                )
+            )
+        assert e.value.path == "steps[1].task.arguments.video"
+        assert "gather:shot" in str(e.value)
+
+    def test_from_previous_result_naming_a_group_says_to_gather(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition(
+                    {"name": "shot", "for_each": ["a"], "task": {}},
+                    {
+                        "name": "edit",
+                        "task": {
+                            "arguments": {"refs": [{"from_previous_result": "shot"}]}
+                        },
+                    },
+                )
+            )
+        assert e.value.path == "steps[1].task.arguments.refs[0].from_previous_result"
+
+    def test_a_property_reference_to_a_group_is_also_refused(self):
+        with pytest.raises(ForEachError):
+            expand_for_each(
+                definition(
+                    {"name": "shot", "for_each": ["a"], "task": {}},
+                    {
+                        "name": "edit",
+                        "task": {"arguments": {"v": "previous_result:shot.frames"}},
+                    },
+                )
+            )
+
+    def test_a_reference_to_an_ordinary_step_is_untouched(self):
+        expanded = expand_for_each(
+            definition(
+                {"name": "draw", "task": {}},
+                {
+                    "name": "shot",
+                    "for_each": ["a"],
+                    "pipeline": {
+                        "arguments": {
+                            "references": [{"from_previous_result": "draw"}],
+                            "still": "previous_result:draw.image",
+                        }
+                    },
+                },
+            )
+        )
+        arguments = expanded["steps"][1]["pipeline"]["arguments"]
+        assert arguments["references"] == [{"from_previous_result": "draw"}]
+        assert arguments["still"] == "previous_result:draw.image"
+
+    def test_a_variable_spelled_from_previous_result_is_untouched(self):
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "edit",
+                    "task": {"arguments": {"r": [{"from_previous_result": "variable:x"}]}},
+                }
+            )
+        )
+        assert expanded["steps"][0]["task"]["arguments"]["r"] == [
+            {"from_previous_result": "variable:x"}
+        ]
+
+
+class TestSameKeySiblings:
+    def shots(self):
+        return [
+            {"name": "open", "start_frame": 0},
+            {"name": "close", "start_frame": 124},
+        ]
+
+    def test_a_sibling_over_the_same_list_resolves_to_the_same_key(self):
+        shots = self.shots()
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "slice",
+                    "for_each": shots,
+                    "task": {"arguments": {"start_frame": "item:start_frame"}},
+                },
+                {
+                    "name": "shot",
+                    "for_each": shots,
+                    "pipeline": {
+                        "arguments": {
+                            "references": [{"from_previous_result": "slice"}],
+                            "audio": "previous_result:slice.audio",
+                        }
+                    },
+                },
+            )
+        )
+        names = [s["name"] for s in expanded["steps"]]
+        assert names == ["slice@open", "slice@close", "shot@open", "shot@close"]
+        close = expanded["steps"][3]["pipeline"]["arguments"]
+        assert close["references"] == [{"from_previous_result": "slice@close"}]
+        assert close["audio"] == "previous_result:slice@close.audio"
+
+    def test_the_same_list_means_equal_not_identical(self):
+        expanded = expand_for_each(
+            definition(
+                {"name": "slice", "for_each": self.shots(), "task": {}},
+                {
+                    "name": "shot",
+                    "for_each": self.shots(),
+                    "task": {"arguments": {"a": "previous_result:slice"}},
+                },
+            )
+        )
+        assert expanded["steps"][2]["task"]["arguments"]["a"] == (
+            "previous_result:slice@open"
+        )
+
+    def test_a_sibling_over_a_different_list_is_an_error(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition(
+                    {"name": "slice", "for_each": ["a", "b"], "task": {}},
+                    {
+                        "name": "shot",
+                        "for_each": ["a"],
+                        "task": {"arguments": {"x": "previous_result:slice"}},
+                    },
+                )
+            )
+        assert "different list" in str(e.value)
+
+    def test_a_step_referencing_its_own_group_is_an_error(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition(
+                    {
+                        "name": "shot",
+                        "for_each": ["a", "b"],
+                        "task": {"arguments": {"x": "previous_result:shot"}},
+                    }
+                )
+            )
+        assert "its own" in str(e.value)
+
+    def test_a_gather_inside_a_member_still_gathers(self):
+        expanded = expand_for_each(
+            definition(
+                {"name": "slice", "for_each": ["a", "b"], "task": {}},
+                {
+                    "name": "shot",
+                    "for_each": ["x"],
+                    "task": {"arguments": {"all": "gather:slice"}},
+                },
+            )
+        )
+        assert expanded["steps"][2]["task"]["arguments"]["all"] == [
+            "previous_result:slice@0",
+            "previous_result:slice@1",
+        ]
+```
+
+- [ ] **Step 2: Run the tests**
+
+Run: `python -m pytest tests/test_for_each.py -q`
+Expected: the new classes PASS against the Task 1 module. If any fails, fix `_gather` / `_rewrite_reference` in `dw/for_each.py` until they pass - the tests are the specification, the code is not.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add dw/for_each.py tests/test_for_each.py
+git commit -m "test(for_each): gather:, same-key siblings and the directed group errors
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: The two templates, expanded back to what they contain today
+
+This is the test that proves stage 2 is mechanical. It writes each template's shot section the list-driven way *inside the test* and asserts the expansion equals the hand-written steps that exist now.
+
+**Files:**
+- Test: `tests/test_for_each.py`
+- Read: `workflows/templates/minimax/music-video.json`, `workflows/templates/minimax/dialogue-short.json`
+
+**Interfaces:**
+- Consumes: `expand_for_each`.
+- Produces: nothing new; a regression guard for stage 2.
+
+- [ ] **Step 1: Write the test for `music-video`**
+
+Append to `tests/test_for_each.py`:
+
+```python
+import json
+import os
+
+TEMPLATES = os.path.join(
+    os.path.dirname(__file__), "..", "workflows", "templates", "minimax"
+)
+
+
+def load_template(name):
+    with open(os.path.join(TEMPLATES, name)) as f:
+        return json.load(f)
+
+
+def steps_by_name(definition):
+    return {s["name"]: s for s in definition["steps"]}
+
+
+def without_pipeline_reference(step, pipeline_step):
+    """A hand-written 'pipeline_reference' shot as the full pipeline block
+    the expansion produces: the reference's arguments over the referenced
+    step's pipeline."""
+    rebuilt = {k: v for k, v in step.items() if k != "pipeline_reference"}
+    pipeline = copy.deepcopy(pipeline_step["pipeline"])
+    pipeline["arguments"] = step["pipeline_reference"]["arguments"]
+    rebuilt["pipeline"] = pipeline
+    return rebuilt
+
+
+class TestMusicVideoTemplate:
+    """music-video's four slices and four shots, written as two for_each
+    groups over one 'shots' list, expand to the steps the template holds
+    by hand today."""
+
+    def test_the_hand_written_shots_are_what_the_list_expands_to(self):
+        template = load_template("music-video.json")
+        today = steps_by_name(template)
+        shots = [
+            {"name": "wide_open", "prompt": "variable:shot_1_wide_open", "start_frame": 0},
+            {"name": "closeup", "prompt": "variable:shot_2_closeup", "start_frame": 124},
+            {"name": "room", "prompt": "variable:shot_3_room", "start_frame": 248},
+            {"name": "finale", "prompt": "variable:shot_4_finale", "start_frame": 372},
+        ]
+        slice_template = copy.deepcopy(today["slice_1"])
+        slice_template["name"] = "slice"
+        slice_template["for_each"] = shots
+        slice_template["task"]["arguments"]["start_frame"] = "item:start_frame"
+
+        shot_template = copy.deepcopy(today["shot_1_wide_open"])
+        shot_template["name"] = "shot"
+        shot_template["for_each"] = shots
+        shot_template["pipeline"]["arguments"]["prompt"] = "item:prompt"
+        for reference in shot_template["pipeline"]["arguments"]["references"]:
+            if reference.get("from_previous_result") == "slice_1":
+                reference["from_previous_result"] = "slice"
+
+        edit = copy.deepcopy(today["edit"])
+        edit["task"]["arguments"]["videos"] = "gather:shot"
+
+        expanded = expand_for_each(
+            definition(
+                today["draw_singer"], today["write_song"], slice_template,
+                today["soundtrack"], shot_template, edit, today["music_video"],
+            )
+        )
+        got = steps_by_name(expanded)
+
+        # Each expanded slice is today's slice with the new name
+        for key, old in zip(["wide_open", "closeup", "room", "finale"], range(1, 5)):
+            expected = copy.deepcopy(today[f"slice_{old}"])
+            expected["name"] = f"slice@{key}"
+            assert got[f"slice@{key}"] == expected
+
+        # Each expanded shot is today's shot (as a full pipeline block) with
+        # the new name and its slice renamed
+        hand_written = ["shot_1_wide_open", "shot_2_closeup", "shot_3_room", "shot_4_finale"]
+        for key, old, index in zip(["wide_open", "closeup", "room", "finale"], hand_written, range(1, 5)):
+            step = today[old]
+            if "pipeline_reference" in step:
+                step = without_pipeline_reference(step, today["shot_1_wide_open"])
+            expected = copy.deepcopy(step)
+            expected["name"] = f"shot@{key}"
+            for reference in expected["pipeline"]["arguments"]["references"]:
+                if reference.get("from_previous_result") == f"slice_{index}":
+                    reference["from_previous_result"] = f"slice@{key}"
+            assert got[f"shot@{key}"] == expected
+
+        assert got["edit"]["task"]["arguments"]["videos"] == [
+            f"previous_result:shot@{k}" for k in ["wide_open", "closeup", "room", "finale"]
+        ]
+```
+
+- [ ] **Step 2: Run it, and adjust the test to the template's real shape**
+
+Run: `python -m pytest tests/test_for_each.py::TestMusicVideoTemplate -q`
+
+The test was written from the template as of 2026-09-11 (`slice_1..4` with `start_frame` 0/124/248/372; shots 2-4 as `pipeline_reference` to `shot_1_wide_open`; `edit.videos` the four shots). If the assertion fails on a field this plan did not anticipate (a `pipeline_reference` carrying more than `arguments`, say), read the diff pytest prints and fix the *test's* reconstruction so it mirrors the template - the expansion is not to be bent to a template. If it fails because the expansion is wrong, fix `dw/for_each.py`.
+
+Expected after adjustment: PASS
+
+- [ ] **Step 3: Write the test for `dialogue-short`**
+
+Append:
+
+```python
+class TestDialogueShortTemplate:
+    """dialogue-short's five shots, whose reference lists differ in length
+    by shot, written as one for_each group whose entries carry the whole
+    references list."""
+
+    def test_the_hand_written_shots_are_what_the_list_expands_to(self):
+        template = load_template("dialogue-short.json")
+        today = steps_by_name(template)
+        hand_written = [
+            ("cold_open", "shot_1_cold_open"),
+            ("deflect", "shot_2_deflect"),
+            ("react", "shot_3_react"),
+            ("button", "shot_4_button"),
+            ("tag", "shot_5_tag"),
+        ]
+        first = today["shot_1_cold_open"]
+        full = {
+            old: (step if "pipeline_reference" not in step else without_pipeline_reference(step, first))
+            for old, step in today.items()
+            if old.startswith("shot_")
+        }
+        shots = []
+        for key, old in hand_written:
+            arguments = full[old]["pipeline"]["arguments"]
+            entry = {"name": key, "prompt": arguments["prompt"], "references": arguments["references"]}
+            # Only the tag shot has its own frame count in the template
+            if arguments.get("num_frames") != first["pipeline"]["arguments"]["num_frames"]:
+                entry["num_frames"] = arguments["num_frames"]
+            shots.append(entry)
+
+        shot_template = copy.deepcopy(full["shot_1_cold_open"])
+        shot_template["name"] = "shot"
+        shot_template["for_each"] = shots
+        shot_template["pipeline"]["arguments"]["prompt"] = "item:prompt"
+        shot_template["pipeline"]["arguments"]["references"] = "item:references"
+
+        expanded = expand_for_each(
+            definition(today["draw_character_a"], today["draw_character_b"], shot_template)
+        )
+        got = steps_by_name(expanded)
+        for key, old in hand_written:
+            expected = copy.deepcopy(full[old])
+            expected["name"] = f"shot@{key}"
+            if "num_frames" not in shots[[k for k, _ in hand_written].index(key)]:
+                # The member inherits the template's frame count, which is
+                # what the hand-written shot has too
+                pass
+            got_step = got[f"shot@{key}"]
+            assert got_step["pipeline"]["arguments"]["prompt"] == expected["pipeline"]["arguments"]["prompt"]
+            assert got_step["pipeline"]["arguments"]["references"] == expected["pipeline"]["arguments"]["references"]
+```
+
+Then read `dialogue-short.json` (`python3 -c "import json; d=json.load(open('workflows/templates/minimax/dialogue-short.json')); [print(s['name'], json.dumps(s)[:600]) for s in d['steps']]"`) and extend the entry to carry every argument that differs between shots (the template's `num_frames` vs `tag_num_frames` is one; there may be others), mapping each to an `item:` in `shot_template`. The final assertion should compare the *whole* step: `assert got[f"shot@{key}"] == expected`, with `expected["name"]` set as above. Replace the two field assertions with that once the entry shape is right.
+
+- [ ] **Step 4: Run both template tests**
+
+Run: `python -m pytest tests/test_for_each.py -q`
+Expected: all PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/test_for_each.py
+git commit -m "test(for_each): music-video and dialogue-short expand back to their hand-written steps
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 4: Schema - `for_each` on a step
+
+**Files:**
+- Modify: `dw/workflow_schema.json` (the `step` definition, around line 100-135)
+- Test: `tests/test_schema.py`
+
+**Interfaces:**
+- Produces: a definition with `"for_each"` on a step validates; `for_each` accepts a list or a `variable:` string.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `tests/test_schema.py`:
+
+```python
+def test_for_each_is_a_list_or_a_variable_reference():
+    schema = load_schema("workflow")
+    base = {
+        "id": "t",
+        "steps": [{"name": "shot", "task": {"command": "x"}, "for_each": None}],
+    }
+    for good in (["a", "b"], [{"name": "a"}], "variable:shots"):
+        base["steps"][0]["for_each"] = good
+        assert validate_data_all(base, schema) == []
+    for bad in (4, "shots", {"a": 1}):
+        base["steps"][0]["for_each"] = bad
+        assert validate_data_all(base, schema) != []
+```
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `python -m pytest tests/test_schema.py::test_for_each_is_a_list_or_a_variable_reference -q`
+Expected: FAIL (the `4` and `"shots"` cases validate today because the step allows unknown keys - check: if the test passes outright, the step has no `additionalProperties: false`; the test's `bad` loop is then the failing half).
+
+- [ ] **Step 3: Add the property**
+
+In `dw/workflow_schema.json`, inside `"step": {"properties": {...}}`, after `"name"`:
+
+```json
+"for_each": {
+    "description": "Run this step once per entry of a list. A list, or a 'variable:' reference to one. Inside the step, 'item:' is the entry and 'item:field' one of its fields; a later step reads every member's result with 'gather:<step name>'. Members are named '<step name>@<entry name>' (or '@<index>' for an entry without a name), so '@' is reserved in step names.",
+    "type": ["array", "string"],
+    "pattern": "^variable:",
+    "maxItems": 32
+},
+```
+
+`"pattern"` only applies to strings and `"maxItems"` only to arrays, which is how `seed` already mixes the two on the same key.
+
+- [ ] **Step 4: Run the schema tests**
+
+Run: `python -m pytest tests/test_schema.py tests/test_configuration_schema.py -q`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/workflow_schema.json tests/test_schema.py
+git commit -m "feat(schema): for_each on a step
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 5: Wire the pass into `Workflow.run` and `validation_errors`
+
+**Files:**
+- Modify: `dw/workflow.py:286-296` (`validation_errors`), `dw/workflow.py:370-386` (the substitution block in `run`)
+- Test: `tests/test_workflow.py`
+
+**Interfaces:**
+- Consumes: `expand_for_each`, `ForEachError` from Task 1; `replace_variables`, `set_variables`, `VariableNotFoundError` from `dw/variables.py`; `argument_errors` from `dw/variables.py`.
+- Produces: `Workflow.validation_errors(self, arguments=None)` - the new keyword is what Task 6 passes; `Workflow.expanded_definition(self, arguments=None) -> dict`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/test_workflow.py` (it already imports `Workflow`/`workflow_from_definition`-style helpers - follow the file's existing pattern for constructing a workflow from a dict, e.g. the one `test_validate_catches_a_reference_to_a_step_that_does_not_exist` at line 583 uses):
+
+```python
+def _for_each_workflow(**overrides):
+    definition = {
+        "id": "fe",
+        "variables": {"shots": [{"name": "a", "text": "A"}, {"name": "b", "text": "B"}]},
+        "steps": [
+            {
+                "name": "shot",
+                "for_each": "variable:shots",
+                "task": {"command": "compose_text", "arguments": {"parts": ["item:text"]}},
+                "result": {"content_type": "text/plain"},
+            },
+            {
+                "name": "edit",
+                "task": {"command": "compose_text", "arguments": {"parts": "gather:shot"}},
+                "result": {"content_type": "text/plain"},
+            },
+        ],
+    }
+    definition.update(overrides)
+    return definition
+
+
+def test_validation_expands_for_each_before_the_reference_check(tmp_path):
+    workflow = _workflow_from(_for_each_workflow(), tmp_path)  # the file's helper
+    assert workflow.validation_errors() == []
+
+
+def test_validation_reports_a_for_each_error_at_its_path(tmp_path):
+    definition = _for_each_workflow()
+    definition["steps"][1]["task"]["arguments"]["parts"] = "previous_result:shot"
+    workflow = _workflow_from(definition, tmp_path)
+    errors = workflow.validation_errors()
+    assert len(errors) == 1
+    assert errors[0]["path"] == "steps[1].task.arguments.parts"
+    assert "gather:shot" in errors[0]["message"]
+
+
+def test_validation_expands_the_callers_list_not_the_default(tmp_path):
+    workflow = _workflow_from(_for_each_workflow(), tmp_path)
+    # Two entries share a name only in the caller's list
+    errors = workflow.validation_errors(
+        arguments={"shots": [{"name": "a"}, {"name": "a"}]}
+    )
+    assert errors and "Duplicate entry name 'a'" in errors[0]["message"]
+
+
+def test_validation_falls_back_to_the_default_when_the_arguments_are_bad(tmp_path):
+    workflow = _workflow_from(_for_each_workflow(), tmp_path)
+    # An undeclared argument is argument_errors' finding, not validation's
+    assert workflow.validation_errors(arguments={"nope": 1}) == []
+
+
+def test_validation_of_an_undeclared_variable_still_does_not_raise(tmp_path):
+    definition = _for_each_workflow()
+    definition["steps"][0]["for_each"] = "variable:missing"
+    workflow = _workflow_from(definition, tmp_path)
+    errors = workflow.validation_errors()
+    assert errors and "variable:missing" in errors[0]["message"]
+
+
+def test_run_expands_for_each_and_names_the_members(tmp_path):
+    workflow = _workflow_from(_for_each_workflow(seed=1), tmp_path)
+    workflow.run({})
+    names = [entry["step"] for entry in workflow.manifest]
+    assert names == ["shot@a", "shot@b", "edit"]
+
+
+def test_run_substitutes_the_callers_list(tmp_path):
+    workflow = _workflow_from(_for_each_workflow(seed=1), tmp_path)
+    workflow.run({"shots": [{"name": "only", "text": "X"}]})
+    names = [entry["step"] for entry in workflow.manifest]
+    assert names == ["shot@only", "edit"]
+```
+
+Check the manifest entry's key for the step name (`grep -n "manifest.append" dw/workflow.py`) and use whatever key it carries in place of `entry["step"]`.
+
+- [ ] **Step 2: Run them to verify they fail**
+
+Run: `python -m pytest tests/test_workflow.py -k "for_each" -q`
+Expected: FAIL - `validation_errors()` reports `gather:shot`/`item:` nothing but the run fails on `for_each` as an unknown step key, and `validation_errors(arguments=...)` is a TypeError.
+
+- [ ] **Step 3: Implement**
+
+In `dw/workflow.py` add the imports:
+
+```python
+from .for_each import expand_for_each, ForEachError
+from .variables import (
+    argument_errors,
+    replace_variables,
+    set_variables,
+    VariableNotFoundError,
+)
+```
+
+(merge with the existing `from .variables import replace_variables, set_variables` at line 45.)
+
+Replace `validation_errors`:
+
+```python
+    def expanded_definition(self, arguments=None):
+        """The definition as the run will see it: variables substituted -
+        the caller's `arguments` folded in when they are all good, else the
+        declared defaults - and every for_each step expanded.
+
+        Raises ForEachError for a for_each that cannot be expanded. A
+        'variable:' that names nothing is left in place rather than raised:
+        validate_workflow already reports that as a warning, and the
+        reference check is happy to skip a reference it cannot read.
+        """
+        definition = copy.deepcopy(self.workflow_definition)
+        variables = definition.get("variables")
+        if isinstance(variables, dict):
+            if arguments and not argument_errors(definition, arguments):
+                set_variables(arguments, variables)
+            try:
+                definition = replace_variables(definition, variables)
+            except VariableNotFoundError:
+                pass
+        return expand_for_each(definition)
+
+    def validation_errors(self, arguments=None):
+        """Every schema violation in the definition, as [{path, message}];
+        empty when it validates. `arguments` are the caller's, so a
+        for_each over a list the caller supplies is checked as it will run."""
+        errors = validate_data_all(self.workflow_definition, load_schema("workflow"))
+        # Only once the shape is known good: the passes below walk the
+        # steps array and a definition that fails the schema may have no
+        # such array to walk
+        if errors:
+            return errors
+        try:
+            expanded = self.expanded_definition(arguments)
+        except ForEachError as e:
+            return [{"path": e.path, "message": str(e)}]
+        return previous_result_reference_errors(expanded)
+```
+
+`set_variables` may need `realize_constants` first when a default is `constant:` - it does not for the list case, and `argument_errors` already runs `set_variables` on the raw declared block, so this mirrors it.
+
+In `run`, directly after `workflow_def = replace_variables(workflow_def, variables)` (line 386) and *outside* the `if variables is not None` block:
+
+```python
+            # One ordinary step per entry of every for_each list, before the
+            # seed, the run id and the realized workflow are computed, so
+            # each covers what actually runs. A ForEachError here fails the
+            # run before anything loads
+            workflow_def = expand_for_each(workflow_def)
+```
+
+Note: `steps = workflow_def["steps"]` (or wherever the loop reads them) must be read *after* this line - check with `grep -n "steps = " dw/workflow.py` and move the read below the expansion if it sits above.
+
+- [ ] **Step 4: Run the tests**
+
+Run: `python -m pytest tests/test_workflow.py tests/test_for_each.py tests/test_previous_results.py -q`
+Expected: PASS. The `previous_result_reference_errors` behaviour changed subtly - it now runs on the *substituted* definition, so a `from_previous_result: "variable:x"` whose variable is declared is now checked by its resolved value. If an existing test pins the old skip, read it: the skip was for a value that "is not knowable before substitution", which a declared default now is. Update the test's expectation, not the code.
+
+- [ ] **Step 5: Run the whole suite**
+
+Run: `python -m pytest tests -q -x`
+Expected: PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add dw/workflow.py tests/test_workflow.py
+git commit -m "feat(for_each): expand in Workflow.run and validate the expanded definition
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 6: The server pre-flight validates with the caller's list
+
+**Files:**
+- Modify: `dw/server/app.py:1270` (the `errors = candidate.validation_errors()` call in `validate_workflow`)
+- Test: `tests/test_validate_arguments.py`
+
+**Interfaces:**
+- Consumes: `Workflow.validation_errors(arguments=...)` from Task 5.
+
+- [ ] **Step 1: Write the failing test**
+
+Look at how `tests/test_validate_arguments.py` builds its client and posts to `/api/validate` (`grep -n "def test\|client.post" tests/test_validate_arguments.py | head`), then append in the same style:
+
+```python
+def test_validate_expands_for_each_with_the_callers_list(client):
+    workflow = {
+        "id": "fe",
+        "variables": {"shots": [{"name": "a", "text": "A"}]},
+        "steps": [
+            {
+                "name": "shot",
+                "for_each": "variable:shots",
+                "task": {"command": "compose_text", "arguments": {"parts": ["item:text"]}},
+                "result": {"content_type": "text/plain"},
+            },
+            {
+                "name": "edit",
+                "task": {"command": "compose_text", "arguments": {"parts": "gather:shot"}},
+                "result": {"content_type": "text/plain"},
+            },
+        ],
+    }
+    ok = client.post("/api/validate", json={"workflow": workflow}).json()
+    assert ok["valid"] is True
+
+    bad = client.post(
+        "/api/validate",
+        json={"workflow": workflow, "arguments": {"shots": [{"name": "x"}, {"name": "x"}]}},
+    ).json()
+    assert bad["valid"] is False
+    assert bad["errors"][0]["path"] == "steps[0].for_each[1].name"
+```
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `python -m pytest tests/test_validate_arguments.py -k for_each -q`
+Expected: FAIL - the second call answers `valid: True` because the default list was expanded.
+
+- [ ] **Step 3: Pass the arguments through**
+
+In `dw/server/app.py`, change
+
+```python
+            errors = candidate.validation_errors()
+```
+
+to
+
+```python
+            # The caller's list is the one a for_each expands over, so the
+            # pre-flight checks the step set that will actually run
+            errors = candidate.validation_errors(arguments=request.arguments)
+```
+
+- [ ] **Step 4: Run the server tests**
+
+Run: `python -m pytest tests/test_validate_arguments.py tests/test_server_jobs.py -q`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/server/app.py tests/test_validate_arguments.py
+git commit -m "feat(server): POST /api/validate expands for_each over the caller's list
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 7: Documentation - the agent-facing conventions
+
+This is how an agent learns the feature. `get_guide("workflows", section=...)` serves `docs/WORKFLOW_GUIDE.md` by heading, and the MCP instructions send an agent to "Authoring a workflow from an agent" before it writes JSON; CLAUDE.md's Type System block is the mirror the repo keeps in sync by rule.
+
+**Files:**
+- Modify: `docs/WORKFLOW_GUIDE.md` (the `### References` list at line 244, and a new subsection after `### Several \`previous_result\` references multiply`, line 318)
+- Modify: `CLAUDE.md` (the Type System bullets, after the `prompt:` bullet at line 152; the Critical Gotchas list)
+- Modify: `docs/SERVER.md` (where the manifest is described - `grep -n "manifest" docs/SERVER.md`)
+- Test: `tests/test_server_guides.py` / `tests/test_mcp_guides.py` only if they pin section names (`grep -n "Authoring\|sections" tests/test_server_guides.py`); nothing to add otherwise.
+
+- [ ] **Step 1: Add the three prefixes to the References list in `docs/WORKFLOW_GUIDE.md`**
+
+After the `prompt:` bullet (ends "rather than resolving twice."), add:
+
+```markdown
+- `item:` — only inside a step that carries `for_each`: `item:` is the
+  entry the member was made for, `item:field` one field of an object entry,
+  spliced in whole whatever its type — a string, a number, a list of
+  references. See "One step per entry" below.
+- `gather:` — `gather:shot` is the result of *every* member of the
+  `for_each` step `shot`, in list order, as one list. Inside a list it splices
+  into it. It is how a step downstream of a fan-out reads the whole group;
+  `previous_result:shot` naming a `for_each` step is an error that says so.
+```
+
+- [ ] **Step 2: Add the subsection**
+
+After the paragraph ending "the signal to restructure the workflow, not to add another reference." and before `### The loop`, add:
+
+```markdown
+### One step per entry: `for_each`
+
+A step that carries `for_each` runs once per entry of a list — a shot per
+entry of `shots` — and the list is a variable the caller supplies, so a
+six-shot episode is an argument rather than a different file.
+
+```json
+{
+  "name": "shot",
+  "for_each": "variable:shots",
+  "pipeline": {
+    "arguments": {
+      "prompt": "item:prompt",
+      "references": "item:references"
+    }
+  }
+}
+```
+
+with
+
+```json
+"shots": [
+  { "name": "wide_open", "prompt": "the band walks on, wide",
+    "references": [{ "reference_type": "…", "from_previous_result": "draw_singer" }] },
+  { "name": "closeup", "prompt": "closeup on the singer",
+    "references": [{ "reference_type": "…", "from_previous_result": "draw_singer" }] }
+]
+```
+
+and downstream
+
+```json
+{ "name": "edit",
+  "task": { "command": "concat_videos", "arguments": { "videos": "gather:shot" } } }
+```
+
+Before the run starts, the engine replaces the `for_each` step with one
+ordinary step per entry, named `shot@wide_open`, `shot@closeup` — the
+entry's `name`, or its index for an entry without one. Those are the names
+the manifest, the job's events and the gallery show, and `@` is reserved
+for them: a hand-written step name may not contain it. An entry's `name`
+must be unique in its list and match `^[a-zA-Z_][a-zA-Z0-9_-]*$`. Give
+entries names: the step cache keys on the member name, so a shot inserted
+in the middle of a named list leaves every other shot cached, while an
+indexed list shifts every later shot onto a different entry and regenerates
+it.
+
+`item:field` is the whole value of that field, so an entry can carry
+anything a step argument can — including a `references` list whose length
+differs by shot, with `from_previous_result` and `asset:` strings inside
+it. Nothing is interpolated: `"item:prompt"` is the field, `"shot: item:prompt"`
+is a literal string.
+
+Two `for_each` steps over the *same* list are paired by name: inside
+`shot@closeup`, a reference to another `for_each` step `slice` over the same
+`shots` list resolves to `slice@closeup`. That is how a shot reads the audio
+slice cut for it when slicing and generating are two steps. It is the one
+pairing the engine has; `for_each` runs over exactly one list, and there is
+no zip and no loop index.
+
+Limits: a list has at most 32 entries. `release_pipeline` on a `for_each`
+step releases after the *last* member. Each entry is a full generation, so
+quote `cost × len(list)` before running a list-driven workflow, and
+`validate_workflow` with the `arguments` you will run with: it expands your
+list, not the template's default, and reports a duplicate name or a missing
+field at the entry's path.
+```
+
+- [ ] **Step 3: Mirror in `CLAUDE.md`**
+
+After the `prompt:` bullet in Type System (line 152-156), add:
+
+```markdown
+- A step carrying `for_each` (a list, or `variable:` naming one) is expanded by
+  `expand_for_each` (`dw/for_each.py`) into one ordinary step per entry, named
+  `<step>@<entry name or index>`, immediately after `replace_variables` in
+  `Workflow.run` and, with the caller's arguments folded, in `validation_errors`.
+  Inside a member `item:` / `item:field` is the entry (any type, spliced whole);
+  a later step reads the group with `gather:<step>` (a list; splices inside a
+  list); two groups over the same list pair by key (`slice` inside `shot@x` is
+  `slice@x`). `previous_result:` naming a group is a directed error. `@` is
+  reserved in step names; entry names are validated and unique; 32 entries max;
+  `release_pipeline`/`release_models` survive on the last member only. The
+  realized workflow keeps `for_each`; the manifest names the members
+```
+
+And in Critical Gotchas, after the `previous_result:` static-check bullet:
+
+```markdown
+- **`for_each` expands before the reference check** — `validation_errors` substitutes
+  (the caller's `arguments` when they are all good, else the defaults) and expands
+  first, so `gather:` and `item:` errors carry the path of the template step
+  (`steps[0].for_each[1].name`) while a bad reference inside a member carries the
+  member's. Since substitution now precedes the check, a `from_previous_result`
+  spelled by a *declared* variable is checked by its value
+```
+
+- [ ] **Step 4: The manifest note in `docs/SERVER.md`**
+
+Find the manifest description (`grep -n "manifest" docs/SERVER.md`) and add one sentence where the manifest's step entries are described:
+
+```markdown
+A `for_each` step appears in the manifest as its members (`shot@wide_open`,
+`shot@closeup`), because the manifest records what ran; the run's
+`workflow.json` keeps the `for_each` form, because it records what was asked.
+```
+
+- [ ] **Step 5: Run the guide tests**
+
+Run: `python -m pytest tests/test_server_guides.py tests/test_mcp_guides.py tests/test_plugin_skills.py -q`
+Expected: PASS (the guide is served by heading; a new heading is a new section, nothing pins the count).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add docs/WORKFLOW_GUIDE.md CLAUDE.md docs/SERVER.md
+git commit -m "docs(for_each): the item:/gather:/for_each conventions for agents, CLAUDE.md mirror, manifest note
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 8: End-to-end on the server, then mark the proposal
+
+**Files:**
+- Modify: `docs/proposals/list-driven-steps-complete.md` (status line)
+- Test: `tests/test_server_jobs.py`
+
+**Interfaces:**
+- Consumes: everything above.
+
+- [ ] **Step 1: Write a job-level test**
+
+In `tests/test_server_jobs.py`, following the file's pattern for submitting an inline workflow and waiting for it (`grep -n "def test.*job\|/api/jobs" tests/test_server_jobs.py | head`), add a test that submits the `_for_each_workflow` from Task 5 (copy the dict - do not import from another test module) with `"arguments": {"shots": [{"name": "one", "text": "1"}, {"name": "two", "text": "2"}, {"name": "three", "text": "3"}]}` and asserts the finished job's manifest step names are `["shot@one", "shot@two", "shot@three", "edit"]` and that `edit`'s text output is `"123"` (or however `compose_text` joins - check `dw/tasks/` for its default separator and assert the actual value).
+
+- [ ] **Step 2: Run it**
+
+Run: `python -m pytest tests/test_server_jobs.py -k for_each -q`
+Expected: PASS. If the worker path fails where the direct `Workflow.run` test passed, the difference is the spawned worker's own validation (`dw/worker.py:185`, `workflow.validate()` with no arguments) - that call validates against the defaults, which is fine, because the run itself then substitutes and expands the real arguments and any ForEachError fails the job with its message.
+
+- [ ] **Step 3: Full suite**
+
+Run: `python -m pytest tests -q`
+Expected: PASS, no skips added.
+
+- [ ] **Step 4: Update the proposal status**
+
+In `docs/proposals/list-driven-steps-complete.md`, change the status line to:
+
+```markdown
+Status: **stage 1 implemented** (expansion pass, validation, schema, docs -
+`dw/for_each.py`); stages 2 and 3 (templates, catalog cost and entry shape)
+not started. Written for MCP feedback ticket T003.
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/test_server_jobs.py docs/proposals/list-driven-steps-complete.md
+git commit -m "test(for_each): a list-driven job end to end; proposal marks stage 1 done
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+## Self-review
+
+**Spec coverage:** expansion pass (T1), `item:` structured values (T1), same-key siblings (T2), `gather:` splice + errors (T2), directed errors (T2), `@` reserved + entry-name validation (T1), release flags on last member (T1), ceiling 32 (T1), schema (T4), validation ordering with folded arguments (T5, T6), realized workflow keeps `for_each` (no change needed - `realize_workflow` reads `self.workflow_definition`, which the pass never touches; stated in Global Constraints), manifest naming documented (T7), the `realize_args` check on entry objects (verified during planning: `resolve_path_references` in `dw/arguments.py:221` walks lists but leaves dicts alone, so an `asset:` inside an entry object stays a string until the member step realizes it - no exemption needed), templates expand back (T3), agent docs (T7). Cost/entry-shape in the catalog and the template rewrite are stages 2-3, deliberately out of this plan.
+
+**Placeholders:** Task 3's `dialogue-short` test asks the implementer to read the template and extend the entry - that is deliberate, because the entry shape is exactly what stage 2 has to get right and the template's argument differences are the ground truth; the assertion to converge on (`got[...] == expected`) is stated. Task 5 names the file's workflow-construction helper generically (`_workflow_from`) - use the helper `test_validate_catches_a_reference_to_a_step_that_does_not_exist` uses.
+
+**Type consistency:** `expand_for_each(definition) -> dict`, `ForEachError(path, message)` with `.path`, `member_name(group, key)`, `MAX_FOR_EACH_ENTRIES` are used identically across Tasks 1-6; `validation_errors(arguments=None)` is defined in Task 5 and called in Task 6.
diff --git a/docs/superpowers/plans/2026-09-11-list-driven-templates.md b/docs/superpowers/plans/2026-09-11-list-driven-templates.md
new file mode 100644
index 00000000..0529c3d1
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-11-list-driven-templates.md
@@ -0,0 +1,1094 @@
+# List-driven templates (for_each stage 2) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Rewrite `workflows/templates/minimax/music-video.json` and `workflows/templates/minimax/dialogue-short.json` onto one `shots` list each, so a six-shot episode is an argument rather than a different file, and move the plugin skill, docs and tests with them.
+
+**Architecture:** Stage 1 shipped `expand_for_each` (`dw/for_each.py`): a step carrying `for_each` becomes one ordinary step per entry, `item:field` splices an entry's field, `gather:<step>` reads the group. This stage (1) lets a list-valued variable's entries reference *other* variables (`"from_file": "variable:character_a_voice"`), resolved once before `realize_args`, because that is how dialogue-short's optional voices survive the move into entries; (2) teaches the catalog's shape derivation that `"videos": "gather:shot"` is a cut over a list; (3) rewrites the two templates, whose shot steps become full `pipeline` blocks (the identity-keyed pipeline cache means every member after the first reuses the loaded H3 exactly as `pipeline_reference` did); (4) rewrites the tests that hand-expanded the *old* templates, the voices test, the plugin skill and the docs.
+
+**Tech Stack:** Python 3.10, pytest, JSON workflow templates, markdown skill/docs.
+
+**Spec:** `docs/proposals/list-driven-steps-complete.md` — "Phasing" item 2, "Decided at review", and "Notes for stage 2".
+
+## Global Constraints
+
+- Every test in the suite passes: `pytest -q -x tests/` (the baseline on `develop` at faa27e1 is 3492 passed, 5 skipped). Run the full suite before every commit that touches `dw/`.
+- No engine behaviour changes beyond the two named here: nested `variable:` resolution inside list/dict variable values, and `gather:` recognised by `_cuts_together`. Nothing else in `dw/for_each.py`, `dw/variables.py` or `dw/workflow.py` changes semantics.
+- The rewritten templates must expand (`Workflow.expanded_definition()`) to the same *number* of shot steps with the same prompts, references (same order, same `from_previous_result` targets), `num_frames` and `start_frame` values the hand-written steps carried on `develop` at faa27e1 — `git show faa27e1:workflows/templates/minimax/<name>.json` is the reference.
+- Member names are `slice@<key>` / `shot@<key>` with keys `wide_open`, `closeup`, `room`, `finale` (music-video) and `cold_open`, `deflect`, `react`, `button`, `tag` (dialogue-short) — the entry names stage 1's tests already chose.
+- The catalog pins hold unchanged: `tests/test_catalog_structure.py` `EXPECTED_SHAPES` (`sequence`, `["has-audio", "identity-referenced"]`) and `COSTED` (35 / 42 minutes) for both templates.
+- `plugins/dw/skills/minimax-h3/SKILL.md` stays at or under 12288 bytes (`SKILL_SIZE_LIMIT`); it is at 11535 now, so every sentence added is paid for by one removed or tightened.
+- Security rules from CLAUDE.md apply: entry names are already validated by `validate_variable_name` in the expansion; nothing new touches the filesystem.
+- Commit trailer on every commit: `Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>`.
+- No version bump in this branch. The proposal calls for the two templates to land together, and they do; the engine version (`pyproject.toml`, `plugins/dw/.claude-plugin/plugin.json`, both `0.4.0-beta.3`) is bumped by `scripts/release.sh` from master, which is the user's call. The breaking change (the `shot_N_*` argument names are gone) is recorded in the proposal's status and in the CLAUDE.md gotcha so the next release note can quote it.
+
+---
+
+### Task 1: A list-valued variable's entries may reference other variables
+
+**Files:**
+- Modify: `dw/variables.py` (add `resolve_variable_values`; extend `undeclared_variable_references`)
+- Modify: `dw/workflow.py:300-312` (`expanded_definition`), `dw/workflow.py:337-354` (`_undeclared_variable_errors`), `dw/workflow.py:430-446` (`Workflow.run` substitution block)
+- Test: `tests/test_variables.py`, `tests/test_workflow.py`
+
+**Interfaces:**
+- Consumes: `replace_variables(data, variables)`, `VariableNotFoundError`, `set_variables`, `argument_errors` (all in `dw/variables.py`).
+- Produces: `resolve_variable_values(variables) -> dict` — a new dict in which every `"variable:<name>"` string found *inside* a list- or dict-valued variable is replaced by that variable's (already resolved) value. Scalar variable values are returned as they are, even a string that begins with `variable:` (that has always been passed through verbatim and stays so). Raises `VariableNotFoundError` for an undeclared name and `ValueError("Variable 'a' references itself through: a -> b -> a")` for a cycle. `undeclared_variable_references(definition)` now also returns references found inside list/dict values of `variables`, with paths like `variables.shots[0].references[2].from_file`. `Workflow._undeclared_variable_errors(arguments=None)` folds good caller arguments in before walking, and reports a reference inside a caller-supplied value at `arguments.<name>...` rather than `variables.<name>...`.
+
+- [ ] **Step 1: Write the failing tests for `resolve_variable_values`**
+
+Append to `tests/test_variables.py`:
+
+```python
+from dw.variables import resolve_variable_values, undeclared_variable_references
+
+
+class TestResolveVariableValues:
+    """A list-valued variable's entries may name other variables - a shot
+    entry says "from_file": "variable:character_a_voice" and one variable
+    sets the voice in every shot it speaks in."""
+
+    def test_a_reference_inside_a_list_value_is_replaced(self):
+        variables = {
+            "voice": "cast/priya.wav",
+            "shots": [{"name": "a", "references": [{"from_file": "variable:voice"}]}],
+        }
+        resolved = resolve_variable_values(variables)
+        assert resolved["shots"][0]["references"][0]["from_file"] == "cast/priya.wav"
+
+    def test_a_reference_inside_a_dict_value_is_replaced(self):
+        variables = {"n": 124, "shape": {"num_frames": "variable:n"}}
+        assert resolve_variable_values(variables)["shape"] == {"num_frames": 124}
+
+    def test_a_null_variable_resolves_to_null(self):
+        variables = {
+            "voice": None,
+            "shots": [{"references": [{"from_file": "variable:voice"}]}],
+        }
+        resolved = resolve_variable_values(variables)
+        assert resolved["shots"][0]["references"][0]["from_file"] is None
+
+    def test_a_scalar_value_that_looks_like_a_reference_is_left_alone(self):
+        variables = {"x": "variable:y", "y": 1}
+        assert resolve_variable_values(variables)["x"] == "variable:y"
+
+    def test_a_chain_resolves_through_a_referenced_list(self):
+        variables = {
+            "voice": "a.wav",
+            "refs": [{"from_file": "variable:voice"}],
+            "shots": [{"references": "variable:refs"}],
+        }
+        resolved = resolve_variable_values(variables)
+        assert resolved["shots"][0]["references"] == [{"from_file": "a.wav"}]
+
+    def test_the_input_is_not_mutated(self):
+        variables = {"voice": "a.wav", "shots": [{"from_file": "variable:voice"}]}
+        before = copy.deepcopy(variables)
+        resolve_variable_values(variables)
+        assert variables == before
+
+    def test_an_undeclared_name_is_the_usual_error(self):
+        with pytest.raises(VariableNotFoundError, match="nope"):
+            resolve_variable_values({"shots": [{"x": "variable:nope"}]})
+
+    def test_a_cycle_is_an_error_that_names_the_loop(self):
+        variables = {"a": [{"x": "variable:b"}], "b": [{"y": "variable:a"}]}
+        with pytest.raises(ValueError, match="a -> b -> a"):
+            resolve_variable_values(variables)
+
+    def test_a_self_reference_is_a_cycle(self):
+        with pytest.raises(ValueError, match="a -> a"):
+            resolve_variable_values({"a": [{"x": "variable:a"}]})
+
+
+class TestUndeclaredReferencesInsideVariableValues:
+    def test_a_reference_inside_a_list_value_is_found_with_its_path(self):
+        definition = {
+            "variables": {"shots": [{"references": [{}, {"from_file": "variable:nope"}]}]},
+            "steps": [],
+        }
+        assert undeclared_variable_references(definition) == [
+            ("variables.shots[0].references[1].from_file", "nope")
+        ]
+
+    def test_a_declared_reference_inside_a_value_is_not_reported(self):
+        definition = {
+            "variables": {"voice": None, "shots": [{"from_file": "variable:voice"}]},
+            "steps": [],
+        }
+        assert undeclared_variable_references(definition) == []
+
+    def test_a_scalar_value_beginning_with_the_prefix_is_not_a_reference(self):
+        definition = {"variables": {"x": "variable:nope"}, "steps": []}
+        assert undeclared_variable_references(definition) == []
+```
+
+Add `import copy` and `import pytest` at the top of the file if they are not already there, and make sure `VariableNotFoundError` is imported from `dw.variables`.
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `pytest tests/test_variables.py -q`
+Expected: ImportError on `resolve_variable_values`.
+
+- [ ] **Step 3: Implement `resolve_variable_values` and extend the undeclared walk**
+
+In `dw/variables.py`, after `replace_variables`:
+
+```python
+def resolve_variable_values(variables):
+    """A copy of `variables` in which every "variable:name" inside a list-
+    or dict-valued variable is replaced by that variable's value.
+
+    A list-driven step reads its entries from a variable, and an entry that
+    says "from_file": "variable:character_a_voice" is how one variable sets
+    a voice in every shot the character speaks in. replace_variables only
+    walks the definition, so those references would reach the step as the
+    literal strings; this resolves them once, before realize_args, so a
+    reference type inside an entry is a type name by the time it is loaded.
+
+    Only list and dict values are walked. A scalar value that begins with
+    "variable:" is passed through as it always was.
+
+    Raises:
+        VariableNotFoundError: a reference names nothing declared
+        ValueError: a value references itself, directly or through others
+    """
+    resolved = {}
+
+    def resolve(name, chain):
+        if name in resolved:
+            return resolved[name]
+        if name in chain:
+            loop = " -> ".join(chain[chain.index(name) :] + [name])
+            raise ValueError(f"Variable '{name}' references itself through: {loop}")
+        value = variables[name]
+        if isinstance(value, (list, dict)):
+            value = walk(value, chain + [name])
+        else:
+            value = copy.deepcopy(value)
+        resolved[name] = value
+        return value
+
+    def walk(node, chain):
+        if isinstance(node, str) and node.startswith("variable:"):
+            target = node.removeprefix("variable:")
+            if target not in variables:
+                available = ", ".join(sorted(variables.keys())) or "<none>"
+                raise VariableNotFoundError(
+                    f"Variable <{target}> not found; available variables: {available}"
+                )
+            return resolve(target, chain)
+        if isinstance(node, list):
+            return [walk(item, chain) for item in node]
+        if isinstance(node, dict):
+            return {key: walk(item, chain) for key, item in node.items()}
+        return copy.deepcopy(node)
+
+    for name in variables:
+        resolve(name, [])
+    return resolved
+```
+
+In `undeclared_variable_references`, replace the final loop so list/dict variable values are walked too:
+
+```python
+    for key, value in definition.items():
+        if key != "variables":
+            walk(value, key)
+    if isinstance(declared, dict):
+        for name, value in declared.items():
+            if isinstance(value, (list, dict)):
+                walk(value, f"variables.{name}")
+    return found
+```
+
+and update its docstring: "Walks everything but `variables` itself, the way resolution does" becomes "Walks everything but `variables` itself, plus the inside of every list- or dict-valued variable, the way `resolve_variable_values` and `replace_variables` together do."
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `pytest tests/test_variables.py -q`
+Expected: PASS.
+
+- [ ] **Step 5: Write the failing workflow-level tests**
+
+Append to `tests/test_workflow.py` (it already has `_for_each_workflow(**overrides)` and `_workflow_from(definition, tmp_path)`; reuse them):
+
+```python
+def test_an_entry_may_reference_another_variable(tmp_path):
+    """A shot entry's "from_file": "variable:voice" is the voice variable's
+    value by the time the member exists."""
+    definition = _for_each_workflow()
+    definition["variables"]["voice"] = "cast/priya.wav"
+    definition["variables"]["shots"] = [
+        {"name": "a", "text": "one", "voice": "variable:voice"}
+    ]
+    definition["steps"][0]["task"]["arguments"]["voice"] = "item:voice"
+    workflow = _workflow_from(definition, tmp_path)
+
+    expanded = workflow.expanded_definition()
+
+    assert expanded["steps"][0]["task"]["arguments"]["voice"] == "cast/priya.wav"
+
+
+def test_an_undeclared_reference_inside_a_default_entry_is_a_validation_error(
+    tmp_path,
+):
+    definition = _for_each_workflow()
+    definition["variables"]["shots"] = [{"name": "a", "text": "variable:nope"}]
+    workflow = _workflow_from(definition, tmp_path)
+
+    errors = workflow.validation_errors()
+
+    assert [e["path"] for e in errors] == ["variables.shots[0].text"]
+    assert "names no declared variable" in errors[0]["message"]
+
+
+def test_an_undeclared_reference_inside_a_caller_s_entry_is_reported_under_arguments(
+    tmp_path,
+):
+    workflow = _workflow_from(_for_each_workflow(), tmp_path)
+
+    errors = workflow.validation_errors(
+        arguments={"shots": [{"name": "a", "text": "variable:nope"}]}
+    )
+
+    assert [e["path"] for e in errors] == ["arguments.shots[0].text"]
+
+
+def test_a_caller_s_entry_may_reference_a_declared_variable(tmp_path):
+    definition = _for_each_workflow()
+    definition["variables"]["voice"] = None
+    workflow = _workflow_from(definition, tmp_path)
+
+    errors = workflow.validation_errors(
+        arguments={"shots": [{"name": "a", "text": "variable:voice"}]}
+    )
+
+    assert errors == []
+```
+
+Read `_for_each_workflow` first (`tests/test_workflow.py:622`) to confirm the step is a `task` step whose arguments include `"text": "item:text"`; if its field is named differently, use that name in place of `text` above.
+
+- [ ] **Step 6: Run them to verify they fail**
+
+Run: `pytest tests/test_workflow.py -q -k "entry"`
+Expected: the first fails with the literal `variable:voice` string surviving; the undeclared ones fail with an empty error list or the wrong path.
+
+- [ ] **Step 7: Wire resolution into the workflow**
+
+In `dw/workflow.py`, import `resolve_variable_values` alongside the other `.variables` imports.
+
+`expanded_definition` — replace the substitution block:
+
+```python
+        definition = copy.deepcopy(self.workflow_definition)
+        variables = definition.get("variables")
+        if isinstance(variables, dict):
+            if arguments and not argument_errors(definition, arguments):
+                set_variables(arguments, variables)
+            variables = resolve_variable_values(variables)
+            definition = replace_variables(definition, variables)
+        return expand_for_each(definition, source_indices)
+```
+
+`validation_errors` — pass the arguments through: `return self._undeclared_variable_errors(arguments)`.
+
+`_undeclared_variable_errors` — take and fold the arguments:
+
+```python
+    def _undeclared_variable_errors(self, arguments=None):
+        """Every 'variable:' reference naming nothing the workflow declares.
+
+        Fatal rather than a warning: once a workflow has a 'variables'
+        block, replace_variables refuses an undeclared reference, so this is
+        a run that cannot start. Good caller `arguments` are folded in first,
+        and a reference inside one of them is reported under `arguments.`,
+        where the caller wrote it.
+        """
+        definition = copy.deepcopy(self.workflow_definition)
+        variables = definition.get("variables")
+        supplied = set()
+        if isinstance(variables, dict) and arguments:
+            if not argument_errors(definition, arguments):
+                set_variables(arguments, variables)
+                supplied = set(arguments)
+        declared = sorted(variables or {})
+
+        def where(path):
+            head, _, rest = path.partition(".")
+            if head == "variables":
+                name = rest.split(".", 1)[0].split("[", 1)[0]
+                if name in supplied:
+                    return "arguments." + rest
+            return path
+
+        return [
+            {
+                "path": where(path),
+                "message": (
+                    f"'variable:{name}' names no declared variable; "
+                    f"declared: {', '.join(declared) or '<none>'}"
+                ),
+            }
+            for path, name in undeclared_variable_references(definition)
+        ]
+```
+
+`Workflow.run` — resolve before `realize_args`, so a `reference_type` inside an entry is a type name when the realizer reaches it:
+
+```python
+                set_variables(arguments, variables)
+                # an entry of a list-valued variable may name another
+                # variable; resolve those before anything inside it is
+                # realized, so a reference type in an entry is a type name
+                variables = resolve_variable_values(variables)
+                # realize the variables, initialiting downloads of images etc
+                realize_args(variables, base_dir)
+```
+
+Check the two later uses of `variables` in that function (the realized-workflow write and the seed) still read the resolved dict — `realize_workflow` takes `arguments` and re-folds them itself, so nothing else changes. Also open `dw/realize.py:75-93` and confirm it does not need resolution: it writes the variables as declared, with the run's arguments folded, and a nested `variable:` string there is right — a rerun resolves it again.
+
+- [ ] **Step 8: Run the tests and the full suite**
+
+Run: `pytest tests/test_workflow.py tests/test_variables.py -q` then `pytest -q -x tests/`
+Expected: PASS; full suite green.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add dw/variables.py dw/workflow.py tests/test_variables.py tests/test_workflow.py
+git commit -m "feat(variables): an entry of a list-valued variable may reference another variable
+
+Resolved once before realize_args, reported as undeclared at the entry's
+path, cycles refused. This is how a for_each template's optional voice
+variable reaches every shot the character speaks in.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 2: The catalog sees a `gather:` concat as a cut over a list
+
+**Files:**
+- Modify: `dw/server/catalog_shape.py:160-183` (`_cuts_together`)
+- Test: `tests/test_catalog_shape.py`
+
+**Interfaces:**
+- Consumes: `derive_catalog_metadata(definition)`, the test file's `definition`, `pipeline_step`, `task_step` helpers.
+- Produces: `_cuts_together` returns True for `"videos": "gather:<step>"` exactly as it does for `"videos": "variable:<name>"`.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `tests/test_catalog_shape.py`, next to `test_a_concat_fed_by_two_steps_is_a_sequence`:
+
+```python
+def test_a_concat_over_a_gathered_for_each_group_is_a_sequence():
+    """A list-driven template's editor says "videos": "gather:shot" - a
+    cut over as many shots as the list holds, which the file cannot count."""
+    meta = derive_catalog_metadata(
+        definition(
+            {
+                "name": "shot",
+                "for_each": "variable:shots",
+                "pipeline": {
+                    "arguments": {"prompt": "item:prompt"},
+                },
+                "result": {"content_type": "video/mp4"},
+            },
+            task_step("cut", "concat_videos", {"videos": "gather:shot"}, "video/mp4"),
+        )
+    )
+    assert meta["shape"] == "sequence"
+```
+
+Read the file's `pipeline_step` helper first; if it can produce a step with a `for_each` key, use it instead of the literal dict, so the test reads like its neighbours.
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `pytest tests/test_catalog_shape.py -q -k gathered`
+Expected: FAIL, shape is `shot`.
+
+- [ ] **Step 3: Recognise the prefix**
+
+In `_cuts_together`, change the string check and its docstring:
+
+```python
+    """A concat or dissolve fed by two or more distinct steps, or by a list
+    of shots handed in whole - one `variable:` reference is a supplied list
+    whose length only the caller knows, one `gather:` reference is every
+    member of a for_each group, and a cut over either is still an edit."""
+    ...
+            if isinstance(videos, str) and videos.startswith(("variable:", "gather:")):
+                return True
+```
+
+- [ ] **Step 4: Run the catalog tests**
+
+Run: `pytest tests/test_catalog_shape.py tests/test_catalog_structure.py -q`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/server/catalog_shape.py tests/test_catalog_shape.py
+git commit -m "fix(catalog): a concat over gather:<step> derives sequence
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: `music-video` on a `shots` list
+
+**Files:**
+- Modify: `workflows/templates/minimax/music-video.json`
+- Modify: `tests/test_for_each.py` (`TestMusicVideoTemplate`, lines 630-712)
+- Modify: `workflows/templates/minimax/README.md:136` (the table row)
+
+**Interfaces:**
+- Consumes: `expand_for_each`, `Workflow.expanded_definition()` (Task 1), `resolve_variable_values`.
+- Produces: the template's `variables.shots`, a list of four `{name, prompt, start_frame}` entries; steps `draw_singer`, `write_song`, `slice` (for_each), `soundtrack`, `shot` (for_each), `edit`, `music_video`.
+
+- [ ] **Step 1: Rewrite the template**
+
+Start from the file as it is. Changes, in order:
+
+1. In `variables`: delete `shot_1_wide_open`, `shot_2_closeup`, `shot_3_room`, `shot_4_finale`. In their place (after `audio_duration`) add:
+
+```json
+        "shots": [
+            {
+                "name": "wide_open",
+                "start_frame": 0,
+                "prompt": "<the exact string that was variables.shot_1_wide_open>"
+            },
+            {
+                "name": "closeup",
+                "start_frame": 124,
+                "prompt": "<the exact string that was variables.shot_2_closeup>"
+            },
+            {
+                "name": "room",
+                "start_frame": 248,
+                "prompt": "<the exact string that was variables.shot_3_room>"
+            },
+            {
+                "name": "finale",
+                "start_frame": 372,
+                "prompt": "<the exact string that was variables.shot_4_finale>"
+            }
+        ],
+```
+
+Move each prompt string byte-for-byte (copy the JSON string literal, escapes and all); do not retype it.
+
+2. Replace the four `slice_N` steps with one:
+
+```json
+        {
+            "name": "slice",
+            "for_each": "variable:shots",
+            "task": {
+                "command": "slice_audio",
+                "arguments": {
+                    "audio": "previous_result:write_song",
+                    "sample_rate": "variable:sample_rate",
+                    "start_frame": "item:start_frame",
+                    "num_frames": "variable:num_frames",
+                    "fps": "variable:fps"
+                }
+            }
+        },
+```
+
+3. Keep `soundtrack` as it is.
+
+4. Replace `shot_1_wide_open` and the three `pipeline_reference` steps with one step: the full `shot_1_wide_open` step, renamed `shot`, with `"for_each": "variable:shots"` inserted directly after `"name"`, `"prompt": "item:prompt"`, and the audio reference's `"from_previous_result": "slice_1"` changed to `"from_previous_result": "slice"`. Everything else in the block (configuration, quantization, components, loras, `num_frames`, `width`, `height`, `num_inference_steps`, `output`, `result`) stays exactly as it was.
+
+5. In `edit`, replace the four-element `videos` list with `"videos": "gather:shot"`.
+
+6. Rewrite `description` (one string; keep the catalog `summary`-less form the file has — it has no `summary`, so the first sentence is the summary):
+
+```
+A music video built from cuts, sung to a soundtrack that never touches a chain. The long-take way to film a song - one chained generation lip-synced end to end - degrades with every carried segment and can let the sync slip. This builds the video the way music television does instead: MiniMax-Music3 writes the song, one 'slice_audio' step per entry of 'shots' cuts it into frame-exact pieces (124 frames at 24 fps each, from each entry's 'start_frame'), and one shot per entry is generated fresh from the same Z-Image portrait plus its own slice, lip-synced to just those five seconds. 'shots' is a list, so the cut is an argument: add an entry and there is one more slice and one more shot, named for it ('slice@closeup', 'shot@closeup'), and the loaded model is reused across every shot - identical pipeline definitions share one model. No shot conditions on another shot's output, so the last cut is as clean as the first. 'concat_videos' gathers the shots in list order, and because each one covered exactly its slice's frames, the edit is sample-accurate by construction: 'pair_audio' drops the original, unbroken song over the whole cut and the mouths line up in every shot. The generation models pass through one at a time - each is released before the next loads - so the workflow peaks no higher than its largest single model.
+```
+
+- [ ] **Step 2: Validate the file the way the CLI does**
+
+Run: `python -m dw.validate workflows/templates/minimax/music-video.json`
+Expected: valid, no errors. Then `python -c "import json; json.load(open('workflows/templates/minimax/music-video.json'))"` to be sure the edit left valid JSON.
+
+- [ ] **Step 3: Replace `TestMusicVideoTemplate`**
+
+Delete the class at `tests/test_for_each.py:630-712` and write in its place:
+
+```python
+class TestMusicVideoTemplate:
+    """music-video's slices and shots are two for_each groups over one
+    'shots' list, paired by entry name: shot@closeup reads slice@closeup."""
+
+    KEYS = ["wide_open", "closeup", "room", "finale"]
+
+    def expanded(self):
+        from dw.workflow import Workflow
+
+        return Workflow(load_template("music-video.json"), TEMPLATES).expanded_definition()
+
+    def test_the_template_validates_as_it_will_run(self):
+        from dw.workflow import Workflow
+
+        assert Workflow(load_template("music-video.json"), TEMPLATES).validation_errors() == []
+
+    def test_one_slice_and_one_shot_per_entry_in_list_order(self):
+        names = [s["name"] for s in self.expanded()["steps"]]
+        assert names == (
+            ["draw_singer", "write_song"]
+            + [f"slice@{k}" for k in self.KEYS]
+            + ["soundtrack"]
+            + [f"shot@{k}" for k in self.KEYS]
+            + ["edit", "music_video"]
+        )
+
+    def test_each_slice_starts_where_its_entry_says(self):
+        got = steps_by_name(self.expanded())
+        starts = [got[f"slice@{k}"]["task"]["arguments"]["start_frame"] for k in self.KEYS]
+        assert starts == [0, 124, 248, 372]
+
+    def test_each_shot_reads_its_own_slice_and_the_one_portrait(self):
+        got = steps_by_name(self.expanded())
+        for key in self.KEYS:
+            references = got[f"shot@{key}"]["pipeline"]["arguments"]["references"]
+            assert [r["from_previous_result"] for r in references] == [
+                "draw_singer",
+                f"slice@{key}",
+            ]
+
+    def test_each_shot_carries_its_entry_s_prompt(self):
+        template = load_template("music-video.json")
+        got = steps_by_name(self.expanded())
+        for entry in template["variables"]["shots"]:
+            prompt = got[f"shot@{entry['name']}"]["pipeline"]["arguments"]["prompt"]
+            assert prompt == entry["prompt"]
+            assert prompt.startswith("subject_definitions:")
+
+    def test_every_shot_is_the_same_pipeline(self):
+        """Full pipeline blocks rather than pipeline_reference: the identity
+        cache reuses the loaded model, so this costs no reload."""
+        from dw.workflow import pipeline_cache_key
+
+        got = steps_by_name(self.expanded())
+        keys = {pipeline_cache_key(got[f"shot@{k}"]["pipeline"]) for k in self.KEYS}
+        assert len(keys) == 1
+
+    def test_the_edit_gathers_the_shots_in_order(self):
+        got = steps_by_name(self.expanded())
+        assert got["edit"]["task"]["arguments"]["videos"] == [
+            f"previous_result:shot@{k}" for k in self.KEYS
+        ]
+
+    def test_the_realized_file_keeps_the_list(self):
+        """workflow.json beside a run is the source form: 'for_each' and the
+        'shots' variable, not the expanded members."""
+        template = load_template("music-video.json")
+        assert "shots" in template["variables"]
+        assert [s["name"] for s in template["steps"] if "for_each" in s] == ["slice", "shot"]
+```
+
+Check `Workflow.__init__`'s signature (`dw/workflow.py`, `class Workflow`) before writing: if it takes `(workflow_definition, base_dir, ...)` in a different order or by keyword, match it. If the file's `without_pipeline_reference` helper is now unused by any test, delete it.
+
+- [ ] **Step 4: Run the tests**
+
+Run: `pytest tests/test_for_each.py tests/test_examples.py tests/test_catalog_structure.py tests/test_plugin_skills.py -q`
+Expected: PASS. If `test_example_type_references_resolve` complains about a `*_type` inside `shots`, read its skip rules (`tests/test_examples.py:135-160`) — a `variable:`-prefixed value is skipped; the music-video entries carry no `*_type` keys, so this should not fire.
+
+- [ ] **Step 5: Update the README row**
+
+`workflows/templates/minimax/README.md:136` becomes:
+
+```
+| [music-video.json](music-video.json) | A music video cut to a generated song, one `shots` list driving both `for_each` groups: `slice_audio` deals each entry its frame-exact piece, the shot lip-syncs to it, and `pair_audio` lays the unbroken track over the finished edit |
+```
+
+- [ ] **Step 6: Full suite and commit**
+
+Run: `pytest -q -x tests/`
+Expected: green.
+
+```bash
+git add workflows/templates/minimax/music-video.json tests/test_for_each.py workflows/templates/minimax/README.md
+git commit -m "feat(templates): music-video's slices and shots are two for_each groups over one shots list
+
+Breaking for scripted callers: shot_1_wide_open .. shot_4_finale are
+entries of 'shots' now, each {name, prompt, start_frame}.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 4: `dialogue-short` on a `shots` list
+
+**Files:**
+- Modify: `workflows/templates/minimax/dialogue-short.json`
+- Modify: `tests/test_dialogue_short_voices.py`
+- Modify: `tests/test_for_each.py` (`TestDialogueShortTemplate`, the class after `TestMusicVideoTemplate`)
+- Modify: `workflows/templates/minimax/README.md:135`
+- Modify: `tests/test_catalog_structure.py` only if a description-mentions test fails (see Step 4)
+
+**Interfaces:**
+- Consumes: Task 1's nested resolution (entries say `"from_file": "variable:character_a_voice"` and `"reference_type": "variable:subject_reference_type"`), `Workflow.expanded_definition()`, `realize_args`.
+- Produces: `variables.shots`, five `{name, prompt, references, num_frames}` entries; steps `draw_character_a`, `draw_character_b`, `shot` (for_each), `episode`. The variables `shot_1_cold_open` … `shot_5_tag`, `num_frames` and `tag_num_frames` are gone; `character_a_voice` / `character_b_voice`, the two `*_reference_type` variables and everything else stay.
+
+- [ ] **Step 1: Rewrite the template**
+
+1. In `variables`, delete `shot_1_cold_open` … `shot_5_tag`, `num_frames` and `tag_num_frames`. After `character_b_portrait_prompt` add `shots`. Each entry's `references` is the reference list its hand-written step carried, verbatim; each `prompt` is the string moved byte-for-byte from the deleted variable:
+
+```json
+        "shots": [
+            {
+                "name": "cold_open",
+                "num_frames": 124,
+                "references": [
+                    {"reference_type": "variable:subject_reference_type", "from_previous_result": "draw_character_a"},
+                    {"reference_type": "variable:subject_reference_type", "from_previous_result": "draw_character_b"},
+                    {"reference_type": "variable:voice_reference_type", "from_file": "variable:character_a_voice"},
+                    {"reference_type": "variable:voice_reference_type", "from_file": "variable:character_b_voice"}
+                ],
+                "prompt": "<was variables.shot_1_cold_open>"
+            },
+            {
+                "name": "deflect",
+                "num_frames": 124,
+                "references": [
+                    {"reference_type": "variable:subject_reference_type", "from_previous_result": "draw_character_b"},
+                    {"reference_type": "variable:voice_reference_type", "from_file": "variable:character_b_voice"}
+                ],
+                "prompt": "<was variables.shot_2_deflect>"
+            },
+            {
+                "name": "react",
+                "num_frames": 124,
+                "references": [
+                    {"reference_type": "variable:subject_reference_type", "from_previous_result": "draw_character_a"},
+                    {"reference_type": "variable:voice_reference_type", "from_file": "variable:character_a_voice"}
+                ],
+                "prompt": "<was variables.shot_3_react>"
+            },
+            {
+                "name": "button",
+                "num_frames": 124,
+                "references": [
+                    {"reference_type": "variable:subject_reference_type", "from_previous_result": "draw_character_b"},
+                    {"reference_type": "variable:voice_reference_type", "from_file": "variable:character_b_voice"}
+                ],
+                "prompt": "<was variables.shot_4_button>"
+            },
+            {
+                "name": "tag",
+                "num_frames": 141,
+                "references": [
+                    {"reference_type": "variable:subject_reference_type", "from_previous_result": "draw_character_a"},
+                    {"reference_type": "variable:subject_reference_type", "from_previous_result": "draw_character_b"},
+                    {"reference_type": "variable:voice_reference_type", "from_file": "variable:character_a_voice"},
+                    {"reference_type": "variable:voice_reference_type", "from_file": "variable:character_b_voice"}
+                ],
+                "prompt": "<was variables.shot_5_tag>"
+            }
+        ],
+```
+
+Format the reference objects one key per line like the rest of the file (four-space indent); the compact form above is for reading.
+
+2. Replace `shot_1_cold_open` and the four `pipeline_reference` steps with one step: the full `shot_1_cold_open` block renamed `shot`, `"for_each": "variable:shots"` after `"name"`, and in `arguments`: `"prompt": "item:prompt"`, `"references": "item:references"`, `"num_frames": "item:num_frames"`. Everything else unchanged.
+
+3. In `episode`, `"videos": "gather:shot"`.
+
+4. Rewrite `description`:
+
+```
+A digital short built the way television is built: from cuts, not from one long take. Chained generation degrades with length - every segment conditions on the previous segment's output, so artifacts compound and identity drifts. A scene cut resets that completely: each shot here is generated fresh from the same two character portraits, so shot five is exactly as clean as shot one and the scene can run as long as the script does. Two Z-Image steps draw the cast (the second reuses the first's loaded pipeline - identical configurations share one model - and 'release_pipeline' frees it before the video model loads). The shots are one 'for_each' step over the 'shots' list: one entry per shot, carrying its 'name', its 'prompt', its 'references' and its 'num_frames' - the tag entry runs 141 frames where the others run 124, since length is per-shot. The list is an argument, so a six-shot scene is one more entry, not another file, and the members are named for their entries ('shot@react'); the loaded MiniMax-H3 is reused across all of them. Character consistency across cuts comes from referencing the same portraits in every shot; voice consistency comes from repeating each character's voice description verbatim in every prompt, and, when 'character_a_voice' / 'character_b_voice' name a clip ('asset:cast/priya.wav'), from the audio reference each entry lists for whoever speaks in it - an entry's reference says 'variable:character_a_voice', so one variable sets the voice in every shot that character has. Both default to null, and a reference whose file is null is left out of the list, so a run that names no voice generates exactly what it generated before the variables existed. A shot where both speak lists both; if that reads worse than one, name one voice and leave the other null. The variables are named for roles rather than for the cast of this example - 'character_a', the 'react' entry - because the beats are the reusable part and the sketch is not. The soundscape writes the laugh track. A final 'concat_videos' task is the editor, gathering the shots in list order into one episode - hard cuts, no trims, no seams to hide, because nothing was carried between them. Only the picture cuts hard: 'audio_bleed_ms' rings each shot's laugh track on over the silent opening of the next, the way a live audience carries across a cut. It and 'seam_fade_ms' are variables, so a seam is re-tuned with an argument rather than a copy of the workflow; 1800 ms is where a five-shot cut measured best, since a generated shot opens on more silence than it looks.
+```
+
+Keep `summary` as it is.
+
+- [ ] **Step 2: Validate**
+
+Run: `python -m dw.validate workflows/templates/minimax/dialogue-short.json`
+Expected: valid.
+
+- [ ] **Step 3: Rewrite the voices test**
+
+Replace the body of `tests/test_dialogue_short_voices.py` from `SPEAKERS` down (keep the module docstring, add one sentence to it: "The shots are entries of a list now, and an entry's voice reference names the variable, so the same one variable still sets the voice everywhere.") with:
+
+```python
+# Which character speaks in which shot - each entry lists a voice
+# reference per speaker, and this is the mapping it is asserted against
+SPEAKERS = {
+    "shot@cold_open": ("a", "b"),
+    "shot@deflect": ("b",),
+    "shot@react": ("a",),
+    "shot@button": ("b",),
+    "shot@tag": ("a", "b"),
+}
+
+
+@pytest.fixture
+def definition():
+    with open(TEMPLATE, encoding="utf-8") as file:
+        return json.load(file)
+
+
+def shot_references(definition, arguments):
+    """Every shot member's references, as the engine realizes them for a
+    run: the caller's arguments folded, entries resolved, the list expanded,
+    then each member's arguments realized as its step would."""
+    from dw.workflow import Workflow
+
+    expanded = Workflow(definition, os.path.dirname(TEMPLATE)).expanded_definition(
+        arguments
+    )
+    references = {}
+    for step in expanded["steps"]:
+        if step["name"] not in SPEAKERS:
+            continue
+        arguments = step["pipeline"]["arguments"]
+        realize_args(arguments)
+        references[step["name"]] = arguments["references"]
+    assert set(references) == set(SPEAKERS)
+    return references
+
+
+class TestOptionalVoices:
+    def test_the_voices_default_to_null(self, definition):
+        variables = definition["variables"]
+        assert variables["character_a_voice"] is None
+        assert variables["character_b_voice"] is None
+
+    def test_every_entry_names_the_voice_variables_rather_than_a_file(self, definition):
+        for entry in definition["variables"]["shots"]:
+            voices = [
+                r["from_file"] for r in entry["references"] if "from_file" in r
+            ]
+            assert voices, entry["name"]
+            assert all(v.startswith("variable:character_") for v in voices), entry["name"]
+
+    def test_no_voice_named_leaves_only_the_portraits(self, definition):
+        for name, references in shot_references(definition, {}).items():
+            assert len(references) == len(set(SPEAKERS[name])), name
+            assert all(
+                reference["from_previous_result"].startswith("draw_character")
+                for reference in references
+            ), name
+
+    def test_a_named_voice_is_referenced_in_the_shots_it_speaks_in(
+        self, definition, tmp_path
+    ):
+        from tests.test_media_info import write_wav
+
+        voice = tmp_path / "priya.wav"
+        write_wav(voice, seconds=1.0)
+
+        for name, references in shot_references(
+            definition, {"character_a_voice": str(voice)}
+        ).items():
+            built = [r for r in references if not isinstance(r, dict)]
+            assert len(built) == (1 if "a" in SPEAKERS[name] else 0), name
+
+    def test_the_tag_runs_longer(self, definition):
+        frames = {e["name"]: e["num_frames"] for e in definition["variables"]["shots"]}
+        assert frames == {
+            "cold_open": 124, "deflect": 124, "react": 124, "button": 124, "tag": 141
+        }
+
+    def test_the_variable_names_are_roles_rather_than_a_cast(self, definition):
+        """Every run carried howie_portrait_prompt and shot_3_howie_incredulous
+        through its arguments, manifest and export whatever the cast was."""
+        names = " ".join(definition["variables"]) + " ".join(
+            step["name"] for step in definition["steps"]
+        ) + " ".join(e["name"] for e in definition["variables"]["shots"])
+        assert "howie" not in names.lower()
+        assert "pat_" not in names.lower()
+        assert "character_a_portrait_prompt" in definition["variables"]
+        assert [e["name"] for e in definition["variables"]["shots"]] == [
+            "cold_open", "deflect", "react", "button", "tag"
+        ]
+```
+
+Note the realized `from_file` reference is built at variable-realization time in a real run (before expansion) and at member-realization time here; both go through `realize_object`, and a built object passes through `realize_args` unchanged, so the count is the same either way. If `realize_args` in `shot_references` fails on an already-loaded `reference_type` (a `type`, not a string), that is a bug to report as a concern, not to work around.
+
+- [ ] **Step 4: Replace `TestDialogueShortTemplate`**
+
+```python
+class TestDialogueShortTemplate:
+    """dialogue-short's five shots are one for_each group whose entries
+    carry everything that differs between shots: prompt, references and
+    length."""
+
+    KEYS = ["cold_open", "deflect", "react", "button", "tag"]
+
+    def expanded(self):
+        from dw.workflow import Workflow
+
+        return Workflow(load_template("dialogue-short.json"), TEMPLATES).expanded_definition()
+
+    def test_the_template_validates_as_it_will_run(self):
+        from dw.workflow import Workflow
+
+        assert Workflow(load_template("dialogue-short.json"), TEMPLATES).validation_errors() == []
+
+    def test_one_shot_per_entry_between_the_cast_and_the_edit(self):
+        names = [s["name"] for s in self.expanded()["steps"]]
+        assert names == (
+            ["draw_character_a", "draw_character_b"]
+            + [f"shot@{k}" for k in self.KEYS]
+            + ["episode"]
+        )
+
+    def test_each_shot_references_the_portraits_its_entry_lists(self):
+        got = steps_by_name(self.expanded())
+        portraits = {
+            key: [
+                r["from_previous_result"]
+                for r in got[f"shot@{key}"]["pipeline"]["arguments"]["references"]
+                if "from_previous_result" in r
+            ]
+            for key in self.KEYS
+        }
+        assert portraits == {
+            "cold_open": ["draw_character_a", "draw_character_b"],
+            "deflect": ["draw_character_b"],
+            "react": ["draw_character_a"],
+            "button": ["draw_character_b"],
+            "tag": ["draw_character_a", "draw_character_b"],
+        }
+
+    def test_the_reference_types_are_resolved_inside_the_entries(self):
+        """An entry's "variable:subject_reference_type" is the dotted type
+        name by the time the member exists - never the literal reference."""
+        got = steps_by_name(self.expanded())
+        for key in self.KEYS:
+            for r in got[f"shot@{key}"]["pipeline"]["arguments"]["references"]:
+                assert r["reference_type"].startswith("diffusers.modular_pipelines")
+
+    def test_the_tag_runs_longer(self):
+        got = steps_by_name(self.expanded())
+        frames = [got[f"shot@{k}"]["pipeline"]["arguments"]["num_frames"] for k in self.KEYS]
+        assert frames == [124, 124, 124, 124, 141]
+
+    def test_every_shot_is_the_same_pipeline(self):
+        from dw.workflow import pipeline_cache_key
+
+        got = steps_by_name(self.expanded())
+        assert len({pipeline_cache_key(got[f"shot@{k}"]["pipeline"]) for k in self.KEYS}) == 1
+
+    def test_the_episode_gathers_the_shots_in_order(self):
+        got = steps_by_name(self.expanded())
+        assert got["episode"]["task"]["arguments"]["videos"] == [
+            f"previous_result:shot@{k}" for k in self.KEYS
+        ]
+```
+
+- [ ] **Step 5: Run the affected tests**
+
+Run: `pytest tests/test_for_each.py tests/test_dialogue_short_voices.py tests/test_examples.py tests/test_catalog_structure.py tests/test_plugin_skills.py -q`
+Expected: PASS. If `test_a_description_names_only_variables_the_workflow_declares` fails because the description quotes `'shots'`-entry words that another workflow declares as a variable, read its allow-list at `tests/test_catalog_structure.py:210` and either reword the description or extend the list with a comment saying why; do not weaken the test.
+
+- [ ] **Step 6: Update the README row**
+
+`workflows/templates/minimax/README.md:135`:
+
+```
+| [dialogue-short.json](dialogue-short.json) | A five-shot sitcom scene: Z-Image draws the cast, one `for_each` step over a `shots` list generates a shot per entry - its prompt, its references, its length - on one loaded model, and `concat_videos` gathers the episode |
+```
+
+- [ ] **Step 7: Full suite and commit**
+
+Run: `pytest -q -x tests/`
+
+```bash
+git add workflows/templates/minimax/dialogue-short.json tests/test_dialogue_short_voices.py tests/test_for_each.py workflows/templates/minimax/README.md tests/test_catalog_structure.py
+git commit -m "feat(templates): dialogue-short's five shots are one for_each group over a shots list
+
+Breaking for scripted callers: shot_1_cold_open .. shot_5_tag, num_frames
+and tag_num_frames are entries of 'shots' now, each {name, prompt,
+references, num_frames}. An entry's voice reference names
+character_a_voice / character_b_voice, so one variable still sets a voice
+in every shot the character speaks in.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+(Drop `tests/test_catalog_structure.py` from `git add` if it was not touched.)
+
+---
+
+### Task 5: The skill, the guide, CLAUDE.md and the proposal say so
+
+**Files:**
+- Modify: `plugins/dw/skills/minimax-h3/SKILL.md` (the "A piece with cuts" bullet; size cap 12288 bytes)
+- Modify: `tests/test_plugin_skills.py` (`TestMiniMaxH3Skill`)
+- Modify: `docs/WORKFLOW_GUIDE.md` (the `### One step per entry: for_each` section, ~line 340-410)
+- Modify: `CLAUDE.md` (the `for_each` bullet in Type System, ~line 157; the `for_each` gotcha in Critical Gotchas)
+- Modify: `docs/proposals/list-driven-steps-complete.md` (status line, lines 3-5; "Notes for stage 2")
+
+**Interfaces:**
+- Consumes: the templates' new `shots` entry shapes from Tasks 3 and 4.
+- Produces: skill text an agent reads before composing; tests that pin it.
+
+- [ ] **Step 1: Write the failing skill tests**
+
+Add to `TestMiniMaxH3Skill` in `tests/test_plugin_skills.py`:
+
+```python
+    def test_the_cuts_templates_are_described_as_list_driven(self):
+        """Both cut templates take one 'shots' list; the skill says what an
+        entry carries, so an agent writes entries rather than the shot_N_*
+        arguments T005 and this rewrite removed."""
+        import json
+
+        text = skill_text(H3_SKILL)
+        assert "`shots`" in text
+        assert "shot_1_" not in text and "shot_2_" not in text
+        for name, fields in (
+            ("dialogue-short", {"name", "prompt", "references", "num_frames"}),
+            ("music-video", {"name", "prompt", "start_frame"}),
+        ):
+            path = os.path.join(
+                REPO_ROOT, "workflows", "templates", "minimax", name + ".json"
+            )
+            spec = json.load(open(path, encoding="utf-8"))
+            entries = spec["variables"]["shots"]
+            assert all(set(entry) == fields for entry in entries), name
+            for field in fields:
+                assert f"`{field}`" in text, f"the skill does not name {field}"
+        # cost scales with the list, and the listing's figure is the default's
+        assert "per shot" in text or "per entry" in text
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `pytest tests/test_plugin_skills.py -q -k list_driven`
+Expected: FAIL on `` `shots` ``.
+
+- [ ] **Step 3: Edit the skill**
+
+In `plugins/dw/skills/minimax-h3/SKILL.md`, the bullet beginning `- **A piece with cuts**:`. Replace its first two sentences
+
+```
+  `templates/minimax/dialogue-short` (Z-Image draws the cast, one loaded model
+  per shot, `concat_videos` splices) and `templates/minimax/music-video`
+  (shots cut to a generated song, lip-synced slices). A cut erases drift; the
+  last shot is as clean as the first. Write shots, not takes.
+```
+
+with
+
+```
+  `templates/minimax/dialogue-short` (Z-Image draws the cast, one shot per
+  entry of its `shots` list on one loaded model, `concat_videos` splices) and
+  `templates/minimax/music-video` (a song, one slice and one lip-synced shot
+  per entry). `shots` is one list argument: a dialogue entry is `name`,
+  `prompt`, `references` (which portraits and voices this shot uses) and
+  `num_frames`; a music-video entry is `name`, `prompt` and `start_frame`.
+  A six-shot piece is one more entry, not another file; the listing's `cost`
+  is the default list's, so quote it per shot times the entries you write.
+  A cut erases drift; the last shot is as clean as the first. Write shots,
+  not takes.
+```
+
+and later in the same bullet, change
+
+```
+  Each shot's `num_frames` is its own, so pace the
+  cut - a trailer builds by varying shot length.
+```
+
+to
+
+```
+  Each entry's `num_frames` is its own, so pace the cut.
+```
+
+Then measure: `wc -c plugins/dw/skills/minimax-h3/SKILL.md`. If over 12288, tighten elsewhere in the same bullet (the Bark/narrator sentences are the longest and can lose "Bark's presets are conversational;") until under. Do not cut a hard rule or a source.
+
+- [ ] **Step 4: Run the plugin tests**
+
+Run: `pytest tests/test_plugin_skills.py -q`
+Expected: PASS, including the size cap.
+
+- [ ] **Step 5: The guide**
+
+In `docs/WORKFLOW_GUIDE.md`, in `### One step per entry: for_each`, after the paragraph beginning "`item:field` is the whole value of that field", add:
+
+```
+An entry may name another variable: `"from_file": "variable:character_a_voice"`
+inside a `references` entry is that variable's value by the time the member
+exists, so one variable sets a voice in every shot the character speaks in
+and a caller who supplies the list still writes `variable:` for the parts the
+template fixes. Those references are resolved before anything in the entry is
+loaded, and an undeclared one is a validation error at the entry's path
+(`arguments.shots[2].references[1].from_file` when the list is yours,
+`variables.shots[...]` when it is the template's). A value may not reference
+itself, directly or through another variable.
+```
+
+And in the closing "Limits" paragraph, after "quote `cost × len(list)`", add nothing new (it already says it), but change "`validate_workflow` with the `arguments` you will run with: it expands your list, not the template's default" to "`validate_workflow` with the `arguments` you will run with: it expands your list, not the template's default, resolves the variables your entries name". Then at the end of the section, before `### The loop`, add:
+
+```
+`templates/minimax/dialogue-short` and `templates/minimax/music-video` are
+this shape: each takes one `shots` list, and `get_workflow` on either shows
+the entry an item needs.
+```
+
+- [ ] **Step 6: CLAUDE.md**
+
+In the Type System `for_each` bullet, after "two groups over the same list pair by key (`slice` inside `shot@x` is `slice@x`)." insert: "An entry of a list-valued variable may reference another variable (`"from_file": "variable:character_a_voice"`); `resolve_variable_values` (`dw/variables.py`) replaces those once, before `realize_args`, refusing a cycle, and `undeclared_variable_references` walks inside list/dict variable values too."
+
+In Critical Gotchas, add a bullet after the `for_each` one:
+
+```
+- **The two MiniMax cut templates take one `shots` list** — since the stage-2
+  rewrite (2026-09-11) `templates/minimax/dialogue-short` and `music-video`
+  have no `shot_N_*` variables; a scripted caller passes `shots` (entries
+  `{name, prompt, references, num_frames}` and `{name, prompt, start_frame}`).
+  The members are `shot@<name>` in the manifest and the gallery. This is the
+  breaking change the next release note should name
+```
+
+- [ ] **Step 7: The proposal**
+
+`docs/proposals/list-driven-steps-complete.md` lines 3-5 become:
+
+```
+Status: **stages 1 and 2 implemented** (expansion pass, validation, schema,
+docs - `dw/for_each.py`; `music-video` and `dialogue-short` on a `shots`
+list, 2026-09-11); stage 3 (catalog per-entry cost and entry shape) not
+started. Written for MCP feedback ticket T003.
+```
+
+Under "## Notes for stage 2", add a closing paragraph:
+
+```
+Resolved in stage 2: the `pipeline_reference` question went away - every
+member is the full pipeline block, and the identity-keyed pipeline cache
+reuses the loaded model exactly as the reference did (a test holds every
+member to one `pipeline_cache_key`). A group's `pipeline_reference` still
+gets no directed error; nothing bundled uses one now. Entries that name
+other variables (`variable:character_a_voice`) are resolved by
+`resolve_variable_values` before `realize_args`, which is what let the
+optional voices move into the entries. The empty-list and
+`realize_constants` questions are still open and belong to stage 3 with the
+catalog work.
+```
+
+- [ ] **Step 8: Full suite, then commit**
+
+Run: `pytest -q -x tests/`
+
+```bash
+git add plugins/dw/skills/minimax-h3/SKILL.md tests/test_plugin_skills.py docs/WORKFLOW_GUIDE.md CLAUDE.md docs/proposals/list-driven-steps-complete.md
+git commit -m "docs(for_each): the cut templates take one shots list; entries may name variables
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
diff --git a/docs/superpowers/specs/2026-09-06-agent-catalog-legibility-design.md b/docs/superpowers/specs/2026-09-06-agent-catalog-legibility-design.md
index 39df74c8..634450be 100644
--- a/docs/superpowers/specs/2026-09-06-agent-catalog-legibility-design.md
+++ b/docs/superpowers/specs/2026-09-06-agent-catalog-legibility-design.md
@@ -1,7 +1,7 @@
 # Agent catalog legibility — design
 
 Status: design, 2026-09-06. Designs Parts 1 and 2 of
-[docs/proposals/agent-catalog-legibility.md](../../proposals/agent-catalog-legibility.md)
+[docs/proposals/agent-catalog-legibility-complete.md](../../proposals/agent-catalog-legibility-complete.md)
 (Proposals 1–10). Part 3's constraint — model-specific prompting knowledge
 stays as data, never engine code — is carried in as a principle every
 section respects. Part 4 (guide-vs-Skill packaging of that knowledge) is
@@ -331,7 +331,7 @@ something composing a draft rather than a person onboarding:
 - the cartesian-product rule: several `previous_result` references on one
   step multiply; a zip-shaped pairing (shot *i* with speaker *i*) is not
   expressible this way and must be written as one step per pair — the
-  general form of the reasoning in `scripted-dialogue-and-tts.md`
+  general form of the reasoning in `scripted-dialogue-and-tts-complete.md`
 - the loop: `validate_workflow` → `save_workflow` → `run_workflow` →
   `wait_for_job` → `get_output_image`
 - the shape and trait vocabulary, and what a good `summary` says, so a
diff --git a/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md b/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md
index 1f234f82..b78b7bf2 100644
--- a/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md
+++ b/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md
@@ -2,7 +2,7 @@
 
 Date: 2026-09-06. Status: approved for planning. Grew out of the MCP capability
 discovery discussion that followed
-[docs/proposals/scripted-dialogue-and-tts.md](../../proposals/scripted-dialogue-and-tts.md),
+[docs/proposals/scripted-dialogue-and-tts-complete.md](../../proposals/scripted-dialogue-and-tts-complete.md),
 whose `generate_speech` half is already implemented.
 
 ## Goal
diff --git a/docs/superpowers/specs/2026-09-07-dw-plugin-skills-design.md b/docs/superpowers/specs/2026-09-07-dw-plugin-skills-design.md
index a8ce90e9..4843b5eb 100644
--- a/docs/superpowers/specs/2026-09-07-dw-plugin-skills-design.md
+++ b/docs/superpowers/specs/2026-09-07-dw-plugin-skills-design.md
@@ -1,7 +1,7 @@
 # dw plugin: model-family composition skills — design
 
 Package B of the Part 4 work in
-[agent-catalog-legibility.md](../../proposals/agent-catalog-legibility.md).
+[agent-catalog-legibility-complete.md](../../proposals/agent-catalog-legibility-complete.md).
 It answers the open question of how model-specific knowledge reaches an
 agent: as a Claude Code plugin of small composition skills that defer the
 prompt format to the vendors' own published text. It depends on Package A
diff --git a/docs/superpowers/specs/2026-09-07-ltx-h3-catalog-repair-design.md b/docs/superpowers/specs/2026-09-07-ltx-h3-catalog-repair-design.md
index aa5b511c..998b6aa6 100644
--- a/docs/superpowers/specs/2026-09-07-ltx-h3-catalog-repair-design.md
+++ b/docs/superpowers/specs/2026-09-07-ltx-h3-catalog-repair-design.md
@@ -1,7 +1,7 @@
 # LTX-2.5 and MiniMax H3 catalog repair — design
 
 Package A of the Part 4 work in
-[agent-catalog-legibility.md](../../proposals/agent-catalog-legibility.md).
+[agent-catalog-legibility-complete.md](../../proposals/agent-catalog-legibility-complete.md).
 It repairs what two vendor-source audits found wrong in the catalog's
 model-specific content, so that the skills in Package B
 ([2026-09-07-dw-plugin-skills-design.md](2026-09-07-dw-plugin-skills-design.md))
diff --git a/dw/for_each.py b/dw/for_each.py
new file mode 100644
index 00000000..cbfe7294
--- /dev/null
+++ b/dw/for_each.py
@@ -0,0 +1,409 @@
+"""Expand a step's 'for_each' list into one ordinary step per entry.
+
+A template that generates one shot per entry of a list is otherwise written
+the long way - 'shot_1', 'shot_2', ... each a near-copy of the one before -
+and a six-shot episode is a different file from a five-shot one. This pass
+runs on the definition after variable substitution and before the run id is
+computed (Workflow.run) and before the reference check (validation_errors),
+and produces a definition with no 'for_each' in it: every member is an
+ordinary step, so the step loop, the step cache, the manifest and the
+reference checker never learn a new reference kind.
+
+Inside a member:
+  - 'item:'       is the whole entry; 'item:field' one field of an object
+                  entry, spliced in whole whatever its type
+  - a reference to another for_each group over the SAME list resolves to
+    the member with the same key ('slice' inside 'shot@open' -> 'slice@open')
+Outside (or inside, for any other group):
+  - 'gather:shot' is the list of every member's result, as explicit
+    'previous_result:shot@<key>' strings; inside a list it splices
+  - 'previous_result:shot' naming a group is an error that says to gather
+
+Members are named '<group>@<key>' - the entry's own 'name' when it carries
+one, else its index - and '@' is reserved in every step name. Names rather
+than indexes because the step cache (dw/step_cache.py) keys on the step
+name: inserting a shot in the middle of a list must not shift every later
+member onto a different entry's cache line.
+"""
+
+import copy
+
+from .arguments import FROM_PREVIOUS_RESULT_KEY, PREVIOUS_RESULT_PREFIX
+from .security import InvalidInputError, validate_variable_name
+from .step_cache import reference_resolves_to
+from .variables import argument_errors, set_variables
+
+FOR_EACH_KEY = "for_each"
+ITEM_PREFIX = "item:"
+GATHER_PREFIX = "gather:"
+MEMBER_SEPARATOR = "@"
+# Each entry is a full generation. Stated against the step cache's bound
+# (DEFAULT_MAX_ENTRIES = 128): a run whose expanded steps exceed the cache
+# evicts its own earlier members, so this is kept well under it
+MAX_FOR_EACH_ENTRIES = 32
+# release_pipeline / release_models would drop the model after the first
+# member and reload it for the second, so they are carried onto the last one
+_LAST_MEMBER_ONLY = ("release_pipeline", "release_models")
+
+
+class ForEachError(ValueError):
+    """A for_each step that cannot be expanded, with the JSON path at fault."""
+
+    def __init__(self, path, message):
+        super().__init__(message)
+        self.path = path
+
+
+def member_name(group, key):
+    return f"{group}{MEMBER_SEPARATOR}{key}"
+
+
+def expand_for_each(definition, source_indices=None):
+    """The definition with every 'for_each' step replaced by its members.
+
+    Returns a new structure; `definition` is left as it was passed in.
+    Raises ForEachError for anything that cannot be expanded.
+
+    `source_indices`, when a list is passed, has the index of the step each
+    expanded step was written as appended to it, so a later check can report
+    an error at a path in the file the author wrote rather than at an
+    expanded index that exists nowhere. A parallel list rather than a key on
+    the step: step_data is what the step cache keys on and what the schema
+    validates, and neither may learn a new field.
+    """
+    steps = definition.get("steps") if isinstance(definition, dict) else None
+    if not isinstance(steps, list):
+        return definition
+
+    # group name -> {"keys": [...], "entries": [...]} for every group
+    # expanded so far, in step order, so a reference can only reach an
+    # earlier group - the same rule previous_result: has always had
+    groups = {}
+    expanded = []
+    for index, step in enumerate(steps):
+        if not isinstance(step, dict):
+            expanded.append(copy.deepcopy(step))
+            _record(source_indices, index)
+            continue
+        path = ("steps", index)
+        name = step.get("name")
+        if isinstance(name, str) and MEMBER_SEPARATOR in name:
+            raise ForEachError(
+                render_path(path + ("name",)),
+                f"Step name '{name}' contains '{MEMBER_SEPARATOR}', which is "
+                f"reserved for the members of a for_each step",
+            )
+        if FOR_EACH_KEY not in step:
+            expanded.append(_rewrite(step, path, groups, member=None))
+            _record(source_indices, index)
+            continue
+
+        entries = step[FOR_EACH_KEY]
+        keys = _entry_keys(entries, path + (FOR_EACH_KEY,))
+        template = {k: v for k, v in step.items() if k != FOR_EACH_KEY}
+        last = len(keys) - 1
+        for position, (key, entry) in enumerate(zip(keys, entries)):
+            member = {
+                "group": name,
+                "key": key,
+                "entry": entry,
+                "entries": entries,
+                "index": position,
+            }
+            expanded_step = _rewrite(template, path, groups, member)
+            expanded_step["name"] = member_name(name, key)
+            if position != last:
+                for flag in _LAST_MEMBER_ONLY:
+                    expanded_step.pop(flag, None)
+            expanded.append(expanded_step)
+            _record(source_indices, index)
+        groups[name] = {"keys": keys, "entries": entries}
+
+    result = {k: v for k, v in definition.items() if k != "steps"}
+    result["steps"] = expanded
+    return result
+
+
+def _record(source_indices, index):
+    if source_indices is not None:
+        source_indices.append(index)
+
+
+def _entry_keys(entries, path):
+    """The key of every entry - its 'name' when it is an object carrying
+    one, else its index - validated and unique."""
+    if not isinstance(entries, list):
+        if isinstance(entries, str) and entries.startswith("variable:"):
+            hint = f" - '{entries}' was not substituted; is the variable declared?"
+        else:
+            hint = ""
+        raise ForEachError(
+            render_path(path),
+            f"for_each must be a list, got {type(entries).__name__}{hint}",
+        )
+    if not entries:
+        raise ForEachError(
+            render_path(path),
+            "for_each over an empty list would run no steps - a workflow that "
+            "generates nothing is never what was asked for",
+        )
+    if len(entries) > MAX_FOR_EACH_ENTRIES:
+        raise ForEachError(
+            render_path(path),
+            f"for_each has {len(entries)} entries; the limit is {MAX_FOR_EACH_ENTRIES}",
+        )
+    keys = []
+    for index, entry in enumerate(entries):
+        key = str(index)
+        if isinstance(entry, dict) and "name" in entry:
+            key = entry["name"]
+            key_path = render_path(path + (index, "name"))
+            if not isinstance(key, str):
+                raise ForEachError(key_path, "An entry's name must be a string")
+            try:
+                validate_variable_name(key)
+            except InvalidInputError as e:
+                raise ForEachError(key_path, f"Invalid entry name '{key}': {e}") from e
+            if key in keys:
+                raise ForEachError(key_path, f"Duplicate entry name '{key}'")
+        keys.append(key)
+    return keys
+
+
+def _rewrite(value, path, groups, member):
+    """Rebuild `value` with item:, gather: and group references resolved.
+
+    `member` is None outside a for_each step; inside one it carries the
+    group, key and entry of the member being built.
+    """
+    if isinstance(value, dict):
+        rebuilt = {}
+        for key, item in value.items():
+            if key == FROM_PREVIOUS_RESULT_KEY and isinstance(item, str):
+                rebuilt[key] = _rewrite_reference(item, path + (key,), groups, member)
+            else:
+                rebuilt[key] = _rewrite(item, path + (key,), groups, member)
+        return rebuilt
+    if isinstance(value, list):
+        rebuilt = []
+        for index, item in enumerate(value):
+            if isinstance(item, str) and item.startswith(GATHER_PREFIX):
+                # A gather inside a list splices into it
+                rebuilt.extend(_gather(item, path + (index,), groups))
+            else:
+                rebuilt.append(_rewrite(item, path + (index,), groups, member))
+        return rebuilt
+    if isinstance(value, str):
+        if value.startswith(GATHER_PREFIX):
+            return _gather(value, path, groups)
+        if value.startswith(ITEM_PREFIX):
+            return _item(value, path, member)
+        if value.startswith(PREVIOUS_RESULT_PREFIX):
+            reference = value[len(PREVIOUS_RESULT_PREFIX) :]
+            return PREVIOUS_RESULT_PREFIX + _rewrite_reference(
+                reference, path, groups, member
+            )
+        return value
+    # A leaf is only copied where the copy is needed: inside a member, where
+    # the same template value is about to appear in every one of them.
+    # Outside, the leaf is handed back as it is - this pass runs on every run
+    # of every workflow, after realize_args has turned 'asset:' arguments
+    # into loaded images and decoded frame lists, and copying all of that
+    # would multiply the media a run holds. The 'input untouched' contract
+    # still holds because nothing here ever mutates a leaf
+    return _copy_leaf(value) if member is not None else value
+
+
+def _copy_leaf(value):
+    """A copy of a leaf, or the leaf itself when it cannot be copied.
+
+    An open handle or a live model object reaching a member is not a reason
+    to fail a run - the step cache makes the same choice for a realized
+    argument it cannot deep-copy (dw/workflow.py).
+    """
+    try:
+        return copy.deepcopy(value)
+    except Exception:
+        return value
+
+
+def _item(value, path, member):
+    if member is None:
+        raise ForEachError(
+            render_path(path), f"'{value}' is only meaningful inside a for_each step"
+        )
+    field = value[len(ITEM_PREFIX) :]
+    entry = member["entry"]
+    if field == "":
+        return _copy_leaf(entry)
+    if not isinstance(entry, dict):
+        raise ForEachError(
+            render_path(path),
+            f"'{value}' asks for a field of entry '{member['key']}' of "
+            f"for_each step '{member['group']}', which is not an object",
+        )
+    if field not in entry:
+        raise ForEachError(
+            render_path(path),
+            f"'{value}' names no field of entry '{member['key']}' of for_each "
+            f"step '{member['group']}'; it has: {sorted(entry)}",
+        )
+    return _copy_leaf(entry[field])
+
+
+def _gather(value, path, groups):
+    group = value[len(GATHER_PREFIX) :]
+    if group not in groups:
+        raise ForEachError(
+            render_path(path),
+            f"'{value}' names no earlier for_each step. "
+            f"for_each steps available here: {sorted(groups)}",
+        )
+    return [
+        PREVIOUS_RESULT_PREFIX + member_name(group, key)
+        for key in groups[group]["keys"]
+    ]
+
+
+def _rewrite_reference(reference, path, groups, member):
+    """A previous_result reference (without its prefix) as the expanded
+    definition spells it: unchanged unless it names a for_each group."""
+    if reference.startswith("variable:"):
+        return reference
+    group = next((g for g in groups if reference_resolves_to(reference, g)), None)
+    if group is None:
+        if member is not None and reference_resolves_to(reference, member["group"]):
+            raise ForEachError(
+                render_path(path),
+                f"'{reference}' names its own for_each step '{member['group']}'",
+            )
+        return reference
+    if member is not None and member["entries"] == groups[group]["entries"]:
+        # Same list: shot@open reads slice@open
+        return member_name(group, member["key"]) + reference[len(group) :]
+    where = (
+        f"from inside for_each step '{member['group']}', which runs over a different list"
+        if member is not None
+        else "from outside a for_each step"
+    )
+    raise ForEachError(
+        render_path(path),
+        f"'{reference}' names the for_each step '{group}' {where}. Use "
+        f"'{GATHER_PREFIX}{group}' for every member's result, or a reference "
+        f"from a for_each step over the same list for the same-keyed member",
+    )
+
+
+def list_fields(definition):
+    """What an entry of each list-driven variable has to carry, read off
+    the definition: for every step whose for_each is 'variable:<name>',
+    the fields its 'item:<field>' references name.
+
+    Returns {<variable>: {"fields": [...] or None, "steps": [...]}} -
+    fields sorted with 'name' first, or None when a step splices the
+    whole entry with a bare 'item:' (the entries are values, not
+    objects). A literal for_each list is not an argument and is skipped.
+    Reads the raw definition, no substitution, so the catalog and the
+    validator derive the same answer from the file as written.
+    """
+    steps = definition.get("steps") if isinstance(definition, dict) else None
+    if not isinstance(steps, list):
+        return {}
+    found = {}
+    for step in steps:
+        if not isinstance(step, dict):
+            continue
+        target = step.get(FOR_EACH_KEY)
+        if not (isinstance(target, str) and target.startswith("variable:")):
+            continue
+        variable = target.removeprefix("variable:")
+        entry = found.setdefault(variable, {"fields": set(), "steps": []})
+        entry["steps"].append(step.get("name"))
+        for value in _strings(step):
+            if not value.startswith(ITEM_PREFIX):
+                continue
+            field = value[len(ITEM_PREFIX) :]
+            if field == "":
+                entry["fields"] = None
+            elif entry["fields"] is not None:
+                entry["fields"].add(field)
+    return {
+        variable: {
+            "fields": (
+                None
+                if entry["fields"] is None
+                else ["name"] + sorted(entry["fields"] - {"name"})
+            ),
+            "steps": entry["steps"],
+        }
+        for variable, entry in found.items()
+    }
+
+
+def entry_field_warnings(definition, arguments=None):
+    """Every entry key of a list-driven variable that no step reads.
+
+    A caller who writes 'num_frame' for 'num_frames' gets the template's
+    value for the field they meant to set, in silence; this names the
+    key, at the entry it sits in, with the fields the list takes. A
+    warning rather than an error: an entry may carry a note on purpose.
+    Good `arguments` are folded in first, and a list the caller supplied
+    is reported under 'arguments.', where they wrote it.
+    """
+    if not isinstance(definition, dict):
+        return []
+    variables = definition.get("variables")
+    if not isinstance(variables, dict):
+        return []
+    variables = copy.deepcopy(variables)
+    supplied = set()
+    if arguments and not argument_errors(definition, arguments):
+        set_variables(arguments, variables)
+        supplied = set(arguments)
+    warnings = []
+    for variable, spec in list_fields(definition).items():
+        fields = spec["fields"]
+        entries = variables.get(variable)
+        if fields is None or not isinstance(entries, list):
+            continue
+        where = "arguments" if variable in supplied else "variables"
+        for index, entry in enumerate(entries):
+            if not isinstance(entry, dict):
+                continue
+            unknown = sorted(set(entry) - set(fields))
+            if not unknown:
+                continue
+            label = repr(entry["name"]) if isinstance(entry.get("name"), str) else index
+            warnings.append(
+                f"{where}.{variable}[{index}]: entry {label} carries "
+                f"{', '.join(repr(k) for k in unknown)}, which no step reads; "
+                f"entries of '{variable}' take: {', '.join(fields)}"
+            )
+    return warnings
+
+
+def _strings(value):
+    """Every string anywhere inside a JSON value, except the for_each key
+    itself."""
+    if isinstance(value, str):
+        yield value
+    elif isinstance(value, list):
+        for item in value:
+            yield from _strings(item)
+    elif isinstance(value, dict):
+        for key, item in value.items():
+            if key != FOR_EACH_KEY:
+                yield from _strings(item)
+
+
+def render_path(path):
+    """'steps[3].task.arguments.videos[1]' - the same shape schema errors use."""
+    rendered = ""
+    for part in path:
+        if isinstance(part, int):
+            rendered += f"[{part}]"
+        elif rendered:
+            rendered += f".{part}"
+        else:
+            rendered = str(part)
+    return rendered
diff --git a/dw/pipeline_processors/pipeline.py b/dw/pipeline_processors/pipeline.py
index d7ec53e3..8aeb29ae 100644
--- a/dw/pipeline_processors/pipeline.py
+++ b/dw/pipeline_processors/pipeline.py
@@ -506,23 +506,35 @@ def _call_pipeline(self, arguments, attn_backend):
                 stack.enter_context(attention_backend(attn_backend))
 
             stack.enter_context(stateful_cache_context(self.pipeline))
+            if not self._takes_step_callback():
+                # A modular pipeline takes no step callback at all, so this
+                # is the only per-step signal it has: the denoise blocks
+                # drive a tqdm bar, and a bar that reports each advance is
+                # the difference between a slow run and a hung one
+                stack.enter_context(reported_progress_bars(self.pipeline))
 
             return self.pipeline(**arguments)
 
+    def _takes_step_callback(self):
+        """Whether this pipeline names `callback_on_step_end` in its own
+        signature. Only a pipeline that names the parameter explicitly gets
+        one - a **kwargs signature is no promise the pipeline honors it, and
+        a ModularPipeline (H3, LTX-2, Qwen-Image) has no such parameter at
+        all, which is why it needs the progress-bar route instead."""
+        try:
+            parameters = inspect.signature(self.pipeline.__call__).parameters
+        except (TypeError, ValueError):
+            return False
+        return "callback_on_step_end" in parameters
+
     def _with_step_callback(self, arguments):
         """Inject a callback_on_step_end that reports per-step progress to the
         active run context and raises when the run has been cancelled.
 
         Workflow JSON cannot express a callable, so this is the only way a
-        diffusion-step callback ever reaches a pipeline call. Only pipelines
-        that name the parameter explicitly get one - a **kwargs signature is
-        no promise the pipeline honors it.
+        diffusion-step callback ever reaches a pipeline call.
         """
-        try:
-            parameters = inspect.signature(self.pipeline.__call__).parameters
-        except (TypeError, ValueError):
-            return arguments
-        if "callback_on_step_end" not in parameters:
+        if not self._takes_step_callback():
             return arguments
 
         run_context = get_context()
@@ -1750,6 +1762,144 @@ def get_cache_transformer(pipeline):
     return None
 
 
+class _ReportingProgressBar:
+    """A tqdm bar that also reports each advance to the active run.
+
+    Wraps rather than subclasses, because the bar it wraps is whatever the
+    block's own progress_bar() built - tqdm, or a notebook bar, or whatever
+    a future diffusers uses. Everything it does not intercept falls through
+    to the real bar, so the terminal output is unchanged.
+    """
+
+    def __init__(self, bar, on_advance, total=None):
+        self._bar = bar
+        self._on_advance = on_advance
+        # Counted here rather than read off the bar: a disabled tqdm - which
+        # is what a quiet server or a notebook config leaves you with - keeps
+        # its own `n` at zero while still being advanced normally
+        self._done = 0
+        self._total = total if total is not None else getattr(bar, "total", None)
+
+    def update(self, n=1):
+        result = self._bar.update(n)
+        self._done += n or 0
+        self._on_advance(self._done, self._total)
+        return result
+
+    def __iter__(self):
+        # Reported after the body of the loop has run, not before it: the
+        # step is finished when control comes back here
+        for item in self._bar:
+            yield item
+            self._done += 1
+            self._on_advance(self._done, self._total)
+
+    def __enter__(self):
+        self._bar.__enter__()
+        return self
+
+    def __exit__(self, *exception):
+        return self._bar.__exit__(*exception)
+
+    def __getattr__(self, name):
+        # Guarded: the wrapped bar is the first thing __init__ sets, and an
+        # unguarded lookup of it before then recurses forever
+        if name == "_bar":
+            raise AttributeError(name)
+        return getattr(self._bar, name)
+
+
+def _progress_bar_holders(pipeline):
+    """Every object under a modular pipeline that can open a progress bar.
+
+    The denoise loop is a block, not the pipeline, and it calls its own
+    `self.progress_bar(...)` - so the tree is what has to be walked. Uses
+    `_blocks`, not the public `blocks`, which hands back a deepcopy: patching
+    a copy would report nothing and look like this never worked.
+    """
+    holders = []
+    seen = set()
+
+    def walk(candidate):
+        if candidate is None or id(candidate) in seen:
+            return
+        seen.add(id(candidate))
+        # __dict__, because the patch is an instance attribute: an object
+        # with none could not be patched and must not be tried
+        if callable(getattr(candidate, "progress_bar", None)) and hasattr(
+            candidate, "__dict__"
+        ):
+            holders.append(candidate)
+        children = getattr(candidate, "sub_blocks", None)
+        if hasattr(children, "values"):
+            for child in children.values():
+                walk(child)
+
+    walk(pipeline)
+    walk(getattr(pipeline, "_blocks", None))
+    return holders
+
+
+@contextlib.contextmanager
+def reported_progress_bars(pipeline):
+    """Report each denoise step of a pipeline that takes no step callback.
+
+    A ModularPipeline - H3, LTX-2, Qwen-Image and every family diffusers has
+    moved over - has no `callback_on_step_end` parameter, so the whole
+    denoise loop passed in silence: one 'generating' phase, then nothing for
+    however many minutes it took, which reads exactly like a hung run. What
+    those blocks do have is a tqdm bar, and every advance of it is a step.
+
+    The patch is per-instance and undone on the way out, so a pipeline this
+    process keeps loaded is handed back as it was found.
+    """
+    holders = _progress_bar_holders(pipeline)
+    if not holders:
+        yield
+        return
+
+    run_context = get_context()
+
+    def on_advance(done, total):
+        run_context.emit("pipeline_step", step=done, total_steps=total)
+        # Past the last step there is still the decode, which on video is
+        # minutes with the bar sitting at 100%
+        if done is not None and total is not None and done >= total:
+            emit_phase("decoding")
+        # The one cancellation checkpoint inside a modular denoise loop:
+        # without it a cancel waits out the whole generation
+        run_context.check_cancelled()
+
+    patched = []
+    for holder in holders:
+        original = holder.progress_bar
+        # Whether the name was already an attribute of the instance decides
+        # how it is put back: restored, or removed so the class method shows
+        # through again rather than a bound copy of it being frozen on
+        patched.append((holder, original, "progress_bar" in vars(holder)))
+
+        def reporting(iterable=None, total=None, _original=original):
+            bar = _original(iterable=iterable, total=total)
+            if total is None and iterable is not None:
+                # An iterated bar's total is the length of what it iterates,
+                # when that can be known at all
+                total = getattr(bar, "total", None)
+            return _ReportingProgressBar(bar, on_advance, total)
+
+        holder.progress_bar = reporting
+    try:
+        yield
+    finally:
+        for holder, original, was_own in patched:
+            if was_own:
+                holder.progress_bar = original
+            else:
+                try:
+                    del holder.progress_bar
+                except AttributeError:
+                    holder.progress_bar = original
+
+
 @contextlib.contextmanager
 def stateful_cache_context(pipeline):
     """Provide the context a stateful cache hook reads its state through.
diff --git a/dw/previous_results.py b/dw/previous_results.py
index 14619298..3a093f37 100644
--- a/dw/previous_results.py
+++ b/dw/previous_results.py
@@ -6,6 +6,7 @@
     PREVIOUS_RESULT_PREFIX,
     build_objects,
 )
+from .for_each import MEMBER_SEPARATOR, render_path
 from .step_cache import reference_resolves_to
 
 logger = logging.getLogger("dw")
@@ -308,7 +309,7 @@ def _not_found(previous_results, previous_result_name):
     return KeyError(message)
 
 
-def previous_result_reference_errors(workflow_definition):
+def previous_result_reference_errors(workflow_definition, source_indices=None):
     """Every 'previous_result:' reference that names no earlier step.
 
     References resolve lazily, one step at a time, so a reference naming a
@@ -318,8 +319,14 @@ def previous_result_reference_errors(workflow_definition):
     a read of the file would have caught (T005). The names are all in the
     definition, so this is answerable before anything runs.
 
-    Only literal references are checked: one spelled by a 'variable:' the
-    caller supplies is not knowable here and is left alone.
+    The definition handed here has already been substituted and expanded,
+    so every reference in it is literal; a 'variable:' still spelled out is
+    one nothing resolved and is left alone.
+
+    `source_indices`, when given, is the source step index of each step -
+    expansion of a 'for_each' group turns one written step into several, and
+    the path an error carries has to be one the author can find in the file
+    they wrote.
     """
     steps = workflow_definition.get("steps")
     if not isinstance(steps, list):
@@ -330,22 +337,34 @@ def previous_result_reference_errors(workflow_definition):
     for index, step in enumerate(steps):
         if not isinstance(step, dict):
             continue
+        name = step.get("name")
         found = {}
         _collect_reference_paths(step, (), found)
         for path, reference in sorted(found.items(), key=lambda item: str(item[0])):
             if any(reference_resolves_to(reference, name) for name in seen):
                 continue
-            location = _render_path(("steps", index) + path)
+            source = (
+                source_indices[index]
+                if source_indices is not None and index < len(source_indices)
+                else index
+            )
+            location = render_path(("steps", source) + path)
+            # Which expansion it was: the source path alone points at the one
+            # step the author wrote, and every member reports the same path
+            where = (
+                f" in member '{name}'"
+                if isinstance(name, str) and MEMBER_SEPARATOR in name
+                else ""
+            )
             errors.append(
                 {
                     "path": location,
                     "message": (
-                        f"previous_result '{reference}' names no earlier step. "
-                        f"Steps available here: {seen}"
+                        f"previous_result '{reference}'{where} names no earlier "
+                        f"step. Steps available here: {seen}"
                     ),
                 }
             )
-        name = step.get("name")
         if isinstance(name, str):
             seen.append(name)
     return errors
@@ -370,16 +389,3 @@ def _collect_reference_paths(value, path, found):
             _collect_reference_paths(item, path + (index,), found)
     elif isinstance(value, str) and value.startswith(PREVIOUS_RESULT_PREFIX):
         found[path] = value[len(PREVIOUS_RESULT_PREFIX) :]
-
-
-def _render_path(path):
-    """'steps[3].task.arguments.videos[1]' - the same shape schema errors use."""
-    rendered = ""
-    for part in path:
-        if isinstance(part, int):
-            rendered += f"[{part}]"
-        elif rendered:
-            rendered += f".{part}"
-        else:
-            rendered = str(part)
-    return rendered
diff --git a/dw/server/app.py b/dw/server/app.py
index d66a42ad..34d98012 100644
--- a/dw/server/app.py
+++ b/dw/server/app.py
@@ -49,6 +49,7 @@
     describe_task,
     workflow_argument_warnings,
 )
+from ..for_each import entry_field_warnings
 from ..schema import load_schema, validate_data, format_validation_errors
 from ..prompts import (
     PROMPT_PREFIX,
@@ -194,7 +195,8 @@ def catalog_name_for(path, source):
 def workflow_details(sources_by_name):
     """Per-workflow card metadata: output kinds, step and variable counts,
     and the variable names themselves - enough for an agent to pick a
-    workflow and know what to pass it without fetching each candidate. The
+    workflow and know what to pass it without fetching each candidate, and,
+    for a list-driven workflow, what an entry of each list carries. The
     names but not their defaults: across the workflows on disk the defaults
     are an order of magnitude more payload, on a listing the UI reloads.
 
@@ -248,6 +250,7 @@ def workflow_details(sources_by_name):
                 "shape": metadata["shape"],
                 "traits": metadata["traits"],
                 "summary": metadata["summary"],
+                "lists": metadata["lists"],
                 "cost": cost if isinstance(cost, list) and cost else None,
             }
         except Exception:
@@ -261,6 +264,7 @@ def workflow_details(sources_by_name):
                 "shape": "utility",
                 "traits": [],
                 "summary": "",
+                "lists": {},
                 "cost": None,
             }
         _workflow_detail_cache[path] = (mtime, detail)
@@ -813,6 +817,23 @@ def submit_job(request: JobRequest, ws: Workspace = Depends(selected_workspace))
             resolved, source = resolve_workflow_reference(
                 request.workflow_path, sources
             )
+            # The same reference check POST /api/validate makes, because a
+            # caller who skipped the free pre-flight should still not get a
+            # job id for an argument that cannot resolve. The name half of
+            # this check lives in JobManager.submit, where the definition is
+            # loaded; this half needs the workspace's search path, which is
+            # here - which is why a bad 'asset:' used to queue and die on the
+            # first step while a bad variable name was refused outright
+            reference_problems = _argument_reference_errors(
+                request.arguments, workspace
+            )
+            if reference_problems:
+                raise ValueError(
+                    "; ".join(
+                        f"{problem['path']}: {problem['message']}"
+                        for problem in reference_problems
+                    )
+                )
             job = manager.submit(
                 workflow_path=resolved,
                 workflow=request.workflow,
@@ -1186,31 +1207,47 @@ def over_roots(roots, resolve):
                     first = first or e
             raise first
 
+        def _string_leaves(value, path):
+            """Every string in `value`, paired with the path it sits at.
+
+            `value` is walked the way a for_each entry is - a list or dict
+            of arbitrary nesting - so a reference inside `shots[2].
+            references[1].from_file` is found the same as one at the
+            argument's own top level."""
+            if isinstance(value, str):
+                yield path, value
+            elif isinstance(value, list):
+                for i, item in enumerate(value):
+                    yield from _string_leaves(item, f"{path}[{i}]")
+            elif isinstance(value, dict):
+                for key, item in value.items():
+                    yield from _string_leaves(item, f"{path}.{key}")
+
         if not isinstance(arguments, dict):
             return []
         errors = []
         for name, value in arguments.items():
-            if not isinstance(value, str):
-                continue
-            path = f"arguments.{name}"
-            try:
-                if is_asset_reference(value):
-                    over_roots(
-                        _asset_roots(ws) or [ws.assets],
-                        lambda root: resolve_asset_reference(value, asset_dir=root),
-                    )
-                elif value.startswith(PROMPT_PREFIX):
-                    over_roots(
-                        _prompt_roots(),
-                        lambda root: resolve_prompt_reference(value, prompt_dir=root),
-                    )
-                elif is_output_reference(value):
-                    resolve_output_reference(value, root=ws.outputs)
-            except Exception as e:
-                # Every resolver here raises with a message written for the
-                # person who wrote the reference - a traversal refusal from
-                # the security layer included
-                errors.append({"path": path, "message": str(e)})
+            for path, leaf in _string_leaves(value, f"arguments.{name}"):
+                try:
+                    if is_asset_reference(leaf):
+                        over_roots(
+                            _asset_roots(ws) or [ws.assets],
+                            lambda root: resolve_asset_reference(leaf, asset_dir=root),
+                        )
+                    elif leaf.startswith(PROMPT_PREFIX):
+                        over_roots(
+                            _prompt_roots(),
+                            lambda root: resolve_prompt_reference(
+                                leaf, prompt_dir=root
+                            ),
+                        )
+                    elif is_output_reference(leaf):
+                        resolve_output_reference(leaf, root=ws.outputs)
+                except Exception as e:
+                    # Every resolver here raises with a message written for
+                    # the person who wrote the reference - a traversal
+                    # refusal from the security layer included
+                    errors.append({"path": path, "message": str(e)})
         return errors
 
     @app.post("/api/validate")
@@ -1267,7 +1304,9 @@ def validate_workflow(
                 "has the detail",
             )
         try:
-            errors = candidate.validation_errors()
+            # The caller's list is the one a for_each expands over, so the
+            # pre-flight checks the step set that will actually run
+            errors = candidate.validation_errors(arguments=request.arguments)
         except Exception:
             # An error here is not the schema's verdict on the workflow -
             # validation_errors() reports that by returning it. It is the
@@ -1310,7 +1349,8 @@ def validate_workflow(
             "valid": True,
             "error": None,
             "errors": [],
-            "warnings": workflow_argument_warnings(definition),
+            "warnings": workflow_argument_warnings(definition)
+            + entry_field_warnings(definition, request.arguments),
         }
         if request.arguments:
             # Naming what was checked is the difference between 'the stored
@@ -1561,11 +1601,12 @@ def get_workflow_variables(
         blocks and all, to read a single integer. This answers that question
         by itself.
 
-        Long defaults - a shot's prompt runs to kilobytes - are cut to their
-        first 200 characters and named in `truncated`, so the answer stays
-        small for the numbers and names it is usually asked about; `full=true`
-        returns them whole, and `GET /api/workflows/{name}` is still the
-        definition itself.
+        Long strings - a shot's prompt runs to kilobytes, and a list-driven
+        workflow's default list holds several - are cut to their first 200
+        characters wherever they sit and named in `truncated`
+        (`shots[0].prompt`), so the answer stays small for the numbers and
+        names it is usually asked about; `full=true` returns them whole, and
+        `GET /api/workflows/{name}` is still the definition itself.
         """
         path, source = resolve_readable_workflow(_sources_for(ws), name)
         try:
@@ -1574,18 +1615,22 @@ def get_workflow_variables(
         except (OSError, json.JSONDecodeError) as e:
             raise HTTPException(status_code=500, detail=f"Could not read workflow: {e}")
 
+        def preview(value, path):
+            if isinstance(value, str) and len(value) > VARIABLE_VALUE_PREVIEW:
+                truncated.append(path)
+                return value[:VARIABLE_VALUE_PREVIEW]
+            if isinstance(value, list):
+                return [preview(item, f"{path}[{i}]") for i, item in enumerate(value)]
+            if isinstance(value, dict):
+                return {
+                    key: preview(item, f"{path}.{key}") for key, item in value.items()
+                }
+            return value
+
         variables = definition.get("variables") or {}
         values, truncated = {}, []
         for variable, value in variables.items():
-            if (
-                not full
-                and isinstance(value, str)
-                and len(value) > VARIABLE_VALUE_PREVIEW
-            ):
-                values[variable] = value[:VARIABLE_VALUE_PREVIEW]
-                truncated.append(variable)
-            else:
-                values[variable] = value
+            values[variable] = value if full else preview(value, variable)
         return {
             "name": name,
             "variables": values,
diff --git a/dw/server/catalog_shape.py b/dw/server/catalog_shape.py
index b9a1cbd1..2fa557f5 100644
--- a/dw/server/catalog_shape.py
+++ b/dw/server/catalog_shape.py
@@ -15,6 +15,8 @@
 
 import re
 
+from ..for_each import list_fields
+
 SHAPES = (
     "image",
     "image-set",
@@ -160,13 +162,13 @@ def _needs_input_media(steps):
 def _cuts_together(steps):
     """A concat or dissolve fed by two or more distinct steps, or by a list
     of shots handed in whole - one `variable:` reference is a supplied list
-    whose length only the caller knows, and a cut over supplied footage is
-    still an edit."""
+    whose length only the caller knows, one `gather:` reference is every
+    member of a for_each group, and a cut over either is still an edit."""
     for step in steps:
         key, body = _block(step)
         if key == "task" and body.get("command") in _CUT_TASKS:
             videos = _arguments(step).get("videos")
-            if isinstance(videos, str) and videos.startswith("variable:"):
+            if isinstance(videos, str) and videos.startswith(("variable:", "gather:")):
                 return True
             sources = _fed_by(videos)
             if isinstance(videos, list):
@@ -283,9 +285,13 @@ def _derive_summary(description):
 def derive_catalog_metadata(definition):
     """shape, traits and summary for one definition, declarations honoured.
 
-    Returns {shape, traits, summary, summary_truncated, declared}; `declared`
-    names which of the three came from the file rather than the rules, so a
-    test can refuse a declaration that merely repeats the derivation.
+    Returns {shape, traits, summary, summary_truncated, lists, declared};
+    `lists` names what an entry of each for_each-driven variable has to
+    carry (`list_fields`) plus its default's length, so an agent can write
+    the list argument without opening the definition; `declared` names
+    which of the three prose fields came from the file rather than the
+    rules, so a test can refuse a declaration that merely repeats the
+    derivation.
     """
     if not isinstance(definition, dict):
         definition = {}
@@ -306,11 +312,23 @@ def derive_catalog_metadata(definition):
     if isinstance(definition.get("summary"), str) and definition["summary"].strip():
         summary, truncated = _truncate(definition["summary"].strip())
         declared.add("summary")
+    variables = definition.get("variables")
+    variables = variables if isinstance(variables, dict) else {}
+    lists = {
+        name: {
+            **fields,
+            "entries": (
+                len(variables[name]) if isinstance(variables.get(name), list) else None
+            ),
+        }
+        for name, fields in list_fields(definition).items()
+    }
     return {
         "shape": shape,
         "traits": traits,
         "summary": summary,
         "summary_truncated": truncated,
+        "lists": lists,
         "declared": declared,
     }
 
@@ -322,9 +340,14 @@ def derive_catalog_metadata(definition):
     "cost",
     "kinds",
     "variable_names",
+    "lists",
     "configures",
 )
 
+# Carried in the compact view only when set: a template has no
+# `configures`, and most workflows have no list-driven step
+_COMPACT_WHEN_SET = frozenset({"configures", "lists"})
+
 
 def project_listing(
     details,
@@ -374,7 +397,7 @@ def project_listing(
             slim = {
                 key: detail.get(key)
                 for key in COMPACT_FIELDS
-                if key != "configures" or detail.get(key)
+                if key not in _COMPACT_WHEN_SET or detail.get(key)
             }
             if detail.get("configures_missing"):
                 slim["configures_missing"] = detail["configures_missing"]
diff --git a/dw/server/jobs.py b/dw/server/jobs.py
index e58cd0bf..db43f95c 100644
--- a/dw/server/jobs.py
+++ b/dw/server/jobs.py
@@ -351,13 +351,96 @@ def __init__(self, spec):
         self.run_id = None
         self.run_dir = None
         self.events = []
+        # The running summary a poll reads - see _note_progress. Kept as the
+        # events arrive rather than derived from the log on request, because
+        # the log is trimmed to its last MAX_PERSISTED_EVENTS and a caller
+        # polling a long render should not have to page through it to learn
+        # that something moved
+        self.last_event_at = None
+        self.phase = None
+        self.phase_detail = None
+        self.phase_started_at = None
+        self.step_name = None
+        self.step_index = None
+        self.total_steps = None
+        self.denoise_step = None
+        self.denoise_total_steps = None
         self.condition = threading.Condition()
 
     def add_event(self, event):
         with self.condition:
-            self.events.append({"seq": len(self.events), **event})
+            # `at` is seconds since the job started (since it was created,
+            # for the events before that). Phases say what a step is waiting
+            # on; only a clock on each event says what it cost - the
+            # lead-in from `step_start` to the first `pipeline_step` on a
+            # reused pipeline is the number a "slow start" report needs
+            since = self.started_at if self.started_at is not None else self.created_at
+            self.events.append(
+                {"seq": len(self.events), "at": round(time.time() - since, 1), **event}
+            )
+            self._note_progress(event)
             self.condition.notify_all()
 
+    def _note_progress(self, event):
+        """Fold one event into the running summary.
+
+        A single-step generation emits `generating` and then nothing until it
+        is done, so 'no new events' is the normal state of a healthy run and
+        says nothing about whether it is progressing. What answers that is
+        how long it has been that way, and how far into the denoise loop it
+        got - both of which are here rather than in the event log.
+        """
+        now = time.time()
+        self.last_event_at = now
+        kind = event.get("event")
+        if kind == "phase":
+            self.phase = event.get("phase")
+            self.phase_detail = event.get("detail")
+            self.phase_started_at = now
+        elif kind == "pipeline_step":
+            self.denoise_step = event.get("step")
+            self.denoise_total_steps = event.get("total_steps")
+        elif kind == "step_start":
+            self.step_name = event.get("step")
+            self.step_index = event.get("index")
+            self.total_steps = event.get("total_steps")
+            # A new step's denoise loop has not started; the previous step's
+            # count would read as this one's progress
+            self.denoise_step = None
+            self.denoise_total_steps = None
+
+    def progress(self):
+        """Where a running job has got to, or None for one that has not
+        started or has finished - a terminal job has a manifest, which is a
+        better answer than a stale phase."""
+        if self.status != RUNNING or self.last_event_at is None:
+            return None
+        now = time.time()
+        summary = {
+            "step": self.step_name,
+            "step_index": self.step_index,
+            "total_steps": self.total_steps,
+            "phase": self.phase,
+            "phase_detail": self.phase_detail,
+            "seconds_in_phase": (
+                round(now - self.phase_started_at, 1) if self.phase_started_at else None
+            ),
+            # The one number that separates a slow run from a hung one -
+            # but only once the denoise loop is running, see below
+            "seconds_since_event": round(now - self.last_event_at, 1),
+            # Always present, null until the loop starts. A key that only
+            # appears once there is a count to report cannot be told apart
+            # from a key that is missing because nothing is happening: the
+            # lead-in to `generating` - encoding the prompt and any
+            # reference image or audio - is over a minute of silence on a
+            # large video model, and read as an absent counter it looks
+            # exactly like a wedged denoise loop. Null here means the loop
+            # has not started; a number that stops moving is the stuck one
+            "denoise_step": self.denoise_step,
+            "denoise_total_steps": self.denoise_total_steps,
+        }
+        return summary
+
     def finish(self, status, error=None, traceback_text=None):
         self.status = status
         self.finished_at = time.time()
@@ -406,6 +489,7 @@ def detail(self):
             "traceback": self.traceback,
             "event_count": len(self.events),
             "run_dir": self.run_dir,
+            "progress": self.progress(),
         }
 
 
diff --git a/dw/step_cache.py b/dw/step_cache.py
index ee472a63..47af61ff 100644
--- a/dw/step_cache.py
+++ b/dw/step_cache.py
@@ -38,7 +38,10 @@
 
 The cache is per-process and bounded (DEFAULT_MAX_ENTRIES, LRU): it holds
 realized media, so unbounded growth would work against the OOM avoidance
-release_unreferenced_results exists for.
+release_unreferenced_results exists for. The bound is sized so a maximal
+for_each run (32 entries over two groups plus fixed steps, ~70 members)
+never evicts its own earlier members before it ends - a smaller cap would
+turn a long list-driven run into one that thrashes its own cache.
 """
 
 import copy
@@ -122,10 +125,13 @@ class StepCache:
 
     Bounded: entries hold realized media, so an unbounded cache would work
     directly against release_unreferenced_results' OOM avoidance. The
-    least-recently-used entry is evicted once the cap is reached.
+    least-recently-used entry is evicted once the cap is reached. The
+    default is sized so a maximal for_each run - 32 entries over two groups
+    plus fixed steps, ~70 members - fits without evicting its own earlier
+    members.
     """
 
-    DEFAULT_MAX_ENTRIES = 50
+    DEFAULT_MAX_ENTRIES = 128
 
     def __init__(self, max_entries=None):
         # (workflow_id, step_name) -> {"step_data", "step_seed", "result",
diff --git a/dw/validate.py b/dw/validate.py
index f7bf74f4..acba83e9 100644
--- a/dw/validate.py
+++ b/dw/validate.py
@@ -2,7 +2,7 @@
 import os
 from .workflow import workflow_from_file
 from . import startup
-from .security import validate_workflow_path, SecurityError
+from .security import validate_workflow_path, set_trust_workflows, SecurityError
 
 
 def main():
@@ -18,8 +18,21 @@ def main():
         default="INFO",
         help="Set the logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)",
     )
+    parser.add_argument(
+        "--trust-workflows",
+        action="store_true",
+        default=False,
+        help="Trust this workflow file to execute arbitrary Python: allow "
+        "pre_load_modules and any dotted *_type/*_dtype/dtype/config_type "
+        "value, not just ones inside the diffusers/torch/transformers/"
+        "quantization-backend ecosystem the tool already depends on. Off "
+        "by default - see docs/SECURITY.md's Trust model. Only pass this "
+        "for a workflow file whose source you trust.",
+    )
     args = parser.parse_args()
 
+    set_trust_workflows(args.trust_workflows)
+
     try:
         validated_file_path = validate_workflow_path(args.file_name)
         if not os.path.exists(validated_file_path):
diff --git a/dw/variables.py b/dw/variables.py
index 4ac42e1d..13a54d34 100644
--- a/dw/variables.py
+++ b/dw/variables.py
@@ -15,6 +15,11 @@ class VariableNotFoundError(ValueError):
     """Raised when a workflow references a "variable:name" that isn't declared."""
 
 
+class VariableCycleError(ValueError):
+    """Raised when a list- or dict-valued variable references itself, directly
+    or through others, inside `resolve_variable_values`."""
+
+
 def _resolve_variable_reference(value, variables):
     """
     If value is a "variable:name" reference, look it up and return (True, resolved).
@@ -86,16 +91,69 @@ def replace_variables(data, variables):
     return copy.deepcopy(data)
 
 
+def resolve_variable_values(variables):
+    """A copy of `variables` in which every "variable:name" inside a list-
+    or dict-valued variable is replaced by that variable's value.
+
+    A list-driven step reads its entries from a variable, and an entry that
+    says "from_file": "variable:character_a_voice" is how one variable sets
+    a voice in every shot the character speaks in. replace_variables only
+    walks the definition, so those references would reach the step as the
+    literal strings; this resolves them once, before realize_args, so a
+    reference type inside an entry is a type name by the time it is loaded.
+
+    Only list and dict values are walked. A scalar value that begins with
+    "variable:" is passed through as it always was.
+
+    Raises:
+        VariableNotFoundError: a reference names nothing declared
+        VariableCycleError: a value references itself, directly or through others
+    """
+    resolved = {}
+
+    def resolve(name, chain):
+        if name in resolved:
+            return resolved[name]
+        if name in chain:
+            loop = " -> ".join(chain[chain.index(name) :] + [name])
+            raise VariableCycleError(
+                f"Variable '{name}' references itself through: {loop}"
+            )
+        value = variables[name]
+        if isinstance(value, (list, dict)):
+            value = walk(value, chain + [name])
+        else:
+            value = copy.deepcopy(value)
+        resolved[name] = value
+        return value
+
+    def walk(node, chain):
+        matched, _ = _resolve_variable_reference(node, variables)
+        if matched:
+            return resolve(node.removeprefix("variable:"), chain)
+        if isinstance(node, list):
+            return [walk(item, chain) for item in node]
+        if isinstance(node, dict):
+            return {key: walk(item, chain) for key, item in node.items()}
+        return copy.deepcopy(node)
+
+    for name in variables:
+        resolve(name, [])
+    return resolved
+
+
 def undeclared_variable_references(definition):
     """The "variable:name" references in a workflow definition that name no
     entry of its `variables` - the ones `replace_variables` will refuse at run
     time, found before anything loads.
 
-    Walks everything but `variables` itself, the way resolution does. Returns
-    a list of (path, name) pairs, path being where the reference sits
-    (`steps[0].pipeline.arguments.prompt`) and name what it asked for - which
-    is the whole remainder of the string, since a reference is the entire
-    value and nothing is interpolated around it.
+    Walks everything but `variables` itself, plus the inside of every list-
+    or dict-valued variable, the way `resolve_variable_values` and
+    `replace_variables` together do. Returns a list of (path, name) pairs,
+    path being where the reference sits (`steps[0].pipeline.arguments.prompt`)
+    and name what it asked for - which is the whole remainder of the string,
+    since a reference is the entire value and nothing is interpolated
+    around it.
     """
     declared = definition.get("variables") or {}
     found = []
@@ -115,9 +173,34 @@ def walk(node, path):
     for key, value in definition.items():
         if key != "variables":
             walk(value, key)
+    if isinstance(declared, dict):
+        for name, value in declared.items():
+            if isinstance(value, (list, dict)):
+                walk(value, f"variables.{name}")
     return found
 
 
+def _validated_strings(value):
+    """A copy of a list- or dict-valued caller argument with every string
+    leaf passed through `validate_string_input` - the same check a
+    top-level string argument gets in `set_variables` below. A for_each
+    entry's `prompt` or `from_file` is exactly as reachable to an attacker
+    as a top-level variable, and `isinstance(v, str)` alone would skip it.
+
+    Non-string leaves (numbers, bools, None, nested lists/dicts) pass
+    through unchanged; only str is validated.
+    """
+    if isinstance(value, str):
+        return validate_string_input(
+            value, max_length=MAX_VARIABLE_VALUE_LENGTH, allow_empty=True
+        )
+    if isinstance(value, list):
+        return [_validated_strings(item) for item in value]
+    if isinstance(value, dict):
+        return {key: _validated_strings(item) for key, item in value.items()}
+    return value
+
+
 def set_variables(values, variables):
     """
     Sets the values of variables from a dictionary of new values with validation
@@ -147,11 +230,15 @@ def set_variables(values, variables):
                     f"Unknown variable '{validated_name}'; declared variables: {declared}"
                 )
 
-            # Validate string values
+            # Validate string values - including strings nested inside a
+            # list- or dict-valued argument, which a for_each entry's
+            # prompt or from_file always is
             if isinstance(v, str):
                 validated_value = validate_string_input(
                     v, max_length=MAX_VARIABLE_VALUE_LENGTH, allow_empty=True
                 )
+            elif isinstance(v, (list, dict)):
+                validated_value = _validated_strings(v)
             else:
                 validated_value = v
 
diff --git a/dw/workflow.py b/dw/workflow.py
index cea1b086..48399ea0 100644
--- a/dw/workflow.py
+++ b/dw/workflow.py
@@ -7,7 +7,12 @@
 import hashlib
 import logging
 from datetime import datetime, timezone
-from .arguments import realize_args, realize_constants
+from .arguments import (
+    realize_args,
+    realize_constants,
+    fetch_constant,
+    is_constant_reference,
+)
 from .events import (
     RunContext,
     emit_phase,
@@ -42,7 +47,16 @@
 )
 from .realize import realize_workflow
 from .schema import validate_data_all, format_validation_errors, load_schema
-from .variables import replace_variables, set_variables
+from .for_each import expand_for_each, ForEachError
+from .variables import (
+    argument_errors,
+    replace_variables,
+    resolve_variable_values,
+    set_variables,
+    undeclared_variable_references,
+    VariableCycleError,
+    VariableNotFoundError,
+)
 from .pipeline_processors.pipeline import Pipeline
 from .tasks.model_cache import clear_model_cache
 from .tasks.task import Task
@@ -55,11 +69,21 @@
     SecurityError,
     PathTraversalError,
     InvalidInputError,
+    UntrustedWorkflowError,
 )
 
 logger = logging.getLogger("dw")
 
 
+class ConstantError(ValueError):
+    """A 'constant:' variable default that failed to resolve during
+    validation, with the 'variables.<name>' path at fault."""
+
+    def __init__(self, path, message):
+        super().__init__(message)
+        self.path = path
+
+
 def workflow_from_file(file_spec, output_dir, workflow_dir=None):
     """Loads a workflow from a JSON file with security validation.
 
@@ -282,16 +306,116 @@ def effective_output_dir(self):
             os.path.join(self.output_dir, subfolder) if subfolder else self.output_dir
         )
 
-    def validation_errors(self):
+    def expanded_definition(self, arguments=None, source_indices=None):
+        """The definition as the run will see it: constants realized,
+        variables substituted - the caller's `arguments` folded in when they
+        are all good, else the declared defaults - and every for_each step
+        expanded.
+
+        Raises ForEachError for a for_each that cannot be expanded,
+        ConstantError for a 'constant:' variable default that fails to
+        resolve, and VariableNotFoundError for a 'variable:' that names
+        nothing - which is exactly what the run itself would raise, since a
+        definition that declares variables is always substituted before it
+        runs.
+
+        `source_indices`, when a list is passed, comes back holding the
+        index in *this* definition's steps of every expanded step, so an
+        error can be reported at a path in the file the author wrote.
+        """
+        definition = copy.deepcopy(self.workflow_definition)
+        variables = definition.get("variables")
+        if isinstance(variables, dict):
+            # the run realizes constants before folding arguments, and a
+            # list defaulted to a 'constant:' name must expand here as it
+            # does there - a name lookup, no download. Realizing a constant
+            # imports the module it names, so validating one runs the same
+            # trust gate (require_trusted_dotted_name) a run would - only
+            # the diffusers ecosystem allowlist, unless the caller trusts
+            # the workflow. Realized per top-level variable, not as one
+            # call over the whole dict, so a failure names the variable.
+            for name, value in variables.items():
+                try:
+                    if is_constant_reference(value):
+                        variables[name] = fetch_constant(value)
+                    else:
+                        realize_constants(value)
+                except (ValueError, InvalidInputError, UntrustedWorkflowError) as e:
+                    raise ConstantError(f"variables.{name}", str(e)) from e
+            if arguments and not argument_errors(definition, arguments):
+                set_variables(arguments, variables)
+            variables = resolve_variable_values(variables)
+            definition = replace_variables(definition, variables)
+        return expand_for_each(definition, source_indices)
+
+    def validation_errors(self, arguments=None):
         """Every schema violation in the definition, as [{path, message}];
-        empty when it validates."""
+        empty when it validates. `arguments` are the caller's, so a
+        for_each over a list the caller supplies is checked as it will run."""
         errors = validate_data_all(self.workflow_definition, load_schema("workflow"))
-        # Only once the shape is known good: the reference pass walks the
+        # Only once the shape is known good: the passes below walk the
         # steps array and a definition that fails the schema may have no
         # such array to walk
         if errors:
             return errors
-        return previous_result_reference_errors(self.workflow_definition)
+        source_indices = []
+        try:
+            expanded = self.expanded_definition(arguments, source_indices)
+        except ForEachError as e:
+            return [{"path": e.path, "message": str(e)}]
+        except ConstantError as e:
+            return [{"path": e.path, "message": str(e)}]
+        except VariableNotFoundError:
+            # Every undeclared reference, not just the first one substitution
+            # tripped over - and reported where each sits rather than as a
+            # for_each whose list arrived unsubstituted, which is what a
+            # half-substituted definition used to look like from here
+            return self._undeclared_variable_errors(arguments)
+        except VariableCycleError as e:
+            # resolve_variable_values raises this for a variable that
+            # references itself, directly or through others - there is
+            # no single path inside the definition to blame, so it is
+            # reported against 'variables' as a whole rather than escaping
+            # as an unhandled exception
+            return [{"path": "variables", "message": str(e)}]
+        return previous_result_reference_errors(expanded, source_indices)
+
+    def _undeclared_variable_errors(self, arguments=None):
+        """Every 'variable:' reference naming nothing the workflow declares.
+
+        Fatal rather than a warning: once a workflow has a 'variables'
+        block, replace_variables refuses an undeclared reference, so this is
+        a run that cannot start. Good caller `arguments` are folded in first,
+        and a reference inside one of them is reported under `arguments.`,
+        where the caller wrote it.
+        """
+        definition = copy.deepcopy(self.workflow_definition)
+        variables = definition.get("variables")
+        supplied = set()
+        if isinstance(variables, dict) and arguments:
+            if not argument_errors(definition, arguments):
+                set_variables(arguments, variables)
+                supplied = set(arguments)
+        declared = sorted(variables or {})
+
+        def where(path):
+            head, _, rest = path.partition(".")
+            if head == "variables":
+                name = rest.split(".", 1)[0].split("[", 1)[0]
+                if name in supplied:
+                    return "arguments." + rest
+            return path
+
+        return [
+            {
+                "path": where(path),
+                "message": (
+                    f"'variable:{name}' names no declared variable; "
+                    f"declared: {', '.join(declared) or '<none>'}"
+                ),
+            }
+            for path, name in undeclared_variable_references(definition)
+        ]
 
     def validate(self):
         """Validates workflow definition against JSON schema.
@@ -378,6 +502,10 @@ def run(
                 # first set variable values base don the arguments passed to the workflow
                 # these may come form the command line or form a parent workflow
                 set_variables(arguments, variables)
+                # an entry of a list-valued variable may name another
+                # variable; resolve those before anything inside it is
+                # realized, so a reference type in an entry is a type name
+                variables = resolve_variable_values(variables)
                 # realize the variables, initialiting downloads of images etc
                 realize_args(variables, base_dir)
                 ## then replace any variable references in the workflow definition with the actual values
@@ -385,6 +513,12 @@ def run(
                 # place, so the result must be captured here
                 workflow_def = replace_variables(workflow_def, variables)
 
+            # One ordinary step per entry of every for_each list, before the
+            # seed, the run id and the realized workflow are computed, so
+            # each covers what actually runs. A ForEachError here fails the
+            # run before anything loads
+            workflow_def = expand_for_each(workflow_def)
+
             # Set up random seed for reproducibility. Resolved lazily - as a
             # dict.get default, torch.seed() would run on every call and reseed
             # the global RNG even when the workflow names an explicit seed
diff --git a/dw/workflow_schema.json b/dw/workflow_schema.json
index 7fe65852..1990e06a 100644
--- a/dw/workflow_schema.json
+++ b/dw/workflow_schema.json
@@ -43,7 +43,18 @@
                     "device": {"type": "string", "enum": ["cuda", "mps", "cpu"]},
                     "name": {"type": "string", "description": "The accelerator, for a person: 'RTX 4090', 'M2 Ultra'"},
                     "vram_gb": {"type": "number", "minimum": 0},
-                    "minutes": {"type": "number", "minimum": 0}
+                    "minutes": {"type": "number", "minimum": 0},
+                    "per_entry": {
+                        "type": "object",
+                        "description": "For a list-driven workflow: the measured cost of one entry of 'variable' (every member it produces), and the length of the default list 'minutes' was measured with, so a run over N entries is (minutes - per_entry.minutes * entries) + per_entry.minutes * N.",
+                        "required": ["variable", "minutes", "entries"],
+                        "properties": {
+                            "variable": {"type": "string"},
+                            "minutes": {"type": "number", "minimum": 0},
+                            "entries": {"type": "integer", "minimum": 1}
+                        },
+                        "additionalProperties": false
+                    }
                 },
                 "additionalProperties": false
             }
@@ -104,6 +115,13 @@
                 "name": {
                     "type": "string"
                 },
+                "for_each": {
+                    "description": "Run this step once per entry of a list. A list, or a 'variable:' reference to one. Inside the step, 'item:' is the entry and 'item:field' one of its fields; a later step reads every member's result with 'gather:<step name>'. Members are named '<step name>@<entry name>' (or '@<index>' for an entry without a name), so '@' is reserved in step names.",
+                    "type": ["array", "string"],
+                    "pattern": "^variable:",
+                    "minItems": 1,
+                    "maxItems": 32
+                },
                 "seed": {
                     "description": "Default seed for the entire step. Accepts a 'variable:' reference.",
                     "type": [
diff --git a/dw_mcp/catalog.py b/dw_mcp/catalog.py
index 1f758a23..6582cfd1 100644
--- a/dw_mcp/catalog.py
+++ b/dw_mcp/catalog.py
@@ -35,7 +35,8 @@ def get_workflow(client, name, variables_only=False):
     confirming that a stored workflow's audio_bleed_ms is 1800 otherwise
     means pulling the whole definition, quantization blocks and all, to
     read one integer (2026-09-11). Long defaults come back cut to their
-    first 200 characters, with the names of the cut ones in `truncated`.
+    first 200 characters, with the names of the cut ones in `truncated`,
+    including strings inside a list default, named like `shots[0].prompt`.
     """
     if variables_only:
         return client.get_json(api_path("api", "workflows", name, "variables"))
diff --git a/dw_mcp/diagnose.py b/dw_mcp/diagnose.py
index 4dcffaa4..480faded 100644
--- a/dw_mcp/diagnose.py
+++ b/dw_mcp/diagnose.py
@@ -72,7 +72,11 @@ def run_workflow(
 
 
 def get_job(client, job_id):
-    """A job's status, arguments, warnings, manifest, error and traceback."""
+    """A job's status, arguments, warnings, manifest, error and traceback.
+    A running job also carries `progress` - the step, the phase and how long
+    it has been in it, with a denoise counter that is null until that loop
+    starts. Null under `generating` is the pipeline's silent lead-in, not a
+    hang; see wait_for_job."""
     return client.get_json(api_path("api", "jobs", job_id))
 
 
@@ -118,6 +122,12 @@ def get_job_events(client, job_id, after=-1, limit=200):
     "warnings",
     "error",
     "event_count",
+    # Where a running job has got to: the step, the phase and how long it
+    # has been in it, plus the denoise counter when one is running. A
+    # single-step generation emits nothing for minutes at a time, so this
+    # is what separates a slow job from a hung one on a poll that would
+    # otherwise come back byte-identical
+    "progress",
 )
 
 
@@ -152,7 +162,23 @@ def wait_for_job(client, job_id, timeout_seconds=20):
     returns the job's last-seen status with `still_running: true` instead
     of hanging - call again to keep waiting. Returns a slim job - status,
     warnings, error, and the manifest once finished - without the
-    arguments; get_job has those."""
+    arguments; get_job has those.
+
+    A running job carries `progress`: the step it is on, the phase
+    (`loading`, `generating`, `decoding`, `saving`) with the model or step
+    named in `phase_detail`, `seconds_in_phase`, `seconds_since_event`, and
+    `denoise_step`/`denoise_total_steps`, which are null until the denoise
+    loop starts. Two calls with the same phase and a growing
+    `seconds_in_phase` but a moving `denoise_step` is a slow run; one where
+    `denoise_step` is a number that does not move while
+    `seconds_since_event` climbs is a stuck one.
+
+    `denoise_step: null` under `generating` is neither: it is the lead-in
+    the pipeline runs before the loop - encoding the prompt and any
+    reference image or audio - which emits nothing and is well over a
+    minute on a large video model (~90 s on MiniMax H3). Silence there is
+    expected; `seconds_since_event` only says something once
+    `denoise_step` is a number, or in any other phase."""
     requested = max(0.0, float(timeout_seconds))
     applied = min(requested, float(MAX_WAIT_SECONDS))
     capped = applied < requested
diff --git a/dw_mcp/server.py b/dw_mcp/server.py
index 729b162b..4e423746 100644
--- a/dw_mcp/server.py
+++ b/dw_mcp/server.py
@@ -74,7 +74,10 @@ def build_server(client):
             "\n"
             "Start from `list_workflows(shape=...)`: the server keeps a "
             "large catalog, and its compact listing carries each "
-            "workflow's summary, shape, traits, cost and variable names - "
+            "workflow's summary, shape, traits, cost, variable names and, "
+            "for a list-driven workflow, `lists` - what an entry of each "
+            "list carries; a list-driven workflow's `cost` may also carry "
+            "a measured `per_entry` (neither template does yet) - "
             "run what is already there, with `arguments` overriding its "
             "variables, rather than authoring a new workflow for a "
             "request an existing one covers. Shapes: image, image-set, "
@@ -166,10 +169,15 @@ def list_workflows(
         composes-workflows. Each entry carries a one-line `summary`, its
         `shape` and `traits` (what it needs supplied), `cost` (measured
         runs per device; null means unknown - call `get_memory` and say
-        so), output kinds and variable names. Templates only by default;
-        `configures=<template>` lists the checkpoint configs tuned for
-        one, `include_models=true` lists them all. `get_workflow` has the
-        full description and definition."""
+        so), output kinds and variable names. `lists`, present for a
+        list-driven workflow, names per list variable the fields an entry
+        takes, the steps run over it and the default's length; there
+        `cost[].per_entry`, when present, is the measured cost of one
+        entry (`{variable, minutes, entries}`), so a run over a
+        different-length list can be priced from it. Templates only by
+        default; `configures=<template>` lists the checkpoint configs
+        tuned for one, `include_models=true` lists them all. `get_workflow`
+        has the full description and definition."""
         return catalog.list_workflows(
             client,
             shape=shape,
@@ -185,8 +193,9 @@ def get_workflow(name: str, variables_only: bool = False) -> dict:
         `variables_only=true` when the question is only what a variable
         defaults to - it answers with the variables and their values and
         nothing else, which is a fraction of the definition; long defaults
-        (a shot's prompt) come back cut to 200 characters with the cut ones
-        named in `truncated`."""
+        come back cut to 200 characters with the cut ones named in
+        `truncated`, reaching into a list default too - a shot's prompt
+        is named `shots[0].prompt`."""
         return catalog.get_workflow(client, name, variables_only=variables_only)
 
     def get_schema() -> dict:
@@ -515,7 +524,7 @@ def create_workspace(name: str, use: bool = False) -> dict:
         """Create a workspace on the server. It gets its own workflows,
         assets and outputs and shares the one prompt library. The name is a
         single path segment and cannot be one of the reserved folder names
-        (workflows, prompts, assets, outputs). Pass use=true to switch this
+        (workflows, prompts, assets, outputs, exports, common). Pass use=true to switch this
         session to it as well; otherwise the session stays where it was and
         the result says so."""
         return workspaces.create_workspace(client, name, use=use)
@@ -705,9 +714,13 @@ def get_job_workflow(job_id: str) -> dict:
         return diagnose.get_job_workflow(client, job_id)
 
     def get_job_events(job_id: str, after: int = -1, limit: int = 200) -> dict:
-        """Get a page of a job's progress events - phase transitions, memory
-        readings and log lines. `after` is exclusive: pass back the previous
-        call's `last_seq` to continue."""
+        """Get a page of a job's progress events - phase transitions, denoise
+        steps, memory readings and log lines. `after` is exclusive: pass back
+        the previous call's `last_seq` to continue. Each event's `at` is
+        seconds since the job started, so where a step's time went is the
+        difference between two events. For 'is it still moving?' the
+        `progress` block on get_job/wait_for_job is cheaper than a page of
+        events."""
         return diagnose.get_job_events(client, job_id, after=after, limit=limit)
 
     def wait_for_job(job_id: str, timeout_seconds: int = 20) -> dict:
@@ -726,7 +739,16 @@ def wait_for_job(job_id: str, timeout_seconds: int = 20) -> dict:
         timeout_capped.
 
         Returns a slim job - status, warnings, error, and the manifest once
-        finished - without the arguments; get_job has those."""
+        finished - without the arguments; get_job has those. A running job
+        also carries `progress`: the step it is on, the phase (`loading`,
+        `generating`, `decoding`, `saving`) with the model named in
+        `phase_detail`, `seconds_in_phase`, `seconds_since_event`, and
+        `denoise_step`/`denoise_total_steps`, null until the denoise loop
+        starts - which is how a slow run and a stuck one tell apart between
+        two otherwise identical polls. A null `denoise_step` under
+        `generating` is the pipeline's lead-in (encoding the prompt and any
+        reference image or audio, ~90 s on MiniMax H3), which emits
+        nothing: wait it out rather than reading the silence as a hang."""
         return diagnose.wait_for_job(client, job_id, timeout_seconds=timeout_seconds)
 
     # The cap is a number a caller paces against, so the description states
diff --git a/plugins/dw/README.md b/plugins/dw/README.md
index 4ada49f7..9478346b 100644
--- a/plugins/dw/README.md
+++ b/plugins/dw/README.md
@@ -3,12 +3,12 @@
 Skills for Claude Code that teach an agent to compose a model family's
 workflows on a [diffusers-workflow](https://github.com/dkackman/diffusers-workflow)
 server. They assume the `dw` MCP server is already registered
-(see the repo README, "Drive it from Claude Code"); a skill's first move is
+(see the repo README, "Drive it from an agent"); a skill's first move is
 `get_server_info`.
 
 Install once, from Claude Code:
 
-```
+```bash
 /plugin marketplace add dkackman/diffusers-workflow
 /plugin install dw@diffusers-workflow
 ```
@@ -24,7 +24,7 @@ fetch the vendor's guides when those are absent, so nothing else is required.
 Installing them is optional and worth it for Music 3, whose skill carries a
 genre router and 1,000 example captions that a fetch does not reach:
 
-```
+```bash
 npx skills add MiniMax-AI/MiniMax-H3 --skill h3-prompt-writing
 npx skills add MiniMax-AI/MiniMax-Music3 --skill music-caption-rewriter
 ```
diff --git a/plugins/dw/skills/minimax-h3/SKILL.md b/plugins/dw/skills/minimax-h3/SKILL.md
index 1cec717e..ab620ab0 100644
--- a/plugins/dw/skills/minimax-h3/SKILL.md
+++ b/plugins/dw/skills/minimax-h3/SKILL.md
@@ -54,22 +54,32 @@ not from here.
   Drift compounds per seam: reference the subject picture in every segment,
   prefer `last_segment` continuity, and use the longest segments memory allows.
 - **A piece with cuts**: fresh shots from shared portraits, then a concat.
-  `templates/minimax/dialogue-short` (Z-Image draws the cast, one loaded model
-  per shot, `concat_videos` splices) and `templates/minimax/music-video`
-  (shots cut to a generated song, lip-synced slices). A cut erases drift; the
-  last shot is as clean as the first. Write shots, not takes. Each shot
-  generates its own audio, so write `non_diegetic_music: N/A` in every shot
-  and lay one score under the concat afterwards: `templates/minimax/music`
-  writes the track and `templates/assemble-and-score` shows the `pair_audio`
-  step that mixes it under the world sound (it takes three shots; for more,
-  author the concat and score steps the same way). A character who speaks in
-  several shots keeps one voice by passing the same clip as an audio
-  reference in each (the `voice-timbre-reference` pattern); a repeated voice
-  description alone drifts. Each shot's `num_frames` is its own, so pace the
-  cut - a trailer builds by varying shot length. The reference carries
-  delivery as well as timbre: a flat read gives a flat performance. Bark's
-  presets are conversational; for a narrator with gravitas, `upload_asset` a
-  recorded read in that register and reference the same file in every shot.
+  `templates/minimax/dialogue-short` (Z-Image draws the cast, one shot per
+  entry of its `shots` list on one loaded model, `concat_videos` splices) and
+  `templates/minimax/music-video` (a song, one slice and one lip-synced shot
+  per entry). `shots` is one list argument: a dialogue entry is `name`,
+  `prompt`, `references` (which portraits and voices this shot uses) and
+  `num_frames`; a music-video entry is `name`, `prompt` and `start_frame`.
+  A six-shot piece is one more entry, not another file.
+  The listing's `lists` block says what an entry carries; its `cost`
+  carries `per_entry` when one shot was measured: quote
+  `minutes - per_entry.minutes × per_entry.entries + per_entry.minutes × N`
+  for N entries. Without `per_entry`, quote the total and say it is the
+  default list's.
+  A cut erases drift; the last shot is as clean as the first. Write shots,
+  not takes. Each shot generates its own audio, so write
+  `non_diegetic_music: N/A` in every shot and lay one score under the concat
+  afterwards: `templates/minimax/music` writes the track and
+  `templates/assemble-and-score` shows the `pair_audio` step that mixes it
+  under the world sound (it takes three shots; for more, author the concat
+  and score steps the same way). A character who speaks in several shots
+  keeps one voice by passing the same clip as an audio reference in each
+  (the `voice-timbre-reference` pattern); a repeated voice description alone
+  drifts. Each entry's `num_frames` is its own, so pace the cut. The
+  reference carries delivery as well as timbre: a flat read gives a flat
+  performance. Bark's presets are conversational; for a narrator with
+  gravitas, `upload_asset` a recorded read in that register and reference
+  the same file in every shot.
 - **Music alone**: `templates/minimax/music` (Music3); the `minimax-music3` skill.
 
 If none fits, compose from `list_tasks` before authoring a new workflow, and
diff --git a/tests/test_catalog_shape.py b/tests/test_catalog_shape.py
index 14a75465..81aad628 100644
--- a/tests/test_catalog_shape.py
+++ b/tests/test_catalog_shape.py
@@ -159,6 +159,25 @@ def test_a_concat_fed_by_two_steps_is_a_sequence():
     assert meta["shape"] == "sequence"
 
 
+def test_a_concat_over_a_gathered_for_each_group_is_a_sequence():
+    """A list-driven template's editor says "videos": "gather:shot" - a
+    cut over as many shots as the list holds, which the file cannot count."""
+    meta = derive_catalog_metadata(
+        definition(
+            {
+                "name": "shot",
+                "for_each": "variable:shots",
+                "pipeline": {
+                    "arguments": {"prompt": "item:prompt"},
+                },
+                "result": {"content_type": "video/mp4"},
+            },
+            task_step("cut", "concat_videos", {"videos": "gather:shot"}, "video/mp4"),
+        )
+    )
+    assert meta["shape"] == "sequence"
+
+
 def test_a_dissolve_fed_by_two_steps_is_a_sequence():
     meta = derive_catalog_metadata(
         definition(
@@ -388,6 +407,36 @@ def test_the_schema_declares_the_vocabulary():
     cost_item = props["cost"]["items"]
     assert set(cost_item["required"]) == {"device", "vram_gb", "minutes"}
     assert cost_item["properties"]["device"]["enum"] == ["cuda", "mps", "cpu"]
+    per_entry = cost_item["properties"]["per_entry"]
+    assert set(per_entry["required"]) == {"variable", "minutes", "entries"}
+    assert per_entry["additionalProperties"] is False
+
+
+def test_a_per_entry_cost_validates_and_a_partial_one_does_not():
+    schema = load_schema("workflow")
+    base = definition(pipeline_step("g", "image/jpeg"))
+    cost = {"device": "cuda", "vram_gb": 24, "minutes": 42}
+    ok, _ = validate_data(
+        {
+            **base,
+            "cost": [
+                {
+                    **cost,
+                    "per_entry": {"variable": "shots", "minutes": 7.2, "entries": 5},
+                }
+            ],
+        },
+        schema,
+    )
+    assert ok
+    bad, message = validate_data(
+        {
+            **base,
+            "cost": [{**cost, "per_entry": {"variable": "shots", "minutes": 7.2}}],
+        },
+        schema,
+    )
+    assert not bad and "per_entry" in message
 
 
 def test_a_declared_cost_validates_and_a_bad_one_does_not():
@@ -419,6 +468,7 @@ def entry(shape, traits=(), configures="", **extra):
         "variable_names": [],
         "description": "long text",
         "configures": configures,
+        "lists": {},
         "prompt_refs": [],
         "origin": "workspace",
         "writable": True,
@@ -464,7 +514,10 @@ def test_configures_filters_to_a_templates_configs():
 def test_compact_drops_prose_and_model_configs_and_keeps_user_workflows():
     compact = project_listing(LISTING, view="compact")
     assert set(compact) == {"templates/tti", "templates/talk", "templates/clip", "mine"}
-    assert set(compact["templates/tti"]) == set(COMPACT_FIELDS) - {"configures"}
+    assert set(compact["templates/tti"]) == set(COMPACT_FIELDS) - {
+        "configures",
+        "lists",
+    }
     assert "description" not in compact["templates/tti"]
     assert "steps" not in compact["templates/tti"]
     assert "variables" not in compact["templates/tti"]
@@ -608,3 +661,59 @@ def test_an_image_pipeline_carrying_a_vocoder_does_not():
     step = pipeline_step("still", "image/jpeg")
     step["pipeline"]["configuration"]["components"] = {"vocoder": {"device": "cuda"}}
     assert "has-audio" not in derive_catalog_metadata(definition(step))["traits"]
+
+
+def for_each_step(name, variable, arguments):
+    return {
+        "name": name,
+        "for_each": f"variable:{variable}",
+        "pipeline": {
+            "configuration": {"component_type": "{Fake}"},
+            "arguments": arguments,
+        },
+        "result": {"content_type": "video/mp4"},
+    }
+
+
+def test_lists_name_the_fields_an_entry_takes_and_the_default_length():
+    meta = derive_catalog_metadata(
+        definition(
+            for_each_step(
+                "shot", "shots", {"prompt": "item:prompt", "n": "item:num_frames"}
+            ),
+            variables={"shots": [{"name": "a", "prompt": "p", "num_frames": 1}] * 3},
+        )
+    )
+    assert meta["lists"] == {
+        "shots": {
+            "fields": ["name", "num_frames", "prompt"],
+            "steps": ["shot"],
+            "entries": 3,
+        }
+    }
+
+
+def test_lists_is_empty_without_for_each_and_entries_is_none_without_a_list_default():
+    assert (
+        derive_catalog_metadata(definition(pipeline_step("g", "image/jpeg")))["lists"]
+        == {}
+    )
+    meta = derive_catalog_metadata(
+        definition(for_each_step("shot", "shots", {"prompt": "item:prompt"}))
+    )
+    assert meta["lists"]["shots"]["entries"] is None
+
+
+def test_compact_carries_lists_only_when_there_are_any():
+    listing = {
+        "plain": entry("image"),
+        "cut": entry(
+            "sequence",
+            lists={
+                "shots": {"fields": ["name", "prompt"], "steps": ["shot"], "entries": 2}
+            },
+        ),
+    }
+    compact = project_listing(listing, view="compact")
+    assert "lists" not in compact["plain"]
+    assert compact["cut"]["lists"]["shots"]["fields"] == ["name", "prompt"]
diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index 9f08baa5..7785ea73 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -203,6 +203,73 @@ def test_a_declared_cost_is_well_formed(path):
         ), path
 
 
+def per_entry_problems(definition):
+    """The checks a per_entry cost has to satisfy: its 'variable' is a
+    for_each list this definition actually reads, and 'entries' is that
+    list's default length - a stale figure left behind by an edited
+    default is otherwise invisible until the wrong minutes gets quoted."""
+    from dw.for_each import list_fields
+
+    problems = []
+    for entry in definition.get("cost") or []:
+        per_entry = entry.get("per_entry")
+        if per_entry is None:
+            continue
+        lists = list_fields(definition)
+        variable = per_entry["variable"]
+        if variable not in lists:
+            problems.append(f"{variable} is not a for_each list")
+            continue
+        default = (definition.get("variables") or {}).get(variable)
+        if not (isinstance(default, list) and len(default) == per_entry["entries"]):
+            problems.append(
+                f"entries={per_entry['entries']} does not match the default "
+                f"list's length ({default!r})"
+            )
+    return problems
+
+
+@pytest.mark.parametrize("path", TEMPLATES + MODEL_CONFIGS)
+def test_a_per_entry_cost_names_a_list_the_steps_read(path):
+    """per_entry is measured over the default list, so the variable it
+    names must be one a for_each expands and `entries` must be that
+    list's length - an edited default that forgot the cost block fails
+    here."""
+    definition = load(path)
+    problems = per_entry_problems(definition)
+    assert not problems, f"{path}: {problems}"
+
+
+def test_per_entry_problems_reports_a_mismatched_entries_count():
+    """Synthetic case so the check above is not vacuous while no bundled
+    template carries a per_entry cost yet."""
+    definition = {
+        "variables": {"shots": [{"name": "a"}, {"name": "b"}]},
+        "steps": [
+            {
+                "name": "shot",
+                "for_each": "variable:shots",
+                "pipeline": {
+                    "configuration": {"component_type": "{Fake}"},
+                    "from_pretrained_arguments": {"model_name": "m"},
+                    "arguments": {"name": "item:name"},
+                },
+                "result": {"content_type": "image/jpeg"},
+            }
+        ],
+        "cost": [
+            {
+                "device": "cuda",
+                "vram_gb": 24,
+                "minutes": 10,
+                "per_entry": {"variable": "shots", "minutes": 5, "entries": 5},
+            }
+        ],
+    }
+    problems = per_entry_problems(definition)
+    assert problems and "entries=5" in problems[0]
+
+
 # The catalog's descriptions quote identifiers in single quotes, not
 # backticks - JSON strings, where a backtick reads as a stray character.
 QUOTED = re.compile(r"'([a-z_][a-z0-9_]*)'")
@@ -219,6 +286,8 @@ def test_a_declared_cost_is_well_formed(path):
     "workflows/templates/image-to-text.json": {"model_name", "prompt"},
     # a field of the step's 'chain' block
     "workflows/templates/minimax/chained-segments.json": {"trim_frames"},
+    # fields of a 'shots' list entry, not this workflow's own variables
+    "workflows/templates/minimax/dialogue-short.json": {"prompt", "num_frames"},
     # the fl2va sub-workflow's argument, named to say this one leaves it unset
     "workflows/templates/minimax/last-frame-only.json": {"image"},
     # a 'result' field the modular pipeline needs declared
diff --git a/tests/test_cli.py b/tests/test_cli.py
index e9b73a60..87ec94c3 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -82,6 +82,27 @@ def test_a_traversing_path_is_refused_before_anything_is_read(
         assert code == 1
         assert "Security validation failed" in capsys.readouterr().out
 
+    def test_trust_workflows_flag_is_accepted_and_wired(
+        self, workflow_file, monkeypatch, capsys
+    ):
+        """--trust-workflows must parse (dw.run has long had it; dw.validate
+        did not) and actually flip the trust gate before the workflow is
+        loaded/validated, since validation now realizes 'constant:' defaults
+        through the same gate a run would."""
+        seen = []
+        monkeypatch.setattr(
+            validate_module, "set_trust_workflows", lambda v: seen.append(v)
+        )
+
+        code = invoke(
+            validate_module,
+            monkeypatch,
+            ["dw-validate", "--trust-workflows", str(workflow_file)],
+        )
+        assert code == 0
+        assert seen == [True]
+        assert "validated successfully" in capsys.readouterr().out
+
 
 class TestRunEntryPoint:
     def test_name_value_arguments_reach_the_workflow(
diff --git a/tests/test_dialogue_short_voices.py b/tests/test_dialogue_short_voices.py
index 7112c8db..5a52bf18 100644
--- a/tests/test_dialogue_short_voices.py
+++ b/tests/test_dialogue_short_voices.py
@@ -6,16 +6,18 @@
 `character_b_voice` name a clip instead, and each shot appends an audio
 reference for whoever speaks in it. Null is the default, and null means the
 reference is not there at all - so the template still generates exactly what
-it generated before the variables existed.
+it generated before the variables existed. The shots are entries of a list
+now, and an entry's voice reference names the variable, so the same one
+variable still sets the voice everywhere.
 """
 
 import json
 import os
+import tempfile
 
 import pytest
 
 from dw.arguments import realize_args
-from dw.variables import replace_variables
 
 TEMPLATE = os.path.join(
     os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
@@ -25,14 +27,14 @@
     "dialogue-short.json",
 )
 
-# Which character speaks in which shot - the template appends a voice
+# Which character speaks in which shot - each entry lists a voice
 # reference per speaker, and this is the mapping it is asserted against
 SPEAKERS = {
-    "shot_1_cold_open": ("a", "b"),
-    "shot_2_deflect": ("b",),
-    "shot_3_react": ("a",),
-    "shot_4_button": ("b",),
-    "shot_5_tag": ("a", "b"),
+    "shot@cold_open": ("a", "b"),
+    "shot@deflect": ("b",),
+    "shot@react": ("a",),
+    "shot@button": ("b",),
+    "shot@tag": ("a", "b"),
 }
 
 
@@ -42,17 +44,23 @@ def definition():
         return json.load(file)
 
 
-def shot_references(definition, variables):
-    """Every shot's references, as the engine realizes them for a run."""
-    resolved = replace_variables(definition, variables)
+def shot_references(arguments):
+    """Every shot member's references, as the engine realizes them for a
+    run: the caller's arguments folded, entries resolved, the list expanded,
+    then each member's arguments realized as its step would."""
+    from dw.workflow import workflow_from_file
+
+    expanded = workflow_from_file(TEMPLATE, tempfile.mkdtemp()).expanded_definition(
+        arguments
+    )
     references = {}
-    for step in resolved["steps"]:
+    for step in expanded["steps"]:
         if step["name"] not in SPEAKERS:
             continue
-        block = step.get("pipeline") or step.get("pipeline_reference")
-        arguments = block["arguments"]
-        realize_args(arguments)
-        references[step["name"]] = arguments["references"]
+        step_arguments = step["pipeline"]["arguments"]
+        realize_args(step_arguments)
+        references[step["name"]] = step_arguments["references"]
+    assert set(references) == set(SPEAKERS)
     return references
 
 
@@ -62,10 +70,16 @@ def test_the_voices_default_to_null(self, definition):
         assert variables["character_a_voice"] is None
         assert variables["character_b_voice"] is None
 
+    def test_every_entry_names_the_voice_variables_rather_than_a_file(self, definition):
+        for entry in definition["variables"]["shots"]:
+            voices = [r["from_file"] for r in entry["references"] if "from_file" in r]
+            assert voices, entry["name"]
+            assert all(v.startswith("variable:character_") for v in voices), entry[
+                "name"
+            ]
+
     def test_no_voice_named_leaves_only_the_portraits(self, definition):
-        for name, references in shot_references(
-            definition, dict(definition["variables"])
-        ).items():
+        for name, references in shot_references({}).items():
             assert len(references) == len(set(SPEAKERS[name])), name
             assert all(
                 reference["from_previous_result"].startswith("draw_character")
@@ -79,20 +93,38 @@ def test_a_named_voice_is_referenced_in_the_shots_it_speaks_in(
 
         voice = tmp_path / "priya.wav"
         write_wav(voice, seconds=1.0)
-        variables = dict(definition["variables"])
-        variables["character_a_voice"] = str(voice)
 
-        for name, references in shot_references(definition, variables).items():
+        for name, references in shot_references(
+            {"character_a_voice": str(voice)}
+        ).items():
             built = [r for r in references if not isinstance(r, dict)]
             assert len(built) == (1 if "a" in SPEAKERS[name] else 0), name
 
+    def test_the_tag_runs_longer(self, definition):
+        frames = {e["name"]: e["num_frames"] for e in definition["variables"]["shots"]}
+        assert frames == {
+            "cold_open": 124,
+            "deflect": 124,
+            "react": 124,
+            "button": 124,
+            "tag": 141,
+        }
+
     def test_the_variable_names_are_roles_rather_than_a_cast(self, definition):
         """Every run carried howie_portrait_prompt and shot_3_howie_incredulous
         through its arguments, manifest and export whatever the cast was."""
-        names = " ".join(definition["variables"]) + " ".join(
-            step["name"] for step in definition["steps"]
+        names = (
+            " ".join(definition["variables"])
+            + " ".join(step["name"] for step in definition["steps"])
+            + " ".join(e["name"] for e in definition["variables"]["shots"])
         )
         assert "howie" not in names.lower()
         assert "pat_" not in names.lower()
         assert "character_a_portrait_prompt" in definition["variables"]
-        assert "shot_3_react" in definition["variables"]
+        assert [e["name"] for e in definition["variables"]["shots"]] == [
+            "cold_open",
+            "deflect",
+            "react",
+            "button",
+            "tag",
+        ]
diff --git a/tests/test_for_each.py b/tests/test_for_each.py
new file mode 100644
index 00000000..e44ef5b7
--- /dev/null
+++ b/tests/test_for_each.py
@@ -0,0 +1,943 @@
+import copy
+import json
+import os
+import tempfile
+
+import pytest
+
+from dw.for_each import (
+    MAX_FOR_EACH_ENTRIES,
+    ForEachError,
+    entry_field_warnings,
+    expand_for_each,
+    list_fields,
+    member_name,
+)
+
+
+def definition(*steps, **extra):
+    return {"id": "test", "steps": list(steps), **extra}
+
+
+TEMPLATES = os.path.normpath(
+    os.path.join(os.path.dirname(__file__), "..", "workflows", "templates", "minimax")
+)
+
+
+def load_template(name):
+    with open(os.path.join(TEMPLATES, name)) as f:
+        return json.load(f)
+
+
+def load_workflow(name, output_dir=None):
+    from dw.workflow import workflow_from_file
+
+    if output_dir is None:
+        output_dir = tempfile.mkdtemp()
+    return workflow_from_file(os.path.join(TEMPLATES, name), output_dir)
+
+
+def steps_by_name(definition):
+    return {s["name"]: s for s in definition["steps"]}
+
+
+class TestNaming:
+    def test_member_name_joins_with_at(self):
+        assert member_name("shot", "wide_open") == "shot@wide_open"
+
+    def test_an_object_entry_is_named_by_its_name(self):
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "shot",
+                    "for_each": [{"name": "wide_open"}, {"name": "closeup"}],
+                    "task": {"command": "x", "arguments": {}},
+                }
+            )
+        )
+        assert [s["name"] for s in expanded["steps"]] == [
+            "shot@wide_open",
+            "shot@closeup",
+        ]
+
+    def test_a_nameless_entry_is_named_by_its_index(self):
+        expanded = expand_for_each(
+            definition(
+                {"name": "shot", "for_each": ["a", "b"], "task": {"arguments": {}}}
+            )
+        )
+        assert [s["name"] for s in expanded["steps"]] == ["shot@0", "shot@1"]
+
+    def test_for_each_is_dropped_from_the_members(self):
+        expanded = expand_for_each(
+            definition({"name": "shot", "for_each": ["a"], "task": {}})
+        )
+        assert "for_each" not in expanded["steps"][0]
+
+    def test_the_input_is_not_mutated(self):
+        original = definition({"name": "shot", "for_each": ["a"], "task": {}})
+        before = copy.deepcopy(original)
+        expand_for_each(original)
+        assert original == before
+
+    def test_a_workflow_without_for_each_comes_back_equal(self):
+        original = definition({"name": "plain", "task": {"arguments": {"a": 1}}})
+        assert expand_for_each(original) == original
+
+    def test_a_hand_written_at_sign_is_an_error(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(definition({"name": "shot@0", "task": {}}))
+        assert e.value.path == "steps[0].name"
+        assert "@" in str(e.value)
+
+    def test_a_duplicate_entry_name_is_an_error(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition(
+                    {
+                        "name": "shot",
+                        "for_each": [{"name": "closeup"}, {"name": "closeup"}],
+                        "task": {},
+                    }
+                )
+            )
+        assert e.value.path == "steps[0].for_each[1].name"
+        assert "closeup" in str(e.value)
+
+    def test_an_invalid_entry_name_is_an_error(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition(
+                    {"name": "shot", "for_each": [{"name": "wide open"}], "task": {}}
+                )
+            )
+        assert e.value.path == "steps[0].for_each[0].name"
+
+    def test_a_non_list_for_each_is_an_error(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(definition({"name": "shot", "for_each": 4, "task": {}}))
+        assert e.value.path == "steps[0].for_each"
+        assert "list" in str(e.value)
+
+    def test_an_unsubstituted_variable_is_an_error_that_says_so(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition({"name": "shot", "for_each": "variable:shots", "task": {}})
+            )
+        assert "variable:shots" in str(e.value)
+
+    def test_an_empty_list_is_an_error_at_the_step(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(definition({"name": "shot", "for_each": [], "task": {}}))
+        assert e.value.path == "steps[0].for_each"
+        assert "would run no steps" in str(e.value)
+
+    def test_the_ceiling_is_enforced(self):
+        entries = [{"name": f"s{i}"} for i in range(MAX_FOR_EACH_ENTRIES + 1)]
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition({"name": "shot", "for_each": entries, "task": {}})
+            )
+        assert str(MAX_FOR_EACH_ENTRIES) in str(e.value)
+
+    def test_a_list_at_the_ceiling_is_fine(self):
+        entries = [{"name": f"s{i}"} for i in range(MAX_FOR_EACH_ENTRIES)]
+        expanded = expand_for_each(
+            definition({"name": "shot", "for_each": entries, "task": {}})
+        )
+        assert len(expanded["steps"]) == MAX_FOR_EACH_ENTRIES
+
+
+class TestItemSubstitution:
+    def test_a_field_is_substituted(self):
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "shot",
+                    "for_each": [{"name": "a", "prompt": "the band walks on"}],
+                    "pipeline": {"arguments": {"prompt": "item:prompt"}},
+                }
+            )
+        )
+        assert expanded["steps"][0]["pipeline"]["arguments"]["prompt"] == (
+            "the band walks on"
+        )
+
+    def test_a_bare_item_is_the_whole_entry(self):
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "shot",
+                    "for_each": ["first prompt", "second prompt"],
+                    "pipeline": {"arguments": {"prompt": "item:"}},
+                }
+            )
+        )
+        prompts = [s["pipeline"]["arguments"]["prompt"] for s in expanded["steps"]]
+        assert prompts == ["first prompt", "second prompt"]
+
+    def test_a_structured_field_is_spliced_whole(self):
+        references = [
+            {"reference_type": "T", "from_previous_result": "draw_a"},
+            {"reference_type": "T", "from_previous_result": "draw_b"},
+        ]
+        expanded = expand_for_each(
+            definition(
+                {"name": "draw_a", "task": {}},
+                {"name": "draw_b", "task": {}},
+                {
+                    "name": "shot",
+                    "for_each": [{"name": "open", "references": references}],
+                    "pipeline": {"arguments": {"references": "item:references"}},
+                },
+            )
+        )
+        assert expanded["steps"][2]["pipeline"]["arguments"]["references"] == references
+
+    def test_a_number_keeps_its_type(self):
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "slice",
+                    "for_each": [{"name": "a", "start_frame": 124}],
+                    "task": {"arguments": {"start_frame": "item:start_frame"}},
+                }
+            )
+        )
+        assert expanded["steps"][0]["task"]["arguments"]["start_frame"] == 124
+
+    def test_item_is_substituted_at_any_depth(self):
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "shot",
+                    "for_each": [{"name": "a", "voice": "asset:a.wav"}],
+                    "pipeline": {
+                        "arguments": {"references": [{"from_file": "item:voice"}]}
+                    },
+                }
+            )
+        )
+        assert expanded["steps"][0]["pipeline"]["arguments"]["references"] == [
+            {"from_file": "asset:a.wav"}
+        ]
+
+    def test_a_missing_field_is_an_error_at_its_path(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition(
+                    {
+                        "name": "shot",
+                        "for_each": [{"name": "a"}],
+                        "pipeline": {"arguments": {"prompt": "item:prompt"}},
+                    }
+                )
+            )
+        assert e.value.path == "steps[0].pipeline.arguments.prompt"
+        assert "prompt" in str(e.value) and "a" in str(e.value)
+
+    def test_a_field_of_a_string_entry_is_an_error(self):
+        with pytest.raises(ForEachError):
+            expand_for_each(
+                definition(
+                    {
+                        "name": "shot",
+                        "for_each": ["just a prompt"],
+                        "pipeline": {"arguments": {"prompt": "item:prompt"}},
+                    }
+                )
+            )
+
+    def test_item_outside_a_for_each_step_is_an_error(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition({"name": "plain", "task": {"arguments": {"p": "item:x"}}})
+            )
+        assert e.value.path == "steps[0].task.arguments.p"
+
+    def test_members_do_not_share_mutable_values(self):
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "shot",
+                    "for_each": [{"name": "a"}, {"name": "b"}],
+                    "pipeline": {"arguments": {"references": [{"k": 1}]}},
+                }
+            )
+        )
+        first, second = expanded["steps"]
+        first["pipeline"]["arguments"]["references"][0]["k"] = 2
+        assert second["pipeline"]["arguments"]["references"][0]["k"] == 1
+
+
+class TestSourceIndices:
+    """The expansion records where each step came from in the source file.
+
+    A parallel list rather than a key on the step: step_data is what the
+    step cache keys on and what the schema validates, so nothing new may
+    appear in it.
+    """
+
+    def test_every_expanded_step_records_its_source_index(self):
+        source_indices = []
+        expanded = expand_for_each(
+            definition(
+                {"name": "draw", "task": {}},
+                {"name": "shot", "for_each": ["a", "b", "c"], "task": {}},
+                {"name": "edit", "task": {}},
+            ),
+            source_indices,
+        )
+        assert [s["name"] for s in expanded["steps"]] == [
+            "draw",
+            "shot@0",
+            "shot@1",
+            "shot@2",
+            "edit",
+        ]
+        assert source_indices == [0, 1, 1, 1, 2]
+
+    def test_the_list_is_optional(self):
+        expanded = expand_for_each(
+            definition({"name": "shot", "for_each": ["a"], "task": {}})
+        )
+        assert [s["name"] for s in expanded["steps"]] == ["shot@0"]
+
+
+class TestLeafCopying:
+    """A leaf is copied only where the copy is needed - inside a member.
+
+    expand_for_each runs on every run of every workflow, after realize_args
+    has turned 'asset:' and '*_image' arguments into loaded PIL images and
+    decoded frame lists. Copying every leaf of every step would multiply
+    that media, and a leaf that cannot be copied at all would fail a run
+    that has always worked.
+    """
+
+    class Uncopyable:
+        def __deepcopy__(self, memo):
+            raise TypeError("cannot copy this")
+
+    def test_a_leaf_outside_a_member_is_passed_through_by_identity(self):
+        leaf = self.Uncopyable()
+        expanded = expand_for_each(
+            definition({"name": "plain", "task": {"arguments": {"model": leaf}}})
+        )
+        assert expanded["steps"][0]["task"]["arguments"]["model"] is leaf
+
+    def test_a_leaf_inside_a_member_that_cannot_be_copied_is_the_object_itself(self):
+        # The step cache makes the same choice for a realized argument it
+        # cannot deep-copy: the run goes on, with the object as it is
+        leaf = self.Uncopyable()
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "shot",
+                    "for_each": ["a", "b"],
+                    "task": {"arguments": {"model": leaf}},
+                }
+            )
+        )
+        assert [s["task"]["arguments"]["model"] for s in expanded["steps"]] == [
+            leaf,
+            leaf,
+        ]
+
+
+class TestRelease:
+    def test_release_flags_survive_on_the_last_member_only(self):
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "shot",
+                    "for_each": [{"name": "a"}, {"name": "b"}, {"name": "c"}],
+                    "release_pipeline": True,
+                    "release_models": True,
+                    "pipeline": {},
+                }
+            )
+        )
+        flags = [
+            (s.get("release_pipeline"), s.get("release_models"))
+            for s in expanded["steps"]
+        ]
+        assert flags == [(None, None), (None, None), (True, True)]
+
+
+class TestGather:
+    def group(self, *extra):
+        return definition(
+            {
+                "name": "shot",
+                "for_each": [{"name": "open"}, {"name": "close"}],
+                "pipeline": {"arguments": {}},
+            },
+            *extra,
+        )
+
+    def test_a_scalar_gather_becomes_the_member_list(self):
+        expanded = expand_for_each(
+            self.group(
+                {"name": "edit", "task": {"arguments": {"videos": "gather:shot"}}}
+            )
+        )
+        assert expanded["steps"][-1]["task"]["arguments"]["videos"] == [
+            "previous_result:shot@open",
+            "previous_result:shot@close",
+        ]
+
+    def test_a_gather_inside_a_list_splices(self):
+        expanded = expand_for_each(
+            self.group(
+                {"name": "intro", "task": {}},
+                {
+                    "name": "edit",
+                    "task": {
+                        "arguments": {
+                            "videos": ["previous_result:intro", "gather:shot"]
+                        }
+                    },
+                },
+            )
+        )
+        assert expanded["steps"][-1]["task"]["arguments"]["videos"] == [
+            "previous_result:intro",
+            "previous_result:shot@open",
+            "previous_result:shot@close",
+        ]
+
+    def test_gather_of_a_plain_step_is_an_error(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition(
+                    {"name": "one", "task": {}},
+                    {"name": "edit", "task": {"arguments": {"videos": "gather:one"}}},
+                )
+            )
+        assert e.value.path == "steps[1].task.arguments.videos"
+        assert "no earlier for_each step" in str(e.value)
+
+    def test_gather_of_a_later_group_is_an_error(self):
+        with pytest.raises(ForEachError):
+            expand_for_each(
+                definition(
+                    {"name": "edit", "task": {"arguments": {"videos": "gather:shot"}}},
+                    {"name": "shot", "for_each": ["a"], "task": {}},
+                )
+            )
+
+    def test_gather_in_a_sub_workflow_argument_map(self):
+        expanded = expand_for_each(
+            self.group(
+                {
+                    "name": "score",
+                    "workflow": {
+                        "path": "builtin:x.json",
+                        "arguments": {"clips": "gather:shot"},
+                    },
+                }
+            )
+        )
+        assert expanded["steps"][-1]["workflow"]["arguments"]["clips"] == [
+            "previous_result:shot@open",
+            "previous_result:shot@close",
+        ]
+
+
+class TestGroupReferences:
+    def test_previous_result_naming_a_group_says_to_gather(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition(
+                    {"name": "shot", "for_each": ["a"], "task": {}},
+                    {
+                        "name": "edit",
+                        "task": {"arguments": {"video": "previous_result:shot"}},
+                    },
+                )
+            )
+        assert e.value.path == "steps[1].task.arguments.video"
+        assert "gather:shot" in str(e.value)
+
+    def test_from_previous_result_naming_a_group_says_to_gather(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition(
+                    {"name": "shot", "for_each": ["a"], "task": {}},
+                    {
+                        "name": "edit",
+                        "task": {
+                            "arguments": {"refs": [{"from_previous_result": "shot"}]}
+                        },
+                    },
+                )
+            )
+        assert e.value.path == "steps[1].task.arguments.refs[0].from_previous_result"
+
+    def test_a_property_reference_to_a_group_is_also_refused(self):
+        with pytest.raises(ForEachError):
+            expand_for_each(
+                definition(
+                    {"name": "shot", "for_each": ["a"], "task": {}},
+                    {
+                        "name": "edit",
+                        "task": {"arguments": {"v": "previous_result:shot.frames"}},
+                    },
+                )
+            )
+
+    def test_a_reference_to_an_ordinary_step_is_untouched(self):
+        expanded = expand_for_each(
+            definition(
+                {"name": "draw", "task": {}},
+                {
+                    "name": "shot",
+                    "for_each": ["a"],
+                    "pipeline": {
+                        "arguments": {
+                            "references": [{"from_previous_result": "draw"}],
+                            "still": "previous_result:draw.image",
+                        }
+                    },
+                },
+            )
+        )
+        arguments = expanded["steps"][1]["pipeline"]["arguments"]
+        assert arguments["references"] == [{"from_previous_result": "draw"}]
+        assert arguments["still"] == "previous_result:draw.image"
+
+    def test_a_variable_spelled_from_previous_result_is_untouched(self):
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "edit",
+                    "task": {
+                        "arguments": {"r": [{"from_previous_result": "variable:x"}]}
+                    },
+                }
+            )
+        )
+        assert expanded["steps"][0]["task"]["arguments"]["r"] == [
+            {"from_previous_result": "variable:x"}
+        ]
+
+
+class TestSameKeySiblings:
+    def shots(self):
+        return [
+            {"name": "open", "start_frame": 0},
+            {"name": "close", "start_frame": 124},
+        ]
+
+    def test_a_sibling_over_the_same_list_resolves_to_the_same_key(self):
+        shots = self.shots()
+        expanded = expand_for_each(
+            definition(
+                {
+                    "name": "slice",
+                    "for_each": shots,
+                    "task": {"arguments": {"start_frame": "item:start_frame"}},
+                },
+                {
+                    "name": "shot",
+                    "for_each": shots,
+                    "pipeline": {
+                        "arguments": {
+                            "references": [{"from_previous_result": "slice"}],
+                            "audio": "previous_result:slice.audio",
+                        }
+                    },
+                },
+            )
+        )
+        names = [s["name"] for s in expanded["steps"]]
+        assert names == ["slice@open", "slice@close", "shot@open", "shot@close"]
+        close = expanded["steps"][3]["pipeline"]["arguments"]
+        assert close["references"] == [{"from_previous_result": "slice@close"}]
+        assert close["audio"] == "previous_result:slice@close.audio"
+
+    def test_the_same_list_means_equal_not_identical(self):
+        expanded = expand_for_each(
+            definition(
+                {"name": "slice", "for_each": self.shots(), "task": {}},
+                {
+                    "name": "shot",
+                    "for_each": self.shots(),
+                    "task": {"arguments": {"a": "previous_result:slice"}},
+                },
+            )
+        )
+        assert expanded["steps"][2]["task"]["arguments"]["a"] == (
+            "previous_result:slice@open"
+        )
+
+    def test_a_sibling_over_a_different_list_is_an_error(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition(
+                    {"name": "slice", "for_each": ["a", "b"], "task": {}},
+                    {
+                        "name": "shot",
+                        "for_each": ["a"],
+                        "task": {"arguments": {"x": "previous_result:slice"}},
+                    },
+                )
+            )
+        assert "different list" in str(e.value)
+
+    def test_a_step_referencing_its_own_group_is_an_error(self):
+        with pytest.raises(ForEachError) as e:
+            expand_for_each(
+                definition(
+                    {
+                        "name": "shot",
+                        "for_each": ["a", "b"],
+                        "task": {"arguments": {"x": "previous_result:shot"}},
+                    }
+                )
+            )
+        assert "its own" in str(e.value)
+
+    def test_a_gather_inside_a_member_still_gathers(self):
+        expanded = expand_for_each(
+            definition(
+                {"name": "slice", "for_each": ["a", "b"], "task": {}},
+                {
+                    "name": "shot",
+                    "for_each": ["x"],
+                    "task": {"arguments": {"all": "gather:slice"}},
+                },
+            )
+        )
+        assert expanded["steps"][2]["task"]["arguments"]["all"] == [
+            "previous_result:slice@0",
+            "previous_result:slice@1",
+        ]
+
+
+class TestMusicVideoTemplate:
+    """music-video's slices and shots are two for_each groups over one
+    'shots' list, paired by entry name: shot@closeup reads slice@closeup."""
+
+    KEYS = ["wide_open", "closeup", "room", "finale"]
+
+    def expanded(self):
+        return load_workflow("music-video.json").expanded_definition()
+
+    def test_the_template_validates_as_it_will_run(self):
+        assert load_workflow("music-video.json").validation_errors() == []
+
+    def test_one_slice_and_one_shot_per_entry_in_list_order(self):
+        names = [s["name"] for s in self.expanded()["steps"]]
+        assert names == (
+            ["draw_singer", "write_song"]
+            + [f"slice@{k}" for k in self.KEYS]
+            + ["soundtrack"]
+            + [f"shot@{k}" for k in self.KEYS]
+            + ["edit", "music_video"]
+        )
+
+    def test_each_slice_starts_where_its_entry_says(self):
+        got = steps_by_name(self.expanded())
+        starts = [
+            got[f"slice@{k}"]["task"]["arguments"]["start_frame"] for k in self.KEYS
+        ]
+        assert starts == [0, 124, 248, 372]
+
+    def test_each_shot_reads_its_own_slice_and_the_one_portrait(self):
+        got = steps_by_name(self.expanded())
+        for key in self.KEYS:
+            references = got[f"shot@{key}"]["pipeline"]["arguments"]["references"]
+            assert [r["from_previous_result"] for r in references] == [
+                "draw_singer",
+                f"slice@{key}",
+            ]
+
+    def test_each_shot_carries_its_entry_s_prompt(self):
+        template = load_template("music-video.json")
+        got = steps_by_name(self.expanded())
+        for entry in template["variables"]["shots"]:
+            prompt = got[f"shot@{entry['name']}"]["pipeline"]["arguments"]["prompt"]
+            assert prompt == entry["prompt"]
+            assert prompt.startswith("subject_definitions:")
+
+    def test_every_shot_is_the_same_pipeline(self):
+        """Full pipeline blocks rather than pipeline_reference: the identity
+        cache reuses the loaded model, so this costs no reload."""
+        from dw.workflow import pipeline_cache_key
+
+        got = steps_by_name(self.expanded())
+        keys = {pipeline_cache_key(got[f"shot@{k}"]["pipeline"]) for k in self.KEYS}
+        assert len(keys) == 1
+
+    def test_the_edit_gathers_the_shots_in_order(self):
+        got = steps_by_name(self.expanded())
+        assert got["edit"]["task"]["arguments"]["videos"] == [
+            f"previous_result:shot@{k}" for k in self.KEYS
+        ]
+
+    def test_the_template_keeps_the_list(self):
+        """The template on disk keeps 'for_each' and the 'shots' variable
+        rather than expanded members - the realized workflow.json a run
+        writes is built from this same definition, but that is not what
+        this test reads."""
+        template = load_template("music-video.json")
+        assert "shots" in template["variables"]
+        assert [s["name"] for s in template["steps"] if "for_each" in s] == [
+            "slice",
+            "shot",
+        ]
+
+    def test_each_shot_keeps_the_generation_settings(self):
+        got = steps_by_name(self.expanded())
+        for key in self.KEYS:
+            arguments = got[f"shot@{key}"]["pipeline"]["arguments"]
+            assert arguments["num_frames"] == 124
+            assert arguments["width"] == 960
+            assert arguments["height"] == 544
+            assert arguments["num_inference_steps"] == 9
+            assert arguments["output"] == ["videos", "audio", "sampling_rate"]
+            loras = got[f"shot@{key}"]["pipeline"]["loras"]
+            assert len(loras) == 1
+            assert loras[0]["model_name"] == "lightx2v/Minimax-h3-Turbo"
+
+
+class TestDialogueShortTemplate:
+    """dialogue-short's five shots are one for_each group whose entries
+    carry everything that differs between shots: prompt, references and
+    length."""
+
+    KEYS = ["cold_open", "deflect", "react", "button", "tag"]
+
+    def expanded(self):
+        return load_workflow("dialogue-short.json").expanded_definition()
+
+    def test_the_template_validates_as_it_will_run(self):
+        assert load_workflow("dialogue-short.json").validation_errors() == []
+
+    def test_one_shot_per_entry_between_the_cast_and_the_edit(self):
+        names = [s["name"] for s in self.expanded()["steps"]]
+        assert names == (
+            ["draw_character_a", "draw_character_b"]
+            + [f"shot@{k}" for k in self.KEYS]
+            + ["episode"]
+        )
+
+    def test_each_shot_references_the_portraits_its_entry_lists(self):
+        got = steps_by_name(self.expanded())
+        portraits = {
+            key: [
+                r["from_previous_result"]
+                for r in got[f"shot@{key}"]["pipeline"]["arguments"]["references"]
+                if "from_previous_result" in r
+            ]
+            for key in self.KEYS
+        }
+        assert portraits == {
+            "cold_open": ["draw_character_a", "draw_character_b"],
+            "deflect": ["draw_character_b"],
+            "react": ["draw_character_a"],
+            "button": ["draw_character_b"],
+            "tag": ["draw_character_a", "draw_character_b"],
+        }
+
+    def test_the_reference_types_are_resolved_inside_the_entries(self):
+        """An entry's "variable:subject_reference_type" is the dotted type
+        name by the time the member exists - never the literal reference."""
+        got = steps_by_name(self.expanded())
+        for key in self.KEYS:
+            for r in got[f"shot@{key}"]["pipeline"]["arguments"]["references"]:
+                assert r["reference_type"].startswith("diffusers.modular_pipelines")
+
+    def test_the_tag_runs_longer(self):
+        got = steps_by_name(self.expanded())
+        frames = [
+            got[f"shot@{k}"]["pipeline"]["arguments"]["num_frames"] for k in self.KEYS
+        ]
+        assert frames == [124, 124, 124, 124, 141]
+
+    def test_every_shot_is_the_same_pipeline(self):
+        from dw.workflow import pipeline_cache_key
+
+        got = steps_by_name(self.expanded())
+        assert (
+            len({pipeline_cache_key(got[f"shot@{k}"]["pipeline"]) for k in self.KEYS})
+            == 1
+        )
+
+    def test_the_episode_gathers_the_shots_in_order(self):
+        got = steps_by_name(self.expanded())
+        assert got["episode"]["task"]["arguments"]["videos"] == [
+            f"previous_result:shot@{k}" for k in self.KEYS
+        ]
+
+    def test_each_shot_keeps_the_generation_settings(self):
+        got = steps_by_name(self.expanded())
+        for key in self.KEYS:
+            arguments = got[f"shot@{key}"]["pipeline"]["arguments"]
+            assert arguments["width"] == 960
+            assert arguments["height"] == 544
+            assert arguments["num_inference_steps"] == 9
+            assert arguments["output"] == ["videos", "audio", "sampling_rate"]
+            loras = got[f"shot@{key}"]["pipeline"]["loras"]
+            assert len(loras) == 1
+            assert loras[0]["model_name"] == "lightx2v/Minimax-h3-Turbo"
+
+
+class TestRunTimeRealizationOrder:
+    """Workflow.run resolves in a fixed order: realize_constants ->
+    set_variables -> resolve_variable_values -> realize_args(variables,
+    base_dir) -> replace_variables -> expand_for_each. This test reproduces
+    that order by calling resolve_variable_values and realize_args itself,
+    in the same sequence, and pins what that order yields: realize_args
+    walks into the 'shots' variable and loads every 'reference_type' there,
+    so resolve_variable_values must already have turned
+    'variable:subject_reference_type' into a dotted name before realize_args
+    runs."""
+
+    KEYS = {
+        "cold_open": 2,
+        "deflect": 1,
+        "react": 1,
+        "button": 1,
+        "tag": 2,
+    }
+
+    def test_the_run_s_own_resolution_order_produces_loaded_types(self):
+        from dw.arguments import realize_args, realize_constants
+        from dw.for_each import expand_for_each
+        from dw.variables import replace_variables, resolve_variable_values
+
+        definition = load_template("dialogue-short.json")
+        variables = definition["variables"]
+        realize_constants(variables)
+        variables = resolve_variable_values(variables)
+        realize_args(variables, TEMPLATES)
+        expanded = expand_for_each(replace_variables(definition, variables))
+
+        got = steps_by_name(expanded)
+        for key, count in self.KEYS.items():
+            references = got[f"shot@{key}"]["pipeline"]["arguments"]["references"]
+            assert len(references) == count, key
+            for reference in references:
+                assert isinstance(reference, dict)
+                assert isinstance(reference["reference_type"], type)
+                assert "from_previous_result" in reference
+                assert "from_file" not in reference
+
+
+class TestListFields:
+    """What an entry has to carry is read off the item: references the
+    for_each steps make - the catalog and the unknown-key warning both
+    derive from this."""
+
+    def test_fields_are_the_item_references_with_name_first(self):
+        fields = list_fields(
+            definition(
+                {
+                    "name": "slice",
+                    "for_each": "variable:shots",
+                    "task": {"arguments": {"start_frame": "item:start_frame"}},
+                },
+                {
+                    "name": "shot",
+                    "for_each": "variable:shots",
+                    "pipeline": {
+                        "arguments": {
+                            "prompt": "item:prompt",
+                            "references": [{"x": "item:references"}],
+                        }
+                    },
+                },
+            )
+        )
+        assert fields == {
+            "shots": {
+                "fields": ["name", "prompt", "references", "start_frame"],
+                "steps": ["slice", "shot"],
+            }
+        }
+
+    def test_a_bare_item_means_the_entry_is_a_value(self):
+        fields = list_fields(
+            definition(
+                {
+                    "name": "say",
+                    "for_each": "variable:lines",
+                    "task": {"arguments": {"text": "item:"}},
+                }
+            )
+        )
+        assert fields == {"lines": {"fields": None, "steps": ["say"]}}
+
+    def test_a_literal_list_is_not_an_argument(self):
+        assert (
+            list_fields(definition({"name": "s", "for_each": ["a"], "task": {}})) == {}
+        )
+
+    def test_a_step_reading_no_field_still_lists_name(self):
+        fields = list_fields(
+            definition(
+                {"name": "s", "for_each": "variable:xs", "task": {"arguments": {}}}
+            )
+        )
+        assert fields == {"xs": {"fields": ["name"], "steps": ["s"]}}
+
+    def test_malformed_definitions_yield_nothing(self):
+        assert list_fields({}) == {}
+        assert list_fields({"steps": "nope"}) == {}
+        assert list_fields({"steps": ["not a dict"]}) == {}
+
+
+class TestEntryFieldWarnings:
+    def workflow(self):
+        return definition(
+            {
+                "name": "shot",
+                "for_each": "variable:shots",
+                "task": {"arguments": {"text": "item:prompt", "n": "item:num_frames"}},
+            },
+            variables={"shots": [{"name": "a", "prompt": "p", "num_frames": 1}]},
+        )
+
+    def test_a_key_no_step_reads_is_reported_at_the_entry(self):
+        w = self.workflow()
+        w["variables"]["shots"].append({"name": "b", "prompt": "q", "num_frame": 2})
+        assert entry_field_warnings(w) == [
+            "variables.shots[1]: entry 'b' carries 'num_frame', which no step reads; "
+            "entries of 'shots' take: name, num_frames, prompt"
+        ]
+
+    def test_a_caller_s_list_is_reported_under_arguments(self):
+        warnings = entry_field_warnings(
+            self.workflow(),
+            arguments={
+                "shots": [{"name": "a", "prompt": "p", "num_frames": 1, "note": "x"}]
+            },
+        )
+        assert warnings == [
+            "arguments.shots[0]: entry 'a' carries 'note', which no step reads; "
+            "entries of 'shots' take: name, num_frames, prompt"
+        ]
+
+    def test_bad_arguments_fall_back_to_the_defaults(self):
+        assert entry_field_warnings(self.workflow(), arguments={"nope": 1}) == []
+
+    def test_value_entries_and_clean_entries_warn_about_nothing(self):
+        assert entry_field_warnings(self.workflow()) == []
+        w = definition(
+            {
+                "name": "say",
+                "for_each": "variable:lines",
+                "task": {"arguments": {"t": "item:"}},
+            },
+            variables={"lines": ["a", "b"]},
+        )
+        assert entry_field_warnings(w) == []
+
+    def test_an_entry_without_a_name_is_named_by_its_index(self):
+        w = self.workflow()
+        w["variables"]["shots"] = [{"prompt": "p", "num_frames": 1, "extra": 0}]
+        assert entry_field_warnings(w)[0].startswith(
+            "variables.shots[0]: entry 0 carries 'extra'"
+        )
diff --git a/tests/test_integration.py b/tests/test_integration.py
index 04e3d8b4..0d22f501 100644
--- a/tests/test_integration.py
+++ b/tests/test_integration.py
@@ -165,7 +165,11 @@ def test_missing_variable_reference(self, temp_workflow_dir):
         }
 
         workflow = Workflow(workflow_data, temp_workflow_dir, "")
-        workflow.validate()
+        # Fatal at run time, so validation reports it rather than letting the
+        # run reach the step that spells it
+        with pytest.raises(Exception) as validation_error:
+            workflow.validate()
+        assert "undefined_var" in str(validation_error.value)
 
         with pytest.raises(Exception) as exc_info:
             workflow.run({})
diff --git a/tests/test_job_progress.py b/tests/test_job_progress.py
new file mode 100644
index 00000000..b3f8b664
--- /dev/null
+++ b/tests/test_job_progress.py
@@ -0,0 +1,172 @@
+"""What a poll learns about a job that is still running.
+
+A single-step generation - every `shot`-shape template, the most expensive
+thing the server does - emits `generating` and then nothing until it is
+finished. Polls come back byte-identical for minutes, so "no new events" is
+the normal state of a healthy run and cannot be read as trouble. The
+progress block is what a caller reads instead: the step, the phase, how long
+it has been in it, and the denoise counter once that loop is running.
+"""
+
+import time
+
+from dw.server.jobs import Job, RUNNING, QUEUED, SUCCEEDED
+from dw_mcp.diagnose import slim_job
+
+
+def running_job(*events):
+    job = Job({"workflow_name": "shot"})
+    job.status = RUNNING
+    job.started_at = time.time()
+    for event in events:
+        job.add_event(event)
+    return job
+
+
+def test_a_job_that_has_not_started_reports_no_progress():
+    job = Job({"workflow_name": "shot"})
+    job.status = QUEUED
+
+    assert job.progress() is None
+    assert job.detail()["progress"] is None
+
+
+def test_a_finished_job_reports_no_progress():
+    """Its manifest is a better answer than a phase it has left."""
+    job = running_job({"event": "phase", "phase": "generating"})
+    job.finish(SUCCEEDED)
+
+    assert job.progress() is None
+
+
+def test_the_step_and_phase_are_reported():
+    job = running_job(
+        {"event": "step_start", "step": "shot_a", "index": 0, "total_steps": 2},
+        {"event": "phase", "phase": "loading", "detail": "MiniMaxAI/MiniMax-H3"},
+    )
+
+    progress = job.progress()
+    assert progress["step"] == "shot_a"
+    assert progress["step_index"] == 0 and progress["total_steps"] == 2
+    assert progress["phase"] == "loading"
+    assert progress["phase_detail"] == "MiniMaxAI/MiniMax-H3"
+    assert progress["seconds_in_phase"] >= 0
+    assert progress["seconds_since_event"] >= 0
+
+
+def test_the_denoise_counter_is_null_until_the_loop_runs():
+    """Null, not absent: the lead-in to `generating` - encoding the prompt
+    and any reference image or audio - is a minute or more of silence, and
+    an absent key there cannot be told from a loop that has stopped."""
+    job = running_job({"event": "phase", "phase": "generating", "detail": "h3"})
+
+    lead_in = job.progress()
+    assert lead_in["denoise_step"] is None
+    assert lead_in["denoise_total_steps"] is None
+
+    job.add_event({"event": "pipeline_step", "step": 3, "total_steps": 20})
+
+    progress = job.progress()
+    assert progress["denoise_step"] == 3
+    assert progress["denoise_total_steps"] == 20
+
+
+def test_a_new_step_drops_the_previous_step_counter():
+    """Otherwise the last step's '20 of 20' reads as this one's progress."""
+    job = running_job(
+        {"event": "step_start", "step": "a", "index": 0, "total_steps": 2},
+        {"event": "pipeline_step", "step": 20, "total_steps": 20},
+        {"event": "step_start", "step": "b", "index": 1, "total_steps": 2},
+    )
+
+    progress = job.progress()
+    assert progress["step"] == "b"
+    assert progress["denoise_step"] is None
+
+
+def test_the_phase_clock_restarts_with_the_phase_but_the_event_clock_does_not():
+    job = running_job({"event": "phase", "phase": "loading"})
+    job.phase_started_at -= 30
+    job.last_event_at -= 30
+
+    assert job.progress()["seconds_in_phase"] >= 30
+
+    job.add_event({"event": "phase", "phase": "generating"})
+
+    progress = job.progress()
+    assert progress["phase"] == "generating"
+    assert progress["seconds_in_phase"] < 1
+    assert progress["seconds_since_event"] < 1
+
+
+def test_progress_survives_the_trim_of_the_event_log():
+    """The log keeps its tail; the summary is kept as events arrive, so a
+    long render's phase is not something a caller has to page back for."""
+    job = running_job({"event": "phase", "phase": "generating", "detail": "h3"})
+    for seq in range(500):
+        job.add_event({"event": "log", "message": f"line {seq}"})
+
+    assert job.progress()["phase"] == "generating"
+
+
+def test_the_mcp_poll_carries_it():
+    job = running_job(
+        {"event": "step_start", "step": "shot_a", "index": 0, "total_steps": 1},
+        {"event": "phase", "phase": "generating", "detail": "h3"},
+        {"event": "pipeline_step", "step": 7, "total_steps": 20},
+    )
+
+    slim = slim_job(job.detail())
+
+    assert slim["progress"]["denoise_step"] == 7
+    assert slim["progress"]["phase"] == "generating"
+
+
+def test_the_generating_lead_in_is_distinguishable_from_a_stalled_loop():
+    """Two polls a minute apart inside H3's ~90 s of pre-loop encoding come
+    back identical apart from the clock - which is the signature a caller is
+    told means 'stuck'. The counter being present and null is what separates
+    the two: null, the loop has not started; a number that stops moving
+    while `seconds_since_event` climbs, it has stopped."""
+    lead_in = running_job({"event": "phase", "phase": "generating", "detail": "h3"})
+    lead_in.phase_started_at -= 90
+    lead_in.last_event_at -= 90
+
+    quiet = lead_in.progress()
+    assert quiet["seconds_since_event"] >= 90
+    assert quiet["denoise_step"] is None
+
+    stalled = running_job(
+        {"event": "phase", "phase": "generating", "detail": "h3"},
+        {"event": "pipeline_step", "step": 4, "total_steps": 20},
+    )
+    stalled.last_event_at -= 90
+
+    stuck = stalled.progress()
+    assert stuck["seconds_since_event"] >= 90
+    assert stuck["denoise_step"] == 4
+
+
+def test_every_event_is_stamped_with_seconds_since_the_job_started():
+    """The gap between `generating` and the first `pipeline_step` is a
+    pipeline's pre-loop encoding, and between `step_start` and `generating`
+    on a reused pipeline is what 'slow start' actually costs - neither is a
+    number without a clock on the events themselves."""
+    job = running_job()
+    job.started_at -= 100
+    job.add_event(
+        {"event": "step_start", "step": "shot_a", "index": 0, "total_steps": 1}
+    )
+    job.add_event({"event": "phase", "phase": "generating", "detail": "h3"})
+
+    step_start, generating = job.events_after(-1)
+    assert 100 <= step_start["at"] < 101
+    assert generating["at"] >= step_start["at"]
+    assert job.events_after(-1)[0]["seq"] == 0
+
+
+def test_a_queued_event_is_stamped_against_creation_until_the_job_starts():
+    job = Job({"workflow_name": "shot"})
+    job.add_event({"event": "job_status", "status": "queued"})
+
+    assert job.events_after(-1)[0]["at"] >= 0
diff --git a/tests/test_library_sources.py b/tests/test_library_sources.py
index 01f14b5c..b73f969b 100644
--- a/tests/test_library_sources.py
+++ b/tests/test_library_sources.py
@@ -230,7 +230,7 @@ def test_validated_arguments_reach_the_whole_asset_path(self, client, tmp_path):
         the caller works in reads as though it was never looked in."""
         api, workspace, checkout = client
         definition = valid_workflow("refs")
-        definition["variables"] = {"image": "asset:mine.png"}
+        definition["variables"]["image"] = "asset:mine.png"
 
         for name in ("asset:mine.png", "asset:iris.png"):
             answer = api.post(
diff --git a/tests/test_modular_progress.py b/tests/test_modular_progress.py
new file mode 100644
index 00000000..700ba18a
--- /dev/null
+++ b/tests/test_modular_progress.py
@@ -0,0 +1,173 @@
+"""Per-step progress from a pipeline that takes no step callback.
+
+A ModularPipeline - H3, LTX-2, Qwen-Image - has no `callback_on_step_end`
+parameter, so the route that reports every other pipeline's denoise steps
+never fired for one: a `generating` phase, then nothing at all for however
+many minutes the loop took. From outside, a slow run and a hung one were the
+same thing. What those pipelines do have is a tqdm bar inside the denoise
+block, and every advance of it is a step.
+"""
+
+import copy
+
+import pytest
+from PIL import Image
+from tqdm.auto import tqdm
+
+from dw.events import RunContext, WorkflowCancelled
+
+from .test_phase_events import _pipeline_workflow, _run
+
+
+class FakeOutput:
+    def __init__(self):
+        self.images = [Image.new("RGB", (2, 2))]
+
+
+class FakeDenoiseBlock:
+    """The block that owns the loop, the way a modular denoise block does:
+    it opens its own bar and advances it once per step."""
+
+    def __init__(self, steps=3, iterate=False):
+        self.steps = steps
+        self.iterate = iterate
+
+    def progress_bar(self, iterable=None, total=None):
+        if iterable is not None:
+            return tqdm(iterable, disable=True)
+        return tqdm(total=total, disable=True)
+
+    def run(self):
+        if self.iterate:
+            for _ in self.progress_bar(range(self.steps)):
+                pass
+            return
+        with self.progress_bar(total=self.steps) as bar:
+            for _ in range(self.steps):
+                bar.update()
+
+
+class FakeBlocks:
+    def __init__(self, denoise):
+        self.sub_blocks = {"denoise": denoise}
+
+
+class FakeModularPipeline:
+    """No `callback_on_step_end` in the signature, and a public `blocks`
+    that hands back a copy - both true of the real thing, and the second is
+    why the patch has to go through `_blocks`."""
+
+    def __init__(self, steps=3, iterate=False):
+        self.denoise = FakeDenoiseBlock(steps, iterate)
+        self._blocks = FakeBlocks(self.denoise)
+
+    @property
+    def blocks(self):
+        return copy.deepcopy(self._blocks)
+
+    def __call__(self, prompt=None, num_inference_steps=None, generator=None):
+        self.denoise.run()
+        return FakeOutput()
+
+
+class FakePipelineWithBoth:
+    """A classic pipeline: it has a bar *and* takes a callback. Only one of
+    the two may report, or every step is counted twice."""
+
+    def __init__(self):
+        self._num_timesteps = 3
+
+    def progress_bar(self, iterable=None, total=None):
+        return tqdm(total=total, disable=True)
+
+    def __call__(
+        self,
+        prompt=None,
+        num_inference_steps=None,
+        generator=None,
+        callback_on_step_end=None,
+    ):
+        with self.progress_bar(total=3) as bar:
+            for i in range(3):
+                callback_on_step_end(self, i, 0, {})
+                bar.update()
+        return FakeOutput()
+
+
+def _events(fake, on_event=None):
+    collected = []
+
+    def sink(event):
+        collected.append(event)
+        if on_event is not None:
+            on_event(context, event)
+
+    context = RunContext(on_event=sink)
+    _run(_pipeline_workflow(), context, fake=fake)
+    return collected
+
+
+def _steps(events):
+    return [
+        (event["step"], event["total_steps"])
+        for event in events
+        if event["event"] == "pipeline_step"
+    ]
+
+
+def test_every_advance_of_the_bar_is_reported():
+    assert _steps(_events(FakeModularPipeline())) == [(1, 3), (2, 3), (3, 3)]
+
+
+def test_an_iterated_bar_reports_too():
+    """The other shape a block writes the loop in."""
+    assert _steps(_events(FakeModularPipeline(iterate=True))) == [
+        (1, 3),
+        (2, 3),
+        (3, 3),
+    ]
+
+
+def test_decoding_follows_the_last_step():
+    events = _events(FakeModularPipeline())
+
+    names = [
+        event.get("phase") if event["event"] == "phase" else event["event"]
+        for event in events
+        if event["event"] in ("phase", "pipeline_step")
+    ]
+    assert names == [
+        "loading",
+        "generating",
+        "pipeline_step",
+        "pipeline_step",
+        "pipeline_step",
+        "decoding",
+    ]
+
+
+def test_a_cancel_lands_inside_the_loop_rather_than_after_it():
+    """The same checkpoint the callback route has: without it a cancel on a
+    modular pipeline waits out the whole generation."""
+
+    def cancel_on_first_step(context, event):
+        if event["event"] == "pipeline_step":
+            context.cancel()
+
+    with pytest.raises(WorkflowCancelled):
+        _events(FakeModularPipeline(steps=20), on_event=cancel_on_first_step)
+
+
+def test_a_pipeline_that_takes_a_callback_is_not_counted_twice():
+    assert _steps(_events(FakePipelineWithBoth())) == [(1, 3), (2, 3), (3, 3)]
+
+
+def test_the_pipeline_is_handed_back_unpatched():
+    """This process keeps a loaded pipeline between runs - a wrapper left on
+    it would report into the run that has finished."""
+    fake = FakeModularPipeline()
+
+    _events(fake)
+
+    assert "progress_bar" not in vars(fake.denoise)
+    assert isinstance(fake.denoise.progress_bar(total=1), tqdm)
diff --git a/tests/test_plugin_skills.py b/tests/test_plugin_skills.py
index 0c959928..e1df1b7a 100644
--- a/tests/test_plugin_skills.py
+++ b/tests/test_plugin_skills.py
@@ -240,6 +240,33 @@ def test_the_skill_starts_with_the_server(self):
         text = skill_text(H3_SKILL)
         assert text.index("get_server_info") < text.index("templates/minimax/")
 
+    def test_the_cuts_templates_are_described_as_list_driven(self):
+        """Both cut templates take one 'shots' list; the skill says what an
+        entry carries, so an agent writes entries rather than the shot_N_*
+        arguments T005 and this rewrite removed."""
+        import json
+
+        text = skill_text(H3_SKILL)
+        assert "`shots`" in text
+        assert "shot_1_" not in text and "shot_2_" not in text
+        for name, fields in (
+            ("dialogue-short", {"name", "prompt", "references", "num_frames"}),
+            ("music-video", {"name", "prompt", "start_frame"}),
+        ):
+            path = os.path.join(
+                REPO_ROOT, "workflows", "templates", "minimax", name + ".json"
+            )
+            with open(path, encoding="utf-8") as f:
+                spec = json.load(f)
+            entries = spec["variables"]["shots"]
+            assert all(set(entry) == fields for entry in entries), name
+            for field in fields:
+                assert f"`{field}`" in text, f"the skill does not name {field}"
+        # cost: the listing's per_entry block when present, the honest
+        # fallback when it is not
+        assert "`per_entry`" in text
+        assert "`lists`" in text
+
 
 LTX_SKILL = os.path.join(PLUGIN_DIR, "skills", "ltx-2.5", "SKILL.md")
 
diff --git a/tests/test_schema.py b/tests/test_schema.py
index 7a2df3e3..f4bff1f1 100644
--- a/tests/test_schema.py
+++ b/tests/test_schema.py
@@ -394,3 +394,40 @@ def test_a_capped_list_says_so(self):
         text = format_validation_errors(errors)
 
         assert text.startswith(f"Validation errors (first {MAX_VALIDATION_ERRORS}):\n")
+
+
+def test_for_each_is_a_list_or_a_variable_reference():
+    schema = load_schema("workflow")
+    base = {
+        "id": "t",
+        "steps": [
+            {
+                "name": "shot",
+                "task": {"command": "x", "arguments": {}},
+                "for_each": None,
+            }
+        ],
+    }
+    for good in (["a", "b"], [{"name": "a"}], "variable:shots"):
+        base["steps"][0]["for_each"] = good
+        assert validate_data_all(base, schema) == []
+    for bad in (4, "shots", {"a": 1}):
+        base["steps"][0]["for_each"] = bad
+        assert validate_data_all(base, schema) != []
+
+
+def test_an_empty_for_each_list_fails_schema_validation():
+    schema = load_schema("workflow")
+    base = {
+        "id": "t",
+        "steps": [
+            {
+                "name": "shot",
+                "task": {"command": "x", "arguments": {}},
+                "for_each": [],
+            }
+        ],
+    }
+    errors = validate_data_all(base, schema)
+    assert errors != []
+    assert any("for_each" in e["path"] for e in errors)
diff --git a/tests/test_server.py b/tests/test_server.py
index 055d41fe..0deee1b7 100644
--- a/tests/test_server.py
+++ b/tests/test_server.py
@@ -247,6 +247,7 @@ def test_failed_job_surfaces_the_error_and_traceback(server):
                     events.append(json.loads(line[len("data: ") :]))
         assert events[-1] == {
             "seq": events[-1]["seq"],
+            "at": events[-1]["at"],
             "event": "job_status",
             "status": "failed",
         }
@@ -1168,6 +1169,33 @@ def test_workflow_variables_answer_without_the_whole_definition(server, tmp_path
         assert client.get("/api/workflows/ghost/variables").status_code == 404
 
 
+def test_workflow_variables_preview_inside_list_entries(server, tmp_path):
+    """A list-driven workflow's default holds several shots, each with its
+    own kilobyte-long prompt - the preview has to reach inside the list,
+    not just the top-level variables."""
+    long = "x" * 500
+    workflow = {
+        "id": "Cut",
+        "variables": {
+            "shots": [{"name": "a", "prompt": long}],
+            "n": 1,
+        },
+        "steps": [],
+    }
+    (tmp_path / "workflows" / "cut.json").write_text(json.dumps(workflow))
+
+    with server(success_script) as client:
+        body = client.get("/api/workflows/cut/variables").json()
+
+        assert body["variables"]["shots"][0]["prompt"] == "x" * 200
+        assert body["variables"]["shots"][0]["name"] == "a"
+        assert body["truncated"] == ["shots[0].prompt"]
+
+        full = client.get("/api/workflows/cut/variables?full=true").json()
+        assert full["variables"]["shots"][0]["prompt"] == long
+        assert full["truncated"] == []
+
+
 def test_gallery_metadata_reports_a_level_envelope_on_request(server, tmp_path):
     """Per-second level is opt-in: the default answer stays small, and
     `envelope=true` says where in the track the level sits."""
@@ -1681,6 +1709,7 @@ def test_workflow_listing_carries_details(server):
             "shape": "image",
             "traits": [],
             "summary": "Renders a small test image.",
+            "lists": {},
             "cost": None,
             # where it came from, and whether a client should offer save and
             # delete for it or only save-a-copy
@@ -3009,6 +3038,40 @@ def test_workflow_details_name_their_variables(server):
         assert details["Knobby"]["variables"] == 2
 
 
+def test_workflow_details_describe_their_lists(server):
+    """A list-driven workflow's listing says what an entry carries, so an
+    agent can write the list without opening the definition."""
+    with server(success_script) as client:
+        workflow = {
+            "id": "cut",
+            "variables": {
+                "shots": [{"name": "a", "prompt": "p"}, {"name": "b", "prompt": "q"}]
+            },
+            "steps": [
+                {
+                    "name": "shot",
+                    "for_each": "variable:shots",
+                    "pipeline": {
+                        "configuration": {
+                            "component_type": "{Fake}",
+                            "no_generator": True,
+                        },
+                        "from_pretrained_arguments": {"model_name": "m"},
+                        "arguments": {"prompt": "item:prompt"},
+                    },
+                }
+            ],
+        }
+        client.put("/api/workflows/cut", json={"workflow": workflow})
+
+        details = client.get("/api/workflows").json()["details"]
+        assert details["cut"]["lists"] == {
+            "shots": {"fields": ["name", "prompt"], "steps": ["shot"], "entries": 2}
+        }
+        compact = client.get("/api/workflows", params={"view": "compact"}).json()
+        assert compact["details"]["cut"]["lists"]["shots"]["entries"] == 2
+
+
 def test_submit_accepts_a_cwd_relative_path_with_a_relative_workflow_dir(
     tmp_path, monkeypatch
 ):
diff --git a/tests/test_server_jobs.py b/tests/test_server_jobs.py
index e24a265c..ed8504bd 100644
--- a/tests/test_server_jobs.py
+++ b/tests/test_server_jobs.py
@@ -121,6 +121,102 @@ def test_a_database_without_the_columns_is_migrated(tmp_path):
     assert row["run_id"] is None and row["run_dir"] is None
 
 
+def _for_each_workflow(**overrides):
+    """Copied from tests/test_workflow.py's helper of the same name (Task 5) -
+    not imported across test modules, per that task's convention."""
+    definition = {
+        "id": "fe",
+        "variables": {
+            "shots": [{"name": "a", "text": "A"}, {"name": "b", "text": "B"}]
+        },
+        "steps": [
+            {
+                "name": "shot",
+                "for_each": "variable:shots",
+                "task": {
+                    "command": "compose_text",
+                    "arguments": {"parts": ["item:text"]},
+                },
+                "result": {"content_type": "text/plain"},
+            },
+            {
+                "name": "edit",
+                "task": {
+                    "command": "compose_text",
+                    "arguments": {"parts": "gather:shot"},
+                },
+                "result": {"content_type": "text/plain"},
+            },
+        ],
+    }
+    definition.update(overrides)
+    return definition
+
+
+def for_each_script(command):
+    """Runs the real Workflow.run() in-process - the actual for_each
+    expansion and compose_text execution, not a canned response - standing
+    in for the spawned worker process the way this file's other scripts do
+    (ScriptedWorkerManager replaces the process, not the workflow code)."""
+    from dw.workflow import workflow_from_definition
+
+    workflow = workflow_from_definition(
+        command["workflow"],
+        command["output_dir"],
+        command["base_dir"],
+        command.get("workflow_dir"),
+    )
+    # Mirrors dw/worker.py's _handle_execute: validated against the
+    # defaults first, then run() substitutes and expands the real arguments.
+    workflow.validate()
+    workflow.run(command["arguments"], {})
+    yield {
+        "type": "success",
+        "message": "ok",
+        "run_count": 1,
+        "manifest": workflow.manifest,
+    }
+
+
+def test_a_for_each_job_expands_and_runs_through_the_server_job_path(tmp_path):
+    manager = JobManager(
+        str(tmp_path / "outputs"),
+        worker_manager=ScriptedWorkerManager(for_each_script),
+        history_path=str(tmp_path / "jobs.sqlite"),
+        workflow_dir=str(tmp_path),
+    )
+    try:
+        job = manager.submit(
+            workflow=_for_each_workflow(),
+            base_dir=None,
+            arguments={
+                "shots": [
+                    {"name": "one", "text": "1"},
+                    {"name": "two", "text": "2"},
+                    {"name": "three", "text": "3"},
+                ]
+            },
+        )
+        deadline = time.time() + 5
+        while job.status not in TERMINAL_STATES and time.time() < deadline:
+            time.sleep(0.01)
+        assert job.status == "succeeded", job.error
+        assert [entry["step"] for entry in job.manifest] == [
+            "shot@one",
+            "shot@two",
+            "shot@three",
+            "edit",
+        ]
+
+        edit_files = job.manifest[-1]["files"]
+        assert len(edit_files) == 1
+        edit_path = tmp_path / "outputs" / edit_files[0]
+        # compose_text's default separator is a blank line
+        assert edit_path.read_text() == "1\n\n2\n\n3"
+    finally:
+        manager.shutdown()
+
+
 def failing_script(command):
     """A run that writes a file, then dies on the next step - the shape of a
     dialogue-short whose last step names a renamed one (T015)."""
diff --git a/tests/test_step_cache.py b/tests/test_step_cache.py
index d226bce7..8cc875ce 100644
--- a/tests/test_step_cache.py
+++ b/tests/test_step_cache.py
@@ -1,5 +1,6 @@
 import pytest
 
+from dw.for_each import MAX_FOR_EACH_ENTRIES
 from dw.step_cache import StepCache, deep_equal, reference_resolves_to
 
 
@@ -217,6 +218,12 @@ def test_step_cache_has_a_default_entry_cap():
     )
 
 
+def test_the_default_cap_fits_a_maximal_for_each_run():
+    # A maximal for_each run over two groups plus fixed steps must fit, or a
+    # run evicts its own earlier members before it finishes.
+    assert StepCache.DEFAULT_MAX_ENTRIES >= 2 * MAX_FOR_EACH_ENTRIES + 8
+
+
 def test_step_cache_clear():
     cache = StepCache()
     step_data = {"name": "gen", "pipeline": {"arguments": {"prompt": "a cat"}}}
diff --git a/tests/test_validate_arguments.py b/tests/test_validate_arguments.py
index 5b4cefd6..fc14d448 100644
--- a/tests/test_validate_arguments.py
+++ b/tests/test_validate_arguments.py
@@ -162,6 +162,120 @@ def test_arguments_are_checked_on_an_inline_definition_too(self, server):
         assert result["valid"] is False
         assert result["errors"][0]["path"] == "arguments.nope"
 
+    def test_validate_expands_for_each_with_the_callers_list(self, server):
+        workflow = {
+            "id": "fe",
+            "variables": {"shots": [{"name": "a", "text": "A"}]},
+            "steps": [
+                {
+                    "name": "shot",
+                    "for_each": "variable:shots",
+                    "task": {
+                        "command": "compose_text",
+                        "arguments": {"parts": ["item:text"]},
+                    },
+                    "result": {"content_type": "text/plain"},
+                },
+                {
+                    "name": "edit",
+                    "task": {
+                        "command": "compose_text",
+                        "arguments": {"parts": "gather:shot"},
+                    },
+                    "result": {"content_type": "text/plain"},
+                },
+            ],
+        }
+        with server() as client:
+            ok = client.post("/api/validate", json={"workflow": workflow}).json()
+            assert ok["valid"] is True
+
+            bad = client.post(
+                "/api/validate",
+                json={
+                    "workflow": workflow,
+                    "arguments": {"shots": [{"name": "x"}, {"name": "x"}]},
+                },
+            ).json()
+
+        assert bad["valid"] is False
+        assert bad["errors"][0]["path"] == "steps[0].for_each[1].name"
+
+    def test_a_missing_reference_inside_a_list_argument_fails_validation(self, server):
+        """A `shots` list entry's `references[].from_file` is checked the
+        same as a top-level string argument - `_argument_reference_errors`
+        walks into list/dict argument values rather than skipping them."""
+        workflow = {
+            "id": "list-refs",
+            "variables": {"shots": [{"name": "a", "references": []}]},
+            "steps": [
+                {
+                    "name": "shot",
+                    "for_each": "variable:shots",
+                    "task": {
+                        "command": "compose_text",
+                        "arguments": {"parts": ["item:name"]},
+                    },
+                    "result": {"content_type": "text/plain"},
+                }
+            ],
+        }
+        with server() as client:
+            result = client.post(
+                "/api/validate",
+                json={
+                    "workflow": workflow,
+                    "arguments": {
+                        "shots": [
+                            {
+                                "name": "a",
+                                "references": [{"from_file": "asset:missing.wav"}],
+                            }
+                        ]
+                    },
+                },
+            ).json()
+
+        assert result["valid"] is False
+        assert (
+            result["errors"][0]["path"] == "arguments.shots[0].references[0].from_file"
+        )
+        assert "missing.wav" in result["errors"][0]["message"]
+
+    def test_a_reference_inside_a_list_argument_that_exists_passes(self, server):
+        workflow = {
+            "id": "list-refs",
+            "variables": {"shots": [{"name": "a", "references": []}]},
+            "steps": [
+                {
+                    "name": "shot",
+                    "for_each": "variable:shots",
+                    "task": {
+                        "command": "compose_text",
+                        "arguments": {"parts": ["item:name"]},
+                    },
+                    "result": {"content_type": "text/plain"},
+                }
+            ],
+        }
+        with server() as client:
+            result = client.post(
+                "/api/validate",
+                json={
+                    "workflow": workflow,
+                    "arguments": {
+                        "shots": [
+                            {
+                                "name": "a",
+                                "references": [{"from_file": "asset:iris.png"}],
+                            }
+                        ]
+                    },
+                },
+            ).json()
+
+        assert result["valid"] is True
+
 
 class TestSubmission:
     def test_a_bad_argument_is_refused_before_the_job_is_queued(self, server):
@@ -183,3 +297,91 @@ def test_good_arguments_still_queue(self, server):
             )
 
         assert response.status_code == 201
+
+    def test_a_bad_reference_is_refused_before_the_job_is_queued(self, server):
+        """The name half of the check was refused at submission and the
+        reference half was not, so a typo'd asset came back as a job id and
+        died on the first step - a success-shaped answer to a question
+        validate could answer for free."""
+        with server() as client:
+            response = client.post(
+                "/api/jobs",
+                json={
+                    "workflow_path": "Typed",
+                    "arguments": {"image": "asset:iirs.png"},
+                },
+            )
+
+            assert response.status_code == 400
+            detail = response.json()["detail"]
+            assert "arguments.image" in detail and "iirs.png" in detail
+            assert client.get("/api/jobs").json()["jobs"] == []
+
+    def test_a_reference_that_resolves_still_queues(self, server):
+        with server() as client:
+            response = client.post(
+                "/api/jobs",
+                json={
+                    "workflow_path": "Typed",
+                    "arguments": {"image": "asset:iris.png"},
+                },
+            )
+
+        assert response.status_code == 201
+
+    def test_an_inline_workflow_is_checked_the_same_way(self, server):
+        with server() as client:
+            response = client.post(
+                "/api/jobs",
+                json={
+                    "workflow": typed_workflow(),
+                    "arguments": {"image": "asset:nowhere.png"},
+                },
+            )
+
+        assert response.status_code == 400
+        assert "arguments.image" in response.json()["detail"]
+
+    def test_submission_and_validation_give_the_same_message(self, server):
+        """The ticket was a consistency gap, not a missing check: what the
+        free pre-flight says is what submission says."""
+        arguments = {"image": "asset:iirs.png"}
+        with server() as client:
+            validated = validate(client, arguments=arguments)
+            refused = client.post(
+                "/api/jobs", json={"workflow_path": "Typed", "arguments": arguments}
+            )
+
+        assert validated["errors"][0]["message"] in refused.json()["detail"]
+
+
+def test_an_entry_key_no_step_reads_is_a_warning_not_an_error(server):
+    workflow = {
+        "id": "cut",
+        "variables": {"shots": [{"name": "a", "text": "p"}]},
+        "steps": [
+            {
+                "name": "shot",
+                "for_each": "variable:shots",
+                "task": {
+                    "command": "compose_text",
+                    "arguments": {"parts": ["item:text"]},
+                },
+                "result": {"content_type": "text/plain"},
+            }
+        ],
+    }
+    with server() as client:
+        response = client.post(
+            "/api/validate",
+            json={
+                "workflow": workflow,
+                "arguments": {"shots": [{"name": "a", "text": "p", "txt": "q"}]},
+            },
+        )
+    body = response.json()
+    assert body["valid"] is True
+    assert any(
+        w.startswith("arguments.shots[0]: entry 'a' carries 'txt'")
+        for w in body["warnings"]
+    )
diff --git a/tests/test_variables.py b/tests/test_variables.py
index 4c84075b..be41677b 100644
--- a/tests/test_variables.py
+++ b/tests/test_variables.py
@@ -1,5 +1,13 @@
+import copy
 import pytest
-from dw.variables import replace_variables, set_variables, VariableNotFoundError
+from dw.variables import (
+    argument_errors,
+    replace_variables,
+    resolve_variable_values,
+    set_variables,
+    undeclared_variable_references,
+    VariableNotFoundError,
+)
 
 
 def test_replace_variables_in_dict():
@@ -182,3 +190,135 @@ def test_set_variables_string_override_of_a_null_default_passes_through():
     variables = {"mask": None}
     set_variables({"mask": "masks/a.png"}, variables)
     assert variables["mask"] == "masks/a.png"
+
+
+def test_set_variables_string_too_long_raises():
+    from dw.security import InvalidInputError, MAX_VARIABLE_VALUE_LENGTH
+
+    variables = {"prompt": "a cat"}
+    values = {"prompt": "a" * (MAX_VARIABLE_VALUE_LENGTH + 1)}
+
+    with pytest.raises(InvalidInputError, match="too long"):
+        set_variables(values, variables)
+
+
+def test_set_variables_list_entry_too_long_raises_the_same_error():
+    """A string nested inside a list-valued argument (a for_each entry's
+    prompt, say) is exactly as reachable as a top-level one, and must be
+    checked the same way - not skipped because `isinstance(v, str)` alone
+    would miss it."""
+    from dw.security import InvalidInputError, MAX_VARIABLE_VALUE_LENGTH
+
+    variables = {"shots": [{"name": "a", "prompt": "short"}]}
+    values = {"shots": [{"name": "a", "prompt": "a" * (MAX_VARIABLE_VALUE_LENGTH + 1)}]}
+
+    with pytest.raises(InvalidInputError, match="too long"):
+        set_variables(values, variables)
+
+
+def test_set_variables_list_with_ordinary_strings_passes_unchanged():
+    variables = {"shots": [{"name": "default"}]}
+    values = {"shots": [{"name": "a", "prompt": "a cat"}, {"name": "b"}]}
+
+    set_variables(values, variables)
+
+    assert variables["shots"] == [{"name": "a", "prompt": "a cat"}, {"name": "b"}]
+
+
+def test_argument_errors_reports_a_too_long_entry_under_the_list_argument():
+    """argument_errors wraps set_variables, so a string too deep inside a
+    list argument to check field-by-field is still reported at the
+    argument's own name, the same as any other bad `shots` value."""
+    from dw.security import MAX_VARIABLE_VALUE_LENGTH
+
+    definition = {"variables": {"shots": [{"name": "default"}]}}
+    arguments = {
+        "shots": [{"name": "a", "prompt": "a" * (MAX_VARIABLE_VALUE_LENGTH + 1)}]
+    }
+
+    errors = argument_errors(definition, arguments)
+
+    assert [error["path"] for error in errors] == ["arguments.shots"]
+    assert "too long" in errors[0]["message"]
+
+
+class TestResolveVariableValues:
+    """A list-valued variable's entries may name other variables - a shot
+    entry says "from_file": "variable:character_a_voice" and one variable
+    sets the voice in every shot it speaks in."""
+
+    def test_a_reference_inside_a_list_value_is_replaced(self):
+        variables = {
+            "voice": "cast/priya.wav",
+            "shots": [{"name": "a", "references": [{"from_file": "variable:voice"}]}],
+        }
+        resolved = resolve_variable_values(variables)
+        assert resolved["shots"][0]["references"][0]["from_file"] == "cast/priya.wav"
+
+    def test_a_reference_inside_a_dict_value_is_replaced(self):
+        variables = {"n": 124, "shape": {"num_frames": "variable:n"}}
+        assert resolve_variable_values(variables)["shape"] == {"num_frames": 124}
+
+    def test_a_null_variable_resolves_to_null(self):
+        variables = {
+            "voice": None,
+            "shots": [{"references": [{"from_file": "variable:voice"}]}],
+        }
+        resolved = resolve_variable_values(variables)
+        assert resolved["shots"][0]["references"][0]["from_file"] is None
+
+    def test_a_scalar_value_that_looks_like_a_reference_is_left_alone(self):
+        variables = {"x": "variable:y", "y": 1}
+        assert resolve_variable_values(variables)["x"] == "variable:y"
+
+    def test_a_chain_resolves_through_a_referenced_list(self):
+        variables = {
+            "voice": "a.wav",
+            "refs": [{"from_file": "variable:voice"}],
+            "shots": [{"references": "variable:refs"}],
+        }
+        resolved = resolve_variable_values(variables)
+        assert resolved["shots"][0]["references"] == [{"from_file": "a.wav"}]
+
+    def test_the_input_is_not_mutated(self):
+        variables = {"voice": "a.wav", "shots": [{"from_file": "variable:voice"}]}
+        before = copy.deepcopy(variables)
+        resolve_variable_values(variables)
+        assert variables == before
+
+    def test_an_undeclared_name_is_the_usual_error(self):
+        with pytest.raises(VariableNotFoundError, match="nope"):
+            resolve_variable_values({"shots": [{"x": "variable:nope"}]})
+
+    def test_a_cycle_is_an_error_that_names_the_loop(self):
+        variables = {"a": [{"x": "variable:b"}], "b": [{"y": "variable:a"}]}
+        with pytest.raises(ValueError, match="a -> b -> a"):
+            resolve_variable_values(variables)
+
+    def test_a_self_reference_is_a_cycle(self):
+        with pytest.raises(ValueError, match="a -> a"):
+            resolve_variable_values({"a": [{"x": "variable:a"}]})
+
+
+class TestUndeclaredReferencesInsideVariableValues:
+    def test_a_reference_inside_a_list_value_is_found_with_its_path(self):
+        definition = {
+            "variables": {
+                "shots": [{"references": [{}, {"from_file": "variable:nope"}]}]
+            },
+            "steps": [],
+        }
+        assert undeclared_variable_references(definition) == [
+            ("variables.shots[0].references[1].from_file", "nope")
+        ]
+
+    def test_a_declared_reference_inside_a_value_is_not_reported(self):
+        definition = {
+            "variables": {"voice": None, "shots": [{"from_file": "variable:voice"}]},
+            "steps": [],
+        }
+        assert undeclared_variable_references(definition) == []
+
+    def test_a_scalar_value_beginning_with_the_prefix_is_not_a_reference(self):
+        definition = {"variables": {"x": "variable:nope"}, "steps": []}
+        assert undeclared_variable_references(definition) == []
diff --git a/tests/test_workflow.py b/tests/test_workflow.py
index bc973e90..8f21ff18 100644
--- a/tests/test_workflow.py
+++ b/tests/test_workflow.py
@@ -14,6 +14,11 @@
 from dw.pipeline_processors.pipeline import Pipeline
 import os
 
+# Referenced by test_validation_realizes_a_constant_default_list via
+# "constant:tests.test_workflow.CONSTANT_SHOTS" - a module-level value a
+# workflow's variable default can point at instead of a literal list.
+CONSTANT_SHOTS = [{"name": "a", "text": "1"}, {"name": "b", "text": "2"}]
+
 
 def test_workflow_validation_valid(valid_workflow_json, tmp_path):
     workflow = Workflow(valid_workflow_json, str(tmp_path), "")
@@ -613,3 +618,248 @@ def test_validate_catches_a_reference_to_a_step_that_does_not_exist(tmp_path):
     assert "steps[1].task.arguments.videos[1]" in message
     assert "shot_2_pat_deflects" in message
     assert message.count("Validation error") == 1
+
+
+def _workflow_from(definition, tmp_path):
+    return Workflow(definition, str(tmp_path), "")
+
+
+def _for_each_workflow(**overrides):
+    definition = {
+        "id": "fe",
+        "variables": {
+            "shots": [{"name": "a", "text": "A"}, {"name": "b", "text": "B"}]
+        },
+        "steps": [
+            {
+                "name": "shot",
+                "for_each": "variable:shots",
+                "task": {
+                    "command": "compose_text",
+                    "arguments": {"parts": ["item:text"]},
+                },
+                "result": {"content_type": "text/plain"},
+            },
+            {
+                "name": "edit",
+                "task": {
+                    "command": "compose_text",
+                    "arguments": {"parts": "gather:shot"},
+                },
+                "result": {"content_type": "text/plain"},
+            },
+        ],
+    }
+    definition.update(overrides)
+    return definition
+
+
+def test_validation_expands_for_each_before_the_reference_check(tmp_path):
+    workflow = _workflow_from(_for_each_workflow(), tmp_path)  # the file's helper
+    assert workflow.validation_errors() == []
+
+
+def test_validation_reports_a_for_each_error_at_its_path(tmp_path):
+    definition = _for_each_workflow()
+    definition["steps"][1]["task"]["arguments"]["parts"] = "previous_result:shot"
+    workflow = _workflow_from(definition, tmp_path)
+    errors = workflow.validation_errors()
+    assert len(errors) == 1
+    assert errors[0]["path"] == "steps[1].task.arguments.parts"
+    assert "gather:shot" in errors[0]["message"]
+
+
+def test_validation_expands_the_callers_list_not_the_default(tmp_path):
+    workflow = _workflow_from(_for_each_workflow(), tmp_path)
+    # Two entries share a name only in the caller's list
+    errors = workflow.validation_errors(
+        arguments={"shots": [{"name": "a"}, {"name": "a"}]}
+    )
+    assert errors and "Duplicate entry name 'a'" in errors[0]["message"]
+
+
+def test_validation_falls_back_to_the_default_when_the_arguments_are_bad(tmp_path):
+    workflow = _workflow_from(_for_each_workflow(), tmp_path)
+    # An undeclared argument is argument_errors' finding, not validation's
+    assert workflow.validation_errors(arguments={"nope": 1}) == []
+
+
+def test_validation_of_an_undeclared_variable_still_does_not_raise(tmp_path):
+    definition = _for_each_workflow()
+    definition["steps"][0]["for_each"] = "variable:missing"
+    workflow = _workflow_from(definition, tmp_path)
+    errors = workflow.validation_errors()
+    assert errors and "variable:missing" in errors[0]["message"]
+    assert errors[0]["path"] == "steps[0].for_each"
+
+
+def test_an_unrelated_undeclared_variable_is_not_blamed_on_for_each(tmp_path):
+    """A typo in one step used to leave the whole definition unsubstituted,
+    so a perfectly good for_each list arrived as the literal
+    'variable:shots' and the error blamed the list the author got right."""
+    definition = _for_each_workflow()
+    definition["steps"][0]["task"]["arguments"]["parts"] = [
+        "item:text",
+        "variable:promt",
+    ]
+    errors = _workflow_from(definition, tmp_path).validation_errors()
+    assert len(errors) == 1
+    assert errors[0]["path"] == "steps[0].task.arguments.parts[1]"
+    assert "promt" in errors[0]["message"] and "shots" in errors[0]["message"]
+    assert "for_each" not in errors[0]["message"]
+
+
+def test_a_reference_error_after_a_group_names_the_step_in_the_file(tmp_path):
+    """The expansion moves the later steps along; the path the author reads
+    has to be the one in the file they wrote, not the expanded index."""
+    definition = _for_each_workflow()
+    definition["variables"]["shots"] = [
+        {"name": "a", "text": "A"},
+        {"name": "b", "text": "B"},
+        {"name": "c", "text": "C"},
+    ]
+    definition["steps"].insert(
+        0,
+        {
+            "name": "draw",
+            "task": {"command": "compose_text", "arguments": {"parts": ["x"]}},
+            "result": {"content_type": "text/plain"},
+        },
+    )
+    definition["steps"][2]["task"]["arguments"]["parts"] = ["previous_result:nope"]
+    errors = _workflow_from(definition, tmp_path).validation_errors()
+    assert len(errors) == 1
+    assert errors[0]["path"] == "steps[2].task.arguments.parts[0]"
+
+
+def test_a_reference_error_inside_a_member_names_the_member(tmp_path):
+    definition = _for_each_workflow()
+    definition["steps"][0]["task"]["arguments"]["parts"] = [
+        "item:text",
+        {"from_previous_result": "nope"},
+    ]
+    errors = _workflow_from(definition, tmp_path).validation_errors()
+    # One per member, each at the source step's path
+    assert [e["path"] for e in errors] == [
+        "steps[0].task.arguments.parts[1].from_previous_result",
+        "steps[0].task.arguments.parts[1].from_previous_result",
+    ]
+    assert "in member 'shot@a'" in errors[0]["message"]
+    assert "in member 'shot@b'" in errors[1]["message"]
+
+
+def test_validation_realizes_a_constant_default_list(tmp_path):
+    """A list defaulted to a constant: name used to fail validation with the
+    string unsubstituted and then run fine, since only the run realized
+    constants."""
+    definition = _for_each_workflow()
+    definition["variables"]["shots"] = "constant:tests.test_workflow.CONSTANT_SHOTS"
+    workflow = _workflow_from(definition, tmp_path)
+    assert workflow.validation_errors() == []
+    assert [s["name"] for s in workflow.expanded_definition()["steps"]][:2] == [
+        "shot@a",
+        "shot@b",
+    ]
+
+
+def test_validation_reports_an_unresolvable_constant_default(tmp_path):
+    """A trusted-ecosystem name that resolves to nothing used to escape
+    validation as an unhandled exception; now it is a validation error
+    naming the variable, with fetch_constant's own message."""
+    definition = _for_each_workflow()
+    definition["variables"]["shots"] = "constant:diffusers.NOPE_DOES_NOT_EXIST"
+    workflow = _workflow_from(definition, tmp_path)
+    errors = workflow.validation_errors()
+    assert len(errors) == 1
+    assert errors[0]["path"] == "variables.shots"
+    assert "diffusers.NOPE_DOES_NOT_EXIST" in errors[0]["message"]
+
+
+def test_validation_reports_a_malformed_constant_default(tmp_path):
+    definition = _for_each_workflow()
+    definition["variables"]["shots"] = "constant:not a name"
+    workflow = _workflow_from(definition, tmp_path)
+    errors = workflow.validation_errors()
+    assert len(errors) == 1
+    assert errors[0]["path"] == "variables.shots"
+
+
+def test_run_expands_for_each_and_names_the_members(tmp_path):
+    workflow = _workflow_from(_for_each_workflow(seed=1), tmp_path)
+    workflow.run({})
+    names = [entry["step"] for entry in workflow.manifest]
+    assert names == ["shot@a", "shot@b", "edit"]
+
+
+def test_run_substitutes_the_callers_list(tmp_path):
+    workflow = _workflow_from(_for_each_workflow(seed=1), tmp_path)
+    workflow.run({"shots": [{"name": "only", "text": "X"}]})
+    names = [entry["step"] for entry in workflow.manifest]
+    assert names == ["shot@only", "edit"]
+
+
+def test_an_entry_may_reference_another_variable(tmp_path):
+    """A shot entry's "from_file": "variable:voice" is the voice variable's
+    value by the time the member exists."""
+    definition = _for_each_workflow()
+    definition["variables"]["voice"] = "cast/priya.wav"
+    definition["variables"]["shots"] = [
+        {"name": "a", "text": "one", "voice": "variable:voice"}
+    ]
+    definition["steps"][0]["task"]["arguments"]["voice"] = "item:voice"
+    workflow = _workflow_from(definition, tmp_path)
+
+    expanded = workflow.expanded_definition()
+
+    assert expanded["steps"][0]["task"]["arguments"]["voice"] == "cast/priya.wav"
+
+
+def test_an_undeclared_reference_inside_a_default_entry_is_a_validation_error(
+    tmp_path,
+):
+    definition = _for_each_workflow()
+    definition["variables"]["shots"] = [{"name": "a", "text": "variable:nope"}]
+    workflow = _workflow_from(definition, tmp_path)
+
+    errors = workflow.validation_errors()
+
+    assert [e["path"] for e in errors] == ["variables.shots[0].text"]
+    assert "names no declared variable" in errors[0]["message"]
+
+
+def test_an_undeclared_reference_inside_a_caller_s_entry_is_reported_under_arguments(
+    tmp_path,
+):
+    workflow = _workflow_from(_for_each_workflow(), tmp_path)
+
+    errors = workflow.validation_errors(
+        arguments={"shots": [{"name": "a", "text": "variable:nope"}]}
+    )
+
+    assert [e["path"] for e in errors] == ["arguments.shots[0].text"]
+
+
+def test_a_caller_s_entry_may_reference_a_declared_variable(tmp_path):
+    definition = _for_each_workflow()
+    definition["variables"]["voice"] = None
+    workflow = _workflow_from(definition, tmp_path)
+
+    errors = workflow.validation_errors(
+        arguments={"shots": [{"name": "a", "text": "variable:voice"}]}
+    )
+
+    assert errors == []
+
+
+def test_a_variable_cycle_is_a_validation_error_at_variables(tmp_path):
+    definition = _for_each_workflow()
+    definition["variables"] = {
+        "a": [{"x": "variable:b"}],
+        "b": [{"y": "variable:a"}],
+    }
+    workflow = _workflow_from(definition, tmp_path)
+
+    errors = workflow.validation_errors()
+
+    assert [e["path"] for e in errors] == ["variables"]
+    assert "a -> b -> a" in errors[0]["message"]
diff --git a/tests/test_workflow_trust.py b/tests/test_workflow_trust.py
index b4531372..85eacee2 100644
--- a/tests/test_workflow_trust.py
+++ b/tests/test_workflow_trust.py
@@ -21,6 +21,28 @@
 )
 from dw.type_helpers import load_type_from_full_name
 from dw.pipeline_processors.pipeline import Pipeline
+from dw.workflow import Workflow
+
+
+def _untrusted_constant_workflow():
+    """A minimal workflow whose only variable defaults to a 'constant:'
+    reference outside the diffusers ecosystem - the same code-execution
+    surface as a dotted '*_type' value, gated by require_trusted_dotted_name
+    via dw.type_helpers.load_constant_from_name."""
+    return {
+        "id": "untrusted_constant",
+        "variables": {"sep": "constant:os.sep"},
+        "steps": [
+            {
+                "name": "step",
+                "task": {
+                    "command": "compose_text",
+                    "arguments": {"parts": ["variable:sep"]},
+                },
+                "result": {"content_type": "text/plain"},
+            }
+        ],
+    }
 
 
 def _untrust(monkeypatch):
@@ -179,6 +201,34 @@ def test_out_of_ecosystem_constant_allowed_when_trusted(self, monkeypatch):
         assert load_constant_from_name("os.sep") == "/"
 
 
+class TestValidationGatesUntrustedConstantDefaults:
+    """Workflow.validation_errors() realizes 'constant:' variable defaults
+    (Workflow.expanded_definition), which runs the same trust gate a run
+    would. An out-of-ecosystem name must come back as a validation error
+    naming the variable, not an unhandled UntrustedWorkflowError, and the
+    same definition must validate cleanly once trusted."""
+
+    def test_untrusted_constant_default_is_a_validation_error(
+        self, monkeypatch, tmp_path
+    ):
+        _untrust(monkeypatch)
+        workflow = Workflow(_untrusted_constant_workflow(), str(tmp_path), "")
+        try:
+            require_trusted_dotted_name("os.sep", "a constant: reference")
+        except UntrustedWorkflowError as e:
+            expected_message = str(e)
+        assert workflow.validation_errors() == [
+            {"path": "variables.sep", "message": expected_message}
+        ]
+
+    def test_untrusted_constant_default_validates_when_trusted(
+        self, monkeypatch, tmp_path
+    ):
+        monkeypatch.setenv("DW_TRUST_WORKFLOWS", "1")
+        workflow = Workflow(_untrusted_constant_workflow(), str(tmp_path), "")
+        assert workflow.validation_errors() == []
+
+
 class TestRemoteCodeIsGated:
     """diffusers/transformers' own remote-code paths - trust_remote_code and
     custom_pipeline in from_pretrained_arguments - download and execute
diff --git a/ui/src/lib/flow.test.ts b/ui/src/lib/flow.test.ts
index 3a801076..83fed24e 100644
--- a/ui/src/lib/flow.test.ts
+++ b/ui/src/lib/flow.test.ts
@@ -218,3 +218,64 @@ describe('dataFlowGraph', () => {
     expect(graph.fanIn.get('combine')?.label).toBe('combines 2 upstream steps')
   })
 })
+
+describe('for_each references', () => {
+  const cut = {
+    steps: [
+      step('draw', {}),
+      step('slice', { audio: 'previous_result:song' }),
+      {
+        name: 'shot',
+        for_each: 'variable:shots',
+        pipeline: {
+          configuration: { component_type: 'ModularPipeline' },
+          arguments: {
+            prompt: 'item:prompt',
+            references: [
+              { reference_type: 'T', from_previous_result: 'draw' },
+              { reference_type: 'T', from_previous_result: 'slice' },
+            ],
+          },
+        },
+      },
+      step('edit', { videos: 'gather:shot' }),
+    ],
+  }
+
+  it('from_previous_result inside a reference list is an edge labeled by the list', () => {
+    const graph = dataFlowGraph(cut)
+    expect(graph.edges).toContainEqual({
+      from: 'draw',
+      to: 'shot',
+      attribute: 'references',
+    })
+    expect(graph.edges).toContainEqual({
+      from: 'slice',
+      to: 'shot',
+      attribute: 'references',
+    })
+    expect(graph.nodes.find((n) => n.name === 'shot')?.isEntryPoint).toBe(false)
+  })
+
+  it('gather: is an edge from the for_each step to the step that gathers it', () => {
+    const graph = dataFlowGraph(cut)
+    expect(graph.edges).toContainEqual({
+      from: 'shot',
+      to: 'edit',
+      attribute: 'videos',
+    })
+    expect(graph.nodes.find((n) => n.name === 'edit')?.isEntryPoint).toBe(false)
+    expect(flowGraph(cut)[3].inputs).toEqual(['shot'])
+    expect(flowGraph(cut)[2].consumers).toEqual(['edit'])
+  })
+
+  it('a gather of a step that does not exist is dangling', () => {
+    const wf = { steps: [step('edit', { videos: 'gather:nope' })] }
+    expect(danglingReferenceDetails(wf)).toEqual([
+      {
+        stepIndex: 0,
+        message: "Step 'edit': gather:nope - no earlier step has that name",
+      },
+    ])
+  })
+})
diff --git a/ui/src/lib/flow.ts b/ui/src/lib/flow.ts
index cdb2d2ab..c4709771 100644
--- a/ui/src/lib/flow.ts
+++ b/ui/src/lib/flow.ts
@@ -24,10 +24,15 @@ function scanStrings(value: unknown, visit: (s: string) => void): void {
     Object.values(value).forEach((v) => scanStrings(v, visit))
 }
 
-/** previous_result: target step name, media suffix stripped. */
-function refTarget(s: string): string | null {
-  if (!s.startsWith('previous_result:')) return null
-  return s.slice('previous_result:'.length).split('.')[0]
+/** The earlier step a value refers to: `previous_result:<step>[.suffix]`,
+ * `gather:<step>` (every member of a for_each step), or the string under
+ * a `from_previous_result` key inside a reference object. */
+function refTarget(s: string, path: string[] = []): string | null {
+  if (s.startsWith('previous_result:'))
+    return s.slice('previous_result:'.length).split('.')[0]
+  if (s.startsWith('gather:')) return s.slice('gather:'.length)
+  if (path[path.length - 1] === 'from_previous_result') return s
+  return null
 }
 
 export function flowGraph(workflow: Record<string, any>): StepFlow[] {
@@ -45,8 +50,8 @@ export function flowGraph(workflow: Record<string, any>): StepFlow[] {
     steps.slice(0, index).forEach((s, i) => {
       if (s.name) earlier.set(s.name, i)
     })
-    scanStrings(step, (s) => {
-      const target = refTarget(s)
+    scanStringsWithPath(step, [], (s, path) => {
+      const target = refTarget(s, path)
       if (target === null || !earlier.has(target)) return
       graph[index].resolvedRefs += 1
       if (!graph[index].inputs.includes(target)) {
@@ -173,9 +178,12 @@ export function dataFlowGraph(workflow: Record<string, any>): DataFlowGraph {
     })
     const seen = new Set<string>() // producer|attribute - dedupe repeats
     scanStringsWithPath(step, [], (value, path) => {
-      const target = refTarget(value)
+      const target = refTarget(value, path)
       if (target === null || !earlier.has(target)) return
-      const attribute = attributeLabel(path)
+      const attribute =
+        path[path.length - 1] === 'from_previous_result'
+          ? attributeLabel(path.slice(0, -1))
+          : attributeLabel(path)
       const key = `${target}|${attribute}`
       if (seen.has(key)) return
       seen.add(key)
@@ -241,6 +249,14 @@ export function danglingReferenceDetails(
             message: `Step '${step.name}': previous_result:${name} - no earlier step has that name`,
           })
         }
+      } else if (value.startsWith('gather:')) {
+        const name = refTarget(value)!
+        if (!earlier.has(name)) {
+          problems.push({
+            stepIndex: index,
+            message: `Step '${step.name}': gather:${name} - no earlier step has that name`,
+          })
+        }
       } else if (value.startsWith('prompt:')) {
         // Without a listing the server resolves these at run time - only
         // a supplied library can say a name is missing
diff --git a/workflows/templates/inpaint.json b/workflows/templates/inpaint.json
index 7d0d18eb..abc62680 100644
--- a/workflows/templates/inpaint.json
+++ b/workflows/templates/inpaint.json
@@ -1,6 +1,6 @@
 {
     "variables": {
-        "mage": "https://huggingface.co/datasets/diffusers/diffusers-images-docs/resolve/main/cup.png",
+        "image": "https://huggingface.co/datasets/diffusers/diffusers-images-docs/resolve/main/cup.png",
         "mask_image": "https://huggingface.co/datasets/diffusers/diffusers-images-docs/resolve/main/cup_mask.png"
     },
     "id": "FluxFill",
diff --git a/workflows/templates/minimax/README.md b/workflows/templates/minimax/README.md
index 7ff7e899..c06e04be 100644
--- a/workflows/templates/minimax/README.md
+++ b/workflows/templates/minimax/README.md
@@ -132,5 +132,5 @@ same clip as an audio reference in each shot, as
 
 | Example | What it introduces |
 | ------- | ------------------ |
-| [dialogue-short.json](dialogue-short.json) | A five-shot sitcom scene: Z-Image draws the cast, `pipeline_reference` reruns one loaded model per shot, `concat_videos` splices the episode |
-| [music-video.json](music-video.json) | A music video cut to a generated song: `slice_audio` deals frame-exact pieces to lip-synced shots, and `pair_audio` lays the unbroken track over the finished edit |
+| [dialogue-short.json](dialogue-short.json) | A five-shot sitcom scene: Z-Image draws the cast, one `for_each` step over a `shots` list generates a shot per entry - its prompt, its references, its length - on one loaded model, and `concat_videos` gathers the episode |
+| [music-video.json](music-video.json) | A music video cut to a generated song, one `shots` list driving both `for_each` groups: `slice_audio` deals each entry its frame-exact piece, the shot lip-syncs to it, and `pair_audio` lays the unbroken track over the finished edit |
diff --git a/workflows/templates/minimax/dialogue-short.json b/workflows/templates/minimax/dialogue-short.json
index fafcc0e5..c0fbe45f 100644
--- a/workflows/templates/minimax/dialogue-short.json
+++ b/workflows/templates/minimax/dialogue-short.json
@@ -1,6 +1,6 @@
 {
     "id": "MiniMaxH3SitcomShort",
-    "description": "A digital short built the way television is built: from cuts, not from one long take. Chained generation degrades with length - every segment conditions on the previous segment's output, so artifacts compound and identity drifts. A scene cut resets that completely: each shot here is generated fresh from the same two character portraits, so shot five is exactly as clean as shot one and the scene can run as long as the script does. Two Z-Image steps draw the cast (the second reuses the first's loaded pipeline - identical configurations share one model - and 'release_pipeline' frees it before the video model loads). The first shot loads MiniMax-H3 once; the remaining shots are 'pipeline_reference' steps that rerun it with a new prompt, references and length - the tag shot runs 141 frames where the others run 124, since length is per-run. Character consistency across cuts comes from referencing the same portraits in every shot; voice consistency comes from repeating each character's voice description verbatim in every prompt, and, when 'character_a_voice' / 'character_b_voice' name a clip ('asset:cast/priya.wav'), from an audio reference appended to every shot that character speaks in - a repeated description alone drifts. Both default to null, and a reference whose file is null is left out of the list, so a run that names no voice generates exactly what it generated before the variables existed. A shot where both speak gets both references; if that reads worse than one, name one voice and leave the other null. The variables are named for roles rather than for the cast of this example - 'character_a', 'shot_3_react' - because the beats are the reusable part and the sketch is not. The soundscape writes the laugh track. A final 'concat_videos' task is the editor, splicing the shots into one episode - hard cuts, no trims, no seams to hide, because nothing was carried between them. Only the picture cuts hard: 'audio_bleed_ms' rings each shot's laugh track on over the silent opening of the next, the way a live audience carries across a cut. It and 'seam_fade_ms' are variables, so a seam is re-tuned with an argument rather than a copy of the workflow; 1800 ms is where a five-shot cut measured best, since a generated shot opens on more silence than it looks.",
+    "description": "A digital short built the way television is built: from cuts, not from one long take. Chained generation degrades with length - every segment conditions on the previous segment's output, so artifacts compound and identity drifts. A scene cut resets that completely: each shot here is generated fresh from the same two character portraits, so shot five is exactly as clean as shot one and the scene can run as long as the script does. Two Z-Image steps draw the cast (the second reuses the first's loaded pipeline - identical configurations share one model - and 'release_pipeline' frees it before the video model loads). The shots are one 'for_each' step over the 'shots' list: one entry per shot, carrying its 'name', its 'prompt', its 'references' and its 'num_frames' - the tag entry runs 141 frames where the others run 124, since length is per-shot. The list is an argument, so a six-shot scene is one more entry, not another file, and the members are named for their entries ('shot@react'); the loaded MiniMax-H3 is reused across all of them. Character consistency across cuts comes from referencing the same portraits in every shot; voice consistency comes from repeating each character's voice description verbatim in every prompt, and, when 'character_a_voice' / 'character_b_voice' name a clip ('asset:cast/priya.wav'), from the audio reference each entry lists for whoever speaks in it - an entry's reference says 'variable:character_a_voice', so one variable sets the voice in every shot that character has. Both default to null, and a reference whose file is null is left out of the list, so a run that names no voice generates exactly what it generated before the variables existed. A shot where both speak lists both; if that reads worse than one, name one voice and leave the other null. The variables are named for roles rather than for the cast of this example - 'character_a', the 'react' entry - because the beats are the reusable part and the sketch is not. The soundscape writes the laugh track. A final 'concat_videos' task is the editor, gathering the shots in list order into one episode - hard cuts, no trims, no seams to hide, because nothing was carried between them. Only the picture cuts hard: 'audio_bleed_ms' rings each shot's laugh track on over the silent opening of the next, the way a live audience carries across a cut. It and 'seam_fade_ms' are variables, so a seam is re-tuned with an argument rather than a copy of the workflow; 1800 ms is where a five-shot cut measured best, since a generated shot opens on more silence than it looks.",
     "summary": "A multi-shot dialogue short: Z-Image draws the cast, each shot is generated fresh from the same portraits, then cut.",
     "cost": [
         {
@@ -13,17 +13,103 @@
     "variables": {
         "character_a_portrait_prompt": "a 3/4-length studio portrait of a wiry man in his early 30s with short curly dark hair and expressive eyebrows, wearing a mustard-yellow sweater vest over a white button-down shirt, standing in a 1990s multi-camera sitcom apartment set with a sagging olive-green couch and a brick wall behind him, warm even studio lighting, sharp focus, photographic",
         "character_b_portrait_prompt": "a 3/4-length studio portrait of a heavyset man in his mid 40s with a shaved head and a calm, heavy-lidded expression, wearing an open gray flannel shirt over a dark t-shirt, standing in a 1990s multi-camera sitcom apartment set with a sagging olive-green couch and a brick wall behind him, warm even studio lighting, sharp focus, photographic",
-        "shot_1_cold_open": "subject_definitions:\n<Subject 1> is the wiry man in <Picture 1>, early 30s, short curly dark hair, mustard-yellow sweater vest over a white button-down shirt.\n<Subject 2> is the heavyset man in <Picture 2>, mid 40s, shaved head, open gray flannel shirt over a dark t-shirt.\n\nsummary:\n[reference generation] The target video is one shot of a 1990s multi-camera sitcom: <Subject 2> reads on the couch while <Subject 1> enters holding an empty ice cream carton and confronts him, in front of a live studio audience.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the face, hair, sweater vest and proportions of <Picture 1> are kept exactly, with the body newly animated to walk and speak.\n<Subject 2> (appears in [Shot 1]): fully_preserved - the face, head, flannel shirt and proportions of <Picture 2> are kept exactly, with the body newly posed seated and reading.\n\ndetailed_description:\nThe target video is in the style of a 1990s multi-camera sitcom, shot on studio video with warm, even, shadowless lighting. [Shot 1] A wide shot frames a living room set: a sagging olive-green couch centre frame in front of a brick wall with a window onto a painted city backdrop. <Subject 2> sits at the right end of the couch, ankles crossed, reading a magazine and not looking up. <Subject 1> strides in from frame left holding an empty pint-sized ice cream carton at chest height, stops beside the couch, holds the carton out toward <Subject 2> and turns it upside down to show it is empty. <Subject 1> (S1), a fast, nasal, high-pitched male tenor voice, tight with disbelief, says <d>[English] Okay. Who finished the pistachio?</d> <Subject 2> keeps reading and does not react. A live studio audience laughs warmly as the carton turns over. The camera holds a static wide shot throughout, level with the set, the way a sitcom master camera holds a scene.\n\noverall_soundscape:\nA bright, close television-studio room tone. Quick footsteps on a hollow stage floor as <Subject 1> enters, the papery rattle of the empty carton as it turns over, a soft page turn from the couch, and a warm burst of live studio-audience laughter that begins as the carton flips and settles under the end of the shot.\n\nnon_diegetic_music:\nN/A",
-        "shot_2_deflect": "subject_definitions:\n<Subject 1> is the heavyset man in <Picture 1>, mid 40s, shaved head, calm and heavy-lidded, open gray flannel shirt over a dark t-shirt.\n\nsummary:\n[reference generation] The target video is one close-up shot of a 1990s multi-camera sitcom: <Subject 1> answers an accusation without looking up from his magazine, in front of a live studio audience.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the face, head, flannel shirt and proportions of <Picture 1> are kept exactly, with the head and jaw newly animated to speak.\n\ndetailed_description:\nThe target video is in the style of a 1990s multi-camera sitcom, shot on studio video with warm, even, shadowless lighting. [Shot 1] A medium close-up frames <Subject 1> from the chest up, seated at the end of an olive-green couch in front of a brick wall, holding an open magazine just below the frame line and reading it. He does not look up. <Subject 1> (S1), a flat, low, unhurried male baritone voice, completely unbothered, says <d>[English] Technically? The freezer has a defrost cycle.</d> On the last word he turns a page. A live studio audience laughs as the line lands. The camera holds a static close-up throughout, the way a sitcom cross-shot camera holds a speaker.\n\noverall_soundscape:\nA bright, close television-studio room tone. A soft page turn, the faint creak of couch springs as <Subject 1> settles, and a rolling wave of live studio-audience laughter that starts on the last word of the line and carries under the end of the shot.\n\nnon_diegetic_music:\nN/A",
-        "shot_3_react": "subject_definitions:\n<Subject 1> is the wiry man in <Picture 1>, early 30s, short curly dark hair, expressive eyebrows, mustard-yellow sweater vest over a white button-down shirt.\n\nsummary:\n[reference generation] The target video is one close-up shot of a 1990s multi-camera sitcom: <Subject 1> repeats an absurd excuse back in disbelief, holding up an empty ice cream carton, in front of a live studio audience.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the face, hair, sweater vest and proportions of <Picture 1> are kept exactly, with the head, jaw and arm newly animated to speak and gesture.\n\ndetailed_description:\nThe target video is in the style of a 1990s multi-camera sitcom, shot on studio video with warm, even, shadowless lighting. [Shot 1] A medium close-up frames <Subject 1> from the chest up, standing beside a couch in front of a brick wall, an empty pint-sized ice cream carton raised in one hand at head height. His eyebrows are high and his mouth is half open before he speaks. <Subject 1> (S1), a fast, nasal, high-pitched male tenor voice, tight with disbelief, cracking upward on the last word, says <d>[English] The defrost cycle used a spoon?</d> He shakes the empty carton once on the word spoon. A live studio audience erupts in a big laugh as the line lands. The camera holds a static close-up throughout, the way a sitcom cross-shot camera holds a speaker.\n\noverall_soundscape:\nA bright, close television-studio room tone. The hollow papery rattle of the empty carton as it shakes, and a big rising wave of live studio-audience laughter that breaks on the word spoon and rolls under the end of the shot.\n\nnon_diegetic_music:\nN/A",
-        "shot_4_button": "subject_definitions:\n<Subject 1> is the heavyset man in <Picture 1>, mid 40s, shaved head, calm and heavy-lidded, open gray flannel shirt over a dark t-shirt.\n\nsummary:\n[reference generation] The target video is one close-up shot of a 1990s multi-camera sitcom: <Subject 1> shrugs off the accusation with a deadpan line, in front of a live studio audience.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the face, head, flannel shirt and proportions of <Picture 1> are kept exactly, with the head, jaw and shoulders newly animated to speak and shrug.\n\ndetailed_description:\nThe target video is in the style of a 1990s multi-camera sitcom, shot on studio video with warm, even, shadowless lighting. [Shot 1] A medium close-up frames <Subject 1> from the chest up, seated at the end of an olive-green couch in front of a brick wall, the magazine now closed in his lap. He looks up for the first time, holds a beat of eye contact just past the lens, and gives one slow shrug. <Subject 1> (S1), a flat, low, unhurried male baritone voice, perfectly deadpan, says <d>[English] I don't know its life.</d> He goes back to the magazine. A live studio audience gives a big laugh with scattered applause as he looks back down. The camera holds a static close-up throughout, the way a sitcom cross-shot camera holds a speaker.\n\noverall_soundscape:\nA bright, close television-studio room tone. The soft slap of the magazine reopening, a couch-spring creak under the shrug, and a big wave of live studio-audience laughter with a few claps in it that breaks after the line and rolls under the end of the shot.\n\nnon_diegetic_music:\nN/A",
-        "shot_5_tag": "subject_definitions:\n<Subject 1> is the wiry man in <Picture 1>, early 30s, short curly dark hair, mustard-yellow sweater vest over a white button-down shirt.\n<Subject 2> is the heavyset man in <Picture 2>, mid 40s, shaved head, open gray flannel shirt over a dark t-shirt.\n\nsummary:\n[reference generation] The target video is one shot of a 1990s multi-camera sitcom: <Subject 1> gives up and sits down next to <Subject 2>, the two trade a final exchange, and the scene ends on applause.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the face, hair, sweater vest and proportions of <Picture 1> are kept exactly, with the body newly animated to sit and speak.\n<Subject 2> (appears in [Shot 1]): fully_preserved - the face, head, flannel shirt and proportions of <Picture 2> are kept exactly, with the head newly animated to reply.\n\ndetailed_description:\nThe target video is in the style of a 1990s multi-camera sitcom, shot on studio video with warm, even, shadowless lighting. [Shot 1] A wide shot frames the living room set: the sagging olive-green couch centre frame in front of a brick wall with a window onto a painted city backdrop. <Subject 2> sits at the right end of the couch reading his magazine. <Subject 1> exhales, drops the empty carton onto the coffee table, and sits down heavily at the left end of the couch, staring straight ahead. A beat of silence. <Subject 1> (S1), a fast, nasal, high-pitched male tenor voice, now flat with defeat, says <d>[English] We're getting a padlock.</d> Without looking up, <Subject 2> (S2), a flat, low, unhurried male baritone voice, says <d>[English] Sure.</d> The studio audience laughs and applauds as the shot holds on the two of them side by side, neither moving. The camera holds a static wide shot throughout.\n\noverall_soundscape:\nA bright, close television-studio room tone. The hollow knock of the carton landing on the coffee table, a heavy couch-spring compression as <Subject 1> sits, a page turn, then a full wave of live studio-audience laughter that turns into warm applause and carries to the end of the shot.\n\nnon_diegetic_music:\nA short, bright sitcom scene-change sting - a bass guitar walk-down with a light drum hit - enters under the applause in the final second of the shot.",
+        "shots": [
+            {
+                "name": "cold_open",
+                "num_frames": 124,
+                "references": [
+                    {
+                        "reference_type": "variable:subject_reference_type",
+                        "from_previous_result": "draw_character_a"
+                    },
+                    {
+                        "reference_type": "variable:subject_reference_type",
+                        "from_previous_result": "draw_character_b"
+                    },
+                    {
+                        "reference_type": "variable:voice_reference_type",
+                        "from_file": "variable:character_a_voice"
+                    },
+                    {
+                        "reference_type": "variable:voice_reference_type",
+                        "from_file": "variable:character_b_voice"
+                    }
+                ],
+                "prompt": "subject_definitions:\n<Subject 1> is the wiry man in <Picture 1>, early 30s, short curly dark hair, mustard-yellow sweater vest over a white button-down shirt.\n<Subject 2> is the heavyset man in <Picture 2>, mid 40s, shaved head, open gray flannel shirt over a dark t-shirt.\n\nsummary:\n[reference generation] The target video is one shot of a 1990s multi-camera sitcom: <Subject 2> reads on the couch while <Subject 1> enters holding an empty ice cream carton and confronts him, in front of a live studio audience.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the face, hair, sweater vest and proportions of <Picture 1> are kept exactly, with the body newly animated to walk and speak.\n<Subject 2> (appears in [Shot 1]): fully_preserved - the face, head, flannel shirt and proportions of <Picture 2> are kept exactly, with the body newly posed seated and reading.\n\ndetailed_description:\nThe target video is in the style of a 1990s multi-camera sitcom, shot on studio video with warm, even, shadowless lighting. [Shot 1] A wide shot frames a living room set: a sagging olive-green couch centre frame in front of a brick wall with a window onto a painted city backdrop. <Subject 2> sits at the right end of the couch, ankles crossed, reading a magazine and not looking up. <Subject 1> strides in from frame left holding an empty pint-sized ice cream carton at chest height, stops beside the couch, holds the carton out toward <Subject 2> and turns it upside down to show it is empty. <Subject 1> (S1), a fast, nasal, high-pitched male tenor voice, tight with disbelief, says <d>[English] Okay. Who finished the pistachio?</d> <Subject 2> keeps reading and does not react. A live studio audience laughs warmly as the carton turns over. The camera holds a static wide shot throughout, level with the set, the way a sitcom master camera holds a scene.\n\noverall_soundscape:\nA bright, close television-studio room tone. Quick footsteps on a hollow stage floor as <Subject 1> enters, the papery rattle of the empty carton as it turns over, a soft page turn from the couch, and a warm burst of live studio-audience laughter that begins as the carton flips and settles under the end of the shot.\n\nnon_diegetic_music:\nN/A"
+            },
+            {
+                "name": "deflect",
+                "num_frames": 124,
+                "references": [
+                    {
+                        "reference_type": "variable:subject_reference_type",
+                        "from_previous_result": "draw_character_b"
+                    },
+                    {
+                        "reference_type": "variable:voice_reference_type",
+                        "from_file": "variable:character_b_voice"
+                    }
+                ],
+                "prompt": "subject_definitions:\n<Subject 1> is the heavyset man in <Picture 1>, mid 40s, shaved head, calm and heavy-lidded, open gray flannel shirt over a dark t-shirt.\n\nsummary:\n[reference generation] The target video is one close-up shot of a 1990s multi-camera sitcom: <Subject 1> answers an accusation without looking up from his magazine, in front of a live studio audience.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the face, head, flannel shirt and proportions of <Picture 1> are kept exactly, with the head and jaw newly animated to speak.\n\ndetailed_description:\nThe target video is in the style of a 1990s multi-camera sitcom, shot on studio video with warm, even, shadowless lighting. [Shot 1] A medium close-up frames <Subject 1> from the chest up, seated at the end of an olive-green couch in front of a brick wall, holding an open magazine just below the frame line and reading it. He does not look up. <Subject 1> (S1), a flat, low, unhurried male baritone voice, completely unbothered, says <d>[English] Technically? The freezer has a defrost cycle.</d> On the last word he turns a page. A live studio audience laughs as the line lands. The camera holds a static close-up throughout, the way a sitcom cross-shot camera holds a speaker.\n\noverall_soundscape:\nA bright, close television-studio room tone. A soft page turn, the faint creak of couch springs as <Subject 1> settles, and a rolling wave of live studio-audience laughter that starts on the last word of the line and carries under the end of the shot.\n\nnon_diegetic_music:\nN/A"
+            },
+            {
+                "name": "react",
+                "num_frames": 124,
+                "references": [
+                    {
+                        "reference_type": "variable:subject_reference_type",
+                        "from_previous_result": "draw_character_a"
+                    },
+                    {
+                        "reference_type": "variable:voice_reference_type",
+                        "from_file": "variable:character_a_voice"
+                    }
+                ],
+                "prompt": "subject_definitions:\n<Subject 1> is the wiry man in <Picture 1>, early 30s, short curly dark hair, expressive eyebrows, mustard-yellow sweater vest over a white button-down shirt.\n\nsummary:\n[reference generation] The target video is one close-up shot of a 1990s multi-camera sitcom: <Subject 1> repeats an absurd excuse back in disbelief, holding up an empty ice cream carton, in front of a live studio audience.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the face, hair, sweater vest and proportions of <Picture 1> are kept exactly, with the head, jaw and arm newly animated to speak and gesture.\n\ndetailed_description:\nThe target video is in the style of a 1990s multi-camera sitcom, shot on studio video with warm, even, shadowless lighting. [Shot 1] A medium close-up frames <Subject 1> from the chest up, standing beside a couch in front of a brick wall, an empty pint-sized ice cream carton raised in one hand at head height. His eyebrows are high and his mouth is half open before he speaks. <Subject 1> (S1), a fast, nasal, high-pitched male tenor voice, tight with disbelief, cracking upward on the last word, says <d>[English] The defrost cycle used a spoon?</d> He shakes the empty carton once on the word spoon. A live studio audience erupts in a big laugh as the line lands. The camera holds a static close-up throughout, the way a sitcom cross-shot camera holds a speaker.\n\noverall_soundscape:\nA bright, close television-studio room tone. The hollow papery rattle of the empty carton as it shakes, and a big rising wave of live studio-audience laughter that breaks on the word spoon and rolls under the end of the shot.\n\nnon_diegetic_music:\nN/A"
+            },
+            {
+                "name": "button",
+                "num_frames": 124,
+                "references": [
+                    {
+                        "reference_type": "variable:subject_reference_type",
+                        "from_previous_result": "draw_character_b"
+                    },
+                    {
+                        "reference_type": "variable:voice_reference_type",
+                        "from_file": "variable:character_b_voice"
+                    }
+                ],
+                "prompt": "subject_definitions:\n<Subject 1> is the heavyset man in <Picture 1>, mid 40s, shaved head, calm and heavy-lidded, open gray flannel shirt over a dark t-shirt.\n\nsummary:\n[reference generation] The target video is one close-up shot of a 1990s multi-camera sitcom: <Subject 1> shrugs off the accusation with a deadpan line, in front of a live studio audience.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the face, head, flannel shirt and proportions of <Picture 1> are kept exactly, with the head, jaw and shoulders newly animated to speak and shrug.\n\ndetailed_description:\nThe target video is in the style of a 1990s multi-camera sitcom, shot on studio video with warm, even, shadowless lighting. [Shot 1] A medium close-up frames <Subject 1> from the chest up, seated at the end of an olive-green couch in front of a brick wall, the magazine now closed in his lap. He looks up for the first time, holds a beat of eye contact just past the lens, and gives one slow shrug. <Subject 1> (S1), a flat, low, unhurried male baritone voice, perfectly deadpan, says <d>[English] I don't know its life.</d> He goes back to the magazine. A live studio audience gives a big laugh with scattered applause as he looks back down. The camera holds a static close-up throughout, the way a sitcom cross-shot camera holds a speaker.\n\noverall_soundscape:\nA bright, close television-studio room tone. The soft slap of the magazine reopening, a couch-spring creak under the shrug, and a big wave of live studio-audience laughter with a few claps in it that breaks after the line and rolls under the end of the shot.\n\nnon_diegetic_music:\nN/A"
+            },
+            {
+                "name": "tag",
+                "num_frames": 141,
+                "references": [
+                    {
+                        "reference_type": "variable:subject_reference_type",
+                        "from_previous_result": "draw_character_a"
+                    },
+                    {
+                        "reference_type": "variable:subject_reference_type",
+                        "from_previous_result": "draw_character_b"
+                    },
+                    {
+                        "reference_type": "variable:voice_reference_type",
+                        "from_file": "variable:character_a_voice"
+                    },
+                    {
+                        "reference_type": "variable:voice_reference_type",
+                        "from_file": "variable:character_b_voice"
+                    }
+                ],
+                "prompt": "subject_definitions:\n<Subject 1> is the wiry man in <Picture 1>, early 30s, short curly dark hair, mustard-yellow sweater vest over a white button-down shirt.\n<Subject 2> is the heavyset man in <Picture 2>, mid 40s, shaved head, open gray flannel shirt over a dark t-shirt.\n\nsummary:\n[reference generation] The target video is one shot of a 1990s multi-camera sitcom: <Subject 1> gives up and sits down next to <Subject 2>, the two trade a final exchange, and the scene ends on applause.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the face, hair, sweater vest and proportions of <Picture 1> are kept exactly, with the body newly animated to sit and speak.\n<Subject 2> (appears in [Shot 1]): fully_preserved - the face, head, flannel shirt and proportions of <Picture 2> are kept exactly, with the head newly animated to reply.\n\ndetailed_description:\nThe target video is in the style of a 1990s multi-camera sitcom, shot on studio video with warm, even, shadowless lighting. [Shot 1] A wide shot frames the living room set: the sagging olive-green couch centre frame in front of a brick wall with a window onto a painted city backdrop. <Subject 2> sits at the right end of the couch reading his magazine. <Subject 1> exhales, drops the empty carton onto the coffee table, and sits down heavily at the left end of the couch, staring straight ahead. A beat of silence. <Subject 1> (S1), a fast, nasal, high-pitched male tenor voice, now flat with defeat, says <d>[English] We're getting a padlock.</d> Without looking up, <Subject 2> (S2), a flat, low, unhurried male baritone voice, says <d>[English] Sure.</d> The studio audience laughs and applauds as the shot holds on the two of them side by side, neither moving. The camera holds a static wide shot throughout.\n\noverall_soundscape:\nA bright, close television-studio room tone. The hollow knock of the carton landing on the coffee table, a heavy couch-spring compression as <Subject 1> sits, a page turn, then a full wave of live studio-audience laughter that turns into warm applause and carries to the end of the shot.\n\nnon_diegetic_music:\nA short, bright sitcom scene-change sting - a bass guitar walk-down with a light drum hit - enters under the applause in the final second of the shot."
+            }
+        ],
         "character_a_voice": null,
         "character_b_voice": null,
         "voice_reference_type": "diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference",
         "subject_reference_type": "diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference",
-        "num_frames": 124,
-        "tag_num_frames": 141,
         "audio_bleed_ms": 1800,
         "seam_fade_ms": null,
         "width": 960,
@@ -89,7 +175,8 @@
             }
         },
         {
-            "name": "shot_1_cold_open",
+            "name": "shot",
+            "for_each": "variable:shots",
             "pipeline": {
                 "configuration": {
                     "component_type": "ModularPipeline",
@@ -198,162 +285,9 @@
                     }
                 ],
                 "arguments": {
-                    "prompt": "variable:shot_1_cold_open",
-                    "references": [
-                        {
-                            "reference_type": "variable:subject_reference_type",
-                            "from_previous_result": "draw_character_a"
-                        },
-                        {
-                            "reference_type": "variable:subject_reference_type",
-                            "from_previous_result": "draw_character_b"
-                        },
-                        {
-                            "reference_type": "variable:voice_reference_type",
-                            "from_file": "variable:character_a_voice"
-                        },
-                        {
-                            "reference_type": "variable:voice_reference_type",
-                            "from_file": "variable:character_b_voice"
-                        }
-                    ],
-                    "num_frames": "variable:num_frames",
-                    "width": "variable:width",
-                    "height": "variable:height",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "output": [
-                        "videos",
-                        "audio",
-                        "sampling_rate"
-                    ]
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        },
-        {
-            "name": "shot_2_deflect",
-            "pipeline_reference": {
-                "reference_name": "shot_1_cold_open",
-                "arguments": {
-                    "prompt": "variable:shot_2_deflect",
-                    "references": [
-                        {
-                            "reference_type": "variable:subject_reference_type",
-                            "from_previous_result": "draw_character_b"
-                        },
-                        {
-                            "reference_type": "variable:voice_reference_type",
-                            "from_file": "variable:character_b_voice"
-                        }
-                    ],
-                    "num_frames": "variable:num_frames",
-                    "width": "variable:width",
-                    "height": "variable:height",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "output": [
-                        "videos",
-                        "audio",
-                        "sampling_rate"
-                    ]
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        },
-        {
-            "name": "shot_3_react",
-            "pipeline_reference": {
-                "reference_name": "shot_1_cold_open",
-                "arguments": {
-                    "prompt": "variable:shot_3_react",
-                    "references": [
-                        {
-                            "reference_type": "variable:subject_reference_type",
-                            "from_previous_result": "draw_character_a"
-                        },
-                        {
-                            "reference_type": "variable:voice_reference_type",
-                            "from_file": "variable:character_a_voice"
-                        }
-                    ],
-                    "num_frames": "variable:num_frames",
-                    "width": "variable:width",
-                    "height": "variable:height",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "output": [
-                        "videos",
-                        "audio",
-                        "sampling_rate"
-                    ]
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        },
-        {
-            "name": "shot_4_button",
-            "pipeline_reference": {
-                "reference_name": "shot_1_cold_open",
-                "arguments": {
-                    "prompt": "variable:shot_4_button",
-                    "references": [
-                        {
-                            "reference_type": "variable:subject_reference_type",
-                            "from_previous_result": "draw_character_b"
-                        },
-                        {
-                            "reference_type": "variable:voice_reference_type",
-                            "from_file": "variable:character_b_voice"
-                        }
-                    ],
-                    "num_frames": "variable:num_frames",
-                    "width": "variable:width",
-                    "height": "variable:height",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "output": [
-                        "videos",
-                        "audio",
-                        "sampling_rate"
-                    ]
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        },
-        {
-            "name": "shot_5_tag",
-            "pipeline_reference": {
-                "reference_name": "shot_1_cold_open",
-                "arguments": {
-                    "prompt": "variable:shot_5_tag",
-                    "references": [
-                        {
-                            "reference_type": "variable:subject_reference_type",
-                            "from_previous_result": "draw_character_a"
-                        },
-                        {
-                            "reference_type": "variable:subject_reference_type",
-                            "from_previous_result": "draw_character_b"
-                        },
-                        {
-                            "reference_type": "variable:voice_reference_type",
-                            "from_file": "variable:character_a_voice"
-                        },
-                        {
-                            "reference_type": "variable:voice_reference_type",
-                            "from_file": "variable:character_b_voice"
-                        }
-                    ],
-                    "num_frames": "variable:tag_num_frames",
+                    "prompt": "item:prompt",
+                    "references": "item:references",
+                    "num_frames": "item:num_frames",
                     "width": "variable:width",
                     "height": "variable:height",
                     "num_inference_steps": "variable:num_inference_steps",
@@ -374,13 +308,7 @@
             "task": {
                 "command": "concat_videos",
                 "arguments": {
-                    "videos": [
-                        "previous_result:shot_1_cold_open",
-                        "previous_result:shot_2_deflect",
-                        "previous_result:shot_3_react",
-                        "previous_result:shot_4_button",
-                        "previous_result:shot_5_tag"
-                    ],
+                    "videos": "gather:shot",
                     "trim_frames": 0,
                     "audio_bleed_ms": "variable:audio_bleed_ms",
                     "fps": 24,
diff --git a/workflows/templates/minimax/music-video.json b/workflows/templates/minimax/music-video.json
index 0e0b4747..db77fad6 100644
--- a/workflows/templates/minimax/music-video.json
+++ b/workflows/templates/minimax/music-video.json
@@ -1,6 +1,6 @@
 {
     "id": "MiniMaxH3MusicVideo",
-    "description": "A music video built from cuts, sung to a soundtrack that never touches a chain. The long-take way to film a song - one chained generation lip-synced end to end - degrades with every carried segment and can let the sync slip. This builds the video the way music television does instead: MiniMax-Music3 writes the song, 'slice_audio' cuts it into frame-exact pieces (124 frames at 24 fps each), and every shot is generated fresh from the same Z-Image portrait plus its own slice, lip-synced to just those five seconds. No shot conditions on another shot's output, so the last cut is as clean as the first. 'concat_videos' splices the shots, and because each one covered exactly its slice's frames, the edit is sample-accurate by construction: 'pair_audio' drops the original, unbroken song over the whole cut and the mouths line up in every shot. The generation models pass through one at a time - each is released before the next loads - so the workflow peaks no higher than its largest single model.",
+    "description": "A music video built from cuts, sung to a soundtrack that never touches a chain. The long-take way to film a song - one chained generation lip-synced end to end - degrades with every carried segment and can let the sync slip. This builds the video the way music television does instead: MiniMax-Music3 writes the song, one 'slice_audio' step per entry of 'shots' cuts it into frame-exact pieces (124 frames at 24 fps each, from each entry's 'start_frame'), and one shot per entry is generated fresh from the same Z-Image portrait plus its own slice, lip-synced to just those five seconds. 'shots' is a list, so the cut is an argument: add an entry and there is one more slice and one more shot, named for it ('slice@closeup', 'shot@closeup'), and the loaded model is reused across every shot - identical pipeline definitions share one model. No shot conditions on another shot's output, so the last cut is as clean as the first. 'concat_videos' gathers the shots in list order, and because each one covered exactly its slice's frames, the edit is sample-accurate by construction: 'pair_audio' drops the original, unbroken song over the whole cut and the mouths line up in every shot. The generation models pass through one at a time - each is released before the next loads - so the workflow peaks no higher than its largest single model.",
     "cost": [
         {"device": "cuda", "name": "RTX 3090", "vram_gb": 24, "minutes": 35}
     ],
@@ -9,10 +9,28 @@
         "song_prompt": "prompt:minimax/otter_soul_song",
         "song_lyrics": "[verse]\nI've been waiting on you darling like a render overnight\nEvery frame of my devotion coming slowly into light\n[chorus]\nOoh, progress bar of love\nOoh, don't you stall on me now",
         "audio_duration": 30,
-        "shot_1_wide_open": "subject_definitions:\n<Subject 1> is the anthropomorphic river otter lounge singer in <Picture 1>, in a burgundy velvet dinner jacket and black bow tie, whose face, fur, jacket and proportions define his appearance for the whole video.\n<Audio 1> is the song <Subject 1> (S1) is lip-synchronised to: a smooth male crooner over a retro soul arrangement.\n\nsummary:\n[reference generation + audio reuse] The target video shows <Subject 1> performing the song carried by <Audio 1> at a vintage microphone on a nightclub stage, in one continuous wide shot.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the face, fur, velvet jacket, bow tie and proportions of <Picture 1> are kept exactly, with the body newly animated to sing.\n<Audio 1>: partially_copy - the piece of the song covering this part of the video is reused as the soundtrack, and <Subject 1>'s mouth is synchronised to its vocal.\n\ndetailed_description:\nThe target video is in realistic photographic style. [Shot 1] A wide shot frames a small nightclub stage: <Subject 1> stands centred at a vintage chrome ribbon microphone under a single warm spotlight, deep blue darkness and the faint silhouettes of a band behind him. He sings the vocal of <Audio 1>, his mouth moving in natural synchronisation with it, one paw resting on the microphone stand and the other loose at his side, swaying gently with the tempo. His tail sways in counterpoint behind him. The camera holds a static wide shot throughout, the stage lights unchanging.\n\noverall_soundscape:\nThe song of <Audio 1> carries the shot. Under it, a low nightclub room tone, the soft clink of glassware far off, and the faint brush of <Subject 1>'s jacket as he sways.\n\nnon_diegetic_music:\nN/A",
-        "shot_2_closeup": "subject_definitions:\n<Subject 1> is the anthropomorphic river otter lounge singer in <Picture 1>, in a burgundy velvet dinner jacket and black bow tie, whose face, fur, jacket and proportions define his appearance for the whole video.\n<Audio 1> is the song <Subject 1> (S1) is lip-synchronised to: a smooth male crooner over a retro soul arrangement.\n\nsummary:\n[reference generation + audio reuse] The target video shows <Subject 1> crooning the song carried by <Audio 1> in close-up at a vintage microphone, in one continuous shot.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the face, fur, velvet jacket, bow tie and proportions of <Picture 1> are kept exactly, with the head and jaw newly animated to sing.\n<Audio 1>: partially_copy - the piece of the song covering this part of the video is reused as the soundtrack, and <Subject 1>'s mouth is synchronised to its vocal.\n\ndetailed_description:\nThe target video is in realistic photographic style. [Shot 1] A close-up frames <Subject 1> from the shoulders up, angled slightly off centre, the vintage chrome microphone in the lower corner of frame and the warm spotlight modelling his fur against deep blue darkness. He sings the vocal of <Audio 1> with his eyes half closed, whiskers catching the light, his mouth in natural synchronisation with the vocal, leaning a breath closer to the microphone on the held notes and easing back between phrases. The camera holds a static close-up throughout.\n\noverall_soundscape:\nThe song of <Audio 1> carries the shot, the vocal close and warm at this distance. Under it, a low nightclub room tone and the faint creak of the microphone stand as he leans in.\n\nnon_diegetic_music:\nN/A",
-        "shot_3_room": "subject_definitions:\n<Subject 1> is the anthropomorphic river otter lounge singer in <Picture 1>, in a burgundy velvet dinner jacket and black bow tie, whose face, fur, jacket and proportions define his appearance for the whole video.\n<Audio 1> is the song <Subject 1> (S1) is lip-synchronised to: a smooth male crooner over a retro soul arrangement.\n\nsummary:\n[reference generation + audio reuse] The target video shows <Subject 1> performing the song carried by <Audio 1> seen across the tables of the nightclub, in one continuous shot.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the face, fur, velvet jacket, bow tie and proportions of <Picture 1> are kept exactly, with the body newly animated to sing and gesture.\n<Audio 1>: partially_copy - the piece of the song covering this part of the video is reused as the soundtrack, and <Subject 1>'s mouth is synchronised to its vocal.\n\ndetailed_description:\nThe target video is in realistic photographic style. [Shot 1] A medium-wide shot looks across the nightclub toward the stage from table height: candlelit tables blur softly in the foreground, and beyond them <Subject 1> stands at the vintage microphone in his spotlight, singing the vocal of <Audio 1> with his mouth in natural synchronisation. On the swell of the hook he lifts his free paw in a slow, open gesture and lets it settle back to the microphone stand. The camera holds a static shot from among the tables throughout, the candle flames flickering gently.\n\noverall_soundscape:\nThe song of <Audio 1> carries the shot with the slight distance and room reverb of the back of the club. Under it, the close clink of glasses at the foreground tables and a low murmur that hushes as the hook lands.\n\nnon_diegetic_music:\nN/A",
-        "shot_4_finale": "subject_definitions:\n<Subject 1> is the anthropomorphic river otter lounge singer in <Picture 1>, in a burgundy velvet dinner jacket and black bow tie, whose face, fur, jacket and proportions define his appearance for the whole video.\n<Audio 1> is the song <Subject 1> (S1) is lip-synchronised to: a smooth male crooner over a retro soul arrangement.\n\nsummary:\n[reference generation + audio reuse] The target video shows <Subject 1> bringing the song carried by <Audio 1> home, holding the last note with his arms spread wide, in one continuous shot.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the face, fur, velvet jacket, bow tie and proportions of <Picture 1> are kept exactly, with the body newly animated to sing.\n<Audio 1>: partially_copy - the piece of the song covering this part of the video is reused as the soundtrack, and <Subject 1>'s mouth is synchronised to its vocal.\n\ndetailed_description:\nThe target video is in realistic photographic style. [Shot 1] A wide shot frames the nightclub stage straight on: <Subject 1> at the vintage chrome microphone under his spotlight, deep blue darkness behind. He sings the vocal of <Audio 1> in natural synchronisation, and as the last line arrives he tips his head back, spreads both arms wide from the microphone, and holds the final note with his eyes closed, his tail still, the spotlight warming slightly around him. He brings his paws gently back together on the stand as the note ends. The camera holds a static wide shot throughout.\n\noverall_soundscape:\nThe song of <Audio 1> carries the shot. Under it, a low nightclub room tone that goes attentively quiet on the held note, and the soft brush of velvet as his arms spread.\n\nnon_diegetic_music:\nN/A",
+        "shots": [
+            {
+                "name": "wide_open",
+                "start_frame": 0,
+                "prompt": "subject_definitions:\n<Subject 1> is the anthropomorphic river otter lounge singer in <Picture 1>, in a burgundy velvet dinner jacket and black bow tie, whose face, fur, jacket and proportions define his appearance for the whole video.\n<Audio 1> is the song <Subject 1> (S1) is lip-synchronised to: a smooth male crooner over a retro soul arrangement.\n\nsummary:\n[reference generation + audio reuse] The target video shows <Subject 1> performing the song carried by <Audio 1> at a vintage microphone on a nightclub stage, in one continuous wide shot.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the face, fur, velvet jacket, bow tie and proportions of <Picture 1> are kept exactly, with the body newly animated to sing.\n<Audio 1>: partially_copy - the piece of the song covering this part of the video is reused as the soundtrack, and <Subject 1>'s mouth is synchronised to its vocal.\n\ndetailed_description:\nThe target video is in realistic photographic style. [Shot 1] A wide shot frames a small nightclub stage: <Subject 1> stands centred at a vintage chrome ribbon microphone under a single warm spotlight, deep blue darkness and the faint silhouettes of a band behind him. He sings the vocal of <Audio 1>, his mouth moving in natural synchronisation with it, one paw resting on the microphone stand and the other loose at his side, swaying gently with the tempo. His tail sways in counterpoint behind him. The camera holds a static wide shot throughout, the stage lights unchanging.\n\noverall_soundscape:\nThe song of <Audio 1> carries the shot. Under it, a low nightclub room tone, the soft clink of glassware far off, and the faint brush of <Subject 1>'s jacket as he sways.\n\nnon_diegetic_music:\nN/A"
+            },
+            {
+                "name": "closeup",
+                "start_frame": 124,
+                "prompt": "subject_definitions:\n<Subject 1> is the anthropomorphic river otter lounge singer in <Picture 1>, in a burgundy velvet dinner jacket and black bow tie, whose face, fur, jacket and proportions define his appearance for the whole video.\n<Audio 1> is the song <Subject 1> (S1) is lip-synchronised to: a smooth male crooner over a retro soul arrangement.\n\nsummary:\n[reference generation + audio reuse] The target video shows <Subject 1> crooning the song carried by <Audio 1> in close-up at a vintage microphone, in one continuous shot.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the face, fur, velvet jacket, bow tie and proportions of <Picture 1> are kept exactly, with the head and jaw newly animated to sing.\n<Audio 1>: partially_copy - the piece of the song covering this part of the video is reused as the soundtrack, and <Subject 1>'s mouth is synchronised to its vocal.\n\ndetailed_description:\nThe target video is in realistic photographic style. [Shot 1] A close-up frames <Subject 1> from the shoulders up, angled slightly off centre, the vintage chrome microphone in the lower corner of frame and the warm spotlight modelling his fur against deep blue darkness. He sings the vocal of <Audio 1> with his eyes half closed, whiskers catching the light, his mouth in natural synchronisation with the vocal, leaning a breath closer to the microphone on the held notes and easing back between phrases. The camera holds a static close-up throughout.\n\noverall_soundscape:\nThe song of <Audio 1> carries the shot, the vocal close and warm at this distance. Under it, a low nightclub room tone and the faint creak of the microphone stand as he leans in.\n\nnon_diegetic_music:\nN/A"
+            },
+            {
+                "name": "room",
+                "start_frame": 248,
+                "prompt": "subject_definitions:\n<Subject 1> is the anthropomorphic river otter lounge singer in <Picture 1>, in a burgundy velvet dinner jacket and black bow tie, whose face, fur, jacket and proportions define his appearance for the whole video.\n<Audio 1> is the song <Subject 1> (S1) is lip-synchronised to: a smooth male crooner over a retro soul arrangement.\n\nsummary:\n[reference generation + audio reuse] The target video shows <Subject 1> performing the song carried by <Audio 1> seen across the tables of the nightclub, in one continuous shot.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the face, fur, velvet jacket, bow tie and proportions of <Picture 1> are kept exactly, with the body newly animated to sing and gesture.\n<Audio 1>: partially_copy - the piece of the song covering this part of the video is reused as the soundtrack, and <Subject 1>'s mouth is synchronised to its vocal.\n\ndetailed_description:\nThe target video is in realistic photographic style. [Shot 1] A medium-wide shot looks across the nightclub toward the stage from table height: candlelit tables blur softly in the foreground, and beyond them <Subject 1> stands at the vintage microphone in his spotlight, singing the vocal of <Audio 1> with his mouth in natural synchronisation. On the swell of the hook he lifts his free paw in a slow, open gesture and lets it settle back to the microphone stand. The camera holds a static shot from among the tables throughout, the candle flames flickering gently.\n\noverall_soundscape:\nThe song of <Audio 1> carries the shot with the slight distance and room reverb of the back of the club. Under it, the close clink of glasses at the foreground tables and a low murmur that hushes as the hook lands.\n\nnon_diegetic_music:\nN/A"
+            },
+            {
+                "name": "finale",
+                "start_frame": 372,
+                "prompt": "subject_definitions:\n<Subject 1> is the anthropomorphic river otter lounge singer in <Picture 1>, in a burgundy velvet dinner jacket and black bow tie, whose face, fur, jacket and proportions define his appearance for the whole video.\n<Audio 1> is the song <Subject 1> (S1) is lip-synchronised to: a smooth male crooner over a retro soul arrangement.\n\nsummary:\n[reference generation + audio reuse] The target video shows <Subject 1> bringing the song carried by <Audio 1> home, holding the last note with his arms spread wide, in one continuous shot.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the face, fur, velvet jacket, bow tie and proportions of <Picture 1> are kept exactly, with the body newly animated to sing.\n<Audio 1>: partially_copy - the piece of the song covering this part of the video is reused as the soundtrack, and <Subject 1>'s mouth is synchronised to its vocal.\n\ndetailed_description:\nThe target video is in realistic photographic style. [Shot 1] A wide shot frames the nightclub stage straight on: <Subject 1> at the vintage chrome microphone under his spotlight, deep blue darkness behind. He sings the vocal of <Audio 1> in natural synchronisation, and as the last line arrives he tips his head back, spreads both arms wide from the microphone, and holds the final note with his eyes closed, his tail still, the spotlight warming slightly around him. He brings his paws gently back together on the stand as the note ends. The camera holds a static wide shot throughout.\n\noverall_soundscape:\nThe song of <Audio 1> carries the shot. Under it, a low nightclub room tone that goes attentively quiet on the held note, and the soft brush of velvet as his arms spread.\n\nnon_diegetic_music:\nN/A"
+            }
+        ],
         "audio_reference_type": "diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference",
         "image_reference_type": "diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference",
         "sample_rate": 44100,
@@ -86,52 +104,14 @@
             }
         },
         {
-            "name": "slice_1",
-            "task": {
-                "command": "slice_audio",
-                "arguments": {
-                    "audio": "previous_result:write_song",
-                    "sample_rate": "variable:sample_rate",
-                    "start_frame": 0,
-                    "num_frames": "variable:num_frames",
-                    "fps": "variable:fps"
-                }
-            }
-        },
-        {
-            "name": "slice_2",
-            "task": {
-                "command": "slice_audio",
-                "arguments": {
-                    "audio": "previous_result:write_song",
-                    "sample_rate": "variable:sample_rate",
-                    "start_frame": 124,
-                    "num_frames": "variable:num_frames",
-                    "fps": "variable:fps"
-                }
-            }
-        },
-        {
-            "name": "slice_3",
-            "task": {
-                "command": "slice_audio",
-                "arguments": {
-                    "audio": "previous_result:write_song",
-                    "sample_rate": "variable:sample_rate",
-                    "start_frame": 248,
-                    "num_frames": "variable:num_frames",
-                    "fps": "variable:fps"
-                }
-            }
-        },
-        {
-            "name": "slice_4",
+            "name": "slice",
+            "for_each": "variable:shots",
             "task": {
                 "command": "slice_audio",
                 "arguments": {
                     "audio": "previous_result:write_song",
                     "sample_rate": "variable:sample_rate",
-                    "start_frame": 372,
+                    "start_frame": "item:start_frame",
                     "num_frames": "variable:num_frames",
                     "fps": "variable:fps"
                 }
@@ -151,7 +131,8 @@
             }
         },
         {
-            "name": "shot_1_wide_open",
+            "name": "shot",
+            "for_each": "variable:shots",
             "pipeline": {
                 "configuration": {
                     "component_type": "ModularPipeline",
@@ -260,7 +241,7 @@
                     }
                 ],
                 "arguments": {
-                    "prompt": "variable:shot_1_wide_open",
+                    "prompt": "item:prompt",
                     "references": [
                         {
                             "reference_type": "variable:image_reference_type",
@@ -268,106 +249,7 @@
                         },
                         {
                             "reference_type": "variable:audio_reference_type",
-                            "from_previous_result": "slice_1",
-                            "sample_rate": "variable:sample_rate"
-                        }
-                    ],
-                    "num_frames": "variable:num_frames",
-                    "width": "variable:width",
-                    "height": "variable:height",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "output": [
-                        "videos",
-                        "audio",
-                        "sampling_rate"
-                    ]
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        },
-        {
-            "name": "shot_2_closeup",
-            "pipeline_reference": {
-                "reference_name": "shot_1_wide_open",
-                "arguments": {
-                    "prompt": "variable:shot_2_closeup",
-                    "references": [
-                        {
-                            "reference_type": "variable:image_reference_type",
-                            "from_previous_result": "draw_singer"
-                        },
-                        {
-                            "reference_type": "variable:audio_reference_type",
-                            "from_previous_result": "slice_2",
-                            "sample_rate": "variable:sample_rate"
-                        }
-                    ],
-                    "num_frames": "variable:num_frames",
-                    "width": "variable:width",
-                    "height": "variable:height",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "output": [
-                        "videos",
-                        "audio",
-                        "sampling_rate"
-                    ]
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        },
-        {
-            "name": "shot_3_room",
-            "pipeline_reference": {
-                "reference_name": "shot_1_wide_open",
-                "arguments": {
-                    "prompt": "variable:shot_3_room",
-                    "references": [
-                        {
-                            "reference_type": "variable:image_reference_type",
-                            "from_previous_result": "draw_singer"
-                        },
-                        {
-                            "reference_type": "variable:audio_reference_type",
-                            "from_previous_result": "slice_3",
-                            "sample_rate": "variable:sample_rate"
-                        }
-                    ],
-                    "num_frames": "variable:num_frames",
-                    "width": "variable:width",
-                    "height": "variable:height",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "output": [
-                        "videos",
-                        "audio",
-                        "sampling_rate"
-                    ]
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        },
-        {
-            "name": "shot_4_finale",
-            "pipeline_reference": {
-                "reference_name": "shot_1_wide_open",
-                "arguments": {
-                    "prompt": "variable:shot_4_finale",
-                    "references": [
-                        {
-                            "reference_type": "variable:image_reference_type",
-                            "from_previous_result": "draw_singer"
-                        },
-                        {
-                            "reference_type": "variable:audio_reference_type",
-                            "from_previous_result": "slice_4",
+                            "from_previous_result": "slice",
                             "sample_rate": "variable:sample_rate"
                         }
                     ],
@@ -392,12 +274,7 @@
             "task": {
                 "command": "concat_videos",
                 "arguments": {
-                    "videos": [
-                        "previous_result:shot_1_wide_open",
-                        "previous_result:shot_2_closeup",
-                        "previous_result:shot_3_room",
-                        "previous_result:shot_4_finale"
-                    ],
+                    "videos": "gather:shot",
                     "trim_frames": 0,
                     "fps": "variable:fps",
                     "audio_bleed_ms": "variable:audio_bleed_ms",