@slatesvideo/shared 0.6.4 → 0.6.6

package/skills/slates-prompting-inworld-tts.md

@@ -1,166 +1,174 @@
----
-name: slates-prompting-inworld-tts
-description: How to use Inworld Realtime TTS-2, the VOICE seat. Read before calling slates_generate_audio with model inworld-tts-2. Speech in a SPECIFIC voice, billed per character - the prompt is the words spoken, verbatim, max 2000. Covers the identity-versus-acoustics rule (what a reference clip does and does not carry), how to write a line so it is performed rather than read, when to reach for seed-audio instead, and the voice-consent rule.
----
-
-# Inworld Realtime TTS-2 — the voice seat
-
-<!-- @card:start -->
-<!-- slates-only -->
-<!-- MACHINE-READ. Everything between the @card markers is extracted by
-     src/prompts/craft-cards.ts and returned on every cost estimate for this
-     model, so it is the ONE piece of positive craft guidance the agent cannot
-     skip. Keep it under 2,400 characters (the build fails above that) and keep
-     the rationale and the worked examples in the body below. -->
-<!-- /slates-only -->
-**Card — Inworld TTS-2.** Speech in a SPECIFIC voice. The prompt is the words spoken, verbatim — not a description of them. Max 2000 characters, and the length of the text is the bill.
-
-**IDENTITY, NOT ACOUSTICS — the rule that decides whether cloning works**
-A reference carries WHO is speaking: timbre, pitch, accent, age, vowel shape. It does NOT carry WHERE they are — room tone, distance, phone EQ, reverb and mic character are *acoustics*, and this model reproduces the identity while discarding the room. So:
-1. **A noisy reference does not give a noisy read — it gives a WORSE identity.** Music, a second speaker or heavy reverb corrupt what is being extracted. Feed it the cleanest 5–15 seconds of one person you have.
-2. **You cannot get "on a payphone" by cloning a payphone recording.** Acoustics come from the MIX, or from `seed-audio` which renders a room.
-
-**DIRECTION GOES IN SQUARE BRACKETS. PARENTHESES ARE SPOKEN ALOUD.** `[whispering] I hope nobody notices` is whispered; `(quietly) I hope nobody notices` says the word "quietly" out loud. Verified by ear — the easiest way to ruin a take.
-
-- **Plain English works inside them** — it is natural-language steering, not a fixed vocabulary: `[very quiet]`, `[whisper in a hushed style]`, `[very slow]`, `[say excitedly]`. Non-verbals are their own tags: `[laugh]`, `[sigh]`, `[breathe]`, `[clear throat]`.
-- **A tag it does not recognise is still consumed, and still changes the read.** Never spoken, never an error — so a mistyped tag fails SILENTLY and only listening catches it.
-- **Tags persist across sentences** until changed; `[reset]` returns to normal.
-- **Punctuation is the timing.** `Wait. Stop.` differs from `Wait, stop.`
-- **One line, one take.** Split a paragraph so a bad clause costs one re-roll.
-- **Spell numbers and titles aloud:** `twenty twenty-six`, `Doctor Reyes`.
-
-**Route elsewhere when:** the scene needs dialogue mixed with effects and room tone in one pass (`seed-audio`), or it is a single non-speech sound (`eleven-sfx`). This surface makes ONE voice saying ONE thing, cleanly.
-
-**Hard constraints:** no duration parameter — length falls out of the text. Max 2000 characters per take. Every generation needs a voice; a voice is a field on a CHARACTER, not a per-generation pick.
-<!-- @card:end -->
-
-<!-- @banned:start -->
-<!-- slates-only -->
-<!-- MACHINE-READ. Every `backticked` token between the @banned markers is
-     extracted by src/prompts/banned-tokens.ts and returned on this model's cost
-     estimate, and every submitted prompt is matched against it. Keep entries
-     backticked and prose outside the backticks. -->
-<!-- /slates-only -->
-**Never use** — the prompt on this surface is SPOKEN ALOUD, so anything that describes the audio instead of being the audio gets read out as words:
-
-- `SFX`, `Ambient noise`, `Background music` as labels — this model speaks; it does not render a scene. Use `seed-audio` for those.
-- shot language: `wide shot`, `slow push in`, `warm tungsten` — video-prompt words, and here they would literally be said aloud
-- `voiceover`, `narrator says`, `he says` as stage directions wrapping the line — write only the words that should come out of the speaker
-<!-- @banned:end -->
-
-## Why the prompt is not a prompt
-
-On every other surface in Slates the prompt DESCRIBES what you want and the model interprets it. Here the prompt IS the deliverable: each character is spoken aloud and each character is billed. `a gravelly man says he is tired` produces a voice saying the words "a gravelly man says he is tired".
-
-That also means the two numbers a user cares about are the same number. The text length sets the price (in 250-character buckets) and sets the length of the audio. There is nothing to choose and nothing to reconcile.
-
-## Steering the delivery
-
-`VERIFIED BY EAR, 2026-09-05.` Every claim in this section was listened to, not
-inferred — an earlier draft of this skill documented tag forms that had only been
-probed for an HTTP 200, which proves the request was accepted and nothing about
-whether it was obeyed.
-
-**Square brackets are consumed. Parentheses are read aloud.** That is the whole
-rule, and getting it wrong is not a subtle degradation — the audience hears a
-narrator say the word "quietly" in the middle of your line.
-
-| Written | What comes out |
-|---|---|
-| `[whispering] I really hope nobody notices that.` | whispered, tag not spoken ✅ |
-| `[very quiet] I really hope nobody notices that.` | very quiet, tag not spoken ✅ |
-| `[whisper in a hushed style] …` | hushed, tag not spoken ✅ |
-| `[very slow] …` | slowed right down, tag not spoken ✅ |
-| `[laugh] …` | an actual laugh, then the line ✅ |
-| `(quietly, under his breath) …` | 🚨 **the words "quietly, under his breath" are SPOKEN** |
-
-**Plain English works — it is natural-language steering, not a fixed vocabulary.**
-Both the documented phrasings (`[whisper in a hushed style]`) and ordinary adverbs
-(`[whispering]`) were obeyed. Write the direction the way you would say it to an
-actor.
-
-The eight dimensions the model steers on, with a working example of each:
-
-| Dimension | Example |
-|---|---|
-| Emotion | `[say excitedly]`, `[sound sad]`, `[sound terrified]` |
-| Articulation | `[say with force]`, `[articulate clearly]` |
-| Intonation | `[say with a rising pitch]` |
-| Volume | `[very quiet]`, `[very loud]` |
-| Pitch | `[say in a low tone]` |
-| Range | `[say playfully]`, `[say with no pitch variation]` |
-| Speed | `[very fast]`, `[very slow]` |
-| Vocal style | `[whisper in a hushed style]`, `[give a nasal quality]` |
-
-Non-verbals sit inline where they happen: `[laugh]`, `[sigh]`, `[cough]`,
-`[breathe]`, `[yawn]`, `[clear throat]`.
-
-### Three rules that are not obvious
-
-1. 🚨 **A tag it does not recognise is still consumed, and still changes the read.**
-   `[zzzqqq]` is not spoken and does not error — it produces a different, arbitrary
-   delivery. So a typo in a tag is SILENT: there is no rejection, no warning, and no
-   way to catch it except listening to the take. Treat an unexpected performance as
-   a possible misspelled tag before you blame the voice.
-2. **Tags persist across sentences.** A `[very slow]` at the top governs everything
-   after it until something changes it. Use `[reset]` to go back to normal rather
-   than assuming the next sentence starts clean.
-3. **Do not stack opposing directions.** `[whisper in a hushed style]` together with
-   `[very loud]` produces unpredictable results — the model is resolving a
-   contradiction, and which side wins is not something you can rely on.
-4. **Tags COUNT toward the billed characters**, even though they are never spoken.
-   They are part of the text sent to the vendor, so the vendor charges for them and
-   so do we — billing what was actually sent is the only honest basis. It rarely
-   matters (a 13-character tag inside a 250-character bucket), but a line sitting
-   just under a bucket boundary can be pushed into the next one by a long
-   direction. Prefer `[very slow]` over `[say this one very slowly please]`.
-
-## Identity versus acoustics, at length
-
-This is the distinction that decides whether the feature feels good, and it is worth being precise about because the failure is quiet — you get a usable clip that is subtly not the person.
-
-**What a reference clip transfers:** vocal timbre, pitch range, accent and regional vowels, apparent age, speech rate tendencies, and the particular rasp or breathiness of the source speaker.
-
-**What it does not transfer:** the room, the microphone, the codec, the distance from the mic, any processing on the source, and any other sound present in it.
-
-So the ideal reference is boring: one person, close to a microphone, no music, no second speaker, no heavy reverb, five to fifteen seconds, speaking normally rather than performing. A phone voice memo in a quiet room beats a beautifully produced clip with a music bed underneath it.
-
-**Two failure modes, both common:**
-
-- *"I cloned my podcast intro and it doesn't sound like me."* The intro had music under it. The model averaged the music into the identity. Re-clone from a clean stretch.
-- *"I want the line to sound like it's coming through a car radio."* Clone the clean voice, then EQ and process the returned clip on the timeline. A radio-sounding reference makes a worse voice, not a radio effect.
-
-## Consent
-
-Cloning a real person's voice needs that person's explicit, documented permission, scoped to what you are making. Clone from original human recordings only — never from another model's output. This is the same gate the real-face route applies to likeness, and it applies here for the same reason.
-
-## Worked examples
-
-**A line with a direction**
-
-```
-[very quiet] I heard what you said in there. I'm not going to pretend I didn't.
-```
-
-**A line that needs its numbers spoken**
-
-```
-The vote was three hundred and twelve to eighty-nine. It carried at four minutes past midnight.
-```
-
-**A paragraph, split into three takes** — so one bad clause costs one re-roll:
-
-```
-1. You keep asking me why I stayed.
-2. It wasn't loyalty. It wasn't even fear, not by the end.
-3. [very slow] It was that I couldn't picture the version of me that left.
-```
-
-**What NOT to send**
-
-```
-(gravelly, tired) a tired old man narrates the opening of the film, wide shot, warm tungsten
-```
-
-Every word of that is spoken aloud — **including the parenthetical**, which is the
-trap: it looks like a stage direction and is treated as dialogue. Describe the voice when you are BUILDING one (the character's voice bench takes a description); once the voice exists, send only the words.
+---
+name: slates-prompting-inworld-tts
+description: How to use Inworld Realtime TTS-2, the VOICE seat. Read before calling slates_generate_audio with model inworld-tts-2. Speech in a SPECIFIC voice, billed per character - the prompt is the words spoken, verbatim. Covers the identity-versus-acoustics rule (what a reference clip does and does not carry), how to write a line so it is performed rather than read, when to reach for seed-audio instead, and the voice-consent rule.
+---
+
+# Inworld Realtime TTS-2 — the voice seat
+
+<!-- @card:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Everything between the @card markers is extracted by
+     src/prompts/craft-cards.ts and returned on every cost estimate for this
+     model, so it is the ONE piece of positive craft guidance the agent cannot
+     skip. Keep it under 2,400 characters (the build fails above that) and keep
+     the rationale and the worked examples in the body below. -->
+<!-- /slates-only -->
+**Card — Inworld TTS-2.** Speech in a SPECIFIC voice. The prompt is the words spoken, verbatim — not a description of them. Text length determines the bill.
+
+**IDENTITY, NOT ACOUSTICS — the rule that decides whether cloning works**
+A reference carries WHO is speaking: timbre, pitch, accent, age, vowel shape. It does NOT carry WHERE they are — room tone, distance, phone EQ, reverb and mic character are *acoustics*, and this model reproduces the identity while discarding the room. So:
+1. **A noisy reference does not give a noisy read — it gives a WORSE identity.** Music, a second speaker or heavy reverb corrupt what is being extracted. Use a clean single-speaker recording.
+2. **You cannot get "on a payphone" by cloning a payphone recording.** Acoustics come from the MIX, or from `seed-audio` which renders a room.
+
+**DIRECTION GOES IN SQUARE BRACKETS. PARENTHESES ARE SPOKEN ALOUD.** `[whispering] I hope nobody notices` is whispered; `(quietly) I hope nobody notices` says the word "quietly" out loud. Verified by ear — the easiest way to ruin a take.
+
+- **Plain English works inside them** — it is natural-language steering, not a fixed vocabulary: `[very quiet]`, `[whisper in a hushed style]`, `[very slow]`, `[say excitedly]`. Non-verbals are their own tags: `[laugh]`, `[sigh]`, `[breathe]`, `[clear throat]`.
+- **A tag it does not recognise is still consumed, and still changes the read.** Never spoken, never an error — so a mistyped tag fails SILENTLY and only listening catches it.
+- **Tags persist across sentences** until changed; `[reset]` returns to normal.
+- **Punctuation is the timing.** `Wait. Stop.` differs from `Wait, stop.`
+- **One line, one take.** Split a paragraph so a bad clause costs one re-roll.
+- **Spell numbers and titles aloud:** `twenty twenty-six`, `Doctor Reyes`.
+
+**Route elsewhere when:** the scene needs dialogue mixed with effects and room tone in one pass (`seed-audio`), or it is a single non-speech sound (`eleven-sfx`). This surface makes ONE voice saying ONE thing, cleanly.
+
+**Hard constraints:** no duration parameter — length falls out of the text. Exactly one voice source: a preset `voiceId` from `slates_list_voices`, a clip as `voiceReferenceAssetId` (a character's voice clip to speak AS the character, or any clean clip of one speaker), or `voiceDescription`.
+<!-- @card:end -->
+
+<!-- @banned:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Every `backticked` token between the @banned markers is
+     extracted by src/prompts/banned-tokens.ts and returned on this model's cost
+     estimate, and every submitted prompt is matched against it. Keep entries
+     backticked and prose outside the backticks. -->
+<!-- /slates-only -->
+**Never use** — the prompt on this surface is SPOKEN ALOUD, so anything that describes the audio instead of being the audio gets read out as words:
+
+- `SFX`, `Ambient noise`, `Background music` as labels — this model speaks; it does not render a scene. Use `seed-audio` for those.
+- shot language: `wide shot`, `slow push in`, `warm tungsten` — video-prompt words, and here they would literally be said aloud
+- `voiceover`, `narrator says`, `he says` as stage directions wrapping the line — write only the words that should come out of the speaker
+<!-- @banned:end -->
+
+## Why the prompt is not a prompt
+
+On every other surface in Slates the prompt DESCRIBES what you want and the model interprets it. Here the prompt IS the deliverable: each character is spoken aloud and each character is billed. `a gravelly man says he is tired` produces a voice saying the words "a gravelly man says he is tired".
+
+That also means the two numbers a user cares about are the same number. The text length sets the price (in 250-character buckets) and sets the length of the audio. There is nothing to choose and nothing to reconcile.
+
+## Steering the delivery
+
+`VERIFIED BY EAR, 2026-09-05.` Every claim in this section was listened to, not
+inferred — an earlier draft of this skill documented tag forms that had only been
+probed for an HTTP 200, which proves the request was accepted and nothing about
+whether it was obeyed.
+
+**Square brackets are consumed. Parentheses are read aloud.** That is the whole
+rule, and getting it wrong is not a subtle degradation — the audience hears a
+narrator say the word "quietly" in the middle of your line.
+
+| Written | What comes out |
+|---|---|
+| `[whispering] I really hope nobody notices that.` | whispered, tag not spoken ✅ |
+| `[very quiet] I really hope nobody notices that.` | very quiet, tag not spoken ✅ |
+| `[whisper in a hushed style] …` | hushed, tag not spoken ✅ |
+| `[very slow] …` | slowed right down, tag not spoken ✅ |
+| `[laugh] …` | an actual laugh, then the line ✅ |
+| `(quietly, under his breath) …` | 🚨 **the words "quietly, under his breath" are SPOKEN** |
+
+**Plain English works — it is natural-language steering, not a fixed vocabulary.**
+Both the documented phrasings (`[whisper in a hushed style]`) and ordinary adverbs
+(`[whispering]`) were obeyed. Write the direction the way you would say it to an
+actor.
+
+The eight dimensions the model steers on, with a working example of each:
+
+| Dimension | Example |
+|---|---|
+| Emotion | `[say excitedly]`, `[sound sad]`, `[sound terrified]` |
+| Articulation | `[say with force]`, `[articulate clearly]` |
+| Intonation | `[say with a rising pitch]` |
+| Volume | `[very quiet]`, `[very loud]` |
+| Pitch | `[say in a low tone]` |
+| Range | `[say playfully]`, `[say with no pitch variation]` |
+| Speed | `[very fast]`, `[very slow]` |
+| Vocal style | `[whisper in a hushed style]`, `[give a nasal quality]` |
+
+Non-verbals sit inline where they happen: `[laugh]`, `[sigh]`, `[cough]`,
+`[breathe]`, `[yawn]`, `[clear throat]`.
+
+### Four rules that are not obvious
+
+1. 🚨 **A tag it does not recognise is still consumed, and still changes the read.**
+   `[zzzqqq]` is not spoken and does not error — it produces a different, arbitrary
+   delivery. So a typo in a tag is SILENT: there is no rejection, no warning, and no
+   way to catch it except listening to the take. Treat an unexpected performance as
+   a possible misspelled tag before you blame the voice.
+2. **Tags persist across sentences.** A `[very slow]` at the top governs everything
+   after it until something changes it. Use `[reset]` to go back to normal rather
+   than assuming the next sentence starts clean.
+3. **Do not stack opposing directions.** `[whisper in a hushed style]` together with
+   `[very loud]` produces unpredictable results — the model is resolving a
+   contradiction, and which side wins is not something you can rely on.
+4. **Tags COUNT toward the billed characters**, even though they are never spoken.
+   They are part of the text sent to the vendor, so the vendor charges for them and
+   so do we — billing what was actually sent is the only honest basis. It rarely
+   matters (a 13-character tag inside a 250-character bucket), but a line sitting
+   just under a bucket boundary can be pushed into the next one by a long
+   direction. Prefer `[very slow]` over `[say this one very slowly please]`.
+
+## Identity versus acoustics, at length
+
+This is the distinction that decides whether the feature feels good, and it is worth being precise about because the failure is quiet — you get a usable clip that is subtly not the person.
+
+**What a reference clip transfers:** vocal timbre, pitch range, accent and regional vowels, apparent age, speech rate tendencies, and the particular rasp or breathiness of the source speaker.
+
+**What it does not transfer:** the room, the microphone, the codec, the distance from the mic, any processing on the source, and any other sound present in it.
+
+So the ideal reference is boring: one person, close to a microphone, no music, no second speaker, no heavy reverb, five to fifteen seconds, speaking normally rather than performing. A phone voice memo in a quiet room beats a beautifully produced clip with a music bed underneath it.
+
+**Two failure modes, both common:**
+
+- *"I cloned my podcast intro and it doesn't sound like me."* The intro had music under it. The model averaged the music into the identity. Re-clone from a clean stretch.
+- *"I want the line to sound like it's coming through a car radio."* Clone the clean voice, then EQ and process the returned clip on the timeline. A radio-sounding reference makes a worse voice, not a radio effect.
+
+## Getting the voice onto the call
+
+Exactly one source per call, and none of them requires a character to exist first:
+
+- **A preset:** `slates_list_voices` lists stock voices with gender, age, accent and tags — filter by any of them, or search the descriptions ("gravelly", "narration"). Pass the chosen `voiceId`. Presets clone nothing, so they are the fastest path and avoid the clone-creation rate ceiling.
+- **Speak AS a character:** `voiceReferenceAssetId: <its voiceAssetId>` (the clip on the row `slates_list_characters` returns). The seat clones the clip for that take and discards the vendor voice afterwards, so there is nothing to reconcile — but cloning shares a ceiling of two new voices a minute across every Slates user, so a run of lines in one cloned voice pauses between takes rather than failing. Send each line once; do not re-send one that already came back. Any other clean clip of one speaker works the same way.
+- **A voice with no recording:** `voiceDescription` (7–1000 characters of words). If it will be used again, keep the returned clip on a character with `slates_update_character` (`voiceAssetId`) so later lines clone the same clip instead of designing a new voice each time — a convenience, never a requirement.
+
+## Consent
+
+Cloning a real person's voice needs that person's explicit, documented permission, scoped to what you are making. Clone from original human recordings only — never from another model's output. This is the same gate the real-face route applies to likeness, and it applies here for the same reason.
+
+## Worked examples
+
+**A line with a direction**
+
+```
+[very quiet] I heard what you said in there. I'm not going to pretend I didn't.
+```
+
+**A line that needs its numbers spoken**
+
+```
+The vote was three hundred and twelve to eighty-nine. It carried at four minutes past midnight.
+```
+
+**A paragraph, split into three takes** — so one bad clause costs one re-roll:
+
+```
+1. You keep asking me why I stayed.
+2. It wasn't loyalty. It wasn't even fear, not by the end.
+3. [very slow] It was that I couldn't picture the version of me that left.
+```
+
+**What NOT to send**
+
+```
+(gravelly, tired) a tired old man narrates the opening of the film, wide shot, warm tungsten
+```
+
+Every word of that is spoken aloud — **including the parenthetical**, which is the
+trap: it looks like a stage direction and is treated as dialogue. Describe the voice when you are CHOOSING one (`voiceDescription`, or the desktop's voice picker); the prompt is only ever the words.

package/skills/slates-prompting-lip-sync.md

@@ -28,7 +28,7 @@ description: How to set up lip-sync — Kling-only (dedicated lip-sync and avata
 - `Soft rim light, warm office, gentle confident smile between sentences.`
 - `Cool blue evening light through a window, focused intent expression.` (Or `.` — an empty prompt is fine when you have nothing to add.)
 
-**Hard constraint:** it is Kling-only and always 5 seconds. For a generated PERFORMANCE instead — head movement, gesture, delivery energy, with the dialogue as a native conditioning signal — that is a normal Seedance video generation with the clip attached as a video reference, not a mode of this tool. Real voice or a cloned voice for production; TTS is for scratch.
+**Hard constraint:** it is Kling-only and always 5 seconds. For a generated PERFORMANCE instead — head movement, gesture, delivery energy, with the dialogue as a native conditioning signal — that is a normal Seedance video generation with the clip attached as a video reference, not a mode of this tool. A real recording, or a cloned/cast voice rendered on `inworld-tts-2`, for production; this tool's built-in TTS is for scratch.
 <!-- @card:end -->
 
 <!-- @banned:start -->

package/skills/slates-prompting-nano-banana-2.md

@@ -219,5 +219,5 @@ Everything in this skill applies to the whole Nano Banana family; two variants t
 - **nano-banana-pro** — the hero-frame/typography ceiling (~2× NB2, 4K native). NB2 ≈ 95% of Pro; escalate only when spatial composition, cinematic lighting/skin, fine typography-in-scene, or deep multi-element frames must be perfect. Up to 14 refs — it takes a full subject library in one call.
 
 <!-- slates-only -->
-Routing between them (and vs GPT Image 2 / FLUX / Seedream): `slates-model-selection`.
+Routing between them (and vs GPT Image 2.5 / FLUX / Seedream): `slates-model-selection`.
 <!-- /slates-only -->

package/skills/slates-prompting-seed-audio.md

@@ -48,7 +48,7 @@ ByteDance's one-pass audio scene model, carried on fal (`bytedance/seed-audio-1.
 ## Where it routes
 
 - **Scene audio, room tone, ambience beds, crowd/nature soundscapes** — anything where several sounds share a space. One generation, not three layered ones.
-- **Dialogue and scratch VO.** This is the only speech surface in Slates: the line is performed inside the scene. Lock the read by re-rolling until a take is right, then lip-sync against it with `slates_generate_lip_sync`.
+- **Dialogue and scratch VO inside a scene.** The line is performed in the room, by a voice the scene casts. When WHO is speaking matters — a character's own voice, a clean narrator — that is `inworld-tts-2` instead. Lock the read by re-rolling until a take is right, then lip-sync against it with `slates_generate_lip_sync`.
 - **NOT** a single effect that must land on a known frame — that is `eleven-sfx`, which takes an exact duration.
 - **NOT** music. Slates has no music model; import a track and drop it on an audio track.
 - **AUDIO-ONLY.** It cannot produce images or video.

package/skills/slates-prompting-seedance-2-5.md

@@ -253,9 +253,11 @@ renumbers the citations. Write the prompt against those numbers:
 
 ```
 Marcus (image 1) performs the motion from video 1 in the workshop from image 2,
-speaking the line in audio 1. Preserve his identity, appearance and outfit.
+using the voice timbre from audio 1. Preserve his identity, appearance and outfit.
 ```
 
+🚨 **SAY WHAT AN AUDIO REFERENCE IS FOR.** It can mean music, dialogue, voice, tone or timbre — five roles on one attachment — so an unroled clip falls back to **dialogue**: the model re-transcribes it and speaks ITS words. A real take came back as *"a map called Slates"* for *"an app called Slates"*. Name it as the voice timbre and the clip carries the voice while the prompt carries the words. ByteDance's own sentence: *"Image 1 depicts the protagonist John and uses the voice timbre from Audio 1."* Bind each speaker in a sentence, never by attachment order — position carries nothing.
+
 Frames and reference media stay mutually exclusive, in every combination — the reference endpoint
 has no first/last-frame parameters at all, so this is a shape mismatch rather than a preference.
 

package/skills/slates-prompting-seedance.md

@@ -238,8 +238,10 @@ Cite each by type and index, in the order they were attached — `image 1`, `vid
 
 ```
 Marcus (image 1) performs the motion from video 1, in the workshop from image 2,
-speaking the line in audio 1. Preserve his identity, appearance and outfit.
+using the voice timbre from audio 1. Preserve his identity, appearance and outfit.
 ```
+
+🚨 **SAY WHAT AN AUDIO REFERENCE IS FOR.** It can mean music, dialogue, voice, tone or timbre — five roles on one attachment — so an unroled clip falls back to **dialogue**: the model re-transcribes it and speaks ITS words. A real take came back as *"a map called Slates"* for *"an app called Slates"*. Name it as the voice timbre and the clip carries the voice while the prompt carries the words. ByteDance's own sentence: *"Image 1 depicts the protagonist John and uses the voice timbre from Audio 1."* Bind each speaker in a sentence, never by attachment order — position carries nothing.
 <!-- slates-only -->
 **Attaching a clip is NOT the same as editing it.** "Add as reference" puts it in the composer alongside everything else and wipes nothing; "Edit with AI" makes the clip the canvas and clears the tray for a fresh instruction. Two different jobs, two different menu entries — never infer one from the other.
 

package/skills/slates-ugc-influencer-ad.md

@@ -140,11 +140,13 @@ Eight plates in eight different rooms, all carrying *"shot on a phone at arm's l
 
 ## PHASE 4 — THE PLATES. One per beat.
 
-`slates_generate_image`, model `gpt-image-2`, `quality: high`, vertical `9:16`. **Fire concurrently — 8 slots run at once; serial calls waste the day.** Pass `projectId` so every plate lands in the gallery where you can see it.
+`slates_generate_image`, model `gpt-image-2-5-sunburst`, `quality: max`, vertical `9:16`. **Fire concurrently — 8 slots run at once; serial calls waste the day.** Pass `projectId` so every plate lands in the gallery where you can see it.
 
-**GPT Image 2 is the rail for photoreal people.** Head-to-head against the alternatives it is the one that returns photographic rather than plastic skin. Routing detail: `slates-model-selection`.
+**Why that seat and that rung.** `max` because the 2026-08-24 photoreal result was measured at GPT Image 2's `high`, which is `max` here — the ladder was renamed, not repriced. **Sunburst** because these plates are finals and OpenAI routes quality to Sunburst: Flare's quality is only *comparable to* GPT Image 2, while Sunburst is documented higher. Same price, so the only cost is latency, and you are firing eight in parallel anyway. Use **Flare** while you are still exploring wardrobe, room or framing, then re-fire the chosen direction on Sunburst. ⚠️ Reasoned from OpenAI's positioning, not measured — if you A/B one plate, write the answer into `slates-prompting-gpt-image-2-5`.
 
-### 🚨 GPT Image 2 routes references through its EDIT endpoint
+**GPT Image is the rail for photoreal people.** Head-to-head against the alternatives it is the one that returns photographic rather than plastic skin. Routing detail: `slates-model-selection`.
+
+### 🚨 GPT Image 2.5 routes references through its EDIT endpoint
 
 Two consequences, both of which waste a generation:
 

package/skills/slates-vision-feedback-loop.md

@@ -58,9 +58,9 @@ This is a **cost** rule as much as a craft rule: a 1080p/10s premium video gener
 ### Per-model accents — check the one you actually used
 
 - **Nano Banana Pro** (`nano-banana-pro`) — ruler-straight symmetry, everything parallel and square, flat even light, pretty but staged/stock, textures reading as 3D render rather than photograph. **It hyperbolizes every edit**: ask for graffiti on one wall and the whole location gets tagged.
-- **GPT Image 2** (`gpt-image-2`) — microcontrast to the ceiling, hard halos on every edge, no depth or bokeh, white balance pulled warm until the frame yellows, plastic licked-smooth materials. Worst tell: **one sickly texture pattern laid over the entire frame**.
+- **GPT Image** (`gpt-image-2-5-flare`, `gpt-image-2-5-sunburst`) — microcontrast to the ceiling, hard halos on every edge, no depth or bokeh, white balance pulled warm until the frame yellows, plastic licked-smooth materials. Worst tell: **one sickly texture pattern laid over the entire frame**. ⚠️ Catalogued on `gpt-image-2`, which 2.5 replaced on 2026-09-09 — an accent is a per-model observation, so treat this as a prior to check rather than a finding, and correct it here the first time a 2.5 frame disagrees.
 
-> ⚠️ These are accents for **`nano-banana-pro`** and **`gpt-image-2`** specifically. `nano-banana-2` is a **different model** (Gemini 3.1 Flash Image vs NB Pro's Gemini 3 Pro Image) and we have **no evidence** about its accent. Do not inherit one — say nothing rather than warn about a failure mode you can't substantiate.
+> ⚠️ These are accents for **`nano-banana-pro`** and the **GPT Image** line specifically. `nano-banana-2` is a **different model** (Gemini 3.1 Flash Image vs NB Pro's Gemini 3 Pro Image) and we have **no evidence** about its accent. Do not inherit one — say nothing rather than warn about a failure mode you can't substantiate. That caution applies to the GPT Image entry above too: it was measured on `gpt-image-2`, not on either 2.5 seat.
 
 ## Where the fault lives — triage before you change anything
 

package/skills/slates-prompting-gpt-image-2.md

@@ -1,109 +0,0 @@
----
-name: slates-prompting-gpt-image-2
-description: Prompting GPT Image 2 — the readable-text / character-sheet / shot-grid engine AND the current photoreal front-runner. Read before calling slates_generate_image with model gpt-image-2. Covers the quality tiers (medium default, high for max text precision), resolution classes (1k/2k=1080p/3k=1440p/4k), text-accuracy prompting, panel/grid layout direction, and when to route to the Banana line instead.
----
-
-# GPT Image 2 — sheets, grids, and text that actually reads
-
-<!-- @card:start -->
-<!-- slates-only -->
-<!-- MACHINE-READ. Everything between the @card markers is extracted by
-     src/prompts/craft-cards.ts and returned on every cost estimate for this
-     model, so it is the ONE piece of positive craft guidance the agent cannot
-     skip. Measured 2026-08-30: a fact inlined where it cannot be skipped moved
-     compliance 0/8 to 30/32; the same guidance behind a fetch moved nothing.
-     Keep it under 2,400 characters (the build fails above that) and keep the
-     rationale, the receipts and the worked examples in the body below. -->
-<!-- /slates-only -->
-**Card — GPT Image 2.** The readable-text, ordered-panel and exact-placement engine, and (measured 2026-08-24 at `quality: high`) the photoreal front-runner for people. Structure: subject and action, then the exact copy in quotes, then layout, then light.
-
-**The five levers**
-1. **Quote every string that must render verbatim** — `the sign reads "OPEN 24 HOURS"`. Quoted strings render most reliably.
-2. **Font FEEL, never a font name** — `clean geometric sans, high contrast`, `hand-painted brush lettering`.
-3. **Order dense copy explicitly** — `Line 1: "..." Line 2: "..."`. It respects the ordering.
-4. **Name the layout as a grid** for sheets and panels — `a 3x2 grid of panels, reading left to right, equal gutters`.
-5. **Set `quality` deliberately.** `medium` is sharp text at a quarter of the price and is within a hair of `high` in blind tests; reach for `high` only when tiny type, dense diagrams or many labelled elements ARE the job.
-
-**Examples**
-- `A 2x3 character turnaround sheet on a neutral grey field, equal gutters, reading left to right: front, three-quarter, profile, back, three-quarter back, top. One woman, mid-30s, cropped dark hair, olive field jacket. Flat even studio light, no cast shadows. Small caption under each panel naming the angle.`
-- `Photoreal portrait, natural window light from camera-left, visible skin texture and pores, 85mm compression. A man in his 50s in a charcoal knit, half-smile, looking just past lens.`
-
-**Hard constraint:** keep total on-image text under about 30 words for perfect accuracy — beyond that it degrades, gracefully but really. It has its own content filter, distinct from Gemini's.
-<!-- @card:end -->
-
-<!-- @banned:start -->
-<!-- slates-only -->
-<!-- MACHINE-READ. Every `backticked` token between the @banned markers is
-     extracted by src/prompts/banned-tokens.ts and returned on this model's cost
-     estimate, and every submitted prompt is matched against it. Keep entries
-     backticked and prose outside the backticks. -->
-<!-- /slates-only -->
-**Never use:**
-- a font NAME — describe the feel (`clean geometric sans, high contrast`) instead
-- a reference role essay (`Reference image 1 is a photograph of a woman. Use that exact woman.`) — name the subject inline instead
-- `8k`, `masterpiece`, `best quality`, `highly detailed` — quality incantations do nothing here either
-<!-- @banned:end -->
-
-GPT Image 2's edge is **character-level text accuracy** (~99% on English), ordered panels, and exact element placement — the jobs where every other model garbles a word or shuffles a layout.
-
-🚨 **It is ALSO the photoreal front-runner, and this file said the opposite until 2026-08-24.** **Receipts:** Eric's direct call, plus a head-to-head on the Higgsfield rail where GPT Image 2 at `quality: high`, 2K beat both Nano Banana rails on skin realism for photoreal people — that result is why the whole AI-influencer ad lane generates its plates here. **Route photoreal to this model, not away from it.**
-
-**What the Banana line still owns:** edit-heavy work and the 14-reference ceiling.
-
-**What would kill this:** a head-to-head at the intended crop going the other way. Per `slates-model-selection` § The meta-rule, re-run the evidence test when the roster changes — never carry a ranking forward on reputation. That rule is exactly what this correction failed.
-
-## Quality tiers — always set explicitly
-
-- **medium** (default) — sharp text, fast, the value seat: half NB2's price at the 1080p class. Blind benchmarks put it within a hair of high at a quarter of the cost. Start here.
-- **high** — ~4× the price; max text precision + reasoning. A deliberate premium pick when tiny type, dense diagrams, or many labeled elements ARE the job.
-
-Never rely on the provider default (it's high — the priciest tier). The Slates ops send medium unless you say otherwise.
-
-## Resolution classes
-
-`1k` = 1024²-class · `2k` = 1920×1080-class · `3k` = 2560×1440-class · `4k` = 3840×2160-class. Pick 2k for most sheets/panels; 4k for print-density grids. 4K exists at BOTH tiers and is API-only — even paid ChatGPT can't render it.
-
-## Prompting for text accuracy
-
-- **Quote every string that must render verbatim**: `the sign reads "OPEN 24 HOURS"` — quoted strings render most reliably.
-- Specify font *feel*, not font names: "clean geometric sans, high contrast", "hand-painted brush lettering".
-- For dense text (posters, UI mocks), list the copy as ordered lines: `Line 1: "..." Line 2: "..."` — GPT Image 2 respects ordering.
-- Keep total on-image text under ~30 words for perfect accuracy; beyond that, accuracy degrades gracefully but degrades.
-
-## Panels, sheets, and grids
-
-- State the grid explicitly and number the cells: "a 2×3 grid of panels, numbered 1–6, reading left-to-right, top-to-bottom".
-- Give each cell ONE content clause: "Panel 3: the character mid-jump, side view".
-- Character identity sheets: GPT Image 2 holds both the structured panel layout AND photoreal skin, which is why the influencer-ad lane builds its sheets here at `quality: high`, 2K. Reach for NB2/NB Pro when the sheet needs many reference images folded in (14-ref ceiling) or when it is an edit of an existing sheet.
-
-## References & editing
-
-Reference images route through the edit endpoint (up to ~10). The composed "image N" naming applies as everywhere else. Mask-based inpainting exists at the API level but isn't surfaced — describe the change instead.
-
-## 🚨 WHAT GETS YOU BLOCKED — read before writing a prompt with a person in it
-
-**Receipt: 24 consecutive attempts on one character, 2026-08-24, same project and same rail.** Eleven were refused with `content_policy_violation` on the fal edit endpoint. The refusals were never about the scene — one of the blocked prompts was a woman standing at a kitchen counter with her hand on it. **Two phrasings were hard blocks, 5 for 5 each, and neither ever passed:**
-
-**1. Never describe the reference as a photograph of a real person.**
-
-> ❌ `Reference image 1 is a photograph of a woman. Use that exact woman.`
-> ✅ `Reference image 1 is a character identity sheet showing one woman across several panels — the face in the large portrait panel is the authority for her identity. Use that exact woman.`
-
-The first reads to the filter as *recreate this real person's likeness*, which is a hard refusal regardless of what the rest of the prompt says. The second signals a fictional character and passes. **This is a wording change only — the reference image can be the same file either way.** One plate flipped from refused to accepted on this single sentence with nothing else altered.
-
-**2. Never attach a reference sheet containing a headless body panel.** A sheet whose full-body panels are cropped above the neck is refused every time, even with the correct opener. Regenerate the sheet with the head visible in every panel. Related, and already in this file's sheet guidance: phrase a cropped panel as *framing* (`cropped at the collarbone`), never as *absence* (`the head not shown`).
-
-**On top of those, ordinary content triggers still apply** and they stack independently — a correct opener does not rescue them:
-
-| Refused | Why, and the fix |
-|---|---|
-| A woman sitting on a bed in a bedroom | Domestic + bed reads as intimate. Move her to a chair, a rug, another room. |
-| A knife, even lying flat on a chopping board next to a lemon | The object is the trigger, not the framing. Swap it — a cast-iron pan cleared instantly. |
-
-**🚨 Refusals are PROBABILISTIC. Retry once before rewriting a word.** In the same session an identical prompt, identical reference, identical params was refused and then accepted on a straight re-fire. A rejected job returns no file and costs nothing, so a retry is free and a rewrite is not — rewriting first is how you end up changing four variables and learning nothing. **Only redesign after two or three refusals.**
-
-**And change ONE thing at a time.** The eleven refusals above took far longer to diagnose than they should have because a reference swap and an opener rewrite shipped in the same call. Isolate on the prompt you actually want, so a pass leaves you with a usable asset instead of a data point.
-
-## Filter regime
-
-OpenAI moderate — a third regime distinct from Gemini (NB family) and ByteDance (Seedream). Real-face references pass more readily than Gemini; violence/brand rules are similar. `slates-content-policy` applies unchanged.