@slatesvideo/shared 0.5.4 → 0.5.5

package/README.md

@@ -21,3 +21,16 @@ Prompting doctrine that applies to more than one model lives **once**, in `skill
 `npm run build` runs `sync-partials.mjs --check`, which fails with a diff if anything inside a marker block was hand-edited, if a skill references a partial that doesn't exist, if markers are unbalanced, or if a partial is referenced by nothing. Run `npm run sync-partials` to apply changes after editing a partial.
 
 **To change shared prompting doctrine: edit the partial.** Never edit between markers, never edit `partials.generated.ts`, and never hand-copy a shared rule into a new skill — a copy is a fork with a delay fuse. Per-model levers (a vendor's own official consistency mechanism, its caps and transport quirks) stay hand-authored, below the injected block, under a `### For <model> specifically` heading.
+
+## Portable Prompt Builder export
+
+The downloadable Claude `.skill` is generated at `exports/slates-prompt-builder/generated/`. Its model, character, and content-policy references come directly from the resolved production files in `skills/`; its routing table derives from `MODEL_FACTS`; the portable wrapper owns only export-specific scope and output behavior.
+
+```bash
+npm run sync-prompt-builder   # regenerate markdown, manifest, and deterministic .skill
+npm run typecheck             # fails if the committed export is stale
+```
+
+`scripts/build-prompt-builder.mjs --check` validates generated text content (normalizing LF/CRLF), keeps the archive byte-exact, opens it to verify its exact entry set, and enforces the runtime character contract (one sheet, the canonical `IDENTITY_PLATE_HEX`, flat/shadowless light, and the three-panel builder). Never edit `exports/slates-prompt-builder/generated/` directly.
+
+The repository verification workflow runs both typecheck and build on every pull request and push to `main`, so stale exports cannot merge through the normal GitHub path.

package/dist/operations/index.d.ts

@@ -89,11 +89,7 @@ export declare const createCharacter: Operation<{
     description?: string;
     style?: string;
 }>;
-export declare const setCharacterTurnaround: Operation<{
-    characterId: string;
-    assetId: string | null;
-}>;
-export declare const setCharacterExpression: Operation<{
+export declare const setCharacterIdentity: Operation<{
     characterId: string;
     assetId: string | null;
 }>;
@@ -106,11 +102,10 @@ export declare const createEnvironment: Operation<{
     description?: string;
     style?: string;
 }>;
-export declare const generateCharacterSheets: Operation<{
+export declare const generateCharacterIdentity: Operation<{
     characterId: string;
     projectId: string;
     baseAssetId: string;
-    sheetTypes?: ('turnaround' | 'expression')[];
     userNotes?: string;
     model?: 'nano-banana-2' | 'nano-banana-2-lite' | 'nano-banana-pro' | 'gpt-image-2';
 }>;
@@ -377,7 +372,7 @@ export declare const updateEnvironment: Operation<{
     name?: string;
     description?: string;
     style?: string;
-    gridAssetId?: string | null;
+    referenceAssetId?: string | null;
 }>;
 export declare const deleteEnvironment: Operation<{
     environmentId: string;

package/dist/operations/index.js

@@ -528,9 +528,9 @@ export const createCharacter = {
         return ok(await ctx.desktop().post('/agent/characters', input));
     },
 };
-export const setCharacterTurnaround = {
-    id: 'slates_set_character_turnaround_asset',
-    description: 'Bind an image asset to the character\'s turnaround slot (or clear with assetId=null). The user sees the character card update live.',
+export const setCharacterIdentity = {
+    id: 'slates_set_character_identity_asset',
+    description: 'Bind one image asset as the character identity (or clear with assetId=null). The user sees the character card update live.',
     input: z.object({
         characterId: z.string().uuid(),
         assetId: z.string().uuid().nullable(),
@@ -538,21 +538,7 @@ export const setCharacterTurnaround = {
     async run(input, ctx) {
         return ok(await ctx.desktop().post('/agent/characters/update', {
             id: input.characterId,
-            data: { turnaroundAssetId: input.assetId },
-        }));
-    },
-};
-export const setCharacterExpression = {
-    id: 'slates_set_character_expression_asset',
-    description: 'Bind an image asset to the character\'s expression-sheet slot (or clear with assetId=null).',
-    input: z.object({
-        characterId: z.string().uuid(),
-        assetId: z.string().uuid().nullable(),
-    }),
-    async run(input, ctx) {
-        return ok(await ctx.desktop().post('/agent/characters/update', {
-            id: input.characterId,
-            data: { expressionAssetId: input.assetId },
+            data: { identityAssetId: input.assetId, expressionAssetId: null },
         }));
     },
 };
@@ -578,17 +564,13 @@ export const createEnvironment = {
         return ok(await ctx.desktop().post('/agent/environments', input));
     },
 };
-export const generateCharacterSheets = {
-    id: 'slates_generate_character_sheets',
-    description: "Generate a character's identity reference sheet from a base portrait asset and bind it to the character. THE real character-building workflow — call right after slates_create_character. ONE sheet per character by default: a dominant three-quarter chest-up portrait (the sole face authority) plus full-body front and back panels on a deep neutral-grey plate — it binds to the turnaround slot and the expression slot stays null. That is deliberate: every bound sheet costs a reference slot on EVERY downstream shot, so one sheet per character doubles the cast you can stage against real caps (Kling 3.0 takes 4 ingredients, NB2 4 character slots, Seedance 9). Pass sheetTypes:['expression'] only when a character genuinely needs a separate expression range. baseAssetId is the source portrait (a project asset). Afterward, carry the character into a scene by passing its bound sheet asset id as characterAssetIds to slates_generate_video (or referenceAssetIds to slates_generate_image). Read slates-character-turnaround before calling. Default nano-banana-2 @ 2K — quote the price from slates_estimate_generation_cost, never from memory.",
+export const generateCharacterIdentity = {
+    id: 'slates_generate_character_identity',
+    description: "Generate one character identity sheet from a base portrait asset and bind it as the character's canonical reference. Call after slates_create_character. Read slates-character-identity before calling and quote the cost from slates_estimate_generation_cost.",
     input: z.object({
         characterId: z.string().uuid(),
         projectId: z.string().uuid(),
-        baseAssetId: z.string().uuid().describe('The base portrait asset the sheets are generated from.'),
-        sheetTypes: z
-            .array(z.enum(['turnaround', 'expression']))
-            .optional()
-            .describe("Which sheets to generate. Default ['turnaround'] — the single identity sheet. Add 'expression' only when the character needs a dedicated expression range; it costs a second reference slot on every downstream generation."),
+        baseAssetId: z.string().uuid().describe('The base portrait asset the identity is generated from.'),
         userNotes: z.string().optional().describe('Extra instruction, e.g. "use the woman on the left".'),
         model: z
             .enum(['nano-banana-2', 'nano-banana-2-lite', 'nano-banana-pro', 'gpt-image-2'])
@@ -596,11 +578,10 @@ export const generateCharacterSheets = {
             .describe('Image model for the sheet. Omit for the default (nano-banana-2). Exists so the layout-vs-face tradeoff can be tested with comparison gens — do not switch without a receipt.'),
     }),
     async run(input, ctx) {
-        return ok(await ctx.desktop().post('/agent/characters/generate-sheets', {
+        return ok(await ctx.desktop().post('/agent/characters/generate-identity', {
             characterId: input.characterId,
             projectId: input.projectId,
             baseAssetIds: [input.baseAssetId],
-            sheetTypes: input.sheetTypes,
             userNotes: input.userNotes,
             model: input.model,
         }));
@@ -608,7 +589,7 @@ export const generateCharacterSheets = {
 };
 export const generateEnvironmentPlate = {
     id: 'slates_generate_environment_plate',
-    description: "Generate an environment's single clean establishing plate (Nano Banana 2, 2K) from an optional base image, and bind it as the environment's reference. THE real environment-building workflow — call right after slates_create_environment. Afterward, pass the plate asset id as environmentAssetIds to slates_generate_video (or referenceAssetIds to slates_generate_image) so the location stays consistent across shots. Cost ~6 credits.",
+    description: "Generate one clean establishing image from an optional base image and bind it as the environment's canonical reference. Call after slates_create_environment and quote the cost from slates_estimate_generation_cost.",
     input: z.object({
         environmentId: z.string().uuid(),
         projectId: z.string().uuid(),
@@ -1384,7 +1365,7 @@ export const generateVideo = {
         lastFrameAssetId: z.string().optional().describe('Ending frame (UUID or badge code). Veo and Seedance only. Pairs with firstFrameAssetId for guided transitions.'),
         ingredientAssetIds: z.array(z.string()).max(9).optional().describe('Visual reference / ingredient assets (UUIDs or badge codes) for Kling Omni, Seedance, or Omni Flash. Up to 9 (Seedance), 4 (Kling), or 7 (Omni Flash, combined across all ref params).'),
         characterAssetIds: z.array(z.string()).optional().describe('Character sheet assets (UUIDs or badge codes) — keeps a character consistent across the shot.'),
-        environmentAssetIds: z.array(z.string()).optional().describe('Environment grid assets (UUIDs or badge codes) — keeps a location/setting consistent across the shot.'),
+        environmentAssetIds: z.array(z.string()).optional().describe('Environment reference assets (UUIDs or badge codes) — keeps a location/setting consistent across the shot.'),
         styleAssetIds: z.array(z.string()).optional().describe('Style reference assets (UUIDs or badge codes) — locks the visual style of the shot.'),
         videoReferenceAssetId: z.string().optional().describe('Seedance ONLY: an existing VIDEO asset (UUID or badge code) to use as a reference — edit/relocate a clip, or MOTION TRANSFER (pair with a subject in ingredientAssetIds and a prompt like "the character from image 1 performs the motion from video 1"). 2-15s. Billing switches to input+output seconds (the vref key) — pass videoReferenceSeconds so the quote is right. If the clip contains a human/AI character, pair with seedanceFace=true (the default Seedance route blocks people). Ignored by Kling/Veo.'),
         videoReferenceSeconds: z.number().optional().describe('REQUIRED with videoReferenceAssetId: the reference clip\'s duration in seconds (from the asset listing). Feeds the vref cost key — a video-reference gen bills combined input+output seconds; the server re-derives this by probing the clip, so an understated value just gets corrected upward.'),
@@ -2532,7 +2513,7 @@ export const setFolderCover = {
 };
 export const updateCharacter = {
     id: 'slates_update_character',
-    description: 'Update a character\'s name, description, or style. (Turnaround / expression image slots have their own dedicated set_character_* ops.)',
+    description: 'Update a character\'s name, description, or style. Use slates_set_character_identity_asset for its canonical image.',
     input: z.object({
         characterId: z.string().uuid(),
         name: z.string().min(1).max(120).optional(),
@@ -2556,13 +2537,13 @@ export const deleteCharacter = {
 };
 export const updateEnvironment = {
     id: 'slates_update_environment',
-    description: 'Update an environment\'s name, description, style, or bound grid asset (gridAssetId=null clears it).',
+    description: 'Update an environment\'s name, description, style, or bound reference image (referenceAssetId=null clears it).',
     input: z.object({
         environmentId: z.string().uuid(),
         name: z.string().min(1).max(120).optional(),
         description: z.string().optional(),
         style: z.string().max(200).optional().describe("Art style. Omit to inherit the reference's style (the default). Canonical styles: photoreal, anime, painterly, 3d-render, comic. Or pass any free-text instruction, e.g. 'turn this into a real person'."),
-        gridAssetId: z.string().uuid().nullable().optional(),
+        referenceAssetId: z.string().uuid().nullable().optional(),
     }),
     async run(input, ctx) {
         return ok(await ctx.desktop().post('/agent/environments/update', {
@@ -2571,7 +2552,7 @@ export const updateEnvironment = {
                 name: input.name,
                 description: input.description,
                 style: input.style,
-                gridAssetId: input.gridAssetId,
+                referenceAssetId: input.referenceAssetId,
             },
         }));
     },
@@ -2728,6 +2709,9 @@ function resolveGuideTopic(topic) {
     const t = topic.trim().toLowerCase();
     if (SKILLS[t])
         return t;
+    if (t === 'slates-character-turnaround' || t === 'character-turnaround') {
+        return 'slates-character-identity';
+    }
     if (t === 'model-selection' ||
         t === 'model selection' ||
         t === 'which-model' ||
@@ -2780,7 +2764,7 @@ export const getPromptingGuide = {
         topic: z
             .string()
             .min(1)
-            .describe('Guide name, model id, or style name. Guides: slates-model-selection (which model for which job — read before choosing any model), slates-cost-discipline, slates-content-policy, slates-style-prompting, slates-prompting-nano-banana-2, slates-prompting-veo-3, slates-prompting-kling-v3, slates-prompting-seedance, slates-prompting-lip-sync, slates-prompting-motion-transfer, slates-prompting-flux-2-max, slates-prompting-seedream-5-lite, slates-edit-and-iterate, slates-vision-feedback-loop, slates-character-turnaround, slates-storyboard-from-script, slates-direct-response-ad, slates-one-prompt-film. Style names (photoreal, anime, painterly, 3d-render) resolve to slates-style-prompting.'),
+            .describe('Guide name, model id, or style name. Guides: slates-model-selection (which model for which job — read before choosing any model), slates-cost-discipline, slates-content-policy, slates-style-prompting, slates-prompting-nano-banana-2, slates-prompting-veo-3, slates-prompting-kling-v3, slates-prompting-seedance, slates-prompting-lip-sync, slates-prompting-motion-transfer, slates-prompting-flux-2-max, slates-prompting-seedream-5-lite, slates-edit-and-iterate, slates-vision-feedback-loop, slates-character-identity, slates-storyboard-from-script, slates-direct-response-ad, slates-one-prompt-film. Style names (photoreal, anime, painterly, 3d-render) resolve to slates-style-prompting.'),
     }),
     async run(input) {
         const resolved = resolveGuideTopic(input.topic);
@@ -2814,11 +2798,10 @@ export const ALL_OPERATIONS = [
     moveAssetsToFolder,
     listCharacters,
     createCharacter,
-    setCharacterTurnaround,
-    setCharacterExpression,
+    setCharacterIdentity,
     listEnvironments,
     createEnvironment,
-    generateCharacterSheets,
+    generateCharacterIdentity,
     generateEnvironmentPlate,
     listStoryboards,
     createStoryboard,

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

@@ -4,33 +4,22 @@
  * 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, not removal.
  */
 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,51 @@
 //
 // 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.
 //
-// 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.
+// THE FRONT PANEL IS HEADLESS (shipped 2026-07-22, receipt-gated). The face is
+// cropped off the front body panel — the "ghost mannequin" treatment — taking
+// competing face renderings 2 → 1. 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".
 //
-// 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.
+// 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, head not shown, invisible-mannequin
+//      presentation"), a standard e-commerce genre with deep training data.
+//      Never phrase it as removal or decapitation.
+//   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 +60,19 @@ 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, not removal.
  */
 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, framed from the collarbone down with the head not shown — ' +
+    'an invisible-mannequin presentation where the clothing holds its own shape, ' +
+    '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 +80,20 @@ 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. ` +
+        `No second rendering of the face anywhere on the sheet. ` +
         `Neutral expression 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 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/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.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']}`,
             },
             {

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

package/dist/prompts/reference-rules.js

@@ -30,9 +30,9 @@ export const REFERENCE_RULES = [
     },
     {
         id: 'identity-name-as-one-entity',
-        title: 'One identity sheet per character — NAME whatever you attach as one entity',
-        rule: 'Attach the character\'s single identity sheet (dominant portrait + body panels) rather than a pile of views — fewer competing renderings of a face is always better, because the model cannot tell which is authoritative and averages them. When a character DOES carry a second bound sheet (an explicit expression range, or a legacy turnaround+expression pair), NAME both inline as the SAME subject ("Marcus (images 1 and 2)") — that shared name is what tells the model they are ONE person. Do NOT inject a role essay ("use for identity, ignore the outfit/lighting, render neutral"): the user\'s prompt owns wardrobe, expression, and lighting.',
-        why: 'Naming both images as one entity IS each model\'s OWN official consistency lever — NB2 "assign a distinct name to each character/object"; Seedance "Reference <Subject_N> in <Image_N>"; Kling "reuse a fixed label verbatim". The old heavy role-essay was the OFF-doctrine part: telling the model to "use for identity" while injecting "ignore the outfit" dragged the studio-lit sheet\'s wardrobe + lighting into scenes that explicitly wanted otherwise (the movie-still injection failure). The close-ups still carry far more facial signal (eyes, skin, teeth, bone structure) than a turnaround\'s postage-stamp faces, so attach both — the NAME, not an instruction, is what makes many refs work. The trend is MORE references (video/audio/3D into Seedance-class models), all addressed by name.',
+        title: 'One identity sheet per character, named inline',
+        rule: 'Attach the character\'s single identity sheet (dominant portrait + body panels) rather than a pile of views — fewer competing renderings of a face is better, because the model cannot tell which is authoritative and averages them. Cite it inline as the subject ("Marcus (image 1)"). Do not inject a role essay ("use for identity, ignore the outfit/lighting, render neutral"): the user\'s prompt owns wardrobe, expression, and lighting.',
+        why: 'Distinct inline naming is each model\'s own consistency lever — NB2 "assign a distinct name to each character/object"; Seedance "Reference <Subject_N> in <Image_N>"; Kling "reuse a fixed label verbatim". One canonical identity image removes same-role competition before it starts.',
         grade: 'Eric-test',
     },
     {