@slatesvideo/shared 0.5.3 → 0.5.4

package/README.md

@@ -3,3 +3,21 @@
 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.

package/dist/operations/index.d.ts

@@ -112,6 +112,7 @@ export declare const generateCharacterSheets: Operation<{
     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;

package/dist/operations/index.js

@@ -580,7 +580,7 @@ export const createEnvironment = {
 };
 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.",
+    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.",
     input: z.object({
         characterId: z.string().uuid(),
         projectId: z.string().uuid(),
@@ -588,8 +588,12 @@ export const generateCharacterSheets = {
         sheetTypes: z
             .array(z.enum(['turnaround', 'expression']))
             .optional()
-            .describe('Which sheets to generate. Default both.'),
+            .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."),
         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', {
@@ -598,6 +602,7 @@ export const generateCharacterSheets = {
             baseAssetIds: [input.baseAssetId],
             sheetTypes: input.sheetTypes,
             userNotes: input.userNotes,
+            model: input.model,
         }));
     },
 };

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

@@ -1,24 +1,36 @@
-/** 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 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.
+ */
+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 BODY_POSE_LABELS: readonly ["front", "back", "profile-left", "profile-right"];
 export declare const EXPRESSION_LABELS: readonly ["neutral", "smile", "serious"];
 /**
- * Body turnaround sheet — the identity reference.
+ * 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.
+ *
  * @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.
+ * 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;
 //# sourceMappingURL=character-sheet.d.ts.map

package/dist/prompts/character-sheet.js

@@ -1,24 +1,70 @@
-// 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 sheet binds to the
+// character's TURNAROUND slot and the expression slot is left null.
+//
+// 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.
+//
+// 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.
+//
+// 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.
+//
+// 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 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.
+ */
+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';
+/** 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 BODY_POSE_LABELS = ['front', 'back', 'profile-left', 'profile-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
@@ -27,27 +73,31 @@ function styleDirective(userStyle) {
     return renderStyleInstruction(userStyle).trim() || INHERIT_SOURCE_STYLE;
 }
 /**
- * Body turnaround sheet — the identity reference.
+ * 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.
+ *
  * @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.`);
+    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. ` +
+        `${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. ` +
+        `No text, no labels, no captions, no panel borders.`);
 }
 /**
- * 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.
+ * 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} Same framing for each. ` +
+        `${styleDirective(userStyle)} ${IDENTITY_LIGHTING_CLAUSE} ${IDENTITY_CRAFT_CLAUSE} Same framing for each. ` +
         `No text, no labels, no captions.`);
 }
 //# 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 — 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.",
+    "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

package/dist/prompts/prompting-tips.js

@@ -9,11 +9,19 @@
 // matching entry here in the same pass. Keys are model FAMILIES — the
 // desktop maps concrete model ids to a family key with its MODEL_REGISTRY
 // helpers (the runtime truth for ids lives in slate/src/shared/pricing.ts).
+//
+// Cards whose content is ALSO doctrine (not just model trivia) compose their
+// copy from skills/_partials/*.md via PARTIALS rather than restating it. The
+// NANO_BANANA reference card is why: it shipped "label every role" — retired
+// doctrine — for thirteen months after the reversal, in the same package as
+// the rule forbidding it. Hand-sync didn't merely drift, it survived a
+// reversal. Add a short partial; don't hand-copy a rule into a card.
+import { PARTIALS } from './partials.generated.js';
 const SEEDANCE = {
     label: 'Seedance 2.0',
     intro: [
-        'Seedance 2.0 wants natural prose with narrative timing beats. Not shot brackets, not bullet points. Audio is always generated alongside video at no extra cost.',
-        "Follow ByteDance's official 6-step formula: Subject, Action, Environment, Camera, Style, Constraints. Sweet spot 60-150 words for single shots, longer for multi-shot.",
+        'Seedance 2.0 is a multimodal director: it reads your text, images, video and audio at once and splits them into a "spatial layer" (what is in frame) and a "temporal layer" (how it changes). So a good prompt is an engineering-style instruction, not a piece of copywriting. Audio is always generated alongside video at no extra cost.',
+        "ByteDance's official advanced formula has 8 slots: precise subject + action details + scene/environment + lighting & color tone + camera movement + visual style + image quality + constraints. Sweet spot 60-150 words for a single shot, longer for multi-shot.",
     ],
     columns: [
         [
@@ -23,37 +31,55 @@ const SEEDANCE = {
                 note: "The first 20-30 words are the identity anchor. If the subject isn't locked in immediately, Seedance will hallucinate new subjects mid-generation.",
             },
             {
-                heading: 'Narrative timing beats',
-                example: 'At 2 seconds, the camera begins a slow dolly forward. At 4 seconds, the lid opens in slow-motion...',
-                note: 'Use "At N seconds" — not SHOT brackets. 2 beats for a 5s clip, 3 for 10s, 4-5 for 15s.',
+                heading: 'Shot 1 / Shot 2 / Shot 3 — never time stamps',
+                example: 'Shot 1: Side shot of the alley; the man slowly starts running.\nShot 2: He knocks over a fruit stand; the camera shakes and cuts to his face.\nShot 3: He climbs a low wall; the camera pulls back onto the empty street.',
+                note: 'ByteDance: write a "Shot 1 / Shot 2 / Shot 3" storyboard in the order events occur, then merge it into one prompt. Do NOT write "At 4 seconds" or "0:00–0:03" and do not set per-shot durations — official docs say precise timing is unstable and forcing it "may lead to abnormal generation results." Let the plot set the pacing.',
+                critical: true,
             },
             {
-                heading: 'Lighting is the #1 quality lever',
+                heading: 'Order inside each shot',
+                example: 'camera move → action + expression → position change → audio',
+                note: "ByteDance's recommended per-shot order. Lead with the camera (\"slowly push in from a wide shot\", \"fixed camera position\", \"cut to...\"), then what the subject does, then where they end up, then the sound.",
+            },
+            {
+                heading: 'Lighting is a top quality lever',
                 example: 'A cool-white diagonal beam from upper left, dust particles drifting through...',
-                note: 'ByteDance says lighting has the biggest impact on quality of any prompt element. Describe it before or alongside the subject.',
+                note: 'Lighting & color tone has its own slot in the official formula. Describe it before or alongside the subject.',
             },
         ],
         [
             {
-                heading: '8 supported camera moves',
-                example: 'push-in · pull-out · pan · tracking · orbit · aerial · handheld · fixed',
-                note: 'Use these exact terms. "Dolly in" not "zoom in." "Orbit" not "circle." One primary camera move per beat — never stack them.',
+                heading: 'Standard camera terms — including shot size',
+                example: 'medium shot · close-up · wide shot · slow push-in · smooth lateral tracking · fixed shot',
+                note: 'ByteDance: the model has a strong understanding of camera terminology, so use it directly — this is an open vocabulary, not a fixed list, and shot size counts as camera direction. Only ONE camera movement per shot: asking for push, pull, pan and move at once increases image instability.',
+            },
+            {
+                heading: 'Slow, gentle, continuous movement',
+                example: 'slowly raise a hand · quickly turn the head · walk slowly · sit down naturally with the motion',
+                note: 'Official rule: name the body part and quantify range, speed and force — and prefer small continuous movement over sprints, big jumps and violent rolls. Slow-motion is supported in natural language; "fast" is a known quality-degrading word.',
             },
             {
-                heading: 'Slow-motion works ("fast" doesn\'t)',
-                example: 'the lid opens in slow-motion · the blade whips through the air',
-                note: 'Speed ramps and slow-motion are supported in natural language. Avoid the word "fast" — it\'s ByteDance\'s #1 quality-degrading keyword.',
+                heading: 'Externalize emotion',
+                example: '❌ she looks very sad\n✅ head lowering, shoulders trembling slightly, eyes reddening, fingers clutching the corner of her clothing',
+                note: 'Replace abstract emotion words with the physical detail that shows them. This is the single highest-leverage habit in ByteDance\'s guide — the model renders bodies, not adjectives.',
             },
             {
                 heading: 'Separate camera from subject motion',
                 example: 'The earbud rises smoothly. The camera tracks upward.',
-                note: 'Two different sentences. Mixing them ("the camera speed ramps as the earbud rises") is the #1 cause of shaky, glitchy output.',
+                note: 'Two different sentences. Mixing them ("the camera speed ramps as the earbud rises") is a common cause of shaky, glitchy output.',
+            },
+            {
+                heading: 'Multi-character shots — forbid twins',
+                example: 'Throughout the video, characters with completely identical appearance, clothing, and accessories are prohibited. Do not generate duplicate avatars or a twin effect.',
+                note: 'With several characters in frame, Seedance can render the same person twice. ByteDance\'s fix: bind each character to its image ("Marcus (image 1)"), append that constraint verbatim at the end, and prefer single-person reference photos. Past 4 reference people, stability drops — compose a group still first.',
             },
         ],
     ],
     footer: [
+        'Quality and constraint slots have their own official vocabulary: ask for "HD, rich details, cinematic texture, natural colors, soft lighting" — not "8K / masterpiece / trending on artstation." Seedance has no negative-prompt field, so constraints go inline: "keep it subtitle-free", "do not generate a logo", "do not generate a watermark".',
         'Style block at the end: one primary anchor plus 2-3 supporting details. End with "Single continuous take" if you want one shot with no cuts. Never write "no cut" or "seamless transition" — those aren\'t in the training vocabulary.',
-        'Multi-modal: up to 9 images + 1 video + audio refs. Reference in prompt with @character, @environment, @audio1. Max length: 4,000 characters.',
+        'Multi-modal: up to 9 images, 3 videos and 3 audio references. Cite them by type and index — "Zhang San@Image 1", or the "Marcus (image 1)" form Slates composes from your @mentions. Never cite an asset ID instead of the image number; the model can\'t associate the two. Max length: 4,000 characters.',
+        'Don\'t cross-pollinate image-model syntax: named lenses, apertures and film stocks ("85mm f/1.4", "Kodak Portra 400") are a Nano Banana lever and a Seedance anti-pattern. Translate them into shot size, depth of field and colour tone instead.',
     ],
 };
 const KLING = {
@@ -269,6 +295,11 @@ const NANO_BANANA = {
                 example: 'Kodak Portra 400 · Fuji Velvia 50 · Ilford HP5 Plus · CineStill 800T',
                 note: 'Portra = natural skin warmth. Velvia = saturated landscape. HP5 = gritty B&W grain. CineStill 800T = tungsten night with halation. Never mix stocks.',
             },
+            {
+                heading: "Don't carry lens + stock into a video prompt",
+                example: '85mm f/1.4, Portra 400\n→ close-up, shallow depth of field, warm natural colors, cinematic texture',
+                note: 'Lenses, apertures, film stocks and camera bodies are an image-model lever and a video-model anti-pattern — ByteDance\'s Seedance guide never mentions f-stops, lens millimetres, fps or shutter angle. When you animate a frame you made here, translate the look into shot size, depth of field and colour tone instead of pasting the gear list across.',
+            },
             {
                 heading: 'Physics-based lighting',
                 example: 'Single key light at 45 degrees from upper left. Color temperature 4500K. Crisp catchlights in the eyes.',
@@ -293,9 +324,9 @@ const NANO_BANANA = {
                 note: 'Reframe positively first. Use inline "without" / "free of" only when positive framing can\'t suppress the unwanted element.',
             },
             {
-                heading: 'Reference images — label every role',
-                example: 'Image 1: Character ref — facial features, body proportions\nImage 2: Environment ref — architecture, lighting\nImage 3: Style ref — mood, aesthetic',
-                note: "Up to 14 refs (10 object + 4 character — caps don't trade). The @ and # mention system labels these automatically. Start with 2-3 focused refs.",
+                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).',
+                note: `Up to 14 refs (10 object + 4 character — caps don't trade). ${PARTIALS['reference-tips-short']}`,
             },
             {
                 heading: 'Common fixes',

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

@@ -1,3 +1,4 @@
+export { PARTIALS } from './partials.generated.js';
 export type SourceGrade = 'Eric-test' | 'community' | 'code-verified' | 'creator-demo';
 export interface ReferenceRule {
     id: string;
@@ -11,24 +12,52 @@ export interface ReferenceRule {
  * are the reusable text the templates compose.
  */
 export declare const REFERENCE_RULES: ReferenceRule[];
-/** Flat, even, shadowless identity lighting on a plain neutral background. */
+/** Flat, even, shadowless identity lighting on a deep neutral-grey plate. */
 export declare const IDENTITY_LIGHTING = "flat, even, shadowless lighting";
-export declare const IDENTITY_BACKGROUND = "a plain neutral-grey background";
-export declare const IDENTITY_LIGHTING_CLAUSE = "Render on a plain neutral-grey background with flat, even, shadowless lighting so the sheet captures the character's identity, not scene lighting.";
+/**
+ * The plate value is deliberate, not decorative: **white bleeds into the
+ * generated video and washes out the location; black eats edge detail and
+ * crushes hair and wardrobe silhouettes.** A deep neutral grey holds both.
+ */
+export declare const IDENTITY_PLATE_HEX = "#3a3a3c";
+export declare const IDENTITY_BACKGROUND = "a plain, deep neutral-grey background (#3a3a3c)";
+export declare const IDENTITY_LIGHTING_CLAUSE = "Render on a plain, deep neutral-grey background (#3a3a3c) with flat, even, shadowless lighting so the sheet captures the character's identity, not scene lighting.";
+/**
+ * Craft clauses every identity reference wants — the eye and skin detail that
+ * survives downstream, plus the two "reads literally" guards. Crushed-black
+ * irises carry no light information, so eye tone drifts between generations;
+ * no catchlight reads as dead eyes; perfect mirroring reads as synthetic and
+ * the model PRESERVES that reading; a game-render look gets ANIMATED like game
+ * footage. See skills/_partials/references-read-literally.md.
+ */
+export declare const IDENTITY_CRAFT_CLAUSE: string;
 /** Inherit the source's artistic medium unless told otherwise. */
 export declare const INHERIT_SOURCE_STYLE = "Preserve the artistic medium and visual style of the reference image (photograph, anime, illustration, 3D render, painterly, etc.).";
 /** Environment plate guidance: one clean, naturally-lit establishing image. */
-export declare const ENVIRONMENT_NATURAL_LIGHT = "natural, even ambient lighting that reads as the location's real light, not a studio setup";
-/** One-line summary used as a header in skills + the lead magnet. */
-export declare const REFERENCE_RULES_HEADLINE = "Identity = a few flat-lit neutral angles; one reference per role, labeled; 2-4 refs not 12; describe environments instead of feeding a grid.";
+export declare const ENVIRONMENT_NATURAL_LIGHT = "natural ambient lighting that reads as the location's real light, not a studio setup";
+/**
+ * One-line summary used as a header in skills + the lead magnet. DERIVED from
+ * the partial's opening line — a hand-authored copy here would be a ninth
+ * wording of the same rule, which is the thing this whole mechanism exists to
+ * stop. Edit `skills/_partials/reference-rules-core.md`.
+ */
+export declare const REFERENCE_RULES_HEADLINE: string;
 /**
- * Canonical markdown block — the SOURCE OF TRUTH the skill markdown and the
- * lead-magnet are reconciled AGAINST. NOTE: nothing imports this yet — the
- * skills hand-author their own reference-rule prose and embed-skills.mjs ships
- * the raw .md as-is, so a change here must be propagated to the per-model skill
- * blocks + lead-magnet by hand until the skill-embed wiring lands (see
- * plans/2026-06-25-slates-prompting-system-overhaul.md). The TARGET is to
- * inject this text so it can't drift; today it's reconciled manually.
+ * Canonical markdown block — the SOURCE OF TRUTH for reference-image doctrine
+ * across every Slates surface.
+ *
+ * ✅ WIRED 2026-07-21. This is no longer hand-reconciled prose. The text lives
+ * in `skills/_partials/reference-rules-core.md`; `scripts/sync-partials.mjs`
+ * injects it between the `@inject:reference-rules-core` markers in the
+ * per-model skills AND emits it here via `partials.generated.ts`. One edit to
+ * the partial now moves the markdown skills, this export, the MCP
+ * prompting-guide op, the CLI-installed skills, and the Studio Agent together.
+ *
+ * The build runs `sync-partials.mjs --check`, so a hand-edit inside a marker
+ * block fails the build with a diff instead of silently forking.
+ *
+ * To change reference doctrine: edit `skills/_partials/reference-rules-core.md`.
+ * Do NOT edit this file, and do NOT edit between markers in a skill.
  */
-export declare const REFERENCE_RULES_TEXT = "## Reference rules (how to use reference images)\n\nIdentity = a few flat-lit neutral angles; one reference per role, labeled; 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.\n2. **One reference per ROLE, labeled in the prompt.** Identity / style-grade / environment. The model does not infer roles from order \u2014 name each role in the prompt text. Same-role competitors drift.\n3. **Attach both sheets \u2014 NAME them as one entity, don't gate them.** Attach the full-body turnaround (body/proportion/outfit) AND the close-up expression sheet (high-res facial detail: eyes, skin, teeth, bone structure). NAME both inline as the same subject (\"Marcus (images 1 and 2)\") \u2014 the shared name tells the model they are ONE person, which is what stops the varied expressions from averaging the face. Do **not** inject a role essay (\"use for identity, ignore the outfit/lighting, render neutral\") \u2014 that drags the studio-lit sheet's wardrobe + lighting into the scene; the user's prompt owns wardrobe, expression, and lighting. Naming-as-one-entity IS each model's official lever (NB2 \"assign a distinct name\"; Seedance \"Reference Subject_N in Image_N\"; Kling \"reuse a fixed label verbatim\"). The trend is MORE references \u2014 addressing each by name is what makes many refs work.\n4. **Flat-light identity refs.** Prep identity refs with flat, even, shadowless lighting on a plain neutral background. Studio-lit / scene-lit sheets bleed their lighting into every generation (the studio-lit sheet \u2192 \"green-screen-pasted in front of mountains\" failure). Reference prep beats prompting here.\n5. **Environment: describe it, don't feed a grid.** Default to describing the location in words. Reserve an environment reference for a mandatory exact-match, and then use ONE clean establishing image with natural, even ambient lighting that reads as the location's real light, not a studio setup \u2014 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 \u2014 cells share a split detail budget and generate jointly, so flaws propagate.\n7. **Reuse the same refs across all shots.** Lock a set and reuse it; swapping refs mid-sequence causes drift.\n8. **Legible in-shot text \u2192 bake it into an image start frame, never trust text-to-video.** Animate from the locked frame.\n9. **I2V / own-footage superpower.** Restyle your own clip keeping the performance; delayed-VFX on \"video one\"; marker-object insertion; video-as-ref for a series. Describe ONLY what changes.\n10. **Style transform by natural language.** Default keeps the source's art style; an optional plain-text instruction transforms it (\"anime \u2192 real person\"). No preset pickers.";
+export declare const REFERENCE_RULES_TEXT: string;
 //# sourceMappingURL=reference-rules.d.ts.map