@slatesvideo/shared 0.6.2 → 0.6.4

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

@@ -0,0 +1,218 @@
+---
+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.
+---
+
+# LTX-2.5 — prompting
+
+<!-- @card:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Everything between the @card markers is extracted by
+     src/prompts/craft-cards.ts and returned on every cost estimate for this
+     model, so it is the ONE piece of positive craft guidance the agent cannot
+     skip. Measured 2026-08-30: a fact inlined where it cannot be skipped moved
+     compliance 0/8 to 30/32; the same guidance behind a fetch moved nothing.
+     Keep it under 2,400 characters (the build fails above that) and keep the
+     rationale, the receipts and the worked examples in the body below. -->
+<!-- /slates-only -->
+**Card — LTX-2.5.** It scores the picture on the same pass that draws it, so SOUND IS THE FIRST THING YOU WRITE. Lightricks' own priority order: sound, camera, character detail, shot type and scene, then scene dressing. One flowing paragraph, not labelled sections. When a prompt sprawls, cut from the bottom.
+
+**The five levers**
+1. **Lead with sound, and anchor every sound to something in frame.** The test is "visible, or at least locatable" — `the rope creaks against the cleat`, `the hull knocking hollow against the fenders`, `rain on the awning`. A distant whistle is fine IF you have named the post it comes from.
+2. **Camera second**, because framing decides the visual weight of the shot — `low camera at the gunwale`, `slow drift right`, `static medium behind the counter`.
+3. **Character detail as physical ACTION**, not as adjectives about a person — `she braces a boot on the rail and hauls`, `his hands counting notes`.
+4. **It is the native MULTISHOT seat** — one generation carries two to four connected shots holding character, light and voice across the cuts. Write the cuts.
+5. **Quote dialogue and name the language and accent** — `in English with a slight German accent` — `"We should not have come back," in English with a slight German accent.`
+
+**Examples**
+- `The rope creaks against the cleat as she leans back, gulls calling somewhere off the port bow, the hull knocking hollow against the fenders. Low camera at the gunwale, slow drift right. She braces a boot on the rail and hauls, twice, then stops.`
+- `A till drawer bangs shut, a fan ticks against its cage, rain on the awning outside. Static medium behind the counter, then cut to a close-up of his hands counting notes, then cut wide as he looks up at the door.`
+
+**Hard constraint:** durations are EVEN numbers from six — there is no 5s or 7s clip. There is NO reference endpoint at all, so identity references are unavailable; use MiniMax H3 or Kling when a character must hold across shots. Any sound not anchored to something in frame gets invented for you. And never write mood adjectives as sound: "tense atmosphere", "a sense of dread" and "ominous ambience" produce nothing usable — the fix is one more moving object in frame with a sound attached to it.
+<!-- @card:end -->
+
+<!-- @banned:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Every `backticked` token between the @banned markers is
+     extracted by src/prompts/banned-tokens.ts and returned on this model's cost
+     estimate, and every submitted prompt is matched against it. Keep entries
+     backticked and prose outside the backticks. -->
+<!-- /slates-only -->
+**Never use** — mood adjectives standing in for sound produce nothing usable:
+- `tense atmosphere`, `a sense of dread`, `ominous ambience`, `eerie silence`
+- an unanchored sound: name the thing in frame it comes from, or cut it
+<!-- @banned:end -->
+
+LTX-2.5 generates picture and sound **in a single pass**, with a Gemma-4 12B text encoder reading
+one flowing paragraph. That single fact drives everything below: the prompt is not a shot
+description with audio bolted on, it is **a scene where the sound is load-bearing** — and
+Lightricks' own priority order puts sound first, ahead of the camera.
+
+Two seats, and the naming is a trap:
+
+| | `ltx-2-5` (base) | `ltx-2-5-pro` |
+|---|---|---|
+| Build | Distilled, 8-step | Full diffusion ("Diffusion Fidelity Rendering") |
+| Resolutions | 720p / 1080p / **1440p** / 4K | 720p / 1080p |
+| Durations | 6–20s, even steps | 6 / 8 / 10s |
+| Price | $0.09–$0.30 per second | $0.12–$0.17 per second |
+| Reach for it when | iterating, long takes, 4K delivery, batch volume | one dense final render inside 1080p and 10s |
+
+**Pro is not "base plus more."** It buys picture quality on a *narrower* envelope — it cannot make
+a 1440p frame and it cannot make a 12-second clip. Reaching for it out of habit costs a third more
+*and* takes away the reach.
+
+---
+
+## 1. The six parts, in priority order, in one paragraph
+
+Lightricks ranks the elements of an LTX prompt like this. When a prompt sprawls, **cut from the
+bottom.**
+
+1. **Sound** — highest priority; the model scores the picture as it draws it.
+2. **Camera** — framing decides visual weight and the feel of the shot.
+3. **Character detail** — expressed as physical action.
+4. **Shot type and scene** — the action itself.
+5. **Scene dressing** — the first thing to trim.
+
+Write it as **one flowing paragraph**, not a list of labelled sections. LTX is not Seedance (eight
+engineering slots) and not H3 (three separate audio layers) — it wants continuous prose.
+
+---
+
+## 2. Sound: anchor it or it gets invented
+
+**Write the audio line last, then go back and check every cue has a source you could point at.**
+Anything unanchored, the model invents for you.
+
+The test is **"visible, or at least locatable."** A distant whistle is fine *if* you have named the
+marshal's post it comes from. A "distant whistle" with nothing to attach to is a coin flip.
+
+> the rope creaks against the cleat as she leans back, gulls calling somewhere off the port bow,
+> the hull knocking hollow against the fenders
+
+**Never write mood adjectives as sound.** "Tense atmosphere", "a sense of dread" and "ominous
+ambience" produce nothing usable. If a scene feels thin, the fix is **one more moving object in
+frame with a sound attached to it** — never another adjective.
+
+### Dialogue
+
+Quote it, and name the language and accent:
+
+> "We should not have come back," in English with a slight German accent.
+
+Two rules that decide whether the lip sync lands:
+
+- **Give the character a beat of stillness before they speak.** The sync needs something to lock
+  against; a character already mid-motion when the line starts drifts.
+- **Describe the beat structure** — when they look, how long they wait, when they speak, where they
+  look afterwards.
+
+Slates pins the frame rate at 25fps, which is also what Lightricks recommends for dialogue: at 50fps
+the performance "pulls toward a video look."
+
+---
+
+## 3. Character emotion is physical
+
+The model renders actions. It does not render adjectives.
+
+| Instead of | Write |
+|---|---|
+| she looks anxious | her jaw sets, she turns the ring on her finger twice |
+| he seems exhausted | he blinks slowly and lets his shoulder take the doorframe |
+| a tense standoff | neither moves; his thumb finds the strap and stays there |
+
+---
+
+## 4. Multishot — the thing this model is uniquely for
+
+**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.
+
+**Working range is two to four shots.** Three is the comfortable stopping point.
+
+At **every** transition you must supply four things:
+
+1. **Name the edit in the prose** — "hard cut", "dissolve", "match cut".
+2. **Re-establish the shot completely** — scale, angle, lens and light all reset at a cut. A cut is
+   not a continuation.
+3. **Re-identify recurring characters by their original descriptor.** "The woman in the bronze
+   gown", never "she". Pronouns lose the character across a cut — this is the single most common
+   multishot failure.
+4. **State what the sound does at the cut.** Silence is not assumed; if the room tone should drop
+   out, say so.
+
+A shape that works:
+
+> Wide establishing shot of the workshop, dust in the window light, a lathe turning somewhere off
+> frame — hard cut — macro close-up of the brass fitting as it seats, the turning noise gone,
+> replaced by a single dry click — match cut — medium shot of the woman in the bronze gown stepping
+> back, the room tone returning underneath her.
+
+---
+
+## 5. Camera: write it, don't enumerate it
+
+fal exposes a `camera_motion` enum (dolly in/out/left/right, jib up/down, static, focus shift).
+**Slates does not surface it, deliberately** — and prose is the better instrument anyway:
+
+- **A written move can be tied to a specific moment.** "A slow push-in that settles as she reaches
+  the door, then holds" is not expressible as an enum value.
+- **For multishot it would be actively wrong** — one enum value would impose a single camera
+  behaviour on three shots that each want their own.
+
+So name the lens, the framing, the move, and **the moment the move resolves**.
+
+---
+
+## 6. The hard constraints
+
+### Durations are even numbers only, starting at six
+
+**6, 8, 10, 12, 14, 16, 18, 20.** There is no 5-second LTX clip and no odd duration of any length.
+Asking for 7s is not a rounding matter — that generation does not exist.
+
+**And the long end is 1080p-and-below only.** At 1440p and 4K the ceiling drops to **6, 8 or 10**.
+
+fal's own default is `auto`, which lets the model pick the length from the described action.
+**Slates always sends an explicit length instead**, so what you choose is what you are billed for.
+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
+model at any resolution.
+
+### Frames, not references
+
+LTX takes a **start frame** and an **optional end frame** (which generates a transition between the
+two). It has **no reference-to-video endpoint at all** — no identity references, no style
+references, no environment references, no reference video, no reference audio.
+
+**For character consistency across separate shots, use MiniMax H3 or Kling.** Within a single LTX
+generation, use multishot instead — that is precisely the gap it fills.
+
+In image-to-video, **do not cut away from the opening frame too early.** You have paid for that
+frame; let it play before the first move.
+
+### Do not ask for text on screen
+
+Neither the spelling nor its stability from frame to frame can be relied on. Signage, labels,
+captions and lower-thirds belong in post.
+
+---
+
+## 7. Audio is free here, and that changes the routing
+
+Native synchronised audio is **included at every resolution on both seats**, with no surcharge and
+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
+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.
+
+Route away from it when you need identity references (H3, Kling), a ratio other than 16:9 or 9:16
+(Seedance, Kling), or authored multi-layer audio direction (H3).

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

@@ -5,6 +5,45 @@ description: How to prompt MiniMax H3 and MiniMax H3 Max. Read before calling sl
 
 # MiniMax H3 — prompting
 
+<!-- @card:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Everything between the @card markers is extracted by
+     src/prompts/craft-cards.ts and returned on every cost estimate for this
+     model, so it is the ONE piece of positive craft guidance the agent cannot
+     skip. Measured 2026-08-30: a fact inlined where it cannot be skipped moved
+     compliance 0/8 to 30/32; the same guidance behind a fetch moved nothing.
+     Keep it under 2,400 characters (the build fails above that) and keep the
+     rationale, the receipts and the worked examples in the body below. -->
+<!-- /slates-only -->
+**Card — 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.
+
+**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.
+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.`
+
+**Hard constraint:** the two seats differ in what the ENDPOINT accepts, not in grammar. Base H3 reaches 2K/4K and takes references; `minimax-h3-max` is capped at 768p, has NO reference endpoint at all (start and end frames still work), and costs MORE at the tier they share — it is a speed pick, never the cheap one. H3's top two resolution tiers are UPSCALES of the native render: judge at native. Reference images past the fifth are a paid dimension of the cost key — declare the count when quoting.
+<!-- @card:end -->
+
+<!-- @banned:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Every `backticked` token between the @banned markers is
+     extracted by src/prompts/banned-tokens.ts and returned on this model's cost
+     estimate, and every submitted prompt is matched against it. Keep entries
+     backticked and prose outside the backticks. -->
+<!-- /slates-only -->
+**Never use:**
+- a sound written into the wrong audio section — it is dropped, doubled, or attributed to the wrong layer
+- `background music` as a bare instruction: the score is its own authored layer, audience-only, and it is named as such
+- an undeclared reference relationship — say kept whole, partly kept, transferred, or a loose echo
+<!-- @banned:end -->
+
 H3 is an **omni transformer**: it generates picture and sound in the same pass, at 24fps with
 32kHz stereo, 5–15 seconds, in 11 stably-supported languages (Arabic, Chinese, English, French,
 German, Italian, Japanese, Korean, Portuguese, Russian, Spanish). That single fact drives

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

@@ -5,6 +5,44 @@ description: How to set up motion transfer — Kling Motion Control only (std an
 
 # Motion transfer — setup guide
 
+<!-- @card:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Everything between the @card markers is extracted by
+     src/prompts/craft-cards.ts and returned on every cost estimate for this
+     model, so it is the ONE piece of positive craft guidance the agent cannot
+     skip. Measured 2026-08-30: a fact inlined where it cannot be skipped moved
+     compliance 0/8 to 30/32; the same guidance behind a fetch moved nothing.
+     Keep it under 2,400 characters (the build fails above that) and keep the
+     rationale, the receipts and the worked examples in the body below. -->
+<!-- /slates-only -->
+**Card — 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.
+
+**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.
+2. **Single character in the target.** A group image breaks the identity anchor.
+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.
+
+**Examples**
+- `Soft afternoon sunlight, dust motes in the air, vintage warm color grade.`
+- `Clean studio backdrop, sharp focus on the character.` (Or leave it empty.)
+
+**Hard constraint:** cartoon driving videos fail, and a cropped or partial target character drifts. std is fine while the motion-and-framing combination is still moving; switch to pro once it is locked. For a REGENERATED shot instead — physical contact, cloth and hair, camera motion, native audio — that is a normal Seedance video generation with the driving clip as a video reference, not a mode of this tool.
+<!-- @card:end -->
+
+<!-- @banned:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Every `backticked` token between the @banned markers is
+     extracted by src/prompts/banned-tokens.ts and returned on this model's cost
+     estimate, and every submitted prompt is matched against it. Keep entries
+     backticked and prose outside the backticks. -->
+<!-- /slates-only -->
+**Never use** — the motion is already in the driving video, so motion verbs are ignored:
+- `spins faster`, `jumps higher`, `add more energy`, `moves quicker`
+<!-- @banned:end -->
+
 Take a still **target image** (your character) and a **source video** (the motion you want), produce a new video of your character performing the source video's motion. **This tool is Kling-only** — it wraps Kling Motion Control and nothing else.
 
 | Tier | Cost | Use case |

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

@@ -5,6 +5,32 @@ description: How to write prompts that produce cinematic, photorealistic results
 
 # Nano Banana 2 — cinematic & photorealistic prompting
 
+<!-- @card:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Everything between the @card markers is extracted by
+     src/prompts/craft-cards.ts and returned on every cost estimate for this
+     model, so it is the ONE piece of positive craft guidance the agent cannot
+     skip. Measured 2026-08-30: a fact inlined where it cannot be skipped moved
+     compliance 0/8 to 30/32; the same guidance behind a fetch moved nothing.
+     Keep it under 2,400 characters (the build fails above that) and keep the
+     rationale, the receipts and the worked examples in the body below. -->
+<!-- /slates-only -->
+**Card — Nano Banana 2 (Gemini 3.1 Flash Image).** Brief it like a creative director, not a tag list. Structure: `Film still from [director] [genre]. Shot on [camera] with [lens]. [Subject and action]. [3-5 specific visual details]. [Lighting — direction + quality]. [Color palette]. [Film stock]. [1-2 word tone].`
+
+**The five levers**
+1. **Named lens + aperture** beats "shallow depth of field" — `85mm f/1.4`, `135mm f/2.8` (the cheat code for skin), `Panavision anamorphic`, `400mm telephoto`.
+2. **Light by direction and quality**, never "good lighting" — `hard sidelight from a single window, deep falloff`, `overcast north light`, `practical tungsten spill`.
+3. **A named film stock or sensor** carries a whole palette — `Kodak Portra 400`, `Cinestill 800T`, `ARRI Alexa 65`.
+4. **Composition as a shot** — `low angle`, `aerial view`, `rule of thirds with the subject camera-left`, `foreground occlusion`.
+5. **Positive framing only.** Describe what is there. "Empty street", never "no cars"; "unstaged documentary photography", never "not anime".
+
+**Examples**
+- `Film still from a Denis Villeneuve thriller. Shot on ARRI Alexa 65, 85mm f/1.4. A woman in a charcoal wool coat stands at a rain-slick bus stop, breath visible. Hard sodium light from a single overhead lamp, deep falloff into blue night. Kodak Vision3 500T. Isolated.`
+- `Editorial still life on seamless bone paper. 100mm macro, f/8. A cracked ceramic bowl holding three figs. Soft north light from camera-left, one gentle shadow. Muted earth palette. Portra 400 grain. Quiet.`
+
+**Hard constraint:** there is no `negativePrompt` field. Suppress by reframing positively, or inline `without` / `free of`. Knowledge cutoff January 2025 — anything later needs reference images.
+<!-- @card:end -->
+
 Nano Banana 2 is **Gemini 3.1 Flash Image**.<!-- slates-only --> It is the default model behind `slates_generate_image` — the op also exposes `flux-2-max` and `seedream-5-lite`, each with its own prompting skill.<!-- /slates-only --> It is **not** Gemini 3 Pro Image; that is Nano Banana **Pro** (`nano-banana-pro`), a separate model with its own seat.<!-- slates-only --> Verified against the runtime slug map in `slate/src/main/api/google.ts`.<!-- /slates-only --> NB2 is a language model that outputs pixels — brief it like a creative director, not like a Stable-Diffusion tag-soup tool. The single biggest lever for realism: **specificity that mimics how real photographers and cinematographers describe their work**.
 
 Knowledge cutoff: January 2025. Anything after needs explicit reference images.
@@ -78,6 +104,15 @@ Film still from [DIRECTOR] [GENRE]. Shot on [CAMERA] with [LENS]. [SUBJECT and a
 
 These are Stable-Diffusion-era tag soup. The model treats them as low-signal noise. Measured success rate: ~60-70% with these vs ~95%+ with positive description.
 
+<!-- @banned:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Every `backticked` token between the @banned markers is extracted
+     by src/prompts/banned-tokens.ts, inlined verbatim into the slates_generate_image
+     op description (always in context on both surfaces), and matched against every
+     submitted prompt. Editing this list changes what the agent is told AND what it
+     is warned about — keep every entry backticked, and keep prose outside the
+     backticks. -->
+<!-- /slates-only -->
 **Never use:**
 - `8k`, `4k` (as a quality token)
 - `hyperrealistic`, `ultra-realistic`, `photorealistic` standing alone
@@ -86,6 +121,7 @@ These are Stable-Diffusion-era tag soup. The model treats them as low-signal noi
 - `perfect skin`, `flawless`, `airbrushed`, `smooth skin`
 - `cinematic` standing alone — always specify *which cinema* (director, lens, era, stock)
 - `not anime, not cartoon, not 3D` — negation tag soup, replace with a positive style cue
+<!-- @banned:end -->
 
 ## Negative prompting — there is no field
 

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

@@ -5,6 +5,47 @@ description: How to prompt Gemini Omni Flash (Google, via fal). Read before call
 
 # Gemini Omni Flash — prompting
 
+<!-- @card:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Everything between the @card markers is extracted by
+     src/prompts/craft-cards.ts and returned on every cost estimate for this
+     model, so it is the ONE piece of positive craft guidance the agent cannot
+     skip. Measured 2026-08-30: a fact inlined where it cannot be skipped moved
+     compliance 0/8 to 30/32; the same guidance behind a fetch moved nothing.
+     Keep it under 2,400 characters (the build fails above that) and keep the
+     rationale, the receipts and the worked examples in the body below. -->
+<!-- /slates-only -->
+**Card — Gemini Omni Flash.** Two different jobs with OPPOSITE prompt rules, and getting them the wrong way round is the whole failure mode.
+
+**The five levers**
+1. **Editing: short prompt, ONE change, nothing else.** Google's own doc says so and a 2026-07-09 receipt confirms it — a long "keep every frame identical" preamble produced WORSE drift than two sentences.
+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.
+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**
+- Edit: `Small magical flames appear on his fingertips when he snaps his fingers, and vanish when he blows on them. Keep everything else the same.`
+- Generate: `A courier in a yellow shell jacket weaves between stalled cars on a wet arterial road, camera tracking alongside at shoulder height. Overcast flat light, spray from tyres. Rain patters on car roofs, a horn somewhere behind.`
+
+**Hard constraint:** it is a CHEAP DRAFT seat for generation and the EDIT-fidelity winner for footage-synced VFX — never a hero generation shot. Expect a possible jitter or doubled speech beat in the last half second of an edit: trim the tail rather than burning a re-roll.
+<!-- @card:end -->
+
+<!-- @banned:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Every `backticked` token between the @banned markers is
+     extracted by src/prompts/banned-tokens.ts and returned on this model's cost
+     estimate, and every submitted prompt is matched against it. Keep entries
+     backticked and prose outside the backticks. -->
+<!-- /slates-only -->
+**Never use 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
+- harm-to-person framing: `ignite`, `catch fire`, `on fire` applied to a person trips the safety filter
+<!-- @banned:end -->
+
 Google's fast video generation + editing model ("Nano Banana Pro for video" in creator slang — a nickname; it is NOT the NB Pro image model). Carried on fal (`google/gemini-omni-flash*`). 720p only, 24fps, 3–10 second clips, 16:9 or 9:16. **Audio is native and included** — dialogue, SFX, and ambient generate WITH the video at no extra cost.
 
 ## Where it routes

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

@@ -5,6 +5,44 @@ description: How to prompt Seed Audio 1.0 (ByteDance, via fal). Read before call
 
 # Seed Audio 1.0 — prompting
 
+<!-- @card:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Everything between the @card markers is extracted by
+     src/prompts/craft-cards.ts and returned on every cost estimate for this
+     model, so it is the ONE piece of positive craft guidance the agent cannot
+     skip. Measured 2026-08-30: a fact inlined where it cannot be skipped moved
+     compliance 0/8 to 30/32; the same guidance behind a fetch moved nothing.
+     Keep it under 2,400 characters (the build fails above that) and keep the
+     rationale, the receipts and the worked examples in the body below. -->
+<!-- /slates-only -->
+**Card — Seed Audio 1.0.** One plain sentence describing a SCENE, and it returns dialogue, effects and ambience together in one pass. For ONE named voice saying ONE line, `inworld-tts-2` is the seat instead; this one renders the whole room.
+
+**The five levers**
+1. **Write one sentence in plain language.** Describe the room and what is happening in it; the model casts and performs it.
+2. **Name the crowd size, the room size and the distance.** This is the highest-leverage single edit on any bed — unqualified nouns default BIG. "Tiny applause of two or three people at an open mic", not "applause".
+3. **Put the length in the prompt** and make it deliberate.
+4. **Dialogue is performed inside the scene** — write the line as spoken in the room, then re-roll until a take is right and lip-sync against it.
+5. **Describe sounds directly** — "one coffee machine hissing, cutlery somewhere behind the counter" — with the object, the action and where it is.
+
+**Examples**
+- `a diner at 2am, one coffee machine hissing, cutlery somewhere behind the counter, one man says quietly "you're late again". 15 seconds`
+- `nature soundscape, a wide open field, cicadas near, birds mid-distance, one loon far off across water. 20 seconds`
+
+**Hard constraint:** it has NO duration parameter — the length you request is written into the prompt AND is what you are billed, whatever comes back, so choose it deliberately. Kling's `SFX:` / `Ambient noise:` / `Background music:` labels have no parser here and measurably worsen the output. Shot language, camera moves and lighting are video-prompt words the model must ignore. It is not a music model and it cannot produce pixels.
+<!-- @card:end -->
+
+<!-- @banned:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Every `backticked` token between the @banned markers is
+     extracted by src/prompts/banned-tokens.ts and returned on this model's cost
+     estimate, and every submitted prompt is matched against it. Keep entries
+     backticked and prose outside the backticks. -->
+<!-- /slates-only -->
+**Never use** — Kling video syntax has no parser here and measurably worsens the output:
+- `SFX`, `Ambient noise`, `Background music` as labels — describe the sounds directly
+- 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.
 
 ## Where it routes

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

@@ -5,6 +5,44 @@ description: How to prompt Seedance 2.5 and Seedance 2.5 Edit. Read before calli
 
 # Seedance 2.5 — prompting
 
+<!-- @card:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Everything between the @card markers is extracted by
+     src/prompts/craft-cards.ts and returned on every cost estimate for this
+     model, so it is the ONE piece of positive craft guidance the agent cannot
+     skip. Measured 2026-08-30: a fact inlined where it cannot be skipped moved
+     compliance 0/8 to 30/32; the same guidance behind a fetch moved nothing.
+     Keep it under 2,400 characters (the build fails above that) and keep the
+     rationale, the receipts and the worked examples in the body below. -->
+<!-- /slates-only -->
+**Card — Seedance 2.5.** Shares 2.0's grammar exactly (subject binding, camera vocabulary, externalised emotion, inline constraints — read `slates-prompting-seedance` for those). Two things are different, and both matter.
+
+**The five levers**
+1. **Timestamps work here** — integer seconds, and the model acts on them: `[0-4] she reads the letter. [4-9] she folds it and looks up.` 2.0 ignores exactly this syntax.
+2. **Length is the reason to be here** — takes up to 30 seconds, where 2.0 stops at 15. Write the beats as `[0-6]`, `[6-12]`, `[12-18]`; do not hope for them.
+3. **Up to 30 image references**, and a multi-view image can serve as ONE subject reference (up to 5 subjects). 2.0 cannot do either.
+4. **Audio-only references are accepted** without an image or video alongside — the only Seedance seat that takes one.
+5. **Keep the 2.0 discipline**: one camera move per beat (`slow track right`, `handheld follow`), physical action instead of stated emotion, and quality asked for in the image-quality slot vocabulary — `rich details`, `natural colors`, `cinematic texture`, `soft lighting`.
+
+**Examples**
+- `[0-6] Wide shot, <Subject_1>@<Image_1> crosses an empty car park toward a idling van, slow track right. [6-12] Medium, she stops as the driver's window comes down. [12-18] Close-up, she looks off past the lens and does not answer. Rich details, natural colors. Keep it subtitle-free.`
+- `[0-10] A single continuous handheld follow behind a courier climbing a fire escape, rain. [10-20] She reaches the landing, turns, and the city opens behind her. Cinematic texture, soft lighting.`
+
+**Hard constraint:** it is the EXPENSIVE seat and it has NO 4K — 480p/720p/1080p only, and dearer than 2.0 at every resolution they share. It is a second seat, never an upgrade. Long takes multiply cost linearly: quote a 30-second take before you fire it.
+<!-- @card:end -->
+
+<!-- @banned:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Every `backticked` token between the @banned markers is
+     extracted by src/prompts/banned-tokens.ts and returned on this model's cost
+     estimate, and every submitted prompt is matched against it. Keep entries
+     backticked and prose outside the backticks. -->
+<!-- /slates-only -->
+**Never use** (2.5 reclassifies the task and fails a fresh generation on these):
+- `edit`, `extend`, `continue the video`, `same video but` — they make the provider read a fresh generation as an edit
+- `85mm`, `f/1.4`, `Portra 400` and any other lens, aperture, film-stock or camera-body token — image-model vocabulary, a Seedance anti-pattern on both seats
+<!-- @banned:end -->
+
 **Read `slates-prompting-seedance` first.** The prompt GRAMMAR is the same model family: the
 8-slot advanced formula, subject binding by `<Subject_N>@<Image_N>`, camera vocabulary,
 externalised emotion, inline constraint words, the anti-twin fix. None of it is restated here.

package/skills/slates-prompting-seedance.md

@@ -5,6 +5,32 @@ description: How to prompt Seedance 2.0 (ByteDance video model). Read before cal
 
 # Seedance 2.0 — prompting
 
+<!-- @card:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Everything between the @card markers is extracted by
+     src/prompts/craft-cards.ts and returned on every cost estimate for this
+     model, so it is the ONE piece of positive craft guidance the agent cannot
+     skip. Measured 2026-08-30: a fact inlined where it cannot be skipped moved
+     compliance 0/8 to 30/32; the same guidance behind a fetch moved nothing.
+     Keep it under 2,400 characters (the build fails above that) and keep the
+     rationale, the receipts and the worked examples in the body below. -->
+<!-- /slates-only -->
+**Card — Seedance 2.0.** Not copywriting — an ENGINEERING instruction to a spatial layer and a temporal layer: who, in what scene, doing what, how the camera moves, and in what order. Multi-beat work is a `Shot 1 / Shot 2 / Shot 3` storyboard.
+
+**The five levers**
+1. **Bind every subject to its reference** — `<Subject_1>@<Image_1>` — and keep the descriptions identical across shots. Unbound subjects are where twins come from.
+2. **Shot sizes and camera MOVES, not lens data** — `medium close-up`, `slow push in`, `handheld follow`, `whip pan`. One primary move per shot.
+3. **Externalise emotion as physical action.** Not "she is nervous": `she turns the ring on her finger twice, then stops`.
+4. **Use the image-quality slot vocabulary** for quality — `HD`, `rich details`, `cinematic texture`, `natural colors`, `soft lighting`. That is the officially sanctioned way to ask.
+5. **Constraints go INLINE**, led by the official templates — `keep it subtitle-free`, `do not generate a watermark`, `avoid jitter and bent limbs`, `avoid temporal flicker`.
+
+**Examples**
+- `Shot 1: medium shot, <Subject_1>@<Image_1> steps out of the freight lift into a wet loading bay, slow push in. Shot 2: close-up, she turns the ring on her finger twice and stops, handheld. Rich details, cinematic texture, natural colors. Keep it subtitle-free.`
+- `Single continuous take. Wide shot of a fishing skiff crossing a grey swell, camera tracks from the starboard rail. Spray hits the lens once. Soft lighting, natural colors, film-grain texture. Avoid jitter and bent limbs.`
+
+**Hard constraint:** NO timestamps — 2.0 ignores them and answers only to shot numbers (2.5 acts on them). No lens, aperture, film stock or camera body: that is image-model vocabulary and a Seedance anti-pattern. There is no negativePrompt field.
+<!-- @card:end -->
+
 ByteDance's video model — first-party via **BytePlus ModelArk** (credits only, no BYOK). Audio always generated alongside the video. Single model `seedance-2` across the full resolution ladder (480p / 720p / 1080p / native 4K — 4K video is Pro-only, default 1080p), 4–15s, first+last frame, and up to 9 reference images / 3 videos / 3 audio clips.
 
 > **How to read this file.**
@@ -339,7 +365,16 @@ Speed ramps and slow-motion are supported in natural language, and `fast` is wid
 the lid opens in slow-motion · the blade whips through the air
 ```
 
-**Slop tokens to avoid:** `epic`, `amazing`, `beautiful`, `lots of movement`, `8K`, `masterpiece`, `trending on artstation`. These are quality *incantations* — the officially sanctioned way to ask for quality is the image-quality slot vocabulary in Part 1 (`HD`, `rich details`, `cinematic texture`, `natural colors`, `soft lighting`).
+<!-- @banned:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ — same contract as the anti-list in slates-prompting-nano-banana-2.
+     Extracted by src/prompts/banned-tokens.ts into the slates_generate_video op
+     description and matched against submitted prompts. The RECOMMENDED vocabulary
+     below sits OUTSIDE the markers on purpose — it is backticked too. -->
+<!-- /slates-only -->
+**Slop tokens to avoid:** `epic`, `amazing`, `beautiful`, `lots of movement`, `8K`, `masterpiece`, `trending on artstation`.
+<!-- @banned:end -->
+These are quality *incantations* — the officially sanctioned way to ask for quality is the image-quality slot vocabulary in Part 1 (`HD`, `rich details`, `cinematic texture`, `natural colors`, `soft lighting`).
 
 ## Style block at the end
 

package/skills/slates-prompting-seedream-5-lite.md

@@ -5,6 +5,44 @@ description: How to prompt Seedream 5 Lite (ByteDance image model — the cheap
 
 # Seedream 5 Lite — prompting
 
+<!-- @card:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Everything between the @card markers is extracted by
+     src/prompts/craft-cards.ts and returned on every cost estimate for this
+     model, so it is the ONE piece of positive craft guidance the agent cannot
+     skip. Measured 2026-08-30: a fact inlined where it cannot be skipped moved
+     compliance 0/8 to 30/32; the same guidance behind a fetch moved nothing.
+     Keep it under 2,400 characters (the build fails above that) and keep the
+     rationale, the receipts and the worked examples in the body below. -->
+<!-- /slates-only -->
+**Card — Seedream 5 Lite.** The cheap volume seat: flat-priced at every resolution, which makes it the right default for storyboard passes, variant grids and look-dev. Structure, most important first: `Subject + Style + Composition + Lighting/Atmosphere + Technical`.
+
+**The five levers**
+1. **Lead with the subject.** Earlier words weigh more; close with the camera and technical detail.
+2. **Keep it 30-100 words.** Unlike models that reward verbosity, this one gets confused by very long prompts. Focused beats exhaustive.
+3. **Name the composition** — `symmetrical composition`, `rule of thirds`, `foreground detail with blurred background`, `overhead perspective`.
+4. **Name the light as a named condition** — `golden hour`, `dramatic side lighting`, `soft diffused light`, `moody low-key`, `bright high-key`.
+5. **Quote in-image text.** It takes quoted strings for posters and layouts, which is half of why it is the drafting seat.
+
+**Examples**
+- `Professional headshot of a female CEO, short blonde hair, confident expression, navy suit, neutral office background. Studio lighting, shallow depth of field, high-end corporate photography, shot on 85mm.`
+- `A rain-soaked night market stall, cinematic, rule of thirds with the vendor camera-right, foreground steam blurred, moody low-key lighting with practical neon, shot on 35mm.`
+
+**Hard constraint:** it is the DRAFTING seat, not the hero seat. Explore here, then re-run the winner on Nano Banana 2 or FLUX.2 Max for the locked shot.
+<!-- @card:end -->
+
+<!-- @banned:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Every `backticked` token between the @banned markers is
+     extracted by src/prompts/banned-tokens.ts and returned on this model's cost
+     estimate, and every submitted prompt is matched against it. Keep entries
+     backticked and prose outside the backticks. -->
+<!-- /slates-only -->
+**Never use:**
+- `masterpiece`, `best quality`, `highly detailed`, `8k`, `award-winning` — quality incantations, not description
+- a prompt past about 100 words: this model gets confused by very long prompts, and focused beats exhaustive
+<!-- @banned:end -->
+
 ByteDance's Seedream image model, Lite tier, routed via fal.ai. In Slates: `slates_generate_image` with `model: seedream-5-lite` (REQUIRES projectId — no headless path). **Flat-priced regardless of resolution** — the cheapest image model in Slates, which makes it the right default for high-volume drafting, storyboard exploration, and variant grids. Call `slates_estimate_generation_cost` for the current number; never quote prices from memory. Less censored than Nano Banana 2.
 
 **When to pick it:** lots of frames cheap (storyboard passes, 3-4 variant exploration), posters/layouts with text, quick look-dev. Step up to NB2 or FLUX.2 Max for the locked hero shot.