videowright 0.1.0

package/skill/references/audio/voiceover/providers/elevenlabs.md

@@ -0,0 +1,288 @@
+# ElevenLabs
+
+## When this is loaded
+
+You need to guide the user through ElevenLabs to generate voiceover audio and per-word timing data. This reference covers both the API-key flow (automated) and the portal flow (manual web UI).
+
+This reference also covers Speech-to-Text for the manual voiceover flow (Flow B).
+
+## Mode selection
+
+This question is asked at the start of Flow A (before style intake). Present the user with two options:
+
+> Two ways to generate the voiceover with ElevenLabs:
+>
+> 1. **API key (recommended for repeated use)** -- set up once in `.env`, then the agent generates audio and timings via curl. **Requires a paid ElevenLabs plan** (not available on the free tier). Note: granting the agent API access means it will spend your ElevenLabs credits, which costs real money.
+> 2. **Portal (web UI, works with any plan)** -- the agent walks you through TTS in the ElevenLabs web portal, then STT to extract timings.
+>
+> API key is faster and reusable across projects. Portal needs no setup but takes more clicks per video.
+>
+> If you don't have an account: open https://elevenlabs.io and sign up first.
+
+After the user picks, if they chose **API key**, immediately present the curated voice catalog (see [voiceover.md curated voice catalog](../../voiceover.md#curated-voice-catalog)). Then continue with style intake and script writing. When it is time for audio generation, dispatch into the appropriate sub-flow below.
+
+---
+
+## Flow 1: API Key
+
+### Step 1: Credit / cost warning
+
+Before generating audio, warn the user about costs:
+
+> **Cost notice:** ElevenLabs charges credits for TTS generation. A 60-second voiceover (~900 characters) costs roughly 900-1,000 credits, which is a small fraction of most paid plan quotas.
+>
+> Check your plan's remaining quota at https://elevenlabs.io/app/subscription before generating.
+
+<!-- TODO: Verify current pricing tiers -- ElevenLabs pricing may have changed. The rough estimate above is based on ~1 credit per character for standard voices. -->
+
+### Step 2: Get the API key
+
+Guide the user:
+
+> **Creating your ElevenLabs API key:**
+>
+> 1. Go to https://elevenlabs.io/app/developers/api-keys (sign in if prompted).
+> 2. Click **Create API Key**.
+> 3. Give it a name (e.g., "videowright").
+> 4. **Enable these permissions** on the key before creating it. The key creation UI has toggles for which features the key can access. Enable all of the following:
+>    - **Text to Speech** -- required for generating voiceover audio.
+>    - **Speech to Text** -- required for extracting word-level timing from audio.
+>    - **Sound Effects** -- for upcoming SFX generation features.
+>    - **Music Generation** -- for upcoming background music features.
+>
+>    If you don't see individual permission toggles, create the key with full access -- the default may already include all required permissions.
+> 5. Click **Create** and copy the key.
+
+**Storage rules -- do NOT paste the key into chat:**
+
+> **Important:** Do not paste your API key into this chat -- it would be sent to the LLM provider.
+>
+> Instead:
+> 1. Create a `.env` file at your project root (if it doesn't already exist).
+> 2. Add this line: `ELEVENLABS_API_KEY=your-key-here`
+> 3. Make sure `.env` is in your `.gitignore` (add it if not).
+
+The agent reads the key via `process.env.ELEVENLABS_API_KEY` when running curl commands.
+
+### Step 3: Voice (already selected)
+
+The voice was chosen during approach selection (Flow A step 1). Use this voice ID when constructing the API call below, and write it to the `eleven_labs_voice_id` field when creating `voiceover.ts` in step 8. If no voice was explicitly chosen, default to Asher (`tMvyQtpCVQ0DkixuYm6J`). No action needed here -- proceed to audio generation.
+
+The voice ID lookup table for the curated catalog:
+
+| Voice | ID |
+|---|---|
+| Asher (default) | `tMvyQtpCVQ0DkixuYm6J` |
+| Cecily | `Uc7anshoV8mdBhDnEZEX` |
+| Don | `8IbUB2LiiCZ85IJAHNnZ` |
+| Hanna | `Hh0rE70WfnSFN80K8uJC` |
+
+### Step 4: Generate audio with timestamps
+
+Use the text-to-speech-with-timestamps endpoint. This returns both the audio and per-word timing in a single request.
+
+**Endpoint:** `POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id}/with-timestamps`
+
+The agent reads the voice ID from the `eleven_labs_voice_id` field in `voiceover.ts`. If not set, default to Asher: `tMvyQtpCVQ0DkixuYm6J`.
+
+The agent constructs and runs a curl command like this:
+
+```bash
+# Read the provider script (everything below the --- line)
+SCRIPT_TEXT=$(sed '1,/^---$/d' "videos/<video>/audio/originals/voiceovers/<slug>/provider_script.md")
+
+# Voice ID from eleven_labs_voice_id (default: Asher tMvyQtpCVQ0DkixuYm6J)
+VOICE_ID="<selected voice ID>"
+
+curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/${VOICE_ID}/with-timestamps" \
+  -H "xi-api-key: ${ELEVENLABS_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d "$(jq -n \
+    --arg text "$SCRIPT_TEXT" \
+    --arg model "eleven_multilingual_v2" \
+    '{
+      text: $text,
+      model_id: $model,
+      voice_settings: {
+        stability: 0.5,
+        similarity_boost: 0.75
+      }
+    }'
+  )" \
+  -o "$TMPDIR/elevenlabs_response.json"
+```
+
+<!-- TODO: Verify the exact response shape of the with-timestamps endpoint. The format below is based on known ElevenLabs API behavior -- confirm against current docs. -->
+
+**Processing the response:**
+
+The response JSON contains base64-encoded audio and word-level alignment data. The agent must:
+
+1. **Extract the audio.** The response includes an `audio_base64` field. Decode and save it:
+
+```bash
+jq -r '.audio_base64' "$TMPDIR/elevenlabs_response.json" | base64 --decode > "videos/<video>/audio/originals/voiceovers/<slug>/audio.mp3"
+```
+
+2. **Extract the timing data.** The response includes an `alignment` field with per-character or per-word timing. Transform it into the standard timing JSON format and save:
+
+```bash
+jq '{
+  words: [.alignment.words[] | {word: .word, start: .start, end: .end}]
+}' "$TMPDIR/elevenlabs_response.json" > "videos/<video>/audio/originals/voiceovers/<slug>/timing.json"
+```
+
+If the response uses character-level alignment instead of word-level, aggregate characters into words by grouping on whitespace boundaries and using the start of the first character and end of the last character for each word.
+
+3. **Clean up** the temporary response file.
+
+### API flow output
+
+After a successful API call, the voiceover folder should contain:
+
+```
+audio/originals/voiceovers/<slug>/
+  provider_script.md       # already created in prior step
+  audio.mp3                # decoded from API response
+  timing.json              # extracted from API response
+```
+
+Proceed to the sync algorithm: [../sync_algorithm.md](../sync_algorithm.md).
+
+---
+
+## Flow 2: Portal (Web UI)
+
+The portal flow has two steps: TTS to generate audio, then STT to extract per-word timing.
+
+### Step 1 -- Generate the audio (TTS)
+
+Portal users do **not** use the curated voice catalog -- they pick a voice visually in the ElevenLabs UI below.
+
+Guide the user:
+
+> **Generating voiceover audio with ElevenLabs:**
+>
+> 1. Open https://elevenlabs.io/app and sign in.
+> 2. Navigate to **Text to Speech** in the sidebar.
+> 3. **Important: Select the v2 model in the model dropdown.** Look for **"Eleven Multilingual v2"** (or **"Multilingual v2"**). Do NOT use the default v3 model -- v3 does not honor exact pause timing via `<break>` tags.
+> 4. Select a voice that matches your tone preferences. You can preview voices before generating.
+> 5. Paste the content from `audio/originals/voiceovers/<slug>/provider_script.md` (everything below the horizontal rule) into the text area.
+> 6. Click **Generate**.
+> 7. Listen to the preview. If pauses or delivery need adjustment, update the provider script and regenerate.
+> 8. **Download the audio file.** Click the download button on the generated audio. Save as `audio.mp3`.
+> 9. Place the file in `audio/originals/voiceovers/<slug>/audio.mp3`.
+
+### Step 2 -- Extract timings (STT)
+
+The TTS portal does not export per-word timing data. To get timings, run the generated audio through Speech-to-Text:
+
+> **Extracting word-level timing via Speech-to-Text:**
+>
+> 1. In the ElevenLabs portal, switch to **Speech to Text** in the sidebar.
+> 2. Upload the audio file you just saved (`audio/originals/voiceovers/<slug>/audio.mp3`).
+> 3. Wait for transcription to complete.
+> 4. **Export the result as JSON.** Look for an "Export" or "Download" option and select **JSON** format. **Do not use plain text export** -- plain text does not include per-word timing data.
+> 5. Save the JSON file as `audio/originals/voiceovers/<slug>/timing.json`.
+
+### Portal flow output
+
+After both steps, the voiceover folder should contain:
+
+```
+audio/originals/voiceovers/<slug>/
+  provider_script.md       # already created in prior step
+  audio.mp3                # downloaded from TTS in step 1
+  timing.json              # exported from STT in step 2
+```
+
+Proceed to the sync algorithm: [../sync_algorithm.md](../sync_algorithm.md).
+
+---
+
+## Speech-to-Text (for manual flow / Flow B)
+
+Used when the user provides their own audio and needs per-word timing data. This is the same STT process as portal step 2 above.
+
+### Portal walkthrough: STT transcription
+
+> **Transcribing audio with ElevenLabs Speech-to-Text:**
+>
+> 1. Open https://elevenlabs.io/app and sign in.
+> 2. Navigate to **Speech to Text** in the sidebar.
+> 3. Upload the audio file (mp3 or wav).
+> 4. Wait for transcription to complete.
+> 5. **Export as JSON.** Select the JSON export option -- plain text export does not include word timing data.
+> 6. Save the JSON file in `audio/originals/voiceovers/<slug>/` as `timing.json`.
+
+### Timing JSON format (STT)
+
+ElevenLabs STT output contains word-level timestamps:
+
+```json
+{
+  "words": [
+    {
+      "word": "Welcome",
+      "start": 0.12,
+      "end": 0.58,
+      "confidence": 0.98
+    }
+  ]
+}
+```
+
+Additional fields like `confidence` can be ignored for sync purposes. The sync algorithm uses only `word`, `start`, and `end`.
+
+### STT accuracy notes
+
+- STT may not perfectly transcribe the audio. Minor differences (filler words, slight wording changes) are normal.
+- When the STT transcript differs from the PLAN.md script, use the STT timestamps for timing but the PLAN.md script text for the canonical record.
+- Flag significant discrepancies to the user -- they may want to update PLAN.md to match what was actually spoken.
+
+---
+
+## Timing JSON format (canonical)
+
+Both flows produce the same timing JSON format at `audio/originals/voiceovers/<slug>/timing.json`:
+
+```json
+{
+  "words": [
+    {
+      "word": "Welcome",
+      "start": 0.0,
+      "end": 0.45
+    },
+    {
+      "word": "to",
+      "start": 0.47,
+      "end": 0.55
+    }
+  ]
+}
+```
+
+Fields:
+- `word`: the spoken word
+- `start`: seconds from audio start when the word begins
+- `end`: seconds from audio start when the word ends
+
+The exact JSON structure may vary by ElevenLabs endpoint or export version. Adapt by looking for word-level entries with start/end timestamps. The sync algorithm needs: word text, start time, end time.
+
+## Known limitations
+
+- **`<break>` tags cannot appear at the very start of audio.** ElevenLabs does not support a `<break time="Ns" />` tag as the first element in the provider script. The TTS engine requires spoken text before the first break. If the video needs an initial silent pause before narration begins, that must be handled separately (e.g., by adding a leading silent segment in the timeline). A proper initial-pause feature is planned but not yet available.
+
+## Troubleshooting
+
+| Issue | Resolution |
+|---|---|
+| API returns 401 | Check that `ELEVENLABS_API_KEY` is set correctly in `.env` and the key is valid. |
+| API returns 429 | Rate limited. Wait a moment and retry, or check your plan's quota. |
+| Audio quality is poor | Re-generate with a different voice or adjusted settings. Try adjusting `stability` (higher = more consistent) and `similarity_boost` in the API call. |
+| Pauses are too short/long | Adjust the `provider_script.md` pause annotations and regenerate. For `<break>` tags, adjust the `time` value. |
+| TTS mispronounces a word | Add phonetic spelling to the provider script and regenerate. |
+| STT misses words or adds extra words | Use the best-match approach in the sync algorithm. Flag mismatches to the user. |
+| Portal does not show v2 model option | The model may be listed as "Eleven Multilingual v2" or similar. Check the model dropdown carefully. If v2 is not available, the `<break>` tags for exact pause timing will not work reliably in v3 -- note this to the user. |
+| STT JSON export option not visible | Look for a download/export button after transcription completes. The option may be labeled "Export", "Download", or appear as a dropdown with format choices. Select JSON specifically. |

package/skill/references/audio/voiceover/providers/manual.md

@@ -0,0 +1,100 @@
+# Manual Voiceover
+
+## When this is loaded
+
+The user has their own audio file and wants to add it as a voiceover. This is Flow B from the main voiceover reference.
+
+## Overview
+
+The manual flow takes a user-provided audio file and generates the transcript and timing data needed for sync. The user provides the audio; the agent guides them through ElevenLabs Speech-to-Text to get per-word timing, then runs the sync algorithm to produce a `Timing` object.
+
+## Step 1: Get the audio file
+
+Ask the user for the audio file. Two options:
+
+1. **File path.** The user provides a path to an existing file on disk. Copy or move it into the voiceover folder.
+2. **Drop-in.** Create the voiceover folder and ask the user to place the file there.
+
+```
+audio/originals/voiceovers/<slug>/
+  audio.mp3    # or .wav
+```
+
+Slug naming:
+- Ask the user for a slug, or suggest one based on context: `v1`, `narrator`, `take-1`.
+- Create the directory: `videos/<video>/audio/originals/voiceovers/<slug>/`.
+
+### Audio format requirements
+
+- MP3 or WAV are the standard formats. Both work with ElevenLabs and ffmpeg.
+- If the user provides a different format (M4A, OGG, FLAC), note that ffmpeg can handle most formats. ElevenLabs STT also accepts most common formats.
+- No specific sample rate or bitrate requirements -- ElevenLabs and ffmpeg handle resampling.
+
+## Step 2: Generate transcript and timing
+
+The user needs per-word timing data for the sync algorithm. Guide them through ElevenLabs Speech-to-Text:
+
+> **To generate the timing data, we need to transcribe your audio with per-word timestamps.**
+>
+> Follow these steps:
+>
+> 1. Open https://elevenlabs.io/app and sign in (or create a free account).
+> 2. Navigate to **Speech to Text** in the sidebar.
+> 3. Upload your audio file (`<filename>`).
+> 4. Wait for transcription to complete.
+> 5. **Export as JSON.** Select the JSON export option -- **do not use plain text export**, which does not include per-word timing data.
+> 6. Save the JSON file as `timing.json` in `audio/originals/voiceovers/<slug>/`.
+
+See [elevenlabs.md](elevenlabs.md) for the detailed STT portal walkthrough and expected JSON format.
+
+## Step 3: Verify the transcript
+
+After the user downloads the timing JSON:
+
+1. Read `timing.json` and extract the full transcript text.
+2. Present it to the user for review: "Here's what ElevenLabs heard. Does this match your recording?"
+3. If the transcript is significantly wrong (wrong words, missing sections), the timing data may be unreliable. Ask the user to:
+   - Re-record with clearer audio, or
+   - Manually correct the timing JSON (rare -- usually re-recording is easier).
+4. If the transcript has minor differences (filler words, slight variations), proceed -- the sync algorithm handles this.
+
+## Step 4: Update PLAN.md script
+
+If the video does not already have a script in PLAN.md:
+
+1. Use the STT transcript as the basis for the script.
+2. Divide it by segment, matching content to segment ids using the timeline's segment outline and each segment's `notes`/`voiceover` hints.
+3. Write the script section into PLAN.md.
+4. Update each segment's `voiceover` field to match.
+
+If the video already has a script in PLAN.md:
+
+1. Compare the STT transcript with the existing script.
+2. Flag significant differences.
+3. The existing PLAN.md script is the canonical version -- use it for segment boundary alignment in the sync algorithm, but use the STT timestamps for timing.
+
+## Step 5: Proceed to sync
+
+With the audio file and `timing.json` in place, proceed to the sync algorithm: [../sync_algorithm.md](../sync_algorithm.md).
+
+The sync algorithm uses the provider timing JSON to compute a `Timing` object. The rest of the flow (default voiceover question, animation sync, writing `voiceover.ts`) is identical to the AI-generated flow.
+
+## Expected folder state after manual flow
+
+```
+audio/originals/voiceovers/<slug>/
+  voiceover.ts             # created at the end of the flow
+  audio.mp3                # user-provided audio
+  timing.json              # from ElevenLabs STT
+```
+
+Note: there is no `provider_script.md` in the manual flow since the user recorded the audio themselves.
+
+## Edge cases
+
+| Situation | Behavior |
+|---|---|
+| Audio has background music or noise | STT accuracy may suffer. Warn the user that timing data could be less precise. Suggest clean audio for best results. |
+| Audio has multiple speakers | Videowright supports only single-narrator voiceovers. Ask the user to provide a single-speaker recording. |
+| Audio is very short (< 5 seconds) | Proceed normally, but the resulting timing may be too sparse for meaningful sync. |
+| User does not want to use ElevenLabs STT | There is no alternative STT integration in V1. The user would need to manually create `timing.json` with per-word timestamps, which is impractical. Recommend ElevenLabs STT (free tier available). |

package/skill/references/audio/voiceover/script_writing.md

@@ -0,0 +1,100 @@
+# Script Writing
+
+## When this is loaded
+
+You are writing or integrating a voiceover script into the video's PLAN.md. This happens before generating the provider script.
+
+## Where the script lives
+
+The canonical script lives in the video's `PLAN.md` under a `## Script` section, divided by segment. Each segment gets a subsection with its VO text:
+
+```markdown
+## Script
+
+### intro
+Welcome to Acme Product. Today we'll walk through the three features that set us apart.
+
+### feature-cards
+First up: real-time collaboration. Your team can edit simultaneously, with changes syncing instantly across devices.
+
+[pause for animation]
+
+Next, the analytics dashboard. Track engagement, conversion, and retention in one view.
+
+[pause for animation]
+
+Finally, integrations. Connect with the tools you already use -- Slack, GitHub, Jira, and more.
+
+### outro
+Ready to get started? Visit acme.com for a free trial. Thanks for watching.
+```
+
+### Rules for the script section
+
+- One subsection per segment, using the segment id as the heading.
+- Segment ids must match the ids in the timeline.
+- Use `[pause for animation]` markers where the script expects a visual beat to play before the narration continues. These are hints for the agent when computing multi-advance timing.
+- Segments with no voiceover content are omitted from the script section.
+
+## Writing a new script
+
+When the user wants a script written for them:
+
+1. **Read the video's PLAN.md.** Understand the purpose, audience, segment outline, and any creative direction.
+2. **Read each segment's code** (or at minimum its `notes` and `voiceover` fields) to understand what visuals are on screen.
+3. **Draft the script** section-by-section, following the segment outline order.
+
+### Writing guidelines
+
+- **Match visuals to narration.** The script should describe or complement what is on screen, not fight it. If a segment shows a data chart, the narration should reference the data.
+- **Pacing: ~150 WPM.** A 30-word section takes about 12 seconds to speak. A 100-word section takes about 40 seconds. Use this to estimate segment durations. Err on the side of shorter -- spoken pace with pauses is slower than reading pace.
+- **Use natural language.** Avoid jargon unless the audience expects it. Write like you are speaking to someone, not writing a whitepaper.
+- **One idea per segment.** Each segment should have a single narrative focus. If a segment's script covers multiple unrelated ideas, consider splitting the segment.
+- **Mark pauses explicitly.** Use `[pause for animation]` at points where the visual needs time to play without narration. These become multi-advance beats in the Timing.
+- **End with a call to action or wrap-up.** The final segment's script should give the video a sense of closure.
+
+## Integrating a user-provided script
+
+When the user provides their own script (pasted or from a document):
+
+1. **Chunk by segment.** Read the timeline's segment outline and divide the script into sections that match each segment's purpose. Use the segment's `notes` and `voiceover` hint fields as alignment cues.
+2. **Write into PLAN.md** using the subsection format above.
+3. **Add pause markers** where the script transitions between ideas within a segment, especially where an animation beat is expected.
+
+If the script does not divide cleanly by segment:
+
+- Propose a mapping and ask the user to confirm.
+- If the script implies a different segment structure, suggest adding or removing segments to match.
+
+## Sanity checks
+
+Run these checks before proceeding to the provider script:
+
+### Spelling and grammar
+
+- Read the script aloud (mentally) and flag anything that sounds awkward when spoken.
+- Flag common TTS pitfalls: abbreviations that should be spelled out (e.g., "API" should stay as "A-P-I" or "API" depending on desired pronunciation), numbers that might be misread, technical terms with unusual pronunciation.
+
+### Script-video alignment
+
+- For each segment, verify the script references content that is actually on screen.
+- Flag cases where:
+  - The script mentions a feature or visual that does not appear in the segment.
+  - A segment has prominent visuals that the script ignores.
+  - The script order does not match the timeline order.
+
+When a misalignment is found, present it to the user:
+
+> The script for segment "feature-cards" mentions "pricing comparison" but that segment shows collaboration features. Would you like to: (1) update the script to match the video, (2) update the video to match the script, or (3) keep it as-is?
+
+### Duration estimate
+
+- Sum up the word count per segment and estimate total duration at ~150 WPM.
+- Flag if any segment's script seems much longer or shorter than expected given the segment's visual complexity.
+- Present the estimate: "The full script is ~320 words, which should take about 2 minutes 8 seconds to narrate at a moderate pace."
+
+## After the script is confirmed
+
+1. Update each segment's `voiceover` field to match its PLAN.md script section.
+2. Run `npx videowright script --write` to generate `voiceover_script/script.md`.
+3. Proceed to [provider_script.md](provider_script.md) for Flow A, or directly to sync for Flow B.

package/skill/references/audio/voiceover/style_intake.md

@@ -0,0 +1,56 @@
+# Style Intake
+
+## When this is loaded
+
+You are preparing to generate a voiceover and need to understand the user's tone and pacing preferences before creating the provider script.
+
+## Purpose
+
+Style intake captures preferences that the agent **directly uses** when writing the provider script: tone, emotional arc, and reference style. Voice selection (which voice to use, gender, accent, speaking rate) is handled separately -- in the ElevenLabs provider walkthrough for API-mode users, or visually in the portal UI for portal-mode users.
+
+## Questions to ask
+
+Ask these questions before generating the provider script. Group them into a single message -- do not ask one at a time. Skip any question whose answer is already clear from the user's input.
+
+1. **Tone.** What overall tone should the narration have?
+   - Examples: conversational, professional, enthusiastic, calm, authoritative, playful, serious, warm
+   - If the user is unsure, default to "conversational and warm" -- it works for most explainer videos.
+
+2. **Emotional arc.** Should the tone shift across the video? For example:
+   - Start serious, build to excited
+   - Maintain a steady calm throughout
+   - Start warm, shift to urgent for the call to action
+   - If the user has no preference, a steady tone is fine.
+
+3. **Reference** (optional). Is there a narrator or video style they want to emulate?
+   - "Like a TED talk", "like a product launch keynote", "like a podcast host"
+
+## How answers map to provider script
+
+The agent targets ElevenLabs v2, which does not have v3-style emotion tags (`[excited]`, `[calm]`, etc.). Instead, tone is conveyed through punctuation, sentence structure, and pacing cues:
+
+| Preference | Provider script effect |
+|---|---|
+| Tone: enthusiastic | Exclamation marks, short punchy sentences, emphatic word choice |
+| Tone: calm/serious | Longer sentences, measured pacing, more pauses between phrases |
+| Tone: warm | Natural conversational phrasing -- the default for most v2 voices |
+| Emotional arc | Vary sentence structure and punctuation across sections of the script |
+
+See [provider_script.md](provider_script.md) for the full v2 writing toolkit.
+
+## What NOT to ask
+
+Voice attributes (gender, accent, age, speaking rate) are **not** part of style intake. They are chosen at voice-selection time:
+
+- **API-mode users** pick from a curated voice catalog during the ElevenLabs provider walkthrough (see [providers/elevenlabs.md](providers/elevenlabs.md)).
+- **Portal-mode users** select a voice visually in the ElevenLabs web UI.
+
+If the user volunteers voice preferences during style intake, acknowledge them and note that they will be applied during voice selection.
+
+## When to skip style intake
+
+- The user has explicitly described the voice style they want in their initial request.
+- The user is iterating on an existing voiceover and the style is already established.
+- The user is using the manual flow (Flow B) -- they already have the audio.
+
+In these cases, proceed directly to the next step without asking style questions.