@slatesvideo/shared 0.5.3 → 0.5.5

package/README.md

@@ -3,3 +3,34 @@
 Internal shared layer for the [Slates](https://slates.video) MCP server and CLI: the auth/connection-file reader, the cloud and desktop HTTP clients, and the single operations array both surfaces register. You almost certainly want [@slatesvideo/mcp-server](https://www.npmjs.com/package/@slatesvideo/mcp-server) (MCP clients like Claude Desktop and Cursor) or [@slatesvideo/cli](https://www.npmjs.com/package/@slatesvideo/cli) (the `slates` command) instead — this package is published only as their dependency.
 
 Source: [github.com/EricDisero/slates-mcp](https://github.com/EricDisero/slates-mcp)
+
+## Prompt partials — how shared prompting prose stays de-forked
+
+Prompting doctrine that applies to more than one model lives **once**, in `skills/_partials/<name>.md`. Every surface that needs it derives:
+
+- **Skill markdown** (`skills/*.md`) carries a marker pair; `scripts/sync-partials.mjs` writes the resolved text between them and commits it, so each de-fork is visible in review and `install-skills` can keep writing the files verbatim to disk.
+
+  ```markdown
+  <!-- @inject:reference-rules-core -->
+  …generated; do not edit between the markers…
+  <!-- @end:reference-rules-core -->
+  ```
+
+- **TypeScript** reads the same text from the generated `PARTIALS` record (`src/prompts/partials.generated.ts`) — that is how `REFERENCE_RULES_TEXT` and the doctrine-bearing cards in `prompting-tips.ts` are built.
+
+`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,12 +102,12 @@ 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';
 }>;
 export declare const generateEnvironmentPlate: Operation<{
     environmentId: string;
@@ -376,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,32 +564,32 @@ 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 turnaround sheet (4 neutral full-body angles — identity: body, proportions, outfit) AND expression sheet (close-up facial detail) from a base portrait asset, on Nano Banana 2 at 2K, and bind both to the character. THE real character-building workflow — call right after slates_create_character. baseAssetId is the source portrait (a project asset). Both sheets generate by default. Afterward, carry the character into a scene by passing its turnaround + expression asset ids as characterAssetIds to slates_generate_video (or referenceAssetIds to slates_generate_image) so identity stays consistent across shots. Cost ~$0.36 for both sheets.",
+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 both.'),
+        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'])
+            .optional()
+            .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,
         }));
     },
 };
 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(),
@@ -1379,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.'),
@@ -2527,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(),
@@ -2551,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', {
@@ -2566,7 +2552,7 @@ export const updateEnvironment = {
                 name: input.name,
                 description: input.description,
                 style: input.style,
-                gridAssetId: input.gridAssetId,
+                referenceAssetId: input.referenceAssetId,
             },
         }));
     },
@@ -2723,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' ||
@@ -2775,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);
@@ -2809,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

@@ -1,24 +1,25 @@
-/** Turnaround = the IDENTITY reference. 4 neutral full-body angles. */
-export declare const CHARACTER_ANGLES_DESC = "front view, back view, left side profile, right side profile";
 /**
- * Expression-sheet close-ups = the FACE identity reference (high-res
- * eyes/skin/teeth/bone). Attached alongside the turnaround; the scene-time
- * reference label drives the rendered expression.
+ * The identity sheet's panels. The portrait is FIRST and DOMINANT — every
+ * detail the downstream model will ever know about the face comes from those
+ * pixels, so it gets the resolution. The body panels exist for build,
+ * proportion, wardrobe and hair, not for the face.
+ *
+ * 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_EXPRESSIONS_DESC = "neutral expression on left, genuine smile showing teeth in center, serious frown on right";
-export declare const BODY_POSE_LABELS: readonly ["front", "back", "profile-left", "profile-right"];
-export declare const EXPRESSION_LABELS: readonly ["neutral", "smile", "serious"];
+export declare const CHARACTER_SHEET_PANELS_DESC: string;
+/** Panel identifiers, in sheet order. */
+export declare const BODY_POSE_LABELS: readonly ["portrait", "front", "back"];
 /**
- * Body turnaround sheet — the identity reference.
+ * 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 — the close-up face reference. Its three portraits carry
- * high-res facial detail (eyes, skin, teeth, bone structure) plus the
- * character's expression range. Attached ALONGSIDE the turnaround; the
- * reference label drives identity-use + scene-driven expression so the multiple
- * expressions don't average the generated face.
- */
-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

@@ -1,25 +1,78 @@
-// Canonical character-sheet prompt content. ONE mode: inherit the source's
-// medium, render on a flat-lit plain background, optional natural-language
-// style transform. (Replaces the old photorealistic / match-reference fork
-// that baked studio lighting or a scene's lighting into the identity ref.)
+// Canonical character-sheet prompt content.
 //
-// This is the SOURCE OF TRUTH that the desktop templates, the MCP skill
-// markdown, and the lead-magnet are RECONCILED against. They do NOT import it
-// yet (the skill-embed + desktop-import wiring is future work per
-// plans/2026-06-25-slates-prompting-system-overhaul.md), so when you change a
-// rule here, update those copies in the same pass until the wiring ships.
-import { IDENTITY_LIGHTING_CLAUSE, INHERIT_SOURCE_STYLE, } from './reference-rules.js';
+// 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 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 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.
+//
+// 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".
+//
+// 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)
+// — there is no desktop prompt mirror to update. Map:
+// second-brain business/projects/slates/product/prompting-ssot.md
+import { IDENTITY_CRAFT_CLAUSE, IDENTITY_LIGHTING_CLAUSE, INHERIT_SOURCE_STYLE, } from './reference-rules.js';
 import { renderStyleInstruction } from './style-library.js';
-/** Turnaround = the IDENTITY reference. 4 neutral full-body angles. */
-export const CHARACTER_ANGLES_DESC = 'front view, back view, left side profile, right side profile';
 /**
- * Expression-sheet close-ups = the FACE identity reference (high-res
- * eyes/skin/teeth/bone). Attached alongside the turnaround; the scene-time
- * reference label drives the rendered expression.
+ * The identity sheet's panels. The portrait is FIRST and DOMINANT — every
+ * detail the downstream model will ever know about the face comes from those
+ * pixels, so it gets the resolution. The body panels exist for build,
+ * proportion, wardrobe and hair, not for the face.
+ *
+ * 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_EXPRESSIONS_DESC = 'neutral expression on left, genuine smile showing teeth in center, serious frown on right';
-export const BODY_POSE_LABELS = ['front', 'back', 'profile-left', 'profile-right'];
-export const EXPRESSION_LABELS = ['neutral', 'smile', 'serious'];
+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, 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'];
 // 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.
@@ -27,27 +80,20 @@ function styleDirective(userStyle) {
     return renderStyleInstruction(userStyle).trim() || INHERIT_SOURCE_STYLE;
 }
 /**
- * Body turnaround sheet — the identity reference.
+ * 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) {
-    return (`Character model reference sheet with 4 full body views of the same character: ${CHARACTER_ANGLES_DESC}. ` +
-        `Neutral pose, neutral expression, consistent character appearance across all views. ` +
-        `${styleDirective(userStyle)} ${IDENTITY_LIGHTING_CLAUSE} ` +
-        `For upright/bipedal characters arrange side-by-side; for quadruped/animal characters use a 2x2 grid. ` +
-        `No text, no labels, no captions.`);
-}
-/**
- * Expression sheet — the close-up face reference. Its three portraits carry
- * high-res facial detail (eyes, skin, teeth, bone structure) plus the
- * character's expression range. Attached ALONGSIDE the turnaround; the
- * reference label drives identity-use + scene-driven expression so the multiple
- * expressions don't average the generated face.
- */
-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} Same framing for each. ` +
-        `No text, no labels, no captions.`);
+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, 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.`);
 }
+/** @deprecated Use buildCharacterIdentityPrompt. */
+export const buildCharacterTurnaroundPrompt = buildCharacterIdentityPrompt;
 //# sourceMappingURL=character-sheet.js.map

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

@@ -5,5 +5,13 @@
  */
 export declare function buildEnvironmentEstablishingPrompt(userStyle?: string | null): string;
 /** Guidance shown to users/agents: prefer describing the environment in text. */
-export declare const ENVIRONMENT_DESCRIBE_FIRST = "Default to describing the environment in words and let the model build it to fit the shot. Generate an establishing plate only when a location must be locked exactly across shots.";
+export declare const ENVIRONMENT_DESCRIBE_FIRST: string;
+/**
+ * The continuity test for a location that must hold across shots: generate a
+ * SECOND frame from the reverse angle and approve the plate only if the anchor
+ * object, the openings, the light side, the materials and the palette all still
+ * match. A plate that fails this will drift the moment the camera turns — and a
+ * broken plate gives every later character failure a second plausible cause.
+ */
+export declare const ENVIRONMENT_REVERSE_ANGLE_TEST = "Reverse-angle check: generate one frame from the opposite side of the space and confirm the anchor object, openings, light direction, materials and colour palette all still match. If they do not, the plate is not locked \u2014 fix the plate before staging anything in it.";
 //# sourceMappingURL=environment-sheet.d.ts.map

package/dist/prompts/environment-sheet.js

@@ -16,12 +16,26 @@ function styleDirective(userStyle) {
  * @param userStyle optional natural-language style transform
  */
 export function buildEnvironmentEstablishingPrompt(userStyle) {
-    return (`A single clean establishing shot of this empty location: a wide, eye-level view that captures the space — its architecture or geography, materials, and depth. ` +
+    return (`A single clean establishing shot of this empty location, framed at a three-quarter angle — never a dead-on frontal view — so two walls or planes are visible and the floor reads as usable staging space. ` +
+        `Capture the space: its architecture or geography, materials, and depth. ` +
+        `Include a clearly readable ANCHOR OBJECT with a definite position in the room — a sofa, a doorway, a counter, a signpost — so later shots can be blocked against it. ` +
         `The location is empty and unpopulated, ready for scene staging. ` +
-        `${styleDirective(userStyle)} Use ${ENVIRONMENT_NATURAL_LIGHT}. ` +
+        `${styleDirective(userStyle)} Use ${ENVIRONMENT_NATURAL_LIGHT}, motivated by ONE dominant source with shadows falling consistently away from it — soft and diffused for interiors, no hard visible light rays. ` +
+        `Add gentle atmospheric haze with distance so near and far planes separate in depth rather than reading at the same sharpness. ` +
         `If the reference image contains people or characters, generate the location as an empty space — ignore the figures. ` +
         `No text, no labels, no captions.`);
 }
 /** Guidance shown to users/agents: prefer describing the environment in text. */
-export const ENVIRONMENT_DESCRIBE_FIRST = 'Default to describing the environment in words and let the model build it to fit the shot. Generate an establishing plate only when a location must be locked exactly across shots.';
+export const ENVIRONMENT_DESCRIBE_FIRST = 'Default to describing the environment in words and let the model build it to fit the shot. Generate an establishing plate only when a location must be locked exactly across shots. ' +
+    'When you do: frame it three-quarter, never dead-on (a frontal facade turns the location into a backdrop characters stand in FRONT of; a three-quarter exposes side geometry and usable floor), ' +
+    'name an anchor object so blocking can be stated as "between the sofa\'s hall-side arm and the window" instead of "on the left" — one is testable after a camera turn, the other drifts, ' +
+    'give it one motivated light source with shadows falling away from it, and ask for atmospheric haze so depth separates.';
+/**
+ * The continuity test for a location that must hold across shots: generate a
+ * SECOND frame from the reverse angle and approve the plate only if the anchor
+ * object, the openings, the light side, the materials and the palette all still
+ * match. A plate that fails this will drift the moment the camera turns — and a
+ * broken plate gives every later character failure a second plausible cause.
+ */
+export const ENVIRONMENT_REVERSE_ANGLE_TEST = 'Reverse-angle check: generate one frame from the opposite side of the space and confirm the anchor object, openings, light direction, materials and colour palette all still match. If they do not, the plate is not locked — fix the plate before staging anything in it.';
 //# sourceMappingURL=environment-sheet.js.map

package/dist/prompts/model-facts.js

@@ -6,7 +6,10 @@
 export const MODEL_FACTS = [
     {
         id: 'nano-banana-2',
-        label: 'Nano Banana 2 (Gemini 3 Image)',
+        // Gemini 3.1 FLASH Image — verified against the runtime slug map in
+        // slate/src/main/api/google.ts. Nano Banana PRO is a different model
+        // (gemini-3-pro-image-preview); do not conflate them.
+        label: 'Nano Banana 2 (Gemini 3.1 Flash Image)',
         kind: 'image',
         maxRefImages: 14, // 10 object-fidelity + 4 character-consistency; categories don't trade.
         maxIngredients: null,

package/dist/prompts/partials.generated.d.ts

@@ -0,0 +1,2 @@
+export declare const PARTIALS: Record<string, string>;
+//# sourceMappingURL=partials.generated.d.ts.map

package/dist/prompts/partials.generated.js

@@ -0,0 +1,14 @@
+// GENERATED — do not edit. Source: packages/shared/skills/_partials/*.md
+// Regenerated by scripts/sync-partials.mjs on every build.
+//
+// This is the SAME text injected between the @inject markers in the
+// per-model skills, so the TS consumers and the markdown consumers can
+// 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, 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.",
+};
+//# sourceMappingURL=partials.generated.js.map