@slatesvideo/shared 0.7.2 → 0.7.3

package/skills/slates-previs-blocking.md

@@ -1,6 +1,6 @@
 ---
 name: slates-previs-blocking
-description: Build a 3D blocking pass in Blender, render it grey-box, and use it as a reference video so the generated shot follows a camera path you designed instead of one the model invented. Use when the user wants precise camera control, a multi-cut sequence, a one-take move, spatial consistency across shots, or says the camera keeps drifting / they keep burning credits re-rolling.
+description: "Build and render a Blender blocking pass for precise camera paths, cut timing or spatial continuity, then guide video generation with the clip. Use when those controls are required or prompting has failed to hold them."
 ---
 
 # Previs blocking — design the shot, then generate it
@@ -89,17 +89,48 @@ The whole of `slates-camera-language`. Build the rig, then keyframe it. Then **r
 
 Add it after the moves are right, never before — noise on top of a wrong path just hides the wrong path.
 
+<!-- @inject:blender-action-curves -->
+## Read animation curves from the active action layout
+
+Blender 5 uses layered actions: curves belong to the channelbag for `animation_data.action_slot`, inside each layer's strips. A direct `action.fcurves` lookup failed on Blender 5.2.1 in the 2026-08-28 blocking run. Feature-detect the layout before changing interpolation or noise; an unanimated object can legitimately have no curves.
+
+The snippets below use this small Blender-side iterator. It runs inside Blender; no add-on code is imported into the MCP package.
+
+```python
+def action_curves(datablock):
+    anim = getattr(datablock, "animation_data", None)
+    action = getattr(anim, "action", None)
+    if action is None:
+        return
+    if hasattr(action, "fcurves"):
+        yield from action.fcurves
+    elif getattr(anim, "action_slot", None) is not None:
+        for layer in action.layers:
+            for strip in layer.strips:
+                if hasattr(strip, "channelbag"):
+                    bag = strip.channelbag(anim.action_slot)
+                    if bag is not None:
+                        yield from bag.fcurves
+```
+
+Use the datablock that owns the keyed property: the curve data for `eval_time`, the object for location and rotation, the camera data for lens. Confirm a named channel exists before assuming a keyframe operation created it.
+<!-- @end:blender-action-curves -->
+
 ### 5. Verify the cuts
 
 The one check that catches the most damage: on a multi-cut blocking, camera position, target and focal length must all change **exactly on the cut frame, with no transition frame between**. One interpolated frame reads as a whip-pan the model will faithfully reproduce.
 
 ```python
-# Every camera f-curve keyframe on a cut frame must be CONSTANT out of the
-# previous key, or the cut smears.
-for fc in cam.animation_data.action.fcurves:
-    for kp in fc.keyframe_points:
-        if int(kp.co[0]) in CUT_FRAMES:
-            kp.interpolation = 'CONSTANT'
+# On a jump-cut camera, key the final pre-cut pose at cut_frame - 1.
+# CONSTANT belongs to that preceding key: interpolation controls its OUTGOING segment.
+# Check object transforms and camera data (including lens). Repeat for a keyed target.
+for owner in (cam, cam.data):
+    for fc in action_curves(owner):
+        keys = list(fc.keyframe_points)
+        for previous, current in zip(keys, keys[1:]):
+            if current.co[0] in CUT_FRAMES:
+                assert previous.co[0] == current.co[0] - 1, "Key the final pre-cut state first"
+                previous.interpolation = 'CONSTANT'
 ```
 
 Also check nothing interpenetrates — proxies through floors, clones through the hero object, letters through each other. The model renders intersections as faithfully as it renders everything else.
@@ -118,27 +149,27 @@ bpy.ops.wm.save_as_mainfile(filepath=path, copy=True)
 slates_blender_render_blocking { projectId, fps: 24 }
 ```
 
-Renders the **scene camera** through scene settings — never the user's viewport, so the result does not depend on where they left their mouse — imports the mp4 into the project, and returns `assetId` + `durationSeconds`.
+Renders the **scene camera** through scene settings and imports the mp4 into the project. The result does not depend on where the user left their viewport or mouse. It returns `asset.id` + `durationSeconds`.
 
 Then:
 
 ```
 slates_generate_video {
   model: "seedance-2.5",
-  videoReferenceAssetIds: [<the blocking asset>],
+  videoReferenceAssetIds: [<asset.id>],
   videoReferenceSecondsEach: [<durationSeconds>],
   characterAssetIds: [...], environmentAssetIds: [...], styleAssetIds: [...],
   prompt: <written per slates-blocking-to-prompt>
 }
 ```
 
-**Four inputs, and that is the entire stack:** a character sheet each, one location/style reference, the blocking clip, and a prompt written against the blocking. Resist adding a fifth.
+**A focused reference stack:** one identity sheet per character, any location or look reference the brief needs, the blocking clip, and a prompt written against it. Add a reference only for a distinct requirement; more competing references add variables rather than guaranteeing fidelity. An audio reference is valid when voice or sound continuity needs it and the selected endpoint supports it.
 
-Model note: seedance-2.5 is the seat for this — 10 reference videos at up to 30s each. seedance-2 and minimax-h3 take 3 at 15s. Route per `slates-model-selection`.
+Choose a model that accepts video references using `slates-model-selection`, then read its current reference caps. Video duration limits apply to the combined reference clips, not to each clip independently; quote each actual input duration.
 
 ## Leaving holes on purpose
 
-Where the model outperforms any blockout you could build — liquid, smoke, fire, cloth — **block a black gap instead** and say so in the prompt: `CUT 7 (14.5-17.0, black gap in the reference)`. You are reserving a slot, not forgetting one.
+Where the model outperforms any blockout you could build — liquid, smoke, fire, cloth — **block a black gap instead** and say so in the prompt: `CUT 7 (14.5-17.0, black gap in the reference)`. You are reserving a slot, not forgetting one. Keep these exact times in the blocking record, then translate model-facing time cues through `slates-blocking-to-prompt`; not every endpoint accepts fractional timestamps.
 
 ## What not to do
 
@@ -146,7 +177,7 @@ Where the model outperforms any blockout you could build — liquid, smoke, fire
 - **Don't animate what you don't need.** Heads especially — a proxy head turning wrong is worse than one that never turns.
 - **Don't build the camera before the geometry.** It has nothing to aim at, and every value you set gets redone.
 - **Don't skip reading the scene back.** Write timings from `slates_blender_scene`'s `cutSeconds`, never from what you intended to build.
-- **Don't exceed the model's reference-video ceiling.** A 40s blocking against a 30s cap silently truncates.
+- **Don't exceed the model's reference-video ceiling.** A 40s blocking against a 30s cap is rejected; trim it first.
 
 ## Related
 

package/skills/slates-project-organization.md

@@ -1,13 +1,13 @@
 ---
 name: slates-project-organization
-description: Use when the user names an asset by code ("use IMG-A36"), asks what a code means, or is organizing or navigating a project. Covers the asset short-code system (IMG-A12 / VID-V3 / AUD-S1 badges on every gallery card), folders for film STRUCTURE, and the typed tabs for reusable references.
+description: "Navigate and organize Slates projects, asset codes such as IMG-A12 or VID-V3, folders, Library references and templates. Use when locating media, preparing a reusable production or keeping a project legible."
 ---
 
 # Organizing a Slates project
 
 Slates already gives every REUSABLE reference a home — the **Library**, in categories the user names (Characters, Locations, Products, Looks…; `slates_list_library`), each item used in a prompt as `@name`, or `#name` for a look. Do NOT recreate those as folders, and never invent a category the user did not ask for. Folders are for **structure**, never type.
 
-**Folders = where an asset sits in the FILM**, and they mirror to real subfolders on disk (`projects/<id>/…`), so a human can open the project in Resolve/Finder and navigate it like an edit. Use them for work product, not references.
+**Folders = where an asset sits in the FILM.** They are in-app structure only. Use them for work product, not references.
 
 Create with `slates_create_folder`; file assets with `slates_move_assets_to_folder`. Generations land in the project's active folder, so set it before a batch.
 

package/skills/slates-prompting-elevenlabs.md

@@ -1,6 +1,6 @@
 ---
 name: slates-prompting-elevenlabs
-description: How to prompt ElevenLabs Sound Effects v2 in Slates. Read before calling slates_generate_audio with model eleven-sfx — ONE short effect with an EXACT duration, or a seamless loop, billed per second. Covers describing an effect by its physical cause, the one-sound-per-generation rule, picking a duration, loops, prompt_influence, and when to use Seed Audio instead.
+description: "Prompt ElevenLabs Sound Effects v2 (eleven-sfx) for a single effect or loop. Use with slates_generate_audio on this model; covers physical causes, duration, material, space and prompt influence."
 ---
 
 # ElevenLabs Sound Effects v2 — prompting
@@ -15,7 +15,7 @@ description: How to prompt ElevenLabs Sound Effects v2 in Slates. Read before ca
      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 — ElevenLabs Sound Effects v2.** ONE short sound with an exact length, or a seamless loop. The only Slates audio surface with a real duration control and a real loop mode.
+**Card: ElevenLabs Sound Effects v2.** ONE short sound with an exact length, or a seamless loop. A Slates audio surface with a real duration control and a real loop mode.
 
 **The five levers**
 1. **Describe the physical CAUSE, not the label** — `heavy oak door slams shut`, `boot scuffs on grit`, `a latch drops home`.
@@ -42,7 +42,7 @@ description: How to prompt ElevenLabs Sound Effects v2 in Slates. Read before ca
 - `door sound`, `whoosh`, `footsteps`, `impact`, `ambience` standing alone
 <!-- @banned:end -->
 
-One short sound with an exact length, carried on fal (`fal-ai/elevenlabs/sound-effects/v2`). This is the only Slates audio surface with a real duration control and a real loop mode.
+One short sound with an exact length, carried on fal (`fal-ai/elevenlabs/sound-effects/v2`). This Slates audio surface has a real duration control and a real loop mode.
 
 ## Where it routes
 
@@ -87,7 +87,7 @@ Slates **always sends** `durationSeconds`. (Left null the model picks, which mak
 **The thresholds, from the code that enforces them:**
 
 - **Confirm gate:** above **17 credits** an op returns `requires_confirm` and will not
-  proceed until you re-call with `confirm: true`. Below it, announce the cost once and go.
+  proceed until you re-call with `confirm: true`. This is a code gate, not permission to spend: every generation still needs the user-approved plan or quote.
 - **Deviation pause:** the desktop Studio Agent stops and re-asks when projected generation spend
   exceeds the approved plan by more than **20%**. You do not trigger this; the app does.
 - **Seed Audio duration:** **3–120 seconds.** There is no duration

package/skills/slates-prompting-flux-2-max.md

@@ -1,6 +1,6 @@
 ---
 name: slates-prompting-flux-2-max
-description: How to prompt FLUX.2 Max (Black Forest Labs image model). Read before calling slates_generate_image with model flux-2-max, or slates_edit_image with editModel flux-2-max. FLUX.2 wants front-loaded structure, real camera vocabulary, and positive-only phrasing — no negative prompts, no tag soup.
+description: "Prompt or edit images with FLUX.2 Max (flux-2-max). Use with slates_generate_image or slates_edit_image on this model; covers word order, camera vocabulary, materials, colours and positive phrasing."
 ---
 
 # FLUX.2 Max — prompting
@@ -130,7 +130,7 @@ Use natural language for exploration, JSON when the layout is locked and you're
 
 ## Reference images (edit path)
 
-In Slates, pass `referenceAssetIds` on `slates_generate_image` — FLUX routes them through its edit endpoint. Slates names each reference inline in the prompt ("the subject (image 1), the style (image 2)") in the order it sends them, so you don't hand-write role labels; the name carries the role and unnamed-by-position blending is avoided. For surgical changes to one existing image use `slates_edit_image` with `editModel: flux-2-max` (note: FLUX edits ignore extra referenceAssetIds — that's NB2-only).
+In Slates, pass `referenceAssetIds` on `slates_generate_image` — FLUX routes them through its edit endpoint. Slates names each reference inline in the prompt ("the subject (image 1), the style (image 2)") in the order it sends them, so you don't hand-write role labels; the name carries the role and unnamed-by-position blending is avoided. For surgical changes to one existing image use `slates_edit_image` with `editModel: flux-2-max`. Extra `referenceAssetIds` are supported within the current edit-reference cap, with the source occupying one slot; read the tool schema for that cap. An older desktop without this capability refuses the request rather than silently omitting references.
 
 ### Reference rules (the verified ones)
 
@@ -166,7 +166,6 @@ Identity = a few flat-lit neutral angles; one reference per role, named inline;
 ### For FLUX.2 Max specifically
 
 - **FLUX caps references well below NB2's 14, so rule 1's "2-4" is a ceiling here, not a starting point.** Be deliberate about which roles earn a slot.
-- **Rule 9 has a hard edge on this model:** `slates_edit_image` with `editModel: flux-2-max` ignores extra `referenceAssetIds` — that is NB2-only. A FLUX edit sees the source image and the prompt, nothing else.
 - **FLUX has no memory between generations, so rule 7 is enforced by repetition.** Define the character exhaustively once and repeat those exact descriptors verbatim in every subsequent prompt — see Character consistency across a series below.
 
 ## Character consistency across a series

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

@@ -1,6 +1,6 @@
 ---
 name: slates-prompting-gpt-image-2-5
-description: Prompt and edit images with GPT Image 2.5 Flare or Sunburst. Covers reference roles, realistic lighting, text, grids, quality choices and targeted edits. Use with slates_generate_image or slates_edit_image on these models.
+description: "Prompt or edit images with GPT Image 2.5 Flare or Sunburst. Use with slates_generate_image or slates_edit_image on these models; covers reference roles, lighting, text, panels, quality choices and edits."
 ---
 
 # GPT Image 2.5 — sheets, grids, and text that actually reads
@@ -135,7 +135,7 @@ Reference images route through the edit endpoint, **up to 16** — fal's documen
 
 ## Transparent backgrounds
 
-If you need a cut-out rather than a scene, **ask for it explicitly and check the alpha**. OpenAI: request `background=transparent` and use PNG or WebP, then *"check the decoded image's alpha channel, including hair, glass, shadows, and object edges"* — a painted-white backdrop is the common failure and it is not transparency. Say what must NOT appear: *"no solid backdrop, no checkerboard, no scenery, no watermark"*, and do not let the product get restyled while the background is removed. **On every follow-up edit, repeat the transparency requirement** or it gets dropped. (Slates always requests PNG, so the format half is handled for you. **`background` IS surfaced now** — the Background control on the prompt bar, and `backgroundMode` on `slates_generate_image` / `slates_edit_image`. It is free: fal prices this family on size × quality alone.)
+If you need a cut-out rather than a scene, **ask for it explicitly and check the alpha**. OpenAI: request `background=transparent` and use PNG or WebP, then *"check the decoded image's alpha channel, including hair, glass, shadows, and object edges"* — a painted-white backdrop is the common failure and it is not transparency. Say what must NOT appear: *"no solid backdrop, no checkerboard, no scenery, no watermark"*, and do not let the product get restyled while the background is removed. **On every follow-up edit, repeat the transparency requirement** or it gets dropped. <!-- slates-only -->(Slates always requests PNG, so the format half is handled for you. **`background` IS surfaced now** — the Background control on the prompt bar, and `backgroundMode` on `slates_generate_image` / `slates_edit_image`. It is free: fal prices this family on size × quality alone.)<!-- /slates-only -->
 
 ## When an edit must not touch a region at all
 

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

@@ -1,174 +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. 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.
+---
+name: slates-prompting-inworld-tts
+description: "Direct speech with Inworld Realtime TTS-2 (inworld-tts-2). Use with slates_generate_audio on this model; covers voice identity, reference acoustics, delivery tags, punctuation and voice consent."
+---
+
+# 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.