diff --git a/docs/MCP.md b/docs/MCP.md
index 2be4b937..6dbe0d35 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -233,7 +233,7 @@ when no single workflow covers it.
 
 | Tool | Arguments | Purpose |
 | --- | --- | --- |
-| `get_output_image(name, max_dimension=768, workspace=None)` | `name`, `max_dimension`, `workspace` | Look at a generated image, downscaled to `max_dimension` on its longest side. Returns the image plus a text part reporting `original_size`, `returned_size` and `bytes`, so a downscale is never silent. `workspace` names the workspace for this one call without switching the session to it - the same pin `run_workflow` takes, so a job run into another workspace stays reachable from the session that queued it |
+| `get_output_image(name, max_dimension=768, workspace=None, crop=None)` | `name`, `max_dimension`, `workspace`, `crop` | Look at a generated image, downscaled to `max_dimension` on its longest side. Returns the image plus a text part reporting `original_size`, `returned_size` and `bytes`, so a downscale is never silent. `crop` is `[x, y, width, height]` in the original's pixels, cut before the downscale and reported back clamped - the way to see a region of a 2K still at 100%, where the whole would be shrunk past what a small element or a decode-tiling seam can be judged at. `workspace` names the workspace for this one call without switching the session to it - the same pin `run_workflow` takes, so a job run into another workspace stays reachable from the session that queued it |
 | `get_output_audio(name, workspace=None)` | `name`, `workspace` | Listen to a generated audio output, as base64. Unlike `get_output_image` there is no downscale - a clip whose base64 size would exceed the same 4MB budget is refused outright rather than cut or transcoded, since a truncated clip is a different, misleading answer rather than a smaller correct one (#204). Use `download_output` or the gallery `url` for a longer file, and `get_gallery_metadata` for its duration and sample rate without fetching the bytes at all. `workspace` names the workspace for this one call without switching the session to it |
 | `get_output_text(name, max_characters=20000, workspace=None)` | `name`, `max_characters`, `workspace` | Read a text output — a prompt enhancement, or any step whose result is `text/plain` or JSON. Reports the file's real length and whether it was truncated. `workspace` names the workspace for this one call without switching the session to it - the same pin `run_workflow` takes, so a job run into another workspace stays reachable from the session that queued it |
 | `download_output(name, destination=None, overwrite=False, workspace=None)` | `name`, `destination`, `overwrite`, `workspace` | Save one output file to local disk, of any content type. `destination` may be a full path, a directory, or omitted to save under the output's own name in the current working directory; `~` expands and missing parent directories are created. `overwrite=True` is required to replace a file already at the resolved path. Over a `dw.serve --mcp` endpoint the file lands on the server, so the destination is confined to that workspace and a relative one is joined onto it. Returns nothing to the conversation but where the file landed — unlike the other media tools, the point is a file on disk, not a payload in context. Writes on the machine running the MCP server - over `dw.serve --mcp` that is the GPU box. A write that fails there (a path that exists only on the client, for instance) comes back as an error naming the server-side write and the client-side alternatives, not as an anonymous tool failure. `workspace` names the workspace for this one call without switching the session to it - the same pin `run_workflow` takes, so a job run into another workspace stays reachable from the session that queued it |
diff --git a/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md
index 29d80af7..924045b5 100644
--- a/docs/WORKFLOW_GUIDE.md
+++ b/docs/WORKFLOW_GUIDE.md
@@ -283,6 +283,10 @@ for existence.
 - `asset:` — `asset:name` is a file in the asset library. Rooted at the
   library and confined to it, never resolved relative to the workflow file; a path that
   escapes the library is rejected. `upload_asset` returns one of these names.
+  One name, three places it can sit: a bare string (`"image": "asset:x.png"`),
+  an element of a list, or the `location` of a media dict
+  (`{"location": "asset:x.png"}`, with or without `media_type`) - all resolve
+  to the same file.
 - `output:` — `output:<workflow identity>/<run id>/<file>` is a file an earlier
   run wrote, under the output root and confined to it. `latest` in the run-id position
   picks the newest run that holds that file. A run id is not stable against
@@ -727,7 +731,12 @@ longer than that is truncated with an ellipsis in every listing.
 Declare `shape`, `traits` or `summary` at the top level only when derivation
 gets it wrong; a declaration that merely repeats the derivation is noise that
 rots when the rules change, and the repo's catalog tests refuse it. `cost` is
-never derived — leave it absent until a run has been measured.
+never derived — leave it absent until a run has been measured. That makes it
+the catalog's verified marker as well: an entry carrying `cost` has been run
+to completion on the device it names, and one without has only been authored
+— its description may still say what it has not been able to check (VRAM at
+a size, whether a format carries what the pipeline returns), and the first
+run is the one that finds out.
 
 `cost_drivers` is the other half of saying what a workflow costs, and it *is*
 for derivation: the variables that move the wall clock — a frame count, a
diff --git a/docs/proposals/agent-catalog-legibility-complete.md b/docs/proposals/agent-catalog-legibility-complete.md
index d9512afe..9843d81b 100644
--- a/docs/proposals/agent-catalog-legibility-complete.md
+++ b/docs/proposals/agent-catalog-legibility-complete.md
@@ -517,7 +517,7 @@ starts from the record rather than the intent. Updated as work lands.
 | 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. |
+| 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. Qwen-Image-2.1 onboarded 2026-09-20, the day of its release: audited (docs/proposals/audits/2026-09-20-qwen-image-2.1-audit.md) against the day-zero vendor README, license and diffusers docs page, superseding the 2026-09-08 draft `qwen-image-wan-onboarding.md`'s assumptions about the older 20B Qwen-Image (that draft's model is a different, larger, Apache-2.0 checkpoint and stays a separate backlog item); `workflows/models/qwen-image-2.1.json` is the one flagship text-to-image template the audit recommended, `QwenImage21Pipeline` under model offload, no `guidance_scale` (the pipeline has none), explicit 2048x2048 (undoing the pipeline's 1024 `output_resolution` fallback), width/height bound to the 32-px floor grid via `variable_constraints` with no `snap`; its description carries the non-commercial license note and flags VRAM-at-2K, `cost` and the `transformers>=5.17` vendor ask as unverified pending a GPU run. No composition skill: editing is an argument to the one pipeline, not a separate checkpoint, so there is no shape to pick between. |
 
 
 ### Cold-session probe, 2026-09-07
diff --git a/docs/proposals/audits/2026-09-20-qwen-image-2.1-audit.md b/docs/proposals/audits/2026-09-20-qwen-image-2.1-audit.md
new file mode 100644
index 00000000..58536bdd
--- /dev/null
+++ b/docs/proposals/audits/2026-09-20-qwen-image-2.1-audit.md
@@ -0,0 +1,292 @@
+# Qwen-Image-2.1 — onboarding research
+
+Researched 2026-09-20. Greenfield: the catalog has no Qwen entry of any kind.
+The model was released **the same day** this was written (2026.09.20), so every
+number below is vendor-stated or read out of the installed diffusers source —
+none of it is corroborated by a community run yet.
+
+## Sources
+
+| URL | Type | Date | Contributes |
+|---|---|---|---|
+| https://huggingface.co/Qwen/Qwen-Image-2.1 | primary (vendor model card) | repo created 2026-09-14, last modified 2026-09-20 (HF API) | Identity, 7B visual generator / 32 single-stream DiT layers, unified T2I + editing, RGBA, ≤10 reference images, Qwen Research License, aspect-ratio table, 40 steps, 2048×2048 |
+| https://huggingface.co/Qwen/Qwen-Image-2.1/raw/main/README.md | primary (raw card) | 2026-09-20 | **Not gated** — fetched fine. Same content as the HTML card; `pipeline_tag: text-to-image`, tags `diffusers, qwen, image-generation, image-editing, rgba` |
+| https://github.com/QwenLM/Qwen-Image-2.1 + https://raw.githubusercontent.com/QwenLM/Qwen-Image-2.1/main/README.md | primary (vendor repo) | repo created 2026-09-14T04:12Z, pushed 2026-09-20T12:25Z (GitHub API); News entries all dated 2026.09.20 | Full README read verbatim: all code examples, default-parameter table, aspect-ratio dict, RGBA prompt format, `enable_model_cpu_offload()` as the only memory advice, architecture section, prefix-KV-cache note, Day-0 integrations |
+| https://raw.githubusercontent.com/QwenLM/Qwen-Image-2.1/main/prompt_rewrite/README.md | primary | 2026-09-20 | The two PE (prompt-enhancer) checkpoints, Qwen3.5-VL 9B, ~20 GB bf16, 40 GB GPU |
+| https://raw.githubusercontent.com/QwenLM/Qwen-Image-2.1/main/prompt_rewrite/prompts/system_prompt_t2i.txt | primary | 2026-09-20 | **The vendor's actual prompt-writing convention** — English, ~20 sentences / 400–500 words, prescribed section order, "observe don't instruct", no quality boosters |
+| https://huggingface.co/Qwen/Qwen-Image-2.1/raw/main/LICENSE | primary | agreement effective 2026-09-20 | Qwen **Research** License: non-commercial only, "Built with Qwen" attribution, commercial use by separate request |
+| https://huggingface.co/docs/diffusers/main/en/api/pipelines/qwenimage21 | primary (diffusers docs, main) | current as of 2026-09-20 | **This page exists.** Confirms `QwenImage21Pipeline`, "defaults are the values Qwen recommends: 40 steps and no guidance", multi-condition-image block semantics, flex-attention processor guidance |
+| https://huggingface.co/docs/diffusers/main/en/api/pipelines/qwenimage | primary | current | The *old* family's page — lists 8 classes, **does not mention QwenImage21**. Its settings (50 steps, `true_cfg_scale=4.0`, 1024×1024, Lightning 8-step LoRA) belong to Qwen-Image, **not** to 2.1 |
+| Installed diffusers `0.41.0.dev0` at `venv/lib/python3.14/site-packages/diffusers/pipelines/qwenimage21/pipeline_qwenimage21.py` | primary (source) | installed build | Exact `__call__` signature and defaults, prompt templates, `calculate_dimensions` 32-px rounding, `vae_scale_factor = 16`, `model_cpu_offload_seq`, RGBA/alpha handling |
+| HF API `/api/models/Qwen/Qwen-Image-2.1?blobs=true` | primary (derived) | 2026-09-20 | Per-component bf16 weight sizes — the hard VRAM arithmetic below |
+| HF API for `Qwen/Qwen-Image`, `-2512`, `-Edit`, `-Edit-2511`, `-2.1-PE-*` | primary (derived) | 2026-09-20 | Sibling dates, licenses, sizes, download counts |
+| WebSearch "Qwen-Image-2.1 VRAM 24GB GGUF…" (sandner.art, qwen-image-2512.com, dev.to) | secondary | 2025-Q4 / 2026 | **All about Qwen-Image / 2512, not 2.1.** No 2.1-specific community hardware data exists yet |
+| WebSearch "Qwen-Image-2.1 release model card GitHub QwenLM" | secondary | 2026-09-20 | Mostly stale; one aggregator (artrealmai.com) still reported the card as non-public. Ignored |
+| https://qwen.ai/blog?id=qwen-image-2.1 | primary | 2026-09-20 | **Fetch returned only the word "Qwen"** — JS-rendered, no content extractable. Not used |
+| Repo: `docs/proposals/qwen-image-wan-onboarding.md` | internal | draft 2026-09-08 | The assumptions this research supersedes |
+| Repo: `docs/RECIPES_24GB.md` lines 33-37 | internal | — | The only existing Qwen knowledge in the repo, and it is about the 20B model |
+
+`docs/QUANTIZATION.md` and `docs/ACCELERATION.md` contain **no** "qwen" mentions.
+
+## Model identity and scope
+
+- **Repo**: `Qwen/Qwen-Image-2.1`. Weights public, **not gated** (`gated: false`), 33.1 GB total in bf16.
+- **Parameters**: 7B in the visual generator — 32 single-stream DiT layers with block-causal
+  attention (`(q_idx >= kv_idx) or same_image_block`). Plus a **Qwen3-VL 8B** text encoder that
+  also does the vision encoding, and a 64-channel RGBA VAE at 16× spatial compression.
+  Per-file bf16 sizes from the HF API: `text_encoder` 17.53 GB, `transformer` 14.23 GB,
+  `vae` 1.35 GB.
+- **License**: **Qwen Research License Agreement**, effective 2026-09-20 — *non-commercial only*,
+  requires "Built with Qwen" attribution, commercial use needs a separate grant. This is a
+  **hard break from every sibling**, all of which are Apache-2.0. Anything shipped in the catalog
+  should say so in the workflow `description`.
+- **Pipeline class**: `diffusers.QwenImage21Pipeline`, in `diffusers/pipelines/qwenimage21/`.
+  **Already present in the repo's venv** (diffusers `0.41.0.dev0`), imports cleanly, and the
+  diffusers `main` docs page for it exists. **No engine work and no diffusers bump is needed.**
+  One caveat: the vendor asks for `transformers>=5.17`; the venv has **5.16.1**. `Qwen3VLForConditionalGeneration`
+  and `Qwen3VLProcessor` both import successfully on 5.16.1, but this is untested against a real load.
+- **Unified, not split.** One pipeline does text-to-image *and* editing: `image=` (a PIL image or a
+  **list of up to 10**) turns the same call into conditioned generation. There is no separate
+  `QwenImage21EditPipeline`. Components for a dw workflow are `scheduler`, `vae`, `text_encoder`,
+  `processor`, `transformer`.
+- **Native RGBA.** The VAE decodes 4 channels and `VaeImageProcessor.numpy_to_pil` hands back a
+  4-channel `PIL.Image` (`Image.fromarray` on a 4-channel array → mode RGBA), so transparency
+  survives to `Result.save` — but **only if saved as PNG**. `dw/result.py` handles `image/png`;
+  the existing templates all use `image/jpeg`, which would silently flatten the alpha. This is a
+  real template-design constraint.
+
+### Relation to the siblings (all dates from the HF API)
+
+| Repo | Created | License | Tag | bf16 weights | Note |
+|---|---|---|---|---|---|
+| `Qwen/Qwen-Image` | 2025-08-02 | apache-2.0 | text-to-image | 57.7 GB | The 20B model the draft proposal is about |
+| `Qwen/Qwen-Image-Edit` | 2025-08-17 | apache-2.0 | image-to-image | 57.7 GB | Editing sibling of the 20B |
+| `Qwen/Qwen-Image-Edit-2511` | 2025-12-17 | apache-2.0 | image-to-image | 57.7 GB | Most-downloaded of the family (323k) |
+| `Qwen/Qwen-Image-2512` | 2025-12-30 | apache-2.0 | text-to-image | 57.7 GB | Refresh of the 20B, same scale |
+| `Qwen/Qwen-Image-2.1` | 2026-09-14 (public 09-20) | **Qwen Research** | text-to-image (but unified) | **33.1 GB** | This model |
+| `Qwen/Qwen-Image-2.1-PE-T2I` / `-PE-I2I` | 2026-09-20 | other | — | 18.8 GB each | Optional Qwen3.5-VL 9B prompt rewriters |
+
+A "Qwen-Image-2.0" was reported (2026-02-10) by search results; `Qwen/Qwen-Image-2.0` returns an
+API error and I did not verify it. Do not cite it.
+
+**Qwen-Image-2.1 supersedes the older line in practice** — it is a new architecture (single-stream
+DiT, Qwen3-VL encoder, RGBA VAE) at roughly **half** the weight footprint, and it folds
+`Qwen-Image` + `Qwen-Image-Edit` + `Qwen-Image-Edit-Plus` into one checkpoint. But it does **not
+retire** them: the older ones stay Apache-2.0 and keep the large ecosystem (Lightning LoRAs, GGUF
+builds, ControlNets) that 2.1 has none of yet. They coexist, and the licence is the reason a user
+might still want the 20B.
+
+### Where this differs from `docs/proposals/qwen-image-wan-onboarding.md` (draft 2026-09-08)
+
+The draft predates this release by 12 days and is about the **20B Qwen-Image**. Explicitly:
+
+1. **Scale.** Draft: "Qwen-Image (20B)… bf16 doesn't fit; 4-bit BitsAndBytes brings it to ~17GB."
+   2.1 is 7B + an 8B encoder = 33.1 GB bf16 — still doesn't fit 24 GB resident, but model
+   *offloading alone* plausibly suffices; 4-bit may not be needed at all.
+2. **Split vs unified.** Draft: "`QwenImagePipeline` / `QwenImageEditPipeline`… Qwen-Image-Edit is
+   the piece that would carry real shape decisions… the reason a skill might be worthwhile."
+   In 2.1 there is **one** pipeline; editing is an argument, not a checkpoint. The skill question
+   changes shape entirely — see Assessment.
+3. **Guidance.** Draft assumes the FLUX/Z-Image flat `guidance_scale` shape. 2.1 takes **no**
+   `guidance_scale` at all — only `true_cfg_scale`, defaulting to **1.0 (off)**. A template that
+   copies `workflows/templates/text-to-image`'s shape verbatim with a `guidance_scale` argument
+   would raise.
+4. **Text encoder.** Draft: "The Qwen2.5-VL text encoder is large — quantize it or group-offload
+   it (`"text_encoder.model"` with `leaf_level`)" (also in `docs/RECIPES_24GB.md` line 35).
+   2.1 uses **Qwen3-VL 8B**, and that encoder also consumes the condition images, so it cannot
+   simply be swapped for a remote/quantized text-only encoder.
+5. **License.** The draft assumes nothing; 2.1 being research-only is new and material.
+6. **RGBA and ≤10 references** are capabilities the draft does not contemplate at all.
+7. **Resolution.** Draft assumes the 1024-class default. 2.1 is a **native 2K** model.
+
+`docs/RECIPES_24GB.md` lines 33-37 stay correct **for the 20B model** and should not be edited to
+describe 2.1; 2.1 wants its own entry.
+
+## Hardware / quantization fit
+
+**Vendor's own note is thin**: the only memory advice in the entire README is
+`pipe.enable_model_cpu_offload()` "for GPUs with limited memory". No VRAM table, no minimum.
+The diffusers source states no footprints either. So the arithmetic below is mine, from the HF
+blob sizes — reliable for weights, silent about activations.
+
+- **bf16 resident: 33.1 GB. Does not fit 24 GB.** (17.53 + 14.23 + 1.35.)
+- **`offload: "model"` (the vendor's `enable_model_cpu_offload`)**: `model_cpu_offload_seq` is
+  `"text_encoder->transformer->vae"`, so peak weight residency is the largest single component,
+  **17.5 GB** (the text encoder), leaving ~6 GB for activations on a 24 GB card. This is the
+  vendor-endorsed path and is the one a first template should take.
+  **Untested at 2048×2048**: the target latent grid at 2K is 128×128 = 16 384 tokens, plus the
+  Qwen3-VL prefix and (in editing) up to ten condition-image blocks. Attention activations at that
+  sequence length are not something I can size from documentation.
+- **`offload: "sequential"`** would drop peak weight residency much further at a large speed cost —
+  and on MPS the repo downgrades it to `"model"` anyway (`place_component`).
+- **4-bit / GGUF**: **nothing exists yet.** There is no `diffusers/Qwen-Image-2.1-bnb-4bit`
+  analogous to `diffusers/FLUX.2-dev-bnb-4bit`, and no community GGUF. Every GGUF result the
+  search returned is for **Qwen-Image / 2512**, i.e. the 20B — do not carry those claims over.
+  A bnb-4bit `text_encoder` component following `workflows/models/flux2-dev.json`'s pattern
+  would have to be quantized on the fly via `config_objects.py` rather than pulled pre-quantized.
+- FP8 is mentioned only as a vLLM-Omni / SGLang feature, not a diffusers one.
+- AMD ROCm and FlagOS multi-chip are claimed; MPS is not mentioned anywhere by the vendor.
+
+## Recommended inference settings
+
+Vendor defaults (README "Default Parameters" table + diffusers docs, in agreement):
+
+| Setting | Value | Source |
+|---|---|---|
+| `num_inference_steps` | **40** | README table; also the diffusers `__call__` default |
+| `width`/`height` | **2048 × 2048** | README table ("Native 2K resolution") |
+| `true_cfg_scale` | **1.0 — guidance off** | diffusers default; docs: "Qwen-Image 2.1 is meant to be sampled without guidance, hence the default of 1.0" |
+| `guidance_scale` | **does not exist** | `__call__` signature has no such parameter |
+| `negative_prompt` | pointless unless `true_cfg_scale > 1`; the pipeline logs a warning either way if the two disagree | source lines ~669-679 |
+| dtype | `torch.bfloat16` | every vendor example |
+| scheduler | `FlowMatchEulerDiscreteScheduler` with dynamic shift (`mu` from `calculate_shift`, base_shift 0.5 / max_shift 1.15) | source + architecture section |
+| `use_kv_cache` | `True` (prefix KV reuse; big win for multi-reference editing) | source; note it changes the *sample*, not just the speed — "Fix a sample by fixing this flag" |
+| `output_resolution` | diffusers default **1024** | source — **conflicts with the card's 2048 in effect**: omit width/height and you get a 1024 image, not the recommended 2K |
+
+**Note that conflict.** The diffusers `output_resolution` default of 1024 means a template that
+does not pass `width`/`height` silently renders at half the vendor-recommended resolution. A
+template should set them explicitly.
+
+**Aspect ratios** (README dict; all values are multiples of 32, which is what the pipeline enforces
+via `multiple_of = vae_scale_factor * 2 = 32`, floor-rounding anything off-grid):
+
+```
+1:1 (2048,2048)  4:3 (2400,1792)  3:4 (1792,2400)  3:2 (2528,1696)
+2:3 (1696,2528)  16:9 (2752,1536) 9:16 (1536,2752)
+```
+
+This is a **32-pixel grid constraint**, analogous to H3's `17n+5` and LTX's `8k+1`, and it
+**floors** rather than raising — so it belongs in `variable_constraints` **without** `snap`,
+exactly as the LTX-2.5 templates do (`dw/variable_constraints.py`).
+
+**Transparent output** — the vendor's literal prompt wrapper:
+
+> `This is an RGBA image with transparency. <your description>. The image has alpha channel and the background is transparent.`
+
+**Prompt-writing convention** (from `prompt_rewrite/prompts/system_prompt_t2i.txt`, the system
+prompt of the vendor's own rewriter — this is the closest thing to a MiniMax/LTX-style trained
+caption spec):
+
+- Output **English**, whatever the input language.
+- **~20 sentences, 400–500 words, ~25 words a sentence.**
+- Structure, in order: opening sentence naming medium/style/subject/background/orientation → a
+  positional inventory of elements across frame regions → a sequential walkthrough → a dedicated
+  text-rendering section if any legible text appears → a dedicated lighting sentence → a closing
+  composition summary.
+- **Preserve verbatim**: every text string to be rendered, "character for character, in their own
+  script, including punctuation and spacing"; every named object, count, stated colour, stated
+  position, and the aspect ratio if given.
+- **"Observe, don't instruct"** — present tense, third person, no imperatives.
+- **Never** include resolution, pixel counts, or quality boosters.
+- **"Enumerate; never summarise."**
+- Unspecified aspect ratio defaults to 3:2 or 2:3.
+- The rewriter emits `{"rewritten_prompt": ..., "wh_ratio": "16:9"}` and the README's own
+  integration snippet maps `wh_ratio` through the aspect table to `width`/`height`.
+
+The **edit** rewriter additionally emits `ratio_follow: "<image1>"`, meaning "inherit that input
+image's aspect ratio" — which matches the pipeline's own behaviour of deriving `height`/`width`
+from the *last* condition image when they are omitted.
+
+The PE models themselves (Qwen3.5-VL 9B, ~20 GB bf16, "a single 40 GB GPU handles either task")
+are **too heavy to bundle into a template** on a 24 GB box alongside the generator. The repo's
+existing `workflows/templates/expand-prompt.json` / `minimax/enhance-prompt.json` pattern is the
+right home if it is ever wanted; the written convention above is the part worth encoding in a
+skill or a stored prompt.
+
+## Missing knowledge / open questions
+
+Not answerable from documentation — each needs a real GPU run:
+
+1. **Actual peak VRAM at 2048×2048 with `offload: "model"` on a 24 GB card.** The weight
+   arithmetic says 17.5 GB resident; activations at 16 384 target tokens are unknown. This is the
+   single most important unknown and it decides whether the flagship template ships at 2K or 1K.
+2. **Wall-clock minutes** for the `cost` block. No vendor benchmark, no community number, nothing
+   in `jobs.sqlite`. A `cost` entry must be measured (the schema says "Never derived").
+3. **Peak VRAM and speed in editing mode with several reference images** — each condition image
+   adds a block to the joint sequence and a KV-cache entry across 32 layers.
+4. **Whether `transformers` 5.16.1 actually loads the checkpoint.** Vendor asks `>=5.17`. Imports
+   succeed; a real `from_pretrained` has not been tried.
+5. **Whether RGBA survives the repo's save path end to end** — `content_type: "image/png"` plus
+   `embed_metadata`. Plausible from the code, unverified.
+6. **Whether `sequential` offload works** at all here (Qwen3-VL is a composite module;
+   `exclude_from_cpu_offload` is sequential-only).
+7. **Does bnb-4bit quantization of `text_encoder` behave** when that encoder must also run the
+   vision tower? No pre-quantized repo exists to test against.
+8. **The blog post's benchmark numbers** — `qwen.ai/blog?id=qwen-image-2.1` is JS-rendered and
+   returned no text. Any quality claim relative to the 20B is currently uncited.
+9. **`use_kv_cache` and the step cache.** The docs say toggling it changes the sample
+   bit-for-bit-differently at fixed seed. If a template exposes it, it must be part of the cache
+   key — it already is, since it would be a step argument.
+10. **Circle / painted-annotation / mask local editing** is advertised but the README shows no
+    code for it beyond passing the annotated image as a condition image. Probably just that, but
+    unconfirmed.
+
+## What the templates should teach
+
+One idea per template, reading order. `qwen` as the family directory, matching `ltx2/` and
+`minimax/`. Every one of these should set `content_type: "image/png"` if alpha is in play and
+carry the non-commercial licence note in its `description`.
+
+1. **`workflows/models/qwen-image-2.1.json`** — the flagship, `configures: templates/text-to-image`
+   in spirit but with its own argument set (no `guidance_scale`). Teaches: `QwenImage21Pipeline`,
+   bf16, `offload: "model"`, 40 steps, an explicit 2K `width`/`height`, guidance left off.
+   Declares `variable_constraints` for `width`/`height` on the 32-px grid, no `snap`.
+2. **a `templates/qwen/aspect-ratios` template** (not yet written) — teaches the seven recommended sizes and
+   that the pipeline floors off-grid values. Could reasonably be folded into #1 as a documented
+   variable rather than its own file.
+3. **a `templates/qwen/transparent` template** (not yet written) — the one idea no other model in the catalog
+   has: native RGBA. Teaches the vendor's prompt wrapper *and* `content_type: "image/png"`, which
+   is the half that actually preserves the alpha.
+4. **`workflows/models/qwen-image-2.1-edit.json`** (shipped, after a field run found the
+   text-to-image entry's three silent breaks) — single condition image, instruction prompt, same
+   pipeline, `configures: templates/image-edit` (FLUX.1 Kontext) as the comparison. Runs
+   `offload: "sequential"` where the text-to-image entry runs `"model"`: the condition latents
+   lengthen the sequence, and `"model"` OOMs at 2048x1024 on a clean 24GB card.
+5. **a `templates/qwen/multi-reference` template** (not yet written) — up to 10 references, following the
+   `"image": ["variable:first_image", "variable:second_image"]` list shape that
+   `templates/multi-image-reference.json` already established for FLUX.2. Teaches that order is
+   semantic (block-causal: later blocks attend to earlier ones) and that the prompt refers to them
+   positionally.
+6. **a `templates/qwen/true-cfg` template** (not yet written) — the only template that turns guidance *on*, with
+   a `negative_prompt` and `true_cfg_scale > 1`, and says plainly that this doubles the work per
+   step and is off by default on purpose. Guards against the next author copying FLUX's
+   `guidance_scale: 4`.
+7. *(optional, later)* **a prompt-rewriting chain** reusing `templates/expand-prompt` with the PE
+   convention written into a stored prompt — only if the 40 GB rewriter can be replaced by an
+   instruction to a model already in the catalog.
+
+A `for_each`-driven template is not obviously warranted; this family has no chaining or frame
+arithmetic.
+
+## Assessment (under 300 words)
+
+**Yes — onboard it, but ship one template, not six.**
+
+The primary documentation is unusually good for a day-zero release: a full vendor README with a
+default-parameter table, an aspect-ratio dict, verbatim code for all three modes, a diffusers docs
+page that already exists, and — rarest of all — the vendor's own prompt-rewriter **system prompt**,
+which gives a trained-caption spec as concrete as MiniMax's. `QwenImage21Pipeline` is already in
+the repo's venv and imports. No engine work is implied.
+
+What I would trust in a template's defaults: the class name and repo id; `torch.bfloat16`;
+`num_inference_steps: 40`; `true_cfg_scale` absent (guidance off); the seven aspect-ratio pairs and
+the 32-px floor rule; the RGBA prompt wrapper; the list-of-images editing shape; the prompt
+convention. All of these are stated by the vendor or readable in the installed source.
+
+What I would **not** ship without a real GPU run: any `cost` entry (there is no number anywhere,
+and the schema forbids deriving one); `2048 × 2048` as the default resolution on a 24 GB card —
+the weight arithmetic (17.5 GB peak under model offload) leaves ~6 GB for a 16 384-token attention
+and I cannot size that from documents, so a first template should probably default to 1K and
+document 2K as the vendor's recommendation; anything about `sequential` offload or 4-bit, since no
+pre-quantized build exists and the text encoder doubles as the vision tower; and the RGBA→PNG save
+path.
+
+Two non-technical flags: the **Qwen Research License is non-commercial**, unlike every Apache-2.0
+sibling, and the repo has no convention yet for recording that. And `transformers` is **5.16.1**
+against a stated `>=5.17`.
+
+**On a skill**: the draft proposal reserved that question for Qwen-Image-Edit. In 2.1 editing is an
+argument, not a checkpoint, so the shape-picking a skill would do collapses to "is there an input
+image, and how many". That is template-selection, not a skill — *unless* the prompt convention
+(400–500 words, prescribed section order, verbatim text preservation) is judged worth a skill on
+its own, the way the LTX-2.5 caption spec was. That is a real argument, and it is the only one.
diff --git a/docs/proposals/output-assessment.md b/docs/proposals/output-assessment.md
new file mode 100644
index 00000000..44e6437b
--- /dev/null
+++ b/docs/proposals/output-assessment.md
@@ -0,0 +1,481 @@
+# Proposal: output assessment - let an agent measure, look at and listen to what it made
+
+Status: proposed, 2026-09-20. Scopes issue #193 (agent has no way to hear or
+watch generated output), folding in #210 (no `VideoContent` in the MCP SDK)
+and the per-segment `analyze_cut` proposal from #193's thread. Written from
+a design conversation with Don, every section agreed; revised the same day
+after a review pass against the code (the *Review findings* section records
+what changed and why). No code changes yet.
+
+## The goal
+
+An agent that drives `dw` over MCP should be able to assess the quality of a
+generated deliverable and decide whether to redo or tweak it. Four use cases
+drive the design:
+
+1. **Lip-sync synchronisation** - is the speech where the mouth is.
+2. **Seam transitions** - is each join in a cut clean, in the audio and in
+   the picture.
+3. **Continuity between clips** - does shot B look like it belongs after
+   shot A.
+4. **Audio/video contextual alignment** - does the sound swell where the
+   picture does; does the score reach its climax with the cut.
+
+Today the agent has `get_output_image` (stills only), `get_output_audio`
+(audio only, refuses `video/mp4`), `get_gallery_metadata` (whole-file
+duration/level, `envelope=true` for second-by-second rms/peak keyed to time
+rather than to shots), `analyze_audio` (whole-track), `transcribe_audio`,
+and `frame_grid` (#245 - a contact sheet, but only reachable by authoring a
+workflow; no MCP tool wraps it, and the `minimax-h3` skill still says "you
+cannot watch a video"). Nothing measures a seam, a drift, a continuity
+break or an alignment, and nothing gets a frame *pair* at a boundary into
+the agent's context. The issue's own motivating miss - a five-shot cut at
+exactly the right duration whose audio drifted 267 samples per shot and was
+33 ms late by the end - passed every check that exists.
+
+## Decisions taken (with Don, 2026-09-20)
+
+| Question | Decision |
+|---|---|
+| Where does judgement live? | **Tier 1: the engine measures, the agent judges.** Deterministic numbers plus evidence the agent can perceive (frames as `ImageContent`, audio excerpts). No ML judges in the engine. Tier 2 (CLIP/DINO similarity, SyncNet-class sync) and tier 3 (a VLM judge) are marked `TODO` where they would slot in, not built. |
+| How does the agent invoke a measurement? | **Both paths, one implementation.** Measurements are engine tasks (composable into a template's own self-check step, recorded in the manifest, cacheable) *and* run synchronously in the server process over an MCP tool for an output or asset, so a question about a finished file does not queue behind a 20-minute render. |
+| Where do shot boundaries come from? | **Persisted at join time, caller override.** The engine made the cut, so it records where the seams are; asking the agent to reconstruct that is the arithmetic that produced the 33 ms miss. |
+| Lip sync at tier 1? | **Drift only.** Per-shot and cumulative audio-vs-video offset. Onset-frame evidence and motion correlation were considered and deferred with SyncNet to tier 2 - too weak to be worth teaching. |
+| Who holds the thresholds? | **The engine emits `findings`** from one declared rules table, so an agent over bare MCP gets a place to look without the plugin; the skill teaches what to *do* about a finding. |
+| Surface shape | **Narrow probes plus one verdict call.** `assess_output` runs every applicable probe and returns findings plus a one-line summary per probe; `inspect_output(probe=...)` returns one probe's full body. Fat verdict, narrow detail. |
+| Are findings verdicts? | **No. The agent is the ultimate authority.** Nothing in the engine acts on a finding: no probe fails, no job fails, no template refuses to save, and `assess_output` never says pass or fail. A finding is a place to look. Severity is `info`/`warn` only - `error` was dropped because it reads like a verdict. |
+
+## Vocabulary
+
+The boundary list is called **`shots`** everywhere - on the artifact, in the
+manifest, in the file tag, as the probe argument. Not `segments`: that word
+already means chain *generation* segments throughout the engine
+(`SegmentedFrames`, `save_segments`, `chain.py`'s `Segment`), and a grep
+that finds both is a grep that finds neither. A **seam** is the boundary
+between two adjacent shots; seam *i* sits between shot *i* and shot *i+1*.
+
+## Section 1 - Probes (engine tasks, `dw/tasks/assess.py`)
+
+All CPU-only (numpy + PyAV), read-only: the frames and waveform pass through
+unmodified, and what comes back is diagnostics rather than an artifact, as
+`analyze_audio` does. Each takes a video or audio in any shape a result
+carries (a path, an `asset:`/`output:` reference, a `previous_result:`,
+a generated `AudioVideo`), an optional `shots` list (section 3), and
+returns `{...measurements, findings: [...], rules_applied: [...],
+shots_source: "argument" | "manifest" | "file" | "none"}`.
+
+**A probe over a path streams.** The existing loaders (`load_audio_video`,
+`load_audio`) materialise every frame as a PIL image - a four-minute 1080p
+clip is ~36 GB that way - and both route the track through
+`_fit_audio_to_frames`, which snaps audio to the frame count within
+`AUDIO_FIT_TOLERANCE_SECONDS` (0.25 s) and so *hides the very drift
+`analyze_sync_drift` exists to see*. So a probe given a path decodes in one
+`probe_media`-style pass (`dw/media_info.py`) that keeps only what the
+rules need: the waveform (~46 MB for four minutes of 48 kHz stereo), one
+motion scalar per frame, a fixed-size downsampled luma/Lab image per frame,
+the frame pair either side of each seam, and the container's own stream
+durations. A probe given an in-memory `AudioVideo` (the task-step path)
+reads those from the object it has. Nothing ever holds "the decoded file".
+
+| Probe | Answers | Measurements |
+|---|---|---|
+| `analyze_shots` | per-shot level - the "whole-file mean hides a 6.5 dB jump" case | per shot: `peak_dbfs`, `rms_dbfs`, `crest_db`, `low/mid/high_dbfs` (the `analyze_audio` numbers, per shot); `rms_range_db` across shots |
+| `analyze_seams` | is each join itself clean, in audio and in picture | per seam, audio: `level_step_db` (rms of the 250 ms either side), `floor_dbfs` (rms of the 20 ms centred on the join - the "seam floor"), `click_db` (peak of the 2 ms window at the join over the peak of its neighbours), `spectral_shift` (band-share change across the join). Video: `frame_delta` (mean absolute difference between the last frame of A and the first of B, both downsampled to a fixed size) and `typical_delta` (the *90th percentile* of inter-frame difference inside each shot, floored - a median is near zero on a static talking head and would flag every cut after one), reported as `jump_ratio` |
+| `analyze_sync_drift` | lip-sync drift (tier 1) | per shot: `offset_ms` at its start and end, read as `start_sample / rate - start_frame / fps` from the recorded boundaries, and `cumulative_ms`; whole file: `length_delta_ms` = the container's audio stream duration minus its video stream duration, *after subtracting the codec's declared priming* (AAC's 1024-sample block is 21 ms at 48 kHz and 43 ms at H3's 24 kHz - over the threshold on a clean file if left in). **TODO tier 2:** SyncNet / AV-HuBERT offset and confidence per shot |
+| `analyze_av_alignment` | does the sound swell where the picture does | the audio rms envelope and the video motion envelope (mean inter-frame difference), both at 4 Hz and normalised; `correlation` (Pearson, whole file and per shot), `audio_peak_s`, `motion_peak_s`, `peak_offset_s`, `cut_density` (seams per 10 s, when there are shots) against the audio envelope |
+| `analyze_continuity` | does shot B look like it belongs after shot A | for each adjacent pair, on the fixed-size downsampled frames: `color_distance` (Lab histogram distance, last frame of A vs first of B), `luma_step`, `sharpness_ratio` (Laplacian variance of B's first frame over A's last - catches "drift sharpening into noise late in a chain"; resolution- and quantisation-dependent, so only ever compared *within* one file, never against a constant). **TODO tier 2:** CLIP/DINO embedding similarity, face identity |
+
+`analyze_seams` and `analyze_continuity` both look at the boundary frames;
+the split is *cut hygiene* (is the join itself clean) versus *content* (does
+B belong after A), kept separate so a deliberate hard cut between two
+locations trips continuity and not seams.
+
+`analyze_sync_drift`'s per-shot `offset_ms` measures the *recorded*
+boundaries, so it is only as honest as the recording: section 3 requires
+`start_sample` to be read from the joined waveform's actual length at each
+seam, never derived from `start_frame / fps`, or the probe is a tautology.
+`length_delta_ms` is the one number read from the file itself and is what
+catches a file whose boundaries were never recorded.
+
+A dissolve's shot B starts at the first blended frame, and its seam is at
+`start_frame + overlap_frames / 2`; the seam probe widens its windows to
+the whole fade rather than measuring a step in the middle of one.
+
+`frame_grid` (#245) stays as it is - it is the evidence half of this.
+`analyze_audio` stays as the single-track probe and is on the `inspect`
+whitelist.
+
+**A probe step saves as JSON.** A dict result is written whole only under
+`content_type: application/json` (`Result.save`'s JSON branch); under any
+other type the dict branch explodes it per key and a scalar raises. The
+schema requires `application/json` on a step whose command is a probe, and
+`scalar_result_validation` refuses anything else.
+
+## Section 2 - Evidence tools (sight and sound into the agent's context)
+
+The tools that let an agent look at a flagged finding rather than trust the
+number. The MCP SDK has no `VideoContent` (#210); the ruling there stands:
+frames go back as `ImageContent`, sound as the existing audio path.
+
+- **`get_output_frames(name, at=None, seams=None, count=None,
+  max_dimension=512, workspace=None)`** - new MCP tool in `dw_mcp/media.py`
+  over `GET /api/gallery/{name:path}/frames`. Returns a list of images
+  (base64, the `get_output_image` shape) each labelled with its time and
+  frame index. Three selectors, mutually exclusive:
+  - `at: [seconds | "frame:N", ...]` - specific moments.
+  - `seams: true | [indices]` - for each seam, the last frame before and the
+    first frame after, composed into *one* side-by-side tile per seam with
+    the shot names burned in. This is the seam and continuity evidence in
+    one image.
+  - `count: N` - `frame_grid` reached without authoring a workflow: N evenly
+    spaced frames as one contact sheet.
+
+  Same `_encode_within_budget` path as `get_output_image`, capped at
+  `MAX_RETURNED_BYTES` across the whole call; over budget it halves the
+  dimension before it drops tiles, and the answer says which it did. The
+  server decodes with PyAV, seeking to each timestamp rather than reading the
+  clip through.
+
+- **`get_output_audio` becomes mux-aware and takes an excerpt.** It moves
+  from the raw `/outputs` mount to `GET /api/gallery/{name:path}/audio?start=&duration=`.
+  On `video/mp4` the server extracts the track and returns it as WAV. New
+  `start`/`duration` seconds pull the two seconds around seam 3 rather than
+  refusing a four-minute cut; the answer carries `excerpt: {start, duration,
+  of}` so it names itself as a cut (#204 objected to *silent* truncation).
+  **The whole-file refusal stays**: without `start`/`duration` a file over
+  `MAX_RETURNED_BYTES` base64 is refused exactly as today, and the refusal
+  now says to ask for an excerpt. An audio-only file under budget with no
+  excerpt asked for is returned as-is in its own encoding, not transcoded.
+
+- **`get_gallery_metadata`** gains `media.shots` (section 3), so the
+  existing `envelope` can be read against shot boundaries.
+
+## Section 3 - Boundary persistence
+
+Video files carry no embedded metadata today (only PNG/JPEG do; a video's
+`get_gallery_metadata` comes from job history via the manifest). Three
+layers, and a precedence:
+
+- **The artifact carries it.** `AudioVideo` and a plain frames result gain
+  an optional `shots` attribute: `[{name, start_frame, num_frames,
+  start_sample, num_samples, overlap_frames?, hard_cut?}]`.
+  - **Who populates it**: `concat_videos`, `dissolve_videos` and
+    `run_chain` (`dw/pipeline_processors/chain.py` - the other join in the
+    catalog, `templates/ltx2/chained-segments` and `extend-clip`, and the
+    place late-chain sharpening actually happens; it already knows every
+    seam from `Segment.head_trim` and `config.plan`).
+  - **`start_sample` is measured, not derived.** The join task records each
+    shot's `start_sample` from the length of the waveform it has actually
+    accumulated when the shot is appended, so a per-shot codec overrun is
+    *in* the record. This is what makes `analyze_sync_drift`'s `offset_ms`
+    a measurement.
+  - **Names are assigned in the workflow layer, not the task.** A task
+    receives resolved objects and can only name a shot by position
+    (`video_names` says "video 2"). `Workflow.run` renames the positional
+    entries from the step's pre-resolution `gather:` reference list, the
+    way `selected_field` already reads `step_data` - so a shot that came
+    through `gather:shot` is `shot@intro`, and a finding says "between
+    `shot@intro` and `shot@chase`" rather than "seam 2". A shot with no
+    such origin keeps its index as its name.
+  - **Every `AudioVideo(` constructor has a stated rule**, and a test fails
+    when a new constructor appears without one:
+
+    | Constructor | Rule |
+    |---|---|
+    | `concat_videos`, `dissolve_videos`, `run_chain` | *populate* |
+    | `pair_audio` | frame side survives; `start_sample`/`num_samples` recomputed from the new track's rate, and with `fit: "video"` the last shot's `num_samples` is re-measured |
+    | `interpolate_frames` | frame fields rescaled by the frame multiplier; sample fields unchanged |
+    | `stabilize`, `loop_frames` (same frame count) | carried through unchanged |
+    | `slice_audio`, `trim_*`, anything returning an `AudioTrack` or a different frame count | *dropped* - there are no frames to carry a boundary on, or the timeline changed |
+    | `result.py`, `task.py`, `video_utils.py` wrappers | carried through unchanged |
+- **The manifest records it.** The manifest entry grows `shots` beside
+  `subfolder` when the artifact has them; `get_job`, `get_gallery_metadata`
+  (`media.shots`) and the server-side probes read it from there. The
+  realized `workflow.json` is untouched.
+- **The file keeps it - by a remux pass after the write.** `result.py`
+  does not own the container: `encode_video` and `export_to_video` are
+  diffusers' (`diffusers.utils`), and neither takes metadata. So after
+  either has written an mp4 whose artifact has `shots`, `result.py` opens
+  the file, copies its packets to a sibling with
+  `container.metadata["comment"] = json.dumps({"dw": {"shots": [...]}})`,
+  and replaces it. The chain's spilled `SegmentedFrames` path gets the same
+  pass. The tag round-trips through PyAV and survives `os.link`, so
+  `keep_output` (a hard link), `upload_asset` and a pruned run directory
+  all keep it, and `analyze_seams` on an `asset:` still knows the cut.
+  `read_embedded_metadata` dispatches on extension before it reaches PIL;
+  the metadata route folds the tag read into `probe_media` so a video is
+  opened once per call, not twice.
+- **Precedence** in every probe: the caller's `shots` argument > manifest
+  > file tag > none. With none, the per-shot probes answer over one shot
+  with `shots_source: "none"`, and `analyze_seams` reports zero seams - an
+  answer, not an error.
+
+`hard_cut` is a per-shot flag a template may set on an entry (a cut
+between two locations by design), which suppresses `seam_frame_jump` for
+that boundary. `concat_videos` gains a `hard_cuts` argument naming entries;
+nothing sets it by default.
+
+## Section 4 - Rules and `findings`
+
+One table, `dw/assessment_rules.py`, in the `dw/task_domains.py` style: each
+rule is `{name, probe, field, comparator, threshold, severity, says}`, and
+`tests/test_assessment_rules.py` pins every rule to a real field of the
+real probe's answer so a rename cannot leave one checking nothing. The
+module docstring states the authority rule: **these are places to look, not
+verdicts; nothing in the engine acts on a finding.** Starting thresholds,
+each tunable in that one place:
+
+| rule | probe / field | flags when | severity |
+|---|---|---|---|
+| `shot_level_spread` | `analyze_shots.rms_range_db` | > 3 dB | warn |
+| `seam_level_step` | `analyze_seams.level_step_db` | > 3 dB | warn |
+| `seam_click` | `analyze_seams.click_db` | > 12 dB | warn |
+| `seam_hole` | `analyze_seams.floor_dbfs` | < −50 dBFS while both sides > −30 | warn |
+| `seam_frame_jump` | `analyze_seams.jump_ratio` | > 8, unless the boundary is `hard_cut` | info |
+| `sync_drift` | `analyze_sync_drift.offset_ms` at any shot end | > 40 ms | warn |
+| `sync_length` | `analyze_sync_drift.length_delta_ms` (priming already subtracted) | > 40 ms | warn |
+| `av_peak_offset` | `analyze_av_alignment.peak_offset_s` | > 2 s | info |
+| `continuity_color` | `analyze_continuity.color_distance` | > 0.25 (normalised) | warn |
+| `continuity_sharpness` | `analyze_continuity.sharpness_ratio` | < 0.5 or > 2 | warn |
+
+`av_correlation` is **measured but has no rule yet**: on a 20 s five-shot
+clip the 4 Hz envelopes are 80 samples, motion is per-cut and audio is
+continuous, so a threshold set before the stage-4 field test would be a
+coin flip. The number is reported; the rule lands from lem data.
+
+A finding:
+
+```json
+{
+  "rule": "seam_level_step",
+  "severity": "warn",
+  "at": {"seam": 2, "between": ["shot@intro", "shot@chase"], "seconds": 10.33},
+  "value": 4.2,
+  "threshold": 3.0,
+  "says": "level steps 4.2 dB up across the join"
+}
+```
+
+Findings are a new shape that *reads like* `job.warnings` (run-time warnings
+carry a `kind`, not a severity); `severity` is `info` / `warn` only. Every
+probe answer ends with `rules_applied` so an agent that got no findings
+knows what *was* checked; `assess_output` adds `not_applicable: {probe:
+why}` (no audio track, no shots, a still).
+
+## Section 5 - API and MCP surface, and where the code runs
+
+**Engine** - `dw/tasks/assess.py`, `dw/assessment_rules.py`. The five
+probes are ordinary task commands, so a workflow can wire one as a
+self-check step (by convention `intermediate`, `content_type:
+application/json`) and its answer lands in the manifest. CPU-only; no torch
+model is loaded.
+
+**Server** - `dw/server/assess.py`, routes in `dw/server/app.py`, in the
+existing `{name:path}/metadata|thumbnail|download` family:
+
+- `GET /api/gallery/{name:path}/assess?detail=false` - runs every
+  applicable probe *in the server process* (a sync `def`, so FastAPI runs
+  it in the threadpool the way `metadata?envelope=true` runs today; the
+  worker and its queue are never involved) and answers `{probes: {name:
+  summary}, findings, not_applicable, shots_source}`; `detail=true`
+  includes each probe's full body.
+- `GET /api/gallery/{name:path}/inspect?probe=analyze_seams&...` - one
+  probe's full body. `probe` is checked against the whitelist (the five
+  probes plus `analyze_audio`) *before* any other query parameter is looked
+  at, and only that probe's declared arguments are forwarded - a query
+  string never reaches a task signature unfiltered. Anything else is a 400
+  naming the list.
+- `GET /api/gallery/{name:path}/frames?at=|seams=|count=&max_dimension=` -
+  JSON list of base64 PNG tiles with labels.
+- `GET /api/gallery/{name:path}/audio?start=&duration=` - mux-aware, WAV
+  for an excerpt or an extracted track, the file's own bytes otherwise.
+- All four accept an `asset:` name the way `metadata` does (#127), and
+  `workspace`. Paths go through `validate_output_path` / the asset resolver
+  as every other route does.
+- One request, one streaming pass: `assess` decodes the file once and hands
+  the reduced per-frame/per-sample data to every probe. Nothing is held
+  across requests.
+
+**MCP** - `dw_mcp/assess.py`, wired in `server.py`: `assess_output(name,
+detail=False, workspace=None)`, `inspect_output(name, probe, workspace=None,
+**arguments)`, `get_output_frames(...)`, and the widened `get_output_audio`.
+None needs `acknowledged_cost` - nothing here spends GPU minutes.
+`assess_output`'s description carries the authority rule in one sentence.
+
+**Web UI** - reads the fields only: the job page lists a probe step's
+findings under its result the way it lists warnings. Nothing else in the
+first cut.
+
+## Section 6 - Skill and discovery
+
+### One skill, family-agnostic: `dw:judging-output`
+
+A new plugin skill in `plugins/dw/skills/judging-output/`, named in
+backticks in `plugins/dw/README.md` and `CLAUDE.md` as
+`tests/test_plugin_skills.py` requires. It is the *procedure* for the
+redo-or-tweak loop, and it is one skill rather than a section in each
+family's because the loop is the same for an H3 cut and an LTX chain, and
+because `minimax-h3` (12284 of 12288 bytes) and `ltx-2.5` (12254) cannot
+absorb it.
+
+Trigger line: use when a dw run has finished and the user wants to know
+whether it is good, or when a family skill's "run and judge" step hands off
+here.
+
+Body, in order:
+
+1. **Look before measuring**: `get_output_frames(count=12)` for the shape,
+   `get_output_audio(start, duration)` around anything you mean to judge;
+   what you can see and hear outranks any number below.
+2. **Then `assess_output`**, and read the findings as places to look, not
+   verdicts. One paragraph on each rule family: what the number is, what
+   usually caused it in this catalog, and what it looks like when it is
+   *fine* (a hard cut trips `seam_frame_jump`; a whispered line trips
+   `shot_level_spread`).
+3. **Drill down with `inspect_output(probe=...)` and
+   `get_output_frames(seams=[n])`** on a flagged finding.
+4. **Remediation table** - the part only the skill can hold, because it
+   names template variables: a `seam_level_step` on an H3 cut →
+   `match_levels_dbfs`; a `seam_hole` → `audio_bleed_ms`; a `sync_drift`
+   → the #197 class, re-run through `pair_audio` `fit`; a
+   `continuity_color` between two shots → regenerate B with A's last frame
+   (`chain-video-continuity`) or the shared cast asset; `av_peak_offset` on
+   a music video → re-slice the score (`start_frame`) or recut; a
+   `continuity_sharpness` late in a chain → shorten the chain or reseed the
+   drifting shot. Each row says whether the fix is a *recut* (cheap: the
+   shots exist, `output:` them) or a *regenerate* (a new run, quote the
+   cost).
+5. **Recut, don't regenerate, when you can**: the `series-episodes` recipe
+   for `output:`-referencing a run's `intermediate/` shots.
+6. What tier 1 cannot tell you (identity across shots, whether the mouth
+   matches the words) and that the frames are the way to check those - the
+   honest limit, stated once.
+
+The family skills' "run and judge" steps shrink to a pointer: `minimax-h3`
+step 4 ("You cannot watch a video", ~700 bytes) is replaced by a shorter
+step naming `get_output_frames` and handing off to `dw:judging-output` -
+the replacement is budgeted to be shorter than what it replaces, since the
+skill has four bytes of headroom; `series-episodes` "watch two episodes
+back to back" points at the same place; `ltx-2.5` likewise. The
+thresholds the new skill quotes are pinned to `dw/assessment_rules.py` by a
+new test in the `test_plugin_skills.py` style (that file's existing pins are
+to diffusers symbols; this is the same pattern against a different table).
+
+### How the capability reaches an agent without the plugin
+
+Three layers, each already the way this repo communicates a capability:
+
+- **Tool descriptions** (`dw_mcp/server.py` docstrings) are the only thing
+  a bare MCP client reads. `assess_output`'s says what it checks, that the
+  findings are places to look, and that `inspect_output`, `get_output_frames`
+  and `get_output_audio` are the drill-down. `get_gallery_metadata`'s
+  description and its existing `next` hint point at `assess_output` for a
+  cut ("whole-file numbers cannot see inside a join"). No hint is added to
+  `get_job` - it has none today and #101's budget applies to every job
+  read.
+- **The guide** (`docs/WORKFLOW_GUIDE.md`, read over `get_guide`) gains a
+  `## Assessing a run's output` section (top-level headings are what
+  `list_guides` indexes), holding the probe table, the findings shape and
+  the authority rule - so an agent told "check the seams" can look the
+  mechanism up rather than guess at it.
+- **The task catalog** (`list_tasks` / `get_task`): each probe's docstring
+  is its `get_task` description. `list_tasks` has no categories today (three
+  flat lists from `dw/introspection.py`, consumed by the web UI editor), so
+  the five probes are listed under a new fourth list, `assessment`, rather
+  than tagged - a new field the editor can ignore. `docs/TASKS.md` gets one
+  `### <probe>` section each, as `analyze_audio` has.
+
+The MCP server's own instructions block (the text in `dw_mcp/server.py` that
+a client shows at connect) gains one sentence in the loop description:
+"after a run, `assess_output` measures the deliverable and returns places to
+look; `get_output_frames` and `get_output_audio` let you look and listen."
+
+## Section 7 - Testing
+
+- **Synthetic media, no models.** Every probe is tested on clips built in
+  the test (numpy frames + a synthesised tone), the way `test_video_utils.py`
+  tests `frame_grid`: a cut with a known 6 dB step at seam 2 must flag
+  `seam_level_step` at seam 2 and nowhere else; a track padded by 267 samples
+  per shot must report the drift the issue measured; a dissolve must not
+  flag a step; a `hard_cut` boundary must not flag a jump; a static shot
+  followed by a cut must not flag `seam_frame_jump` on the 90th-percentile
+  baseline. Stage 3's tests pass `shots` as the argument, so they land
+  without stage 2.
+- **The rules table is pinned** (`tests/test_assessment_rules.py`): every
+  rule names a field the probe actually returns; every threshold in the
+  skill's prose matches the table.
+- **Every `AudioVideo(` constructor has a rule**: a test enumerates the
+  constructor sites and fails on one the table in section 3 does not name.
+- **Boundary persistence round-trips**: `concat_videos` → save → manifest
+  entry → `read_embedded_metadata` on the remuxed mp4 → the same list;
+  `keep_output` keeps it; `pair_audio` recomputes the sample fields; a
+  `slice_audio` drops it. `start_sample` on a synthetic cut whose shots
+  each overrun by 267 samples records the overrun.
+- **Memory**: `assess` on a long synthetic clip holds no per-frame image
+  list (assert on peak RSS or on the streaming reader never being asked for
+  a full frame list).
+- **Budget**: `get_output_frames` on a 4K clip lands under
+  `MAX_RETURNED_BYTES` and says it halved the dimension.
+- **Routes**: the four `/api/gallery/{name}/...` routes refuse a traversal,
+  answer 400 for an unknown probe naming the whitelist, forward only a
+  probe's declared arguments, and accept an `asset:` name.
+- **Field test on lem**: `assess_output` over MCP on an existing
+  `music-video` and `dialogue-short` run, a `chained-segments` run, and the
+  #197 repro cut, before the skill's threshold prose is finalised and before
+  `av_correlation` gets a rule - the starting thresholds above are guesses
+  until they have met real output.
+
+## Not in scope
+
+- Any model-based judge (tiers 2 and 3) - each `TODO` in section 1 is the
+  slot.
+- Automatic remediation: no template re-runs itself on a finding.
+- `score-and-select` wiring: a probe's numbers are exactly what that
+  proposal's reducer would read, but that proposal stands on its own.
+- Web UI beyond listing findings.
+- Findings on stills (composition, artifacts) - a different problem with a
+  different evidence tool already in place (`get_output_image`).
+
+## Staging
+
+Four independently landable pieces, each its own branch off `develop`:
+
+1. **Evidence**: mux-aware `get_output_audio` with excerpts;
+   `get_output_frames` and its route. Closes the perceptual half of #193
+   on its own.
+2. **Boundaries**: `shots` on the artifact (every constructor ruled), the
+   manifest, the remux tag; `media.shots` in metadata; the workflow-layer
+   rename from `gather:`.
+3. **Probes and rules**: the five tasks, the streaming reader, the table,
+   `assess` / `inspect` routes and tools; guide section; `list_tasks`
+   fourth list. Tests use the `shots` argument; a probe on a file with no
+   boundaries answers `shots_source: "none"`.
+4. **Skill**: `dw:judging-output`, the family-skill rewrites, the field
+   test that sets the thresholds and decides `av_correlation`'s rule.
+
+Release note items: `get_output_audio` no longer refuses `video/mp4` and
+moved off the `/outputs` mount; manifest entries and mp4 files carry
+`shots`; `list_tasks` has a fourth list; `minimax-h3` step 4 is rewritten.
+
+## Review findings (2026-09-20)
+
+A review pass against the code changed the design in these ways:
+
+- `result.py` does not own the mp4 container (diffusers' `encode_video` /
+  `export_to_video` write it), so the file tag is written by a post-write
+  remux pass, not "at mux time".
+- The existing loaders materialise every frame and snap audio to the frame
+  count within 0.25 s, so probes stream and `analyze_sync_drift` reads
+  stream durations from the container.
+- A task cannot see `for_each` names; the workflow layer assigns them from
+  the `gather:` reference list.
+- `start_sample` must be measured from the accumulated waveform or the
+  drift probe measures its own record.
+- `run_chain` is the other join and populates `shots`; every `AudioVideo(`
+  constructor has an enumerated rule.
+- `segments` renamed `shots` to keep clear of chain segments.
+- `sync_length` subtracts codec priming (43 ms at 24 kHz); `jump_ratio`
+  uses a 90th-percentile floored baseline; `av_correlation` has no rule
+  until lem data; `get_output_audio` keeps its whole-file refusal; probe
+  steps require `application/json`; `list_tasks` gets a fourth list rather
+  than a tag; no `next` hint on `get_job`.
diff --git a/docs/proposals/qwen-image-wan-onboarding.md b/docs/proposals/qwen-image-wan-onboarding.md
index f351062f..8e04f272 100644
--- a/docs/proposals/qwen-image-wan-onboarding.md
+++ b/docs/proposals/qwen-image-wan-onboarding.md
@@ -2,6 +2,14 @@
 
 Status: draft, 2026-09-08. No implementation.
 
+**Note (2026-09-20):** this proposal is about the older, larger, Apache-2.0
+20B `Qwen/Qwen-Image` line. A separate, newer, non-commercial 7B model,
+`Qwen/Qwen-Image-2.1`, released 2026-09-20 and was onboarded on its own —
+see `docs/proposals/audits/2026-09-20-qwen-image-2.1-audit.md` and
+`workflows/models/qwen-image-2.1.json`. The two do not supersede one another:
+they coexist under different licenses. This draft's scope (20B Qwen-Image
+and Wan2.x) is still open.
+
 ## Why these two
 
 Neither has a template under `workflows/models/`. Both rank among the most
diff --git a/docs/superpowers/plans/2026-09-20-output-assessment-stage-1-evidence.md b/docs/superpowers/plans/2026-09-20-output-assessment-stage-1-evidence.md
new file mode 100644
index 00000000..98c7207e
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-20-output-assessment-stage-1-evidence.md
@@ -0,0 +1,1784 @@
+# Output Assessment, Stage 1 (Evidence) 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:** Let an MCP agent hear a generated video's soundtrack (or an excerpt of any track) and see frames from a generated video - the perceptual half of #193 - without any new engine task.
+
+**Architecture:** Two small PyAV-only modules beside `dw/media_info.py` (`dw/media_audio.py` extracts a WAV excerpt, `dw/media_frames.py` seeks out frames and composes tiles), two new gallery routes in `dw/server/app.py` in the existing `{name:path}/metadata` family, and on the MCP side `get_output_audio` moves to the new audio route and gains `start`/`duration`, and a new `get_output_frames` tool returns `ImageContent` tiles. Nothing touches the worker or the queue; everything runs in the server process like `metadata?envelope=true`.
+
+**Tech Stack:** Python 3.11, FastAPI, PyAV 18 (`av`), numpy, Pillow, httpx MockTransport for MCP tests, pytest via `venv/bin/python -m pytest`.
+
+**Spec:** `docs/proposals/output-assessment.md` - sections 2 and 5 are what this stage implements; section 3's `shots` (boundaries) is stage 2, so in this stage seam tiles take the boundaries as an explicit argument and nothing reads a manifest.
+
+## Global Constraints
+
+- Inline payloads are capped at `MAX_RETURNED_BYTES` (4 MB base64) in `dw_mcp/media.py`; a whole file over it is refused, never truncated, and the refusal names the excerpt path (spec section 2).
+- An excerpt names itself: the answer carries `excerpt: {start, duration, of}`.
+- New routes accept an `asset:` name the way `metadata` does (#127), and `workspace`.
+- Every path reaches the disk through `_output_file` / `_asset_file` (`validate_path` inside) - never a bare `os.path.join` (CLAUDE.md, Security Rules; CodeQL models these as sanitizers).
+- `dw_mcp/` must not import `dw.*` (a test guards that boundary).
+- Tool count is pinned: `docs/MCP.md` line ~190 says how many tools; `tests/test_mcp_server.py::test_the_stated_tool_count_is_the_registered_one` compares it to `EXPECTED_TOOLS`.
+- Commit messages: `feat(mcp): #193 - ...` / `feat(server): #193 - ...`, ending with the attribution line the session reminder gives.
+- Run tests with `venv/bin/python -m pytest` (torch is present in that venv).
+- Branch: `feat/193-evidence` off `develop`.
+
+---
+
+### Task 1: `dw/media_audio.py` - a WAV excerpt of any file's soundtrack
+
+**Files:**
+- Create: `dw/media_audio.py`
+- Test: `tests/test_media_audio.py`
+
+**Interfaces:**
+- Consumes: `tests/test_media_info.py::write_mp4(path, frames, fps, width, height, with_audio)` and `write_wav(path, seconds, sample_rate, amplitude)` fixtures (8 kHz stereo, 220 Hz tone).
+- Produces: `extract_audio(path, start=None, duration=None) -> (bytes, dict)` - 16-bit PCM WAV bytes and `{"sample_rate": int, "channels": int, "duration_seconds": float, "of_seconds": float, "start": float, "excerpt": bool}`. Raises `NoSoundtrack` (subclass of `ValueError`) when the file has no audio stream, and `ValueError` when `start` is past the end or `duration <= 0`.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/test_media_audio.py
+"""extract_audio hands back a soundtrack, or a named slice of one, as WAV -
+what get_output_audio needs for a muxed video and for a track too long to
+send whole."""
+
+import io
+import wave
+
+import numpy
+import pytest
+
+from dw.media_audio import NoSoundtrack, extract_audio
+from tests.test_media_info import write_mp4, write_wav
+
+
+def read_wav(data):
+    with wave.open(io.BytesIO(data)) as handle:
+        frames = handle.readframes(handle.getnframes())
+        samples = numpy.frombuffer(frames, dtype="<i2").reshape(
+            -1, handle.getnchannels()
+        )
+        return handle.getframerate(), samples
+
+
+def test_a_video_soundtrack_comes_back_whole_as_wav(tmp_path):
+    write_mp4(tmp_path / "shot.mp4", frames=12, fps=6)  # 2 s of tone at 8 kHz
+
+    data, info = extract_audio(str(tmp_path / "shot.mp4"))
+
+    rate, samples = read_wav(data)
+    assert rate == 8000
+    assert samples.shape[1] == 2
+    assert info["channels"] == 2
+    assert info["sample_rate"] == 8000
+    assert info["excerpt"] is False
+    assert info["of_seconds"] == pytest.approx(2.0, abs=0.1)
+    assert info["duration_seconds"] == pytest.approx(info["of_seconds"], abs=0.05)
+    # the tone is there, not silence
+    assert numpy.abs(samples).max() > 1000
+
+
+def test_an_excerpt_is_cut_where_asked_and_says_so(tmp_path):
+    write_wav(tmp_path / "score.wav", seconds=4.0)
+
+    data, info = extract_audio(str(tmp_path / "score.wav"), start=1.0, duration=0.5)
+
+    rate, samples = read_wav(data)
+    assert samples.shape[0] == pytest.approx(0.5 * rate, abs=rate * 0.02)
+    assert info["excerpt"] is True
+    assert info["start"] == 1.0
+    assert info["duration_seconds"] == pytest.approx(0.5, abs=0.02)
+    assert info["of_seconds"] == pytest.approx(4.0, abs=0.05)
+
+
+def test_an_excerpt_past_the_end_is_clipped_to_it(tmp_path):
+    write_wav(tmp_path / "score.wav", seconds=2.0)
+
+    data, info = extract_audio(str(tmp_path / "score.wav"), start=1.5, duration=5.0)
+
+    rate, samples = read_wav(data)
+    assert samples.shape[0] == pytest.approx(0.5 * rate, abs=rate * 0.02)
+    assert info["duration_seconds"] == pytest.approx(0.5, abs=0.02)
+
+
+def test_a_start_past_the_end_is_refused(tmp_path):
+    write_wav(tmp_path / "score.wav", seconds=2.0)
+
+    with pytest.raises(ValueError, match="past the end"):
+        extract_audio(str(tmp_path / "score.wav"), start=3.0, duration=1.0)
+
+
+def test_a_non_positive_duration_is_refused(tmp_path):
+    write_wav(tmp_path / "score.wav", seconds=2.0)
+
+    with pytest.raises(ValueError, match="duration"):
+        extract_audio(str(tmp_path / "score.wav"), start=0.0, duration=0.0)
+
+
+def test_a_silent_video_has_no_soundtrack(tmp_path):
+    write_mp4(tmp_path / "mute.mp4", frames=6, fps=6, with_audio=False)
+
+    with pytest.raises(NoSoundtrack):
+        extract_audio(str(tmp_path / "mute.mp4"))
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `venv/bin/python -m pytest tests/test_media_audio.py -v`
+Expected: FAIL with `ModuleNotFoundError: No module named 'dw.media_audio'`
+
+- [ ] **Step 3: Write the module**
+
+```python
+# dw/media_audio.py
+"""A soundtrack, or a named slice of one, as WAV bytes - the form
+get_output_audio hands an agent for a muxed video (whose container it
+cannot play) or for a track too long to send whole (#193).
+
+PyAV only, like media_info: this runs in the server process, where a
+request must not pull in torch or materialise frames.
+"""
+
+import io
+import logging
+import wave
+
+import av
+import numpy
+from av.audio.resampler import AudioResampler
+
+logger = logging.getLogger("dw")
+
+
+class NoSoundtrack(ValueError):
+    """The file has no audio stream to extract."""
+
+
+def extract_audio(path, start=None, duration=None):
+    """The soundtrack of `path` as 16-bit PCM WAV bytes, plus what was cut.
+
+    With `start` and `duration` (seconds) only that slice is decoded and
+    returned; the info dict says so (`excerpt: True`) and carries the whole
+    track's length as `of_seconds`, so a slice always names itself. A
+    slice that runs past the end is clipped to it; a `start` past the end
+    is refused, since an empty answer would read as a silent track.
+
+    Returns:
+        (wav_bytes, info) with info = {sample_rate, channels,
+        duration_seconds, of_seconds, start, excerpt}
+    """
+    excerpt = start is not None or duration is not None
+    start = float(start or 0.0)
+    if excerpt and (duration is None or float(duration) <= 0):
+        raise ValueError("An excerpt needs a duration above zero")
+    if start < 0:
+        raise ValueError("An excerpt cannot start before zero")
+
+    with av.open(path) as container:
+        if not container.streams.audio:
+            raise NoSoundtrack(f"{path} has no soundtrack")
+        stream = container.streams.audio[0]
+        total = (
+            float(container.duration / av.time_base)
+            if container.duration is not None
+            else None
+        )
+        if total is not None and start >= total:
+            raise ValueError(
+                f"start {start:.2f}s is past the end of a {total:.2f}s track"
+            )
+        stop = start + float(duration) if excerpt else None
+        if stop is not None and total is not None:
+            stop = min(stop, total)
+
+        rate = int(stream.rate)
+        channels = int(stream.channels)
+        layout = (
+            "stereo"
+            if channels == 2
+            else ("mono" if channels == 1 else stream.layout.name)
+        )
+        resampler = AudioResampler(format="s16", layout=layout, rate=rate)
+
+        if start > 0:
+            # Seek to the keyframe at or before `start`; the frames decoded
+            # before `start` are then dropped sample-accurately below
+            container.seek(int(start / stream.time_base), stream=stream, backward=True)
+
+        pieces = []
+        seen = 0  # samples of the track before the current frame
+        started = False
+        for frame in container.decode(stream):
+            frame_start = (
+                float(frame.pts * stream.time_base)
+                if frame.pts is not None
+                else seen / rate
+            )
+            for chunk in resampler.resample(frame):
+                samples = chunk.to_ndarray()  # (1, samples * channels) packed s16
+                samples = samples.reshape(-1, channels)
+                chunk_start = frame_start
+                chunk_end = chunk_start + samples.shape[0] / rate
+                if chunk_end <= start:
+                    seen += samples.shape[0]
+                    continue
+                if not started and chunk_start < start:
+                    samples = samples[int((start - chunk_start) * rate) :]
+                    chunk_start = start
+                started = True
+                if stop is not None and chunk_end > stop:
+                    samples = samples[: max(0, int((stop - chunk_start) * rate))]
+                pieces.append(samples)
+                if stop is not None and chunk_end >= stop:
+                    break
+        # flush the resampler
+        if stop is None:
+            for chunk in resampler.resample(None):
+                pieces.append(chunk.to_ndarray().reshape(-1, channels))
+
+    pcm = numpy.concatenate(pieces) if pieces else numpy.zeros((0, channels), "<i2")
+    buffer = io.BytesIO()
+    with wave.open(buffer, "w") as handle:
+        handle.setnchannels(channels)
+        handle.setsampwidth(2)
+        handle.setframerate(rate)
+        handle.writeframes(pcm.astype("<i2").tobytes())
+
+    returned = pcm.shape[0] / rate
+    return buffer.getvalue(), {
+        "sample_rate": rate,
+        "channels": channels,
+        "duration_seconds": returned,
+        "of_seconds": total if total is not None else returned,
+        "start": start,
+        "excerpt": excerpt,
+    }
+```
+
+- [ ] **Step 4: Run the tests until they pass**
+
+Run: `venv/bin/python -m pytest tests/test_media_audio.py -v`
+Expected: PASS (6 tests). If the AAC fixture's `of_seconds` is a hair over 2.0 from codec padding, the `abs=0.1` tolerance covers it; do not loosen further - a wide tolerance would hide a broken cut.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/media_audio.py tests/test_media_audio.py
+git commit -m "feat(server): #193 - extract_audio, a WAV excerpt of any file's soundtrack"
+```
+
+---
+
+### Task 2: `GET /api/gallery/{name}/audio` - the soundtrack route
+
+**Files:**
+- Modify: `dw/server/app.py` (after `gallery_metadata`, ~line 2810; import beside `from ..media_info import probe_media` at line 74)
+- Test: `tests/test_server.py` (beside `test_gallery_metadata_describes_audio_and_video`, ~line 1250, and the asset tests ~line 4534)
+
+**Interfaces:**
+- Consumes: `extract_audio`, `NoSoundtrack` from Task 1; `_output_file(name, root)`, `_asset_file(reference, ws)`, `is_asset_reference`, `MEDIA_KINDS`, `selected_workspace` already in `app.py`.
+- Produces: the route. Response is `audio/wav` bytes with headers `X-DW-Duration` (the whole track, seconds), and when an excerpt was asked for `X-DW-Excerpt-Start`, `X-DW-Excerpt-Duration`. An audio-only file asked for whole is served as its own bytes with its own content type (no transcode) and only `X-DW-Duration`. 404 when the file has no soundtrack; 400 when `start`/`duration` are bad.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/test_server.py - add near test_gallery_metadata_describes_audio_and_video
+
+
+def test_gallery_audio_extracts_a_videos_soundtrack(server, tmp_path):
+    """get_output_audio refused video/mp4 outright, so a generated clip's
+    soundtrack could only be heard by fetching the file and demuxing it by
+    hand (#193). The route hands the track back as WAV."""
+    import io
+    import wave
+    from tests.test_media_info import write_mp4
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        write_mp4(outputs / "shot-gen.0-0.0.mp4", frames=12, fps=6)
+
+        response = client.get("/api/gallery/shot-gen.0-0.0.mp4/audio")
+
+        assert response.status_code == 200
+        assert response.headers["content-type"] == "audio/wav"
+        assert float(response.headers["x-dw-duration"]) == pytest.approx(2.0, abs=0.1)
+        assert "x-dw-excerpt-start" not in response.headers
+        with wave.open(io.BytesIO(response.content)) as handle:
+            assert handle.getframerate() == 8000
+            assert handle.getnchannels() == 2
+
+
+def test_gallery_audio_serves_an_audio_file_as_itself_when_asked_whole(
+    server, tmp_path
+):
+    from tests.test_media_info import write_wav
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        write_wav(outputs / "score-gen.0-0.0.wav", seconds=1.0)
+        raw = (outputs / "score-gen.0-0.0.wav").read_bytes()
+
+        response = client.get("/api/gallery/score-gen.0-0.0.wav/audio")
+
+        assert response.status_code == 200
+        assert response.content == raw
+        assert float(response.headers["x-dw-duration"]) == pytest.approx(1.0, abs=0.05)
+
+
+def test_gallery_audio_cuts_an_excerpt_and_names_it(server, tmp_path):
+    import io
+    import wave
+    from tests.test_media_info import write_wav
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        write_wav(outputs / "score-gen.0-0.0.wav", seconds=4.0)
+
+        response = client.get(
+            "/api/gallery/score-gen.0-0.0.wav/audio",
+            params={"start": 1.0, "duration": 0.5},
+        )
+
+        assert response.status_code == 200
+        assert response.headers["content-type"] == "audio/wav"
+        assert response.headers["x-dw-excerpt-start"] == "1.0"
+        assert float(response.headers["x-dw-excerpt-duration"]) == pytest.approx(
+            0.5, abs=0.02
+        )
+        assert float(response.headers["x-dw-duration"]) == pytest.approx(4.0, abs=0.05)
+        with wave.open(io.BytesIO(response.content)) as handle:
+            assert handle.getnframes() == pytest.approx(4000, abs=100)
+
+
+def test_gallery_audio_refuses_a_bad_excerpt_and_a_mute_file(server, tmp_path):
+    from tests.test_media_info import write_mp4, write_wav
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        write_wav(outputs / "score-gen.0-0.0.wav", seconds=2.0)
+        write_mp4(outputs / "mute-gen.0-0.0.mp4", frames=6, fps=6, with_audio=False)
+
+        past = client.get(
+            "/api/gallery/score-gen.0-0.0.wav/audio",
+            params={"start": 5.0, "duration": 1.0},
+        )
+        assert past.status_code == 400
+        assert "past the end" in past.json()["detail"]
+
+        mute = client.get("/api/gallery/mute-gen.0-0.0.mp4/audio")
+        assert mute.status_code == 404
+        assert "soundtrack" in mute.json()["detail"]
+
+        still = client.get("/api/gallery/missing.png/audio")
+        assert still.status_code == 404
+
+
+def test_gallery_audio_reads_an_asset_reference(asset_server, tmp_path):
+    from tests.test_media_info import write_wav
+
+    with asset_server(success_script) as client:
+        write_wav(tmp_path / "assets" / "bed.wav", seconds=1.0)
+
+        response = client.get(
+            "/api/gallery/asset:bed.wav/audio", params={"start": 0.0, "duration": 0.25}
+        )
+
+        assert response.status_code == 200
+        assert float(response.headers["x-dw-excerpt-duration"]) == pytest.approx(
+            0.25, abs=0.02
+        )
+```
+
+Check how `asset_server` lays out its assets directory before relying on `tmp_path / "assets"`: read `test_gallery_metadata_reads_an_asset_reference` (~line 4534) and copy its setup exactly.
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `venv/bin/python -m pytest tests/test_server.py -k gallery_audio -v`
+Expected: FAIL with 404s (route does not exist; FastAPI answers "Not Found").
+
+- [ ] **Step 3: Add the route**
+
+Add the import at line 74:
+
+```python
+from ..media_info import probe_media
+from ..media_audio import NoSoundtrack, extract_audio
+```
+
+Add after `gallery_metadata`:
+
+```python
+    @app.get("/api/gallery/{name:path}/audio")
+    def gallery_audio(
+        name: str,
+        start: Optional[float] = None,
+        duration: Optional[float] = None,
+        ws: Workspace = Depends(selected_workspace),
+    ):
+        """The soundtrack of an output or asset, as WAV - a muxed video's
+        track, which `get_output_audio` used to refuse outright, or an
+        excerpt (`start` + `duration`, seconds) of a track too long to send
+        whole (#193). An excerpt names itself in the response headers
+        (`X-DW-Excerpt-Start`, `X-DW-Excerpt-Duration`) beside the whole
+        track's `X-DW-Duration`, so a cut is never silent (#204).
+
+        An audio-only file asked for whole is served as its own bytes in its
+        own encoding - there is nothing to extract, and a transcode would
+        change what the agent hears."""
+        if is_asset_reference(name):
+            path = _asset_file(name, ws)
+        else:
+            path = _output_file(name, ws.outputs)
+        extension = os.path.splitext(path)[1].lower()
+        kind = MEDIA_KINDS.get(extension)
+        if kind not in ("audio", "video"):
+            raise HTTPException(status_code=404, detail=f"{name} carries no soundtrack")
+
+        excerpt = start is not None or duration is not None
+        if kind == "audio" and not excerpt:
+            media = probe_media(path) or {}
+            headers = {"X-DW-Duration": str(media.get("duration_seconds", ""))}
+            media_type = mimetypes.guess_type(path)[0] or "application/octet-stream"
+            return FileResponse(path, media_type=media_type, headers=headers)
+
+        try:
+            data, info = extract_audio(path, start=start, duration=duration)
+        except NoSoundtrack:
+            raise HTTPException(status_code=404, detail=f"{name} carries no soundtrack")
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        headers = {"X-DW-Duration": str(info["of_seconds"])}
+        if info["excerpt"]:
+            headers["X-DW-Excerpt-Start"] = str(info["start"])
+            headers["X-DW-Excerpt-Duration"] = str(info["duration_seconds"])
+        return Response(content=data, media_type="audio/wav", headers=headers)
+```
+
+Add `import mimetypes` to the stdlib imports at the top of `app.py` (line 8 block) if it is not already there.
+
+- [ ] **Step 4: Run the tests until they pass**
+
+Run: `venv/bin/python -m pytest tests/test_server.py -k gallery_audio -v`
+Expected: PASS (5 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/server/app.py tests/test_server.py
+git commit -m "feat(server): #193 - GET /api/gallery/{name}/audio serves a soundtrack or an excerpt of one"
+```
+
+---
+
+### Task 3: `get_output_audio` moves to the route and takes an excerpt
+
+**Files:**
+- Modify: `dw_mcp/client.py:177-197` (`get_bytes_if`)
+- Modify: `dw_mcp/media.py:106-140` (`get_output_audio`)
+- Modify: `dw_mcp/server.py:550-574` (the tool)
+- Modify: `tests/test_mcp_server.py:359` (wiring row), `tests/test_mcp_media.py`
+- Modify: `docs/MCP.md:237` (tool row) and `:456-458` (the "Images and audio only" bullet), `dw_mcp/CLAUDE.md` (the `get_output_audio` sentence)
+
+**Interfaces:**
+- Consumes: Task 2's route and headers.
+- Produces: `DwClient.get_media_if(path, accept_content_type, workspace=None, params=None) -> (body | None, content_type, headers)`; `media.get_output_audio(client, name, start=None, duration=None, workspace=None) -> {name, data, mime_type, bytes, duration_seconds, excerpt: None | {start, duration, of}}`.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/test_mcp_media.py - add
+
+
+def serving_with_headers(content, content_type, headers):
+    def handler(request):
+        return httpx.Response(
+            200, content=content, headers={"content-type": content_type, **headers}
+        )
+
+    return DwClient(transport=httpx.MockTransport(handler))
+
+
+def test_audio_is_fetched_from_the_gallery_audio_route():
+    seen = []
+
+    def handler(request):
+        seen.append((request.url.path, dict(request.url.params)))
+        return httpx.Response(
+            200,
+            content=b"riff",
+            headers={"content-type": "audio/wav", "x-dw-duration": "2.0"},
+        )
+
+    client = DwClient(transport=httpx.MockTransport(handler))
+    result = get_output_audio(client, "run/shot.mp4")
+
+    assert seen == [("/api/gallery/run%2Fshot.mp4/audio", {})]
+    assert result["mime_type"] == "audio/wav"
+    assert result["duration_seconds"] == 2.0
+    assert result["excerpt"] is None
+
+
+def test_an_excerpt_is_asked_for_and_reported():
+    seen = []
+
+    def handler(request):
+        seen.append(dict(request.url.params))
+        return httpx.Response(
+            200,
+            content=b"riff",
+            headers={
+                "content-type": "audio/wav",
+                "x-dw-duration": "240.0",
+                "x-dw-excerpt-start": "10.0",
+                "x-dw-excerpt-duration": "2.0",
+            },
+        )
+
+    client = DwClient(transport=httpx.MockTransport(handler))
+    result = get_output_audio(client, "cut.mp4", start=10.0, duration=2.0)
+
+    assert seen == [{"start": "10.0", "duration": "2.0"}]
+    assert result["excerpt"] == {"start": 10.0, "duration": 2.0, "of": 240.0}
+
+
+def test_a_whole_track_over_budget_is_refused_and_told_to_excerpt():
+    big = b"\0" * (MAX_RETURNED_BYTES * 3 // 4 + 1024)
+    client = serving_with_headers(big, "audio/wav", {"x-dw-duration": "240.0"})
+
+    with pytest.raises(DwApiError) as caught:
+        get_output_audio(client, "cut.mp4")
+
+    assert "start" in str(caught.value) and "duration" in str(caught.value)
+
+
+def test_a_non_audio_answer_is_refused():
+    client = serving(b"{}", "application/json")
+
+    with pytest.raises(DwApiError, match="not audio"):
+        get_output_audio(client, "thing.json")
+```
+
+Also update the existing `get_output_audio` tests in this file that assert the `/outputs/` path or the old refusal wording on `video/mp4` - read them (`grep -n get_output_audio tests/test_mcp_media.py`) and change the ones whose premise this task removes: a `video/mp4` body is no longer a refusal case at the client (the server now answers WAV), so delete that test or turn it into the "non audio answer" one above.
+
+In `tests/test_mcp_server.py` change the wiring row:
+
+```python
+(("get_output_audio", {"name": "out.wav"}, "GET", "/api/gallery/out.wav/audio"),)
+```
+
+and the wiring handler in `test_each_tool_calls_its_endpoint` already answers `audio/wav` for paths ending `.wav` - it ends with `/audio` now, so change that branch to `if request.url.path.endswith("/audio"):`.
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `venv/bin/python -m pytest tests/test_mcp_media.py tests/test_mcp_server.py -k "audio" -v`
+Expected: FAIL - path is `/outputs/...`, `excerpt` key missing, `TypeError` on `start=`.
+
+- [ ] **Step 3: Extend the client**
+
+In `dw_mcp/client.py`, replace `get_bytes_if` with:
+
+```python
+def get_media_if(self, path, accept_content_type, workspace=None, params=None):
+    """Like `get_bytes`, but the body is only downloaded when
+    `accept_content_type(content_type)` is true, and the response
+    headers come back with it - a media route says what it cut in
+    them.
+
+    Headers arrive before the body over HTTP, so a rejection closes the
+    connection having read nothing past them - useful for `/outputs`,
+    where a rejected file (a video, say) can be arbitrarily large.
+    Returns `(None, content_type, headers)` on rejection, `(body,
+    content_type, headers)` on acceptance. An error status is still
+    raised either way, since the body has to be read to report it.
+    """
+    kwargs = {"params": params} if params else {}
+    response = self._stream_request("GET", path, workspace=workspace, **kwargs)
+    try:
+        content_type = response.headers.get("content-type", "")
+        if response.status_code < 400 and not accept_content_type(content_type):
+            return None, content_type, response.headers
+        self._call_httpx(response.read, path)
+        self._raise_for_status(response, path)
+        return response.content, content_type, response.headers
+    finally:
+        response.close()
+
+
+def get_bytes_if(self, path, accept_content_type, workspace=None):
+    """`get_media_if` without the headers, for the callers that only
+    want the body."""
+    body, content_type, _headers = self.get_media_if(
+        path, accept_content_type, workspace=workspace
+    )
+    return body, content_type
+```
+
+Check `_scoped` merges `params` rather than replacing them (read `dw_mcp/client.py:250-270`); if it does `kwargs.setdefault("params", {})` then `.setdefault("workspace", ...)`, passing `params` works as-is. If it replaces, fix `_scoped` to merge.
+
+- [ ] **Step 4: Rewrite the handler**
+
+In `dw_mcp/media.py` replace `get_output_audio`:
+
+```python
+def get_output_audio(client, name, start=None, duration=None, workspace=None):
+    """One soundtrack from the gallery as base64 WAV - an audio output, or
+    the track muxed into a video (#193) - for a clip short enough to fit
+    MAX_RETURNED_BYTES whole, or an excerpt of one that is not.
+
+    Audio is not resized the way an image is - there is no downscale of a
+    waveform that keeps it meaningful to listen to - so a whole clip over
+    budget is refused rather than truncated (#204). The way to hear part of
+    a long track is to *ask* for the part: `start` and `duration` in
+    seconds, and the answer names what it cut in `excerpt`, so a slice is
+    never mistaken for the whole."""
+
+    def is_audio(content_type):
+        return bool(content_type) and content_type.startswith("audio/")
+
+    params = {}
+    if start is not None:
+        params["start"] = start
+    if duration is not None:
+        params["duration"] = duration
+    body, content_type, headers = client.get_media_if(
+        api_path("api", "gallery", name, "audio"),
+        is_audio,
+        workspace=workspace,
+        params=params,
+    )
+    if body is None:
+        raise DwApiError(
+            f"{name} answered {content_type or 'no declared type'}, not audio - "
+            "this tool returns a soundtrack only. Use get_output_image for "
+            "an image, or get_gallery_metadata for other media."
+        )
+
+    base64_size = 4 * math.ceil(len(body) / 3)
+    if base64_size > MAX_RETURNED_BYTES:
+        raise DwApiError(
+            f"{name} is {len(body)} bytes, which would be {base64_size} "
+            f"bytes base64-encoded - over the {MAX_RETURNED_BYTES} byte "
+            "limit for an inline clip. Ask for an excerpt with `start` and "
+            "`duration` (seconds) - get_gallery_metadata's envelope says "
+            "where to look - or use download_output for the whole file."
+        )
+
+    excerpt = None
+    if "x-dw-excerpt-start" in headers:
+        excerpt = {
+            "start": float(headers["x-dw-excerpt-start"]),
+            "duration": float(headers["x-dw-excerpt-duration"]),
+            "of": _float_header(headers, "x-dw-duration"),
+        }
+    return {
+        "name": name,
+        "data": base64.b64encode(body).decode("ascii"),
+        "mime_type": content_type,
+        "bytes": len(body),
+        "duration_seconds": _float_header(headers, "x-dw-duration"),
+        "excerpt": excerpt,
+    }
+
+
+def _float_header(headers, key):
+    value = headers.get(key)
+    try:
+        return float(value) if value not in (None, "") else None
+    except ValueError:
+        return None
+```
+
+- [ ] **Step 5: Update the tool in `dw_mcp/server.py`**
+
+```python
+    def get_output_audio(
+        name: str,
+        start: float | None = None,
+        duration: float | None = None,
+        workspace: str | None = None,
+    ) -> list[AudioContent | TextContent]:
+        """Listen to a generated soundtrack, named as `list_gallery` or a
+        job's manifest reports it - an audio output, or the track muxed
+        into a video (the audio analogue of `get_output_image`). There is
+        no downscale for audio, so a whole clip too large to fit inline is
+        refused rather than cut; hear part of a long one by asking for the
+        part - `start` and `duration` in seconds, around a seam or a
+        moment `get_gallery_metadata`'s envelope located. The text part
+        reports the whole track's length and, for an excerpt, exactly what
+        was cut, so a slice is never mistaken for the whole. To *see* a
+        video, `get_output_frames`.
+
+        `workspace` names the workspace for this one call without
+        switching the session to it - the same pin `run_workflow`
+        takes (#99)."""
+        result = media.get_output_audio(
+            client, name, start=start, duration=duration, workspace=workspace
+        )
+        audio = AudioContent(
+            type="audio", data=result["data"], mime_type=result["mime_type"]
+        )
+        lines = [f"name: {result['name']}", f"bytes: {result['bytes']}"]
+        if result["duration_seconds"] is not None:
+            lines.append(f"duration_seconds: {result['duration_seconds']}")
+        if result["excerpt"]:
+            e = result["excerpt"]
+            lines.append(f"excerpt: {e['duration']}s from {e['start']}s of {e['of']}s")
+        telemetry = TextContent(type="text", text="\n".join(lines))
+        return [audio, telemetry]
+```
+
+- [ ] **Step 6: Run the tests until they pass**
+
+Run: `venv/bin/python -m pytest tests/test_mcp_media.py tests/test_mcp_server.py tests/test_mcp_client.py -v`
+Expected: PASS. `test_wrapper_handler_map_covers_every_defaulted_handler` still passes (`get_output_audio` is already in the map).
+
+- [ ] **Step 7: Update the docs**
+
+`docs/MCP.md` line 237 row:
+
+```
+| `get_output_audio(name, start=None, duration=None, workspace=None)` | `name`, `start`, `duration`, `workspace` | Listen to a generated soundtrack as base64 WAV - an audio output, or the track muxed into a video (#193). No downscale exists for audio, so a whole clip over the 4MB budget is refused rather than cut (#204); ask for the part instead with `start` and `duration` in seconds, and the text part names what was cut (`excerpt: 2.0s from 10.0s of 240.0s`) so a slice is never mistaken for the whole. `get_gallery_metadata`'s envelope says where in a track to look. `workspace` names the workspace for this one call without switching the session to it |
+```
+
+`docs/MCP.md` lines ~456-458: replace the "Images and audio only" bullet with:
+
+```
+- **Images, sound and frames.** `get_output_image` returns an image,
+  `get_output_audio` a soundtrack (an audio file's, or the one muxed into a
+  video) whole or as a named excerpt, and `get_output_frames` frames of a
+  video as images - there is no video content type over MCP, so a video is
+  seen as frames and heard as its track. `get_output_audio` refuses a whole
+  clip whose base64 size would exceed the same 4MB budget; ask for an
+  excerpt instead.
+```
+
+`dw_mcp/CLAUDE.md`: replace the sentence beginning "`get_output_audio` is `get_output_image`'s sibling for audio" through "no `VideoContent` type to return it as." with:
+
+```
+`get_output_audio` is `get_output_image`'s sibling for sound (`media.py`,
+#204, #193): it reads `GET /api/gallery/{name}/audio`, which extracts a
+video's muxed track as WAV and cuts an excerpt on `start`/`duration`; a
+whole clip over the same 4MB budget is still refused rather than cut short,
+and the refusal says to ask for an excerpt. Video has no MCP content type,
+so `get_output_frames` returns frames of one as `ImageContent` - specific
+moments, a contact sheet, or the frame pair either side of each seam.
+```
+
+- [ ] **Step 8: Run the doc and MCP suites, then commit**
+
+Run: `venv/bin/python -m pytest tests/test_mcp_server.py tests/test_docs_links.py -q`
+Expected: PASS.
+
+```bash
+git add dw_mcp/client.py dw_mcp/media.py dw_mcp/server.py dw_mcp/CLAUDE.md docs/MCP.md tests/test_mcp_media.py tests/test_mcp_server.py
+git commit -m "feat(mcp): #193 - get_output_audio hears a video's soundtrack and takes an excerpt"
+```
+
+---
+
+### Task 4: `dw/media_frames.py` - frames by moment, a contact sheet, seam tiles
+
+**Files:**
+- Create: `dw/media_frames.py`
+- Test: `tests/test_media_frames.py`
+
+**Interfaces:**
+- Consumes: `dw.tasks.video_utils._grid_tile(frame, index, fps, tile_width, label)`, `_compose_grid(tiles, columns)`, `_default_columns(count)`, `_evenly_spaced_indices(total, count)` (all exist; `frame_grid` at `video_utils.py:177` is their caller). `video_utils` imports torch; that is fine in the server process, which already has it loaded.
+- Produces:
+  - `frames_at(path, moments) -> list[Tile]` where `moments` is a list of `float` seconds or `"frame:N"` strings and `Tile` is a `dict` `{"label": str, "frame": int, "seconds": float, "image": PIL.Image}`.
+  - `contact_sheet(path, count, tile_width=320) -> Tile` (one tile whose `image` is the grid, `label` = `"contact sheet, N frames"`).
+  - `seam_tiles(path, boundaries, names=None, tile_width=320) -> list[Tile]` where `boundaries` is a list of frame indexes at which each shot after the first *starts*, so seam *i* is between frame `boundaries[i]-1` and `boundaries[i]`; one side-by-side tile per seam, `label` = `"seam 1: <A> | <B>"` using `names` (defaults `"shot 1"`, `"shot 2"`, ...).
+  - `video_shape(path) -> {"frame_count": int, "fps": float | None, "width": int, "height": int}`.
+  - All raise `ValueError` for a moment past the end, a boundary outside `1..frame_count-1`, a file with no video stream.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/test_media_frames.py
+"""Frames out of a file by seeking, not by decoding it whole - what
+get_output_frames needs so an agent can look at a moment, a contact sheet
+or the frame pair either side of a seam (#193)."""
+
+import numpy
+import pytest
+from PIL import Image
+
+from dw.media_frames import contact_sheet, frames_at, seam_tiles, video_shape
+
+
+def write_ramp_mp4(path, frames=24, fps=6, width=32, height=16):
+    """A clip whose frame N is a flat grey of value N*10, so a returned
+    frame says which one it is."""
+    import av
+
+    container = av.open(str(path), "w")
+    stream = container.add_stream("libx264", rate=fps)
+    stream.width, stream.height, stream.pix_fmt = width, height, "yuv420p"
+    stream.options = {"crf": "0", "preset": "ultrafast"}  # lossless, so grey survives
+    for index in range(frames):
+        pixels = numpy.full((height, width, 3), index * 10, numpy.uint8)
+        frame = av.VideoFrame.from_ndarray(pixels, format="rgb24")
+        for packet in stream.encode(frame):
+            container.mux(packet)
+    for packet in stream.encode():
+        container.mux(packet)
+    container.close()
+
+
+def grey_of(image):
+    return int(numpy.asarray(image.convert("L")).mean().round())
+
+
+def test_video_shape_reads_the_container(tmp_path):
+    write_ramp_mp4(tmp_path / "ramp.mp4", frames=24, fps=6)
+
+    shape = video_shape(str(tmp_path / "ramp.mp4"))
+
+    assert shape == {"frame_count": 24, "fps": 6.0, "width": 32, "height": 16}
+
+
+def test_frames_at_seeks_to_seconds_and_frame_indexes(tmp_path):
+    write_ramp_mp4(tmp_path / "ramp.mp4", frames=24, fps=6)
+
+    tiles = frames_at(str(tmp_path / "ramp.mp4"), [0.0, 2.0, "frame:23"])
+
+    assert [t["frame"] for t in tiles] == [0, 12, 23]
+    assert [t["seconds"] for t in tiles] == pytest.approx([0.0, 2.0, 23 / 6])
+    assert [grey_of(t["image"]) for t in tiles] == pytest.approx([0, 120, 230], abs=6)
+    assert tiles[1]["label"] == "00:02.0 (frame 12)"
+
+
+def test_a_moment_past_the_end_is_refused(tmp_path):
+    write_ramp_mp4(tmp_path / "ramp.mp4", frames=6, fps=6)
+
+    with pytest.raises(ValueError, match="past the end"):
+        frames_at(str(tmp_path / "ramp.mp4"), [5.0])
+    with pytest.raises(ValueError, match="past the end"):
+        frames_at(str(tmp_path / "ramp.mp4"), ["frame:6"])
+
+
+def test_a_contact_sheet_tiles_evenly_spaced_frames(tmp_path):
+    write_ramp_mp4(tmp_path / "ramp.mp4", frames=24, fps=6)
+
+    tile = contact_sheet(str(tmp_path / "ramp.mp4"), count=4, tile_width=32)
+
+    assert tile["label"] == "contact sheet, 4 frames"
+    assert tile["image"].width == 32 * 2  # 4 tiles, two columns
+    assert tile["image"].height == 16 * 2
+    # first tile is frame 0, last is frame 23
+    first = tile["image"].crop((0, 0, 32, 16))
+    last = tile["image"].crop((32, 16, 64, 32))
+    assert grey_of(first) < 20
+    assert grey_of(last) > 200
+
+
+def test_seam_tiles_pair_the_frames_either_side_of_each_boundary(tmp_path):
+    write_ramp_mp4(tmp_path / "ramp.mp4", frames=24, fps=6)
+
+    tiles = seam_tiles(
+        str(tmp_path / "ramp.mp4"),
+        boundaries=[8, 16],
+        names=["shot@a", "shot@b", "shot@c"],
+        tile_width=32,
+    )
+
+    assert [t["label"] for t in tiles] == [
+        "seam 1: shot@a | shot@b",
+        "seam 2: shot@b | shot@c",
+    ]
+    assert [t["frame"] for t in tiles] == [8, 16]
+    image = tiles[0]["image"]
+    assert image.width == 64 and image.height == 16
+    assert grey_of(image.crop((0, 0, 32, 16))) == pytest.approx(70, abs=6)  # frame 7
+    assert grey_of(image.crop((32, 0, 64, 16))) == pytest.approx(80, abs=6)  # frame 8
+
+
+def test_a_boundary_outside_the_clip_is_refused(tmp_path):
+    write_ramp_mp4(tmp_path / "ramp.mp4", frames=6, fps=6)
+
+    with pytest.raises(ValueError, match="boundary"):
+        seam_tiles(str(tmp_path / "ramp.mp4"), boundaries=[0])
+    with pytest.raises(ValueError, match="boundary"):
+        seam_tiles(str(tmp_path / "ramp.mp4"), boundaries=[6])
+```
+
+Note: the label tests burn text into the tile via `_grid_tile(label=True)`; `grey_of` tolerances of ±6 absorb the small label. If a label pushes a mean past the tolerance at 32x16, pass `label=False` inside `seam_tiles`/`frames_at` for the *sub*-tiles and put the label only in the returned dict - the server route burns nothing, the MCP telemetry text carries the label. Prefer that: the spec's "names burned in" is satisfied by a caption strip, which is Task 5's concern, not this module's.
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `venv/bin/python -m pytest tests/test_media_frames.py -v`
+Expected: FAIL with `ModuleNotFoundError: No module named 'dw.media_frames'`
+
+- [ ] **Step 3: Write the module**
+
+```python
+# dw/media_frames.py
+"""Frames out of a video file by seeking to them - a moment, an evenly
+spaced contact sheet, or the frame pair either side of a seam - without
+decoding the clip whole. The server process runs this per request; a
+four-minute 1080p clip materialised as PIL frames is tens of gigabytes,
+so nothing here ever holds more than the frames it returns (#193).
+"""
+
+import logging
+
+import av
+from PIL import Image
+
+from .tasks.video_utils import (
+    _compose_grid,
+    _default_columns,
+    _evenly_spaced_indices,
+    _format_timestamp,
+)
+
+logger = logging.getLogger("dw")
+
+
+def video_shape(path):
+    """Frame count, fps and size, from the container's own headers where
+    they are written and by counting otherwise."""
+    with av.open(path) as container:
+        if not container.streams.video:
+            raise ValueError(f"{path} has no video stream")
+        stream = container.streams.video[0]
+        fps = float(stream.average_rate) if stream.average_rate else None
+        count = int(stream.frames) if stream.frames else None
+        if count is None:
+            count = sum(1 for _ in container.decode(stream))
+        return {
+            "frame_count": count,
+            "fps": fps,
+            "width": int(stream.width),
+            "height": int(stream.height),
+        }
+
+
+def frames_at(path, moments):
+    """One tile per moment - a float in seconds or "frame:N" - in the order
+    asked for. Each tile is {label, frame, seconds, image}."""
+    shape = video_shape(path)
+    indexes = [_moment_to_index(moment, shape) for moment in moments]
+    images = _read_frames(path, indexes)
+    return [_tile(index, images[index], shape) for index in indexes]
+
+
+def contact_sheet(path, count, tile_width=320):
+    """N evenly spaced frames (first and last included) tiled into one
+    image - frame_grid without a workflow."""
+    if int(count) < 1:
+        raise ValueError("count must be at least 1")
+    shape = video_shape(path)
+    count = min(int(count), shape["frame_count"])
+    indexes = _evenly_spaced_indices(shape["frame_count"], count)
+    images = _read_frames(path, indexes)
+    tiles = [_fit_width(images[index], tile_width) for index in indexes]
+    grid = _compose_grid(tiles, _default_columns(len(tiles)))
+    return {
+        "label": f"contact sheet, {len(tiles)} frames",
+        "frame": indexes[0],
+        "seconds": _seconds(indexes[0], shape),
+        "image": grid,
+        "frames": list(indexes),
+    }
+
+
+def seam_tiles(path, boundaries, names=None, tile_width=320):
+    """For each boundary (the frame index a shot *starts* at), the last
+    frame before it and the first frame at it, side by side - the seam and
+    continuity evidence in one image. Seam i sits between shot i and shot
+    i+1; `names` names the shots, "shot 1".. by default."""
+    shape = video_shape(path)
+    total = shape["frame_count"]
+    for boundary in boundaries:
+        if not 1 <= int(boundary) <= total - 1:
+            raise ValueError(
+                f"boundary {boundary} is not inside the clip (1..{total - 1})"
+            )
+    boundaries = [int(b) for b in boundaries]
+    names = list(names or [f"shot {n + 1}" for n in range(len(boundaries) + 1)])
+    if len(names) != len(boundaries) + 1:
+        raise ValueError(
+            f"{len(boundaries)} boundaries make {len(boundaries) + 1} shots, "
+            f"but {len(names)} names were given"
+        )
+    wanted = sorted({b - 1 for b in boundaries} | set(boundaries))
+    images = _read_frames(path, wanted)
+    tiles = []
+    for seam, boundary in enumerate(boundaries):
+        before = _fit_width(images[boundary - 1], tile_width)
+        after = _fit_width(images[boundary], tile_width)
+        pair = _compose_grid([before, after], 2)
+        tiles.append(
+            {
+                "label": f"seam {seam + 1}: {names[seam]} | {names[seam + 1]}",
+                "frame": boundary,
+                "seconds": _seconds(boundary, shape),
+                "image": pair,
+            }
+        )
+    return tiles
+
+
+def _moment_to_index(moment, shape):
+    total = shape["frame_count"]
+    if isinstance(moment, str) and moment.startswith("frame:"):
+        index = int(moment[len("frame:") :])
+    else:
+        fps = shape["fps"]
+        if fps is None:
+            raise ValueError("this clip has no frame rate, so name a frame: 'frame:N'")
+        index = int(round(float(moment) * fps))
+    if index < 0:
+        index += total
+    if not 0 <= index < total:
+        raise ValueError(f"{moment!r} is past the end of a {total}-frame clip")
+    return index
+
+
+def _seconds(index, shape):
+    return index / shape["fps"] if shape["fps"] else float(index)
+
+
+def _tile(index, image, shape):
+    fps = shape["fps"]
+    stamp = _format_timestamp(index, fps) if fps else f"#{index}"
+    return {
+        "label": f"{stamp} (frame {index})",
+        "frame": index,
+        "seconds": _seconds(index, shape),
+        "image": image,
+    }
+
+
+def _fit_width(image, tile_width):
+    height = max(1, round(image.height * tile_width / image.width))
+    return image.resize((tile_width, height), Image.LANCZOS).convert("RGB")
+
+
+def _read_frames(path, indexes):
+    """The frames at these indexes, as {index: PIL image}, in one forward
+    pass that seeks to the keyframe before each wanted frame rather than
+    decoding from the top. Decodes are dropped as soon as they are past."""
+    wanted = sorted(set(int(i) for i in indexes))
+    found = {}
+    with av.open(path) as container:
+        stream = container.streams.video[0]
+        fps = float(stream.average_rate) if stream.average_rate else None
+        position = 0  # index of the next frame decode() will yield
+        for target in wanted:
+            if target < position or target - position > 2 * (int(fps) if fps else 24):
+                # seek back or a long way forward: land on the keyframe at
+                # or before the target, then read up to it
+                seconds = target / fps if fps else 0.0
+                container.seek(
+                    int(seconds / stream.time_base), stream=stream, backward=True
+                )
+                position = None
+            for frame in container.decode(stream):
+                if position is None:
+                    # first frame after a seek says where we landed
+                    position = (
+                        int(round(float(frame.pts * stream.time_base) * fps))
+                        if fps and frame.pts is not None
+                        else 0
+                    )
+                if position == target:
+                    found[target] = frame.to_image()
+                    position += 1
+                    break
+                position += 1
+        missing = [i for i in wanted if i not in found]
+        if missing:
+            raise ValueError(f"could not decode frame(s) {missing} of {path}")
+    return found
+```
+
+The seek-then-count logic assumes constant frame rate, which every file this engine writes has (`encode_video` / `export_to_video` write a fixed `fps`). If the ramp test's returned greys are off by one frame, the keyframe landing computed `position` wrong - fall back to `position = 0` and `container.seek(0)` for that file (correct, slower) rather than loosen the test.
+
+- [ ] **Step 4: Run the tests until they pass**
+
+Run: `venv/bin/python -m pytest tests/test_media_frames.py -v`
+Expected: PASS (6 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/media_frames.py tests/test_media_frames.py
+git commit -m "feat(server): #193 - media_frames seeks out moments, a contact sheet and seam pairs"
+```
+
+---
+
+### Task 5: `GET /api/gallery/{name}/frames` - the frames route
+
+**Files:**
+- Modify: `dw/server/app.py` (after `gallery_audio` from Task 2; import beside `extract_audio`)
+- Test: `tests/test_server.py`
+
+**Interfaces:**
+- Consumes: Task 4's `frames_at`, `contact_sheet`, `seam_tiles`, `video_shape`.
+- Produces: the route. Query: exactly one of `at` (repeatable: `?at=1.5&at=frame:12`), `count` (int), `seams` (`true` or a comma list of 1-based seam numbers); `boundaries` (comma list of frame indexes - required with `seams` in this stage; stage 2 fills it from the manifest when absent); `names` (comma list); `max_dimension` (int, default 512, the longest side of each returned tile). Answer:
+
+```json
+{"name": "...", "frame_count": 120, "fps": 24.0, "width": 960, "height": 544,
+ "tiles": [{"label": "00:02.0 (frame 48)", "frame": 48, "seconds": 2.0,
+            "data": "<base64 png>", "mime_type": "image/png", "width": 512, "height": 290}]}
+```
+
+400 when zero or more than one selector is given, when `seams` has no `boundaries`, or when a moment/boundary is out of range; 404 when the file is not a video.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/test_server.py - add after the gallery_audio tests
+
+
+def _png_of(tile):
+    import base64
+    import io
+    from PIL import Image
+
+    return Image.open(io.BytesIO(base64.b64decode(tile["data"])))
+
+
+def test_gallery_frames_returns_the_moments_asked_for(server, tmp_path):
+    """No tool returned a frame of a video, so judging a clip meant handing
+    the user the file (#193, #245). The route seeks out the moments named."""
+    from tests.test_media_frames import write_ramp_mp4
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        write_ramp_mp4(
+            outputs / "shot-gen.0-0.0.mp4", frames=24, fps=6, width=64, height=32
+        )
+
+        response = client.get(
+            "/api/gallery/shot-gen.0-0.0.mp4/frames",
+            params=[("at", "0.0"), ("at", "frame:12"), ("max_dimension", "32")],
+        )
+
+        assert response.status_code == 200
+        body = response.json()
+        assert body["frame_count"] == 24 and body["fps"] == 6.0
+        assert [t["frame"] for t in body["tiles"]] == [0, 12]
+        assert body["tiles"][0]["mime_type"] == "image/png"
+        assert body["tiles"][0]["width"] == 32  # downscaled to max_dimension
+        assert _png_of(body["tiles"][0]).size == (32, 16)
+
+
+def test_gallery_frames_makes_a_contact_sheet(server, tmp_path):
+    from tests.test_media_frames import write_ramp_mp4
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        write_ramp_mp4(outputs / "shot-gen.0-0.0.mp4", frames=24, fps=6)
+
+        response = client.get(
+            "/api/gallery/shot-gen.0-0.0.mp4/frames", params={"count": 4}
+        )
+
+        assert response.status_code == 200
+        tiles = response.json()["tiles"]
+        assert len(tiles) == 1
+        assert tiles[0]["label"] == "contact sheet, 4 frames"
+        assert tiles[0]["frames"] == [0, 7, 15, 23]
+
+
+def test_gallery_frames_pairs_the_frames_at_each_seam(server, tmp_path):
+    from tests.test_media_frames import write_ramp_mp4
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        write_ramp_mp4(outputs / "cut-gen.0-0.0.mp4", frames=24, fps=6)
+
+        response = client.get(
+            "/api/gallery/cut-gen.0-0.0.mp4/frames",
+            params={"seams": "true", "boundaries": "8,16", "names": "a,b,c"},
+        )
+
+        assert response.status_code == 200
+        tiles = response.json()["tiles"]
+        assert [t["label"] for t in tiles] == ["seam 1: a | b", "seam 2: b | c"]
+
+        second = client.get(
+            "/api/gallery/cut-gen.0-0.0.mp4/frames",
+            params={"seams": "2", "boundaries": "8,16"},
+        )
+        assert [t["label"] for t in second.json()["tiles"]] == [
+            "seam 2: shot 2 | shot 3"
+        ]
+
+
+def test_gallery_frames_refuses_bad_selectors(server, tmp_path):
+    from tests.test_media_frames import write_ramp_mp4
+    from tests.test_media_info import write_wav
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        write_ramp_mp4(outputs / "shot-gen.0-0.0.mp4", frames=6, fps=6)
+        write_wav(outputs / "score-gen.0-0.0.wav")
+
+        none = client.get("/api/gallery/shot-gen.0-0.0.mp4/frames")
+        assert none.status_code == 400 and "one of" in none.json()["detail"]
+
+        two = client.get(
+            "/api/gallery/shot-gen.0-0.0.mp4/frames", params={"count": 2, "at": "0"}
+        )
+        assert two.status_code == 400
+
+        no_boundaries = client.get(
+            "/api/gallery/shot-gen.0-0.0.mp4/frames", params={"seams": "true"}
+        )
+        assert no_boundaries.status_code == 400
+        assert "boundaries" in no_boundaries.json()["detail"]
+
+        past = client.get(
+            "/api/gallery/shot-gen.0-0.0.mp4/frames", params={"at": "9.0"}
+        )
+        assert past.status_code == 400 and "past the end" in past.json()["detail"]
+
+        audio = client.get(
+            "/api/gallery/score-gen.0-0.0.wav/frames", params={"count": 1}
+        )
+        assert audio.status_code == 404
+
+
+def test_gallery_frames_reads_an_asset_reference(asset_server, tmp_path):
+    from tests.test_media_frames import write_ramp_mp4
+
+    with asset_server(success_script) as client:
+        write_ramp_mp4(tmp_path / "assets" / "ref.mp4", frames=6, fps=6)
+
+        response = client.get("/api/gallery/asset:ref.mp4/frames", params={"count": 2})
+
+        assert response.status_code == 200
+        assert response.json()["tiles"][0]["frames"] == [0, 5]
+```
+
+(Use the same `asset_server` setup as the Task 2 asset test.)
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `venv/bin/python -m pytest tests/test_server.py -k gallery_frames -v`
+Expected: FAIL with 404 Not Found from FastAPI.
+
+- [ ] **Step 3: Add the route**
+
+Import beside `extract_audio`:
+
+```python
+from ..media_frames import contact_sheet, frames_at, seam_tiles, video_shape
+```
+
+Add after `gallery_audio`:
+
+```python
+FRAME_MIN_DIMENSION = 64
+
+
+@app.get("/api/gallery/{name:path}/frames")
+def gallery_frames(
+    name: str,
+    at: Optional[List[str]] = Query(None),
+    count: Optional[int] = None,
+    seams: Optional[str] = None,
+    boundaries: Optional[str] = None,
+    names: Optional[str] = None,
+    max_dimension: int = 512,
+    ws: Workspace = Depends(selected_workspace),
+):
+    """Frames of a video output or asset, as PNG tiles - the way an
+    agent with no video content type sees what a run made (#193).
+    Exactly one selector: `at` (repeatable; seconds, or "frame:N"),
+    `count` (an evenly spaced contact sheet, `frame_grid` without a
+    workflow), or `seams` ("true", or a comma list of 1-based seam
+    numbers) for the last frame before and first frame after each
+    boundary, side by side. `boundaries` is the comma list of frame
+    indexes each shot after the first starts at, and `names` the
+    shots' names; both are required with `seams` until a joined file
+    carries its own (stage 2 of docs/proposals/output-assessment.md).
+    Tiles are downscaled to `max_dimension` on their longest side."""
+    if is_asset_reference(name):
+        path = _asset_file(name, ws)
+    else:
+        path = _output_file(name, ws.outputs)
+    if MEDIA_KINDS.get(os.path.splitext(path)[1].lower()) != "video":
+        raise HTTPException(status_code=404, detail=f"{name} is not a video")
+
+    chosen = [
+        key for key, value in (("at", at), ("count", count), ("seams", seams)) if value
+    ]
+    if len(chosen) != 1:
+        raise HTTPException(
+            status_code=400,
+            detail="Pass exactly one of `at`, `count` or `seams`"
+            + (f" - got {', '.join(chosen)}" if chosen else ""),
+        )
+    limit = max(FRAME_MIN_DIMENSION, int(max_dimension))
+
+    try:
+        if at:
+            moments = [m if m.startswith("frame:") else float(m) for m in at]
+            tiles = frames_at(path, moments)
+        elif count:
+            tiles = [contact_sheet(path, count, tile_width=limit)]
+        else:
+            if not boundaries:
+                raise HTTPException(
+                    status_code=400,
+                    detail="`seams` needs `boundaries`: the frame index each "
+                    "shot after the first starts at, comma-separated - this "
+                    "file carries none of its own",
+                )
+            starts = [int(b) for b in boundaries.split(",") if b.strip()]
+            shot_names = [n.strip() for n in names.split(",")] if names else None
+            tiles = seam_tiles(path, starts, names=shot_names, tile_width=limit)
+            if seams.lower() != "true":
+                wanted = {int(s) for s in seams.split(",") if s.strip()}
+                tiles = [t for i, t in enumerate(tiles, start=1) if i in wanted]
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    shape = video_shape(path)
+    return {
+        "name": name,
+        **shape,
+        "tiles": [_encoded_tile(tile, limit) for tile in tiles],
+    }
+
+
+def _encoded_tile(tile, limit):
+    image = tile["image"]
+    longest = max(image.width, image.height)
+    if longest > limit:
+        scale = limit / longest
+        image = image.resize(
+            (max(1, round(image.width * scale)), max(1, round(image.height * scale)))
+        )
+    buffer = io.BytesIO()
+    image.save(buffer, format="PNG")
+    encoded = {key: value for key, value in tile.items() if key != "image"}
+    encoded.update(
+        {
+            "data": base64.b64encode(buffer.getvalue()).decode("ascii"),
+            "mime_type": "image/png",
+            "width": image.width,
+            "height": image.height,
+        }
+    )
+    return encoded
+```
+
+Add `import base64` to the stdlib imports if absent. The `contact_sheet` and `seam_tiles` tile widths are per sub-tile; the composed grid can exceed `limit` on its longest side, so `_encoded_tile` fits the *composite* to `limit` - that is the behaviour the `max_dimension` test asserts.
+
+- [ ] **Step 4: Run the tests until they pass**
+
+Run: `venv/bin/python -m pytest tests/test_server.py -k "gallery_frames or gallery_audio" -v`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/server/app.py tests/test_server.py
+git commit -m "feat(server): #193 - GET /api/gallery/{name}/frames returns moments, a contact sheet or seam pairs"
+```
+
+---
+
+### Task 6: `get_output_frames` MCP tool
+
+**Files:**
+- Modify: `dw_mcp/media.py` (new handler + a budget helper)
+- Modify: `dw_mcp/server.py` (tool after `get_output_audio`; `get_output_image` docstring; the instructions block ~line 116 and ~143)
+- Modify: `tests/test_mcp_server.py` (`EXPECTED_TOOLS`, `TOOL_WIRING`, `WRAPPER_HANDLER_MAP`), `tests/test_mcp_media.py`
+- Modify: `docs/MCP.md` (tool count, table row, the numbered loop ~line 376)
+
+**Interfaces:**
+- Consumes: Task 5's route and JSON shape; `_encode_within_budget` / `MAX_RETURNED_BYTES` in `dw_mcp/media.py`.
+- Produces: `media.get_output_frames(client, name, at=None, seams=None, count=None, boundaries=None, names=None, max_dimension=512, workspace=None) -> {name, frame_count, fps, tiles: [{label, frame, seconds, data, mime_type, width, height}], downscaled_to: int | None}`; the MCP tool returns `[ImageContent, ..., TextContent]`.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/test_mcp_media.py - add
+
+from dw_mcp.media import get_output_frames
+
+
+def tile_json(width, height, label="00:00.0 (frame 0)", frame=0, seconds=0.0):
+    return {
+        "label": label,
+        "frame": frame,
+        "seconds": seconds,
+        "data": base64.b64encode(png_bytes(width, height)).decode("ascii"),
+        "mime_type": "image/png",
+        "width": width,
+        "height": height,
+    }
+
+
+def frames_server(tiles, seen=None):
+    def handler(request):
+        if seen is not None:
+            seen.append((request.url.path, list(request.url.params.multi_items())))
+        return httpx.Response(
+            200,
+            json={
+                "name": "x.mp4",
+                "frame_count": 24,
+                "fps": 6.0,
+                "width": 64,
+                "height": 32,
+                "tiles": tiles,
+            },
+        )
+
+    return DwClient(transport=httpx.MockTransport(handler))
+
+
+def test_frames_are_asked_for_by_moment_and_come_back_labelled():
+    seen = []
+    client = frames_server(
+        [tile_json(64, 32), tile_json(64, 32, "00:02.0 (frame 12)", 12, 2.0)], seen
+    )
+
+    result = get_output_frames(client, "run/x.mp4", at=[0.0, "frame:12"])
+
+    assert seen[0][0] == "/api/gallery/run%2Fx.mp4/frames"
+    assert ("at", "0.0") in seen[0][1] and ("at", "frame:12") in seen[0][1]
+    assert [t["label"] for t in result["tiles"]] == [
+        "00:00.0 (frame 0)",
+        "00:02.0 (frame 12)",
+    ]
+    assert result["downscaled_to"] is None
+
+
+def test_seams_send_boundaries_and_names():
+    seen = []
+    client = frames_server([tile_json(128, 32, "seam 1: a | b", 8, 1.33)], seen)
+
+    get_output_frames(
+        client, "cut.mp4", seams=[1], boundaries=[8, 16], names=["a", "b", "c"]
+    )
+
+    params = dict(seen[0][1])
+    assert params["seams"] == "1"
+    assert params["boundaries"] == "8,16"
+    assert params["names"] == "a,b,c"
+
+
+def test_two_selectors_are_refused_before_any_request():
+    client = frames_server([])
+
+    with pytest.raises(DwApiError, match="one of"):
+        get_output_frames(client, "x.mp4", at=[0.0], count=4)
+
+
+def test_tiles_over_budget_are_shrunk_together_and_say_so():
+    # three noisy 2048x1024 tiles: well over 4MB base64 between them
+    tiles = []
+    for n in range(3):
+        tiles.append(
+            {
+                **tile_json(2048, 1024, frame=n, seconds=float(n)),
+                "data": base64.b64encode(noise_png_bytes(2048, 1024, seed=n)).decode(
+                    "ascii"
+                ),
+            }
+        )
+    client = frames_server(tiles)
+
+    result = get_output_frames(client, "x.mp4", at=[0, 1, 2], max_dimension=2048)
+
+    total = sum(len(t["data"]) for t in result["tiles"])
+    assert total <= MAX_RETURNED_BYTES
+    assert len(result["tiles"]) == 3  # shrunk, not dropped
+    assert result["downscaled_to"] is not None and result["downscaled_to"] < 2048
+    assert all(decoded(t).width == result["tiles"][0]["width"] for t in result["tiles"])
+```
+
+In `tests/test_mcp_server.py`: add `"get_output_frames"` to `EXPECTED_TOOLS`; add the wiring row
+
+```python
+(
+    (
+        "get_output_frames",
+        {"name": "out.mp4", "count": 2},
+        "GET",
+        "/api/gallery/out.mp4/frames",
+    ),
+)
+```
+
+and in `test_each_tool_calls_its_endpoint`'s handler add, before the `/outputs/` branch:
+
+```python
+if request.url.path.endswith("/frames"):
+    return httpx.Response(
+        200,
+        json={
+            "name": "out.mp4",
+            "frame_count": 2,
+            "fps": 6.0,
+            "width": 1,
+            "height": 1,
+            "tiles": [
+                {
+                    "label": "contact sheet, 2 frames",
+                    "frame": 0,
+                    "seconds": 0.0,
+                    "data": base64.b64encode(PNG_1X1).decode("ascii"),
+                    "mime_type": "image/png",
+                    "width": 1,
+                    "height": 1,
+                }
+            ],
+        },
+    )
+```
+
+and `"get_output_frames": (media, "get_output_frames")` to `WRAPPER_HANDLER_MAP`.
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `venv/bin/python -m pytest tests/test_mcp_media.py tests/test_mcp_server.py -k "frames or wiring or tool_count" -v`
+Expected: FAIL - `ImportError: cannot import name 'get_output_frames'`, wiring table mismatch, tool count mismatch.
+
+- [ ] **Step 3: Write the handler**
+
+In `dw_mcp/media.py`:
+
+```python
+def get_output_frames(
+    client,
+    name,
+    at=None,
+    seams=None,
+    count=None,
+    boundaries=None,
+    names=None,
+    max_dimension=512,
+    workspace=None,
+):
+    """Frames of a generated video as images - the way to *see* a clip when
+    there is no video content type to return it as (#193, #210). One
+    selector per call: `at` (moments: seconds, or "frame:N"), `count` (an
+    evenly spaced contact sheet) or `seams` (True, or seam numbers from 1:
+    the last frame before and the first frame after each boundary, side by
+    side). `boundaries` is the list of frame indexes each shot after the
+    first starts at, `names` the shots' names - both needed with `seams`
+    until a joined file carries its own.
+
+    Every tile is fitted to `max_dimension`; when the whole answer would
+    still exceed MAX_RETURNED_BYTES the tiles are shrunk *together* - the
+    same dimension for all, halved until they fit - rather than any being
+    dropped, and `downscaled_to` says what they were shrunk to. A seam
+    pair at half size is still a seam pair; a seam pair missing is a
+    different answer."""
+    chosen = [
+        key for key, value in (("at", at), ("count", count), ("seams", seams)) if value
+    ]
+    if len(chosen) != 1:
+        raise DwApiError(
+            "Pass exactly one of `at`, `count` or `seams`"
+            + (f" - got {', '.join(chosen)}" if chosen else "")
+        )
+    params = [("max_dimension", str(max(MIN_DIMENSION, int(max_dimension))))]
+    if at:
+        params += [("at", str(moment)) for moment in at]
+    elif count:
+        params.append(("count", str(int(count))))
+    else:
+        params.append(
+            ("seams", "true" if seams is True else ",".join(str(s) for s in seams))
+        )
+        if boundaries:
+            params.append(("boundaries", ",".join(str(int(b)) for b in boundaries)))
+        if names:
+            params.append(("names", ",".join(names)))
+
+    body = client.get_json(
+        api_path("api", "gallery", name, "frames"), params=params, workspace=workspace
+    )
+    tiles, downscaled_to = _fit_tiles_within_budget(body.get("tiles", []))
+    return {
+        "name": name,
+        "frame_count": body.get("frame_count"),
+        "fps": body.get("fps"),
+        "tiles": tiles,
+        "downscaled_to": downscaled_to,
+    }
+
+
+def _fit_tiles_within_budget(tiles):
+    """Shrink every tile by the same factor until their base64 sizes sum
+    to MAX_RETURNED_BYTES or less. Returns (tiles, downscaled_to) with
+    downscaled_to None when nothing had to shrink."""
+    total = sum(len(tile["data"]) for tile in tiles)
+    if total <= MAX_RETURNED_BYTES or not tiles:
+        return tiles, None
+    images = [Image.open(io.BytesIO(base64.b64decode(tile["data"]))) for tile in tiles]
+    for image in images:
+        image.load()
+    limit = max(max(image.width, image.height) for image in images)
+    while True:
+        limit = max(MIN_DIMENSION, limit // 2)
+        shrunk = []
+        for tile, image in zip(tiles, images):
+            sized = _fit(image, limit)
+            buffer = io.BytesIO()
+            sized.save(buffer, format="PNG")
+            encoded = base64.b64encode(buffer.getvalue()).decode("ascii")
+            shrunk.append(
+                {**tile, "data": encoded, "width": sized.width, "height": sized.height}
+            )
+        if (
+            sum(len(t["data"]) for t in shrunk) <= MAX_RETURNED_BYTES
+            or limit <= MIN_DIMENSION
+        ):
+            return shrunk, limit
+        images = [Image.open(io.BytesIO(base64.b64decode(t["data"]))) for t in shrunk]
+```
+
+Check `client.get_json` accepts `params` (read `dw_mcp/client.py`'s `get_json`); it does for `get_gallery_metadata` (`params={"envelope": "true"}`), and a list of pairs is what httpx wants for a repeated `at` - confirm httpx accepts a list of tuples for `params` (it does).
+
+- [ ] **Step 4: Register the tool**
+
+In `dw_mcp/server.py` after `get_output_audio`:
+
+```python
+def get_output_frames(
+    name: str,
+    at: list[str | float] | None = None,
+    seams: bool | list[int] | None = None,
+    count: int | None = None,
+    boundaries: list[int] | None = None,
+    names: list[str] | None = None,
+    max_dimension: int = 512,
+    workspace: str | None = None,
+) -> list[ImageContent | TextContent]:
+    """See a generated video, named as `list_gallery` or a job's manifest
+    reports it: there is no video content type over MCP, so a clip is
+    looked at as frames (and heard with `get_output_audio`). One
+    selector per call - `count` for an evenly spaced contact sheet of
+    the whole clip (start here: `count=12` shows a clip's shape in one
+    image), `at` for specific moments (seconds, or "frame:N"), or
+    `seams` (true, or seam numbers from 1) for the last frame before
+    and the first frame after each join, side by side - the picture to
+    check a cut or a continuity break against. `seams` needs
+    `boundaries` (the frame index each shot after the first starts at;
+    sum the shots' frame counts from `get_gallery_metadata`) and takes
+    `names` for the shots. Each tile is fitted to `max_dimension`; the
+    text part lists every tile's label, frame and time, and says if the
+    set was shrunk to fit the 4MB budget. What you see here outranks any
+    number `get_gallery_metadata` reports.
+
+    `workspace` names the workspace for this one call without
+    switching the session to it (#99)."""
+    result = media.get_output_frames(
+        client,
+        name,
+        at=at,
+        seams=seams,
+        count=count,
+        boundaries=boundaries,
+        names=names,
+        max_dimension=max_dimension,
+        workspace=workspace,
+    )
+    parts = [
+        ImageContent(type="image", data=tile["data"], mime_type=tile["mime_type"])
+        for tile in result["tiles"]
+    ]
+    lines = [
+        f"name: {result['name']}",
+        f"frame_count: {result['frame_count']}  fps: {result['fps']}",
+    ]
+    for tile in result["tiles"]:
+        lines.append(f"- {tile['label']}  [{tile['width']}x{tile['height']}]")
+    if result["downscaled_to"]:
+        lines.append(
+            f"downscaled_to: {result['downscaled_to']} (every tile, to fit the inline budget)"
+        )
+    parts.append(TextContent(type="text", text="\n".join(lines)))
+    return parts
+```
+
+Register it wherever the file lists tools for `mcp.tool()` (find how `get_output_audio` is registered - `grep -n "get_output_audio" dw_mcp/server.py` - and mirror it exactly).
+
+Then edit `get_output_image`'s docstring: replace "Images only: audio is `get_output_audio`'s and video is refused, so inspect a video with `get_gallery_metadata` or hand the user the file." with "Images only: a soundtrack is `get_output_audio`'s and a video's frames are `get_output_frames`'s."
+
+In the instructions block (~line 116) change "`get_output_image` to actually look at what was made and say whether it answers the request." to "`get_output_image` (a still), `get_output_frames` (a video, as a contact sheet or the frames either side of each seam) and `get_output_audio` (a soundtrack, or an excerpt of one) to actually look at and listen to what was made and say whether it answers the request."
+
+- [ ] **Step 5: Update `docs/MCP.md`**
+
+- Line ~190: bump the stated tool count by one (read the current number; `test_the_stated_tool_count_is_the_registered_one` checks it).
+- Add a table row after `get_output_audio`'s:
+
+```
+| `get_output_frames(name, at=None, seams=None, count=None, boundaries=None, names=None, max_dimension=512, workspace=None)` | `name`, `at`, `seams`, `count`, `boundaries`, `names`, `max_dimension`, `workspace` | See a generated video as frames, since there is no video content type over MCP (#193). One selector per call: `count` for an evenly spaced contact sheet, `at` for moments (seconds or `"frame:N"`), `seams` (true, or seam numbers from 1) for the last frame before and first frame after each join side by side - with `boundaries`, the frame index each shot after the first starts at, and `names`. Tiles are fitted to `max_dimension` and, when the set would exceed the 4MB budget, shrunk together rather than dropped; the text part lists each tile and says so |
+```
+
+- Line ~376, the numbered loop: after "5. `get_output_image(name)` to look at a result image" add "6. `get_output_frames(name, count=12)` to look at a result video, and `get_output_audio(name, start, duration)` to hear it" and renumber what follows.
+
+- [ ] **Step 6: Run the whole MCP and docs suites**
+
+Run: `venv/bin/python -m pytest tests/test_mcp_media.py tests/test_mcp_server.py tests/test_mcp_client.py tests/test_docs_links.py tests/test_server_mcp.py -q`
+Expected: PASS, including `test_the_wiring_table_covers_every_registered_tool`, `test_the_stated_tool_count_is_the_registered_one`, `test_wrapper_handler_map_covers_every_defaulted_handler`, and `TestNoEngineImport` (the `dw_mcp` no-`dw` import guard - `media.py` uses PIL only).
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add dw_mcp/media.py dw_mcp/server.py docs/MCP.md tests/test_mcp_media.py tests/test_mcp_server.py
+git commit -m "feat(mcp): #193 - get_output_frames, a video seen as moments, a contact sheet or seam pairs"
+```
+
+---
+
+### Task 7: Full suite, the mounted MCP surface, and the hand-off
+
+**Files:**
+- Modify: `CLAUDE.md` (the `MCP Server` paragraph is one line pointing at `dw_mcp/CLAUDE.md`; no change needed unless the count of "seven tools require acknowledged_cost" sentence there needs one - it does not, nothing here is gated)
+- Modify: `docs/proposals/output-assessment.md` - flip the Status line's "No code changes yet" to "Stage 1 (evidence) landed on `develop` as <sha>".
+
+- [ ] **Step 1: Run the full suite**
+
+Run: `venv/bin/python -m pytest -q -x`
+Expected: PASS. Two places may break that no task above named: (a) `tests/test_server_mcp.py` exercises the *mounted* MCP surface (`dw.serve --mcp`), which registers the same tools - a snapshot of tool names there gains `get_output_frames`; (b) any test asserting `get_output_audio`'s old `/outputs` refusal wording for `video/mp4`. Fix each by updating the expectation to the new behaviour, never by weakening the new code.
+
+- [ ] **Step 2: Try it against a real file**
+
+```bash
+venv/bin/python -m dw.serve &   # from a checkout with an outputs/ holding one mp4
+# in another shell, with the MCP server pointed at it:
+#   get_output_frames(name="<some>.mp4", count=8)
+#   get_output_audio(name="<some>.mp4", start=0, duration=2)
+```
+
+Confirm the frames arrive as images in the client and the audio part plays. Note the response time on a 300-frame clip; `frames_at` with three moments should be well under a second.
+
+- [ ] **Step 3: Finish the branch**
+
+Use the `superpowers:finishing-a-development-branch` skill: merge `feat/193-evidence` into `develop` with a merge commit (the repo's pattern is `Merge branch 'fix/...' into develop`), do not push or deploy without asking - lem deploys are a separate, explicit step in this repo (see memory: lem restart recipe).
+
+- [ ] **Step 4: Note the release items**
+
+Append to whatever release-note draft is open (or open `docs/RELEASING.md`'s "unreleased" section if it has one): `get_output_audio` now reads `GET /api/gallery/{name}/audio`, extracts a video's soundtrack, and takes `start`/`duration`; new tool `get_output_frames`; new routes `/api/gallery/{name}/audio` and `/frames`.
+
+---
+
+## Self-review
+
+**Spec coverage (sections 2 and 5 only - this is stage 1):**
+- `get_output_frames` with `at` / `seams` / `count`, same budget path, halve-before-drop, says which - Tasks 4, 5, 6. ✔
+- `get_output_audio` mux-aware, moves to the gallery route, `start`/`duration`, `excerpt: {start, duration, of}`, whole-file refusal kept, audio-only file served as-is - Tasks 1, 2, 3. ✔
+- Routes accept `asset:` and `workspace`; paths through `_output_file`/`_asset_file` - Tasks 2, 5. ✔
+- Runs in the server process as a sync `def` - Tasks 2, 5. ✔
+- `media.shots` in metadata, and `seams` reading boundaries from the manifest/file - **stage 2, deliberately not here**; the route and tool take `boundaries` explicitly and their docstrings say why.
+- Tool descriptions and the instructions block name the new tools; `dw_mcp/CLAUDE.md` and `docs/MCP.md` updated - Tasks 3, 6. ✔
+- `minimax-h3` step 4 rewrite - **stage 4**, per the spec's staging.
+
+**Placeholder scan:** none - every step has its code or its exact edit.
+
+**Type consistency:** `extract_audio -> (bytes, dict)` used by Task 2 as `data, info`; header names `X-DW-Duration` / `X-DW-Excerpt-Start` / `X-DW-Excerpt-Duration` match between Task 2 (set) and Task 3 (read, lower-cased by httpx); `get_media_if` returns a 3-tuple in Task 3 and `get_bytes_if` keeps its 2-tuple for `get_output_image`/`get_output_text`; `Tile` dict keys `label/frame/seconds/image` in Task 4 become `label/frame/seconds/data/mime_type/width/height` in Task 5 (`_encoded_tile` strips `image`, keeps `frames` on a contact sheet), and Task 6 reads exactly those; `boundaries` is a frame-index list everywhere.
diff --git a/dw/arguments.py b/dw/arguments.py
index a0da8751..b6111251 100644
--- a/dw/arguments.py
+++ b/dw/arguments.py
@@ -116,7 +116,7 @@ def realize_args(arg, base_dir=None):
             # library, and does it first: what it stands for is a path, so
             # everything below - the media conventions, an object's
             # 'from_file' - then handles it as the path it always was
-            if is_path_reference(v) or isinstance(v, list):
+            if is_path_reference(v) or isinstance(v, (list, dict)):
                 v = arg[k] = resolve_path_references(v, base_dir)
             # A constant resolves under any argument name, and before the
             # conventions below - what it holds is the value, not a file to load
@@ -212,7 +212,12 @@ def resolve_path_references(value, base_dir=None):
     A list is walked in place, because an 'image' argument may be a list of
     references and the key conventions hand the whole list to the loader at
     once - by then it is too late for a reference to be recognized.
-    Dictionaries are left alone: realize_args recurses into those itself,
+    A {"location": ...} dict is walked the same way, for the same reason: the
+    media conventions hand the whole dict to the loader, which reads the
+    location out of it and joins it onto the workflow directory - so
+    {"location": "asset:x.png"} passed validation (which sees every string)
+    and then failed the run on a path that was never resolved. Other
+    dictionaries are left alone: realize_args recurses into those itself,
     and each of their values reaches this on the way through.
     """
     if is_asset_reference(value):
@@ -222,6 +227,8 @@ def resolve_path_references(value, base_dir=None):
     if isinstance(value, list):
         for index, item in enumerate(value):
             value[index] = resolve_path_references(item, base_dir)
+    elif isinstance(value, dict) and is_path_reference(value.get("location")):
+        value["location"] = resolve_path_references(value["location"], base_dir)
     return value
 
 
diff --git a/dw/host_memory_projection.py b/dw/host_memory_projection.py
new file mode 100644
index 00000000..63488b83
--- /dev/null
+++ b/dw/host_memory_projection.py
@@ -0,0 +1,162 @@
+"""Whether a list-driven or composed run is projected to exceed host RAM.
+
+`dw/host_memory.py` reads what a *running* worker is holding; this module is
+the pre-flight half, for the failure mode `device_memory_stats`/VRAM warnings
+never covered - a `for_each` that keeps its pipeline resident across a
+12-entry list, or a per-clip step whose footprint scales with the list, can
+SIGKILL on host RAM with the accelerator nowhere near full (#243).
+
+Scope is v1, by the repo owner's own sign-off on the issue: observed, not
+curated (no author-declared memory figure - `host_memory_peak_rss_mb` is a
+worker-reported field, not a schema key); warn, not refuse (host RAM headroom
+is a property of *this machine*, not something a caller chose, so it never
+blocks a run); no cross-machine normalization; and a cold start - no history
+for this workflow at all - means no check, the same rule `observed_cost.py`
+uses for GPU minutes.
+"""
+
+import json
+import logging
+
+from .for_each import FOR_EACH_KEY
+
+logger = logging.getLogger("dw")
+
+# The fraction of physical RAM a projected peak may reach before this module
+# says anything - matches nothing else in the codebase; there is no existing
+# "safe headroom" constant to share, because nothing else projects against
+# the machine's total RAM rather than a curated figure.
+CEILING_FRACTION = 0.9
+
+_RELEASE_FLAGS = ("release_pipeline", "release_models")
+
+
+def releases_between_iterations(definition):
+    """Whether every `for_each` step in this workflow drops its pipeline (or
+    its models) between entries, rather than holding it resident for the
+    whole list.
+
+    `release_pipeline`/`release_models` survive on a for_each step's *last*
+    member only (`dw/for_each.py`), so their presence on the template step is
+    what says the author asked for the resident-vs-released shape here - the
+    same field, read for a different question. A workflow with no `for_each`
+    step at all answers True: there is no list to hold anything resident
+    across, so the "keeps everything resident" projection would not describe
+    it.
+    """
+    for_each_steps = [
+        step
+        for step in definition.get("steps") or []
+        if isinstance(step, dict) and FOR_EACH_KEY in step
+    ]
+    if not for_each_steps:
+        return True
+    return all(
+        any(step.get(flag) for flag in _RELEASE_FLAGS) for step in for_each_steps
+    )
+
+
+def _requested_count(list_entries):
+    """The largest list length the caller's own arguments drive, or None
+    when this run has no list at all - such a run is never the failure mode
+    this module exists for."""
+    if not list_entries:
+        return None
+    counts = [value for value in list_entries.values() if isinstance(value, int)]
+    return max(counts) if counts else None
+
+
+def _row_count(row, list_entries):
+    """The list length a historical row ran with, read from its own stored
+    arguments rather than the current request's - a row that ran a shorter
+    or longer list is still comparable, once divided out, for the resident
+    projection's per-entry figure.
+
+    Only the variable names the *current* request's `list_entries` names are
+    read back, on the assumption that a workflow's list-driving variables
+    are stable across its history - the same assumption `observed_cost.py`
+    makes bucketing by declared `cost_drivers`.
+    """
+    try:
+        arguments = json.loads(row.get("arguments") or "{}")
+    except (TypeError, ValueError):
+        return None
+    if not isinstance(arguments, dict):
+        return None
+    counts = [
+        len(arguments[name])
+        for name in list_entries
+        if isinstance(arguments.get(name), list)
+    ]
+    return max(counts) if counts else None
+
+
+def _already_survived(rows, list_entries, requested, projected_mb):
+    """Whether a run at least as large as this request already finished on
+    this box at or above the projected peak.
+
+    A projection built from this workflow's own history can land above the
+    ceiling for a shape that is itself part of that history - the run being
+    projected already happened and succeeded (#254). `rows` only ever holds
+    successful runs (`JobHistory.finished_runs()`), so a matching row is a
+    completed data point, not a guess: warning about a peak already reached
+    without incident tells a caller nothing they don't already know from ten
+    minutes ago.
+    """
+    for row in rows:
+        peak = row.get("host_memory_peak_rss_mb")
+        if not isinstance(peak, (int, float)) or peak < projected_mb:
+            continue
+        count = _row_count(row, list_entries)
+        if count is not None and count >= requested:
+            return True
+    return False
+
+
+def host_memory_warnings(definition, list_entries, rows, ceiling_mb):
+    """Warnings for a projected host-memory peak this machine cannot hold,
+    or [] when there is nothing to project from or nothing to warn about.
+
+    `rows` are this workflow's finished runs as `JobHistory.finished_runs()`
+    groups them - the same history `observed_cost.py` reads, extended with
+    `host_memory_peak_rss_mb` per row (#243). `ceiling_mb` is this box's own
+    RAM, scaled by `CEILING_FRACTION`; the caller reads that once per request
+    rather than this module importing `host_memory` for a per-validate
+    syscall.
+    """
+    requested = _requested_count(list_entries)
+    if requested is None or not rows or not ceiling_mb:
+        return []
+    peaks = [row["host_memory_peak_rss_mb"] for row in rows]
+    peaks = [value for value in peaks if isinstance(value, (int, float))]
+    if not peaks:
+        # Cold start: history exists for this workflow, but no run of it
+        # ever reported a host-memory reading - nothing to project from
+        return []
+    if releases_between_iterations(definition):
+        projected_mb = max(peaks)
+        shape = "the largest single iteration observed"
+    else:
+        per_entry = []
+        for row in rows:
+            peak = row["host_memory_peak_rss_mb"]
+            count = _row_count(row, list_entries)
+            if isinstance(peak, (int, float)) and count:
+                per_entry.append(peak / count)
+        if not per_entry:
+            return []
+        per_entry.sort()
+        median_per_entry = per_entry[len(per_entry) // 2]
+        projected_mb = median_per_entry * requested
+        shape = f"{requested} entries held resident together"
+    if projected_mb <= ceiling_mb:
+        return []
+    if _already_survived(rows, list_entries, requested, projected_mb):
+        return []
+    return [
+        "Projected host memory for this run (~"
+        f"{round(projected_mb)} MB, {shape}) exceeds this machine's usable RAM "
+        f"(~{round(ceiling_mb)} MB) - based on {len(rows)} run(s) of this "
+        "workflow's own history on this machine, not a curated figure. The "
+        "run is not blocked, but it may be killed by the OS partway through."
+    ]
diff --git a/dw/plan.py b/dw/plan.py
index 7999cd4e..2d34469e 100644
--- a/dw/plan.py
+++ b/dw/plan.py
@@ -316,7 +316,15 @@ def estimate(
         return measured
     own = _price(definition.get("cost"), device, list_entries, measured_entries or {})
     minutes = own["minutes"]
-    partial = False
+    # An unpriced parent (own["minutes"] is None) whose total ends up coming
+    # only from a priced child is not a complete figure - the parent's own
+    # steps (a for_each step with no cost block, say) contributed nothing to
+    # it, so the sum understates the run rather than merely omitting a piece
+    # of it (#242). `unpriced` names each contributor that landed here, so a
+    # caller can tell a trivial utility step from an unpriced 12-shot loop
+    # apart rather than just seeing `partial: true` (#252)
+    partial = minutes is None
+    unpriced = [definition.get("id", "workflow")] if partial else []
     for path in _sub_workflow_paths(expanded):
         # A builtin is the parent's to price; a local child prices itself
         raw = read_sub_workflow(path, base_dir, workflow_dir)
@@ -329,16 +337,21 @@ def estimate(
         child = _price(child_cost, device, {}, {})
         if child["minutes"] is None:
             partial = True
+            unpriced.append(path)
         elif minutes is not None:
             minutes += child["minutes"]
         else:
             minutes = child["minutes"]
+    if minutes is None:
+        partial = False
+        unpriced = []
     return {
         "minutes": round(minutes, 1) if minutes is not None else None,
         "basis": own["basis"],
         "device": device,
         "measured_on": own["measured_on"],
         "partial": partial,
+        "unpriced": unpriced,
         "runs": None,
     }
 
@@ -367,6 +380,7 @@ def _observed(observed, device):
         "device": device,
         "measured_on": observed.get("name"),
         "partial": False,
+        "unpriced": [],
         "runs": runs,
     }
 
diff --git a/dw/result.py b/dw/result.py
index f2532362..a6e0d983 100644
--- a/dw/result.py
+++ b/dw/result.py
@@ -74,6 +74,44 @@ def _peak_dbfs(waveform):
     return 20.0 * float(numpy.log10(peak))
 
 
+# Image formats that carry an alpha channel; every other image content type
+# takes the picture flattened over white
+ALPHA_CONTENT_TYPES = {"image/png", "image/webp", "image/gif", "image/tiff"}
+
+
+def flatten_alpha_for(image, content_type, file_name):
+    """The image as the content type can carry it: unchanged when it has no
+    alpha channel or the format keeps one, otherwise composited over white
+    and said out loud.
+
+    Pillow refuses to write mode RGBA as JPEG, and it refused after the whole
+    generation had run - Qwen-Image-2.1 decodes an alpha channel natively,
+    and every image template in the catalog asked for image/jpeg. A warning
+    rather than an error, because the run did what was asked and the file
+    is usable; the warning names the format that would have kept the alpha.
+    """
+    mode = getattr(image, "mode", None)
+    if mode not in ("RGBA", "LA", "PA") or content_type in ALPHA_CONTENT_TYPES:
+        return image
+    from PIL import Image as PILImage
+
+    rgba = image.convert("RGBA")
+    flattened = PILImage.new("RGB", rgba.size, (255, 255, 255))
+    flattened.paste(rgba, mask=rgba.getchannel("A"))
+    if getattr(image, "info", None):
+        flattened.info.update(image.info)
+    emit_warning(
+        f"The image written to {file_name} had an alpha channel that "
+        f"{content_type} cannot carry - it was flattened over white. Set "
+        f"the step's result 'content_type' to 'image/png' to keep the "
+        f"transparency.",
+        kind="alpha_discarded",
+        file=file_name,
+        content_type=content_type,
+    )
+    return flattened
+
+
 def warn_without_headroom(waveform, file_name):
     """Say when the soundtrack about to be written is at or over full scale.
 
@@ -715,6 +753,10 @@ def save_artifact(
                 with open(output_path, "w") as file:
                     file.write(artifact)
             elif hasattr(artifact, "save"):
+                if content_type.startswith("image/"):
+                    artifact = flatten_alpha_for(
+                        artifact, content_type, os.path.basename(output_path)
+                    )
                 if (
                     self.metadata is not None
                     and self.result_definition.get("embed_metadata", False)
diff --git a/dw/server/app.py b/dw/server/app.py
index 97dc3c34..43111a74 100644
--- a/dw/server/app.py
+++ b/dw/server/app.py
@@ -73,6 +73,7 @@
 from ..result import read_embedded_metadata
 from ..media_info import probe_media
 from ..hub_cache import scan_models, delete_model, DownloadManager
+from ..host_memory_projection import CEILING_FRACTION, host_memory_warnings
 from ..plan import build_plan, gate_warnings, unseeded_cache_warnings
 from ..runs import (
     MANIFEST_FILE_NAME,
@@ -1786,8 +1787,29 @@ def validate_workflow(
             answer["plan"]["workspace"] = workspace.name
             answer["plan"]["output_dir"] = workspace.outputs
             answer["warnings"] += gate_warnings(answer["plan"]["downloads_required"])
+            if catalog_name:
+                answer["warnings"] += _host_memory_warnings(
+                    catalog_name, definition, answer["plan"]["list_entries"]
+                )
         return answer
 
+    def _host_memory_warnings(name, definition, list_entries):
+        """Whether this box's own history says the requested list is
+        projected to exceed host RAM (#243) - best effort, since a warning
+        that 500s the free pre-flight would be worse than skipping it."""
+        costs = getattr(app.state, "observed_costs", None)
+        if costs is None:
+            return []
+        try:
+            from ..host_memory import host_memory_stats
+
+            rows = costs.rows_for(name)
+            ceiling_mb = (host_memory_stats().get("total_mb") or 0) * CEILING_FRACTION
+            return host_memory_warnings(definition, list_entries, rows, ceiling_mb)
+        except Exception:
+            logger.debug("host memory projection failed for %s", name, exc_info=True)
+            return []
+
     # ------------------------------------------------------------ workspaces
 
     class WorkspaceRequest(BaseModel):
@@ -2363,6 +2385,11 @@ def enhance(request: EnhanceRequest, ws: Workspace = Depends(selected_workspace)
         **{ext: "image" for ext in ALLOWED_IMAGE_EXTENSIONS},
         **{ext: "video" for ext in ALLOWED_VIDEO_EXTENSIONS},
         **{ext: "audio" for ext in ALLOWED_AUDIO_EXTENSIONS},
+        # Not in the security allowlists above (nothing loads a .txt back
+        # into a pipeline, so it is not a path a run reads), but a
+        # text-shape run's deliverable is a real output and belongs in the
+        # gallery like any other kind (#238)
+        ".txt": "text",
     }
 
     # The allowlist members that are not already-compressed containers -
@@ -2863,9 +2890,14 @@ def _zip_download(entries, filename):
                         # temp file is complete), so it is stored instead.
                         # Everything else - .json, .md, .txt, .bmp, .wav, an
                         # unrecognized extension - deflates, including the
-                        # export zip's text files
+                        # export zip's text files. ".txt" is in MEDIA_KINDS
+                        # (kind "text", #238) but is plain text, not an
+                        # already-compressed container, so it stays out of
+                        # this policy the same way .json and .md do
+                        kind = MEDIA_KINDS.get(extension)
                         stored = (
-                            extension in MEDIA_KINDS
+                            kind is not None
+                            and kind != "text"
                             and extension not in RAW_MEDIA_EXTENSIONS
                         )
                         archive.write(
diff --git a/dw/server/jobs.py b/dw/server/jobs.py
index ab6e6475..28e04f89 100644
--- a/dw/server/jobs.py
+++ b/dw/server/jobs.py
@@ -140,6 +140,13 @@ def __init__(self, db_path):
                 connection.execute(
                     "ALTER TABLE jobs ADD COLUMN acknowledged TEXT DEFAULT 'none'"
                 )
+            # The worker's own high-water mark for this run (#243) - NULL for
+            # a row predating the column and for any run that never reported
+            # one (cancelled/errored before the worker's final memory_info)
+            if "host_memory_peak_rss_mb" not in columns:
+                connection.execute(
+                    "ALTER TABLE jobs ADD COLUMN host_memory_peak_rss_mb REAL"
+                )
 
     def _connect(self):
         return sqlite3.connect(self.db_path, timeout=5)
@@ -152,8 +159,8 @@ def record(self, job):
                 "INSERT OR REPLACE INTO jobs (id, workflow, status, created_at,"
                 " started_at, finished_at, arguments, spec, manifest, warnings,"
                 " error, events, workspace, workflow_name, run_id, run_dir,"
-                " acknowledged) VALUES"
-                " (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+                " acknowledged, host_memory_peak_rss_mb) VALUES"
+                " (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
                 (
                     job.id,
                     job.workflow_name,
@@ -172,6 +179,11 @@ def record(self, job):
                     job.run_id,
                     job.run_dir,
                     job.acknowledged,
+                    # A test double or an older in-memory Job predating this
+                    # column reports None here rather than failing record()
+                    # (#243) - the same "absent means unknown" the column
+                    # itself allows
+                    getattr(job, "host_memory_peak_rss_mb", None),
                 ),
             )
 
@@ -264,13 +276,23 @@ def finished_runs(self):
             rows = connection.execute(
                 "SELECT workflow_name, started_at, finished_at, arguments,"
                 " manifest, INSTR(COALESCE(events, ''), ?) > 0,"
-                " COALESCE(json_array_length(COALESCE(events, '[]')), 0) >= ?"
+                " COALESCE(json_array_length(COALESCE(events, '[]')), 0) >= ?,"
+                " host_memory_peak_rss_mb"
                 " FROM jobs WHERE status = ? AND workflow_name IS NOT NULL"
                 " AND started_at IS NOT NULL AND finished_at IS NOT NULL",
                 (LOADING_MARKER, EVENT_CAP, SUCCEEDED),
             ).fetchall()
         grouped = {}
-        for name, started, finished, arguments, manifest, had_load, at_cap in rows:
+        for (
+            name,
+            started,
+            finished,
+            arguments,
+            manifest,
+            had_load,
+            at_cap,
+            peak_rss_mb,
+        ) in rows:
             grouped.setdefault(name, []).append(
                 {
                     "started_at": started,
@@ -280,6 +302,7 @@ def finished_runs(self):
                     "manifest": manifest,
                     "had_load": bool(had_load),
                     "events_at_cap": bool(at_cap),
+                    "host_memory_peak_rss_mb": peak_rss_mb,
                 }
             )
         return grouped
@@ -429,6 +452,9 @@ def __init__(self, spec):
         self.run_dir = None
         # Which form of cost acknowledgement queued this job (#85)
         self.acknowledged = spec.get("acknowledged") or ACK_NONE
+        # The worker's own high-water mark for this run, from its final
+        # memory_info message - None for a run that never got that far (#243)
+        self.host_memory_peak_rss_mb = 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
@@ -1194,6 +1220,11 @@ def _consume_results(self, job):
             elif message_type == "memory_info":
                 self._record_memory(message.get("info"))
                 job.add_event({"event": "memory", "info": self.last_memory})
+                # The worker's post-run reading, so it survives as a real
+                # column rather than only inside the trimmed event tail (#243)
+                peak = (message.get("info") or {}).get("host_memory_peak_rss_mb")
+                if peak is not None:
+                    job.host_memory_peak_rss_mb = peak
             elif message_type == "success":
                 self._record_manifest(job, message)
                 return (SUCCEEDED, None, None)
diff --git a/dw/step_cache.py b/dw/step_cache.py
index e1a687ec..0473720e 100644
--- a/dw/step_cache.py
+++ b/dw/step_cache.py
@@ -45,11 +45,16 @@
 """
 
 import copy
+import dataclasses
 import itertools
 import logging
 import os
 from collections import OrderedDict
 
+import numpy as np
+import torch
+from PIL import Image
+
 logger = logging.getLogger("dw")
 
 # Monotonic across the process: every put stamps its entry, and a downstream
@@ -98,7 +103,22 @@ def scan(value):
 
 
 def deep_equal(a, b):
-    """Value equality across the JSON-ish types a resolved step definition holds."""
+    """Value equality across the JSON-ish types a resolved step definition holds.
+
+    realize_args runs before the step loop (and before for_each expansion's
+    per-member `from_file` construction), so a resolved argument can be a
+    diffusers reference dataclass wrapping in-memory media - a
+    MiniMaxH3ImageReference, an LTX2ReferenceCondition - built fresh by
+    `from_file()` on every run from the same source file. Two such instances
+    hold identical media but are never `==`: PIL.Image has no value equality
+    (falls back to identity), and comparing torch.Tensor/np.ndarray fields
+    with `==` yields an array rather than a bool, which the dataclass's
+    generated `__eq__` cannot resolve to True/False and which the fallback
+    below (correctly) treats as "cannot tell, so unequal". Left unhandled,
+    that made every for_each member carrying an image/audio/video reference
+    an unconditional cache miss - identical inputs included (#253). These
+    checks give those types real value equality before the generic fallback.
+    """
     if a is b:
         return True
     if type(a) is not type(b):
@@ -107,13 +127,27 @@ def deep_equal(a, b):
         return a.keys() == b.keys() and all(deep_equal(a[k], b[k]) for k in a)
     if isinstance(a, (list, tuple)):
         return len(a) == len(b) and all(deep_equal(x, y) for x, y in zip(a, b))
+    if isinstance(a, Image.Image):
+        return a.mode == b.mode and a.size == b.size and a.tobytes() == b.tobytes()
+    if isinstance(a, np.ndarray):
+        return a.shape == b.shape and a.dtype == b.dtype and bool(np.array_equal(a, b))
+    if isinstance(a, torch.Tensor):
+        return (
+            a.shape == b.shape
+            and a.dtype == b.dtype
+            and bool(torch.equal(a.cpu(), b.cpu()))
+        )
+    if dataclasses.is_dataclass(a) and not isinstance(a, type):
+        return all(
+            deep_equal(getattr(a, f.name), getattr(b, f.name))
+            for f in dataclasses.fields(a)
+        )
     try:
-        # realize_args runs before the step loop, so a resolved argument can
-        # hold a numpy array or a tensor, whose == yields an array rather
-        # than a bool (and an exotic object's == can raise outright). A value
-        # that cannot answer "are these equal" cleanly is treated as unequal:
-        # a cache miss just re-runs the step, where a raised exception would
-        # abort the whole run
+        # An exotic object's == can still raise, or (for a type not caught
+        # above) return something other than a bool. A value that cannot
+        # answer "are these equal" cleanly is treated as unequal: a cache
+        # miss just re-runs the step, where a raised exception would abort
+        # the whole run
         return bool(a == b)
     except (ValueError, TypeError, RuntimeError):
         return False
@@ -160,17 +194,30 @@ def get(
         key = (workflow_id, name)
         entry = self._entries.get(key)
         if entry is None:
+            logger.debug(f"No cache entry for step '{name}' - treating as a miss")
             return None
         if entry["step_seed"] != step_seed:
+            logger.debug(
+                f"Cached result for step '{name}' used a different seed - treating as a miss"
+            )
             return None
         # The output *root* a run was told to write to. A run directory is
         # new every execution and would defeat the cache; the root changing
         # means the caller asked for output somewhere the cached files are not
         if entry["output_dir"] != output_dir:
+            logger.debug(
+                f"Cached result for step '{name}' used a different output_dir - treating as a miss"
+            )
             return None
         if needs_result and not entry["retained"]:
+            logger.debug(
+                f"Cached result for step '{name}' did not retain its Result, and this run needs one - treating as a miss"
+            )
             return None
         if not deep_equal(entry["step_data"], step_data):
+            logger.debug(
+                f"Cached result for step '{name}' has different resolved arguments - treating as a miss"
+            )
             return None
 
         upstream = referenced_result_names([step_data])
diff --git a/dw/task_domains.py b/dw/task_domains.py
index fc7f6704..0993b79e 100644
--- a/dw/task_domains.py
+++ b/dw/task_domains.py
@@ -96,6 +96,7 @@
         "sample_rate": POSITIVE,
     },
     "loop_frames": {"num_frames": POSITIVE},
+    "frame_grid": {"count": POSITIVE, "columns": POSITIVE, "tile_width": POSITIVE},
     "dissolve_videos": {
         "dissolve_frames": NON_NEGATIVE,
         "fade_in_frames": NON_NEGATIVE,
diff --git a/dw/tasks/pair_audio.py b/dw/tasks/pair_audio.py
index b7f9ccd4..320b2833 100644
--- a/dw/tasks/pair_audio.py
+++ b/dw/tasks/pair_audio.py
@@ -102,9 +102,17 @@ def _fit_to_video(waveform, rate, frames, fps, fit):
             video_seconds=video_seconds,
         )
     else:
-        logger.info(
-            f"pair_audio: trimmed the track from {audio_seconds:.2f} s to the "
-            f"{video_seconds:.2f} s of video it is laid over"
+        emit_warning(
+            f"pair_audio: 'fit' trimmed {(have - wanted) / float(rate):.2f} s "
+            f"off the {audio_seconds:.2f} s track to reach the "
+            f"{video_seconds:.2f} s of video it is laid over - that part of "
+            f"the track, whatever it held, is gone from the deliverable. A "
+            f"shorter track, or more frames, is what keeps it.",
+            kind="audio_trimmed_to_video",
+            command="pair_audio",
+            audio_seconds=audio_seconds,
+            video_seconds=video_seconds,
+            trimmed_seconds=(have - wanted) / float(rate),
         )
     return fitted
 
diff --git a/dw/tasks/task.py b/dw/tasks/task.py
index 288273f5..d0fcecff 100644
--- a/dw/tasks/task.py
+++ b/dw/tasks/task.py
@@ -231,6 +231,15 @@ def _handle_loop_frames(task, arguments, previous_pipelines):
     return loop_frames(**arguments)
 
 
+@register_command("frame_grid", implementation="dw.tasks.video_utils.frame_grid")
+def _handle_frame_grid(task, arguments, previous_pipelines):
+    """Tile evenly sampled frames of a video into one contact-sheet image"""
+    logger.debug("Building frame grid")
+    from .video_utils import frame_grid
+
+    return frame_grid(**arguments)
+
+
 @register_command("pair_audio", implementation="dw.tasks.pair_audio.pair_audio")
 def _handle_pair_audio(task, arguments, previous_pipelines):
     """Pair a video's frames with an audio track generated beside them"""
diff --git a/dw/tasks/video_utils.py b/dw/tasks/video_utils.py
index f636ac94..ba92b02f 100644
--- a/dw/tasks/video_utils.py
+++ b/dw/tasks/video_utils.py
@@ -8,6 +8,7 @@
 """
 
 import logging
+import math
 import re
 
 import numpy
@@ -173,6 +174,123 @@ def loop_frames(video, num_frames):
     return numpy.concatenate([frames] * laps, axis=0)[:num_frames]
 
 
+def frame_grid(video, count=12, columns=None, tile_width=320, label=True):
+    """Task command: tile evenly sampled frames of a video into one contact
+    sheet - a preview of a clip's shape without authoring a frames-extraction
+    workflow (#245).
+
+    Args:
+        video: Frames in any shape a result carries
+        count: How many frames to sample, spaced evenly across the clip's
+            full duration (including its first and last frame). Clamped to
+            the clip's own frame count when the clip is shorter
+        columns: Tiles per row. Defaults to a grid biased wide - clips are
+            usually landscape - with the last row left-justified when
+            `count` is not a perfect multiple of it
+        tile_width: Width in pixels of each tile; height follows the source
+            frame's aspect ratio
+        label: Burn the sampled timestamp (or frame index, when the video
+            carries no frame rate) into each tile's corner
+
+    Returns:
+        One PIL image, the tiled contact sheet
+    """
+    count = _positive_int(count, "frame_grid", "count")
+    if columns is not None:
+        columns = _positive_int(columns, "frame_grid", "columns")
+    tile_width = _positive_int(tile_width, "frame_grid", "tile_width")
+    if not isinstance(label, bool):
+        raise ValueError(f"frame_grid needs 'label' as true or false, got {label!r}")
+
+    total = frame_count(video)
+    if total == 0:
+        raise ValueError("frame_grid was given a video with no frames")
+    count = min(count, total)
+    fps = getattr(video, "fps", None)
+
+    indices = _evenly_spaced_indices(total, count)
+    tiles = [
+        _grid_tile(extract_frame(video, index), index, fps, tile_width, label)
+        for index in indices
+    ]
+
+    if columns is None:
+        columns = _default_columns(len(tiles))
+    return _compose_grid(tiles, columns)
+
+
+def _positive_int(value, command, name):
+    if isinstance(value, str):
+        try:
+            value = int(value)
+        except ValueError:
+            raise ValueError(
+                f"{command} needs '{name}' as a whole number, got {value!r}"
+            )
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise ValueError(f"{command} needs '{name}' as a whole number, got {value!r}")
+    if value < 1:
+        raise ValueError(f"{command} needs '{name}' of at least 1, got {value}")
+    return value
+
+
+def _evenly_spaced_indices(total, count):
+    """`count` frame indices spaced evenly across [0, total - 1], inclusive
+    of both ends. Rounding can coincide two spacings on one index in a short
+    clip; those collapse rather than repeating the same frame as a tile."""
+    if count == 1:
+        return [0]
+    raw = numpy.linspace(0, total - 1, num=count)
+    seen = []
+    for value in raw.round().astype(int).tolist():
+        if not seen or seen[-1] != value:
+            seen.append(value)
+    return seen
+
+
+def _default_columns(count):
+    """A grid biased wide: rows no more than columns, columns >= sqrt(count)."""
+    rows = math.isqrt(count) or 1
+    return math.ceil(count / rows)
+
+
+def _grid_tile(frame, index, fps, tile_width, label):
+    tile_height = max(1, round(frame.height * tile_width / frame.width))
+    tile = frame.resize((tile_width, tile_height), Image.LANCZOS).convert("RGB")
+    if not label:
+        return tile
+
+    from PIL import ImageDraw, ImageFont
+
+    text = _format_timestamp(index, fps) if fps else f"#{index}"
+    draw = ImageDraw.Draw(tile)
+    font_size = max(10, tile_width // 16)
+    try:
+        font = ImageFont.truetype("Arial", font_size)
+    except (IOError, OSError):
+        font = ImageFont.load_default(size=font_size)
+    draw.text(
+        (4, 4), text, font=font, fill="white", stroke_width=2, stroke_fill="black"
+    )
+    return tile
+
+
+def _format_timestamp(index, fps):
+    seconds = index / fps
+    minutes, remainder = divmod(seconds, 60)
+    return f"{int(minutes):02d}:{remainder:04.1f}"
+
+
+def _compose_grid(tiles, columns):
+    tile_width, tile_height = tiles[0].size
+    rows = math.ceil(len(tiles) / columns)
+    grid = Image.new("RGB", (columns * tile_width, rows * tile_height), (0, 0, 0))
+    for position, tile in enumerate(tiles):
+        row, col = divmod(position, columns)
+        grid.paste(tile, (col * tile_width, row * tile_height))
+    return grid
+
+
 def is_video(value):
     """Whether a value is a run of frames rather than one image.
 
diff --git a/dw_mcp/assets.py b/dw_mcp/assets.py
index aa76dc02..e7dbadd6 100644
--- a/dw_mcp/assets.py
+++ b/dw_mcp/assets.py
@@ -114,7 +114,20 @@ def _confine_source(path, roots, named):
     )
 
 
-def list_assets(client):
+# What a compact asset entry keeps: enough to name and choose one, nothing
+# that only opening or previewing it needs
+ASSET_SUMMARY_FIELDS = ("name", "reference", "kind", "size", "origin")
+
+
+def _summarised_asset_entries(entries):
+    return [
+        {key: entry.get(key) for key in ASSET_SUMMARY_FIELDS if key in entry}
+        for entry in entries
+        if isinstance(entry, dict)
+    ]
+
+
+def list_assets(client, detail=False):
     """The input media on the server, each with the 'asset:' reference a
     workflow argument carries.
 
@@ -126,8 +139,32 @@ def list_assets(client):
     nearer library hides - present in a farther root but not resolvable by
     'asset:', since the nearer file wins; a shadowed entry carries no 'url'
     because that URL would serve the file that shadows it.
+
+    Compact by default - each `assets`/`shadowed` entry cut to
+    `name`/`reference`/`kind`/`size`/`origin` - because a library that has
+    accumulated months of episode and regression assets answers in the tens
+    of KB otherwise for a question that is usually "what's available and
+    under what name" (#249). Pass `detail=True` for each entry's `folder`,
+    `mtime` and `url` too.
     """
-    return client.get_json("/api/assets")
+    result = client.get_json("/api/assets")
+    if detail:
+        return result
+    assets = result.get("assets")
+    shadowed = result.get("shadowed")
+    if not isinstance(assets, list):
+        return result
+    return {
+        **result,
+        "assets": _summarised_asset_entries(assets),
+        "shadowed": _summarised_asset_entries(shadowed)
+        if isinstance(shadowed, list)
+        else shadowed,
+        "note": (
+            "Compact: each entry is name/reference/kind/size/origin only. "
+            "Call list_assets(detail=True) for folder, mtime and url too."
+        ),
+    }
 
 
 def delete_asset(client, name):
diff --git a/dw_mcp/diagnose.py b/dw_mcp/diagnose.py
index ee08976e..7356a993 100644
--- a/dw_mcp/diagnose.py
+++ b/dw_mcp/diagnose.py
@@ -7,6 +7,7 @@
 progress is polled from the event log.
 """
 
+import os
 import time
 
 from dw_mcp.client import DwApiError, api_path
@@ -19,8 +20,11 @@
 
 # A generation can run for minutes, far longer than an MCP client holds a
 # tool call open, so wait_for_job's own budget stays well under that no
-# matter what a caller asks for.
-MAX_WAIT_SECONDS = 55
+# matter what a caller asks for. Some clients hold a tool call open far
+# longer than the 55s this was tuned against (#248), so a deployment that
+# knows its own harness's tool-call budget can raise the cap with
+# DW_MCP_MAX_WAIT_SECONDS - unset, it stays 55.
+MAX_WAIT_SECONDS = float(os.environ.get("DW_MCP_MAX_WAIT_SECONDS", 55))
 
 COST_REFUSAL = (
     "Running a workflow occupies the GPU for minutes and the engine runs one "
@@ -206,9 +210,12 @@ def wait_for_job(client, job_id, timeout_seconds=20):
 
     `timeout_seconds` is clamped to [0, MAX_WAIT_SECONDS]: a generation can
     run for minutes, far longer than an MCP client holds a tool call open,
-    so this never blocks past a budget kept well under that. Every reply
-    says what was applied - `timeout_applied_seconds` is the budget the
-    call actually ran under, `timeout_requested_seconds` what was asked
+    so this never blocks past a budget kept well under that - 55s by
+    default, raised for a deployment whose harness tolerates a longer tool
+    call via the `DW_MCP_MAX_WAIT_SECONDS` env var, in which case one call
+    can cover a whole short job rather than needing several polls. Every
+    reply says what was applied - `timeout_applied_seconds` is the budget
+    the call actually ran under, `timeout_requested_seconds` what was asked
     for, and `waited_seconds` how long this call blocked - so a caller
     asking for 600 can tell a capped return from an elapsed one rather
     than inferring it from wall clock. Returns as soon as the job's status
diff --git a/dw_mcp/media.py b/dw_mcp/media.py
index 3fb86de4..f3f2711e 100644
--- a/dw_mcp/media.py
+++ b/dw_mcp/media.py
@@ -30,9 +30,14 @@
 MAX_RETURNED_CHARACTERS = 20000
 
 
-def get_output_image(client, name, max_dimension=768, workspace=None):
+def get_output_image(client, name, max_dimension=768, workspace=None, crop=None):
     """One image from the output directory, downscaled, as base64 plus the
-    sizes it went in and came out at."""
+    sizes it went in and came out at.
+
+    `crop` is `[x, y, width, height]` in the original's pixels, cut before
+    the downscale, so a region of a 2K still comes back at 100% where the
+    whole would be shrunk past what a seam or a small element can be read
+    at. Clamped to the image; the box actually cut is reported."""
 
     def is_image(content_type):
         return not content_type or content_type.startswith("image/")
@@ -52,6 +57,10 @@ def is_image(content_type):
         raise DwApiError(f"{name} could not be decoded as an image.")
 
     original_size = [image.width, image.height]
+    if crop is not None:
+        box = _crop_box(crop, image.width, image.height)
+        crop = [box[0], box[1], box[2] - box[0], box[3] - box[1]]
+        image = image.crop(box)
     fmt = "JPEG" if (image.format or "").upper() == "JPEG" else "PNG"
     if image.mode not in ("RGB", "L") and fmt == "JPEG":
         image = image.convert("RGB")
@@ -63,11 +72,31 @@ def is_image(content_type):
         "data": base64.b64encode(encoded).decode("ascii"),
         "mime_type": "image/jpeg" if fmt == "JPEG" else "image/png",
         "original_size": original_size,
+        "crop": crop,
         "returned_size": [sized.width, sized.height],
         "bytes": len(encoded),
     }
 
 
+def _crop_box(crop, width, height):
+    """`[x, y, w, h]` as Pillow's `(left, upper, right, lower)`, clamped to
+    the image. Refused when it is not four non-negative integers, starts
+    outside the image, or has nothing in it."""
+    try:
+        x, y, w, h = (int(v) for v in crop)
+    except (TypeError, ValueError):
+        raise DwApiError(f"crop must be [x, y, width, height] in pixels, got {crop!r}.")
+    if x < 0 or y < 0 or w <= 0 or h <= 0:
+        raise DwApiError(
+            f"crop must have a non-negative origin and a positive size, got {crop!r}."
+        )
+    if x >= width or y >= height:
+        raise DwApiError(
+            f"crop origin ({x}, {y}) lies outside the {width}x{height} image."
+        )
+    return (x, y, min(x + w, width), min(y + h, height))
+
+
 def _encode_within_budget(image, limit, fmt):
     """Shrink until the base64-encoded bytes fit the ceiling. Two loops
     rather than one calculation because compressed size does not follow
diff --git a/dw_mcp/server.py b/dw_mcp/server.py
index fc7bce57..f503ffe9 100644
--- a/dw_mcp/server.py
+++ b/dw_mcp/server.py
@@ -6,6 +6,7 @@
 """
 
 import functools
+import inspect
 from typing import Literal, Optional
 
 from mcp.server.mcpserver import MCPServer
@@ -151,7 +152,17 @@ def build_server(client):
     )
 
     def tool(fn, annotations):
-        server.add_tool(_anticipated(fn), name=fn.__name__, annotations=annotations)
+        # The SDK ships fn.__doc__ verbatim. Python 3.13+ strips a docstring's
+        # common indentation at compile time, 3.12 does not - so without this
+        # every continuation line reaches the agent with eight leading spaces,
+        # about 1_100 tokens of resident surface on the interpreter most
+        # servers run. cleandoc makes the description the same on both.
+        server.add_tool(
+            _anticipated(fn),
+            name=fn.__name__,
+            description=inspect.cleandoc(fn.__doc__ or ""),
+            annotations=annotations,
+        )
 
     # ------------------------------------------------------------- catalog
 
@@ -171,7 +182,10 @@ def list_workflows(
         figures a maintainer measured once on the devices named and wrote
         into the workflow, never derived from this server's job history -
         so null means nobody wrote one down, not that the run is cheap;
-        the answer's `cost_basis` says as much. `observed_minutes` and
+        the answer's `cost_basis` says as much. It is also the mark of an
+        entry that has been run through on a real device: one without a
+        `cost` has only been authored, and its first run is the one that
+        finds what the description could not verify. `observed_minutes` and
         `observed_runs`, when present, are this box's *own* finished runs
         of that workflow - the cold median, model load included, and how
         many runs are behind it. Prefer it when quoting a price for this
@@ -503,7 +517,10 @@ def get_guide(name: str, section: str | None = None) -> dict:
     # --------------------------------------------------------------- media
 
     def get_output_image(
-        name: str, max_dimension: int = 768, workspace: str | None = None
+        name: str,
+        max_dimension: int = 768,
+        workspace: str | None = None,
+        crop: list[int] | None = None,
     ) -> list[ImageContent | TextContent]:
         """Look at a generated image, named as `list_gallery` or a job's
         manifest reports it. Use this to judge output quality - it is the
@@ -513,14 +530,17 @@ def get_output_image(
         with `get_gallery_metadata` or hand the user the file. The image is
         downscaled to `max_dimension` on its longest side; the second part
         of the result reports the size it went in and came out at, so a
-        downscale is never silent.
+        downscale is never silent. `crop` is `[x, y, width, height]` in the
+        original's pixels, cut before the downscale - the way to see a
+        region of a 2K still at 100%, where the whole would be shrunk past
+        what a small element or a tiling seam can be judged at.
 
         `workspace` names the workspace for this one call without
         switching the session to it - the same pin `run_workflow`
         takes, so a job run into another workspace is reachable from
         here without leaving this one (#99)."""
         result = media.get_output_image(
-            client, name, max_dimension=max_dimension, workspace=workspace
+            client, name, max_dimension=max_dimension, workspace=workspace, crop=crop
         )
         image = ImageContent(
             type="image", data=result["data"], mime_type=result["mime_type"]
@@ -530,7 +550,8 @@ def get_output_image(
             text=(
                 f"name: {result['name']}\n"
                 f"original_size: {result['original_size']}\n"
-                f"returned_size: {result['returned_size']}\n"
+                + (f"crop: {result['crop']}\n" if result["crop"] else "")
+                + f"returned_size: {result['returned_size']}\n"
                 f"bytes: {result['bytes']}"
             ),
         )
@@ -641,14 +662,17 @@ def download_output(
 
     # ---------------------------------------------------------------- assets
 
-    def list_assets() -> dict:
+    def list_assets(detail: bool = False) -> dict:
         """List the input media on the server, each with the "asset:"
         reference a workflow argument carries. Look here before asking for
         a file: what a workflow needs may already be there. Entries carry
-        name, kind, size and origin only - for one asset's duration, frame
-        count, fps, sample rate or channels, pass its reference to
-        `get_gallery_metadata`, which reads inputs as well as outputs."""
-        return assets.list_assets(client)
+        name, reference, kind, size and origin only - for one asset's
+        duration, frame count, fps, sample rate or channels, pass its
+        reference to `get_gallery_metadata`, which reads inputs as well as
+        outputs. Pass detail=true for each entry's folder, mtime and url
+        too, needed before naming a shared library's writable/read-only
+        roots or opening the file's preview URL."""
+        return assets.list_assets(client, detail=detail)
 
     def upload_asset(
         file_path: str | None = None,
@@ -741,15 +765,17 @@ def delete_asset(name: str) -> dict:
 
     # ------------------------------------------------------------ workspaces
 
-    def list_workspaces() -> dict:
+    def list_workspaces(detail: bool = False) -> dict:
         """List the server's workspaces and say which one this session is
         working in. Each has its own workflows, assets and outputs; the
         stored prompt library is shared by all of them, and so is the
         shared asset library that `upload_asset(shared=true)` and
         `keep_output(shared=true)` write into - which is how a recurring
         cast stays reachable from the workspace the next piece is made
-        in."""
-        return workspaces.list_workspaces(client)
+        in. Entries carry name, default and usage (files/bytes) only; pass
+        detail=true for each entry's full folder paths (workflows, assets,
+        outputs, prompts, common_assets)."""
+        return workspaces.list_workspaces(client, detail=detail)
 
     def use_workspace(name: str) -> dict:
         """Work in a different workspace for the rest of this session - every
@@ -1069,10 +1095,11 @@ def wait_for_job(job_id: str, timeout_seconds: int = 20) -> dict:
         can call again. Does not queue anything, so no acknowledged_cost.
 
         One call blocks for at most {cap} seconds, no matter what
-        timeout_seconds asks for - an MCP client will not hold a tool call
-        open for a generation's real runtime, which is minutes. A larger
-        value is not honoured, it is clamped, so budget roughly one call per
-        {cap}s of the job. Every reply says which happened: waited_seconds,
+        timeout_seconds asks for - this deployment's cap, set for the tool
+        call budget the MCP client actually holds open. A larger value is
+        not honoured, it is clamped, so budget roughly one call per {cap}s
+        of the job - if {cap} covers the job's whole runtime, one call is
+        enough. Every reply says which happened: waited_seconds,
         timeout_requested_seconds, timeout_applied_seconds and
         timeout_capped.
 
diff --git a/dw_mcp/workspaces.py b/dw_mcp/workspaces.py
index 0c6368be..e323fe6a 100644
--- a/dw_mcp/workspaces.py
+++ b/dw_mcp/workspaces.py
@@ -12,9 +12,43 @@
 from dw_mcp import catalog
 
 
-def list_workspaces(client):
-    """The workspaces on the server, and which one this session is using."""
+# What a compact workspace entry keeps: enough to choose one or judge its
+# size, nothing that only naming its folders needs
+WORKSPACE_SUMMARY_FIELDS = ("name", "default", "usage")
+
+
+def list_workspaces(client, detail=False):
+    """The workspaces on the server, and which one this session is using.
+
+    Compact by default - each entry cut to `name`, `default` and `usage`
+    (files/bytes) - because a server that has accumulated dozens of
+    workspaces across episodes and regression runs answers in the tens of
+    KB otherwise for a question that is usually "which workspaces exist and
+    how big are they" (#249). Pass `detail=True` for each entry's full
+    folder paths (`root`, `workflows`, `assets`, `outputs`, `prompts`,
+    `common_assets`), needed before naming one to `use_workspace` or a
+    remote read.
+    """
     result = client.get_json("/api/workspaces")
+    if not detail:
+        entries = result.get("workspaces")
+        if isinstance(entries, list):
+            result = {
+                **result,
+                "workspaces": [
+                    {
+                        key: entry.get(key)
+                        for key in WORKSPACE_SUMMARY_FIELDS
+                        if key in entry
+                    }
+                    for entry in entries
+                    if isinstance(entry, dict)
+                ],
+                "note": (
+                    "Compact: each entry is name/default/usage only. Call "
+                    "list_workspaces(detail=True) for full folder paths."
+                ),
+            }
     return {**result, "current": client.workspace}
 
 
diff --git a/tests/test_assets.py b/tests/test_assets.py
index d6763eb3..3664d884 100644
--- a/tests/test_assets.py
+++ b/tests/test_assets.py
@@ -118,6 +118,19 @@ def test_a_list_of_assets_resolves(self, asset_dir):
         realize_args(args)
         assert [image.size for image in args["image"]] == [(8, 8), (8, 8)]
 
+    def test_a_location_dict_under_an_image_key_resolves(self, asset_dir):
+        # The form templates/image-edit writes. The dict reaches fetch_image
+        # whole through the key convention, so the reference inside it has to
+        # be resolved before that, not on the recursion that never happens
+        args = {"image": {"location": "asset:iris.png"}}
+        realize_args(args)
+        assert args["image"].size == (8, 8)
+
+    def test_a_location_dict_in_a_media_reference_resolves(self, asset_dir):
+        args = {"anything": {"media_type": "image", "location": "asset:iris.png"}}
+        realize_args(args)
+        assert args["anything"].size == (8, 8)
+
     def test_an_object_built_from_an_asset_resolves(self, asset_dir):
         args = {"reference": {"from_file": "asset:iris.png"}}
         realize_args(args)
diff --git a/tests/test_host_memory_projection.py b/tests/test_host_memory_projection.py
new file mode 100644
index 00000000..c74924be
--- /dev/null
+++ b/tests/test_host_memory_projection.py
@@ -0,0 +1,111 @@
+"""Host-RAM projection for a list-driven or composed run (#243).
+
+Warn, not refuse: this module never fails a run, only says the caller's own
+history projects past what this machine's RAM can hold. Each rule below is a
+way a naive projection would mislead, so each has a test that fails if the
+rule is dropped.
+"""
+
+import json
+
+from dw.host_memory_projection import host_memory_warnings, releases_between_iterations
+
+MB = 1.0
+
+
+def row(peak_mb, arguments=None):
+    return {
+        "arguments": json.dumps(arguments or {}),
+        "host_memory_peak_rss_mb": peak_mb,
+    }
+
+
+def for_each_workflow(release=False):
+    step = {
+        "name": "shot",
+        "for_each": "variable:shots",
+        "task": "noop",
+    }
+    if release:
+        step["release_pipeline"] = True
+    return {"id": "w", "variables": {"shots": []}, "steps": [step]}
+
+
+class TestReleaseDetection:
+    def test_no_for_each_step_is_treated_as_released(self):
+        definition = {"id": "w", "variables": {}, "steps": [{"name": "a"}]}
+        assert releases_between_iterations(definition) is True
+
+    def test_release_pipeline_on_the_for_each_step_is_released(self):
+        assert releases_between_iterations(for_each_workflow(release=True)) is True
+
+    def test_no_release_flag_keeps_the_pipeline_resident(self):
+        assert releases_between_iterations(for_each_workflow(release=False)) is False
+
+
+class TestProjection:
+    def test_cold_start_warns_nothing(self):
+        definition = for_each_workflow(release=False)
+        warnings = host_memory_warnings(definition, {"shots": 12}, [], 10_000 * MB)
+        assert warnings == []
+
+    def test_history_with_no_memory_reading_warns_nothing(self):
+        definition = for_each_workflow(release=False)
+        rows = [
+            {
+                "arguments": json.dumps({"shots": [1, 2, 3]}),
+                "host_memory_peak_rss_mb": None,
+            }
+        ]
+        warnings = host_memory_warnings(definition, {"shots": 12}, rows, 10_000 * MB)
+        assert warnings == []
+
+    def test_resident_pipeline_projects_per_entry_times_requested_count(self):
+        definition = for_each_workflow(release=False)
+        # 3-entry runs each peaked at 3000 MB -> 1000 MB/entry; 12 entries
+        # projects to 12000 MB, over an 8000 MB ceiling
+        rows = [row(3000 * MB, {"shots": [1, 2, 3]}) for _ in range(3)]
+        warnings = host_memory_warnings(definition, {"shots": 12}, rows, 8_000 * MB)
+        assert len(warnings) == 1
+        assert "12000" in warnings[0] or "12,000" in warnings[0]
+
+    def test_resident_pipeline_under_the_ceiling_warns_nothing(self):
+        definition = for_each_workflow(release=False)
+        rows = [row(3000 * MB, {"shots": [1, 2, 3]}) for _ in range(3)]
+        warnings = host_memory_warnings(definition, {"shots": 4}, rows, 8_000 * MB)
+        assert warnings == []
+
+    def test_released_pipeline_projects_the_largest_single_iteration(self):
+        definition = for_each_workflow(release=True)
+        # Released between iterations: projection does not scale with count,
+        # since only one entry's pipeline is ever resident at a time
+        rows = [row(3000 * MB, {"shots": [1, 2, 3]}), row(3200 * MB, {"shots": [1]})]
+        warnings = host_memory_warnings(definition, {"shots": 12}, rows, 8_000 * MB)
+        assert warnings == []
+
+    def test_released_pipeline_over_the_ceiling_still_warns(self):
+        definition = for_each_workflow(release=True)
+        rows = [row(9000 * MB, {"shots": [1, 2, 3]})]
+        warnings = host_memory_warnings(definition, {"shots": 12}, rows, 8_000 * MB)
+        assert len(warnings) == 1
+
+    def test_no_list_in_this_request_warns_nothing(self):
+        definition = for_each_workflow(release=False)
+        rows = [row(9000 * MB, {"shots": [1, 2, 3]})]
+        warnings = host_memory_warnings(definition, {}, rows, 100 * MB)
+        assert warnings == []
+
+    def test_identical_shape_that_already_succeeded_warns_nothing(self):
+        # #254: a 2-entry run that just succeeded at ~62 GB shouldn't warn
+        # about a repeat request for the same 2 entries, even though 62 GB
+        # is itself above the ceiling - it already happened without incident.
+        definition = for_each_workflow(release=False)
+        rows = [row(62197 * MB, {"shots": [1, 2]})]
+        warnings = host_memory_warnings(definition, {"shots": 2}, rows, 57788 * MB)
+        assert warnings == []
+
+    def test_larger_request_than_any_survived_shape_still_warns(self):
+        definition = for_each_workflow(release=False)
+        rows = [row(62197 * MB, {"shots": [1, 2]})]
+        warnings = host_memory_warnings(definition, {"shots": 4}, rows, 57788 * MB)
+        assert len(warnings) == 1
diff --git a/tests/test_mcp_media.py b/tests/test_mcp_media.py
index b03f1b14..721a3c89 100644
--- a/tests/test_mcp_media.py
+++ b/tests/test_mcp_media.py
@@ -80,6 +80,54 @@ def test_a_small_image_is_returned_at_its_own_size():
     assert result["returned_size"] == [64, 48]
 
 
+class TestCrop:
+    """A 2K still cannot be checked for whether a small element reads, or
+    for a decode-tiling seam, through a 768-pixel downscale. `crop` is a
+    box in the original's pixels, cut before the downscale, so a region
+    of the full-resolution file comes back at 100%."""
+
+    def two_tone(self):
+        # left half red, right half blue, 2048 wide
+        image = Image.new("RGB", (2048, 1024), (255, 0, 0))
+        image.paste((0, 0, 255), (1024, 0, 2048, 1024))
+        buffer = io.BytesIO()
+        image.save(buffer, format="PNG")
+        return serving(buffer.getvalue(), "image/png")
+
+    def test_a_crop_returns_that_region_at_full_resolution(self):
+        result = get_output_image(
+            self.two_tone(), "big.png", max_dimension=768, crop=[1000, 0, 400, 300]
+        )
+        image = decoded(result)
+        assert image.size == (400, 300)
+        assert image.getpixel((0, 0)) == (255, 0, 0)
+        assert image.getpixel((399, 0)) == (0, 0, 255)
+        assert result["original_size"] == [2048, 1024]
+        assert result["crop"] == [1000, 0, 400, 300]
+        assert result["returned_size"] == [400, 300]
+
+    def test_a_crop_wider_than_max_dimension_is_still_downscaled(self):
+        result = get_output_image(
+            self.two_tone(), "big.png", max_dimension=256, crop=[0, 0, 1024, 512]
+        )
+        assert decoded(result).size == (256, 128)
+        assert result["crop"] == [0, 0, 1024, 512]
+
+    def test_a_crop_is_clamped_to_the_image(self):
+        result = get_output_image(
+            self.two_tone(), "big.png", max_dimension=768, crop=[1900, 900, 500, 500]
+        )
+        assert decoded(result).size == (148, 124)
+        assert result["crop"] == [1900, 900, 148, 124]
+
+    @pytest.mark.parametrize(
+        "crop", [[0, 0, 0, 10], [-1, 0, 10, 10], [2048, 0, 10, 10], [0, 0, 10], "x"]
+    )
+    def test_an_empty_or_malformed_crop_is_refused(self, crop):
+        with pytest.raises(DwApiError, match="crop"):
+            get_output_image(self.two_tone(), "big.png", crop=crop)
+
+
 def test_a_jpeg_source_comes_back_as_jpeg():
     client = serving(jpeg_bytes(300, 300), "image/jpeg")
 
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index d8d124f1..2033970b 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -170,6 +170,24 @@ async def test_every_tool_has_a_description():
     assert missing == []
 
 
+@pytest.mark.asyncio
+async def test_descriptions_carry_no_docstring_indentation():
+    """The SDK ships `fn.__doc__` verbatim. Python 3.13+ strips a docstring's
+    common indentation at compile time; 3.12 keeps it, so every continuation
+    line reached the agent with eight leading spaces - about 1_100 tokens of
+    the resident surface on the interpreter most servers run, invisible to a
+    test run on a newer one."""
+    tools = await tools_of(server_over(ok({})))
+
+    indented = {
+        name: line
+        for name, tool in tools.items()
+        for line in (tool.description or "").splitlines()
+        if line[:1].isspace()
+    }
+    assert indented == {}
+
+
 @pytest.mark.asyncio
 async def test_read_only_tools_are_annotated_read_only():
     tools = await tools_of(server_over(ok({})))
@@ -261,6 +279,29 @@ def refusing(request):
     assert "dw-serve" in str(caught.value)
 
 
+@pytest.mark.asyncio
+async def test_a_crop_is_cut_and_reported():
+    import io
+    from PIL import Image
+
+    buffer = io.BytesIO()
+    Image.new("RGB", (2048, 1024), (1, 2, 3)).save(buffer, format="PNG")
+    body = buffer.getvalue()
+
+    def serving_png(request):
+        return httpx.Response(200, content=body, headers={"content-type": "image/png"})
+
+    server = server_over(serving_png)
+
+    result = await server.call_tool(
+        "get_output_image", {"name": "out.png", "crop": [1000, 500, 300, 200]}
+    )
+
+    text = result.content[1].text
+    assert "crop: [1000, 500, 300, 200]" in text
+    assert "returned_size: [300, 200]" in text
+
+
 @pytest.mark.asyncio
 async def test_an_image_comes_back_as_an_image_block():
     def serving_png(request):
@@ -1100,7 +1141,11 @@ def test_the_stated_tool_count_is_the_registered_one():
 # 999), and at 13_421 after it (9_138 / 3_283 / 1_000) - the three filter
 # parameters and the docstring that says what the library is for. Set at
 # 13_800, which is room for a tool or two and not room for a second
-# validate_workflow.
+# validate_workflow. Those figures were taken on Python 3.14, which dedents
+# docstrings at compile time; on 3.12 the same surface measured 14_574
+# (descriptions 10_281) until `tool()` began passing the cleandoc'd
+# docstring as the description, since then 13_474 (9_181 / 3_293 / 1_000)
+# on either interpreter. Measure on the interpreter CI runs, or on both.
 # Worth knowing before raising it: four tools are a quarter of the
 # descriptions (validate_workflow 774, wait_for_job 518, list_workflows 482,
 # list_gallery 445), and validate_workflow's `plan.basis` taxonomy and
diff --git a/tests/test_pair_audio_fit.py b/tests/test_pair_audio_fit.py
index 37493d6e..be933198 100644
--- a/tests/test_pair_audio_fit.py
+++ b/tests/test_pair_audio_fit.py
@@ -70,6 +70,15 @@ def test_the_other_direction_pads_and_warns(self, warnings_emitted):
         assert samples(result) == round(744 / FPS * SAMPLE_RATE)
         assert any("padded" in w for w in warnings_emitted)
 
+    def test_trimming_the_track_warns_with_the_seconds_cut(self, warnings_emitted):
+        """The pad direction cannot lose content; the trim direction always
+        can, so it is the one that most needs saying out loud (#246)."""
+        result = pair_audio(cut(248), song(30), sample_rate=SAMPLE_RATE, fit="video")
+        assert samples(result) == round(248 / FPS * SAMPLE_RATE)
+        trimmed = [w for w in warnings_emitted if "trimmed" in w]
+        assert len(trimmed) == 1
+        assert "19.67 s" in trimmed[0]
+
     def test_a_track_that_already_matches_is_left_alone(self, warnings_emitted):
         exact = song(248 / FPS)
         result = pair_audio(cut(248), exact, sample_rate=SAMPLE_RATE, fit="video")
diff --git a/tests/test_plan.py b/tests/test_plan.py
index 7f806a63..d51d7fbf 100644
--- a/tests/test_plan.py
+++ b/tests/test_plan.py
@@ -240,6 +240,7 @@ def test_no_cost_block_is_unknown(self, plan):
             "device": "cuda",
             "measured_on": None,
             "partial": False,
+            "unpriced": [],
             "runs": None,
         }
 
@@ -257,6 +258,7 @@ def test_the_serving_devices_entry_is_the_catalog_figure(self, plan):
             "device": "cuda",
             "measured_on": "4090",
             "partial": False,
+            "unpriced": [],
             "runs": None,
         }
 
@@ -269,6 +271,7 @@ def test_another_devices_entry_is_reported_as_such(self, plan):
             "device": "cuda",
             "measured_on": "M2",
             "partial": False,
+            "unpriced": [],
             "runs": None,
         }
 
@@ -397,6 +400,7 @@ def test_history_is_quoted_when_there_is_no_cost_block(self, plan):
             "device": "cuda",
             "measured_on": "RTX 3090",
             "partial": False,
+            "unpriced": [],
             "runs": 11,
         }
 
@@ -446,6 +450,7 @@ def test_a_composed_child_is_not_added_to_an_observed_figure(self, plan, tmp_pat
         answer = plan(composing("child.json"), observed=observed(minutes=6))["estimate"]
         assert answer["minutes"] == 6.0
         assert answer["partial"] is False
+        assert answer["unpriced"] == []
 
 
 def composing(child_path):
@@ -465,19 +470,50 @@ def test_a_childs_catalog_cost_is_added(self, plan, tmp_path):
         (tmp_path / "child.json").write_text(json.dumps(child))
         answer = plan(composing("child.json"))["estimate"]
         assert (answer["minutes"], answer["partial"]) == (7.0, False)
+        assert answer["unpriced"] == []
 
     def test_a_child_without_a_cost_makes_the_estimate_partial(self, plan, tmp_path):
         (tmp_path / "child.json").write_text(json.dumps({"id": "child", "steps": []}))
         answer = plan(composing("child.json"))["estimate"]
         assert (answer["minutes"], answer["partial"]) == (2.0, True)
+        assert answer["unpriced"] == ["child.json"]
 
     def test_an_unreadable_child_makes_the_estimate_partial(self, plan):
         answer = plan(composing("missing.json"))["estimate"]
         assert (answer["minutes"], answer["partial"]) == (2.0, True)
+        assert answer["unpriced"] == ["missing.json"]
 
     def test_a_builtin_adds_nothing_and_is_not_partial(self, plan):
         answer = plan(composing("builtin:text-to-image.json"))["estimate"]
         assert (answer["minutes"], answer["partial"]) == (2.0, False)
+        assert answer["unpriced"] == []
+
+    def test_an_unpriced_parent_with_a_priced_child_is_partial(self, plan, tmp_path):
+        """A for_each step with no cost block contributes nothing to the
+        total; a composed child's own figure should not be reported as
+        though it were the whole run's (#242)."""
+        child = {"id": "child", "cost": [cost("cuda", 5)], "steps": []}
+        (tmp_path / "child.json").write_text(json.dumps(child))
+        parent = {
+            "id": "parent",
+            "steps": [
+                {"name": "own", "task": {"command": "x", "arguments": {}}},
+                {
+                    "name": "child",
+                    "workflow": {"path": "child.json", "arguments": {}},
+                },
+            ],
+        }
+        answer = plan(parent)["estimate"]
+        assert (answer["minutes"], answer["partial"]) == (5.0, True)
+        assert answer["unpriced"] == ["parent"]
+
+    def test_a_fully_unpriced_workflow_is_unknown_not_partial(self, plan):
+        """No cost block anywhere - 'unknown' already says nobody has a
+        number; 'partial' would wrongly imply some of it is known."""
+        answer = plan({"id": "parent", "steps": []})["estimate"]
+        assert (answer["minutes"], answer["partial"]) == (None, False)
+        assert answer["unpriced"] == []
 
     def test_a_child_measured_on_another_device_is_still_added(self, plan, tmp_path):
         child = {"id": "child", "cost": [cost("mps", 5)], "steps": []}
diff --git a/tests/test_result.py b/tests/test_result.py
index a577b922..6b381549 100644
--- a/tests/test_result.py
+++ b/tests/test_result.py
@@ -1483,6 +1483,65 @@ def test_upmix_warns(self, monkeypatch):
         assert warnings and "mono" in warnings[0].lower()
 
 
+class TestAlphaIntoJpeg:
+    """An RGBA image handed to a JPEG (or WebP-with-metadata) result used to
+    fail the save with Pillow's 'cannot write mode RGBA as JPEG' - after a
+    full generation, on every card, for any pipeline that decodes an alpha
+    channel (Qwen-Image-2.1 does natively). The file is written flattened
+    over white instead, and the flattening is said out loud, since the
+    workflow asked for a format that cannot carry what the pipeline made."""
+
+    def _save(self, monkeypatch, temp_dir, result_def):
+        import dw.result as result_module
+
+        warnings = []
+        monkeypatch.setattr(
+            result_module,
+            "emit_warning",
+            lambda message, **data: warnings.append((message, data)),
+        )
+        result = Result(result_def)
+        result.add_result(Image.new("RGBA", (4, 4), (255, 0, 0, 0)))
+        result.save(temp_dir, "wf-step.0")
+        return warnings
+
+    def test_an_rgba_image_is_flattened_into_the_jpeg(self, monkeypatch):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            warnings = self._save(
+                monkeypatch, temp_dir, {"content_type": "image/jpeg", "save": True}
+            )
+            (name,) = os.listdir(temp_dir)
+            with Image.open(os.path.join(temp_dir, name)) as written:
+                assert written.mode == "RGB"
+                # transparent red over white is white
+                assert written.getpixel((0, 0)) == (255, 255, 255)
+            assert len(warnings) == 1
+            assert warnings[0][1]["kind"] == "alpha_discarded"
+            assert "image/png" in warnings[0][0]
+
+    def test_the_flattening_also_happens_on_the_metadata_path(self, monkeypatch):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            warnings = self._save(
+                monkeypatch,
+                temp_dir,
+                {"content_type": "image/jpeg", "save": True, "embed_metadata": True},
+            )
+            (name,) = os.listdir(temp_dir)
+            with Image.open(os.path.join(temp_dir, name)) as written:
+                assert written.mode == "RGB"
+            assert [data["kind"] for _, data in warnings] == ["alpha_discarded"]
+
+    def test_a_png_keeps_its_alpha_and_says_nothing(self, monkeypatch):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            warnings = self._save(
+                monkeypatch, temp_dir, {"content_type": "image/png", "save": True}
+            )
+            (name,) = os.listdir(temp_dir)
+            with Image.open(os.path.join(temp_dir, name)) as written:
+                assert written.mode == "RGBA"
+            assert warnings == []
+
+
 class TestNoHeadroom:
     """#158: `music-video`'s deliverable came back at +3.26 dBFS and the job
     warned about a 6.4 dB level jump between shots, which is the lesser
diff --git a/tests/test_server.py b/tests/test_server.py
index a69bb0b2..712bafb3 100644
--- a/tests/test_server.py
+++ b/tests/test_server.py
@@ -1202,7 +1202,7 @@ def test_gallery_lists_media_and_reads_metadata(server, tmp_path):
     with server(success_script) as client:
         outputs = tmp_path / "outputs"
 
-        # a plain image, a video stand-in, and a non-media file
+        # a plain image, a video stand-in, and a text deliverable (#238)
         Image.new("RGB", (4, 4)).save(outputs / "plain-gen.0-0.0.png")
         (outputs / "clip-gen.0-0.0.mp4").write_bytes(b"\x00" * 10)
         (outputs / "notes.txt").write_text("not media")
@@ -1222,9 +1222,11 @@ def test_gallery_lists_media_and_reads_metadata(server, tmp_path):
             "plain-gen.0-0.0.png",
             "clip-gen.0-0.0.mp4",
             "meta-gen.0-0.0.png",
+            "notes.txt",
         }
         kinds = {f["name"]: f["kind"] for f in listing["files"]}
         assert kinds["clip-gen.0-0.0.mp4"] == "video"
+        assert kinds["notes.txt"] == "text"
 
         # metadata endpoint: full workflow comes back for the editor
         response = client.get("/api/gallery/meta-gen.0-0.0.png/metadata").json()
@@ -1869,15 +1871,16 @@ def test_the_asset_library_lists_what_it_holds(asset_server, tmp_path):
     (library / "gyre").mkdir(parents=True)
     (library / "iris.png").write_bytes(b"png")
     (library / "gyre" / "voice.wav").write_bytes(b"riff")
-    (library / "notes.txt").write_text("not media")
+    (library / "notes.txt").write_text("a caption, a script - a real asset (#238)")
 
     with asset_server(success_script) as client:
         body = client.get("/api/assets").json()
 
     names = {entry["name"]: entry for entry in body["assets"]}
-    assert set(names) == {"iris.png", "gyre/voice.wav"}
+    assert set(names) == {"iris.png", "gyre/voice.wav", "notes.txt"}
     assert names["iris.png"]["reference"] == "asset:iris.png"
     assert names["gyre/voice.wav"]["kind"] == "audio"
+    assert names["notes.txt"]["kind"] == "text"
     assert body["folders"] == ["", "gyre"]
 
 
@@ -3973,6 +3976,7 @@ def observed(self, name, definition, arguments=None):
             "device": serving,
             "measured_on": "RTX 3090",
             "partial": False,
+            "unpriced": [],
             "runs": 11,
         }
         assert asked == [("Basic", {"prompt": "x"})]
diff --git a/tests/test_step_cache.py b/tests/test_step_cache.py
index 949b7051..8be4f960 100644
--- a/tests/test_step_cache.py
+++ b/tests/test_step_cache.py
@@ -159,16 +159,60 @@ def test_step_cache_miss_when_a_saved_file_was_deleted(tmp_path):
     assert cache.get("w", step_data, 42, set(), "/out", True) is None
 
 
-def test_deep_equal_is_false_rather_than_raising_on_array_values():
+def test_deep_equal_compares_array_values_by_content_rather_than_raising():
     """A realized step argument can hold a numpy array (or a tensor), whose
-    == yields an array, not a bool. That must degrade to a cache miss, not
-    abort the run with 'truth value of an array is ambiguous'."""
+    == yields an array, not a bool - that must not abort the run with 'truth
+    value of an array is ambiguous'. Two arrays with the same content are a
+    match (#253: a from_file() reference rebuilt from an unchanged asset on
+    every run must still compare equal to the entry it was cached under),
+    and two with different content are correctly a miss."""
     numpy = pytest.importorskip("numpy")
 
     a = {"latents": numpy.zeros(4), "steps": 9}
     b = {"latents": numpy.zeros(4), "steps": 9}
+    c = {"latents": numpy.ones(4), "steps": 9}
 
-    assert deep_equal(a, b) is False
+    assert deep_equal(a, b) is True
+    assert deep_equal(a, c) is False
+
+
+def test_deep_equal_matches_a_reconstructed_dataclass_holding_an_image():
+    """#253: a from_file() reference (MiniMaxH3ImageReference,
+    LTX2ReferenceCondition, ...) is a dataclass wrapping in-memory media,
+    rebuilt fresh by realize_args on every run of a for_each member that
+    takes an asset: reference - identical content, but never `is` the same
+    object and never `==` by the dataclass's generated equality, since
+    PIL.Image has no value equality and comparing tensor/array fields with
+    `==` cannot resolve to a bool. Without special-casing these, that made
+    every such step an unconditional cache miss."""
+    from dataclasses import dataclass
+
+    from PIL import Image
+
+    numpy = pytest.importorskip("numpy")
+    torch = pytest.importorskip("torch")
+
+    @dataclass
+    class FakeImageReference:
+        image: object
+        weight: float = 1.0
+
+    def load():
+        # A fresh object each call, like from_file() reloading the same file
+        return FakeImageReference(image=Image.new("RGB", (4, 4), color=(1, 2, 3)))
+
+    assert deep_equal(load(), load()) is True
+    assert (
+        deep_equal(
+            load(), FakeImageReference(image=Image.new("RGB", (4, 4), color=(9, 9, 9)))
+        )
+        is False
+    )
+
+    # The same holds for a reference built straight over an array or tensor
+    assert deep_equal(numpy.zeros((2, 2)), numpy.zeros((2, 2))) is True
+    assert deep_equal(torch.zeros(3), torch.zeros(3)) is True
+    assert deep_equal(torch.zeros(3), torch.ones(3)) is False
 
 
 def test_deep_equal_is_false_when_comparison_raises_a_type_error():
diff --git a/tests/test_video_utils.py b/tests/test_video_utils.py
index cb8f6e7d..114ff3fe 100644
--- a/tests/test_video_utils.py
+++ b/tests/test_video_utils.py
@@ -471,6 +471,108 @@ def test_a_numeric_string_is_taken(self):
         assert len(loop_frames(Image.new("RGB", (2, 2)), "121")) == 121
 
 
+class TestFrameGrid:
+    """#245. A contact sheet for previewing a clip's shape without authoring
+    a frames-extraction workflow."""
+
+    @pytest.fixture
+    def clip(self):
+        from dw.tasks.video_utils import FrameList
+
+        frames = FrameList(
+            Image.new("RGB", (64, 32), (index, 0, 0)) for index in range(30)
+        )
+        frames.fps = 24
+        return frames
+
+    def test_default_tiling(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        grid = frame_grid(clip)
+
+        # count=12 -> rows=isqrt(12)=3, columns=ceil(12/3)=4, tile 320 wide
+        # (source 64x32 halved-aspect at width 320 -> height 160)
+        assert grid.size == (4 * 320, 3 * 160)
+
+    def test_custom_columns(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        grid = frame_grid(clip, count=5, columns=2, tile_width=100)
+
+        # 5 tiles over 2 columns is 3 rows, last row left-justified
+        assert grid.size == (2 * 100, 3 * 50)
+
+    def test_count_is_clamped_to_the_available_frames(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        grid = frame_grid(clip, count=100, tile_width=64)
+
+        # clamped to 30 -> rows=isqrt(30)=5, columns=ceil(30/5)=6
+        assert grid.size == (6 * 64, 5 * 32)
+
+    def test_a_single_tile(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        assert frame_grid(clip, count=1, tile_width=160).size == (160, 80)
+
+    def test_label_true_burns_in_a_timestamp(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        labeled = frame_grid(clip, count=4, tile_width=64, label=True)
+        unlabeled = frame_grid(clip, count=4, tile_width=64, label=False)
+
+        assert numpy.asarray(labeled).tobytes() != numpy.asarray(unlabeled).tobytes()
+
+    def test_label_falls_back_to_frame_index_without_fps(self):
+        from dw.tasks.video_utils import frame_grid
+
+        frames = [Image.new("RGB", (64, 32), (index, 0, 0)) for index in range(10)]
+
+        # No .fps attribute on a bare list - must not raise
+        assert frame_grid(frames, count=4, tile_width=32).size == (2 * 32, 2 * 16)
+
+    def test_a_count_below_one_is_refused(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        with pytest.raises(ValueError, match="count"):
+            frame_grid(clip, count=0)
+
+    def test_a_negative_count_is_refused(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        with pytest.raises(ValueError, match="count"):
+            frame_grid(clip, count=-1)
+
+    def test_a_non_integer_columns_is_refused(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        with pytest.raises(ValueError, match="columns"):
+            frame_grid(clip, columns="many")
+
+    def test_a_non_integer_tile_width_is_refused(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        with pytest.raises(ValueError, match="tile_width"):
+            frame_grid(clip, tile_width=0)
+
+    def test_a_non_bool_label_is_refused(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        with pytest.raises(ValueError, match="label"):
+            frame_grid(clip, label="yes")
+
+    def test_registered_as_a_task_command(self):
+        from dw.tasks.task import _COMMAND_REGISTRY
+
+        assert "frame_grid" in _COMMAND_REGISTRY
+
+    def test_a_numeric_string_count_is_taken(self, clip):
+        """A count that arrived through a `variable:` may still be a string."""
+        from dw.tasks.video_utils import frame_grid
+
+        assert frame_grid(clip, count="4", tile_width=32).size == (2 * 32, 2 * 16)
+
+
 class TestFitAudioToFrames:
     """Codec padding trimmed off a generated track, in whatever layout the
     waveform arrived in.
diff --git a/ui/src/lib/plan.test.ts b/ui/src/lib/plan.test.ts
index 4f218a96..005f3196 100644
--- a/ui/src/lib/plan.test.ts
+++ b/ui/src/lib/plan.test.ts
@@ -15,6 +15,7 @@ const base: Plan = {
     device: 'cuda',
     measured_on: 'RTX 3090',
     partial: false,
+    unpriced: [],
   },
 }
 
@@ -76,6 +77,7 @@ describe('describePlan', () => {
         device: 'cuda',
         measured_on: null,
         partial: false,
+        unpriced: [],
       },
     })
     expect(figure.text).toBe('no measured cost')
@@ -85,9 +87,9 @@ describe('describePlan', () => {
   it('a partial figure names what it is missing', () => {
     const [, figure] = describePlan({
       ...base,
-      estimate: { ...base.estimate, partial: true },
+      estimate: { ...base.estimate, partial: true, unpriced: ['child.json'] },
     })
-    expect(figure.text).toContain('plus a composed workflow with no cost')
+    expect(figure.text).toContain('plus unpriced: child.json')
   })
 
   it('an unknown cache answer and a single step read naturally', () => {
diff --git a/ui/src/lib/plan.ts b/ui/src/lib/plan.ts
index a8a3584b..b4e4b45d 100644
--- a/ui/src/lib/plan.ts
+++ b/ui/src/lib/plan.ts
@@ -62,9 +62,12 @@ export function describePlan(plan: Plan): PlanLine[] {
 }
 
 function figure(plan: Plan): PlanLine {
-  const { minutes, basis, device, measured_on, partial } = plan.estimate
+  const { minutes, basis, device, measured_on, partial, unpriced } =
+    plan.estimate
   const card = measured_on ? `measured on ${measured_on}` : 'measured'
-  const missing = partial ? ', plus a composed workflow with no cost' : ''
+  const missing = partial
+    ? `, plus unpriced: ${(unpriced ?? []).join(', ')}`
+    : ''
   if (basis === 'unknown' || minutes === null) {
     return { text: 'no measured cost', tone: 'warn' }
   }
diff --git a/ui/src/lib/types.ts b/ui/src/lib/types.ts
index ad80c761..d1dabb7c 100644
--- a/ui/src/lib/types.ts
+++ b/ui/src/lib/types.ts
@@ -249,6 +249,10 @@ export interface Plan {
     device: string
     measured_on: string | null
     partial: boolean
+    /** What contributed nothing to `minutes` when `partial` is true - the
+     * workflow's own id when its own steps went unpriced, else the path of
+     * each composed child with no cost block. Empty when `partial` is false. */
+    unpriced: string[]
   }
 }
 
diff --git a/workflows/models/qwen-image-2.1-edit.json b/workflows/models/qwen-image-2.1-edit.json
new file mode 100644
index 00000000..7a95d7d1
--- /dev/null
+++ b/workflows/models/qwen-image-2.1-edit.json
@@ -0,0 +1,69 @@
+{
+    "cost": [
+        {
+            "device": "cuda",
+            "name": "RTX 3090",
+            "vram_gb": 24,
+            "minutes": 4.7
+        }
+    ],
+    "cost_drivers": ["num_inference_steps", "width", "height"],
+    "variables": {
+        "prompt": "recolor this person's hair blonde",
+        "input_image": {
+            "location": "https://pbs.twimg.com/media/HNi-N_eWIAAJfTZ?format=jpg&name=900x900"
+        },
+        "seed": 20260921,
+        "width": 2048,
+        "height": 1024,
+        "output_resolution": 2048,
+        "num_inference_steps": 40
+    },
+    "seed": "variable:seed",
+    "id": "QwenImage21Edit",
+    "description": "Instruction editing with Qwen-Image-2.1: re-renders a supplied picture toward a written instruction, the editing path the unified model advertises and models/qwen-image-2.1 does not exercise. Offload is a property of the mode, not the model: the condition image's latents are prepended to the noise, so an edit at 2048x1024 carries a longer sequence than plain text-to-image at 2048x2048, and under 'model' offload it runs out of memory by 582 MiB on a clean 24GB card - measured, and shape-determined rather than leakage from an earlier job - so this entry runs 'sequential' where the text-to-image entry runs 'model'. output_resolution is set to 2048 so the condition image is not resized down to the pipeline's 1024 default; width/height name the canvas the edit lands on. The VAE is tiled and sliced because the decode at this size does not otherwise fit, and the result is image/png because the pipeline returns RGBA. true_cfg_scale is left at its default of 1.0, so negative_prompt is ignored and the instruction has to be written positively. input_image takes a URL, a path, or an asset: reference - keep_output turns an earlier run's picture into one. Qwen Research License: non-commercial use only - see https://huggingface.co/Qwen/Qwen-Image-2.1/blob/main/LICENSE.",
+    "configures": "templates/image-edit",
+    "variable_constraints": {
+        "width": {
+            "modulus": 32,
+            "remainder": 0,
+            "reason": "Qwen-Image-2.1 rounds width/height down to a multiple of 32 (vae_scale_factor * 2), so an off-grid value is not refused by the pipeline but silently shrunk - refused here instead, with no 'snap', since rounding the other way would be a second silent change to the size asked for"
+        },
+        "height": {
+            "modulus": 32,
+            "remainder": 0,
+            "reason": "Qwen-Image-2.1 rounds width/height down to a multiple of 32 (vae_scale_factor * 2), so an off-grid value is not refused by the pipeline but silently shrunk - refused here instead, with no 'snap', since rounding the other way would be a second silent change to the size asked for"
+        }
+    },
+    "steps": [
+        {
+            "name": "edit",
+            "pipeline": {
+                "configuration": {
+                    "component_type": "QwenImage21Pipeline",
+                    "offload": "sequential",
+                    "vae": {
+                        "enable_slicing": true,
+                        "enable_tiling": true
+                    }
+                },
+                "from_pretrained_arguments": {
+                    "model_name": "Qwen/Qwen-Image-2.1",
+                    "torch_dtype": "torch.bfloat16"
+                },
+                "arguments": {
+                    "prompt": "variable:prompt",
+                    "image": "variable:input_image",
+                    "output_resolution": "variable:output_resolution",
+                    "width": "variable:width",
+                    "height": "variable:height",
+                    "num_inference_steps": "variable:num_inference_steps"
+                }
+            },
+            "result": {
+                "content_type": "image/png",
+                "embed_metadata": true
+            }
+        }
+    ]
+}
diff --git a/workflows/models/qwen-image-2.1.json b/workflows/models/qwen-image-2.1.json
new file mode 100644
index 00000000..89f633b1
--- /dev/null
+++ b/workflows/models/qwen-image-2.1.json
@@ -0,0 +1,68 @@
+{
+    "cost": [
+        {
+            "device": "cuda",
+            "name": "RTX 3090",
+            "vram_gb": 24,
+            "minutes": 4.3
+        }
+    ],
+    "cost_drivers": [
+        "num_images_per_prompt",
+        "num_inference_steps",
+        "width",
+        "height"
+    ],
+    "variables": {
+        "prompt": "A realistic photograph of a mouse wearing a skirt playing volleyball against a team of professional volleyball players.",
+        "num_images_per_prompt": 1,
+        "num_inference_steps": 40,
+        "width": 2048,
+        "height": 2048
+    },
+    "id": "QwenImage2.1",
+    "description": "Text-to-image with Qwen-Image-2.1: a unified 7B model (32 single-stream DiT layers, Qwen3-VL 8B text encoder) that also does instruction editing and native RGBA output; this entry exercises plain text-to-image and models/qwen-image-2.1-edit exercises editing. No guidance_scale - the pipeline takes only true_cfg_scale, which the vendor recommends leaving at its default of 1.0 (off). width/height are set explicitly because the pipeline falls back to a 1024x1024 output_resolution default otherwise, well under the model's native 2K. The result is image/png because the pipeline returns RGBA: a jpeg result would flatten the alpha over white (and warn). The VAE is tiled and sliced because at 2048x2048 on a 24GB card the decode - not the denoise - runs out of memory, with all 40 steps already done. Offload is a property of the mode, not the model: 'model' offload fits plain text-to-image at 2048x2048, but an edit prepends the condition image's latents to the sequence and needs 'sequential' at half those pixels - which is why the edit entry differs. Qwen Research License: non-commercial use only, unlike every other model in this catalog, which are Apache-2.0 - see https://huggingface.co/Qwen/Qwen-Image-2.1/blob/main/LICENSE.",
+    "configures": "templates/text-to-image",
+    "variable_constraints": {
+        "width": {
+            "modulus": 32,
+            "remainder": 0,
+            "reason": "Qwen-Image-2.1 rounds width/height down to a multiple of 32 (vae_scale_factor * 2), so an off-grid value is not refused by the pipeline but silently shrunk - refused here instead, with no 'snap', since rounding the other way would be a second silent change to the size asked for"
+        },
+        "height": {
+            "modulus": 32,
+            "remainder": 0,
+            "reason": "Qwen-Image-2.1 rounds width/height down to a multiple of 32 (vae_scale_factor * 2), so an off-grid value is not refused by the pipeline but silently shrunk - refused here instead, with no 'snap', since rounding the other way would be a second silent change to the size asked for"
+        }
+    },
+    "steps": [
+        {
+            "name": "main",
+            "pipeline": {
+                "configuration": {
+                    "component_type": "QwenImage21Pipeline",
+                    "offload": "model",
+                    "vae": {
+                        "enable_slicing": true,
+                        "enable_tiling": true
+                    }
+                },
+                "from_pretrained_arguments": {
+                    "model_name": "Qwen/Qwen-Image-2.1",
+                    "torch_dtype": "torch.bfloat16"
+                },
+                "arguments": {
+                    "prompt": "variable:prompt",
+                    "num_inference_steps": "variable:num_inference_steps",
+                    "num_images_per_prompt": "variable:num_images_per_prompt",
+                    "width": "variable:width",
+                    "height": "variable:height"
+                }
+            },
+            "result": {
+                "content_type": "image/png",
+                "embed_metadata": true
+            }
+        }
+    ]
+}