@slatesvideo/shared 0.4.1 → 0.4.3

package/dist/operations/index.d.ts

@@ -93,6 +93,19 @@ export declare const createEnvironment: Operation<{
     description?: string;
     style?: string;
 }>;
+export declare const generateCharacterSheets: Operation<{
+    characterId: string;
+    projectId: string;
+    baseAssetId: string;
+    sheetTypes?: ('turnaround' | 'expression')[];
+    userNotes?: string;
+}>;
+export declare const generateEnvironmentPlate: Operation<{
+    environmentId: string;
+    projectId: string;
+    baseAssetId?: string;
+    userNotes?: string;
+}>;
 export declare const listStoryboards: Operation<{
     projectId: string;
 }>;
@@ -141,7 +154,7 @@ export declare const editImage: Operation<{
     confirm?: boolean;
     background?: boolean;
 }>;
-declare const VIDEO_MODELS: readonly ["kling-v3.0-std", "kling-v3.0-pro", "kling-v3.0-omni", "veo-3.1-fast", "veo-3.1-standard", "seedance-2-fast", "seedance-2-std"];
+declare const VIDEO_MODELS: readonly ["kling-v3.0-std", "kling-v3.0-pro", "kling-v3.0-omni", "veo-3.1-fast", "veo-3.1-standard", "seedance-2"];
 type VideoModel = (typeof VIDEO_MODELS)[number];
 export declare const generateVideo: Operation<{
     prompt: string;
@@ -149,14 +162,18 @@ export declare const generateVideo: Operation<{
     projectId?: string;
     aspectRatio?: '1:1' | '16:9' | '9:16' | '4:3' | '3:4' | '21:9' | '9:21' | '4:5' | '5:4' | '2:3' | '3:2';
     duration?: number;
-    videoResolution?: '720p' | '1080p' | '4k';
-    seedanceSpeed?: 'economy' | 'priority';
+    videoResolution?: '480p' | '720p' | '1080p' | '4k';
     firstFrameAssetId?: string;
     lastFrameAssetId?: string;
     ingredientAssetIds?: string[];
+    characterAssetIds?: string[];
+    environmentAssetIds?: string[];
+    styleAssetIds?: string[];
+    videoReferenceAssetId?: string;
     sound?: boolean;
     audioLanguage?: 'EN' | 'ZH' | 'JA' | 'KO' | 'ES';
     generateMusic?: boolean;
+    seedanceFace?: boolean;
     negativePrompt?: string;
     background?: boolean;
     confirm?: boolean;
@@ -172,6 +189,7 @@ export declare const generateLipSync: Operation<{
     ttsSpeed?: number;
     audioFilePath?: string;
     avatarModel?: 'avatar-standard' | 'avatar-pro';
+    klingProvider?: 'fal' | 'kling';
     background?: boolean;
     confirm?: boolean;
 }>;
@@ -182,6 +200,7 @@ export declare const generateMotionTransfer: Operation<{
     motionModel?: 'kling-mc-std' | 'kling-mc-pro';
     characterOrientation?: 'video' | 'image';
     prompt?: string;
+    klingProvider?: 'fal' | 'kling';
     background?: boolean;
     confirm?: boolean;
 }>;

package/dist/operations/index.js

@@ -372,6 +372,51 @@ 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.",
+    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.'),
+        userNotes: z.string().optional().describe('Extra instruction, e.g. "use the woman on the left".'),
+    }),
+    async run(input, ctx) {
+        return ok(await ctx.desktop().post('/agent/characters/generate-sheets', {
+            characterId: input.characterId,
+            projectId: input.projectId,
+            baseAssetIds: [input.baseAssetId],
+            sheetTypes: input.sheetTypes,
+            userNotes: input.userNotes,
+        }));
+    },
+};
+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 ~$0.18.",
+    input: z.object({
+        environmentId: z.string().uuid(),
+        projectId: z.string().uuid(),
+        baseAssetId: z
+            .string()
+            .uuid()
+            .optional()
+            .describe('Optional base image to establish from (e.g. a rough location shot).'),
+        userNotes: z.string().optional(),
+    }),
+    async run(input, ctx) {
+        return ok(await ctx.desktop().post('/agent/environments/generate-plate', {
+            environmentId: input.environmentId,
+            projectId: input.projectId,
+            baseAssetIds: input.baseAssetId ? [input.baseAssetId] : [],
+            userNotes: input.userNotes,
+        }));
+    },
+};
 // ── Storyboards ─────────────────────────────────────────────────
 export const listStoryboards = {
     id: 'slates_list_storyboards',
@@ -915,19 +960,16 @@ const VIDEO_MODELS = [
     'kling-v3.0-omni',
     'veo-3.1-fast',
     'veo-3.1-standard',
-    'seedance-2-fast',
-    'seedance-2-std',
+    'seedance-2',
 ];
 // Model → registry cost-key. Each provider's keys ship with their own
 // shape (verified against /api/agent/models):
 //   Kling: kling-v3-{standard|pro|omni}-{N}s — note the user-facing
 //     model id `kling-v3.0-std` maps to registry key `kling-v3-standard`.
 //   Veo:   veo-3.1-{fast|standard}[-4k]-{N}s[-audio]
-//   Seedance: seedance-2-{fast|std}[-priority]-{N}s. Economy (PiAPI) and
-//     Priority (fal.ai) are DIFFERENT registry keys at DIFFERENT prices —
-//     priority is ~2.2x economy. The cost key MUST encode the tier or the
-//     pre-flight quote understates a priority gen (the desktop charges the
-//     priority key regardless of what we quoted).
+//   Seedance: seedance-2-{res}-{N}s (BytePlus ModelArk, sole provider). The
+//     cost key encodes resolution (480p/720p/1080p/4k) — price scales with
+//     resolution, so the key MUST carry it or the pre-flight quote is wrong.
 const KLING_TIER_MAP = {
     'kling-v3.0-std': 'kling-v3-standard',
     'kling-v3.0-pro': 'kling-v3-pro',
@@ -935,10 +977,12 @@ const KLING_TIER_MAP = {
 };
 function videoCostKey(input) {
     if (input.model.startsWith('seedance')) {
-        // Mirrors seedanceCreditKey() in slate/src/shared/pricing.ts.
-        return input.seedanceSpeed === 'priority'
-            ? `${input.model}-priority-${input.duration}s`
-            : `${input.model}-${input.duration}s`;
+        // Mirrors seedanceCreditKey() in slate/src/shared/pricing.ts (face × res × duration).
+        // Face route (AI-character face ref) bills the EvoLink relaxed rate (+10%) via
+        // the `-face-` key; faceless uses the cheaper BytePlus key.
+        const res = input.videoResolution ?? '1080p';
+        const face = input.seedanceFace ? '-face' : '';
+        return `${input.model}${face}-${res}-${input.duration}s`;
     }
     if (input.model.startsWith('veo')) {
         const is4k = input.videoResolution === '4k';
@@ -972,21 +1016,25 @@ function promptingSkillFor(model) {
 }
 export const generateVideo = {
     id: 'slates_generate_video',
-    description: 'Generate video via Slates credits. REQUIRED before calling: read the slates-cost-discipline skill plus the per-model prompting skill (slates-prompting-seedance / slates-prompting-kling-v3 / slates-prompting-veo-3) — video models prompt very differently. projectId is REQUIRED for UI integration (the user sees a progress card and the asset lands in the project — without it the call fails). aspectRatio + duration are required (server returns requires_clarification when missing). Cost > $0.50 returns requires_confirm — pass confirm=true after explicit user OK. Veo locks to 16:9 and to 4/6/8s durations (4K only at 8s). Image-to-video via firstFrameAssetId. Frames-to-video via firstFrameAssetId + lastFrameAssetId (Veo / Seedance only). Ingredients via ingredientAssetIds (Kling Omni / Seedance). No skill files installed? Call slates_get_prompting_guide with the per-model guide (\'slates-prompting-veo-3\' / \'slates-prompting-kling-v3\' / \'slates-prompting-seedance\') and \'slates-cost-discipline\' before first use.',
+    description: 'Generate video via Slates credits. REQUIRED before calling: read the slates-cost-discipline skill plus the per-model prompting skill (slates-prompting-seedance / slates-prompting-kling-v3 / slates-prompting-veo-3) — video models prompt very differently. Also read slates-content-policy when the scene involves conflict, creatures, crowds, destruction, weapons, or young characters (build it safe-by-construction so the filter doesn\'t reject or degrade it). projectId is REQUIRED for UI integration (the user sees a progress card and the asset lands in the project — without it the call fails). aspectRatio + duration are required (server returns requires_clarification when missing). Cost > $0.50 returns requires_confirm — pass confirm=true after explicit user OK. Veo locks to 16:9 and to 4/6/8s durations (4K only at 8s). Image-to-video via firstFrameAssetId. Frames-to-video via firstFrameAssetId + lastFrameAssetId (Veo / Seedance only). Ingredients via ingredientAssetIds (Kling Omni / Seedance). No skill files installed? Call slates_get_prompting_guide with the per-model guide (\'slates-prompting-veo-3\' / \'slates-prompting-kling-v3\' / \'slates-prompting-seedance\') and \'slates-cost-discipline\' before first use.',
     input: z.object({
         prompt: z.string().min(1).max(4000),
-        model: z.enum(VIDEO_MODELS).describe('Pick deliberately by capability AND cost. Kling V3.0 std = cheapest (no audio); pro = mid; omni = multi-char dialogue + audio. Veo 3.1 = top quality, locks 16:9, audio; fast vs standard. Seedance 2 = ByteDance, audio included, supports first+last frame; pick economy vs priority via seedanceSpeed. For exact per-call credit cost, call slates_estimate_generation_cost or slates_list_available_models — never quote prices from memory (they change).'),
+        model: z.enum(VIDEO_MODELS).describe('Pick deliberately by capability AND cost. Kling V3.0 std = cheapest (no audio); pro = mid; omni = multi-char dialogue + audio. Veo 3.1 = top quality, locks 16:9, audio; fast vs standard. Seedance 2 = ByteDance (BytePlus), audio included, first+last frame + up to 9 reference images, full 480p–4K ladder (native 4K) via videoResolution. For exact per-call credit cost, call slates_estimate_generation_cost or slates_list_available_models — never quote prices from memory (they change).'),
         projectId: z.string().uuid().optional().describe('Save into this Slates project. Strongly recommended — the desktop UI shows a progress card live and the asset appears when complete.'),
         aspectRatio: z.enum(['1:1', '16:9', '9:16', '4:3', '3:4', '21:9', '9:21', '4:5', '5:4', '2:3', '3:2']).optional().describe('Veo locks to 16:9 — passing anything else will be ignored or fail. Kling/Seedance support all.'),
         duration: z.number().int().min(4).max(15).optional().describe('Seconds. Kling: 5-15. Veo: 4, 6, or 8 only (4K only at 8s). Seedance: 4-15. Default 5 if omitted but always be explicit (cost scales linearly).'),
-        videoResolution: z.enum(['720p', '1080p', '4k']).optional().describe('Veo only. 720p / 1080p same price. 4k more expensive.'),
-        seedanceSpeed: z.enum(['economy', 'priority']).optional().describe('Seedance only. Economy via PiAPI (cheaper, slower). Priority via fal.ai (faster).'),
+        videoResolution: z.enum(['480p', '720p', '1080p', '4k']).optional().describe('Veo + Seedance. Seedance: 480p/720p/1080p/4K (default 1080p; 4K is native, the most expensive). Veo: 720p/1080p same price, 4K more (8s only).'),
         firstFrameAssetId: z.string().uuid().optional().describe('Asset id from the project — used as the starting frame for image-to-video. Must already exist in the project.'),
         lastFrameAssetId: z.string().uuid().optional().describe('Asset id from the project — used as the ending frame. Veo and Seedance only. Pairs with firstFrameAssetId for guided transitions.'),
         ingredientAssetIds: z.array(z.string().uuid()).max(9).optional().describe('Asset ids used as visual reference / ingredients for Kling Omni or Seedance. Up to 9 (Seedance) or 4 (Kling).'),
+        characterAssetIds: z.array(z.string().uuid()).optional().describe('Asset ids of character sheets — keeps a character consistent across the shot. From a Slates project.'),
+        environmentAssetIds: z.array(z.string().uuid()).optional().describe('Asset ids of environment grids — keeps a location/setting consistent across the shot. From a Slates project.'),
+        styleAssetIds: z.array(z.string().uuid()).optional().describe('Asset ids of style references — locks the visual style of the shot. From a Slates project.'),
+        videoReferenceAssetId: z.string().uuid().optional().describe('Seedance ONLY: an existing VIDEO asset to use as a reference (edit / relocate an existing clip — Seedance ref-to-video). 2-15s. If the clip contains a human/AI character, pair with seedanceFace=true so it routes to the face-capable provider (the default Seedance route blocks people). Ignored by Kling/Veo.'),
         sound: z.boolean().optional().describe('Kling Omni / Veo / Seedance: enable audio generation. Default true.'),
         audioLanguage: z.enum(['EN', 'ZH', 'JA', 'KO', 'ES']).optional().describe('Kling Omni only — language for dialogue.'),
         generateMusic: z.boolean().optional().describe('Kling Omni only — auto-generate background music.'),
+        seedanceFace: z.boolean().optional().describe('Seedance ONLY: set true when a reference/ingredient shows an AI-character\'s FACE. Faces are blocked on the default (cheaper) Seedance route, so this reroutes the gen to a face-capable provider and costs ~10% more (the cost key becomes seedance-2-face-*). Leave false/unset for faceless or object-only references. No effect on Kling/Veo. Real-person faces are not supported on any route.'),
         negativePrompt: z.string().optional(),
         background: z.boolean().optional().describe(BACKGROUND_DESCRIBE),
         confirm: z.boolean().optional().describe('Set true after explicit user OK to bypass the >$0.50 cost confirm gate (which fires for almost every video gen since they\'re expensive).'),
@@ -1044,7 +1092,7 @@ export const generateVideo = {
             duration: input.duration,
             videoResolution: input.videoResolution,
             sound: input.sound,
-            seedanceSpeed: input.seedanceSpeed,
+            seedanceFace: input.seedanceFace,
         });
         const entry = registry.models.find((m) => m.model === costKey);
         if (!entry) {
@@ -1070,6 +1118,15 @@ export const generateVideo = {
         for (const id of input.ingredientAssetIds ?? []) {
             referenceRefs.push({ id, type: 'image', role: 'ingredient' });
         }
+        for (const id of input.characterAssetIds ?? []) {
+            referenceRefs.push({ id, type: 'image', role: 'character' });
+        }
+        for (const id of input.environmentAssetIds ?? []) {
+            referenceRefs.push({ id, type: 'image', role: 'environment' });
+        }
+        for (const id of input.styleAssetIds ?? []) {
+            referenceRefs.push({ id, type: 'image', role: 'style' });
+        }
         const hasReferences = referenceRefs.length > 0;
         if ((totalCents > 50 || hasReferences) && !input.confirm) {
             const previews = hasReferences ? await previewAssets(ctx, referenceRefs) : [];
@@ -1114,13 +1171,17 @@ export const generateVideo = {
             aspectRatio: input.aspectRatio,
             duration: input.duration,
             videoResolution: input.videoResolution,
-            seedanceSpeed: input.seedanceSpeed,
             firstFrameAssetId: input.firstFrameAssetId,
             lastFrameAssetId: input.lastFrameAssetId,
             ingredientAssetIds: input.ingredientAssetIds ?? [],
+            characterAssetIds: input.characterAssetIds ?? [],
+            environmentAssetIds: input.environmentAssetIds ?? [],
+            styleAssetIds: input.styleAssetIds ?? [],
+            videoReferenceAssetId: input.videoReferenceAssetId,
             sound: input.sound,
             audioLanguage: input.audioLanguage,
             generateMusic: input.generateMusic,
+            seedanceFace: input.seedanceFace,
             negativePrompt: input.negativePrompt,
             background: input.background,
         });
@@ -1170,6 +1231,7 @@ export const generateLipSync = {
         ttsSpeed: z.number().min(0.5).max(2).optional().describe('TTS speech rate. Default 1.0. Range 0.5-2.0.'),
         audioFilePath: z.string().optional().describe('Required when audioMethod=upload. Absolute path to the audio file on the user\'s machine (mp3, wav, m4a).'),
         avatarModel: z.enum(['avatar-standard', 'avatar-pro']).optional().describe('Image-source only. avatar-standard ($0.42/5s) for general use. avatar-pro ($0.86/5s) for sharper face fidelity. Ignored when sourceType=video.'),
+        klingProvider: z.enum(['fal', 'kling']).optional().describe('Provider routing for the Kling call. "fal" (default) uses Slates credits. "kling" uses the user\'s own BYOK Kling key if configured — omit unless the user explicitly wants BYOK.'),
         background: z.boolean().optional().describe(BACKGROUND_DESCRIBE),
         confirm: z.boolean().optional().describe('Set true to bypass the >$0.50 cost confirm gate. Required for avatar-pro.'),
     }),
@@ -1238,6 +1300,7 @@ export const generateLipSync = {
             ttsSpeed: input.ttsSpeed,
             audioFilePath: input.audioFilePath,
             avatarModel: input.avatarModel,
+            klingProvider: input.klingProvider,
             estimatedCost: totalCents,
             background: input.background,
         });
@@ -1283,6 +1346,7 @@ export const generateMotionTransfer = {
         motionModel: z.enum(['kling-mc-std', 'kling-mc-pro']).optional().describe('std ($0.95) for general motion. pro ($1.26) for cleaner anatomy + identity preservation. Default pro — pick std deliberately for cost savings.'),
         characterOrientation: z.enum(['video', 'image']).optional().describe('"video" = use the source video\'s framing. "image" = use the target image\'s framing. Default video.'),
         prompt: z.string().optional().describe('Optional refinement prompt. Read slates-prompting-motion-transfer for guidance.'),
+        klingProvider: z.enum(['fal', 'kling']).optional().describe('Provider routing for the Kling call. "fal" (default) uses Slates credits. "kling" uses the user\'s own BYOK Kling key if configured — omit unless the user explicitly wants BYOK.'),
         background: z.boolean().optional().describe(BACKGROUND_DESCRIBE),
         confirm: z.boolean().optional().describe('Set true to bypass the >$0.50 confirm gate. Required — both tiers exceed.'),
     }),
@@ -1329,6 +1393,7 @@ export const generateMotionTransfer = {
             motionModel,
             characterOrientation: input.characterOrientation ?? 'video',
             prompt: input.prompt,
+            klingProvider: input.klingProvider,
             estimatedCost: totalCents,
             background: input.background,
         });
@@ -1838,12 +1903,12 @@ function resolveGuideTopic(topic) {
 }
 export const getPromptingGuide = {
     id: 'slates_get_prompting_guide',
-    description: "Return the full markdown of a bundled Slates prompting/workflow guide. MCP-only clients (Claude Desktop, Smithery) don't get the CLI-installed skill files — call this instead. Accepts a guide name or a model id (e.g. 'veo-3.1-fast', 'kling-v3.0-pro', 'seedance-2-std', 'nano-banana-2') which maps to the right guide. ALWAYS read 'slates-cost-discipline' plus the relevant model guide before your first generation in a session.",
+    description: "Return the full markdown of a bundled Slates prompting/workflow guide. MCP-only clients (Claude Desktop, Smithery) don't get the CLI-installed skill files — call this instead. Accepts a guide name or a model id (e.g. 'veo-3.1-fast', 'kling-v3.0-pro', 'seedance-2', 'nano-banana-2') which maps to the right guide. ALWAYS read 'slates-cost-discipline' plus the relevant model guide before your first generation in a session.",
     input: z.object({
         topic: z
             .string()
             .min(1)
-            .describe('Guide name or model id. Guides: slates-cost-discipline, 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'),
+            .describe('Guide name or model id. Guides: slates-cost-discipline, slates-content-policy, 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'),
     }),
     async run(input) {
         const resolved = resolveGuideTopic(input.topic);
@@ -1881,6 +1946,8 @@ export const ALL_OPERATIONS = [
     setCharacterExpression,
     listEnvironments,
     createEnvironment,
+    generateCharacterSheets,
+    generateEnvironmentPlate,
     listStoryboards,
     createStoryboard,
     getStoryboardWithFrames,

package/dist/prompts/content-policy.d.ts

@@ -0,0 +1,31 @@
+export interface SubstitutionRule {
+    /** The risky construction to avoid. */
+    avoid: string;
+    /** The safe-by-construction substitution that usually reads more cinematic. */
+    use: string;
+}
+/**
+ * The substitution table — the core craft move. When a scene drifts toward any
+ * `avoid`, re-stage it as the matching `use` before writing the prompt.
+ */
+export declare const CONTENT_POLICY_SUBSTITUTIONS: SubstitutionRule[];
+/** The pre-flight checklist — run before delivering any risk-surface prompt. */
+export declare const CONTENT_POLICY_PREFLIGHT: string[];
+/** One-line summary used as a header in skills + the lead magnet. */
+export declare const CONTENT_POLICY_HEADLINE = "Don't depict the harm \u2014 depict the energy, the aftermath, the threat, or the scale. Build the scene safe from the first word.";
+/** The confirmed-safe envelope — pull a drifting scene back toward this shape. */
+export declare const CONTENT_POLICY_SAFE_BENCHMARK = "One original creature, in a generalized monument or amphitheatre, in daylight, no weapons present, performing expressive action (rising, roaring, spreading wings). Original design, generalized location, daylight, expressive rather than violent \u2014 most epic ideas re-stage into this without losing the punch.";
+/** The containment clause — keeps a scene in policy AND grounds its physics. */
+export declare const CONTENT_POLICY_CONTAINMENT = "Give any creature or combat scene a containment rule (\"the fight STAYS at the sea surface\", \"boss scale locked ~2.5 human-heights, NOT kaiju-giant\", \"destruction stays in the evacuated valley\"). It improves coherence (no absurd escalation) AND keeps the scene inside policy \u2014 same clause buys both.";
+/** The hard, non-negotiable rule on minors. Overrides every stylistic goal. */
+export declare const CONTENT_POLICY_MINORS = "Never write romantic, sexual, or suggestive content involving or directed at minors, and never anything that sexualizes a young-presenting character. Any scene with children stays wholesome and age-appropriate. Non-negotiable.";
+/**
+ * Canonical markdown block — the SOURCE OF TRUTH the skill markdown, the desktop
+ * inline mirror, and the lead-magnet are reconciled AGAINST. NOTE: nothing
+ * imports this yet — the desktop carries its own inline copy and the skills
+ * hand-author their prose, so a change here must be propagated to those copies
+ * in the same pass until the desktop-import + skill-embed wiring lands (see
+ * plans/2026-06-25-slates-prompting-system-overhaul.md).
+ */
+export declare const CONTENT_POLICY_TEXT: string;
+//# sourceMappingURL=content-policy.d.ts.map

package/dist/prompts/content-policy.js

@@ -0,0 +1,108 @@
+// Content-policy-safe construction — the canonical "build the scene safe from
+// the first word" knowledge for every Slates surface (desktop templates, MCP
+// skills, the lead-magnet .skill). Authored ONCE here; consumers derive from it.
+//
+// The principle: don't depict the harm — depict the energy, the aftermath, the
+// threat, or the scale. A standoff is more tense than a massacre; an evacuated
+// city is eerier than a crowd in panic; a roar lands harder than a kill. The
+// substitutions below usually read as MORE cinematic, not less, and they keep a
+// generation from getting silently rejected or degraded by the model's filter.
+//
+// Source: second-brain business/projects/slates/content-strategy/lead-magnets/
+// reference-content-policy.md. SSOT map: business/projects/slates/product/
+// prompting-ssot.md.
+/**
+ * The substitution table — the core craft move. When a scene drifts toward any
+ * `avoid`, re-stage it as the matching `use` before writing the prompt.
+ */
+export const CONTENT_POLICY_SUBSTITUTIONS = [
+    {
+        avoid: 'Civilians in panic, crowds fleeing under debris',
+        use: 'An evacuated / empty city; abandoned streets; a lone figure for scale',
+    },
+    {
+        avoid: 'Weapons firing into buildings or at people',
+        use: 'Energy-discharge standoffs, searchlights sweeping, charged auras, shockwaves with no muzzle fire',
+    },
+    {
+        avoid: 'Creatures tearing into each other, gore',
+        use: 'A grapple / standoff — roars, near-misses, circling, an energy clash; combat that stays contained (in/on the water, never lifting into the air)',
+    },
+    {
+        avoid: 'Destruction with people in harm’s way',
+        use: 'Destruction in uninhabited terrain — glaciers, deserts, ruins, open sea, evacuated zones',
+    },
+    {
+        avoid: 'Realistic guns as the focus',
+        use: 'Stylized / fantasy implements, weapons slung-not-fired, the weapon as silhouette or prop only',
+    },
+    {
+        avoid: 'Blood, wounds, death',
+        use: 'Impact light, dust, debris, buckling and collapse, a silhouette dropping out of frame',
+    },
+    {
+        avoid: 'Real, named public figures',
+        use: 'Original / anonymous characters',
+    },
+    {
+        avoid: 'Real brand logos',
+        use: 'Original or generalized branding — except the user’s own product, which is the whole point of a brand film',
+    },
+];
+/** The pre-flight checklist — run before delivering any risk-surface prompt. */
+export const CONTENT_POLICY_PREFLIGHT = [
+    'No civilians depicted in panic/harm; crowds are evacuated or absent.',
+    'No weapons firing at people/buildings; threat is energy / searchlight / silhouette.',
+    'No creature-on-creature or creature-on-person gore; combat is grapple / standoff / roar, contained.',
+    'Destruction is in uninhabited / evacuated terrain.',
+    'Creatures are original ("not based on any franchise"); no real public figures; no real brand logos except the user’s own product.',
+    'Anything with children is wholesome and age-appropriate.',
+];
+// ── Reusable text fragments (the template-assembly building blocks) ──
+// The exact strings the desktop prompt templates, MCP skills, and lead-magnet
+// compose. Change a rule HERE and every consumer follows.
+/** One-line summary used as a header in skills + the lead magnet. */
+export const CONTENT_POLICY_HEADLINE = "Don't depict the harm — depict the energy, the aftermath, the threat, or the scale. Build the scene safe from the first word.";
+/** The confirmed-safe envelope — pull a drifting scene back toward this shape. */
+export const CONTENT_POLICY_SAFE_BENCHMARK = 'One original creature, in a generalized monument or amphitheatre, in daylight, no weapons present, performing expressive action (rising, roaring, spreading wings). Original design, generalized location, daylight, expressive rather than violent — most epic ideas re-stage into this without losing the punch.';
+/** The containment clause — keeps a scene in policy AND grounds its physics. */
+export const CONTENT_POLICY_CONTAINMENT = 'Give any creature or combat scene a containment rule ("the fight STAYS at the sea surface", "boss scale locked ~2.5 human-heights, NOT kaiju-giant", "destruction stays in the evacuated valley"). It improves coherence (no absurd escalation) AND keeps the scene inside policy — same clause buys both.';
+/** The hard, non-negotiable rule on minors. Overrides every stylistic goal. */
+export const CONTENT_POLICY_MINORS = 'Never write romantic, sexual, or suggestive content involving or directed at minors, and never anything that sexualizes a young-presenting character. Any scene with children stays wholesome and age-appropriate. Non-negotiable.';
+/**
+ * Canonical markdown block — the SOURCE OF TRUTH the skill markdown, the desktop
+ * inline mirror, and the lead-magnet are reconciled AGAINST. NOTE: nothing
+ * imports this yet — the desktop carries its own inline copy and the skills
+ * hand-author their prose, so a change here must be propagated to those copies
+ * in the same pass until the desktop-import + skill-embed wiring lands (see
+ * plans/2026-06-25-slates-prompting-system-overhaul.md).
+ */
+export const CONTENT_POLICY_TEXT = `## Content-policy-safe construction
+
+${CONTENT_POLICY_HEADLINE}
+
+Write scenes that hit full cinematic impact without ever *needing* to depict prohibited content. This is a craft move, not a compromise — the substitutions below usually read as more cinematic, not less, and they keep your generation from getting silently rejected or degraded by the model's filter. Load this whenever a prompt involves conflict, creatures, crowds, destruction, weapons, or young characters.
+
+### Substitution table
+
+| Avoid | Use instead |
+|---|---|
+${CONTENT_POLICY_SUBSTITUTIONS.map((s) => `| ${s.avoid} | ${s.use} |`).join('\n')}
+
+### The safe benchmark
+${CONTENT_POLICY_SAFE_BENCHMARK}
+
+### Containment rule — it doubles as a physics win
+${CONTENT_POLICY_CONTAINMENT}
+
+### Scale and stakes without harm
+Epic stakes come from environmental danger and reaction, not depicted victims: tiny figures diving clear of *collapsing* terrain (not being crushed), a war-horn over an *empty* field, an army *scrambling* across a frozen valley as a titan tears free of a glacier. The danger is the environment; the figures are reacting, not dying. Snow plumes, glowing runes, splintering ice, shockwaves, and dust carry the chaos.
+
+### Minors — hard rule
+${CONTENT_POLICY_MINORS}
+
+### Pre-flight (run before delivering any risk-surface prompt)
+${CONTENT_POLICY_PREFLIGHT.map((c) => `- [ ] ${c}`).join('\n')}
+
+If a box fails, apply the substitution table before writing the prompt.`;
+//# sourceMappingURL=content-policy.js.map

package/dist/prompts/index.d.ts

@@ -1,4 +1,6 @@
 export * from './reference-rules.js';
+export * from './reference-composer.js';
+export * from './content-policy.js';
 export * from './style-library.js';
 export * from './model-facts.js';
 export * from './character-sheet.js';

package/dist/prompts/index.js

@@ -10,6 +10,8 @@
 // plan). So a change here must be applied to those copies in the same pass for
 // now. SSOT map: second-brain business/projects/slates/product/prompting-ssot.md
 export * from './reference-rules.js';
+export * from './reference-composer.js';
+export * from './content-policy.js';
 export * from './style-library.js';
 export * from './model-facts.js';
 export * from './character-sheet.js';

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

@@ -0,0 +1,46 @@
+export type ReferenceKind = 'character' | 'environment' | 'style' | 'pinned' | 'first-frame' | 'last-frame' | 'video';
+export interface ReferenceMedia {
+    path: string;
+    mediaKind: 'image' | 'video';
+}
+/**
+ * A named bucket of reference media that can be @mentioned. The whole definition
+ * of a reference. It does NOT mandate a structure — one photo or eight angles,
+ * the composer treats them all as "this is one named thing".
+ */
+export interface ReferenceGroup {
+    /** '@Marcus' | '@Cafe' | '#noir' | null (pinned / frames / picked video) */
+    token: string | null;
+    /** Display + citation name: 'Marcus' | 'the cafe' | 'noir'. Used verbatim. */
+    name: string;
+    kind: ReferenceKind;
+    /** A group can carry several images (e.g. turnaround + expression). */
+    media: ReferenceMedia[];
+}
+export interface ComposedReferences {
+    /** The composed prompt: user's words lead, references cited inline as "image N". */
+    prompt: string;
+    /** Free-reference image paths in cited order — flatten yields "image 1..N". */
+    orderedImagePaths: string[];
+    /** Video reference paths in cited order — "video 1..M". */
+    orderedVideoPaths: string[];
+}
+/**
+ * Compose the raw prompt (mentions intact) + an ORDERED list of reference groups
+ * into the named prompt text + ordered media the API receives. The group order
+ * IS the send order — image numbers are assigned by walking the list, so the
+ * caller controls numbering by ordering the list (default: pinned/base first,
+ * then @mentions in first-appearance order, then #style last).
+ *
+ * @param rawPrompt  the user's prompt with @mentions / #tags still in it
+ * @param groups     the single ordered ReferenceGroup[] (rail + prompt read this)
+ * @param opts.startImageNumber  images already attached AHEAD of these groups
+ *   (e.g. a grid-cell base that is "image 1" before the free-refs). Free-ref
+ *   numbering and orderedImagePaths begin after it. Default 0.
+ */
+export interface ComposeOptions {
+    startImageNumber?: number;
+    startVideoNumber?: number;
+}
+export declare function composeReferences(rawPrompt: string, groups: ReferenceGroup[], opts?: ComposeOptions): ComposedReferences;
+//# sourceMappingURL=reference-composer.d.ts.map