@slatesvideo/shared 0.4.2 → 0.4.4

package/skills/slates-prompting-kling-v3.md

@@ -106,9 +106,9 @@ Upload 2-4 multi-angle reference photos per character/object. Tag inline:
 
 ## Reference discipline (character / environment refs)
 
-- **2-4 strong refs per role**, labeled (which element is which) and reused across every shot — swapping mid-sequence drifts.
+- **2-4 strong refs per role**, named (the same fixed label reused verbatim) and reused across every shot — swapping mid-sequence drifts. Kling's consistency lever is **"lock the subject with a fixed label reused verbatim"** (pronoun/synonym drift breaks it), so reusing the exact name on every mention is the whole game. Slates composes this for you from `@mentions`.
 - **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.
+- **Attach both character sheets, named as one entity** — the turnaround (body/proportion/outfit) and the close-up expression sheet (face detail), cited under the same name. The shared name keeps the varied expressions from averaging the face; don't write a role essay or tell it to "render neutral" — the user's prompt owns the expression, wardrobe, and lighting.
 - **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 — has a real field

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

@@ -96,27 +96,19 @@ Default to #1. Reach for #2 only when positive framing can't suppress the unwant
 ## 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]
-```
+- **Name each reference inline — Slates does this for you.** When you `@mention` a subject/environment or `#mention` a style (or pass `referenceAssetIds`), Slates composes the prompt so each reference is named inline as "image N" — e.g. `Marcus (images 1 and 2) sits across from the woman (images 3 and 4) in the cafe (image 5)`, with a trailing `Render in the visual style of image 6.` The model does NOT infer a reference's role from its position; the NAME carries it. NB2's own consistency lever is literally **"assign a distinct name to each character/object"**, so citing both of a subject's sheets under the SAME name ("Marcus") is what tells the model they are ONE person and stops the face averaging. **Do NOT hand-write a "Reference Image Instructions" block or role essays** ("use for identity, ignore the outfit, render the scene's expression") — that drags the sheet's wardrobe + studio lighting into the scene. The prompt leads; the user's words own wardrobe, expression, lighting, and action.
 
 ### 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.
+2. **One reference per ROLE, named** (identity / style-grade / environment). Same-role competitors drift. The model doesn't infer roles from order — the inline name does it.
+3. **Identity refs: attach both sheets, named as one entity — 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, cited under the SAME name ("Marcus (images 1 and 2)"). That shared name — not a role essay — is what stops the varied expressions from averaging the face. An *unnamed* expression sheet hurts; named as one entity, 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.
+- **Injection is stochastic — budget 3-5 re-rolls per shot; re-roll, don't re-engineer.** First rolls miss faces/hands; the same prompt lands a clean one within a few tries.
 
 ## Common failure modes + fixes
 

package/skills/slates-prompting-seedance.md

@@ -83,11 +83,24 @@ Reference-to-video endpoint accepts up to **9 reference images, 3 reference vide
 
 **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.
 
+## Faces — set `seedanceFace` for AI-character faces
+
+Seedance routes through **two providers** depending on whether a reference shows a **face**, and the app exposes this as the "Face in Reference" toggle (param `seedanceFace` on `slates_generate_video`):
+
+- **Faceless / object / environment refs → default route (cheapest).** Leave `seedanceFace` off.
+- **An AI-character's FACE in a reference → `seedanceFace: true`.** The default (BytePlus) route's baseline moderation rejects or degrades faces, so this reroutes to the face-capable provider (relaxed mode). It costs **~10% more** — the cost key becomes `seedance-2-face-{res}-{N}s`, so the pre-flight quote already reflects it. Announce the face-route price, not the faceless one.
+
+Rules:
+- **AI-generated characters only.** Real people (yourself, an actor, a photo of a real person) are **walled on every route** — ByteDance's Feb-2026 real-person policy. Never promise "upload a real face and animate it"; it will be rejected. The toggle is for fictional/AI characters.
+- 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.
+- Don't toggle it on "just in case" — a faceless gen on the face route just burns the +10% for nothing.
+
 ## Reference rules (the verified ones)
 
+- **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).
 - **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.
+- **One reference per ROLE, named in the prompt.** Seedance's official idiom is **"Reference \<Subject_N\> in \<Image_N\>"** — `Image_N` indexes the order the refs are attached, so the name + index carries the role; the model doesn't infer it from order alone. Slates composes this for you from `@mentions`: it cites each reference inline as "image N" in the exact order it sends them. You don't hand-write role labels.
+- **Character identity: attach the turnaround AND the close-up expression sheet, named as one entity** — cite both under the same name. The shared name — not a role essay — is what keeps the varied expressions from averaging the face; don't gate the expression sheet, and don't tell it to "render neutral / ignore the outfit" (the user's prompt owns expression, wardrobe, and lighting). The trend is MORE references (video/audio into Seedance), all addressed by name — lean into attaching rich refs and let the naming do the work.
 - **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.

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

@@ -98,9 +98,9 @@ Verbatim example:
 
 ## Reference discipline (character / environment refs)
 
-- **2-4 strong refs per role**, labeled (name what each provided image is for) and reused across every shot.
+- **2-4 strong refs per role**, named inline (Slates cites each as "image N" from your `@mentions`) and reused across every shot. The model doesn't infer a ref's role from order — the name does it.
 - **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.
+- **Attach both character sheets, named as one entity** — the turnaround (body/proportion/outfit) and the close-up expression sheet (face detail), cited under the same name. The shared name keeps the varied expressions from averaging the face; don't write a role essay or "render neutral" instruction — the user's prompt owns the expression, wardrobe, and lighting.
 - **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