@slatesvideo/shared 0.5.4 → 0.5.6

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

@@ -0,0 +1,110 @@
+---
+name: slates-prompting-seed-audio
+description: How to prompt Seed Audio 1.0 (ByteDance, via fal). Read before calling slates_generate_audio with model seed-audio. The one-pass audio SCENE model — dialogue, SFX and ambience together from ONE plain sentence. CRITICAL - it has NO duration parameter, so length must be named IN THE PROMPT TEXT and Slates bills the duration you request. Covers the one-sentence doctrine, the crowd-size rule, why Kling "SFX:" syntax hurts here, and the audio-refs-XOR-image input rule.
+---
+
+# Seed Audio 1.0 — prompting
+
+ByteDance's one-pass audio scene model, carried on fal (`bytedance/seed-audio-1.0`). It generates dialogue, sound effects and ambience **together**, from a single plain sentence. 1–120 seconds. It is the default audio model in Slates and the workhorse for continuity beds.
+
+## Where it routes
+
+- **Scene audio, room tone, ambience beds, crowd/nature soundscapes** — anything where several sounds share a space. One generation, not three layered ones.
+- **Fast scratch dialogue** when the exact wording is still moving. Once the script locks and the read has to be repeatable, switch to `eleven-v3`.
+- **NOT** a single effect that must land on a known frame — that is `eleven-sfx`, which takes an exact duration.
+- **NOT** music — that is `suno`.
+- **AUDIO-ONLY.** It cannot produce images or video.
+
+## THE RULES
+
+### 1. 🚨 There is no duration parameter — the words set the length
+
+This is the single most important fact about this model. Output length is driven by the prompt text ("… 15 seconds"), capped at 120s.
+
+**Slates handles this for you:** the `durationSeconds` param appends the duration to the prompt and **bills that number of seconds**. So:
+
+- Set `durationSeconds` to what you actually want.
+- **Do not also write a different length into your sentence.** Two numbers fight, and you pay for the one you selected, not the one you got.
+- If the returned clip is shorter than requested you still paid for the request — that is the deal that keeps the displayed price equal to the charge. Ask for what you need.
+
+<!-- slates-only -->
+The server re-derives the billed key from `durationSeconds` (a client cannot under-bill), probes the returned `audio.duration` after completion, and logs `SEED AUDIO BILLING DRIFT` if the model overshot. No auto-charge, no refund — the request is the contract.
+<!-- /slates-only -->
+
+### 2. One plain sentence. No production jargon.
+
+Field-proven (Higgsfield sprint, 2026-07-27/28). Working prompts look like this:
+
+```
+tiny applause of 2 or 3 people at an open mic. 15 seconds
+nature soundscape, wide open field cicadas and birds and a loon.
+a diner at 2am, one coffee machine hissing, cutlery somewhere behind the counter
+```
+
+Not this:
+
+```
+✗ AMBIENCE: interior diner, night. SFX: espresso machine (hiss, 2s), cutlery.
+✗ Wide shot of a diner. Slow push in. Warm tungsten. Ambient noise: ...
+```
+
+Shot language, camera moves and lighting belong to video prompts. Here they are just words the model has to ignore.
+
+### 3. Never bring Kling's audio syntax to this model
+
+`SFX:` and `Ambient noise:` prefixes and `Background music:` labels are **Kling 3.0 video** syntax. Seed Audio has no parser for them — it reads them as text in the scene and the output gets measurably worse. Describe the sounds directly instead.
+
+### 4. Name the crowd size, the room size, the distance
+
+The highest-leverage single edit on any bed. Unqualified nouns default big:
+
+| Vague | What it returns | Fixed |
+|---|---|---|
+| `applause` | a full auditorium | `tiny applause of 2 or 3 people` |
+| `traffic` | a highway | `one car passing on a wet residential street` |
+| `crowd` | a stadium | `four people talking at the next table` |
+
+Distance words (`far off`, `muffled through a wall`, `right next to the mic`) work the same way and are how you build depth in one sentence.
+
+### 5. Beds must outlast the cut
+
+Ask for a few seconds more than the clip needs so the edit has handles to fade through. A bed that ends exactly on the cut always sounds clipped. This is a product requirement, not a preference — it is why the duration control exists at all.
+
+### 6. Dialogue goes in quotes, inside the same sentence as the room
+
+```
+a tired bartender says, "we closed twenty minutes ago", glasses clinking behind him
+```
+
+Pick a preset voice when a specific speaker matters. Leave `voice` unset and the scene casts itself — which is usually right for crowd and background dialogue.
+
+Preset voices (20): `vivi_mixed_en_zh_ja_es_id`, `mindy_en_es_id_pt_zh`, `kian_en_zh`, `cedric_en_zh`, `sophie_en_zh`, `jean_en_zh`, `magnus_en_zh`, `mabel_en_zh`, `nadia_en_zh`, `opal_en_zh`, `pearl_en_zh`, `quentin_en_zh`, `corinne_mixed_en_zh`, `esther_mixed_en_zh`, `lyla_mixed_en_zh`, `tracy_es_zh`, `sandy_es_mixed_en_zh`, `felix_zh`, `celeste_zh`, `monkey_king_zh`.
+
+Set `multilingual: true` for non-English or mixed-language lines.
+
+### 7. Inputs: up to 3 audio clips **XOR** one image. Never both.
+
+- **Audio references** — up to 3 clips, each ≤30s and ≤10MB (wav/mp3/pcm/ogg_opus). Refer to them in the prompt as `@Audio1`, `@Audio2`, `@Audio3`: *"match the room tone of @Audio1"*.
+- **Image reference** — one image (jpeg/png/webp ≤10MB). The model scores what it sees.
+- Sending both is rejected by the API. Pick the one that carries the intent.
+
+### 8. The knobs, and when to touch them
+
+| Param | Range | Reach for it when |
+|---|---|---|
+| `speed` | 0.5–2.0 | Dialogue is racing or dragging against picture. |
+| `volume` | 0.5–2.0 | Rarely — normalize on the timeline instead. |
+| `pitch` | −12…+12 semitones | Ageing or shifting a voice. Small moves only; ±3 is already a lot. |
+| `multilingual` | bool | Non-English or code-switched lines. |
+| `sampleRate` | 8k–48k | Leave at 24000 unless you are matching an existing stem. |
+| `outputFormat` | mp3 / wav / pcm / ogg_opus | wav when this is going into a mix; mp3 otherwise. |
+
+## Iterating
+
+- A bed that came back wrong is almost always a **scale** problem (crowd/room too big) or a **jargon** problem (the sentence reads like a spec). Fix those two before touching `speed`/`pitch`.
+- Three failed takes on the same sentence means the sentence is wrong, not the seed. Rewrite it the way you would say it out loud.
+- Generations are cheap enough at short durations that auditioning two phrasings beats agonizing over one.
+
+## Content notes
+
+Provider-side moderation applies to voices and to recognizable real people. See slates-content-policy.

package/skills/slates-prompting-seedance.md

@@ -55,7 +55,7 @@ Seedance classifies your request from the phrasing. Use the pattern that matches
 
 > *"For edit / extend video tasks, directly use `<Video_N>` to refer to the video. **Do not use "reference `<Video_N>`"**, to avoid being incorrectly identified as a reference task."*
 
-This is easy to trip: Slates has an edit lane (`slates_generate_video` with `videoReferenceAssetId`, plus the Seedance edit/relocate routes). Writing *"reference video 1 and change the jacket to red"* gets classified as a **reference** task — the model generates a brand-new clip inspired by the source instead of editing it. Write *"Strictly edit video 1, and modify the blue jacket to red."*
+This is easy to trip: Slates has an edit lane<!-- slates-only --> (`slates_generate_video` with `videoReferenceAssetId`, plus the Seedance edit/relocate routes)<!-- /slates-only -->. Writing *"reference video 1 and change the jacket to red"* gets classified as a **reference** task — the model generates a brand-new clip inspired by the source instead of editing it. Write *"Strictly edit video 1, and modify the blue jacket to red."*
 
 ## Shot structure — "Shot 1 / Shot 2 / Shot 3" `[official :1563-1598]`
 
@@ -91,7 +91,7 @@ Every time a subject appears, it must be **explicitly referred to**. Two support
 
 Also official: keep descriptions concise, avoid redundancy, avoid semantic conflicts (contradictory traits for one subject), and prefer expressing spatial relationships through reference images rather than dense text. `[:1550-1556]`
 
-**`[slates]`** — the app composes this for you. `composeReferences()` cites each reference inline as `Name (image N)` / `Name (images 1 and 2)` in the exact order it sends them, which is ByteDance's own duplicate-character format (*"Zhang San (corresponding to image 1)"* `[:1976]`). You never hand-write role labels or index numbers.
+**`[slates]`** — the app composes this for you. `composeReferences()` cites each canonical character or environment reference inline as `Name (image N)` in the exact order it sends them, which is ByteDance's own duplicate-character format (*"Zhang San (corresponding to image 1)"* `[:1976]`). You never hand-write role labels or index numbers.
 
 ## Action description `[official :1602-1621]`
 
@@ -153,7 +153,7 @@ Seedance has **no `negativePrompt` field** — constraints go inline in this slo
 3. **Optimize reference assets** `[:1988]` — *"For character reference images, prioritize independent single-person photos. Three-view or multi-view assets are not recommended."*
 4. **Simplify the prompt** — do not paste a whole script; redundant copy confuses the model.
 
-**Scope this honestly.** This is troubleshooting for the twin problem in **multi-character frames**, not a blanket verdict on turnaround sheets. Practical rule for Slates:
+**Scope this honestly.** This is troubleshooting for the twin problem in **multi-character frames**, not a blanket verdict on identity sheets. Practical rule for Slates:
 
 - **Multi-character Seedance shot** → bind every character to its image, append the anti-twin constraint, and prefer single-person / dominant-portrait references over multi-view sheets.
 - **Single-character shot** → the standard character-sheet flow is fine.
@@ -206,13 +206,16 @@ Reference-to-video accepts up to **9 reference images, 3 reference videos, 3 aud
 
 ### Motion transfer & lip-sync recipes (reference video / audio)
 
-These aren't separate Seedance features — they're prompting strategies over reference media, and the Slates tools (`slates_generate_motion_transfer` / `slates_generate_lip_sync` with the seedance engine) compose them for you. When driving them by hand through `slates_generate_video`:
+These aren't separate Seedance features — they're prompting strategies over reference media.<!-- slates-only --> The Slates tools (`slates_generate_motion_transfer` / `slates_generate_lip_sync` with the seedance engine) compose them for you. When driving them by hand through `slates_generate_video`:<!-- /slates-only -->
 
-- **Motion transfer:** subject image as a reference + the driving clip via `videoReferenceAssetId` (2–15s) + `The character from image 1 performs the exact motion, choreography, and camera movement from video 1. Preserve the character's identity, appearance, and outfit.`
-- **Lip-sync / dialogue:** write the line in the prompt — `The person in video 1 says: "…"` — with `generate_audio` on (always on in Slates). A **video** source's own voice is cloned natively; an **audio** reference (`audioReferenceAssetId`, ≤15s) drives speech from an existing recording: `…speaks the dialogue from audio 1 with accurate lip sync.`
+- **Motion transfer:** subject image as a reference + the driving clip<!-- slates-only --> via `videoReferenceAssetId`<!-- /slates-only --> (2–15s) + `The character from image 1 performs the exact motion, choreography, and camera movement from video 1. Preserve the character's identity, appearance, and outfit.`
+- **Lip-sync / dialogue:** write the line in the prompt — `The person in video 1 says: "…"` — with audio generation on (always on in Slates). A **video** source's own voice is cloned natively; an **audio** reference (≤15s) drives speech from an existing recording: `…speaks the dialogue from audio 1 with accurate lip sync.`
 - **Voice + face from one clip (the talking-head recipe):** ONE unedited 2–15s clip of the person speaking (clear voice, no music, no cuts) as the video reference + prompt with the new script → their likeness AND voice deliver the new line.
+<!-- slates-only -->
 - **Billing:** a reference VIDEO switches the cost key to `seedance-2*-vref-{res}-{T}s` where T = clip seconds + output seconds — quote before confirming. Audio references are free (audio is included on every route).
+<!-- /slates-only -->
 
+<!-- slates-only -->
 ## Faces — set `seedanceFace` for AI-character faces
 
 Seedance routes through **three tiers** depending on the face in the reference, exposed as the "Face in Reference" toggle plus the real-face params on `slates_generate_video`:
@@ -223,8 +226,9 @@ Seedance routes through **three tiers** depending on the face in the reference,
 
 Rules:
 - **The real-vs-AI call is the PROVIDER'S, not yours.** ByteDance's classifier is probabilistic — some real photos pass the standard face route (billed at the cheap rate; fine), others get rejected with `[REAL_FACE_DETECTED]` (auto-refunded). Don't preemptively route to the real-face tier just because a photo looks real; try `seedanceFace: true` first and escalate only on the marked rejection. Public figures / celebrities fail on every route.
-- It's about the **reference, not the output.** If your character refs (turnaround, expression sheet, a generated portrait) show a face, turn it on. A product shot with no person stays off.
+- It's about the **reference, not the output.** If your character identity or generated portrait shows a face, turn it on. A product shot with no person stays off.
 - Don't toggle it on "just in case" — a faceless gen on the face route burns ~45% extra for nothing.
+<!-- /slates-only -->
 
 ## Reference rules (the verified ones)
 
@@ -247,7 +251,7 @@ Identity = a few flat-lit neutral angles; one reference per role, named inline;
 
 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 — and whatever you do attach for a subject, NAME it as one entity.** A character's identity sheet 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 always better, because the model cannot tell which one is authoritative and averages them.** Where a character carries a second bound sheet — an explicit expression range, or a legacy turnaround+expression pair — cite BOTH under the SAME name, `Marcus (images 1 and 2)`. That shared name, not a role essay, is what tells the model they are ONE person and stops the varied expressions from averaging the face. **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.
+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.
@@ -259,12 +263,13 @@ Identity = a few flat-lit neutral angles; one reference per role, named inline;
 
 ### For Seedance specifically
 
-- **Describe the ACTION, never the reference's content.** With refs attached, prompt only what is *happening* — motion, change, camera. Never re-describe what's in the reference, and never say "still / scene / from a movie / from the image." The model already sees the refs; narrating them wastes tokens and induces drift. Injection is stochastic — if a roll misses, **re-roll, don't re-engineer** (and a slow gen is not a failed one — see slates-cost-discipline).
+- **Describe the ACTION, never the reference's content.** With refs attached, prompt only what is *happening* — motion, change, camera. Never re-describe what's in the reference, and never say "still / scene / from a movie / from the image." The model already sees the refs; narrating them wastes tokens and induces drift. Injection is stochastic — if a roll misses, **re-roll, don't re-engineer** (and a slow gen is not a failed one<!-- slates-only --> — see slates-cost-discipline<!-- /slates-only -->).
 - **Seedance's own idiom for rule 2 is `Reference <Subject_N> in <Image_N>`** `[official :1389]` — `Image_N` indexes the order the refs are attached, so the name plus the index carries the role. The full binding grammar is in Part 1 (Subject binding).
 - **Rule 3 has an official ceiling here.** The trend is MORE references (video and audio into Seedance), all addressed by name — but for **multi-character frames** see the twin-problem section above: bind every character to its image, append the anti-twin constraint, and prefer single-person references. Past 4 reference people, stability drops `[official :2048-2052]`.
 - **Rule 8 holds even though Seedance can render common text natively** `[official :1758]`. A baked NB2 start frame is still the reliable route for text that must be legible.
 - **Rule 5 pairs with the first/last-frame exclusion** — frames and reference images are mutually exclusive on this model (see Reference media above), so an environment you must match exactly costs you the frame lane.
 
+<!-- slates-only -->
 ## 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`.
@@ -273,6 +278,7 @@ When talking to the user about the gen, refer to each reference by its short cod
 
 - ✅ "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.)
+<!-- /slates-only -->
 
 ---
 

package/skills/slates-prompting-suno.md

@@ -0,0 +1,110 @@
+---
+name: slates-prompting-suno
+description: How to prompt Suno in Slates. Read before calling slates_generate_audio with model suno. Full music tracks - EVERY call returns TWO variations for one flat price and duration is FREE up to 360 seconds. The rule that decides everything - in CUSTOM mode the prompt field is the EXACT LYRICS (sung as written), in DESCRIPTION mode it is a description and the lyrics get written for you. Covers the mode matrix, style vs prompt steering, instrumental scoring, negative tags, and the character caps.
+---
+
+# Suno — prompting
+
+Full music generation, reached through the sunoapi.org wrapper. Models `V4`, `V4_5`, `V4_5PLUS`, `V4_5ALL`, `V5`, `V5_5`.
+
+**Two facts that should shape every decision:**
+
+1. **Every call returns TWO songs** — two genuinely different takes on the same brief, for one flat price. Audition both before re-rolling.
+2. **Length is free.** A 360-second track costs exactly what a default one costs (measured against the live provider balance 2026-07-31: a default call and a `duration: 240` call both debited the same). There is never a reason to generate a bed shorter than your edit.
+
+## Where it routes
+
+- **Anything a listener would call a song or a score** — theme, underscore, needle-drop, montage bed, end-card sting.
+- **NOT** ambience or room tone — that is `seed-audio`, which is cheaper and better at it.
+- **NOT** a single effect — that is `eleven-sfx`.
+- **AUDIO-ONLY.**
+
+## 🚨 THE RULE: which mode you are in changes what `prompt` means
+
+| `customMode` | `instrumental` | Required | What `prompt` means |
+|---|---|---|---|
+| `false` | either | `prompt` only (≤500 chars) | **A description.** Lyrics get written for you. |
+| `true` | `true` | `style`, `title` | **Unused.** Style + title do all the steering. |
+| `true` | `false` | `style`, `title`, `prompt` | **THE EXACT LYRICS**, sung as written. |
+
+Putting a description in the prompt field while `customMode: true` and `instrumental: false` gets your description **sung back at you**. This is the single most common Suno mistake and it costs a full generation every time.
+
+## Description mode — the fast path
+
+```
+customMode: false
+prompt: "brooding synthwave for a night drive, analog bass, no vocals, 90 bpm"
+```
+
+Use it when you need a mood and do not care about specific words. 500-character cap. This is the right default for background beds.
+
+## Custom mode — when the words matter
+
+```
+customMode: true
+instrumental: false
+style:  "dream pop, hazy, reverb-heavy guitars, female vocal, 100 bpm"
+title:  "Blue Hour"
+prompt: "[Verse 1]\nThe lights come on before we're ready\n..."
+```
+
+Structure tags (`[Verse]`, `[Chorus]`, `[Bridge]`, `[Outro]`) inside the lyrics are how you control the arrangement. Everything that is not a structure tag will be sung.
+
+## Instrumental scoring
+
+```
+customMode: true
+instrumental: true
+style: "tense orchestral strings, low brass swells, no percussion"
+title: "Approach"
+```
+
+`instrumental: true` is the right answer for almost every film bed — a vocal you did not ask for will fight your dialogue.
+
+## Steer with `style`, not with adjective piles
+
+Genre + era + instrumentation + tempo belong in `style`, not stuffed into `prompt`.
+
+```
+✓ style: "90s trip-hop, dusty breakbeat, Rhodes piano, upright bass, 85 bpm"
+✗ prompt: "a really cool dusty 90s trip hop song with a Rhodes and..."
+```
+
+`negativeTags` removes what keeps creeping in: `"brass, EDM drop, male vocal"`.
+
+## The steering knobs
+
+| Param | Range | Reach for it when |
+|---|---|---|
+| `duration` | 10–360s (**V5_5 + custom mode only**) | Always, when the bed must outlast the cut. It is free. |
+| `vocalGender` | `m` / `f` — **the wire values, not "male"/"female"** | A specific voice is required. |
+| `styleWeight` | 0–1 | The style field is being ignored (raise) or strangling the song (lower). |
+| `weirdnessConstraint` | 0–1 | Takes are too safe (raise) or falling apart (lower). |
+| `audioWeight` | 0–1 | Balancing an audio input against the prompt. |
+| `personaId` / `personaModel` | — | A series needs the same voice/sound across episodes. |
+
+## Character caps
+
+| Field | V4 | V4_5 / V4_5PLUS / V5 / V5_5 | V4_5ALL |
+|---|---|---|---|
+| prompt (custom = literal lyrics) | 3000 | 5000 | 5000 |
+| prompt (non-custom = description) | 500 | 500 | 500 |
+| style | 200 | 1000 | 1000 |
+| title | 80 | 100 | 80 |
+
+## Iterating
+
+- **Audition both returned songs first.** A re-roll costs a full generation; the second variation is already paid for.
+- Wrong genre → fix `style`. Wrong words → you are in the wrong mode, check the matrix above.
+- Something keeps appearing that you do not want → `negativeTags`, not more prompt.
+- Three failed generations on the same brief means the style field is too vague, not that the seed is unlucky.
+
+## Ops notes
+
+- Tracks take 2–3 minutes; a streamable preview exists ~30–40s in. Use `background: true` and poll.
+- The provider hosts files for a limited window — **Slates downloads and stores them locally as soon as the track finishes**, so nothing expires out from under a project.
+- Suno has **no official public API**; this rides an unofficial wrapper. Treat availability as best-effort and do not build a deadline around it.
+
+## Content notes
+
+Provider-side moderation rejects lyrics and style prompts naming real artists or protected material (`SENSITIVE_WORD_ERROR`). Describe the sound, not the artist. See slates-content-policy.

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

@@ -117,7 +117,7 @@ Identity = a few flat-lit neutral angles; one reference per role, named inline;
 
 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 — and whatever you do attach for a subject, NAME it as one entity.** A character's identity sheet 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 always better, because the model cannot tell which one is authoritative and averages them.** Where a character carries a second bound sheet — an explicit expression range, or a legacy turnaround+expression pair — cite BOTH under the SAME name, `Marcus (images 1 and 2)`. That shared name, not a role essay, is what tells the model they are ONE person and stops the varied expressions from averaging the face. **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.
+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.