dkackman · Sep 7, 2026 · Sep 6, 2026 · Sep 6, 2026 · Sep 6, 2026 · Sep 6, 2026
diff --git 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/CLAUDE.md b/CLAUDE.md
@@ -12,16 +12,16 @@ 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/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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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/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,9 +188,19 @@ 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_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_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. 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/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
@@ -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
@@ -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
@@ -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
@@ -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"