From 5f8f910de4ea0f5f35844fe2780dd80b61796f31 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 10 Sep 2026 22:54:20 -0500
Subject: [PATCH 1/3] Stop stabilizing shots in the assembly templates; expose
 seam controls

assemble-and-score and dissolve-between-shots ran every shot through
stabilize_video with smooth 0 under a description that said it only
re-encoded them. smooth 0 is a full first-frame lock: on a shot with a
deliberate camera move it fights the move, crops and rescales every frame,
and nothing downstream notices because duration, size and sample rate all
survive (measured 13-20 dB PSNR against the source vs 45 dB for a plain
cut). The hold steps are gone; the shots go straight into the join, as
one 'shots' list variable so a diptych is two entries and a reel is however
many the cut needs. concat_videos and dissolve_videos now refuse shots of
different sizes by name, which is the check the hold steps were imagined
to be. The catalog shape rule counts a variable-fed or asset-fed cut as a
sequence that needs input media, so the templates keep their listing.

audio_bleed_ms and seam_fade_ms are variables in dialogue-short,
music-video and assemble-and-score, so a seam is re-tuned with an argument
rather than an inline copy of the workflow; dialogue-short defaults to
1800 ms, where a five-shot H3 cut measured best (700 ms left a 44 dB hole
at the worst seam, 1800 brought it to 32, 2500 gained almost nothing).

validate_workflow warns when concat_videos is given a crossfade_ms with
nothing trimmed - the crossfade is drawn from the trimmed material, so at
a hard cut it reads as active and does nothing. The concat_videos and
stabilize_video docs say all of this.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs/TASKS.md                                 | 30 ++++++++---
 dw/introspection.py                           | 19 +++++++
 dw/server/catalog_shape.py                    | 24 +++++++--
 dw/tasks/concat_videos.py                     | 26 ++++++----
 dw/tasks/dissolve_videos.py                   |  3 +-
 dw/tasks/video_utils.py                       | 28 ++++++++++
 tests/test_catalog_shape.py                   | 19 +++++++
 tests/test_concat_videos.py                   |  9 ++++
 tests/test_dissolve_videos.py                 |  6 +++
 tests/test_introspection.py                   | 41 +++++++++++++++
 workflows/templates/assemble-and-score.json   | 52 +++++--------------
 .../templates/dissolve-between-shots.json     | 46 +++-------------
 .../templates/minimax/dialogue-short.json     |  9 ++--
 workflows/templates/minimax/music-video.json  |  6 ++-
 14 files changed, 214 insertions(+), 104 deletions(-)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index 49930833..688d513a 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -200,9 +200,9 @@ video generation" in the workflow guide):
 | -------- | -------- | ----------- |
 | `videos` | Yes | The videos to join, in order - `previous_result` references, or the path or URL of a video file an earlier run wrote, which is read with the audio muxed into it |
 | `trim_frames` | No | Frames dropped from the head of every video after the first (default: 0) |
-| `crossfade_ms` | No | Equal-power crossfade at each audio seam (default: 75) |
+| `crossfade_ms` | No | Equal-power crossfade at each audio seam, drawn from the trimmed material - no effect when `trim_frames` is 0, and validation warns when one is written there (default: 75) |
 | `audio_bleed_ms` | No | How long the outgoing video's tail rings on over the head of the next one, at seams with nothing trimmed to crossfade (default: 0, off) |
-| `seam_fade_ms` | No | Fade on each side of a seam that gets neither a crossfade nor a bleed (default: 3, just enough not to click) |
+| `seam_fade_ms` | No | Fade on each side of a seam that gets neither a crossfade nor a bleed - for tonal material, not for a continuous bed (default: 3, just enough not to click) |
 | `fps` | No | Frame rate of the videos - required to join audio when trimming |
 
 A video may also be named by path or URL, which is how shots an earlier run
@@ -242,7 +242,11 @@ open on near-silence and end mid-sound, leaving a butt-join that drops a running
 laugh track or a ringing room into a hole. `audio_bleed_ms` fills it the way an
 audience carries across a picture cut: a decaying copy of the outgoing tail is laid
 over the incoming head, added to whatever is already there, shortening neither side.
-Reach for a few hundred milliseconds - the MiniMaxH3SitcomShort example uses 700:
+Reach for more than the gap looks like it needs: a shot's head is silent for
+longer than the picture suggests, and the bleed has to outlast it. Measured on
+a five-shot H3 sitcom cut, 700 ms still left a 44 dB hole at the worst seam;
+1800 ms brought it to 32 dB and 2500 ms gained almost nothing more, so the
+`dialogue-short` template defaults to 1800 and exposes it as `audio_bleed_ms`:
 
 ```json
 {
@@ -251,7 +255,7 @@ Reach for a few hundred milliseconds - the MiniMaxH3SitcomShort example uses 700
         "arguments": {
             "videos": ["previous_result:shot_1", "previous_result:shot_2"],
             "trim_frames": 0,
-            "audio_bleed_ms": 700,
+            "audio_bleed_ms": 1800,
             "fps": 24
         }
     },
@@ -265,7 +269,12 @@ phrase or half-spoken word reads as a stutter whichever direction it runs. When
 shot ends on something tonal, either give the cut a continuous bed with
 `slice_audio` + `pair_audio`, which leaves no seam to treat at all, or fade the
 seam gracefully with `seam_fade_ms` (a hundred or so milliseconds) and accept the
-cut. `audio_bleed_ms` wins where both are set and there is material to bleed.
+cut. That advice inverts on a continuous bed - a laugh track, room tone - where a
+longer fade only digs the hole deeper (the same sitcom cut measured 54-59 dB
+holes with a 250-500 ms fade and no bleed). `audio_bleed_ms` wins where both are
+set and there is material to bleed. A bleed covers the gap but cannot fill it:
+the silence is inside the incoming shot's own head, and the only complete fix is
+a continuous bed under the whole cut with `slice_audio` + `pair_audio`.
 
 ### dissolve_videos
 
@@ -335,7 +344,14 @@ before the task ever saw it. Frames are shifted back and the result is cropped
 to the region every frame covers, then resized to the original size; a
 soundtrack passes through untouched.
 
-**Example:** [dissolve-between-shots.json](../workflows/templates/dissolve-between-shots.json)
+It is a stabilization pass, not a format pass. `smooth: 0` on a shot with a
+deliberate camera move fights the move - every frame is shifted back toward
+the first, cropped and rescaled - and nothing downstream will notice, since
+the duration, size and sample rate all survive. Run it on a shot that drifts,
+as its own step; do not run it on every shot before a cut, which is what the
+assembly templates once did and what made their output visibly wider than
+the source. The join tasks refuse shots of different sizes, so no
+normalization step is needed before them.
 
 ### video_frames
 
@@ -1206,4 +1222,4 @@ Canny edge detection followed by ControlNet generation:
 - [audio-trim-fade.json](../workflows/templates/audio-trim-fade.json) — Trim a generated track and fade its tail
 - [generate-speech.json](../workflows/templates/generate-speech.json) — Speak a line with a local text-to-speech model
 - [voice-timbre-reference.json](../workflows/templates/minimax/voice-timbre-reference.json) — Generate a voice and condition H3's `<Audio 1>` on it
-- [dissolve-between-shots.json](../workflows/templates/dissolve-between-shots.json) — Stabilize generated shots, dissolve between them, and mix a score under their own audio
+- [dissolve-between-shots.json](../workflows/templates/dissolve-between-shots.json) — Dissolve between supplied shots and mix a score under their own audio
diff --git a/dw/introspection.py b/dw/introspection.py
index 3db90ef0..08cf9980 100644
--- a/dw/introspection.py
+++ b/dw/introspection.py
@@ -480,6 +480,24 @@ def unknown_task_arguments(command, argument_names):
     return sorted(set(argument_names) - known)
 
 
+def _inert_crossfade_warnings(step, command, arguments):
+    """concat_videos draws its crossfade from the trimmed-off material, so
+    with nothing trimmed a `crossfade_ms` the author wrote does nothing. A
+    referenced trim is unknown until the run and is left alone."""
+    if command != "concat_videos":
+        return []
+    crossfade = arguments.get("crossfade_ms")
+    trim = arguments.get("trim_frames", 0)
+    if not isinstance(crossfade, (int, float)) or crossfade <= 0 or trim != 0:
+        return []
+    return [
+        f"Step '{step.get('name')}': 'crossfade_ms' has no effect when "
+        f"'trim_frames' is 0 - the crossfade is drawn from the trimmed "
+        f"material. At a hard cut, 'audio_bleed_ms' or 'seam_fade_ms' is "
+        f"what shapes the seam"
+    ]
+
+
 def workflow_argument_warnings(workflow_definition):
     """Best-effort pre-load check of a workflow's arguments.
 
@@ -513,6 +531,7 @@ def workflow_argument_warnings(workflow_definition):
                         f"Step '{step.get('name')}': task '{command}' does not "
                         f"accept argument '{argument_name}'"
                     )
+            warnings.extend(_inert_crossfade_warnings(step, command, task["arguments"]))
         pipeline = step.get("pipeline")
         if not pipeline:
             continue
diff --git a/dw/server/catalog_shape.py b/dw/server/catalog_shape.py
index 5241db70..2a706faa 100644
--- a/dw/server/catalog_shape.py
+++ b/dw/server/catalog_shape.py
@@ -51,7 +51,9 @@
 _CHAIN_ARGUMENTS = frozenset(
     {"last_frame", "last_segment", "last_image", "match_audio"}
 )
-_MEDIA_ARGUMENTS = frozenset({"image", "video", "audio", "mask_image", "urls"})
+_MEDIA_ARGUMENTS = frozenset(
+    {"image", "video", "audio", "mask_image", "urls", "videos", "clip"}
+)
 _CUT_TASKS = frozenset({"concat_videos", "dissolve_videos"})
 # Components that exist only to synthesise a waveform. A video pipeline
 # carrying one emits an audio track whether or not it says so in `output`.
@@ -156,11 +158,27 @@ def _needs_input_media(steps):
 
 
 def _cuts_together(steps):
-    """A concat or dissolve fed by two or more distinct steps."""
+    """A concat or dissolve fed by two or more distinct steps, or by a list
+    of shots handed in whole - one `variable:` reference is a supplied list
+    whose length only the caller knows, and a cut over supplied footage is
+    still an edit."""
     for step in steps:
         key, body = _block(step)
         if key == "task" and body.get("command") in _CUT_TASKS:
-            if len(_fed_by(_arguments(step).get("videos"))) >= 2:
+            videos = _arguments(step).get("videos")
+            if isinstance(videos, str) and videos.startswith("variable:"):
+                return True
+            sources = _fed_by(videos)
+            if isinstance(videos, list):
+                # Each supplied shot - a variable, an asset, a path - is its
+                # own source; two previous_result entries naming one step are not
+                sources |= {
+                    item
+                    for item in videos
+                    if isinstance(item, str)
+                    and not item.startswith("previous_result:")
+                }
+            if len(sources) >= 2:
                 return True
     return False
 
diff --git a/dw/tasks/concat_videos.py b/dw/tasks/concat_videos.py
index 4047443c..a5bae35d 100644
--- a/dw/tasks/concat_videos.py
+++ b/dw/tasks/concat_videos.py
@@ -17,7 +17,7 @@
     equal_power_crossfade_join,
     frames_to_samples,
 )
-from .video_utils import frames_as_pil_list, load_audio_video
+from .video_utils import check_same_frame_size, frames_as_pil_list, load_audio_video
 
 logger = logging.getLogger("dw")
 
@@ -42,8 +42,10 @@ def concat_videos(
         trim_frames: Frames dropped from the head of every video after the
             first - the trim used when each video was generated from the
             previous one's last frame
-        crossfade_ms: Equal-power crossfade at each audio seam, clamped to
-            the trimmed material
+        crossfade_ms: Equal-power crossfade at each audio seam, drawn from
+            the trimmed material - so it has no effect when trim_frames is 0,
+            which is where every cut-based workflow sits. A hard cut's seam is
+            shaped by audio_bleed_ms or seam_fade_ms instead
         audio_bleed_ms: How long the outgoing video's tail rings on over the head
             of the next one, at seams with nothing trimmed to crossfade. For
             cut-based workflows, where every shot is generated independently and
@@ -52,7 +54,9 @@ def concat_videos(
         seam_fade_ms: Fade applied on each side of a seam that gets neither a
             crossfade nor a bleed. Defaults to the few milliseconds that keep a
             butt-join from clicking; raise it to a hundred or so for a graceful
-            hard cut on tonal material, which a bleed would only stutter
+            hard cut on tonal material, which a bleed would only stutter. It is
+            the wrong tool for a continuous bed such as a laugh track or room
+            tone: a fade only deepens the hole a bleed is there to cover
         fps: Frame rate of the videos - required to join audio when trimming
 
     Returns:
@@ -61,17 +65,19 @@ def concat_videos(
     if not isinstance(videos, list) or not videos:
         raise ValueError("concat_videos needs a non-empty list of videos")
 
+    # A shot an earlier run already wrote is loaded here rather than by
+    # gather_videos, which reads frames only and would join it silent
+    videos = [load_audio_video(v) if isinstance(v, str) else v for v in videos]
+    clips = [frames_as_pil_list(v) for v in videos]
+    check_same_frame_size(clips, "concat_videos")
+
     frames = []
     audio = None
     sample_rate = None
 
-    for index, video in enumerate(videos):
-        if isinstance(video, str):
-            # A shot an earlier run already wrote - loaded here rather than by
-            # gather_videos, which reads frames only and would join it silent
-            video = load_audio_video(video)
+    for index, (video, clip) in enumerate(zip(videos, clips)):
         head_trim = trim_frames if index > 0 else 0
-        frames.extend(frames_as_pil_list(video)[head_trim:])
+        frames.extend(clip[head_trim:])
 
         if not isinstance(video, AudioVideo) or video.audio is None:
             continue
diff --git a/dw/tasks/dissolve_videos.py b/dw/tasks/dissolve_videos.py
index 614bf5c2..5e57a052 100644
--- a/dw/tasks/dissolve_videos.py
+++ b/dw/tasks/dissolve_videos.py
@@ -19,7 +19,7 @@
 
 from ..result import AudioVideo
 from .audio_utils import as_channels_samples, crossfade_concat
-from .video_utils import frames_as_array, load_audio_video
+from .video_utils import check_same_frame_size, frames_as_array, load_audio_video
 
 logger = logging.getLogger("dw")
 
@@ -59,6 +59,7 @@ def dissolve_videos(
 
     loaded = [load_audio_video(v) if isinstance(v, str) else v for v in videos]
     clips = [frames_as_array(v).astype(numpy.float32) for v in loaded]
+    check_same_frame_size(clips, "dissolve_videos")
 
     for index, clip in enumerate(clips):
         seams = (index > 0) + (index < len(clips) - 1)
diff --git a/dw/tasks/video_utils.py b/dw/tasks/video_utils.py
index 109f53a9..fbbcd2ca 100644
--- a/dw/tasks/video_utils.py
+++ b/dw/tasks/video_utils.py
@@ -61,6 +61,34 @@ def frame_count(video):
     return len(_frames_of(video))
 
 
+def check_same_frame_size(clips, task_name):
+    """Refuse to join clips whose frames disagree in size.
+
+    Args:
+        clips: The clips about to be joined, each a PIL frame list or a
+            (frames, height, width, channels) array
+        task_name: Named in the error
+
+    Joining is frame-by-frame concatenation, which either fails deep in numpy
+    or, for a PIL list, produces a film that changes size mid-cut. Naming the
+    two sizes points at the shot that was rendered differently rather than at
+    the join.
+    """
+    sizes = []
+    for clip in clips:
+        if isinstance(clip, numpy.ndarray):
+            sizes.append((int(clip.shape[2]), int(clip.shape[1])))
+        else:
+            sizes.append(tuple(clip[0].size) if len(clip) else None)
+    first = next((size for size in sizes if size is not None), None)
+    for index, size in enumerate(sizes):
+        if size is not None and size != first:
+            raise ValueError(
+                f"{task_name} needs every video at one size: video 0 is "
+                f"{first[0]}x{first[1]}, video {index} is {size[0]}x{size[1]}"
+            )
+
+
 def frames_as_pil_list(video):
     """The video's frames as a list of PIL images.
 
diff --git a/tests/test_catalog_shape.py b/tests/test_catalog_shape.py
index 2ecd6ade..14a75465 100644
--- a/tests/test_catalog_shape.py
+++ b/tests/test_catalog_shape.py
@@ -527,6 +527,25 @@ def test_a_cut_of_supplied_shots_is_a_sequence_not_a_utility():
     assert meta["shape"] == "sequence"
 
 
+def test_a_cut_of_a_supplied_shot_list_is_a_sequence_that_needs_media():
+    """The assembly templates take their shots as one list variable, so the
+    cut task is fed by a single `variable:` reference rather than by two
+    steps - which is still an edit of supplied footage."""
+    meta = derive_catalog_metadata(
+        definition(
+            task_step(
+                "edit",
+                "concat_videos",
+                {"videos": "variable:shots"},
+                content_type="video/mp4",
+            ),
+            variables={"shots": ["asset:shot_1.mp4", "asset:shot_2.mp4"]},
+        )
+    )
+    assert meta["shape"] == "sequence"
+    assert "needs-input-media" in meta["traits"]
+
+
 def test_one_supplied_clip_reprocessed_is_still_a_utility():
     """The sequence rule needs two distinct sources; one clip through a
     filter is processing, not an edit."""
diff --git a/tests/test_concat_videos.py b/tests/test_concat_videos.py
index 78ecb8e6..94623b3f 100644
--- a/tests/test_concat_videos.py
+++ b/tests/test_concat_videos.py
@@ -86,6 +86,15 @@ def test_an_empty_list_raises(self):
         with pytest.raises(ValueError, match="non-empty"):
             concat_videos([])
 
+    def test_mismatched_frame_sizes_raise(self):
+        # Shots of different sizes were once "normalized" by a stabilize pass
+        # that actually rescaled every frame; refusing them names the real
+        # problem instead of quietly producing a film that jumps size mid-cut
+        wide = [Image.new("RGB", (16, 8)) for _ in range(3)]
+
+        with pytest.raises(ValueError, match="8x8.*16x8"):
+            concat_videos([frames(3), wide])
+
     def test_the_result_is_a_single_artifact(self):
         # add_result flattens lists - the joined video must never be one
         result = concat_videos([frames(3), frames(3)])
diff --git a/tests/test_dissolve_videos.py b/tests/test_dissolve_videos.py
index 2577f2cd..c9844b19 100644
--- a/tests/test_dissolve_videos.py
+++ b/tests/test_dissolve_videos.py
@@ -66,6 +66,12 @@ def test_negative_counts_are_refused(self):
         with pytest.raises(ValueError, match="negative"):
             dissolve_videos([frames(4, 0)], dissolve_frames=-1)
 
+    def test_mismatched_frame_sizes_are_refused(self):
+        wide = [Image.new("RGB", (16, 8)) for _ in range(3)]
+
+        with pytest.raises(ValueError, match="4x4.*16x8"):
+            dissolve_videos([frames(3, 0), wide], 0)
+
     def test_an_empty_list_is_refused(self):
         with pytest.raises(ValueError):
             dissolve_videos([])
diff --git a/tests/test_introspection.py b/tests/test_introspection.py
index fccc1816..fc906724 100644
--- a/tests/test_introspection.py
+++ b/tests/test_introspection.py
@@ -160,3 +160,44 @@ def test_scheduler_compatibles_reported_when_present():
 
     description = describe_class("EulerDiscreteScheduler", target="init")
     assert "DDIMScheduler" in description.get("compatibles", [])
+
+
+def _concat_step(**arguments):
+    return {
+        "variables": {"trim": 0},
+        "steps": [
+            {
+                "name": "cut",
+                "task": {
+                    "command": "concat_videos",
+                    "arguments": {"videos": ["a.mp4", "b.mp4"], **arguments},
+                },
+            }
+        ],
+    }
+
+
+def test_a_crossfade_with_nothing_trimmed_is_warned_about():
+    """concat_videos draws its crossfade from the trimmed-off material, so at
+    `trim_frames: 0` a `crossfade_ms` reads as active and does nothing - the
+    cut-based templates all sit there. Only a value the author wrote is
+    warned about; the argument's own default is not their mistake."""
+    warnings = workflow_argument_warnings(_concat_step(crossfade_ms=200))
+    assert len(warnings) == 1
+    assert "crossfade_ms" in warnings[0] and "trim_frames" in warnings[0]
+    assert "audio_bleed_ms" in warnings[0]
+
+    warnings = workflow_argument_warnings(
+        _concat_step(crossfade_ms=200, trim_frames=0)
+    )
+    assert len(warnings) == 1
+
+
+def test_a_crossfade_over_a_trim_is_not_warned_about():
+    assert workflow_argument_warnings(_concat_step(crossfade_ms=200, trim_frames=1)) == []
+    assert workflow_argument_warnings(_concat_step(trim_frames=0)) == []
+    assert workflow_argument_warnings(_concat_step(crossfade_ms=0)) == []
+    # A referenced trim is unknown until the run - do not guess
+    assert workflow_argument_warnings(
+        _concat_step(crossfade_ms=200, trim_frames="variable:trim")
+    ) == []
diff --git a/workflows/templates/assemble-and-score.json b/workflows/templates/assemble-and-score.json
index 34217ed2..6eeadcf9 100644
--- a/workflows/templates/assemble-and-score.json
+++ b/workflows/templates/assemble-and-score.json
@@ -1,60 +1,32 @@
 {
     "id": "assemble-and-score",
-    "description": "Cuts shots that already exist into one film with a score under them, generating nothing in the run. It is the pass you re-run while cutting, when re-generating the footage each time would cost GPU hours to change a fade. Each clip is held through stabilize_video with smooth 0, which re-encodes them to one consistent format rather than smoothing anything, then cut together with hard cuts. The shots' own recorded sound is carried up to the score's sample rate and mixed underneath it, so the room tone of each world survives the edit instead of being replaced by music. Supply the shots and the score as asset: references - 'shot_1.mp4' and friends, uploaded with upload_asset or promoted from a generated run with keep_output.",
+    "description": "Cuts shots that already exist into one film with a score under them, generating nothing in the run. It is the pass you re-run while cutting, when re-generating the footage each time would cost GPU hours to change a fade. The shots go straight into concat_videos as hard cuts - nothing is stabilized or rescaled on the way, so a deliberate camera move survives the edit; they must already share one size and frame rate, and the task refuses a set that does not. 'shots' is a list, so a diptych is two entries and a reel is however many the cut needs. The shots' own recorded sound is carried up to the score's sample rate and mixed underneath it, so the room tone of each world survives the edit instead of being replaced by music. Supply the shots and the score as asset: references - 'shot_1.mp4' and friends, uploaded with upload_asset or promoted from a generated run with keep_output.",
     "variables": {
-        "shot_1": "asset:shot_1.mp4",
-        "shot_2": "asset:shot_2.mp4",
-        "shot_3": "asset:shot_3.mp4",
+        "shots": [
+            "asset:shot_1.mp4",
+            "asset:shot_2.mp4",
+            "asset:shot_3.mp4"
+        ],
         "score": "asset:score.wav",
         "sample_rate": 44100,
         "fps": 24,
+        "audio_bleed_ms": 0,
+        "seam_fade_ms": null,
         "score_start_frame": 0,
         "total_frames": 360,
         "score_gain": 1.0,
         "world_gain": 1.8
     },
     "steps": [
-        {
-            "name": "hold_1",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_1"
-                }
-            }
-        },
-        {
-            "name": "hold_2",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_2"
-                }
-            }
-        },
-        {
-            "name": "hold_3",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_3"
-                }
-            }
-        },
         {
             "name": "edit",
             "task": {
                 "command": "concat_videos",
                 "arguments": {
-                    "videos": [
-                        "previous_result:hold_1",
-                        "previous_result:hold_2",
-                        "previous_result:hold_3"
-                    ],
-                    "fps": "variable:fps"
+                    "videos": "variable:shots",
+                    "fps": "variable:fps",
+                    "audio_bleed_ms": "variable:audio_bleed_ms",
+                    "seam_fade_ms": "variable:seam_fade_ms"
                 }
             }
         },
diff --git a/workflows/templates/dissolve-between-shots.json b/workflows/templates/dissolve-between-shots.json
index b2890dd8..e8ec27c3 100644
--- a/workflows/templates/dissolve-between-shots.json
+++ b/workflows/templates/dissolve-between-shots.json
@@ -1,10 +1,12 @@
 {
     "id": "dissolve-between-shots",
-    "description": "assemble-and-score.json with the cuts softened into cross-dissolves. dissolve_videos overlaps each pair by 'dissolve_frames' rather than butting them together, which suits shots that share a composition - registered on the same centre at the same size, an overlap reads as one thing becoming another rather than as a fade between two pictures. Shots whose framing disagrees will read as a plain cross-fade, so use hard cuts there. The audio bed is mixed the same way as in assemble-and-score.",
+    "description": "assemble-and-score.json with the cuts softened into cross-dissolves. dissolve_videos overlaps each pair by 'dissolve_frames' rather than butting them together, which suits shots that share a composition - registered on the same centre at the same size, an overlap reads as one thing becoming another rather than as a fade between two pictures. Shots whose framing disagrees will read as a plain cross-fade, so use hard cuts there. As in assemble-and-score the shots are a list and go in untouched - a shot that drifts wants stabilize_video run on it first, as its own step, not on every shot by default. The audio bed is mixed the same way as in assemble-and-score.",
     "variables": {
-        "shot_1": "asset:shot_1.mp4",
-        "shot_2": "asset:shot_2.mp4",
-        "shot_3": "asset:shot_3.mp4",
+        "shots": [
+            "asset:shot_1.mp4",
+            "asset:shot_2.mp4",
+            "asset:shot_3.mp4"
+        ],
         "dissolve_frames": 12,
         "score": "asset:score.wav",
         "sample_rate": 44100,
@@ -15,46 +17,12 @@
         "world_gain": 1.8
     },
     "steps": [
-        {
-            "name": "hold_1",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_1"
-                }
-            }
-        },
-        {
-            "name": "hold_2",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_2"
-                }
-            }
-        },
-        {
-            "name": "hold_3",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_3"
-                }
-            }
-        },
         {
             "name": "edit",
             "task": {
                 "command": "dissolve_videos",
                 "arguments": {
-                    "videos": [
-                        "previous_result:hold_1",
-                        "previous_result:hold_2",
-                        "previous_result:hold_3"
-                    ],
+                    "videos": "variable:shots",
                     "dissolve_frames": "variable:dissolve_frames",
                     "fps": "variable:fps"
                 }
diff --git a/workflows/templates/minimax/dialogue-short.json b/workflows/templates/minimax/dialogue-short.json
index acb9b8c8..aa557743 100644
--- a/workflows/templates/minimax/dialogue-short.json
+++ b/workflows/templates/minimax/dialogue-short.json
@@ -1,6 +1,6 @@
 {
     "id": "MiniMaxH3SitcomShort",
-    "description": "A digital short built the way television is built: from cuts, not from one long take. Chained generation degrades with length - every segment conditions on the previous segment's output, so artifacts compound and identity drifts. A scene cut resets that completely: each shot here is generated fresh from the same two character portraits, so shot five is exactly as clean as shot one and the scene can run as long as the script does. Two Z-Image steps draw the cast (the second reuses the first's loaded pipeline - identical configurations share one model - and 'release_pipeline' frees it before the video model loads). The first shot loads MiniMax-H3 once; the remaining shots are 'pipeline_reference' steps that rerun it with a new prompt, references and length - the tag shot runs 141 frames where the others run 124, since length is per-run. Character consistency across cuts comes from referencing the same portraits in every shot; voice consistency comes from repeating each character's voice description verbatim in every prompt. The soundscape writes the laugh track. A final 'concat_videos' task is the editor, splicing the shots into one episode - hard cuts, no trims, no seams to hide, because nothing was carried between them. Only the picture cuts hard: 'audio_bleed_ms' rings each shot's laugh track on over the silent opening of the next, the way a live audience carries across a cut.",
+    "description": "A digital short built the way television is built: from cuts, not from one long take. Chained generation degrades with length - every segment conditions on the previous segment's output, so artifacts compound and identity drifts. A scene cut resets that completely: each shot here is generated fresh from the same two character portraits, so shot five is exactly as clean as shot one and the scene can run as long as the script does. Two Z-Image steps draw the cast (the second reuses the first's loaded pipeline - identical configurations share one model - and 'release_pipeline' frees it before the video model loads). The first shot loads MiniMax-H3 once; the remaining shots are 'pipeline_reference' steps that rerun it with a new prompt, references and length - the tag shot runs 141 frames where the others run 124, since length is per-run. Character consistency across cuts comes from referencing the same portraits in every shot; voice consistency comes from repeating each character's voice description verbatim in every prompt. The soundscape writes the laugh track. A final 'concat_videos' task is the editor, splicing the shots into one episode - hard cuts, no trims, no seams to hide, because nothing was carried between them. Only the picture cuts hard: 'audio_bleed_ms' rings each shot's laugh track on over the silent opening of the next, the way a live audience carries across a cut. It and 'seam_fade_ms' are variables, so a seam is re-tuned with an argument rather than a copy of the workflow; 1800 ms is where a five-shot cut measured best, since a generated shot opens on more silence than it looks.",
     "summary": "A multi-shot dialogue short: Z-Image draws the cast, each shot is generated fresh from the same portraits, then cut.",
     "variables": {
         "howie_portrait_prompt": "a 3/4-length studio portrait of a wiry man in his early 30s with short curly dark hair and expressive eyebrows, wearing a mustard-yellow sweater vest over a white button-down shirt, standing in a 1990s multi-camera sitcom apartment set with a sagging olive-green couch and a brick wall behind him, warm even studio lighting, sharp focus, photographic",
@@ -13,6 +13,8 @@
         "subject_reference_type": "diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference",
         "num_frames": 124,
         "tag_num_frames": 141,
+        "audio_bleed_ms": 1800,
+        "seam_fade_ms": null,
         "width": 960,
         "height": 544,
         "num_inference_steps": 9,
@@ -341,8 +343,9 @@
                         "previous_result:shot_5_tag"
                     ],
                     "trim_frames": 0,
-                    "audio_bleed_ms": 700,
-                    "fps": 24
+                    "audio_bleed_ms": "variable:audio_bleed_ms",
+                    "fps": 24,
+                    "seam_fade_ms": "variable:seam_fade_ms"
                 }
             },
             "result": {
diff --git a/workflows/templates/minimax/music-video.json b/workflows/templates/minimax/music-video.json
index acb288de..d82cacb8 100644
--- a/workflows/templates/minimax/music-video.json
+++ b/workflows/templates/minimax/music-video.json
@@ -15,6 +15,8 @@
         "sample_rate": 44100,
         "num_frames": 124,
         "fps": 24,
+        "audio_bleed_ms": 0,
+        "seam_fade_ms": null,
         "width": 960,
         "height": 544,
         "num_inference_steps": 9,
@@ -394,7 +396,9 @@
                         "previous_result:shot_4_finale"
                     ],
                     "trim_frames": 0,
-                    "fps": "variable:fps"
+                    "fps": "variable:fps",
+                    "audio_bleed_ms": "variable:audio_bleed_ms",
+                    "seam_fade_ms": "variable:seam_fade_ms"
                 }
             }
         },

From 42ab472b92760c25f1522e256a8d496b0d914a3b Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 10 Sep 2026 22:57:12 -0500
Subject: [PATCH 2/3] Plan: MCP field report follow-ups (PR-2 surface, PR-3
 media info)

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../2026-09-10-mcp-field-report-followups.md  | 904 ++++++++++++++++++
 1 file changed, 904 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-09-10-mcp-field-report-followups.md

diff --git a/docs/superpowers/plans/2026-09-10-mcp-field-report-followups.md b/docs/superpowers/plans/2026-09-10-mcp-field-report-followups.md
new file mode 100644
index 00000000..125a6be4
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-10-mcp-field-report-followups.md
@@ -0,0 +1,904 @@
+# MCP Field Report Follow-ups 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:** Close the remaining items of the 2026-09-10 Opus-over-MCP field report (`/Users/don/testing/10/dw-improvements.md`): MCP payload bloat (#4), workspace sharp edges (#5), audio/video inspection (#6), catalog costs (#9) and the download recipe (#10).
+
+**Architecture:** Two independent PRs. PR-2 is the MCP surface only (`dw_mcp/`, docs) - it changes what tools return and accept, never what the server does. PR-3 adds one server-side probe (`dw/media_info.py`, PyAV) and surfaces it on the gallery-metadata route and its MCP tool. Items 1-3 already shipped on branch `field-report-1-3` (commit `5f8f910`).
+
+**Tech Stack:** Python 3.12, FastAPI, httpx MockTransport for MCP tests, PyAV (already a dependency for muxing), pytest.
+
+**Spec:** `/Users/don/testing/10/dw-improvements.md` (the report) and the assessment in this conversation's memory note `mcp-field-report-2026-09-10`.
+
+## Global Constraints
+
+- Never `eval`/`exec`/`shell=True`; every filesystem read goes through `dw/security.py` validators (`_output_file` in `dw/server/app.py` already confines gallery paths - reuse it, do not open a path the route did not validate).
+- MCP tool wrappers in `dw_mcp/server.py` are thin: behaviour lives in `dw_mcp/<module>.py` with a matching `tests/test_mcp_<module>.py` using `httpx.MockTransport`.
+- Docstrings on MCP tools are the tool descriptions an agent reads; a change in behaviour changes the docstring in the same commit.
+- `docs/MCP.md` and `docs/WORKFLOW_GUIDE.md` ("Authoring a workflow from an agent") describe the same conventions; change both when one changes.
+- Commit messages end with `Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>`.
+
+---
+
+# PR-2: MCP surface (branch `field-report-mcp-surface`, from `master` after PR-1 merges)
+
+### Task 1: `export_job` stops inlining the three JSON files
+
+**Files:**
+- Modify: `dw_mcp/exports.py:12-48`
+- Modify: `dw_mcp/server.py:675-700` (docstring only)
+- Test: `tests/test_mcp_exports.py:60-68`
+
+**Interfaces:**
+- Produces: `export_job(client, job_id, overwrite=False) -> dict` with keys `job_id, where, directory, zip_url, files, total_bytes, missing, next` - no `workflow`, `manifest`, `job`.
+
+- [ ] **Step 1: Rewrite the failing test**
+
+Replace `test_the_three_json_files_come_back_inline` in `tests/test_mcp_exports.py` with:
+
+```python
+def test_the_three_json_files_stay_in_the_zip():
+    """A music-video export inlined 55 KB of workflow, manifest and job row
+    that the zip already carries and get_job_workflow / get_job already
+    serve - it blew past the tool output limit. The listing says they are
+    there; the bytes are not repeated."""
+    client, _ = exporting()
+
+    result = exports.export_job(client, "job-1")
+
+    assert "workflow" not in result
+    assert "manifest" not in result
+    assert "job" not in result
+    assert "get_job_workflow" in result["next"]
+```
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `python -m pytest tests/test_mcp_exports.py -q -k stay_in_the_zip`
+Expected: FAIL on `assert "workflow" not in result`.
+
+- [ ] **Step 3: Drop the three keys and say where they live**
+
+In `dw_mcp/exports.py`, remove the `"workflow"`, `"manifest"`, `"job"` entries from the returned dict and change the `next` text to:
+
+```python
+        "next": "The directory is on the server. To give the user the files, "
+        "fetch zip_url and unpack it into exports/ under the session's "
+        "working directory - it is the user's deliverable, not a temporary "
+        "file, so not a scratch or temp directory. The archive already "
+        "unpacks into one folder named after the job id; do not create "
+        "that folder first or the id is doubled in the path. workflow.json, "
+        "manifest.json and job.json are inside it - they are not repeated "
+        "here; get_job_workflow and get_job serve them individually.",
+```
+
+Update the docstring's "Returns the directory, the zip URL, the file list with sizes and the total, and the three JSON files inline" to "... the file list with sizes and the total. The three JSON files are in the zip, not repeated here." Make the same edit to the `export_job` docstring in `dw_mcp/server.py`.
+
+- [ ] **Step 4: Run the file's tests**
+
+Run: `python -m pytest tests/test_mcp_exports.py tests/test_mcp_server.py -q -k export`
+Expected: all pass. If `test_mcp_server.py` asserts on the inline keys, update that assertion the same way.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw_mcp/exports.py dw_mcp/server.py tests/test_mcp_exports.py tests/test_mcp_server.py
+git commit -m "export_job: leave the three JSON files in the zip"
+```
+
+### Task 2: `wait_for_job` returns a slim job
+
+**Files:**
+- Modify: `dw_mcp/diagnose.py:103-142`
+- Modify: `dw_mcp/server.py:633-641` (docstring)
+- Test: `tests/test_mcp_diagnose.py:274-330`
+
+**Interfaces:**
+- Produces: `slim_job(job: dict) -> dict` in `dw_mcp/diagnose.py`, keeping exactly `id, workflow_name, status, created_at, started_at, finished_at, workspace, run_id, warnings, error, event_count` plus `manifest` only when status is terminal. `arguments` and `traceback` are dropped. `wait_for_job`'s `job` value is `slim_job(job)`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/test_mcp_diagnose.py`:
+
+```python
+FAT_JOB = {
+    "id": "job-1",
+    "workflow_name": "minimax/dialogue-short",
+    "status": "running",
+    "created_at": 1.0,
+    "started_at": 2.0,
+    "finished_at": None,
+    "workspace": "default",
+    "run_id": None,
+    "arguments": {"shot_1_cold_open": "x" * 6000},
+    "warnings": [],
+    "manifest": None,
+    "error": None,
+    "traceback": None,
+    "event_count": 12,
+    "run_dir": None,
+}
+
+
+def test_wait_for_job_does_not_echo_the_arguments_on_every_poll(monkeypatch):
+    """An H3 workflow's arguments are 4-6k tokens of prompt text; a
+    45-minute render is polled many times. They are get_job's to serve,
+    once."""
+    monkeypatch.setattr(diagnose, "MAX_WAIT_SECONDS", 0)
+    client, _ = scripted({("GET", "/api/jobs/job-1"): (200, FAT_JOB)})
+
+    result = diagnose.wait_for_job(client, "job-1", timeout_seconds=0)
+
+    assert result["still_running"] is True
+    assert "arguments" not in result["job"]
+    assert "traceback" not in result["job"]
+    assert result["job"]["status"] == "running"
+    assert result["job"]["event_count"] == 12
+
+
+def test_wait_for_job_keeps_the_manifest_and_error_once_terminal(monkeypatch):
+    done = {**FAT_JOB, "status": "failed", "manifest": {"steps": []}, "error": "boom"}
+    client, _ = scripted({("GET", "/api/jobs/job-1"): (200, done)})
+
+    result = diagnose.wait_for_job(client, "job-1")
+
+    assert result["job"]["manifest"] == {"steps": []}
+    assert result["job"]["error"] == "boom"
+    assert "arguments" not in result["job"]
+```
+
+- [ ] **Step 2: Run them to verify they fail**
+
+Run: `python -m pytest tests/test_mcp_diagnose.py -q -k "echo_the_arguments or once_terminal"`
+Expected: FAIL on `assert "arguments" not in result["job"]`.
+
+- [ ] **Step 3: Implement `slim_job` and use it**
+
+In `dw_mcp/diagnose.py`, above `wait_for_job`:
+
+```python
+_SLIM_KEYS = (
+    "id",
+    "workflow_name",
+    "status",
+    "created_at",
+    "started_at",
+    "finished_at",
+    "workspace",
+    "run_id",
+    "warnings",
+    "error",
+    "event_count",
+)
+
+
+def slim_job(job):
+    """A job row without its arguments and traceback - what a poll needs.
+
+    The arguments of an H3 workflow are thousands of tokens of prompt text,
+    repeated on every poll of a long render; get_job serves them once. The
+    manifest is kept only once the job is terminal, when it names files.
+    """
+    slim = {key: job.get(key) for key in _SLIM_KEYS if key in job}
+    if job.get("status") in TERMINAL_STATUSES:
+        slim["manifest"] = job.get("manifest")
+    return slim
+```
+
+In both `return` dicts inside `wait_for_job`, change `"job": job` to `"job": slim_job(job)`. Add to the terminal return a `"next": "get_job(job_id) for the arguments and traceback, get_job_workflow(job_id) for the realized workflow."`.
+
+Update the `wait_for_job` docstrings in `dw_mcp/diagnose.py` and `dw_mcp/server.py`: append "Returns a slim job - status, warnings, error, and the manifest once finished - without the arguments; get_job has those."
+
+- [ ] **Step 4: Run the tests**
+
+Run: `python -m pytest tests/test_mcp_diagnose.py tests/test_mcp_server.py -q`
+Expected: all pass. `test_wait_for_job_returns_promptly_once_terminal` may assert `result["job"] == <full row>`; if so change it to compare `result["job"]["status"]` and `result["job"]["id"]`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw_mcp/diagnose.py dw_mcp/server.py tests/test_mcp_diagnose.py tests/test_mcp_server.py
+git commit -m "wait_for_job: poll with a slim job, not the arguments"
+```
+
+### Task 3: `run_workflow` and `validate_workflow` take an optional `workspace`
+
+**Files:**
+- Modify: `dw_mcp/diagnose.py:33-66`
+- Modify: `dw_mcp/authoring.py:12-26`
+- Modify: `dw_mcp/server.py:483-491, 582-605`
+- Test: `tests/test_mcp_diagnose.py`, `tests/test_mcp_authoring.py`
+
+**Interfaces:**
+- Consumes: `DwClient._scoped` (`dw_mcp/client.py:230`) adds `params["workspace"]` only when `client.workspace != DEFAULT_WORKSPACE`, and uses `setdefault`, so a `workspace` already present in `params` wins.
+- Produces: `run_workflow(client, ..., workspace=None)` and `validate_workflow(client, workflow=None, name=None, workspace=None)`; when `workspace` is given it is sent as the `workspace` query parameter of that one request and the session's workspace is unchanged.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/test_mcp_diagnose.py`:
+
+```python
+def test_run_pins_a_job_to_a_named_workspace_without_switching():
+    """A session restart resets the session workspace to default, and a
+    concat job then resolved output: references against the wrong root.
+    A run can name its workspace itself, for that one request."""
+    client, seen = submitting()
+    client.workspace = "music-video"
+
+    diagnose.run_workflow(
+        client, workflow_path="w", acknowledged_cost=True, workspace="dialogue-short"
+    )
+
+    assert seen[0]["params"]["workspace"] == "dialogue-short"
+    assert client.workspace == "music-video"
+
+
+def test_run_sends_the_session_workspace_when_none_is_named():
+    client, seen = submitting()
+    client.workspace = "music-video"
+
+    diagnose.run_workflow(client, workflow_path="w", acknowledged_cost=True)
+
+    assert seen[0]["params"]["workspace"] == "music-video"
+```
+
+Append to `tests/test_mcp_authoring.py` (use its existing `scripted`/recording helper; the route is `("POST", "/api/validate")`):
+
+```python
+def test_validate_can_name_a_workspace_for_one_request():
+    client, seen = scripted({("POST", "/api/validate"): (200, {"valid": True})})
+
+    authoring.validate_workflow(client, name="w", workspace="dialogue-short")
+
+    assert seen[0]["params"]["workspace"] == "dialogue-short"
+    assert client.workspace == DEFAULT_WORKSPACE
+```
+
+(Import `DEFAULT_WORKSPACE` from `dw_mcp.client`; check the helper records `params` - the diagnose one does, the authoring one may need the same `"params": dict(request.url.params)` line added.)
+
+- [ ] **Step 2: Run them to verify they fail**
+
+Run: `python -m pytest tests/test_mcp_diagnose.py tests/test_mcp_authoring.py -q -k workspace`
+Expected: FAIL with `TypeError: ... unexpected keyword argument 'workspace'`.
+
+- [ ] **Step 3: Thread the parameter**
+
+`dw_mcp/diagnose.py`:
+
+```python
+def run_workflow(
+    client,
+    workflow_path=None,
+    inline_workflow=None,
+    arguments=None,
+    acknowledged_cost=False,
+    workspace=None,
+):
+    ...
+    # A named workspace pins this one job rather than the session: a
+    # restarted session forgets use_workspace, and a job that resolves
+    # output: references in the wrong root fails after it was queued
+    params = {"workspace": workspace} if workspace else None
+    job = client.post_json("/api/jobs", payload, params=params)
+```
+
+`dw_mcp/authoring.py`:
+
+```python
+def validate_workflow(client, workflow=None, name=None, workspace=None):
+    ...
+    params = {"workspace": workspace} if workspace else None
+    if name is not None:
+        return client.post_json("/api/validate", {"workflow_path": name}, params=params)
+    return client.post_json("/api/validate", {"workflow": workflow}, params=params)
+```
+
+`dw_mcp/server.py`: add `workspace: str | None = None` to both tool signatures, pass it through, and append to each docstring: "`workspace` names the workspace for this one call without switching the session to it - use it to pin a job whose `output:` or `asset:` references live in a workspace other than the session's."
+
+- [ ] **Step 4: Run the tests**
+
+Run: `python -m pytest tests/test_mcp_diagnose.py tests/test_mcp_authoring.py tests/test_mcp_server.py -q`
+Expected: all pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw_mcp/diagnose.py dw_mcp/authoring.py dw_mcp/server.py tests/test_mcp_diagnose.py tests/test_mcp_authoring.py
+git commit -m "run_workflow/validate_workflow: pin one call to a named workspace"
+```
+
+### Task 4: `create_workspace(use=...)` and a louder result
+
+**Files:**
+- Modify: `dw_mcp/workspaces.py:49-53`
+- Modify: `dw_mcp/server.py:460-466`
+- Test: `tests/test_mcp_workspaces.py:84-89`
+
+**Interfaces:**
+- Consumes: `use_workspace(client, name)` (`dw_mcp/workspaces.py`) which sets `client.workspace` after checking the server's listing.
+- Produces: `create_workspace(client, name, use=False) -> dict` = the server's body plus `current` (the session workspace after the call) and `next`.
+
+- [ ] **Step 1: Write the failing tests**
+
+In `tests/test_mcp_workspaces.py` `TestLifecycle`, add beside `test_creating_one_does_not_switch_to_it`:
+
+```python
+    def test_creating_one_says_it_did_not_switch(self):
+        """A create-then-run sequence landed a five-shot job in the wrong
+        workspace; the result now says where the session still is."""
+        client, _ = recording({"name": "shots"})
+        result = create_workspace(client, "shots")
+        assert result["current"] == DEFAULT_WORKSPACE
+        assert "use_workspace" in result["next"]
+
+    def test_creating_with_use_switches_to_it(self):
+        client, seen = recording({"name": "shots"})
+        result = create_workspace(client, "shots", use=True)
+        assert client.workspace == "shots"
+        assert result["current"] == "shots"
+```
+
+`recording` scripts one response for every request; `use_workspace` GETs the listing and checks the name is in it. If the recorded body `{"name": "shots"}` makes `use_workspace` raise "No workspace named", script the listing instead: look at how `test_deleting_the_current_one_falls_back_to_the_default` uses `listing("default", "shots")` and use that body for the `use=True` test.
+
+- [ ] **Step 2: Run them to verify they fail**
+
+Run: `python -m pytest tests/test_mcp_workspaces.py -q -k "says_it_did_not_switch or with_use"`
+Expected: FAIL (`KeyError: 'current'`, then `TypeError` on `use`).
+
+- [ ] **Step 3: Implement**
+
+```python
+def create_workspace(client, name, use=False):
+    """Make a new workspace on the server. It gets its own workflows, assets
+    and outputs, and shares the server's one prompt library. Creating it
+    does not switch to it unless `use` is true - the natural
+    create-then-run sequence otherwise runs in the workspace the session
+    was already in, and the result says which that is."""
+    body = client.post_json("/api/workspaces", {"name": name})
+    if use:
+        use_workspace(client, name)
+    return {
+        **body,
+        "current": client.workspace,
+        "next": (
+            f"This session now works in '{client.workspace}'."
+            if use
+            else f"This session still works in '{client.workspace}' - call "
+            f"use_workspace('{name}') or pass workspace='{name}' to "
+            f"run_workflow before running anything meant for it."
+        ),
+    }
+```
+
+`dw_mcp/server.py`: `def create_workspace(name: str, use: bool = False) -> dict:` passing `use=use`; docstring: replace "Creating does not switch to it: call use_workspace after." with "Pass use=true to switch this session to it as well; otherwise the session stays where it was and the result says so."
+
+- [ ] **Step 4: Run the tests**
+
+Run: `python -m pytest tests/test_mcp_workspaces.py tests/test_mcp_server.py -q`
+Expected: all pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw_mcp/workspaces.py dw_mcp/server.py tests/test_mcp_workspaces.py
+git commit -m "create_workspace: optional use=, and say where the session still is"
+```
+
+### Task 5: Catalog costs for the cut templates
+
+**Files:**
+- Modify: `workflows/templates/minimax/music-video.json:2-4`, `workflows/templates/minimax/dialogue-short.json:2-4`, `workflows/templates/assemble-and-score.json:2-4`, `workflows/templates/dissolve-between-shots.json:2-4`
+- Test: `tests/test_catalog_structure.py`
+
+**Interfaces:**
+- Consumes: the `cost` array format at `workflows/templates/minimax/music.json:4`: `[{"device": "cuda", "name": "RTX 3090", "vram_gb": 24, "minutes": 3.6}]`, read at `dw/server/app.py:223`.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `tests/test_catalog_structure.py`:
+
+```python
+COSTED = {
+    "workflows/templates/minimax/music-video.json": 35,
+    "workflows/templates/minimax/dialogue-short.json": 42,
+    "workflows/templates/assemble-and-score.json": 0.2,
+    "workflows/templates/dissolve-between-shots.json": 0.2,
+}
+
+
+@pytest.mark.parametrize("path,minutes", sorted(COSTED.items()))
+def test_the_cut_templates_quote_a_measured_cost(path, minutes):
+    """Measured on an RTX 3090, 2026-09-10; without a figure an agent
+    cannot quote a price before spending 40 minutes of GPU."""
+    definition = json.load(open(path))
+    entry = definition["cost"][0]
+    assert entry["name"] == "RTX 3090"
+    assert entry["minutes"] == minutes
+```
+
+(Use the file's existing imports; it already opens every workflow, so `json` and `pytest` are present.)
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `python -m pytest tests/test_catalog_structure.py -q -k measured_cost`
+Expected: 4 FAIL with `KeyError: 'cost'`.
+
+- [ ] **Step 3: Add the cost arrays**
+
+Insert after `"description"` (or after `"summary"` where one exists) in each file, matching the indentation used in `music.json`:
+
+```json
+    "cost": [
+        {"device": "cuda", "name": "RTX 3090", "vram_gb": 24, "minutes": 35}
+    ],
+```
+
+with `35` (music-video: 4 shots + song + portrait), `42` (dialogue-short: 5 shots + 2 portraits), `0.2` (assemble-and-score and dissolve-between-shots: no generation, 5-13 s measured).
+
+- [ ] **Step 4: Run the tests**
+
+Run: `python -m pytest tests/test_catalog_structure.py tests/test_examples.py -q`
+Expected: all pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add workflows/templates
+git commit -m "Catalog: measured 3090 costs for the cut templates"
+```
+
+### Task 6: The download recipe in the guide
+
+**Files:**
+- Modify: `docs/WORKFLOW_GUIDE.md` after step 6 of "The loop" (line ~346)
+- Modify: `docs/MCP.md` (a pointer in the client-configuration section, after the `claude mcp add` block at line ~91)
+
+- [ ] **Step 1: Add a step 7 to "The loop"**
+
+After the `get_output_image` step, add:
+
+```markdown
+7. Getting the files to the user's machine. `download_output` and `export_job`
+   write on the machine running `dw.serve`, which over a remote `--mcp`
+   endpoint is the GPU box. The last mile of every deliverable is the `url`
+   each `list_gallery` entry carries (or `export_job`'s `zip_url`), fetched
+   with the same bearer token the MCP connection uses:
+
+       curl -H "Authorization: Bearer $DW_TOKEN" \
+            -o exports/still.png "$DW_SERVER/outputs/ltx2/Gyre/20260910-.../still.png"
+
+   Put the result under `exports/` in the session's working directory - it is
+   the user's deliverable, not a temporary file.
+```
+
+- [ ] **Step 2: Point to it from MCP.md**
+
+After the `claude mcp add ... --header` block, add one sentence: "The same token fetches generated files: see step 7 of `The loop` in [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md#the-loop)."
+
+- [ ] **Step 3: Check the guide's tests still pass**
+
+Run: `python -m pytest tests/test_mcp_guides.py tests/test_plugin_skills.py -q`
+Expected: pass (the guides tool indexes sections by heading; no heading changed).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add docs/WORKFLOW_GUIDE.md docs/MCP.md
+git commit -m "Guide: the last mile - fetching outputs with the MCP token"
+```
+
+### Task 7: Update the report's authors
+
+- [ ] **Step 1:** Run the full suite: `python -m pytest tests -q` - expected all pass.
+- [ ] **Step 2:** Open a PR titled "MCP surface: slim payloads, pinned workspaces, costs" with the field-report item numbers (#4, #5, #9, #10) in the body.
+
+---
+
+# PR-3: Media info on gallery metadata (branch `field-report-media-info`, independent of PR-2)
+
+### Task 8: `probe_media(path)` in `dw/media_info.py`
+
+**Files:**
+- Create: `dw/media_info.py`
+- Test: `tests/test_media_info.py`
+
+**Interfaces:**
+- Produces: `probe_media(path: str) -> dict | None`. For audio: `{"kind": "audio", "duration_seconds": float, "sample_rate": int, "channels": int, "peak_dbfs": float, "mean_dbfs": float}`. For video: the same plus `"kind": "video", "fps": float, "frame_count": int, "width": int, "height": int`; the audio fields are present only when the file carries an audio stream. `None` for a file PyAV cannot open. Levels are computed from the decoded waveform: `peak_dbfs = 20*log10(max|x|)`, `mean_dbfs = 20*log10(rms(x))`, `-inf` clamped to `-120.0`.
+
+- [ ] **Step 1: Write the failing tests**
+
+`tests/test_media_info.py`:
+
+```python
+"""probe_media reports what the server knows about a generated file and
+would otherwise not say - an agent cannot listen, so duration and level
+are the only way it checks an audio deliverable."""
+
+import math
+
+import numpy
+import pytest
+
+from dw.media_info import probe_media
+
+
+def write_wav(path, seconds=2.0, sample_rate=8000, amplitude=0.5):
+    import wave
+
+    t = numpy.arange(int(seconds * sample_rate)) / sample_rate
+    samples = (numpy.sin(2 * numpy.pi * 220 * t) * amplitude * 32767).astype("<i2")
+    with wave.open(str(path), "w") as handle:
+        handle.setnchannels(2)
+        handle.setsampwidth(2)
+        handle.setframerate(sample_rate)
+        handle.writeframes(numpy.stack([samples, samples], 1).tobytes())
+
+
+def write_mp4(path, frames=12, fps=6, width=32, height=16, with_audio=True):
+    import av
+
+    container = av.open(str(path), "w")
+    video = container.add_stream("libx264", rate=fps)
+    video.width, video.height, video.pix_fmt = width, height, "yuv420p"
+    audio = container.add_stream("aac", rate=8000) if with_audio else None
+    if audio is not None:
+        audio.layout = "stereo"
+    for _ in range(frames):
+        frame = av.VideoFrame.from_ndarray(
+            numpy.zeros((height, width, 3), numpy.uint8), format="rgb24"
+        )
+        for packet in video.encode(frame):
+            container.mux(packet)
+    if audio is not None:
+        total = 8000 * frames // fps
+        tone = numpy.stack([numpy.full(total, 0.25, numpy.float32)] * 2)
+        for start in range(0, total, 1024):
+            chunk = av.AudioFrame.from_ndarray(
+                numpy.ascontiguousarray(tone[:, start : start + 1024]),
+                format="fltp",
+                layout="stereo",
+            )
+            chunk.sample_rate = 8000
+            chunk.pts = start
+            for packet in audio.encode(chunk):
+                container.mux(packet)
+        for packet in audio.encode():
+            container.mux(packet)
+    for packet in video.encode():
+        container.mux(packet)
+    container.close()
+
+
+def test_a_wav_reports_duration_rate_channels_and_level(tmp_path):
+    write_wav(tmp_path / "score.wav", seconds=2.0, sample_rate=8000, amplitude=0.5)
+
+    info = probe_media(str(tmp_path / "score.wav"))
+
+    assert info["kind"] == "audio"
+    assert info["duration_seconds"] == pytest.approx(2.0, abs=0.01)
+    assert info["sample_rate"] == 8000
+    assert info["channels"] == 2
+    # a 0.5-amplitude sine peaks at -6 dBFS and sits at -9 dBFS rms
+    assert info["peak_dbfs"] == pytest.approx(-6.0, abs=0.2)
+    assert info["mean_dbfs"] == pytest.approx(-9.0, abs=0.2)
+
+
+def test_a_video_reports_its_picture_and_its_soundtrack(tmp_path):
+    write_mp4(tmp_path / "shot.mp4", frames=12, fps=6, width=32, height=16)
+
+    info = probe_media(str(tmp_path / "shot.mp4"))
+
+    assert info["kind"] == "video"
+    assert info["frame_count"] == 12
+    assert info["fps"] == pytest.approx(6.0)
+    assert (info["width"], info["height"]) == (32, 16)
+    assert info["duration_seconds"] == pytest.approx(2.0, abs=0.1)
+    assert info["sample_rate"] == 8000
+    assert info["channels"] == 2
+    assert info["peak_dbfs"] == pytest.approx(-12.0, abs=1.0)
+
+
+def test_a_silent_video_has_no_audio_fields(tmp_path):
+    write_mp4(tmp_path / "mute.mp4", with_audio=False)
+
+    info = probe_media(str(tmp_path / "mute.mp4"))
+
+    assert info["kind"] == "video"
+    assert "sample_rate" not in info
+    assert "peak_dbfs" not in info
+
+
+def test_silence_is_clamped_not_minus_infinity(tmp_path):
+    write_wav(tmp_path / "quiet.wav", amplitude=0.0)
+
+    info = probe_media(str(tmp_path / "quiet.wav"))
+
+    assert info["peak_dbfs"] == -120.0
+    assert not math.isinf(info["mean_dbfs"])
+
+
+def test_a_file_that_is_not_media_answers_none(tmp_path):
+    (tmp_path / "notes.txt").write_text("not media")
+
+    assert probe_media(str(tmp_path / "notes.txt")) is None
+```
+
+- [ ] **Step 2: Run them to verify they fail**
+
+Run: `python -m pytest tests/test_media_info.py -q`
+Expected: FAIL with `ModuleNotFoundError: dw.media_info`.
+
+- [ ] **Step 3: Implement `dw/media_info.py`**
+
+```python
+"""What the server knows about a generated media file and would otherwise
+not say. An agent cannot listen: duration against a ceiling, peak against
+a normalization target and the level at a seam are the only checks it can
+make on an audio deliverable, and every one of them was being made by
+fetching the file and running ffprobe by hand.
+"""
+
+import logging
+import math
+
+import av
+import numpy
+
+logger = logging.getLogger("dw")
+
+# The floor a level is reported at rather than -inf, which JSON cannot carry
+SILENCE_DBFS = -120.0
+
+
+def _dbfs(value):
+    if value <= 0:
+        return SILENCE_DBFS
+    return max(SILENCE_DBFS, 20.0 * math.log10(float(value)))
+
+
+def _audio_levels(container, stream):
+    """Peak and rms of the whole decoded track, in dBFS."""
+    peak = 0.0
+    total = 0.0
+    count = 0
+    for frame in container.decode(stream):
+        samples = frame.to_ndarray()
+        if samples.dtype.kind in "iu":
+            samples = samples.astype(numpy.float32) / numpy.iinfo(samples.dtype).max
+        samples = samples.astype(numpy.float32)
+        peak = max(peak, float(numpy.abs(samples).max(initial=0.0)))
+        total += float(numpy.square(samples).sum())
+        count += samples.size
+    rms = math.sqrt(total / count) if count else 0.0
+    return _dbfs(peak), _dbfs(rms)
+
+
+def probe_media(path):
+    """Duration, format and level of an audio or video file, or None.
+
+    Video answers fps, frame_count, width and height, plus the soundtrack's
+    sample_rate, channels, peak_dbfs and mean_dbfs when it carries one;
+    audio answers the soundtrack fields. Levels come from decoding the
+    whole track, which is cheap next to generating it.
+    """
+    try:
+        container = av.open(path)
+    except Exception as e:
+        logger.debug(f"Not probeable as media: {path}: {e}")
+        return None
+    with container:
+        video = container.streams.video[0] if container.streams.video else None
+        audio = container.streams.audio[0] if container.streams.audio else None
+        if video is None and audio is None:
+            return None
+        info = {}
+        if video is not None:
+            info["kind"] = "video"
+            info["fps"] = float(video.average_rate) if video.average_rate else None
+            info["frame_count"] = int(video.frames) if video.frames else None
+            info["width"] = int(video.width)
+            info["height"] = int(video.height)
+        else:
+            info["kind"] = "audio"
+        if container.duration is not None:
+            info["duration_seconds"] = container.duration / av.time_base
+        if audio is not None:
+            info["sample_rate"] = int(audio.rate)
+            info["channels"] = int(audio.channels)
+            info["peak_dbfs"], info["mean_dbfs"] = _audio_levels(container, audio)
+        return info
+```
+
+If `frame_count` comes back `None` for the test mp4 (some muxers do not write the count), count the decoded video frames instead: `sum(1 for _ in container.decode(video))` - do that only when `video.frames` is 0, and decode video before audio so the two passes do not interleave.
+
+- [ ] **Step 4: Run the tests**
+
+Run: `python -m pytest tests/test_media_info.py -q`
+Expected: 5 pass. Adjust the level tolerances only if AAC's lossy encode shifts the mp4 peak by more than 1 dB - the wav assertions must hold exactly as written.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/media_info.py tests/test_media_info.py
+git commit -m "media_info: probe duration, format and level of a generated file"
+```
+
+### Task 9: The gallery metadata route carries `media`
+
+**Files:**
+- Modify: `dw/server/app.py:1820-1834`
+- Test: `tests/test_server.py:1062-1110`
+
+**Interfaces:**
+- Consumes: `probe_media` from Task 8; `_output_file(name, ws.outputs)` already validates and confines the path.
+- Produces: `GET /api/gallery/{name}/metadata` answers `{"name", "metadata", "job", "media"}`, `media` being `probe_media(path)` for a file whose extension is in `MEDIA_KINDS` as `audio` or `video`, else `None`.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `tests/test_server.py`, next to `test_gallery_lists_media_and_reads_metadata`:
+
+```python
+def test_gallery_metadata_describes_audio_and_video(server, tmp_path):
+    """A generated mp3 answered metadata: null and nothing else, so every
+    duration and level check was ffprobe by hand. The route now says what
+    the server knows."""
+    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 / "shot-gen.0-0.0.mp4", frames=12, fps=6)
+        Image.new("RGB", (4, 4)).save(outputs / "still-gen.0-0.0.png")
+
+        score = client.get("/api/gallery/score-gen.0-0.0.wav/metadata").json()
+        assert score["metadata"] is None
+        assert score["media"]["kind"] == "audio"
+        assert score["media"]["duration_seconds"] == pytest.approx(2.0, abs=0.01)
+        assert score["media"]["channels"] == 2
+
+        shot = client.get("/api/gallery/shot-gen.0-0.0.mp4/metadata").json()
+        assert shot["media"]["kind"] == "video"
+        assert shot["media"]["frame_count"] == 12
+
+        still = client.get("/api/gallery/still-gen.0-0.0.png/metadata").json()
+        assert still["media"] is None
+```
+
+(`from PIL import Image` and `pytest` are already imported in that file; if `tests/` is not a package, move `write_wav`/`write_mp4` into `tests/conftest.py` as plain functions and import from there instead.)
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `python -m pytest tests/test_server.py -q -k describes_audio_and_video`
+Expected: FAIL with `KeyError: 'media'`.
+
+- [ ] **Step 3: Add `media` to the route**
+
+In `dw/server/app.py`, import `from dw.media_info import probe_media` beside the other `dw.` imports, and change `gallery_metadata`:
+
+```python
+    @app.get("/api/gallery/{name:path}/metadata")
+    def gallery_metadata(name: str, ws: Workspace = Depends(selected_workspace)):
+        """Generation metadata embedded in a saved image ('workflow' inside
+        it is the full definition the editor can reopen), plus the job that
+        produced the file when history remembers one, plus - for audio and
+        video - what the file itself holds: duration, format and level,
+        which is how an agent that cannot listen checks a track."""
+        path = _output_file(name, ws.outputs)
+        metadata = read_embedded_metadata(path)
+        try:
+            job = manager.history.job_for_file(name, workspace=ws.name)
+        except Exception:
+            job = None
+        extension = os.path.splitext(path)[1].lower()
+        media = (
+            probe_media(path)
+            if MEDIA_KINDS.get(extension) in ("audio", "video")
+            else None
+        )
+        return {"name": name, "metadata": metadata, "job": job, "media": media}
+```
+
+Keep the existing "Scoped to this workspace" comment above the `job_for_file` call.
+
+- [ ] **Step 4: Run the tests**
+
+Run: `python -m pytest tests/test_server.py -q -k gallery`
+Expected: pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/server/app.py tests/test_server.py
+git commit -m "Gallery metadata: describe audio and video files"
+```
+
+### Task 10: The MCP tool and the skills say what to check
+
+**Files:**
+- Modify: `dw_mcp/catalog.py:104-107`, `dw_mcp/server.py:287-295`
+- Modify: `plugins/dw/skills/minimax-music3/SKILL.md` (the `get_gallery_metadata` duration check), `plugins/dw/skills/minimax-h3/SKILL.md` (if it mentions checking audio)
+- Modify: `docs/MCP.md` tool table entry for `get_gallery_metadata`
+- Test: `tests/test_mcp_catalog.py`, `tests/test_plugin_skills.py`
+
+**Interfaces:**
+- Consumes: the `media` block from Task 9.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `tests/test_mcp_catalog.py` (using its `scripted` helper and the metadata route):
+
+```python
+def test_gallery_metadata_passes_the_media_block_through_and_says_how_to_read_it():
+    body = {
+        "name": "score.mp3",
+        "metadata": None,
+        "job": {"id": "job-1", "status": "succeeded"},
+        "media": {"kind": "audio", "duration_seconds": 45.05, "peak_dbfs": -1.0},
+    }
+    client, _ = scripted({("GET", "/api/gallery/score.mp3/metadata"): (200, body)})
+
+    result = catalog.get_gallery_metadata(client, "score.mp3")
+
+    assert result["media"]["duration_seconds"] == 45.05
+    assert "audio_duration" in result["next"]
+```
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `python -m pytest tests/test_mcp_catalog.py -q -k media_block`
+Expected: FAIL with `KeyError: 'next'`.
+
+- [ ] **Step 3: Implement**
+
+`dw_mcp/catalog.py`:
+
+```python
+def get_gallery_metadata(client, name):
+    """Metadata embedded in a saved file: the full workflow that made it,
+    plus the job that produced it when history remembers one, plus for
+    audio and video what the file holds - duration, sample rate, channels,
+    fps, size, peak and mean level in dBFS."""
+    body = client.get_json(api_path("api", "gallery", name, "metadata"))
+    media = body.get("media")
+    if media and media.get("kind") in ("audio", "video"):
+        body["next"] = (
+            "Check duration_seconds against what was asked for: a Music 3 "
+            "track that lands within 0.2 s of its audio_duration ceiling was "
+            "cut off, one well short of it finished naturally. peak_dbfs is "
+            "the level normalize_audio would be given; mean_dbfs below -40 "
+            "on a track that should be full is a near-silent render."
+        )
+    return body
+```
+
+`dw_mcp/server.py` `get_gallery_metadata` docstring: append "For audio and video the `media` block carries duration, sample rate, channels, fps, size and level - the checks an agent that cannot listen makes on a deliverable."
+
+`plugins/dw/skills/minimax-music3/SKILL.md`: where it tells the agent to use `get_gallery_metadata` to check duration, state the rule: "`media.duration_seconds` within 0.2 s of `audio_duration` means the ceiling cut the track; raise the ceiling and rerun. Well short of it means the song finished." `tests/test_plugin_skills.py` pins numbers to diffusers symbols - 0.2 s is a measurement, not a model constant, so it needs no pin; run the test to confirm.
+
+`docs/MCP.md`: extend the `get_gallery_metadata` row with "and, for audio/video, a `media` block (duration, rate, channels, fps, size, peak/mean dBFS)".
+
+- [ ] **Step 4: Run the tests**
+
+Run: `python -m pytest tests/test_mcp_catalog.py tests/test_mcp_server.py tests/test_plugin_skills.py -q`
+Expected: pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw_mcp/catalog.py dw_mcp/server.py plugins/dw/skills docs/MCP.md tests/test_mcp_catalog.py
+git commit -m "get_gallery_metadata: surface the media block and how to read it"
+```
+
+### Task 11: PR
+
+- [ ] **Step 1:** `python -m pytest tests -q` - all pass.
+- [ ] **Step 2:** Open a PR titled "Gallery metadata describes audio and video" citing field-report #6 and #6a. Note in the body that the per-second level envelope (#6's last ask) is deliberately not in this PR - see Deferred.
+
+---
+
+# Deferred (not planned here; each is its own brainstorm)
+
+- **`loop_audio` task (#2b).** A room-tone bed under a cut is the only complete fix for the seam hole; needs `loop_audio(source, target_frames, fps, crossfade_ms)` composing with `mix_audio` + `pair_audio`. Small task, but a template (`dialogue-short`) should demonstrate it, and that wants a measured bed on real H3 output first.
+- **`compose_text` task (#8).** Character bibles written once and assembled per shot as a task step (`previous_result:compose_shot_n`), instead of `{{var}}` interpolation, which the no-interpolation rule in `docs/WORKFLOW_GUIDE.md:285` exists to forbid. Needs a decision on the template syntax (positional parts vs named) - brainstorm first.
+- **List-driven step count for generation templates (#7).** `music-video`/`dialogue-short` generate per shot; a `shots: [...]` variable that fans out *generation* steps is an engine feature (a `for_each` over a variable), not a template edit. `assemble-and-score` already takes a list after PR-1.
+- **Per-second level envelope (#6).** `probe_media(path, envelope=True)` returning `[rms_dbfs per second]`; cheap once Task 8 exists, but it belongs behind an opt-in query parameter so the default metadata call stays small - the same lesson as #4.

From 1f641d7813e803bd1c4439c8d6dee42c85268bd8 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 10 Sep 2026 22:57:23 -0500
Subject: [PATCH 3/3] Plan: authoring test helper detail

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../2026-09-10-mcp-field-report-followups.md    | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/docs/superpowers/plans/2026-09-10-mcp-field-report-followups.md b/docs/superpowers/plans/2026-09-10-mcp-field-report-followups.md
index 125a6be4..5e21c69c 100644
--- a/docs/superpowers/plans/2026-09-10-mcp-field-report-followups.md
+++ b/docs/superpowers/plans/2026-09-10-mcp-field-report-followups.md
@@ -254,7 +254,22 @@ def test_validate_can_name_a_workspace_for_one_request():
     assert client.workspace == DEFAULT_WORKSPACE
 ```
 
-(Import `DEFAULT_WORKSPACE` from `dw_mcp.client`; check the helper records `params` - the diagnose one does, the authoring one may need the same `"params": dict(request.url.params)` line added.)
+`tests/test_mcp_authoring.py`'s `scripted` records only `(method, path)` keys in `seen`. Add a second helper beside it rather than changing the existing one's shape:
+
+```python
+def scripted_with_params(routes):
+    seen = []
+
+    def handler(request):
+        key = (request.method, request.url.path)
+        seen.append({"key": key, "params": dict(request.url.params)})
+        status, body = routes.get(key, (404, {"detail": f"unrouted {key}"}))
+        return httpx.Response(status, json=body)
+
+    return DwClient(transport=httpx.MockTransport(handler)), seen
+```
+
+and use it in the new test (`client, seen = scripted_with_params(...)`). Import `DEFAULT_WORKSPACE` from `dw_mcp.client`.
 
 - [ ] **Step 2: Run them to verify they fail**