@slatesvideo/shared 0.5.4 → 0.5.6

package/exports/slates-prompt-builder/generated/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: slates-prompt-builder
+description: Turn a plain-language idea into a paste-ready AI video or image prompt using the production Slates prompting guides for Seedance 2.0, Kling 3.0, and Nano Banana 2. Use for video prompts, image prompts, shot planning, character-reference preparation, ads, brand films, product videos, talking heads, or any request that needs generation-ready visual direction.
+---
+
+<!-- Generated from the Slates production prompting guides. Do not edit — this file is rebuilt from source. -->
+
+# Slates Prompt Builder
+
+Turn the user's idea into the exact prompt to paste into their generation tool. The deliverable is the prompt, not a lecture about prompting.
+
+This portable skill is deliberately thin. Its reference files are generated directly from the same production skills used by the Slates MCP server, CLI-installed Claude skills, and Studio Agent. Treat those references as authoritative; never recreate their rules from memory.
+
+## The curated stack
+
+<!-- @generated:model-routing -->
+| Model | Canonical route | Guide |
+|---|---|---|
+| **Kling 3.0** | DEFAULT general-purpose video model — cost-effective, strong start-frame adherence (identity/layout/text), acting, dialogue, lip-sync, any aspect ratio. Escalate to Seedance for physics. In the Motion Transfer / Lip Sync tools, Kling (MC / lip-sync / avatar) is the cheap utility lane; Seedance is the premium single-pass lane. | `reference-kling.md` |
+| **Seedance 2.0** | PREMIUM video tier — route here the moment physics, effects, destruction, or scale matter, and for hero shots. VIDEO-ONLY: cannot generate standalone images (use NB2/FLUX.2/Seedream for those). Up to 9 ingredient images. Strong I2V / own-footage restyle. Native 4K, but 4K VIDEO is a Pro-only tier gate (base maxes at 1080p; server returns PRO_REQUIRED) — default 1080p unless the user is on Pro. Also the PREMIUM engine inside the Motion Transfer and Lip Sync tools (single-pass: driving video / dialogue are native conditioning signals — better motion fidelity, natural speech, voice cloned from a video source; video references bill input+output seconds). | `reference-seedance.md` |
+| **Nano Banana 2 (Gemini 3.1 Flash Image)** | Default image model. 14 refs hard cap (10 object + 4 character). Brief it like a creative director, not tag soup. No negativePrompt field — use positive reframing. Best image start-frame for legible text. Knowledge cutoff Jan 2025. | `reference-nano-banana.md` |
+<!-- @end:model-routing -->
+
+If the user names a model, use it. Otherwise route by the generated table above.
+
+## Workflow
+
+1. Read the brief. A sentence or a full storyboard is enough.
+2. If intent is clear, take the fast path: choose the model and write the prompt immediately. Do not interrogate the user for optional detail.
+3. Load the matching generated reference file before writing:
+   - `reference-seedance.md`
+   - `reference-kling.md`
+   - `reference-nano-banana.md`
+4. For recurring characters, identity consistency, or character-sheet preparation, also load `reference-character.md`. It owns the exact sheet architecture, background plate, lighting, and evaluation gate.
+5. For conflict, creatures, crowds, destruction, weapons, public figures, or young characters, also load `reference-content-policy.md` and construct the scene safely from the first word.
+6. If a referenced production guide mentions Slates operations or billing and those tools are not available, use its prompting doctrine and ignore only the transport-specific instruction. Never invent a tool call.
+7. Return one paste-ready prompt. If the concept genuinely requires multiple generations, return the smallest ordered chain (for example: Nano Banana 2 start frame, then Kling motion prompt).
+
+## Output
+
+```text
+--- PROMPT (<Model>) ---
+<paste-ready prompt>
+--- END ---
+```
+
+Then give no more than three short notes covering only decisions the user needs to understand: the model route, a non-obvious constraint, or how references should be attached. Do not expose chain-of-thought, internal scoring, density maps, or a shot table unless the user explicitly asks for one.
+
+## Hard boundaries
+
+- Never restate a model's syntax from memory; load its generated reference.
+- Never hand-invent a character-sheet prompt when `reference-character.md` already defines the canonical one.
+- Never silently add weather, props, style, or camera movement the user did not request. If you apply a sane default, name it briefly in the notes.
+- Never carry image-model lens, aperture, film-stock, or camera-body syntax into Seedance. Follow the model reference's translation rule.
+- Never second-stamp Seedance shots. Follow its official `Shot 1 / Shot 2 / Shot 3` structure.
+
+## Provenance
+
+Every `reference-*.md` file in this package is generated from `@slatesvideo/shared`. If a generated reference and this router appear to disagree, the generated reference wins and the router must be corrected at its canonical source.

package/{skills/slates-character-turnaround.md → exports/slates-prompt-builder/generated/reference-character.md}

@@ -1,7 +1,6 @@
----
-name: slates-character-turnaround
-description: Build a Slates character from a reference image — generate its identity reference sheet and bind it to the character so the card updates live. Use when the user wants to "create a character", "build a character from this image", "generate a turnaround for X", or starts any storyboard flow that needs consistent character references.
----
+<!-- Generated from the Slates production prompting guides. Do not edit — this file is rebuilt from source. -->
+
+> **This is the real thing.** Every rule below is the working doctrine Slates runs in production against this model — not a summary written for a handout. Slates automates it end to end; the doctrine works by hand too.
 
 # Character identity sheet — Slates workflow
 
@@ -23,59 +22,50 @@ Every reference rule below is a corollary of that one sentence, which is why "pr
 
 ## The shape: ONE sheet, three panels
 
-Slates generates **one identity sheet per character**, bound to the character's turnaround slot:
+Slates generates **one identity sheet per character**, bound as the character's canonical reference:
 
 | Panel | What it carries |
 |---|---|
 | **Chest-up portrait, three-quarter angle, largest panel (~25–30% of the sheet)** | The face. **This is the only place the model reads facial identity from** — every detail it will ever know comes from those pixels, so it gets the resolution. Off-frontal, never dead-on: an angled head reads its volume instantly. |
-| **Full-body front, relaxed A-pose** | Build, proportion, wardrobe |
-| **Full-body back** | Hair fall and the back of the outfit — the only panel where either reads |
+| **Full-body front, relaxed A-pose — cropped at the collarbone, just the face cropped out** | Build, proportion, wardrobe. The face is cropped off on purpose: a front-facing body panel renders a ~40px face that can't match the portrait's, so the sheet would carry two competing identities and the model averages them. **Only the face** — neck, arms and hands render as skin. |
+| **Full-body back, head and hair visible** | Hair fall and the back of the outfit — the only panel where either reads. Keeps its head because there's no face to compete with. |
 
-On a deep neutral-grey plate (`#3a3a3c`), flat and shadowless, with catchlights in the eyes, irises never crushed to black, surface texture at the medium's own natural level of detail, broken symmetry, and no over-clean 3D-game-model look.
+The rule is **kill every competing rendering of the FACE, not every head** — which is why exactly one body panel is headless.
 
-**The sheet inherits the source's medium** — photo, anime, illustration, painterly, 3D render — unless the user explicitly asks for a transform. None of the craft clauses above override that: they ask for *readable* eyes and *material-looking* surfaces within whatever medium the character is in, not for photorealism.
+On a deep neutral-grey plate (hex `3a3a3c`, emitted without the `#` — see the sigil warning in Don'ts), flat and shadowless, with catchlights in the eyes, irises never crushed to black, surface texture at the medium's own natural level of detail, broken symmetry, and no over-clean 3D-game-model look. Expression is **a slight natural smile with the teeth just visible** — a closed mouth carries no dental information, so every downstream smiling shot invents teeth, and teeth are person-specific.
 
-**Why one sheet and not two.** Every `@character` mention pushes *all* of that character's bound sheets into one reference group, so a two-sheet character costs **two reference slots on every generation**. Against real caps that is brutal — Kling 3.0 takes 4 ingredients (2 characters, zero room for an environment), NB2 has 4 character slots, Seedance 9. One sheet each **doubles the cast you can stage on every model.** It also takes competing facial renderings from six down to two, which is what stops a face from averaging (see the general law above), and it halves the per-character sheet spend.
+**Two carve-outs, scoped differently on purpose.** Non-human characters get a natural neutral expression instead of a smile — that one is scoped by *having a human mouth*, so a bipedal robot or humanoid alien is covered. Quadrupeds and non-bipedal characters get a natural standing stance with the head shown on both body panels — that one is *anatomical*. **Both are conditionals the image model evaluates against your reference; neither is a code branch, because the op has no character-kind input.**
+
+**The sheet inherits the source's medium** — photo, anime, illustration, painterly, 3D render — unless the user explicitly asks for a transform. None of the craft clauses above override that: they ask for *readable* eyes and *material-looking* surfaces within whatever medium the character is in, not for photorealism.
 
-**The expression slot still exists** and is still read — characters built before this change have one bound and keep working. Generate one only when a character genuinely needs a dedicated expression range, and tell the user it costs a reference slot on every shot from then on.
+**Why one sheet.** Every `@character` mention attaches that character's canonical identity image, so each character costs one reference slot. It also reduces competing facial renderings to **one** — with the front panel headless and the back panel turned away, the portrait is the only face on the sheet, so there is nothing left to average.
 
 ## Workflow
 
-### 1. Get the reference
+### Get the reference
 The user has either:
 - Pasted/uploaded an image of the character (real person, drawing, AI render).
 - Described the character in text only.
 
-If image: upload it as a reference (`slates_upload_reference_image`).
+If image: upload it as a reference.
 If text only: generate from prompt-only — less consistent, so warn the user.
 
-### 2. Create the character record
-`slates_create_character` with:
-- `name` (ask if not given)
-- `description` — 1-2 sentences, *visual* only ("tall, dark hair, scar over left eye"), not personality.
-- `style` — leave as the source's own medium by default. Only name a transform if the user wants one (e.g. anime → realistic).
+### Generate the sheet
 
-### 3. Generate the sheet
-`slates_generate_character_sheets` with `characterId`, `projectId`, and `baseAssetId` (the source portrait).
-
-**Do not hand-write the sheet prompt.** Slates builds it from the canonical template in `@slatesvideo/shared/prompts` (`buildCharacterTurnaroundPrompt`) — panels, plate, lighting and craft clauses included — and appends your `userNotes`. Use `userNotes` for what the template can't know: *"use the woman on the left"*, *"keep the scar on the right cheek"*. A hand-written prompt is a fork of the template and will drift from it.
-
-- Estimate cost first with `slates_estimate_generation_cost` and announce in **credits** — never quote a price from memory. Default is Nano Banana 2 at 2K. **Never 4K** — no identity gain at sheet scale, wasted credits.
+- Default to Nano Banana 2 at 2K. **Never 4K** — no identity gain at sheet scale, wasted spend.
 - When the result returns inline, **evaluate it before binding**:
   - Is the portrait clearly the largest panel, and is it off-frontal?
-  - Is it the same person across all three panels?
+  - **Is the front body panel cleanly headless** — an empty collar above a normally rendered body, no partial face, no floating jaw, no smeared neck stump? A botched crop is worse than no crop.
+  - **Is the body still there?** Neck, forearms and hands rendered as skin, not an empty outfit floating on nothing. A hollow garment means the invisible-mannequin genre ran unbounded.
+  - Do the body panels read as the same build, wardrobe and hair as the portrait?
   - Catchlights present, irises readable rather than black holes?
   - Is it in the source's medium, and does it read as *that* medium done well — or has it drifted toward the over-clean game-model look?
   - Plate a flat deep grey, not white and not black?
 - If off: one focused refinement, then regenerate. The sheet is upstream of everything — it is worth a re-roll that a scene frame is not.
-- The op binds the result to the turnaround slot automatically.
-
-### 4. Hand back
-> "Character {name} ready — identity sheet bound. Use `@{name}` in any prompt and Slates attaches it and names it inline, so the face stays consistent."
 
 ## How the reference gets used at scene time
 
-Slates cites the sheet inline under the character's name — `{name} (image N)` — in the exact order it sends references. That **name** is the anti-averaging lever, and it is each model's own official mechanism (NB2: "assign a distinct name"; Seedance: `Reference <Subject_N> in <Image_N>`; Kling: reuse a fixed label verbatim). If a character has both slots bound, both are cited under the *same* name so the model reads them as one person.
+Slates cites the sheet inline under the character's name — `{name} (image N)` — in the exact order it sends references. That **name** is the anti-averaging lever, and it is each model's own official mechanism (NB2: "assign a distinct name"; Seedance: `Reference <Subject_N> in <Image_N>`; Kling: reuse a fixed label verbatim).
 
 Critically, the app injects **no** wardrobe, expression, or lighting directive. The user's scene prompt owns all of that — which is why `@{name}` dropped into a movie-still injection keeps the still's own clothing and lighting instead of dragging the sheet's.
 
@@ -83,8 +73,11 @@ Critically, the app injects **no** wardrobe, expression, or lighting directive.
 
 - **Don't** studio-light, white-background, or black-background the sheet. White bleeds into the video and washes out the location; black eats edge detail. Flat, even, shadowless light on a deep neutral grey.
 - **Don't** hand-write the sheet prompt when the op will build it — that is how the template and the shipped prompt fork.
-- **Don't** generate an expression sheet by reflex. It is opt-in now, and it costs a reference slot on every downstream shot.
-- **Don't** skip binding. The slots are what the storyboard pipeline reads — an unbound asset doesn't help downstream.
+- **Don't** create a second character image. One canonical identity is what the storyboard pipeline reads.
+- **Don't** skip binding. An unbound asset doesn't help downstream.
 - **Don't** invent character details. Stick to what's in the reference image and the user's description.
+- **Don't** describe the front panel's crop as an absent head — in `userNotes` or any hand-written variant. The template asks for it as *framing*: **"cropped at the collarbone, an invisible-mannequin presentation with just the face cropped out"**, a standard e-commerce genre with deep training data. **"the head not shown" is a hard 422 on gpt-image-2** — fal returns `content_policy_violation` with `loc: ["body","prompt"]`, so the text is rejected before any image is read, because an anatomical absence reads as gore to OpenAI's classifier. It passed NB2, which is why the original receipt looked safe: **it was model-scoped.** State an exclusion as a framing choice, never as a missing body part.
+- **Don't** invoke the invisible-mannequin genre without bounding it to the face. **"an invisible-mannequin presentation where the clothing holds its own shape" removed all the skin** — no neck, no hands, no forearms, a garment floating on nothing — because that *is* the e-commerce genre in full: an empty outfit. **"with just the face cropped out"** keeps the anchor and bounds it. Generalises: a genre anchor imports the whole genre, so name what STAYS, not only what goes.
+- **Don't** put `#` or `@` anywhere in prompt text. Both are reference-token sigils in the desktop prompt composer and an unresolved one is **silently deleted** — no error, no log, just missing words. `#3a3a3c` reached fal as `background ()` on a real 2026-07-30 request, meaning the plate value had never been delivered to any model since the composer shipped. Write hex values bare.
 - **Don't** use 4K — wastes credits, no quality gain at sheet scale.
-- **Don't** feed a multi-view sheet into a Seedance shot that has **several characters in frame** without binding each character to its image and appending the anti-twin constraint — ByteDance documents multi-view assets as a cause of duplicate characters. See `slates-prompting-seedance`.
+- **Don't** feed a multi-view sheet into a Seedance shot that has **several characters in frame** without binding each character to its image and appending the anti-twin constraint — ByteDance documents multi-view assets as a cause of duplicate characters. See `reference-seedance.md`.

package/exports/slates-prompt-builder/generated/reference-content-policy.md

@@ -0,0 +1,75 @@
+<!-- Generated from the Slates production prompting guides. Do not edit — this file is rebuilt from source. -->
+
+> **This is the real thing.** Every rule below is the working doctrine Slates runs in production against this model — not a summary written for a handout. Slates automates it end to end; the doctrine works by hand too.
+
+# Content-policy-safe construction — read before any risk-surface prompt
+
+Don't depict the harm — depict the energy, the aftermath, the threat, or the scale. Build the scene safe from the first word.
+
+Write scenes that hit full cinematic impact without ever *needing* to depict prohibited content. This is a craft move, not a compromise — the substitutions below usually read as more cinematic, not less, and they keep your generation from getting silently rejected or degraded by the model's filter. A standoff is more tense than a massacre; an evacuated city is eerier than a crowd in panic; a roar lands harder than a kill. Load this whenever a prompt involves conflict, creatures, crowds, destruction, weapons, or young characters.
+
+## Substitution table
+
+| Avoid | Use instead |
+|---|---|
+| Civilians in panic, crowds fleeing under debris | An evacuated / empty city; abandoned streets; a lone figure for scale |
+| Weapons firing into buildings or at people | Energy-discharge standoffs, searchlights sweeping, charged auras, shockwaves with no muzzle fire |
+| Creatures tearing into each other, gore | A grapple / standoff — roars, near-misses, circling, an energy clash; combat that stays contained (in/on the water, never lifting into the air) |
+| Destruction with people in harm's way | Destruction in uninhabited terrain — glaciers, deserts, ruins, open sea, evacuated zones |
+| Realistic guns as the focus | Stylized / fantasy implements, weapons slung-not-fired, the weapon as silhouette or prop only |
+| Blood, wounds, death | Impact light, dust, debris, buckling and collapse, a silhouette dropping out of frame |
+| Real, named public figures | Original / anonymous characters |
+| Real brand logos | Original or generalized branding — except the user's own product, which is the whole point of a brand film |
+
+## The safe benchmark
+
+When a scene starts drifting risky, pull it back toward this shape: **one original creature, in a generalized monument or amphitheatre, in daylight, no weapons present, performing expressive action** (rising, roaring, spreading wings). Original design, generalized location, daylight, expressive rather than violent. That's the confirmed-safe envelope — most epic ideas re-stage into it without losing the punch.
+
+## Containment rule — it doubles as a physics win
+
+Give any creature or combat scene a **containment rule** that grounds the physics at the same time:
+- "the fight STAYS at the sea surface — they breach, dive, grapple, submerge, but never fly or get carried into the air"
+- "boss scale locked ~2.5 human-heights, NOT kaiju-giant"
+- "destruction stays in the evacuated valley"
+
+This improves coherence (the model isn't inventing absurd escalation) AND keeps the scene inside policy — same clause buys both.
+
+## Scale and stakes without harm
+
+Epic stakes come from environmental danger and reaction, not depicted victims: tiny figures diving clear of *collapsing* terrain (not being crushed), a war-horn over an *empty* field, an army *scrambling* across a frozen valley as a titan tears free of a glacier. The danger is the environment; the figures are reacting, not dying. Snow plumes, glowing runes, splintering ice, shockwaves, and dust carry the chaos.
+
+## Minors — hard rule
+
+Never write romantic, sexual, or suggestive content involving or directed at minors, and never anything that sexualizes a young-presenting character. Any scene with children stays wholesome and age-appropriate. Non-negotiable — it overrides every stylistic goal.
+
+## Pre-flight (run before delivering any risk-surface prompt)
+
+- [ ] No civilians depicted in panic/harm; crowds are evacuated or absent.
+- [ ] No weapons firing at people/buildings; threat is energy / searchlight / silhouette.
+- [ ] No creature-on-creature or creature-on-person gore; combat is grapple / standoff / roar, contained.
+- [ ] Destruction is in uninhabited / evacuated terrain.
+- [ ] Creatures are original ("not based on any franchise"); no real public figures; no real brand logos except the user's own product.
+- [ ] Anything with children is wholesome and age-appropriate.
+
+If a box fails, apply the substitution table before writing the prompt.
+
+## Editing real footage (Kling O3 edit / Omni Flash edit) — real people in the SOURCE
+
+Video edit takes the user's own footage, which often contains real people. Rules:
+
+- The user must hold rights/consent for any real person's likeness in footage they edit — ask once when it's clearly someone other than the user, then proceed.
+- Kling's video-to-video filter behavior on real faces is **not yet verified** (unlike Seedance, where the consent-gated real-face route is confirmed). If an edit of real-person footage is rejected by the provider, do NOT retry-spam variations — tell the user the filter blocked it and offer a no-face crop/segment or an AI-character swap instead.
+- **Omni Flash: own-footage editing of the uploader's own face PASSED live 2026-07-09** (real talking-head clip, edited on our fal route) despite Google's documented "recognizable people" restriction — treat that restriction as aimed at third-party/public figures, but expect probabilistic refusals and never promise passage.
+- Never use edit to put a real, named public figure into a scene, or to make someone appear to say/do something they didn't. Faceless b-roll (hands, products, landscapes, crowds-from-behind) edits freely.
+
+## Gemini / Omni Flash filter regime (video gen + edit) — receipts 2026-07-09
+
+Google's filter is its own regime (stricter than fal-hosted Kling about harm-to-a-person, looser than BytePlus about faces). Live receipts:
+
+| Blocked (`content_policy_violation`) | Passed |
+|---|---|
+| "his fingertips **ignite** with a small real flame" (fire ON a body part = harm) | "small **magical** flames appear on his fingertips … vanish when he blows on them" |
+
+- **Harm-to-person framing is the tripwire**, not the effect itself. Reframe body-contact effects as magical / supernatural / harmless VFX: "magical flames", "a glowing aura", "sparks of light dance on". Avoid ignite / burn / on fire / catch fire applied to a person.
+- **Never use a real object as a metaphor** — "candle-like flame" rendered a literal candle in the subject's hand. Describe the effect, not an object that resembles it.
+- The block is a 422 refund (no credits lost) and arrives mid-generation — one reframe per the substitution mindset above, don't retry-spam.

package/exports/slates-prompt-builder/generated/reference-kling.md

@@ -0,0 +1,212 @@
+<!-- Generated from the Slates production prompting guides. Do not edit — this file is rebuilt from source. -->
+
+> **This is the real thing.** Every rule below is the working doctrine Slates runs in production against this model — not a summary written for a handout. Slates automates it end to end; the doctrine works by hand too.
+
+# Kling V3.0 — prompting
+
+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).
+
+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.
+
+## Subject definition rule (verbatim, fal blog)
+
+> "Define your core subjects clearly at the beginning of the prompt and keep descriptions consistent across shots."
+
+## Dialogue syntax
+
+```
+Character says, "exact words here"
+```
+
+Use quotation marks for precise speech. Languages (Omni only): EN, ZH, JA, KO, ES.
+
+## Voice direction formula (Omni)
+
+```
+Gender + Age Range + Voice Quality + Speech Rate + Emotional Tone + Language
+```
+
+Example:
+```
+[Character A: Detective, mid-40s, raspy voice, slow cadence, weary]: "I've seen this before."
+```
+
+Tone phrases that fire:
+- `speaking in a hushed, trembling whisper`
+- `shouting with commanding authority`
+- `clear, fearful voice`
+- `with a trembling voice, "I'm scared"`
+
+## The `Immediately` keyword (Omni only)
+
+Without `Immediately`, Kling adds a natural conversational beat between speakers. With it, dialogue is back-to-back. Use when timing matters.
+
+```
+[Alice]: "Get down!" Immediately, [Bob]: "Where?"
+```
+
+## Speaker label discipline
+
+Unique labels per character. **No pronouns or synonyms after first introduction** — they cause voice drift.
+
+✅ `[Character A: Black-suited Agent]` ... `[Character A: Black-suited Agent]: "Stop."`
+❌ `[Agent]... then he says...`
+
+## Multi-character dialogue (Omni)
+
+```
+Alice says in English, "Hello!" Then Bob replies in Spanish, "¡Hola!"
+```
+
+## Sound effects, ambient noise, music
+
+```
+SFX: thunder cracks, footsteps approaching
+Ambient noise: city traffic, birds chirping, ocean waves
+Background music: tense orchestral strings, low cello
+```
+
+SFX accepts physical-cause specificity:
+- ✅ `SFX: heavy boots on wet pavement, distant siren wailing`
+- ❌ `SFX: footsteps`
+
+## Image-to-video guidance
+
+**Verbatim (fal blog):**
+> "Treat the input image as an anchor. Kling 3.0 excels at preserving the identity, layout, and text details. Focus prompts on how the scene evolves *from* the image: subtle movements, camera motion, or environmental changes."
+
+**Don't re-describe what's already in the image.** Focus on motion, changes, evolution.
+
+## Multi-shot — what makes them hit
+
+**Hard cap: total duration ≤ 15s across all shots. Max 6 cuts.**
+
+Hit conditions:
+- Shot labels are explicit: `Shot 1:`, `Shot 2:`
+- One primary action per shot
+- Subject described identically in each shot block
+- Camera move per shot is **one verb**, not a chain
+- Per-shot blocks: 30-60 words
+
+Miss conditions:
+- Compressing narrative into one paragraph
+- Pronoun-only references after the first shot
+- 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)
+
+Upload 2-4 multi-angle reference photos per character/object. Tag inline:
+
+```
+@element1 is the protagonist (refs: front, side, back angles).
+@element2 is the antagonist.
+```
+
+## Reference discipline (character / environment refs)
+
+<!-- @inject:references-read-literally -->
+> **The general law: the model reads a reference literally.**
+> A reference image is not a suggestion. Whatever is baked into it — lighting, medium, texture, symmetry, competing identities — is read as a **property of the subject** and reproduced downstream. A baked rim light tints every shot made from that sheet. A sheet that looks like a 3D game render gets animated like game footage. Two competing renderings of one face get averaged into a third face.
+
+Every reference rule below is a corollary of that one sentence, which is why "prep the reference" beats "prompt around the reference" every time:
+
+- **Flat, plain identity refs** — because scene lighting in the sheet becomes scene lighting in the output (Slates' own receipt: a studio-lit sheet produced a subject that looked green-screen-pasted in front of mountains).
+- **One authoritative rendering per subject** — because the model cannot tell which panel is the real one. ByteDance documents this failure directly: multi-view character assets "confuse the model's character recognition, causing it to generate duplicate characters of the same appearance."
+- **No 3D-game-render look in a reference** — the model recognizes the render mood and inherits its motion character, so the *animation* comes out looking like game footage. This is not a taste rule; it is the same literal-reading mechanism applied to the temporal layer.
+- **Break perfect symmetry** — mirrored faces and dead-square framing read as synthetic, and the model preserves that reading rather than correcting it.
+
+**What this means in practice:** when output is wrong in a way that tracks the *subject* rather than the *scene* — the lighting is wrong the same way in every shot, the face drifts, the material looks synthetic everywhere — fix the reference, not the prompt. Prompting around a baked-in property is the expensive way to lose.
+<!-- @end:references-read-literally -->
+
+<!-- @inject:reference-rules-core -->
+Identity = a few flat-lit neutral angles; one reference per role, named inline; 2-4 refs not 12; describe environments instead of feeding a grid.
+
+1. **2-4 strong references beat both extremes.** Not 1 (warps toward itself), not 12 (averages worse). Start with 2-3 focused refs — each one adds context AND another variable to balance.
+2. **One reference per ROLE, named in the prompt** — identity / style-grade / environment. The model does **not** infer a reference's role from its position in the list; the inline name carries it. Same-role competitors drift (two "identity" refs of different people blend into a third face). Slates composes the naming for you from your `@mentions` / `#tags` — you never hand-write role labels.
+3. **One identity sheet per character, named inline.** A character's identity is a single asset (dominant portrait + body panels), so attach that one asset rather than a pile of views: **fewer competing renderings of a face is better, because the model cannot tell which one is authoritative and averages them.** Slates cites it as `Marcus (image 1)`. **Do NOT hand-write a "Reference Image Instructions" block or role essays** ("use for identity, ignore the outfit, render a neutral expression") — that drags the sheet's studio lighting and wardrobe into a scene that asked for neither. The prompt leads; the user's words own wardrobe, expression, lighting, and action.
+4. **Flat-light identity refs.** Prep identity references with flat, even, shadowless lighting on a plain neutral background. A studio-lit or scene-lit character sheet bleeds its lighting into every generation — the failure looks like the subject was green-screen-pasted in front of the location. Reference prep beats prompting here.
+5. **Environment: describe it, don't feed a grid.** Default to describing the location in words and let the model build a space that fits the shot. Reserve an environment reference for a mandatory exact-match, and then use ONE clean establishing image with natural ambient light that reads as the location's real light — never a multi-panel grid fed whole.
+6. **Grids: explore, don't input.** Use grids to explore compositions cheaply, then pick a cell. Never feed a grid back in as a reference — the cells share a split detail budget and were generated jointly, so their flaws propagate.
+7. **Reuse the same refs across every shot** in a sequence. Lock a set and keep it; swapping references mid-sequence causes drift, because the model adapts each reference to the current prompt rather than copying it.
+8. **Legible in-shot text → bake it into a still start frame, never trust text-to-video.** Have an image model render the text, then animate from that locked frame. Video models smear type.
+9. **Working from existing media — describe ONLY what changes.** The source already carries its composition, motion, timing, and performance; re-describing them fights the model. Narrate the delta. (Video lane: restyle your own clip while keeping the performance; delayed-VFX on "video one"; marker-object insertion; video-as-reference for a series.)
+10. **Style transforms happen in natural language.** By default the source's artistic medium and visual style are inherited. To change it, add a plain-text instruction ("anime → real person"). There are no preset pickers, and there is no style slider.
+<!-- @end:reference-rules-core -->
+
+### For Kling specifically
+
+- **Kling's consistency lever is "lock the subject with a fixed label reused verbatim."** That is Kling's phrasing for rules 2 and 3, and it is stricter than the others: **pronoun and synonym drift breaks it**, so the exact same label must appear on every single mention — not "he", not "the detective" after you named him. Reusing the label verbatim is the whole game. Slates composes this for you from `@mentions`.
+- **Element references are the transport for rule 1** — 2-4 multi-angle photos per character/object, tagged `@element1` / `@element2` (see Element references above). The cap is 4 combined refs on the edit path.
+
+## Negative prompting — has a real field
+
+Kling exposes `negative_prompt` on the fal endpoint (different from Seedance which has none). Default block to start from:
+
+```
+blurry, low quality, watermark, text overlay, distorted hands, extra fingers,
+duplicate limbs, unnatural skin texture, overly saturated colors, lens flare,
+floating objects, inconsistent shadows, jittery, flickering, morphing face
+```
+
+Layer scene-specific suppressions on top.
+
+## Cinematic tactics
+
+- **Motion adverb precision** modulates motion energy directly: `slowly`, `rapidly`, `gently`, `explosively`
+- **Camera vocabulary that registers as instructions:** profile shot, tracking, following, freezing, panning, "moving in sync with the subject"
+- **One primary camera move per shot** — never stack
+
+## 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
+
+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.
+
+## Benchmark prompt structure
+
+```
+[Character A: <role>, <voice quality>]: "<line>." Immediately, [Character B: <role>, <voice quality>]: "<reply>."
+Ambient noise: <soundscape>.
+Camera <single move>.
+```
+
+Cinematic example (paraphrasing fal blog patterns):
+> "Shot 1: Wide establishing shot of a neon-lit alleyway in heavy rain, steam rising from grates. Camera slowly tracks forward.
+> Shot 2: Medium shot of a detective in a trench coat ducking under an awning, water dripping from his hat brim. [Detective: weary, raspy]: 'I knew she'd come back.' Ambient noise: distant traffic, rain on metal.
+> Shot 3: Close-up on his eyes, narrowing as headlights flash across his face."
+
+## Video-to-video EDIT — @Video1 / @ElementN / @ImageN
+
+Kling O3 edit takes an EXISTING 3-15s clip and changes only what the prompt names — character swap, environment change, style transfer — in one pass, no masking. Original motion, camera, and audio are preserved by default. Its notation is Kling's own, different from the "image N" naming used everywhere else:
+
+- **`@Video1`** — the source clip (always; the transport anchors the instruction to it).
+- **`@Element1..`** — subjects to swap IN. Each element = one frontal image + up to 3 angle images.
+- **`@Image1..`** — style/appearance references.
+- Max **4 combined** element + image refs per edit.
+
+**Prompt shape — the change, not the whole scene:**
+
+```
+Replace the man in @Video1 with @Element1, keeping his walk cycle, the camera move, and the rain unchanged.
+```
+
+```
+Edit @Video1: turn the daytime street into a neon-lit Tokyo alley at night, wet asphalt reflections. Apply the visual style of @Image1. Keep the subject and camera motion exactly as they are.
+```
+
+Rules:
+- Name what CHANGES; explicitly state what stays ("keep the motion / camera / everything else unchanged") — the model preserves better when told to.
+- 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.
+
+## Sources
+
+- [fal.ai — Kling 3.0 Prompting Guide](https://blog.fal.ai/kling-3-0-prompting-guide/)
+- [Vidguru — Kling 3.0 Omni Guide](https://www.vidguru.ai/blog/kling-3.0-omni-guide.html)
+- [AcceptPrompt — Kling 3 Prompt Guide](https://www.acceptprompt.com/blog/kling-3-prompt-guide)
+- [DataCamp — Kling 3.0 Tutorial](https://www.datacamp.com/tutorial/kling-3-0)