@slatesvideo/shared 0.7.2 → 0.7.3

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

@@ -1,110 +1,118 @@
----
-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 still-gate — never animate a bad frame
-
-<!-- @inject:still-gate -->
-**A visible defect in the still is already a STOP.** Do not animate it. Fix the frame first, then move to motion — and go to motion only when the crop passes the still scan and you genuinely need movement to confirm an uncertain edge, reflection, or object.
-
-This is a **cost** rule as much as a craft rule: a 1080p/10s premium video generation costs many multiples of an image re-roll, and video is where a defect stops being fixable. Anything wrong in the still gets worse in motion — soft geometry mushes, broken-but-plausible objects fall apart, oily textures start crawling. **Animating a known-bad frame is the single most expensive mistake in the pipeline.** Re-rolling the image is the cheap move; re-rolling the video is not.
-<!-- @end:still-gate -->
-
-## The pattern
-
-1. **Generate.** Call `slates_generate_image` with a prompt. The result is in your context as an image content block.
-2. **Evaluate on TWO axes — they are different questions:**
-   - **Brief-conformance** — what did the user actually want? Are the elements right? Composition? Lighting? Subject identity?
-   - **Defects** — run the slop rubric below. *A frame can match the brief perfectly and still be slop that mushes the moment it moves.* Checking only the first axis is how a bad frame reaches an expensive video call.
-3. **One of three outcomes:**
-   - **Right** → save it (bind to a frame, character slot, etc.) and move on.
-   - **Close, but adjustable** → refine with a specific delta, regenerate **once**.
-   - **Wrong direction** → ask the user before regenerating. Don't burn credits on prompt-thrashing.
-
-## The defect rubric — five slop tells
-
-| Tell | What it looks like | Why it matters downstream |
-|---|---|---|
-| **Light with no transitions** | Flat-black pits instead of a shadow ramp; light that stops rather than falls off | Transfers onto every character or object added into that plate later |
-| **Broken-but-plausible objects** | Crates, railings, hardware, mechanisms you can *almost* read but that don't resolve | Turn to mush in motion, and the model multiplies them |
-| **Local logic breaks** | An effect present in only part of the frame — rain scratching one corner, wet ground under one figure | The video model's physical logic breaks along with it |
-| **Oily textures** | Soapy, licked-smooth surfaces that have lost their material identity | Reflections crawl in motion; the plate can't hold continuity |
-| **Too perfect** | A soft light on the face that nothing in the scene could cast, the subject sharper and cleaner than everything around them, every region exposed to be readable, colour pushed warm and saturated | It reads as a subject pasted onto a location, and every shot built from the plate inherits the studio look. Fix it in words: `slates-cinematic-look` |
-
-### Per-model accents — check the one you actually used
-
-- **Nano Banana Pro** (`nano-banana-pro`) — ruler-straight symmetry, everything parallel and square, flat even light, pretty but staged/stock, textures reading as 3D render rather than photograph. **It hyperbolizes every edit**: ask for graffiti on one wall and the whole location gets tagged.
-- **GPT Image** (`gpt-image-2-5-flare`, `gpt-image-2-5-sunburst`) — microcontrast to the ceiling, hard halos on every edge, no depth or bokeh, white balance pulled warm until the frame yellows, plastic licked-smooth materials. Worst tell: **one sickly texture pattern laid over the entire frame**. ⚠️ Catalogued on `gpt-image-2`, which 2.5 replaced on 2026-09-09 — an accent is a per-model observation, so treat this as a prior to check rather than a finding, and correct it here the first time a 2.5 frame disagrees.
-
-> ⚠️ These are accents for **`nano-banana-pro`** and the **GPT Image** line specifically. `nano-banana-2` is a **different model** (Gemini 3.1 Flash Image vs NB Pro's Gemini 3 Pro Image) and we have **no evidence** about its accent. Do not inherit one — say nothing rather than warn about a failure mode you can't substantiate. That caution applies to the GPT Image entry above too: it was measured on `gpt-image-2`, not on either 2.5 seat.
-
-## Where the fault lives — triage before you change anything
-
-We say "one specific delta per regeneration" but that only helps once you know *which* variable to move. Diagnose first:
-
-| Visible pattern | Diagnosis | Fix |
-|---|---|---|
-| The defect exists in the source asset, or stays tied to the same feature when the direction changes | **Source asset** | Fix the sheet / plate, not the prompt |
-| Source is clean, and the defect changes when only the suspect motion clause changes | **Motion direction** | Fix the prompt |
-| Controls conflict, or the failure follows neither variable | **Inconclusive** | Narrow the test — change less, not more |
-
-**Review routes; it is not pass/fail.** Geography melts → fix the location. Identity drifts → fix the character sheet. Assets are sound but the action is wrong → fix the video direction. Wrong idea entirely → reopen the brief with the user.
-
-**Correct the earliest broken handoff.** Polishing a downstream symptom hides the source and guarantees it resurfaces in the next shot built from the same asset.
-
-## Baseline hygiene — isolate the variable you're testing
-
-When the **character** is the question, keep the location out of it: test on a plate that already holds its own geometry, depth, materials, and light. **A broken plate gives every character failure a second plausible cause**, and you will spend re-rolls deciding which one you're looking at. The same applies in reverse — test a plate empty before you populate it.
-
-## Refinement rules
-
-- **One specific delta per regeneration.** Don't change five things at once — you won't know what helped.
-- **Rewrite the FULL prompt on every iteration — never a diff, never a fragment.** Change one decision, then re-emit the whole prompt so every slot still agrees with every other slot. This composes with the rule above rather than replacing it: *one delta* governs **what changes**, *full rewrite* governs **how you re-emit it**. A patched fragment leaves the old slots stale and silently contradicting the new one.
-  - On **Seedance**, a re-emit must keep the `Shot N` structure intact — see `slates-prompting-seedance`.
-  - **Exception — Omni Flash Edit.** Long prompts documentedly destroy its fidelity. There the rule inverts: one short instruction plus *"Keep everything else the same."*
-- **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 a high-cost generation — anything past the confirm gate in `slates-cost-discipline` — 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."
+---
+name: slates-vision-feedback-loop
+description: "Inspect generated media against the brief, diagnose defects and choose a targeted correction. Use during production or iteration; covers reference review, image defects and model-specific failure receipts."
+---
+
+# 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. These sampled stills support appearance, framing and identity checks. They do not verify continuous motion, lip sync or sound. Use actual playback or an audio-capable host for those claims when available; otherwise report them unreviewed and retain the saved asset.
+
+## Pre-flight is automatic on the gen tools
+
+`slates_generate_video` and `slates_generate_image` 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 still-gate — never animate a bad frame
+
+<!-- @inject:still-gate -->
+**Inspect a start frame before animating it.** Repair a visible defect that would make the intended crop or performance unusable before spending on motion. A clean frame can be animated whenever the brief calls for movement; this check does not require an image stage for text-to-video.
+
+This is a cost rule as well as craft: a premium video call can cost many times an image correction. Broken geometry can turn to mush, oily textures can crawl and malformed objects can fall apart in motion. Fix a known source defect at the source instead of buying a more expensive copy. Judge intentional stylisation against the brief, not a universal photoreal standard. Additional image or video requests still follow the existing generation authorization.
+<!-- @end:still-gate -->
+
+## The pattern
+
+1. **Generate.** Call `slates_generate_image` with a prompt. The result is in your context as an image content block.
+2. **Evaluate on TWO axes — they are different questions:**
+   - **Brief-conformance** — what did the user actually want? Are the elements right? Composition? Lighting? Subject identity?
+   - **Defects** — run the slop rubric below. *A frame can match the brief perfectly and still be slop that mushes the moment it moves.* Checking only the first axis is how a bad frame reaches an expensive video call.
+3. **One of three outcomes:**
+   - **Right** → save it (bind to a frame, character slot, etc.) and move on.
+   - **Close, but adjustable** → refine with a specific delta, regenerate **once**.
+   - **Wrong direction** → diagnose the failed requirement. Refine within the supplied brief and existing authorization; ask only when the creative intent is unresolved or the next request needs fresh consent.
+
+## The defect rubric — five slop tells
+
+| Tell | What it looks like | Why it matters downstream |
+|---|---|---|
+| **Light with no transitions** | Flat-black pits instead of a shadow ramp; light that stops rather than falls off | Transfers onto every character or object added into that plate later |
+| **Broken-but-plausible objects** | Crates, railings, hardware, mechanisms you can *almost* read but that don't resolve | Turn to mush in motion, and the model multiplies them |
+| **Local logic breaks** | An effect present in only part of the frame — rain scratching one corner, wet ground under one figure | The video model's physical logic breaks along with it |
+| **Oily textures** | Soapy, licked-smooth surfaces that have lost their material identity | Reflections crawl in motion; the plate can't hold continuity |
+| **Too perfect** | A soft light on the face that nothing in the scene could cast, the subject sharper and cleaner than everything around them, every region exposed to be readable, colour pushed warm and saturated | It reads as a subject pasted onto a location, and every shot built from the plate inherits the studio look. Fix it in words: `slates-cinematic-look` |
+
+### Per-model accents — check the one you actually used
+
+- **Nano Banana Pro** (`nano-banana-pro`) — ruler-straight symmetry, everything parallel and square, flat even light, pretty but staged/stock, textures reading as 3D render rather than photograph. **It hyperbolizes every edit**: ask for graffiti on one wall and the whole location gets tagged.
+- **GPT Image** (`gpt-image-2-5-flare`, `gpt-image-2-5-sunburst`) — microcontrast to the ceiling, hard halos on every edge, no depth or bokeh, white balance pulled warm until the frame yellows, plastic licked-smooth materials. Worst tell: **one sickly texture pattern laid over the entire frame**. ⚠️ Catalogued on `gpt-image-2`, which 2.5 replaced on 2026-09-09 — an accent is a per-model observation, so treat this as a prior to check rather than a finding, and correct it here the first time a 2.5 frame disagrees.
+
+> ⚠️ These are accents for **`nano-banana-pro`** and the **GPT Image** line specifically. `nano-banana-2` is a **different model** (Gemini 3.1 Flash Image vs NB Pro's Gemini 3 Pro Image) and we have **no evidence** about its accent. Do not inherit one — say nothing rather than warn about a failure mode you can't substantiate. That caution applies to the GPT Image entry above too: it was measured on `gpt-image-2`, not on either 2.5 seat.
+
+## Where the fault lives — triage before you change anything
+
+We say "one specific delta per regeneration" but that only helps once you know *which* variable to move. Diagnose first:
+
+| Visible pattern | Diagnosis | Fix |
+|---|---|---|
+| The defect exists in the source asset, or stays tied to the same feature when the direction changes | **Source asset** | Fix the sheet / plate, not the prompt |
+| Source is clean, and the defect changes when only the suspect motion clause changes | **Motion direction** | Fix the prompt |
+| Controls conflict, or the failure follows neither variable | **Inconclusive** | Narrow the test — change less, not more |
+
+**Review routes; it is not pass/fail.** Geography melts → fix the location. Identity drifts → fix the character sheet. Assets are sound but the action is wrong → fix the video direction. Wrong idea entirely → reopen the brief with the user.
+
+**Correct the earliest broken handoff.** Polishing a downstream symptom hides the source and guarantees it resurfaces in the next shot built from the same asset.
+
+## Baseline hygiene — isolate the variable you're testing
+
+When the **character** is the question, keep the location out of it: test on a plate that already holds its own geometry, depth, materials, and light. **A broken plate gives every character failure a second plausible cause**, and you will spend re-rolls deciding which one you're looking at. The same applies in reverse — test a plate empty before you populate it.
+
+## Refinement rules
+
+- **One specific delta per regeneration.** Don't change five things at once — you won't know what helped.
+- **A fresh generation needs a complete coherent prompt.** Change one decision and retain the unchanged requirements so old and new clauses do not conflict. An edit request uses its model's change-only grammar instead; do not turn a surgical edit into a full scene re-description.
+  - On **Seedance**, retain the selected model's structure: shot numbers for 2.0, whole-second timing where used for 2.5. See the matching model guide.
+  - **Exception — Omni Flash Edit.** Long prompts documentedly destroy its fidelity. There the rule inverts: one short instruction plus *"Keep everything else the same."*
+- **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.
+- Use the repeated-failure checkpoint below; do not keep submitting an unchanged failed request.
+- **Follow the existing consent for every attempt.** An approved enumerated batch covers its listed calls. A retry or changed input outside that batch needs a new quote and the applicable confirmation; a timeout requires a status check before another submission.
+
+<!-- @inject:iteration-diagnosis -->
+## Diagnose repeated failures
+
+After three failed attempts at the same requirement, pause unchanged re-rolls and diagnose the source reference, prompt structure, model fit and tool result. Three is a review checkpoint, not a universal limit or proof that the seed cannot matter. Preserve the attempts and name what each test changed.
+
+Continue autonomously when the brief is clear, a specific correction is supported and the next request is already authorized. Hand control back when taste or intent cannot be inferred, the next request needs fresh consent, or the available tool cannot meet the requirement. A failed roll never authorizes an additional charge. Follow the existing batch and per-request cost policy.
+<!-- @end:iteration-diagnosis -->
+
+## When to break the loop
+
+- The user said "good enough" or "ship it." Stop iterating.
+- Repeated attempts show no progress. Diagnose the source, prompt or model before spending again; apply the scoped retry rule above.
+- 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."

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

@@ -1,224 +0,0 @@
----
-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 is a NICHE pick, never the default (route per slates-model-selection — Kling is the general default, Seedance the premium tier) — reach for it only when native synchronized audio must generate WITH the video in one gen. 16:9 or 9:16, 4/6/8s. Different cinematography formula than Seedance/Kling. (no subtitles) is mandatory after every dialogue line.
----
-
-# Veo 3.1 — 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 — Veo 3.1.** Google's formula, in order: `[Cinematography] + [Subject] + [Action] + [Context] + [Style & Ambiance]`. Sweet spot 50-150 words; the official benchmark is about 50.
-
-**The five levers**
-1. **Open with the cinematography** — `Medium shot`, `low angle`, `aerial`, `dolly in`, `rack focus`, `vertigo effect`. Veo reads the first clause as the camera.
-2. **Texture words counter the AI-plastic look** — `fine skin pores`, `visible fabric weave`, `subtle contrast, no gloss or sharpening`. Name materials concretely: `charcoal cotton hoodie`, `matte concrete`, `silk lapel`.
-3. **Weight verbs stop floaty motion** — `trudges`, `drops heavily`, and a ground contact: `boots crunch on gravel`.
-4. **Terse voice direction only** — `says in a weary voice`, `whispers`, `mutters`. Veo is far less responsive to long voice blocks than Kling.
-5. **Always include an ambience line.** Without one the mix feels dead. `Soft office ambience.` `Wind on the open ridge.` And SFX always carries a cause: `SFX: thunder cracks in the distance`, never `SFX: thunder`.
-
-**Examples**
-- `Medium shot, a tired founder rubbing her temples in front of a bulky monitor in a cluttered office late at night. Harsh fluorescent overheads and the green glow of the screen. Fine skin pores, visible fabric weave on a charcoal cotton hoodie. Soft office ambience, a fan hum. Retro, slightly grainy.`
-- `Low angle, a farrier trudges across a wet yard carrying a shoeing box, boots crunching on gravel. Overcast north light, matte concrete and wet steel. Wind and distant livestock. He says in a weary voice, "One more and we're done." (no subtitles).`
-
-**Hard constraint:** `(no subtitles)` after EVERY dialogue line you do not want burned in as text. Negatives are NOUNS, not instructions — `wall, frame`, never `no walls`. And do not cross syntaxes: Seedance's `single continuous take` suppresses Veo's cuts, and Veo timestamps in a Seedance prompt cause drift.
-<!-- @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** (each one is spelled out above):
-- `single continuous take` — Seedance's phrase; in a Veo prompt it suppresses the cuts you asked for
-- `no subtitles` is REQUIRED after dialogue, but instruction-shaped negatives are not: `no walls`, `no man-made structures`, `don't show` — negatives are NOUNS here
-- `SFX: thunder` and any label-only effect — every effect carries a cause and a distance
-<!-- @banned:end -->
-
-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 (4K video requires Slates Pro).
-
-**Native single-shot duration: 4, 6, or 8 seconds** — and **8s only** at 1080p or 4K, or whenever you attach reference images (that endpoint is 8s-fixed). 4s and 6s exist at 720p, text-to-video or single-start-frame only. 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 or 9:16** on the route Slates uses. `slates_generate_video` REFUSES anything outside these before submit and names the legal set — nothing is silently ignored or downgraded.
-
-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)
-
-<!-- @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 resolves `@mentions` / `#tags` into numbered citations. You can also bind references directly in scene prose, naming what each image supplies.
-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 Veo specifically
-
-- **Veo's idiom for rule 2 is plain-English role naming in the sentence itself** — *"Using the provided images for the detective, the woman, and the office setting, create a medium shot of…"* (see Ingredients-to-Video above). The role rides in the noun phrase, not in a separate label block.
-- **Rule 8 has a second reason to matter here:** Veo bakes subtitle text into the frame unless every dialogue line carries `(no subtitles)`. Text you did not ask for is the failure mode, not just text you did.
-
-## 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/)