@slatesvideo/shared 0.5.4 → 0.5.6

package/dist/prompts/character-sheet.d.ts

@@ -4,33 +4,23 @@
  * pixels, so it gets the resolution. The body panels exist for build,
  * proportion, wardrobe and hair, not for the face.
  *
- * The back panel KEEPS its head on purpose: it has no face to compete with the
- * portrait, and it is the only panel where hair fall reads.
+ * The front panel is headless and the back panel KEEPS its head — that
+ * asymmetry is the whole rule. A front-facing body panel renders a ~40px face
+ * that cannot match the portrait's, so the sheet would carry two competing
+ * identities and the model averages them. A back view has no face to compete
+ * with, and it is the only panel where hair fall reads. See the header comment
+ * for the receipt, and for why the phrasing must stay FRAMING rather than
+ * removal and must be SCOPED TO THE FACE rather than to the whole body.
  */
 export declare const CHARACTER_SHEET_PANELS_DESC: string;
 /** Panel identifiers, in sheet order. */
 export declare const BODY_POSE_LABELS: readonly ["portrait", "front", "back"];
 /**
- * Expression-sheet close-ups — LEGACY. Kept so characters built before the
- * 2026-07-21 single-sheet architecture keep regenerating correctly, and so the
- * expression slot remains usable for a character that genuinely needs a
- * dedicated expression range.
- */
-export declare const CHARACTER_EXPRESSIONS_DESC = "neutral expression on left, genuine smile showing teeth in center, serious frown on right";
-export declare const EXPRESSION_LABELS: readonly ["neutral", "smile", "serious"];
-/**
- * The character identity sheet — one asset, three panels, bound to the
- * turnaround slot. Named `buildCharacterTurnaroundPrompt` for continuity with
- * every existing caller and with the slot it binds to.
+ * The character identity sheet — one asset, three panels.
  *
  * @param userStyle optional natural-language style transform (e.g. "make her a real person")
  */
-export declare function buildCharacterTurnaroundPrompt(userStyle?: string | null): string;
-/**
- * Expression sheet — LEGACY close-up face reference. Since 2026-07-21 the
- * identity sheet above is the default and this slot is normally left null.
- * Generate one only when a character needs an explicit expression range;
- * attaching it costs a second reference slot on every generation.
- */
-export declare function buildExpressionSheetPrompt(userStyle?: string | null): string;
+export declare function buildCharacterIdentityPrompt(userStyle?: string | null): string;
+/** @deprecated Use buildCharacterIdentityPrompt. */
+export declare const buildCharacterTurnaroundPrompt: typeof buildCharacterIdentityPrompt;
 //# sourceMappingURL=character-sheet.d.ts.map

package/dist/prompts/character-sheet.js

@@ -2,41 +2,118 @@
 //
 // ARCHITECTURE (locked by Eric 2026-07-21): ONE identity sheet per character.
 // A dominant off-frontal chest-up portrait carries the face; two full-body
-// panels (front + back) carry build, wardrobe and hair. The sheet binds to the
-// character's TURNAROUND slot and the expression slot is left null.
+// panels (front + back) carry build, wardrobe and hair. The result is the
+// character's one canonical identity reference.
 //
 // Why one sheet and not two — three arguments, none of which depend on a
 // comparison generation:
-//   1. Reference-cap economics. Every `@character` mention pushes BOTH bound
-//      sheets into one reference group, so a two-sheet character costs TWO
-//      reference slots on every generation. Against real caps that is brutal:
-//      Kling 3.0 takes 4 ingredients (2 characters, zero room for an
-//      environment), NB2 has 4 character slots, Seedance 9. One sheet each
-//      DOUBLES the cast you can stage on every model we route to.
-//   2. Competing face renderings drop 6 → 2. The old pair sent three large
-//      portraits plus three postage-stamp faces (turnaround front + both
-//      profiles). The model cannot tell which rendering is authoritative and
-//      averages them; ByteDance documents the same root cause for its
-//      duplicate-character failure (ModelArk :1959) and prescribes fewer
-//      competing views. Both profile panels disappear with the shape change.
-//   3. One generation instead of two per character — half the sheet spend, one
-//      asset to inspect and bind.
+//   1. Reference-cap economics. Every character uses one reference slot.
+//   2. One authoritative face avoids averaging competing renderings.
+//   3. One generation means one asset to inspect and bind.
 //
-// KNOWN COST, accepted for v1: a neutral chest-up portrait carries no dental
-// information, so a character who smiles in a shot gets invented teeth. The
-// 2026-06-26 doctrine already holds that the user's prompt owns expression.
-// Revisit only if a receipt shows invented teeth.
+// EXPRESSION IS A SLIGHT SMILE WITH THE TEETH JUST VISIBLE (Eric, 2026-07-30,
+// replacing the v1 neutral default). The v1 note called neutral's missing
+// dental information a "known cost, revisit only if a receipt shows invented
+// teeth" — this is that revisit, and it arrived from the other direction:
+// Eric hand-edited a sheet to smiling and the result "worked really well".
 //
-// DEFERRED, not rejected: cropping the face off the front body panel (the
-// "ghost mannequin" treatment). Adopting this layout takes competing faces
-// 6 → 2 for free; the crop buys only 2 → 1, and it is contradicted by the only
-// visible output in the source corpus. Flipping it later is a one-line change
-// here — no migration, no data touched.
+// WHY: a closed-mouth portrait carries ZERO dental information, so every
+// downstream shot where the character smiles has to invent teeth, and teeth are
+// person-specific and stable — inventing them is a highly visible identity
+// break. The smile also records the nasolabial fold, the eye crinkle and where
+// the cheeks sit raised, none of which a neutral mouth shows.
 //
-// BACK-COMPAT IS MANDATORY: ~20 live users have characters bound to BOTH
-// slots. `buildExpressionSheetPrompt` stays exported and the expression slot
-// stays readable; `mentions.ts` only pushes non-null paths, so old two-sheet
-// characters and new one-sheet characters both work unchanged.
+// THE COST, NAMED: `references-read-literally.md` says a baked-in property is
+// read as a property of the SUBJECT, so a smile risks a character who smiles
+// through a beat that asked for grief. Survivable because the 2026-06-26
+// doctrine still holds — the user's prompt owns expression, and downstream
+// prompts name an emotional register on every delivered line.
+//
+// SLIGHT, never a grin: a broad smile deforms eyes, cheeks and mouth enough
+// that the model has to un-deform it for any neutral shot.
+//
+// NON-HUMANS ARE CARVED OUT (Eric, 2026-07-30). A smile clause on a horse, a
+// dragon or a robot produces bared teeth. Non-human characters get a natural
+// neutral expression instead. NOTE THE SCOPE DIFFERS from the A-pose carve-out
+// beside it: that one is anatomical (quadruped / non-bipedal), this one is
+// about having a human mouth — so a BIPEDAL robot or humanoid alien is covered
+// by this carve-out and not by that one. Two carve-outs, deliberately, because
+// one predicate does not fit both.
+//
+// Receipt strength: N=1, and it is a "looked right" judgement, not a scored
+// identity-hold comparison against the neutral sheets. HOW YOU'D KNOW THIS IS
+// BEATEN: a character smiling through a beat prompted angry or grieving, or
+// identity holding measurably worse than neutral did. Reverting is one line.
+//
+// THE FRONT PANEL IS HEADLESS (shipped 2026-07-22, receipt-gated). The face is
+// cropped off the front body panel, taking competing face renderings 2 → 1.
+// ONLY the face — the body, neck, arms and hands render normally; see the
+// 2026-07-30 (b) note below for what happens when that isn't said. The BACK
+// panel keeps its head: it has no
+// face to compete with the portrait, and it is the only panel where hair fall
+// reads. The rule is "kill every competing rendering of the FACE", not "kill
+// every head".
+//
+// Two things had to be true before this shipped, and both were verified on
+// real generations (research/model-prompting-research.md, "Head-crop receipt"):
+//   1. It is prompt-reachable. NB2 renders a clean invisible-mannequin panel
+//      with no refusal. THIS DEPENDS ON THE PHRASING: it is framed as FRAMING
+//      ("cropped at the collarbone, invisible-mannequin presentation"), a
+//      standard e-commerce genre with deep training data. Never phrase it as
+//      removal or decapitation.
+//
+//      2026-07-30 (a) — THE PHRASING NARROWED, and the receipt above was
+//      MODEL-SCOPED. "framed from the collarbone down with the head not shown"
+//      passed NB2 and is a HARD 422 on gpt-image-2: fal returns
+//      content_policy_violation with loc ["body","prompt"], so the text is
+//      rejected before any image is read. Diagnosis: "the head not shown"
+//      states an anatomical ABSENCE — a headless human body — which reads as
+//      gore to OpenAI's classifier. "cropped at the collarbone" states a
+//      CAMERA fact and carries the same instruction.
+//      RULE: describe an exclusion as a framing choice, never as a missing
+//      body part. The "invisible-mannequin" genre anchor is KEPT because the
+//      NB2 receipt says it is what makes the panel reachable there.
+//      HOW YOU'D KNOW THIS IS BEATEN: a front panel that comes back with a
+//      head on it, meaning "cropped at the collarbone" alone is too weak
+//      without the absence clause. If that happens, the fix is a
+//      model-conditional phrasing, not restoring the 422.
+//
+//      2026-07-30 (b) — THE GENRE ANCHOR HAS TO BE SCOPED TO THE FACE, and
+//      this one cost real generations. "an invisible-mannequin presentation
+//      WHERE THE CLOTHING HOLDS ITS OWN SHAPE" is the e-commerce genre stated
+//      in full — and the full genre means NO BODY AT ALL, an empty outfit
+//      photographed on nothing. Eric's sheets came back with the skin removed:
+//      no neck, no hands, no forearms, a floating garment. The genre anchor
+//      was doing exactly what it says.
+//      Eric's replacement, verbatim, and the default since: "an invisible-
+//      mannequin presentation with just the face cropped out." Same anchor
+//      (still what makes the panel reachable on NB2), bounded so the only
+//      thing missing is the face.
+//      RULE: a genre anchor imports the WHOLE genre unless you bound it —
+//      name what STAYS, not just what goes. This is the same failure shape as
+//      (a) from the opposite side: (a) was an exclusion phrased too
+//      anatomically, (b) was an exclusion scoped too widely.
+//      HOW YOU'D KNOW THIS IS BEATEN: front panels returning with a head on
+//      them — "just the face cropped out" would then be reading as a face
+//      edit rather than a crop, leaving the collarbone clause to carry it
+//      alone.
+//   2. The literal-reading law does NOT fire on it. This was the real risk and
+//      it is ours, not the source corpus's: `references-read-literally.md` says
+//      a baked-in property is read as a property of the SUBJECT, and this panel
+//      renders headlessness as CONTENT (empty plate above the collar), not as
+//      photographic framing. The predicted failure was a headless or
+//      neck-glitched downstream character. A Kling shot from a bound sheet came
+//      back head intact, identity holding, wardrobe held — in a MULTI-CHARACTER
+//      frame, which is the scope ByteDance's averaging failure lives in
+//      (ModelArk :1948-1994), so it is the hardest form of the test.
+//
+// Receipt strength: N=1 character, decisive for filterability, strong for the
+// literal-reading risk, NOT a scored V2-vs-V3 comparison — nobody measured
+// whether 2 → 1 improves identity hold, only that it doesn't break. HOW YOU'D
+// KNOW THIS IS BEATEN: a downstream character generating headless,
+// neck-glitched, or with a floating collar; or a scored run where heads-kept
+// holds identity better. Reverting is a one-line change here — no migration,
+// no data touched. Quadrupeds are carved out below (a horse has no collarbone).
 //
 // SOURCE OF TRUTH. The desktop imports these builders through
 // `slate/src/shared/prompts/character-sheet.ts` (a thin re-export since 1.2.1)
@@ -50,22 +127,20 @@ import { renderStyleInstruction } from './style-library.js';
  * pixels, so it gets the resolution. The body panels exist for build,
  * proportion, wardrobe and hair, not for the face.
  *
- * The back panel KEEPS its head on purpose: it has no face to compete with the
- * portrait, and it is the only panel where hair fall reads.
+ * The front panel is headless and the back panel KEEPS its head — that
+ * asymmetry is the whole rule. A front-facing body panel renders a ~40px face
+ * that cannot match the portrait's, so the sheet would carry two competing
+ * identities and the model averages them. A back view has no face to compete
+ * with, and it is the only panel where hair fall reads. See the header comment
+ * for the receipt, and for why the phrasing must stay FRAMING rather than
+ * removal and must be SCOPED TO THE FACE rather than to the whole body.
  */
 export const CHARACTER_SHEET_PANELS_DESC = 'a large chest-up portrait on the left at a three-quarter angle (never dead-on), ' +
-    'a full-body front view in a relaxed A-pose in the centre, ' +
-    'and a full-body back view on the right';
+    'a full-body front view in a relaxed A-pose in the centre, cropped at the collarbone — ' +
+    'an invisible-mannequin presentation with just the face cropped out, ' +
+    'and a full-body back view on the right with the head and hair fully visible';
 /** Panel identifiers, in sheet order. */
 export const BODY_POSE_LABELS = ['portrait', 'front', 'back'];
-/**
- * Expression-sheet close-ups — LEGACY. Kept so characters built before the
- * 2026-07-21 single-sheet architecture keep regenerating correctly, and so the
- * expression slot remains usable for a character that genuinely needs a
- * dedicated expression range.
- */
-export const CHARACTER_EXPRESSIONS_DESC = 'neutral expression on left, genuine smile showing teeth in center, serious frown on right';
-export const EXPRESSION_LABELS = ['neutral', 'smile', 'serious'];
 // The sheet's style directive: a user transform REPLACES the inherit-source
 // instruction (so the model isn't told to both preserve the medium AND change
 // it); otherwise inherit the source medium.
@@ -73,31 +148,21 @@ function styleDirective(userStyle) {
     return renderStyleInstruction(userStyle).trim() || INHERIT_SOURCE_STYLE;
 }
 /**
- * The character identity sheet — one asset, three panels, bound to the
- * turnaround slot. Named `buildCharacterTurnaroundPrompt` for continuity with
- * every existing caller and with the slot it binds to.
+ * The character identity sheet — one asset, three panels.
  *
  * @param userStyle optional natural-language style transform (e.g. "make her a real person")
  */
-export function buildCharacterTurnaroundPrompt(userStyle) {
+export function buildCharacterIdentityPrompt(userStyle) {
     return (`A single character identity reference sheet of one character, three panels side by side on one plate: ` +
         `${CHARACTER_SHEET_PANELS_DESC}. ` +
         `The portrait is the largest panel and occupies roughly a quarter to a third of the sheet — it is the sole authority for the face, so render it at maximum facial detail. ` +
-        `Neutral expression and identical appearance, wardrobe and hair across all three panels. ` +
+        `No second rendering of the face anywhere on the sheet. ` +
+        `A slight natural smile with the teeth just visible, and identical appearance, wardrobe and hair across all three panels. ` +
         `${styleDirective(userStyle)} ${IDENTITY_LIGHTING_CLAUSE} ${IDENTITY_CRAFT_CLAUSE} ` +
-        `For quadruped or non-bipedal characters, replace the A-pose with a natural standing stance and keep the same three-panel layout. ` +
+        `For non-human characters, use a natural neutral expression instead of a smile. ` +
+        `For quadruped or non-bipedal characters, replace the A-pose with a natural standing stance, show the whole animal including the head on both body panels, and keep the same three-panel layout. ` +
         `No text, no labels, no captions, no panel borders.`);
 }
-/**
- * Expression sheet — LEGACY close-up face reference. Since 2026-07-21 the
- * identity sheet above is the default and this slot is normally left null.
- * Generate one only when a character needs an explicit expression range;
- * attaching it costs a second reference slot on every generation.
- */
-export function buildExpressionSheetPrompt(userStyle) {
-    return (`Character expression reference sheet with 3 head and shoulder portraits arranged side by side horizontally: ${CHARACTER_EXPRESSIONS_DESC}. ` +
-        `Consistent character appearance across all three. ` +
-        `${styleDirective(userStyle)} ${IDENTITY_LIGHTING_CLAUSE} ${IDENTITY_CRAFT_CLAUSE} Same framing for each. ` +
-        `No text, no labels, no captions.`);
-}
+/** @deprecated Use buildCharacterIdentityPrompt. */
+export const buildCharacterTurnaroundPrompt = buildCharacterIdentityPrompt;
 //# sourceMappingURL=character-sheet.js.map

package/dist/prompts/model-facts.d.ts

@@ -1,7 +1,7 @@
 export interface ModelFact {
     id: string;
     label: string;
-    kind: 'image' | 'video';
+    kind: 'image' | 'video' | 'audio';
     /** Max reference images (image models) — null if not applicable. */
     maxRefImages: number | null;
     /** Max ingredient images (video models) — null if not applicable. */

package/dist/prompts/model-facts.js

@@ -103,6 +103,38 @@ export const MODEL_FACTS = [
         maxIngredients: 0, // prompt + source clip ONLY — no element/style refs on this endpoint
         notes: 'VIDEO-TO-VIDEO EDIT, prompt-only — THE EDIT-FIDELITY WINNER (7/09 head-to-head vs Kling edit on real talking footage: lips held perfectly, audio near-identical, both action beats landed). Takes an EXISTING 3-10s clip and changes what the prompt names, footage-synced (prop/effect/environment/lighting swaps). Fidelity is EARNED by prompt discipline: ONE short instruction + "Keep everything else the same." — long descriptive prompts DESTROY it (Google-documented + 7/09 receipt). Never name objects as metaphors ("candle-like" → literal candle). Quirk: occasional tail jitter/doubled last speech beat — trim the tail. NO reference images (identity swaps needing refs → Kling edit); bit-exact audio needs → Kling keep_audio or segment-splice. 720p output, cheapest edit seat (~2/3 of Kling edit Std).',
     },
+    {
+        id: 'seed-audio',
+        label: 'Seed Audio 1.0',
+        kind: 'audio',
+        maxRefImages: 1, // ONE image XOR up to 3 audio clips — the two inputs are mutually exclusive.
+        maxIngredients: null,
+        notes: 'DEFAULT audio model — the one-pass SCENE workhorse: dialogue, SFX, and ambience together from ONE plain sentence. Route here for continuity beds, room tone, crowd/nature soundscapes, and quick scratch VO. AUDIO-ONLY: cannot generate images or video. 🚨 THERE IS NO DURATION PARAMETER — length comes from the words, so you MUST NAME THE LENGTH IN THE PROMPT TEXT ("... 15 seconds"). Slates appends the requested length automatically and BILLS the requested seconds, so a prompt that fights the number wastes credits. Prompts are ONE plain sentence, no production jargon and no SFX:/Ambient: prefixes (those are Kling syntax and hurt here). Say the crowd size out loud — "applause" returns a full room when the joke was three people. 1-120s. Inputs: ONE image (describe-what-you-see scoring) XOR up to 3 audio clips referenced in the prompt as @Audio1-@Audio3, never both. 20 preset voices, or leave voice unset and let the scene cast itself.',
+    },
+    {
+        id: 'eleven-v3',
+        label: 'ElevenLabs Eleven v3 (TTS)',
+        kind: 'audio',
+        maxRefImages: null,
+        maxIngredients: null,
+        notes: 'CONTROLLED, REPEATABLE named-voice VOICEOVER — route here whenever the exact words matter and must be re-renderable in the same voice (ad reads, narration, character lines to lip-sync against). AUDIO-ONLY. The text field IS the script: it is spoken verbatim, so never put stage directions in it. 1-5000 characters, billed per 100-character bucket, so trimming a sentence genuinely saves credits. 20 preset voices (Rachel default) — pick one and keep it for the whole piece. stability 0-1 trades consistency against expressiveness (low = more emotive and more variable). No voice cloning on this route. Word-level timestamps come back free and are what a future caption pass consumes. For scene ambience or SFX rather than speech, use seed-audio / eleven-sfx.',
+    },
+    {
+        id: 'eleven-sfx',
+        label: 'ElevenLabs Sound Effects v2',
+        kind: 'audio',
+        maxRefImages: null,
+        maxIngredients: null,
+        notes: 'ONE-SHOT SOUND EFFECT with an EXACT duration — route here for a single hit that must land on a frame (door slam, whoosh, impact, UI blip) or for a seamless loop. AUDIO-ONLY. 0.5-22s, and Slates always sends the duration explicitly (a null duration means a non-deterministic charge, so it is never left to the model). Describe the physical CAUSE, not the label: "heavy oak door slams shut in a stone hallway" beats "door sound". Text caps at 450 characters. loop=true produces a seamless bed. prompt_influence 0-1: higher hugs the prompt with less variation, lower explores. For layered scenes with dialogue or room tone, seed-audio does it in one pass instead.',
+    },
+    {
+        id: 'suno',
+        label: 'Suno',
+        kind: 'audio',
+        maxRefImages: null,
+        maxIngredients: null,
+        notes: 'FULL MUSIC TRACKS with structure — route here for anything a listener would call a song or a score. AUDIO-ONLY. EVERY call returns TWO variations for one flat price, and duration is FREE up to 360s (measured 2026-07-31: a 240s track costs the same as a default one), which makes it the cheapest way to get a bed that outlasts a cut. Two modes: DESCRIPTION mode (customMode=false, prompt is a <=500-char description and the lyrics get written for you) and CUSTOM mode (customMode=true, needs style + title; prompt then holds the EXACT LYRICS, sung as written — never put a description there). instrumental=true scores a scene with no vocals. Steer with style/negativeTags rather than piling adjectives into the prompt. duration 10-360s is V5_5 + custom mode only. Unofficial API wrapper, so treat availability as best-effort.',
+    },
 ];
 const FACT_BY_ID = new Map(MODEL_FACTS.map((m) => [m.id, m]));
 export function getModelFact(id) {

package/dist/prompts/partials.generated.js

@@ -6,8 +6,8 @@
 // no longer disagree. Edit the partial, not this file, not the skills.
 export const PARTIALS = {
     "decision-log": "When you surface the plan, include a short **decision log** — one line per decision *you* made that the user did not specify:\n\n```\nsource phrase or declared default → what you wrote → what it resolves\n\"in a diner\"        → chrome-and-vinyl booth, 3/4 on the counter   → fixes the anchor so blocking is repeatable\n(no time of day)    → late afternoon, low warm key                 → default; say the word and it changes\n(no camera)         → slow push-in, single move                    → one move per shot; stacking increases instability\n```\n\n**Hard rule: never silently add weather, props, style, or camera movement.** If it wasn't in the brief and you added it, it goes in the log. This is the \"why did you add that?\" affordance — for an agent that writes prompts on the user's behalf and spends their credits, it is what keeps the model in assembly and the user in the director's chair.\n\n> ❌ **Do NOT turn this into a question gate.** Clarifying questions before optimizing directly fight the locked fast-path rule: *if intent is clear, generate immediately with sane defaults, don't ask questions; only ask for production intent, and batch every question into one message.* Log the decisions, then go. The log is an **output**, not an interrogation — surfaced alongside the plan, never as a separate ceremony, and never as a reason to wait.",
-    "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.\n\n1. **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.\n2. **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.\n3. **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.\n4. **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.\n5. **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.\n6. **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.\n7. **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.\n8. **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.\n9. **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.)\n10. **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.",
-    "reference-tips-short": "Name each reference inline; never write role essays. Slates does this for you: `@mention` a subject or environment and it composes `Marcus (images 1 and 2) in the cafe (image 3)`, citing them in the exact order it sends them. Citing both of a character's sheets under the SAME name is what tells the model they are one person — a \"Reference Image Instructions\" block does the opposite and drags the sheet's studio lighting into your scene. Start with 2-3 focused refs.",
+    "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.\n\n1. **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.\n2. **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.\n3. **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.\n4. **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.\n5. **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.\n6. **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.\n7. **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.\n8. **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.\n9. **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.)\n10. **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.",
+    "reference-tips-short": "Name each reference inline; never write role essays. Slates does this for you: `@mention` a subject or environment and it composes `Marcus (image 1) in the cafe (image 2)`, citing them in the exact order it sends them. One canonical identity image avoids competing facial renderings; a \"Reference Image Instructions\" block drags reference lighting into your scene. Start with 2-3 focused refs.",
     "references-read-literally": "> **The general law: the model reads a reference literally.**\n> 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.\n\nEvery reference rule below is a corollary of that one sentence, which is why \"prep the reference\" beats \"prompt around the reference\" every time:\n\n- **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).\n- **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.\"\n- **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.\n- **Break perfect symmetry** — mirrored faces and dead-square framing read as synthetic, and the model preserves that reading rather than correcting it.\n\n**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.",
     "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.\n\nThis 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.",
 };

package/dist/prompts/prompting-tips.d.ts

@@ -16,7 +16,7 @@ export interface PromptingTipsEntry {
     /** Footer callout paragraphs. */
     footer?: string[];
 }
-export type PromptingTipsKey = 'seedance' | 'kling' | 'kling-edit' | 'veo' | 'omni-flash' | 'omni-flash-edit' | 'nano-banana' | 'nano-banana-lite';
+export type PromptingTipsKey = 'seedance' | 'kling' | 'kling-edit' | 'veo' | 'omni-flash' | 'omni-flash-edit' | 'nano-banana' | 'nano-banana-lite' | 'seed-audio' | 'eleven-v3' | 'eleven-sfx' | 'suno';
 export declare const PROMPTING_TIPS: Record<PromptingTipsKey, PromptingTipsEntry>;
 /** Null when no tips exist for the key — callers render an honest fallback. */
 export declare function getPromptingTips(key: string): PromptingTipsEntry | null;

package/dist/prompts/prompting-tips.js

@@ -212,7 +212,7 @@ const OMNI_FLASH = {
         [
             {
                 heading: 'Name references inline',
-                example: 'Marcus (images 1 and 2) walks into the cafe...',
+                example: 'Marcus (image 1) walks into the cafe...',
                 note: 'Up to 7 reference images merge into one list — refer to them by number in the prompt.',
             },
             {
@@ -325,7 +325,7 @@ const NANO_BANANA = {
             },
             {
                 heading: 'Reference images — name them, never label roles',
-                example: 'Marcus (images 1 and 2) sits across from the woman (image 3) in the cafe (image 4).',
+                example: 'Marcus (image 1) sits across from the woman (image 2) in the cafe (image 3).',
                 note: `Up to 14 refs (10 object + 4 character — caps don't trade). ${PARTIALS['reference-tips-short']}`,
             },
             {
@@ -359,6 +359,196 @@ const NANO_BANANA_LITE = {
             : card),
     ],
 };
+// ── Audio lane ──────────────────────────────────────────────────
+// The four audio surfaces prompt NOTHING like the video models. The single
+// most expensive mistake is bringing Kling's "SFX:" / "Ambient noise:" syntax
+// to Seed Audio, which reads it as literal text. Every entry below leads with
+// what the surface actually wants.
+const SEED_AUDIO = {
+    label: 'Seed Audio 1.0',
+    intro: [
+        'Seed Audio builds a whole audio scene — dialogue, effects and ambience together — from one plain sentence. Write it the way you would describe the moment to a person standing next to you, not the way you would write a video prompt.',
+        'It has no duration setting. Length comes from the words, so Slates appends your chosen duration to the prompt ("… 15 seconds") and bills exactly that. Set the duration control to what you actually want and let the sentence stay clean.',
+    ],
+    columns: [
+        [
+            {
+                heading: 'One plain sentence',
+                example: 'nature soundscape, wide open field cicadas and birds and a loon.',
+                note: 'No shot language, no production jargon, no formatting. Plain description outperforms anything that reads like a spec sheet.',
+            },
+            {
+                heading: 'Duration lives in the prompt',
+                example: 'tiny applause of 2 or 3 people at an open mic. 15 seconds',
+                note: 'The duration control writes this for you. Do not also type a different length into your sentence — the two will fight and you pay for the one you selected.',
+                critical: true,
+            },
+            {
+                heading: 'Say the crowd size',
+                example: 'tiny applause of 2 or 3 people  ·  a packed arena roaring',
+                note: '"Applause" alone returns a full room. Scale words are the single highest-leverage edit on any crowd, traffic or nature bed.',
+            },
+            {
+                heading: 'Cut beds longer than the shot',
+                note: 'Ask for a few seconds more than the clip needs so the edit has handles to fade in and out of. Beds that end exactly on the cut always sound clipped.',
+            },
+        ],
+        [
+            {
+                heading: 'No Kling syntax here',
+                example: '✗ SFX: heavy boots\n✓ heavy boots on wet pavement, a siren far off',
+                note: 'The "SFX:" and "Ambient noise:" prefixes belong to Kling video prompts. Seed Audio treats them as words in the scene and the result gets worse.',
+                critical: true,
+            },
+            {
+                heading: 'Dialogue in quotes',
+                example: 'a tired bartender says, "we closed twenty minutes ago", glasses clinking behind him',
+                note: 'Speech goes in quotes inside the same sentence as the room. Pick a preset voice for a specific speaker, or leave it unset and let the scene cast itself.',
+            },
+            {
+                heading: 'References',
+                example: 'match the room tone of @Audio1',
+                note: 'Up to 3 audio clips (max 30s each), referenced as @Audio1–@Audio3 — OR one image to score what is in frame. Never both in the same generation.',
+            },
+            {
+                heading: 'Know its seat',
+                note: 'Scenes, beds and room tone in one pass. For an exact script in a repeatable voice use Eleven v3; for a single effect on a specific frame use Sound Effects; for a song use Suno.',
+            },
+        ],
+    ],
+};
+const ELEVEN_V3 = {
+    label: 'ElevenLabs Eleven v3',
+    intro: [
+        'Eleven v3 speaks your text verbatim in a named voice. It is the controlled, repeatable lane: the same text and the same voice give you a read you can regenerate after a script tweak without the performance drifting.',
+        'Billing is per 100 characters of text, rounded up — so tightening a sentence genuinely costs less, and a stray pasted paragraph genuinely costs more.',
+    ],
+    columns: [
+        [
+            {
+                heading: 'The text field is the script',
+                example: '✗ (excited) Say this fast: Grab yours today!\n✓ Grab yours today!',
+                note: 'Everything you type gets spoken. Stage directions, character names and bracketed notes will be read out loud.',
+                critical: true,
+            },
+            {
+                heading: 'Punctuate for pace',
+                example: 'It works. Every time.  ·  It works — every time…',
+                note: 'Full stops, commas, dashes and ellipses are your only timing controls. Rewrite the punctuation before you touch the settings.',
+            },
+            {
+                heading: 'Pick a voice and stay',
+                note: '20 preset voices. Choosing one per character or per piece is what makes a series sound deliberate; swapping voices mid-piece reads as a mistake.',
+            },
+        ],
+        [
+            {
+                heading: 'Stability',
+                example: '0.3 emotive · 0.5 default · 0.8 steady',
+                note: 'Lower is more expressive and more variable take-to-take. Higher is flatter and more repeatable. Raise it for long narration, lower it for a single dramatic line.',
+            },
+            {
+                heading: 'Spell out the tricky bits',
+                example: 'SKU → "ess kay you"  ·  2026 → "twenty twenty six"',
+                note: 'Acronyms, product names, prices and years are where TTS embarrasses itself. Write the pronunciation you want.',
+            },
+            {
+                heading: 'Know its seat',
+                note: 'Exact words, repeatable voice, lines you will lip-sync against. Ambience, crowds and rooms belong to Seed Audio; one-shot effects to Sound Effects.',
+            },
+        ],
+    ],
+    footer: [
+        'Word-level timestamps come back with every generation at no extra cost — that is what a future caption pass will read, so there is no reason to turn them off.',
+    ],
+};
+const ELEVEN_SFX = {
+    label: 'ElevenLabs Sound Effects',
+    intro: [
+        'Sound Effects makes one short sound with an exact length — the lane for a hit that has to land on a specific frame, or a seamless loop you can lay under a whole scene.',
+        'Duration is always sent explicitly (0.5–22s). Billing is per second, so the length you pick is the price you pay.',
+    ],
+    columns: [
+        [
+            {
+                heading: 'Describe the cause, not the label',
+                example: '✗ door sound\n✓ heavy oak door slams shut in a stone hallway',
+                note: 'Material, weight and room are what separate a usable effect from a stock-library shrug. Name all three.',
+                critical: true,
+            },
+            {
+                heading: 'One sound per generation',
+                note: 'This surface makes a single event. A door, then footsteps, then a siren is three generations layered on the timeline — or one Seed Audio scene.',
+            },
+            {
+                heading: 'Duration is the edit',
+                example: '0.8s for an impact · 4s for a whoosh · 22s for a bed',
+                note: 'Ask for roughly the length you need. A 4-second request for a door slam pads the tail with room tone you then have to trim.',
+            },
+        ],
+        [
+            {
+                heading: 'Loops',
+                example: 'steady rain on a canvas tent  (loop on, 12s)',
+                note: 'Turn loop on for anything continuous — rain, engine hum, crowd murmur — and it will tile without a seam.',
+            },
+            {
+                heading: 'Prompt influence',
+                example: '0.3 default · 0.7 literal',
+                note: 'Higher hugs your wording with less variation between takes; lower explores. Raise it when a re-roll keeps wandering off the brief.',
+            },
+            {
+                heading: 'Know its seat',
+                note: 'One precise effect on a known frame. Full rooms and layered scenes are cheaper and better in one Seed Audio pass.',
+            },
+        ],
+    ],
+};
+const SUNO = {
+    label: 'Suno',
+    intro: [
+        'Suno writes full music. Every generation returns TWO variations for one flat price, and length is free up to six minutes — so there is never a reason to generate a bed that is shorter than your edit.',
+        'The one thing to get right is which mode you are in, because it changes what the prompt field means.',
+    ],
+    columns: [
+        [
+            {
+                heading: 'Description mode',
+                example: 'brooding synthwave for a night drive, analog bass, no vocals',
+                note: 'The prompt is a description (max 500 characters) and the lyrics get written for you. This is the fast path when you just need a mood.',
+            },
+            {
+                heading: 'Custom mode — the prompt IS the lyrics',
+                example: 'Style: dream pop, hazy\nTitle: Blue Hour\nPrompt: [Verse 1] The lights come on…',
+                note: 'In custom mode the prompt is sung exactly as written. Putting a description there gets your description sung back at you.',
+                critical: true,
+            },
+            {
+                heading: 'Instrumental',
+                note: 'Turn instrumental on to score a scene with no vocals — style and title still steer it, and the prompt field is ignored.',
+            },
+        ],
+        [
+            {
+                heading: 'Steer with style, not adjectives',
+                example: 'Style: 90s trip-hop, dusty breakbeat, Rhodes\nAvoid: brass, EDM drops',
+                note: 'Genre, era, instrumentation and tempo belong in the style field. Negative tags remove what keeps creeping in.',
+            },
+            {
+                heading: 'Length is free',
+                example: '10–360 seconds',
+                note: 'A six-minute track costs exactly what a default one does. Ask for longer than the cut needs and trim on the timeline.',
+            },
+            {
+                heading: 'Two songs, both yours',
+                note: 'Both variations land in the gallery. They are genuinely different takes on the same brief — audition both before re-rolling.',
+            },
+        ],
+    ],
+    footer: [
+        'Files are hosted by the provider for a limited window — Slates downloads and stores them on your machine as soon as the track finishes, so nothing expires out from under a project.',
+    ],
+};
 export const PROMPTING_TIPS = {
     seedance: SEEDANCE,
     kling: KLING,
@@ -368,6 +558,10 @@ export const PROMPTING_TIPS = {
     'omni-flash-edit': OMNI_FLASH_EDIT,
     'nano-banana': NANO_BANANA,
     'nano-banana-lite': NANO_BANANA_LITE,
+    'seed-audio': SEED_AUDIO,
+    'eleven-v3': ELEVEN_V3,
+    'eleven-sfx': ELEVEN_SFX,
+    suno: SUNO,
 };
 /** Null when no tips exist for the key — callers render an honest fallback. */
 export function getPromptingTips(key) {

package/dist/prompts/reference-composer.d.ts

@@ -14,7 +14,7 @@ export interface ReferenceGroup {
     /** Display + citation name: 'Marcus' | 'the cafe' | 'noir'. Used verbatim. */
     name: string;
     kind: ReferenceKind;
-    /** A group can carry several images (e.g. turnaround + expression). */
+    /** A group can carry several images for workflows that genuinely need them. */
     media: ReferenceMedia[];
 }
 export interface ComposedReferences {

package/dist/prompts/reference-composer.js

@@ -14,10 +14,9 @@
 // the desktop generation + rail read from this one function, so the rail's badge
 // numbers and the prompt's "image N" citations can never desync.
 //
-// Naming is the ONLY identity signal. Citing both of a subject's images as the
-// SAME name ("Marcus (images 1 and 2)") tells the model they are ONE entity —
-// which is what prevents a multi-image bucket from averaging into a blended
-// face. This IS each model's own official consistency lever (NB2 "assign a
+// Naming is the identity signal. Citing the canonical subject image inline
+// ("Marcus (image 1)") tells the model which reference owns that entity. This
+// is each model's own official consistency lever (NB2 "assign a
 // distinct name", Seedance "Reference Subject_N in Image_N", Kling "reuse a fixed
 // label verbatim"); the heavy role-essay block was the off-doctrine part.
 // Normalize a name/token for matching: drop the sigil, lowercase, strip