Text-to-speech, MCP capability guides, and a two-tree workflow catalog

[dkackman]

Three pieces of work, each building on the last. They started from a design
question about scripted dialogue shorts and ended in a restructured catalog.

1. generate_speech

A HuggingFace text-to-speech task (dw/tasks/speech_generation.py),
modelled on text_generation and defaulting to suno/bark-small — its voice
presets give distinct speakers, which is what two characters in a scene need.

The role it 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. templates/minimax/voice-timbre-reference.json
shows the clip going in as <Audio 1> via from_previous_result.

It returns a new 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 differs, so a declared 44100 against a 24 kHz model plays the
speech fast and low without ever failing. normalize_audio and
media_arguments now read .audio/.sample_rate off whatever they are handed,
the way the rest of the audio plumbing already did.

Verified beyond the mocks: bark-small on MPS wrote a 24000 Hz, 3.59 s wav with
nothing declared in the result, and voice_preset was confirmed to reach the
processor as history_prompt against the real library.

2. MCP capability guides

list_guides / get_guide (dw_mcp/guides.py) serve nine
curated docs, read by path so the no-dw.*-import boundary holds, from
dw/docs/ when installed and the repo's docs/ from a checkout.

The gap they close: a request names a subject ("a lego movie trailer set in
the marvel universe") while the catalog is written in shapes. The index is
~830 tokens — small enough to read every session — and a guide can be fetched
one section at a time, 3.3k chars against 51.7k for the whole of TASKS.md. The
server instructions now say to decide the deliverable's shape first.

3. Two-tree workflow catalog

121 workflows → 73: 64 templates, 9 model configs.

templates/ teaches a pattern, models/ records what makes a checkpoint fit
real hardware and names the template it configures via a new configures
field. Previously nothing in a catalog entry distinguished the two, so the
eight files that answer a multi-shot video request were indistinguishable from
a hundred checkpoint iterations.

• archive/ (a pure model gallery) and gyre/ (a test project's production
  history) are gone; qr_code, sdxl and txt2img2vid graduated
• minimax/ and ltx2/ are kept intact — each file demonstrates a
  conditioning mode or mechanism nothing else does
• six checkpoint variations collapsed into argument sets in their template's
  description

Backward compatibility is deliberately not maintained: run-directory identity
changes with the path, so existing outputs are orphaned. What replaces it is
stricter — every reference in the repo resolves: 66 markdown links (plus 75
whose text still named the old filename), 6 workflow→workflow paths, type and
constant references, and the 18 prompt: references that nothing checked
before this branch added a guard for them.

Workflow ids are preserved (70 of them) so the step cache survives, with one
approved exception. The duplicate sd35 and test_job ids, which collided in
the step cache, are resolved by emptying archive/.

Notes

The design spec's original premise — that most of the catalog was redundant —
was wrong, and is corrected in d5693bf after reading all 121 workflows.
The redundancy was concentrated in archive/. The inventory in
docs/superpowers/plans/2026-09-06-catalog-inventory.md records a verdict for
every file.

Tests: 2544 passed, 5 skipped.

🤖 Generated with Claude Code