@slatesvideo/shared 0.1.0 → 0.4.0

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

@@ -0,0 +1,154 @@
+---
+name: slates-prompting-nano-banana-2
+description: How to write prompts that produce cinematic, photorealistic results from Nano Banana 2 (Google Gemini 3 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.
+---
+
+# Nano Banana 2 — cinematic & photorealistic prompting
+
+The **default** model behind `slates_generate_image` is **Gemini 3 Image** (Nano Banana 2 / Flash) — the op also exposes `flux-2-max` and `seedream-5-lite`, each with its own prompting skill. 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.
+
+## Google's 4 official rules (verbatim)
+
+1. **Be specific.** Provide concrete details on subject, lighting, and composition.
+2. **Use positive framing.** Describe what you want, not what you don't want.
+3. **Control the camera.** Use photographic and cinematic terms like "low angle" and "aerial view."
+4. **Iterate.** Refine images with follow-up prompts in a conversational manner.
+
+## Official prompt formula
+
+```
+[Subject] + [Action] + [Location/context] + [Composition] + [Style]
+```
+
+For the cinematic / photoreal use case, expand to:
+
+```
+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 or sensor language]. [1-2 word emotional tone].
+```
+
+## Photorealism positives — what consistently works
+
+**Named lenses + apertures** beat generic "shallow depth of field":
+- `85mm f/1.4`, `135mm f/2.8` (the cheat code for skin texture), `50mm f/1.2`, `35mm f/2`
+- `Panavision anamorphic` for horizontal flares + cinematic width
+- `400mm telephoto` for compression + isolation
+- `24mm` for environmental interiors
+
+**Named cameras / sensors:**
+- `ARRI Alexa 65`, `Hasselblad X2D`, `Canon EOS R5`, `Sony A7III`, `Fujifilm X-T5`
+- "Specific gear" beats "DSLR"
+
+**Named film stocks** (one per prompt — never mix):
+- `Kodak Portra 400` — natural skin, warm
+- `Fuji Velvia 50` — saturated, landscape
+- `Ilford HP5 Plus` — black and white, gritty grain
+- `CineStill 800T` — tungsten night, halation
+
+**Physics-based lighting** (direction + quality):
+- `Single key light at 45 degrees from upper left`
+- `Late afternoon sun at 15 degrees above horizon`
+- `Color temperature 4500K` beats `slightly warm`
+- `Practicals only — no fill` for Deakins-style realism
+
+**Imperfection vocabulary** (forces away from AI-clean):
+- `visible pores`, `natural skin grain`, `peach fuzz`, `slight hyperpigmentation`
+- `unretouched raw photography`, `ISO noise`, `sweat beading`
+- `crisp catchlights in the eyes`, `skin micro-detail`
+
+**Director references** (use when locking style):
+| Director | Tone | Visual signature |
+|---|---|---|
+| Denis Villeneuve | Cold, vast, existential | Desaturated, overwhelming scale |
+| Roger Deakins | Precise motivated light | Single source, deep shadows, practicals |
+| Emmanuel Lubezki | Natural, spiritual | Available light, golden hour |
+| Bradford Young | Warm darkness | Underexposed, rich shadows, skin tones |
+
+**Genre cues that move the model:**
+- `unstaged documentary photography style`
+- `fashion magazine editorial, shot on medium-format analog film, pronounced grain`
+- `Film still from [Director] [genre]`
+
+## The anti-list — phrases that DEGRADE realism
+
+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.
+
+**Never use:**
+- `8k`, `4k` (as a quality token)
+- `hyperrealistic`, `ultra-realistic`, `photorealistic` standing alone
+- `masterpiece`, `best quality`, `highly detailed`, `ultra-detailed`
+- `trending on ArtStation`, `award-winning`
+- `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
+
+## Negative prompting — there is no field
+
+Nano Banana 2 has **no `negativePrompt` parameter**. Three patterns to suppress unwanted content:
+
+1. **Positive reframing (preferred):** "empty street" not "no cars". "Unstaged documentary photography" not "not anime."
+2. **Inline `without` / `free of`:** "without any people, vehicles, or man-made structures", "free of text overlays, logos, or watermarks."
+3. **Constraint clauses for anatomy/quality:** "accurate anatomy with five fingers per hand, symmetrical features, natural proportions"; "sharp, well-exposed, free of blur or JPEG artifacts."
+
+Default to #1. Reach for #2 only when positive framing can't suppress the unwanted element.
+
+## Reference images
+
+- **Hard limit: 14 images** (10 object-fidelity + 4 character-consistency). Categories don't trade — you can't use 14 object slots even if no characters are referenced.
+- **Always label every reference's role** in the prompt. The model does not infer roles from order. Use the Slates composition pattern:
+
+```
+Reference Image Instructions:
+- Image 1: Character reference (@samurai) — use for the character's identity (facial features, skin, bone structure, body, outfit); render the expression the scene describes, default neutral
+- Image 2: Environment reference (@temple) — use for location architecture, spatial layout, environmental lighting, and atmospheric qualities
+- Image 3: Style reference (#kurosawa) — use for visual style, mood, and aesthetic treatment
+
+Scene prompt: [actual prompt]
+```
+
+### Reference rules (the verified ones)
+1. **2-4 strong refs beat both extremes.** Not 1 (warps toward itself), not 12 (averages worse). Start with 2-3 focused refs — each adds context AND variables to balance.
+2. **One reference per ROLE, labeled** (identity / style-grade / environment). Same-role competitors drift.
+3. **Identity refs: attach both sheets, labeled — don't gate them.** A character's turnaround (body/proportion/outfit) AND its close-up expression sheet (high-res face: eyes, skin, teeth) both go in. The label ("use for identity; render the scene's expression, default neutral") is what stops the varied expressions from averaging the face. An *unlabeled* expression sheet hurts; labeled, the close-ups are a fidelity win.
+4. **Flat-light identity refs.** Prep them with flat, even, shadowless lighting on a plain neutral background. Studio-lit / scene-lit sheets bleed their lighting into the generation ("green-screen pasted in front of mountains").
+5. **Environment: describe it, don't feed a grid.** Default to describing the location in words. Reserve an environment ref for a mandatory exact-match, and then use ONE clean establishing image — never a multi-panel grid fed whole.
+6. **Grids: explore, don't input.** Use grids to explore compositions, then pick a cell. Never feed a grid back in as a reference — cells share a split detail budget, so flaws propagate.
+7. **Reuse the same refs across all shots.** Swapping mid-sequence causes drift.
+8. **Legible in-shot text → bake it into the NB2 start frame**, then animate from it. Never trust text-to-video to render clean text.
+- **Character consistency is officially "not 100% perfect"** per Google. Test before bulk generations. High-resolution, front-facing reference images help most.
+
+## Common failure modes + fixes
+
+**Hands:** Append `accurate anatomy with five fingers per hand, symmetrical features, natural proportions, relaxed open palm`. Avoid heavy jewelry, props intersecting fingers, motion blur in references.
+
+**Text in images:** Quote-wrap target text. Specify font (`Century Gothic, 12pt`). Long phrases work; small text degrades. Two-step works best — generate text concepts conversationally first, then ask for the image.
+
+**Left/right confusion:** Default is **viewer's perspective**, not subject's. Append `left and right are from the character's perspective, NOT the camera's` when scene-blocking matters.
+
+**Surreal / absurd prompts trip uncanny valley:** The model drags toward realism. If you want surrealism, lean hard into stylization keywords (`painted`, `illustrated`, `stop-motion`).
+
+**Soft faces / dead eyes:** Add `crisp catchlights in the eyes`, `skin micro-detail`, `peach fuzz visible`. Don't stack quality enhancers — single clean prompt beats multiple re-interpretations.
+
+**Post-cutoff content (anything after Jan 2025):** Use reference images. The model has no knowledge of recent franchises, products, events.
+
+## Resolution tactics
+
+- Resolution is priced: NB2 4k costs roughly 2x 1k. Prices change — call `slates_estimate_generation_cost` for current numbers. Pick the cheapest resolution that serves the use case.
+- **At 2K and above, the model allocates more tokens to surface detail** — explicit texture vocabulary (pores, fabric weave, grain) compounds at higher resolution.
+- 1k for fast iteration / drafts; 2k for hero shots; 4k only when you need print-grade detail.
+- 2K generations vary 20-60s+. Don't time-budget tightly.
+
+## Boring vs cinema — examples
+
+❌ **Boring:** "Wide shot of a man on a dock looking at the forest."
+
+✅ **Cinema:** "Direct overhead drone shot on weathered dock surface. Single figure standing center frame, climbing up from frame bottom. Boot prints leading away from him toward shore. Pale winter light. Anamorphic lens flare from low sun. Desaturated blue and slate grey palette. Kodak Portra 400 grain. The path already walked by someone else. Map of threat."
+
+❌ **Boring:** "Close up of a woman looking scared."
+
+✅ **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
+
+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.

package/skills/slates-prompting-seedance.md

@@ -0,0 +1,155 @@
+---
+name: slates-prompting-seedance
+description: How to prompt Seedance 2.0 (ByteDance video model). Read before calling slates_generate_video with model seedance-2-fast or seedance-2-std. Seedance prompts have very specific structure (6-step formula + narrative timing beats) that differs from Kling and Veo — don't cross-pollinate the syntax.
+---
+
+# Seedance 2.0 — prompting
+
+ByteDance's video model. Routed via PiAPI (Economy) or fal.ai (Priority). Audio always generated alongside video. Models: `seedance-2-fast` (cheaper) and `seedance-2-std` (higher quality). Up to 15s.
+
+## Official 6-step formula
+
+```
+Subject + Action + Environment + Camera + Style + Constraints
+```
+
+**Sweet spot length:** 60-150 words (not 150-300 — that's the upper bound). Multi-shot can run longer.
+
+## Pin the subject in the first 20-30 words
+
+The opening sentence is the **identity anchor**. If the subject isn't locked early, the model hallucinates new subjects mid-clip.
+
+```
+A matte black earbud case sits on a polished obsidian surface...
+```
+
+## Narrative timing beats — "At N seconds"
+
+Use natural-language time markers, NOT shot brackets or labels.
+
+```
+At 2 seconds, the camera begins a slow dolly forward.
+At 4 seconds, the lid opens in slow-motion...
+```
+
+Beat count: **2 for 5s, 3 for 10s, 4-5 for 15s**.
+
+## Camera moves — exact terms only
+
+8 supported: `push-in`, `pull-out`, `pan`, `tracking`, `orbit`, `aerial`, `handheld`, `fixed`.
+
+- "Dolly in" not "zoom in"
+- "Orbit" not "circle"
+- **One primary camera move per beat** — never stack them
+
+## Lighting is the #1 quality lever
+
+ByteDance says lighting has the biggest impact of any prompt element. Describe before or alongside the subject.
+
+```
+A cool-white diagonal beam from upper left, dust particles drifting through.
+Soft golden hour lighting from low west angle.
+Dramatic rim light against dark background.
+```
+
+## Camera and subject motion — separate sentences
+
+Mixing them is the #1 cause of glitchy / shaky output.
+
+❌ "The camera speed ramps as the earbud rises."
+✅ "The earbud rises smoothly. The camera tracks upward."
+
+## Slow-motion works. "Fast" doesn't.
+
+`fast` is ByteDance's #1 quality-degrading keyword. Speed ramps and slow-motion are supported in natural language.
+
+```
+the lid opens in slow-motion · the blade whips through the air
+```
+
+Other dangerous tags (treated as slop): `epic`, `amazing`, `beautiful`, `lots of movement`, `8K`, `masterpiece`, `trending on artstation`.
+
+## Style block at the end
+
+One primary anchor + 2-3 supporting details. End with `Single continuous take` if you want one shot with no cuts. **Never** write `no cut` or `seamless transition` — not in the training vocabulary.
+
+## Reference media — `@Image1` / `@Video1` / `@Audio1` syntax
+
+Reference-to-video endpoint accepts up to **9 reference images, 3 reference videos, 3 audio clips**. Tag inline:
+
+```
+@Image1 is the character. @Image2 is the environment. @Audio1 is the foley.
+```
+
+**Mutually exclusive:** First-frame/last-frame mode CANNOT be combined with reference images. The error reads `"first/last frame content cannot be mixed with reference media content."` Pick one or the other.
+
+## Reference rules (the verified ones)
+
+- **2-4 strong refs beat both extremes** — not 1 (warps), not 12 (averages worse). Start focused.
+- **One reference per ROLE, labeled** — `@Image1 is the character`, `@Image2 is the environment`. The model needs to know what each ref is FOR; it doesn't infer roles from order.
+- **Character identity: attach the turnaround AND the close-up expression sheet, labeled for identity** (face/skin/body/outfit), and render the expression the SCENE describes (default neutral). That label is what keeps the varied expressions from averaging the face — don't gate the expression sheet. The trend is MORE references (video/audio into Seedance), so lean into attaching rich refs and labeling every role.
+- **Flat-lit identity refs.** A studio-lit / scene-lit character sheet bleeds its lighting into the clip ("green-screen pasted in front of mountains"). Prep refs flat and plain.
+- **Environment: describe it, don't feed a grid.** Default to words and let the model build the space to fit; reserve an environment ref for a hard exact-match, and then use ONE clean establishing image — never a multi-panel grid.
+- **Reuse the same refs across every shot** in a sequence — swapping mid-sequence drifts.
+- **Legible on-screen text → bake it into an NB2 start frame** and animate from it; Seedance won't render clean text from scratch.
+- **Grids are for EXPLORING compositions, not for inputting** — pick a cell, don't feed the grid back as a reference.
+
+## Image-to-video / first-frame guidance
+
+**Describe motion, not image.** The model already sees the visual; tokens spent re-describing appearance are wasted.
+
+Required stability phrases:
+- `preserve composition and colors`
+- `maintain exact appearance from reference image`
+- `consistent character throughout, no deformation or drift`
+
+**Cap I2V prompts under 60 words** when possible. Over 100 words frequently triggers silent generation failure.
+
+## Negative prompting — inline only
+
+Seedance has **no `negativePrompt` field**. Use the Constraints slot:
+
+```
+avoid jitter and bent limbs
+avoid temporal flicker
+avoid identity drift
+no distortion, no stretching
+```
+
+Also fine: positive reframing ("empty street" not "no cars").
+
+## Common failure modes + fixes
+
+| Failure | Fix |
+|---|---|
+| Hallucinated subject mid-clip | First 20-30 words = identity anchor |
+| Bent limbs / extra fingers | `avoid jitter and bent limbs` in Constraints |
+| Identity drift across multi-shot | Repeat subject anchor at each beat |
+| Silent generation failure on I2V | Cut prompt under 100 words, single primary camera move |
+| Speech / motion conflict | Limit dialogue to one line per action shot |
+
+## Benchmark prompts (verbatim from authoritative sources)
+
+**Single-shot (fal.ai):**
+> "A golden retriever runs across a sandy beach at sunset, kicking up wet sand with each stride, the camera tracking alongside at ground level. Waves crash softly in the background."
+
+**Multi-shot commercial (fal.ai):**
+> "Shot 1: extreme close-up of condensation dripping down a glass bottle, the sound of ice clinking. Shot 2: the bottle rises from a bed of crushed ice, camera tilting up slowly, bright backlight creating a halo effect. Shot 3: a hand grabs the bottle against a sunset rooftop backdrop, the city humming below."
+
+**Cinematic anchor (atlabs):**
+> "Modern Rural Aesthetics, Cinematic Commercial quality, shot with Sony A7S3/cinema camera, 4K/8K ultra-clear, Extreme Macro, natural transparent lighting, healing ASMR, no historical costume drama feel."
+
+## Pre-flight: references arrive inline, refer by code
+
+When you call `slates_generate_video` with reference asset IDs (firstFrameAssetId, lastFrameAssetId, ingredientAssetIds), the first call returns those references **inline as image content blocks** alongside a cost estimate and `requires_confirm: true`. **Look at the references** — if they suggest a different framing, lighting, or motion than your current prompt captures, revise the prompt before re-calling with `confirm=true`.
+
+When talking to the user about the gen, refer to each reference by its short code: `IMG-A12 — Beach Sunset`. The user sees that code as a badge on the gallery thumbnail, so they can match what you're saying to what they're looking at.
+
+- ✅ "I'm using **IMG-A12** as the first frame and **IMG-A15** as the last frame — the camera move is going to be a slow dolly forward through the gap."
+- ❌ "I'm using the first beach image and the last one..." (which? They have four.)
+
+## Sources
+
+- [fal.ai — How to Use Seedance 2.0](https://fal.ai/learn/tools/how-to-use-seedance-2-0)
+- [apiyi.com — Seedance 2.0 Prompt Guide](https://help.apiyi.com/en/seedance-2-0-prompt-guide-video-generation-camera-style-tips-en.html)
+- [atlabs.ai — Ultimate Seedance 2.0 Prompting Guide](https://www.atlabs.ai/blog/the-ultimate-seedance-2.0-prompting-guide-47-prompts-2026)

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

@@ -0,0 +1,74 @@
+---
+name: slates-prompting-seedream-5-lite
+description: How to prompt Seedream 5 Lite (ByteDance image model — the cheap volume option in Slates). Read before calling slates_generate_image with model seedream-5-lite, or slates_edit_image with editModel seedream-5-lite. Seedream front-loads attention, likes 30-100 focused words, and takes quoted strings for in-image text.
+---
+
+# Seedream 5 Lite — prompting
+
+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.
+
+## Core structure — five components, most important first
+
+```
+Subject + Style + Composition + Lighting/Atmosphere + Technical parameters
+```
+
+Seedream weights concepts mentioned **earlier in the prompt** more heavily. Lead with the subject; close with camera/technical details.
+
+**Length sweet spot: 30-100 words.** Unlike models that reward verbosity, Seedream gets confused by very long prompts. Focused beats exhaustive.
+
+## Style, composition, lighting vocabulary it responds to
+
+- **Style:** portrait photography, macro photography, cinematic, photorealistic, minimalist, oil painting, watercolor, digital art
+- **Composition:** symmetrical composition, rule of thirds, foreground detail with blurred background, wide-angle view, overhead perspective, medium shot, close-up
+- **Lighting:** golden hour lighting, dramatic side lighting, soft diffused light, moody low-key lighting, bright high-key lighting
+- **Technical:** shot on 85mm lens, shallow depth of field, high resolution
+
+## Worked examples
+
+**Portrait:**
+> "Professional headshot of a female CEO with short blonde hair, confident expression, wearing a navy blue suit, neutral office background, studio lighting, shallow depth of field, high-end corporate photography style"
+
+**Product:**
+> "Modern smartphone floating in space, dark background with subtle blue gradient, product photography, studio lighting highlighting the glossy screen, ultra-detailed, commercial quality, photorealistic rendering"
+
+## In-image text: double-quote it
+
+Put the exact string in double quotation marks — Seedream treats quoted text as render-this-verbatim:
+
+```
+A minimalist poster with the headline "SUMMER SALE" in bold sans-serif, centered
+```
+
+Seedream is one of the stronger models for layout-heavy work (posters, mockups, diagrams): call out the layout explicitly — "centered headline, subtitle beneath, clean margins."
+
+## Edits: change one thing, lock the rest
+
+Via `slates_edit_image` with `editModel: seedream-5-lite`. Seedream edits respond well to instructions that name the change AND the preserved elements:
+
+```
+Change the bag to brown leather. Keep the person's face, pose, and the room unchanged.
+```
+
+Note: Seedream edits in Slates ignore extra `referenceAssetIds` — that path is Nano Banana 2 only.
+
+## Common failure modes + fixes
+
+| Failure | Fix |
+|---|---|
+| Subject inconsistent / mutates | Put the subject description first; break complex subjects into clear components |
+| Style drift | Reinforce the aesthetic with 2-3 related terms ("cinematic, photorealistic, shallow depth of field") |
+| Compositional confusion | Use photography terms ("medium shot," "overhead view"); simplify the scene |
+| Garbled text | Double-quote the exact string; keep it short; state placement |
+| Mushy long-prompt output | Cut to under 100 words — Seedream rewards focus, not volume |
+
+## Iterate cheap, lock expensive
+
+Flat pricing makes Seedream the iterate-fast model: run the 3-strike loop here (draft → evaluate inline → one specific delta → regenerate), and only re-render the winning composition on a pricier model if the project's hero shot demands it. Cost rules live in `slates-cost-discipline` — the batch-authorization pattern applies when generating variant grids.
+
+## Sources
+
+- [fal.ai — Seedream Prompt Guide](https://fal.ai/learn/devs/seedream-v4-5-prompt-guide)
+- [BytePlus ModelArk — Seedream Prompt Guide](https://docs.byteplus.com/en/docs/ModelArk/1829186)

package/skills/slates-prompting-veo-3.md

@@ -0,0 +1,156 @@
+---
+name: slates-prompting-veo-3
+description: How to prompt Veo 3.1 (Google). Read before calling slates_generate_video with veo-3.1-fast or veo-3.1-standard. Veo has the strongest first-frame + last-frame workflow of the three video models, native synchronized audio, and a different cinematography formula than Seedance/Kling. (no subtitles) is mandatory after every dialogue line.
+---
+
+# Veo 3.1 — prompting
+
+Google DeepMind's video model. Two tiers: `veo-3.1-fast` (cheaper, quick) and `veo-3.1-standard` (higher quality). 4k variants exist for both.
+
+**Native single-shot duration: 4, 6, or 8 seconds.** Longer durations require chaining clips via Extend / last-frame reuse — quality degrades if naively requested past 8s in a single generation. Aspect ratio: **16:9 only** — `slates_generate_video` locks Veo to 16:9; anything else is ignored or fails. For 9:16 vertical, use Kling or Seedance instead.
+
+Native synchronized audio at 48kHz: dialogue, SFX, ambient — generated WITH video, not added after.
+
+## Official Google formula
+
+```
+[Cinematography] + [Subject] + [Action] + [Context] + [Style & Ambiance]
+```
+
+Sweet spot length: 50-150 words. Cloud's official benchmark is ~50 words.
+
+Verbatim official benchmark:
+> "Medium shot, a tired corporate worker, rubbing his temples in exhaustion, in front of a bulky 1980s computer in a cluttered office late at night. The scene is lit by the harsh fluorescent overhead lights and the green glow of the monochrome monitor. Retro aesthetic, shot as if on 1980s color film, slightly grainy."
+
+## Cinematography vocabulary (Vertex AI docs)
+
+**Lenses:** wide-angle, telephoto, fisheye, anamorphic, 35mm, 85mm, shallow/deep depth of field
+
+**Lighting:** Rembrandt lighting, volumetric lighting, backlighting, golden hour glow, lens flare, rack focus, **vertigo effect** (dolly zoom)
+
+**Camera moves:** dolly (in/out), truck (left/right), pan, tilt, crane, aerial/drone, handheld, whip pan, arc shot, zoom
+
+## Texture-realism phrases (counter the AI-plastic look)
+
+```
+fine skin pores · visible fabric weave · subtle contrast, no gloss or sharpening
+```
+
+Specify materials concretely: `charcoal cotton hoodie`, `matte concrete`, `silk lapel`. Generic "smooth, beautiful" rendering is the failure mode you're avoiding.
+
+## Dialogue — `(no subtitles)` is mandatory
+
+Every dialogue line you don't want burned in as text overlay needs `(no subtitles)`. Verbatim from the founder talking-head benchmark:
+
+```
+The founder says, "This update cuts setup time in half, helping teams get started faster." (no subtitles).
+```
+
+Without this, Veo will overlay subtitle text on top of your generation.
+
+## Voice direction — keep it terse
+
+Veo is less responsive to long voice-direction blocks than Kling. Use brief modifiers:
+
+```
+says in a weary voice
+whispers
+shouts
+mutters
+```
+
+Multi-character: handles 2-3 speakers natively. Past 3, sync degrades — use first-frame/last-frame chaining for 4+.
+
+## SFX with cause
+
+```
+✅ SFX: thunder cracks in the distance
+❌ SFX: thunder
+```
+
+Always specify direction or distance.
+
+## Ambient is mandatory
+
+Always include an ambience line per scene. Without it, the audio mix feels dead.
+
+```
+Soft office ambience.
+Wind on the open ridge.
+Distant city hum.
+```
+
+## First-frame + last-frame workflow (Veo's strength)
+
+1. Generate start frame (Gemini 2.5 Flash Image is the recommended pair — Slates' Nano Banana 2 works)
+2. Generate end frame
+3. Animate with both frames as anchors
+
+**Motion-Lock hack:** Keep ~60% of the same background pixels between start and end frames. Prevents latent drift across the clip.
+
+Verbatim arc-shot example:
+> "The camera performs a smooth 180-degree arc shot, starting with the front-facing view of the singer and circling around her to seamlessly end on the POV shot from behind her on stage. The singer sings 'when you look me in the eyes, I can see a million stars.'"
+
+## Ingredients-to-Video (multiple references)
+
+Verbatim example:
+> "Using the provided images for the detective, the woman, and the office setting, create a medium shot of the detective behind his desk. He looks up at the woman and says in a weary voice, 'Of all the offices in this town, you had to walk into mine.'"
+
+## Reference discipline (character / environment refs)
+
+- **2-4 strong refs per role**, labeled (name what each provided image is for) and reused across every shot.
+- **Flat-lit identity refs.** A studio-lit / scene-lit character sheet bleeds its lighting into the clip. Prep refs flat and plain.
+- **Attach both character sheets, labeled for identity** — the turnaround (body/proportion/outfit) and the close-up expression sheet (face detail). Render the scene's expression (default neutral); the label keeps the varied expressions from averaging the face.
+- **Environment: describe it, don't feed a multi-panel grid.** Reserve an environment ref for a hard exact-match, then use ONE clean establishing image.
+
+## Negative prompting — nouns, not instructions
+
+Veo has a `negativePrompt` field. **Verbatim Vertex AI rule:**
+> "Describe unwanted elements as nouns rather than instructions. Use 'wall, frame' instead of 'no walls' or 'don't show walls.'"
+
+Inline: positive reframing in the body too.
+- ✅ `"a desolate landscape with no buildings or roads"`
+- ❌ `"no man-made structures"`
+
+## Common failure modes + fixes
+
+| Failure | Fix |
+|---|---|
+| Subject identity shifts mid-clip | Front-load identity at prompt start; use material cues (`charcoal canvas`, `cotton`, `silk`) to stabilize |
+| Floaty / weightless motion | Weight verbs (`trudges`, `drops heavily`), ground contact (`boots crunch on gravel`) |
+| AI-plastic look | `fine skin pores`, `visible fabric weave`, `subtle contrast` |
+| Subtitles baked into video | `(no subtitles)` after every dialogue line |
+| Rushed dialogue | Lines fit one natural breath in 8s |
+| Mismatched ambience | Always include an ambience line |
+| Warped geometry | `photorealistic stability` |
+
+## Timestamp shot syntax (for chained / multi-beat scenes)
+
+Veo accepts `[00:00-00:02]` brackets for timed sequences within an 8s clip. **Do NOT cross syntaxes** — Veo timestamps in a Seedance prompt cause subject drift; Seedance "single continuous take" in a Veo prompt suppresses cuts.
+
+Verbatim multi-beat:
+> "[00:00-00:02] Medium shot from behind a young female explorer with a leather satchel and messy brown hair in a ponytail, as she pushes aside a large jungle vine to reveal a hidden path.
+> [00:02-00:04] Reverse shot of the explorer's freckled face, her expression filled with awe as she gazes upon ancient, moss-covered ruins. SFX: The rustle of dense leaves, distant exotic bird calls.
+> [00:04-00:06] Tracking shot following the explorer as she steps into the clearing and runs her hand over the intricate carvings on a crumbling stone wall.
+> [00:06-00:08] Wide, high-angle crane shot, revealing the lone explorer standing small in the center of the vast, forgotten temple complex, half-swallowed by the jungle. SFX: A swelling, gentle orchestral score begins to play."
+
+## Benchmark prompt — founder talking head (full)
+
+> "Camera locked at eye level, medium close-up on a 35mm lens: a startup founder in his late 30s with short black hair and light stubble, wearing a charcoal cotton hoodie, speaking directly to camera, leaning slightly forward as he speaks, lifting one hand to emphasize a point, then relaxing back to neutral, in a quiet office during late afternoon, with blurred monitors glowing faintly in the background, lit by soft daylight from a side window with gentle fill on the opposite side and natural falloff across his face. Style: fine skin pores, visible fabric weave, subtle contrast, no gloss or sharpening. Audio: The founder says, 'This update cuts setup time in half, helping teams get started faster.' (no subtitles). Soft office ambience."
+
+## Pre-flight: references arrive inline, refer by code
+
+When you call `slates_generate_video` with `firstFrameAssetId` / `lastFrameAssetId` / `ingredientAssetIds`, the first call returns those references **inline as image content blocks** alongside a cost estimate and `requires_confirm: true`. Veo's strongest move is first-frame + last-frame; the pre-flight is where you confirm the two frames actually anchor the motion you wrote. Revise the prompt before `confirm=true` if needed.
+
+When talking to the user about the gen, refer to each reference by its short code: `IMG-A12 — Founder Headshot`. The user sees that code as a badge on the gallery thumbnail, so they can match what you're saying to what they're looking at.
+
+- ✅ "I'm anchoring on **IMG-A12** as the open shot and **IMG-A18** as the close — the 180° arc lands on her looking offscreen left."
+- ❌ "I'm using two of the founder shots..." (which two? They have six.)
+
+## Sources
+
+- [Google Cloud — Ultimate Prompting Guide for Veo 3.1](https://cloud.google.com/blog/products/ai-machine-learning/ultimate-prompting-guide-for-veo-3-1)
+- [Google DeepMind — Veo Prompt Guide](https://deepmind.google/models/veo/prompt-guide/)
+- [Google Cloud Docs — Vertex AI Video Generation Prompt Guide](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/video/video-gen-prompt-guide)
+- [Atlas Cloud — Veo 3.1 Master Guide](https://www.atlascloud.ai/blog/guides/google-veo-3-1-guide-master-image-to-video-ai-with-native-sound-and-4k-realism)
+- [Invideo — Veo 3.1 Prompt Guide](https://invideo.io/blog/google-veo-prompt-guide/)

package/skills/slates-storyboard-from-script.md

@@ -0,0 +1,49 @@
+---
+name: slates-storyboard-from-script
+description: Turn a script or treatment into a Slates storyboard with scenes and frames. Use when the user has a script, treatment, shot list, or scene-by-scene description and wants to materialize it as a Slates storyboard, optionally generating frame images per shot.
+---
+
+# Storyboard from script — Slates workflow
+
+The user has a script, treatment, or shot list. You're turning it into a Slates storyboard with scene → frame structure, optionally generating images for each frame.
+
+## Workflow
+
+### 1. Parse the script
+Read the user's script. Decide:
+
+- **Scene count** — usually 1 scene per location/setting change. Don't fragment into one-frame scenes.
+- **Frames per scene** — match the shot list. Default is 3-6 frames per scene unless the script specifies more.
+- **Shot labels** — pull them from the script (e.g., "Wide", "Close-up", "Over-the-shoulder").
+
+If the user hasn't named the storyboard, suggest one based on the project tone.
+
+### 2. Materialize the structure first (no generation yet)
+- `slates_create_storyboard` with the chosen name.
+- For each scene: `slates_add_scene` with a descriptive name and order.
+- For each frame: write a *visual-only* prompt (image, not action), the shot label, and any director notes. **Don't generate yet.**
+
+Surface the planned structure back to the user as a tight summary:
+> Storyboard "X" • 4 scenes • 12 frames total
+>   Scene 1: Forest opening (3 frames)
+>   Scene 2: Confrontation (4 frames)
+>   ...
+
+Ask: **"Generate frame images now? (y/N)"**
+
+### 3. Generate frames if requested
+For each frame:
+- Estimate cost (`slates_estimate_generation_cost`, `count = total frames`). Confirm with user if total > $0.50.
+- Generate sequentially, with character/environment/style references attached when present in the project (`slates_list_characters`, `slates_list_environments`).
+- Each result returns inline. Evaluate. If wrong, refine prompt + regenerate (charge once, not multiple).
+- Bind to the frame via `slates_add_frame`.
+
+### 4. Hand back
+- Total frames generated, total credits spent, storyboard id.
+- Suggest next steps: review via `slates_get_storyboard_with_frames`, or take the frames to motion — `slates_generate_video` per frame (`firstFrameAssetId`, `background: true`, poll `slates_get_generation_status`), then `slates_add_clip_to_timeline` in story order and `slates_export_video`. The full frames-to-film pipeline (batch cost authorization, model mixing) is `slates-one-prompt-film`.
+
+## Anti-patterns
+
+- **Don't** auto-generate without asking. Generation is the expensive step. Always confirm first.
+- **Don't** invent shot details the script doesn't mention. If the script says "they argue," ask what the shot looks like, don't fabricate "she clenches her fists in a wide shot."
+- **Don't** mix scene structure and frame generation in one pass — building the skeleton first lets the user catch errors before spending credits.

package/skills/slates-vision-feedback-loop.md

@@ -0,0 +1,62 @@
+---
+name: slates-vision-feedback-loop
+description: Lower-level utility skill for any Slates workflow that needs to "generate, look at the result, refine, regenerate." Defines the standard inline-vision pattern. Other Slates skills compose this. Use when generating images and you need to confirm they match the brief before moving on, or when the user asks to "iterate" on an image.
+---
+
+# Vision feedback loop — Slates utility skill
+
+Slates returns generated images inline as base64. You see the actual pixels. Use that — don't trust prompt-following blindly.
+
+## Asset codes are your shared vocabulary with the user
+
+Every asset in Slates has a short stable code (e.g. `IMG-A12`, `VID-V3`, `AUD-S1`) and a label derived from its prompt (e.g. `Beach Sunset`). These are visible in the gallery as a corner badge on each thumbnail. **Always refer to assets by their code in chat** so the user can match what you're saying to a specific card in their gallery.
+
+- ✅ "I'm using **IMG-A12 — Beach Sunset** as the first frame. The second-frame candidate **IMG-A15** has the right composition but warmer light — want me to use that one instead?"
+- ❌ "I'm using the beach sunset image..." (user has four beach sunset variants — which one?)
+- ❌ "I'm using asset `7a3f9e4b-...`" (UUIDs aren't readable; user can't match to a badge)
+
+The code is the FORMAL reference. The label is human texture. Use both: `IMG-A12 — Beach Sunset`.
+
+## Vision tools at your disposal
+
+- `slates_get_asset_image` — pull one image into context. Returns its code+label.
+- `slates_get_assets_batch` — pull up to 8 images in one call. Use when picking from a candidate set; cheaper than N individual fetches.
+- `slates_get_asset_video_frames` — extract N keyframes (default 3) from a video and inline them as JPEGs. You can't see video natively; this is how you "look at" a clip before refining its motion prompt.
+
+## Pre-flight is automatic on the gen tools
+
+`slates_generate_video`, `slates_generate_motion_transfer`, and `slates_generate_lip_sync` now show you their reference assets **inline** on the confirm response. You don't need to fetch them yourself — but you DO need to look at what comes back, revise the prompt if the references suggest a different motion/framing, and only then re-call with `confirm=true`.
+
+## The pattern
+
+1. **Generate.** Call `slates_generate_image` with a prompt. The result is in your context as an image content block.
+2. **Evaluate against the brief.** What did the user actually want? Are the elements right? Composition? Lighting? Subject identity?
+3. **One of three outcomes:**
+   - **Right** → save it (bind to a frame, character slot, etc.) and move on.
+   - **Close, but adjustable** → refine the prompt with a specific delta ("wider shot", "warmer light", "remove the second figure"), regenerate **once**.
+   - **Wrong direction** → ask the user before regenerating. Don't burn credits on prompt-thrashing.
+
+## Refinement rules
+
+- **One specific delta per regeneration.** Don't change five things at once — you won't know what helped.
+- **Anchor with references.** If the result drifted from the user's intent, attach the *previous best* generation as a reference image alongside the original brief.
+- **Use `slates_get_asset_image`** to pull a previously-generated image back into context if you need to compare against a fresh generation.
+- **Use `slates_edit_image`** for surgical tweaks instead of full regeneration when ~90% of the image is right — `sourceAssetId` = the asset, `prompt` = the change only. Edits preserve composition and identity; full regen rolls the dice. Recipe: `slates-edit-and-iterate`.
+
+## Cost discipline
+
+- Track total credits spent across the loop. Surface to the user every 3 iterations.
+- Stop after 3 failed iterations on the same prompt — escalate to the user with what you tried and what's not working. The slot machine never converges.
+- For high-cost generations (`> $0.50`), confirm before *every* attempt, not just the first.
+
+## When to break the loop
+
+- The user said "good enough" or "ship it." Stop iterating.
+- You've burned >5 generations on one frame. Hand back and ask.
+- The user changes brief mid-loop. Treat it as a new brief, not a continuation.
+
+## Voice when narrating to the user
+
+Tight, observational, no editorializing.
+- ✅ "Frame 2 has the wrong lighting direction — back-lit instead of side. Regenerating with side light."
+- ❌ "I notice that the lighting in frame 2 isn't quite what we were going for. I'll go ahead and try again with a different approach."