@slatesvideo/shared 0.7.2 → 0.7.3

package/skills/slates-prompting-kling-v3.md

@@ -1,6 +1,6 @@
 ---
 name: slates-prompting-kling-v3
-description: How to prompt Kling V3.0 (Kuaishou). Read before calling slates_generate_video with kling-v3.0-std, kling-v3.0-pro, or kling-v3.0-omni. Kling has dialogue + SFX + ambient native syntax (Omni adds multi-character dialogue and language codes). Multi-shot rules differ from Seedance/Veo — don't cross syntaxes.
+description: "Prompt Kling V3.0 video generation and Kling O3 video edits. Use with Kling models on slates_generate_video or slates_edit_video; covers subjects, dialogue, sound syntax, multi-shot direction and edit fidelity."
 ---
 
 # Kling V3.0 — prompting
@@ -15,7 +15,7 @@ description: How to prompt Kling V3.0 (Kuaishou). Read before calling slates_gen
      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 — Kling V3.0.** The general default. Define the core subjects clearly at the START and keep those descriptions identical across shots. Up to 15s, up to 6 cuts, and the strongest image-to-video identity hold in the catalogue.
+**Card — Kling V3.0.** Define the core subjects clearly at the START and keep those descriptions identical across shots. Strong image-to-video identity hold; use the current capability surface for duration and multi-shot limits, and the model catalogue for routing.
 
 **The five levers**
 1. **Dialogue in quotes** — `Character says, "exact words here"`. On Omni, direct the voice with `Gender + Age + Voice quality + Speech rate + Emotional tone + Language`: `[Character A: Detective, mid-40s, raspy, slow cadence, weary]: "I've seen this before."`
@@ -44,7 +44,7 @@ description: How to prompt Kling V3.0 (Kuaishou). Read before calling slates_gen
 - `single continuous take` — Seedance's phrase, and it fights Kling's multi-shot
 <!-- @banned:end -->
 
-Kuaishou's video model. Three tiers: `kling-v3.0-std` (general use, no audio), `kling-v3.0-pro` (higher visual quality, no audio), `kling-v3.0-omni` (multi-character dialogue + audio-visual co-generation).
+Kuaishou's video model. Three tiers: `kling-v3.0-std` (general use, sound supported), `kling-v3.0-pro` (higher visual quality, sound supported), `kling-v3.0-omni` (multi-character dialogue + audio-visual co-generation).
 
 Up to 15s. Multi-shot supported (up to 6 cuts in 15s total). Strong on image-to-video — preserves identity, layout, and text from the input image well.
 
@@ -134,7 +134,9 @@ Miss conditions:
 - Mixing camera moves within a shot ("pan then orbit then push in")
 - Extreme wide → extreme close in adjacent shots without reference images
 
-## Element references (Omni)
+## Element references
+
+Standard and Pro take element references with a first frame; Omni also takes references without one. 4K refuses reference images.
 
 Upload 2-4 multi-angle reference photos per character/object. Tag inline:
 
@@ -199,11 +201,11 @@ Layer scene-specific suppressions on top, and never suppress something the promp
 
 ## Tier choice
 
-- **Standard**: general use, no audio
-- **Pro**: higher visual quality, no audio
-- **Omni**: multi-character dialogue, audio-visual co-gen, language codes, `@elementN` references
+- **Standard**: general use, sound supported
+- **Pro**: higher visual quality, sound supported
+- **Omni**: multi-character dialogue, audio-visual co-gen, language codes, references without a first frame
 
-Pick by capability: need dialogue/audio → Omni; need maximum visual quality silent → Pro; everything else → Standard. Prices change — check current numbers before choosing a tier<!-- slates-only -->; call `slates_estimate_generation_cost` or `slates_list_available_models`<!-- /slates-only -->.
+Every tier can generate dialogue and sound. Sound is on unless `sound: false` is passed; below 4K it bills the audio key, while 4K includes audio. Pick by visual quality and reference needs. Prices change; check current numbers before choosing a tier<!-- slates-only -->; call `slates_estimate_generation_cost` or `slates_list_available_models`<!-- /slates-only -->.
 
 ## Benchmark prompt structure
 
@@ -253,7 +255,7 @@ Rules:
 - One edit intent per pass. Chain passes for compound changes (each output is itself an editable clip, linked to its parent).
 - Billing is per second of OUTPUT ≈ the clip length, rounded UP to the next second. A 7.3s clip bills as 8s.
 - Clip constraints: 3-15s, 720-3840px, MP4/MOV. Agents can pre-trim on the timeline when a clip runs long.
-- Routing: Kling edit is the default edit tool (element lock + audio intact); Seedance edit/relocate wins style-transfer-heavy re-imaginings<!-- slates-only --> — see `slates-model-selection`<!-- /slates-only -->.
+- Route by the required change: this edit seat supports element/style-reference control and original-audio retention. Read the current catalogue for defaults and competing seats<!-- slates-only --> — see `slates-model-selection`<!-- /slates-only -->.
 
 ## Sources
 

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

@@ -1,6 +1,6 @@
 ---
 name: slates-prompting-lip-sync
-description: How to set up lip-sync — Kling-only (dedicated lip-sync and avatar endpoints, 5-second outputs). Read before calling slates_generate_lip_sync. Two flows — video→video re-dub and image→video avatar — with different inputs, pricing, and gotchas. Voice catalog, framing rules, audio file constraints, and which tier to pick. Also covers the Seedance alternative, which is a normal video generation rather than a mode of this tool.
+description: "Prepare Kling lip-sync or avatar generation with slates_generate_lip_sync. Covers source selection, voice, framing, audio constraints and the separate Seedance video-reference alternative."
 ---
 
 # Lip-sync — setup guide
@@ -15,7 +15,7 @@ description: How to set up lip-sync — Kling-only (dedicated lip-sync and avata
      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 — Lip-sync (Kling only).** Two different flows with different inputs and different prices; every output is 5 seconds.
+**Card: Lip-sync (Kling only).** Two different flows with different inputs and different prices; output follows the source clip for video or the voice track for a still, billed per 5s block.
 
 **The five levers**
 1. **Pick `sourceType` deliberately** — `video` re-dubs an existing talking head (cheapest); `image` animates a still portrait (avatar-standard, then avatar-pro only on the final selected take).
@@ -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. A real recording, or a cloned/cast voice rendered on `inworld-tts-2`, for production; this tool's built-in TTS is for scratch.
+**Hard constraint:** it is Kling-only; output follows the media and bills per 5s block. 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 -->
@@ -43,13 +43,13 @@ description: How to set up lip-sync — Kling-only (dedicated lip-sync and avata
 - `reader_en_m-v1` — listed in fal's docs, returns "Voice id not found" in production
 <!-- @banned:end -->
 
-**This tool is Kling-only.** It wraps Kling's dedicated lip-sync and avatar endpoints; every entry is a real endpoint and every output is 5 seconds.
+**This tool is Kling-only.** It wraps Kling's dedicated lip-sync and avatar endpoints; output follows the source clip for video or the voice track for a still, billed per 5s block.
 
 | Flow | Source | Model | Cost | Use case |
 |------|--------|-------|-----------|----------|
-| Re-dub | video clip | kling-lip-sync-video | ~4 credits / 5s | Replace dialogue on an existing talking head |
-| Avatar standard | still image | ai-avatar/v2/standard | ~14 credits / 5s | Animate a portrait into a talking avatar |
-| Avatar pro | still image | ai-avatar/v2/pro | ~29 credits / 5s | Higher facial fidelity for hero shots |
+| Re-dub | video clip | kling-lip-sync-video | ~4 credits / 5s block | Replace dialogue on an existing talking head |
+| Avatar standard | still image | ai-avatar/v2/standard | ~14 credits / 5s block with uploaded audio; typed text adds one flat voice block | Animate a portrait into a talking avatar |
+| Avatar pro | still image | ai-avatar/v2/pro | ~29 credits / 5s block with uploaded audio; typed text adds one flat voice block | Higher facial fidelity for hero shots |
 
 Pick `sourceType` deliberately — it decides the pricing tier and the underlying endpoint.
 
@@ -60,7 +60,7 @@ Seedance can generate the performance rather than bolting a mouth onto finished
 That is the same endpoint the old `engine=seedance-2` branch called — it just built the sentence for you, invisibly, and it presupposed a "video 1" that might not exist. Writing the prompt is the whole difference, and it is the part you want control of.
 
 - Driving clips must be 2–15s; output duration is whatever you set (4–15s).
-- Video references bill COMBINED input+output seconds (`seedance-2*-vref-*` keys) — pass the clip duration and quote before confirming. On Seedance 2.5's AI-face route (EvoLink) the input side counts as at least the output's length: max(input, output) + output.
+- Video references bill COMBINED input+output seconds (`seedance-2*-vref-*` keys); pass the clip duration and quote before confirming. On both Seedance 2.0 and 2.5's AI-face route (EvoLink) the input side counts as at least the output's length: max(input, output) + output.
 - Faces go through the normal cascade: `seedanceFace` for a character, `[REAL_FACE_DETECTED]` → `seedanceRealFace` + `realFaceConsent` for a real person.
 
 Everything below is about the Kling tool.
@@ -81,7 +81,7 @@ Use **avatar** when:
 
 ### Video flow (`sourceType: 'video'`)
 - Format: mp4 or mov
-- Duration: 2–10s (lip-sync output is always 5s — long videos get trimmed)
+- Duration: 2–10s (output follows the source clip)
 - Resolution: 720p or 1080p (480p will be rejected)
 - Max file size: 100MB
 - Face must be visible and roughly facing camera. Profile shots fail.
@@ -107,7 +107,7 @@ Two ways to drive the lips:
 - Pass `audioFilePath` — absolute path to an audio file on the user's machine
 - Format: mp3, wav, m4a, ogg, aac
 - Max 5MB
-- Duration: 2–60s (output is 5s — longer audio gets trimmed)
+- Duration: 2–60s (avatar output follows the voice track)
 - Single clean voice. Music underneath, multiple speakers, or noisy mics produce garbage lips.
 
 Prefer upload for production-quality voice. TTS for fast iteration / placeholder dialogue.
@@ -181,15 +181,15 @@ Don't default to pro. The ~15-credit delta per take adds up across iteration.
 
 ## Cost discipline
 
-- Video re-dub at ~4 credits is the cheapest dialogue iteration in the entire Slates stack — use it for voice A/B testing
-- Avatar standard at ~14 credits is fine for medium use
-- Avatar pro at ~29 credits trips the confirm gate — explicit user OK required every time
-- All 5s. There is no shorter option.
+- Video re-dub at ~4 credits per 5s block is the cheapest dialogue iteration in the entire Slates stack; use it for voice A/B testing
+- Avatar standard at ~14 credits per 5s block is fine for medium use; typed text on a still adds one flat voice block
+- Avatar pro at ~29 credits per 5s block trips the confirm gate; explicit user OK required every time
+- Output follows the media; billing rounds up to whole 5s blocks.
 
 ## Workflow patterns
 
 **Voice A/B test (cheap):**
-1. Generate one base talking-head video clip with Veo or Seedance (~40 credits)
+1. Generate one base talking-head video clip with Seedance (~40 credits)
 2. Run `slates_generate_lip_sync` with `sourceType: 'video'` against 3–5 different `ttsVoice` values
 3. Total cost: ~40 + (5 × ~4) ≈ 60 credits to compare voices
 

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

@@ -1,6 +1,6 @@
 ---
 name: slates-prompting-ltx-2-5
-description: How to prompt LTX-2.5 and LTX-2.5 Pro. Read before calling slates_generate_video with model ltx-2-5 or ltx-2-5-pro. LTX scores the picture on the same pass that draws it, so SOUND IS THE FIRST THING YOU WRITE — Lightricks ranks the prompt sound, camera, character detail, shot type and scene, then scene dressing, all in one flowing paragraph. It is also the catalogue's native MULTISHOT seat: one generation carries two to four connected shots holding character, light and voice across the cuts. Base ltx-2-5 is the distilled build — 720p/1080p/1440p/4K, clips of 6 to 20 seconds in EVEN steps, and the cheapest native 1080p second in Slates; ltx-2-5-pro is the full diffusion build and is NOT a superset, reaching only 1080p and 10 seconds for about a third more money. Three hazards live here: durations are even numbers only from six (there is no 5s or 7s clip), the model has NO reference endpoint at all so identity references are unavailable, and any sound not anchored to something in frame gets invented for you.
+description: "Prompt LTX-2.5 or LTX-2.5 Pro (ltx-2-5, ltx-2-5-pro) with slates_generate_video. Covers sound-first direction, connected shots, frame inputs, variant differences and duration constraints."
 ---
 
 # LTX-2.5 — prompting
@@ -125,11 +125,10 @@ The model renders actions. It does not render adjectives.
 
 ---
 
-## 4. Multishot — the thing this model is uniquely for
+## 4. Multishot
 
 **One LTX generation can carry several connected shots**, holding character, environment, lighting,
-voice and style across every cut. Nothing else in the catalogue does this natively; everywhere else
-you generate separate clips and stitch them, and identity drifts between them.
+voice and style across every cut. It is one of the seats that carry several shots in one generation.
 
 **Working range is two to four shots.** Three is the comfortable stopping point.
 
@@ -182,7 +181,7 @@ Choose the length the beat needs.
 
 ### Aspect ratios: 16:9 and 9:16, and nothing else
 
-The narrowest set in the catalogue alongside Veo. Square, 4:5 and 21:9 are not available on this
+The narrowest set in the catalogue. Square, 4:5 and 21:9 are not available on this
 model at any resolution.
 
 ### Frames, not references
@@ -210,7 +209,7 @@ Native synchronised audio is **included at every resolution on both seats**, wit
 no toggle that costs money — unlike Kling, where sound is a paid dimension. A 6-second 1080p LTX
 clip **with sound** is 39 credits.
 
-Combined with 1080p at $0.13/s — the cheapest native 1080p second in Slates — this makes LTX **the
+Combined with 1080p at $0.13/s, the cheapest native 1080p second with sound included in Slates, this makes LTX **the
 coverage seat**: the one to reach for when the job is many takes rather than one hero shot, when a
 sequence needs its own sound, or when the credit budget is the binding constraint.
 

package/skills/slates-prompting-minimax-h3.md

@@ -1,6 +1,6 @@
 ---
 name: slates-prompting-minimax-h3
-description: How to prompt MiniMax H3, H3 Max and H3 Max Turbo. Read before calling slates_generate_video with model minimax-h3, minimax-h3-max or minimax-h3-max-turbo. H3 is the only Slates video seat where AUDIO IS AUTHORED rather than toggled — synchronised dialogue, scene sound and an audience-only score are three separate sections of the prompt, generated in one pass — and the only one where a reference carries a DECLARED RELATIONSHIP (kept whole, partly kept, transferred onto a different subject, or a loose echo). Base minimax-h3 runs 480p/768p/2K/4K and reads 9 images + 3 video + 3 audio references; minimax-h3-max is fal's faster post-train, runs 480p/768p plus a 1080p refinement of its 768p render, and costs MORE than base H3 at 768p — a deliberate speed pick, never the default and never the cheap one; it animates start and end frames AND takes the same 9+3+3 omni-reference set (corrected 2026-09-09). minimax-h3-max-turbo is a second fal post-train with Max's ladder at half Max's rate; it takes start and end frames but has NO reference endpoint. Two hazards live here: reference images past the free allowance are billed (5 free then +4 credits on base H3; pooled media tokens on Max), and audio written into the wrong section is dropped or duplicated.
+description: "Prompt MiniMax H3, H3 Max or H3 Max Turbo with slates_generate_video. Covers separately authored dialogue, scene sound and score, declared reference relationships, frame inputs and variant-specific constraints."
 ---
 
 # MiniMax H3 — prompting
@@ -15,18 +15,18 @@ description: How to prompt MiniMax H3, H3 Max and H3 Max Turbo. Read before call
      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 — MiniMax H3.** The only seat where audio is AUTHORED rather than toggled: dialogue, scene sound and score are three separate sections of the prompt, generated in one pass, and putting a sound in the wrong section drops or doubles it.
+**Card: MiniMax H3.** The only seat with three separately authored audio layers: dialogue, scene sound and score are three separate sections of the prompt, generated in one pass, and putting a sound in the wrong section drops or doubles it.
 
 **The five levers**
-1. **Write the three audio layers separately** — `Scene sound:` for what is in the room, `Score:` for what only the audience hears, and the dialogue quoted inline. Section decides attribution.
+1. **Write the three audio layers separately**: `overall_soundscape:` for what is in the room, `non_diegetic_music:` for what only the audience hears, and the dialogue quoted inline. Section decides attribution.
 2. **Quote dialogue and name the language** — `says in English`, `speaks in Spanish`. Eleven languages are stably supported; the language is part of the instruction, not an afterthought.
 3. **Declare the reference RELATIONSHIP**, which no other seat has: `kept whole`, `partly kept`, `transferred`, or `a loose echo`. An undeclared reference is a guess.
 4. **Give a beat of stillness before a line** — `sits still for a beat, then looks up`. The sync needs something to lock against; a character already mid-motion when the line starts drifts.
 5. **Describe the beat structure** — `waits`, `then speaks`, `under the last three seconds`. H3 is a timeline, so write one.
 
 **Examples**
-- `A woman sits still at a kitchen table for a beat, then looks up. She says in English, "You said Tuesday." Scene sound: a fridge hum, a spoon set down on formica. Score: none.`
-- `Two mechanics either side of an open bonnet. The younger one wipes his hands, waits, then speaks in Spanish, "No es el alternador." Scene sound: a socket wrench, a radio two bays over. Score: a low sustained cello under the last three seconds, audience only.`
+- `A woman sits still at a kitchen table for a beat, then looks up. She says in English, "You said Tuesday." overall_soundscape: a fridge hum, a spoon set down on formica. non_diegetic_music: N/A.`
+- `Two mechanics either side of an open bonnet. The younger one wipes his hands, waits, then speaks in Spanish, "No es el alternador." overall_soundscape: a socket wrench, a radio two bays over. non_diegetic_music: a low sustained cello under the last three seconds, audience only.`
 
 **Hard constraint:** the three seats differ in what the ENDPOINT accepts, not in grammar. Base H3 reaches 2K/4K and takes references; `minimax-h3-max` tops out at 1080p, takes the same 9+3+3 references, and costs MORE at the tier they share — a speed pick, never the cheap one; `minimax-h3-max-turbo` has Max's ladder at half its rate and takes frames only, NO references. Every tier above 768p is built from the native 768p render: judge at native. Reference inputs affect the quote; include every attached modality when estimating.
 <!-- @card:end -->
@@ -61,7 +61,7 @@ what the endpoint accepts:
 | Price at 768p | **$0.060/s** | $0.080/s | $0.040/s |
 | Why pick it | resolution, references, and the cheaper second | **speed** — a 5s 768p clip in **4.8s** vs **57s** (measured) | **price** — half Max's rate at every tier |
 
-**Max is the premium seat, not the budget one.** It is 33% dearer at the one tier they share and it
+**Max is the premium seat, not the budget one.** It is 33% dearer at 768p, equal at 480p, and it
 tops out lower. Route there when a fast turnaround on a text-to-video or start-frame shot is worth
 paying for; route to base H3 for anything needing resolution, references, or the same tier cheaper.
 
@@ -91,15 +91,15 @@ reaching for 2K, which adds its own artifacting on top.
 
 ## The one thing that makes H3 different: audio is a THREE-LAYER instruction
 
-Every other video seat treats sound as on or off. H3 splits it, and the split is enforced by where
+Kling and Seedance have their own sound syntax. H3 splits audio into three separately authored layers, enforced by where
 you write each thing. Get the section wrong and the sound is dropped, doubled, or attributed to the
 wrong source.
 
 | Layer | What belongs in it | Where it goes |
 |---|---|---|
 | **Synchronised events** | dialogue, singing, and any sound tied to a specific shot or action | the **body** of the prompt, on the beat it lands |
-| **Scene sound** | ambience and physical sounds that run across the whole clip — room tone, rain, traffic, a ventilation hum | the **soundscape** section |
-| **Score** | music the characters cannot hear; audience-only | the **music** section |
+| **Scene sound** | ambience and physical sounds that run across the whole clip, room tone, rain, traffic, a ventilation hum | the **overall_soundscape** section |
+| **Score** | music the characters cannot hear; audience-only | the **non_diegetic_music** section |
 
 **Three rules, all from MiniMax's own guide:**
 
@@ -125,10 +125,10 @@ the middle-aged baker with a calm, slightly raspy voice places a fresh loaf on t
 says: "First batch of the morning." [Shot 2] At 00:05.000, the camera cuts to a close-up of
 steam rising from the sliced bread while his final words carry over from the previous shot.
 
-Soundscape: wooden shutters scrape open over a quiet street, trays clink softly inside, a
+overall_soundscape: wooden shutters scrape open over a quiet street, trays clink softly inside, a
 doorbell rings once, then light footsteps and the crisp sound of bread being sliced.
 
-Score: a soft acoustic-guitar pattern at a moderate tempo, joined by sparse upright-bass notes,
+non_diegetic_music: a soft acoustic-guitar pattern at a moderate tempo, joined by sparse upright-bass notes,
 gentle fade at the end.
 ```
 

package/skills/slates-prompting-motion-transfer.md

@@ -1,6 +1,6 @@
 ---
 name: slates-prompting-motion-transfer
-description: How to set up motion transfer — Kling Motion Control only (std and pro tiers, 5-second outputs). Read before calling slates_generate_motion_transfer. Reference image (character) + driving video (motion source) → new video of the character performing the motion. Asset selection rules, character_orientation, tiers, and prompt usage. Also covers the Seedance alternative, which is a normal video generation rather than a mode of this tool.
+description: "Prepare Kling Motion Control with slates_generate_motion_transfer: a character image plus a driving clip. Covers orientation, source selection, tiers and the separate Seedance video-reference alternative."
 ---
 
 # Motion transfer — setup guide
@@ -15,7 +15,7 @@ description: How to set up motion transfer — Kling Motion Control only (std an
      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 — Motion transfer (Kling Motion Control only).** A target IMAGE (your character) plus a source VIDEO (the motion) produces your character performing that motion. Always 5 seconds.
+**Card: Motion transfer (Kling Motion Control only).** A target IMAGE (your character) plus a source VIDEO (the motion) produces your character performing that motion. Output follows the driving clip, up to 30s with video orientation or 10s with image orientation, billed per 5s block.
 
 **The five levers**
 1. **The target image must show body proportions clearly** and the character must occupy more than about 5% of the frame. A tiny figure in a wide shot has nothing to drive.
@@ -23,7 +23,7 @@ description: How to set up motion transfer — Kling Motion Control only (std an
 3. **Choose `characterOrientation` on purpose** — `video` takes the source clip's framing, `image` preserves the portrait's. It is the most-missed choice here.
 
 4. **The prompt is atmosphere only** — `Soft afternoon sunlight, dust motes in the air, vintage warm color grade.` Motion verbs are ignored; the motion is already in the driving video.
-5. **Pick the best 5 seconds of the source up front**, and write only atmosphere: `soft afternoon sunlight`, `vintage warm color grade`, `clean studio backdrop`. The output is 5s regardless, so a long driving clip just wastes the choice.
+5. **Pick the source section up front**, and write only atmosphere: `soft afternoon sunlight`, `vintage warm color grade`, `clean studio backdrop`. The output follows that section, up to the orientation's limit; longer clips cost more blocks.
 
 **Examples**
 - `Soft afternoon sunlight, dust motes in the air, vintage warm color grade.`
@@ -63,8 +63,8 @@ movement from video 1. Preserve the character's identity, appearance, and outfit
 
 That is the same endpoint the old `motionModel=seedance-2` branch called — it just wrote that sentence for you, invisibly. Add style/setting/camera direction freely; Seedance re-generates the whole shot.
 
-- **Driving clip must be 2–15s** (all providers cap reference video at 15s). Longer clips: trim first, or use Kling MC (`characterOrientation: 'video'` takes up to 30s).
-- **Billing = combined input+output seconds** (the vref keys). The server probes the clip and corrects an understated key — quote via the confirm gate before spending. On Seedance 2.5's AI-face route (EvoLink) the input side counts as at least the output's length: max(input, output) + output.
+- **Reference videos must total 2–15s on 2.0, or 2–30s on 2.5.** Longer clips: trim first. Kling MC (`characterOrientation: 'video'`) takes up to 30s.
+- **Billing = combined input+output seconds** (the vref keys). The server probes the clip and corrects an understated key; quote via the confirm gate before spending. On both Seedance 2.0 and 2.5's AI-face route (EvoLink) the input side counts as at least the output's length: max(input, output) + output.
 - **Faces route through the face cascade**: `seedanceFace` for a character, `[REAL_FACE_DETECTED]` → confirm consent → `seedanceRealFace=true, realFaceConsent=true` (premium realface vref pricing).
 - `characterOrientation` has no Seedance equivalent; framing follows the prompt + `aspectRatio`.
 
@@ -180,13 +180,13 @@ Leave it empty if you don't have a specific atmospheric note.
 - Pro tier on first iteration — waste, switch to it once the motion + framing combo is locked
 - Cartoon driving videos — guaranteed failure
 - Cropped or partial target characters — identity will drift
-- Long driving videos when output is 5s — pick the best 5s of the source upfront
+- Driving videos longer than the needed motion; pick the source section upfront, within the orientation's limit
 
 ## Cost discipline
 
-- 5 seconds, no shorter option
+- Output follows the driving clip, up to 30s with video orientation or 10s with image orientation; billed per 5s block
 - Both tiers trip the confirm gate — every call needs explicit user OK
-- Iteration is expensive: 4 takes at pro ≈ 168 credits. Lock framing + driving video before tier-up to pro.
+- Iteration is expensive: 4 five-second takes at pro ≈ 168 credits. Lock framing + driving video before tier-up to pro.
 - Always run a single std take first to validate the motion + framing combo before committing to pro
 
 ## Confirm gate: cost + codes, no inline preview

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

@@ -1,6 +1,6 @@
 ---
 name: slates-prompting-nano-banana-2
-description: How to write prompts that produce cinematic, photorealistic results from Nano Banana 2 (Google Gemini 3.1 Flash Image, accessed via fal-ai/nano-banana-2). Read this before calling slates_generate_image when the user wants film-quality, real-world, or cinematic output. Skip for stylized / illustrated / cartoon work — the rules differ.
+description: "Prompt Nano Banana 2, Lite or Pro image generation and edits. Use on these models; covers photographic craft, subject and reference binding, typography, prompt structure and family differences."
 ---
 
 # Nano Banana 2 — cinematic & photorealistic prompting
@@ -220,16 +220,20 @@ Identity = a few flat-lit neutral angles; one reference per role, named inline;
 
 ✅ **Cinema:** "Extreme close on subject's mouth and nose, 135mm f/2.8, shallow depth of field. Breath pluming out, catching cold light from upper-left key. Lips slightly parted, peach fuzz visible. The breath holds. CineStill 800T halation around catchlights. Waiting."
 
-## The 3-strike rule
+<!-- @inject:iteration-diagnosis -->
+## Diagnose repeated failures
 
-If three iterations on the same prompt haven't produced what the user wants, stop. Hand back to the user with what you tried and what isn't working. The slot machine doesn't converge — the prompt structure is wrong, not the seed.
+After three failed attempts at the same requirement, pause unchanged re-rolls and diagnose the source reference, prompt structure, model fit and tool result. Three is a review checkpoint, not a universal limit or proof that the seed cannot matter. Preserve the attempts and name what each test changed.
+
+Continue autonomously when the brief is clear, a specific correction is supported and the next request is already authorized. Hand control back when taste or intent cannot be inferred, the next request needs fresh consent, or the available tool cannot meet the requirement. A failed roll never authorizes an additional charge. Follow the existing batch and per-request cost policy.
+<!-- @end:iteration-diagnosis -->
 
 ## Family variants — Lite and Pro
 
 Everything in this skill applies to the whole Nano Banana family; two variants trade speed/ceiling around NB2 full:
 
 - **nano-banana-2-lite** — ~half the price, ~2.7× faster, **1K output only**, max 4 refs. The draft/iteration seat: explore compositions here, then re-run the winner on NB2 full at 2K/4K. Same Gemini filter.
-- **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.
+- **nano-banana-pro**: the hero-frame/typography ceiling (2× NB2 at 1K, 1.33× at 2K, about 1.9× at 4K; 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.5 / FLUX / Seedream): `slates-model-selection`.

package/skills/slates-prompting-omni-flash.md

@@ -1,6 +1,6 @@
 ---
 name: slates-prompting-omni-flash
-description: How to prompt Gemini Omni Flash (Google, via fal). Read before calling slates_generate_video with omni-flash or slates_edit_video with omni-flash-edit. Cheap 720p tier with native synced audio included — 3-10s, 16:9/9:16 only; t2v, single-start-frame i2v, or reference-to-video with up to 7 reference images. The edit variant is the EDIT-FIDELITY WINNER for footage-synced VFX (receipt 2026-07-09) — but ONLY with short prompts: one change + "Keep everything else the same." Long descriptive prompts destroy fidelity.
+description: "Prompt Gemini Omni Flash video generation or Omni Flash edits (omni-flash, omni-flash-edit). Covers native sound, reference inputs and short change-only prompts that preserve edit fidelity."
 ---
 
 # Gemini Omni Flash — prompting
@@ -22,7 +22,7 @@ description: How to prompt Gemini Omni Flash (Google, via fal). Read before call
 2. **Editing: always end with `Keep everything else the same.`** — the one documented preservation lever.
 
 3. **Editing: describe the EFFECT, never a real object as a metaphor.** "Candle-like flame" rendered a literal candle in the subject's hand.
-4. **Editing: no conditional timing cues.** "…when he calls it, as he walks…" hard-fails with `invalid_request`. Collapse to one continuous action; the model syncs to the footage's own motion.
+4. **Editing: no chained stage directions.** Several beats cued to moments ("…flies onto his shoulder when he calls it, and perches as he walks…") hard-failed with `invalid_request`. One effect tied to an action already in the footage ("…when he snaps his fingers…") passed. Collapse to one continuous action; the model syncs to the footage's own motion.
 5. **Generation: the opposite — describe fully.** Subject, action, setting, `camera tracking alongside`, `overcast flat light`, tone. Audio is prompt-driven with no parameters: dialogue in quotes, sound in plain language — `rain patters on the tin roof`, `spray from tyres`, `a horn somewhere behind`.
 
 **Examples**
@@ -42,7 +42,7 @@ description: How to prompt Gemini Omni Flash (Google, via fal). Read before call
 **Never use in an EDIT prompt** (each one has a receipt above):
 - a long preservation preamble — it produces WORSE drift than `Keep everything else the same.`
 - a real object as a metaphor: `candle-like`, `flame-like`, `laser-like`
-- a conditional timing cue: `when he`, `as she`, `once they` — these hard-fail, they do not merely drift
+- several staged beats cued to moments (`when he calls it, and perches as he walks`): these hard-fail, they do not merely drift. One effect tied to an action already in the clip (`when he snaps his fingers`) passed
 - harm-to-person framing: `ignite`, `catch fire`, `on fire` applied to a person trips the safety filter
 <!-- @banned:end -->
 
@@ -51,15 +51,15 @@ Google's fast video generation + editing model ("Nano Banana Pro for video" in c
 ## Where it routes
 
 - **Video editing (`omni-flash-edit`) — its headline strength and the edit-lane default** for footage-synced VFX: verified 2026-07-09 head-to-head vs Kling O3 Edit on real phone footage (fire-on-fingertips on a talking take) — Omni Flash held lip movement perfectly, audio near-identical, and executed both action beats; Kling kept audio verbatim but drifted lips and missed the second beat. Full routing: slates-model-selection.
-- **Cheap drafts and iteration volume** — lowest-cost audio-native video seat (~6.4 cr/s at 720p).
-- **NOT hero GENERATION shots** — Kling 3.0 stays the general gen default, Seedance 2.0 the premium tier; Omni Flash's *generation* quality seat is still unproven.
+- **Drafts and iteration volume with sound**: an audio-native video seat (~6.4 cr/s at 720p).
+- **Hero-generation quality is still unproven.** Use the current model-routing guide for the final generation seat; the edit-fidelity receipt does not establish generation quality.
 
-## Editing (`slates_edit_video`, model `omni-flash-edit`) — THE RULES (receipts, not theory)
+## Editing (<!-- slates-only -->`slates_edit_video`, <!-- /slates-only -->model `omni-flash-edit`) — THE RULES (receipts, not theory)
 
 1. **SHORT PROMPT. One change. Nothing else.** Google's own doc: *"Simple prompts work best for video editing. Overly descriptive prompts can lead to unintended changes."* Live receipt 2026-07-09: a long "keep every frame/word/movement identical…" preamble produced WORSE drift (re-synthesized performance, wrong timing); the winning prompt was two sentences: *"Small magical flames appear on his fingertips when he snaps his fingers, and vanish when he blows on them. Keep everything else the same."*
 2. **Always end with "Keep everything else the same."** — the one documented preservation lever.
 3. **Never name a real-world object as a metaphor.** "Candle-like flame" rendered a literal candle in his hand. Describe the effect itself ("small magical flames on his fingertips").
-3b. **No conditional timing cues — they HARD-FAIL, not drift.** Receipt 2026-07-09: "a dragon appears behind him, flies onto his shoulder WHEN HE CALLS IT, and perches AS HE WALKS…" → deterministic `invalid_request` (2×, "could not generate with the given inputs"); collapsing to one continuous action — "A small photorealistic dragon flies in and perches on his shoulder, puffing a small breath of flame and smoke." — succeeded first try. The model syncs the change to the footage's own motion; it cannot take beat-by-beat stage directions cued to moments in the video.
+3b. **No chained stage directions: they HARD-FAIL, not drift.** Receipt 2026-07-09: "a dragon appears behind him, flies onto his shoulder WHEN HE CALLS IT, and perches AS HE WALKS…" → deterministic `invalid_request` (2×, "could not generate with the given inputs"); collapsing to one continuous action — "A small photorealistic dragon flies in and perches on his shoulder, puffing a small breath of flame and smoke." — succeeded first try. The model syncs the change to the footage's own motion; it cannot take beat-by-beat stage directions cued to moments in the video. The winning flames prompt above ("when he snaps his fingers") shows one effect tied to an action the footage already contains is fine; which part of the dragon prompt triggered the refusal is untested beyond that.
 4. **Safety filter (Google's, strict about harm-to-person):** "fingertips ignite / catch fire" → `content_policy_violation`. Frame effects as magical/harmless VFX: "small magical flames appear on his fingertips" passed. See slates-content-policy §Gemini for the substitution patterns.
 5. **Expect a possible tail artifact** — jitter or a doubled final speech beat in the last ~0.5s. Plan to trim the tail on the timeline; don't burn a re-roll on it.
 6. **Prompt + source clip ONLY.** No element/style reference images — identity swaps that need refs go to `kling-v3.0-omni-edit`.
@@ -67,9 +67,9 @@ Google's fast video generation + editing model ("Nano Banana Pro for video" in c
 8. **Ship via segment-splice** (the workflow, not the model): edit only the seconds where the change happens, splice back over the original on the timeline with the original audio underneath. Most of the deliverable stays untouched original footage — this is how the pro demos are actually assembled (gesture-only edited beats + voiceover in post).
 9. Chain edits one change at a time — each edit saves as a new asset linked to its parent.
 
-## Generation (`slates_generate_video`, model `omni-flash`)
+## Generation (<!-- slates-only -->`slates_generate_video`, <!-- /slates-only -->model `omni-flash`)
 
-- **Inputs:** prompt only (t2v), prompt + ONE start frame (`firstFrameAssetId`, i2v), or prompt + up to **7 reference images** (ingredient/character/environment/style asset params — they merge into one reference list). No last frame, no video/audio references — the op rejects them.
+- **Inputs:** prompt only (t2v), prompt + ONE start frame (<!-- slates-only -->`firstFrameAssetId`, <!-- /slates-only -->i2v), or prompt + up to **7 reference images** (ingredient/character/environment/style asset params — they merge into one reference list). No last frame, no video/audio references — the op rejects them.
 - Descriptive prompts are fine for GENERATION (the short-prompt law above is edit-specific). Structure like a shot brief: subject + action + setting + camera + lighting + tone.
 - **Name references inline** the standard Slates way ("Marcus (image 1) walks…"). The endpoint also accepts explicit `<IMAGE_REF_0>`-style binding tags (zero-indexed) — useful when a specific image must bind to a specific role.
 - **Audio is prompt-driven** — no audio parameters. Dialogue in quotes; direct sound in plain language ("rain patters on the tin roof"). Negative direction as plain instructions ("Do not show text").

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

@@ -1,6 +1,6 @@
 ---
 name: slates-prompting-seed-audio
-description: How to prompt Seed Audio 1.0 (ByteDance, via fal). Read before calling slates_generate_audio with model seed-audio. The one-pass audio SCENE model — dialogue, SFX and ambience together from ONE plain sentence. CRITICAL - it has NO duration parameter, so length must be named IN THE PROMPT TEXT and Slates bills the duration you request. Covers the one-sentence doctrine, the crowd-size rule, why Kling "SFX:" syntax hurts here, and the audio-refs-XOR-image input rule.
+description: "Prompt Seed Audio 1.0 (seed-audio) with slates_generate_audio. Covers scene sentences, dialogue, crowd size, spatial sound, duration in prompt text and mutually exclusive audio or image references."
 ---
 
 # Seed Audio 1.0 — prompting
@@ -43,7 +43,29 @@ description: How to prompt Seed Audio 1.0 (ByteDance, via fal). Read before call
 - shot language: `wide shot`, `slow push in`, `warm tungsten` — camera and lighting words are video-prompt words the model has to ignore
 <!-- @banned:end -->
 
-ByteDance's one-pass audio scene model, carried on fal (`bytedance/seed-audio-1.0`). It generates dialogue, sound effects and ambience **together**, from a single plain sentence. 1–120 seconds. It is the default audio model in Slates and the workhorse for continuity beds.
+ByteDance's one-pass audio scene model, carried on fal (`bytedance/seed-audio-1.0`). It generates dialogue, sound effects and ambience **together**, from a single plain sentence. Use the generated duration bounds below and the current catalogue for routing; it is useful for continuity beds.
+
+<!-- @inject:thresholds -->
+<!-- GENERATED from @slatesvideo/shared — do not edit between the markers.
+     Source: CONFIRM_CREDITS, DEVIATION_FACTOR and the audio bounds in
+     packages/shared/src/operations/index.ts. Every number here is REFUSED by an
+     op when a prompt gets it wrong, which is why none of them is typed by hand
+     any more: this block replaced four claims that contradicted the code. -->
+
+**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`. 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
+  parameter on the model — the number you pass is written into the prompt AND is what the user is
+  billed. Outside that range the op refuses rather than clamping.
+- **Sound Effects duration:** **1–22 seconds**, billed per second, never left for the
+  model to pick.
+
+Never quote a credit figure from memory: `slates_estimate_generation_cost` returns the real one.
+<!-- @end:thresholds -->
 
 ## Where it routes
 
@@ -134,8 +156,6 @@ Set `multilingual: true` for non-English or mixed-language lines.
 | `volume` | 0.5–2.0 | Rarely — normalize on the timeline instead. |
 | `pitch` | −12…+12 semitones | Ageing or shifting a voice. Small moves only; ±3 is already a lot. |
 | `multilingual` | bool | Non-English or code-switched lines. |
-| `sampleRate` | 8k–48k | Leave at 24000 unless you are matching an existing stem. |
-| `outputFormat` | mp3 / wav / pcm / ogg_opus | wav when this is going into a mix; mp3 otherwise. |
 
 ## Iterating