From 7bd942ccee1e493ae3662b9957ddd42121808b7e Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 13:22:34 +0000
Subject: [PATCH 01/32] Proposal: scripted dialogue shorts and where TTS
 belongs

Design notes only. Records why dialogue audio should not be generated
ahead of H3 (follow-supplied-audio lip sync is the weak pathway), where a
text-to-speech task does earn its place (voice timbre reference), and the
larger missing piece: script -> Context-IR shot list.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs/proposals/scripted-dialogue-and-tts.md | 109 ++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 docs/proposals/scripted-dialogue-and-tts.md

diff --git a/docs/proposals/scripted-dialogue-and-tts.md b/docs/proposals/scripted-dialogue-and-tts.md
new file mode 100644
index 00000000..fbac2a1b
--- /dev/null
+++ b/docs/proposals/scripted-dialogue-and-tts.md
@@ -0,0 +1,109 @@
+# Proposal: scripted dialogue shorts, and where text-to-speech belongs
+
+Status: design only, no code changes. Records the conclusion of a design
+discussion about supporting a flow like: *write a script of two people talking
+→ give each a consistent voice and face → generate H3 clips of each speaking
+their lines → cut between them into a finished dialogue scene.*
+
+## The question
+
+Should text-to-speech become a task (or a workflow shape), generating each
+speaker's lines as audio up front, which H3 then follows? Or does predefined
+textual content belong inside H3 itself?
+
+## Conclusion: do not generate the dialogue audio first
+
+The text being predefined is not an argument for TTS. H3 already takes
+predefined dialogue — it speaks the exact line written inline in the prompt:
+
+```
+<Subject 1> (S1), a fast, nasal, high-pitched male tenor voice, tight with
+disbelief, says <d>[English] Okay. Who finished the pistachio?</d>
+```
+
+Generating the audio first and asking H3 to follow it moves every line of
+dialogue onto the model's weak pathway. H3 lip-syncs well when it *generates*
+the speech (speech and mouth come out of one process, sync is free) and poorly
+when it must *follow* an audio reference. Investigated 2026-09-04 on the
+MarmotCroons rebuild; ruled out with a run each: conditioning-window choice,
+prompt language, LoRA family, 30 steps without the turbo LoRA, and dw's own
+plumbing (verified end to end). Nothing recovered it. Conditioning on a
+centre-extracted vocal isolate was a partial win, not a fix.
+
+So: script → TTS → `match_audio` trades away the one thing that works for free.
+
+## The workflow already largely exists
+
+[`workflows/minimax/MiniMaxH3SitcomShort.json`](../../workflows/minimax/MiniMaxH3SitcomShort.json)
+is nearly the described flow already:
+
+- two Z-Image steps draw the cast portraits (the second reuses the first's
+  loaded pipeline; `release_pipeline` frees it before the video model loads)
+- the first shot loads H3 once; the remaining shots are `pipeline_reference`
+  steps rerunning that loaded model with a new prompt, references and length
+- `concat_videos` splices the episode with hard cuts, and `audio_bleed_ms`
+  rings each shot's room tone over the silent head of the next, so only the
+  picture cuts hard
+
+Consistency in this cut-based shape comes from repetition, not from a shared
+audio track:
+
+| What stays consistent | How |
+| --- | --- |
+| Identity | reference the same portrait in every shot |
+| Voice | repeat the character's voice description **verbatim** in every prompt |
+| Ambience | repeat `overall_soundscape` verbatim; `audio_bleed_ms` carries it across the cut |
+| Quality | each shot is generated fresh from the portraits, so shot 12 is as clean as shot 1 |
+
+Constraints to design around: a shot is 5.17–14.4 s (`num_frames` of the form
+`17n + 5`, 124–345, at 24 fps), so a long line must be split across shots; and
+roughly 13 shots is the ceiling for a single `dw.run` on a 24 GB box — beyond
+that, batch and stitch.
+
+## Where a TTS task does earn its place
+
+There is no TTS in the repo today. It is worth adding, in these roles — none of
+which is "the track the mouth follows":
+
+1. **Voice *timbre* reference.** `ref2va` takes an `<Audio 1>` reference that
+   fixes a voice while H3 still generates the speech — see
+   [`MiniMaxH3Ref2VA.json`](../../workflows/minimax/MiniMaxH3Ref2VA.json), whose
+   `retention_analysis` says explicitly that only timbre, pitch and delivery are
+   referenced and "none of its content is reused". A few seconds of TTS per
+   character, referenced in every shot, makes voice consistency an actual
+   conditioning signal rather than hoping prose like "flat, low, unhurried
+   baritone" lands identically twelve times. Keeps the strong sync pathway.
+   Highest value, smallest change.
+2. **A voice that must be matched** — a cloned or specific voice, or a delivery
+   H3 will not produce from description alone.
+3. **Non-lip-sync audio** — narration over B-roll and cutaways, muxed with
+   `pair_audio`, where no mouth has to follow it.
+
+### Shape
+
+Model it on [`dw/tasks/text_generation.py`](../../dw/tasks/text_generation.py):
+a HuggingFace `text-to-speech` pipeline behind `cached_model`, returning a
+waveform plus sample rate, so it composes with the existing `slice_audio`,
+`pair_audio` and `concat_videos` tasks. A task, not an H3 pipeline mode.
+
+## The larger gap: script → Context-IR shot list
+
+Bigger than TTS. `generate_text` can write prose dialogue, but H3 wants
+Context-IR: `subject_definitions` / `summary` / `retention_analysis` /
+`detailed_description` / `overall_soundscape` / `non_diegetic_music`. Turning a
+plain script into one Context-IR prompt **per shot** — voice descriptions
+carried verbatim, speaker alternation driving the cuts — is the piece that does
+not exist.
+
+It must also strip the portrait of compositional authority, in
+`subject_definitions` *and* in a `<Picture N>` `retention_analysis` entry
+("carries no compositional detail: no framing, no shot size, no camera
+position"). Without that the reference's framing wins and every shot comes back
+as the same medium shot, so the cuts read as jump cuts. Measure framing variety
+as mean absolute difference between shots' average frames; under ~10 means the
+reference won.
+
+## Suggested next step
+
+Prototype either (a) the `generate_speech` task in its timbre-reference role, or
+(b) the script → Context-IR shot-list step. (b) is the higher-value one.

From e75fa843bafefe1e52e16b175d8f5892f060a618 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 13:49:25 -0500
Subject: [PATCH 02/32] Implement text-to-speech functionality with
 generate_speech task

- Removed the MCP proposal document as it is no longer needed.
- Added a new task for speech generation using Hugging Face transformers, allowing the generation of audio from text with a specified voice preset.
- Introduced AudioTrack class to encapsulate generated audio and its sample rate.
- Updated media_arguments to handle AudioTrack and AudioVideo types.
- Created workflows for generating speech and integrating it into video generation, ensuring that the audio sample rate is preserved.
- Added tests for the speech generation functionality to ensure correct behavior and integration.
---
 docs/TASKS.md                                 |  53 ++++
 docs/proposals/mcp.md                         | 253 ------------------
 docs/proposals/scripted-dialogue-and-tts.md   |  30 +++
 dw/arguments.py                               |  12 +-
 dw/result.py                                  |  40 ++-
 dw/tasks/speech_generation.py                 | 103 +++++++
 dw/tasks/task.py                              |  13 +
 tests/test_arguments.py                       |  22 ++
 tests/test_result.py                          |  30 +++
 tests/test_speech_generation.py               | 132 +++++++++
 .../minimax/MiniMaxH3GeneratedVoice.json      | 165 ++++++++++++
 workflows/tasks/GenerateSpeech.json           |  25 ++
 12 files changed, 618 insertions(+), 260 deletions(-)
 delete mode 100644 docs/proposals/mcp.md
 create mode 100644 dw/tasks/speech_generation.py
 create mode 100644 tests/test_speech_generation.py
 create mode 100644 workflows/minimax/MiniMaxH3GeneratedVoice.json
 create mode 100644 workflows/tasks/GenerateSpeech.json

diff --git a/docs/TASKS.md b/docs/TASKS.md
index c814331b..4d62d171 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -953,6 +953,57 @@ It is merged after everything else, so it can override `repetition_penalty` and
 - [ExpandPrompt.json](../workflows/tasks/ExpandPrompt.json) — Expand a short prompt and save as `.txt`
 - [ExpandAndGenerate.json](../workflows/tasks/ExpandAndGenerate.json) — Expand prompt, then generate with Flux
 
+## Speech Generation
+
+Speak a line of text with a local text-to-speech model. The result is a waveform carrying the rate its model generated at, so it composes with [`slice_audio`](#slice_audio), [`fade_audio`](#fade_audio), [`pair_audio`](#pair_audio) and [`concat_videos`](#concat_videos) directly.
+
+```json
+{
+    "task": {
+        "command": "generate_speech",
+        "arguments": {
+            "text": "The way ahead is longer still.",
+            "voice_preset": "v2/en_speaker_6"
+        }
+    },
+    "result": { "content_type": "audio/wav" }
+}
+```
+
+| Argument | Required | Description |
+| -------- | -------- | ----------- |
+| `text` | Yes | The line to speak |
+| `model_name` | No | HuggingFace model ID (default: `suno/bark-small`) |
+| `voice_preset` | No | The speaker, for a model with presets — `v2/en_speaker_0` through `v2/en_speaker_9` for Bark |
+| `forward_params` | No | Passed to the model's forward/generate call |
+| `generate_kwargs` | No | Ad-hoc generation settings for a generative model — `temperature`, `do_sample` |
+
+The default is Bark because its voice presets give distinct speakers, which is what two characters in a scene need; `facebook/mms-tts-eng` is a quarter the size and a good override where one voice will do. `voice_preset` is a preprocessing argument — it selects the speaker before generation rather than parameterizing it — so naming it here is what makes it reach the processor. Passed through `forward_params` it would be dropped and every character would sound the same.
+
+The result needs no `sample_rate`. A generated track carries the rate its model produced it at, and that beats the 44100 default; declaring one still wins over both, for a track whose rate was reported wrong. Every TTS model runs at a different rate, so a declared rate that does not match plays the speech at the wrong speed and pitch without ever failing.
+
+### Generating a voice to condition on
+
+The role this earns its place in is voice *timbre reference*, not the track a mouth follows. MiniMax H3 lip-syncs well when it generates the speech itself and poorly when it must follow supplied audio, so its `MiniMaxH3AudioReference` takes a few seconds of a voice to fix timbre, pitch and delivery while H3 still generates the line. Build the reference with `from_previous_result` and the clip's own sample rate comes across with it:
+
+```json
+"references": [
+    {
+        "reference_type": "diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference",
+        "from_previous_result": "voice"
+    }
+]
+```
+
+Referencing the same preset in every shot of a scene makes a character's voice a conditioning signal rather than a prose description that has to land identically a dozen times. The other honest uses are a voice that must be matched — a specific delivery H3 will not produce from description alone — and narration over shots where nothing has to lip-sync to it, muxed with [`pair_audio`](#pair_audio).
+
+A speech model is worth releasing before a video model loads — set `release_models` on the step, as in the example below.
+
+**Examples:**
+
+- [GenerateSpeech.json](../workflows/tasks/GenerateSpeech.json) — Speak a line and save it as a `.wav`
+- [MiniMaxH3GeneratedVoice.json](../workflows/minimax/MiniMaxH3GeneratedVoice.json) — Generate a voice, then condition H3's `<Audio 1>` on it
+
 ## Frame Interpolation
 
 Increase video frame rate using RIFE (Real-Time Intermediate Flow Estimation). Takes a video and inserts intermediate frames between each pair. The result is one video artifact without a soundtrack - the frame count changed, so [`pair_audio`](#pair_audio) is how the original track comes back. [InterpolateFrames.json](../workflows/InterpolateFrames.json) shows the interpolation itself.
@@ -1164,4 +1215,6 @@ Canny edge detection followed by ControlNet generation:
 - [UpscaleImage.json](../workflows/tasks/UpscaleImage.json) — Spandrel upscale of an existing image
 - [DiffusionUpscaleImage.json](../workflows/tasks/DiffusionUpscaleImage.json) — Diffusion upscale of an existing image
 - [TrimFadeAudio.json](../workflows/tasks/TrimFadeAudio.json) — Trim a generated track and fade its tail
+- [GenerateSpeech.json](../workflows/tasks/GenerateSpeech.json) — Speak a line with a local text-to-speech model
+- [MiniMaxH3GeneratedVoice.json](../workflows/minimax/MiniMaxH3GeneratedVoice.json) — Generate a voice and condition H3's `<Audio 1>` on it
 - [GyreDissolve.json](../workflows/gyre/GyreDissolve.json) — Stabilize generated shots, dissolve between them, and mix a score under their own audio
diff --git a/docs/proposals/mcp.md b/docs/proposals/mcp.md
deleted file mode 100644
index 17ce6abe..00000000
--- a/docs/proposals/mcp.md
+++ /dev/null
@@ -1,253 +0,0 @@
-# MCP Server for diffusers-workflow — Scoping Doc
-
-> Status: scoped and verified against the code on 2026-09-01. The design
-> that came out of this document is
-> [2026-09-01-mcp-server-design.md](../specs/2026-09-01-mcp-server-design.md).
-
-## Background
-
-`diffusers-workflow` (dkackman/diffusers-workflow) is a declarative JSON
-workflow engine for Hugging Face Diffusers, with a local HTTP server
-(`dw.serve`, default port 8765) that exposes a full REST API: workflow
-CRUD, a job queue with SSE progress streaming, model management,
-introspection of diffusers pipeline signatures, and a gallery of past
-generations with embedded metadata.
-
-Today, workflow authoring and debugging, for the project developer, can
-happen via Claude Code in VS Code, with direct repo/filesystem access:
-"create a workflow that does X," or "workflow Y produces bad output, find
-out why" — Claude Code runs the workflow, reads logs, checks GPU memory,
-and proposes fixes to code or workflow config. It has even gone so far as
-to identify bad RAM causing intermittent generation failures.
-
-That flow works well for the developer (me), but it assumes a dev
-environment: a repo checkout, a terminal, VS Code, comfort reading stack
-traces. The next audience is **non-developer end users** of the packaged
-product, who won't have any of that. They'll have the app (web UI /
-`dw.serve`, or an embedded product surface), not a coding agent with shell
-access.
-
-## Goal
-
-The modes a workflow can be authored and run in today:
-
-- a text editor plus the CLI, `python -m dw.run workflow.json`
-- the command-line REPL, `python -m dw.repl`
-- the HTTP API `dw.serve` and its web UI
-
-Add a fourth: an **MCP server** wrapping the existing `dw.serve` HTTP API,
-exposing the same "author a workflow / run it / diagnose why it failed or
-produced bad output" capability through a bounded, structured tool surface
-— no shell, no repo checkout, no stack traces. Any MCP-compatible client
-can drive it: Claude Code first, later an embedded chat UI in the product,
-and eventually a local-LLM-backed client for users without a paid Claude
-subscription.
-
-## Why MCP (not just keep using Claude Code)
-
-- Claude Code assumes a dev environment; end users won't have one.
-- MCP tools are a defined, constrained surface (structured in/out, no
-  arbitrary code execution) — appropriate once non-developers are the
-  audience, and safer than raw shell access.
-- The underlying HTTP API already exists and is already defensive (path
-  validation, traversal blocking, `Origin` header checks, JSON size
-  limits) — MCP adds a protocol layer in front of it, not new attack
-  surface.
-- Protocol-agnostic: the same server can later be pointed at Claude Code,
-  a future embedded chat UI, or a local-LLM-backed client.
-
-## Rollout sequence (decided)
-
-1. **MCP server + Claude Code** as the client, for continued dev use and
-   to validate the tool surface.
-2. **Embedded-in-app** later, once the product is packaged for
-   non-developer users. This phase needs its own auth story, since the
-   server binds to `127.0.0.1` with no authentication (see Security,
-   below) — fine for local/trusted-LAN use, not fine for a hosted product.
-3. **Local LLM support** stays a goal throughout. MCP is
-   protocol-agnostic, so this is a separate, later concern, not a blocker.
-
-## Topology
-
-`dw_mcp/` is a **stdio MCP server that is an HTTP client of a running
-`dw.serve`**. (It shipped as `dw/mcp/` and moved to a top-level package in
-F8, below.) It owns no job state, no GPU, and no worker process; it
-holds no state the REST API doesn't already hold. If `dw.serve` isn't
-reachable it fails with an instruction to start it, rather than starting
-one itself.
-
-Rejected: embedding the FastAPI app in-process. `create_app()` builds its
-own `JobManager` and GPU worker, so an in-process copy running alongside a
-real `dw.serve` would mean two workers contending for one GPU — which the
-single-job-at-a-time design cannot tolerate.
-
-## Proposed MCP tool set
-
-Mapped to existing `dw.serve` routes. One new endpoint is required (see
-"Corrections", below); everything else exists.
-
-### Read-only / low-cost (build first)
-
-| Tool | Route(s) | Notes |
-| --- | --- | --- |
-| `list_workflows` | `GET /api/workflows` | descriptions, output kinds, variable counts |
-| `get_workflow(name)` | `GET /api/workflows/{name}` | full JSON |
-| `validate_workflow(json)` | `POST /api/validate` | schema + signature-level argument checks; no GPU cost — the pre-flight tool |
-| `get_schema` | `GET /api/schema` | workflow JSON schema |
-| `list_pipelines` | `GET /api/pipelines` | what pipelines the installed diffusers offers |
-| `get_pipeline_signature(name)` | `GET /api/pipelines/{name}` | real pipeline arguments, before proposing a config fix |
-| `list_classes(kind)` / `get_class(name)` | `GET /api/classes?kind=...`, `GET /api/classes/{name}` | broader introspection beyond pipelines |
-| `list_tasks` / `get_task(command)` | `GET /api/tasks`, `GET /api/tasks/{command}` | task-step argument schemas |
-| `list_models` | `GET /api/models` | hub cache inventory: sizes, revisions, last-used |
-| `get_memory` | `GET /api/memory` | worker VRAM/RAM stats — answers the GPU-diagnosis need directly |
-| `get_health` | `GET /api/health` | liveness |
-| `list_jobs` | `GET /api/jobs` | live queue plus recent history |
-| `list_gallery(limit)` | `GET /api/gallery` | recent outputs, newest first |
-| `get_gallery_metadata(name)` | `GET /api/gallery/{name}/metadata` | a prior run's exact workflow + seed, e.g. to reproduce a failure |
-| `get_output_image(name, max_dimension)` | `GET /outputs/{name}` (static mount) | returns a downscaled MCP image block — this is how the agent actually *sees* bad output |
-
-### Authoring (build second)
-
-| Tool | Route(s) | Notes |
-| --- | --- | --- |
-| `save_workflow(name, json)` | `PUT /api/workflows/{name}` | overwrites; `destructiveHint: true`, `idempotentHint: true` |
-| `delete_workflow(name)` | `DELETE /api/workflows/{name}` | `destructiveHint: true` |
-
-Without these the server is a read-only advisor: it can propose a workflow
-but never complete the validate-then-save loop.
-
-### Diagnostic loop (build third)
-
-| Tool | Route(s) | Notes |
-| --- | --- | --- |
-| `run_workflow(workflow_path \| inline_workflow, arguments, acknowledged_cost)` | `POST /api/jobs` | **Costs GPU time; one job runs at a time.** Submits and returns immediately. See confirm-gating below. |
-| `get_job(job_id)` | `GET /api/jobs/{id}` | status, arguments, warnings, manifest, error, traceback, `event_count` |
-| `get_job_events(job_id, after, limit)` | `GET /api/jobs/{id}/event-log` **(new)** | live or persisted `job_status` / `phase` / `memory` / `log` events — phase transitions (loading → generating → decoding → saving) |
-| `cancel_job(job_id)` | `POST /api/jobs/{id}/cancel` | cooperative cancel |
-| `rerun_job(job_id, acknowledged_cost)` | `POST /api/jobs/{id}/rerun` | re-queue after a fix — cost-gated like a run |
-| `move_job(job_id, direction)` | `POST /api/jobs/{id}/move` | reorder queued jobs |
-
-### Deferred / optional
-
-- `POST /api/models/download`, `DELETE /api/models`, `/api/system/diffusers*`
-  — model and dependency management; useful eventually, not needed for the
-  first author/run/diagnose loop.
-- Prompt library endpoints (`/api/prompts*`, `/api/enhance`,
-  `/api/enhancers`, `/api/prompt-schema`) — relevant if the agent should
-  also help build/enhance prompts, not core to diagnosis.
-- `base_dir` on `POST /api/jobs` is deliberately **not** exposed. It is a
-  path-authority parameter that decides where an inline workflow's
-  relative paths resolve; v1 lets them resolve against the server's own
-  workflow directory only.
-
-## Corrections found while verifying against the code
-
-Checked against `dw/server/app.py` and `dw/server/jobs.py` on 2026-09-01.
-
-1. **`get_job` returns no events and no spec.** `Job.detail()`
-   (`jobs.py:222`) returns `event_count`, not `events`, and `arguments`,
-   not the whole spec. The event trail exists only behind the SSE stream,
-   which a request/response MCP tool cannot consume sensibly. Hence the
-   one new endpoint, `GET /api/jobs/{job_id}/event-log`.
-2. **Outputs are not on an `/api` route.** Generated media is served from
-   a `StaticFiles` mount at `/outputs` (`app.py:840`). Any tool that shows
-   the agent an image must read from there.
-3. **MCP does have a confirmation primitive.** The 2025-06-18 spec
-   revision added **elicitation**, and tool **annotations**
-   (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`)
-   exist for exactly this purpose. The earlier claim that confirmation had
-   to live entirely in client prose was wrong.
-4. **Events did not survive a restart.** They live in the in-memory `Job`
-   object (`jobs.py:182`); `JobHistory` persisted eleven columns and none
-   of them was the event log, so a job recovered from history had no
-   trail. Originally deferred as F1, this has been pulled into the build —
-   history now persists a bounded tail of each job's events.
-
-## Key design decisions
-
-1. **`run_workflow` is confirm-gated, in three layers.** A run costs real
-   GPU time and the engine is single-GPU/single-job-at-a-time. The tool
-   carries annotations so a client can surface the cost; it uses MCP
-   elicitation when the client advertises that capability; and it requires
-   an explicit `acknowledged_cost` argument as the client-agnostic floor,
-   since Claude Code does not implement elicitation today.
-   `validate_workflow` is free and runs first, without confirmation.
-
-2. **`run_workflow` never blocks.** It submits and returns
-   `{job_id, status, queue_position}` immediately. A generation takes
-   minutes; no MCP client will hold a tool call open that long. Progress
-   comes from polling `get_job_events`.
-
-3. **Security model carries over, doesn't change.** The server already
-   validates every path (`dw/security.py`), blocks traversal, rejects
-   non-local `Origin` headers, and confines file access to the configured
-   workflow/output/prompt directories. MCP wrapping this doesn't add new
-   risk for the local/Claude-Code phase. It does **not** solve remote
-   auth — the server binds to `127.0.0.1` by default with no
-   authentication; `--host 0.0.0.0` exists but is explicitly documented as
-   trusted-LAN-only. The embedded-in-app phase needs a real auth story
-   before any hosted/remote exposure.
-
-4. **Tools only, no resources or prompts, in v1.** `get_schema` and
-   `get_workflow` are natural MCP *resources*, and "diagnose this job" is
-   a natural MCP *prompt* — but client support for tools is universal and
-   support for the other two is not. Revisit once the tool surface has
-   been validated.
-
-5. **Build order:** read-only tools first (a workflow authoring assistant
-   usable almost immediately), then authoring writes, then the
-   run/diagnose loop once confirm-gating is settled.
-
-## Post-v1 follow-ups
-
-Deliberately out of the first build. Each is its own change. (F1, persisting
-a job's event tail, was pulled into the build instead — without it the
-diagnostic loop only explains jobs from the current server process, which is
-the wrong trade for the non-developer audience this is aimed at.)
-
-- **F2 — Cost/time estimation for the confirm prompt.** Nothing in the API
-  can say "this will take about four minutes." Job history holds durations
-  per workflow id; a `GET /api/workflows/{name}/stats` could turn that
-  into an estimate worth putting in front of a human before a run.
-- **F3 — Expose the server log.** `log_filename` is already a setting; a
-  `get_server_log(tail)` tool would help diagnosis, but it widens the read
-  surface beyond the confined directories and needs its own redaction
-  thinking first.
-- **F4 — Model and dependency management tools.** *(Done 2026-09-01.)* The
-  deferred `/api/models/*` and `/api/system/diffusers*` routes — the first
-  wall a non-developer hits is "that model isn't downloaded," and until this
-  the agent could see the gap and not close it. Six tools in `dw_mcp/models.py`:
-  `download_model`, `list_downloads`, `cancel_download`, `delete_model`,
-  `get_diffusers_state`, `update_diffusers`.
-
-  This widened the `acknowledged_cost` gate past its original GPU-only
-  charter. `download_model` (tens of gigabytes), `delete_model`
-  (unrecoverable without re-downloading) and `update_diffusers` (an untagged
-  development build, no undo) each carry it, with a distinct refusal message
-  apiece: one shared message would be wrong for each of them in a different
-  way, and a gate the user learns to wave through is not a gate. The two
-  cancels stay ungated — they end a cost rather than starting one, and
-  gating them would make the safe direction the harder one.
-- **F5 — Prompt library tools.** `/api/prompts*` and `/api/enhance`, for
-  an agent that helps compose prompts rather than only workflows.
-- **F6 — MCP resources and prompts.** Re-expose the schema, workflows, and
-  gallery as resources, and ship a "diagnose this job" prompt template,
-  once target clients support them.
-- **F7 — Remote/auth story.** Required before the embedded-in-app phase.
-  Blocks any non-localhost exposure of either the REST API or the MCP
-  server.
-- **F8 — The MCP server imported the whole engine.** *(Found during the v1
-  build; not part of the original scoping. Done 2026-09-01.)* The package
-  shipped as `dw/mcp/`, and importing any `dw.*` submodule runs
-  `dw/__init__.py`, which imports torch and diffusers — so a process that is
-  a pure HTTP client, owning no models, paid for the model framework at
-  startup. Measured: `import dw` 1.05s (1.40s cumulative) against 0.35s for
-  the client's own dependencies (`httpx`, `PIL`, `mcp`). Paid once per
-  client session, since a stdio server is spawned once and lives for the
-  session — a real but modest cost, which is why this is recorded with its
-  numbers rather than asserted as severe. Fixed by moving the package to a
-  top-level `dw_mcp/`, taking startup to 0.36s with torch never imported.
-  A regression guard in `tests/test_mcp_server.py` asserts the boundary
-  (`torch`, `diffusers` and `dw` absent from `sys.modules` after importing
-  `dw_mcp.server`), because the failure mode is one convenience import away
-  and is otherwise invisible.
diff --git a/docs/proposals/scripted-dialogue-and-tts.md b/docs/proposals/scripted-dialogue-and-tts.md
index fbac2a1b..3b02eb12 100644
--- a/docs/proposals/scripted-dialogue-and-tts.md
+++ b/docs/proposals/scripted-dialogue-and-tts.md
@@ -107,3 +107,33 @@ reference won.
 
 Prototype either (a) the `generate_speech` task in its timbre-reference role, or
 (b) the script → Context-IR shot-list step. (b) is the higher-value one.
+
+## What was built (2026-09-06)
+
+(a) is implemented: the `generate_speech` task
+([`dw/tasks/speech_generation.py`](../../dw/tasks/speech_generation.py),
+documented in [TASKS.md](../TASKS.md#speech-generation)), with
+[`GenerateSpeech.json`](../../workflows/tasks/GenerateSpeech.json) and
+[`MiniMaxH3GeneratedVoice.json`](../../workflows/minimax/MiniMaxH3GeneratedVoice.json)
+showing the timbre-reference role.
+
+It returns an `AudioTrack` - a waveform carrying the rate it was generated at -
+rather than the bare waveform the other audio tasks return. Those rates are a
+property of the workflow; a TTS model's rate is a property of the model, and every
+one of them differs, so a declared 44100 against a 24 kHz model plays the speech
+fast and low without ever failing. `normalize_audio` and `media_arguments` read
+`.audio`/`.sample_rate` off whatever they are handed, the way the rest of the audio
+plumbing already did, so a declared rate still wins where a workflow names one.
+
+(b) was **not** built as a task, and the reasoning is worth keeping. Turning a
+script into shots is authoring, not runtime. Putting it in the engine hides the
+prompts until after the GPU has spent the time on them, and it needs shot *i*'s
+prompt paired with speaker *i*'s portrait - a zip, where
+[`previous_results.py`](../../dw/previous_results.py) deliberately does a cartesian
+product. A generator that emits an ordinary workflow keeps the artifact
+inspectable and needs no engine change; the missing piece is then the *format
+knowledge* (the Context-IR fields, verbatim voice descriptions, the `<Picture N>`
+clause stripping compositional authority, `17n + 5`, ~13 shots a run), which is
+documentation and a template workflow rather than code. Revisit a `dw.script`
+generator or an MCP tool once that shape has been used enough by hand to be sure
+of it.
diff --git a/dw/arguments.py b/dw/arguments.py
index e27dddcb..242576b8 100644
--- a/dw/arguments.py
+++ b/dw/arguments.py
@@ -717,7 +717,6 @@ def media_arguments(object_type, artifact):
     import torch
     from PIL import Image
 
-    from .result import AudioVideo
     from .tasks.audio_utils import as_channels_samples
     from .tasks.video_utils import frames_as_pil_list
 
@@ -732,12 +731,15 @@ def media_arguments(object_type, artifact):
             )
         return {"image": artifact}
 
-    # A generated soundtrack arrives paired with the frames it was generated with;
-    # anything else the step produced carries none
+    # A generated soundtrack arrives paired with the frames it was generated with
+    # (an AudioVideo) or by itself with the rate it was generated at (an
+    # AudioTrack); anything else the step produced carries none. Read off the
+    # attributes rather than the types, which is how every other audio consumer
+    # here accepts both
     audio, sample_rate = None, None
-    if isinstance(artifact, AudioVideo) and artifact.audio is not None:
+    if getattr(artifact, "audio", None) is not None:
         audio = torch.as_tensor(as_channels_samples(artifact.audio))
-        sample_rate = artifact.sample_rate
+        sample_rate = getattr(artifact, "sample_rate", None)
 
     if kind == "video":
         frames = frames_as_pil_list(artifact)
diff --git a/dw/result.py b/dw/result.py
index dddf0599..39f8fe73 100644
--- a/dw/result.py
+++ b/dw/result.py
@@ -116,6 +116,32 @@ def __init__(self, frames, audio, sample_rate):
         self.sample_rate = sample_rate
 
 
+class AudioTrack:
+    """A generated waveform together with the rate it was generated at.
+
+    A step that produces audio alone usually returns the waveform by itself, and
+    the workflow declares the rate - which is fine where the rate is a property of
+    the workflow (a slice of a file it named) rather than of the model. It is not
+    fine for a generated track: every text-to-speech model has its own rate, and a
+    declared 44100 against a 24 kHz model plays the speech fast without failing.
+
+    Carrying the rate with the waveform is what lets a workflow say nothing about
+    it. Everything downstream of audio already reads '.audio' and '.sample_rate'
+    off whatever it is handed - slice_audio, fade_audio, pair_audio and the H3
+    audio references all accept one of these - and a rate the workflow does declare
+    still wins over the one carried here.
+    """
+
+    def __init__(self, audio, sample_rate):
+        """
+        Args:
+            audio: The waveform, shaped (channels, samples)
+            sample_rate: Sample rate the waveform was generated at
+        """
+        self.audio = audio
+        self.sample_rate = sample_rate
+
+
 class Result:
     """Manages and stores results from workflow steps.
 
@@ -378,9 +404,15 @@ def save_artifact(
                 )
             elif content_type.startswith("audio"):
                 waveforms = normalize_audio(artifact)
+                # A track generated by a model carries the rate it was generated
+                # at, which beats the default - but not a rate the workflow named
                 sample_rate = self.result_definition.get(
                     "sample_rate",
-                    self.result_definition.get("samplerate", DEFAULT_AUDIO_SAMPLE_RATE),
+                    self.result_definition.get(
+                        "samplerate",
+                        getattr(artifact, "sample_rate", None)
+                        or DEFAULT_AUDIO_SAMPLE_RATE,
+                    ),
                 )
                 # A batched waveform holds several songs - save each one separately
                 if len(waveforms) > 1:
@@ -855,11 +887,15 @@ def normalize_audio(artifact):
     optionally batched. soundfile wants samples first, one waveform at a time.
 
     Args:
-        artifact: Audio waveform(s) as a torch tensor or numpy array
+        artifact: Audio waveform(s) as a torch tensor or numpy array, or anything
+            carrying one as '.audio' - an AudioTrack, or a video whose soundtrack
+            is what is being saved
 
     Returns:
         List of numpy arrays shaped (samples,) or (samples, channels)
     """
+    artifact = getattr(artifact, "audio", artifact)
+
     # Torch tensors may be on the GPU and in a dtype numpy does not understand
     if hasattr(artifact, "detach"):
         artifact = artifact.detach().float().cpu().numpy()
diff --git a/dw/tasks/speech_generation.py b/dw/tasks/speech_generation.py
new file mode 100644
index 00000000..d559a9ee
--- /dev/null
+++ b/dw/tasks/speech_generation.py
@@ -0,0 +1,103 @@
+"""
+Speech generation via HuggingFace transformers.
+
+Takes a line of text and speaks it with a local text-to-speech model, returning
+the waveform and the rate it was generated at so the rest of the audio plumbing -
+slice_audio, fade_audio, pair_audio, concat_videos - composes with it directly.
+
+The role this is built for is voice *timbre reference*, not the track a mouth
+follows. MiniMax H3 lip-syncs well when it generates the speech itself and poorly
+when it must follow supplied audio, so its audio reference takes a few seconds of
+a voice to fix timbre, pitch and delivery while the model still generates the
+line. A generated clip referenced in every shot makes voice consistency an actual
+conditioning signal rather than a prose description that has to land identically
+a dozen times. The other honest uses are a voice that must be matched, and
+narration over shots where nothing has to lip-sync to it.
+"""
+
+import logging
+
+from transformers import pipeline as hf_pipeline
+
+from .. import get_device_type, preferred_task_dtype
+from ..result import AudioTrack
+from .audio_utils import as_channels_samples
+from .model_cache import cached_model
+
+logger = logging.getLogger("dw")
+
+# Small, loads without a separate speaker-embedding dataset, and its voice presets
+# give distinct speakers - which is the point when two characters have to sound
+# like two people. A single-voice model like facebook/mms-tts-eng is a quarter the
+# size and a reasonable override where only one voice is needed
+_DEFAULT_MODEL = "suno/bark-small"
+
+
+def generate_speech(text, device="cpu", **kwargs):
+    """Speak a line of text with a local text-to-speech model.
+
+    Args:
+        text: The line to speak.
+        device: Target device ("cuda", "mps", "cpu").
+        **kwargs:
+            model_name: HuggingFace model ID. Defaults to suno/bark-small.
+            voice_preset: The speaker to use, for a model that has presets -
+                "v2/en_speaker_6" and friends for Bark. This is a preprocessing
+                argument: it selects the speaker before generation rather than
+                parameterizing it, which is why it is named here rather than left
+                to forward_params, where it would be silently dropped.
+            forward_params: Passed to the model's forward/generate call.
+            generate_kwargs: Ad-hoc generation settings for a generative model -
+                temperature, do_sample and so on.
+
+    Returns:
+        An AudioTrack holding the waveform, shaped (channels, samples), and the
+        sample rate the model generated it at.
+
+    Raises:
+        ValueError: If the model reports no sample rate for what it generated.
+    """
+    model_name = kwargs.get("model_name", _DEFAULT_MODEL)
+    voice_preset = kwargs.get("voice_preset", None)
+    dtype = preferred_task_dtype(device)
+
+    def load_pipe():
+        logger.info(f"Generating speech with {model_name} on {device}")
+        # The same MPS accommodation text_generation makes: a device_map has the
+        # loading threads cast their shards straight onto the device, which races
+        # inside torch's Metal shader cache. Passing `device` leaves the load on
+        # the CPU and moves the finished model in one call on this thread
+        placement = (
+            {"device": device}
+            if get_device_type(device) == "mps"
+            else {"device_map": device}
+        )
+        return hf_pipeline(
+            "text-to-speech",
+            model=model_name,
+            torch_dtype=dtype,
+            **placement,
+        )
+
+    pipe = cached_model(
+        ("speech_generation", model_name, str(device), str(dtype)),
+        load_pipe,
+    )
+
+    logger.info(f"Speaking: {text[:100]}{'...' if len(text) > 100 else ''}")
+    output = pipe(
+        text,
+        preprocess_params={"voice_preset": voice_preset} if voice_preset else {},
+        forward_params=kwargs.get("forward_params") or {},
+        generate_kwargs=kwargs.get("generate_kwargs") or {},
+    )
+
+    sample_rate = output.get("sampling_rate")
+    if sample_rate is None:
+        # Saving at the 44100 default instead would be quietly wrong rather than
+        # loud, and speech at the wrong rate is wrong in pitch as well as length
+        raise ValueError(
+            f"{model_name} reported no sample rate for the speech it generated"
+        )
+
+    return AudioTrack(as_channels_samples(output["audio"]), int(sample_rate))
diff --git a/dw/tasks/task.py b/dw/tasks/task.py
index ee088e49..e84f079b 100644
--- a/dw/tasks/task.py
+++ b/dw/tasks/task.py
@@ -353,6 +353,19 @@ def _handle_text_generation(task, arguments, previous_pipelines):
     return generate_text(prompt, device=task.device_for(arguments), **arguments)
 
 
+@register_command(
+    "generate_speech",
+    implementation="dw.tasks.speech_generation.generate_speech",
+)
+def _handle_speech_generation(task, arguments, previous_pipelines):
+    """Speak a line of text with a local text-to-speech model"""
+    logger.debug("Generating speech")
+    text = arguments.pop("text")
+    from .speech_generation import generate_speech
+
+    return generate_speech(text, device=task.device_for(arguments), **arguments)
+
+
 @register_command(
     "extract_sections", implementation="dw.tasks.text_sections.extract_sections"
 )
diff --git a/tests/test_arguments.py b/tests/test_arguments.py
index ecea3413..6e5ea1f6 100644
--- a/tests/test_arguments.py
+++ b/tests/test_arguments.py
@@ -745,6 +745,28 @@ def test_an_audio_reference_takes_a_bare_waveform(self):
         assert reference.audio.shape == (2, 50)
         assert reference.sample_rate == 44100
 
+    def test_an_audio_reference_takes_a_generated_track_with_its_rate(self):
+        # A step that generates audio alone but knows the rate it generated at -
+        # generate_speech - carries the rate across rather than making the
+        # reference declare one that may not match
+        import numpy
+
+        from dw.result import AudioTrack
+
+        arguments = {
+            "reference": {
+                "reference_type": AudioReference,
+                "from_previous_result": AudioTrack(
+                    numpy.zeros((1, 50), dtype="float32"), 24000
+                ),
+            }
+        }
+
+        reference = build_objects(arguments)["reference"]
+
+        assert reference.audio.shape == (1, 50)
+        assert reference.sample_rate == 24000
+
     def test_a_named_field_wins_over_the_one_the_media_carried(self):
         # A step that generated at another rate than the consuming pipeline reads
         arguments = {
diff --git a/tests/test_result.py b/tests/test_result.py
index 47c1a4eb..68f46cff 100644
--- a/tests/test_result.py
+++ b/tests/test_result.py
@@ -638,6 +638,36 @@ def test_default_sample_rate(self):
             _, sample_rate = soundfile.read(os.path.join(temp_dir, "song-0.0.wav"))
             assert sample_rate == 44100
 
+    def test_a_track_saves_at_the_rate_it_carries(self):
+        # A generated track knows its own rate - generate_speech produces one at
+        # whatever its model runs at - so the workflow does not have to declare it
+        from dw.result import AudioTrack
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            result = Result({"content_type": "audio/wav"})
+            result.add_result(
+                AudioTrack(numpy.zeros((1, 4410), dtype=numpy.float32), 24000)
+            )
+
+            result.save(temp_dir, "line")
+
+            _, sample_rate = soundfile.read(os.path.join(temp_dir, "line-0.0.wav"))
+            assert sample_rate == 24000
+
+    def test_a_declared_rate_wins_over_the_one_the_track_carries(self):
+        from dw.result import AudioTrack
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            result = Result({"content_type": "audio/wav", "sample_rate": 44100})
+            result.add_result(
+                AudioTrack(numpy.zeros((1, 4410), dtype=numpy.float32), 24000)
+            )
+
+            result.save(temp_dir, "line")
+
+            _, sample_rate = soundfile.read(os.path.join(temp_dir, "line-0.0.wav"))
+            assert sample_rate == 44100
+
     def test_numpy_audios_output_saves_without_attribute_error(self):
         # Regression test: AudioPipelineOutput.audios is a numpy ndarray under the
         # default output_type='np', which has no .float()/.cpu() - saving used to raise
diff --git a/tests/test_speech_generation.py b/tests/test_speech_generation.py
new file mode 100644
index 00000000..6b1177bd
--- /dev/null
+++ b/tests/test_speech_generation.py
@@ -0,0 +1,132 @@
+"""Tests for the speech_generation task."""
+
+import unittest
+from unittest.mock import patch, MagicMock
+
+import numpy
+
+from dw.tasks.speech_generation import generate_speech, _DEFAULT_MODEL
+
+
+def spoken(sample_rate=24000, samples=480):
+    """What a HuggingFace text-to-audio pipeline hands back."""
+    return {
+        "audio": numpy.zeros((1, samples), dtype=numpy.float32),
+        "sampling_rate": sample_rate,
+    }
+
+
+class TestGenerateSpeech(unittest.TestCase):
+    """Tests for the generate_speech function."""
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_returns_the_waveform_channels_first(self, mock_pipeline):
+        pipe = MagicMock(return_value=spoken(samples=480))
+        mock_pipeline.return_value = pipe
+
+        track = generate_speech("hello", device="cpu")
+
+        self.assertEqual(track.audio.shape, (1, 480))
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_carries_the_rate_the_model_generated_at(self, mock_pipeline):
+        # The whole point of returning a track rather than a bare waveform: every
+        # TTS model has its own rate, and a workflow declaring the wrong one plays
+        # the speech at the wrong speed without ever failing
+        mock_pipeline.return_value = MagicMock(return_value=spoken(sample_rate=16000))
+
+        track = generate_speech("hello", device="cpu")
+
+        self.assertEqual(track.sample_rate, 16000)
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_uses_the_default_model(self, mock_pipeline):
+        mock_pipeline.return_value = MagicMock(return_value=spoken())
+
+        generate_speech("hello", device="cpu")
+
+        self.assertEqual(mock_pipeline.call_args[1]["model"], _DEFAULT_MODEL)
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_custom_model_name(self, mock_pipeline):
+        mock_pipeline.return_value = MagicMock(return_value=spoken())
+
+        generate_speech("hello", device="cpu", model_name="facebook/mms-tts-eng")
+
+        self.assertEqual(mock_pipeline.call_args[1]["model"], "facebook/mms-tts-eng")
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_the_text_to_speech_task_is_what_is_loaded(self, mock_pipeline):
+        mock_pipeline.return_value = MagicMock(return_value=spoken())
+
+        generate_speech("hello", device="cpu")
+
+        self.assertEqual(mock_pipeline.call_args[0][0], "text-to-speech")
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_voice_preset_reaches_the_processor(self, mock_pipeline):
+        # A preset is a preprocessing argument - it selects the speaker before
+        # generation rather than parameterizing it. Passed as a forward argument
+        # it would be silently dropped and every character would sound the same
+        pipe = MagicMock(return_value=spoken())
+        mock_pipeline.return_value = pipe
+
+        generate_speech("hello", device="cpu", voice_preset="v2/en_speaker_6")
+
+        self.assertEqual(
+            pipe.call_args[1]["preprocess_params"], {"voice_preset": "v2/en_speaker_6"}
+        )
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_no_preprocessing_arguments_without_a_preset(self, mock_pipeline):
+        pipe = MagicMock(return_value=spoken())
+        mock_pipeline.return_value = pipe
+
+        generate_speech("hello", device="cpu")
+
+        self.assertEqual(pipe.call_args[1]["preprocess_params"], {})
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_forward_params_are_passed_through(self, mock_pipeline):
+        pipe = MagicMock(return_value=spoken())
+        mock_pipeline.return_value = pipe
+
+        generate_speech("hello", device="cpu", forward_params={"do_sample": True})
+
+        self.assertEqual(pipe.call_args[1]["forward_params"], {"do_sample": True})
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_generate_kwargs_are_passed_through(self, mock_pipeline):
+        pipe = MagicMock(return_value=spoken())
+        mock_pipeline.return_value = pipe
+
+        generate_speech("hello", device="cpu", generate_kwargs={"temperature": 0.7})
+
+        self.assertEqual(pipe.call_args[1]["generate_kwargs"], {"temperature": 0.7})
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_a_batched_waveform_is_flattened_to_channels_and_samples(
+        self, mock_pipeline
+    ):
+        # Bark returns (1, samples); as_channels_samples is what the rest of the
+        # audio plumbing expects everything to arrive in
+        mock_pipeline.return_value = MagicMock(
+            return_value={
+                "audio": numpy.zeros((1, 1, 200), dtype=numpy.float32),
+                "sampling_rate": 24000,
+            }
+        )
+
+        track = generate_speech("hello", device="cpu")
+
+        self.assertEqual(track.audio.shape, (1, 200))
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_a_model_reporting_no_rate_is_an_error(self, mock_pipeline):
+        # Better to say so than to save at a default rate that is quietly wrong
+        mock_pipeline.return_value = MagicMock(
+            return_value={"audio": numpy.zeros((1, 200), dtype=numpy.float32)}
+        )
+
+        with self.assertRaisesRegex(ValueError, "sample rate"):
+            generate_speech("hello", device="cpu")
diff --git a/workflows/minimax/MiniMaxH3GeneratedVoice.json b/workflows/minimax/MiniMaxH3GeneratedVoice.json
new file mode 100644
index 00000000..5f0fa419
--- /dev/null
+++ b/workflows/minimax/MiniMaxH3GeneratedVoice.json
@@ -0,0 +1,165 @@
+{
+    "id": "MiniMaxH3GeneratedVoice",
+    "description": "Generates the voice it conditions on. A 'generate_speech' step speaks a throwaway line with a chosen Bark preset, and that clip goes in as H3's <Audio 1> - which references timbre, pitch and delivery only, while H3 still generates the dialogue itself and so keeps the lip sync it is good at. Repeat the same preset across every shot of a scene and a character's voice is a conditioning signal rather than a prose description hoping to land the same way twice. The reference is built with 'from_previous_result', which carries the clip's own sample rate across, and 'release_models' drops the speech model before the video model loads.",
+    "variables": {
+        "prompt": "subject_definitions:\n<Subject 1> is the astronaut in <Picture 1>, in a white hard-shell suit with a gold-mirrored visor, an orange chest harness and a soft-sided life-support pack.\n<Audio 1> is the voice timbre reference for <Subject 1> (S1): a male voice, mid-range in pitch, measured and formal in delivery.\n\nsummary:\n[reference generation + audio reference] The target video shows <Subject 1> speaking directly to camera in the setting of <Picture 1>. The lip and jaw movement is synchronised to the generated dialogue, and the voice timbre references <Audio 1>.\n\nretention_analysis:\n<Subject 1> (appears in [Shot 1]): fully_preserved - the suit, visor, harness and proportions of <Picture 1> are kept exactly, with the head and shoulders newly animated to speak.\n<Picture 1>: carries no compositional detail - no framing, no shot size, no camera position. Only the appearance of <Subject 1> is taken from it; the framing below is what governs the shot.\n<Audio 1>: reference - only the timbre, pitch and measured delivery of the voice are referenced for <Subject 1>'s speech; none of its content is reused.\n\ndetailed_description:\nThe target video is in realistic photographic style. [Shot 1] A medium close-up frames <Subject 1> from the chest up, centred and facing camera, in the setting of <Picture 1>. Warm low sunlight rakes across the left of the suit and reflects off the gold visor as a long soft highlight; the background sits well behind in shallow focus. <Subject 1> (S1) speaks in a measured, formal male voice, his jaw and lips moving in natural synchronisation behind the open visor, <d>[English] We have come a long way, and the way ahead is longer still.</d> As he delivers the line he lifts his chin slightly and turns a few degrees toward the light, one gloved hand rising into the lower frame to settle on the chest harness. Exactly as his voice stops his mouth closes and holds, and he looks past the lens toward the horizon. The camera pushes in with small amplitude at slow speed across the whole shot.\n\noverall_soundscape:\nA broad, open outdoor room tone with a steady low wind moving across the microphone. The suit fabric and harness give a dry creak as he turns and as his glove meets his chest, and a faint regulator hiss cycles quietly under the dialogue throughout.\n\nnon_diegetic_music:\nA slow, sparse orchestral bed of sustained low strings under a single held horn note, mixed well beneath the voice, swelling gently as he turns toward the light and settling back into stillness at the end of the clip.",
+        "subject": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg",
+        "voice_line": "The way ahead is longer still, and we are going anyway.",
+        "voice_preset": "v2/en_speaker_6",
+        "num_frames": 124,
+        "width": 960,
+        "height": 544,
+        "num_inference_steps": 20,
+        "weights_dtype": "{int4}"
+    },
+    "steps": [
+        {
+            "name": "voice",
+            "task": {
+                "command": "generate_speech",
+                "arguments": {
+                    "text": "variable:voice_line",
+                    "voice_preset": "variable:voice_preset"
+                }
+            },
+            "result": {
+                "content_type": "audio/wav",
+                "save": false
+            },
+            "release_models": true
+        },
+        {
+            "name": "reference_to_video_audio",
+            "pipeline": {
+                "configuration": {
+                    "component_type": "ModularPipeline",
+                    "pre_load_modules": [
+                        "sdnq"
+                    ],
+                    "cache": {
+                        "type": "first_block",
+                        "threshold": 0.1
+                    },
+                    "load_components": {
+                        "dtype": "torch.bfloat16",
+                        "quantization_config": {
+                            "transformer_ref": {
+                                "configuration": {
+                                    "config_type": "sdnq.SDNQConfig"
+                                },
+                                "arguments": {
+                                    "weights_dtype": "variable:weights_dtype",
+                                    "quantization_device": "cuda",
+                                    "return_device": "cpu",
+                                    "use_quantized_matmul": true,
+                                    "dequantize_fp32": false,
+                                    "modules_to_not_convert": [
+                                        "proj_in",
+                                        "audio_proj_in",
+                                        "context_embedder",
+                                        "time_embedder",
+                                        "time_proj",
+                                        "token_refiner",
+                                        "norm_out",
+                                        "proj_out",
+                                        "audio_proj_out"
+                                    ]
+                                }
+                            },
+                            "text_encoder": {
+                                "configuration": {
+                                    "config_type": "sdnq.SDNQConfig"
+                                },
+                                "arguments": {
+                                    "weights_dtype": "variable:weights_dtype",
+                                    "quantization_device": "cuda",
+                                    "return_device": "cpu",
+                                    "dequantize_fp32": false,
+                                    "modules_to_not_convert": [
+                                        ".model.visual",
+                                        "lm_head"
+                                    ]
+                                }
+                            },
+                            "vae": {
+                                "configuration": {
+                                    "config_type": "sdnq.SDNQConfig"
+                                },
+                                "arguments": {
+                                    "weights_dtype": "{int8}",
+                                    "quant_conv": true,
+                                    "use_quantized_matmul_conv": true,
+                                    "quantization_device": "cuda",
+                                    "return_device": "cpu",
+                                    "dequantize_fp32": false
+                                }
+                            }
+                        }
+                    },
+                    "components": {
+                        "transformer_ref": {
+                            "group_offload": {
+                                "offload_type": "block_level",
+                                "num_blocks_per_group": 1,
+                                "use_stream": true,
+                                "record_stream": true,
+                                "low_cpu_mem_usage": true
+                            }
+                        },
+                        "text_encoder": {
+                            "remove_modules": [
+                                "lm_head"
+                            ]
+                        },
+                        "text_encoder.model": {
+                            "truncate_layers": {
+                                "language_model.layers": 51
+                            },
+                            "group_offload": {
+                                "offload_type": "leaf_level"
+                            }
+                        },
+                        "vae": {
+                            "device": "cuda",
+                            "residency": "on_demand"
+                        },
+                        "audio_vae": {
+                            "device": "cuda",
+                            "residency": "on_demand"
+                        }
+                    }
+                },
+                "from_pretrained_arguments": {
+                    "model_name": "MiniMaxAI/MiniMax-H3",
+                    "workflow": "ref2va"
+                },
+                "arguments": {
+                    "prompt": "variable:prompt",
+                    "references": [
+                        {
+                            "reference_type": "diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference",
+                            "from_file": "variable:subject"
+                        },
+                        {
+                            "reference_type": "diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference",
+                            "from_previous_result": "voice"
+                        }
+                    ],
+                    "num_frames": "variable:num_frames",
+                    "width": "variable:width",
+                    "height": "variable:height",
+                    "num_inference_steps": "variable:num_inference_steps",
+                    "output": [
+                        "videos",
+                        "audio",
+                        "sampling_rate"
+                    ]
+                }
+            },
+            "result": {
+                "content_type": "video/mp4",
+                "fps": 24
+            }
+        }
+    ]
+}
diff --git a/workflows/tasks/GenerateSpeech.json b/workflows/tasks/GenerateSpeech.json
new file mode 100644
index 00000000..bf5a1c30
--- /dev/null
+++ b/workflows/tasks/GenerateSpeech.json
@@ -0,0 +1,25 @@
+{
+  "id": "GenerateSpeech",
+  "description": "Speaks a line of text with a local text-to-speech model and saves it as a wav. The result declares no 'sample_rate': a generated track carries the rate its model produced it at, so saying nothing is what saves it correctly. Bark's 'voice_preset' selects the speaker - give two characters two presets and they sound like two people.",
+  "variables": {
+    "text": "Somebody finished the pistachio and nobody is saying anything.",
+    "voice_preset": "v2/en_speaker_6",
+    "model_name": "suno/bark-small"
+  },
+  "steps": [
+    {
+      "name": "speak",
+      "task": {
+        "command": "generate_speech",
+        "arguments": {
+          "text": "variable:text",
+          "voice_preset": "variable:voice_preset",
+          "model_name": "variable:model_name"
+        }
+      },
+      "result": {
+        "content_type": "audio/wav"
+      }
+    }
+  ]
+}

From 1e8c05ecb90d98c6acead2572eedecbdf27036a4 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 14:14:05 -0500
Subject: [PATCH 03/32] Add documentation guides and update server to serve
 them

---
 .gitignore               |   3 +
 docs/MCP.md              |  12 ++-
 dw_mcp/CLAUDE.md         |   7 +-
 dw_mcp/guides.py         | 175 +++++++++++++++++++++++++++++++++++++++
 dw_mcp/server.py         |  35 ++++++++
 pyproject.toml           |   5 +-
 scripts/build_dist.sh    |  28 +++++--
 tests/test_mcp_guides.py | 108 ++++++++++++++++++++++++
 tests/test_mcp_server.py |  31 ++++++-
 9 files changed, 395 insertions(+), 9 deletions(-)
 create mode 100644 dw_mcp/guides.py
 create mode 100644 tests/test_mcp_guides.py

diff --git a/.gitignore b/.gitignore
index 47c8200f..0c9a77e2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -148,6 +148,9 @@ test_outputs/
 
 # built SPA copied into the package by scripts/build_dist.sh
 dw/server/ui/
+
+# the guides dw_mcp serves, copied into the package by the same script
+dw/docs/
 venv
 
 # generated media - regenerable, archived outside the repo
diff --git a/docs/MCP.md b/docs/MCP.md
index 6f13f935..430da1dc 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -176,7 +176,7 @@ Nothing in this sequence costs GPU time.
 
 ## Tool reference
 
-50 tools in six groups. Names and arguments below are transcribed from
+52 tools in six groups. Names and arguments below are transcribed from
 `dw_mcp/server.py` — nothing here is renamed or reshaped for the docs.
 
 ### Catalog (read-only)
@@ -188,8 +188,18 @@ pass it, without fetching every candidate's definition. Reusing a stored
 workflow is a preference, not a rule; `run_workflow` still takes an
 `inline_workflow` for a request nothing on disk covers.
 
+A request usually names a *subject* ("a lego movie trailer set in the marvel
+universe") while the catalog is written in *shapes* - a single image, an image
+set, one shot, a multi-shot cut sequence, video with speech. Nothing in a
+catalog entry will match the subject, so the shape is what has to be decided
+first and matched against. `list_guides` indexes the shipped documentation by
+section for exactly that, and `list_tasks` is what a shape gets composed from
+when no single workflow covers it.
+
 | Tool | Arguments | Purpose |
 | --- | --- | --- |
+| `list_guides()` | — | List the documentation shipped with the engine: each guide's name, what it covers, and its section headings. The index is the routing table - match a request's shape against a heading rather than guessing |
+| `get_guide(name, section=None)` | `name`, `section` | Get one guide whole, or one section of it. Prefer a section: a guide runs to thousands of lines. Section names match loosely, so a heading copied approximately still resolves |
 | `list_workflows()` | — | List stored workflows, each with its description, output kinds, step count, variable names, the stored prompts it references, and its `origin`/`writable` - a workflow from a read-only examples directory can be read and run but not saved over or deleted. The first call to make for a request an existing workflow might cover |
 | `get_workflow(name)` | `name` | Get one stored workflow's full JSON definition |
 | `get_schema()` | — | Get the JSON schema every workflow definition must satisfy |
diff --git a/dw_mcp/CLAUDE.md b/dw_mcp/CLAUDE.md
index d4ca0c0f..a3d7b430 100644
--- a/dw_mcp/CLAUDE.md
+++ b/dw_mcp/CLAUDE.md
@@ -21,7 +21,12 @@ session that never chooses looks exactly like one from before workspaces.
 (`/api/server`) is the capability call: the device a run will use, the dw
 version, the workspace and the workflow/output/prompt/asset directories, which is what tells an
 agent authoring remotely whether a CUDA-only choice is even available. It is an HTTP client of a *running* `dw.serve` — it owns no
-job state and no GPU worker. Only `dw_mcp/server.py` imports the MCP SDK; the
+job state and no GPU worker. `guides.py` is the one handler that talks to no
+server at all: `list_guides`/`get_guide` read the markdown in `docs/` (copied
+into `dw/docs/` at build time, so an install carries it) by path rather than by
+import, which keeps the no-`dw.*`-import boundary intact. They exist because a
+request names a subject and the catalog is written in shapes, and an agent with
+nowhere to look up the shape authors a fresh workflow instead of composing one. Only `dw_mcp/server.py` imports the MCP SDK; the
 handlers in `catalog.py`, `authoring.py`, `prompts.py`, `diagnose.py`,
 `media.py`, `assets.py`, `models.py` and `workspaces.py` are plain `(client, **kwargs)` functions, which is what makes
 them testable without an MCP session. It is a top-level package rather than
diff --git a/dw_mcp/guides.py b/dw_mcp/guides.py
new file mode 100644
index 00000000..17485b29
--- /dev/null
+++ b/dw_mcp/guides.py
@@ -0,0 +1,175 @@
+"""The prose guides, served to an agent that has to pick a capability.
+
+Everything else in this package proxies the server. These do not: they are
+documentation shipped with the package, so they are read locally and work the
+same against a remote engine as a local one.
+
+The gap they close is that a catalog entry describes what a workflow *is*, and
+an open-ended request ("a lego movie trailer set in the marvel universe")
+names nothing that appears in any of them. What has to be matched is shape -
+multi-shot video, cuts, a consistent cast, narration - and that is what the
+guides are written in. An agent that reads one before choosing composes from
+what exists instead of authoring a fresh workflow badly.
+
+Two things keep this cheap. The listing carries each guide's section headings,
+so the index is itself the routing table and is small enough to read every
+time. And a guide can be fetched one section at a time, because handing over
+three thousand lines of TASKS.md is how an agent ends up reading none of it
+carefully.
+"""
+
+import re
+from pathlib import Path
+
+from dw_mcp.client import DwApiError
+
+# The docs that bear on choosing a capability. Deliberately not all of them -
+# testing, releasing, security and dependency notes are for people working on
+# dw, and listing them would dilute an index whose whole value is that it is
+# short enough to read in full.
+GUIDES = {
+    "workflows": (
+        "WORKFLOW_GUIDE.md",
+        "How a workflow is put together: steps, variables, the reference "
+        "conventions that carry data between steps, sub-workflows, and "
+        "releasing models mid-run. Read before authoring one.",
+    ),
+    "tasks": (
+        "TASKS.md",
+        "The utility task commands - image and video processing, audio, "
+        "captioning, text and speech generation, gathering. Compose these "
+        "before writing anything new.",
+    ),
+    "recipes": (
+        "RECIPES_24GB.md",
+        "What actually fits and runs on a 24 GB accelerator, model by model. "
+        "Read before proposing something large.",
+    ),
+    "acceleration": (
+        "ACCELERATION.md",
+        "Offloading, attention slicing, caching and compilation - how to make "
+        "a pipeline fit or run faster, and what each costs.",
+    ),
+    "quantization": (
+        "QUANTIZATION.md",
+        "Running a model in fewer bits: the supported frameworks and how a "
+        "quantization config is written per component.",
+    ),
+    "loras": (
+        "LORAS.md",
+        "Loading, weighting and combining LoRA adapters.",
+    ),
+    "prompt-weighting": (
+        "PROMPT_WEIGHTING.md",
+        "Emphasis and de-emphasis syntax in prompts, and which pipelines "
+        "honour it.",
+    ),
+    "ip-adapter": (
+        "IP_ADAPTER.md",
+        "Conditioning generation on a reference image with IP-Adapter.",
+    ),
+    "workspaces": (
+        "WORKSPACES.md",
+        "How a run's workflows, prompts, assets and outputs are rooted, and "
+        "what changes when a workspace is named.",
+    ),
+}
+
+# Only the top level. Sub-headings would triple the index for detail that is
+# better reached by reading the section they sit in
+SECTION_PATTERN = re.compile(r"^## (.+)$", re.M)
+
+
+def _guide_file(file_name):
+    """Where a guide's markdown actually is.
+
+    Packaged into dw/docs/ at build time, the way the SPA is copied into
+    dw/server/ui - so an install carries them. A checkout has no such copy
+    until something builds one, and reads the repo's own docs/ instead.
+    """
+    packaged = Path(__file__).resolve().parent.parent / "dw" / "docs" / file_name
+    if packaged.is_file():
+        return packaged
+    return Path(__file__).resolve().parent.parent / "docs" / file_name
+
+
+def read_guide(name):
+    """One guide's full markdown text.
+
+    Raises:
+        DwApiError: If the name is not a guide, or its file is missing - as a
+            DwApiError rather than anything else so the message reaches the
+            model instead of being replaced by a traceback.
+    """
+    if name not in GUIDES:
+        raise DwApiError(
+            f"No guide named '{name}'. The guides are: "
+            f"{', '.join(sorted(GUIDES))}."
+        )
+
+    path = _guide_file(GUIDES[name][0])
+    if not path.is_file():
+        raise DwApiError(
+            f"The '{name}' guide is missing from this install "
+            f"({GUIDES[name][0]} was not found)."
+        )
+    return path.read_text(encoding="utf-8")
+
+
+def _sections(text):
+    """The top-level section headings of a guide, in the order they appear."""
+    return SECTION_PATTERN.findall(text)
+
+
+def _normalized(heading):
+    """A heading reduced to what a loose match compares.
+
+    An agent reproduces a heading from the listing approximately -
+    "speech-generation" for "Speech Generation" - and refusing that costs a
+    round trip to say something it already knew.
+    """
+    return re.sub(r"[^a-z0-9]+", "", heading.lower())
+
+
+def _extract_section(text, section):
+    """One section's text, heading included, or None if there is no such one."""
+    wanted = _normalized(section)
+    matches = list(SECTION_PATTERN.finditer(text))
+    for index, match in enumerate(matches):
+        if _normalized(match.group(1)) != wanted:
+            continue
+        end = matches[index + 1].start() if index + 1 < len(matches) else len(text)
+        return match.group(1), text[match.start() : end].rstrip() + "\n"
+    return None
+
+
+def list_guides():
+    """Every guide, with what it covers and the sections it holds."""
+    listed = []
+    for name, (file_name, summary) in GUIDES.items():
+        text = read_guide(name)
+        listed.append(
+            {
+                "name": name,
+                "file": file_name,
+                "summary": summary,
+                "sections": _sections(text),
+            }
+        )
+    return {"guides": listed}
+
+
+def get_guide(name, section=None):
+    """One guide, whole or one section of it."""
+    text = read_guide(name)
+    if section is None:
+        return {"name": name, "section": None, "content": text}
+
+    found = _extract_section(text, section)
+    if found is None:
+        raise DwApiError(
+            f"The '{name}' guide has no section '{section}'. Its sections are: "
+            f"{', '.join(_sections(text))}."
+        )
+    heading, content = found
+    return {"name": name, "section": heading, "content": content}
diff --git a/dw_mcp/server.py b/dw_mcp/server.py
index f5317640..83e2e124 100644
--- a/dw_mcp/server.py
+++ b/dw_mcp/server.py
@@ -17,6 +17,7 @@
     authoring,
     catalog,
     diagnose,
+    guides,
     media,
     models,
     prompts,
@@ -77,6 +78,18 @@ def build_server(client):
             "authoring a new workflow for a request an existing one "
             "covers.\n"
             "\n"
+            "When a request is open-ended - a subject rather than a shape "
+            '("a lego movie trailer set in the marvel universe") - no '
+            "catalog entry will name it, because entries are written in "
+            "shapes: a single image, an image set, one shot, a multi-shot "
+            "cut sequence, video with speech. Decide which shape the "
+            "deliverable is first, then match the catalog against that; "
+            "`list_guides` indexes the documentation by section so a shape "
+            "can be looked up rather than guessed at, and `list_tasks` is "
+            "what a shape is composed from when no single workflow covers "
+            "it. Author new JSON only once neither does, and say what it "
+            "will cost before spending it.\n"
+            "\n"
             "The engine that answers is one machine: `get_server_info` "
             "reports its accelerator, its directories and which workspace "
             "this session works in, and what a workflow can ask for "
@@ -252,7 +265,29 @@ def get_gallery_metadata(name: str) -> dict:
         re-run."""
         return catalog.get_gallery_metadata(client, name)
 
+    def list_guides() -> dict:
+        """List the documentation shipped with this engine: each guide's
+        name, what it covers, and its section headings. Read this when a
+        request is open-ended enough that no catalog entry obviously
+        answers it - a request names a subject ("a lego movie trailer"),
+        while the catalog and these guides are written in shapes
+        (multi-shot video, cuts, a consistent cast, narration over
+        B-roll), and the section headings are where the two get matched
+        up. Cheaper than guessing: reading a section costs a fraction of
+        one wrong run."""
+        return guides.list_guides()
+
+    def get_guide(name: str, section: str | None = None) -> dict:
+        """Get one guide from `list_guides`, whole or one section of it.
+        Prefer a section - a guide runs to thousands of lines, and the
+        headings in the listing are there so the right part can be asked
+        for by name. A section name is matched loosely, so a heading
+        copied approximately still resolves."""
+        return guides.get_guide(name, section=section)
+
     for fn in (
+        list_guides,
+        get_guide,
         list_workflows,
         get_workflow,
         get_schema,
diff --git a/pyproject.toml b/pyproject.toml
index fd1b85d1..1c9b86ec 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -121,6 +121,9 @@ include = ["dw*"]
 namespaces = true
 
 [tool.setuptools.package-data]
-dw = ["*.json", "workflows/*.json", "community_pipelines/*.py"]
+dw = ["*.json", "workflows/*.json", "community_pipelines/*.py", "docs/*.md"]
+# docs/ is copied in by scripts/build_dist.sh, the way the SPA is - it is what
+# dw_mcp's list_guides/get_guide serve. A checkout has no copy and reads the
+# repo's own docs/ instead
 # The built SPA, copied in by scripts/build_dist.sh before packaging
 "dw.server" = ["ui/**"]
diff --git a/scripts/build_dist.sh b/scripts/build_dist.sh
index 9d33c102..cebe5e7a 100755
--- a/scripts/build_dist.sh
+++ b/scripts/build_dist.sh
@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
-# Build a distributable wheel: the SPA is built with npm, copied into the
-# dw.server package (where default_ui_dir finds it in an install), and the
-# wheel is assembled around it.
+# Build a distributable wheel: the SPA is built with npm and copied into the
+# dw.server package (where default_ui_dir finds it in an install), the guides
+# dw_mcp serves are copied into dw/docs/, and the wheel is assembled around
+# them.
 set -euo pipefail
 cd "$(dirname "$0")/.."
 
@@ -10,9 +11,26 @@ cd "$(dirname "$0")/.."
 rm -rf dw/server/ui
 cp -r ui/dist dw/server/ui
 
+# The guides dw_mcp serves. A checkout reads the repo's docs/ directly, so this
+# copy only matters to an install - but without it an installed dw-mcp has no
+# guides at all
+rm -rf dw/docs
+mkdir -p dw/docs
+python - <<'GUIDES'
+import shutil
+from pathlib import Path
+
+from dw_mcp.guides import GUIDES
+
+for file_name in sorted({f for f, _ in GUIDES.values()}):
+    shutil.copy(Path("docs") / file_name, Path("dw/docs") / file_name)
+    print(f"docs/{file_name} -> dw/docs/{file_name}")
+GUIDES
+
 python -m pip show build >/dev/null 2>&1 || python -m pip install build
 python -m build
 
 echo ""
-echo "Artifacts in dist/. dw/server/ui/ is a build product (gitignored);"
-echo "remove it or rebuild it - a checkout serves ui/dist first regardless."
+echo "Artifacts in dist/. dw/server/ui/ and dw/docs/ are build products"
+echo "(gitignored); remove or rebuild them - a checkout serves ui/dist and"
+echo "the repo's own docs/ regardless."
diff --git a/tests/test_mcp_guides.py b/tests/test_mcp_guides.py
new file mode 100644
index 00000000..26fdb880
--- /dev/null
+++ b/tests/test_mcp_guides.py
@@ -0,0 +1,108 @@
+"""The guides an agent reads before choosing a capability.
+
+These are packaged documentation rather than server state, so unlike the rest
+of the MCP surface they are read locally and there is no route to pin. What
+matters instead: the index is complete enough to route a request by, a guide
+can be fetched a section at a time rather than whole, and a wrong name says
+what the right ones are.
+"""
+
+import pytest
+
+from dw_mcp import guides
+from dw_mcp.client import DwApiError
+
+
+class TestListing:
+    def test_every_curated_guide_is_listed(self):
+        listed = {guide["name"] for guide in guides.list_guides()["guides"]}
+
+        assert listed == set(guides.GUIDES)
+
+    def test_each_guide_carries_a_summary(self):
+        # The summary is what an agent matches a request against before
+        # spending context on the guide itself
+        for guide in guides.list_guides()["guides"]:
+            assert guide["summary"].strip()
+
+    def test_each_guide_lists_its_sections(self):
+        # The index doubles as a routing table: section headings are what a
+        # request shape is matched to, so they have to be in the listing
+        listed = guides.list_guides()["guides"]
+        tasks = next(g for g in listed if g["name"] == "tasks")
+
+        assert "Speech Generation" in tasks["sections"]
+
+    def test_every_curated_guide_file_exists(self):
+        # Guards the set against a doc being renamed or moved out from under it
+        for name in guides.GUIDES:
+            assert guides.read_guide(name).strip()
+
+
+class TestWhereTheyComeFrom:
+    def test_the_packaged_copy_is_preferred_over_the_repo(self, tmp_path, monkeypatch):
+        """An install has no docs/ beside the package - only the dw/docs/ copy
+        the build makes. A checkout has no copy and reads docs/ directly, so the
+        preference is what makes the same code work in both."""
+        root = tmp_path / "site-packages"
+        (root / "dw" / "docs").mkdir(parents=True)
+        (root / "docs").mkdir()
+        (root / "dw" / "docs" / "TASKS.md").write_text("## Packaged\n")
+        (root / "docs" / "TASKS.md").write_text("## Checkout\n")
+        monkeypatch.setattr(guides, "__file__", str(root / "dw_mcp" / "guides.py"))
+
+        assert guides.read_guide("tasks") == "## Packaged\n"
+
+    def test_a_checkout_falls_back_to_the_repo_docs(self, tmp_path, monkeypatch):
+        root = tmp_path / "repo"
+        (root / "docs").mkdir(parents=True)
+        (root / "docs" / "TASKS.md").write_text("## Checkout\n")
+        monkeypatch.setattr(guides, "__file__", str(root / "dw_mcp" / "guides.py"))
+
+        assert guides.read_guide("tasks") == "## Checkout\n"
+
+    def test_a_guide_missing_from_the_install_says_so(self, tmp_path, monkeypatch):
+        monkeypatch.setattr(guides, "__file__", str(tmp_path / "dw_mcp" / "guides.py"))
+
+        with pytest.raises(DwApiError, match="missing from this install"):
+            guides.read_guide("tasks")
+
+
+class TestFetching:
+    def test_a_guide_comes_back_whole_by_default(self):
+        guide = guides.get_guide("tasks")
+
+        assert guide["name"] == "tasks"
+        assert guide["section"] is None
+        assert "## Speech Generation" in guide["content"]
+
+    def test_one_section_comes_back_alone(self):
+        # A whole guide is thousands of lines; handing all of it over is how an
+        # agent ends up reading none of it carefully
+        guide = guides.get_guide("tasks", section="Speech Generation")
+
+        assert guide["section"] == "Speech Generation"
+        assert "generate_speech" in guide["content"]
+        assert "## Frame Interpolation" not in guide["content"]
+
+    def test_a_section_keeps_its_own_heading(self):
+        guide = guides.get_guide("tasks", section="Speech Generation")
+
+        assert guide["content"].lstrip().startswith("## Speech Generation")
+
+    def test_a_section_name_need_not_match_case_or_spacing(self):
+        # An agent reproduces a heading from the listing loosely - "speech-generation"
+        # for "Speech Generation" - and being strict about it just costs a round trip
+        guide = guides.get_guide("tasks", section="speech-generation")
+
+        assert guide["section"] == "Speech Generation"
+
+
+class TestErrors:
+    def test_an_unknown_guide_names_the_ones_that_exist(self):
+        with pytest.raises(DwApiError, match="tasks"):
+            guides.get_guide("nonexistent")
+
+    def test_an_unknown_section_names_the_sections_that_exist(self):
+        with pytest.raises(DwApiError, match="Speech Generation"):
+            guides.get_guide("tasks", section="nonexistent")
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index 257fd000..73265f15 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -15,6 +15,8 @@
 from dw_mcp.server import build_server  # noqa: E402
 
 EXPECTED_TOOLS = {
+    "list_guides",
+    "get_guide",
     "list_workflows",
     "get_workflow",
     "get_schema",
@@ -433,8 +435,35 @@ def _a_file_to_upload():
 ]
 
 
+# The guides are documentation packaged with dw rather than server state, so
+# these two answer without a request. Everything else is a proxy and belongs in
+# the wiring table above; the test below holds them to making no request at all,
+# so this stays a statement about them rather than a hole in the coverage.
+LOCAL_TOOLS = {"list_guides", "get_guide"}
+
+
 def test_the_wiring_table_covers_every_registered_tool():
-    assert {name for name, _, _, _ in TOOL_WIRING} == EXPECTED_TOOLS
+    assert {name for name, _, _, _ in TOOL_WIRING} == EXPECTED_TOOLS - LOCAL_TOOLS
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "name,arguments",
+    [("list_guides", {}), ("get_guide", {"name": "tasks", "section": "Speech Generation"})],
+)
+async def test_the_guide_tools_reach_no_server(name, arguments):
+    """They have to work against an engine that is not answering - and against a
+    remote one, whose disk is not where the packaged guides are."""
+    seen = []
+
+    def handler(request):
+        seen.append(request.url.path)
+        return httpx.Response(500, json={"detail": "the engine is down"})
+
+    result = await server_over(handler).call_tool(name, arguments)
+
+    assert seen == []
+    assert result.content
 
 
 @pytest.mark.asyncio

From c27be7a226c6b59085382bfabcb91ed7d1c5a49e Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 14:20:00 -0500
Subject: [PATCH 04/32] Add workflow catalog restructure design

Separates the catalog into templates (teach a pattern) and model configs
(record a hardware fact), which have been sharing one flat list of 121
entries. Measured: 54 of 84 non-archive workflows share a feature
signature with another, and the clusters are checkpoint iterations rather
than feature variations.

Records the compatibility constraints a move runs into - the step cache
survives on id, run-directory identity does not survive a path change -
and defers the derived shape index until after the restructure.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 ...-06-workflow-catalog-restructure-design.md | 183 ++++++++++++++++++
 1 file changed, 183 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md

diff --git a/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md b/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md
new file mode 100644
index 00000000..ce51feff
--- /dev/null
+++ b/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md
@@ -0,0 +1,183 @@
+# Workflow catalog restructure: design
+
+Date: 2026-09-06. Status: approved for planning. Grew out of the MCP capability
+discovery discussion that followed
+[docs/proposals/scripted-dialogue-and-tts.md](../../proposals/scripted-dialogue-and-tts.md),
+whose `generate_speech` half is already implemented.
+
+## Goal
+
+Make the workflow catalog answerable to an open-ended request. An agent handed
+"a lego movie trailer set in the marvel universe" has to decide the *shape* of
+the deliverable - a multi-shot cut sequence - and find the workflows that make
+that shape. Today it faces 121 undifferentiated entries in which the 8 that
+matter are indistinguishable from 100 iterations on a checkpoint.
+
+The fix is not to prune. It is to separate two artifacts that have been sharing
+one flat list, and to let the catalog say which is which.
+
+## Decisions
+
+| Question | Decision |
+| --- | --- |
+| Structure | Separate trees: `workflows/templates/` and `workflows/models/`. |
+| Pruned workflows | Deleted. Git history is the archive; `archive/` stops being a graveyard. |
+| Collapsing model variation | Into variables where the pipeline class matches; stop where component configs genuinely differ. |
+| `archive/` | Pruned to the generalizable few, which graduate into `templates/`. The rest is deleted. |
+| Workflow `id` | Stays stable across a move, so the step cache survives. |
+| Run-directory identity | Allowed to change with the path. A one-time break, documented. |
+| Sequencing | The keep/collapse/delete inventory is agreed with the user *before* anything is deleted. |
+| Out of scope | The derived shape index and measured runtimes (a separate piece, built on top of this - see "What this unblocks"). |
+
+## What is wrong today
+
+Measured across the 84 non-archive workflows on 2026-09-06:
+
+1. **54 of 84 share a feature signature with at least one other file** - there
+   are 43 distinct signatures. The redundancy is not incidental; it is most of
+   the catalog.
+2. The clusters are checkpoint iterations, not feature variations: 5 MiniMax H3
+   `ref2va` files differing only in chaining and output kind, 4 LTX-2 files
+   differing only in conditioning, 5 one-step text-to-image files differing only
+   in the checkpoint (`FluxDev`, `Krea2`, `ZImage`, `ZImageSDNQ`,
+   `FluxSchnellWeighted`), and `FluxGGUF`/`FluxTorchAO` differing only in
+   quantization backend.
+3. `archive/` (37 files) is almost purely a model gallery - 4 CogVideoX
+   variants, 6 Wan variants, 3 Kandinsky - and still costs listing space.
+4. Nothing in a catalog entry distinguishes "this teaches a pattern" from "this
+   records a hardware fact", so an agent cannot weight them differently and a
+   person browsing the repo cannot either.
+
+A caveat on point 1, recorded so nobody over-trusts it: the signature used to
+measure it was crude, and missed ControlNet - it put `FluxCanny` and `Segment`
+in one bucket when they demonstrate different features. The clusters are
+indicative. The inventory (below) is the authority, and it is done by reading.
+
+## The distinction the structure encodes
+
+**A template teaches a pattern.** Its value is in being read and copied, so it
+wants to be general, commented, and *few* - one per capability.
+
+**A model config records a fact.** The quantization, `group_offload` and
+`residency: on_demand` block that makes MiniMax H3 fit in 24 GB is not
+derivable, not generalizable, and worth keeping runnable. But nobody learns
+anything from the fifth one.
+
+Pruning alone would fix the noise and throw away the facts. Separating keeps
+both and makes each findable as what it is.
+
+## Structure
+
+```
+workflows/
+  templates/   one file per capability; model as a variable where the
+               pipeline class allows; commented
+  models/      tuned per-checkpoint configurations; reference data, each
+               naming the template it configures
+```
+
+`archive/` is emptied. Its generalizable few - `txt2img2vid` (two-stage chain),
+`sdxl_refiner` (the refiner pattern), `ip-adapter`, `qr_code` (still linked from
+TASKS.md) - graduate into `templates/`. Everything else is deleted.
+
+### What earns a slot
+
+A **template** demonstrates a feature nothing else demonstrates:
+
+- a shape - multi-shot cut sequence, chained conditioning, image-to-video
+- a mechanism - shared components, sub-workflows, `pipeline_reference`,
+  `references`, `release_pipeline`/`release_models`
+- a reference convention - `prompt:`, `asset:`, `output:`, `previous_result:`
+
+A **model config** carries settings that make a specific checkpoint fit real
+hardware: quantization, offload, component placement, truncation, cache.
+
+Anything that is a third checkpoint through an existing pattern is deleted.
+
+### Collapsing
+
+Where the pipeline class matches, one template takes the model as a variable
+plus one argument set per checkpoint, written into the template's own
+`description` so it travels with the file and reaches `list_workflows` - not
+into a doc that drifts from it. `FluxDev`, `FluxSchnell` and `Krea2` become one
+text-to-image template.
+
+It stops where component configs genuinely differ. The MiniMax H3 files share a
+pipeline class but not their quantization blocks, so they keep separate model
+configs under one template. Collapsing those would produce a file that is
+harder to read than the ones it replaced, which is the opposite of the point.
+
+## Compatibility
+
+Moving a file has two consequences, and they are not equal.
+
+**The step cache survives.** It is keyed on the workflow's `id`
+(`dw/step_cache.py`), not its path, so every surviving workflow keeps the `id`
+it has even where its filename changes. This is a constraint on the
+restructure, not an observation: renaming ids would silently invalidate the
+cache for every workflow at once.
+
+**Run-directory identity does not survive.** `workflow_identity`
+(`dw/runs.py:246`) derives identity from the file's path under a `workflows/`
+tree, so `flux/FluxDev.json` is `flux/FluxDev`. Moving it changes where its runs
+land. Consequences, all accepted as a one-time cost:
+
+- existing outputs for a moved workflow are orphaned from it - the gallery
+  groups them under the old identity
+- any `output:flux/FluxDev/latest/file.png` reference stops resolving
+- the old→new mapping is documented so a stale reference can be repaired by
+  hand
+
+Not mitigated in code. An identity-alias mechanism would be a permanent feature
+carried for a one-time move.
+
+**Links.** 66 distinct paths under `workflows/` are linked from `docs/`,
+`README.md` and `ui/`. All are updated; `tests/test_docs_links.py` enforces that
+they resolve.
+
+**Relative paths inside workflows.** Six workflows name another workflow by
+path, and a `path` resolves against the referencing file's own directory. Moves
+have to be applied to both files together or the reference silently breaks -
+schema validation does not follow it, and nothing else does until the workflow
+runs.
+
+## Verification
+
+- every surviving file validates - `tests/test_examples.py` already walks the
+  tree and loads each one
+- every doc link resolves - `tests/test_docs_links.py`
+- a new test for the invariant this exists to create: every template carries a
+  description, and every model config names the template it configures
+
+The listing needs no change to distinguish the two: a catalog name already
+carries its path, so `templates/...` and `models/...` are self-describing.
+Anything beyond that - grouping, filtering, ranking templates first - belongs to
+the follow-on piece.
+
+## Sequence
+
+1. **Inventory.** Read all 121 workflows and classify each: template, model
+   config, collapse-into, or delete. Produce the list.
+2. **Agree the list with the user.** Nothing is deleted before this. The
+   inventory is a judgement call across 121 files and is the step most likely to
+   throw away something worth keeping.
+3. **Move and collapse.** Apply the agreed list, keeping `id`s stable and moving
+   path-referencing pairs together.
+4. **Fix links and docs.** All 66, plus any prose describing the old layout.
+5. **Record the mapping.** Old identity → new identity, for repairing stale
+   `output:` references.
+
+## What this unblocks
+
+The derived shape index and measured runtimes - the follow-on piece - should be
+built *after* this, not before. Two reasons: classifying a catalog about to be
+halved is wasted work, and the derivation gets materially more accurate once
+"template or model config" is a distinction it can read rather than infer.
+
+That piece, as agreed but not specified here: shape derived from the definition
+in `workflow_details` (`dw/server/app.py:154`, which already parses and caches
+per file) with an optional declared override where the derivation is wrong; and
+median observed runtime per workflow from the `jobs` table, which carries
+`workflow`, `status`, `started_at` and `finished_at`. One wrinkle to resolve
+then: that column stores the loaded workflow name, which may not match the
+catalog name the listing keys on.

From 912c4efbe53fee81b52f7f7a58024a73792275cf Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 14:27:27 -0500
Subject: [PATCH 05/32] Trade backward compatibility for a consistency
 guarantee

Backward compatibility is not maintained: existing outputs may be
orphaned and references into them may break, and no alias or migration
shim is carried for a one-time move.

What replaces it is stricter - when this lands, every reference in the
repo resolves. Enumerates the reference classes with counts and what
enforces each, which surfaced one gap: 18 distinct prompt: references
across 20 workflows that nothing checks, and that collapsing will rewrite.
Closing that gap is now part of the work.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 ...-06-workflow-catalog-restructure-design.md | 76 ++++++++++++-------
 1 file changed, 47 insertions(+), 29 deletions(-)

diff --git a/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md b/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md
index ce51feff..f1b38677 100644
--- a/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md
+++ b/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md
@@ -25,7 +25,8 @@ one flat list, and to let the catalog say which is which.
 | Collapsing model variation | Into variables where the pipeline class matches; stop where component configs genuinely differ. |
 | `archive/` | Pruned to the generalizable few, which graduate into `templates/`. The rest is deleted. |
 | Workflow `id` | Stays stable across a move, so the step cache survives. |
-| Run-directory identity | Allowed to change with the path. A one-time break, documented. |
+| Backward compatibility | Not maintained. Existing outputs and any reference into them may break. |
+| Acceptance criterion | The post-state is internally consistent: every reference in the repo resolves. |
 | Sequencing | The keep/collapse/delete inventory is agreed with the user *before* anything is deleted. |
 | Out of scope | The derived shape index and measured runtimes (a separate piece, built on top of this - see "What this unblocks"). |
 
@@ -107,39 +108,53 @@ pipeline class but not their quantization blocks, so they keep separate model
 configs under one template. Collapsing those would produce a file that is
 harder to read than the ones it replaced, which is the opposite of the point.
 
-## Compatibility
+## Compatibility, and what replaces it
 
-Moving a file has two consequences, and they are not equal.
+Backward compatibility is explicitly not a goal (user's decision, 2026-09-06).
+Existing outputs may be orphaned and references into them may break. No alias
+mechanism, no migration shim, no old->new mapping document - each would be a
+permanent feature carried for a one-time move.
 
-**The step cache survives.** It is keyed on the workflow's `id`
-(`dw/step_cache.py`), not its path, so every surviving workflow keeps the `id`
-it has even where its filename changes. This is a constraint on the
-restructure, not an observation: renaming ids would silently invalidate the
-cache for every workflow at once.
+What replaces it is a stricter obligation on the *end* state: **when this lands,
+every reference in the repo resolves.** Not "mostly", and not "the ones a test
+happens to cover" - the point of the restructure is a catalog that can be
+trusted, and a catalog with a dangling reference in it cannot be.
 
-**Run-directory identity does not survive.** `workflow_identity`
-(`dw/runs.py:246`) derives identity from the file's path under a `workflows/`
-tree, so `flux/FluxDev.json` is `flux/FluxDev`. Moving it changes where its runs
-land. Consequences, all accepted as a one-time cost:
+### The reference classes, and what enforces each
 
-- existing outputs for a moved workflow are orphaned from it - the gallery
-  groups them under the old identity
-- any `output:flux/FluxDev/latest/file.png` reference stops resolving
-- the old→new mapping is documented so a stale reference can be repaired by
-  hand
+Counted on 2026-09-06:
 
-Not mitigated in code. An identity-alias mechanism would be a permanent feature
-carried for a one-time move.
+| Class | Count | Enforced by |
+| --- | --- | --- |
+| Markdown links into `workflows/` (docs/ + README) | 66 distinct paths | `tests/test_docs_links.py`, which walks every `.md` in the repo |
+| Workflow naming another workflow by `path` | 6 files | `tests/test_examples.py::test_example_workflow_references_resolve` |
+| `prompt:` references into the prompt library | 18 distinct names across 20 files | **nothing - a gap this work closes** |
+| `asset:` and `output:` references | none in `workflows/` | moot |
+| UI source referencing a workflow path | none | moot |
 
-**Links.** 66 distinct paths under `workflows/` are linked from `docs/`,
-`README.md` and `ui/`. All are updated; `tests/test_docs_links.py` enforces that
-they resolve.
+The `prompt:` gap matters here specifically because collapsing rewrites and
+merges the files that carry those references, and a `prompt:` naming something
+that no longer exists fails only when the workflow is actually run. A test
+asserting every `prompt:` reference in the tree resolves against `prompts/` is
+part of this work, and is worth having independently of the restructure.
 
-**Relative paths inside workflows.** Six workflows name another workflow by
-path, and a `path` resolves against the referencing file's own directory. Moves
-have to be applied to both files together or the reference silently breaks -
-schema validation does not follow it, and nothing else does until the workflow
-runs.
+### The one thing that must not change
+
+The workflow `id`. The step cache is keyed on it (`dw/step_cache.py`), not on
+the path, so every surviving workflow keeps the `id` it has even where its
+filename changes. This is a constraint on the restructure, not an observation:
+renaming ids would silently invalidate the cache for every workflow at once.
+
+Run-directory identity, by contrast, is derived from the file's path under a
+`workflows/` tree (`workflow_identity`, `dw/runs.py:246`) and therefore does
+change. That is the accepted break.
+
+### Relative paths inside workflows
+
+A `path` resolves against the referencing file's own directory, so a move has to
+be applied to both files together. Schema validation does not follow those
+references and nothing else does until the workflow runs - which is why the test
+above is the thing standing between a move and a silent break.
 
 ## Verification
 
@@ -148,6 +163,8 @@ runs.
 - every doc link resolves - `tests/test_docs_links.py`
 - a new test for the invariant this exists to create: every template carries a
   description, and every model config names the template it configures
+- a new test that every `prompt:` reference in `workflows/` resolves against
+  `prompts/` - the one reference class nothing currently checks
 
 The listing needs no change to distinguish the two: a catalog name already
 carries its path, so `templates/...` and `models/...` are self-describing.
@@ -164,8 +181,9 @@ the follow-on piece.
 3. **Move and collapse.** Apply the agreed list, keeping `id`s stable and moving
    path-referencing pairs together.
 4. **Fix links and docs.** All 66, plus any prose describing the old layout.
-5. **Record the mapping.** Old identity → new identity, for repairing stale
-   `output:` references.
+5. **Prove consistency.** Every reference class in the table above resolves,
+   including the `prompt:` one under its new test. This is the acceptance
+   criterion, and the point at which the work is done.
 
 ## What this unblocks
 

From 3035ba00dc34c9216549cfcfa70fd54a5bfb5839 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 14:31:24 -0500
Subject: [PATCH 06/32] Add workflow catalog restructure implementation plan

Seven tasks: close the prompt: reference gap first as a safety net,
inventory all 121 workflows and stop for approval, then build
templates/ and models/, prune, repoint the docs, and prove every
reference class resolves.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 ...2026-09-06-workflow-catalog-restructure.md | 625 ++++++++++++++++++
 1 file changed, 625 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-09-06-workflow-catalog-restructure.md

diff --git a/docs/superpowers/plans/2026-09-06-workflow-catalog-restructure.md b/docs/superpowers/plans/2026-09-06-workflow-catalog-restructure.md
new file mode 100644
index 00000000..8d811246
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-06-workflow-catalog-restructure.md
@@ -0,0 +1,625 @@
+# Workflow Catalog Restructure 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:** Split the 121-workflow catalog into `workflows/templates/` (one file per capability) and `workflows/models/` (tuned per-checkpoint configs), deleting checkpoint iterations that teach nothing, and land with every reference in the repo resolving.
+
+**Architecture:** A catalog entry today cannot say whether it teaches a pattern or records a hardware fact, so an agent handed an open-ended request cannot weight them. Two trees encode that distinction in the path itself. The work is: build the missing safety net first, agree an inventory before deleting anything, then move/collapse/prune, then prove consistency.
+
+**Tech Stack:** Python 3.14, pytest, jsonschema. No new dependencies.
+
+**Spec:** [docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md](../specs/2026-09-06-workflow-catalog-restructure-design.md)
+
+## Global Constraints
+
+- **A surviving workflow keeps its `id` verbatim.** The step cache is keyed on `id` (`dw/step_cache.py`), not path. Renaming ids silently invalidates the cache for every workflow at once. Moving and renaming *files* is fine; changing the `id` field inside them is not.
+- **Backward compatibility is not maintained.** Existing outputs may be orphaned and `output:` references into them may break. Do not add an alias mechanism, migration shim, or old→new mapping document.
+- **The acceptance criterion is internal consistency:** when this lands, every reference in the repo resolves.
+- **Nothing is deleted before the inventory is approved** (Task 2 gate).
+- **Reference classes and their enforcement** (counted 2026-09-06): 66 distinct markdown links into `workflows/` (enforced by `tests/test_docs_links.py`); 6 workflow→workflow `path` references (enforced by `tests/test_examples.py::test_example_workflow_references_resolve`); 18 distinct `prompt:` names across 20 files (enforced by nothing — Task 1 closes this). No workflow uses `asset:` or `output:`; the UI references no workflow paths.
+- **Run the full suite before every commit:** `python -m pytest tests/ -q`. It is ~2 minutes and this work touches files that many tests walk.
+
+---
+
+### Task 1: Close the `prompt:` reference gap
+
+Build the safety net before the demolition. 20 workflows carry `prompt:` references that nothing checks; collapsing rewrites exactly those files, and a broken `prompt:` fails only when the workflow is actually run.
+
+**Files:**
+- Create: `tests/test_prompt_references.py`
+
+**Interfaces:**
+- Consumes: `dw.prompts.resolve_prompt_reference(reference, prompt_dir=None, base_dir=None)` — returns the validated absolute path for a `"prompt:name"` or `"prompt:folder/name"` string, and **raises `ValueError` when no such prompt file exists** (`dw/prompts.py:76`). The test below catches that rather than asserting on a return value, so the failure names the workflow instead of surfacing as a bare ValueError. `dw.prompts.PROMPT_PREFIX` is the string `"prompt:"`.
+- Consumes: `tests.test_examples.get_example_files()` — returns every workflow JSON path under `workflows/`, relative to the repo root, subfolders included.
+- Produces: nothing later tasks import. This is a standalone guard.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/test_prompt_references.py`:
+
+```python
+"""Every prompt: reference in the catalog names a prompt that exists.
+
+The engine resolves a prompt: reference when the workflow runs, so a
+reference to a prompt that was renamed or removed fails on the GPU rather
+than in CI. This is the one reference class in the tree that nothing else
+checks - sub-workflow paths, type names and constants all have their own
+test in test_examples.py.
+"""
+
+import json
+import os
+
+import pytest
+
+from dw.prompts import PROMPT_PREFIX, resolve_prompt_reference
+from tests.test_examples import REPO_ROOT, get_example_files
+
+PROMPT_DIR = os.path.join(REPO_ROOT, "prompts")
+
+
+def prompt_references(definition):
+    """Every "prompt:..." string anywhere in a workflow definition."""
+    if isinstance(definition, dict):
+        for value in definition.values():
+            yield from prompt_references(value)
+    elif isinstance(definition, list):
+        for value in definition:
+            yield from prompt_references(value)
+    elif isinstance(definition, str) and definition.startswith(PROMPT_PREFIX):
+        yield definition
+
+
+@pytest.mark.parametrize("example_file", get_example_files())
+def test_every_prompt_reference_resolves(example_file):
+    path = os.path.join(REPO_ROOT, example_file)
+    with open(path, encoding="utf-8") as file:
+        definition = json.load(file)
+
+    for reference in prompt_references(definition):
+        # resolve_prompt_reference raises rather than returning a missing path,
+        # and a bare ValueError would not say which workflow carried the
+        # reference - the only thing that makes the failure actionable
+        try:
+            resolve_prompt_reference(reference, prompt_dir=PROMPT_DIR)
+        except ValueError as e:
+            pytest.fail(f"{example_file} references '{reference}': {e}")
+
+
+def test_the_catalog_actually_uses_prompt_references():
+    """Guards the guard: if the walk stops finding references, the test above
+    passes vacuously and would keep passing through the restructure."""
+    found = []
+    for example_file in get_example_files():
+        with open(os.path.join(REPO_ROOT, example_file), encoding="utf-8") as file:
+            found.extend(prompt_references(json.load(file)))
+
+    assert len(set(found)) >= 10
+```
+
+- [ ] **Step 2: Run it and confirm it passes on the current tree**
+
+Run: `python -m pytest tests/test_prompt_references.py -q`
+Expected: PASS. The catalog is consistent today — this test is a guard against the restructure breaking it, not a bug fix. If it FAILS, stop: there is a pre-existing broken reference to report before going further.
+
+- [ ] **Step 3: Confirm the guard actually catches a break**
+
+Temporarily rename a prompt the catalog uses and confirm the test fails:
+
+```bash
+REF=$(python -c "
+import json, os
+from tests.test_examples import REPO_ROOT, get_example_files
+from tests.test_prompt_references import prompt_references
+for f in get_example_files():
+    refs = list(prompt_references(json.load(open(os.path.join(REPO_ROOT, f)))))
+    if refs:
+        print(refs[0].split(':', 1)[1]); break
+")
+mv "prompts/$REF.json" "prompts/$REF.json.bak"
+python -m pytest tests/test_prompt_references.py -q   # expect FAIL
+mv "prompts/$REF.json.bak" "prompts/$REF.json"
+python -m pytest tests/test_prompt_references.py -q   # expect PASS
+```
+
+Expected: FAIL while renamed, PASS once restored. A guard never seen to fail is not a guard.
+
+- [ ] **Step 4: Run the full suite**
+
+Run: `python -m pytest tests/ -q`
+Expected: all pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/test_prompt_references.py
+git commit -m "Check that every prompt: reference in the catalog resolves
+
+Sub-workflow paths, type names and constants each have a test that they
+resolve; prompt: references had none, and they fail on the GPU rather
+than in CI. Added ahead of the catalog restructure, which rewrites the
+20 workflows carrying them."
+```
+
+---
+
+### Task 2: The inventory, and the approval gate
+
+The judgement call across all 121 workflows, written down before anything moves. This task produces a document and stops. **No file is moved, renamed or deleted in this task.**
+
+**Files:**
+- Create: `docs/superpowers/plans/2026-09-06-catalog-inventory.md`
+
+**Interfaces:**
+- Produces: the inventory document. Every later task consumes it as its file list. Its schema is fixed below so later tasks can be executed mechanically.
+
+- [ ] **Step 1: Generate the raw list of every workflow**
+
+```bash
+find workflows -name "*.json" | sort > /tmp/catalog.txt
+wc -l /tmp/catalog.txt   # expect 121
+```
+
+- [ ] **Step 2: Read every workflow and classify it**
+
+Read each file. Do not classify from the filename — the filename is what made the catalog misleading in the first place. For each, record the verdict using the criteria from the spec:
+
+- `TEMPLATE` — demonstrates a feature nothing else demonstrates: a shape (multi-shot cut sequence, chained conditioning, image-to-video), a mechanism (shared components, sub-workflows, `pipeline_reference`, `references`, `release_pipeline`/`release_models`), or a reference convention (`prompt:`, `previous_result:`).
+- `MODEL` — carries settings that make a specific checkpoint fit real hardware: quantization, offload, component placement, truncation, cache.
+- `COLLAPSE INTO <template>` — the same pattern as a template through a different checkpoint, where the pipeline class matches. Its distinguishing arguments become an argument set in that template's `description`.
+- `DELETE` — a third checkpoint through an existing pattern, teaching nothing new.
+
+- [ ] **Step 3: Write the inventory document**
+
+Create `docs/superpowers/plans/2026-09-06-catalog-inventory.md` with this exact table schema — later tasks parse it by column:
+
+```markdown
+# Catalog inventory, 2026-09-06
+
+Verdicts for every workflow under `workflows/`. Produced by Task 2 of the
+[restructure plan](2026-09-06-workflow-catalog-restructure.md); the file lists
+in Tasks 3-5 are this table, filtered by verdict.
+
+Status: AWAITING APPROVAL
+
+| Current path | Verdict | Destination | `id` | Why |
+| --- | --- | --- | --- | --- |
+| workflows/flux/FluxDev.json | COLLAPSE INTO | templates/text-to-image.json | FluxDev | One-step t2i; differs from Krea2/ZImage only by checkpoint |
+| workflows/minimax/MiniMaxH3SitcomShort.json | TEMPLATE | templates/dialogue-short.json | MiniMaxH3SitcomShort | Only multi-shot cut sequence with per-shot references |
+| workflows/archive/CogVideoX-5b.json | DELETE | — | — | Fourth CogVideoX variant; no feature the tree lacks |
+```
+
+Rules for the table:
+- Every one of the 121 paths appears exactly once.
+- `Destination` is a path relative to `workflows/`, or `—` for DELETE.
+- The `id` column is the file's current `id` field, copied verbatim — it is what Task 3 and Task 4 must preserve.
+- `Why` is one clause. If it takes a sentence, the verdict is probably wrong.
+
+- [ ] **Step 4: Check the inventory against itself**
+
+```bash
+python - <<'PY'
+import json, re, pathlib
+rows = [l for l in pathlib.Path(
+    "docs/superpowers/plans/2026-09-06-catalog-inventory.md"
+).read_text().splitlines() if l.startswith("| workflows/")]
+paths = [r.split("|")[1].strip() for r in rows]
+on_disk = sorted(str(p) for p in pathlib.Path("workflows").rglob("*.json"))
+print("rows:", len(rows), "on disk:", len(on_disk))
+assert sorted(paths) == on_disk, set(on_disk) ^ set(paths)
+dests = [r.split("|")[3].strip() for r in rows]
+dupes = {d for d in dests if d != "—" and dests.count(d) > 1}
+print("destinations reused by more than one row (expected for COLLAPSE):", dupes)
+ids = [r.split("|")[4].strip() for r in rows]
+for path, wid in zip(paths, ids):
+    if wid == "—":
+        continue
+    actual = json.load(open(path)).get("id")
+    assert wid == actual, f"{path}: inventory says id {wid!r}, file says {actual!r}"
+print("every row's id matches the file")
+PY
+```
+
+Expected: row count 121, matching path sets, and every `id` verified against the file it came from.
+
+- [ ] **Step 5: Commit the inventory**
+
+```bash
+git add docs/superpowers/plans/2026-09-06-catalog-inventory.md
+git commit -m "Inventory every workflow ahead of the catalog restructure
+
+A verdict per file - template, model config, collapse target or delete -
+with the id each surviving file must keep. Awaiting approval; nothing is
+moved or deleted until it has it."
+```
+
+- [ ] **Step 6: STOP. Get the user's approval.**
+
+Present the inventory with counts per verdict and the full DELETE list, and ask for approval. **Do not begin Task 3 until the user approves.** If they change verdicts, edit the table, re-run Step 4, amend the commit, and ask again. When approved, change `Status: AWAITING APPROVAL` to `Status: approved <date>` and commit that.
+
+---
+
+### Task 3: Build `workflows/templates/`
+
+**Files:**
+- Create: `workflows/templates/` (contents per the inventory)
+- Create: `tests/test_catalog_structure.py`
+- Modify: `dw/workflow_schema.json` (add the optional `configures` property)
+
+**Interfaces:**
+- Consumes: the approved inventory's `TEMPLATE` and `COLLAPSE INTO` rows.
+- Produces: `workflows/templates/*.json`, each with a non-empty `description` and its original `id`. Task 4 relies on these paths existing to point `configures` at them.
+- Produces: `tests/test_catalog_structure.py`, which Task 4 extends.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/test_catalog_structure.py`:
+
+```python
+"""The catalog's two trees, and the invariant each carries.
+
+templates/ teaches a pattern and models/ records a hardware fact. The
+distinction is only useful if it is legible from outside the file, so a
+template must describe itself and a model config must name the template it
+configures.
+"""
+
+import json
+import os
+
+import pytest
+
+from tests.test_examples import REPO_ROOT
+
+TEMPLATES_DIR = os.path.join(REPO_ROOT, "workflows", "templates")
+
+
+def files_under(directory):
+    if not os.path.isdir(directory):
+        return []
+    found = []
+    for root, _, names in os.walk(directory):
+        found.extend(
+            os.path.join(root, name) for name in names if name.endswith(".json")
+        )
+    return sorted(found)
+
+
+def test_there_are_templates():
+    assert files_under(TEMPLATES_DIR)
+
+
+@pytest.mark.parametrize("path", files_under(TEMPLATES_DIR))
+def test_every_template_describes_itself(path):
+    """A template is read before it is run - by a person choosing one and by an
+    agent matching a request's shape. An undescribed template is invisible to
+    both, whatever its filename says."""
+    definition = json.load(open(path, encoding="utf-8"))
+
+    assert definition.get("description", "").strip(), (
+        f"{os.path.relpath(path, REPO_ROOT)} has no description"
+    )
+```
+
+- [ ] **Step 2: Run it and watch it fail**
+
+Run: `python -m pytest tests/test_catalog_structure.py -q`
+Expected: FAIL on `test_there_are_templates` — `workflows/templates/` does not exist yet.
+
+- [ ] **Step 3: Add `configures` to the schema**
+
+The workflow schema sets no top-level `additionalProperties`, so an unknown key already validates — but an undeclared field is undocumented. In `dw/workflow_schema.json`, add to the top-level `properties` object alongside `description`:
+
+```json
+"configures": {
+    "type": "string",
+    "description": "For a workflow under models/: the templates/ workflow this is a tuned per-checkpoint configuration of, as a catalog name such as 'templates/text-to-image'."
+}
+```
+
+- [ ] **Step 4: Move and collapse, per the inventory**
+
+For each `TEMPLATE` row, `git mv` the file to its destination. For each `COLLAPSE INTO` row, fold its distinguishing arguments into the destination template as a documented argument set in that template's `description`, then `git rm` the source.
+
+Preserve each surviving file's `id` verbatim — Global Constraints. Where two workflows collapse into one, the destination keeps the `id` of whichever row's destination equals its own path.
+
+Six workflows name another workflow by a relative `path`; when either end moves, fix the path in the same commit. `tests/test_examples.py::test_example_workflow_references_resolve` is what catches a miss.
+
+- [ ] **Step 5: Run the structure and example tests**
+
+Run: `python -m pytest tests/test_catalog_structure.py tests/test_examples.py tests/test_prompt_references.py -q`
+Expected: all pass. A `prompt:` failure here means a collapse dropped a reference; an examples failure means a relative `path` was left pointing at a moved file.
+
+- [ ] **Step 6: Run the full suite**
+
+Run: `python -m pytest tests/ -q`
+Expected: all pass except `tests/test_docs_links.py`, which will fail until Task 6 updates the 66 markdown links. Note which links fail — that is Task 6's worklist.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add -A workflows/ tests/test_catalog_structure.py dw/workflow_schema.json
+git commit -m "Move the feature templates into workflows/templates/
+
+One file per capability, with checkpoint variations collapsed into
+argument sets in each template's description where the pipeline class
+matched. Every surviving file keeps its id, so the step cache survives.
+
+Doc links are updated in a later commit and test_docs_links fails until
+then."
+```
+
+---
+
+### Task 4: Build `workflows/models/`
+
+**Files:**
+- Create: `workflows/models/` (contents per the inventory)
+- Modify: `tests/test_catalog_structure.py`
+
+**Interfaces:**
+- Consumes: the approved inventory's `MODEL` rows; the `workflows/templates/*.json` paths Task 3 produced.
+- Produces: `workflows/models/*.json`, each carrying `configures` naming an existing template.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `tests/test_catalog_structure.py`:
+
+```python
+MODELS_DIR = os.path.join(REPO_ROOT, "workflows", "models")
+
+
+def test_there_are_model_configs():
+    assert files_under(MODELS_DIR)
+
+
+@pytest.mark.parametrize("path", files_under(MODELS_DIR))
+def test_every_model_config_names_the_template_it_configures(path):
+    """A model config is a tuned instance of a pattern. Without the pointer it
+    is just another entry in the list, which is the problem this restructure
+    exists to fix."""
+    definition = json.load(open(path, encoding="utf-8"))
+    configures = definition.get("configures", "")
+
+    assert configures, (
+        f"{os.path.relpath(path, REPO_ROOT)} has no 'configures'"
+    )
+    target = os.path.join(REPO_ROOT, "workflows", f"{configures}.json")
+    assert os.path.isfile(target), (
+        f"{os.path.relpath(path, REPO_ROOT)} configures '{configures}', "
+        f"which is not a workflow ({target})"
+    )
+```
+
+- [ ] **Step 2: Run it and watch it fail**
+
+Run: `python -m pytest tests/test_catalog_structure.py -q`
+Expected: FAIL on `test_there_are_model_configs` — `workflows/models/` does not exist yet.
+
+- [ ] **Step 3: Move the model configs and add `configures`**
+
+For each `MODEL` row, `git mv` the file to its destination and add a top-level `configures` naming its template as a catalog name without the `.json` — for example `"configures": "templates/text-to-image"`. Preserve each `id` verbatim.
+
+- [ ] **Step 4: Run the structure and example tests**
+
+Run: `python -m pytest tests/test_catalog_structure.py tests/test_examples.py tests/test_prompt_references.py -q`
+Expected: all pass.
+
+- [ ] **Step 5: Run the full suite**
+
+Run: `python -m pytest tests/ -q`
+Expected: all pass except `tests/test_docs_links.py` (Task 6).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add -A workflows/ tests/test_catalog_structure.py
+git commit -m "Move the per-checkpoint configurations into workflows/models/
+
+Each names the template it configures, so a tuned 24GB config is findable
+as an instance of a pattern rather than as another undifferentiated
+catalog entry. Ids preserved."
+```
+
+---
+
+### Task 5: Prune
+
+Everything the inventory marks `DELETE`, plus what is left of `archive/`. Separate from Tasks 3 and 4 because a reviewer could reasonably approve the moves and reject a deletion.
+
+**Files:**
+- Delete: every `DELETE` row's path
+- Delete: `workflows/archive/` entirely
+
+**Interfaces:**
+- Consumes: the approved inventory's `DELETE` rows.
+- Produces: nothing. This task only removes.
+
+- [ ] **Step 1: Confirm nothing surviving points at what is about to go**
+
+```bash
+python - <<'PY'
+import pathlib, re
+inv = pathlib.Path("docs/superpowers/plans/2026-09-06-catalog-inventory.md").read_text()
+doomed = [l.split("|")[1].strip() for l in inv.splitlines()
+          if l.startswith("| workflows/") and l.split("|")[2].strip() == "DELETE"]
+print(len(doomed), "files to delete")
+for path in doomed:
+    stem = pathlib.Path(path).name
+    hits = []
+    for f in list(pathlib.Path("workflows").rglob("*.json")) + \
+             list(pathlib.Path("docs").rglob("*.md")) + [pathlib.Path("README.md")]:
+        if str(f) in doomed:
+            continue
+        if stem in f.read_text():
+            hits.append(str(f))
+    if hits:
+        print(f"  STILL REFERENCED {path}: {hits}")
+PY
+```
+
+Expected: no `STILL REFERENCED` lines. Any that appear must be resolved first — either the referencing file is updated, or the verdict was wrong and the inventory needs revisiting with the user.
+
+- [ ] **Step 2: Delete**
+
+```bash
+# every DELETE row, then what remains of archive/
+python - <<'PY'
+import pathlib, subprocess
+inv = pathlib.Path("docs/superpowers/plans/2026-09-06-catalog-inventory.md").read_text()
+doomed = [l.split("|")[1].strip() for l in inv.splitlines()
+          if l.startswith("| workflows/") and l.split("|")[2].strip() == "DELETE"]
+for path in doomed:
+    if pathlib.Path(path).exists():
+        subprocess.run(["git", "rm", "-q", path], check=True)
+PY
+git rm -rq workflows/archive 2>/dev/null || true
+find workflows -name "*.json" | wc -l   # the surviving count
+```
+
+- [ ] **Step 3: Run the full suite**
+
+Run: `python -m pytest tests/ -q`
+Expected: all pass except `tests/test_docs_links.py` (Task 6). If `test_examples.py` fails, a surviving workflow referenced a deleted one and Step 1 missed it.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add -A workflows/
+git commit -m "Delete the checkpoint iterations and empty archive/
+
+Every removed file was a further checkpoint through a pattern the tree
+already demonstrates. Git history is the archive, so archive/ stops being
+a graveyard that costs listing space."
+```
+
+---
+
+### Task 6: Fix every link and every description of the old layout
+
+**Files:**
+- Modify: `docs/*.md` (66 distinct workflow paths across them), `README.md`
+- Modify: `CLAUDE.md` if it describes the old layout
+
+**Interfaces:**
+- Consumes: the new tree from Tasks 3–5.
+- Produces: a repo whose markdown all resolves.
+
+- [ ] **Step 1: List every broken link**
+
+Run: `python -m pytest tests/test_docs_links.py -q 2>&1 | head -40`
+Expected: failures naming each unresolvable path. This is the worklist.
+
+- [ ] **Step 2: Repoint each link**
+
+For each, find the file's new home in the inventory's `Destination` column and update the link. Where the target was deleted, remove the reference and the sentence around it if the sentence only existed to introduce it — a dangling half-sentence is worse than the missing link.
+
+Check the prose too, not only the link targets: any text describing `workflows/flux/` or `archive/` as places, and any "Examples:" list naming a deleted file.
+
+- [ ] **Step 3: Run the docs-link test**
+
+Run: `python -m pytest tests/test_docs_links.py -q`
+Expected: PASS.
+
+- [ ] **Step 4: Run the full suite**
+
+Run: `python -m pytest tests/ -q`
+Expected: all pass, with no exceptions this time.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A docs/ README.md CLAUDE.md
+git commit -m "Repoint documentation at the restructured catalog
+
+All 66 workflow links, plus the prose describing the old folder layout
+and the example lists naming deleted files."
+```
+
+---
+
+### Task 7: Prove consistency and describe the new layout
+
+The acceptance criterion, made checkable, plus the one doc that has to exist for the new structure to be legible.
+
+**Files:**
+- Modify: `docs/WORKFLOW_GUIDE.md` (a section on the two trees)
+- Modify: `dw_mcp/guides.py` if the guide summary needs updating
+- Modify: `docs/superpowers/plans/2026-09-06-catalog-inventory.md` (mark it done)
+
+**Interfaces:**
+- Consumes: everything above.
+- Produces: the finished state.
+
+- [ ] **Step 1: Run every reference class at once**
+
+```bash
+python -m pytest tests/test_docs_links.py tests/test_examples.py \
+    tests/test_prompt_references.py tests/test_catalog_structure.py -q
+```
+
+Expected: all pass. These four are the whole acceptance criterion — markdown links, sub-workflow paths, type and constant references, `prompt:` references, and the two-tree invariants.
+
+- [ ] **Step 2: Confirm no id changed**
+
+```bash
+python - <<'IDCHECK'
+import json, pathlib
+# The inventory is the record of what every id was before anything moved. Read
+# it from the working tree - it was written in Task 2, so no earlier commit has
+# it.
+inv = pathlib.Path(
+    "docs/superpowers/plans/2026-09-06-catalog-inventory.md"
+).read_text()
+rows = [l.split("|") for l in inv.splitlines() if l.startswith("| workflows/")]
+deleted = {r[1].strip() for r in rows if r[2].strip() == "DELETE"}
+expected = {
+    r[4].strip()
+    for r in rows
+    if r[1].strip() not in deleted and r[4].strip() not in ("—", "")
+}
+on_disk = {json.load(open(p))["id"] for p in pathlib.Path("workflows").rglob("*.json")}
+lost = sorted(expected - on_disk)
+assert not lost, f"surviving ids missing from disk: {lost}"
+print(f"all {len(expected)} surviving ids intact")
+IDCHECK
+```
+
+Expected: the only absent ids belong to deleted rows. Any other absence means an `id` was changed, which invalidates the step cache — fix it before continuing.
+
+- [ ] **Step 3: Document the two trees**
+
+Add a section to `docs/WORKFLOW_GUIDE.md` explaining the split: `templates/` teaches a pattern and is what to copy; `models/` records what makes a checkpoint fit real hardware and names the template it configures. Say that a template carries its per-checkpoint argument sets in its own `description`, and that `configures` is how a model config points home.
+
+Then check whether `dw_mcp/guides.py`'s one-line summary for `workflows` still describes the guide accurately, and update it if not.
+
+- [ ] **Step 4: Mark the inventory done**
+
+Change its status line to `Status: applied <date>`.
+
+- [ ] **Step 5: Run the full suite**
+
+Run: `python -m pytest tests/ -q`
+Expected: all pass.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add -A docs/ dw_mcp/guides.py
+git commit -m "Document the two-tree catalog and mark the inventory applied
+
+templates/ teaches a pattern, models/ records what makes a checkpoint fit
+and names the template it configures. Every reference class - markdown
+links, sub-workflow paths, type and constant references, prompt:
+references - resolves."
+```
+
+---
+
+## What this deliberately leaves out
+
+The derived shape index and measured runtimes. They belong on top of this, not
+beside it: classifying a catalog about to be halved is wasted work, and the
+derivation gets materially more accurate once "template or model config" is a
+distinction it can read from the path rather than infer. See the spec's "What
+this unblocks".

From 7d9af4e104e521851ae14be334f3953fc46ee838 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 14:36:23 -0500
Subject: [PATCH 07/32] Check that every prompt: reference in the catalog
 resolves

Sub-workflow paths, type names and constants each have a test that they
resolve; prompt: references had none, and they fail on the GPU rather
than in CI. Added ahead of the catalog restructure, which rewrites the
20 workflows carrying them.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 tests/test_prompt_references.py | 57 +++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 tests/test_prompt_references.py

diff --git a/tests/test_prompt_references.py b/tests/test_prompt_references.py
new file mode 100644
index 00000000..13a74d01
--- /dev/null
+++ b/tests/test_prompt_references.py
@@ -0,0 +1,57 @@
+"""Every prompt: reference in the catalog names a prompt that exists.
+
+The engine resolves a prompt: reference when the workflow runs, so a
+reference to a prompt that was renamed or removed fails on the GPU rather
+than in CI. This is the one reference class in the tree that nothing else
+checks - sub-workflow paths, type names and constants all have their own
+test in test_examples.py.
+"""
+
+import json
+import os
+
+import pytest
+
+from dw.prompts import PROMPT_PREFIX, resolve_prompt_reference
+from tests.test_examples import REPO_ROOT, get_example_files
+
+PROMPT_DIR = os.path.join(REPO_ROOT, "prompts")
+
+
+def prompt_references(definition):
+    """Every "prompt:..." string anywhere in a workflow definition."""
+    if isinstance(definition, dict):
+        for value in definition.values():
+            yield from prompt_references(value)
+    elif isinstance(definition, list):
+        for value in definition:
+            yield from prompt_references(value)
+    elif isinstance(definition, str) and definition.startswith(PROMPT_PREFIX):
+        yield definition
+
+
+@pytest.mark.parametrize("example_file", get_example_files())
+def test_every_prompt_reference_resolves(example_file):
+    path = os.path.join(REPO_ROOT, example_file)
+    with open(path, encoding="utf-8") as file:
+        definition = json.load(file)
+
+    for reference in prompt_references(definition):
+        # resolve_prompt_reference raises rather than returning a missing path,
+        # and a bare ValueError would not say which workflow carried the
+        # reference - the only thing that makes the failure actionable
+        try:
+            resolve_prompt_reference(reference, prompt_dir=PROMPT_DIR)
+        except ValueError as e:
+            pytest.fail(f"{example_file} references '{reference}': {e}")
+
+
+def test_the_catalog_actually_uses_prompt_references():
+    """Guards the guard: if the walk stops finding references, the test above
+    passes vacuously and would keep passing through the restructure."""
+    found = []
+    for example_file in get_example_files():
+        with open(os.path.join(REPO_ROOT, example_file), encoding="utf-8") as file:
+            found.extend(prompt_references(json.load(file)))
+
+    assert len(set(found)) >= 10

From d5693bf207140fc5eb65d38db9ddefaf3920e8e5 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 14:44:17 -0500
Subject: [PATCH 08/32] Correct the restructure spec's premise after reading
 all 121 workflows

The first draft argued from a crude feature signature and overstated the
redundancy. Reading found it concentrated in archive/, which is a pure
model gallery, while minimax/ and ltx2/ are a curriculum where each file
demonstrates a conditioning mode or mechanism nothing else does - those
stay. gyre/ is a test project's production history; only the mechanisms
that generalize earn templates.

Also records two ids used by two workflows each, which collide in the
step cache today and are resolved by emptying archive/.

Expected scale is now 45-50 deletions rather than a halving.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 ...-06-workflow-catalog-restructure-design.md | 59 +++++++++++++------
 1 file changed, 40 insertions(+), 19 deletions(-)

diff --git a/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md b/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md
index f1b38677..bb90ffa3 100644
--- a/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md
+++ b/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md
@@ -32,27 +32,48 @@ one flat list, and to let the catalog say which is which.
 
 ## What is wrong today
 
-Measured across the 84 non-archive workflows on 2026-09-06:
-
-1. **54 of 84 share a feature signature with at least one other file** - there
-   are 43 distinct signatures. The redundancy is not incidental; it is most of
-   the catalog.
-2. The clusters are checkpoint iterations, not feature variations: 5 MiniMax H3
-   `ref2va` files differing only in chaining and output kind, 4 LTX-2 files
-   differing only in conditioning, 5 one-step text-to-image files differing only
-   in the checkpoint (`FluxDev`, `Krea2`, `ZImage`, `ZImageSDNQ`,
-   `FluxSchnellWeighted`), and `FluxGGUF`/`FluxTorchAO` differing only in
-   quantization backend.
-3. `archive/` (37 files) is almost purely a model gallery - 4 CogVideoX
-   variants, 6 Wan variants, 3 Kandinsky - and still costs listing space.
-4. Nothing in a catalog entry distinguishes "this teaches a pattern" from "this
+Revised 2026-09-06 after reading all 121 workflows. The first version of this
+section argued from a crude feature signature and overstated the problem; what
+follows is what reading found.
+
+1. **`archive/` (37 files) is a model gallery and nothing else.** Almost every
+   entry is one line - "Text-to-video with Allegro", "Text-to-image with
+   Kolors", "Text-to-video with CogVideoX 5B". Four CogVideoX, six Wan, three
+   Kandinsky, three Hunyuan. This is where the redundancy actually is.
+2. **The `minimax/` (18) and `ltx2/` (8) families are not redundant at all.**
+   They are a curriculum: each file demonstrates a conditioning mode or
+   mechanism nothing else does - first-frame, last-frame and both-ends
+   conditioning; `match_audio` sizing a chain from a supplied track;
+   `last_segment` handing over a video tail rather than one frame; composable
+   reference types. Under this spec's own criteria they are all templates, and
+   they stay (user's decision, 2026-09-06: these are current models and of
+   interest to people).
+3. The genuine non-archive redundancy is narrower and specific: `flux/`
+   acceleration variants (`FluxDevTeaCache`, `FluxDevFirstBlockCache`,
+   `FluxDevFast` - three ways to speed up one model), `FluxGGUF`/`FluxTorchAO`
+   (two quantization backends), and the one-step text-to-image set spread across
+   `FluxDev`, `Krea2`, `ZImage`, `Flux2Dev` and `sd15`.
+4. **`gyre/` (8) is a test project's production history, not examples.**
+   `GyreStillsFix2` is described as "Third attempt at GYRE's second shot". The
+   mechanisms in it that generalize - cross-dissolves, an edit-only assembly
+   pass, `recenter_crop` registration - are worth templates; the project-specific
+   passes and one-off repairs are not (user's decision, 2026-09-06).
+5. Nothing in a catalog entry distinguishes "this teaches a pattern" from "this
    records a hardware fact", so an agent cannot weight them differently and a
-   person browsing the repo cannot either.
+   person browsing the repo cannot either. This is the problem the restructure
+   is actually for, and it is unaffected by the correction above.
 
-A caveat on point 1, recorded so nobody over-trusts it: the signature used to
-measure it was crude, and missed ControlNet - it put `FluxCanny` and `Segment`
-in one bucket when they demonstrate different features. The clusters are
-indicative. The inventory (below) is the authority, and it is done by reading.
+**Two ids are used twice**, which collides in the step cache (keyed on
+`(workflow id, step name)`): `sd35` for both `archive/bnb_quant.json` and
+`archive/sd35.json`, and `test_job` for both `archive/sd15.json` and
+`workflows/sd15.json`. Emptying `archive/` resolves both - the restructure fixes
+this rather than causing it.
+
+### Expected scale
+
+Roughly 45-50 deletions, most of them in `archive/`, leaving around 70-75
+workflows. Not the halving the first draft of this spec implied. The change is
+worth making for the structure it creates, not for the volume it removes.
 
 ## The distinction the structure encodes
 

From e59a4716b52d58fa295f4b4940b4518222060d54 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 14:45:50 -0500
Subject: [PATCH 09/32] Inventory every workflow ahead of the catalog
 restructure

A verdict per file - template, model config, collapse target or delete -
with the id each surviving file must keep. Awaiting approval; nothing is
moved or deleted until it has it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../plans/2026-09-06-catalog-inventory.md     | 150 ++++++++++++++++++
 1 file changed, 150 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-09-06-catalog-inventory.md

diff --git a/docs/superpowers/plans/2026-09-06-catalog-inventory.md b/docs/superpowers/plans/2026-09-06-catalog-inventory.md
new file mode 100644
index 00000000..1c0b8ff2
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-06-catalog-inventory.md
@@ -0,0 +1,150 @@
+# Catalog inventory, 2026-09-06
+
+Verdicts for every workflow under `workflows/`. Produced by Task 2 of the
+[restructure plan](2026-09-06-workflow-catalog-restructure.md); the file lists
+in Tasks 3-5 are this table, filtered by verdict.
+
+Status: AWAITING APPROVAL
+
+Counts: COLLAPSE INTO 6, DELETE 42, MODEL 9, TEMPLATE 64 (total 121)
+
+| Current path | Verdict | Destination | `id` | Why |
+| --- | --- | --- | --- | --- |
+| workflows/InterpolateFrames.json | TEMPLATE | templates/interpolate-frames.json | InterpolateFrames | Only RIFE interpolation demo |
+| workflows/Krea2.json | MODEL | models/krea2.json | Krea2 | One-step t2i with Krea 2 Turbo |
+| workflows/Krea2Edit.json | TEMPLATE | templates/image-edit.json | Krea2Edit | Identity-preserving edit via LoRA; needs a description written |
+| workflows/ZImage.json | MODEL | models/z-image.json | ZImage | One-step t2i with Z-Image Turbo |
+| workflows/ZImageSDNQ.json | MODEL | models/z-image-sdnq.json | ZImageSDNQ | Pre-quantized SDNQ uint4 - a VRAM fact |
+| workflows/archive/Allegro.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/CogVideoX-5B-I2V.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/CogVideoX-5b.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/CogVideoX1.5-5B-I2V.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/CogVideoX1.5-5B.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/ErnieImageTurbo.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/HunyuanVideo.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/HunyuanVideoGguf.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/Ideogram4.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/Kolors.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/Lumina.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/Mochi.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/NucleusAI.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/QwenImageEdit.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/Wan22I2V14B.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/Wan22T2V14B.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/Wan22TI2V5B.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/WanI2V14.json | DELETE | — | — | Outpaint-then-animate; both halves have templates |
+| workflows/archive/WanT2V1.3.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/WanT2V14.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/bnb_quant.json | DELETE | — | — | Shares the id sd35 with archive/sd35.json |
+| workflows/archive/hunyuan15.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/img2vid.json | DELETE | — | — | Four checkpoints through one image-to-video shape |
+| workflows/archive/ip-adapter.json | DELETE | — | — | templates/ip-adapter.json covers the mechanism |
+| workflows/archive/kandinsky.json | DELETE | — | — | Kandinsky-specific prior + ControlNet chain |
+| workflows/archive/kandinsky3.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/kandinsky_i2i.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/ltx.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/owl.json | DELETE | — | — | Workflow composition survives in templates/compose-workflows.json |
+| workflows/archive/qr_code.json | TEMPLATE | templates/qr-code.json | qr_code | Unique task command, still linked from TASKS.md |
+| workflows/archive/sana.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/sd15.json | DELETE | — | — | Duplicate of workflows/sd15.json, same id |
+| workflows/archive/sd35.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/sd35ip.json | DELETE | — | — | Model-gallery entry; no feature the tree lacks |
+| workflows/archive/sdxl.json | TEMPLATE | templates/base-and-refiner.json | sdxl | The two-stage base-plus-refiner pattern |
+| workflows/archive/sdxl_refiner.json | DELETE | — | — | The refiner pattern survives in templates/base-and-refiner.json |
+| workflows/archive/txt2img2vid.json | TEMPLATE | templates/compose-workflows.json | txt2img2vid | Composes any t2i with any i2v, both named as variables |
+| workflows/attention_processors_example.json | TEMPLATE | templates/attention-processor.json | attention_processors_example | Only custom attention-processor demo |
+| workflows/controlnet.json | TEMPLATE | templates/controlnet-component.json | sd15-controlnet | ControlNetModel loaded as a separate component, unlike FluxControlPipeline |
+| workflows/flux/Flux2Dev.json | MODEL | models/flux2-dev.json | Flux2Dev | One-step t2i with FLUX.2 dev, 4-bit |
+| workflows/flux/Flux2DevImageCombine.json | TEMPLATE | templates/multi-image-reference.json | Flux2DevImageCombine | Combining several reference images into one generation |
+| workflows/flux/FluxCanny.json | TEMPLATE | templates/controlnet.json | FluxCanny | Preprocessor step feeding a control pipeline |
+| workflows/flux/FluxDepth.json | COLLAPSE INTO | templates/controlnet.json | FluxDepth | Same shape as FluxCanny; only the preprocessor differs |
+| workflows/flux/FluxDev.json | MODEL | models/flux-dev.json | FluxDev | One-step t2i with FLUX.1 dev |
+| workflows/flux/FluxDevFast.json | MODEL | models/flux-dev-fast.json | FluxDevFast | 24GB tuning: int8 TorchAO resident + regional offload |
+| workflows/flux/FluxDevFirstBlockCache.json | TEMPLATE | templates/step-caching.json | FluxDevFirstBlockCache | Skipping redundant transformer work across denoise steps |
+| workflows/flux/FluxDevKrea.json | MODEL | models/flux-krea.json | FluxDevKrea | One-step t2i with the FLUX.1 Krea dev checkpoint |
+| workflows/flux/FluxDevTeaCache.json | COLLAPSE INTO | templates/step-caching.json | FluxDevTeaCache | Same cache block, different type |
+| workflows/flux/FluxFill.json | TEMPLATE | templates/inpaint.json | FluxFill | Only inpainting demo |
+| workflows/flux/FluxGGUF.json | MODEL | models/flux-gguf.json | FluxGGUF | GGUF-quantized transformer checkpoint |
+| workflows/flux/FluxIP.json | TEMPLATE | templates/ip-adapter.json | FluxIP | Only IP-Adapter demo outside archive |
+| workflows/flux/FluxImg2Img.json | TEMPLATE | templates/image-to-image.json | FluxImg2Img | Only img2img demo |
+| workflows/flux/FluxInContext.json | TEMPLATE | templates/lora-styles.json | FluxInContext | Ten adapters, one image each - per-step LoRA switching |
+| workflows/flux/FluxLogo.json | TEMPLATE | templates/sub-workflow.json | FluxLogo | Delegates to another workflow, then post-processes |
+| workflows/flux/FluxLora.json | TEMPLATE | templates/lora.json | FluxLora | The LoRA reference |
+| workflows/flux/FluxOutpaint.json | TEMPLATE | templates/outpaint.json | FluxOutpaint | Border mask then fill - only outpaint demo |
+| workflows/flux/FluxRFInversion.json | TEMPLATE | templates/community-pipeline.json | FluxRfInversion | Only community pipeline + pipeline_reference demo |
+| workflows/flux/FluxRedux.json | TEMPLATE | templates/image-variation.json | FluxRedux | Prior redux encode then regenerate |
+| workflows/flux/FluxSchnellWeighted.json | TEMPLATE | templates/prompt-weighting.json | FluxSchnellWeighted | Only A1111-style weighting demo |
+| workflows/flux/FluxTorchAO.json | MODEL | models/flux-torchao.json | FluxTorchAO | int8 TorchAO quantization |
+| workflows/flux/img2txt2img.json | TEMPLATE | templates/describe-and-regenerate.json | img2txt2img | VLM then LLM then generate, across sub-workflows |
+| workflows/gyre/GyreAssemble.json | TEMPLATE | templates/assemble-and-score.json | GyreAssemble | Edit-only pass: stabilize, cut, mix a score under shot audio; needs generalizing off GYRE |
+| workflows/gyre/GyreDissolve.json | TEMPLATE | templates/dissolve-between-shots.json | GyreDissolve | Only dissolve_videos user; needs generalizing off GYRE |
+| workflows/gyre/GyreFilm.json | DELETE | — | — | Project-specific 24-step pass; SitcomShort teaches multi-shot generation |
+| workflows/gyre/GyreFrames.json | TEMPLATE | templates/recenter-crop.json | GyreFrames | recenter_crop registration; needs generalizing off GYRE |
+| workflows/gyre/GyreReshoot.json | DELETE | — | — | One-off repair of GYRE shot 4 |
+| workflows/gyre/GyreStills.json | DELETE | — | — | Project-specific keyframe pass |
+| workflows/gyre/GyreStillsFix.json | DELETE | — | — | One-off repair of two GYRE stills |
+| workflows/gyre/GyreStillsFix2.json | DELETE | — | — | Third attempt at GYRE's second shot |
+| workflows/lora.json | COLLAPSE INTO | templates/lora.json | sd35_lora | Same LoRA mechanism as FluxLora, different base |
+| workflows/ltx2/LTX2.json | TEMPLATE | templates/ltx2/text-to-video.json | LTX2 | LTX-2.5 baseline: video with a soundtrack on one 24GB card |
+| workflows/ltx2/LTX2Extend.json | TEMPLATE | templates/ltx2/extend-clip.json | LTX2Extend | Conditioning on a full clip to carry motion forward |
+| workflows/ltx2/LTX2I2V.json | TEMPLATE | templates/ltx2/image-to-video.json | LTX2I2V | Still becomes the first frame |
+| workflows/ltx2/LTX2I2VChained.json | TEMPLATE | templates/ltx2/chained-segments.json | LTX2I2VChained | Long clip from short ones, frames and audio stitched |
+| workflows/ltx2/LTX2I2VEnhancePrompt.json | TEMPLATE | templates/ltx2/enhance-prompt.json | LTX2I2VEnhancePrompt | LTX-2.5's own enhancer plus the duration head |
+| workflows/ltx2/LTX2ICLora.json | TEMPLATE | templates/ltx2/generative-upscale.json | LTX2ICLora | In-context LoRA re-renders at 2x, inventing detail |
+| workflows/ltx2/LTX2Keyframes.json | TEMPLATE | templates/ltx2/keyframes.json | LTX2Keyframes | Pinning first and last frames as conditions |
+| workflows/ltx2/LTX2TwoStage.json | TEMPLATE | templates/ltx2/two-stage.json | LTX2TwoStage | Render small then upscale in latent space |
+| workflows/minimax/MiniMaxH3.json | TEMPLATE | templates/minimax/video-with-audio.json | MiniMaxH3 | H3 baseline every other H3 example builds on |
+| workflows/minimax/MiniMaxH3EnhancePrompt.json | TEMPLATE | templates/minimax/enhance-prompt.json | MiniMaxH3EnhancePrompt | Sub-workflow output feeding the next step's argument |
+| workflows/minimax/MiniMaxH3FL2VA.json | TEMPLATE | templates/minimax/first-and-last-frame.json | MiniMaxH3FL2VA | Both ends pinned, motion interpolated |
+| workflows/minimax/MiniMaxH3GeneratedVoice.json | TEMPLATE | templates/minimax/voice-timbre-reference.json | MiniMaxH3GeneratedVoice | Generated speech as an <Audio 1> timbre reference |
+| workflows/minimax/MiniMaxH3I2V.json | TEMPLATE | templates/minimax/image-to-video.json | MiniMaxH3I2V | First frame pinned |
+| workflows/minimax/MiniMaxH3I2VChained.json | TEMPLATE | templates/minimax/chained-segments.json | MiniMaxH3I2VChained | Fixed segment count with last_frame continuity |
+| workflows/minimax/MiniMaxH3I2VEnhancePrompt.json | TEMPLATE | templates/minimax/enhance-prompt-with-image.json | MiniMaxH3I2VEnhancePrompt | Enhancer sees the same still the pipeline pins |
+| workflows/minimax/MiniMaxH3L2V.json | TEMPLATE | templates/minimax/last-frame-only.json | MiniMaxH3L2V | Final frame pinned, everything before it invented |
+| workflows/minimax/MiniMaxH3MusicVideo.json | TEMPLATE | templates/minimax/music-video.json | MiniMaxH3MusicVideo | Cuts against a soundtrack that never touches a chain |
+| workflows/minimax/MiniMaxH3Ref2VA.json | TEMPLATE | templates/minimax/reference-to-video.json | MiniMaxH3Ref2VA | Identity conditioning via typed reference objects |
+| workflows/minimax/MiniMaxH3Ref2VAChained.json | TEMPLATE | templates/minimax/chain-matched-to-audio.json | MiniMaxH3Ref2VAChained | match_audio sizes the chain from a supplied track |
+| workflows/minimax/MiniMaxH3Ref2VAChainedAligned.json | TEMPLATE | templates/minimax/chain-matched-and-aligned.json | MiniMaxH3Ref2VAChainedAligned | match_audio and last_segment used together |
+| workflows/minimax/MiniMaxH3Ref2VAChainedVideo.json | TEMPLATE | templates/minimax/chain-video-continuity.json | MiniMaxH3Ref2VAChainedVideo | last_segment hands over a video tail, not one frame |
+| workflows/minimax/MiniMaxH3Ref2VAGeneratedSubject.json | TEMPLATE | templates/minimax/generated-subject-reference.json | MiniMaxH3Ref2VAGeneratedSubject | from_previous_result builds a reference from a generated still |
+| workflows/minimax/MiniMaxH3Ref2VAVideo.json | TEMPLATE | templates/minimax/composable-references.json | MiniMaxH3Ref2VAVideo | Image supplies the subject, video supplies the shot |
+| workflows/minimax/MiniMaxH3SitcomShort.json | TEMPLATE | templates/minimax/dialogue-short.json | MiniMaxH3SitcomShort | Multi-shot cut sequence with per-shot references |
+| workflows/minimax/MiniMaxH3Storyboard.json | TEMPLATE | templates/minimax/storyboard.json | MiniMaxH3Storyboard | Several stills in one generation, each with a stated role |
+| workflows/minimax/MiniMaxMusic.json | TEMPLATE | templates/minimax/music.json | MiniMaxMusic | Audio-only output from a pipeline |
+| workflows/sd15.json | TEMPLATE | templates/text-to-image.json | test_job | Ungated baseline - the no-login quickstart CLAUDE.md points at |
+| workflows/tasks/CaptionToImage.json | DELETE | — | — | img2txt2img is the richer caption-then-generate demo |
+| workflows/tasks/DiffusionUpscale.json | DELETE | — | — | Generate-then-upscale is previous_result chaining, shown everywhere |
+| workflows/tasks/DiffusionUpscaleImage.json | TEMPLATE | templates/upscale-diffusion.json | DiffusionUpscaleImage | Upscales any existing image, no generation step |
+| workflows/tasks/ExpandAndGenerate.json | COLLAPSE INTO | templates/expand-prompt.json | ExpandAndGenerate | Expand-then-generate is the same task plus a generation step |
+| workflows/tasks/ExpandPrompt.json | TEMPLATE | templates/expand-prompt.json | ExpandPrompt | LLM prompt expansion, text out |
+| workflows/tasks/FaceRestore.json | TEMPLATE | templates/restore-faces.json | FaceRestore | Only face restoration demo |
+| workflows/tasks/GenerateSpeech.json | TEMPLATE | templates/generate-speech.json | GenerateSpeech | Only text-to-speech demo |
+| workflows/tasks/ImageToText.json | TEMPLATE | templates/image-to-text.json | ImageToText | Captioning with the small default |
+| workflows/tasks/ImageToTextVLM.json | COLLAPSE INTO | templates/image-to-text.json | ImageToTextVLM | Same task, a VLM and a specific question |
+| workflows/tasks/MarigoldDepth.json | TEMPLATE | templates/depth-marigold.json | MarigoldDepth | Depth maps with Marigold |
+| workflows/tasks/MarigoldNormals.json | TEMPLATE | templates/surface-normals.json | MarigoldNormals | Surface normals - a different output, different pipeline class |
+| workflows/tasks/MetadataEmbed.json | TEMPLATE | templates/embed-metadata.json | MetadataEmbed | Only metadata-embedding demo |
+| workflows/tasks/Segment.json | TEMPLATE | templates/segment.json | Segment | Text-prompted segmentation |
+| workflows/tasks/SegmentAndInpaint.json | TEMPLATE | templates/segment-and-inpaint.json | SegmentAndInpaint | Segment then inpaint the selected region |
+| workflows/tasks/SpandrelUpscale.json | DELETE | — | — | Generate-then-upscale; UpscaleImage covers the task |
+| workflows/tasks/TrimFadeAudio.json | TEMPLATE | templates/audio-trim-fade.json | TrimFadeAudio | Only audio finishing-pass demo |
+| workflows/tasks/UpscaleImage.json | TEMPLATE | templates/upscale-spandrel.json | UpscaleImage | Upscales any existing image, no generation step |
+| workflows/tasks/face-swap.json | COLLAPSE INTO | templates/ip-adapter.json | face_swap | IP-Adapter with a face model - same mechanism |
+| workflows/tasks/image_processors.json | TEMPLATE | templates/image-processors.json | image_processors | Every preprocessor side by side - the preprocessor catalog |
+
+## Judgement calls worth a second look
+
+- **`templates/text-to-image.json` inherits the id `test_job`** from
+  `workflows/sd15.json`. The plan forbids changing an id, so it carries a poor
+  name into a prominent file. Overriding that constraint for this one file is
+  reasonable if you would rather it read `text-to-image`.
+- **The one-step text-to-image models become `models/` entries** - `flux-dev`,
+  `krea2`, `z-image`, `flux2-dev`, `flux-krea`. The collapse rule stops at a
+  pipeline class boundary and these are four different classes, so they cannot
+  merge into the template; as per-checkpoint setups they are model configs.
+- **`gyre/` keeps three templates that still name GYRE's own shots.** They need
+  generalizing as part of Task 3, not just moving.
+- **`Krea2Edit.json` has no description at all** and needs one written before it
+  can pass the template test.
+- **`archive/sdxl.json` graduates but `archive/sdxl_refiner.json` does not** - the
+  two-stage file demonstrates the pattern, the standalone refiner is a subset.

From d5c5e1761c4316063d26425b4bf744b6cb47e4a7 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 14:55:47 -0500
Subject: [PATCH 10/32] Approve the catalog inventory

One approved exception to the keep-ids-verbatim constraint: the
text-to-image template takes the id 'text-to-image' rather than the
'test_job' it would inherit from sd15.json. Costs one workflow's
step-cache entries.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../plans/2026-09-06-catalog-inventory.md          | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/docs/superpowers/plans/2026-09-06-catalog-inventory.md b/docs/superpowers/plans/2026-09-06-catalog-inventory.md
index 1c0b8ff2..1ab18f7c 100644
--- a/docs/superpowers/plans/2026-09-06-catalog-inventory.md
+++ b/docs/superpowers/plans/2026-09-06-catalog-inventory.md
@@ -4,7 +4,7 @@ Verdicts for every workflow under `workflows/`. Produced by Task 2 of the
 [restructure plan](2026-09-06-workflow-catalog-restructure.md); the file lists
 in Tasks 3-5 are this table, filtered by verdict.
 
-Status: AWAITING APPROVAL
+Status: approved 2026-09-06
 
 Counts: COLLAPSE INTO 6, DELETE 42, MODEL 9, TEMPLATE 64 (total 121)
 
@@ -111,7 +111,7 @@ Counts: COLLAPSE INTO 6, DELETE 42, MODEL 9, TEMPLATE 64 (total 121)
 | workflows/minimax/MiniMaxH3SitcomShort.json | TEMPLATE | templates/minimax/dialogue-short.json | MiniMaxH3SitcomShort | Multi-shot cut sequence with per-shot references |
 | workflows/minimax/MiniMaxH3Storyboard.json | TEMPLATE | templates/minimax/storyboard.json | MiniMaxH3Storyboard | Several stills in one generation, each with a stated role |
 | workflows/minimax/MiniMaxMusic.json | TEMPLATE | templates/minimax/music.json | MiniMaxMusic | Audio-only output from a pipeline |
-| workflows/sd15.json | TEMPLATE | templates/text-to-image.json | test_job | Ungated baseline - the no-login quickstart CLAUDE.md points at |
+| workflows/sd15.json | TEMPLATE | templates/text-to-image.json | text-to-image | Ungated baseline - the no-login quickstart CLAUDE.md points at |
 | workflows/tasks/CaptionToImage.json | DELETE | — | — | img2txt2img is the richer caption-then-generate demo |
 | workflows/tasks/DiffusionUpscale.json | DELETE | — | — | Generate-then-upscale is previous_result chaining, shown everywhere |
 | workflows/tasks/DiffusionUpscaleImage.json | TEMPLATE | templates/upscale-diffusion.json | DiffusionUpscaleImage | Upscales any existing image, no generation step |
@@ -134,10 +134,12 @@ Counts: COLLAPSE INTO 6, DELETE 42, MODEL 9, TEMPLATE 64 (total 121)
 
 ## Judgement calls worth a second look
 
-- **`templates/text-to-image.json` inherits the id `test_job`** from
-  `workflows/sd15.json`. The plan forbids changing an id, so it carries a poor
-  name into a prominent file. Overriding that constraint for this one file is
-  reasonable if you would rather it read `text-to-image`.
+- **`templates/text-to-image.json` takes the id `text-to-image`**, not the
+  `test_job` it inherits from `workflows/sd15.json`. This is a deliberate,
+  approved exception to the keep-ids-verbatim constraint (2026-09-06): the cost
+  is one workflow's step-cache entries, and the alternative was carrying a
+  meaningless id onto the most prominent file in the catalog. It is the ONLY id
+  that changes.
 - **The one-step text-to-image models become `models/` entries** - `flux-dev`,
   `krea2`, `z-image`, `flux2-dev`, `flux-krea`. The collapse rule stops at a
   pipeline class boundary and these are four different classes, so they cannot

From 0bef06eaa74ba27f70ea4dd0b9043e6f3b56d6a4 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 15:01:33 -0500
Subject: [PATCH 11/32] Move the feature templates into workflows/templates/

One file per capability, with six checkpoint variations collapsed into
argument sets in each template's description where the pipeline class
matched. Every moved file keeps its id, so the step cache survives.

Two deliberate id deviations, both narrow. The text-to-image template
takes 'text-to-image' rather than sd15.json's 'test_job' (approved).
The three templates replacing GYRE's editing passes are authored fresh
rather than moved and take new ids: the originals referenced
workflows/gyre/assets/, which was never committed, so they could not run
as written and have no cache entries to preserve. The rest of the GYRE
project goes with them - it is a test project's production history, not
a set of examples.

Doc links are updated in a later commit; test_docs_links fails until then.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 dw/workflow_schema.json                       |   4 +
 tests/test_catalog_structure.py               |  43 ++
 workflows/flux/FluxDepth.json                 |  47 --
 workflows/flux/FluxDevTeaCache.json           |  35 --
 workflows/gyre/GyreAssemble.json              | 203 -------
 workflows/gyre/GyreDissolve.json              | 203 -------
 workflows/gyre/GyreFilm.json                  | 552 ------------------
 workflows/gyre/GyreFrames.json                | 191 ------
 workflows/gyre/GyreReshoot.json               | 190 ------
 workflows/gyre/GyreStills.json                | 219 -------
 workflows/gyre/GyreStillsFix.json             |  82 ---
 workflows/gyre/GyreStillsFix2.json            |  50 --
 workflows/gyre/NOTES.md                       | 216 -------
 workflows/gyre/README.md                      |  92 ---
 workflows/lora.json                           |  35 --
 workflows/tasks/ExpandAndGenerate.json        |  43 --
 workflows/tasks/ExpandPrompt.json             |  23 -
 workflows/tasks/ImageToTextVLM.json           |  36 --
 workflows/tasks/face-swap.json                |  36 --
 workflows/templates/assemble-and-score.json   | 128 ++++
 .../attention-processor.json}                 |   0
 .../audio-trim-fade.json}                     |   0
 .../base-and-refiner.json}                    |   0
 .../community-pipeline.json}                  |   0
 .../compose-workflows.json}                   |   0
 .../controlnet-component.json}                |   0
 .../controlnet.json}                          |   4 +-
 .../depth-marigold.json}                      |   0
 .../describe-and-regenerate.json}             |   2 +-
 .../templates/dissolve-between-shots.json     | 130 +++++
 .../embed-metadata.json}                      |   0
 workflows/templates/expand-prompt.json        |  23 +
 .../generate-speech.json}                     |   0
 .../image-edit.json}                          |   5 +-
 .../image-processors.json}                    |   0
 .../image-to-image.json}                      |   0
 .../image-to-text.json}                       |   2 +-
 .../image-variation.json}                     |   0
 .../FluxFill.json => templates/inpaint.json}  |   0
 .../interpolate-frames.json}                  |   0
 .../FluxIP.json => templates/ip-adapter.json} |   4 +-
 .../lora-styles.json}                         |   0
 .../FluxLora.json => templates/lora.json}     |   4 +-
 .../ltx2/chained-segments.json}               |   0
 .../ltx2/enhance-prompt.json}                 |   0
 .../ltx2/extend-clip.json}                    |   0
 .../ltx2/generative-upscale.json}             |   0
 .../ltx2/image-to-video.json}                 |   0
 .../ltx2/keyframes.json}                      |   0
 .../ltx2/text-to-video.json}                  |   0
 .../ltx2/two-stage.json}                      |   0
 .../minimax/chain-matched-and-aligned.json}   |   0
 .../minimax/chain-matched-to-audio.json}      |   0
 .../minimax/chain-video-continuity.json}      |   0
 .../minimax/chained-segments.json}            |   0
 .../minimax/composable-references.json}       |   0
 .../minimax/dialogue-short.json}              |   0
 .../minimax/enhance-prompt-with-image.json}   |   0
 .../minimax/enhance-prompt.json}              |   0
 .../minimax/first-and-last-frame.json}        |   0
 .../minimax/generated-subject-reference.json} |   0
 .../minimax/image-to-video.json}              |   0
 .../minimax/last-frame-only.json}             |   0
 .../minimax/music-video.json}                 |   0
 .../minimax/music.json}                       |   0
 .../minimax/reference-to-video.json}          |   0
 .../minimax/storyboard.json}                  |   0
 .../minimax/video-with-audio.json}            |   0
 .../minimax/voice-timbre-reference.json}      |   0
 .../multi-image-reference.json}               |   0
 .../outpaint.json}                            |   0
 .../prompt-weighting.json}                    |   0
 .../qr_code.json => templates/qr-code.json}   |   0
 workflows/templates/recenter-crop.json        |  71 +++
 .../restore-faces.json}                       |   0
 .../segment-and-inpaint.json}                 |   0
 .../Segment.json => templates/segment.json}   |   0
 .../step-caching.json}                        |   2 +-
 .../sub-workflow.json}                        |   2 +-
 .../surface-normals.json}                     |   0
 .../text-to-image.json}                       |   2 +-
 .../upscale-diffusion.json}                   |   0
 .../upscale-spandrel.json}                    |   0
 83 files changed, 413 insertions(+), 2266 deletions(-)
 create mode 100644 tests/test_catalog_structure.py
 delete mode 100644 workflows/flux/FluxDepth.json
 delete mode 100644 workflows/flux/FluxDevTeaCache.json
 delete mode 100644 workflows/gyre/GyreAssemble.json
 delete mode 100644 workflows/gyre/GyreDissolve.json
 delete mode 100644 workflows/gyre/GyreFilm.json
 delete mode 100644 workflows/gyre/GyreFrames.json
 delete mode 100644 workflows/gyre/GyreReshoot.json
 delete mode 100644 workflows/gyre/GyreStills.json
 delete mode 100644 workflows/gyre/GyreStillsFix.json
 delete mode 100644 workflows/gyre/GyreStillsFix2.json
 delete mode 100644 workflows/gyre/NOTES.md
 delete mode 100644 workflows/gyre/README.md
 delete mode 100644 workflows/lora.json
 delete mode 100644 workflows/tasks/ExpandAndGenerate.json
 delete mode 100644 workflows/tasks/ExpandPrompt.json
 delete mode 100644 workflows/tasks/ImageToTextVLM.json
 delete mode 100644 workflows/tasks/face-swap.json
 create mode 100644 workflows/templates/assemble-and-score.json
 rename workflows/{attention_processors_example.json => templates/attention-processor.json} (100%)
 rename workflows/{tasks/TrimFadeAudio.json => templates/audio-trim-fade.json} (100%)
 rename workflows/{archive/sdxl.json => templates/base-and-refiner.json} (100%)
 rename workflows/{flux/FluxRFInversion.json => templates/community-pipeline.json} (100%)
 rename workflows/{archive/txt2img2vid.json => templates/compose-workflows.json} (100%)
 rename workflows/{controlnet.json => templates/controlnet-component.json} (100%)
 rename workflows/{flux/FluxCanny.json => templates/controlnet.json} (83%)
 rename workflows/{tasks/MarigoldDepth.json => templates/depth-marigold.json} (100%)
 rename workflows/{flux/img2txt2img.json => templates/describe-and-regenerate.json} (97%)
 create mode 100644 workflows/templates/dissolve-between-shots.json
 rename workflows/{tasks/MetadataEmbed.json => templates/embed-metadata.json} (100%)
 create mode 100644 workflows/templates/expand-prompt.json
 rename workflows/{tasks/GenerateSpeech.json => templates/generate-speech.json} (100%)
 rename workflows/{Krea2Edit.json => templates/image-edit.json} (80%)
 rename workflows/{tasks/image_processors.json => templates/image-processors.json} (100%)
 rename workflows/{flux/FluxImg2Img.json => templates/image-to-image.json} (100%)
 rename workflows/{tasks/ImageToText.json => templates/image-to-text.json} (77%)
 rename workflows/{flux/FluxRedux.json => templates/image-variation.json} (100%)
 rename workflows/{flux/FluxFill.json => templates/inpaint.json} (100%)
 rename workflows/{InterpolateFrames.json => templates/interpolate-frames.json} (100%)
 rename workflows/{flux/FluxIP.json => templates/ip-adapter.json} (84%)
 rename workflows/{flux/FluxInContext.json => templates/lora-styles.json} (100%)
 rename workflows/{flux/FluxLora.json => templates/lora.json} (85%)
 rename workflows/{ltx2/LTX2I2VChained.json => templates/ltx2/chained-segments.json} (100%)
 rename workflows/{ltx2/LTX2I2VEnhancePrompt.json => templates/ltx2/enhance-prompt.json} (100%)
 rename workflows/{ltx2/LTX2Extend.json => templates/ltx2/extend-clip.json} (100%)
 rename workflows/{ltx2/LTX2ICLora.json => templates/ltx2/generative-upscale.json} (100%)
 rename workflows/{ltx2/LTX2I2V.json => templates/ltx2/image-to-video.json} (100%)
 rename workflows/{ltx2/LTX2Keyframes.json => templates/ltx2/keyframes.json} (100%)
 rename workflows/{ltx2/LTX2.json => templates/ltx2/text-to-video.json} (100%)
 rename workflows/{ltx2/LTX2TwoStage.json => templates/ltx2/two-stage.json} (100%)
 rename workflows/{minimax/MiniMaxH3Ref2VAChainedAligned.json => templates/minimax/chain-matched-and-aligned.json} (100%)
 rename workflows/{minimax/MiniMaxH3Ref2VAChained.json => templates/minimax/chain-matched-to-audio.json} (100%)
 rename workflows/{minimax/MiniMaxH3Ref2VAChainedVideo.json => templates/minimax/chain-video-continuity.json} (100%)
 rename workflows/{minimax/MiniMaxH3I2VChained.json => templates/minimax/chained-segments.json} (100%)
 rename workflows/{minimax/MiniMaxH3Ref2VAVideo.json => templates/minimax/composable-references.json} (100%)
 rename workflows/{minimax/MiniMaxH3SitcomShort.json => templates/minimax/dialogue-short.json} (100%)
 rename workflows/{minimax/MiniMaxH3I2VEnhancePrompt.json => templates/minimax/enhance-prompt-with-image.json} (100%)
 rename workflows/{minimax/MiniMaxH3EnhancePrompt.json => templates/minimax/enhance-prompt.json} (100%)
 rename workflows/{minimax/MiniMaxH3FL2VA.json => templates/minimax/first-and-last-frame.json} (100%)
 rename workflows/{minimax/MiniMaxH3Ref2VAGeneratedSubject.json => templates/minimax/generated-subject-reference.json} (100%)
 rename workflows/{minimax/MiniMaxH3I2V.json => templates/minimax/image-to-video.json} (100%)
 rename workflows/{minimax/MiniMaxH3L2V.json => templates/minimax/last-frame-only.json} (100%)
 rename workflows/{minimax/MiniMaxH3MusicVideo.json => templates/minimax/music-video.json} (100%)
 rename workflows/{minimax/MiniMaxMusic.json => templates/minimax/music.json} (100%)
 rename workflows/{minimax/MiniMaxH3Ref2VA.json => templates/minimax/reference-to-video.json} (100%)
 rename workflows/{minimax/MiniMaxH3Storyboard.json => templates/minimax/storyboard.json} (100%)
 rename workflows/{minimax/MiniMaxH3.json => templates/minimax/video-with-audio.json} (100%)
 rename workflows/{minimax/MiniMaxH3GeneratedVoice.json => templates/minimax/voice-timbre-reference.json} (100%)
 rename workflows/{flux/Flux2DevImageCombine.json => templates/multi-image-reference.json} (100%)
 rename workflows/{flux/FluxOutpaint.json => templates/outpaint.json} (100%)
 rename workflows/{flux/FluxSchnellWeighted.json => templates/prompt-weighting.json} (100%)
 rename workflows/{archive/qr_code.json => templates/qr-code.json} (100%)
 create mode 100644 workflows/templates/recenter-crop.json
 rename workflows/{tasks/FaceRestore.json => templates/restore-faces.json} (100%)
 rename workflows/{tasks/SegmentAndInpaint.json => templates/segment-and-inpaint.json} (100%)
 rename workflows/{tasks/Segment.json => templates/segment.json} (100%)
 rename workflows/{flux/FluxDevFirstBlockCache.json => templates/step-caching.json} (76%)
 rename workflows/{flux/FluxLogo.json => templates/sub-workflow.json} (95%)
 rename workflows/{tasks/MarigoldNormals.json => templates/surface-normals.json} (100%)
 rename workflows/{sd15.json => templates/text-to-image.json} (97%)
 rename workflows/{tasks/DiffusionUpscaleImage.json => templates/upscale-diffusion.json} (100%)
 rename workflows/{tasks/UpscaleImage.json => templates/upscale-spandrel.json} (100%)

diff --git a/dw/workflow_schema.json b/dw/workflow_schema.json
index c29b9408..0df183a5 100644
--- a/dw/workflow_schema.json
+++ b/dw/workflow_schema.json
@@ -10,6 +10,10 @@
         "description": {
             "type": "string"
         },
+        "configures": {
+            "type": "string",
+            "description": "For a workflow under models/: the templates/ workflow this is a tuned per-checkpoint configuration of, as a catalog name such as 'templates/text-to-image'."
+        },
         "variables": {
             "$ref": "#/$defs/arguments"
         },
diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
new file mode 100644
index 00000000..24aceb3d
--- /dev/null
+++ b/tests/test_catalog_structure.py
@@ -0,0 +1,43 @@
+"""The catalog's two trees, and the invariant each carries.
+
+templates/ teaches a pattern and models/ records a hardware fact. The
+distinction is only useful if it is legible from outside the file, so a
+template must describe itself and a model config must name the template it
+configures.
+"""
+
+import json
+import os
+
+import pytest
+
+from tests.test_examples import REPO_ROOT
+
+TEMPLATES_DIR = os.path.join(REPO_ROOT, "workflows", "templates")
+
+
+def files_under(directory):
+    if not os.path.isdir(directory):
+        return []
+    found = []
+    for root, _, names in os.walk(directory):
+        found.extend(
+            os.path.join(root, name) for name in names if name.endswith(".json")
+        )
+    return sorted(found)
+
+
+def test_there_are_templates():
+    assert files_under(TEMPLATES_DIR)
+
+
+@pytest.mark.parametrize("path", files_under(TEMPLATES_DIR))
+def test_every_template_describes_itself(path):
+    """A template is read before it is run - by a person choosing one and by an
+    agent matching a request's shape. An undescribed template is invisible to
+    both, whatever its filename says."""
+    definition = json.load(open(path, encoding="utf-8"))
+
+    assert definition.get("description", "").strip(), (
+        f"{os.path.relpath(path, REPO_ROOT)} has no description"
+    )
diff --git a/workflows/flux/FluxDepth.json b/workflows/flux/FluxDepth.json
deleted file mode 100644
index e06ba04c..00000000
--- a/workflows/flux/FluxDepth.json
+++ /dev/null
@@ -1,47 +0,0 @@
-{
-    "id": "FluxDepth",
-    "description": "Estimates depth from an input image and generates with FLUX.1 Depth dev guided by it.",
-    "steps": [
-        {
-            "name": "depth",
-            "task": {
-                "command": "depth",
-                "arguments": {
-                    "image": {
-                        "location": "https://pbs.twimg.com/media/GezfaKzaQAEwLJJ?format=jpg&name=medium"
-                    }
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        },
-        {
-            "name": "FluxDepth",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "FluxControlPipeline",
-                    "offload": "sequential"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "black-forest-labs/FLUX.1-Depth-dev",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "control_image": "previous_result:depth",
-                    "prompt": "A Chimpanzee dressed as super man flying over a city",
-                    "height": 1024,
-                    "width": 1024,
-                    "guidance_scale": 10,
-                    "num_inference_steps": 25,
-                    "max_sequence_length": 512
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/flux/FluxDevTeaCache.json b/workflows/flux/FluxDevTeaCache.json
deleted file mode 100644
index 843cca11..00000000
--- a/workflows/flux/FluxDevTeaCache.json
+++ /dev/null
@@ -1,35 +0,0 @@
-{
-    "variables": {
-        "prompt": "A photorealistic image of a red fox sitting in a snowy forest clearing, soft morning light filtering through the trees",
-        "num_inference_steps": 28,
-        "guidance_scale": 3.5
-    },
-    "id": "FluxDevTeaCache",
-    "description": "FLUX.1 dev accelerated with TeaCache.",
-    "steps": [
-        {
-            "name": "txt2img",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "FluxPipeline",
-                    "teacache": {
-                        "rel_l1_thresh": 0.4
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "black-forest-labs/FLUX.1-dev",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "guidance_scale": "variable:guidance_scale"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/gyre/GyreAssemble.json b/workflows/gyre/GyreAssemble.json
deleted file mode 100644
index 2b00c74f..00000000
--- a/workflows/gyre/GyreAssemble.json
+++ /dev/null
@@ -1,203 +0,0 @@
-{
-    "id": "GyreAssemble",
-    "description": "The edit half of GyreFilm.json, run over the nine shots it already wrote. Every shot is stabilized, cut together, and laid under the score mixed over the nine worlds' own sound. Generation is the expensive part and it is already done, so the edit can be re-cut - a different mix balance, a different score - for the cost of the edit alone. Paths here are relative to the working directory, not to this file: the engine only re-roots an argument it loads itself, and these are loaded by the tasks.",
-    "variables": {
-        "score": "workflows/gyre/assets/Gyre-score_choir.10-0.0.wav",
-        "sample_rate": 44100,
-        "fps": 24,
-        "score_gain": 1.0,
-        "world_gain": 1.8,
-        "start_frame": 85,
-        "total_frames": 1116,
-        "shot_1_iris": "workflows/gyre/assets/shots/GyreFilm-shot_1_iris.0-0.0.mp4",
-        "shot_2_fingerprint": "workflows/gyre/assets/shots/GyreFilm-shot_2_fingerprint.1-0.0.mp4",
-        "shot_3_fiddlehead": "workflows/gyre/assets/shots/GyreFilm-shot_3_fiddlehead.2-0.0.mp4",
-        "shot_4_nautilus": "workflows/gyre/assets/shots/GyreFilm-shot_4_nautilus.3-0.0.mp4",
-        "shot_5_web": "workflows/gyre/assets/shots/GyreFilm-shot_5_web.4-0.0.mp4",
-        "shot_6_whirlpool": "workflows/gyre/assets/shots/GyreFilm-shot_6_whirlpool.5-0.0.mp4",
-        "shot_7_hurricane": "workflows/gyre/assets/shots/GyreFilm-shot_7_hurricane.6-0.0.mp4",
-        "shot_8_galaxy": "workflows/gyre/assets/shots/GyreFilm-shot_8_galaxy.7-0.0.mp4",
-        "shot_9_return": "workflows/gyre/assets/shots/GyreFilm-shot_9_return.8-0.0.mp4"
-    },
-    "seed": 11,
-    "steps": [
-        {
-            "name": "hold_1_iris",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_1_iris"
-                }
-            }
-        },
-        {
-            "name": "hold_2_fingerprint",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_2_fingerprint"
-                }
-            }
-        },
-        {
-            "name": "hold_3_fiddlehead",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_3_fiddlehead"
-                }
-            }
-        },
-        {
-            "name": "hold_4_nautilus",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_4_nautilus"
-                }
-            }
-        },
-        {
-            "name": "hold_5_web",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_5_web"
-                }
-            }
-        },
-        {
-            "name": "hold_6_whirlpool",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_6_whirlpool"
-                }
-            }
-        },
-        {
-            "name": "hold_7_hurricane",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_7_hurricane"
-                }
-            }
-        },
-        {
-            "name": "hold_8_galaxy",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_8_galaxy"
-                }
-            }
-        },
-        {
-            "name": "hold_9_return",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_9_return"
-                }
-            }
-        },
-        {
-            "name": "edit",
-            "task": {
-                "command": "concat_videos",
-                "arguments": {
-                    "videos": [
-                        "previous_result:hold_1_iris",
-                        "previous_result:hold_2_fingerprint",
-                        "previous_result:hold_3_fiddlehead",
-                        "previous_result:hold_4_nautilus",
-                        "previous_result:hold_5_web",
-                        "previous_result:hold_6_whirlpool",
-                        "previous_result:hold_7_hurricane",
-                        "previous_result:hold_8_galaxy",
-                        "previous_result:hold_9_return"
-                    ],
-                    "trim_frames": 0,
-                    "seam_fade_ms": 120,
-                    "fps": "variable:fps"
-                }
-            }
-        },
-        {
-            "name": "world",
-            "task": {
-                "command": "resample_audio",
-                "arguments": {
-                    "audio": "previous_result:edit",
-                    "target_sample_rate": "variable:sample_rate"
-                }
-            }
-        },
-        {
-            "name": "soundtrack",
-            "task": {
-                "command": "slice_audio",
-                "arguments": {
-                    "audio": "variable:score",
-                    "start_frame": "variable:start_frame",
-                    "num_frames": "variable:total_frames",
-                    "fps": "variable:fps",
-                    "sample_rate": "variable:sample_rate"
-                }
-            }
-        },
-        {
-            "name": "mixed",
-            "task": {
-                "command": "mix_audio",
-                "arguments": {
-                    "audios": [
-                        "previous_result:soundtrack",
-                        "previous_result:world"
-                    ],
-                    "gains": [
-                        "variable:score_gain",
-                        "variable:world_gain"
-                    ],
-                    "sample_rate": "variable:sample_rate"
-                }
-            }
-        },
-        {
-            "name": "balanced",
-            "task": {
-                "command": "normalize_audio",
-                "arguments": {
-                    "audio": "previous_result:mixed",
-                    "peak_dbfs": -1.0,
-                    "sample_rate": "variable:sample_rate"
-                }
-            }
-        },
-        {
-            "name": "gyre",
-            "task": {
-                "command": "pair_audio",
-                "arguments": {
-                    "video": "previous_result:edit",
-                    "audio": "previous_result:balanced",
-                    "sample_rate": "variable:sample_rate"
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/gyre/GyreDissolve.json b/workflows/gyre/GyreDissolve.json
deleted file mode 100644
index da040fca..00000000
--- a/workflows/gyre/GyreDissolve.json
+++ /dev/null
@@ -1,203 +0,0 @@
-{
-    "id": "GyreDissolve",
-    "description": "GyreAssemble.json with the cuts softened into cross-dissolves. Because the nine spirals are registered on the same centre at the same size, an overlap does not read as a fade between two pictures - the shape stays put and its material transforms through the seam. dissolve_videos consumes one overlap per seam, so the film is 8 x dissolve_frames shorter than the 1116-frame cut and the score slice moves with it: total_frames = 1116 - 8 * dissolve_frames, and start_frame = round((50.05 - total_frames / 24) * 24) so the piece still ends on the score's final chord. Pass all three together when changing the dissolve length, since JSON cannot do the arithmetic itself.",
-    "variables": {
-        "score": "workflows/gyre/assets/Gyre-score_choir.10-0.0.wav",
-        "sample_rate": 44100,
-        "fps": 24,
-        "score_gain": 1.0,
-        "world_gain": 1.8,
-        "start_frame": 133,
-        "total_frames": 1068,
-        "shot_1_iris": "workflows/gyre/assets/shots/GyreFilm-shot_1_iris.0-0.0.mp4",
-        "shot_2_fingerprint": "workflows/gyre/assets/shots/GyreFilm-shot_2_fingerprint.1-0.0.mp4",
-        "shot_3_fiddlehead": "workflows/gyre/assets/shots/GyreFilm-shot_3_fiddlehead.2-0.0.mp4",
-        "shot_4_nautilus": "workflows/gyre/assets/shots/GyreFilm-shot_4_nautilus.3-0.0.mp4",
-        "shot_5_web": "workflows/gyre/assets/shots/GyreFilm-shot_5_web.4-0.0.mp4",
-        "shot_6_whirlpool": "workflows/gyre/assets/shots/GyreFilm-shot_6_whirlpool.5-0.0.mp4",
-        "shot_7_hurricane": "workflows/gyre/assets/shots/GyreFilm-shot_7_hurricane.6-0.0.mp4",
-        "shot_8_galaxy": "workflows/gyre/assets/shots/GyreFilm-shot_8_galaxy.7-0.0.mp4",
-        "shot_9_return": "workflows/gyre/assets/shots/GyreFilm-shot_9_return.8-0.0.mp4",
-        "dissolve_frames": 6
-    },
-    "seed": 11,
-    "steps": [
-        {
-            "name": "hold_1_iris",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_1_iris"
-                }
-            }
-        },
-        {
-            "name": "hold_2_fingerprint",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_2_fingerprint"
-                }
-            }
-        },
-        {
-            "name": "hold_3_fiddlehead",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_3_fiddlehead"
-                }
-            }
-        },
-        {
-            "name": "hold_4_nautilus",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_4_nautilus"
-                }
-            }
-        },
-        {
-            "name": "hold_5_web",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_5_web"
-                }
-            }
-        },
-        {
-            "name": "hold_6_whirlpool",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_6_whirlpool"
-                }
-            }
-        },
-        {
-            "name": "hold_7_hurricane",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_7_hurricane"
-                }
-            }
-        },
-        {
-            "name": "hold_8_galaxy",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_8_galaxy"
-                }
-            }
-        },
-        {
-            "name": "hold_9_return",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "variable:shot_9_return"
-                }
-            }
-        },
-        {
-            "name": "edit",
-            "task": {
-                "command": "dissolve_videos",
-                "arguments": {
-                    "videos": [
-                        "previous_result:hold_1_iris",
-                        "previous_result:hold_2_fingerprint",
-                        "previous_result:hold_3_fiddlehead",
-                        "previous_result:hold_4_nautilus",
-                        "previous_result:hold_5_web",
-                        "previous_result:hold_6_whirlpool",
-                        "previous_result:hold_7_hurricane",
-                        "previous_result:hold_8_galaxy",
-                        "previous_result:hold_9_return"
-                    ],
-                    "dissolve_frames": "variable:dissolve_frames",
-                    "fps": "variable:fps"
-                }
-            }
-        },
-        {
-            "name": "world",
-            "task": {
-                "command": "resample_audio",
-                "arguments": {
-                    "audio": "previous_result:edit",
-                    "target_sample_rate": "variable:sample_rate"
-                }
-            }
-        },
-        {
-            "name": "soundtrack",
-            "task": {
-                "command": "slice_audio",
-                "arguments": {
-                    "audio": "variable:score",
-                    "start_frame": "variable:start_frame",
-                    "num_frames": "variable:total_frames",
-                    "fps": "variable:fps",
-                    "sample_rate": "variable:sample_rate"
-                }
-            }
-        },
-        {
-            "name": "mixed",
-            "task": {
-                "command": "mix_audio",
-                "arguments": {
-                    "audios": [
-                        "previous_result:soundtrack",
-                        "previous_result:world"
-                    ],
-                    "gains": [
-                        "variable:score_gain",
-                        "variable:world_gain"
-                    ],
-                    "sample_rate": "variable:sample_rate"
-                }
-            }
-        },
-        {
-            "name": "balanced",
-            "task": {
-                "command": "normalize_audio",
-                "arguments": {
-                    "audio": "previous_result:mixed",
-                    "peak_dbfs": -1.0,
-                    "sample_rate": "variable:sample_rate"
-                }
-            }
-        },
-        {
-            "name": "gyre",
-            "task": {
-                "command": "pair_audio",
-                "arguments": {
-                    "video": "previous_result:edit",
-                    "audio": "previous_result:balanced",
-                    "sample_rate": "variable:sample_rate"
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/gyre/GyreFilm.json b/workflows/gyre/GyreFilm.json
deleted file mode 100644
index d25c000b..00000000
--- a/workflows/gyre/GyreFilm.json
+++ /dev/null
@@ -1,552 +0,0 @@
-{
-    "id": "GyreFilm",
-    "description": "Pass 3 of GYRE - 'one shape, nine worlds'. Every registered keyframe from GyreFrames.json becomes the pinned first frame of a 124-frame MiniMax-H3 shot, each generated fresh from its own still so no shot inherits another's drift. Every shot rolls clockwise at the same slow rate about the same centre, so the turn runs unbroken across all nine hard cuts while the world underneath it is replaced. Every shot is then run through stabilize_video, which removes the framing drift H3 accumulates over 124 frames - about 38px on a 704px frame, enough to make the spiral visibly jump back to centre at each cut. H3's own soundtrack for each world is kept, resampled from 32 kHz, and mixed under the unbroken Music3 score, which is sliced to end on its final chord: 9 x 124 frames at 24 fps against a 1116-frame slice of the track.",
-    "variables": {
-        "score": {
-            "location": "assets/Gyre-score_choir.10-0.0.wav"
-        },
-        "sample_rate": 44100,
-        "h3_sample_rate": 32000,
-        "num_frames": 124,
-        "fps": 24,
-        "width": 704,
-        "height": 704,
-        "num_inference_steps": 9,
-        "score_gain": 1.0,
-        "world_gain": 1.8,
-        "weights_dtype": "{int4}",
-        "lora_scale": 1.0,
-        "lora_model_name": "lightx2v/Minimax-h3-Turbo",
-        "lora_weight_name": "minimax_h3_fl2v_turbo_8step_v1.0_bf16.safetensors",
-        "lora_adapter_name": "turbo",
-        "shot_1_iris": "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\nintegrated_multimodal_description: [Shot 1] Cinematic, live-action extreme macro photography. The shot opens exactly on <Picture 1>: a single human iris filling the centre of the frame, deep amber and hazel fibres radiating outward from a perfectly round black pupil at the exact centre, a small bright catchlight above the pupil, the wet lower lid and dark lashes across the bottom of frame. The pupil contracts smoothly and slowly, drawing the amber fibres inward with it, then eases open again; the fine crypts and folds of the iris shift as it moves, a film of moisture creeps across the wet surface and the catchlight trembles, and once the eye blinks, the lashes sweeping down and up quickly, leaving the surface wetter and brighter than before. The camera holds the centre of the spiral exactly at the centre of frame and rolls clockwise with small amplitude at slow speed throughout.\n\noverall_soundscape: Almost nothing: a very close, dry, intimate room tone, one soft wet blink, and the faint sound of a slow human breath near the microphone.\n\nnon_diegetic_music: None.",
-        "frame_1_iris": {
-            "location": "assets/frame_1_iris.jpg"
-        },
-        "shot_2_fingerprint": "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\nintegrated_multimodal_description: [Shot 1] Cinematic, live-action extreme macro photography. The shot opens exactly on <Picture 1>: the whorl of a human fingertip filling the frame, a single continuous ridge line winding inward turn after turn to one point at the exact centre, the skin wet and lit from a low angle so every ridge catches a thin bright highlight while the valleys stay black. The pad presses very slightly closer, so the ridges flatten and spread outward from the centre and then relax back, beads of moisture squeeze along the valleys and creep between the ridges, and a faint tremor runs through the skin as it holds the pressure. The camera holds the centre of the spiral exactly at the centre of frame and rolls clockwise with small amplitude at slow speed throughout.\n\noverall_soundscape: An extremely close, dry contact sound: the faint squeak and tack of wet skin pressing and shifting against glass, and a slow held breath somewhere behind it.\n\nnon_diegetic_music: None.",
-        "frame_2_fingerprint": {
-            "location": "assets/frame_2_fingerprint.jpg"
-        },
-        "shot_3_fiddlehead": "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\nintegrated_multimodal_description: [Shot 1] Cinematic, live-action macro nature photography. The shot opens exactly on <Picture 1>: a single fern fiddlehead, a tight bright green coil furled around its exact centre and held square-on to the camera, fine silver hairs standing along the stem, beads of dew caught on the coil, a very dark blurred forest behind. The coil unfurls slowly, its outermost turn loosening and lifting away from the centre while the small furled leaflets along its length open one after another, dew beads sliding down the hairs and falling away out of frame, and the whole frond swaying very slightly in a breath of moving air. The camera holds the centre of the spiral exactly at the centre of frame and rolls clockwise with small amplitude at slow speed throughout.\n\noverall_soundscape: A close, damp woodland: a soft breath of wind moving leaves, one dew drop falling onto a leaf below, and small birds calling far off among the trees.\n\nnon_diegetic_music: None.",
-        "frame_3_fiddlehead": {
-            "location": "assets/frame_3_fiddlehead.jpg"
-        },
-        "shot_4_nautilus": "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\nintegrated_multimodal_description: [Shot 1] Cinematic, live-action nature photography. The shot opens exactly on <Picture 1>: a cross-sectioned nautilus shell lying on black volcanic sand, its chambers opening out from the exact centre of the frame in a perfect logarithmic curve, the mother-of-pearl interior glowing pale pink and cream, the dark speckled sand lying evenly all around it. The shell rests completely still and the sand around it stays black, dry and undisturbed for the whole shot. The only thing that changes is the light on the nacre: the iridescence travels slowly around the spiral, bands of pink, green and gold sliding along the chambers from the outer whorl toward the tight centre, brightening as they follow the inner curve and fading as they pass, while the individual wet grains of black sand glitter one by one and go dark again as the light moves over them. The camera holds the centre of the spiral exactly at the centre of frame and rolls clockwise with small amplitude at slow speed throughout.\n\noverall_soundscape: A wide, quiet beach heard from far above the tideline: a low distant surf rising and falling, a thin dry wind moving over sand, and one gull calling a long way off.\n\nnon_diegetic_music: None.",
-        "frame_4_nautilus": {
-            "location": "assets/frame_4_nautilus.jpg"
-        },
-        "shot_5_web": "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\nintegrated_multimodal_description: [Shot 1] Cinematic, live-action macro nature photography. The shot opens exactly on <Picture 1>: an orb spider's web strung with dew against pure black, the spiral of silk winding out from its exact centre at the middle of the frame, every droplet a tiny bright bead threaded on the line, straight radial guy lines running away into the darkness. The whole web trembles and springs in a light breath of air, the spiral flexing and turning slightly as it moves, the droplets shivering on the threads and one or two breaking loose and falling away down the frame, the silk flaring bright where it catches the light and going dark again as it swings. The camera holds the centre of the spiral exactly at the centre of frame and rolls clockwise with small amplitude at slow speed throughout.\n\noverall_soundscape: A still, cold night in the open: a very faint breath of wind, the tiny tick of a droplet falling through leaves somewhere below, and far-off crickets.\n\nnon_diegetic_music: None.",
-        "frame_5_web": {
-            "location": "assets/frame_5_web.jpg"
-        },
-        "shot_6_whirlpool": "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\nintegrated_multimodal_description: [Shot 1] Cinematic, live-action nature photography. The shot opens exactly on <Picture 1>: a whirlpool turning in dark peat-brown river water, long lines of white foam drawn into a tightening spiral around a black funnel at the exact centre of the frame, the surface glassy and stretched where it bends down into the throat. The water turns steadily and continuously clockwise, the foam lines stretching and thinning as they are drawn inward and vanish down the funnel, the glassy throat of the vortex breathing wider and narrower, and a single yellow leaf in the outermost turn carried slowly around and inward. The camera holds the centre of the spiral exactly at the centre of frame and rolls clockwise with small amplitude at slow speed throughout.\n\noverall_soundscape: The full close sound of moving water: a deep steady pull and gurgle at the throat of the vortex, water sliding and slapping around it, and a river running on beyond.\n\nnon_diegetic_music: None.",
-        "frame_6_whirlpool": {
-            "location": "assets/frame_6_whirlpool.jpg"
-        },
-        "shot_7_hurricane": "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\nintegrated_multimodal_description: [Shot 1] Cinematic, live-action satellite photography from orbit. The shot opens exactly on <Picture 1>: a hurricane seen from directly above, its small clear round eye at the exact centre of the frame, immense white cloud bands spiralling around it, deep blue-black ocean showing beyond the outer arms. The whole storm rotates slowly and steadily clockwise, the cloud bands winding inward toward the eye, towers of cloud boiling upward along the arms and throwing moving shadows across the cloud deck below, the eye wall staying crisp and the eye itself holding open and clear the whole time. The camera holds the centre of the spiral exactly at the centre of frame and rolls clockwise with small amplitude at slow speed throughout.\n\noverall_soundscape: Silence, or as near to it as orbit gets: a vast low airless hum, a faint electrical hiss, and nothing else at all.\n\nnon_diegetic_music: None.",
-        "frame_7_hurricane": {
-            "location": "assets/frame_7_hurricane.jpg"
-        },
-        "shot_8_galaxy": "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\nintegrated_multimodal_description: [Shot 1] Cinematic, live-action deep-space photography. The shot opens exactly on <Picture 1>: a grand-design spiral galaxy seen exactly face-on, a blazing gold core at the exact centre of the frame, two great arms of blue-white star formation winding outward through lanes of dark dust, pink nebulae strung along the arms, deep black space all around. The galaxy turns very slowly clockwise, the arms trailing as they sweep, the gold core pulsing faintly brighter and dimmer, the dark dust lanes drifting slowly across the bright face behind them, and individual foreground stars twinkling sharply against the black. The camera holds the centre of the spiral exactly at the centre of frame and rolls clockwise with small amplitude at slow speed throughout.\n\noverall_soundscape: Deep space: a vast, almost subsonic hum with a faint high shimmer moving over it, and nothing else.\n\nnon_diegetic_music: None.",
-        "frame_8_galaxy": {
-            "location": "assets/frame_8_galaxy.jpg"
-        },
-        "shot_9_return": "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\nintegrated_multimodal_description: [Shot 1] Cinematic, live-action extreme macro photography. The shot opens exactly on <Picture 1>: a single human eye in near-total darkness, and mirrored across the wet glassy curve of it the bright reflection of a great spiral galaxy, its gold core sitting exactly over the round black pupil at the centre of the frame and its blue-white arms curving out across the amber fibres of the iris. The reflected galaxy turns slowly clockwise across the wet surface of the eye while the iris fibres beneath it shift and the pupil contracts a little, the moving light sliding over the curve of the cornea; at the very end the eye blinks once, slowly, and when the lashes lift the galaxy is still reflected there. The camera holds the centre of the spiral exactly at the centre of frame and rolls clockwise with small amplitude at slow speed throughout.\n\noverall_soundscape: Nearly silent and very close: one slow soft blink, a single quiet human breath, and behind them the faintest trace of the same deep hum.\n\nnon_diegetic_music: None.",
-        "frame_9_return": {
-            "location": "assets/frame_9_return.jpg"
-        }
-    },
-    "seed": 11,
-    "steps": [
-        {
-            "name": "shot_1_iris",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "ModularPipeline",
-                    "pre_load_modules": [
-                        "sdnq"
-                    ],
-                    "load_components": {
-                        "dtype": "torch.bfloat16",
-                        "quantization_config": {
-                            "transformer": {
-                                "configuration": {
-                                    "config_type": "sdnq.SDNQConfig"
-                                },
-                                "arguments": {
-                                    "weights_dtype": "variable:weights_dtype",
-                                    "quantization_device": "cuda",
-                                    "return_device": "cpu",
-                                    "use_quantized_matmul": true,
-                                    "dequantize_fp32": false,
-                                    "modules_to_not_convert": [
-                                        "proj_in",
-                                        "audio_proj_in",
-                                        "context_embedder",
-                                        "time_embedder",
-                                        "time_proj",
-                                        "token_refiner",
-                                        "norm_out",
-                                        "proj_out",
-                                        "audio_proj_out"
-                                    ]
-                                }
-                            },
-                            "text_encoder": {
-                                "configuration": {
-                                    "config_type": "sdnq.SDNQConfig"
-                                },
-                                "arguments": {
-                                    "weights_dtype": "variable:weights_dtype",
-                                    "quantization_device": "cuda",
-                                    "return_device": "cpu",
-                                    "dequantize_fp32": false,
-                                    "modules_to_not_convert": [
-                                        ".model.visual",
-                                        "lm_head"
-                                    ]
-                                }
-                            },
-                            "vae": {
-                                "configuration": {
-                                    "config_type": "sdnq.SDNQConfig"
-                                },
-                                "arguments": {
-                                    "weights_dtype": "{int8}",
-                                    "quant_conv": true,
-                                    "use_quantized_matmul_conv": true,
-                                    "quantization_device": "cuda",
-                                    "return_device": "cpu",
-                                    "dequantize_fp32": false
-                                }
-                            }
-                        }
-                    },
-                    "components": {
-                        "transformer": {
-                            "group_offload": {
-                                "offload_type": "block_level",
-                                "num_blocks_per_group": 2,
-                                "use_stream": true,
-                                "record_stream": true,
-                                "low_cpu_mem_usage": true
-                            }
-                        },
-                        "text_encoder": {
-                            "remove_modules": [
-                                "lm_head"
-                            ]
-                        },
-                        "text_encoder.model": {
-                            "truncate_layers": {
-                                "language_model.layers": 51
-                            },
-                            "group_offload": {
-                                "offload_type": "leaf_level"
-                            }
-                        },
-                        "vae": {
-                            "device": "cuda",
-                            "residency": "on_demand"
-                        },
-                        "audio_vae": {
-                            "device": "cuda",
-                            "residency": "on_demand"
-                        }
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "MiniMaxAI/MiniMax-H3",
-                    "workflow": "fl2va"
-                },
-                "loras": [
-                    {
-                        "model_name": "variable:lora_model_name",
-                        "weight_name": "variable:lora_weight_name",
-                        "adapter_name": "variable:lora_adapter_name",
-                        "scale": "variable:lora_scale"
-                    }
-                ],
-                "arguments": {
-                    "prompt": "variable:shot_1_iris",
-                    "image": "variable:frame_1_iris",
-                    "num_frames": "variable:num_frames",
-                    "width": "variable:width",
-                    "height": "variable:height",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "output": [
-                        "videos",
-                        "audio",
-                        "sampling_rate"
-                    ]
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        },
-        {
-            "name": "shot_2_fingerprint",
-            "pipeline_reference": {
-                "reference_name": "shot_1_iris",
-                "arguments": {
-                    "prompt": "variable:shot_2_fingerprint",
-                    "image": "variable:frame_2_fingerprint",
-                    "num_frames": "variable:num_frames",
-                    "width": "variable:width",
-                    "height": "variable:height",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "output": [
-                        "videos",
-                        "audio",
-                        "sampling_rate"
-                    ]
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        },
-        {
-            "name": "shot_3_fiddlehead",
-            "pipeline_reference": {
-                "reference_name": "shot_1_iris",
-                "arguments": {
-                    "prompt": "variable:shot_3_fiddlehead",
-                    "image": "variable:frame_3_fiddlehead",
-                    "num_frames": "variable:num_frames",
-                    "width": "variable:width",
-                    "height": "variable:height",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "output": [
-                        "videos",
-                        "audio",
-                        "sampling_rate"
-                    ]
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        },
-        {
-            "name": "shot_4_nautilus",
-            "pipeline_reference": {
-                "reference_name": "shot_1_iris",
-                "arguments": {
-                    "prompt": "variable:shot_4_nautilus",
-                    "image": "variable:frame_4_nautilus",
-                    "num_frames": "variable:num_frames",
-                    "width": "variable:width",
-                    "height": "variable:height",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "output": [
-                        "videos",
-                        "audio",
-                        "sampling_rate"
-                    ]
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        },
-        {
-            "name": "shot_5_web",
-            "pipeline_reference": {
-                "reference_name": "shot_1_iris",
-                "arguments": {
-                    "prompt": "variable:shot_5_web",
-                    "image": "variable:frame_5_web",
-                    "num_frames": "variable:num_frames",
-                    "width": "variable:width",
-                    "height": "variable:height",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "output": [
-                        "videos",
-                        "audio",
-                        "sampling_rate"
-                    ]
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        },
-        {
-            "name": "shot_6_whirlpool",
-            "pipeline_reference": {
-                "reference_name": "shot_1_iris",
-                "arguments": {
-                    "prompt": "variable:shot_6_whirlpool",
-                    "image": "variable:frame_6_whirlpool",
-                    "num_frames": "variable:num_frames",
-                    "width": "variable:width",
-                    "height": "variable:height",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "output": [
-                        "videos",
-                        "audio",
-                        "sampling_rate"
-                    ]
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        },
-        {
-            "name": "shot_7_hurricane",
-            "pipeline_reference": {
-                "reference_name": "shot_1_iris",
-                "arguments": {
-                    "prompt": "variable:shot_7_hurricane",
-                    "image": "variable:frame_7_hurricane",
-                    "num_frames": "variable:num_frames",
-                    "width": "variable:width",
-                    "height": "variable:height",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "output": [
-                        "videos",
-                        "audio",
-                        "sampling_rate"
-                    ]
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        },
-        {
-            "name": "shot_8_galaxy",
-            "pipeline_reference": {
-                "reference_name": "shot_1_iris",
-                "arguments": {
-                    "prompt": "variable:shot_8_galaxy",
-                    "image": "variable:frame_8_galaxy",
-                    "num_frames": "variable:num_frames",
-                    "width": "variable:width",
-                    "height": "variable:height",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "output": [
-                        "videos",
-                        "audio",
-                        "sampling_rate"
-                    ]
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        },
-        {
-            "name": "shot_9_return",
-            "pipeline_reference": {
-                "reference_name": "shot_1_iris",
-                "arguments": {
-                    "prompt": "variable:shot_9_return",
-                    "image": "variable:frame_9_return",
-                    "num_frames": "variable:num_frames",
-                    "width": "variable:width",
-                    "height": "variable:height",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "output": [
-                        "videos",
-                        "audio",
-                        "sampling_rate"
-                    ]
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        },
-        {
-            "name": "hold_1_iris",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "previous_result:shot_1_iris"
-                }
-            }
-        },
-        {
-            "name": "hold_2_fingerprint",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "previous_result:shot_2_fingerprint"
-                }
-            }
-        },
-        {
-            "name": "hold_3_fiddlehead",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "previous_result:shot_3_fiddlehead"
-                }
-            }
-        },
-        {
-            "name": "hold_4_nautilus",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "previous_result:shot_4_nautilus"
-                }
-            }
-        },
-        {
-            "name": "hold_5_web",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "previous_result:shot_5_web"
-                }
-            }
-        },
-        {
-            "name": "hold_6_whirlpool",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "previous_result:shot_6_whirlpool"
-                }
-            }
-        },
-        {
-            "name": "hold_7_hurricane",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "previous_result:shot_7_hurricane"
-                }
-            }
-        },
-        {
-            "name": "hold_8_galaxy",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "previous_result:shot_8_galaxy"
-                }
-            }
-        },
-        {
-            "name": "hold_9_return",
-            "task": {
-                "command": "stabilize_video",
-                "arguments": {
-                    "smooth": 0,
-                    "clip": "previous_result:shot_9_return"
-                }
-            }
-        },
-        {
-            "name": "edit",
-            "task": {
-                "command": "concat_videos",
-                "arguments": {
-                    "videos": [
-                        "previous_result:hold_1_iris",
-                        "previous_result:hold_2_fingerprint",
-                        "previous_result:hold_3_fiddlehead",
-                        "previous_result:hold_4_nautilus",
-                        "previous_result:hold_5_web",
-                        "previous_result:hold_6_whirlpool",
-                        "previous_result:hold_7_hurricane",
-                        "previous_result:hold_8_galaxy",
-                        "previous_result:hold_9_return"
-                    ],
-                    "trim_frames": 0,
-                    "seam_fade_ms": 120,
-                    "fps": "variable:fps"
-                }
-            }
-        },
-        {
-            "name": "world",
-            "task": {
-                "command": "resample_audio",
-                "arguments": {
-                    "audio": "previous_result:edit",
-                    "target_sample_rate": "variable:sample_rate"
-                }
-            }
-        },
-        {
-            "name": "soundtrack",
-            "task": {
-                "command": "slice_audio",
-                "arguments": {
-                    "audio": "variable:score",
-                    "start_frame": 85,
-                    "num_frames": 1116,
-                    "fps": "variable:fps",
-                    "sample_rate": "variable:sample_rate"
-                }
-            }
-        },
-        {
-            "name": "mixed",
-            "task": {
-                "command": "mix_audio",
-                "arguments": {
-                    "audios": [
-                        "previous_result:soundtrack",
-                        "previous_result:world"
-                    ],
-                    "gains": [
-                        "variable:score_gain",
-                        "variable:world_gain"
-                    ],
-                    "sample_rate": "variable:sample_rate"
-                }
-            }
-        },
-        {
-            "name": "balanced",
-            "task": {
-                "command": "normalize_audio",
-                "arguments": {
-                    "audio": "previous_result:mixed",
-                    "peak_dbfs": -1.0,
-                    "sample_rate": "variable:sample_rate"
-                }
-            }
-        },
-        {
-            "name": "gyre",
-            "task": {
-                "command": "pair_audio",
-                "arguments": {
-                    "video": "previous_result:edit",
-                    "audio": "previous_result:balanced",
-                    "sample_rate": "variable:sample_rate"
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/gyre/GyreFrames.json b/workflows/gyre/GyreFrames.json
deleted file mode 100644
index bbc903e5..00000000
--- a/workflows/gyre/GyreFrames.json
+++ /dev/null
@@ -1,191 +0,0 @@
-{
-    "id": "GyreFrames",
-    "description": "Pass 2 of GYRE - registration. Each source still is re-framed by recenter_crop around its own spiral's centre, at a crop chosen so every bounded subject lands at the same size in the 704x704 frame. Nothing here is generated; this pass only decides where each picture is looked at from. It is what makes the hard cuts in GyreFilm.json land in register, so that the shape appears to survive while the world under it is replaced.",
-    "variables": {
-        "width": 704,
-        "height": 704,
-        "src_1_iris": {
-            "location": "assets/src_1_iris.jpg"
-        },
-        "src_2_fingerprint": {
-            "location": "assets/src_2_fingerprint.jpg"
-        },
-        "src_3_fiddlehead": {
-            "location": "assets/src_3_fiddlehead.jpg"
-        },
-        "src_4_nautilus": {
-            "location": "assets/src_4_nautilus.jpg"
-        },
-        "src_5_web": {
-            "location": "assets/src_5_web.jpg"
-        },
-        "src_6_whirlpool": {
-            "location": "assets/src_6_whirlpool.jpg"
-        },
-        "src_7_hurricane": {
-            "location": "assets/src_7_hurricane.jpg"
-        },
-        "src_8_galaxy": {
-            "location": "assets/src_8_galaxy.jpg"
-        },
-        "src_9_return": {
-            "location": "assets/src_9_return.jpg"
-        }
-    },
-    "steps": [
-        {
-            "name": "frame_1_iris",
-            "task": {
-                "command": "recenter_crop",
-                "arguments": {
-                    "image": "variable:src_1_iris",
-                    "center_x": 0.4892,
-                    "center_y": 0.4592,
-                    "crop": 0.83,
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg"
-            }
-        },
-        {
-            "name": "frame_2_fingerprint",
-            "task": {
-                "command": "recenter_crop",
-                "arguments": {
-                    "image": "variable:src_2_fingerprint",
-                    "center_x": 0.495,
-                    "center_y": 0.4825,
-                    "crop": 0.55,
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg"
-            }
-        },
-        {
-            "name": "frame_3_fiddlehead",
-            "task": {
-                "command": "recenter_crop",
-                "arguments": {
-                    "image": "variable:src_3_fiddlehead",
-                    "center_x": 0.5508,
-                    "center_y": 0.3652,
-                    "crop": 0.52,
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg"
-            }
-        },
-        {
-            "name": "frame_4_nautilus",
-            "task": {
-                "command": "recenter_crop",
-                "arguments": {
-                    "image": "variable:src_4_nautilus",
-                    "center_x": 0.5615,
-                    "center_y": 0.4887,
-                    "crop": 0.99,
-                    "width": "variable:width",
-                    "height": "variable:height",
-                    "fill": "symmetric"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg"
-            }
-        },
-        {
-            "name": "frame_5_web",
-            "task": {
-                "command": "recenter_crop",
-                "arguments": {
-                    "image": "variable:src_5_web",
-                    "center_x": 0.5,
-                    "center_y": 0.4888,
-                    "crop": 0.76,
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg"
-            }
-        },
-        {
-            "name": "frame_6_whirlpool",
-            "task": {
-                "command": "recenter_crop",
-                "arguments": {
-                    "image": "variable:src_6_whirlpool",
-                    "center_x": 0.557,
-                    "center_y": 0.509,
-                    "crop": 0.8,
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg"
-            }
-        },
-        {
-            "name": "frame_7_hurricane",
-            "task": {
-                "command": "recenter_crop",
-                "arguments": {
-                    "image": "variable:src_7_hurricane",
-                    "center_x": 0.5,
-                    "center_y": 0.505,
-                    "crop": 0.95,
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg"
-            }
-        },
-        {
-            "name": "frame_8_galaxy",
-            "task": {
-                "command": "recenter_crop",
-                "arguments": {
-                    "image": "variable:src_8_galaxy",
-                    "center_x": 0.5095,
-                    "center_y": 0.563,
-                    "crop": 0.9,
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg"
-            }
-        },
-        {
-            "name": "frame_9_return",
-            "task": {
-                "command": "recenter_crop",
-                "arguments": {
-                    "image": "variable:src_9_return",
-                    "center_x": 0.505,
-                    "center_y": 0.4786,
-                    "crop": 0.64,
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg"
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/gyre/GyreReshoot.json b/workflows/gyre/GyreReshoot.json
deleted file mode 100644
index 81b023f0..00000000
--- a/workflows/gyre/GyreReshoot.json
+++ /dev/null
@@ -1,190 +0,0 @@
-{
-    "id": "GyreReshoot",
-    "description": "Re-shoots one GYRE shot on its own. Shot 4 asked H3 for too much change - a sheet of seawater flooding in over the sand - and it dissolved the black sand into a grey wash with blob artifacts by mid-shot. The rewritten prompt holds the scene still and moves only the light. Point it at any shot by editing which step is kept.",
-    "variables": {
-        "score": {
-            "location": "assets/Gyre-score_choir.10-0.0.wav"
-        },
-        "sample_rate": 44100,
-        "h3_sample_rate": 32000,
-        "num_frames": 124,
-        "fps": 24,
-        "width": 704,
-        "height": 704,
-        "num_inference_steps": 9,
-        "score_gain": 1.0,
-        "world_gain": 0.55,
-        "weights_dtype": "{int4}",
-        "lora_scale": 1.0,
-        "lora_model_name": "lightx2v/Minimax-h3-Turbo",
-        "lora_weight_name": "minimax_h3_fl2v_turbo_8step_v1.0_bf16.safetensors",
-        "lora_adapter_name": "turbo",
-        "shot_1_iris": "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\nintegrated_multimodal_description: [Shot 1] Cinematic, live-action extreme macro photography. The shot opens exactly on <Picture 1>: a single human iris filling the centre of the frame, deep amber and hazel fibres radiating outward from a perfectly round black pupil at the exact centre, a small bright catchlight above the pupil, the wet lower lid and dark lashes across the bottom of frame. The pupil contracts smoothly and slowly, drawing the amber fibres inward with it, then eases open again; the fine crypts and folds of the iris shift as it moves, a film of moisture creeps across the wet surface and the catchlight trembles, and once the eye blinks, the lashes sweeping down and up quickly, leaving the surface wetter and brighter than before. The camera holds the centre of the spiral exactly at the centre of frame and rolls clockwise with small amplitude at slow speed throughout.\n\noverall_soundscape: Almost nothing: a very close, dry, intimate room tone, one soft wet blink, and the faint sound of a slow human breath near the microphone.\n\nnon_diegetic_music: None.",
-        "frame_1_iris": {
-            "location": "assets/frame_1_iris.jpg"
-        },
-        "shot_2_fingerprint": "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\nintegrated_multimodal_description: [Shot 1] Cinematic, live-action extreme macro photography. The shot opens exactly on <Picture 1>: the whorl of a human fingertip filling the frame, a single continuous ridge line winding inward turn after turn to one point at the exact centre, the skin wet and lit from a low angle so every ridge catches a thin bright highlight while the valleys stay black. The pad presses very slightly closer, so the ridges flatten and spread outward from the centre and then relax back, beads of moisture squeeze along the valleys and creep between the ridges, and a faint tremor runs through the skin as it holds the pressure. The camera holds the centre of the spiral exactly at the centre of frame and rolls clockwise with small amplitude at slow speed throughout.\n\noverall_soundscape: An extremely close, dry contact sound: the faint squeak and tack of wet skin pressing and shifting against glass, and a slow held breath somewhere behind it.\n\nnon_diegetic_music: None.",
-        "frame_2_fingerprint": {
-            "location": "assets/frame_2_fingerprint.jpg"
-        },
-        "shot_3_fiddlehead": "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\nintegrated_multimodal_description: [Shot 1] Cinematic, live-action macro nature photography. The shot opens exactly on <Picture 1>: a single fern fiddlehead, a tight bright green coil furled around its exact centre and held square-on to the camera, fine silver hairs standing along the stem, beads of dew caught on the coil, a very dark blurred forest behind. The coil unfurls slowly, its outermost turn loosening and lifting away from the centre while the small furled leaflets along its length open one after another, dew beads sliding down the hairs and falling away out of frame, and the whole frond swaying very slightly in a breath of moving air. The camera holds the centre of the spiral exactly at the centre of frame and rolls clockwise with small amplitude at slow speed throughout.\n\noverall_soundscape: A close, damp woodland: a soft breath of wind moving leaves, one dew drop falling onto a leaf below, and small birds calling far off among the trees.\n\nnon_diegetic_music: None.",
-        "frame_3_fiddlehead": {
-            "location": "assets/frame_3_fiddlehead.jpg"
-        },
-        "shot_4_nautilus": "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\nintegrated_multimodal_description: [Shot 1] Cinematic, live-action nature photography. The shot opens exactly on <Picture 1>: a cross-sectioned nautilus shell lying on black volcanic sand, its chambers opening out from the exact centre of the frame in a perfect logarithmic curve, the mother-of-pearl interior glowing pale pink and cream, the dark speckled sand lying evenly all around it. The shell rests completely still and the sand around it stays black, dry and undisturbed for the whole shot. The only thing that changes is the light on the nacre: the iridescence travels slowly around the spiral, bands of pink, green and gold sliding along the chambers from the outer whorl toward the tight centre, brightening as they follow the inner curve and fading as they pass, while the individual wet grains of black sand glitter one by one and go dark again as the light moves over them. The camera holds the centre of the spiral exactly at the centre of frame and rolls clockwise with small amplitude at slow speed throughout.\n\noverall_soundscape: A wide, quiet beach heard from far above the tideline: a low distant surf rising and falling, a thin dry wind moving over sand, and one gull calling a long way off.\n\nnon_diegetic_music: None.",
-        "frame_4_nautilus": {
-            "location": "assets/frame_4_nautilus.jpg"
-        },
-        "shot_5_web": "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\nintegrated_multimodal_description: [Shot 1] Cinematic, live-action macro nature photography. The shot opens exactly on <Picture 1>: an orb spider's web strung with dew against pure black, the spiral of silk winding out from its exact centre at the middle of the frame, every droplet a tiny bright bead threaded on the line, straight radial guy lines running away into the darkness. The whole web trembles and springs in a light breath of air, the spiral flexing and turning slightly as it moves, the droplets shivering on the threads and one or two breaking loose and falling away down the frame, the silk flaring bright where it catches the light and going dark again as it swings. The camera holds the centre of the spiral exactly at the centre of frame and rolls clockwise with small amplitude at slow speed throughout.\n\noverall_soundscape: A still, cold night in the open: a very faint breath of wind, the tiny tick of a droplet falling through leaves somewhere below, and far-off crickets.\n\nnon_diegetic_music: None.",
-        "frame_5_web": {
-            "location": "assets/frame_5_web.jpg"
-        },
-        "shot_6_whirlpool": "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\nintegrated_multimodal_description: [Shot 1] Cinematic, live-action nature photography. The shot opens exactly on <Picture 1>: a whirlpool turning in dark peat-brown river water, long lines of white foam drawn into a tightening spiral around a black funnel at the exact centre of the frame, the surface glassy and stretched where it bends down into the throat. The water turns steadily and continuously clockwise, the foam lines stretching and thinning as they are drawn inward and vanish down the funnel, the glassy throat of the vortex breathing wider and narrower, and a single yellow leaf in the outermost turn carried slowly around and inward. The camera holds the centre of the spiral exactly at the centre of frame and rolls clockwise with small amplitude at slow speed throughout.\n\noverall_soundscape: The full close sound of moving water: a deep steady pull and gurgle at the throat of the vortex, water sliding and slapping around it, and a river running on beyond.\n\nnon_diegetic_music: None.",
-        "frame_6_whirlpool": {
-            "location": "assets/frame_6_whirlpool.jpg"
-        },
-        "shot_7_hurricane": "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\nintegrated_multimodal_description: [Shot 1] Cinematic, live-action satellite photography from orbit. The shot opens exactly on <Picture 1>: a hurricane seen from directly above, its small clear round eye at the exact centre of the frame, immense white cloud bands spiralling around it, deep blue-black ocean showing beyond the outer arms. The whole storm rotates slowly and steadily clockwise, the cloud bands winding inward toward the eye, towers of cloud boiling upward along the arms and throwing moving shadows across the cloud deck below, the eye wall staying crisp and the eye itself holding open and clear the whole time. The camera holds the centre of the spiral exactly at the centre of frame and rolls clockwise with small amplitude at slow speed throughout.\n\noverall_soundscape: Silence, or as near to it as orbit gets: a vast low airless hum, a faint electrical hiss, and nothing else at all.\n\nnon_diegetic_music: None.",
-        "frame_7_hurricane": {
-            "location": "assets/frame_7_hurricane.jpg"
-        },
-        "shot_8_galaxy": "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\nintegrated_multimodal_description: [Shot 1] Cinematic, live-action deep-space photography. The shot opens exactly on <Picture 1>: a grand-design spiral galaxy seen exactly face-on, a blazing gold core at the exact centre of the frame, two great arms of blue-white star formation winding outward through lanes of dark dust, pink nebulae strung along the arms, deep black space all around. The galaxy turns very slowly clockwise, the arms trailing as they sweep, the gold core pulsing faintly brighter and dimmer, the dark dust lanes drifting slowly across the bright face behind them, and individual foreground stars twinkling sharply against the black. The camera holds the centre of the spiral exactly at the centre of frame and rolls clockwise with small amplitude at slow speed throughout.\n\noverall_soundscape: Deep space: a vast, almost subsonic hum with a faint high shimmer moving over it, and nothing else.\n\nnon_diegetic_music: None.",
-        "frame_8_galaxy": {
-            "location": "assets/frame_8_galaxy.jpg"
-        },
-        "shot_9_return": "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\nintegrated_multimodal_description: [Shot 1] Cinematic, live-action extreme macro photography. The shot opens exactly on <Picture 1>: a single human eye in near-total darkness, and mirrored across the wet glassy curve of it the bright reflection of a great spiral galaxy, its gold core sitting exactly over the round black pupil at the centre of the frame and its blue-white arms curving out across the amber fibres of the iris. The reflected galaxy turns slowly clockwise across the wet surface of the eye while the iris fibres beneath it shift and the pupil contracts a little, the moving light sliding over the curve of the cornea; at the very end the eye blinks once, slowly, and when the lashes lift the galaxy is still reflected there. The camera holds the centre of the spiral exactly at the centre of frame and rolls clockwise with small amplitude at slow speed throughout.\n\noverall_soundscape: Nearly silent and very close: one slow soft blink, a single quiet human breath, and behind them the faintest trace of the same deep hum.\n\nnon_diegetic_music: None.",
-        "frame_9_return": {
-            "location": "assets/frame_9_return.jpg"
-        }
-    },
-    "seed": 11,
-    "steps": [
-        {
-            "name": "shot_4_nautilus",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "ModularPipeline",
-                    "pre_load_modules": [
-                        "sdnq"
-                    ],
-                    "load_components": {
-                        "dtype": "torch.bfloat16",
-                        "quantization_config": {
-                            "transformer": {
-                                "configuration": {
-                                    "config_type": "sdnq.SDNQConfig"
-                                },
-                                "arguments": {
-                                    "weights_dtype": "variable:weights_dtype",
-                                    "quantization_device": "cuda",
-                                    "return_device": "cpu",
-                                    "use_quantized_matmul": true,
-                                    "dequantize_fp32": false,
-                                    "modules_to_not_convert": [
-                                        "proj_in",
-                                        "audio_proj_in",
-                                        "context_embedder",
-                                        "time_embedder",
-                                        "time_proj",
-                                        "token_refiner",
-                                        "norm_out",
-                                        "proj_out",
-                                        "audio_proj_out"
-                                    ]
-                                }
-                            },
-                            "text_encoder": {
-                                "configuration": {
-                                    "config_type": "sdnq.SDNQConfig"
-                                },
-                                "arguments": {
-                                    "weights_dtype": "variable:weights_dtype",
-                                    "quantization_device": "cuda",
-                                    "return_device": "cpu",
-                                    "dequantize_fp32": false,
-                                    "modules_to_not_convert": [
-                                        ".model.visual",
-                                        "lm_head"
-                                    ]
-                                }
-                            },
-                            "vae": {
-                                "configuration": {
-                                    "config_type": "sdnq.SDNQConfig"
-                                },
-                                "arguments": {
-                                    "weights_dtype": "{int8}",
-                                    "quant_conv": true,
-                                    "use_quantized_matmul_conv": true,
-                                    "quantization_device": "cuda",
-                                    "return_device": "cpu",
-                                    "dequantize_fp32": false
-                                }
-                            }
-                        }
-                    },
-                    "components": {
-                        "transformer": {
-                            "group_offload": {
-                                "offload_type": "block_level",
-                                "num_blocks_per_group": 2,
-                                "use_stream": true,
-                                "record_stream": true,
-                                "low_cpu_mem_usage": true
-                            }
-                        },
-                        "text_encoder": {
-                            "remove_modules": [
-                                "lm_head"
-                            ]
-                        },
-                        "text_encoder.model": {
-                            "truncate_layers": {
-                                "language_model.layers": 51
-                            },
-                            "group_offload": {
-                                "offload_type": "leaf_level"
-                            }
-                        },
-                        "vae": {
-                            "device": "cuda",
-                            "residency": "on_demand"
-                        },
-                        "audio_vae": {
-                            "device": "cuda",
-                            "residency": "on_demand"
-                        }
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "MiniMaxAI/MiniMax-H3",
-                    "workflow": "fl2va"
-                },
-                "loras": [
-                    {
-                        "model_name": "variable:lora_model_name",
-                        "weight_name": "variable:lora_weight_name",
-                        "adapter_name": "variable:lora_adapter_name",
-                        "scale": "variable:lora_scale"
-                    }
-                ],
-                "arguments": {
-                    "prompt": "variable:shot_4_nautilus",
-                    "image": "variable:frame_4_nautilus",
-                    "num_frames": "variable:num_frames",
-                    "width": "variable:width",
-                    "height": "variable:height",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "output": [
-                        "videos",
-                        "audio",
-                        "sampling_rate"
-                    ]
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/gyre/GyreStills.json b/workflows/gyre/GyreStills.json
deleted file mode 100644
index 0dba3f2b..00000000
--- a/workflows/gyre/GyreStills.json
+++ /dev/null
@@ -1,219 +0,0 @@
-{
-    "id": "Gyre",
-    "description": "Pass 1 of GYRE - 'one shape, nine worlds'. Z-Image Turbo paints the nine keyframes the film is built from, one per shot, and MiniMax-Music3 writes two candidate scores (a pure instrumental and one with a wordless choir; the film uses the choir, whose level rises monotonically to a peak in its final decile). Shots 2, 5 and 9 miss here and are re-shot by GyreStillsFix.json and GyreStillsFix2.json - the three workflows together reproduce the nine source stills exactly, which matters because GyreFrames.json's centres are measured on those exact images.",
-    "variables": {
-        "still_1_iris": "An extreme macro photograph of a single human iris, deep amber and hazel fibres radiating and curling outward from a perfectly round black pupil at the exact centre of the frame, fine crypts and folds catching a soft light, a thin wet rim of moisture at the outer edge, one small bright catchlight, the surrounding eyelids and skin lost in near-black shadow; perfectly centred square composition, shot square-on flat to the eye, the iris a clean circle occupying about two thirds of the frame with dark space all around it, ultra-sharp macro photograph, natural colours",
-        "still_2_fingerprint": "An extreme macro photograph looking straight down at a single fingertip pressed flat and hard against a sheet of wet black glass, seen from directly beneath the glass so the flattened oval pad fills the middle of the frame and the whorl of the fingerprint is viewed perfectly head-on, the ridge lines circling around the exact centre of the whorl, every ridge picked out by a low raking light, tiny beads of water caught in the valleys, no hand or finger visible beyond the pad, the glass glossy and near-black all around it; perfectly centred square composition, the whorl's centre at the exact centre of the frame, the print occupying about two thirds of the frame, ultra-sharp macro photograph, cool grey and warm amber",
-        "still_3_fiddlehead": "A macro photograph of a single fern fiddlehead, a tight bright green coil furled around its exact centre and held square-on to the camera, fine silver hairs standing along the stem, beads of dew on the coil catching low morning light, a very dark blurred forest floor far behind; perfectly centred square composition, the spiral occupying about two thirds of the frame with clear open space all around it, ultra-sharp photograph, deep greens and black",
-        "still_4_nautilus": "A cross-sectioned nautilus shell lying on wet black volcanic sand, its chambers opening out from the exact centre of the frame in a perfect logarithmic curve, mother-of-pearl interior glowing pale pink and cream, a thin film of seawater around it reflecting an overcast sky, wide black sand all around the shell; perfectly centred square composition, the spiral occupying about two thirds of the frame with clear open space all around it, ultra-sharp photograph, soft even light",
-        "still_5_web": "An orb spider's web strung with dew at first light, the spiral of silk winding out from its exact centre, every droplet a tiny bright bead threaded on the line, straight radial guy lines running away to the corners of the frame, a deep black out-of-focus hedgerow behind; perfectly centred square composition, the spiral occupying about two thirds of the frame with clear open space all around it, ultra-sharp photograph, silver and cold blue",
-        "still_6_whirlpool": "A whirlpool turning in dark peat-brown river water, long lines of white foam drawn into a tightening spiral around a black funnel at the exact centre of the frame, the surface glassy and stretched where it bends down into the vortex, a single yellow leaf caught in the outermost turn, calm dark water all around; perfectly centred square composition, the spiral occupying about two thirds of the frame with clear open space all around it, ultra-sharp photograph, amber-brown water and white foam",
-        "still_7_hurricane": "A hurricane photographed from orbit, its small clear round eye at the exact centre of the frame, immense white cloud bands spiralling around it, deep blue-black ocean showing beyond the outer arms; perfectly centred square composition, the spiral occupying about two thirds of the frame with clear open space all around it, ultra-sharp photograph, brilliant white and deep blue satellite photograph",
-        "still_8_galaxy": "A grand-design spiral galaxy seen exactly face-on, a blazing gold core at the exact centre of the frame, two great arms of blue-white star formation winding outward through lanes of dark dust, pink nebulae strung along the arms like beads, deep black space all around it; perfectly centred square composition, the spiral occupying about two thirds of the frame with clear open space all around it, ultra-sharp photograph, gold, blue-white and dark red deep-space photograph",
-        "still_9_return": "An extreme macro photograph of a single human eye, and mirrored across the wet glassy curve of the cornea the bright clear reflection of a great spiral galaxy - its gold core sitting exactly over the round black pupil at the centre of the frame and its blue-white spiral arms curving out across the amber iris - so that the galaxy and the iris are the same spiral seen at once, the surrounding eyelids and skin lost in near-black shadow; perfectly centred square composition, shot square-on flat to the eye, the iris a clean circle occupying about two thirds of the frame, ultra-sharp macro photograph, amber and blue",
-        "score_prompt": "Genre: ambient neoclassical, minimalist, cinematic. BPM: 60, in 3/4. Key: D minor opening out into D major. Emotional progression: begins as one quiet circling figure, almost still and very small; gathers slowly and without a break as more voices join the same turning motion; opens at the very end into a vast radiant major chord that hangs in the air and fades. Listening scenario: the score under a wordless film in which a single spiral turns through every scale of the universe. Production profile: enormous natural cathedral reverb, pristine and dynamic, no compression, no drums and no percussion beat of any kind. Arrangement: a solo cello plays a slow three-note circling figure over a low sustained drone; a second cello answers it a beat later, then violas, then violins, each entering on the same figure so the texture builds into a wheel of overlapping voices; a glass harmonica and high sustained strings shimmer above them; at the end the whole ensemble arrives together on one immense held major chord that decays into silence.",
-        "instrumental_lyrics": "[intro]\n[instrumental]\n[verse]\n[instrumental]\n[chorus]\n[instrumental]\n[outro]\n[instrumental]",
-        "choir_lyrics": "[intro]\n[instrumental]\n[verse]\nAh, ah, ah\n[chorus]\nAh, ah, ah, ah\nAh, ah\n[outro]\n[instrumental]",
-        "audio_duration": 50,
-        "width": 1024,
-        "height": 1024
-    },
-    "seed": 11,
-    "steps": [
-        {
-            "name": "still_1_iris",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "ZImagePipeline",
-                    "offload": "sequential"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "Tongyi-MAI/Z-Image-Turbo",
-                    "torch_dtype": "torch.bfloat16",
-                    "low_cpu_mem_usage": true
-                },
-                "arguments": {
-                    "prompt": "variable:still_1_iris",
-                    "num_inference_steps": 9,
-                    "guidance_scale": 0.0,
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg"
-            }
-        },
-        {
-            "name": "still_2_fingerprint",
-            "pipeline_reference": {
-                "reference_name": "still_1_iris",
-                "arguments": {
-                    "prompt": "variable:still_2_fingerprint",
-                    "num_inference_steps": 9,
-                    "guidance_scale": 0.0,
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg"
-            }
-        },
-        {
-            "name": "still_3_fiddlehead",
-            "pipeline_reference": {
-                "reference_name": "still_1_iris",
-                "arguments": {
-                    "prompt": "variable:still_3_fiddlehead",
-                    "num_inference_steps": 9,
-                    "guidance_scale": 0.0,
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg"
-            }
-        },
-        {
-            "name": "still_4_nautilus",
-            "pipeline_reference": {
-                "reference_name": "still_1_iris",
-                "arguments": {
-                    "prompt": "variable:still_4_nautilus",
-                    "num_inference_steps": 9,
-                    "guidance_scale": 0.0,
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg"
-            }
-        },
-        {
-            "name": "still_5_web",
-            "pipeline_reference": {
-                "reference_name": "still_1_iris",
-                "arguments": {
-                    "prompt": "variable:still_5_web",
-                    "num_inference_steps": 9,
-                    "guidance_scale": 0.0,
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg"
-            }
-        },
-        {
-            "name": "still_6_whirlpool",
-            "pipeline_reference": {
-                "reference_name": "still_1_iris",
-                "arguments": {
-                    "prompt": "variable:still_6_whirlpool",
-                    "num_inference_steps": 9,
-                    "guidance_scale": 0.0,
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg"
-            }
-        },
-        {
-            "name": "still_7_hurricane",
-            "pipeline_reference": {
-                "reference_name": "still_1_iris",
-                "arguments": {
-                    "prompt": "variable:still_7_hurricane",
-                    "num_inference_steps": 9,
-                    "guidance_scale": 0.0,
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg"
-            }
-        },
-        {
-            "name": "still_8_galaxy",
-            "pipeline_reference": {
-                "reference_name": "still_1_iris",
-                "arguments": {
-                    "prompt": "variable:still_8_galaxy",
-                    "num_inference_steps": 9,
-                    "guidance_scale": 0.0,
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg"
-            }
-        },
-        {
-            "name": "still_9_return",
-            "pipeline_reference": {
-                "reference_name": "still_1_iris",
-                "arguments": {
-                    "prompt": "variable:still_9_return",
-                    "num_inference_steps": 9,
-                    "guidance_scale": 0.0,
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg"
-            }
-        },
-        {
-            "name": "score_instrumental",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "ModularPipeline",
-                    "load_components": {
-                        "dtype": "torch.bfloat16"
-                    },
-                    "components_manager": {
-                        "enable_auto_cpu_offload": true
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "MiniMaxAI/MiniMax-Music3"
-                },
-                "arguments": {
-                    "prompt": "variable:score_prompt",
-                    "lyrics": "variable:instrumental_lyrics",
-                    "audio_duration": "variable:audio_duration",
-                    "output": "audios"
-                }
-            },
-            "result": {
-                "content_type": "audio/wav",
-                "sample_rate": 44100
-            }
-        },
-        {
-            "name": "score_choir",
-            "pipeline_reference": {
-                "reference_name": "score_instrumental",
-                "arguments": {
-                    "prompt": "variable:score_prompt",
-                    "lyrics": "variable:choir_lyrics",
-                    "audio_duration": "variable:audio_duration",
-                    "output": "audios"
-                }
-            },
-            "result": {
-                "content_type": "audio/wav",
-                "sample_rate": 44100
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/gyre/GyreStillsFix.json b/workflows/gyre/GyreStillsFix.json
deleted file mode 100644
index 5e50a716..00000000
--- a/workflows/gyre/GyreStillsFix.json
+++ /dev/null
@@ -1,82 +0,0 @@
-{
-    "id": "GyreFix",
-    "description": "Re-shoots the two GYRE stills that missed - the fingerprint had lost its wet glass and the web had a bright sky that broke the film's dark surround - and tries two ways of making the closing image, in which the galaxy is reflected across the eye it started in: painted from scratch by Z-Image, and edited onto the opening iris by Krea 2.",
-    "variables": {
-        "still_2_fingerprint": "An extreme macro photograph of a fingerprint left in condensation on a sheet of cold black glass, the whorl a set of concentric ridge lines circling around one clear centre point at the exact middle of the frame, each ridge picked out as a chain of tiny bright water droplets against the black, a soft raking light from one side, more condensation beading and creeping across the glass around the print, no hand or finger in the picture; perfectly centred square composition, the print occupying about two thirds of the frame with black glass all around it, ultra-sharp macro photograph, silver, grey and faint amber on black",
-        "still_5_web": "An orb spider's web strung with dew photographed at night against pure black, lit by a single low lamp from one side so every droplet burns as a tiny bright bead threaded on the silk, the spiral of the web winding out from its exact centre at the middle of the frame, straight radial guy lines running away into the darkness, nothing behind the web but black; perfectly centred square composition, the web occupying about two thirds of the frame, no sky and no background, ultra-sharp macro photograph, silver and cold blue on black",
-        "still_9_painted": "An extreme macro photograph of a single human iris in near-total darkness, the surrounding eyelids and skin lost in black, and mirrored across the wet glassy curve of the eye the bright reflection of a great spiral galaxy - its gold core sitting exactly over the round black pupil at the centre of the frame and its blue-white spiral arms curving out across the amber fibres of the iris - so that the galaxy and the iris read as one single spiral; perfectly centred square composition, shot square-on flat to the eye, the iris a clean circle occupying about two thirds of the frame, ultra-sharp macro photograph, amber and blue on black",
-        "edit_instruction": "Mirror the bright reflection of a great blue and gold spiral galaxy across the wet curve of this eye, its glowing core sitting exactly over the black pupil and its spiral arms curving out across the iris, and sink the surrounding skin and eyelashes into near-black darkness",
-        "iris_image": { "location": "assets/Gyre-still_1_iris.0-0.0.jpg" },
-        "width": 1024,
-        "height": 1024
-    },
-    "seed": 11,
-    "steps": [
-        {
-            "name": "still_2_fingerprint",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "ZImagePipeline",
-                    "offload": "sequential"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "Tongyi-MAI/Z-Image-Turbo",
-                    "torch_dtype": "torch.bfloat16",
-                    "low_cpu_mem_usage": true
-                },
-                "arguments": {
-                    "prompt": "variable:still_2_fingerprint",
-                    "num_inference_steps": 9,
-                    "guidance_scale": 0.0,
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": { "content_type": "image/jpeg" }
-        },
-        {
-            "name": "still_5_web",
-            "pipeline_reference": {
-                "reference_name": "still_2_fingerprint",
-                "arguments": { "prompt": "variable:still_5_web", "num_inference_steps": 9, "guidance_scale": 0.0, "width": "variable:width", "height": "variable:height" }
-            },
-            "result": { "content_type": "image/jpeg" }
-        },
-        {
-            "name": "still_9_painted",
-            "pipeline_reference": {
-                "reference_name": "still_2_fingerprint",
-                "arguments": { "prompt": "variable:still_9_painted", "num_inference_steps": 9, "guidance_scale": 0.0, "width": "variable:width", "height": "variable:height" }
-            },
-            "result": { "content_type": "image/jpeg" }
-        },
-        {
-            "name": "still_9_edited",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "Krea2Pipeline",
-                    "offload": "sequential"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "krea/Krea-2-Turbo",
-                    "torch_dtype": "torch.bfloat16",
-                    "custom_pipeline": "ostris/Krea2OstrisEdit",
-                    "trust_remote_code": true
-                },
-                "loras": [
-                    {
-                        "model_name": "conradlocke/krea2-identity-edit",
-                        "weight_name": "krea2_identity_edit_v1_2.safetensors"
-                    }
-                ],
-                "arguments": {
-                    "prompt": "variable:edit_instruction",
-                    "image": "variable:iris_image",
-                    "num_inference_steps": 8,
-                    "guidance_scale": 0.0
-                }
-            },
-            "result": { "content_type": "image/jpeg" }
-        }
-    ]
-}
diff --git a/workflows/gyre/GyreStillsFix2.json b/workflows/gyre/GyreStillsFix2.json
deleted file mode 100644
index bd119d8c..00000000
--- a/workflows/gyre/GyreStillsFix2.json
+++ /dev/null
@@ -1,50 +0,0 @@
-{
-    "id": "GyreFix2",
-    "description": "Third attempt at GYRE's second shot. The fingerprint kept coming out a loop pattern rather than a whorl, which reads as arcs instead of a spiral - fatal for shot two, where the film's rule is still being established. Two harder-pushed fingerprint prompts and a sunflower seed head as the fallback subject at the same scale.",
-    "variables": {
-        "fingerprint_a": "An extreme macro photograph of a whorl-type fingerprint left in condensation on cold black glass, the ridges forming closed concentric rings around one single point at the exact centre of the frame like the growth rings of a tree, no arches and no loops, each ridge a chain of tiny bright water droplets against the black, soft raking light from one side, no hand or finger in the picture; perfectly centred square composition, the round print occupying about two thirds of the frame with black glass all around it, ultra-sharp macro photograph, silver and grey on black",
-        "fingerprint_b": "An extreme macro photograph of a single fingertip's whorl pattern, a continuous ridge line winding inward turn after turn to one point at the exact centre of the frame, a true spiral, the skin wet and lit from a low angle so each ridge catches a thin highlight and the valleys stay black, the print round rather than oval, surrounded by darkness; perfectly centred square composition, the whorl occupying about two thirds of the frame, ultra-sharp macro photograph, warm grey and amber on black",
-        "sunflower": "An extreme macro photograph of the centre of a sunflower head seen exactly face-on, the packed seeds spiralling out from the exact centre of the frame in interlocking curved ranks, the tight dark green and violet florets at the middle giving way to gold pollen further out, low raking light bringing up the texture of every seed, the outer petals cropped away so only the spiralling disc is in frame; perfectly centred square composition, the disc occupying about two thirds of the frame with darkness all around it, ultra-sharp macro photograph, gold, olive and deep brown on black"
-    },
-    "seed": 23,
-    "steps": [
-        {
-            "name": "fingerprint_a",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "ZImagePipeline",
-                    "offload": "sequential"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "Tongyi-MAI/Z-Image-Turbo",
-                    "torch_dtype": "torch.bfloat16",
-                    "low_cpu_mem_usage": true
-                },
-                "arguments": {
-                    "prompt": "variable:fingerprint_a",
-                    "num_inference_steps": 9,
-                    "guidance_scale": 0.0,
-                    "width": 1024,
-                    "height": 1024
-                }
-            },
-            "result": { "content_type": "image/jpeg" }
-        },
-        {
-            "name": "fingerprint_b",
-            "pipeline_reference": {
-                "reference_name": "fingerprint_a",
-                "arguments": { "prompt": "variable:fingerprint_b", "num_inference_steps": 9, "guidance_scale": 0.0, "width": 1024, "height": 1024 }
-            },
-            "result": { "content_type": "image/jpeg" }
-        },
-        {
-            "name": "sunflower",
-            "pipeline_reference": {
-                "reference_name": "fingerprint_a",
-                "arguments": { "prompt": "variable:sunflower", "num_inference_steps": 9, "guidance_scale": 0.0, "width": 1024, "height": 1024 }
-            },
-            "result": { "content_type": "image/jpeg" }
-        }
-    ]
-}
diff --git a/workflows/gyre/NOTES.md b/workflows/gyre/NOTES.md
deleted file mode 100644
index 9840cdbf..00000000
--- a/workflows/gyre/NOTES.md
+++ /dev/null
@@ -1,216 +0,0 @@
-# GYRE - build log
-
-A record of what was made for this piece and what was changed in the engine to
-make it, so both can be reviewed independently of the film.
-
-## The piece
-
-**GYRE** - one shape, nine worlds. A spiral holds the exact centre of a square
-frame and turns clockwise for the whole film. Every 5.17 seconds the material of
-it is replaced on a hard cut, moving outward through scale: an iris, a
-fingerprint, a fern fiddlehead, a nautilus, a dew-strung orb web, a whirlpool, a
-hurricane, a galaxy - and back to an eye, with the galaxy reflected in it.
-
-The cut is the whole idea. The eye tracks a shape it believes it is still
-watching while the universe underneath it is swapped out. That only works if
-every spiral sits at the same point on screen at the same size, which is what
-the registration pass below exists to guarantee.
-
-## Passes
-
-| File | What it does |
-| ---- | ------------ |
-| `GyreStills.json` | Z-Image Turbo paints the nine source stills at 1024x1024, and MiniMax-Music3 writes two candidate scores |
-| `GyreFrames.json` | Registration: `recenter_crop` re-frames each still to 704x704 around its own measured spiral centre, at a per-still scale, so all nine agree |
-| `GyreFilm.json` | MiniMax-H3 (fl2va) animates each registered still into a 124-frame shot, `concat_videos` cuts them together, `pair_audio` lays the unbroken score over the edit |
-
-## Changes to the engine
-
-### `recenter_crop` image processor - `dw/tasks/image_utils.py`
-
-New. Takes a square window `crop` of the shorter side across, centred on
-`(center_x, center_y)` in normalised 0-1 coordinates, and resizes it to
-`width` x `height`. The window may run off the edge of the source - a feature
-near a border is the case that needs moving furthest - and `fill` decides what
-lies outside: `"edge"` replicates the border pixels, anything else is read as a
-PIL colour.
-
-Registered in the `_PROCESSORS` table beside `crop_square`, so it is available
-as a task command with no further plumbing.
-
-Why it was needed: a generative model will not put a subject on an exact pixel
-just because the prompt asks it to, and across nine unrelated prompts it never
-puts them in the same place twice. Measuring each spiral's centre once and
-re-framing around it is both more reliable and far cheaper than re-rolling
-stills until they happen to line up. It generalises past this film to any
-sequence that has to cut or dissolve in register.
-
-### `mix_audio` task command - `dw/tasks/audio_utils.py`
-
-New, registered in `dw/tasks/task.py`. Layers audio tracks on top of one
-another and returns the weighted sum; `crossfade_audio` already joined tracks
-end to end, but nothing in the engine put one *under* another. Shorter tracks
-are padded with silence to the longest. It does not rescale the result, because
-quietening a mix is a decision about how it should sound - follow it with
-`normalize_audio`.
-
-Why it was needed: H3 generates a soundtrack for each world alongside the
-picture, and the existing pattern (`concat_videos` then `pair_audio`) throws all
-of it away in favour of the score. For this film that is the wrong trade - the
-sound of the whirlpool, the hurricane and the surf changing at every cut while
-the music runs unbroken *is* the idea, in the ear instead of the eye. GYRE mixes
-the nine worlds at 0.55 under the score at 1.0 and normalizes to -1 dBFS.
-
-### `stabilize_video` task command - `dw/tasks/stabilize.py`
-
-New module, registered in `dw/tasks/task.py`. Measures the translation between
-consecutive frames by phase correlation, accumulates it into the clip's drift,
-and shifts every frame back so the framing at the end is the framing at the
-start. `smooth=0` locks to the first frame; a window in frames instead removes
-only the wander faster than that window, so a slow deliberate camera move
-survives. The result is cropped to the rectangle every frame still covers and
-resized back to the original size, so no exposed edges appear.
-
-Why it was needed, and this one is the real find: **H3 drifts.** Asked for a
-locked camera on a pinned keyframe, the test shot still slid 38px down a 704px
-frame over 124 frames - 5% of the picture, invisible within the shot and glaring
-the moment two shots are cut together, because the subject snaps back to centre
-at every cut. That would have quietly wrecked the whole premise of this film
-after an hour of GPU time. Phase correlation takes the measured drift from 38px
-to 2px.
-
-Note on the sign convention: the peak of the cross-power spectrum sits at the
-*negative* of the displacement. `_pair_shift` negates it so every caller can
-read `(dx, dy)` as "how far the picture moved", which is worth knowing because
-getting it backwards doubles the drift instead of removing it, and looks
-plausible enough in a single number to miss.
-
-## Things tried and abandoned
-
-- **Automatic spiral-centre detection.** A centre-of-rotational-symmetry finder
-  (score each candidate centre by how well the image matches a rotated copy of
-  itself about that point). It found the flat, blurred backgrounds instead of
-  the spirals, because a featureless patch correlates perfectly with any
-  rotation of itself. Weighting the score by local contrast helped and did not
-  fix it. Registration was measured by eye instead, and the utility was not
-  shipped - an unreliable one is worse than none. The prototype is in the
-  session scratchpad, not the repo.
-- **A continuous clockwise camera roll across all nine shots**, so the whole
-  film would be one unbroken turn. H3 ignored `Roll Clockwise with small
-  amplitude at slow speed` entirely - the test shot has no roll in it. Doing it
-  in post would mean zooming ~1.41x to keep the corners covered, which throws
-  away a third of the resolution for a decorative flourish. Dropped in favour of
-  fixing the drift, which the concept actually depends on.
-- **`fill="edge"` when a crop window runs off the source.** Replicated border
-  pixels leave visible streaks against texture. `reflect` and `symmetric` were
-  added to `recenter_crop` for it; the nautilus uses `symmetric` and the
-  mirrored volcanic sand is undetectable.
-
-## What the first full run taught
-
-Three things only showed up once the whole thing existed, and all three are now
-fixed in the workflows.
-
-**The score was passed as `{"location": ...}`.** The engine resolves that into a
-bare waveform, which carries no sample rate, so `slice_audio` refused it - after
-all nine shots had been generated. Every expensive step writes its shot out, so
-nothing was lost, but it is the reason `GyreAssemble.json` exists: the edit half
-of the film, run over the shots already on disk. Re-cutting a different mix
-balance now costs a minute instead of an hour.
-
-**`stabilize_video`'s argument could not be called `video`.** `dw/arguments.py`
-loads any argument named `video` or `*_video` itself, with diffusers'
-`load_video`, which returns bare frames and drops the soundtrack. So a path
-passed under that name arrived stripped of its audio *and* as a list, which the
-previous-result machinery then fanned out one iteration per frame - nine shots
-of 124 frames asked the engine for 124^9 combinations. The argument is `clip`
-for that reason, which is why `concat_videos` can take paths too: `videos`
-escapes the same magic by being plural.
-
-**The world sound was inaudible.** At `world_gain` 0.55 against the score's 1.0,
-H3's own soundtrack sat 22 dB under the music - present in the file, absent to
-the ear, which defeats the whole reason `mix_audio` was written. The measurement
-worth keeping is the method: project the mix onto the score, and whatever is
-left over is the world. `world_gain` 1.8 puts it 13 dB down, which is a bed you
-hear change at every cut without it competing with the music.
-
-## Shot 4 took three attempts
-
-The nautilus is the only shot that had to be re-generated, and it is a good
-illustration of what H3 will and will not hold. The first prompt asked for a
-sheet of seawater to slide in across the sand and flood the chambers; by
-mid-shot the black volcanic sand had dissolved into a grey wash with circular
-blob artifacts and the shell was covered in black speckles. The second held the
-scene still but still asked for water, and H3 rendered it as a grey smear
-sweeping through the frame. The third removed water from the shot entirely and
-made light the only thing that moves - iridescence travelling around the spiral,
-wet sand grains glittering and going dark - and it is clean end to end.
-
-The lesson generalises: H3 is reliable when the frame's *contents* stay put and
-something about them changes, and unreliable when it has to move new material
-through a scene it was given as a still. `GyreReshoot.json` is kept for this -
-re-generating one shot without disturbing the other eight.
-
-## The dissolve variant
-
-[`GyreDissolve.json`](GyreDissolve.json) replaces `concat_videos` with
-`dissolve_videos`, softening every cut into a cross-dissolve.
-
-It turns out to be a different piece rather than a softer one. Because all nine
-spirals sit on the same centre at the same size, an overlap does not read as a
-fade between two pictures - at the midpoint of the seam the two subjects are
-concentric, so the pupil sits inside the fingerprint's whorl and the iris fibres
-read as ridges. The shape holds still and its *material* transforms through the
-seam. Registration bought this for free; it would look like an ordinary mix
-between any two unregistered shots.
-
-The arithmetic has to be passed in, since JSON cannot compute it:
-`dissolve_videos` consumes one overlap per seam, so
-`total_frames = 1116 - 8 * dissolve_frames`, and
-`start_frame = round((50.05 - total_frames / 24) * 24)` keeps the piece ending
-on the score's final chord. Rendered at 6 frames (0.25s, 44.50s total) and 12
-frames (0.50s, 42.50s total).
-
-## A per-step seed does not isolate the RNG stream
-
-Worth writing down, because it looks like it should. `dw/workflow_schema.json`
-lets a step carry its own `seed` ("Default seed for the entire step"), so the
-three stills workflows looked consolidatable into one that names, per step, the
-seed its chosen image was drawn on. Tried it: only `still_1_iris` came back
-byte-identical. The other eight differed by a mean of 11 to 109 levels per
-pixel - different pictures, not drifted ones. A step's result still depends on
-its position in the run, not on its seed alone.
-
-That is why `GyreStills.json`, `GyreStillsFix.json` and `GyreStillsFix2.json`
-are all kept rather than merged. Together they reproduce the nine source stills
-exactly, and they have to: `GyreFrames.json`'s crop centres are hand-measured on
-those exact images, so regenerating the stills differently would leave its
-numbers pointing at nothing while still validating and still running.
-
-## Cleanup
-
-Intermediates removed (124 MB): the stills and re-shoot runs, the four
-registration passes, the single-shot probe, the two discarded nautilus takes,
-and the three superseded cuts of the film. Everything the pipeline needs was
-first copied into `assets/` - nine source stills, nine registered frames, nine
-generated shots, both scores - and `GyreAssemble.json` and `GyreDissolve.json`
-were re-run afterwards to confirm they still rebuild both films byte-identically
-from those assets alone.
-
-`assets/` was itself removed from the repository afterwards - 30 MB across the
-nine stills, the nine frames, the nine shots and both scores, none of which the
-engine needs to be in version control. The workflows still address those paths,
-so the directory has to be restored from the archived copy before passes 2 and
-3, `GyreAssemble.json`, `GyreDissolve.json` or `GyreReshoot.json` will run.
-Re-running the workflows gets close but does not get back: the re-shoot takes
-and the choice between the two scores were both hand-picked and neither
-selection was recorded. The rejected instrumental score is in the archive too,
-although no workflow reads it.
-
-`GyreTest.json`, the single-shot probe, was deleted as redundant:
-`GyreReshoot.json` does the same job and is needed anyway.
-
-The pytest files added with the three new utilities - `tests/test_stabilize.py`,
-`tests/test_mix_audio.py`, `tests/test_recenter_crop.py` - are kept. They cover
-shipped engine code rather than this film, and the phase-correlation sign
-convention in particular is the kind of thing that fails silently.
diff --git a/workflows/gyre/README.md b/workflows/gyre/README.md
deleted file mode 100644
index a30feff3..00000000
--- a/workflows/gyre/README.md
+++ /dev/null
@@ -1,92 +0,0 @@
-# GYRE
-
-*One shape, nine worlds.*
-
-A spiral holds the exact centre of a square frame. Every 5.17 seconds the
-material of it is replaced on a hard cut, moving outward through scale:
-
-> an iris → a fingerprint → a fern fiddlehead → a nautilus → a dew-strung orb
-> web → a whirlpool → a hurricane → a galaxy → and back to an eye, with the
-> galaxy reflected in it
-
-The cut is the whole idea. Your eye tracks a shape it believes it is still
-watching while the universe underneath it is swapped out. Each world brings its
-own sound — surf, wind, water, the hum of orbit — and those change at the cuts
-too, while a single unbroken score runs under all of them.
-
-## Running it
-
-Three passes, in order. Each one is cheap to review before committing to the
-next, which is the point of splitting them.
-
-```bash
-python -m dw.run workflows/gyre/GyreStills.json  --output_dir ./outputs/gyre
-python -m dw.run workflows/gyre/GyreFrames.json  --output_dir ./outputs/gyre
-python -m dw.run workflows/gyre/GyreFilm.json    --output_dir ./outputs/gyre
-```
-
-Those write into `./outputs/gyre`. Passes 2 and 3, and every workflow below,
-also *read* from `assets/` - the nine source stills, the nine registered frames,
-the nine generated shots and the score. **`assets/` is not in the repository.**
-It is about 30 MB of generated media kept outside the tree, so restore it from
-wherever you archived it before running anything but `GyreStills.json`.
-
-| Pass | What it does | Cost |
-| ---- | ------------ | ---- |
-| [`GyreStills.json`](GyreStills.json) | Z-Image Turbo paints the nine source stills at 1024x1024; MiniMax-Music3 writes two candidate scores | ~10 min |
-| [`GyreFrames.json`](GyreFrames.json) | Registration. `recenter_crop` re-frames each still to 704x704 around its own spiral's centre | seconds |
-| [`GyreFilm.json`](GyreFilm.json) | MiniMax-H3 animates each frame into a 124-frame shot, `stabilize_video` holds each one still, `concat_videos` cuts them together, and the score is mixed over the nine worlds' own sound | ~40 min on a 3090 |
-
-[`GyreDissolve.json`](GyreDissolve.json) is the same edit with the cuts softened
-into cross-dissolves - which, because the spirals are registered, transforms one
-subject into the next rather than fading between them.
-[`GyreAssemble.json`](GyreAssemble.json) re-cuts the film from the shots already
-written, without regenerating them - the edit is a minute, the generation is an
-hour, and they should not be tied together.
-[`GyreReshoot.json`](GyreReshoot.json) re-generates a single shot when one of
-them misses, leaving the other eight alone.
-
-[`GyreStillsFix.json`](GyreStillsFix.json) and [`GyreStillsFix2.json`](GyreStillsFix2.json)
-are the re-shoots of the three stills the first pass missed. They are kept
-because the three stills workflows together reproduce the nine source stills
-*exactly*, and `GyreFrames.json`'s centres are hand-measured on those exact
-images — regenerate them differently and its numbers no longer mean anything.
-They do not rebuild `assets/` by themselves, though: which of their takes became
-which `src_*.jpg` was picked by eye and never written down, so the archived copy
-is the only authority. `GyreStillsFix.json` also reads one of pass 1's stills
-back out of `assets/` under its original run name, so it cannot run from a bare
-tree either.
-
-Run [`GyreReshoot.json`](GyreReshoot.json) as a single-shot probe before
-committing to the full film whenever a parameter changes — it is the cheapest way
-to find out that something is wrong.
-
-## The two things that make it work
-
-**Registration.** A generative model will not put a subject on an exact pixel
-because the prompt asked it to, and across nine unrelated prompts it never puts
-them in the same place twice. `GyreFrames.json` measures each spiral's centre
-once and re-frames around it, so all nine agree on where the centre is and how
-big it is. Without this the cuts are nine pictures in a row; with it they are
-one thing changing.
-
-**Stabilization.** H3 drifts. Given a pinned keyframe and a prompt asking for a
-locked camera, the probe shot still slid 38px down a 704px frame over 124 frames.
-That is invisible inside a shot and glaring across a cut, where the subject snaps
-back to centre. `stabilize_video` takes it to 2px.
-
-Both are documented, with what was tried and abandoned, in [NOTES.md](NOTES.md).
-
-## Notes on the prompts
-
-The H3 prompts are hand-written Context-IR, in the format the
-[built-in enhancer](../minimax/MiniMaxH3EnhancePrompt.json) produces: the I2VA
-instruction line, then `integrated_multimodal_description`,
-`overall_soundscape` and `non_diegetic_music`. `non_diegetic_music` is `None.`
-in all nine, because the music is not H3's job here — the score is laid on
-afterwards, and asking H3 for music as well only muddies the soundscape that is
-wanted.
-
-Each prompt opens on `<Picture 1>` and describes what is actually in that frame
-before it describes any motion, which is what keeps the generated first frame
-faithful to the registered still.
diff --git a/workflows/lora.json b/workflows/lora.json
deleted file mode 100644
index be6f69df..00000000
--- a/workflows/lora.json
+++ /dev/null
@@ -1,35 +0,0 @@
-{
-    "id": "sd35_lora",
-    "description": "Stable Diffusion 3.5 Large with a LoRA adapter applied at generation time.",
-    "steps": [
-        {
-            "name": "main",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "StableDiffusion3Pipeline",
-                    "offload": "sequential"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "stabilityai/stable-diffusion-3.5-large",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "loras": [
-                    {
-                        "model_name": "linoyts/yart_art_sd3-5_lora"
-                    }
-                ],
-                "arguments": {
-                    "prompt": "marmot, yarn art style",
-                    "num_inference_steps": 25,
-                    "guidance_scale": 4.5,
-                    "max_sequence_length": 512,
-                    "num_images_per_prompt": 4
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/tasks/ExpandAndGenerate.json b/workflows/tasks/ExpandAndGenerate.json
deleted file mode 100644
index eb76675a..00000000
--- a/workflows/tasks/ExpandAndGenerate.json
+++ /dev/null
@@ -1,43 +0,0 @@
-{
-  "id": "ExpandAndGenerate",
-  "description": "Expands a short prompt with a language model, then generates with SD 1.5",
-  "variables": {
-    "prompt": "a cat sitting on a windowsill",
-    "system_prompt": "prompt:prompt_enhancement/text_to_image"
-  },
-  "steps": [
-    {
-      "name": "expand",
-      "task": {
-        "command": "text_generation",
-        "arguments": {
-          "prompt": "variable:prompt",
-          "system_prompt": "variable:system_prompt"
-        }
-      },
-      "result": {
-        "content_type": "text/plain",
-        "save": false
-      }
-    },
-    {
-      "name": "generate",
-      "pipeline": {
-        "configuration": {
-          "component_type": "StableDiffusionPipeline"
-        },
-        "from_pretrained_arguments": {
-          "model_name": "stable-diffusion-v1-5/stable-diffusion-v1-5",
-          "torch_dtype": "torch.float16"
-        },
-        "arguments": {
-          "prompt": "previous_result:expand"
-        }
-      },
-      "result": {
-        "content_type": "image/png",
-        "embed_metadata": true
-      }
-    }
-  ]
-}
diff --git a/workflows/tasks/ExpandPrompt.json b/workflows/tasks/ExpandPrompt.json
deleted file mode 100644
index 3fb5cf25..00000000
--- a/workflows/tasks/ExpandPrompt.json
+++ /dev/null
@@ -1,23 +0,0 @@
-{
-  "id": "ExpandPrompt",
-  "description": "Expands a short prompt into a detailed one with a language model - text out, no image.",
-  "variables": {
-    "prompt": "a cat sitting on a windowsill",
-    "system_prompt": "prompt:prompt_enhancement/text_to_image"
-  },
-  "steps": [
-    {
-      "name": "expand",
-      "task": {
-        "command": "text_generation",
-        "arguments": {
-          "prompt": "variable:prompt",
-          "system_prompt": "variable:system_prompt"
-        }
-      },
-      "result": {
-        "content_type": "text/plain"
-      }
-    }
-  ]
-}
diff --git a/workflows/tasks/ImageToTextVLM.json b/workflows/tasks/ImageToTextVLM.json
deleted file mode 100644
index d166814f..00000000
--- a/workflows/tasks/ImageToTextVLM.json
+++ /dev/null
@@ -1,36 +0,0 @@
-{
-    "id": "ImageToTextVLM",
-    "description": "Describes input images with a vision-language model.",
-    "variables": {
-        "image_url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/car.jpg?download=true",
-        "prompt": "What is shown in this image? Answer in one sentence."
-    },
-    "steps": [
-        {
-            "name": "input_image",
-            "task": {
-                "command": "gather_images",
-                "arguments": {
-                    "urls": [
-                        "variable:image_url"
-                    ]
-                }
-            }
-        },
-        {
-            "name": "caption",
-            "task": {
-                "command": "image_to_text",
-                "arguments": {
-                    "image": "previous_result:input_image",
-                    "model_name": "Qwen/Qwen2.5-VL-3B-Instruct",
-                    "prompt": "variable:prompt",
-                    "max_new_tokens": 100
-                }
-            },
-            "result": {
-                "content_type": "text/plain"
-            }
-        }
-    ]
-}
diff --git a/workflows/tasks/face-swap.json b/workflows/tasks/face-swap.json
deleted file mode 100644
index fe44772e..00000000
--- a/workflows/tasks/face-swap.json
+++ /dev/null
@@ -1,36 +0,0 @@
-{
-    "id": "face_swap",
-    "description": "SD 1.5 with an IP-Adapter face model - generates a new scene keeping the face from a reference photo.",
-    "steps": [
-        {
-            "name": "sd15",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "StableDiffusionPipeline"
-                },
-                "ip_adapter": {
-                    "model_name": "h94/IP-Adapter",
-                    "subfolder": "models",
-                    "weight_name": "ip-adapter-full-face_sd15.bin",
-                    "scale": 0.5
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "stable-diffusion-v1-5/stable-diffusion-v1-5",
-                    "torch_dtype": "torch.float16"
-                },
-                "arguments": {
-                    "ip_adapter_image": {
-                        "location": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/ip_adapter_einstein_base.png"
-                    },
-                    "prompt": "A photo of Einstein as a chef, wearing an apron, cooking in a French restaurant",
-                    "negative_prompt": "deformed, ugly, wrong proportion, low res, bad anatomy, worst quality, low quality",
-                    "num_inference_steps": 100
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/templates/assemble-and-score.json b/workflows/templates/assemble-and-score.json
new file mode 100644
index 00000000..b5abb457
--- /dev/null
+++ b/workflows/templates/assemble-and-score.json
@@ -0,0 +1,128 @@
+{
+    "id": "assemble-and-score",
+    "description": "Editing shots that already exist, with no generation in the run at all - 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.",
+    "variables": {
+        "shot_1": "asset:shot_1.mp4",
+        "shot_2": "asset:shot_2.mp4",
+        "shot_3": "asset:shot_3.mp4",
+        "score": "asset:score.wav",
+        "sample_rate": 44100,
+        "fps": 24,
+        "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"
+                }
+            }
+        },
+        {
+            "name": "world",
+            "task": {
+                "command": "resample_audio",
+                "arguments": {
+                    "audio": "previous_result:edit",
+                    "target_sample_rate": "variable:sample_rate"
+                }
+            }
+        },
+        {
+            "name": "soundtrack",
+            "task": {
+                "command": "slice_audio",
+                "arguments": {
+                    "audio": "variable:score",
+                    "start_frame": "variable:score_start_frame",
+                    "num_frames": "variable:total_frames",
+                    "fps": "variable:fps",
+                    "sample_rate": "variable:sample_rate"
+                }
+            }
+        },
+        {
+            "name": "mixed",
+            "task": {
+                "command": "mix_audio",
+                "arguments": {
+                    "audios": [
+                        "previous_result:soundtrack",
+                        "previous_result:world"
+                    ],
+                    "gains": [
+                        "variable:score_gain",
+                        "variable:world_gain"
+                    ],
+                    "sample_rate": "variable:sample_rate"
+                }
+            }
+        },
+        {
+            "name": "balanced",
+            "task": {
+                "command": "normalize_audio",
+                "arguments": {
+                    "audio": "previous_result:mixed",
+                    "peak_dbfs": -1.0,
+                    "sample_rate": "variable:sample_rate"
+                }
+            }
+        },
+        {
+            "name": "film",
+            "task": {
+                "command": "pair_audio",
+                "arguments": {
+                    "video": "previous_result:edit",
+                    "audio": "previous_result:balanced",
+                    "sample_rate": "variable:sample_rate"
+                }
+            },
+            "result": {
+                "content_type": "video/mp4",
+                "fps": 24
+            }
+        }
+    ]
+}
diff --git a/workflows/attention_processors_example.json b/workflows/templates/attention-processor.json
similarity index 100%
rename from workflows/attention_processors_example.json
rename to workflows/templates/attention-processor.json
diff --git a/workflows/tasks/TrimFadeAudio.json b/workflows/templates/audio-trim-fade.json
similarity index 100%
rename from workflows/tasks/TrimFadeAudio.json
rename to workflows/templates/audio-trim-fade.json
diff --git a/workflows/archive/sdxl.json b/workflows/templates/base-and-refiner.json
similarity index 100%
rename from workflows/archive/sdxl.json
rename to workflows/templates/base-and-refiner.json
diff --git a/workflows/flux/FluxRFInversion.json b/workflows/templates/community-pipeline.json
similarity index 100%
rename from workflows/flux/FluxRFInversion.json
rename to workflows/templates/community-pipeline.json
diff --git a/workflows/archive/txt2img2vid.json b/workflows/templates/compose-workflows.json
similarity index 100%
rename from workflows/archive/txt2img2vid.json
rename to workflows/templates/compose-workflows.json
diff --git a/workflows/controlnet.json b/workflows/templates/controlnet-component.json
similarity index 100%
rename from workflows/controlnet.json
rename to workflows/templates/controlnet-component.json
diff --git a/workflows/flux/FluxCanny.json b/workflows/templates/controlnet.json
similarity index 83%
rename from workflows/flux/FluxCanny.json
rename to workflows/templates/controlnet.json
index 69105cb5..2d913bd8 100644
--- a/workflows/flux/FluxCanny.json
+++ b/workflows/templates/controlnet.json
@@ -1,6 +1,6 @@
 {
     "id": "FluxCanny",
-    "description": "Extracts Canny edges from an input image and generates with FLUX.1 Canny dev guided by them.",
+    "description": "Extracts Canny edges from an input image and generates with FLUX.1 Canny dev guided by them. The preprocessor is the only thing that changes between control types: swap the 'canny' task for 'depth' and the model for 'black-forest-labs/FLUX.1-Depth-dev' (guidance_scale 10 rather than 30) for depth control. image-processors.json runs every preprocessor side by side.",
     "steps": [
         {
             "name": "canny",
@@ -46,4 +46,4 @@
             }
         }
     ]
-}
\ No newline at end of file
+}
diff --git a/workflows/tasks/MarigoldDepth.json b/workflows/templates/depth-marigold.json
similarity index 100%
rename from workflows/tasks/MarigoldDepth.json
rename to workflows/templates/depth-marigold.json
diff --git a/workflows/flux/img2txt2img.json b/workflows/templates/describe-and-regenerate.json
similarity index 97%
rename from workflows/flux/img2txt2img.json
rename to workflows/templates/describe-and-regenerate.json
index f978c360..a1f536d8 100644
--- a/workflows/flux/img2txt2img.json
+++ b/workflows/templates/describe-and-regenerate.json
@@ -43,7 +43,7 @@
         {
             "name": "flux",
             "workflow": {
-                "path": "FluxDev.json",
+                "path": "../flux/FluxDev.json",
                 "arguments": {
                     "prompt": "previous_result:augment_prompt",
                     "num_images_per_prompt": 1
diff --git a/workflows/templates/dissolve-between-shots.json b/workflows/templates/dissolve-between-shots.json
new file mode 100644
index 00000000..b2890dd8
--- /dev/null
+++ b/workflows/templates/dissolve-between-shots.json
@@ -0,0 +1,130 @@
+{
+    "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.",
+    "variables": {
+        "shot_1": "asset:shot_1.mp4",
+        "shot_2": "asset:shot_2.mp4",
+        "shot_3": "asset:shot_3.mp4",
+        "dissolve_frames": 12,
+        "score": "asset:score.wav",
+        "sample_rate": 44100,
+        "fps": 24,
+        "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": "dissolve_videos",
+                "arguments": {
+                    "videos": [
+                        "previous_result:hold_1",
+                        "previous_result:hold_2",
+                        "previous_result:hold_3"
+                    ],
+                    "dissolve_frames": "variable:dissolve_frames",
+                    "fps": "variable:fps"
+                }
+            }
+        },
+        {
+            "name": "world",
+            "task": {
+                "command": "resample_audio",
+                "arguments": {
+                    "audio": "previous_result:edit",
+                    "target_sample_rate": "variable:sample_rate"
+                }
+            }
+        },
+        {
+            "name": "soundtrack",
+            "task": {
+                "command": "slice_audio",
+                "arguments": {
+                    "audio": "variable:score",
+                    "start_frame": "variable:score_start_frame",
+                    "num_frames": "variable:total_frames",
+                    "fps": "variable:fps",
+                    "sample_rate": "variable:sample_rate"
+                }
+            }
+        },
+        {
+            "name": "mixed",
+            "task": {
+                "command": "mix_audio",
+                "arguments": {
+                    "audios": [
+                        "previous_result:soundtrack",
+                        "previous_result:world"
+                    ],
+                    "gains": [
+                        "variable:score_gain",
+                        "variable:world_gain"
+                    ],
+                    "sample_rate": "variable:sample_rate"
+                }
+            }
+        },
+        {
+            "name": "balanced",
+            "task": {
+                "command": "normalize_audio",
+                "arguments": {
+                    "audio": "previous_result:mixed",
+                    "peak_dbfs": -1.0,
+                    "sample_rate": "variable:sample_rate"
+                }
+            }
+        },
+        {
+            "name": "film",
+            "task": {
+                "command": "pair_audio",
+                "arguments": {
+                    "video": "previous_result:edit",
+                    "audio": "previous_result:balanced",
+                    "sample_rate": "variable:sample_rate"
+                }
+            },
+            "result": {
+                "content_type": "video/mp4",
+                "fps": 24
+            }
+        }
+    ]
+}
diff --git a/workflows/tasks/MetadataEmbed.json b/workflows/templates/embed-metadata.json
similarity index 100%
rename from workflows/tasks/MetadataEmbed.json
rename to workflows/templates/embed-metadata.json
diff --git a/workflows/templates/expand-prompt.json b/workflows/templates/expand-prompt.json
new file mode 100644
index 00000000..8fc43097
--- /dev/null
+++ b/workflows/templates/expand-prompt.json
@@ -0,0 +1,23 @@
+{
+    "id": "ExpandPrompt",
+    "description": "Expands a short prompt into a detailed one with a language model - text out, no image. To generate from the expanded text rather than saving it, add a pipeline step whose prompt is 'previous_result:expand' and set this step's result to \"save\": false.",
+    "variables": {
+        "prompt": "a cat sitting on a windowsill",
+        "system_prompt": "prompt:prompt_enhancement/text_to_image"
+    },
+    "steps": [
+        {
+            "name": "expand",
+            "task": {
+                "command": "text_generation",
+                "arguments": {
+                    "prompt": "variable:prompt",
+                    "system_prompt": "variable:system_prompt"
+                }
+            },
+            "result": {
+                "content_type": "text/plain"
+            }
+        }
+    ]
+}
diff --git a/workflows/tasks/GenerateSpeech.json b/workflows/templates/generate-speech.json
similarity index 100%
rename from workflows/tasks/GenerateSpeech.json
rename to workflows/templates/generate-speech.json
diff --git a/workflows/Krea2Edit.json b/workflows/templates/image-edit.json
similarity index 80%
rename from workflows/Krea2Edit.json
rename to workflows/templates/image-edit.json
index 61640a96..ec6989d6 100644
--- a/workflows/Krea2Edit.json
+++ b/workflows/templates/image-edit.json
@@ -38,5 +38,6 @@
                 "embed_metadata": true
             }
         }
-    ]
-}
\ No newline at end of file
+    ],
+    "description": "Instruction-driven image editing: the input picture is edited toward a written instruction rather than regenerated from scratch, with an identity-preserving LoRA holding the subject's likeness steady across the edit. Krea 2 Turbo through the ostris/Krea2OstrisEdit custom pipeline, which needs trust_remote_code."
+}
diff --git a/workflows/tasks/image_processors.json b/workflows/templates/image-processors.json
similarity index 100%
rename from workflows/tasks/image_processors.json
rename to workflows/templates/image-processors.json
diff --git a/workflows/flux/FluxImg2Img.json b/workflows/templates/image-to-image.json
similarity index 100%
rename from workflows/flux/FluxImg2Img.json
rename to workflows/templates/image-to-image.json
diff --git a/workflows/tasks/ImageToText.json b/workflows/templates/image-to-text.json
similarity index 77%
rename from workflows/tasks/ImageToText.json
rename to workflows/templates/image-to-text.json
index 08e8841f..9bfb1f3a 100644
--- a/workflows/tasks/ImageToText.json
+++ b/workflows/templates/image-to-text.json
@@ -1,6 +1,6 @@
 {
     "id": "ImageToText",
-    "description": "Captions input images with an image-to-text model.",
+    "description": "Captions input images with an image-to-text model. Supplying 'model_name' switches to a vision-language model, which answers a question rather than captioning: 'Qwen/Qwen2.5-VL-3B-Instruct' with a 'prompt' such as \"What is shown in this image? Answer in one sentence.\" and 'max_new_tokens' of 100.",
     "variables": {
         "image_url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/car.jpg?download=true"
     },
diff --git a/workflows/flux/FluxRedux.json b/workflows/templates/image-variation.json
similarity index 100%
rename from workflows/flux/FluxRedux.json
rename to workflows/templates/image-variation.json
diff --git a/workflows/flux/FluxFill.json b/workflows/templates/inpaint.json
similarity index 100%
rename from workflows/flux/FluxFill.json
rename to workflows/templates/inpaint.json
diff --git a/workflows/InterpolateFrames.json b/workflows/templates/interpolate-frames.json
similarity index 100%
rename from workflows/InterpolateFrames.json
rename to workflows/templates/interpolate-frames.json
diff --git a/workflows/flux/FluxIP.json b/workflows/templates/ip-adapter.json
similarity index 84%
rename from workflows/flux/FluxIP.json
rename to workflows/templates/ip-adapter.json
index cbb213d1..1d7f9ecc 100644
--- a/workflows/flux/FluxIP.json
+++ b/workflows/templates/ip-adapter.json
@@ -3,7 +3,7 @@
         "prompt": "A marmot sits at the counter and drinks a milkshake"
     },
     "id": "FluxIP",
-    "description": "FLUX.1 dev with an IP-Adapter conditioning generation on a reference image.",
+    "description": "FLUX.1 dev with an IP-Adapter conditioning generation on a reference image. The same 'ip_adapter' block takes a face model, which keeps a person's face across a new scene: 'h94/IP-Adapter' with subfolder 'models', weight_name 'ip-adapter-full-face_sd15.bin' and a scale of 0.5, on a StableDiffusionPipeline.",
     "steps": [
         {
             "name": "main",
@@ -37,4 +37,4 @@
             }
         }
     ]
-}
\ No newline at end of file
+}
diff --git a/workflows/flux/FluxInContext.json b/workflows/templates/lora-styles.json
similarity index 100%
rename from workflows/flux/FluxInContext.json
rename to workflows/templates/lora-styles.json
diff --git a/workflows/flux/FluxLora.json b/workflows/templates/lora.json
similarity index 85%
rename from workflows/flux/FluxLora.json
rename to workflows/templates/lora.json
index 0e670288..cce7b4d7 100644
--- a/workflows/flux/FluxLora.json
+++ b/workflows/templates/lora.json
@@ -7,7 +7,7 @@
         "guidance_scale": 3.5
     },
     "id": "FluxLora",
-    "description": "FLUX.1 dev with a LoRA adapter.",
+    "description": "FLUX.1 dev with a LoRA adapter. The same 'loras' list works on any pipeline that supports adapters - on StableDiffusion3Pipeline with 'stabilityai/stable-diffusion-3.5-large' and the 'linoyts/yart_art_sd3-5_lora' adapter, for instance.",
     "steps": [
         {
             "name": "txt2img",
@@ -44,4 +44,4 @@
             }
         }
     ]
-}
\ No newline at end of file
+}
diff --git a/workflows/ltx2/LTX2I2VChained.json b/workflows/templates/ltx2/chained-segments.json
similarity index 100%
rename from workflows/ltx2/LTX2I2VChained.json
rename to workflows/templates/ltx2/chained-segments.json
diff --git a/workflows/ltx2/LTX2I2VEnhancePrompt.json b/workflows/templates/ltx2/enhance-prompt.json
similarity index 100%
rename from workflows/ltx2/LTX2I2VEnhancePrompt.json
rename to workflows/templates/ltx2/enhance-prompt.json
diff --git a/workflows/ltx2/LTX2Extend.json b/workflows/templates/ltx2/extend-clip.json
similarity index 100%
rename from workflows/ltx2/LTX2Extend.json
rename to workflows/templates/ltx2/extend-clip.json
diff --git a/workflows/ltx2/LTX2ICLora.json b/workflows/templates/ltx2/generative-upscale.json
similarity index 100%
rename from workflows/ltx2/LTX2ICLora.json
rename to workflows/templates/ltx2/generative-upscale.json
diff --git a/workflows/ltx2/LTX2I2V.json b/workflows/templates/ltx2/image-to-video.json
similarity index 100%
rename from workflows/ltx2/LTX2I2V.json
rename to workflows/templates/ltx2/image-to-video.json
diff --git a/workflows/ltx2/LTX2Keyframes.json b/workflows/templates/ltx2/keyframes.json
similarity index 100%
rename from workflows/ltx2/LTX2Keyframes.json
rename to workflows/templates/ltx2/keyframes.json
diff --git a/workflows/ltx2/LTX2.json b/workflows/templates/ltx2/text-to-video.json
similarity index 100%
rename from workflows/ltx2/LTX2.json
rename to workflows/templates/ltx2/text-to-video.json
diff --git a/workflows/ltx2/LTX2TwoStage.json b/workflows/templates/ltx2/two-stage.json
similarity index 100%
rename from workflows/ltx2/LTX2TwoStage.json
rename to workflows/templates/ltx2/two-stage.json
diff --git a/workflows/minimax/MiniMaxH3Ref2VAChainedAligned.json b/workflows/templates/minimax/chain-matched-and-aligned.json
similarity index 100%
rename from workflows/minimax/MiniMaxH3Ref2VAChainedAligned.json
rename to workflows/templates/minimax/chain-matched-and-aligned.json
diff --git a/workflows/minimax/MiniMaxH3Ref2VAChained.json b/workflows/templates/minimax/chain-matched-to-audio.json
similarity index 100%
rename from workflows/minimax/MiniMaxH3Ref2VAChained.json
rename to workflows/templates/minimax/chain-matched-to-audio.json
diff --git a/workflows/minimax/MiniMaxH3Ref2VAChainedVideo.json b/workflows/templates/minimax/chain-video-continuity.json
similarity index 100%
rename from workflows/minimax/MiniMaxH3Ref2VAChainedVideo.json
rename to workflows/templates/minimax/chain-video-continuity.json
diff --git a/workflows/minimax/MiniMaxH3I2VChained.json b/workflows/templates/minimax/chained-segments.json
similarity index 100%
rename from workflows/minimax/MiniMaxH3I2VChained.json
rename to workflows/templates/minimax/chained-segments.json
diff --git a/workflows/minimax/MiniMaxH3Ref2VAVideo.json b/workflows/templates/minimax/composable-references.json
similarity index 100%
rename from workflows/minimax/MiniMaxH3Ref2VAVideo.json
rename to workflows/templates/minimax/composable-references.json
diff --git a/workflows/minimax/MiniMaxH3SitcomShort.json b/workflows/templates/minimax/dialogue-short.json
similarity index 100%
rename from workflows/minimax/MiniMaxH3SitcomShort.json
rename to workflows/templates/minimax/dialogue-short.json
diff --git a/workflows/minimax/MiniMaxH3I2VEnhancePrompt.json b/workflows/templates/minimax/enhance-prompt-with-image.json
similarity index 100%
rename from workflows/minimax/MiniMaxH3I2VEnhancePrompt.json
rename to workflows/templates/minimax/enhance-prompt-with-image.json
diff --git a/workflows/minimax/MiniMaxH3EnhancePrompt.json b/workflows/templates/minimax/enhance-prompt.json
similarity index 100%
rename from workflows/minimax/MiniMaxH3EnhancePrompt.json
rename to workflows/templates/minimax/enhance-prompt.json
diff --git a/workflows/minimax/MiniMaxH3FL2VA.json b/workflows/templates/minimax/first-and-last-frame.json
similarity index 100%
rename from workflows/minimax/MiniMaxH3FL2VA.json
rename to workflows/templates/minimax/first-and-last-frame.json
diff --git a/workflows/minimax/MiniMaxH3Ref2VAGeneratedSubject.json b/workflows/templates/minimax/generated-subject-reference.json
similarity index 100%
rename from workflows/minimax/MiniMaxH3Ref2VAGeneratedSubject.json
rename to workflows/templates/minimax/generated-subject-reference.json
diff --git a/workflows/minimax/MiniMaxH3I2V.json b/workflows/templates/minimax/image-to-video.json
similarity index 100%
rename from workflows/minimax/MiniMaxH3I2V.json
rename to workflows/templates/minimax/image-to-video.json
diff --git a/workflows/minimax/MiniMaxH3L2V.json b/workflows/templates/minimax/last-frame-only.json
similarity index 100%
rename from workflows/minimax/MiniMaxH3L2V.json
rename to workflows/templates/minimax/last-frame-only.json
diff --git a/workflows/minimax/MiniMaxH3MusicVideo.json b/workflows/templates/minimax/music-video.json
similarity index 100%
rename from workflows/minimax/MiniMaxH3MusicVideo.json
rename to workflows/templates/minimax/music-video.json
diff --git a/workflows/minimax/MiniMaxMusic.json b/workflows/templates/minimax/music.json
similarity index 100%
rename from workflows/minimax/MiniMaxMusic.json
rename to workflows/templates/minimax/music.json
diff --git a/workflows/minimax/MiniMaxH3Ref2VA.json b/workflows/templates/minimax/reference-to-video.json
similarity index 100%
rename from workflows/minimax/MiniMaxH3Ref2VA.json
rename to workflows/templates/minimax/reference-to-video.json
diff --git a/workflows/minimax/MiniMaxH3Storyboard.json b/workflows/templates/minimax/storyboard.json
similarity index 100%
rename from workflows/minimax/MiniMaxH3Storyboard.json
rename to workflows/templates/minimax/storyboard.json
diff --git a/workflows/minimax/MiniMaxH3.json b/workflows/templates/minimax/video-with-audio.json
similarity index 100%
rename from workflows/minimax/MiniMaxH3.json
rename to workflows/templates/minimax/video-with-audio.json
diff --git a/workflows/minimax/MiniMaxH3GeneratedVoice.json b/workflows/templates/minimax/voice-timbre-reference.json
similarity index 100%
rename from workflows/minimax/MiniMaxH3GeneratedVoice.json
rename to workflows/templates/minimax/voice-timbre-reference.json
diff --git a/workflows/flux/Flux2DevImageCombine.json b/workflows/templates/multi-image-reference.json
similarity index 100%
rename from workflows/flux/Flux2DevImageCombine.json
rename to workflows/templates/multi-image-reference.json
diff --git a/workflows/flux/FluxOutpaint.json b/workflows/templates/outpaint.json
similarity index 100%
rename from workflows/flux/FluxOutpaint.json
rename to workflows/templates/outpaint.json
diff --git a/workflows/flux/FluxSchnellWeighted.json b/workflows/templates/prompt-weighting.json
similarity index 100%
rename from workflows/flux/FluxSchnellWeighted.json
rename to workflows/templates/prompt-weighting.json
diff --git a/workflows/archive/qr_code.json b/workflows/templates/qr-code.json
similarity index 100%
rename from workflows/archive/qr_code.json
rename to workflows/templates/qr-code.json
diff --git a/workflows/templates/recenter-crop.json b/workflows/templates/recenter-crop.json
new file mode 100644
index 00000000..01464c9f
--- /dev/null
+++ b/workflows/templates/recenter-crop.json
@@ -0,0 +1,71 @@
+{
+    "id": "recenter-crop",
+    "description": "Registering a set of stills on each other before they become shots. recenter_crop re-frames each picture around a point given in fractions of its own width and height, at a crop size chosen per image, so subjects that were photographed at different distances all land at the same size in the same square frame. That is what lets a later dissolve read as one shape becoming another rather than as a fade. 'center_x'/'center_y' locate the subject, 'crop' sets how much of the source to keep, and 'fill' - 'symmetric' here - decides what happens when the crop runs past an edge.",
+    "variables": {
+        "width": 704,
+        "height": 704,
+        "source_1": {
+            "location": "asset:source_1.jpg"
+        },
+        "source_2": {
+            "location": "asset:source_2.jpg"
+        },
+        "source_3": {
+            "location": "asset:source_3.jpg"
+        }
+    },
+    "steps": [
+        {
+            "name": "frame_1",
+            "task": {
+                "command": "recenter_crop",
+                "arguments": {
+                    "image": "variable:source_1",
+                    "center_x": 0.4892,
+                    "center_y": 0.4592,
+                    "crop": 0.83,
+                    "width": "variable:width",
+                    "height": "variable:height"
+                }
+            },
+            "result": {
+                "content_type": "image/jpeg"
+            }
+        },
+        {
+            "name": "frame_2",
+            "task": {
+                "command": "recenter_crop",
+                "arguments": {
+                    "image": "variable:source_2",
+                    "center_x": 0.495,
+                    "center_y": 0.4825,
+                    "crop": 0.55,
+                    "width": "variable:width",
+                    "height": "variable:height"
+                }
+            },
+            "result": {
+                "content_type": "image/jpeg"
+            }
+        },
+        {
+            "name": "frame_3",
+            "task": {
+                "command": "recenter_crop",
+                "arguments": {
+                    "image": "variable:source_3",
+                    "center_x": 0.5615,
+                    "center_y": 0.4887,
+                    "crop": 0.99,
+                    "width": "variable:width",
+                    "height": "variable:height",
+                    "fill": "symmetric"
+                }
+            },
+            "result": {
+                "content_type": "image/jpeg"
+            }
+        }
+    ]
+}
diff --git a/workflows/tasks/FaceRestore.json b/workflows/templates/restore-faces.json
similarity index 100%
rename from workflows/tasks/FaceRestore.json
rename to workflows/templates/restore-faces.json
diff --git a/workflows/tasks/SegmentAndInpaint.json b/workflows/templates/segment-and-inpaint.json
similarity index 100%
rename from workflows/tasks/SegmentAndInpaint.json
rename to workflows/templates/segment-and-inpaint.json
diff --git a/workflows/tasks/Segment.json b/workflows/templates/segment.json
similarity index 100%
rename from workflows/tasks/Segment.json
rename to workflows/templates/segment.json
diff --git a/workflows/flux/FluxDevFirstBlockCache.json b/workflows/templates/step-caching.json
similarity index 76%
rename from workflows/flux/FluxDevFirstBlockCache.json
rename to workflows/templates/step-caching.json
index e3634e79..c00f690c 100644
--- a/workflows/flux/FluxDevFirstBlockCache.json
+++ b/workflows/templates/step-caching.json
@@ -5,7 +5,7 @@
         "guidance_scale": 3.5
     },
     "id": "FluxDevFirstBlockCache",
-    "description": "FLUX.1 dev accelerated with first-block caching, skipping redundant transformer work across denoise steps.",
+    "description": "FLUX.1 dev accelerated with first-block caching, skipping redundant transformer work across denoise steps. Two cache implementations, one shape. This uses first-block caching, a 'cache' block of {\"type\": \"first_block\", \"threshold\": 0.05}. For TeaCache instead, replace it with a sibling 'teacache' block of {\"rel_l1_thresh\": 0.4}. Both trade a little fidelity for skipped transformer work; raise the threshold to skip more.",
     "steps": [
         {
             "name": "txt2img",
diff --git a/workflows/flux/FluxLogo.json b/workflows/templates/sub-workflow.json
similarity index 95%
rename from workflows/flux/FluxLogo.json
rename to workflows/templates/sub-workflow.json
index f465d78b..20a03f76 100644
--- a/workflows/flux/FluxLogo.json
+++ b/workflows/templates/sub-workflow.json
@@ -8,7 +8,7 @@
         {
             "name": "logo",
             "workflow": {
-                "path": "./FluxLora.json",
+                "path": "./lora.json",
                 "arguments": {
                     "prompt": "variable:prompt",
                     "lora": "Shakker-Labs/FLUX.1-dev-LoRA-Logo-Design"
diff --git a/workflows/tasks/MarigoldNormals.json b/workflows/templates/surface-normals.json
similarity index 100%
rename from workflows/tasks/MarigoldNormals.json
rename to workflows/templates/surface-normals.json
diff --git a/workflows/sd15.json b/workflows/templates/text-to-image.json
similarity index 97%
rename from workflows/sd15.json
rename to workflows/templates/text-to-image.json
index 3ea795a8..ee1b2975 100644
--- a/workflows/sd15.json
+++ b/workflows/templates/text-to-image.json
@@ -3,7 +3,7 @@
         "prompt": "an apple",
         "num_images_per_prompt": 1
     },
-    "id": "test_job",
+    "id": "text-to-image",
     "description": "Baseline text-to-image with Stable Diffusion 1.5 - the smallest, fastest starting point.",
     "steps": [
         {
diff --git a/workflows/tasks/DiffusionUpscaleImage.json b/workflows/templates/upscale-diffusion.json
similarity index 100%
rename from workflows/tasks/DiffusionUpscaleImage.json
rename to workflows/templates/upscale-diffusion.json
diff --git a/workflows/tasks/UpscaleImage.json b/workflows/templates/upscale-spandrel.json
similarity index 100%
rename from workflows/tasks/UpscaleImage.json
rename to workflows/templates/upscale-spandrel.json

From 1bc6685f4428d5ecc5256bf3b00284a45b7a758a Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 15:04:29 -0500
Subject: [PATCH 12/32] Move the per-checkpoint configurations into
 workflows/models/

Each names the template it configures, so a tuned 24GB config is findable
as an instance of a pattern rather than as another undifferentiated
catalog entry. All nine configure templates/text-to-image: the collapse
rule stops at a pipeline class boundary, and FluxPipeline, Flux2Pipeline,
Krea2Pipeline and ZImagePipeline are four of them.

The ltx2/ and minimax/ READMEs move with the families they document.
Ids preserved.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 tests/test_catalog_structure.py               | 23 ++++++
 workflows/flux/FluxDevFast.json               | 74 ------------------
 workflows/models/flux-dev-fast.json           | 75 +++++++++++++++++++
 .../FluxDev.json => models/flux-dev.json}     |  3 +-
 .../FluxGGUF.json => models/flux-gguf.json}   |  3 +-
 .../flux-krea.json}                           |  3 +-
 .../flux-torchao.json}                        |  3 +-
 .../Flux2Dev.json => models/flux2-dev.json}   |  3 +-
 workflows/{Krea2.json => models/krea2.json}   |  3 +-
 .../z-image-sdnq.json}                        |  3 +-
 .../{ZImage.json => models/z-image.json}      |  1 +
 .../templates/describe-and-regenerate.json    |  2 +-
 workflows/{ => templates}/ltx2/README.md      |  0
 workflows/{ => templates}/minimax/README.md   |  0
 14 files changed, 114 insertions(+), 82 deletions(-)
 delete mode 100644 workflows/flux/FluxDevFast.json
 create mode 100644 workflows/models/flux-dev-fast.json
 rename workflows/{flux/FluxDev.json => models/flux-dev.json} (96%)
 rename workflows/{flux/FluxGGUF.json => models/flux-gguf.json} (97%)
 rename workflows/{flux/FluxDevKrea.json => models/flux-krea.json} (96%)
 rename workflows/{flux/FluxTorchAO.json => models/flux-torchao.json} (97%)
 rename workflows/{flux/Flux2Dev.json => models/flux2-dev.json} (96%)
 rename workflows/{Krea2.json => models/krea2.json} (95%)
 rename workflows/{ZImageSDNQ.json => models/z-image-sdnq.json} (97%)
 rename workflows/{ZImage.json => models/z-image.json} (97%)
 rename workflows/{ => templates}/ltx2/README.md (100%)
 rename workflows/{ => templates}/minimax/README.md (100%)

diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index 24aceb3d..2f6f9309 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -41,3 +41,26 @@ def test_every_template_describes_itself(path):
     assert definition.get("description", "").strip(), (
         f"{os.path.relpath(path, REPO_ROOT)} has no description"
     )
+
+
+MODELS_DIR = os.path.join(REPO_ROOT, "workflows", "models")
+
+
+def test_there_are_model_configs():
+    assert files_under(MODELS_DIR)
+
+
+@pytest.mark.parametrize("path", files_under(MODELS_DIR))
+def test_every_model_config_names_the_template_it_configures(path):
+    """A model config is a tuned instance of a pattern. Without the pointer it
+    is just another entry in the list, which is the problem this restructure
+    exists to fix."""
+    definition = json.load(open(path, encoding="utf-8"))
+    configures = definition.get("configures", "")
+
+    assert configures, f"{os.path.relpath(path, REPO_ROOT)} has no 'configures'"
+    target = os.path.join(REPO_ROOT, "workflows", f"{configures}.json")
+    assert os.path.isfile(target), (
+        f"{os.path.relpath(path, REPO_ROOT)} configures '{configures}', "
+        f"which is not a workflow ({target})"
+    )
diff --git a/workflows/flux/FluxDevFast.json b/workflows/flux/FluxDevFast.json
deleted file mode 100644
index 68f77188..00000000
--- a/workflows/flux/FluxDevFast.json
+++ /dev/null
@@ -1,74 +0,0 @@
-{
-  "id": "FluxDevFast",
-  "description": "Flux dev tuned for speed on a 24GB card: int8 TorchAO quantization on the transformer (quantized directly onto the GPU - quantized tensors cannot be moved between devices, so it stays resident), regional torch.compile, first-block caching, and group offload for the T5 encoder. On Ada/40-series cards use Float8DynamicActivationFloat8WeightConfig instead of Int8WeightOnlyConfig.",
-  "variables": {
-    "prompt": "a marmot wearing a tophat, in a forest scene.",
-    "num_inference_steps": 28,
-    "model_name": "black-forest-labs/FLUX.1-schnell"
-  },
-  "steps": [
-    {
-      "name": "main",
-      "pipeline": {
-        "configuration": {
-          "component_type": "FluxPipeline",
-          "cache": {
-            "type": "first_block",
-            "threshold": 0.05
-          },
-          "components": {
-            "transformer": {
-              "compile": {
-                "repeated_blocks": true
-              }
-            },
-            "text_encoder_2": {
-              "group_offload": {
-                "offload_type": "leaf_level",
-                "use_stream": true
-              }
-            },
-            "text_encoder": {
-              "device": "cuda"
-            },
-            "vae": {
-              "device": "cuda"
-            }
-          }
-        },
-        "transformer": {
-          "configuration": {
-            "component_type": "FluxTransformer2DModel",
-            "preserve_device_placement": true
-          },
-          "quantization_config": {
-            "configuration": {
-              "config_type": "TorchAoConfig"
-            },
-            "arguments": {
-              "quant_type": "torchao.quantization.Int8WeightOnlyConfig"
-            }
-          },
-          "from_pretrained_arguments": {
-            "model_name": "variable:model_name",
-            "subfolder": "transformer",
-            "torch_dtype": "torch.bfloat16",
-            "device_map": "cuda"
-          }
-        },
-        "from_pretrained_arguments": {
-          "model_name": "variable:model_name",
-          "torch_dtype": "torch.bfloat16"
-        },
-        "arguments": {
-          "prompt": "variable:prompt",
-          "num_inference_steps": "variable:num_inference_steps"
-        }
-      },
-      "result": {
-        "content_type": "image/jpeg",
-        "embed_metadata": true
-      }
-    }
-  ]
-}
diff --git a/workflows/models/flux-dev-fast.json b/workflows/models/flux-dev-fast.json
new file mode 100644
index 00000000..64a5954f
--- /dev/null
+++ b/workflows/models/flux-dev-fast.json
@@ -0,0 +1,75 @@
+{
+    "id": "FluxDevFast",
+    "description": "Flux dev tuned for speed on a 24GB card: int8 TorchAO quantization on the transformer (quantized directly onto the GPU - quantized tensors cannot be moved between devices, so it stays resident), regional torch.compile, first-block caching, and group offload for the T5 encoder. On Ada/40-series cards use Float8DynamicActivationFloat8WeightConfig instead of Int8WeightOnlyConfig.",
+    "configures": "templates/text-to-image",
+    "variables": {
+        "prompt": "a marmot wearing a tophat, in a forest scene.",
+        "num_inference_steps": 28,
+        "model_name": "black-forest-labs/FLUX.1-schnell"
+    },
+    "steps": [
+        {
+            "name": "main",
+            "pipeline": {
+                "configuration": {
+                    "component_type": "FluxPipeline",
+                    "cache": {
+                        "type": "first_block",
+                        "threshold": 0.05
+                    },
+                    "components": {
+                        "transformer": {
+                            "compile": {
+                                "repeated_blocks": true
+                            }
+                        },
+                        "text_encoder_2": {
+                            "group_offload": {
+                                "offload_type": "leaf_level",
+                                "use_stream": true
+                            }
+                        },
+                        "text_encoder": {
+                            "device": "cuda"
+                        },
+                        "vae": {
+                            "device": "cuda"
+                        }
+                    }
+                },
+                "transformer": {
+                    "configuration": {
+                        "component_type": "FluxTransformer2DModel",
+                        "preserve_device_placement": true
+                    },
+                    "quantization_config": {
+                        "configuration": {
+                            "config_type": "TorchAoConfig"
+                        },
+                        "arguments": {
+                            "quant_type": "torchao.quantization.Int8WeightOnlyConfig"
+                        }
+                    },
+                    "from_pretrained_arguments": {
+                        "model_name": "variable:model_name",
+                        "subfolder": "transformer",
+                        "torch_dtype": "torch.bfloat16",
+                        "device_map": "cuda"
+                    }
+                },
+                "from_pretrained_arguments": {
+                    "model_name": "variable:model_name",
+                    "torch_dtype": "torch.bfloat16"
+                },
+                "arguments": {
+                    "prompt": "variable:prompt",
+                    "num_inference_steps": "variable:num_inference_steps"
+                }
+            },
+            "result": {
+                "content_type": "image/jpeg",
+                "embed_metadata": true
+            }
+        }
+    ]
+}
diff --git a/workflows/flux/FluxDev.json b/workflows/models/flux-dev.json
similarity index 96%
rename from workflows/flux/FluxDev.json
rename to workflows/models/flux-dev.json
index 7f10ad70..083b6679 100644
--- a/workflows/flux/FluxDev.json
+++ b/workflows/models/flux-dev.json
@@ -9,6 +9,7 @@
     },
     "id": "FluxDev",
     "description": "Text-to-image with FLUX.1 dev - the reference FLUX workflow.",
+    "configures": "templates/text-to-image",
     "steps": [
         {
             "name": "txt2img",
@@ -37,4 +38,4 @@
             }
         }
     ]
-}
\ No newline at end of file
+}
diff --git a/workflows/flux/FluxGGUF.json b/workflows/models/flux-gguf.json
similarity index 97%
rename from workflows/flux/FluxGGUF.json
rename to workflows/models/flux-gguf.json
index 408caa1f..91104dd6 100644
--- a/workflows/flux/FluxGGUF.json
+++ b/workflows/models/flux-gguf.json
@@ -5,6 +5,7 @@
     },
     "id": "FluxGGUF",
     "description": "FLUX.1 dev loaded from a GGUF-quantized transformer checkpoint.",
+    "configures": "templates/text-to-image",
     "steps": [
         {
             "name": "main",
@@ -43,4 +44,4 @@
             }
         }
     ]
-}
\ No newline at end of file
+}
diff --git a/workflows/flux/FluxDevKrea.json b/workflows/models/flux-krea.json
similarity index 96%
rename from workflows/flux/FluxDevKrea.json
rename to workflows/models/flux-krea.json
index 26f1abf5..72f65e24 100644
--- a/workflows/flux/FluxDevKrea.json
+++ b/workflows/models/flux-krea.json
@@ -9,6 +9,7 @@
     },
     "id": "FluxDevKrea",
     "description": "Text-to-image with FLUX.1 Krea dev, tuned for photographic aesthetics.",
+    "configures": "templates/text-to-image",
     "steps": [
         {
             "name": "txt2img",
@@ -37,4 +38,4 @@
             }
         }
     ]
-}
\ No newline at end of file
+}
diff --git a/workflows/flux/FluxTorchAO.json b/workflows/models/flux-torchao.json
similarity index 97%
rename from workflows/flux/FluxTorchAO.json
rename to workflows/models/flux-torchao.json
index 6ad6f1ec..abb6e781 100644
--- a/workflows/flux/FluxTorchAO.json
+++ b/workflows/models/flux-torchao.json
@@ -4,6 +4,7 @@
     },
     "id": "FluxTorchAO",
     "description": "FLUX.1 dev with the transformer quantized to int8 via TorchAO.",
+    "configures": "templates/text-to-image",
     "steps": [
         {
             "name": "main",
@@ -51,4 +52,4 @@
             }
         }
     ]
-}
\ No newline at end of file
+}
diff --git a/workflows/flux/Flux2Dev.json b/workflows/models/flux2-dev.json
similarity index 96%
rename from workflows/flux/Flux2Dev.json
rename to workflows/models/flux2-dev.json
index 60c0596a..eec9152f 100644
--- a/workflows/flux/Flux2Dev.json
+++ b/workflows/models/flux2-dev.json
@@ -7,6 +7,7 @@
     },
     "id": "Flux2Dev",
     "description": "Text-to-image with FLUX.2 dev, pre-quantized to 4-bit BitsAndBytes.",
+    "configures": "templates/text-to-image",
     "steps": [
         {
             "name": "txt2img",
@@ -35,4 +36,4 @@
             }
         }
     ]
-}
\ No newline at end of file
+}
diff --git a/workflows/Krea2.json b/workflows/models/krea2.json
similarity index 95%
rename from workflows/Krea2.json
rename to workflows/models/krea2.json
index a3ab33c5..b76b649a 100644
--- a/workflows/Krea2.json
+++ b/workflows/models/krea2.json
@@ -4,6 +4,7 @@
     },
     "id": "Krea2",
     "description": "Text-to-image with Krea 2 Turbo - fast, few-step photorealistic generation.",
+    "configures": "templates/text-to-image",
     "steps": [
         {
             "name": "txt2img",
@@ -30,4 +31,4 @@
             }
         }
     ]
-}
\ No newline at end of file
+}
diff --git a/workflows/ZImageSDNQ.json b/workflows/models/z-image-sdnq.json
similarity index 97%
rename from workflows/ZImageSDNQ.json
rename to workflows/models/z-image-sdnq.json
index 6de894d1..b0a52306 100644
--- a/workflows/ZImageSDNQ.json
+++ b/workflows/models/z-image-sdnq.json
@@ -9,6 +9,7 @@
     },
     "id": "ZImageSDNQ",
     "description": "Z-Image Turbo pre-quantized to SDNQ uint4 - the same nine-step generation in a fraction of the VRAM.",
+    "configures": "templates/text-to-image",
     "steps": [
         {
             "name": "txt2img",
@@ -42,4 +43,4 @@
             }
         }
     ]
-}
\ No newline at end of file
+}
diff --git a/workflows/ZImage.json b/workflows/models/z-image.json
similarity index 97%
rename from workflows/ZImage.json
rename to workflows/models/z-image.json
index 92767920..8dca49f3 100644
--- a/workflows/ZImage.json
+++ b/workflows/models/z-image.json
@@ -12,6 +12,7 @@
     "seed": "variable:seed",
     "id": "ZImage",
     "description": "Text-to-image with Z-Image Turbo - photorealistic output in nine steps.",
+    "configures": "templates/text-to-image",
     "steps": [
         {
             "name": "txt2img",
diff --git a/workflows/templates/describe-and-regenerate.json b/workflows/templates/describe-and-regenerate.json
index a1f536d8..aa6d6a27 100644
--- a/workflows/templates/describe-and-regenerate.json
+++ b/workflows/templates/describe-and-regenerate.json
@@ -43,7 +43,7 @@
         {
             "name": "flux",
             "workflow": {
-                "path": "../flux/FluxDev.json",
+                "path": "../models/flux-dev.json",
                 "arguments": {
                     "prompt": "previous_result:augment_prompt",
                     "num_images_per_prompt": 1
diff --git a/workflows/ltx2/README.md b/workflows/templates/ltx2/README.md
similarity index 100%
rename from workflows/ltx2/README.md
rename to workflows/templates/ltx2/README.md
diff --git a/workflows/minimax/README.md b/workflows/templates/minimax/README.md
similarity index 100%
rename from workflows/minimax/README.md
rename to workflows/templates/minimax/README.md

From 38c62f0cadd1fc6f2deaf045f03e83345f73137a Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 15:07:23 -0500
Subject: [PATCH 13/32] Delete the checkpoint iterations and empty archive/

Every removed file was a further checkpoint through a pattern the tree
already demonstrates. Git history is the archive, so archive/ stops being
a graveyard that costs listing space. 121 workflows become 73.

compose-workflows.json named two archive workflows as its defaults, which
would have broken silently - it now points at surviving files.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 workflows/archive/Allegro.json             |  44 -------
 workflows/archive/CogVideoX-5B-I2V.json    |  41 ------
 workflows/archive/CogVideoX-5b.json        |  43 -------
 workflows/archive/CogVideoX1.5-5B-I2V.json |  93 --------------
 workflows/archive/CogVideoX1.5-5B.json     |  90 --------------
 workflows/archive/ErnieImageTurbo.json     |  40 ------
 workflows/archive/HunyuanVideo.json        |  54 --------
 workflows/archive/HunyuanVideoGguf.json    |  54 --------
 workflows/archive/Ideogram4.json           |  40 ------
 workflows/archive/Kolors.json              |  35 ------
 workflows/archive/Lumina.json              |  41 ------
 workflows/archive/Mochi.json               |  32 -----
 workflows/archive/NucleusAI.json           |  42 -------
 workflows/archive/QwenImageEdit.json       |  93 --------------
 workflows/archive/Wan22I2V14B.json         | 136 --------------------
 workflows/archive/Wan22T2V14B.json         |  99 ---------------
 workflows/archive/Wan22TI2V5B.json         |  43 -------
 workflows/archive/WanI2V14.json            | 138 ---------------------
 workflows/archive/WanT2V1.3.json           |  47 -------
 workflows/archive/WanT2V14.json            |  68 ----------
 workflows/archive/bnb_quant.json           |  58 ---------
 workflows/archive/hunyuan15.json           |  92 --------------
 workflows/archive/img2vid.json             | 124 ------------------
 workflows/archive/ip-adapter.json          |  68 ----------
 workflows/archive/kandinsky.json           |  79 ------------
 workflows/archive/kandinsky3.json          |  38 ------
 workflows/archive/kandinsky_i2i.json       |  48 -------
 workflows/archive/ltx.json                 |  32 -----
 workflows/archive/owl.json                 |  33 -----
 workflows/archive/sana.json                |  45 -------
 workflows/archive/sd15.json                |  32 -----
 workflows/archive/sd35.json                |  39 ------
 workflows/archive/sd35ip.json              |  80 ------------
 workflows/archive/sdxl_refiner.json        |  36 ------
 workflows/tasks/CaptionToImage.json        |  56 ---------
 workflows/tasks/DiffusionUpscale.json      |  60 ---------
 workflows/tasks/SpandrelUpscale.json       |  56 ---------
 workflows/templates/compose-workflows.json |  12 +-
 38 files changed, 6 insertions(+), 2255 deletions(-)
 delete mode 100644 workflows/archive/Allegro.json
 delete mode 100644 workflows/archive/CogVideoX-5B-I2V.json
 delete mode 100644 workflows/archive/CogVideoX-5b.json
 delete mode 100644 workflows/archive/CogVideoX1.5-5B-I2V.json
 delete mode 100644 workflows/archive/CogVideoX1.5-5B.json
 delete mode 100644 workflows/archive/ErnieImageTurbo.json
 delete mode 100644 workflows/archive/HunyuanVideo.json
 delete mode 100644 workflows/archive/HunyuanVideoGguf.json
 delete mode 100644 workflows/archive/Ideogram4.json
 delete mode 100644 workflows/archive/Kolors.json
 delete mode 100644 workflows/archive/Lumina.json
 delete mode 100644 workflows/archive/Mochi.json
 delete mode 100644 workflows/archive/NucleusAI.json
 delete mode 100644 workflows/archive/QwenImageEdit.json
 delete mode 100644 workflows/archive/Wan22I2V14B.json
 delete mode 100644 workflows/archive/Wan22T2V14B.json
 delete mode 100644 workflows/archive/Wan22TI2V5B.json
 delete mode 100644 workflows/archive/WanI2V14.json
 delete mode 100644 workflows/archive/WanT2V1.3.json
 delete mode 100644 workflows/archive/WanT2V14.json
 delete mode 100644 workflows/archive/bnb_quant.json
 delete mode 100644 workflows/archive/hunyuan15.json
 delete mode 100644 workflows/archive/img2vid.json
 delete mode 100644 workflows/archive/ip-adapter.json
 delete mode 100644 workflows/archive/kandinsky.json
 delete mode 100644 workflows/archive/kandinsky3.json
 delete mode 100644 workflows/archive/kandinsky_i2i.json
 delete mode 100644 workflows/archive/ltx.json
 delete mode 100644 workflows/archive/owl.json
 delete mode 100644 workflows/archive/sana.json
 delete mode 100644 workflows/archive/sd15.json
 delete mode 100644 workflows/archive/sd35.json
 delete mode 100644 workflows/archive/sd35ip.json
 delete mode 100644 workflows/archive/sdxl_refiner.json
 delete mode 100644 workflows/tasks/CaptionToImage.json
 delete mode 100644 workflows/tasks/DiffusionUpscale.json
 delete mode 100644 workflows/tasks/SpandrelUpscale.json

diff --git a/workflows/archive/Allegro.json b/workflows/archive/Allegro.json
deleted file mode 100644
index bab14eae..00000000
--- a/workflows/archive/Allegro.json
+++ /dev/null
@@ -1,44 +0,0 @@
-{
-    "id": "Allegro",
-    "description": "Text-to-video with Allegro.",
-    "steps": [
-        {
-            "name": "text_to_video",
-            "pipeline": {
-                "configuration": {
-                    "offload": "sequential",
-                    "component_type": "AllegroPipeline",
-                    "vae": {
-                        "enable_tiling": true,
-                        "enable_slicing": true
-                    }
-                },
-                "vae": {
-                    "configuration": {
-                        "component_type": "AutoencoderKLAllegro"
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "rhymes-ai/Allegro",
-                        "subfolder": "vae",
-                        "torch_dtype": "torch.float32"
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "rhymes-ai/Allegro",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "a marmot wearing a hat, with him blinking slowly. Ultra high resolution 4k.",
-                    "negative_prompt": "nsfw, lowres, bad anatomy, bad hands, text, error, missing fingers, extra digit, fewer digits, cropped, worst quality, low quality, normal quality, jpeg artifacts, signature, watermark, username, blurry",
-                    "guidance_scale": 7.5,
-                    "max_sequence_length": 512,
-                    "num_inference_steps": 25
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 15
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/CogVideoX-5B-I2V.json b/workflows/archive/CogVideoX-5B-I2V.json
deleted file mode 100644
index 5c3fbbd9..00000000
--- a/workflows/archive/CogVideoX-5B-I2V.json
+++ /dev/null
@@ -1,41 +0,0 @@
-{
-    "variables": {
-        "image": {
-            "location": "https://pbs.twimg.com/profile_images/1833270307039105025/aKnawnm-_400x400.jpg"
-        },
-        "prompt": "the super hero stands heroically as fireworks explode around him and he smiles and winks",
-        "num_inference_steps": 50
-    },
-    "id": "CogVideoX-5B-I2V",
-    "description": "Image-to-video with CogVideoX 5B.",
-    "steps": [
-        {
-            "name": "img2vid",
-            "pipeline": {
-                "configuration": {
-                    "offload": "sequential",
-                    "component_type": "CogVideoXImageToVideoPipeline",
-                    "vae": {
-                        "enable_slicing": true,
-                        "enable_tiling": true
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "THUDM/CogVideoX-5B-I2V",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "image": "variable:image",
-                    "prompt": "variable:prompt",
-                    "num_videos_per_prompt": 1,
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "num_frames": 49,
-                    "guidance_scale": 6
-                }
-            },
-            "result": {
-                "content_type": "video/mp4"
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/CogVideoX-5b.json b/workflows/archive/CogVideoX-5b.json
deleted file mode 100644
index b45d4588..00000000
--- a/workflows/archive/CogVideoX-5b.json
+++ /dev/null
@@ -1,43 +0,0 @@
-{
-    "id": "CogVideoX-5b",
-    "description": "Text-to-video with CogVideoX 5B.",
-    "steps": [
-        {
-            "name": "gather_prompts",
-            "task": {
-                "command": "gather_inputs",
-                "inputs": [
-                    "Photorealisitc movie trailer, urban city with high-rise buildings, tracking shot of a marmot driving a cycle, intricate details photographed by professional directors",
-                    "Photorealisitc movie trailer, tracking shot of a bug driving a cycle, intricate details photographed by professional directors"
-                ]
-            }
-        },
-        {
-            "name": "text_to_video",
-            "pipeline": {
-                "configuration": {
-                    "offload": "sequential",
-                    "component_type": "CogVideoXPipeline",
-                    "vae": {
-                        "enable_slicing": true,
-                        "enable_tiling": true
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "THUDM/CogVideoX-5b",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "previous_result:gather_prompts",
-                    "num_videos_per_prompt": 1,
-                    "num_inference_steps": 5,
-                    "num_frames": 49,
-                    "guidance_scale": 6
-                }
-            },
-            "result": {
-                "content_type": "video/mp4"
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/CogVideoX1.5-5B-I2V.json b/workflows/archive/CogVideoX1.5-5B-I2V.json
deleted file mode 100644
index db32f512..00000000
--- a/workflows/archive/CogVideoX1.5-5B-I2V.json
+++ /dev/null
@@ -1,93 +0,0 @@
-{
-    "variables": {
-        "model_name": "THUDM/CogVideoX1.5-5B-I2V"
-    },
-    "id": "CogVideoX1.5-5B-I2V",
-    "description": "Image-to-video with CogVideoX 1.5 5B, int8-quantized via TorchAO.",
-    "steps": [
-        {
-            "name": "image_to_video",
-            "pipeline": {
-                "configuration": {
-                    "offload": "model",
-                    "component_type": "CogVideoXImageToVideoPipeline",
-                    "vae": {
-                        "enable_slicing": true,
-                        "enable_tiling": true
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "variable:model_name",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "transformer": {
-                    "configuration": {
-                        "component_type": "CogVideoXTransformer3DModel"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "TorchAoConfig"
-                        },
-                        "arguments": {
-                            "quant_type": "{int8wo}"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "transformer",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "vae": {
-                    "configuration": {
-                        "component_type": "AutoencoderKLCogVideoX"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "TorchAoConfig"
-                        },
-                        "arguments": {
-                            "quant_type": "{int8wo}"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "vae",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "text_encoder": {
-                    "configuration": {
-                        "component_type": "transformers.T5EncoderModel"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "TorchAoConfig"
-                        },
-                        "arguments": {
-                            "quant_type": "{int8wo}"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "text_encoder",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "arguments": {
-                    "image": {
-                        "location": "https://pbs.twimg.com/media/GcpCDN8asAA9V2U?format=jpg&name=medium"
-                    },
-                    "prompt": "the diamond spins",
-                    "num_videos_per_prompt": 1,
-                    "num_inference_steps": 35,
-                    "num_frames": 49,
-                    "guidance_scale": 6
-                }
-            },
-            "result": {
-                "content_type": "video/mp4"
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/CogVideoX1.5-5B.json b/workflows/archive/CogVideoX1.5-5B.json
deleted file mode 100644
index 9f37f0d2..00000000
--- a/workflows/archive/CogVideoX1.5-5B.json
+++ /dev/null
@@ -1,90 +0,0 @@
-{
-    "variables": {
-        "model_name": "THUDM/CogVideoX1.5-5B"
-    },
-    "id": "CogVideoX1.5-5B",
-    "description": "Text-to-video with CogVideoX 1.5 5B, int8-quantized via TorchAO.",
-    "steps": [
-        {
-            "name": "text_to_video",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "CogVideoXPipeline",
-                    "offload": "model",
-                    "vae": {
-                        "enable_slicing": true,
-                        "enable_tiling": true
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "variable:model_name",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "transformer": {
-                    "configuration": {
-                        "component_type": "CogVideoXTransformer3DModel"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "TorchAoConfig"
-                        },
-                        "arguments": {
-                            "quant_type": "{int4wo}"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "transformer",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "vae": {
-                    "configuration": {
-                        "component_type": "AutoencoderKLCogVideoX"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "TorchAoConfig"
-                        },
-                        "arguments": {
-                            "quant_type": "{int4wo}"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "vae",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "text_encoder": {
-                    "configuration": {
-                        "component_type": "transformers.T5EncoderModel"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "TorchAoConfig"
-                        },
-                        "arguments": {
-                            "quant_type": "{int4wo}"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "text_encoder",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "arguments": {
-                    "prompt": "the diamond spins",
-                    "num_videos_per_prompt": 1,
-                    "num_inference_steps": 35,
-                    "num_frames": 49,
-                    "guidance_scale": 6
-                }
-            },
-            "result": {
-                "content_type": "video/mp4"
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/ErnieImageTurbo.json b/workflows/archive/ErnieImageTurbo.json
deleted file mode 100644
index ab99658e..00000000
--- a/workflows/archive/ErnieImageTurbo.json
+++ /dev/null
@@ -1,40 +0,0 @@
-{
-    "variables": {
-        "prompt": "A photorealistic, cinematic wide shot of a futuristic, bio-mechanical daffodil housed inside a massive, transparent glass dome on the dark ocean floor. The daffodil has iridescent, metallic petals and glowing fiber-optic stamens that emit a soft golden light. Outside the thick glass of the dome, the deep sea is filled with glowing, bioluminescent jellyfish and shimmering blue sea creatures, casting ethereal light patterns through the water. The ocean floor is covered in dark sand and ancient coral. Dramatic lighting with caustic light refractions from the water, high detail, 8k resolution, hyper-realistic.",
-        "num_images_per_prompt": 1,
-        "num_inference_steps": 8,
-        "guidance_scale": 1.0,
-        "width": 848,
-        "height": 1264
-    },
-    "id": "ErnieImageTurbo",
-    "description": "Text-to-image with ERNIE Image Turbo.",
-    "steps": [
-        {
-            "name": "txt2img",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "ErnieImagePipeline",
-                    "offload": "sequential"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "Baidu/ERNIE-Image-Turbo",
-                    "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",
-                    "guidance_scale": "variable:guidance_scale",
-                    "use_pe": true
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/HunyuanVideo.json b/workflows/archive/HunyuanVideo.json
deleted file mode 100644
index d1d0d4c6..00000000
--- a/workflows/archive/HunyuanVideo.json
+++ /dev/null
@@ -1,54 +0,0 @@
-{
-    "id": "HunyuanVideo",
-    "description": "Text-to-video with HunyuanVideo, 4-bit quantized.",
-    "variables": {
-        "prompt": "A lone marmot walks across vast, green forest landscape under a clear blue sky. The camera begins with a wide shot, capturing the endless forests, then slowly zooms in on the marmot as it moves gracefully. The soft wind blows sand into gentle waves, adding motion to the scene. The atmosphere is serene and timeless, emphasizing the beauty of the forest. Bright sunlight casts sharp shadows on the trees, creating striking contrasts. The shot transitions from a wide view of the forest  to a medium shot of the marmot, framed against the soaring trees."
-    },
-    "steps": [
-        {
-            "name": "text_to_video",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "HunyuanVideoPipeline",
-                    "offload": "model",
-                    "vae": {
-                        "enable_tiling": true
-                    }
-                },
-                "transformer": {
-                    "configuration": {
-                        "component_type": "HunyuanVideoTransformer3DModel"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "BitsAndBytesConfig"
-                        },
-                        "arguments": {
-                            "load_in_8bit": true
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "hunyuanvideo-community/HunyuanVideo",
-                        "subfolder": "transformer",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "hunyuanvideo-community/HunyuanVideo",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "height": 320,
-                    "width": 512,
-                    "num_inference_steps": 30,
-                    "num_frames": 61
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 15
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/HunyuanVideoGguf.json b/workflows/archive/HunyuanVideoGguf.json
deleted file mode 100644
index 65b8598f..00000000
--- a/workflows/archive/HunyuanVideoGguf.json
+++ /dev/null
@@ -1,54 +0,0 @@
-{
-    "id": "HunyuanVideoGguf",
-    "description": "HunyuanVideo from a GGUF-quantized checkpoint.",
-    "variables": {
-        "prompt": "A lone marmot walks across vast, green forest landscape under a clear blue sky. The camera begins with a wide shot, capturing the endless forests, then slowly zooms in on the marmot as it moves gracefully. The soft wind blows sand into gentle waves, adding motion to the scene. The atmosphere is serene and timeless, emphasizing the beauty of the forest. Bright sunlight casts sharp shadows on the trees, creating striking contrasts. The shot transitions from a wide view of the forest  to a medium shot of the marmot, framed against the soaring trees."
-    },
-    "steps": [
-        {
-            "name": "text_to_video",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "HunyuanVideoPipeline",
-                    "offload": "model",
-                    "vae": {
-                        "enable_slicing": true,
-                        "enable_tiling": true
-                    }
-                },
-                "transformer": {
-                    "configuration": {
-                        "component_type": "HunyuanVideoTransformer3DModel"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "GGUFQuantizationConfig"
-                        },
-                        "arguments": {
-                            "compute_dtype": "torch.bfloat16"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "from_single_file": "https://huggingface.co/city96/HunyuanVideo-gguf/blob/main/hunyuan-video-t2v-720p-Q6_K.gguf",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "hunyuanvideo-community/HunyuanVideo",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "height": 320,
-                    "width": 512,
-                    "num_inference_steps": 30,
-                    "num_frames": 129
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 15
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/Ideogram4.json b/workflows/archive/Ideogram4.json
deleted file mode 100644
index 18de8b29..00000000
--- a/workflows/archive/Ideogram4.json
+++ /dev/null
@@ -1,40 +0,0 @@
-{
-    "variables": {
-        "prompt": "a picture of a marmot in a top hat, holding a sign saying the 'i for one welcome our new robot overlords'"
-    },
-    "id": "Ideogram4",
-    "description": "Text-to-image with Ideogram 4 from an nf4-quantized checkpoint.",
-    "steps": [
-        {
-            "name": "txt2img",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "Ideogram4Pipeline"
-                },
-                "prompt_enhancer_head": {
-                    "configuration": {
-                        "component_type": "Ideogram4PromptEnhancerHead"
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "diffusers/qwen3-vl-8b-instruct-lm-head",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "ideogram-ai/ideogram-4-nf4-diffusers",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "height": 1024,
-                    "width": 1024,
-                    "prompt_upsampling": true
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/Kolors.json b/workflows/archive/Kolors.json
deleted file mode 100644
index 06f3c552..00000000
--- a/workflows/archive/Kolors.json
+++ /dev/null
@@ -1,35 +0,0 @@
-{
-    "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": 25,
-        "guidance_scale": 6.5
-    },
-    "id": "Kolors",
-    "description": "Text-to-image with Kolors.",
-    "steps": [
-        {
-            "name": "txt2img",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "KolorsPipeline"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "Kwai-Kolors/Kolors-diffusers",
-                    "torch_dtype": "torch.float16",
-                    "variant": "fp16"
-                },
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "num_images_per_prompt": "variable:num_images_per_prompt",
-                    "guidance_scale": "variable:guidance_scale"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/Lumina.json b/workflows/archive/Lumina.json
deleted file mode 100644
index aa4c8842..00000000
--- a/workflows/archive/Lumina.json
+++ /dev/null
@@ -1,41 +0,0 @@
-{
-    "variables": {
-        "prompt": "Image of a marmot in a bull costume holding a sign that says 'i'm bullish on chia'",
-        "num_images_per_prompt": 1,
-        "num_inference_steps": 50,
-        "guidance_scale": 3.5,
-        "width": 1024,
-        "height": 1024
-    },
-    "id": "Lumina",
-    "description": "Text-to-image with Lumina Image 2.0.",
-    "steps": [
-        {
-            "name": "txt2img",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "Lumina2Text2ImgPipeline",
-                    "offload": "model"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "Alpha-VLLM/Lumina-Image-2.0",
-                    "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",
-                    "guidance_scale": "variable:guidance_scale",
-                    "cfg_trunc_ratio": 0.25,
-                    "cfg_normalization": true
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/Mochi.json b/workflows/archive/Mochi.json
deleted file mode 100644
index abc17eb1..00000000
--- a/workflows/archive/Mochi.json
+++ /dev/null
@@ -1,32 +0,0 @@
-{
-    "id": "Mochi",
-    "description": "Text-to-video with Mochi 1.",
-    "steps": [
-        {
-            "name": "text_to_video",
-            "pipeline": {
-                "configuration": {
-                    "offload": "sequential",
-                    "component_type": "MochiPipeline",
-                    "vae": {
-                        "enable_tiling": true,
-                        "enable_slicing": true
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "genmo/mochi-1-preview",
-                    "variant": "bf16",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "Close-up of a marmot wearing a hat, with him blinking slowly. Ultra high resolution 4k.",
-                    "num_frames": 85
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 30
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/NucleusAI.json b/workflows/archive/NucleusAI.json
deleted file mode 100644
index 8a0e3901..00000000
--- a/workflows/archive/NucleusAI.json
+++ /dev/null
@@ -1,42 +0,0 @@
-{
-    "variables": {
-        "prompt": "A photorealistic, cinematic wide shot of a futuristic, bio-mechanical daffodil housed inside a massive, transparent glass dome on the dark ocean floor. The daffodil has iridescent, metallic petals and glowing fiber-optic stamens that emit a soft golden light. Outside the thick glass of the dome, the deep sea is filled with glowing, bioluminescent jellyfish and shimmering blue sea creatures, casting ethereal light patterns through the water. The ocean floor is covered in dark sand and ancient coral. Dramatic lighting with caustic light refractions from the water, high detail, 8k resolution, hyper-realistic.",
-        "num_images_per_prompt": 1,
-        "num_inference_steps": 50,
-        "guidance_scale": 4.0,
-        "width": 1344,
-        "height": 768
-    },
-    "id": "NucleusAI",
-    "description": "Text-to-image with Nucleus, using text-KV caching.",
-    "steps": [
-        {
-            "name": "txt2img",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "DiffusionPipeline",
-                    "offload": "sequential",
-                    "cache": {
-                        "type": "text_kv"
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "NucleusAI/Nucleus-Image",
-                    "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",
-                    "guidance_scale": "variable:guidance_scale"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/QwenImageEdit.json b/workflows/archive/QwenImageEdit.json
deleted file mode 100644
index d3ebb6ef..00000000
--- a/workflows/archive/QwenImageEdit.json
+++ /dev/null
@@ -1,93 +0,0 @@
-{
-    "id": "QwenImageEdit",
-    "description": "Instruction-based image editing with Qwen Image Edit Plus, LoRA-accelerated and 4-bit quantized.",
-    "variables": {
-        "model_name": "Qwen/Qwen-Image-Edit-2509",
-        "prompt": "the dragon in the image is flying in the sky over the man giving a speech",
-        "first_image": {
-            "location": "https://as2.ftcdn.net/v2/jpg/05/62/00/49/1000_F_562004924_e7isCRgRekdrQY10DYrAb2M0g7lPL3lD.jpg"
-        },
-        "second_image": {
-            "location": "https://images.wsj.net/im-628212/IM?width=1300&height=975"
-        },
-        "guidance_scale": 1.0
-    },
-    "steps": [
-        {
-            "name": "edit_image",
-            "pipeline": {
-                "transformer": {
-                    "configuration": {
-                        "component_type": "QwenImageTransformer2DModel"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "BitsAndBytesConfig"
-                        },
-                        "arguments": {
-                            "load_in_4bit": true,
-                            "bnb_4bit_quant_type": "{nf4}",
-                            "bnb_4bit_compute_dtype": "torch.bfloat16",
-                            "llm_int8_skip_modules": [
-                                "transformer_blocks.0.img_mod"
-                            ]
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "transformer",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "text_encoder": {
-                    "configuration": {
-                        "component_type": "transformers.Qwen2_5_VLForConditionalGeneration"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "BitsAndBytesConfig"
-                        },
-                        "arguments": {
-                            "load_in_4bit": true,
-                            "bnb_4bit_quant_type": "{nf4}",
-                            "bnb_4bit_compute_dtype": "torch.bfloat16"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "text_encoder",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "configuration": {
-                    "component_type": "QwenImageEditPlusPipeline",
-                    "offload": "model"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "variable:model_name",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "loras": [
-                    {
-                        "model_name": "lightx2v/Qwen-Image-Lightning",
-                        "weight_name": "Qwen-Image-Lightning-8steps-V1.1.safetensors"
-                    }
-                ],
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "num_inference_steps": 8,
-                    "image": [
-                        "variable:first_image",
-                        "variable:second_image"
-                    ],
-                    "true_cfg_scale": 4.0,
-                    "guidance_scale": "variable:guidance_scale"
-                }
-            },
-            "result": {
-                "content_type": "image/png",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/Wan22I2V14B.json b/workflows/archive/Wan22I2V14B.json
deleted file mode 100644
index a419f348..00000000
--- a/workflows/archive/Wan22I2V14B.json
+++ /dev/null
@@ -1,136 +0,0 @@
-{
-    "id": "Wan22I2V14B",
-    "description": "Image-to-video with Wan 2.2 14B, LoRA-accelerated and 4-bit quantized.",
-    "variables": {
-        "model_name": "Wan-AI/Wan2.2-I2V-A14B-Diffusers",
-        "prompt": "The marmot growls at the camera, holding a sign that says 'On-chain rage baiting only 23 mojos!!' in a forest setting, highly detailed, photorealistic, 8k, sharp focus, vibrant colors, dramatic lighting",
-        "negative_prompt": "Bright tones, overexposed, static, blurred details, subtitles, style, works, paintings, images, static, overall gray, worst quality, low quality, JPEG compression residue, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn faces, deformed, disfigured, misshapen limbs, fused fingers, still picture, messy background, three legs, many people in the background, walking backwards",
-        "image": {
-            "location": "https://pbs.twimg.com/media/G6h8Ji7WIAAfzXN?format=png&name=900x900"
-        },
-        "num_inference_steps": 4
-    },
-    "steps": [
-        {
-            "name": "image_to_video",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "WanImageToVideoPipeline",
-                    "offload": "model"
-                },
-                "vae": {
-                    "configuration": {
-                        "component_type": "AutoencoderKLWan",
-                        "device": "cpu"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "BitsAndBytesConfig"
-                        },
-                        "arguments": {
-                            "load_in_4bit": true,
-                            "bnb_4bit_quant_type": "{nf4}",
-                            "bnb_4bit_compute_dtype": "torch.bfloat16"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "vae",
-                        "torch_dtype": "torch.float32"
-                    }
-                },
-                "transformer": {
-                    "configuration": {
-                        "component_type": "WanTransformer3DModel"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "BitsAndBytesConfig"
-                        },
-                        "arguments": {
-                            "load_in_4bit": true,
-                            "bnb_4bit_quant_type": "{nf4}",
-                            "bnb_4bit_compute_dtype": "torch.bfloat16"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "transformer",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "transformer_2": {
-                    "configuration": {
-                        "component_type": "WanTransformer3DModel"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "BitsAndBytesConfig"
-                        },
-                        "arguments": {
-                            "load_in_4bit": true,
-                            "bnb_4bit_quant_type": "{nf4}",
-                            "bnb_4bit_compute_dtype": "torch.bfloat16"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "transformer_2",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "text_encoder": {
-                    "configuration": {
-                        "component_type": "transformers.UMT5EncoderModel",
-                        "device": "cpu"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "BitsAndBytesConfig"
-                        },
-                        "arguments": {
-                            "load_in_4bit": true,
-                            "bnb_4bit_quant_type": "{nf4}",
-                            "bnb_4bit_compute_dtype": "torch.bfloat16"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "text_encoder",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "loras": [
-                    {
-                        "model_name": "lightx2v/Wan2.2-Distill-Loras",
-                        "weight_name": "wan2.2_i2v_A14b_high_noise_lora_rank64_lightx2v_4step_1022.safetensors",
-                        "scale": 0.5
-                    },
-                    {
-                        "model_name": "lightx2v/Wan2.2-Distill-Loras",
-                        "weight_name": "wan2.2_i2v_A14b_low_noise_lora_rank64_lightx2v_4step_1022.safetensors",
-                        "scale": 0.5
-                    }
-                ],
-                "from_pretrained_arguments": {
-                    "model_name": "variable:model_name",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "negative_prompt": "variable:negative_prompt",
-                    "guidance_scale": 5.0,
-                    "num_frames": 121,
-                    "image": "variable:image",
-                    "width": 640,
-                    "height": 480,
-                    "num_inference_steps": "variable:num_inference_steps"
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/Wan22T2V14B.json b/workflows/archive/Wan22T2V14B.json
deleted file mode 100644
index 909ff164..00000000
--- a/workflows/archive/Wan22T2V14B.json
+++ /dev/null
@@ -1,99 +0,0 @@
-{
-    "id": "Wan22T2V14B",
-    "description": "Text-to-video with Wan 2.2 14B, 4-bit quantized.",
-    "variables": {
-        "model_name": "Wan-AI/Wan2.2-T2V-A14B-Diffusers",
-        "prompt": "Over-the-shoulder shot. A man in a white shirt and brown vest stands, A man in a white shirt and a brown vest stands by a fireplace, looking at someone to the right.",
-        "num_inference_steps": 40
-    },
-    "steps": [
-        {
-            "name": "text_to_video",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "WanPipeline",
-                    "offload": "model"
-                },
-                "vae": {
-                    "configuration": {
-                        "component_type": "AutoencoderKLWan",
-                        "device": "cpu"
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "vae",
-                        "torch_dtype": "torch.float32"
-                    }
-                },
-                "transformer": {
-                    "configuration": {
-                        "component_type": "WanTransformer3DModel"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "BitsAndBytesConfig"
-                        },
-                        "arguments": {
-                            "load_in_4bit": true,
-                            "bnb_4bit_quant_type": "{nf4}",
-                            "bnb_4bit_compute_dtype": "torch.bfloat16"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "transformer",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "transformer_2": {
-                    "configuration": {
-                        "component_type": "WanTransformer3DModel"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "BitsAndBytesConfig"
-                        },
-                        "arguments": {
-                            "load_in_4bit": true,
-                            "bnb_4bit_quant_type": "{nf4}",
-                            "bnb_4bit_compute_dtype": "torch.bfloat16"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "transformer_2",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "text_encoder": {
-                    "configuration": {
-                        "component_type": "transformers.UMT5EncoderModel",
-                        "device": "cpu"
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "text_encoder",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "variable:model_name",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "guidance_scale": 4.0,
-                    "guidance_scale_2": 3.0,
-                    "num_frames": 121,
-                    "width": 640,
-                    "height": 480,
-                    "num_inference_steps": "variable:num_inference_steps"
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/Wan22TI2V5B.json b/workflows/archive/Wan22TI2V5B.json
deleted file mode 100644
index 6714647d..00000000
--- a/workflows/archive/Wan22TI2V5B.json
+++ /dev/null
@@ -1,43 +0,0 @@
-{
-    "id": "Wan22TI2V5B",
-    "description": "Text- or image-to-video with the Wan 2.2 5B TI2V model.",
-    "variables": {
-        "model_name": "Wan-AI/Wan2.2-TI2V-5B-Diffusers",
-        "num_inference_steps": 50,
-        "guidance_scale": 5.0,
-        "prompt": "Two anthropomorphic marmots in comfy boxing gear and bright gloves fight intensely on a spotlighted stage.",
-        "negative_prompt": "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走",
-        "image": {
-            "location": "https://pbs.twimg.com/media/G6h8Ji7WIAAfzXN?format=png&name=900x900"
-        }
-    },
-    "steps": [
-        {
-            "name": "2TI2V5B",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "WanPipeline",
-                    "offload": "model",
-                    "attention_backend": "flash_hub"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "variable:model_name",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "negative_prompt": "variable:negative_prompt",
-                    "height": 704,
-                    "width": 1280,
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "num_frames": 121,
-                    "guidance_scale": "variable:guidance_scale"
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/WanI2V14.json b/workflows/archive/WanI2V14.json
deleted file mode 100644
index a6f1d360..00000000
--- a/workflows/archive/WanI2V14.json
+++ /dev/null
@@ -1,138 +0,0 @@
-{
-    "id": "WanI2V14",
-    "description": "Outpaints a portrait to widescreen with FLUX Fill, then animates it with Wan 14B image-to-video.",
-    "variables": {
-        "model_name": "Wan-AI/Wan2.1-I2V-14B-480P-Diffusers",
-        "prompt": "The sand dragon turns to the camera and roars",
-        "negative_prompt": "Bright tones, overexposed, static, blurred details, subtitles, style, works, paintings, images, static, overall gray, worst quality, low quality, JPEG compression residue, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn faces, deformed, disfigured, misshapen limbs, fused fingers, still picture, messy background, three legs, many people in the background, walking backwards",
-        "image": {
-            "location": "https://pbs.twimg.com/media/GkRVQJfWUAAxITD?format=png&name=900x900"
-        },
-        "height": 480,
-        "width": 832,
-        "num_inference_steps": 25
-    },
-    "steps": [
-        {
-            "name": "mask_image",
-            "task": {
-                "command": "add_border_and_mask_with_size",
-                "arguments": {
-                    "image": {
-                        "location": "variable:image"
-                    },
-                    "height": "variable:height",
-                    "width": "variable:width"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        },
-        {
-            "name": "outpaint",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "FluxFillPipeline",
-                    "offload": "sequential"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "black-forest-labs/FLUX.1-Fill-dev",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "image": "previous_result:mask_image.bordered_image",
-                    "mask_image": "previous_result:mask_image.mask",
-                    "prompt": "",
-                    "guidance_scale": 30,
-                    "num_inference_steps": 25,
-                    "max_sequence_length": 512,
-                    "height": "variable:height",
-                    "width": "variable:width"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        },
-        {
-            "name": "image_to_video",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "WanImageToVideoPipeline",
-                    "offload": "model"
-                },
-                "vae": {
-                    "configuration": {
-                        "component_type": "AutoencoderKLWan"
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "vae",
-                        "torch_dtype": "torch.float32"
-                    }
-                },
-                "image_encoder": {
-                    "configuration": {
-                        "component_type": "transformers.CLIPVisionModelWithProjection"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "BitsAndBytesConfig"
-                        },
-                        "arguments": {
-                            "load_in_4bit": true,
-                            "bnb_4bit_quant_type": "{nf4}",
-                            "bnb_4bit_compute_dtype": "torch.bfloat16"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "image_encoder",
-                        "torch_dtype": "torch.float32"
-                    }
-                },
-                "transformer": {
-                    "configuration": {
-                        "component_type": "WanTransformer3DModel"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "BitsAndBytesConfig"
-                        },
-                        "arguments": {
-                            "load_in_4bit": true,
-                            "bnb_4bit_quant_type": "{nf4}",
-                            "bnb_4bit_compute_dtype": "torch.bfloat16"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "transformer",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "variable:model_name",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "negative_prompt": "variable:negative_prompt",
-                    "guidance_scale": 5.0,
-                    "num_frames": 81,
-                    "image": "previous_result:outpaint",
-                    "height": "variable:height",
-                    "width": "variable:width",
-                    "num_inference_steps": "variable:num_inference_steps"
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 15
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/WanT2V1.3.json b/workflows/archive/WanT2V1.3.json
deleted file mode 100644
index 27c9b44b..00000000
--- a/workflows/archive/WanT2V1.3.json
+++ /dev/null
@@ -1,47 +0,0 @@
-{
-    "id": "WanT2V1.3",
-    "description": "Text-to-video with the small Wan 1.3B model.",
-    "variables": {
-        "model_name": "Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
-        "prompt": "A lone marmot walks across vast, green forest landscape under a clear blue sky. The camera begins with a wide shot, capturing the endless forests, then slowly zooms in on the marmot as it moves gracefully. The soft wind blows sand into gentle waves, adding motion to the scene. The atmosphere is serene and timeless, emphasizing the beauty of the forest. Bright sunlight casts sharp shadows on the trees, creating striking contrasts. The shot transitions from a wide view of the forest  to a medium shot of the marmot, framed against the soaring trees.",
-        "negative_prompt": "Bright tones, overexposed, static, blurred details, subtitles, style, works, paintings, images, static, overall gray, worst quality, low quality, JPEG compression residue, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn faces, deformed, disfigured, misshapen limbs, fused fingers, still picture, messy background, three legs, many people in the background, walking backwards",
-        "height": 480,
-        "width": 832
-    },
-    "steps": [
-        {
-            "name": "text_to_video",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "WanPipeline"
-                },
-                "vae": {
-                    "configuration": {
-                        "component_type": "AutoencoderKLWan"
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "vae",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "variable:model_name",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "negative_prompt": "variable:negative_prompt",
-                    "height": "variable:height",
-                    "width": "variable:width",
-                    "guidance_scale": 5.0,
-                    "num_frames": 81
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 15
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/WanT2V14.json b/workflows/archive/WanT2V14.json
deleted file mode 100644
index 0f4cd3e6..00000000
--- a/workflows/archive/WanT2V14.json
+++ /dev/null
@@ -1,68 +0,0 @@
-{
-    "id": "WanT2V14",
-    "description": "Text-to-video with Wan 14B, 4-bit quantized.",
-    "variables": {
-        "model_name": "Wan-AI/Wan2.1-T2V-14B-Diffusers",
-        "prompt": "A lone marmot walks across vast, green forest landscape under a clear blue sky. The camera begins with a wide shot, capturing the endless forests, then slowly zooms in on the marmot as it moves gracefully. The soft wind blows sand into gentle waves, adding motion to the scene. The atmosphere is serene and timeless, emphasizing the beauty of the forest. Bright sunlight casts sharp shadows on the trees, creating striking contrasts. The shot transitions from a wide view of the forest  to a medium shot of the marmot, framed against the soaring trees.",
-        "negative_prompt": "Bright tones, overexposed, static, blurred details, subtitles, style, works, paintings, images, static, overall gray, worst quality, low quality, JPEG compression residue, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn faces, deformed, disfigured, misshapen limbs, fused fingers, still picture, messy background, three legs, many people in the background, walking backwards",
-        "height": 480,
-        "width": 832
-    },
-    "steps": [
-        {
-            "name": "text_to_video",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "WanPipeline",
-                    "offload": "model"
-                },
-                "vae": {
-                    "configuration": {
-                        "component_type": "AutoencoderKLWan"
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "vae",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "transformer": {
-                    "configuration": {
-                        "component_type": "WanTransformer3DModel"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "BitsAndBytesConfig"
-                        },
-                        "arguments": {
-                            "load_in_4bit": true,
-                            "bnb_4bit_quant_type": "{nf4}",
-                            "bnb_4bit_compute_dtype": "torch.bfloat16"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "transformer",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "variable:model_name",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "negative_prompt": "variable:negative_prompt",
-                    "height": "variable:height",
-                    "width": "variable:width",
-                    "guidance_scale": 5.0,
-                    "num_frames": 81
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 15
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/bnb_quant.json b/workflows/archive/bnb_quant.json
deleted file mode 100644
index 42ef4426..00000000
--- a/workflows/archive/bnb_quant.json
+++ /dev/null
@@ -1,58 +0,0 @@
-{
-    "variables": {
-        "prompt": "cubart a leaf"
-    },
-    "id": "sd35",
-    "description": "SD 3.5 Large 4-bit quantized with BitsAndBytes, plus a LoRA.",
-    "steps": [
-        {
-            "name": "main",
-            "pipeline": {
-                "transformer": {
-                    "configuration": {
-                        "component_type": "SD3Transformer2DModel"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "BitsAndBytesConfig"
-                        },
-                        "arguments": {
-                            "load_in_4bit": true,
-                            "bnb_4bit_quant_type": "{nf4}",
-                            "bnb_4bit_compute_dtype": "torch.bfloat16"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "stabilityai/stable-diffusion-3.5-large",
-                        "subfolder": "transformer",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "configuration": {
-                    "component_type": "StableDiffusion3Pipeline"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "stabilityai/stable-diffusion-3.5-large",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "loras": [
-                    {
-                        "model_name": "crystalwizard/cubic-abstract-1",
-                        "weight_name": "cubic-abstract-lora.safetensors"
-                    }
-                ],
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "num_inference_steps": 25,
-                    "guidance_scale": 4.5,
-                    "max_sequence_length": 512,
-                    "num_images_per_prompt": 1
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/hunyuan15.json b/workflows/archive/hunyuan15.json
deleted file mode 100644
index 2f720dd1..00000000
--- a/workflows/archive/hunyuan15.json
+++ /dev/null
@@ -1,92 +0,0 @@
-{
-    "id": "hunyuan15",
-    "description": "Text-to-video with HunyuanVideo 1.5, 4-bit quantized.",
-    "variables": {
-        "checkpoint_path": "https://huggingface.co/Comfy-Org/HunyuanVideo_1.5_repackaged/resolve/main/split_files/vae/hunyuanvideo15_vae_fp16.safetensors",
-        "num_inference_steps": 1,
-        "model_name": "hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v_distilled",
-        "prompt": "A lone marmot walks across vast, green forest landscape under a clear blue sky. The camera begins with a wide shot, capturing the endless forests, then slowly zooms in on the marmot as it moves gracefully. The soft wind blows sand into gentle waves, adding motion to the scene. The atmosphere is serene and timeless, emphasizing the beauty of the forest. Bright sunlight casts sharp shadows on the trees, creating striking contrasts. The shot transitions from a wide view of the forest  to a medium shot of the marmot, framed against the soaring trees."
-    },
-    "steps": [
-        {
-            "name": "text_to_video",
-            "pipeline": {
-                "transformer": {
-                    "configuration": {
-                        "component_type": "HunyuanVideo15Transformer3DModel"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "BitsAndBytesConfig"
-                        },
-                        "arguments": {
-                            "load_in_4bit": true,
-                            "bnb_4bit_quant_type": "{nf4}",
-                            "bnb_4bit_compute_dtype": "torch.bfloat16"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "transformer",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "text_encoder": {
-                    "configuration": {
-                        "component_type": "transformers.Qwen2_5_VLTextModel",
-                        "device": "cpu"
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "text_encoder",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "text_encoder_2": {
-                    "configuration": {
-                        "component_type": "transformers.T5EncoderModel",
-                        "device": "cpu"
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "text_encoder_2",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "vae": {
-                    "configuration": {
-                        "component_type": "AutoencoderKLHunyuanVideo15",
-                        "device": "cpu"
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "variable:model_name",
-                        "subfolder": "vae",
-                        "torch_dtype": "torch.float32"
-                    }
-                },
-                "configuration": {
-                    "component_type": "HunyuanVideo15Pipeline",
-                    "offload": "model",
-                    "vae": {
-                        "enable_tiling": true,
-                        "enable_slicing": true
-                    },
-                    "attention_backend": "flash_hub"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "variable:model_name",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "num_frames": 121
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/img2vid.json b/workflows/archive/img2vid.json
deleted file mode 100644
index 6bf33513..00000000
--- a/workflows/archive/img2vid.json
+++ /dev/null
@@ -1,124 +0,0 @@
-{
-    "variables": {
-        "source_image": "https://pbs.twimg.com/media/GdCdt6NWkAA4QTX?format=png&name=small"
-    },
-    "id": "img2vid",
-    "description": "Animates an input image four ways: CogVideoX I2V plus three Stable Video Diffusion variants.",
-    "steps": [
-        {
-            "name": "cog5b",
-            "seed": 42,
-            "pipeline": {
-                "configuration": {
-                    "offload": "sequential",
-                    "component_type": "CogVideoXImageToVideoPipeline",
-                    "vae": {
-                        "enable_slicing": true,
-                        "enable_tiling": true
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "THUDM/CogVideoX-5b-I2V",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "Sparkles and fire",
-                    "image": {
-                        "location": "variable:source_image"
-                    },
-                    "num_videos_per_prompt": 1,
-                    "num_inference_steps": 25,
-                    "num_frames": 49,
-                    "guidance_scale": 6
-                }
-            },
-            "result": {
-                "content_type": "video/mp4"
-            }
-        },
-        {
-            "name": "svd",
-            "pipeline": {
-                "configuration": {
-                    "offload": "sequential",
-                    "component_type": "StableVideoDiffusionPipeline",
-                    "unet": {
-                        "enable_forward_chunking": true
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "stabilityai/stable-video-diffusion-img2vid",
-                    "torch_dtype": "torch.float16",
-                    "use_safe_tensors": true,
-                    "variant": "fp16"
-                },
-                "arguments": {
-                    "image": {
-                        "location": "variable:source_image"
-                    },
-                    "num_frames": 25,
-                    "decode_chunk_size": 2
-                }
-            },
-            "result": {
-                "content_type": "video/mp4"
-            }
-        },
-        {
-            "name": "svdxt",
-            "pipeline": {
-                "configuration": {
-                    "offload": "sequential",
-                    "component_type": "StableVideoDiffusionPipeline",
-                    "unet": {
-                        "enable_forward_chunking": true
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "stabilityai/stable-video-diffusion-img2vid-xt",
-                    "torch_dtype": "torch.float16",
-                    "use_safe_tensors": true,
-                    "variant": "fp16"
-                },
-                "arguments": {
-                    "image": {
-                        "location": "variable:source_image"
-                    },
-                    "num_frames": 25,
-                    "decode_chunk_size": 2
-                }
-            },
-            "result": {
-                "content_type": "video/mp4"
-            }
-        },
-        {
-            "name": "svdxt1-1",
-            "pipeline": {
-                "configuration": {
-                    "offload": "sequential",
-                    "component_type": "StableVideoDiffusionPipeline",
-                    "unet": {
-                        "enable_forward_chunking": true
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "stabilityai/stable-video-diffusion-img2vid-xt-1-1",
-                    "torch_dtype": "torch.float16",
-                    "use_safe_tensors": true,
-                    "variant": "fp16"
-                },
-                "arguments": {
-                    "image": {
-                        "location": "variable:source_image"
-                    },
-                    "num_frames": 25,
-                    "decode_chunk_size": 2
-                }
-            },
-            "result": {
-                "content_type": "video/mp4"
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/ip-adapter.json b/workflows/archive/ip-adapter.json
deleted file mode 100644
index 60dfffed..00000000
--- a/workflows/archive/ip-adapter.json
+++ /dev/null
@@ -1,68 +0,0 @@
-{
-    "variables": {
-        "ip_adapter_image_location": "https://pbs.twimg.com/media/GeiyNysXUAAYEAs?format=jpg&name=small"
-    },
-    "id": "ip_adapter",
-    "description": "IP-Adapter reference-image conditioning on both SD 1.5 and SDXL.",
-    "steps": [
-        {
-            "name": "sd15",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "AutoPipelineForText2Image"
-                },
-                "ip_adapter": {
-                    "model_name": "h94/IP-Adapter",
-                    "subfolder": "models",
-                    "weight_name": "ip-adapter_sd15.bin"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "stable-diffusion-v1-5/stable-diffusion-v1-5",
-                    "torch_dtype": "torch.float16"
-                },
-                "arguments": {
-                    "ip_adapter_image": {
-                        "location": "variable:ip_adapter_image_location"
-                    },
-                    "prompt": "an image of an Axolotl in the style of Salvador Dalí..",
-                    "negative_prompt": "monochrome, lowres, bad anatomy, worst quality, low quality",
-                    "num_inference_steps": 50
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        },
-        {
-            "name": "sdxl",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "AutoPipelineForText2Image"
-                },
-                "ip_adapter": {
-                    "model_name": "h94/IP-Adapter",
-                    "subfolder": "sdxl_models",
-                    "weight_name": "ip-adapter_sdxl.bin",
-                    "scale": 0.6
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "stabilityai/stable-diffusion-xl-base-1.0",
-                    "torch_dtype": "torch.float16"
-                },
-                "arguments": {
-                    "ip_adapter_image": {
-                        "location": "variable:ip_adapter_image_location"
-                    },
-                    "prompt": "an image of an Axolotl in the style of Salvador Dalí..",
-                    "negative_prompt": "deformed, ugly, wrong proportion, low res, bad anatomy, worst quality, low quality",
-                    "num_inference_steps": 100
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/kandinsky.json b/workflows/archive/kandinsky.json
deleted file mode 100644
index ffb49143..00000000
--- a/workflows/archive/kandinsky.json
+++ /dev/null
@@ -1,79 +0,0 @@
-{
-    "id": "kandinsky_controlnet",
-    "description": "Kandinsky 2.2 with a depth ControlNet: prior embeddings, depth estimation, then controlled generation.",
-    "steps": [
-        {
-            "name": "prior",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "KandinskyV22PriorPipeline"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "kandinsky-community/kandinsky-2-2-prior",
-                    "torch_dtype": "torch.float16"
-                },
-                "arguments": {
-                    "negative_prompt": "lowres, text, error, cropped, worst quality, low quality, jpeg artifacts, ugly, duplicate, morbid, mutilated, out of frame, extra fingers, mutated hands, poorly drawn hands, poorly drawn face, mutation, deformed, blurry, dehydrated, bad anatomy, bad proportions, extra limbs, cloned face, disfigured, gross proportions, malformed limbs, missing arms, missing legs, extra arms, extra legs, fused fingers, too many fingers, long neck, username, watermark, signature",
-                    "prompt": "A robot, 4k photo"
-                }
-            }
-        },
-        {
-            "name": "gather_images",
-            "task": {
-                "command": "gather_images",
-                "arguments": {
-                    "urls": [
-                        "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/kandinskyv22/cat.png",
-                        "https://i.etsystatic.com/26048301/r/il/aa495c/3143939494/il_1080xN.3143939494_qbjy.jpg"
-                    ]
-                }
-            }
-        },
-        {
-            "name": "resize",
-            "task": {
-                "command": "resize_center_crop",
-                "arguments": {
-                    "image": "previous_result:gather_images",
-                    "height": 768,
-                    "width": 768
-                }
-            }
-        },
-        {
-            "name": "depth_estimator",
-            "task": {
-                "command": "depth_estimator_tensor",
-                "arguments": {
-                    "image": "previous_result:resize"
-                }
-            }
-        },
-        {
-            "name": "main",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "KandinskyV22ControlnetPipeline"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "kandinsky-community/kandinsky-2-2-controlnet-depth",
-                    "torch_dtype": "torch.float16"
-                },
-                "arguments": {
-                    "image_embeds": "previous_result:prior.image_embeds",
-                    "negative_image_embeds": "previous_result:prior.negative_image_embeds",
-                    "hint": "previous_result:depth_estimator",
-                    "num_inference_steps": 25,
-                    "num_images_per_prompt": 1,
-                    "height": 768,
-                    "width": 768
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/kandinsky3.json b/workflows/archive/kandinsky3.json
deleted file mode 100644
index 6024728c..00000000
--- a/workflows/archive/kandinsky3.json
+++ /dev/null
@@ -1,38 +0,0 @@
-{
-    "variables": {
-        "prompt": "",
-        "num_images_per_prompt": 1,
-        "num_inference_steps": 15,
-        "width": 768,
-        "height": 768
-    },
-    "id": "kandinsky3",
-    "description": "Text-to-image with Kandinsky 3.",
-    "steps": [
-        {
-            "name": "main",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "AutoPipelineForText2Image",
-                    "offload": "sequential"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "kandinsky-community/kandinsky-3",
-                    "torch_dtype": "torch.float16",
-                    "variant": "fp16"
-                },
-                "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/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/kandinsky_i2i.json b/workflows/archive/kandinsky_i2i.json
deleted file mode 100644
index 6ee8c2c9..00000000
--- a/workflows/archive/kandinsky_i2i.json
+++ /dev/null
@@ -1,48 +0,0 @@
-{
-    "variables": {
-        "prompt": "a realistic polaroid camera taking a picture of seedling growing from the ground",
-        "num_images_per_prompt": 1,
-        "num_inference_steps": 25,
-        "image": {
-            "location": "https://pbs.twimg.com/media/GgA2RMRXwAACXC4?format=png&name=large"
-        }
-    },
-    "id": "kandinsky_i2i",
-    "description": "Image-to-image with Kandinsky 3.",
-    "steps": [
-        {
-            "name": "resize",
-            "task": {
-                "command": "resize_rescale",
-                "arguments": {
-                    "image": "variable:image"
-                }
-            }
-        },
-        {
-            "name": "main",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "AutoPipelineForImage2Image",
-                    "offload": "sequential"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "kandinsky-community/kandinsky-3",
-                    "torch_dtype": "torch.float16",
-                    "variant": "fp16"
-                },
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "image": "previous_result:resize",
-                    "strength": 0.75,
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "num_images_per_prompt": "variable:num_images_per_prompt"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/ltx.json b/workflows/archive/ltx.json
deleted file mode 100644
index 3e0371e7..00000000
--- a/workflows/archive/ltx.json
+++ /dev/null
@@ -1,32 +0,0 @@
-{
-    "id": "ltx",
-    "description": "Text-to-video with LTX-Video 0.9.",
-    "steps": [
-        {
-            "name": "main",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "LTXPipeline"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "a-r-r-o-w/LTX-Video-0.9.1-diffusers",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "a faerie wearing boots dances in the forest",
-                    "width": 704,
-                    "height": 480,
-                    "num_frames": 161,
-                    "num_inference_steps": 50,
-                    "decode_timestep": 0.03,
-                    "decode_noise_scale": 0.025,
-                    "negative_prompt": "worst quality, inconsistent motion, blurry, jittery, distorted"
-                }
-            },
-            "result": {
-                "content_type": "video/mp4",
-                "fps": 24
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/owl.json b/workflows/archive/owl.json
deleted file mode 100644
index 9d341c96..00000000
--- a/workflows/archive/owl.json
+++ /dev/null
@@ -1,33 +0,0 @@
-{
-    "id": "owl",
-    "description": "Generates an image with SD 3.5, then animates it with CogVideoX - a workflow-composition demo.",
-    "steps": [
-        {
-            "name": "image_generation",
-            "workflow": {
-                "path": "./sd35.json",
-                "arguments": {
-                    "prompt": "portrait | wide angle shot of eyes off to one side of frame, lucid dream-like 3d model of an owl, game asset, blender, looking off in distance ::8 style | glowing ::8 background | forest, vivid neon wonderland, particles, blue, green, orange ::7 parameters | rule of thirds, golden ratio, asymmetric composition, hyper- maximalist, octane render, photorealism, cinematic realism, unreal engine, 8k ::7 --ar 16:9 --s 1000"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        },
-        {
-            "name": "video_generation",
-            "workflow": {
-                "path": "./CogVideoX-5B-I2V.json",
-                "arguments": {
-                    "image": "previous_result:image_generation",
-                    "prompt": "The owl stares intently and blinks",
-                    "num_inference_steps": 50
-                }
-            },
-            "result": {
-                "content_type": "video/mp4"
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/sana.json b/workflows/archive/sana.json
deleted file mode 100644
index 4e731913..00000000
--- a/workflows/archive/sana.json
+++ /dev/null
@@ -1,45 +0,0 @@
-{
-    "variables": {
-        "prompt": "Image of a marmot in a bull costume",
-        "num_images_per_prompt": 4,
-        "guidance_scale": 4.5,
-        "num_inference_steps": 20,
-        "width": 1024,
-        "height": 1024
-    },
-    "id": "sana",
-    "description": "Text-to-image with Sana 1.6B.",
-    "steps": [
-        {
-            "name": "txt2img",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "SanaPipeline",
-                    "vae": {
-                        "torch_dtype": "torch.bfloat16"
-                    },
-                    "text_encoder": {
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "Efficient-Large-Model/Sana_1600M_1024px_BF16_diffusers",
-                    "torch_dtype": "torch.bfloat16",
-                    "variant": "bf16"
-                },
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "guidance_scale": "variable:guidance_scale",
-                    "num_images_per_prompt": "variable:num_images_per_prompt",
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/sd15.json b/workflows/archive/sd15.json
deleted file mode 100644
index 3ea795a8..00000000
--- a/workflows/archive/sd15.json
+++ /dev/null
@@ -1,32 +0,0 @@
-{
-    "variables": {
-        "prompt": "an apple",
-        "num_images_per_prompt": 1
-    },
-    "id": "test_job",
-    "description": "Baseline text-to-image with Stable Diffusion 1.5 - the smallest, fastest starting point.",
-    "steps": [
-        {
-            "name": "main",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "StableDiffusionPipeline"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "stable-diffusion-v1-5/stable-diffusion-v1-5",
-                    "torch_dtype": "torch.float32"
-                },
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "num_inference_steps": 25,
-                    "num_images_per_prompt": "variable:num_images_per_prompt"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true,
-                "file_base_name": "test_image"
-            }
-        }
-    ]
-}
diff --git a/workflows/archive/sd35.json b/workflows/archive/sd35.json
deleted file mode 100644
index e099066b..00000000
--- a/workflows/archive/sd35.json
+++ /dev/null
@@ -1,39 +0,0 @@
-{
-    "variables": {
-        "prompt": "centi-mojo",
-        "num_images_per_prompt": 4,
-        "num_inference_steps": 25,
-        "width": 768,
-        "height": 768
-    },
-    "id": "sd35",
-    "description": "Text-to-image with Stable Diffusion 3.5 Large.",
-    "steps": [
-        {
-            "name": "txt2img",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "StableDiffusion3Pipeline",
-                    "offload": "model"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "stabilityai/stable-diffusion-3.5-large",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "num_inference_steps": "variable:num_inference_steps",
-                    "guidance_scale": 4.5,
-                    "max_sequence_length": 512,
-                    "num_images_per_prompt": "variable:num_images_per_prompt",
-                    "width": "variable:width",
-                    "height": "variable:height"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/sd35ip.json b/workflows/archive/sd35ip.json
deleted file mode 100644
index ea7f07e2..00000000
--- a/workflows/archive/sd35ip.json
+++ /dev/null
@@ -1,80 +0,0 @@
-{
-    "variables": {
-        "prompt": "a marmot drinks a milkshake"
-    },
-    "id": "sd35ip",
-    "description": "SD 3.5 Large with an IP-Adapter, 4-bit quantized.",
-    "steps": [
-        {
-            "name": "main",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "StableDiffusion3Pipeline"
-                },
-                "transformer": {
-                    "configuration": {
-                        "component_type": "SD3Transformer2DModel"
-                    },
-                    "quantization_config": {
-                        "configuration": {
-                            "config_type": "BitsAndBytesConfig"
-                        },
-                        "arguments": {
-                            "load_in_4bit": true,
-                            "bnb_4bit_quant_type": "{nf4}",
-                            "bnb_4bit_compute_dtype": "torch.bfloat16"
-                        }
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "stabilityai/stable-diffusion-3.5-large",
-                        "subfolder": "transformer",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "feature_extractor": {
-                    "configuration": {
-                        "component_type": "transformers.SiglipImageProcessor"
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "google/siglip-so400m-patch14-384",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "image_encoder": {
-                    "configuration": {
-                        "component_type": "transformers.SiglipVisionModel"
-                    },
-                    "from_pretrained_arguments": {
-                        "model_name": "google/siglip-so400m-patch14-384",
-                        "torch_dtype": "torch.bfloat16"
-                    }
-                },
-                "ip_adapter": {
-                    "model_name": "InstantX/SD3.5-Large-IP-Adapter",
-                    "weight_name": "ip-adapter.bin",
-                    "scale": 0.6,
-                    "revision": "f1f54ca369ae759f9278ae9c87d46def9f133c78"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "stabilityai/stable-diffusion-3.5-large",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "negative_prompt": "lowres, low quality, worst quality",
-                    "num_inference_steps": 25,
-                    "guidance_scale": 4.5,
-                    "width": 1024,
-                    "height": 1024,
-                    "ip_adapter_image": {
-                        "location": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/ip_adapter_diner.png"
-                    }
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/archive/sdxl_refiner.json b/workflows/archive/sdxl_refiner.json
deleted file mode 100644
index f4044b98..00000000
--- a/workflows/archive/sdxl_refiner.json
+++ /dev/null
@@ -1,36 +0,0 @@
-{
-    "variables": {
-        "prompt": "a realistic polaroid camera taking a picture of seedling growing from the ground",
-        "num_images_per_prompt": 1,
-        "num_inference_steps": 25,
-        "image": {
-            "location": "https://pbs.twimg.com/media/GgA2RMRXwAACXC4?format=png&name=large"
-        }
-    },
-    "id": "sdxl_refiner",
-    "description": "Refines an input image with the SDXL refiner.",
-    "steps": [
-        {
-            "name": "main",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "StableDiffusionXLImg2ImgPipeline"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "stabilityai/stable-diffusion-xl-refiner-1.0",
-                    "torch_dtype": "torch.float16",
-                    "variant": "fp16",
-                    "use_safetensors": true
-                },
-                "arguments": {
-                    "prompt": "variable:prompt",
-                    "image": "variable:image"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/tasks/CaptionToImage.json b/workflows/tasks/CaptionToImage.json
deleted file mode 100644
index 044a79dd..00000000
--- a/workflows/tasks/CaptionToImage.json
+++ /dev/null
@@ -1,56 +0,0 @@
-{
-    "id": "CaptionToImage",
-    "description": "Captions input images, then generates new images from those captions with FLUX.1 dev.",
-    "variables": {
-        "image_url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/car.jpg?download=true"
-    },
-    "steps": [
-        {
-            "name": "input_image",
-            "task": {
-                "command": "gather_images",
-                "arguments": {
-                    "urls": [
-                        "variable:image_url"
-                    ]
-                }
-            }
-        },
-        {
-            "name": "caption",
-            "task": {
-                "command": "image_to_text",
-                "arguments": {
-                    "image": "previous_result:input_image",
-                    "max_new_tokens": 75
-                }
-            },
-            "result": {
-                "content_type": "text/plain",
-                "save": false
-            }
-        },
-        {
-            "name": "generate",
-            "pipeline": {
-                "configuration": {
-                    "offload": "model",
-                    "component_type": "FluxPipeline"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "black-forest-labs/FLUX.1-dev",
-                    "torch_dtype": "torch.bfloat16"
-                },
-                "arguments": {
-                    "prompt": "previous_result:caption",
-                    "num_inference_steps": 25,
-                    "guidance_scale": 3.5
-                }
-            },
-            "result": {
-                "content_type": "image/png",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
diff --git a/workflows/tasks/DiffusionUpscale.json b/workflows/tasks/DiffusionUpscale.json
deleted file mode 100644
index 64de4a7a..00000000
--- a/workflows/tasks/DiffusionUpscale.json
+++ /dev/null
@@ -1,60 +0,0 @@
-{
-    "variables": {
-        "prompt": "a photo of an astronaut riding a horse on mars",
-        "upscale_prompt": "high quality, detailed",
-        "negative_prompt": "blurry, low quality, artifacts",
-        "num_images_per_prompt": 1,
-        "num_inference_steps": 9,
-        "upscale_steps": 25,
-        "guidance_scale": 0.0,
-        "width": 512,
-        "height": 512,
-        "mode": "x4"
-    },
-    "id": "DiffusionUpscaleX4",
-    "description": "Generates with Z-Image Turbo, then upscales the result with a diffusion upscaler.",
-    "steps": [
-        {
-            "name": "generate",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "ZImagePipeline"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "Tongyi-MAI/Z-Image-Turbo",
-                    "torch_dtype": "torch.bfloat16",
-                    "low_cpu_mem_usage": false
-                },
-                "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",
-                    "guidance_scale": "variable:guidance_scale"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        },
-        {
-            "name": "upscale",
-            "task": {
-                "command": "diffusion_upscale",
-                "arguments": {
-                    "image": "previous_result:generate",
-                    "prompt": "variable:upscale_prompt",
-                    "negative_prompt": "variable:negative_prompt",
-                    "mode": "variable:mode",
-                    "num_inference_steps": "variable:upscale_steps"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/tasks/SpandrelUpscale.json b/workflows/tasks/SpandrelUpscale.json
deleted file mode 100644
index 3150ecad..00000000
--- a/workflows/tasks/SpandrelUpscale.json
+++ /dev/null
@@ -1,56 +0,0 @@
-{
-    "variables": {
-        "prompt": "a photo of an astronaut riding a horse on mars",
-        "upscale_model": "Kim2091/UltraSharp",
-        "upscale_filename": "4x-UltraSharp.pth",
-        "num_images_per_prompt": 1,
-        "num_inference_steps": 9,
-        "guidance_scale": 0.0,
-        "width": 512,
-        "height": 512
-    },
-    "id": "SpandrelUpscale",
-    "description": "Generates with Z-Image Turbo, then upscales with a Spandrel super-resolution model.",
-    "steps": [
-        {
-            "name": "generate",
-            "pipeline": {
-                "configuration": {
-                    "component_type": "ZImagePipeline"
-                },
-                "from_pretrained_arguments": {
-                    "model_name": "Tongyi-MAI/Z-Image-Turbo",
-                    "torch_dtype": "torch.bfloat16",
-                    "low_cpu_mem_usage": false
-                },
-                "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",
-                    "guidance_scale": "variable:guidance_scale"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        },
-        {
-            "name": "upscale",
-            "task": {
-                "command": "upscale",
-                "arguments": {
-                    "image": "previous_result:generate",
-                    "model_name": "variable:upscale_model",
-                    "filename": "variable:upscale_filename"
-                }
-            },
-            "result": {
-                "content_type": "image/jpeg",
-                "embed_metadata": true
-            }
-        }
-    ]
-}
\ No newline at end of file
diff --git a/workflows/templates/compose-workflows.json b/workflows/templates/compose-workflows.json
index cb44cef5..99d8deb1 100644
--- a/workflows/templates/compose-workflows.json
+++ b/workflows/templates/compose-workflows.json
@@ -2,15 +2,15 @@
     "variables": {
         "width": 720,
         "height": 480,
-        "image_generation_workflow": "./kandinsky3.json",
-        "image_num_inference_steps": 25,
+        "image_generation_workflow": "../models/z-image.json",
+        "image_num_inference_steps": 9,
         "image_prompt": "portrait | wide angle shot of eyes off to one side of frame, lucid dream-like 3d model of a marmot, game asset, blender, looking off in distance ::8 style | glowing ::8 background | forest, vivid neon wonderland, particles, blue, green, orange ::7 parameters | rule of thirds, golden ratio, asymmetric composition, hyper- maximalist, octane render, photorealism, cinematic realism, unreal engine, 8k ::7 --ar 16:9 --s 1000",
-        "video_generation_workflow": "./CogVideoX-5B-I2V.json",
+        "video_generation_workflow": "./minimax/image-to-video.json",
         "video_prompt": "the marmot blinks and looks around",
-        "video_num_inference_steps": 50
+        "video_num_inference_steps": 20
     },
     "id": "txt2img2vid",
-    "description": "Composes any text-to-image workflow with any image-to-video workflow - both named as variables.",
+    "description": "Composes any text-to-image workflow with any image-to-video workflow - both named as variables, so the pair can be swapped without touching this file. The still the first step generates is handed to the second as its 'image'. Paths resolve against this file's own directory, so a workflow elsewhere in the catalog is named relatively: '../models/z-image.json' here for the still, './minimax/image-to-video.json' for the animation.",
     "steps": [
         {
             "name": "image_generation",
@@ -43,4 +43,4 @@
             }
         }
     ]
-}
\ No newline at end of file
+}

From 8d55821f9b3a6a99e4b52390d527a80448a1105c Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 15:12:18 -0500
Subject: [PATCH 14/32] Repoint documentation at the restructured catalog

All 66 broken workflow links, plus 75 whose text still named the old
filename, plus the REPL examples that loaded flux/FluxDev.

Fourteen links whose targets were deleted needed judgement rather than a
mapping. In RECIPES_24GB the per-model VRAM prose is knowledge no template
carries, so it stays and only the dead example links go, replaced by a
pointer to the template to author from. The IP-Adapter, LoRA and
quantization examples move to the surviving template or model config.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                                     |  8 +-
 README.md                                     | 12 +--
 docs/ACCELERATION.md                          | 10 +-
 docs/DEPENDENCIES.md                          |  2 +-
 docs/IP_ADAPTER.md                            |  7 +-
 docs/LORAS.md                                 |  6 +-
 docs/PROMPT_WEIGHTING.md                      |  4 +-
 docs/QUANTIZATION.md                          | 10 +-
 docs/RECIPES_24GB.md                          | 24 ++---
 docs/REPL_COMMANDS.md                         |  6 +-
 docs/REPL_WORKER_GUIDE.md                     |  2 +-
 docs/SECURITY.md                              |  2 +-
 docs/TASKS.md                                 | 92 +++++++++----------
 docs/TESTING.md                               |  2 +-
 docs/WORKFLOW_GUIDE.md                        | 42 ++++-----
 docs/WORKSPACES.md                            |  4 +-
 docs/proposals/scripted-dialogue-and-tts.md   |  8 +-
 docs/proposals/sweeps-and-comparison.md       |  2 +-
 .../plans/2026-09-04-remote-gpu-server.md     |  2 +-
 19 files changed, 122 insertions(+), 123 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index a4cc6676..c260f8f4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -14,14 +14,14 @@ bash ./install.sh && source ./activate
 
 # Run a workflow - sd15.json uses a small, ungated model and a literal
 # prompt, so it needs no Hugging Face login and downloads only a few GB
-python -m dw.run workflows/sd15.json
-python -m dw.run workflows/sd15.json prompt="a cat" num_images_per_prompt=4
+python -m dw.run workflows/templates/text-to-image.json
+python -m dw.run workflows/templates/text-to-image.json prompt="a cat" num_images_per_prompt=4
 
-# A gated model (e.g. workflows/flux/FluxDev.json) needs Hugging Face auth
+# A gated model (e.g. workflows/models/flux-dev.json) needs Hugging Face auth
 # first: huggingface-cli login
 
 # Validate a workflow against schema
-python -m dw.validate workflows/ZImage.json
+python -m dw.validate workflows/models/z-image.json
 
 # Basic system test (torch, diffusers import check)
 python -m dw.test
diff --git a/README.md b/README.md
index 470c9429..25558ff6 100644
--- a/README.md
+++ b/README.md
@@ -160,14 +160,14 @@ the pages and the HTTP API.
 ## The command line
 
 The engine runs standalone, with no server involved.
-`workflows/sd15.json` is the smallest starting point — a small, ungated model
+`workflows/templates/text-to-image.json` is the smallest starting point — a small, ungated model
 and a literal prompt, so the first run needs no Hugging Face login and
 downloads only a few GB:
 
 ```bash
-python -m dw.run workflows/sd15.json
-python -m dw.run workflows/sd15.json prompt="a cat" num_images_per_prompt=4
-python -m dw.validate workflows/sd15.json
+python -m dw.run workflows/templates/text-to-image.json
+python -m dw.run workflows/templates/text-to-image.json prompt="a cat" num_images_per_prompt=4
+python -m dw.validate workflows/templates/text-to-image.json
 ```
 
 Most of the workflows under `workflows/` (Flux, LTX-2, MiniMax...) use **gated**
@@ -177,7 +177,7 @@ then:
 
 ```bash
 huggingface-cli login
-python -m dw.run workflows/flux/FluxDev.json
+python -m dw.run workflows/models/flux-dev.json
 ```
 
 Without this, the run fails partway through with an HTTP 401/403 from the Hub.
@@ -186,7 +186,7 @@ An interactive REPL keeps models resident between runs for 2-4x faster
 iteration:
 
 ```text
-dw> workflow load flux/FluxDev
+dw> workflow load models/flux-dev
 dw> arg set prompt="a beautiful sunset"
 dw> workflow run
 [... models load once ...]
diff --git a/docs/ACCELERATION.md b/docs/ACCELERATION.md
index 36124df6..0bc0721d 100644
--- a/docs/ACCELERATION.md
+++ b/docs/ACCELERATION.md
@@ -42,7 +42,7 @@ Simplest and broadest support. Compares first-block residuals to decide whether
 
 Higher threshold = more speedup, more quality loss. Start with `0.05` and increase to taste.
 
-**Example:** [FluxDevFirstBlockCache.json](../workflows/flux/FluxDevFirstBlockCache.json)
+**Example:** [step-caching.json](../workflows/templates/step-caching.json)
 
 ### MagCache
 
@@ -165,7 +165,7 @@ Some models have multiple variants with different coefficients:
 }
 ```
 
-**Example:** [FluxDevTeaCache.json](../workflows/flux/FluxDevTeaCache.json)
+**Example:** [step-caching.json](../workflows/templates/step-caching.json)
 
 ## Cache vs TeaCache
 
@@ -206,7 +206,7 @@ A component can also pin its backend persistently instead, via `set_attention_ba
 
 Prefer the pinned form for a compiled component - the per-call context manager switches implementations under the compiled graph and forces a recompile on every run.
 
-**Example:** [Flux2Dev.json](../workflows/flux/Flux2Dev.json), [hunyuan15.json](../workflows/archive/hunyuan15.json), [Wan22TI2V5B.json](../workflows/archive/Wan22TI2V5B.json)
+**Example:** [flux2-dev.json](../workflows/models/flux2-dev.json)
 
 ## Attention Slicing
 
@@ -252,7 +252,7 @@ Typical gains are 1.3-1.5x on diffusion transformers, and compilation stacks wit
 - **Don't combine `fullgraph` with a `cache`**: the cache hooks decide skip-or-compute per step, a data-dependent branch diffusers wraps in `torch.compiler.disable` - it needs the graph break that `fullgraph: true` forbids. Compile with the default (partial) graph mode when a cache is active.
 - **TorchAO quantization needs compile to be fast** - see [QUANTIZATION.md](QUANTIZATION.md#torchao).
 
-**Example:** [FluxDevFast.json](../workflows/flux/FluxDevFast.json), [FluxTorchAO.json](../workflows/flux/FluxTorchAO.json)
+**Example:** [flux-dev-fast.json](../workflows/models/flux-dev-fast.json), [flux-torchao.json](../workflows/models/flux-torchao.json)
 
 ## Layerwise Casting
 
@@ -296,7 +296,7 @@ Three older per-component knobs, set in the pipeline `configuration` beside
 
 `"residency": "on_demand"` on a component is the cheap case of the same trade: the model rests in system memory and is moved to the device whole around each of its own calls. That is a bad deal for anything called once per step, and a good one for a VAE called twice a run - it frees the VAE's VRAM for the denoise loop at the cost of two transfers, where group offloading the same VAE would restream it once per decode tile. See [On-demand components](WORKFLOW_GUIDE.md#on-demand-components).
 
-**Example:** [FluxDev.json](../workflows/flux/FluxDev.json) (`"offload": "model"`), [ZImage.json](../workflows/ZImage.json) (`"offload": "sequential"`), [MiniMaxH3.json](../workflows/minimax/MiniMaxH3.json) (`group_offload` per component), [MiniMaxH3Ref2VA.json](../workflows/minimax/MiniMaxH3Ref2VA.json) (`group_offload` for the transformer, `on_demand` for the VAEs)
+**Example:** [flux-dev.json](../workflows/models/flux-dev.json) (`"offload": "model"`), [z-image.json](../workflows/models/z-image.json) (`"offload": "sequential"`), [video-with-audio.json](../workflows/templates/minimax/video-with-audio.json) (`group_offload` per component), [reference-to-video.json](../workflows/templates/minimax/reference-to-video.json) (`group_offload` for the transformer, `on_demand` for the VAEs)
 
 ## TF32 and cuDNN
 
diff --git a/docs/DEPENDENCIES.md b/docs/DEPENDENCIES.md
index f5a45d5e..606fe19f 100644
--- a/docs/DEPENDENCIES.md
+++ b/docs/DEPENDENCIES.md
@@ -82,7 +82,7 @@ bash ./install.sh
 huggingface-cli login
 ```
 
-`workflows/sd15.json` uses an ungated model and needs no login - start there if you just want to confirm the install works.
+`workflows/templates/text-to-image.json` uses an ungated model and needs no login - start there if you just want to confirm the install works.
 
 **Package conflicts:** Re-run the install script — it recreates the venv from scratch.
 
diff --git a/docs/IP_ADAPTER.md b/docs/IP_ADAPTER.md
index dfcd6d46..5524fce7 100644
--- a/docs/IP_ADAPTER.md
+++ b/docs/IP_ADAPTER.md
@@ -77,7 +77,7 @@ Some base models (e.g. Stable Diffusion 3.5) don't ship a default image encoder,
 }
 ```
 
-See [sd35ip.json](../workflows/archive/sd35ip.json) for the full workflow.
+See [ip-adapter.json](../workflows/templates/ip-adapter.json) for the full workflow.
 
 ## Image Argument
 
@@ -105,6 +105,5 @@ Can also reference a previous step's output:
 
 ## Examples
 
-- [FluxIP.json](../workflows/flux/FluxIP.json) — Flux with IP-Adapter for style transfer
-- [sd35ip.json](../workflows/archive/sd35ip.json) — SD 3.5 (quantized) with an explicit `image_encoder`/`feature_extractor` pair
-- [ip-adapter.json](../workflows/archive/ip-adapter.json) — SD 1.5 and SDXL, each with an `AutoPipelineForText2Image` step
+- [ip-adapter.json](../workflows/templates/ip-adapter.json) — Flux with IP-Adapter for style transfer
+- [ip-adapter.json](../workflows/templates/ip-adapter.json) — FLUX.1 dev with an IP-Adapter, and the face-model variant in its description
diff --git a/docs/LORAS.md b/docs/LORAS.md
index d598a7a9..79269366 100644
--- a/docs/LORAS.md
+++ b/docs/LORAS.md
@@ -126,6 +126,6 @@ python -m dw.run workflow.json lora="other-user/other-lora"
 
 ## Examples
 
-- [FluxLora.json](../workflows/flux/FluxLora.json) — Flux with realism LoRA and variables
-- [lora.json](../workflows/lora.json) — SD 3.5 with yarn art style LoRA
-- [bnb_quant.json](../workflows/archive/bnb_quant.json) — Quantized model with LoRA
+- [lora.json](../workflows/templates/lora.json) — Flux with realism LoRA and variables
+- [lora.json](../workflows/templates/lora.json) — SD 3.5 with yarn art style LoRA
+- [lora.json](../workflows/templates/lora.json) — A LoRA adapter on FLUX.1 dev, with the SD 3.5 variant in its description
diff --git a/docs/PROMPT_WEIGHTING.md b/docs/PROMPT_WEIGHTING.md
index ccbeb1a9..8ba6912a 100644
--- a/docs/PROMPT_WEIGHTING.md
+++ b/docs/PROMPT_WEIGHTING.md
@@ -71,8 +71,8 @@ Any other pipeline whose class name starts with `Flux` (e.g. `FluxKontextPipelin
 ## Example
 
 ```bash
-python -m dw.run workflows/flux/FluxSchnellWeighted.json \
+python -m dw.run workflows/templates/prompt-weighting.json \
     prompt="a (cinematic:1.5) shot of a (dragon:1.3) breathing [smoke] over a (medieval:0.8) castle"
 ```
 
-See [FluxSchnellWeighted.json](../workflows/flux/FluxSchnellWeighted.json).
+See [prompt-weighting.json](../workflows/templates/prompt-weighting.json).
diff --git a/docs/QUANTIZATION.md b/docs/QUANTIZATION.md
index 64d7af90..0243f394 100644
--- a/docs/QUANTIZATION.md
+++ b/docs/QUANTIZATION.md
@@ -55,7 +55,7 @@ For 8-bit:
 "arguments": { "load_in_8bit": true }
 ```
 
-**Example:** [bnb_quant.json](../workflows/archive/bnb_quant.json)
+**Example:** [flux2-dev.json](../workflows/models/flux2-dev.json) (a pre-quantized 4-bit checkpoint)
 
 ## TorchAO
 
@@ -78,7 +78,7 @@ Common choices: `Int8WeightOnlyConfig` (any CUDA card), `Int4WeightOnlyConfig` (
 `Float8DynamicActivationFloat8WeightConfig` (fastest, requires compute capability 8.9+ -
 RTX 40-series/Ada or newer).
 
-**Example:** [FluxTorchAO.json](../workflows/flux/FluxTorchAO.json)
+**Example:** [flux-torchao.json](../workflows/models/flux-torchao.json)
 
 **Pair TorchAO with `torch.compile`.** Int8 weight-only and float8 dynamic-activation
 quant types get their fused-kernel speedups only under compilation - uncompiled they are
@@ -117,7 +117,7 @@ GGUF models load from single files using `from_single_file`:
 }
 ```
 
-**Example:** [FluxGGUF.json](../workflows/flux/FluxGGUF.json)
+**Example:** [flux-gguf.json](../workflows/models/flux-gguf.json)
 
 ## SDNQ (SD.Next Quantization)
 
@@ -146,7 +146,7 @@ examples use for their large transformers and text encoders:
 - `quantization_device` / `return_device` — where the quantization pass runs and where the finished component lands; quantizing on `cuda` is much faster than on CPU
 - `use_quantized_matmul` — quantized matmul kernels (CUDA/XPU only)
 
-**Examples:** [LTX2.json](../workflows/ltx2/LTX2.json), [MiniMaxH3.json](../workflows/minimax/MiniMaxH3.json)
+**Examples:** [text-to-video.json](../workflows/templates/ltx2/text-to-video.json), [video-with-audio.json](../workflows/templates/minimax/video-with-audio.json)
 
 ### Pre-quantized models
 
@@ -171,7 +171,7 @@ Pre-quantized SDNQ repos load as complete pipelines. The `sdnq` module must be i
 - `pre_load_modules` — Imports sdnq before pipeline loading (registers quantization method)
 - `sdnq_optimize` — Applies quantized matmul to listed components (CUDA/XPU only, skipped on MPS/CPU)
 
-**Example:** [ZImageSDNQ.json](../workflows/ZImageSDNQ.json)
+**Example:** [z-image-sdnq.json](../workflows/models/z-image-sdnq.json)
 
 ## Modular Pipelines
 
diff --git a/docs/RECIPES_24GB.md b/docs/RECIPES_24GB.md
index 87eaad29..9de52b3d 100644
--- a/docs/RECIPES_24GB.md
+++ b/docs/RECIPES_24GB.md
@@ -20,26 +20,26 @@ The bf16 transformer is ~24GB - it does not fit alongside the T5 encoder. Two go
 | **float8 TorchAO** (RTX 40-series+) | same, with `Float8DynamicActivationFloat8WeightConfig` | Fastest, but fp8 needs compute capability 8.9+ (Ada). |
 | **GGUF Q8** | `from_single_file` Q8_0 transformer + `offload: "model"` | Simplest, best quality retention, slower than TorchAO+compile. |
 
-**Examples:** [FluxDevFast.json](../workflows/flux/FluxDevFast.json) (the int8 recipe - swap in `Float8DynamicActivationFloat8WeightConfig` on Ada or newer), [FluxGGUF.json](../workflows/flux/FluxGGUF.json), [FluxDevFirstBlockCache.json](../workflows/flux/FluxDevFirstBlockCache.json)
+**Examples:** [flux-dev-fast.json](../workflows/models/flux-dev-fast.json) (the int8 recipe - swap in `Float8DynamicActivationFloat8WeightConfig` on Ada or newer), [flux-gguf.json](../workflows/models/flux-gguf.json), [step-caching.json](../workflows/templates/step-caching.json)
 
 ## Qwen-Image (20B)
 
 Too large for bf16 on 24GB. Quantize the transformer (TorchAO int8/float8 or GGUF Q4/Q5) and model-offload the rest; add `compile` + `first_block` cache as for Flux. The Qwen2.5-VL text encoder is large - quantize it too, or group-offload it (`"text_encoder.model"` with `leaf_level`).
 
-**Example:** [QwenImageEdit.json](../workflows/archive/QwenImageEdit.json)
+The catalog no longer ships a Qwen-Image workflow - author one from [text-to-image.json](../workflows/templates/text-to-image.json) with the configuration above.
 
 ## Wan 2.2
 
 - **TI2V-5B**: fits in bf16 on 24GB. No quantization needed - just `compile` + `cache` + VAE tiling for longer clips.
 - **T2V/I2V-A14B**: two 14B transformers (`transformer` + `transformer_2`). Quantize both (GGUF Q4/Q5 or TorchAO int8) and use `offload: "model"`; enable `vae.enable_tiling`.
 
-**Examples:** [Wan22TI2V5B.json](../workflows/archive/Wan22TI2V5B.json), [Wan22T2V14B.json](../workflows/archive/Wan22T2V14B.json)
+The catalog no longer ships Wan workflows - author one from [minimax/image-to-video.json](../workflows/templates/minimax/image-to-video.json) with the configuration above.
 
 ## HunyuanVideo (13B)
 
 Same shape as Flux: quantize the transformer (GGUF Q6/Q8, or TorchAO int8/float8 per the Flux table) + `offload: "model"` + `vae.enable_tiling`. The Llama text encoder benefits from group offload. Use `first_block` cache - video steps are expensive, caching pays off more than on images.
 
-**Examples:** [HunyuanVideoGguf.json](../workflows/archive/HunyuanVideoGguf.json), [hunyuan15.json](../workflows/archive/hunyuan15.json)
+The catalog no longer ships a HunyuanVideo workflow - author one from [ltx2/text-to-video.json](../workflows/templates/ltx2/text-to-video.json) with the configuration above.
 
 ## MiniMax-H3
 
@@ -92,7 +92,7 @@ model first (Z-Image drawing a subject, Music3 writing a song) must free it with
 `release_pipeline` before H3 loads - with it, the multi-model digital-short
 workflows below fit; without it, the load is an OOM kill, not a slowdown.
 
-**Examples:** [MiniMaxH3Ref2VA.json](../workflows/minimax/MiniMaxH3Ref2VA.json), [MiniMaxH3Ref2VAChained.json](../workflows/minimax/MiniMaxH3Ref2VAChained.json), [MiniMaxH3I2V.json](../workflows/minimax/MiniMaxH3I2V.json), [MiniMaxH3SitcomShort.json](../workflows/minimax/MiniMaxH3SitcomShort.json) (five ref2va shots + two Z-Image portraits in ~35 minutes end to end)
+**Examples:** [reference-to-video.json](../workflows/templates/minimax/reference-to-video.json), [chain-matched-to-audio.json](../workflows/templates/minimax/chain-matched-to-audio.json), [image-to-video.json](../workflows/templates/minimax/image-to-video.json), [dialogue-short.json](../workflows/templates/minimax/dialogue-short.json) (five ref2va shots + two Z-Image portraits in ~35 minutes end to end)
 
 ## LTX-2.5 (22B, video + audio)
 
@@ -135,19 +135,19 @@ upsample the latents 2x, and the result is sharper than a single pass at 1536x89
 fits where that would not. The base step shares its `vae` into the upsampler and sets
 `release_pipeline`, which frees the 11GB transformer before the 2x decode runs.
 
-**Examples:** [LTX2.json](../workflows/ltx2/LTX2.json) (t2v),
-[LTX2TwoStage.json](../workflows/ltx2/LTX2TwoStage.json) (base -> latent upsample -> mux),
-[LTX2Keyframes.json](../workflows/ltx2/LTX2Keyframes.json) (first and
-last frame), [LTX2Extend.json](../workflows/ltx2/LTX2Extend.json) (continue a clip),
-[LTX2ICLora.json](../workflows/ltx2/LTX2ICLora.json) (generative 2x upscale via IC-LoRA),
-[LTX2I2VEnhancePrompt.json](../workflows/ltx2/LTX2I2VEnhancePrompt.json) (native prompt
+**Examples:** [text-to-video.json](../workflows/templates/ltx2/text-to-video.json) (t2v),
+[two-stage.json](../workflows/templates/ltx2/two-stage.json) (base -> latent upsample -> mux),
+[keyframes.json](../workflows/templates/ltx2/keyframes.json) (first and
+last frame), [extend-clip.json](../workflows/templates/ltx2/extend-clip.json) (continue a clip),
+[generative-upscale.json](../workflows/templates/ltx2/generative-upscale.json) (generative 2x upscale via IC-LoRA),
+[enhance-prompt.json](../workflows/templates/ltx2/enhance-prompt.json) (native prompt
 enhancer and duration head)
 
 ## SDXL (2.6B UNet)
 
 Fits several times over in 24GB. Skip quantization and offloading entirely; `compile` the UNet if you generate many images per session. Use `num_images_per_prompt` batching with `vae.enable_slicing`.
 
-**Example:** [sdxl.json](../workflows/archive/sdxl.json)
+**Example:** [base-and-refiner.json](../workflows/templates/base-and-refiner.json)
 
 ## Multi-model workflows
 
diff --git a/docs/REPL_COMMANDS.md b/docs/REPL_COMMANDS.md
index c47a0de9..faa27d08 100644
--- a/docs/REPL_COMMANDS.md
+++ b/docs/REPL_COMMANDS.md
@@ -32,8 +32,8 @@ workflow restart         Restart the worker process (clears GPU cache)
 ```
 
 `workflow load` resolves names against the workflow directory (`./workflows`
-by default), including subfolders - `workflow load flux/FluxDev` loads
-`workflows/flux/FluxDev.json`. `workflow list` shows the available names.
+by default), including subfolders - `workflow load models/flux-dev` loads
+`workflows/models/flux-dev.json`. `workflow list` shows the available names.
 
 `workflow run ask <arg>` prompts you interactively for `<arg>`'s value (the
 value is not saved to shell/readline history) before running — a shortcut
@@ -101,7 +101,7 @@ cached; a second Ctrl+C stops the worker process itself.
 ## Typical Session
 
 ```bash
-dw> workflow load flux/FluxDev
+dw> workflow load models/flux-dev
 dw> arg show
 dw> arg set prompt="a majestic mountain landscape"
 dw> workflow run
diff --git a/docs/REPL_WORKER_GUIDE.md b/docs/REPL_WORKER_GUIDE.md
index c0e27e6d..d68f2b0b 100644
--- a/docs/REPL_WORKER_GUIDE.md
+++ b/docs/REPL_WORKER_GUIDE.md
@@ -13,7 +13,7 @@ python -m dw.repl
 ```
 
 ```text
-dw> workflow load flux/FluxDev
+dw> workflow load models/flux-dev
 dw> arg set prompt="a cat wearing a hat"
 dw> workflow run         # first run — loads model (~30-60s)
 dw> arg set prompt="a dog in a park"
diff --git a/docs/SECURITY.md b/docs/SECURITY.md
index 4299c833..244bea8a 100644
--- a/docs/SECURITY.md
+++ b/docs/SECURITY.md
@@ -88,7 +88,7 @@ own modeling code) and `custom_pipeline` (fetches and imports a pipeline
 module from the Hub or a local path). Neither goes through an
 `importlib` call of ours, so the dotted-name gate alone would leave
 diffusers' remote-code paths open. A workflow that needs them
-(`workflows/Krea2Edit.json`, say) needs `--trust-workflows`.
+(`workflows/templates/image-edit.json`, say) needs `--trust-workflows`.
 
 `--trust-workflows` is a blanket, process-wide choice - it is not scoped
 per-workflow or per-request. A `dw-serve` instance that accepts jobs from
diff --git a/docs/TASKS.md b/docs/TASKS.md
index 4d62d171..82304027 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -305,7 +305,7 @@ the joined length, not the sum. When every input carries audio, the tracks are
 crossfaded over exactly the seam's span so they stay in step with the picture;
 when any input is silent the result is, and `pair_audio` puts a score under it.
 
-**Example:** [GyreDissolve.json](../workflows/gyre/GyreDissolve.json)
+**Example:** [dissolve-between-shots.json](../workflows/templates/dissolve-between-shots.json)
 
 ### stabilize_video
 
@@ -335,7 +335,7 @@ 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:** [GyreDissolve.json](../workflows/gyre/GyreDissolve.json)
+**Example:** [dissolve-between-shots.json](../workflows/templates/dissolve-between-shots.json)
 
 ### video_frames
 
@@ -364,7 +364,7 @@ An argument that goes through diffusers' video processor instead - LTX-2's
 IC-LoRA references - wants the `[0, 1]` frames the pipeline returned rather than
 this array; hand those over with `previous_result:step.frames`.
 
-**Example:** [LTX2Extend.json](../workflows/ltx2/LTX2Extend.json)
+**Example:** [extend-clip.json](../workflows/templates/ltx2/extend-clip.json)
 
 ### pair_audio
 
@@ -392,7 +392,7 @@ returns frames without it, and this puts it back:
 | `audio` | Yes | The soundtrack - a waveform, or the earlier step whose video carried one, which brings its sample rate along |
 | `sample_rate` | No | Sample rate of the waveform. Required unless `audio` carries one; given here it wins |
 
-**Example:** [LTX2TwoStage.json](../workflows/ltx2/LTX2TwoStage.json)
+**Example:** [two-stage.json](../workflows/templates/ltx2/two-stage.json)
 
 ### slice_audio
 
@@ -470,7 +470,7 @@ ending. The curve is the equal-power cosine the seam joins use:
 | `fade_out_ms` | No | Length of the fade out, to the tail of the track (default: 0) |
 | `sample_rate` | With a waveform | Sample rate of a directly passed waveform (files carry their own) |
 
-**Example:** [TrimFadeAudio.json](../workflows/tasks/TrimFadeAudio.json) — slice a generated track to length, then fade the cut into an ending.
+**Example:** [audio-trim-fade.json](../workflows/templates/audio-trim-fade.json) — slice a generated track to length, then fade the cut into an ending.
 
 ### normalize_audio
 
@@ -500,7 +500,7 @@ changes, so the dynamics survive:
 
 A silent track is returned unchanged.
 
-**Example:** [GyreDissolve.json](../workflows/gyre/GyreDissolve.json)
+**Example:** [dissolve-between-shots.json](../workflows/templates/dissolve-between-shots.json)
 
 ### mix_audio
 
@@ -533,7 +533,7 @@ shorter than the picture leaves the tail dry rather than cutting the picture
 down to fit. Summing can push peaks past full scale and the sum is *not*
 rescaled - follow it with `normalize_audio` to bring the peak back down.
 
-**Example:** [GyreDissolve.json](../workflows/gyre/GyreDissolve.json) — a
+**Example:** [dissolve-between-shots.json](../workflows/templates/dissolve-between-shots.json) — a
 generated score mixed under the shots' own audio.
 
 ### resample_audio
@@ -563,7 +563,7 @@ supplied recording once, up front, feeds it what it already wants:
 A track already at the target rate is returned untouched. The conversion is
 PyAV's, which dw already needs for video - no torchaudio dependency.
 
-**Example:** [GyreAssemble.json](../workflows/gyre/GyreAssemble.json)
+**Example:** [assemble-and-score.json](../workflows/templates/assemble-and-score.json)
 
 ## Data Gathering
 
@@ -653,8 +653,8 @@ Upscale images using spandrel-compatible super-resolution models (ESRGAN, SwinIR
 Large images are automatically tiled to avoid GPU memory issues. Models can be loaded from HuggingFace Hub repos or local `.pth`/`.safetensors` files.
 
 **Examples:**
-- [SpandrelUpscale.json](../workflows/tasks/SpandrelUpscale.json) — Generate at 512px, then 4x upscale to 2048px.
-- [UpscaleImage.json](../workflows/tasks/UpscaleImage.json) — Upscale an image you already have; there is no generation step, so the input is a path or URL.
+- [upscale-spandrel.json](../workflows/templates/upscale-spandrel.json) — Upscale any existing image 4x.
+- [upscale-spandrel.json](../workflows/templates/upscale-spandrel.json) — Upscale an image you already have; there is no generation step, so the input is a path or URL.
 
 ## Diffusion Upscaling
 
@@ -690,8 +690,8 @@ Two modes are available:
 | `noise_level` | No | Noise level for x4 mode (default: 20, ignored for x2) |
 
 **Examples:**
-- [DiffusionUpscale.json](../workflows/tasks/DiffusionUpscale.json) — Generate at 512px, then upscale. `mode` selects which: `x4` (the default) reaches 2048px, `x2` reaches 1024px through the latent upscaler.
-- [DiffusionUpscaleImage.json](../workflows/tasks/DiffusionUpscaleImage.json) — Prompt-guided upscale of an image you already have, with no generation step.
+- [upscale-diffusion.json](../workflows/templates/upscale-diffusion.json) — Upscale any existing image. `mode` selects which: `x4` (the default) reaches 2048px, `x2` reaches 1024px through the latent upscaler.
+- [upscale-diffusion.json](../workflows/templates/upscale-diffusion.json) — Prompt-guided upscale of an image you already have, with no generation step.
 
 ## Face Restoration
 
@@ -725,7 +725,7 @@ Restore and enhance faces in images using spandrel-compatible face restoration m
 
 Models are loaded via spandrel, so any `.pth`/`.safetensors` face restoration weights work. CodeFormer requires `pip install spandrel-extra-arches` (non-commercial license).
 
-**Example:** [FaceRestore.json](../workflows/tasks/FaceRestore.json) — Generate a portrait, then restore faces with GFPGAN v1.4.
+**Example:** [restore-faces.json](../workflows/templates/restore-faces.json) — Generate a portrait, then restore faces with GFPGAN v1.4.
 
 ### Combining with Upscaling
 
@@ -801,8 +801,8 @@ Returns a grayscale PIL Image (mode "L") — white (255) for detected objects, b
 
 **Examples:**
 
-- [Segment.json](../workflows/tasks/Segment.json) — Segment an object from an image
-- [SegmentAndInpaint.json](../workflows/tasks/SegmentAndInpaint.json) — Segment, then inpaint the masked region
+- [segment.json](../workflows/templates/segment.json) — Segment an object from an image
+- [segment-and-inpaint.json](../workflows/templates/segment-and-inpaint.json) — Segment, then inpaint the masked region
 
 ## Image Captioning
 
@@ -849,9 +849,9 @@ For Florence-2's advanced task-token captioning (detailed captions, object detec
 
 **Examples:**
 
-- [ImageToText.json](../workflows/tasks/ImageToText.json) — Basic captioning with the default model, saves as `.txt`
-- [ImageToTextVLM.json](../workflows/tasks/ImageToTextVLM.json) — Larger VLM answering a specific question
-- [CaptionToImage.json](../workflows/tasks/CaptionToImage.json) — Caption an image, then regenerate with Flux
+- [image-to-text.json](../workflows/templates/image-to-text.json) — Basic captioning with the default model, saves as `.txt`
+- [image-to-text.json](../workflows/templates/image-to-text.json) — Larger VLM answering a specific question
+- [describe-and-regenerate.json](../workflows/templates/describe-and-regenerate.json) — Describe an image, expand the caption, then regenerate it
 
 ## Extracting Sections
 
@@ -950,8 +950,8 @@ It is merged after everything else, so it can override `repetition_penalty` and
 
 **Examples:**
 
-- [ExpandPrompt.json](../workflows/tasks/ExpandPrompt.json) — Expand a short prompt and save as `.txt`
-- [ExpandAndGenerate.json](../workflows/tasks/ExpandAndGenerate.json) — Expand prompt, then generate with Flux
+- [expand-prompt.json](../workflows/templates/expand-prompt.json) — Expand a short prompt and save as `.txt`
+- [expand-prompt.json](../workflows/templates/expand-prompt.json) — Expand prompt, then generate with Flux
 
 ## Speech Generation
 
@@ -1001,12 +1001,12 @@ A speech model is worth releasing before a video model loads — set `release_mo
 
 **Examples:**
 
-- [GenerateSpeech.json](../workflows/tasks/GenerateSpeech.json) — Speak a line and save it as a `.wav`
-- [MiniMaxH3GeneratedVoice.json](../workflows/minimax/MiniMaxH3GeneratedVoice.json) — Generate a voice, then condition H3's `<Audio 1>` on it
+- [generate-speech.json](../workflows/templates/generate-speech.json) — Speak a line and save it as a `.wav`
+- [voice-timbre-reference.json](../workflows/templates/minimax/voice-timbre-reference.json) — Generate a voice, then condition H3's `<Audio 1>` on it
 
 ## Frame Interpolation
 
-Increase video frame rate using RIFE (Real-Time Intermediate Flow Estimation). Takes a video and inserts intermediate frames between each pair. The result is one video artifact without a soundtrack - the frame count changed, so [`pair_audio`](#pair_audio) is how the original track comes back. [InterpolateFrames.json](../workflows/InterpolateFrames.json) shows the interpolation itself.
+Increase video frame rate using RIFE (Real-Time Intermediate Flow Estimation). Takes a video and inserts intermediate frames between each pair. The result is one video artifact without a soundtrack - the frame count changed, so [`pair_audio`](#pair_audio) is how the original track comes back. [interpolate-frames.json](../workflows/templates/interpolate-frames.json) shows the interpolation itself.
 
 ```json
 {
@@ -1030,7 +1030,7 @@ Increase video frame rate using RIFE (Real-Time Intermediate Flow Estimation). T
 
 Uses vendored IFNet v4.13 architecture. Weights are downloaded from HuggingFace Hub on first use.
 
-**Example:** [InterpolateFrames.json](../workflows/InterpolateFrames.json) — Generate video with Mochi, then 2x interpolate from 30fps to 60fps.
+**Example:** [interpolate-frames.json](../workflows/templates/interpolate-frames.json) — Generate video with Mochi, then 2x interpolate from 30fps to 60fps.
 
 ## Metadata Embedding
 
@@ -1052,7 +1052,7 @@ Embed generation parameters in saved images. Enable by setting `embed_metadata:
 
 Metadata includes step name, model name, and generation arguments (prompt, steps, guidance scale, etc.) as JSON.
 
-**Example:** [MetadataEmbed.json](../workflows/tasks/MetadataEmbed.json) — Generate with Flux and embed parameters in PNG.
+**Example:** [embed-metadata.json](../workflows/templates/embed-metadata.json) — Generate with Flux and embed parameters in PNG.
 
 ## QR Code Generation
 
@@ -1075,7 +1075,7 @@ Metadata includes step name, model name, and generation arguments (prompt, steps
 
 The QR code is generated then resampled to `max(height, width)`, aligned to the nearest 64px multiple.
 
-**Example:** [qr_code.json](../workflows/archive/qr_code.json) — QR code with artistic ControlNet
+**Example:** [qr-code.json](../workflows/templates/qr-code.json) — QR code with artistic ControlNet
 
 ## Chat/Dict Plumbing
 
@@ -1198,23 +1198,23 @@ Canny edge detection followed by ControlNet generation:
 
 ## Examples
 
-- [FluxCanny.json](../workflows/flux/FluxCanny.json) — Canny edge ControlNet
-- [FluxDepth.json](../workflows/flux/FluxDepth.json) — Depth-guided generation
-- [qr_code.json](../workflows/archive/qr_code.json) — QR code with artistic ControlNet
-- [SpandrelUpscale.json](../workflows/tasks/SpandrelUpscale.json) — Generate + spandrel 4x upscale
-- [FaceRestore.json](../workflows/tasks/FaceRestore.json) — Generate portrait + GFPGAN face restoration
-- [Segment.json](../workflows/tasks/Segment.json) — Text-prompted object segmentation
-- [SegmentAndInpaint.json](../workflows/tasks/SegmentAndInpaint.json) — Segment + inpaint
-- [ImageToText.json](../workflows/tasks/ImageToText.json) — image captioning with the SmolVLM default
-- [ImageToTextVLM.json](../workflows/tasks/ImageToTextVLM.json) — VLM captioning with a specific question
-- [CaptionToImage.json](../workflows/tasks/CaptionToImage.json) — Caption then regenerate
-- [InterpolateFrames.json](../workflows/InterpolateFrames.json) — RIFE frame interpolation
-- [MetadataEmbed.json](../workflows/tasks/MetadataEmbed.json) — Embed generation parameters in PNG
-- [ExpandPrompt.json](../workflows/tasks/ExpandPrompt.json) — LLM prompt expansion
-- [ExpandAndGenerate.json](../workflows/tasks/ExpandAndGenerate.json) — Expand prompt + generate image
-- [UpscaleImage.json](../workflows/tasks/UpscaleImage.json) — Spandrel upscale of an existing image
-- [DiffusionUpscaleImage.json](../workflows/tasks/DiffusionUpscaleImage.json) — Diffusion upscale of an existing image
-- [TrimFadeAudio.json](../workflows/tasks/TrimFadeAudio.json) — Trim a generated track and fade its tail
-- [GenerateSpeech.json](../workflows/tasks/GenerateSpeech.json) — Speak a line with a local text-to-speech model
-- [MiniMaxH3GeneratedVoice.json](../workflows/minimax/MiniMaxH3GeneratedVoice.json) — Generate a voice and condition H3's `<Audio 1>` on it
-- [GyreDissolve.json](../workflows/gyre/GyreDissolve.json) — Stabilize generated shots, dissolve between them, and mix a score under their own audio
+- [controlnet.json](../workflows/templates/controlnet.json) — Canny edge ControlNet
+- [controlnet.json](../workflows/templates/controlnet.json) — Depth-guided generation
+- [qr-code.json](../workflows/templates/qr-code.json) — QR code with artistic ControlNet
+- [upscale-spandrel.json](../workflows/templates/upscale-spandrel.json) — Spandrel 4x upscale of an existing image
+- [restore-faces.json](../workflows/templates/restore-faces.json) — Generate portrait + GFPGAN face restoration
+- [segment.json](../workflows/templates/segment.json) — Text-prompted object segmentation
+- [segment-and-inpaint.json](../workflows/templates/segment-and-inpaint.json) — Segment + inpaint
+- [image-to-text.json](../workflows/templates/image-to-text.json) — image captioning with the SmolVLM default
+- [image-to-text.json](../workflows/templates/image-to-text.json) — VLM captioning with a specific question
+- [describe-and-regenerate.json](../workflows/templates/describe-and-regenerate.json) — Describe, expand, then regenerate
+- [interpolate-frames.json](../workflows/templates/interpolate-frames.json) — RIFE frame interpolation
+- [embed-metadata.json](../workflows/templates/embed-metadata.json) — Embed generation parameters in PNG
+- [expand-prompt.json](../workflows/templates/expand-prompt.json) — LLM prompt expansion
+- [expand-prompt.json](../workflows/templates/expand-prompt.json) — Expand prompt + generate image
+- [upscale-spandrel.json](../workflows/templates/upscale-spandrel.json) — Spandrel upscale of an existing image
+- [upscale-diffusion.json](../workflows/templates/upscale-diffusion.json) — Diffusion upscale of an existing image
+- [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
diff --git a/docs/TESTING.md b/docs/TESTING.md
index fe134a5f..c7d20603 100644
--- a/docs/TESTING.md
+++ b/docs/TESTING.md
@@ -67,5 +67,5 @@ An autouse `_clear_task_model_cache` fixture clears `dw.tasks.model_cache` befor
 python -m dw.test
 
 # Validate a workflow against schema
-python -m dw.validate workflows/flux/FluxDev.json
+python -m dw.validate workflows/models/flux-dev.json
 ```
diff --git a/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md
index ad811e91..1d69ee3b 100644
--- a/docs/WORKFLOW_GUIDE.md
+++ b/docs/WORKFLOW_GUIDE.md
@@ -72,7 +72,7 @@ inverted latents:
 ```
 
 `reference_name` must name a step earlier in the same workflow that has a `pipeline`.
-See [workflows/flux/FluxRFInversion.json](../workflows/flux/FluxRFInversion.json) for a full example.
+See [workflows/templates/community-pipeline.json](../workflows/templates/community-pipeline.json) for a full example.
 
 ### Task Steps
 
@@ -400,8 +400,8 @@ cache and succeeds on the retry - but each one is a synchronising stall, and a r
 close to the limit fails outright on any workload that needs slightly more. Every
 MiniMax H3 example uses on-demand VAEs for this reason.
 
-**Example:** [MiniMaxH3Ref2VA.json](../workflows/minimax/MiniMaxH3Ref2VA.json),
-[MiniMaxH3I2V.json](../workflows/minimax/MiniMaxH3I2V.json)
+**Example:** [reference-to-video.json](../workflows/templates/minimax/reference-to-video.json),
+[image-to-video.json](../workflows/templates/minimax/image-to-video.json)
 
 #### Releasing a pipeline mid-workflow
 
@@ -443,7 +443,7 @@ The flag applies to any step type, and on a `workflow` step it fires once the wh
 sub-workflow has finished. It clears every cached task model, not only this step's, and a
 later step needing one of them reloads it.
 
-**Example:** [MiniMaxH3EnhancePrompt.json](../workflows/minimax/MiniMaxH3EnhancePrompt.json)
+**Example:** [enhance-prompt.json](../workflows/templates/minimax/enhance-prompt.json)
 
 ### VAE Options
 
@@ -475,7 +475,7 @@ Attach one or more LoRAs to a pipeline with `loras`, a sibling of `configuration
 - `adapter_name` — name passed to `set_adapters()`. Defaults to the LoRA's index in the list.
 - `scale` — the adapter's weight, passed to `set_adapters()`. Defaults to `1.0`.
 
-See [workflows/flux/FluxLora.json](../workflows/flux/FluxLora.json) for a full example.
+See [workflows/templates/lora.json](../workflows/templates/lora.json) for a full example.
 
 ### IP-Adapter
 
@@ -489,7 +489,7 @@ See [workflows/flux/FluxLora.json](../workflows/flux/FluxLora.json) for a full e
 
 `model_name` is required; `weight_name`, `subfolder` and `scale` are optional. The
 adapter image itself is passed as a normal `ip_adapter_image` pipeline argument. See
-[workflows/archive/ip-adapter.json](../workflows/archive/ip-adapter.json).
+[workflows/templates/ip-adapter.json](../workflows/templates/ip-adapter.json).
 
 ### Sharing Components Across Steps
 
@@ -548,7 +548,7 @@ stays alive for the steps that reuse it.
   don't accept one.
 - `inversion` — run the pipeline's `invert()` instead of the pipeline itself; the step
   returns the inverted/image latents for a later step to consume (see
-  [FluxRFInversion.json](../workflows/flux/FluxRFInversion.json)).
+  [community-pipeline.json](../workflows/templates/community-pipeline.json)).
 - `generate` — run the pipeline's `generate()` instead, for components with a
   generation head (the step returns `generated_ids`).
 
@@ -567,7 +567,7 @@ Two mutually exclusive ways to speed up inference by skipping redundant computat
 `num_inference_steps`, `max_skip_steps`, `retention_ratio`, `cache_interval`,
 `max_order`, `mag_ratios`, `calibrate` — see [dw/workflow_schema.json](../dw/workflow_schema.json) for which
 fields apply to which type). See
-[workflows/flux/FluxDevFirstBlockCache.json](../workflows/flux/FluxDevFirstBlockCache.json).
+[workflows/templates/step-caching.json](../workflows/templates/step-caching.json).
 
 ```json
 "configuration": {
@@ -699,11 +699,11 @@ downloaded and loaded:
 A task is chosen by the arguments the step passes, so one `workflow` name can cover more
 than one of them: MiniMax-H3's `fl2va` takes an `image`, a `last_image`, or both. Given
 only a `last_image` it generates *up to* that frame, inventing everything that leads to
-it — see [workflows/minimax/MiniMaxH3L2V.json](../workflows/minimax/MiniMaxH3L2V.json) beside
-[workflows/minimax/MiniMaxH3FL2VA.json](../workflows/minimax/MiniMaxH3FL2VA.json).
+it — see [workflows/templates/minimax/last-frame-only.json](../workflows/templates/minimax/last-frame-only.json) beside
+[workflows/templates/minimax/first-and-last-frame.json](../workflows/templates/minimax/first-and-last-frame.json).
 
-See [workflows/minimax/MiniMaxMusic.json](../workflows/minimax/MiniMaxMusic.json) and
-[workflows/minimax/MiniMaxH3.json](../workflows/minimax/MiniMaxH3.json) for full examples.
+See [workflows/templates/minimax/music.json](../workflows/templates/minimax/music.json) and
+[workflows/templates/minimax/video-with-audio.json](../workflows/templates/minimax/video-with-audio.json) for full examples.
 
 ### Chained Video Generation
 
@@ -779,9 +779,9 @@ chain. Expect some visual drift across many segments with `last_frame` continuit
 it is single-frame conditioning; `last_segment` continuity exists for exactly that,
 where the pipeline can take a video reference.
 
-See [workflows/ltx2/LTX2I2VChained.json](../workflows/ltx2/LTX2I2VChained.json),
-[workflows/minimax/MiniMaxH3I2VChained.json](../workflows/minimax/MiniMaxH3I2VChained.json), and
-[workflows/minimax/MiniMaxH3Ref2VAChained.json](../workflows/minimax/MiniMaxH3Ref2VAChained.json)
+See [workflows/templates/ltx2/chained-segments.json](../workflows/templates/ltx2/chained-segments.json),
+[workflows/templates/minimax/chained-segments.json](../workflows/templates/minimax/chained-segments.json), and
+[workflows/templates/minimax/chain-matched-to-audio.json](../workflows/templates/minimax/chain-matched-to-audio.json)
 (audio-matched lip-sync of arbitrary length).
 
 ## Schedulers
@@ -834,7 +834,7 @@ settable per run without editing the file:
 ```
 
 ```bash
-python -m dw.run workflows/ZImage.json seed=1234
+python -m dw.run workflows/models/z-image.json seed=1234
 ```
 
 Declare the variable with an integer default, as above: the value from the command line
@@ -1055,7 +1055,7 @@ its own 24 fps, so a wrong rate is a request conditioned at the wrong speed —
 motion and camera alone. A name that is neither an argument of `from_file()` nor a field
 of the object raises, with the fields it does have.
 
-See [workflows/minimax/MiniMaxH3Ref2VA.json](../workflows/minimax/MiniMaxH3Ref2VA.json) for a full example.
+See [workflows/templates/minimax/reference-to-video.json](../workflows/templates/minimax/reference-to-video.json) for a full example.
 
 ### Objects Built From an Earlier Step
 
@@ -1091,7 +1091,7 @@ Any other key is a field of the object and wins over what the media carried —
 not share, for instance. A step that produced several artifacts fans out the same way
 every `previous_result` reference does: four images in, four videos out.
 
-See [workflows/minimax/MiniMaxH3Ref2VAGeneratedSubject.json](../workflows/minimax/MiniMaxH3Ref2VAGeneratedSubject.json)
+See [workflows/templates/minimax/generated-subject-reference.json](../workflows/templates/minimax/generated-subject-reference.json)
 for a full example.
 
 ### Objects Built From Named Arguments
@@ -1138,8 +1138,8 @@ Which of the three forms a type wants is decided by the type, not by preference:
 | `from_previous_result` | declares a media `kind`, so a step's output lands in the right field on its own |
 | `from_arguments` | is a plain record of fields - no `from_file()`, no `kind` (LTX-2's conditions and references) |
 
-See [workflows/ltx2/LTX2Keyframes.json](../workflows/ltx2/LTX2Keyframes.json) for the file form and
-[workflows/ltx2/LTX2Extend.json](../workflows/ltx2/LTX2Extend.json) for the one built from an
+See [workflows/templates/ltx2/keyframes.json](../workflows/templates/ltx2/keyframes.json) for the file form and
+[workflows/templates/ltx2/extend-clip.json](../workflows/templates/ltx2/extend-clip.json) for the one built from an
 earlier step.
 
 ### Frames Across a Step Boundary
@@ -1177,4 +1177,4 @@ array, while an IC-LoRA reference goes through the video processor, which expect
 `[0, 1]` frames the pipeline returned - `previous_result:step.frames` hands those over
 untouched.
 
-**Example:** [workflows/ltx2/LTX2TwoStage.json](../workflows/ltx2/LTX2TwoStage.json)
+**Example:** [workflows/templates/ltx2/two-stage.json](../workflows/templates/ltx2/two-stage.json)
diff --git a/docs/WORKSPACES.md b/docs/WORKSPACES.md
index 50fa827a..4ce6dd76 100644
--- a/docs/WORKSPACES.md
+++ b/docs/WORKSPACES.md
@@ -42,7 +42,7 @@ The existing per-directory flags still work and each overrides exactly one
 folder of the workspace:
 
 ```bash
-python -m dw.run workflows/sd15.json -o /mnt/big-disk/renders
+python -m dw.run workflows/templates/text-to-image.json -o /mnt/big-disk/renders
 python -m dw.serve --workspace ~/studio --output-dir /mnt/big-disk/renders
 python -m dw.run some.json --prompt-dir ~/shared-prompts
 ```
@@ -67,7 +67,7 @@ An example from a checkout still runs by path, and writes into the workspace's
 outputs:
 
 ```bash
-DW_WORKSPACE=~/studio python -m dw.run ~/src/diffusers-workflow/workflows/sd15.json
+DW_WORKSPACE=~/studio python -m dw.run ~/src/diffusers-workflow/workflows/templates/text-to-image.json
 ```
 
 The server reports what it resolved at `GET /api/server`, under
diff --git a/docs/proposals/scripted-dialogue-and-tts.md b/docs/proposals/scripted-dialogue-and-tts.md
index 3b02eb12..7b9d7c87 100644
--- a/docs/proposals/scripted-dialogue-and-tts.md
+++ b/docs/proposals/scripted-dialogue-and-tts.md
@@ -34,7 +34,7 @@ So: script → TTS → `match_audio` trades away the one thing that works for fr
 
 ## The workflow already largely exists
 
-[`workflows/minimax/MiniMaxH3SitcomShort.json`](../../workflows/minimax/MiniMaxH3SitcomShort.json)
+[`workflows/templates/minimax/dialogue-short.json`](../../workflows/templates/minimax/dialogue-short.json)
 is nearly the described flow already:
 
 - two Z-Image steps draw the cast portraits (the second reuses the first's
@@ -67,7 +67,7 @@ which is "the track the mouth follows":
 
 1. **Voice *timbre* reference.** `ref2va` takes an `<Audio 1>` reference that
    fixes a voice while H3 still generates the speech — see
-   [`MiniMaxH3Ref2VA.json`](../../workflows/minimax/MiniMaxH3Ref2VA.json), whose
+   [`MiniMaxH3Ref2VA.json`](../../workflows/templates/minimax/reference-to-video.json), whose
    `retention_analysis` says explicitly that only timbre, pitch and delivery are
    referenced and "none of its content is reused". A few seconds of TTS per
    character, referenced in every shot, makes voice consistency an actual
@@ -113,8 +113,8 @@ Prototype either (a) the `generate_speech` task in its timbre-reference role, or
 (a) is implemented: the `generate_speech` task
 ([`dw/tasks/speech_generation.py`](../../dw/tasks/speech_generation.py),
 documented in [TASKS.md](../TASKS.md#speech-generation)), with
-[`GenerateSpeech.json`](../../workflows/tasks/GenerateSpeech.json) and
-[`MiniMaxH3GeneratedVoice.json`](../../workflows/minimax/MiniMaxH3GeneratedVoice.json)
+[`GenerateSpeech.json`](../../workflows/templates/generate-speech.json) and
+[`MiniMaxH3GeneratedVoice.json`](../../workflows/templates/minimax/voice-timbre-reference.json)
 showing the timbre-reference role.
 
 It returns an `AudioTrack` - a waveform carrying the rate it was generated at -
diff --git a/docs/proposals/sweeps-and-comparison.md b/docs/proposals/sweeps-and-comparison.md
index 06a3ef4b..8ce4a9f4 100644
--- a/docs/proposals/sweeps-and-comparison.md
+++ b/docs/proposals/sweeps-and-comparison.md
@@ -72,7 +72,7 @@ extending `arguments`:
 ```jsonc
 POST /api/jobs
 {
-  "workflow_path": "workflows/ZImage.json",
+  "workflow_path": "workflows/models/z-image.json",
   "arguments": { "prompt": "a cat", "num_images_per_prompt": 4 },
   "sweep": { "variable": "steps", "values": [20, 30, 40] }
 }
diff --git a/docs/superpowers/plans/2026-09-04-remote-gpu-server.md b/docs/superpowers/plans/2026-09-04-remote-gpu-server.md
index a43549f5..4f209836 100644
--- a/docs/superpowers/plans/2026-09-04-remote-gpu-server.md
+++ b/docs/superpowers/plans/2026-09-04-remote-gpu-server.md
@@ -1445,5 +1445,5 @@ Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
 
 1. `git pull && bash ./install.sh` on the box; install the unit per `contrib/systemd/README.md`.
 2. From the laptop: `curl http://<box>:8765/api/health -H "Authorization: Bearer <token>"` shows the box's hostname and `"device": "cuda"`.
-3. Browser: open `http://<box>:8765`, paste the token, run `workflows/sd15.json`. The POST must return 201, not 403 - that is Task 1 working.
+3. Browser: open `http://<box>:8765`, paste the token, run `workflows/templates/text-to-image.json`. The POST must return 201, not 403 - that is Task 1 working.
 4. `claude mcp add --transport http dw http://<box>:8765/mcp --header "Authorization: Bearer <token>"`, new session, `/mcp` shows connected, `get_health` returns the box's hostname, `list_workflows` returns the catalog, `run_workflow` on `sd15.json` with `acknowledged_cost=true` queues a job and `wait_for_job` sees it succeed.

From 4ebee188ebe6d5e1793f5ce4b81b60462c353ab9 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 15:15:31 -0500
Subject: [PATCH 15/32] Document the two-tree catalog and mark the inventory
 applied

templates/ teaches a pattern, models/ records what makes a checkpoint fit
and names the template it configures. The workflows guide leads with the
layout, and the MCP guide summary says so - that is the first thing an
agent matching a request's shape needs.

Also corrects the plan's own id check, which excluded only DELETE rows and
so would fail on the six COLLAPSE rows whose files were folded away.

Every reference class resolves: markdown links, sub-workflow paths, type
and constant references, and prompt: references.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs/WORKFLOW_GUIDE.md                        | 32 +++++++++++++++++++
 .../plans/2026-09-06-catalog-inventory.md     |  2 +-
 ...2026-09-06-workflow-catalog-restructure.md |  6 ++--
 dw_mcp/guides.py                              |  8 +++--
 4 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md
index 1d69ee3b..68a0b6ae 100644
--- a/docs/WORKFLOW_GUIDE.md
+++ b/docs/WORKFLOW_GUIDE.md
@@ -1,5 +1,37 @@
 # Workflow Guide
 
+## How the catalog is organised
+
+`workflows/` holds two trees, and which one a file is in says what it is for.
+
+**`workflows/templates/`** teaches a pattern. One file per capability - a shape
+(image to video, a multi-shot cut sequence), a mechanism (shared components,
+sub-workflows, `pipeline_reference`, typed references), or a reference
+convention (`prompt:`, `previous_result:`). These are what to read and copy.
+Where several checkpoints run the same pattern through the same pipeline class,
+one template carries them all and its `description` spells out the per-checkpoint
+argument sets, so the variations travel with the file rather than in a document
+that drifts from it. The `templates/ltx2/` and `templates/minimax/` subfolders
+each hold a family whose members build on one baseline.
+
+**`workflows/models/`** records a hardware fact: the quantization, offloading and
+component placement that make one checkpoint fit a real card. That is knowledge
+you cannot re-derive from a template, so it is kept runnable - but nobody learns
+a pattern from the fifth one, so these stay out of the way. Each carries a
+`configures` naming the template it is an instance of:
+
+```json
+{
+    "id": "flux-dev",
+    "description": "Text-to-image with FLUX.1 dev - the reference FLUX workflow.",
+    "configures": "templates/text-to-image",
+    "steps": [ ... ]
+}
+```
+
+The distinction exists because a catalog entry that cannot say which of the two
+it is leaves every reader - and every agent - to guess from the filename.
+
 ## Structure
 
 Every workflow is a JSON file with an `id`, optional `variables`, and a list of `steps`:
diff --git a/docs/superpowers/plans/2026-09-06-catalog-inventory.md b/docs/superpowers/plans/2026-09-06-catalog-inventory.md
index 1ab18f7c..78c2acec 100644
--- a/docs/superpowers/plans/2026-09-06-catalog-inventory.md
+++ b/docs/superpowers/plans/2026-09-06-catalog-inventory.md
@@ -4,7 +4,7 @@ Verdicts for every workflow under `workflows/`. Produced by Task 2 of the
 [restructure plan](2026-09-06-workflow-catalog-restructure.md); the file lists
 in Tasks 3-5 are this table, filtered by verdict.
 
-Status: approved 2026-09-06
+Status: applied 2026-09-06
 
 Counts: COLLAPSE INTO 6, DELETE 42, MODEL 9, TEMPLATE 64 (total 121)
 
diff --git a/docs/superpowers/plans/2026-09-06-workflow-catalog-restructure.md b/docs/superpowers/plans/2026-09-06-workflow-catalog-restructure.md
index 8d811246..b8d833e3 100644
--- a/docs/superpowers/plans/2026-09-06-workflow-catalog-restructure.md
+++ b/docs/superpowers/plans/2026-09-06-workflow-catalog-restructure.md
@@ -572,11 +572,13 @@ inv = pathlib.Path(
     "docs/superpowers/plans/2026-09-06-catalog-inventory.md"
 ).read_text()
 rows = [l.split("|") for l in inv.splitlines() if l.startswith("| workflows/")]
-deleted = {r[1].strip() for r in rows if r[2].strip() == "DELETE"}
+# An id survives only where its file survives as itself: DELETE removes the
+# file, and COLLAPSE folds it into another that keeps its own id
+gone = {r[1].strip() for r in rows if r[2].strip() in ("DELETE", "COLLAPSE INTO")}
 expected = {
     r[4].strip()
     for r in rows
-    if r[1].strip() not in deleted and r[4].strip() not in ("—", "")
+    if r[1].strip() not in gone and r[4].strip() not in ("—", "")
 }
 on_disk = {json.load(open(p))["id"] for p in pathlib.Path("workflows").rglob("*.json")}
 lost = sorted(expected - on_disk)
diff --git a/dw_mcp/guides.py b/dw_mcp/guides.py
index 17485b29..a8dc8568 100644
--- a/dw_mcp/guides.py
+++ b/dw_mcp/guides.py
@@ -30,9 +30,11 @@
 GUIDES = {
     "workflows": (
         "WORKFLOW_GUIDE.md",
-        "How a workflow is put together: steps, variables, the reference "
-        "conventions that carry data between steps, sub-workflows, and "
-        "releasing models mid-run. Read before authoring one.",
+        "How the catalog is organised - templates/ teaching a pattern, models/ "
+        "recording what makes a checkpoint fit - and how a workflow is put "
+        "together: steps, variables, the reference conventions that carry data "
+        "between steps, sub-workflows, and releasing models mid-run. Read "
+        "before authoring one.",
     ),
     "tasks": (
         "TASKS.md",

From 92a0951905dc4c7bff34c2b0705b86fdf147a93e Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 16:57:06 -0500
Subject: [PATCH 16/32] Group the catalog by full folder and mark model configs
 in the UI

The restructure regressed browsing without touching the UI. FolderGroups
grouped by the first path segment only, so the new layout collapsed to two
groups - templates (64) and models (9) - hiding the ltx2 and minimax
families entirely, where the old layout showed six. Gallery entries
regressed the same way: their names are <workflow identity>/<file> and the
identity is now itself a path, so every run grouped under 'templates'.

Grouping by everything but the last segment restores the structure and
fixes both pages, so it lives in one shared helper rather than being
recomputed per page.

The listing also carries 'configures' now, and a model config's card says
which template it is a tuned instance of - without it the two trees look
identical in the one place a person actually browses them.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 dw/server/app.py                      |  3 +++
 tests/test_server.py                  | 24 ++++++++++++++++++
 ui/src/lib/FolderGroups.svelte        |  3 +--
 ui/src/lib/grouping.test.ts           | 36 +++++++++++++++++++++++++++
 ui/src/lib/grouping.ts                | 15 +++++++++++
 ui/src/lib/pages/PromptsPage.svelte   |  4 +--
 ui/src/lib/pages/WorkflowsPage.svelte | 20 +++++++++++++--
 7 files changed, 99 insertions(+), 6 deletions(-)
 create mode 100644 ui/src/lib/grouping.test.ts
 create mode 100644 ui/src/lib/grouping.ts

diff --git a/dw/server/app.py b/dw/server/app.py
index bdfc9528..deb64cbc 100644
--- a/dw/server/app.py
+++ b/dw/server/app.py
@@ -192,6 +192,9 @@ def workflow_details(sources_by_name):
                 "variables": len(variables),
                 "variable_names": sorted(variables),
                 "description": str(definition.get("description", "") or ""),
+                # Empty for a template; a catalog name for a model config, which
+                # is what lets a client show the two as different kinds of thing
+                "configures": str(definition.get("configures", "") or ""),
                 "prompt_refs": sorted(collect_prompt_references(definition)),
             }
         except Exception:
diff --git a/tests/test_server.py b/tests/test_server.py
index 07c38867..2adf01b0 100644
--- a/tests/test_server.py
+++ b/tests/test_server.py
@@ -1336,6 +1336,7 @@ def test_workflow_listing_carries_details(server):
             "variables": 1,
             "variable_names": ["prompt"],
             "description": "Renders a small test image.",
+            "configures": "",
             "prompt_refs": [],
             # where it came from, and whether a client should offer save and
             # delete for it or only save-a-copy
@@ -1345,6 +1346,29 @@ def test_workflow_listing_carries_details(server):
         assert listing["details"]["Basic"]["kinds"] == []
 
 
+def test_workflow_details_name_the_template_a_model_config_configures(server):
+    """A model config is a tuned instance of a template, and a client that
+    cannot see which is which shows it as just another catalog entry - the
+    thing the two-tree layout exists to stop."""
+    with server(success_script) as client:
+        workflow = valid_workflow("tuned")
+        workflow["configures"] = "templates/text-to-image"
+        client.put("/api/workflows/models/Tuned", json={"workflow": workflow})
+
+        listing = client.get("/api/workflows").json()
+
+        assert listing["details"]["models/Tuned"]["configures"] == (
+            "templates/text-to-image"
+        )
+
+
+def test_a_workflow_that_configures_nothing_says_so(server):
+    with server(success_script) as client:
+        listing = client.get("/api/workflows").json()
+
+        assert listing["details"]["Basic"]["configures"] == ""
+
+
 @pytest.fixture
 def examples_server(tmp_path):
     """A server whose workspace library is empty and whose examples come
diff --git a/ui/src/lib/FolderGroups.svelte b/ui/src/lib/FolderGroups.svelte
index 4610d532..d7c55740 100644
--- a/ui/src/lib/FolderGroups.svelte
+++ b/ui/src/lib/FolderGroups.svelte
@@ -2,6 +2,7 @@
   import type { Snippet } from 'svelte'
   import { ChevronDown, ChevronRight, Plus } from '@lucide/svelte'
   import { storageGet, storageSet } from './storage'
+  import { groupOf } from './grouping'
 
   let {
     names,
@@ -29,8 +30,6 @@
     storageSet(collapseKey, $state.snapshot(collapsed))
   }
 
-  const groupOf = (name: string) =>
-    name.includes('/') ? name.split('/')[0] : ''
   const groups = $derived(
     [...new Set(names.map(groupOf))].sort((a, b) => a.localeCompare(b)),
   )
diff --git a/ui/src/lib/grouping.test.ts b/ui/src/lib/grouping.test.ts
new file mode 100644
index 00000000..2ead55ba
--- /dev/null
+++ b/ui/src/lib/grouping.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest'
+import { groupOf, leafOf } from './grouping'
+
+describe('groupOf', () => {
+  it('has no group for a name at the root', () => {
+    expect(groupOf('sd15')).toBe('')
+  })
+
+  it('groups a one-level name by its folder', () => {
+    expect(groupOf('models/flux-dev')).toBe('models')
+  })
+
+  it('keeps every folder level, not just the first', () => {
+    // The regression this exists to prevent: taking only the first segment put
+    // all 64 templates in one group and hid the ltx2 and minimax families
+    expect(groupOf('templates/minimax/dialogue-short')).toBe('templates/minimax')
+  })
+
+  it('groups a gallery entry by the workflow that wrote it', () => {
+    // A gallery name is <workflow identity>/<file>, and the identity is itself
+    // a path now
+    expect(groupOf('templates/ltx2/two-stage/still.png')).toBe(
+      'templates/ltx2/two-stage',
+    )
+  })
+})
+
+describe('leafOf', () => {
+  it('returns the whole name when there is no folder', () => {
+    expect(leafOf('sd15')).toBe('sd15')
+  })
+
+  it('returns the last segment, since the heading shows the rest', () => {
+    expect(leafOf('templates/minimax/dialogue-short')).toBe('dialogue-short')
+  })
+})
diff --git a/ui/src/lib/grouping.ts b/ui/src/lib/grouping.ts
new file mode 100644
index 00000000..4fe4722b
--- /dev/null
+++ b/ui/src/lib/grouping.ts
@@ -0,0 +1,15 @@
+/**
+ * How a catalog name splits into a folder group and the label shown on its card.
+ *
+ * The group is everything but the last segment, not just the first. Catalogs
+ * nest more than one level deep - workflows/templates/minimax/dialogue-short,
+ * and a gallery entry whose name is <workflow identity>/<file> where the
+ * identity is itself a path - so taking only the first segment collapses every
+ * one of those into a single group and hides the structure the folders carry.
+ */
+export const groupOf = (name: string) =>
+  name.includes('/') ? name.slice(0, name.lastIndexOf('/')) : ''
+
+/** The card label: the leaf, since the group heading already shows the rest. */
+export const leafOf = (name: string) =>
+  name.includes('/') ? name.slice(name.lastIndexOf('/') + 1) : name
diff --git a/ui/src/lib/pages/PromptsPage.svelte b/ui/src/lib/pages/PromptsPage.svelte
index dec1cb1b..b2f7592f 100644
--- a/ui/src/lib/pages/PromptsPage.svelte
+++ b/ui/src/lib/pages/PromptsPage.svelte
@@ -3,6 +3,7 @@
   import { api } from '../api'
   import Empty from '../Empty.svelte'
   import FolderGroups from '../FolderGroups.svelte'
+  import { leafOf } from '../grouping'
   import HintBar from '../HintBar.svelte'
   import type { PromptDetail } from '../types'
 
@@ -70,7 +71,6 @@
 >
   {#snippet card(name)}
     {@const detail = details[name]}
-    {@const group = name.includes('/') ? name.split('/')[0] : ''}
     <!-- The link is an overlay rather than a wrapper: buttons may not
          nest inside an anchor, and the chips are real buttons -->
     <div class="card panel">
@@ -82,7 +82,7 @@
       ></a>
       <span class="cardtop">
         <span class="cardname"
-          >{group ? name.split('/').slice(1).join('/') : name}</span
+          >{leafOf(name)}</span
         >
         {#if detail?.intended_model}
           <button
diff --git a/ui/src/lib/pages/WorkflowsPage.svelte b/ui/src/lib/pages/WorkflowsPage.svelte
index b2058359..0203c44e 100644
--- a/ui/src/lib/pages/WorkflowsPage.svelte
+++ b/ui/src/lib/pages/WorkflowsPage.svelte
@@ -3,6 +3,7 @@
   import { api } from '../api'
   import Empty from '../Empty.svelte'
   import FolderGroups from '../FolderGroups.svelte'
+  import { leafOf } from '../grouping'
   import HintBar from '../HintBar.svelte'
   import WorkspacePicker from '../WorkspacePicker.svelte'
   import { workspace } from '../workspace.svelte'
@@ -16,6 +17,7 @@
         steps?: number
         variables: number
         description: string
+        configures: string
         /** Which source the workflow was read from. */
         origin?: string
         /** False for a read-only source - an examples directory. */
@@ -82,7 +84,6 @@
 >
   {#snippet card(name)}
     {@const detail = details[name]}
-    {@const group = name.includes('/') ? name.split('/')[0] : ''}
     <a
       class="card panel"
       href={href(name)}
@@ -90,9 +91,14 @@
     >
       <span class="cardtop">
         <span class="cardname"
-          >{group ? name.split('/').slice(1).join('/') : name}</span
+          >{leafOf(name)}</span
         >
         <span class="cardmeta muted">
+          {#if detail?.configures}<span
+              class="configures"
+              title="a tuned configuration of {detail.configures}"
+              >configures {leafOf(detail.configures)}</span
+            >{/if}
           {#if detail?.writable === false}<span
               title="read-only: from the {detail.origin} directory"
               >{detail.origin}</span
@@ -183,6 +189,16 @@
     -webkit-box-orient: vertical;
     overflow: hidden;
   }
+  /* Marks a model config as a tuned instance of a template rather than a
+     pattern to copy - the one distinction the two-tree catalog turns on */
+  .configures {
+    border: 1px solid currentColor;
+    border-radius: 3px;
+    padding: 0 0.25rem;
+    opacity: 0.75;
+    white-space: nowrap;
+  }
+
   .cardmeta {
     display: inline-flex;
     align-items: center;

From b805f5a60dd58645303c2e633dd8a2c3526ad685 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 16:58:21 -0500
Subject: [PATCH 17/32] Propose indexing the catalog by shape and by measured
 runtime

The follow-on the restructure deferred, written up as a proposal rather
than left in the spec's 'what this unblocks' paragraph.

Derive a small shape vocabulary in workflow_details, which already parses
and caches every workflow, with an optional declared override where the
derivation is wrong. Report observed runtime from the jobs table.

Records the join problem as confirmed rather than assumed: jobs.workflow
stores the workflow's id, not its catalog path, and ids are not unique by
construction - two shared 'sd35' until archive/ was emptied.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs/proposals/catalog-shape-index.md         | 131 ++++++++++++++++++
 ...-06-workflow-catalog-restructure-design.md |   2 +-
 2 files changed, 132 insertions(+), 1 deletion(-)
 create mode 100644 docs/proposals/catalog-shape-index.md

diff --git a/docs/proposals/catalog-shape-index.md b/docs/proposals/catalog-shape-index.md
new file mode 100644
index 00000000..13124f75
--- /dev/null
+++ b/docs/proposals/catalog-shape-index.md
@@ -0,0 +1,131 @@
+# Proposal: indexing the catalog by shape, and by what a run costs
+
+Status: design only, no code changes. Follows the catalog restructure
+([spec](../superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md),
+[plan](../superpowers/plans/2026-09-06-workflow-catalog-restructure.md)), which
+deliberately deferred this piece: classifying a catalog about to be halved is
+wasted work, and the derivation gets more accurate once "template or model
+config" is a distinction it can read.
+
+## The question
+
+An agent is handed "make a lego movie trailer set in the marvel universe".
+Nothing in that names a workflow. What has to be matched is the *shape* of the
+deliverable - a multi-shot cut sequence, with a consistent cast and generated
+speech - against a catalog that says nothing about shape in machine-readable
+form. And once a candidate is found, nothing tells the agent whether running it
+costs ninety seconds or forty minutes.
+
+## What already shipped, and what it did not solve
+
+Three things landed on 2026-09-06 and between them they close about half of
+this:
+
+- **Two trees.** `workflows/templates/` teaches a pattern, `workflows/models/`
+  records what makes a checkpoint fit, and a model config names the template it
+  configures. 121 workflows became 73, so the eight that answer a multi-shot
+  video request are no longer buried under a hundred checkpoint iterations.
+- **`list_guides` / `get_guide`.** Nine curated docs served over MCP, indexed by
+  section, ~830 tokens for the whole index. An agent can look up how a shape is
+  expressed instead of guessing.
+- **The server instructions** now say to decide the deliverable's shape first
+  and match the catalog against that.
+
+What none of that does is make the shape *itself* readable. `list_workflows`
+returns a description written for a human who already knows the domain, plus
+`kinds` (image/video/audio), step and variable counts. "Multi-shot cut
+sequence" is nowhere in that, and neither is "this takes forty minutes".
+
+## Proposal 1: derive the shape, allow an override
+
+Compute a small, controlled shape vocabulary from the definition itself, in
+[`workflow_details`](../../dw/server/app.py) - which already parses every
+workflow and caches per file mtime, so this costs one pass over data it has in
+hand and no new I/O.
+
+What is derivable, and from what:
+
+| Shape fact | Read from |
+| --- | --- |
+| produces image / video / audio / text | result `content_type`s (already computed as `kinds`) |
+| single shot vs multi-shot cut sequence | a `concat_videos` / `dissolve_videos` step with more than one generation step feeding it |
+| chained / continued generation | a `chain` block, or `last_frame` / `last_segment` / `match_audio` |
+| conditioned on a supplied still | an image-to-video pipeline, or an `image` / `last_image` argument |
+| conditioned on identity | a `references` list |
+| speaks / has a soundtrack | an `audio` output, or a `generate_speech` step |
+| needs input media | an `asset:` reference or a `location` variable |
+| composes other workflows | a `workflow` step |
+| tuned for one checkpoint | `configures` is set |
+
+Derivation cannot go stale and needs no backfill across 73 files - the two
+properties that killed hand-authored tags when this was first considered. Where
+it gets a workflow wrong, an optional top-level `shape` block overrides it,
+declared in the schema beside `configures`. Only the odd ones need authoring.
+
+The risk worth naming: a controlled vocabulary is a commitment. Adding a value
+later is easy; changing what an existing value means silently breaks whatever
+matched on it. Keep the list short and concrete, and prefer "has a
+`concat_videos` step" over judgements like "cinematic".
+
+## Proposal 2: report what a run actually cost
+
+`list_workflows` should carry an observed runtime per workflow - median and run
+count - from the `jobs` table, which already holds `workflow`, `status`,
+`started_at` and `finished_at`. Measured beats estimated, needs no authoring,
+and improves as the box is used. It is the number that stops an agent casually
+queueing a forty-minute job, and it is the one thing about cost that no amount
+of reading the definition reveals.
+
+**The wrinkle, confirmed rather than assumed:** `jobs.workflow` stores
+`Workflow.name`, which is the workflow's **`id`** field
+([`dw/workflow.py:216`](../../dw/workflow.py)), not its catalog path. The
+listing is keyed by catalog name. So joining the two means mapping id to catalog
+name, and that mapping is neither free nor guaranteed unique - two workflows
+shared the id `sd35` until `archive/` was emptied, and nothing enforces
+uniqueness today.
+
+Three ways out, in the order I would try them:
+
+1. **Enforce unique ids** with a test, then map id to catalog name from the
+   details cache. Cheapest, and a duplicate id is already a latent step-cache
+   collision worth failing on for its own sake.
+2. **Record the catalog name on the job** alongside the id. Correct, but only
+   for jobs run after the change - the existing history stays unjoinable.
+3. **Join on the run directory's workflow identity**, which is path-derived.
+   Accurate for historical jobs too, but couples the listing to the output tree.
+
+(1) and (2) together are probably right: fail on duplicate ids now, and record
+the catalog name so the join stops depending on ids being unique forever.
+
+## Proposal 3: let the UI show it
+
+The restructure regressed the web UI before anything improved it - the folder
+grouping took only the first path segment, so the new layout collapsed to two
+groups and hid the `ltx2` and `minimax` families. That is fixed, and a model
+config's card now says which template it configures. What shape and runtime data
+would additionally buy:
+
+- **Filter by shape** on the workflows page. The existing filter matches name
+  and description text; shape values would make "show me multi-shot video"
+  a click rather than a guess at vocabulary.
+- **Runtime on the card**, beside the step and variable counts.
+- **Templates before model configs** in the default ordering, since one is for
+  reading and the other for reference.
+
+None of this is worth building before the data exists, and all of it is cheap
+once it does.
+
+## What this is not
+
+Not a recommendation engine. The point is to make the catalog's existing
+structure legible to something that cannot read prose carefully, not to guess
+what the user wants. If shape matching turns into scoring and ranking, it has
+gone too far - an agent that can see the shapes can do its own choosing.
+
+## Suggested next step
+
+Proposal 1 alone is useful and self-contained: it needs no schema migration
+beyond an optional block, no job-history join, and no UI. Ship the derived shape
+first, see whether an agent handed a vague request actually lands on the right
+workflow with it, and let that answer decide whether the runtime join is worth
+its complexity.
diff --git a/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md b/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md
index bb90ffa3..1f234f82 100644
--- a/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md
+++ b/docs/superpowers/specs/2026-09-06-workflow-catalog-restructure-design.md
@@ -213,7 +213,7 @@ built *after* this, not before. Two reasons: classifying a catalog about to be
 halved is wasted work, and the derivation gets materially more accurate once
 "template or model config" is a distinction it can read rather than infer.
 
-That piece, as agreed but not specified here: shape derived from the definition
+That piece is now specified in [docs/proposals/catalog-shape-index.md](../../proposals/catalog-shape-index.md). In outline, as agreed here: shape derived from the definition
 in `workflow_details` (`dw/server/app.py:154`, which already parses and caches
 per file) with an optional declared override where the derivation is wrong; and
 median observed runtime per workflow from the `jobs` table, which carries

From 3ed60ea87cfcfa6def7f04ce86e549623e9228fe Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 17:04:50 -0500
Subject: [PATCH 18/32] Declare configures on the shared listing type

The field was added to WorkflowsPage's local copy of the detail shape but
not to the api.ts type it is assigned from, so npm run check failed on the
incompatible index signature. Optional there, matching prompt_refs: the UI
can be talking to a server older than this field.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 ui/src/lib/api.ts                     | 3 +++
 ui/src/lib/pages/WorkflowsPage.svelte | 3 ++-
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/ui/src/lib/api.ts b/ui/src/lib/api.ts
index cc502a0a..36614f88 100644
--- a/ui/src/lib/api.ts
+++ b/ui/src/lib/api.ts
@@ -215,6 +215,9 @@ export const api = {
           steps?: number
           variables: number
           description: string
+          /** For a model config: the template it is a tuned instance of.
+           * Absent from an older server, and from every template. */
+          configures?: string
           prompt_refs?: string[]
           /** Which source it came from: 'workspace', 'examples', 'builtin'. */
           origin?: string
diff --git a/ui/src/lib/pages/WorkflowsPage.svelte b/ui/src/lib/pages/WorkflowsPage.svelte
index 0203c44e..bdfd9da4 100644
--- a/ui/src/lib/pages/WorkflowsPage.svelte
+++ b/ui/src/lib/pages/WorkflowsPage.svelte
@@ -17,7 +17,8 @@
         steps?: number
         variables: number
         description: string
-        configures: string
+        /** For a model config: the template it configures. */
+        configures?: string
         /** Which source the workflow was read from. */
         origin?: string
         /** False for a read-only source - an examples directory. */

From 78483494bded95f6011ecf75827d96eaf90257d4 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 17:11:45 -0500
Subject: [PATCH 19/32] Repoint the e2e specs at the restructured catalog

The Playwright suite drives the real catalog by name, so the renames broke
five specs: ZImage, flux/FluxDev, tasks/ImageToText and FluxFill no longer
exist. Routes now name the new paths, headings expect the full catalog
name and breadcrumbs the leaf.

The filter assertion is anchored as /^inpaint / rather than /inpaint/,
which matches both the inpaint template and segment-and-inpaint.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 ui/e2e/chrome.spec.ts                 |  6 ++---
 ui/e2e/expanding-text.spec.ts         |  6 ++---
 ui/e2e/responsive.spec.ts             |  4 ++--
 ui/e2e/smoke.spec.ts                  | 34 +++++++++++++++------------
 ui/src/lib/grouping.test.ts           |  4 +++-
 ui/src/lib/pages/PromptsPage.svelte   |  4 +---
 ui/src/lib/pages/WorkflowsPage.svelte |  4 +---
 7 files changed, 32 insertions(+), 30 deletions(-)

diff --git a/ui/e2e/chrome.spec.ts b/ui/e2e/chrome.spec.ts
index f01f0f4e..e568251b 100644
--- a/ui/e2e/chrome.spec.ts
+++ b/ui/e2e/chrome.spec.ts
@@ -99,14 +99,14 @@ test('tab order walks the nav row in reading order', async ({ page }) => {
 
 test('saving surfaces a toast, not a pinned banner', async ({ page }) => {
   test.setTimeout(60_000)
-  await page.goto('/#/edit/ZImage')
+  await page.goto('/#/edit/models/z-image')
   await page.getByRole('button', { name: 'Save', exact: true }).click()
   // success text arrives as a toast...
-  await expect(page.getByText(/Saved to .*ZImage\.json/)).toBeVisible({
+  await expect(page.getByText(/Saved to .*z-image\.json/)).toBeVisible({
     timeout: 30_000,
   })
   // ...and auto-dismisses instead of pinning the page down
-  await expect(page.getByText(/Saved to .*ZImage\.json/)).toHaveCount(0, {
+  await expect(page.getByText(/Saved to .*z-image\.json/)).toHaveCount(0, {
     timeout: 10_000,
   })
 })
diff --git a/ui/e2e/expanding-text.spec.ts b/ui/e2e/expanding-text.spec.ts
index 94119867..3027284c 100644
--- a/ui/e2e/expanding-text.spec.ts
+++ b/ui/e2e/expanding-text.spec.ts
@@ -78,10 +78,10 @@ test('long prose arguments collapse to a line and expand on demand', async ({
 })
 
 test('the run page shares the same field treatment', async ({ page }) => {
-  // FluxDev's prompt default is a stored-prompt reference - short - but
-  // guidance-style workflows aside, ZImage's prompt default is prose; use
+  // flux-dev's prompt default is a stored-prompt reference - short - but
+  // guidance-style workflows aside, z-image's prompt default is prose; use
   // the editor-saved definition instead to stay deterministic
-  await page.goto('/#/workflows/ZImage')
+  await page.goto('/#/workflows/models/z-image')
   await expect(page.getByLabel('num_inference_steps')).toBeVisible()
   // overrides render through the shared form: same grid, same input ids
   await expect(page.locator('input#var-prompt')).toBeVisible()
diff --git a/ui/e2e/responsive.spec.ts b/ui/e2e/responsive.spec.ts
index 2a5310c6..e0f5c0db 100644
--- a/ui/e2e/responsive.spec.ts
+++ b/ui/e2e/responsive.spec.ts
@@ -6,7 +6,7 @@ import { expect, test } from '@playwright/test'
 
 const ROUTES = [
   '#/workflows',
-  '#/workflows/ZImage',
+  '#/workflows/models/z-image',
   '#/prompts',
   '#/prompt-edit/scenic_landscape',
   '#/jobs',
@@ -39,7 +39,7 @@ for (const width of WIDTHS) {
     page,
   }) => {
     await page.setViewportSize({ width, height: 900 })
-    await page.goto('/#/edit/flux/FluxDev')
+    await page.goto('/#/edit/models/flux-dev')
     await page.waitForLoadState('networkidle')
     // loaded steps default to the compact digest - switch to full to render
     // the deepest layout (the component/arguments grid)
diff --git a/ui/e2e/smoke.spec.ts b/ui/e2e/smoke.spec.ts
index 37efc455..293f198f 100644
--- a/ui/e2e/smoke.spec.ts
+++ b/ui/e2e/smoke.spec.ts
@@ -9,13 +9,15 @@ test('workflow browser lists, describes and filters', async ({ page }) => {
   ).toBeVisible()
   // the filter searches descriptions, not just names
   await page.getByPlaceholder('filter…').fill('inpaint')
-  await expect(page.getByRole('link', { name: /FluxFill/ })).toBeVisible()
-  await expect(page.getByRole('link', { name: /^ZImage / })).toHaveCount(0)
+  await expect(page.getByRole('link', { name: /^inpaint / })).toBeVisible()
+  await expect(page.getByRole('link', { name: /^z-image / })).toHaveCount(0)
 })
 
 test('workflow page shows JSON and a run form', async ({ page }) => {
-  await page.goto('/#/workflows/ZImage')
-  await expect(page.getByRole('heading', { name: 'ZImage' })).toBeVisible()
+  await page.goto('/#/workflows/models/z-image')
+  await expect(
+    page.getByRole('heading', { name: 'models/z-image' }),
+  ).toBeVisible()
   // JSON is shown by default via Monaco
   await expect(page.locator('.monaco-editor').first()).toBeVisible({
     timeout: 20_000,
@@ -29,7 +31,7 @@ test('editor opens a workflow with introspected arguments', async ({
   page,
 }) => {
   test.setTimeout(120_000) // first describe imports the pipeline class server-side
-  await page.goto('/#/edit/flux/FluxDev')
+  await page.goto('/#/edit/models/flux-dev')
   await page.getByRole('button', { name: 'full' }).click()
   await expect(page.locator('#ct-0')).toHaveValue('FluxPipeline')
   // the arguments editor discovered real __call__ parameters - the
@@ -51,7 +53,7 @@ test('editor opens a workflow with introspected arguments', async ({
 })
 
 test('split view shows editable JSON beside the form', async ({ page }) => {
-  await page.goto('/#/edit/ZImage')
+  await page.goto('/#/edit/models/z-image')
   await page.getByRole('button', { name: /split/ }).click()
   await expect(page.locator('.jsoncol')).toBeVisible()
   // the live definition renders in a real editor
@@ -115,7 +117,7 @@ test('editor validates, saves into a new folder, and deletes', async ({
   page,
 }) => {
   test.setTimeout(60_000)
-  await page.goto('/#/edit/ZImage')
+  await page.goto('/#/edit/models/z-image')
   await page.getByRole('button', { name: 'Validate' }).click()
   await expect(page.getByText('schema-valid')).toBeVisible({ timeout: 30_000 })
 
@@ -148,14 +150,16 @@ test('editor validates, saves into a new folder, and deletes', async ({
 test('the editor breadcrumb walks back to the workflow it opened', async ({
   page,
 }) => {
-  await page.goto('/#/workflows/ZImage')
+  await page.goto('/#/workflows/models/z-image')
   await page.getByRole('link', { name: 'Edit', exact: true }).click()
-  await expect(page).toHaveURL(/#\/edit\/ZImage$/)
+  await expect(page).toHaveURL(/#\/edit\/models\/z-image$/)
   // the way back to the read-only page, which the bare "← workflows"
   // link never offered
-  await page.getByRole('link', { name: 'ZImage', exact: true }).click()
-  await expect(page).toHaveURL(/#\/workflows\/ZImage$/)
-  await expect(page.getByRole('heading', { name: 'ZImage' })).toBeVisible()
+  await page.getByRole('link', { name: 'z-image', exact: true }).click()
+  await expect(page).toHaveURL(/#\/workflows\/models\/z-image$/)
+  await expect(
+    page.getByRole('heading', { name: 'models/z-image' }),
+  ).toBeVisible()
 })
 
 test('prompts page lists, creates at the root, and deletes', async ({
@@ -253,7 +257,7 @@ test('models page inventories the hub cache', async ({ page }) => {
 })
 
 test('task steps get introspection-driven forms', async ({ page }) => {
-  await page.goto('/#/edit/tasks/ImageToText')
+  await page.goto('/#/edit/templates/image-to-text')
   await page.getByRole('button', { name: 'full' }).first().click()
   // the command's discovered schema renders labeled fields
   await expect(page.locator('label', { hasText: 'image' }).first()).toBeVisible(
@@ -268,7 +272,7 @@ test('task steps get introspection-driven forms', async ({ page }) => {
 test('editor flags a dangling reference without asking the server', async ({
   page,
 }) => {
-  await page.goto('/#/edit/ZImage')
+  await page.goto('/#/edit/models/z-image')
   await expect(page.locator('#wfvar-prompt')).toBeVisible()
   await expect(page.locator('.stepwarn')).toHaveCount(0)
   // removing the variable the step's prompt argument points at - the
@@ -284,7 +288,7 @@ test('editor flags a dangling reference without asking the server', async ({
 
 test('the theme toggle re-themes an open Monaco editor', async ({ page }) => {
   // Playwright's default colour scheme is light, so "system" starts light
-  await page.goto('/#/workflows/ZImage')
+  await page.goto('/#/workflows/models/z-image')
   const editor = page.locator('.monaco-editor').first()
   await expect(editor).toBeVisible({ timeout: 20_000 })
   await expect(editor).toHaveClass(/\bvs\b/)
diff --git a/ui/src/lib/grouping.test.ts b/ui/src/lib/grouping.test.ts
index 2ead55ba..6abd1af2 100644
--- a/ui/src/lib/grouping.test.ts
+++ b/ui/src/lib/grouping.test.ts
@@ -13,7 +13,9 @@ describe('groupOf', () => {
   it('keeps every folder level, not just the first', () => {
     // The regression this exists to prevent: taking only the first segment put
     // all 64 templates in one group and hid the ltx2 and minimax families
-    expect(groupOf('templates/minimax/dialogue-short')).toBe('templates/minimax')
+    expect(groupOf('templates/minimax/dialogue-short')).toBe(
+      'templates/minimax',
+    )
   })
 
   it('groups a gallery entry by the workflow that wrote it', () => {
diff --git a/ui/src/lib/pages/PromptsPage.svelte b/ui/src/lib/pages/PromptsPage.svelte
index b2f7592f..6839268d 100644
--- a/ui/src/lib/pages/PromptsPage.svelte
+++ b/ui/src/lib/pages/PromptsPage.svelte
@@ -81,9 +81,7 @@
         title={detail?.description || detail?.text || undefined}
       ></a>
       <span class="cardtop">
-        <span class="cardname"
-          >{leafOf(name)}</span
-        >
+        <span class="cardname">{leafOf(name)}</span>
         {#if detail?.intended_model}
           <button
             class="chip modelchip"
diff --git a/ui/src/lib/pages/WorkflowsPage.svelte b/ui/src/lib/pages/WorkflowsPage.svelte
index bdfd9da4..0ca55887 100644
--- a/ui/src/lib/pages/WorkflowsPage.svelte
+++ b/ui/src/lib/pages/WorkflowsPage.svelte
@@ -91,9 +91,7 @@
       title={detail?.description || undefined}
     >
       <span class="cardtop">
-        <span class="cardname"
-          >{leafOf(name)}</span
-        >
+        <span class="cardname">{leafOf(name)}</span>
         <span class="cardmeta muted">
           {#if detail?.configures}<span
               class="configures"

From 8d72e19d3d4e6baf0f1fc388e1f6056cea03aba8 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 17:15:39 -0500
Subject: [PATCH 20/32] format

---
 dw_mcp/guides.py                | 6 ++----
 tests/test_catalog_structure.py | 6 +++---
 tests/test_mcp_server.py        | 5 ++++-
 3 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/dw_mcp/guides.py b/dw_mcp/guides.py
index a8dc8568..d8ebe5e9 100644
--- a/dw_mcp/guides.py
+++ b/dw_mcp/guides.py
@@ -63,8 +63,7 @@
     ),
     "prompt-weighting": (
         "PROMPT_WEIGHTING.md",
-        "Emphasis and de-emphasis syntax in prompts, and which pipelines "
-        "honour it.",
+        "Emphasis and de-emphasis syntax in prompts, and which pipelines " "honour it.",
     ),
     "ip-adapter": (
         "IP_ADAPTER.md",
@@ -105,8 +104,7 @@ def read_guide(name):
     """
     if name not in GUIDES:
         raise DwApiError(
-            f"No guide named '{name}'. The guides are: "
-            f"{', '.join(sorted(GUIDES))}."
+            f"No guide named '{name}'. The guides are: " f"{', '.join(sorted(GUIDES))}."
         )
 
     path = _guide_file(GUIDES[name][0])
diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index 2f6f9309..6a4c97e5 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -38,9 +38,9 @@ def test_every_template_describes_itself(path):
     both, whatever its filename says."""
     definition = json.load(open(path, encoding="utf-8"))
 
-    assert definition.get("description", "").strip(), (
-        f"{os.path.relpath(path, REPO_ROOT)} has no description"
-    )
+    assert definition.get(
+        "description", ""
+    ).strip(), f"{os.path.relpath(path, REPO_ROOT)} has no description"
 
 
 MODELS_DIR = os.path.join(REPO_ROOT, "workflows", "models")
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index 73265f15..511e7ceb 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -449,7 +449,10 @@ def test_the_wiring_table_covers_every_registered_tool():
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
     "name,arguments",
-    [("list_guides", {}), ("get_guide", {"name": "tasks", "section": "Speech Generation"})],
+    [
+        ("list_guides", {}),
+        ("get_guide", {"name": "tasks", "section": "Speech Generation"}),
+    ],
 )
 async def test_the_guide_tools_reach_no_server(name, arguments):
     """They have to work against an engine that is not answering - and against a

From 02802629bc53d0866d43cc46703279ffc94819f7 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 17:49:57 -0500
Subject: [PATCH 21/32] Let a sub-workflow path climb to a sibling catalog
 folder

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 dw/workflow.py         |  8 +++--
 tests/test_examples.py | 26 +++++++++-----
 tests/test_workflow.py | 82 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 106 insertions(+), 10 deletions(-)

diff --git a/dw/workflow.py b/dw/workflow.py
index 28555b04..eb99431c 100644
--- a/dw/workflow.py
+++ b/dw/workflow.py
@@ -823,10 +823,14 @@ def create_step_action(
                         os.path.dirname(os.path.abspath(__file__)), "workflows"
                     )
                     path = os.path.join(confine_to, builtin_name)
-                # Handle relative paths
+                # Handle relative paths. A template under templates/ names a
+                # model config as '../models/x.json'; collapsing the '..' here
+                # is what lets the validator judge where the path actually
+                # lands rather than refusing the spelling - containment is
+                # still checked on the resolved path below
                 elif not os.path.isabs(path):
                     base_dir = os.path.dirname(self.file_spec)
-                    path = os.path.join(base_dir, path)
+                    path = os.path.normpath(os.path.join(base_dir, path))
 
                 # Validate the resolved path - confined when this workflow
                 # itself is (an inline/server-submitted run), so a
diff --git a/tests/test_examples.py b/tests/test_examples.py
index 6fafb709..83663743 100644
--- a/tests/test_examples.py
+++ b/tests/test_examples.py
@@ -1,8 +1,8 @@
 """Every example workflow loads, validates, and points at files that exist.
 
-The example workflows in workflows/ live in subfolders - flux/, ltx2/,
-minimax/, tasks/, archive/ - so discovery walks the tree rather than listing
-one directory.
+The example workflows in workflows/ live in subfolders - templates/ (with
+ltx2/ and minimax/ beneath it) and models/ - so discovery walks the tree
+rather than listing one directory.
 
 The reference check guards what subfolders put at risk: a workflow's path to
 another workflow resolves against the referencing file's own directory, so
@@ -77,15 +77,23 @@ def workflow_references(definition):
             yield from workflow_references(value)
 
 
-def resolve_reference(path, base_dir):
-    """Where a sub-workflow path points, or None when only a run can tell."""
+def resolve_reference(path, base_dir, variables=None):
+    """Where a sub-workflow path points, or None when only a run can tell.
+
+    A 'variable:' path is followed to the variable's default when the workflow
+    declares one - the shipped templates do, and a default that cannot be
+    reached is exactly the kind of break this test exists to catch.
+    """
     if path.startswith("variable:"):
-        return None  # supplied at run time
+        default = (variables or {}).get(path.removeprefix("variable:"))
+        if not isinstance(default, str):
+            return None  # supplied at run time
+        path = default
     if path.startswith("builtin:"):
         return os.path.join(BUILTIN_DIR, path.removeprefix("builtin:"))
     if os.path.isabs(path):
         return path
-    return os.path.join(base_dir, path)
+    return os.path.normpath(os.path.join(base_dir, path))
 
 
 @pytest.mark.parametrize("example_file", get_example_files())
@@ -107,7 +115,9 @@ def test_example_workflow_references_resolve(example_file):
         definition = json.load(file)
 
     for reference in workflow_references(definition):
-        target = resolve_reference(reference, os.path.dirname(path))
+        target = resolve_reference(
+            reference, os.path.dirname(path), definition.get("variables")
+        )
         if target is None:
             continue
         assert os.path.isfile(target), (
diff --git a/tests/test_workflow.py b/tests/test_workflow.py
index 4daf1744..9aeb4dd5 100644
--- a/tests/test_workflow.py
+++ b/tests/test_workflow.py
@@ -341,3 +341,85 @@ def test_builtin_sub_workflow_loads_under_a_confined_workflow(self, tmp_path):
 
         assert isinstance(child, Workflow)
         assert child.name == "test_job"
+
+
+class TestSubWorkflowPathsAcrossTheCatalog:
+    """A template under templates/ names a model config under models/ as
+    '../models/x.json'. The path is relative to the referencing file, so it has
+    to climb one directory - and it stays inside the workflows root, which is
+    the confinement that matters."""
+
+    def _catalog(self, tmp_path):
+        import json
+
+        (tmp_path / "templates").mkdir()
+        (tmp_path / "models").mkdir()
+        child = {
+            "id": "child",
+            "steps": [
+                {
+                    "name": "noop",
+                    "task": {"command": "get_dict_value", "arguments": {"dict": {"k": 1}, "key": "k"}},
+                }
+            ],
+        }
+        (tmp_path / "models" / "child.json").write_text(json.dumps(child))
+        parent = {
+            "id": "parent",
+            "steps": [
+                {
+                    "name": "sub",
+                    "workflow": {"path": "../models/child.json", "arguments": {}},
+                }
+            ],
+        }
+        parent_path = tmp_path / "templates" / "parent.json"
+        parent_path.write_text(json.dumps(parent))
+        return parent_path
+
+    def test_a_parent_directory_step_inside_the_root_is_allowed(self, tmp_path):
+        from dw.workflow import workflow_from_file
+
+        parent_path = self._catalog(tmp_path)
+        workflow = workflow_from_file(str(parent_path), str(tmp_path), str(tmp_path))
+
+        # create_step_action is what resolves the path; run() is what calls it.
+        # default_seed flows into the child's own "seed" (setdefault), whose
+        # schema wants an int or string - None is only safe where a
+        # SecurityError fires first, so this branch needs a real seed
+        action = workflow.create_step_action(
+            workflow.workflow_definition["steps"][0],
+            shared_components={},
+            previous_pipelines={},
+            default_seed=42,
+            device="cpu",
+        )
+
+        assert action is not None
+
+    def test_a_parent_directory_step_escaping_the_root_is_refused(self, tmp_path):
+        import json
+
+        from dw.security import SecurityError
+        from dw.workflow import workflow_from_file
+
+        root = tmp_path / "root"
+        root.mkdir()
+        outside = tmp_path / "outside.json"
+        outside.write_text(json.dumps({"id": "x", "steps": []}))
+        parent = {
+            "id": "parent",
+            "steps": [{"name": "sub", "workflow": {"path": "../outside.json", "arguments": {}}}],
+        }
+        parent_path = root / "parent.json"
+        parent_path.write_text(json.dumps(parent))
+        workflow = workflow_from_file(str(parent_path), str(root), str(root))
+
+        with pytest.raises(SecurityError):
+            workflow.create_step_action(
+                workflow.workflow_definition["steps"][0],
+                shared_components={},
+                previous_pipelines={},
+                default_seed=None,
+                device="cpu",
+            )

From a2f082449fb81cba5bc402785df6fa81c724beca Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 17:55:59 -0500
Subject: [PATCH 22/32] Confine a relative sub-workflow reference to the
 catalog root when unconfined

An unconfined CLI run (workflow_from_file with no workflow_dir) had only the
'..' regex standing between a relative sub-workflow path and the filesystem
above it. Normalising the path before validation (previous commit) collapsed
that regex's usefulness away, so a path like '../../../../etc/passwd.json'
would resolve and pass. Confine such a path to the nearest ancestor directory
literally named 'workflows', reusing the approach dw.runs.workflow_identity
uses for output naming (dw.workflow.catalog_root_dir), falling back to the
referencing file's own directory when there is no such ancestor.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 dw/workflow.py         |  30 ++++++++++++
 tests/test_workflow.py | 103 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 133 insertions(+)

diff --git a/dw/workflow.py b/dw/workflow.py
index eb99431c..2f254115 100644
--- a/dw/workflow.py
+++ b/dw/workflow.py
@@ -138,6 +138,26 @@ def workflow_output_subfolder(file_spec):
     return os.path.join(*parts[index + 1 :]) if index + 1 < len(parts) else ""
 
 
+def catalog_root_dir(file_spec):
+    """The nearest ancestor directory literally named 'workflows' of
+    file_spec, else file_spec's own directory.
+
+    Used to confine a relative sub-workflow reference when a run carries no
+    workflow_dir of its own (an unconfined CLI run) - the same "last
+    'workflows' segment" rule workflow_output_subfolder uses for output
+    naming, but returning the directory itself rather than what sits under
+    it.
+    """
+    directory = os.path.dirname(os.path.abspath(file_spec))
+    parts = os.path.normpath(directory).split(os.sep)
+    try:
+        index = len(parts) - 1 - parts[::-1].index("workflows")
+    except ValueError:
+        return directory
+
+    return os.sep.join(parts[: index + 1]) or os.sep
+
+
 def pipeline_cache_key(pipeline_definition):
     """Stable identity for a loaded pipeline.
 
@@ -831,6 +851,16 @@ def create_step_action(
                 elif not os.path.isabs(path):
                     base_dir = os.path.dirname(self.file_spec)
                     path = os.path.normpath(os.path.join(base_dir, path))
+                    # An unconfined run (no workflow_dir - a bare CLI
+                    # invocation) used to rely on the '..' regex alone to
+                    # stop a relative reference from leaving the file's own
+                    # directory; normalising the path removes that guard, so
+                    # here confine it to the catalog root instead - the
+                    # referencing file's nearest ancestor literally named
+                    # 'workflows', which still lets it climb to a sibling
+                    # folder like models/ but not out of the catalog
+                    if confine_to is None:
+                        confine_to = catalog_root_dir(self.file_spec)
 
                 # Validate the resolved path - confined when this workflow
                 # itself is (an inline/server-submitted run), so a
diff --git a/tests/test_workflow.py b/tests/test_workflow.py
index 9aeb4dd5..3be11dbe 100644
--- a/tests/test_workflow.py
+++ b/tests/test_workflow.py
@@ -423,3 +423,106 @@ def test_a_parent_directory_step_escaping_the_root_is_refused(self, tmp_path):
                 default_seed=None,
                 device="cpu",
             )
+
+    def test_an_unconfined_run_still_refuses_climbing_out_of_the_catalog(self, tmp_path):
+        """No workflow_dir (a bare CLI run) still confines a relative
+        sub-workflow reference - to the catalog root now, rather than
+        relying on the '..' regex normpath removes."""
+        import json
+
+        from dw.security import SecurityError
+        from dw.workflow import workflow_from_file
+
+        (tmp_path / "workflows" / "templates").mkdir(parents=True)
+        outside = tmp_path / "outside.json"
+        outside.write_text(json.dumps({"id": "x", "steps": []}))
+        parent = {
+            "id": "parent",
+            "steps": [
+                {"name": "sub", "workflow": {"path": "../../outside.json", "arguments": {}}}
+            ],
+        }
+        parent_path = tmp_path / "workflows" / "templates" / "parent.json"
+        parent_path.write_text(json.dumps(parent))
+        workflow = workflow_from_file(str(parent_path), str(tmp_path))
+
+        with pytest.raises(SecurityError):
+            workflow.create_step_action(
+                workflow.workflow_definition["steps"][0],
+                shared_components={},
+                previous_pipelines={},
+                default_seed=42,
+                device="cpu",
+            )
+
+    def test_an_unconfined_run_may_climb_to_a_sibling_catalog_folder(self, tmp_path):
+        """No workflow_dir, but the reference still stays under the nearest
+        ancestor literally named 'workflows' - the catalog root - so it is
+        still allowed to climb from templates/ to models/."""
+        import json
+
+        from dw.workflow import workflow_from_file
+
+        (tmp_path / "workflows" / "templates").mkdir(parents=True)
+        (tmp_path / "workflows" / "models").mkdir(parents=True)
+        child = {
+            "id": "child",
+            "steps": [
+                {
+                    "name": "noop",
+                    "task": {"command": "get_dict_value", "arguments": {"dict": {"k": 1}, "key": "k"}},
+                }
+            ],
+        }
+        (tmp_path / "workflows" / "models" / "child.json").write_text(json.dumps(child))
+        parent = {
+            "id": "parent",
+            "steps": [
+                {"name": "sub", "workflow": {"path": "../models/child.json", "arguments": {}}}
+            ],
+        }
+        parent_path = tmp_path / "workflows" / "templates" / "parent.json"
+        parent_path.write_text(json.dumps(parent))
+        workflow = workflow_from_file(str(parent_path), str(tmp_path))
+
+        action = workflow.create_step_action(
+            workflow.workflow_definition["steps"][0],
+            shared_components={},
+            previous_pipelines={},
+            default_seed=42,
+            device="cpu",
+        )
+
+        assert action is not None
+
+    def test_a_file_outside_any_catalog_is_confined_to_its_own_directory(self, tmp_path):
+        """No 'workflows' ancestor at all - the referencing file's own
+        directory is the confinement, so a sibling of a sibling is still
+        refused even though the target file genuinely exists."""
+        import json
+
+        from dw.security import SecurityError
+        from dw.workflow import workflow_from_file
+
+        (tmp_path / "a").mkdir()
+        (tmp_path / "b").mkdir()
+        child = {"id": "child", "steps": []}
+        (tmp_path / "b" / "child.json").write_text(json.dumps(child))
+        parent = {
+            "id": "parent",
+            "steps": [
+                {"name": "sub", "workflow": {"path": "../b/child.json", "arguments": {}}}
+            ],
+        }
+        parent_path = tmp_path / "a" / "parent.json"
+        parent_path.write_text(json.dumps(parent))
+        workflow = workflow_from_file(str(parent_path), str(tmp_path))
+
+        with pytest.raises(SecurityError):
+            workflow.create_step_action(
+                workflow.workflow_definition["steps"][0],
+                shared_components={},
+                previous_pipelines={},
+                default_seed=42,
+                device="cpu",
+            )

From 6cb6e8858018343dc144d02526e7293b1f6af223 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 18:03:25 -0500
Subject: [PATCH 23/32] Group gallery runs by the folder the server computed

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 ui/e2e/serve_fixture.py             |  9 ++++++
 ui/e2e/smoke.spec.ts                | 17 +++++++++++
 ui/src/lib/FolderGroups.svelte      | 14 +++++----
 ui/src/lib/FolderGroups.test.ts     | 45 +++++++++++++++++++++++++++++
 ui/src/lib/grouping.test.ts         | 32 ++++++++++++++++----
 ui/src/lib/grouping.ts              | 22 ++++++++++++++
 ui/src/lib/pages/GalleryPage.svelte |  4 +++
 7 files changed, 131 insertions(+), 12 deletions(-)
 create mode 100644 ui/src/lib/FolderGroups.test.ts

diff --git a/ui/e2e/serve_fixture.py b/ui/e2e/serve_fixture.py
index 3b9b5959..38ede9a6 100644
--- a/ui/e2e/serve_fixture.py
+++ b/ui/e2e/serve_fixture.py
@@ -39,6 +39,15 @@
     with open(os.path.join(outputs, name), "wb") as handle:
         handle.write(ONE_PIXEL_PNG)
 
+# Two runs of the same workflow, in the <identity>/<run id>/<file> shape a
+# real execution writes - so the gallery has something to fold under one
+# folder heading instead of one per run.
+for run_id in ("20260906-101500-a1b2c3d4", "20260906-101612-ffffffff"):
+    run_dir = os.path.join(outputs, "e2e-run-group", run_id)
+    os.makedirs(run_dir)
+    with open(os.path.join(run_dir, "still.png"), "wb") as handle:
+        handle.write(ONE_PIXEL_PNG)
+
 os.chdir(root)
 os.execv(
     sys.executable,
diff --git a/ui/e2e/smoke.spec.ts b/ui/e2e/smoke.spec.ts
index 293f198f..cd8788ba 100644
--- a/ui/e2e/smoke.spec.ts
+++ b/ui/e2e/smoke.spec.ts
@@ -202,6 +202,23 @@ test('jobs and gallery pages render', async ({ page }) => {
   await expect(page.getByRole('heading', { name: 'Gallery' })).toBeVisible()
 })
 
+test('gallery groups every run of a workflow under one folder', async ({
+  page,
+}) => {
+  await page.goto('/#/gallery')
+  // The fixture seeds two runs of the same workflow; a heading per run would
+  // show a timestamped folder name. Scoped to the folder headings
+  // (`.group`) rather than every button - a cell's image `alt` is the full
+  // file name and would otherwise also match the run id pattern.
+  const folderHeadings = page.locator('.group')
+  await expect(
+    folderHeadings.filter({ hasText: /\d{8}-\d{6}-[0-9a-f]{8}/ }),
+  ).toHaveCount(0)
+  await expect(
+    folderHeadings.filter({ hasText: 'e2e-run-group/' }),
+  ).toBeVisible()
+})
+
 test('downloads a multi-file gallery selection as one zip', async ({
   page,
 }) => {
diff --git a/ui/src/lib/FolderGroups.svelte b/ui/src/lib/FolderGroups.svelte
index d7c55740..9560656d 100644
--- a/ui/src/lib/FolderGroups.svelte
+++ b/ui/src/lib/FolderGroups.svelte
@@ -2,7 +2,7 @@
   import type { Snippet } from 'svelte'
   import { ChevronDown, ChevronRight, Plus } from '@lucide/svelte'
   import { storageGet, storageSet } from './storage'
-  import { groupOf } from './grouping'
+  import { groupNames, groupOf as defaultGroupOf } from './grouping'
 
   let {
     names,
@@ -11,6 +11,7 @@
     newHref = undefined,
     onnewingroup = undefined,
     minColumn = '210px',
+    groupOf = defaultGroupOf,
     card,
   }: {
     names: string[]
@@ -19,6 +20,9 @@
     newHref?: string
     onnewingroup?: (group: string) => void
     minColumn?: string
+    /** Which folder a name belongs to. The gallery passes its own: its
+     * names carry a run id that the server has already folded into `folder`. */
+    groupOf?: (name: string) => string
     card: Snippet<[string]>
   } = $props()
 
@@ -30,11 +34,9 @@
     storageSet(collapseKey, $state.snapshot(collapsed))
   }
 
-  const groups = $derived(
-    [...new Set(names.map(groupOf))].sort((a, b) => a.localeCompare(b)),
-  )
-  const inGroup = (group: string) =>
-    names.filter((name) => groupOf(name) === group)
+  const grouped = $derived(groupNames(names, groupOf))
+  const groups = $derived([...grouped.keys()])
+  const inGroup = (group: string) => grouped.get(group) ?? []
   // While filtering, everything stays visible - a collapsed folder hiding
   // matches would make the filter look broken
   const isOpen = (group: string) => filterActive || !collapsed[group]
diff --git a/ui/src/lib/FolderGroups.test.ts b/ui/src/lib/FolderGroups.test.ts
new file mode 100644
index 00000000..c5d6e32a
--- /dev/null
+++ b/ui/src/lib/FolderGroups.test.ts
@@ -0,0 +1,45 @@
+import { render } from '@testing-library/svelte'
+import { createRawSnippet } from 'svelte'
+import { describe, expect, it } from 'vitest'
+import FolderGroups from './FolderGroups.svelte'
+
+const card = createRawSnippet((name: () => string) => ({
+  render: () => `<span>${name()}</span>`,
+}))
+
+describe('FolderGroups', () => {
+  it('groups by the default groupOf when none is supplied', () => {
+    const { container } = render(FolderGroups, {
+      names: ['a/one', 'a/two', 'b/three'],
+      collapseKey: 'test-default-groupof',
+      filterActive: false,
+      card,
+    })
+    const headings = [...container.querySelectorAll('.group')].map(
+      (el) => el.textContent,
+    )
+    expect(headings.length).toBe(2)
+    expect(headings.some((h) => h?.includes('a/'))).toBe(true)
+    expect(headings.some((h) => h?.includes('b/'))).toBe(true)
+  })
+
+  it('groups by a caller-supplied groupOf instead, since a gallery name carries a run id the name alone cannot strip', () => {
+    // The default groupOf would put each of these under its own heading -
+    // the last path segment is a run id, not a folder. The gallery instead
+    // passes the server's `folder` lookup.
+    const { container } = render(FolderGroups, {
+      names: [
+        'tti/20260906-101500-a1b2c3d4/a.png',
+        'tti/20260906-101612-ffffffff/b.png',
+      ],
+      collapseKey: 'test-custom-groupof',
+      filterActive: false,
+      groupOf: (name: string) => name.split('/')[0],
+      card,
+    })
+    const headings = [...container.querySelectorAll('.group')]
+    expect(headings.length).toBe(1)
+    expect(headings[0].textContent).toContain('tti/')
+    expect(headings[0].textContent).toContain('(2)')
+  })
+})
diff --git a/ui/src/lib/grouping.test.ts b/ui/src/lib/grouping.test.ts
index 6abd1af2..ddaf1eef 100644
--- a/ui/src/lib/grouping.test.ts
+++ b/ui/src/lib/grouping.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { groupOf, leafOf } from './grouping'
+import { groupNames, groupOf, leafOf } from './grouping'
 
 describe('groupOf', () => {
   it('has no group for a name at the root', () => {
@@ -18,11 +18,11 @@ describe('groupOf', () => {
     )
   })
 
-  it('groups a gallery entry by the workflow that wrote it', () => {
-    // A gallery name is <workflow identity>/<file>, and the identity is itself
-    // a path now
-    expect(groupOf('templates/ltx2/two-stage/still.png')).toBe(
-      'templates/ltx2/two-stage',
+  it('is not how the gallery groups - a gallery name carries a run id', () => {
+    // <identity>/<run id>/<file>: the last folder is the run, not the workflow.
+    // GalleryPage groups by the server's `folder` (strip_run_id) instead
+    expect(groupOf('templates/ltx2/two-stage/20260906-101500-a1b2c3d4/still.png')).toBe(
+      'templates/ltx2/two-stage/20260906-101500-a1b2c3d4',
     )
   })
 })
@@ -36,3 +36,23 @@ describe('leafOf', () => {
     expect(leafOf('templates/minimax/dialogue-short')).toBe('dialogue-short')
   })
 })
+
+describe('groupNames', () => {
+  it('buckets names by their group in one pass, groups sorted', () => {
+    const grouped = groupNames(['b/two', 'a/one', 'root', 'a/three'])
+    expect([...grouped.keys()]).toEqual(['', 'a', 'b'])
+    expect(grouped.get('a')).toEqual(['a/one', 'a/three'])
+    expect(grouped.get('')).toEqual(['root'])
+  })
+
+  it('takes a caller-supplied grouper', () => {
+    // The gallery groups by the folder the server computed, which strips the
+    // run id - the name alone cannot tell a run id from a folder
+    const folderOf = (name: string) => name.split('/')[0]
+    const grouped = groupNames(
+      ['tti/20260906-101500-a1b2c3d4/a.png', 'tti/20260906-101612-ffffffff/b.png'],
+      folderOf,
+    )
+    expect([...grouped.keys()]).toEqual(['tti'])
+  })
+})
diff --git a/ui/src/lib/grouping.ts b/ui/src/lib/grouping.ts
index 4fe4722b..dad3117c 100644
--- a/ui/src/lib/grouping.ts
+++ b/ui/src/lib/grouping.ts
@@ -13,3 +13,25 @@ export const groupOf = (name: string) =>
 /** The card label: the leaf, since the group heading already shows the rest. */
 export const leafOf = (name: string) =>
   name.includes('/') ? name.slice(name.lastIndexOf('/') + 1) : name
+
+/**
+ * Names bucketed by group, one pass, groups in sorted order. A page hands in
+ * its own grouper when the name alone cannot say which folder an entry belongs
+ * to - the gallery's names carry a run id the server has already stripped into
+ * `folder`.
+ */
+export const groupNames = (
+  names: string[],
+  grouper: (name: string) => string = groupOf,
+): Map<string, string[]> => {
+  const buckets = new Map<string, string[]>()
+  for (const name of names) {
+    const group = grouper(name)
+    const bucket = buckets.get(group)
+    if (bucket) bucket.push(name)
+    else buckets.set(group, [name])
+  }
+  return new Map(
+    [...buckets.entries()].sort(([a], [b]) => a.localeCompare(b)),
+  )
+}
diff --git a/ui/src/lib/pages/GalleryPage.svelte b/ui/src/lib/pages/GalleryPage.svelte
index 47651967..833eda39 100644
--- a/ui/src/lib/pages/GalleryPage.svelte
+++ b/ui/src/lib/pages/GalleryPage.svelte
@@ -84,6 +84,9 @@
     files.filter((f) => f.name.toLowerCase().includes(filter.toLowerCase())),
   )
   const byName = $derived(new Map(visible.map((f) => [f.name, f])))
+  // The server folds each run id into `folder`; group by that, since the
+  // name alone reads the run directory as one more folder
+  const folderByName = $derived(new Map(visible.map((f) => [f.name, f.folder])))
 
   const pickedCount = $derived(picked.size)
   /** The selection in the order the grid shows them, which is the order
@@ -295,6 +298,7 @@
 
 <FolderGroups
   names={visible.map((f) => f.name)}
+  groupOf={(name) => folderByName.get(name) ?? ''}
   collapseKey="collapsed-gallery-folders"
   filterActive={filter !== ''}
   minColumn="150px"

From 32b058f089922f3ab47161b82f764fcc4fe68e6f Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 18:06:43 -0500
Subject: [PATCH 24/32] Prefer the checkout's docs over a stale packaged copy;
 build without httpx

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 dw_mcp/guides.py         | 17 +++++++++--------
 scripts/build_dist.sh    | 15 ++++-----------
 tests/test_mcp_guides.py | 21 +++++++++++++++------
 3 files changed, 28 insertions(+), 25 deletions(-)

diff --git a/dw_mcp/guides.py b/dw_mcp/guides.py
index d8ebe5e9..7ef60c31 100644
--- a/dw_mcp/guides.py
+++ b/dw_mcp/guides.py
@@ -82,16 +82,17 @@
 
 
 def _guide_file(file_name):
-    """Where a guide's markdown actually is.
+    """Where a guide lives: the repo's docs/ in a checkout, else the copy
+    build_dist.sh puts under dw/docs/ for an install.
 
-    Packaged into dw/docs/ at build time, the way the SPA is copied into
-    dw/server/ui - so an install carries them. A checkout has no such copy
-    until something builds one, and reads the repo's own docs/ instead.
+    The checkout wins because the build leaves dw/docs/ behind; if that copy
+    took precedence, editing docs/ would change nothing an agent reads.
     """
-    packaged = Path(__file__).resolve().parent.parent / "dw" / "docs" / file_name
-    if packaged.is_file():
-        return packaged
-    return Path(__file__).resolve().parent.parent / "docs" / file_name
+    root = Path(__file__).resolve().parent.parent
+    checkout = root / "docs" / file_name
+    if checkout.is_file():
+        return checkout
+    return root / "dw" / "docs" / file_name
 
 
 def read_guide(name):
diff --git a/scripts/build_dist.sh b/scripts/build_dist.sh
index cebe5e7a..43352626 100755
--- a/scripts/build_dist.sh
+++ b/scripts/build_dist.sh
@@ -13,19 +13,12 @@ cp -r ui/dist dw/server/ui
 
 # The guides dw_mcp serves. A checkout reads the repo's docs/ directly, so this
 # copy only matters to an install - but without it an installed dw-mcp has no
-# guides at all
+# guides at all. Every doc goes in: read_guide only ever opens the names in
+# dw_mcp.guides.GUIDES, so the extras are inert, and this needs no import of
+# dw_mcp (whose client pulls in httpx, which the wheel job does not install)
 rm -rf dw/docs
 mkdir -p dw/docs
-python - <<'GUIDES'
-import shutil
-from pathlib import Path
-
-from dw_mcp.guides import GUIDES
-
-for file_name in sorted({f for f, _ in GUIDES.values()}):
-    shutil.copy(Path("docs") / file_name, Path("dw/docs") / file_name)
-    print(f"docs/{file_name} -> dw/docs/{file_name}")
-GUIDES
+cp docs/*.md dw/docs/
 
 python -m pip show build >/dev/null 2>&1 || python -m pip install build
 python -m build
diff --git a/tests/test_mcp_guides.py b/tests/test_mcp_guides.py
index 26fdb880..73542dae 100644
--- a/tests/test_mcp_guides.py
+++ b/tests/test_mcp_guides.py
@@ -40,20 +40,29 @@ def test_every_curated_guide_file_exists(self):
 
 
 class TestWhereTheyComeFrom:
-    def test_the_packaged_copy_is_preferred_over_the_repo(self, tmp_path, monkeypatch):
-        """An install has no docs/ beside the package - only the dw/docs/ copy
-        the build makes. A checkout has no copy and reads docs/ directly, so the
-        preference is what makes the same code work in both."""
-        root = tmp_path / "site-packages"
+    def test_a_checkout_is_preferred_over_a_stale_packaged_copy(self, tmp_path, monkeypatch):
+        """build_dist.sh leaves dw/docs/ behind (gitignored). If that copy won,
+        every later edit to docs/ would be invisible to the MCP and to these
+        tests - so the repo's docs/ wins whenever it is there, and the packaged
+        copy is only for an install, which has no docs/ beside the package."""
+        root = tmp_path / "checkout"
         (root / "dw" / "docs").mkdir(parents=True)
         (root / "docs").mkdir()
         (root / "dw" / "docs" / "TASKS.md").write_text("## Packaged\n")
         (root / "docs" / "TASKS.md").write_text("## Checkout\n")
         monkeypatch.setattr(guides, "__file__", str(root / "dw_mcp" / "guides.py"))
 
+        assert guides.read_guide("tasks") == "## Checkout\n"
+
+    def test_an_install_reads_the_packaged_copy(self, tmp_path, monkeypatch):
+        root = tmp_path / "site-packages"
+        (root / "dw" / "docs").mkdir(parents=True)
+        (root / "dw" / "docs" / "TASKS.md").write_text("## Packaged\n")
+        monkeypatch.setattr(guides, "__file__", str(root / "dw_mcp" / "guides.py"))
+
         assert guides.read_guide("tasks") == "## Packaged\n"
 
-    def test_a_checkout_falls_back_to_the_repo_docs(self, tmp_path, monkeypatch):
+    def test_a_checkout_with_no_packaged_copy_reads_the_repo_docs(self, tmp_path, monkeypatch):
         root = tmp_path / "repo"
         (root / "docs").mkdir(parents=True)
         (root / "docs" / "TASKS.md").write_text("## Checkout\n")

From 0443ec8e383468271d053d37d46f719672751d1c Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 18:15:51 -0500
Subject: [PATCH 25/32] Carry the sample rate on every .audios item as an
 AudioTrack

Audio-only pipelines now record their vocoder or VAE rate the way LTX-2
already did, and get_artifact_list wraps each item so a workflow need not
declare one. Follow-up: a modular pipeline's dict output (music.json) still
carries no rate of its own.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 dw/pipeline_processors/pipeline.py     | 41 ++++++++++++++-----
 dw/result.py                           | 22 ++++++++++-
 tests/test_pipeline_components.py      | 55 ++++++++++++++++++++++++++
 tests/test_result.py                   | 44 +++++++++++++++++++++
 workflows/templates/minimax/music.json |  2 +-
 5 files changed, 152 insertions(+), 12 deletions(-)

diff --git a/dw/pipeline_processors/pipeline.py b/dw/pipeline_processors/pipeline.py
index b90fe851..e00f89e8 100644
--- a/dw/pipeline_processors/pipeline.py
+++ b/dw/pipeline_processors/pipeline.py
@@ -1091,26 +1091,49 @@ def warn_if_safety_checker_blanked(output):
         )
 
 
+# Where an audio pipeline's components record the rate they generate at, in
+# the order they are tried. LTX-2's vocoder names it output_sampling_rate,
+# AudioLDM2's vocoder and StableAudio's VAE name it sampling_rate
+_SAMPLE_RATE_SOURCES = (
+    ("vocoder", "output_sampling_rate"),
+    ("vocoder", "sampling_rate"),
+    ("vae", "sampling_rate"),
+)
+
+
+def _component_sample_rate(pipeline):
+    for component_name, attribute in _SAMPLE_RATE_SOURCES:
+        config = getattr(getattr(pipeline, component_name, None), "config", None)
+        sample_rate = getattr(config, attribute, None)
+        if sample_rate is not None:
+            return sample_rate
+    return None
+
+
 def attach_audio_sample_rate(pipeline, output):
-    """Record the vocoder's sample rate on an output that carries generated audio.
+    """Record the generating component's sample rate on an output that carries audio.
 
-    Pipelines that generate audio with their video (LTX-2) return the waveform without
-    its sample rate - only the vocoder that produced it knows that. Saving the video
-    needs the rate to mux the audio, so it travels with the output.
+    Pipelines that generate audio - with their video (LTX-2, on `.audio`) or by
+    itself (AudioLDM2, StableAudio, on `.audios`) - return the waveform without
+    its sample rate; only the vocoder or VAE that produced it knows that. Saving
+    needs the rate, so it travels with the output, and get_artifact_list wraps
+    `.audios` items in an AudioTrack that carries it.
 
     Args:
         pipeline: The pipeline that produced the output
         output: The pipeline output
     """
-    if getattr(output, "audio", None) is None:
+    has_audio = getattr(output, "audio", None) is not None
+    has_audios = getattr(output, "audios", None) is not None
+    if not (has_audio or has_audios):
         return
 
-    vocoder_config = getattr(getattr(pipeline, "vocoder", None), "config", None)
-    sample_rate = getattr(vocoder_config, "output_sampling_rate", None)
+    sample_rate = _component_sample_rate(pipeline)
     if sample_rate is None:
         logger.warning(
-            "Pipeline generated audio but has no vocoder sample rate - "
-            "set 'audio_sample_rate' in the step result to save it with the video"
+            "Pipeline generated audio but no component reports its sample rate - "
+            "set 'sample_rate' (audio results) or 'audio_sample_rate' (muxed video) "
+            "in the step result to save it correctly"
         )
         return
 
diff --git a/dw/result.py b/dw/result.py
index 39f8fe73..98089bf3 100644
--- a/dw/result.py
+++ b/dw/result.py
@@ -421,7 +421,12 @@ def save_artifact(
                         saved_files.extend(
                             self.save_artifact(
                                 output_dir,
-                                waveform,
+                                # Keep the rate the track carries across the
+                                # recursion - a bare waveform would fall back
+                                # to the default
+                                AudioTrack(waveform.T, sample_rate)
+                                if isinstance(artifact, AudioTrack)
+                                else waveform,
                                 f"{file_base_name}-{k}",
                                 content_type,
                                 extension,
@@ -645,7 +650,20 @@ def _frames_from_attributes(result):
 
 
 def _audios_from_attribute(result):
-    return [as_waveform_array(audio) for audio in result.audios]
+    """Each `.audios` item as an artifact.
+
+    With the rate attach_audio_sample_rate recorded, each item becomes an
+    AudioTrack carrying it, shaped (channels, samples); without one, the bare
+    (samples, channels) array it always was, and the workflow's 'sample_rate'
+    (or the default) applies at save.
+    """
+    sample_rate = getattr(result, "audio_sample_rate", None)
+    if sample_rate is None:
+        return [as_waveform_array(audio) for audio in result.audios]
+    return [
+        AudioTrack(as_waveform_array(audio).T, int(sample_rate))
+        for audio in result.audios
+    ]
 
 
 # Diffusers output fields get_artifact_list knows how to turn into artifacts, tried in
diff --git a/tests/test_pipeline_components.py b/tests/test_pipeline_components.py
index 0d507fc1..39f29904 100644
--- a/tests/test_pipeline_components.py
+++ b/tests/test_pipeline_components.py
@@ -481,3 +481,58 @@ def test_silent_for_a_pipeline_without_a_safety_checker(self, caplog):
             warn_if_safety_checker_blanked(output)
 
         assert caplog.text == ""
+
+
+class TestAudiosSampleRate:
+    """Audio-only pipelines put the waveform on `.audios` and the rate on a
+    component config - AudioLDM2's vocoder, StableAudio's VAE. The workflow
+    should not have to know which."""
+
+    def _pipeline(self, **components):
+        from types import SimpleNamespace
+
+        return SimpleNamespace(**components)
+
+    def _output(self):
+        from types import SimpleNamespace
+
+        import numpy
+
+        return SimpleNamespace(audios=numpy.zeros((1, 2, 100), dtype="float32"))
+
+    def test_a_vocoder_rate_is_recorded_for_audios(self):
+        from types import SimpleNamespace
+
+        from dw.pipeline_processors.pipeline import attach_audio_sample_rate
+
+        pipeline = self._pipeline(
+            vocoder=SimpleNamespace(config=SimpleNamespace(sampling_rate=16000))
+        )
+        output = self._output()
+
+        attach_audio_sample_rate(pipeline, output)
+
+        assert output.audio_sample_rate == 16000
+
+    def test_a_vae_rate_is_recorded_for_audios(self):
+        from types import SimpleNamespace
+
+        from dw.pipeline_processors.pipeline import attach_audio_sample_rate
+
+        pipeline = self._pipeline(
+            vae=SimpleNamespace(config=SimpleNamespace(sampling_rate=44100))
+        )
+        output = self._output()
+
+        attach_audio_sample_rate(pipeline, output)
+
+        assert output.audio_sample_rate == 44100
+
+    def test_no_rate_anywhere_records_nothing(self):
+        from dw.pipeline_processors.pipeline import attach_audio_sample_rate
+
+        output = self._output()
+
+        attach_audio_sample_rate(self._pipeline(), output)
+
+        assert not hasattr(output, "audio_sample_rate")
diff --git a/tests/test_result.py b/tests/test_result.py
index 68f46cff..52c01356 100644
--- a/tests/test_result.py
+++ b/tests/test_result.py
@@ -284,6 +284,33 @@ class MockResult:
         assert artifacts[0].shape == (100, 2)
         assert artifacts[0].dtype == numpy.float32
 
+    def test_audios_with_a_recorded_rate_become_audio_tracks(self):
+        # attach_audio_sample_rate put the rate on the output; each item
+        # carries it from here on, so a workflow declares nothing
+        from dw.result import AudioTrack
+
+        class MockResult:
+            audios = numpy.zeros((2, 2, 100), dtype=numpy.float32)
+            audio_sample_rate = 16000
+
+        artifacts = get_artifact_list(MockResult())
+
+        assert len(artifacts) == 2
+        assert all(isinstance(a, AudioTrack) for a in artifacts)
+        assert artifacts[0].sample_rate == 16000
+        # channels-first, the layout AudioTrack documents
+        assert artifacts[0].audio.shape == (2, 100)
+
+    def test_audios_without_a_rate_stay_bare_waveforms(self):
+        # Nothing to carry: the shape every existing consumer already handles
+        class MockResult:
+            audios = numpy.zeros((1, 2, 100), dtype=numpy.float32)
+
+        artifacts = get_artifact_list(MockResult())
+
+        assert isinstance(artifacts[0], numpy.ndarray)
+        assert artifacts[0].shape == (100, 2)
+
     def test_images_take_precedence_over_frames(self):
         # The output-field registry is consulted in order - a result exposing both
         # (which nothing real does, but the registry order must still be deterministic)
@@ -668,6 +695,23 @@ def test_a_declared_rate_wins_over_the_one_the_track_carries(self):
             _, sample_rate = soundfile.read(os.path.join(temp_dir, "line-0.0.wav"))
             assert sample_rate == 44100
 
+    def test_a_batch_of_tracks_each_save_at_the_carried_rate(self):
+        # Each item of a batched .audios is its own AudioTrack, so each is saved
+        # as its own artifact at the rate it carries
+        with tempfile.TemporaryDirectory() as temp_dir:
+            result = Result({"content_type": "audio/wav"})
+
+            class MockResult:
+                audios = numpy.zeros((2, 1, 4410), dtype=numpy.float32)
+                audio_sample_rate = 22050
+
+            result.add_result(MockResult())
+            result.save(temp_dir, "song")
+
+            for j in (0, 1):
+                _, rate = soundfile.read(os.path.join(temp_dir, f"song-0.{j}.wav"))
+                assert rate == 22050
+
     def test_numpy_audios_output_saves_without_attribute_error(self):
         # Regression test: AudioPipelineOutput.audios is a numpy ndarray under the
         # default output_type='np', which has no .float()/.cpu() - saving used to raise
diff --git a/workflows/templates/minimax/music.json b/workflows/templates/minimax/music.json
index da5c1af9..ad8b435c 100644
--- a/workflows/templates/minimax/music.json
+++ b/workflows/templates/minimax/music.json
@@ -1,6 +1,6 @@
 {
     "id": "MiniMaxMusic",
-    "description": "Audio-only generation, showing that a pipeline's output need not be visual - the step declares an 'audios' output and an audio result type, and the engine encodes it at the given sample rate. Also the minimal way to run a modular pipeline: rather than placing components by hand, a 'components_manager' with auto CPU offload takes ownership of device placement and keeps only the running components resident, so no quantization or per-component offload configuration is needed. 'audio_duration' is a ceiling, not a target: the model stops where the music stops, so ask for more time than the song needs - a value trimmed to the intended length cuts the outro off mid-decay - and finish the tail with 'tasks/TrimFadeAudio.json'.",
+    "description": "Audio-only generation, showing that a pipeline's output need not be visual - the step declares an 'audios' output and an audio result type, and the engine encodes it at the given sample rate. Also the minimal way to run a modular pipeline: rather than placing components by hand, a 'components_manager' with auto CPU offload takes ownership of device placement and keeps only the running components resident, so no quantization or per-component offload configuration is needed. 'audio_duration' is a ceiling, not a target: the model stops where the music stops, so ask for more time than the song needs - a value trimmed to the intended length cuts the outro off mid-decay - and finish the tail with 'tasks/TrimFadeAudio.json'. The result declares 'sample_rate' because a modular pipeline's dict output carries none of its own.",
     "variables": {
         "prompt": "prompt:minimax/acoustic_pop_song",
         "lyrics": "[verse]\nMining farms burning through the grid all day\nChia swapped the furnace for the plots you lay\nNo more e-waste piling up when the rigs retire\nGreen space farming puts out yesterday's fire\n[chorus]\nChia fixes this\nChia fixes this\nEnergy waste, ASIC greed, centralized control\nChia fixes this\n[verse]\nOffer files trade without a middleman in sight\nChialisp writes the rules and locks the CAT in tight\nMarmots watch the validators keep it fair and slow\nNo more trusting strangers with the coins you owe\n[chorus]\nChia fixes this\nChia fixes this\nEnergy waste, ASIC greed, centralized control\nChia fixes this",

From 14db806d2bffb1edc4be0d77687ad6154c4cda55 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 18:21:21 -0500
Subject: [PATCH 26/32] Name the mismatch when audio meets a video reference or
 a silent video is saved as audio

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 dw/arguments.py         | 33 +++++++++++++++++++++++----------
 dw/result.py            |  7 ++++++-
 tests/test_arguments.py | 19 +++++++++++++++++++
 tests/test_result.py    |  6 ++++++
 4 files changed, 54 insertions(+), 11 deletions(-)

diff --git a/dw/arguments.py b/dw/arguments.py
index 242576b8..92739c1f 100644
--- a/dw/arguments.py
+++ b/dw/arguments.py
@@ -697,6 +697,15 @@ def object_from_result(description):
     return object_type(**arguments)
 
 
+def _carried_audio(artifact, torch, as_channels_samples):
+    """The (waveform tensor, rate) an artifact carries as '.audio'/'.sample_rate'
+    - an AudioVideo or an AudioTrack - or (None, None) for anything else."""
+    if getattr(artifact, "audio", None) is None:
+        return None, None
+    audio = torch.as_tensor(as_channels_samples(artifact.audio))
+    return audio, getattr(artifact, "sample_rate", None)
+
+
 def media_arguments(object_type, artifact):
     """The constructor arguments a step's artifact makes, for a type's media kind.
 
@@ -731,17 +740,19 @@ def media_arguments(object_type, artifact):
             )
         return {"image": artifact}
 
-    # A generated soundtrack arrives paired with the frames it was generated with
-    # (an AudioVideo) or by itself with the rate it was generated at (an
-    # AudioTrack); anything else the step produced carries none. Read off the
-    # attributes rather than the types, which is how every other audio consumer
-    # here accepts both
-    audio, sample_rate = None, None
-    if getattr(artifact, "audio", None) is not None:
-        audio = torch.as_tensor(as_channels_samples(artifact.audio))
-        sample_rate = getattr(artifact, "sample_rate", None)
-
     if kind == "video":
+        # Frames first: an audio-only artifact has none, and that is the thing
+        # to say rather than whatever the frame helper raises about it
+        if (
+            not hasattr(artifact, "frames")
+            and not isinstance(artifact, (list, tuple))
+            and not hasattr(artifact, "ndim")
+        ):
+            raise ValueError(
+                f"{object_type.__name__} holds a video, but the step it names "
+                f"produced a {type(artifact).__name__} - reference a step that "
+                f"generates video"
+            )
         frames = frames_as_pil_list(artifact)
         if not frames:
             raise ValueError(
@@ -749,11 +760,13 @@ def media_arguments(object_type, artifact):
                 f"produced no frames"
             )
         arguments = {"frames": frames}
+        audio, sample_rate = _carried_audio(artifact, torch, as_channels_samples)
         if audio is not None:
             arguments["audio"] = audio
             arguments["sample_rate"] = sample_rate
         return arguments
 
+    audio, sample_rate = _carried_audio(artifact, torch, as_channels_samples)
     if audio is None and hasattr(artifact, "ndim") and artifact.ndim <= 3:
         # A step that generates audio alone - a music pipeline, a slice_audio
         # task - produces the waveform itself rather than an AudioVideo. It
diff --git a/dw/result.py b/dw/result.py
index 98089bf3..00482c32 100644
--- a/dw/result.py
+++ b/dw/result.py
@@ -912,7 +912,12 @@ def normalize_audio(artifact):
     Returns:
         List of numpy arrays shaped (samples,) or (samples, channels)
     """
-    artifact = getattr(artifact, "audio", artifact)
+    if hasattr(artifact, "audio"):
+        if artifact.audio is None:
+            raise ValueError(
+                f"Cannot save a {type(artifact).__name__} as audio - it carries no audio track"
+            )
+        artifact = artifact.audio
 
     # Torch tensors may be on the GPU and in a dtype numpy does not understand
     if hasattr(artifact, "detach"):
diff --git a/tests/test_arguments.py b/tests/test_arguments.py
index 6e5ea1f6..b58a56c2 100644
--- a/tests/test_arguments.py
+++ b/tests/test_arguments.py
@@ -779,6 +779,25 @@ def test_a_named_field_wins_over_the_one_the_media_carried(self):
 
         assert build_objects(arguments)["reference"].fps == 30.0
 
+    def test_a_video_reference_to_a_speech_step_says_so(self):
+        # Pointing a video-kind reference at generate_speech's output should
+        # name the mismatch, not fail inside the frame helper
+        import numpy
+
+        from dw.result import AudioTrack
+
+        arguments = {
+            "reference": {
+                "reference_type": VideoReference,
+                "from_previous_result": AudioTrack(
+                    numpy.zeros((1, 50), dtype="float32"), 24000
+                ),
+            }
+        }
+
+        with pytest.raises(ValueError, match="holds a video, but the step it names produced"):
+            build_objects(arguments)
+
     def test_the_wrong_media_for_the_kind_is_an_error(self):
         arguments = {
             "reference": {
diff --git a/tests/test_result.py b/tests/test_result.py
index 52c01356..fc40978e 100644
--- a/tests/test_result.py
+++ b/tests/test_result.py
@@ -665,6 +665,12 @@ def test_default_sample_rate(self):
             _, sample_rate = soundfile.read(os.path.join(temp_dir, "song-0.0.wav"))
             assert sample_rate == 44100
 
+    def test_saving_a_silent_video_as_audio_names_the_problem(self):
+        from dw.result import AudioVideo, normalize_audio
+
+        with pytest.raises(ValueError, match="carries no audio"):
+            normalize_audio(AudioVideo([], None, None))
+
     def test_a_track_saves_at_the_rate_it_carries(self):
         # A generated track knows its own rate - generate_speech produces one at
         # whatever its model runs at - so the workflow does not have to declare it

From cc8fe36371f9d52fdba38afd6ef0e6faa02ab90e Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 18:25:24 -0500
Subject: [PATCH 27/32] Share the HF pipeline placement and refuse a preset a
 one-voice model drops

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 dw/tasks/model_cache.py         | 16 ++++++++++++++++
 dw/tasks/speech_generation.py   | 30 ++++++++++++++++--------------
 dw/tasks/task.py                |  2 ++
 dw/tasks/text_generation.py     | 18 +++---------------
 tests/test_hf_placement.py      | 14 ++++++++++++++
 tests/test_speech_generation.py | 29 +++++++++++++++++++++++++++++
 6 files changed, 80 insertions(+), 29 deletions(-)
 create mode 100644 tests/test_hf_placement.py

diff --git a/dw/tasks/model_cache.py b/dw/tasks/model_cache.py
index bbf0e468..35c7b92c 100644
--- a/dw/tasks/model_cache.py
+++ b/dw/tasks/model_cache.py
@@ -37,3 +37,19 @@ def clear_model_cache():
     if _cache:
         logger.info(f"Clearing {len(_cache)} cached task models")
     _cache.clear()
+
+
+def hf_pipeline_placement(device):
+    """How a transformers pipeline is told where to load.
+
+    A device_map has the loading threads cast their shards straight onto the
+    device, which races inside torch's Metal shader cache on MPS. Passing
+    `device` instead leaves the load on the CPU and moves the finished model in
+    one call on this thread. Every task that builds a transformers pipeline
+    spells `**hf_pipeline_placement(device)` so the accommodation lives once.
+    """
+    from .. import get_device_type
+
+    if get_device_type(device) == "mps":
+        return {"device": device}
+    return {"device_map": device}
diff --git a/dw/tasks/speech_generation.py b/dw/tasks/speech_generation.py
index d559a9ee..48d0a2a8 100644
--- a/dw/tasks/speech_generation.py
+++ b/dw/tasks/speech_generation.py
@@ -3,7 +3,8 @@
 
 Takes a line of text and speaks it with a local text-to-speech model, returning
 the waveform and the rate it was generated at so the rest of the audio plumbing -
-slice_audio, fade_audio, pair_audio, concat_videos - composes with it directly.
+slice_audio, fade_audio and pair_audio - composes with it directly (concat_videos
+and dissolve_videos join videos; pair the track onto a video first).
 
 The role this is built for is voice *timbre reference*, not the track a mouth
 follows. MiniMax H3 lip-syncs well when it generates the speech itself and poorly
@@ -19,17 +20,18 @@
 
 from transformers import pipeline as hf_pipeline
 
-from .. import get_device_type, preferred_task_dtype
+from .. import preferred_task_dtype
 from ..result import AudioTrack
 from .audio_utils import as_channels_samples
-from .model_cache import cached_model
+from .model_cache import cached_model, hf_pipeline_placement
 
 logger = logging.getLogger("dw")
 
 # Small, loads without a separate speaker-embedding dataset, and its voice presets
 # give distinct speakers - which is the point when two characters have to sound
-# like two people. A single-voice model like facebook/mms-tts-eng is a quarter the
-# size and a reasonable override where only one voice is needed
+# like two people. A single-voice model like facebook/mms-tts-eng (which takes no
+# voice_preset) is a quarter the size and a reasonable override where only one
+# voice is needed
 _DEFAULT_MODEL = "suno/bark-small"
 
 
@@ -63,15 +65,7 @@ def generate_speech(text, device="cpu", **kwargs):
 
     def load_pipe():
         logger.info(f"Generating speech with {model_name} on {device}")
-        # The same MPS accommodation text_generation makes: a device_map has the
-        # loading threads cast their shards straight onto the device, which races
-        # inside torch's Metal shader cache. Passing `device` leaves the load on
-        # the CPU and moves the finished model in one call on this thread
-        placement = (
-            {"device": device}
-            if get_device_type(device) == "mps"
-            else {"device_map": device}
-        )
+        placement = hf_pipeline_placement(device)
         return hf_pipeline(
             "text-to-speech",
             model=model_name,
@@ -84,6 +78,14 @@ def load_pipe():
         load_pipe,
     )
 
+    if voice_preset and getattr(pipe, "processor", None) is None:
+        # A single-voice model has no processor to hand the preset to;
+        # transformers logs the kwarg as unrecognised and speaks anyway
+        raise ValueError(
+            f"{model_name} takes no 'voice_preset' - it has one voice. Drop the "
+            "preset, or use a model with speaker presets such as suno/bark-small"
+        )
+
     logger.info(f"Speaking: {text[:100]}{'...' if len(text) > 100 else ''}")
     output = pipe(
         text,
diff --git a/dw/tasks/task.py b/dw/tasks/task.py
index e84f079b..6467c4e1 100644
--- a/dw/tasks/task.py
+++ b/dw/tasks/task.py
@@ -360,6 +360,8 @@ def _handle_text_generation(task, arguments, previous_pipelines):
 def _handle_speech_generation(task, arguments, previous_pipelines):
     """Speak a line of text with a local text-to-speech model"""
     logger.debug("Generating speech")
+    if "text" not in arguments:
+        raise ValueError("generate_speech needs 'text' - the line to speak")
     text = arguments.pop("text")
     from .speech_generation import generate_speech
 
diff --git a/dw/tasks/text_generation.py b/dw/tasks/text_generation.py
index 48a91730..943cf9a0 100644
--- a/dw/tasks/text_generation.py
+++ b/dw/tasks/text_generation.py
@@ -13,8 +13,8 @@
 
 import logging
 from transformers import pipeline as hf_pipeline
-from .. import get_device_type, preferred_task_dtype
-from .model_cache import cached_model
+from .. import preferred_task_dtype
+from .model_cache import cached_model, hf_pipeline_placement
 
 logger = logging.getLogger("dw")
 
@@ -109,19 +109,7 @@ def generate_text(prompt, device="cpu", **kwargs):
 
     def load_pipe():
         logger.info(f"Generating text with {model_name} on {device}")
-        # transformers materializes the weights across a thread pool, and a
-        # device_map makes each of those threads cast its shard straight onto
-        # the device. On MPS that races inside torch's Metal shader cache and
-        # takes the process down mid-load - the same load crashed in
-        # MetalShaderLibrary::exec_unary_kernel twice, once on a garbage
-        # pointer and once on NULL. Passing `device` instead leaves the load on
-        # the CPU and lets the pipeline move the finished model in one call on
-        # this thread
-        placement = (
-            {"device": device}
-            if get_device_type(device) == "mps"
-            else {"device_map": device}
-        )
+        placement = hf_pipeline_placement(device)
         return hf_pipeline(
             pipeline_task,
             model=model_name,
diff --git a/tests/test_hf_placement.py b/tests/test_hf_placement.py
new file mode 100644
index 00000000..fa6ca712
--- /dev/null
+++ b/tests/test_hf_placement.py
@@ -0,0 +1,14 @@
+"""One place decides how a transformers pipeline is placed on a device."""
+
+from dw.tasks.model_cache import hf_pipeline_placement
+
+
+def test_mps_loads_on_the_cpu_and_moves_afterwards():
+    # A device_map has the loading threads cast shards straight onto the
+    # device, which races inside torch's Metal shader cache
+    assert hf_pipeline_placement("mps") == {"device": "mps"}
+
+
+def test_other_backends_use_a_device_map():
+    assert hf_pipeline_placement("cuda:1") == {"device_map": "cuda:1"}
+    assert hf_pipeline_placement("cpu") == {"device_map": "cpu"}
diff --git a/tests/test_speech_generation.py b/tests/test_speech_generation.py
index 6b1177bd..6cafb966 100644
--- a/tests/test_speech_generation.py
+++ b/tests/test_speech_generation.py
@@ -130,3 +130,32 @@ def test_a_model_reporting_no_rate_is_an_error(self, mock_pipeline):
 
         with self.assertRaisesRegex(ValueError, "sample rate"):
             generate_speech("hello", device="cpu")
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_a_preset_the_model_cannot_take_is_an_error(self, mock_pipeline):
+        # facebook/mms-tts-eng has no processor: transformers would log the
+        # preset as an unrecognised kwarg and speak in its one voice
+        mock_pipeline.return_value.processor = None
+
+        with self.assertRaises(ValueError) as raised:
+            generate_speech("hi", model_name="facebook/mms-tts-eng", voice_preset="v2/en_speaker_6")
+
+        self.assertIn("voice_preset", str(raised.exception))
+        self.assertIn("facebook/mms-tts-eng", str(raised.exception))
+
+
+class TestHandleSpeechGeneration(unittest.TestCase):
+    """Covers the task.py dispatch handler directly, since
+    test_task_discovery.py only introspects the command registry rather than
+    running handlers."""
+
+    def test_generate_speech_without_text_names_the_argument(self):
+        from dw.tasks.task import _COMMAND_REGISTRY
+
+        class FakeTask:
+            def device_for(self, arguments):
+                return "cpu"
+
+        handler = _COMMAND_REGISTRY["generate_speech"]
+        with self.assertRaisesRegex(ValueError, "generate_speech needs 'text'"):
+            handler(FakeTask(), {"voice_preset": "v2/en_speaker_6"}, {})

From ef2757f728a42d04503dbee4fe3206c15f8b96cd Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 18:30:49 -0500
Subject: [PATCH 28/32] Resolve configures against the listing and document it

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/SERVER.md       |  9 ++++++---
 dw/server/app.py     | 14 ++++++++++++++
 tests/test_server.py | 24 ++++++++++++++++++++++++
 3 files changed, 44 insertions(+), 3 deletions(-)

diff --git a/docs/SERVER.md b/docs/SERVER.md
index 32c34732..dc446af0 100644
--- a/docs/SERVER.md
+++ b/docs/SERVER.md
@@ -191,9 +191,12 @@ The editor's forms come from these; they are just as usable from scripts:
 - `GET /api/workflows` — the stored workflow names, plus a `details` entry
   per workflow: `description`, `kinds` (the output content types' top-level
   halves), `steps`, `variables` (a count) and `variable_names`, and
-  `prompt_refs` naming the stored prompts it leans on. Enough to choose a
-  workflow and know what to pass it without reading each one; the variable
-  defaults are deliberately left out, being an order of magnitude more
+  `prompt_refs` naming the stored prompts it leans on, and `configures` - for
+  a workflow under `models/`, the `templates/` name it is a tuned
+  configuration of, empty when it is a template itself or when the name does
+  not resolve (then `configures_missing` carries what was written). Enough
+  to choose a workflow and know what to pass it without reading each one; the
+  variable defaults are deliberately left out, being an order of magnitude more
   payload on a listing the UI reloads. Cached by file mtime
 - `GET/PUT/DELETE /api/workflows/{name}` — read, save, delete workflow files
   (confined to `--workflow-dir`)
diff --git a/dw/server/app.py b/dw/server/app.py
index deb64cbc..f775b1d4 100644
--- a/dw/server/app.py
+++ b/dw/server/app.py
@@ -215,6 +215,20 @@ def workflow_details(sources_by_name):
             "writable": source.writable,
         }
     _prune_missing(_workflow_detail_cache)
+    # A model config names its template as a catalog name. Resolve it here,
+    # where the whole listing is in hand, so a badge is a link to a real card
+    # rather than a string - and say which name did not resolve. Entries can
+    # be the very dict cached above (a cache hit skips the copy at line
+    # 212), so copy before mutating - otherwise a stale "not found yet"
+    # verdict would stick in the cache and outlive the typo once the
+    # template it names is added.
+    for name, detail in details.items():
+        named = detail.get("configures", "")
+        if named and named not in details:
+            detail = dict(detail)
+            detail["configures_missing"] = named
+            detail["configures"] = ""
+            details[name] = detail
     return details
 
 
diff --git a/tests/test_server.py b/tests/test_server.py
index 2adf01b0..ea05455d 100644
--- a/tests/test_server.py
+++ b/tests/test_server.py
@@ -462,6 +462,25 @@ def test_workflow_browsing_and_confinement(server):
         assert client.get("/api/workflows/nope").status_code == 404
 
 
+def test_configures_resolves_against_the_listing(server):
+    with server(success_script) as client:
+        client.put("/api/workflows/templates/tti", json={"workflow": valid_workflow("tti")})
+
+        good = valid_workflow("good")
+        good["configures"] = "templates/tti"
+        client.put("/api/workflows/models/good", json={"workflow": good})
+
+        typo = valid_workflow("typo")
+        typo["configures"] = "templates/nope"
+        client.put("/api/workflows/models/typo", json={"workflow": typo})
+
+        details = client.get("/api/workflows").json()["details"]
+
+        assert details["models/good"]["configures"] == "templates/tti"
+        assert details["models/typo"]["configures"] == ""
+        assert details["models/typo"]["configures_missing"] == "templates/nope"
+
+
 def test_a_silently_killed_worker_reports_its_exit_and_frees_the_manager(tmp_path):
     """The OOM killer leaves no traceback, so the exit code is the whole
     diagnosis - and the manager must stop believing the dead process is
@@ -1351,6 +1370,11 @@ def test_workflow_details_name_the_template_a_model_config_configures(server):
     cannot see which is which shows it as just another catalog entry - the
     thing the two-tree layout exists to stop."""
     with server(success_script) as client:
+        client.put(
+            "/api/workflows/templates/text-to-image",
+            json={"workflow": valid_workflow("tti")},
+        )
+
         workflow = valid_workflow("tuned")
         workflow["configures"] = "templates/text-to-image"
         client.put("/api/workflows/models/Tuned", json={"workflow": workflow})

From 96d0b28b473859fc90367ce2e495539a56e49b0c Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 18:34:19 -0500
Subject: [PATCH 29/32] Tighten the tests the restructure loosened

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 tests/test_catalog_structure.py | 38 +++++++++++----------------------
 tests/test_mcp_server.py        | 20 +++++++++++------
 tests/test_prompt_references.py | 12 +++--------
 ui/e2e/smoke.spec.ts            |  7 +++---
 4 files changed, 32 insertions(+), 45 deletions(-)

diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index 6a4c97e5..c8052dff 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -11,56 +11,42 @@
 
 import pytest
 
-from tests.test_examples import REPO_ROOT
+from tests.test_examples import REPO_ROOT, get_example_files
 
-TEMPLATES_DIR = os.path.join(REPO_ROOT, "workflows", "templates")
-
-
-def files_under(directory):
-    if not os.path.isdir(directory):
-        return []
-    found = []
-    for root, _, names in os.walk(directory):
-        found.extend(
-            os.path.join(root, name) for name in names if name.endswith(".json")
-        )
-    return sorted(found)
+TEMPLATES = [f for f in get_example_files() if f.startswith("workflows/templates/")]
+MODEL_CONFIGS = [f for f in get_example_files() if f.startswith("workflows/models/")]
 
 
 def test_there_are_templates():
-    assert files_under(TEMPLATES_DIR)
+    assert TEMPLATES
 
 
-@pytest.mark.parametrize("path", files_under(TEMPLATES_DIR))
+@pytest.mark.parametrize("path", TEMPLATES)
 def test_every_template_describes_itself(path):
     """A template is read before it is run - by a person choosing one and by an
     agent matching a request's shape. An undescribed template is invisible to
     both, whatever its filename says."""
-    definition = json.load(open(path, encoding="utf-8"))
+    definition = json.load(open(os.path.join(REPO_ROOT, path), encoding="utf-8"))
 
     assert definition.get(
         "description", ""
-    ).strip(), f"{os.path.relpath(path, REPO_ROOT)} has no description"
-
-
-MODELS_DIR = os.path.join(REPO_ROOT, "workflows", "models")
+    ).strip(), f"{path} has no description"
 
 
 def test_there_are_model_configs():
-    assert files_under(MODELS_DIR)
+    assert MODEL_CONFIGS
 
 
-@pytest.mark.parametrize("path", files_under(MODELS_DIR))
+@pytest.mark.parametrize("path", MODEL_CONFIGS)
 def test_every_model_config_names_the_template_it_configures(path):
     """A model config is a tuned instance of a pattern. Without the pointer it
     is just another entry in the list, which is the problem this restructure
     exists to fix."""
-    definition = json.load(open(path, encoding="utf-8"))
+    definition = json.load(open(os.path.join(REPO_ROOT, path), encoding="utf-8"))
     configures = definition.get("configures", "")
 
-    assert configures, f"{os.path.relpath(path, REPO_ROOT)} has no 'configures'"
+    assert configures, f"{path} has no 'configures'"
     target = os.path.join(REPO_ROOT, "workflows", f"{configures}.json")
     assert os.path.isfile(target), (
-        f"{os.path.relpath(path, REPO_ROOT)} configures '{configures}', "
-        f"which is not a workflow ({target})"
+        f"{path} configures '{configures}', which is not a workflow ({target})"
     )
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index 511e7ceb..058f551a 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -446,14 +446,20 @@ def test_the_wiring_table_covers_every_registered_tool():
     assert {name for name, _, _, _ in TOOL_WIRING} == EXPECTED_TOOLS - LOCAL_TOOLS
 
 
+# One case per local tool - and every local tool has one, or the wiring
+# exemption below would be a hole rather than a statement
+LOCAL_TOOL_CASES = [
+    ("list_guides", {}),
+    ("get_guide", {"name": "tasks", "section": "Speech Generation"}),
+]
+
+
+def test_every_local_tool_is_held_to_making_no_request():
+    assert {name for name, _ in LOCAL_TOOL_CASES} == LOCAL_TOOLS
+
+
 @pytest.mark.asyncio
-@pytest.mark.parametrize(
-    "name,arguments",
-    [
-        ("list_guides", {}),
-        ("get_guide", {"name": "tasks", "section": "Speech Generation"}),
-    ],
-)
+@pytest.mark.parametrize("name,arguments", LOCAL_TOOL_CASES)
 async def test_the_guide_tools_reach_no_server(name, arguments):
     """They have to work against an engine that is not answering - and against a
     remote one, whose disk is not where the packaged guides are."""
diff --git a/tests/test_prompt_references.py b/tests/test_prompt_references.py
index 13a74d01..b584724a 100644
--- a/tests/test_prompt_references.py
+++ b/tests/test_prompt_references.py
@@ -13,21 +13,15 @@
 import pytest
 
 from dw.prompts import PROMPT_PREFIX, resolve_prompt_reference
+from dw.server.app import collect_prompt_references
 from tests.test_examples import REPO_ROOT, get_example_files
 
 PROMPT_DIR = os.path.join(REPO_ROOT, "prompts")
 
 
 def prompt_references(definition):
-    """Every "prompt:..." string anywhere in a workflow definition."""
-    if isinstance(definition, dict):
-        for value in definition.values():
-            yield from prompt_references(value)
-    elif isinstance(definition, list):
-        for value in definition:
-            yield from prompt_references(value)
-    elif isinstance(definition, str) and definition.startswith(PROMPT_PREFIX):
-        yield definition
+    """Every 'prompt:' reference a workflow makes, as written."""
+    return [f"{PROMPT_PREFIX}{name}" for name in sorted(collect_prompt_references(definition))]
 
 
 @pytest.mark.parametrize("example_file", get_example_files())
diff --git a/ui/e2e/smoke.spec.ts b/ui/e2e/smoke.spec.ts
index cd8788ba..552d1f3e 100644
--- a/ui/e2e/smoke.spec.ts
+++ b/ui/e2e/smoke.spec.ts
@@ -7,9 +7,10 @@ test('workflow browser lists, describes and filters', async ({ page }) => {
   await expect(
     page.getByText('Text-to-image with Z-Image Turbo').first(),
   ).toBeVisible()
-  // the filter searches descriptions, not just names
-  await page.getByPlaceholder('filter…').fill('inpaint')
-  await expect(page.getByRole('link', { name: /^inpaint / })).toBeVisible()
+  // the filter searches descriptions, not just names: 'fill dev' appears in
+  // outpaint's description and in no workflow's name
+  await page.getByPlaceholder('filter…').fill('fill dev')
+  await expect(page.getByRole('link', { name: /^outpaint / })).toBeVisible()
   await expect(page.getByRole('link', { name: /^z-image / })).toHaveCount(0)
 })
 

From b1945f957301ad0bc31d4d69c091149359002ff0 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 18:35:46 -0500
Subject: [PATCH 30/32] Flatten the audio rate precedence and reuse the
 grouping helpers

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 CLAUDE.md                                |  2 +-
 dw/result.py                             | 14 +++++---------
 ui/src/lib/pages/EditorPage.svelte       | 20 ++++++++------------
 ui/src/lib/pages/PromptEditorPage.svelte | 14 ++++----------
 4 files changed, 18 insertions(+), 32 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index c260f8f4..365c1e6c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -12,7 +12,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 # Install
 bash ./install.sh && source ./activate
 
-# Run a workflow - sd15.json uses a small, ungated model and a literal
+# Run a workflow - templates/text-to-image.json uses a small, ungated model and a literal
 # prompt, so it needs no Hugging Face login and downloads only a few GB
 python -m dw.run workflows/templates/text-to-image.json
 python -m dw.run workflows/templates/text-to-image.json prompt="a cat" num_images_per_prompt=4
diff --git a/dw/result.py b/dw/result.py
index 00482c32..f800bfce 100644
--- a/dw/result.py
+++ b/dw/result.py
@@ -404,15 +404,11 @@ def save_artifact(
                 )
             elif content_type.startswith("audio"):
                 waveforms = normalize_audio(artifact)
-                # A track generated by a model carries the rate it was generated
-                # at, which beats the default - but not a rate the workflow named
-                sample_rate = self.result_definition.get(
-                    "sample_rate",
-                    self.result_definition.get(
-                        "samplerate",
-                        getattr(artifact, "sample_rate", None)
-                        or DEFAULT_AUDIO_SAMPLE_RATE,
-                    ),
+                # Declared rate > the rate a generated track carries > default
+                sample_rate = (
+                    self.result_definition.get("sample_rate")
+                    or getattr(artifact, "sample_rate", None)
+                    or DEFAULT_AUDIO_SAMPLE_RATE
                 )
                 # A batched waveform holds several songs - save each one separately
                 if len(waveforms) > 1:
diff --git a/ui/src/lib/pages/EditorPage.svelte b/ui/src/lib/pages/EditorPage.svelte
index 15fca900..c225bbb0 100644
--- a/ui/src/lib/pages/EditorPage.svelte
+++ b/ui/src/lib/pages/EditorPage.svelte
@@ -24,6 +24,7 @@
     referenceSuggestions,
   } from '../editor'
   import { danglingReferenceDetails, flowGraph } from '../flow'
+  import { groupOf, leafOf } from '../grouping'
   import { loadPromptLibrary, promptLibrary } from '../promptlib.svelte'
   import { PROMPT_LIST_ID } from '../prompts'
   import { storageGet, storageSet } from '../storage'
@@ -70,13 +71,7 @@
   // Existing folders, from the listing - one level is the designed depth,
   // but any deeper directories that exist still appear and keep working
   const folders = $derived(
-    [
-      ...new Set(
-        workflowFiles
-          .filter((file) => file.includes('/'))
-          .map((file) => file.split('/').slice(0, -1).join('/')),
-      ),
-    ].sort(),
+    [...new Set(workflowFiles.map(groupOf).filter(Boolean))].sort(),
   )
   let validation = $state<ValidationResult | null>(null)
   type EditorView = 'form' | 'split' | 'json' | 'flow'
@@ -129,8 +124,10 @@
   // Crumbs back out of the editor. The read-only page is where an edit
   // usually starts, and until now the only exit landed on the list - so
   // the last crumb links back to the workflow itself, when one is saved.
-  const crumbFolders = $derived(name ? name.split('/').slice(0, -1) : [])
-  const crumbName = $derived(name ? name.split('/').slice(-1)[0] : '')
+  const crumbFolders = $derived(
+    name ? groupOf(name).split('/').filter(Boolean) : [],
+  )
+  const crumbName = $derived(name ? leafOf(name) : '')
   const workflowHref = $derived(
     '#/workflows/' + name.split('/').map(encodeURIComponent).join('/'),
   )
@@ -201,9 +198,8 @@
     loadPromptLibrary()
     validation = null
     if (name) {
-      const segments = name.split('/')
-      saveName = segments[segments.length - 1]
-      folder = segments.slice(0, -1).join('/')
+      saveName = leafOf(name)
+      folder = groupOf(name)
       fileOpen = false
       api
         .getWorkflow(name)
diff --git a/ui/src/lib/pages/PromptEditorPage.svelte b/ui/src/lib/pages/PromptEditorPage.svelte
index d42b1676..38db972a 100644
--- a/ui/src/lib/pages/PromptEditorPage.svelte
+++ b/ui/src/lib/pages/PromptEditorPage.svelte
@@ -16,6 +16,7 @@
   import { phaseLabel } from '../progress'
   import { notify } from '../toast'
   import { loadPromptLibrary } from '../promptlib.svelte'
+  import { groupOf, leafOf } from '../grouping'
   import {
     emptyPrompt,
     knownIntendedModels,
@@ -47,13 +48,7 @@
 
   // Existing folders, from the listing - one level is the designed depth
   const folders = $derived(
-    [
-      ...new Set(
-        promptFiles
-          .filter((file) => file.includes('/'))
-          .map((file) => file.split('/').slice(0, -1).join('/')),
-      ),
-    ].sort(),
+    [...new Set(promptFiles.map(groupOf).filter(Boolean))].sort(),
   )
 
   type EditorView = 'form' | 'split' | 'json'
@@ -254,9 +249,8 @@
       .catch((e) => notify.error(e.message))
     refreshModels()
     if (name) {
-      const segments = name.split('/')
-      saveName = segments[segments.length - 1]
-      folder = segments.slice(0, -1).join('/')
+      saveName = leafOf(name)
+      folder = groupOf(name)
       api
         .getPrompt(name)
         .then((definition) => {

From 0154b9dc601f4138319252a3d1fabc3553491e08 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 18:52:51 -0500
Subject: [PATCH 31/32] Apply PR41 review fix wave: formatting, docs, and small
 correctness fixes

- black/prettier the flagged files (CI gate)
- correct generate_speech compose wording and add the voice_preset
  refusal note in docs/TASKS.md
- fix the WORKFLOW_GUIDE.md claim that audio never carries its own
  rate, now false for AudioLDM2/StableAudio/generate_speech
- generalise the batched-audio-save recursion to any artifact
  carrying a sample_rate, not just AudioTrack, with a test
- stop consulting a video pipeline's VAE for an audio sample rate
  on .audio outputs (only .audios), with tests
- assert the "no component reports its sample rate" warning fires
- remove the unreachable `or os.sep` fallback in catalog_root_dir
- document that a models/ catalog entry carries configures /
  configures_missing

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/MCP.md                        |  2 +-
 docs/TASKS.md                      |  4 +--
 docs/WORKFLOW_GUIDE.md             |  5 ++--
 dw/pipeline_processors/pipeline.py |  8 ++++--
 dw/result.py                       |  9 ++++---
 dw/workflow.py                     |  2 +-
 dw_mcp/catalog.py                  |  4 ++-
 tests/test_arguments.py            |  4 ++-
 tests/test_catalog_structure.py    | 10 +++-----
 tests/test_mcp_guides.py           |  8 ++++--
 tests/test_pipeline_components.py  | 22 ++++++++++++++--
 tests/test_prompt_references.py    |  5 +++-
 tests/test_result.py               | 21 ++++++++++++++++
 tests/test_server.py               |  4 ++-
 tests/test_speech_generation.py    |  4 ++-
 tests/test_workflow.py             | 40 ++++++++++++++++++++++++------
 ui/src/lib/grouping.test.ts        | 11 +++++---
 ui/src/lib/grouping.ts             |  4 +--
 18 files changed, 126 insertions(+), 41 deletions(-)

diff --git a/docs/MCP.md b/docs/MCP.md
index 430da1dc..c5627390 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -200,7 +200,7 @@ when no single workflow covers it.
 | --- | --- | --- |
 | `list_guides()` | — | List the documentation shipped with the engine: each guide's name, what it covers, and its section headings. The index is the routing table - match a request's shape against a heading rather than guessing |
 | `get_guide(name, section=None)` | `name`, `section` | Get one guide whole, or one section of it. Prefer a section: a guide runs to thousands of lines. Section names match loosely, so a heading copied approximately still resolves |
-| `list_workflows()` | — | List stored workflows, each with its description, output kinds, step count, variable names, the stored prompts it references, and its `origin`/`writable` - a workflow from a read-only examples directory can be read and run but not saved over or deleted. The first call to make for a request an existing workflow might cover |
+| `list_workflows()` | — | List stored workflows, each with its description, output kinds, step count, variable names, the stored prompts it references, and its `origin`/`writable` - a workflow from a read-only examples directory can be read and run but not saved over or deleted. A `models/` entry also carries `configures`, the template it configures, or `configures_missing` naming it when that template does not resolve. The first call to make for a request an existing workflow might cover |
 | `get_workflow(name)` | `name` | Get one stored workflow's full JSON definition |
 | `get_schema()` | — | Get the JSON schema every workflow definition must satisfy |
 | `list_pipelines()` | — | List every diffusers pipeline class this installation provides |
diff --git a/docs/TASKS.md b/docs/TASKS.md
index 82304027..4eac74b9 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -955,7 +955,7 @@ It is merged after everything else, so it can override `repetition_penalty` and
 
 ## Speech Generation
 
-Speak a line of text with a local text-to-speech model. The result is a waveform carrying the rate its model generated at, so it composes with [`slice_audio`](#slice_audio), [`fade_audio`](#fade_audio), [`pair_audio`](#pair_audio) and [`concat_videos`](#concat_videos) directly.
+Speak a line of text with a local text-to-speech model. The result is a waveform carrying the rate its model generated at, so it composes with [`slice_audio`](#slice_audio), [`fade_audio`](#fade_audio) and [`pair_audio`](#pair_audio) directly ([`concat_videos`](#concat_videos) and `dissolve_videos` join videos — pair the track onto a video first).
 
 ```json
 {
@@ -974,7 +974,7 @@ Speak a line of text with a local text-to-speech model. The result is a waveform
 | -------- | -------- | ----------- |
 | `text` | Yes | The line to speak |
 | `model_name` | No | HuggingFace model ID (default: `suno/bark-small`) |
-| `voice_preset` | No | The speaker, for a model with presets — `v2/en_speaker_0` through `v2/en_speaker_9` for Bark |
+| `voice_preset` | No | The speaker, for a model with presets — `v2/en_speaker_0` through `v2/en_speaker_9` for Bark. A model with no processor (a single-voice model such as `facebook/mms-tts-eng`) refuses a `voice_preset` with an error rather than ignoring it |
 | `forward_params` | No | Passed to the model's forward/generate call |
 | `generate_kwargs` | No | Ad-hoc generation settings for a generative model — `temperature`, `do_sample` |
 
diff --git a/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md
index 68a0b6ae..e74360cc 100644
--- a/docs/WORKFLOW_GUIDE.md
+++ b/docs/WORKFLOW_GUIDE.md
@@ -246,7 +246,8 @@ file, or a URL, exactly like the plain `image`/`video` forms.
 
 Supported content types: `image/jpeg`, `image/png`, `image/webp`, `image/gif`, `video/mp4`, `audio/wav`, `audio/flac`, `audio/mpeg` (mp3), `audio/ogg`, `audio/opus`, `audio/aiff`, `application/json`, `text/plain` (plus the common aliases `audio/x-wav`, `audio/mp3`, `audio/vorbis`).
 
-For video, add `"fps": 8`. For audio, add `"sample_rate": 44100`. Setting `embed_metadata: true`
+For video, add `"fps": 8`. For audio, add `"sample_rate": 44100` when the waveform doesn't
+already carry a rate of its own (a declared rate always wins). Setting `embed_metadata: true`
 on an image result embeds the step's model name and arguments as generation metadata -
 PNG info chunks for `image/png`, EXIF `UserComment` (via `piexif`) for `image/jpeg` and
 `image/webp`.
@@ -1116,7 +1117,7 @@ lands in comes from the type's own `kind`:
 | ------- | ------------------------------------------------------------------------- |
 | `image` | The generated image                                                       |
 | `video` | The generated frames, and the soundtrack generated with them if there was one |
-| `audio` | The generated soundtrack - or, for a step that produced audio alone (a music pipeline, a `slice_audio` task), the waveform itself, which carries no rate of its own, so declare `sample_rate` beside `from_previous_result` |
+| `audio` | The generated soundtrack - or, for a step that produced audio alone (a music pipeline, a `slice_audio` task), the waveform itself. The rate travels with the waveform when the pipeline or task reports one (an `AudioTrack` - AudioLDM2, StableAudio, `generate_speech`); declare `sample_rate` beside `from_previous_result` only for a waveform from a task or file that carries none, and a declared rate always wins |
 
 Any other key is a field of the object and wins over what the media carried —
 `"fps": 30.0` where the producing pipeline generated at a rate the consuming one does
diff --git a/dw/pipeline_processors/pipeline.py b/dw/pipeline_processors/pipeline.py
index e00f89e8..d7ec53e3 100644
--- a/dw/pipeline_processors/pipeline.py
+++ b/dw/pipeline_processors/pipeline.py
@@ -1101,8 +1101,12 @@ def warn_if_safety_checker_blanked(output):
 )
 
 
-def _component_sample_rate(pipeline):
+def _component_sample_rate(pipeline, has_audios):
     for component_name, attribute in _SAMPLE_RATE_SOURCES:
+        if component_name == "vae" and not has_audios:
+            # A video VAE's config is not where an audio rate lives - only an
+            # audio-only pipeline's VAE (StableAudio) reports one there
+            continue
         config = getattr(getattr(pipeline, component_name, None), "config", None)
         sample_rate = getattr(config, attribute, None)
         if sample_rate is not None:
@@ -1128,7 +1132,7 @@ def attach_audio_sample_rate(pipeline, output):
     if not (has_audio or has_audios):
         return
 
-    sample_rate = _component_sample_rate(pipeline)
+    sample_rate = _component_sample_rate(pipeline, has_audios)
     if sample_rate is None:
         logger.warning(
             "Pipeline generated audio but no component reports its sample rate - "
diff --git a/dw/result.py b/dw/result.py
index f800bfce..fd9d7d9d 100644
--- a/dw/result.py
+++ b/dw/result.py
@@ -420,9 +420,12 @@ def save_artifact(
                                 # Keep the rate the track carries across the
                                 # recursion - a bare waveform would fall back
                                 # to the default
-                                AudioTrack(waveform.T, sample_rate)
-                                if isinstance(artifact, AudioTrack)
-                                else waveform,
+                                (
+                                    AudioTrack(waveform.T, sample_rate)
+                                    if getattr(artifact, "sample_rate", None)
+                                    is not None
+                                    else waveform
+                                ),
                                 f"{file_base_name}-{k}",
                                 content_type,
                                 extension,
diff --git a/dw/workflow.py b/dw/workflow.py
index 2f254115..39aa7f1f 100644
--- a/dw/workflow.py
+++ b/dw/workflow.py
@@ -155,7 +155,7 @@ def catalog_root_dir(file_spec):
     except ValueError:
         return directory
 
-    return os.sep.join(parts[: index + 1]) or os.sep
+    return os.sep.join(parts[: index + 1])
 
 
 def pipeline_cache_key(pipeline_definition):
diff --git a/dw_mcp/catalog.py b/dw_mcp/catalog.py
index 08bc5303..d1f07d77 100644
--- a/dw_mcp/catalog.py
+++ b/dw_mcp/catalog.py
@@ -10,7 +10,9 @@ def list_workflows(client):
     """Workflow names the server can reach, with details - description,
     output kinds and variable names per workflow, plus which source each came
     from and whether it can be written to (a read-only examples directory
-    can be read and run, but not saved over or deleted)."""
+    can be read and run, but not saved over or deleted). A `models/` entry
+    also carries `configures`, the template it configures, or
+    `configures_missing` naming it when that template does not resolve."""
     return client.get_json("/api/workflows")
 
 
diff --git a/tests/test_arguments.py b/tests/test_arguments.py
index b58a56c2..66abd03f 100644
--- a/tests/test_arguments.py
+++ b/tests/test_arguments.py
@@ -795,7 +795,9 @@ def test_a_video_reference_to_a_speech_step_says_so(self):
             }
         }
 
-        with pytest.raises(ValueError, match="holds a video, but the step it names produced"):
+        with pytest.raises(
+            ValueError, match="holds a video, but the step it names produced"
+        ):
             build_objects(arguments)
 
     def test_the_wrong_media_for_the_kind_is_an_error(self):
diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index c8052dff..ca920aa3 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -28,9 +28,7 @@ def test_every_template_describes_itself(path):
     both, whatever its filename says."""
     definition = json.load(open(os.path.join(REPO_ROOT, path), encoding="utf-8"))
 
-    assert definition.get(
-        "description", ""
-    ).strip(), f"{path} has no description"
+    assert definition.get("description", "").strip(), f"{path} has no description"
 
 
 def test_there_are_model_configs():
@@ -47,6 +45,6 @@ def test_every_model_config_names_the_template_it_configures(path):
 
     assert configures, f"{path} has no 'configures'"
     target = os.path.join(REPO_ROOT, "workflows", f"{configures}.json")
-    assert os.path.isfile(target), (
-        f"{path} configures '{configures}', which is not a workflow ({target})"
-    )
+    assert os.path.isfile(
+        target
+    ), f"{path} configures '{configures}', which is not a workflow ({target})"
diff --git a/tests/test_mcp_guides.py b/tests/test_mcp_guides.py
index 73542dae..c0f5066f 100644
--- a/tests/test_mcp_guides.py
+++ b/tests/test_mcp_guides.py
@@ -40,7 +40,9 @@ def test_every_curated_guide_file_exists(self):
 
 
 class TestWhereTheyComeFrom:
-    def test_a_checkout_is_preferred_over_a_stale_packaged_copy(self, tmp_path, monkeypatch):
+    def test_a_checkout_is_preferred_over_a_stale_packaged_copy(
+        self, tmp_path, monkeypatch
+    ):
         """build_dist.sh leaves dw/docs/ behind (gitignored). If that copy won,
         every later edit to docs/ would be invisible to the MCP and to these
         tests - so the repo's docs/ wins whenever it is there, and the packaged
@@ -62,7 +64,9 @@ def test_an_install_reads_the_packaged_copy(self, tmp_path, monkeypatch):
 
         assert guides.read_guide("tasks") == "## Packaged\n"
 
-    def test_a_checkout_with_no_packaged_copy_reads_the_repo_docs(self, tmp_path, monkeypatch):
+    def test_a_checkout_with_no_packaged_copy_reads_the_repo_docs(
+        self, tmp_path, monkeypatch
+    ):
         root = tmp_path / "repo"
         (root / "docs").mkdir(parents=True)
         (root / "docs" / "TASKS.md").write_text("## Checkout\n")
diff --git a/tests/test_pipeline_components.py b/tests/test_pipeline_components.py
index 39f29904..0f27d451 100644
--- a/tests/test_pipeline_components.py
+++ b/tests/test_pipeline_components.py
@@ -528,11 +528,29 @@ def test_a_vae_rate_is_recorded_for_audios(self):
 
         assert output.audio_sample_rate == 44100
 
-    def test_no_rate_anywhere_records_nothing(self):
+    def test_no_rate_anywhere_records_nothing(self, caplog):
         from dw.pipeline_processors.pipeline import attach_audio_sample_rate
 
         output = self._output()
 
-        attach_audio_sample_rate(self._pipeline(), output)
+        with caplog.at_level("WARNING", logger="dw"):
+            attach_audio_sample_rate(self._pipeline(), output)
+
+        assert not hasattr(output, "audio_sample_rate")
+        assert "no component reports its sample rate" in caplog.text
+
+    def test_a_vae_rate_is_not_used_for_video_plus_audio(self):
+        # A video+audio pipeline's `vae` is a video VAE - its config is not
+        # where an audio rate lives, so it must not be consulted for `.audio`
+        from types import SimpleNamespace
+
+        from dw.pipeline_processors.pipeline import attach_audio_sample_rate
+
+        pipeline = self._pipeline(
+            vae=SimpleNamespace(config=SimpleNamespace(sampling_rate=44100))
+        )
+        output = SimpleNamespace(audio=[0.0, 0.0])
+
+        attach_audio_sample_rate(pipeline, output)
 
         assert not hasattr(output, "audio_sample_rate")
diff --git a/tests/test_prompt_references.py b/tests/test_prompt_references.py
index b584724a..b8b4cf9e 100644
--- a/tests/test_prompt_references.py
+++ b/tests/test_prompt_references.py
@@ -21,7 +21,10 @@
 
 def prompt_references(definition):
     """Every 'prompt:' reference a workflow makes, as written."""
-    return [f"{PROMPT_PREFIX}{name}" for name in sorted(collect_prompt_references(definition))]
+    return [
+        f"{PROMPT_PREFIX}{name}"
+        for name in sorted(collect_prompt_references(definition))
+    ]
 
 
 @pytest.mark.parametrize("example_file", get_example_files())
diff --git a/tests/test_result.py b/tests/test_result.py
index fc40978e..69688d96 100644
--- a/tests/test_result.py
+++ b/tests/test_result.py
@@ -687,6 +687,27 @@ def test_a_track_saves_at_the_rate_it_carries(self):
             _, sample_rate = soundfile.read(os.path.join(temp_dir, "line-0.0.wav"))
             assert sample_rate == 24000
 
+    def test_a_batched_track_keeps_its_rate_across_the_recursion(self):
+        # A batched AudioTrack (several waveforms in one artifact) recurses through
+        # save_artifact per waveform - the recursion must keep re-wrapping as an
+        # AudioTrack by checking for a carried sample_rate, not by isinstance, so
+        # a batch saved this way still saves at the rate it carries
+        from dw.result import AudioTrack
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            result = Result({"content_type": "audio/wav"})
+            result.add_result(
+                AudioTrack(numpy.zeros((2, 1, 4410), dtype=numpy.float32), 22050)
+            )
+
+            result.save(temp_dir, "line")
+
+            for j in (0, 1):
+                _, sample_rate = soundfile.read(
+                    os.path.join(temp_dir, f"line-0.0-{j}.wav")
+                )
+                assert sample_rate == 22050
+
     def test_a_declared_rate_wins_over_the_one_the_track_carries(self):
         from dw.result import AudioTrack
 
diff --git a/tests/test_server.py b/tests/test_server.py
index ea05455d..6fd86472 100644
--- a/tests/test_server.py
+++ b/tests/test_server.py
@@ -464,7 +464,9 @@ def test_workflow_browsing_and_confinement(server):
 
 def test_configures_resolves_against_the_listing(server):
     with server(success_script) as client:
-        client.put("/api/workflows/templates/tti", json={"workflow": valid_workflow("tti")})
+        client.put(
+            "/api/workflows/templates/tti", json={"workflow": valid_workflow("tti")}
+        )
 
         good = valid_workflow("good")
         good["configures"] = "templates/tti"
diff --git a/tests/test_speech_generation.py b/tests/test_speech_generation.py
index 6cafb966..89d46c61 100644
--- a/tests/test_speech_generation.py
+++ b/tests/test_speech_generation.py
@@ -138,7 +138,9 @@ def test_a_preset_the_model_cannot_take_is_an_error(self, mock_pipeline):
         mock_pipeline.return_value.processor = None
 
         with self.assertRaises(ValueError) as raised:
-            generate_speech("hi", model_name="facebook/mms-tts-eng", voice_preset="v2/en_speaker_6")
+            generate_speech(
+                "hi", model_name="facebook/mms-tts-eng", voice_preset="v2/en_speaker_6"
+            )
 
         self.assertIn("voice_preset", str(raised.exception))
         self.assertIn("facebook/mms-tts-eng", str(raised.exception))
diff --git a/tests/test_workflow.py b/tests/test_workflow.py
index 3be11dbe..f6dbf72c 100644
--- a/tests/test_workflow.py
+++ b/tests/test_workflow.py
@@ -359,7 +359,10 @@ def _catalog(self, tmp_path):
             "steps": [
                 {
                     "name": "noop",
-                    "task": {"command": "get_dict_value", "arguments": {"dict": {"k": 1}, "key": "k"}},
+                    "task": {
+                        "command": "get_dict_value",
+                        "arguments": {"dict": {"k": 1}, "key": "k"},
+                    },
                 }
             ],
         }
@@ -409,7 +412,12 @@ def test_a_parent_directory_step_escaping_the_root_is_refused(self, tmp_path):
         outside.write_text(json.dumps({"id": "x", "steps": []}))
         parent = {
             "id": "parent",
-            "steps": [{"name": "sub", "workflow": {"path": "../outside.json", "arguments": {}}}],
+            "steps": [
+                {
+                    "name": "sub",
+                    "workflow": {"path": "../outside.json", "arguments": {}},
+                }
+            ],
         }
         parent_path = root / "parent.json"
         parent_path.write_text(json.dumps(parent))
@@ -424,7 +432,9 @@ def test_a_parent_directory_step_escaping_the_root_is_refused(self, tmp_path):
                 device="cpu",
             )
 
-    def test_an_unconfined_run_still_refuses_climbing_out_of_the_catalog(self, tmp_path):
+    def test_an_unconfined_run_still_refuses_climbing_out_of_the_catalog(
+        self, tmp_path
+    ):
         """No workflow_dir (a bare CLI run) still confines a relative
         sub-workflow reference - to the catalog root now, rather than
         relying on the '..' regex normpath removes."""
@@ -439,7 +449,10 @@ def test_an_unconfined_run_still_refuses_climbing_out_of_the_catalog(self, tmp_p
         parent = {
             "id": "parent",
             "steps": [
-                {"name": "sub", "workflow": {"path": "../../outside.json", "arguments": {}}}
+                {
+                    "name": "sub",
+                    "workflow": {"path": "../../outside.json", "arguments": {}},
+                }
             ],
         }
         parent_path = tmp_path / "workflows" / "templates" / "parent.json"
@@ -470,7 +483,10 @@ def test_an_unconfined_run_may_climb_to_a_sibling_catalog_folder(self, tmp_path)
             "steps": [
                 {
                     "name": "noop",
-                    "task": {"command": "get_dict_value", "arguments": {"dict": {"k": 1}, "key": "k"}},
+                    "task": {
+                        "command": "get_dict_value",
+                        "arguments": {"dict": {"k": 1}, "key": "k"},
+                    },
                 }
             ],
         }
@@ -478,7 +494,10 @@ def test_an_unconfined_run_may_climb_to_a_sibling_catalog_folder(self, tmp_path)
         parent = {
             "id": "parent",
             "steps": [
-                {"name": "sub", "workflow": {"path": "../models/child.json", "arguments": {}}}
+                {
+                    "name": "sub",
+                    "workflow": {"path": "../models/child.json", "arguments": {}},
+                }
             ],
         }
         parent_path = tmp_path / "workflows" / "templates" / "parent.json"
@@ -495,7 +514,9 @@ def test_an_unconfined_run_may_climb_to_a_sibling_catalog_folder(self, tmp_path)
 
         assert action is not None
 
-    def test_a_file_outside_any_catalog_is_confined_to_its_own_directory(self, tmp_path):
+    def test_a_file_outside_any_catalog_is_confined_to_its_own_directory(
+        self, tmp_path
+    ):
         """No 'workflows' ancestor at all - the referencing file's own
         directory is the confinement, so a sibling of a sibling is still
         refused even though the target file genuinely exists."""
@@ -511,7 +532,10 @@ def test_a_file_outside_any_catalog_is_confined_to_its_own_directory(self, tmp_p
         parent = {
             "id": "parent",
             "steps": [
-                {"name": "sub", "workflow": {"path": "../b/child.json", "arguments": {}}}
+                {
+                    "name": "sub",
+                    "workflow": {"path": "../b/child.json", "arguments": {}},
+                }
             ],
         }
         parent_path = tmp_path / "a" / "parent.json"
diff --git a/ui/src/lib/grouping.test.ts b/ui/src/lib/grouping.test.ts
index ddaf1eef..714dfc82 100644
--- a/ui/src/lib/grouping.test.ts
+++ b/ui/src/lib/grouping.test.ts
@@ -21,9 +21,9 @@ describe('groupOf', () => {
   it('is not how the gallery groups - a gallery name carries a run id', () => {
     // <identity>/<run id>/<file>: the last folder is the run, not the workflow.
     // GalleryPage groups by the server's `folder` (strip_run_id) instead
-    expect(groupOf('templates/ltx2/two-stage/20260906-101500-a1b2c3d4/still.png')).toBe(
-      'templates/ltx2/two-stage/20260906-101500-a1b2c3d4',
-    )
+    expect(
+      groupOf('templates/ltx2/two-stage/20260906-101500-a1b2c3d4/still.png'),
+    ).toBe('templates/ltx2/two-stage/20260906-101500-a1b2c3d4')
   })
 })
 
@@ -50,7 +50,10 @@ describe('groupNames', () => {
     // run id - the name alone cannot tell a run id from a folder
     const folderOf = (name: string) => name.split('/')[0]
     const grouped = groupNames(
-      ['tti/20260906-101500-a1b2c3d4/a.png', 'tti/20260906-101612-ffffffff/b.png'],
+      [
+        'tti/20260906-101500-a1b2c3d4/a.png',
+        'tti/20260906-101612-ffffffff/b.png',
+      ],
       folderOf,
     )
     expect([...grouped.keys()]).toEqual(['tti'])
diff --git a/ui/src/lib/grouping.ts b/ui/src/lib/grouping.ts
index dad3117c..0d6eaee3 100644
--- a/ui/src/lib/grouping.ts
+++ b/ui/src/lib/grouping.ts
@@ -31,7 +31,5 @@ export const groupNames = (
     if (bucket) bucket.push(name)
     else buckets.set(group, [name])
   }
-  return new Map(
-    [...buckets.entries()].sort(([a], [b]) => a.localeCompare(b)),
-  )
+  return new Map([...buckets.entries()].sort(([a], [b]) => a.localeCompare(b)))
 }

From b92402de62666a6164b02987982a333c5ef11499 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 6 Sep 2026 18:59:36 -0500
Subject: [PATCH 32/32] Add proposal for optimizing agent reading capabilities
 and metadata costs

---
 docs/proposals/mcp-discovery-data.md | 183 +++++++++++++++++++++++++++
 1 file changed, 183 insertions(+)
 create mode 100644 docs/proposals/mcp-discovery-data.md

diff --git a/docs/proposals/mcp-discovery-data.md b/docs/proposals/mcp-discovery-data.md
new file mode 100644
index 00000000..4628927f
--- /dev/null
+++ b/docs/proposals/mcp-discovery-data.md
@@ -0,0 +1,183 @@
+# Proposal: right-sizing what an agent reads to choose a capability
+
+Status: proposed, 2026-09-06. Follows the review of PR 41, which added
+`list_guides`/`get_guide` and the two-tree catalog. Builds on
+docs/proposals/catalog-shape-index.md, which proposes the shape index this
+document argues for from the token side.
+
+## The question
+
+An agent connected to `dw_mcp` has to turn a request stated as a *subject*
+("a lego movie trailer set in the marvel universe") into a template, a set of
+arguments, and a cost estimate - without guessing. Everything it can read to
+do that costs tokens on every session, and everything hand-written drifts. Is
+the metadata over-specified, under-specified, or about right?
+
+## What it costs today
+
+Measured on the PR 41 branch (chars ÷ 4 ≈ tokens):
+
+| Surface | Size | When it is read |
+|---|---|---|
+| Server `instructions` | ~780 tokens | every session, unconditionally |
+| 54 tool descriptions | ~3,750 tokens | every session, unconditionally |
+| `list_guides` | ~865 tokens | once, on demand |
+| `list_workflows` (73 entries) | **~11,450 tokens** | the first catalog look - the instructions say to start here |
+| `list_tasks` | ~270 tokens (bare names) | on demand |
+| `get_task <cmd>` | 350-1,400 tokens | per command inspected |
+| a whole guide (`tasks`, `workflows`) | ~13,000 tokens each | should never happen; `get_guide` takes a section |
+
+The standing cost - what every session pays before the first decision - is
+~4.5k tokens. That is lean for 54 tools, and the instructions are the right
+kind of text: a decision *order* (shape first, then catalog, then `list_tasks`,
+author last) rather than a description of each tool. The `acknowledged_cost`
+contract is stated once and the tools refer back to it.
+
+The variable cost is one call. `list_workflows` is 2.5× everything else
+combined, and 21k of its 46k characters are `description` strings, five of
+them (the MiniMax narratives) at 700-1,400 characters each. Every entry also
+repeats `origin`, `writable` and `prompt_refs`, which an agent choosing a
+template never uses.
+
+## What is working and should not change
+
+- **The guides index as a routing table.** ~865 tokens for nine guides with
+  their `##` headings is the best-value addition in PR 41. The 18 `tasks`
+  headings and 9 `workflows` headings are what convert "trailer" into
+  "multi-shot + dialogue + cuts" without reading 13k tokens. Section fetch
+  with loose heading matching is exactly right.
+- **`list_tasks` as bare names.** Discovery goes through the `tasks` guide's
+  sections; `get_task` gives the real signature. Adding summaries to the list
+  would duplicate the guide.
+- **The instructions' shape-first rule.** This is the one sentence that stops
+  an agent from authoring a fresh workflow for a request an existing template
+  covers. Keep it, and make it executable (below).
+- **The two-tree split with `configures`.** Nine `models/` entries collapse to
+  "text-to-image with a checkpoint choice" the moment an agent can see the
+  field; that alone removes nine candidates from the first cut.
+
+## Where it costs more than it needs to
+
+### 1. The listing is prose where it should be fields
+
+An agent picking a template needs, per entry: what shape it produces, what
+inputs it needs, what it will cost, and one line saying what it is for. The
+listing gives it a paragraph and leaves it to infer all four. Prose gets
+reworded and never indexed; five 1,000-character descriptions are five essays
+an agent skims and forgets by the time it reads the fortieth.
+
+**Proposal.** Split `description` into a required `summary` (one sentence,
+≤ 120 characters, what it is for) and the existing free text, and have the
+listing carry the summary only; `get_workflow` returns the full text. Expected
+effect on `list_workflows`: 21k description characters → ~6k, the whole
+listing ~11.4k → ~5.5k tokens. The `summary` field is what a card shows and
+what an agent matches on; the long description stays the place where the
+argument sets and caveats live.
+
+### 2. Shape is the first question and nothing names it
+
+The instructions say "decide which shape the deliverable is first, then match
+the catalog against that". The catalog carries `kinds` (`image`, `video`,
+`audio`, `text`) - the output *media type* - which is not the shape. A single
+still, an image set, one shot, a multi-shot cut sequence, and video with
+generated speech are all `kinds: ["video"]` or `["image"]`.
+
+**Proposal.** A `shape` field on every template, from a closed vocabulary the
+schema enumerates:
+
+| shape | what it produces |
+|---|---|
+| `image` | one still, or a set from one prompt |
+| `image-set` | several stills the workflow relates (a storyboard, variations, a sweep) |
+| `image-edit` | a still derived from a supplied one (inpaint, outpaint, edit, upscale, restore) |
+| `shot` | one continuous clip |
+| `sequence` | several shots cut or dissolved together |
+| `video-with-speech` | a clip whose audio is generated dialogue or narration |
+| `audio` | a track by itself (music, speech) |
+| `text` | a prompt, caption or description |
+| `utility` | a processing step with no generative model (segment, crop, embed metadata) |
+
+`list_workflows` gains an optional `shape` filter (and `kinds`, while at it).
+"A trailer" resolves to `sequence` + `video-with-speech`, which pulls ~12
+entries rather than 73. The instructions then say "decide the shape, call
+`list_workflows(shape=...)`" - one step, no inference. This is the same index
+docs/proposals/catalog-shape-index.md proposes; the token measurement above is
+the argument for doing it before anything else on that list.
+
+Validation: `tests/test_catalog_structure.py` requires every template to carry
+a shape from the vocabulary, the way it now requires a description.
+
+### 3. Cost is the third question and nothing names it either
+
+The instructions say "say what it will cost before spending it". The agent has
+nothing to say it from except a guide (`recipes`) written per model. A
+template that runs MiniMax H3 for 45 seconds of video costs a different order
+of magnitude from `text-to-image`, and nothing in the listing distinguishes
+them.
+
+**Proposal.** A `cost` field on each template: `{"vram_gb": 24, "minutes":
+3}` as a *measured* figure on a named device, filled in by the maintainer
+from a real run and stamped with the device it was measured on. Templates
+without one show `null`; the UI and the agent treat `null` as "unknown - run
+`get_memory` and say so". docs/proposals/catalog-shape-index.md calls this the
+runtime index; the field is the minimum that makes "say what it will cost"
+answerable from the listing.
+
+### 4. Guides are read from the wrong machine
+
+`list_guides`/`get_guide` read the MCP *client's* install (`dw/docs/` or the
+repo's `docs/`). Their tool descriptions say "the documentation shipped with
+this engine", which is not what happens: an MCP at one version against a
+remote `dw.serve` at another confidently indexes sections (`Speech
+Generation`, `templates/`) the server does not have. This is also what forced
+the `build_dist.sh` copy step, the `.gitignore` entry, the stale-copy trap
+and the CI-breaking `httpx` import in the build script (all findings in the
+PR 41 review).
+
+**Proposal.** `GET /api/guides` and `GET /api/guides/{name}?section=` on the
+server, reading `docs/` beside it with the same checkout-else-packaged
+resolution `default_ui_dir` already does for the SPA. `dw_mcp/guides.py`
+becomes a proxy like every other handler; the `GUIDES` table (names, files,
+summaries) moves to the server; the guides an agent reads are then the guides
+for the engine it is about to drive. The one thing lost is answering
+`list_guides` against a server that is down, which the review noted is not a
+real use.
+
+### 5. Descriptions drift; a check can hold them
+
+Nothing checks that a description's argument set (`"prompt", "num_frames" ...`)
+names variables the workflow actually declares, or that the shape a
+description implies matches the `shape` field. Once `summary`, `shape` and
+`cost` exist, `tests/test_catalog_structure.py` can hold each to its
+workflow: every variable named in backticks in a description exists; every
+`prompt:` reference resolves (already done); a `video-with-speech` template
+has a step producing audio.
+
+## What not to do
+
+- **Do not add per-tool examples or longer tool descriptions.** The 54
+  descriptions average 280 characters and the instructions carry the protocol.
+  Examples belong in the guides, one section each, fetched on demand.
+- **Do not put variable defaults in the listing.** `workflow_details` leaves
+  them out on purpose (an order of magnitude more payload); `get_workflow` has
+  them.
+- **Do not summarise the guides into the instructions.** The index is the
+  summary; the instructions should keep pointing at it rather than restating
+  it.
+- **Do not make the shape vocabulary open.** Its whole value is that an agent
+  can enumerate it; a free string is a description with a shorter name.
+
+## Order
+
+1. `summary` field and a listing that carries it (one server change, one
+   schema field, a sweep over 73 descriptions to write the first sentence).
+2. `shape` field, vocabulary in the schema, `list_workflows(shape=)`,
+   catalog-structure test.
+3. Server-side guides; `dw_mcp/guides.py` becomes a proxy; the build-script
+   copy step goes away.
+4. `cost` field, measured on the maintainer's devices, `null` elsewhere.
+5. Description-to-workflow consistency checks.
+
+Each is independent of the next and each shrinks or de-risks what the agent
+reads; 1 and 2 together take the first catalog look from ~11.4k tokens to
+under 3k for a filtered call, with no guesswork left in the shape question.