@slatesvideo/shared 0.6.4 → 0.6.5

package/dist/operations/index.js

@@ -14,6 +14,7 @@ import { SlatesCloudClient } from '../clients/cloud.js';
 import { SlatesDesktopClient } from '../clients/desktop.js';
 import { BlenderBridgeClient, BLENDER_SETUP_HINT, RENDER_TIMEOUT_MS } from '../clients/blender.js';
 import { SKILLS } from '../skills/content.js';
+import { appManualSections } from '../manual/index.js';
 // Reference-capacity prose is DERIVED, never hand-typed — root CLAUDE.md:
 // "never hand-type a fact an LLM will read". These helpers read MODEL_FACTS.
 import { multimodalRefSummary, multimodalRefModels, seedanceTaskIntentWords, 
@@ -183,6 +184,15 @@ export const TTS_MAX_CHARACTERS = (() => {
     return max;
 })();
 export const TTS_BUCKET_COUNT = TTS_MAX_CHARACTERS / TTS_BUCKET_CHARS; // 8
+/** The seat's cloning spec — reference-clip bounds, the design-prompt bounds
+ *  and the workspace-wide clone rate — read from the SSOT for the same reason
+ *  as the cap: every number in it was MEASURED and lives in exactly one row. */
+export const TTS_VOICE_CLONE = (() => {
+    const spec = getModelCapability(TTS_MODEL)?.voiceClone;
+    if (!spec)
+        throw new Error(`MODEL_CAPABILITIES['${TTS_MODEL}'] must declare voiceClone`);
+    return spec;
+})();
 function creditCost(m) {
     if (!m)
         return 0;
@@ -219,7 +229,7 @@ const IMAGE_INLINE_REVIEW = 'The image is attached to this result — look at it
 const VIDEO_REVIEW_POINTER = 'You have NOT seen this clip: call slates_get_asset_video_frames on the asset id above before ' +
     'describing how it looks. A quality claim you cannot point to a tool result for is a REAL NUMBERS ONLY violation.';
 const BACKGROUND_REVIEW_POINTER = 'When it completes, look at it before you describe it — slates_get_asset_image for images, ' +
-    'slates_get_asset_video_frames for video.';
+    'slates_get_asset_video_frames for video. For audio, audition the saved file; metadata alone does not establish voice similarity or delivery quality.';
 // The image saved, but reading it back off disk failed (best-effort fetch). The
 // agent has an asset and NO pixels, which is the one state where a quality
 // claim would be pure invention — so this branch has to say so rather than
@@ -2727,14 +2737,68 @@ export const generateVideo = {
         };
     },
 };
+// ── The preset voice shelf ──────────────────────────────────────
+/**
+ * AGENT PARITY for the voice picker. The desktop browses stock voices by
+ * gender, accent and age and plays each one; until this op the agent could
+ * only pass a `voiceId` it had no way to discover. Disk reads on the desktop,
+ * never a vendor call — browsing is free on every surface.
+ */
+export const listVoices = {
+    id: 'slates_list_voices',
+    description: `Browse ${TTS_MODEL} preset voices. Pass a returned voiceId to slates_generate_audio. Filters AND together.`,
+    input: z.object({
+        gender: z.string().optional().describe('male | female'),
+        accent: z.string().optional().describe('Region ("GB") or languageCode ("en-GB"); available accents come from the shelf.'),
+        age: z.string().optional().describe('young | middle_aged | elderly'),
+        query: z.string().optional().describe('Free text over name, description, tags.'),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('voices', 'the preset voice shelf');
+        const shelf = await desktop.get('/agent/voices');
+        if (!shelf.available) {
+            return ok({ available: false, voices: [], message: 'This desktop build shipped without the preset shelf.' });
+        }
+        const terms = (input.query ?? '').toLowerCase().split(/\s+/).filter(Boolean);
+        const region = input.accent?.includes('-') ? input.accent.split('-')[1] : input.accent;
+        const voices = shelf.voices
+            .filter((v) => !input.gender || v.gender === input.gender)
+            .filter((v) => !region || v.languageCode.split('-')[1]?.toUpperCase() === region.toUpperCase())
+            .filter((v) => !input.age || v.ageGroup === input.age)
+            .filter((v) => {
+            if (terms.length === 0)
+                return true;
+            const hay = [v.displayName, v.description, v.gender, v.ageGroup, v.languageCode, ...(v.tags ?? [])]
+                .join(' ')
+                .toLowerCase();
+            return terms.every((t) => hay.includes(t));
+        })
+            .map(({ voiceId, displayName, description, tags, gender, ageGroup, languageCode }) => ({
+            voiceId,
+            displayName,
+            description,
+            tags,
+            gender,
+            ageGroup,
+            languageCode,
+        }));
+        return ok({
+            available: true,
+            line: shelf.line,
+            count: voices.length,
+            voices,
+            next: `Pass a voiceId to slates_generate_audio (model ${TTS_MODEL}) as voiceId. To keep one on a character for reuse, generate a clip with it and set slates_update_character voiceAssetId.`,
+        });
+    },
+};
 // ── Generate audio ──────────────────────────────────────────────
 export const generateAudio = {
     id: 'slates_generate_audio',
     billable: true,
-    description: 'Generate AUDIO via Slates credits — the third media type, saved as a project asset you can drop on an audio track. Three surfaces: seed-audio (default; a whole audio SCENE — dialogue + SFX + ambience — from one plain sentence, 3-120s), eleven-sfx (ONE effect with an exact 1-22s duration, or a seamless loop), and inworld-tts-2 (one named voice saying one line; the prompt IS the words, billed per character). Which surface for which job: read the slates-model-selection skill. ' +
-        '🚨 seed-audio has NO duration parameter — the length you pass is written INTO THE PROMPT and is what the user is BILLED, whatever comes back. Choose it deliberately. ' +
-        'REQUIRED before calling: read slates-cost-discipline and the matching prompting skill (slates-prompting-seed-audio | slates-prompting-elevenlabs | slates-prompting-inworld-tts). Kling\'s "SFX:" / "Ambient noise:" prompt syntax does NOT transfer to seed-audio and makes results worse. ' +
-        'projectId is REQUIRED (no headless path). ' +
+    description: `Generate project audio using credits. Choose the surface via the model routing below. ` +
+        'Read slates-cost-discipline and the matching prompting skill first (slates-prompting-seed-audio | slates-prompting-elevenlabs | slates-prompting-inworld-tts). ' +
+        'Seed Audio bills the requested duration, which is appended to the prompt regardless of output length. Kling "SFX:" / "Ambient noise:" syntax does not transfer. ' +
         CONFIRM_GATE_SENTENCE +
         ' No skill files installed? Call slates_get_prompting_guide first.',
     input: z.object({
@@ -2753,25 +2817,27 @@ export const generateAudio = {
         durationSeconds: z
             .number()
             .optional()
-            .describe('seed-audio 3-120 (default 15) — ⚠️ THIS IS THE BILL: it is appended to the prompt and charged regardless of the returned length. eleven-sfx 1-22 (default 4) — always sent explicitly so the per-second charge is deterministic.'),
+            .describe(`seed-audio ${SEED_AUDIO_MIN_SECONDS}-${SEED_AUDIO_MAX_SECONDS} (default ${SEED_AUDIO_DEFAULT_SECONDS}) — ⚠️ THIS IS THE BILL: appended to the prompt and charged whatever comes back. eleven-sfx ${ELEVEN_SFX_MIN_SECONDS}-${ELEVEN_SFX_MAX_SECONDS} (default ${ELEVEN_SFX_DEFAULT_SECONDS}) — always sent explicitly so the per-second charge is deterministic. Not for ${TTS_MODEL}.`),
         voice: z
             .string()
             .optional()
-            .describe('seed-audio only — a preset voice id (e.g. "cedric_en_zh"). Leave unset to let the scene cast itself, which is usually right for background dialogue. Agent-facing only: there is no user-facing voice picker.'),
+            .describe('seed-audio only — a preset voice id (e.g. "cedric_en_zh"). Leave unset to let the scene cast itself. Agent-facing only.'),
         voiceId: z
             .string()
             .optional()
-            .describe('inworld-tts-2 — the voice to speak in. One of these three is required there.'),
+            .describe(`${TTS_MODEL} — a preset voiceId from slates_list_voices, not a character or asset id. Exactly one voice source is required.`),
         voiceReferenceAssetId: z
             .string()
             .optional()
-            .describe('inworld-tts-2 — clone the voice from this AUDIO asset (5-15s of one clean speaker).'),
+            .describe(`${TTS_MODEL} — clone this AUDIO asset's voice for the take (${TTS_VOICE_CLONE.minSeconds}-${TTS_VOICE_CLONE.maxSeconds}s, one clean speaker). To speak AS a character pass its voiceAssetId. Cloning: ${TTS_VOICE_CLONE.clonesPerMinute} new voices/min across all of Slates; a burst waits.`),
         voiceDescription: z
             .string()
+            .min(TTS_VOICE_CLONE.designPromptChars.min)
+            .max(TTS_VOICE_CLONE.designPromptChars.max)
             .optional()
-            .describe('inworld-tts-2 — build a voice from this description, for a character with no recording.'),
+            .describe(`${TTS_MODEL} — a voice from words (${TTS_VOICE_CLONE.designPromptChars.min}-${TTS_VOICE_CLONE.designPromptChars.max} chars) for a character with no recording; keep it via slates_update_character voiceAssetId.`),
         speed: z.number().min(0.5).max(2).optional().describe('seed-audio only — 0.5-2.0. Reach for it when dialogue races or drags against picture.'),
-        volume: z.number().min(0.5).max(2).optional().describe('seed-audio only — output gain, 0.5-2.0 (1 = unchanged). Prefer the timeline track fader for mix decisions; this is for when the model itself renders a scene too hot or too quiet.'),
+        volume: z.number().min(0.5).max(2).optional().describe('seed-audio only — output gain, 0.5-2.0 (1 = unchanged). Prefer the timeline fader for mix decisions.'),
         pitch: z.number().int().min(-12).max(12).optional().describe('seed-audio only — semitones. Small moves; ±3 is already a lot.'),
         multilingual: z.boolean().optional().describe('seed-audio only — better non-English / mixed-language handling.'),
         loop: z.boolean().optional().describe('eleven-sfx only — produce a seamless loop (rain, engine hum, crowd murmur).'),
@@ -2780,7 +2846,7 @@ export const generateAudio = {
             .array(z.string())
             .max(3)
             .optional()
-            .describe('seed-audio only — up to 3 AUDIO assets (UUIDs or badge codes like "AUD-S1"), each ≤30s, referenced in the prompt as @Audio1-@Audio3 ("match the room tone of @Audio1"). MUTUALLY EXCLUSIVE with imageReferenceAssetId — the API rejects both.'),
+            .describe('seed-audio only — up to 3 AUDIO assets (UUIDs or badge codes like "AUD-S1"), each ≤30s, referenced in the prompt as @Audio1-@Audio3 ("match the room tone of @Audio1"). MUTUALLY EXCLUSIVE with imageReferenceAssetId.'),
         imageReferenceAssetId: z
             .string()
             .optional()
@@ -2823,7 +2889,7 @@ export const generateAudio = {
                 return ok({
                     requires_clarification: true,
                     missing: ['voiceId'],
-                    message: `${TTS_MODEL} needs a voice. Ask the user WHICH CHARACTER is speaking and pass that character's voice as voiceId — a voice is a field on a character, not a thing to pick at generation time. To make a NEW voice, pass voiceReferenceAssetId (a clip to clone) or voiceDescription (words, for a character with no recording).`,
+                    message: `${TTS_MODEL} needs a voice — exactly one of three. Speaking AS a character: pass its voiceAssetId (slates_list_characters) as voiceReferenceAssetId. A stock voice: slates_list_voices lists presets by gender, accent and age; pass one's voiceId. No recording of the voice: voiceDescription (words), or voiceReferenceAssetId with any clean clip of one speaker. A voice worth reusing can be kept on a character with slates_update_character, but nothing requires that — ask the user which they want only when the request does not say.`,
                 });
             }
             if (voiceSources.length > 1) {
@@ -3725,17 +3791,33 @@ export const setFolderCover = {
 };
 export const updateCharacter = {
     id: 'slates_update_character',
-    description: 'Update a character\'s name, description, or style. Use slates_set_character_identity_asset for its canonical image.',
+    description: 'Update a character\'s name, description, style, or voice. 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(),
         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'."),
+        // Agent parity for the character card's voice slot: the desktop route has
+        // taken this since 2026-08-28; the op never exposed it, so an agent could
+        // render a voice and had no way to keep it on the character.
+        voiceAssetId: z
+            .string()
+            .uuid()
+            .nullable()
+            .optional()
+            .describe("The AUDIO asset that is this character's voice (what inworld-tts-2 clones for its lines); null detaches, the clip stays."),
     }),
     async run(input, ctx) {
         return ok(await ctx.desktop().post('/agent/characters/update', {
             id: input.characterId,
-            data: { name: input.name, description: input.description, style: input.style },
+            data: {
+                name: input.name,
+                description: input.description,
+                style: input.style,
+                // Sent only when given: the route treats presence as intent, and an
+                // explicit null is the detach.
+                ...(input.voiceAssetId !== undefined ? { voiceAssetId: input.voiceAssetId } : {}),
+            },
         }));
     },
 };
@@ -4021,8 +4103,8 @@ const SHOT_ASPECT_RATIOS = [...new Set([...VIDEO_ASPECT_RATIOS, ...IMAGE_ASPECT_
 function shotParamsShape(described) {
     const d = (node, text) => (described ? node.describe(text) : node);
     return {
-        aspectRatio: d(zEnum(SHOT_ASPECT_RATIOS).optional(), 'Validated against the chosen model when the Shot is saved — see slates_generate_video for the per-model sets.'),
-        duration: d(z.number().int().min(1).max(360).optional(), 'Seconds — video or audio. Required before a video Shot can be priced or fired; validated against the model when saved.'),
+        aspectRatio: d(zEnum(SHOT_ASPECT_RATIOS).optional(), 'Validated against the model; see slates_generate_video.'),
+        duration: d(z.number().int().min(1).max(360).optional(), 'Seconds for video or duration-based audio; TTS uses text length.'),
         videoResolution: d(zEnum(VIDEO_RESOLUTIONS).optional(), 'Validated against the chosen model when the Shot is saved.'),
         imageResolution: d(z.enum(['1k', '2k', '3k', '4k']).optional(), 'Image models only.'),
         gptQuality: d(z.enum(['medium', 'high']).optional(), 'gpt-image-2 only.'),
@@ -4031,6 +4113,11 @@ function shotParamsShape(described) {
         sound: d(z.boolean().optional(), 'Video models that co-generate audio.'),
         seedanceFace: d(z.boolean().optional(), "Seedance only — a reference shows an AI character's FACE; reroutes to a face-capable provider at ~45% more."),
         audioDurationSeconds: d(z.number().int().min(1).max(120).optional(), 'Audio lane. On seed-audio the requested duration IS the bill.'),
+        // The TTS voice — the same three fields slates_generate_audio takes, so a
+        // Shot is the audio call, serialized. Exactly one of them, enforced at fire.
+        voiceId: d(z.string().optional(), `${TTS_MODEL}: preset voiceId (slates_list_voices).`),
+        voiceReferenceAssetId: d(z.string().optional(), `${TTS_MODEL}: audio asset to clone.`),
+        voiceDescription: d(z.string().optional(), `${TTS_MODEL}: the voice in words.`),
     };
 }
 const shotParamsSchema = z.object(shotParamsShape(true)).optional();
@@ -4047,10 +4134,7 @@ const shotParamsSchemaTerse = z
  * ship a field with no explanation — the same failure as a column nothing
  * renders.
  *
- * 🚨 AND NONE OF THEM IS SENT TO A MODEL. They are a planning and counting
- * surface; the prompt is the only thing the request carries. The one exception
- * is pre-existing: a multiShotSegment still prepends its own camera and
- * shotSize to its own segment prompt.
+ * Script fields supply prompt prose when no authored prompt exists (shot-spec.ts).
  */
 function shotScriptShape(described) {
     const text = Object.fromEntries(SCRIPT_TEXT_FIELDS.map((field) => [
@@ -4151,6 +4235,8 @@ function shotRefInputs(input) {
         out.push({ ref: input.firstFrameAssetId, role: 'first frame' });
     if (input.lastFrameAssetId)
         out.push({ ref: input.lastFrameAssetId, role: 'last frame' });
+    if (input.params?.voiceReferenceAssetId)
+        out.push({ ref: input.params.voiceReferenceAssetId, role: 'voice reference' });
     return out;
 }
 /**
@@ -4187,7 +4273,10 @@ async function buildShotSpecInput(ctx, projectId, input) {
             // later diverges from it and the desktop card says so — the prompt is
             // never rewritten (that is prompt enhancement, deleted 2026-08-01).
             authoredFor: input.model ?? null,
-            params: shotParamsPatch(input.params),
+            params: {
+                ...shotParamsPatch(input.params),
+                ...(input.params?.voiceReferenceAssetId ? { voiceReferenceAssetId: rid(input.params.voiceReferenceAssetId) } : {}),
+            },
             mentions: {
                 characterIds: input.characterIds ?? [],
                 environmentIds: input.environmentIds ?? [],
@@ -4240,12 +4329,12 @@ function shotCostKey(detail) {
     // has none, so it falls back to the raw ones and is announced as a floor.
     const fires = detail.firesWith;
     if (AUDIO_MODELS.includes(model)) {
-        // The TTS seat prices on the TEXT, and a Shot carries no text field — so a
-        // Shot cannot be a TTS generation and cannot be quoted as one. Explicit,
-        // because the `!seconds` line below would also return null here and that
-        // would read as "duration missing" for a surface that has no duration.
-        if (model === TTS_MODEL)
-            return null;
+        if (model === TTS_MODEL) {
+            const text = detail.composedPrompt ?? (detail.rawPrompt.trim() || detail.line?.trim() || '');
+            if (!text || text.length > TTS_MAX_CHARACTERS)
+                return null;
+            return audioCostKey({ model, characters: text.length });
+        }
         const seconds = fires?.audioDurationSeconds ?? p.audioDurationSeconds;
         if (!seconds)
             return null;
@@ -4453,8 +4542,17 @@ export const duplicateShot = {
             spec.prompt = input.prompt;
         if (input.model !== undefined)
             spec.model = input.model;
-        if (input.params !== undefined)
-            spec.params = shotParamsPatch(input.params);
+        if (input.params !== undefined) {
+            const voiceRef = input.params.voiceReferenceAssetId;
+            if (voiceRef && !UUID_RE.test(voiceRef)) {
+                const { shot } = await desktop.get('/agent/shots/get', { id: input.shotId });
+                const built = await buildShotSpecInput(ctx, shot.projectId, { params: input.params });
+                spec.params = built.spec.params;
+            }
+            else {
+                spec.params = shotParamsPatch(input.params);
+            }
+        }
         const r = await desktop.post('/agent/shots/duplicate', {
             id: input.shotId,
             name: input.name,
@@ -4565,8 +4663,8 @@ export const listShots = {
             ' depend on the reference set — Seedance reference-clip seconds and MiniMax reference images' +
             ' past the free five — are missing from it. slates_get_shot prices one exactly, and' +
             ' slates_generate_from_shots quotes the set exactly before it fires anything.' +
-            (describeVarietyReport(r.variety) ? `
-
+            (describeVarietyReport(r.variety) ? `
+
 ${describeVarietyReport(r.variety)}` : ''));
     },
 };
@@ -4715,7 +4813,7 @@ export const generateFromShots = {
                     // something to try again spends credits before anyone notices.
                     `\n${failedLines.join('\n')}\nThese were NOT retried. Read each error, fix the Shot, and re-fire only what you meant to.`
                 : '') +
-            ` ${VIDEO_REVIEW_POINTER}`);
+            ` ${BACKGROUND_REVIEW_POINTER}`);
     },
 };
 function resolveGuideTopic(topic) {
@@ -4874,15 +4972,16 @@ function describeGuideTopics() {
 }
 export const getPromptingGuide = {
     id: 'slates_get_prompting_guide',
-    description: 
-    // 🚨 NO "ALWAYS READ THIS FIRST" SENTENCE. It stood here for months and was
-    // MEASURED at 13% compliance before and after the enforcement work — pointer
-    // prose is the shape that does not move the agent. What replaced it is
-    // structural: the never-use list rides the generate ops' descriptions and
-    // the craft card rides the estimate result, so the facts arrive whether or
-    // not this op is ever called.
-    "Return 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 ('veo-3.1-fast', 'kling-v3.0-pro', 'seedance-2', 'nano-banana-2'), which maps to the right guide. Reach for it when a card is not enough: the failure modes, the worked examples and the sources are only in the full text.",
+    description: 'For app help and exact UI instructions use topic "app-manual" with a query such as "voice recording". This returns the canonical product manual, shared by every agent surface. ' +
+        // 🚨 NO "ALWAYS READ THIS FIRST" SENTENCE. It stood here for months and was
+        // MEASURED at 13% compliance before and after the enforcement work — pointer
+        // prose is the shape that does not move the agent. What replaced it is
+        // structural: the never-use list rides the generate ops' descriptions and
+        // the craft card rides the estimate result, so the facts arrive whether or
+        // not this op is ever called.
+        "Return 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 ('veo-3.1-fast', 'kling-v3.0-pro', 'seedance-2', 'nano-banana-2'), which maps to the right guide. Reach for it when a card is not enough: the failure modes, the worked examples and the sources are only in the full text.",
     input: z.object({
+        query: z.string().max(200).optional().describe('For app-manual: keywords to retrieve relevant UI sections. Omit for the entire manual.'),
         topic: z
             .string()
             .min(1)
@@ -4890,6 +4989,10 @@ export const getPromptingGuide = {
         depth: z.enum(['card', 'full']).optional().describe('"card" returns just the levers block (a few hundred words — the same card slates_estimate_generation_cost already attached, so usually redundant). "full" (default) returns the whole guide, up to several thousand words.'),
     }),
     async run(input) {
+        if (input.topic.trim().toLowerCase() === 'app-manual') {
+            const content = appManualSections(input.query);
+            return { text: content, data: { topic: 'app-manual', bytes: Buffer.byteLength(content, 'utf8') } };
+        }
         const resolved = resolveGuideTopic(input.topic);
         const content = resolved ? SKILLS[resolved] : undefined;
         if (!resolved || content === undefined) {
@@ -5124,6 +5227,7 @@ export const ALL_OPERATIONS = [
     generateImage,
     generateVideo,
     generateAudio,
+    listVoices,
     generateLipSync,
     generateMotionTransfer,
     editVideo,

package/dist/prompts/agent-doctrine.js

@@ -79,6 +79,7 @@ export function buildSkillIndex() {
 const PREAMBLE = fork(`You are the Slates Studio Agent — a production assistant living inside Slates, the AI video creation studio. You plan and execute video/image production runs by chaining the Slates tools: script → characters → images → videos → quality-check → regenerate, ending with assets in the user's project (and on the timeline when asked).`, `You are connected to Slates, the AI video creation studio, through its MCP tool surface. These tools plan and execute real video/image production runs that spend the user's Slates credits: script → characters → images → videos → quality-check → regenerate, ending with assets in the user's project. Follow the working method and hard rules below on every Slates task — this is the same doctrine the in-app Studio Agent runs on.`);
 // ── The working method ─────────────────────────────────────────────
 export const WORKING_METHOD = [
+    both(`For HOW/WHERE questions, load slates_get_prompting_guide with topic "app-manual" and relevant query keywords. Teach the documented buttons and tabs, preserving model-specific conditions; do not invent UI paths or mutate the project when the user only asks for instructions. Slates is a sandbox of optional tools, not a required pipeline.`),
     both(`1. UNDERSTAND the outcome the user wants. If intent is clear, act with sane defaults — don't interrogate. If genuinely ambiguous, batch every question into ONE message.`),
     both(`2. ORIENT: call slates_get_workspace_state once at the start of a workflow. Work in the user's CURRENT project — this chat lives inside it. NEVER create a new project unless explicitly asked; if there's no current project, ask which to use.`),
     both(`3. LOAD KNOWLEDGE ON DEMAND: before prompting any model or running a multi-step workflow, load the matching guide with slates_get_prompting_guide (index below). Only the guides the task needs, when it needs them.`),

package/dist/prompts/shot-spec.d.ts

@@ -91,6 +91,15 @@ export interface ShotParams {
     audioLoop?: boolean;
     audioPromptInfluence?: number;
     audioMultilingual?: boolean;
+    /**
+     * The VOICE a text-to-speech Shot speaks in — exactly one of the three, the
+     * same three `slates_generate_audio` takes. A Shot that carried the words but
+     * not the voice would fire in whatever voice happened to be on the bar, which
+     * is not the recipe that was saved.
+     */
+    voiceId?: string;
+    voiceReferenceAssetId?: string;
+    voiceDescription?: string;
 }
 /** Prompt-owned identity — the entities the prompt text NAMES. */
 export interface ShotMentions {
@@ -174,14 +183,14 @@ export interface ShotSpec {
  * same failure as a column nothing renders.
  */
 export declare const SCRIPT_FIELD_DESCRIPTION: {
-    readonly speaker: "Who says the line — a character id, a bare name (a character that does not exist yet is fine), or \"VO\". Null for a shot with no words.";
-    readonly line: "What is SAID, verbatim. Never camera, scene or prompt language — this is the half a person reads aloud.";
-    readonly delivery: "The parenthetical: how it is said. \"(flat, exhausted)\"";
-    readonly action: "What happens in the shot, screenplay-style. One line covering everyone in frame.";
-    readonly prop: "The one readable object carrying the beat.";
-    readonly shotSize: "Framing, in your own words — \"wide\", \"long-lens CU, other head blurred\". FREE TEXT: it is bucketed for the variety count and never rejected or rewritten.";
-    readonly camera: "Camera move, in your own words — \"slow push in\", \"through the rearview, eyes only\". FREE TEXT, same rule as shotSize.";
-    readonly continues: "True when this row's line runs on from the previous row's — one sentence split across two cuts. The signature VO move; set it deliberately.";
+    readonly speaker: "Speaker: character id, bare name (including a new character), or \"VO\". Null when silent.";
+    readonly line: "Words spoken verbatim; no camera or scene instructions.";
+    readonly delivery: "Optional performance note. Leave null unless a specific direction is needed; do not fill every line with stock adjectives. Not sent to TTS: put supported inline cues in the spoken text using the selected model's prompting guide.";
+    readonly action: "Screenplay action covering everyone in frame.";
+    readonly prop: "The readable object carrying the beat.";
+    readonly shotSize: "Free-text framing, e.g. \"wide\" or \"long-lens CU, other head blurred\"; bucketed only for variety counts.";
+    readonly camera: "Free-text camera move, e.g. \"slow push in\"; never rejected or rewritten.";
+    readonly continues: "True when this line continues the previous row: one sentence across two cuts.";
 };
 /** The script fields, as a list. Sorted from the description map so the two
  *  cannot disagree — never a second hand-written array. */
@@ -223,6 +232,10 @@ export declare function effectivePrompt(spec: ShotSpec): string;
  *  overlays what it actually found, so a missing field is never `undefined`
  *  leaking into a request. */
 export declare function emptyShotSpec(): ShotSpec;
+/** The mutually exclusive TTS source fields, shared by readers and patch merging. */
+export declare const VOICE_SOURCE_FIELDS: readonly ["voiceId", "voiceReferenceAssetId", "voiceDescription"];
+/** Setting a voice replaces the previous source; unrelated parameter edits preserve it. */
+export declare function mergeShotParams(existing: ShotParams, patch: Record<string, unknown>): ShotParams;
 /**
  * Read a `ShotSpec` out of whatever is on disk — a row written by an older
  * build, a partial object from an op, `null`.

package/dist/prompts/shot-spec.js

@@ -46,14 +46,14 @@ export const ORDERED_ATTACHMENT_ROLES = Object.keys(ORDERED_ROLE_EMISSION).sort(
  * same failure as a column nothing renders.
  */
 export const SCRIPT_FIELD_DESCRIPTION = {
-    speaker: 'Who says the line — a character id, a bare name (a character that does not exist yet is fine), or "VO". Null for a shot with no words.',
-    line: 'What is SAID, verbatim. Never camera, scene or prompt language — this is the half a person reads aloud.',
-    delivery: 'The parenthetical: how it is said. "(flat, exhausted)"',
-    action: 'What happens in the shot, screenplay-style. One line covering everyone in frame.',
-    prop: 'The one readable object carrying the beat.',
-    shotSize: 'Framing, in your own words — "wide", "long-lens CU, other head blurred". FREE TEXT: it is bucketed for the variety count and never rejected or rewritten.',
-    camera: 'Camera move, in your own words — "slow push in", "through the rearview, eyes only". FREE TEXT, same rule as shotSize.',
-    continues: 'True when this row\'s line runs on from the previous row\'s — one sentence split across two cuts. The signature VO move; set it deliberately.',
+    speaker: 'Speaker: character id, bare name (including a new character), or "VO". Null when silent.',
+    line: 'Words spoken verbatim; no camera or scene instructions.',
+    delivery: 'Optional performance note. Leave null unless a specific direction is needed; do not fill every line with stock adjectives. Not sent to TTS: put supported inline cues in the spoken text using the selected model\'s prompting guide.',
+    action: 'Screenplay action covering everyone in frame.',
+    prop: 'The readable object carrying the beat.',
+    shotSize: 'Free-text framing, e.g. "wide" or "long-lens CU, other head blurred"; bucketed only for variety counts.',
+    camera: 'Free-text camera move, e.g. "slow push in"; never rejected or rewritten.',
+    continues: 'True when this line continues the previous row: one sentence across two cuts.',
 };
 /** The seven free-text script fields (everything but the `continues` flag) —
  *  the set an op accepts as `string | null` and a layer renders as text. */
@@ -151,6 +151,17 @@ export function emptyShotSpec() {
 }
 const str = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
 const strArray = (v) => Array.isArray(v) ? v.filter((x) => typeof x === 'string' && x.length > 0) : [];
+/** The mutually exclusive TTS source fields, shared by readers and patch merging. */
+export const VOICE_SOURCE_FIELDS = ['voiceId', 'voiceReferenceAssetId', 'voiceDescription'];
+/** Setting a voice replaces the previous source; unrelated parameter edits preserve it. */
+export function mergeShotParams(existing, patch) {
+    const next = { ...existing };
+    if (VOICE_SOURCE_FIELDS.some((k) => typeof patch[k] === 'string' && patch[k].trim())) {
+        for (const k of VOICE_SOURCE_FIELDS)
+            delete next[k];
+    }
+    return readParams({ ...next, ...patch });
+}
 function readParams(v) {
     if (!v || typeof v !== 'object')
         return {};
@@ -175,6 +186,9 @@ function readParams(v) {
     s('audioLanguage');
     s('audioAccent');
     s('negativePrompt');
+    s('voiceId');
+    s('voiceReferenceAssetId');
+    s('voiceDescription');
     n('duration');
     n('imageQuantity');
     n('audioDurationSeconds');
@@ -276,6 +290,8 @@ export function shotAssetIds(spec) {
         ids.push(spec.firstFrameAssetId);
     if (spec.lastFrameAssetId)
         ids.push(spec.lastFrameAssetId);
+    if (spec.params.voiceReferenceAssetId)
+        ids.push(spec.params.voiceReferenceAssetId);
     return [...new Set(ids.filter(Boolean))];
 }
 /** Total attachment count — what a list row shows without composing anything. */