@slatesvideo/shared 0.7.1 → 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,6 +1,6 @@
 ---
 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.
+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

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`.