@slatesvideo/shared 0.6.1 → 0.6.3

package/dist/operations/index.js

@@ -12,10 +12,16 @@
 import { z } from 'zod';
 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';
 // 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 } from '../prompts/model-facts.js';
+import { multimodalRefSummary, multimodalRefModels, seedanceTaskIntentWords, 
+// 🚨 THE routing renderer. Routing prose is GENERATED here, never typed:
+// slates-mcp/CLAUDE.md forbids restating it in an op description, and this
+// file did it anyway for 1,282 characters that repeated MODEL_FACTS phrase
+// for phrase. Edit model-facts.ts; both surfaces follow.
+describeRouting, } from '../prompts/model-facts.js';
 // 🚨 MODEL CAPABILITY SSOT. Aspect ratios, video resolutions and durations are
 // VALIDATED against and DESCRIBED from `MODEL_CAPABILITIES` — this file must
 // never re-state one of those constraints as a literal enum or a sentence
@@ -26,6 +32,13 @@ import { multimodalRefSummary, multimodalRefModels, seedanceTaskIntentWords } fr
 // 1080p. A customer burned a round trip on `4:5` + Seedance: accepted here,
 // queued, credits reserved, rejected by the provider asynchronously.
 import { AGENT_ROUTE_PROVIDER, aspectRatioUnion, videoResolutionUnion, durationBounds, aspectRatiosFor, getModelCapability, defaultVideoResolutionFor, checkAspectRatio, checkVideoResolution, checkDuration, describeAspectRatios, describeVideoResolutions, describeDurations, describeReferenceImageCaps, } from '../prompts/model-capabilities.js';
+// 🚨 "LOAD THE GUIDE" MADE STRUCTURAL. The never-use token lists are EXTRACTED
+// from the skill files (between `@banned` markers) and inlined into the two
+// generate ops' descriptions, which are always in context on both surfaces —
+// no call to skip, no discretion. `bannedTokenWarning` then reports what the
+// submitted prompt actually contained, in the result, without blocking it.
+// Never hand-type one of these tokens here; edit the skill.
+import { describeBannedTokens, bannedTokenWarning } from '../prompts/banned-tokens.js';
 export function defaultContext() {
     return {
         cloud: () => new SlatesCloudClient(),
@@ -79,6 +92,30 @@ function creditsFromDollars(dollars) {
 // Shared describe-text for the background flag on every generate_* op.
 const BACKGROUND_DESCRIBE = 'Submit and return immediately with generationId(s) instead of blocking until the file is saved. ' +
     'Poll with slates_get_generation_status. Recommended for video (1-5 min renders).';
+// ── Vision QC pointers (the "quality-check with vision" rule, made structural) ──
+//
+// QUALITY-CHECK is a POST-condition, so it cannot be gated the way a
+// pre-condition can. What it CAN have is a result the agent cannot avoid
+// reading, naming the exact op. Deliberately NOT an auto-fetch: that would
+// spend vision tokens on every generation whether review was wanted or not,
+// and the sandbox doctrine says the tool is available, not mandatory.
+//
+// ⚠️ These three differ because what the agent already HAS differs, and telling
+// it to re-fetch something already in front of it burns a turn for nothing:
+// a blocking image generation returns the pixels inline, a video generation
+// returns none, and a background submission has no asset yet.
+const IMAGE_INLINE_REVIEW = 'The image is attached to this result — look at it against the brief before you describe it. ' +
+    'Any claim about how it LOOKS must come from pixels you actually received (slates-vision-feedback-loop).';
+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.';
+// 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
+// fall through to no pointer at all.
+const IMAGE_FETCH_POINTER = 'The pixels could not be attached to this result: call slates_get_asset_image on the asset id ' +
+    'above before describing how it looks.';
 // Early-return shape when a generation route accepted the job in background
 // mode ({ background: true } in the response). No inline-image fetch — the
 // asset doesn't exist yet; the poller delivers it on completion.
@@ -87,7 +124,8 @@ function backgroundSubmitted(kind, ids, extra, note) {
     return {
         text: `Submitted ${kind} in the background — generationId(s): ${idText}. ` +
             `Call slates_get_generation_status with waitSeconds: 45 (it long-polls and returns on completion — ` +
-            `never a rapid loop; video renders commonly take 1-5 minutes). Generations survive app restarts.` +
+            `never a rapid loop; video renders commonly take 1-5 minutes). Generations survive app restarts. ` +
+            BACKGROUND_REVIEW_POINTER +
             (note ? ` ${note}` : ''),
         data: { generationIds: ids, status: 'processing', ...extra },
     };
@@ -190,6 +228,21 @@ export const VIDEO_MODELS = [
     // the Max row at base rates and offers it 2K/4K it cannot render.
     'minimax-h3',
     'minimax-h3-max',
+    // LTX-2.5, two seats in one family (2026-08-29). Base is the VOLUME seat —
+    // cheapest native 1080p second we sell, free native audio at every tier, the
+    // only row reaching 1440p, and the longest clips in the catalogue (20s).
+    // Pro is the fidelity seat and is NOT a superset: shorter ladder (no
+    // 1440p/4K), shorter clips (6/8/10 only) and ~1/3 dearer.
+    //
+    // NEVER PREFIX-MATCH: 'ltx-2-5-pro' starts with 'ltx-2-5'. A prefix test
+    // bills Pro at base rates AND offers it 1440p/4K and 12-20s durations it
+    // cannot render — the same trap as the MiniMax pair, one row worse.
+    //
+    // Durations are DISCRETE AND EVEN (6,8,10,12,14,16,18,20); the union bounds
+    // below stay 3-30 because other rows are wider, so `assertVideoCapabilities`
+    // is what refuses an odd second. It reads `values`, not just min/max.
+    'ltx-2-5',
+    'ltx-2-5-pro',
 ];
 // ── Capability-derived param vocabulary + guard ─────────────────
 //
@@ -230,6 +283,17 @@ const VIDEO_RESOLUTION_VOCAB = VIDEO_RESOLUTIONS;
 const MINIMAX_MODELS = new Set(['minimax-h3', 'minimax-h3-max']);
 /** Reference images fal does not charge for. */
 const MINIMAX_FREE_REF_IMAGES = 5;
+/**
+ * The LTX-2.5 pair. A SET, not a prefix test — `ltx-2-5-pro` starts with
+ * `ltx-2-5`, and the two rows differ on ladder, duration list AND price.
+ *
+ * Their cost key is the plainest shape in the file — `{model}-{res}-{N}s` with
+ * no suffix ever, because LTX has no paid option: native audio is included at
+ * every tier (so no `-audio` variant like Kling) and there is no reference
+ * endpoint at all (so no `-ref{K}` variant like H3). Mirrors `ltxCreditKey()`
+ * in slate/src/shared/pricing.ts.
+ */
+const LTX_MODELS = new Set(['ltx-2-5', 'ltx-2-5-pro']);
 /** K for the `-ref{K}` suffix: images past the free five, capped by the model's
  *  own declared ceiling. 0 for h3-max (no reference transport) and for anything
  *  that is not a MiniMax row. Mirrors refImageSurchargeCount() in
@@ -1076,7 +1140,17 @@ function imageCostKey(model, resolution, quality = 'medium') {
 }
 export const generateImage = {
     id: 'slates_generate_image',
-    description: 'Generate an image via Slates credits. Models: nano-banana-2 (default), nano-banana-2-lite (fast/cheap drafts, 1K only), nano-banana-pro (hero-frame/typography premium), gpt-image-2 (sharp text / character sheets / grids; quality medium|high), flux-2-max (photoreal, less censored), seedream-5-lite (cheapest flat, less censored). Which model for which job: read the slates-model-selection skill. Pass projectId to save into a Slates project (recommended — asset appears live in the desktop UI). All models except nano-banana-2 REQUIRE projectId (no headless path). REQUIRED before calling: read the slates-cost-discipline skill (and the model\'s slates-prompting-* skill). You MUST pass aspectRatio and resolution explicitly (the server returns requires_clarification when missing — defaults waste credits). Cost > $0.50 returns requires_confirm — pass confirm=true after explicit user OK. MCP/CLI generation always charges credits. No skill files installed? Call slates_get_prompting_guide with the model\'s topic (and \'slates-cost-discipline\') before first use.',
+    description: 'Generate an image via Slates credits.\n' +
+        // GENERATED from MODEL_FACTS — the hand-typed model list that stood here
+        // was a third copy of the routing doctrine, and it had already gone stale
+        // (it still described nano-banana-2-lite by a capability the param owns).
+        `${describeRouting('image')}\n` +
+        'Full table: the slates-model-selection skill. ' +
+        'Pass projectId to save into a Slates project (recommended — asset appears live in the desktop UI). All models except nano-banana-2 REQUIRE projectId (no headless path). REQUIRED before calling: read the slates-cost-discipline skill (and the model\'s slates-prompting-* skill). You MUST pass aspectRatio and resolution explicitly (the server returns requires_clarification when missing — defaults waste credits). Cost > $0.50 returns requires_confirm — pass confirm=true after explicit user OK. MCP/CLI generation always charges credits. No skill files installed? Call slates_get_prompting_guide with the model\'s topic (and \'slates-cost-discipline\') before first use. ' +
+        // GENERATED from the skill file's own never-use list -- the one piece of
+        // prompting doctrine that is ALWAYS in context, because the agent has
+        // demonstrably skipped the call that would have taught it.
+        describeBannedTokens('image'),
     input: z.object({
         prompt: z.string().min(1).max(4000),
         model: zEnum(IMAGE_MODELS).optional().describe('Image model. Default nano-banana-2. Routing doctrine: slates-model-selection skill. All except nano-banana-2 require projectId.'),
@@ -1095,6 +1169,10 @@ export const generateImage = {
         // Mirrors the cost confirm gate — defaults silently wasted credits
         // (1:1 when user wanted 16:9, 4k when 1k would have done). The LLM
         // is forced to ask the user or read the skill instead of guessing.
+        // Non-blocking prompt hygiene. Computed once, reported on every exit path
+        // that echoes a prompt -- the clarification and confirm gates are PRE-spend,
+        // which is where a rewrite is still free.
+        const promptWarning = bannedTokenWarning(input.prompt, 'image');
         if (!input.aspectRatio || !input.resolution) {
             const missing = [];
             if (!input.aspectRatio)
@@ -1104,7 +1182,9 @@ export const generateImage = {
             return ok({
                 requires_clarification: true,
                 missing,
-                message: `Missing required field(s): ${missing.join(', ')}. ` +
+                ...(promptWarning ? { prompt_warning: promptWarning } : {}),
+                message: (promptWarning ? `${promptWarning}\n\n` : '') +
+                    `Missing required field(s): ${missing.join(', ')}. ` +
                     `Read the slates-prompting-nano-banana-2 + slates-cost-discipline skills, ` +
                     // Generated from MODEL_CAPABILITIES — never retype a ratio list.
                     `or ask the user. Aspect ratio by model: ${describeAspectRatios(IMAGE_MODELS)}. ` +
@@ -1188,7 +1268,9 @@ export const generateImage = {
                     model: costKey,
                     estimated_cents: totalCents,
                     estimated_credits: totalCents,
-                    message: `Cost exceeds ${CONFIRM_CREDITS} credits. Re-call with confirm=true to proceed, or pick a smaller resolution / count.`,
+                    ...(promptWarning ? { prompt_warning: promptWarning } : {}),
+                    message: (promptWarning ? `${promptWarning}\n\n` : '') +
+                        `Cost exceeds ${CONFIRM_CREDITS} credits. Re-call with confirm=true to proceed, or pick a smaller resolution / count.`,
                 });
             }
             const previews = await previewAssets(ctx, referenceAssetIds.map((id) => ({ id, type: 'image', role: 'reference' })));
@@ -1200,7 +1282,8 @@ export const generateImage = {
                     `Review them against your prompt — every reference's role must be labeled in the prompt text. ` +
                     `If the references suggest a different composition / style than the current prompt captures, REVISE the prompt before confirming. ` +
                     `When you talk to the user about this gen, refer to each reference by its code (e.g. "${previews[0]?.ref ?? 'IMG-A?'}") — they'll see the matching badge in the Slates gallery.` +
-                    `\n\nWhen ready, re-call slates_generate_image with confirm=true and the (possibly revised) prompt.`,
+                    `\n\nWhen ready, re-call slates_generate_image with confirm=true and the (possibly revised) prompt.` +
+                    (promptWarning ? `\n\n${promptWarning}` : ''),
                 images: previews.flatMap((p) => p.images),
                 data: {
                     requires_confirm: true,
@@ -1275,15 +1358,21 @@ export const generateImage = {
             }
             const requestedCount = input.count ?? 1;
             return {
-                text: partialFailure
-                    ? `Partial result: ${assetList.length} of ${requestedCount} image(s) saved into project ${input.projectId} ` +
-                        `(error on the rest: ${result.error ?? 'unknown error'}). ` +
-                        `The saved assets are in data.assets — re-generate only the missing count, don't redo the whole batch. ` +
-                        `Prompt: "${input.prompt.slice(0, 60)}${input.prompt.length > 60 ? '...' : ''}"`
-                    : `Generated ${assetList.length} image(s) into project ${input.projectId} ` +
-                        `for ${fmtCredits(totalCents)}. ` +
-                        `Prompt: "${input.prompt.slice(0, 60)}${input.prompt.length > 60 ? '...' : ''}"` +
-                        (refEcho ? ` ${refEcho}` : ''),
+                // The pixels are ALREADY here when the disk read worked, so the
+                // review pointer says "look at what you have", not "call another op".
+                // Telling the agent to re-fetch an image already in its context would
+                // buy a wasted turn and teach the wrong habit.
+                text: `${images.length > 0 ? IMAGE_INLINE_REVIEW : IMAGE_FETCH_POINTER} ` +
+                    (promptWarning ? `${promptWarning} ` : '') +
+                    (partialFailure
+                        ? `Partial result: ${assetList.length} of ${requestedCount} image(s) saved into project ${input.projectId} ` +
+                            `(error on the rest: ${result.error ?? 'unknown error'}). ` +
+                            `The saved assets are in data.assets — re-generate only the missing count, don't redo the whole batch. ` +
+                            `Prompt: "${input.prompt.slice(0, 60)}${input.prompt.length > 60 ? '...' : ''}"`
+                        : `Generated ${assetList.length} image(s) into project ${input.projectId} ` +
+                            `for ${fmtCredits(totalCents)}. ` +
+                            `Prompt: "${input.prompt.slice(0, 60)}${input.prompt.length > 60 ? '...' : ''}"` +
+                            (refEcho ? ` ${refEcho}` : '')),
                 images,
                 data: {
                     model: imageModel,
@@ -1351,7 +1440,9 @@ export const generateImage = {
             images.push({ data: buf.toString('base64'), mimeType: mt });
         }
         return {
-            text: `Generated ${urls.length} image(s) for ${fmtCredits(totalCents)}. ` +
+            text: `${IMAGE_INLINE_REVIEW} ` +
+                (promptWarning ? `${promptWarning} ` : '') +
+                `Generated ${urls.length} image(s) for ${fmtCredits(totalCents)}. ` +
                 `Prompt: "${input.prompt.slice(0, 60)}${input.prompt.length > 60 ? '...' : ''}"`,
             images,
             data: {
@@ -1568,6 +1659,16 @@ export function videoCostKey(input) {
         const k = minimaxRefSurchargeCount(input.model, input.referenceImages);
         return `${input.model}-${res}-${input.duration}s${k > 0 ? `-ref${k}` : ''}`;
     }
+    // LTX-2.5, both seats. EXACT-ID SET, NEVER A PREFIX — `ltx-2-5-pro` starts
+    // with `ltx-2-5`, and a prefix match would quote base rates for the dearer
+    // row. No suffix dimension exists: audio is free and there are no references.
+    // The resolution default is read PER ROW (both are 1080p today, but the two
+    // ladders differ, so a shared literal would be a latent bug the day one
+    // moves). Mirrors ltxCreditKey() in slate/src/shared/pricing.ts.
+    if (LTX_MODELS.has(input.model)) {
+        const res = input.videoResolution ?? defaultVideoResolutionFor(input.model);
+        return `${input.model}-${res}-${input.duration}s`;
+    }
     if (input.model.startsWith('seedance')) {
         // Mirrors seedanceCreditKey() in slate/src/shared/pricing.ts (version × face
         // × vref × res × duration). AI-face route bills the `-face-` key (~45% over
@@ -1813,6 +1914,33 @@ function resolveVideoModel(raw) {
     }
     return null;
 }
+/**
+ * Pair each reference-audio asset id with the words spoken in it.
+ *
+ * 🚨 THE MODEL RE-TRANSCRIBES A SUPPLIED TAKE. Seedance does not consume
+ * reference audio verbatim — it re-synthesises something close to it, and a
+ * 2026-08-28 field test heard "an app called Slates" come back as "a map called
+ * Slates". The clip carries the voice, the accent and the timing; only text
+ * carries the words. This is the text, and without it every generation with a
+ * voice take has its line guessed.
+ *
+ * Positional in, KEYED out: the desktop route merges its deprecated singular
+ * `audioReferenceAssetId` onto the END of the plural list, so an index would
+ * address different clips depending on which shape the caller used. Blank
+ * entries are dropped rather than sent as empty strings — a clip with no
+ * speech has no line, which is not the same as a line that is empty.
+ */
+function spokenTextByAssetId(assetIds, spoken) {
+    if (!assetIds?.length || !spoken?.length)
+        return undefined;
+    const out = {};
+    assetIds.forEach((id, i) => {
+        const text = spoken[i]?.trim();
+        if (id && text)
+            out[id] = text;
+    });
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 // Maps a video model id to its bundled prompting skill (frontmatter `name:`),
 // so guidance text points at a skill that actually exists. Deriving the name
 // via model.split('-')[0] produced 'slates-prompting-kling' / '...-veo', which
@@ -1839,7 +1967,10 @@ function promptingSkillFor(model) {
 }
 export const generateVideo = {
     id: 'slates_generate_video',
-    description: 'Generate video via Slates credits. REQUIRED before calling: read slates-model-selection (the routing doctrine), slates-cost-discipline, and the matching per-model prompting skill (slates-prompting-seedance / slates-prompting-seedance-2-5 / slates-prompting-kling-v3 / slates-prompting-veo-3 / slates-prompting-minimax-h3) — video models prompt very differently; load them via slates_get_prompting_guide if no skill files are installed. Read slates-content-policy when the scene involves conflict, creatures, crowds, destruction, weapons, or young characters. projectId, aspectRatio, and duration are required (requires_clarification otherwise). Cost > $0.50 returns requires_confirm — pass confirm=true after explicit user OK. Image-to-video via firstFrameAssetId; first+last frames = Veo/Seedance only; ingredients via ingredientAssetIds (Kling Omni / Seedance). Asset params take UUIDs or badge codes ("IMG-A8").',
+    description: 'Generate video via Slates credits. REQUIRED before calling: read slates-model-selection (the routing doctrine), slates-cost-discipline, and the matching per-model prompting skill (slates-prompting-seedance / slates-prompting-seedance-2-5 / slates-prompting-kling-v3 / slates-prompting-veo-3 / slates-prompting-minimax-h3) — video models prompt very differently; load them via slates_get_prompting_guide if no skill files are installed. Read slates-content-policy when the scene involves conflict, creatures, crowds, destruction, weapons, or young characters. projectId, aspectRatio, and duration are required (requires_clarification otherwise). Cost > $0.50 returns requires_confirm — pass confirm=true after explicit user OK. Image-to-video via firstFrameAssetId; first+last frames = Veo/Seedance only; ingredients via ingredientAssetIds (Kling Omni / Seedance). Asset params take UUIDs or badge codes ("IMG-A8"). ' +
+        // GENERATED from the skill's own slop-token list. Always in context on both
+        // surfaces, so it survives an agent that skips slates_get_prompting_guide.
+        describeBannedTokens('video'),
     input: z.object({
         prompt: z.string().min(1).max(4000),
         // ROUTING doctrine only. Every capability number was stripped on 2026-08-16
@@ -1848,7 +1979,14 @@ export const generateVideo = {
         // "seedance-2.5 480p/720p" were both stated here AND there, and the two
         // copies disagreed — and the second of those went stale on 2026-08-24 when
         // 2.5 gained 1080p, which is exactly the failure mode generating it fixes.
-        model: z.string().describe(`One of: ${VIDEO_MODELS.join(' | ')}. Pass the BASE id — duration and videoResolution are separate params (registry cost keys like "kling-v3-standard-8s" auto-resolve). Route per the slates-model-selection skill: Kling std = general-purpose DEFAULT, Seedance 2 = premium physics/effects/hero tier, seedance-2.5 = a SECOND SEAT beside it (longer takes, far more references, audio-only refs — but no 4K, and dearer than seedance-2 at every shared resolution, so stay on seedance-2 unless length or reference count is the point), Veo = native-synced-audio niche only, never the default, omni-flash = cheap tier with audio included (t2v, single-start-frame i2v, or reference images; no last frame, no video/audio refs), minimax-h3 = the AUTHORED-AUDIO seat (dialogue, scene sound and score directed as three separate layers in one pass, plus declared reference relationships; reference images past the fifth are a PAID key dimension — pass referenceImages when quoting), minimax-h3-max = the same model post-trained by fal for SPEED, capped at 768p, and DEARER than minimax-h3 at the tier they share — a deliberate pick, never a default and never the cheap H3; it still takes firstFrameAssetId/lastFrameAssetId, but has no reference endpoint, so the reference set is minimax-h3 only. All are VIDEO-only. Each model's legal aspect ratios, durations and resolutions are in those params' own descriptions — read them there, not from memory. For per-call cost, call slates_estimate_generation_cost.`),
+        model: z.string().describe(`One of: ${VIDEO_MODELS.join(' | ')}. Pass the BASE id — duration and videoResolution are separate ` +
+            `params (registry cost keys like "kling-v3-standard-8s" auto-resolve). All are VIDEO-only.\n` +
+            // GENERATED from MODEL_FACTS. The paragraph that stood here restated it by
+            // hand and had already drifted a phrase at a time.
+            `${describeRouting('video', 'generate')}\n` +
+            `Full table: the slates-model-selection skill. Each model's legal aspect ratios, durations and ` +
+            `resolutions are in those params' own descriptions — read them there, not from memory. ` +
+            `For per-call cost, call slates_estimate_generation_cost.`),
         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.'),
         // 🚨 THESE THREE DESCRIPTIONS ARE GENERATED FROM `MODEL_CAPABILITIES`.
         // Never hand-write a ratio, resolution or duration into them again — every
@@ -1877,6 +2015,7 @@ export const generateVideo = {
         videoReferenceAssetIds: z.array(z.string()).optional().describe(`Reference VIDEOS (UUIDs or badge codes) read alongside the images and audio in the same generation — own-footage restyle, MOTION TRANSFER ("the character from image 1 performs the motion from video 1"), or dialogue conditioning. Cited in the prompt as "video 1", "video 2"… in the order given. ${multimodalRefModels().join(' / ')} only; ignored elsewhere. ${multimodalRefSummary('seedance-2')} ${multimodalRefSummary('seedance-2.5')} Billing switches to combined input+output seconds (the vref key) — pass videoReferenceSecondsEach so the quote is right. If any clip contains a human/AI character, pair with seedanceFace=true (the default Seedance route blocks people). Over the cap is REFUSED, never trimmed: a dropped clip would already have been priced in.`),
         videoReferenceSecondsEach: z.array(z.number()).optional().describe('REQUIRED with videoReferenceAssetIds, same order and length: each reference clip\'s duration in seconds (from the asset listing). Feeds the vref cost key — the bill is Σceil(each) + output seconds. The server re-derives this by probing every uploaded clip, so an understated value just gets corrected upward.'),
         audioReferenceAssetIds: z.array(z.string()).optional().describe(`Reference AUDIO clips (UUIDs or badge codes) read alongside the images and video — e.g. lip-sync a character to a line ("the character in image 1 speaks the dialogue from audio 1"). Cited as "audio 1", "audio 2"… in the order given. No billing surcharge (Seedance audio is included). ${multimodalRefSummary('seedance-2')} ${multimodalRefSummary('seedance-2.5')}`),
+        audioReferenceSpokenText: z.array(z.string()).optional().describe('STRONGLY RECOMMENDED whenever a reference clip contains SPEECH. Same order and length as audioReferenceAssetIds; use "" for a clip with no words (music, ambience, room tone). The model RE-TRANSCRIBES a supplied take rather than using it verbatim — a field test heard "an app called Slates" come back as "a map called Slates" — so the audio decides the VOICE, the ACCENT and the TIMING while only text decides the WORDS. Give the exact line here and it is quoted into the prompt beside the citation. Omit it and the words are a guess. Pairs with the plural audioReferenceAssetIds; the deprecated singular audioReferenceAssetId carries no text.'),
         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.'),
@@ -1911,11 +2050,16 @@ export const generateVideo = {
         // no asset to reference later, and a failed gen leaves the user with
         // nothing. The MCP-only headless path that exists for image gen is
         // not reasonable for video given the cost.
+        // Non-blocking prompt hygiene, computed once. Reported on the gates that
+        // fire BEFORE any spend, where a rewrite is still free.
+        const promptWarning = bannedTokenWarning(input.prompt, 'video');
         if (!input.projectId) {
             return ok({
                 requires_clarification: true,
                 missing: ['projectId'],
-                message: 'projectId is required for video generation. Use slates_list_projects to find one or slates_create_project to make a new one. Video gens cost tens to a few hundred credits per call — they need to land in a project so the user sees the progress card and the result.',
+                ...(promptWarning ? { prompt_warning: promptWarning } : {}),
+                message: (promptWarning ? `${promptWarning}\n\n` : '') +
+                    'projectId is required for video generation. Use slates_list_projects to find one or slates_create_project to make a new one. Video gens cost tens to a few hundred credits per call — they need to land in a project so the user sees the progress card and the result.',
             });
         }
         if (!input.aspectRatio || !input.duration) {
@@ -1927,7 +2071,9 @@ export const generateVideo = {
             return ok({
                 requires_clarification: true,
                 missing,
-                message: `Missing required field(s): ${missing.join(', ')}. ` +
+                ...(promptWarning ? { prompt_warning: promptWarning } : {}),
+                message: (promptWarning ? `${promptWarning}\n\n` : '') +
+                    `Missing required field(s): ${missing.join(', ')}. ` +
                     `Read the slates-cost-discipline + ${promptingSkillFor(input.model)} skills, ` +
                     // Generated from MODEL_CAPABILITIES. The prose that stood here claimed
                     // "Veo locks to 16:9", "Kling/Seedance support 1:1 16:9 9:16 4:3 3:4
@@ -1973,6 +2119,34 @@ export const generateVideo = {
                 });
             }
         }
+        // LTX-2.5's SHAPE constraint: FRAMES, NEVER REFERENCES. fal publishes
+        // text-to-video and image-to-video for `lightricks/ltx-2.5` and nothing
+        // else — there is no reference-to-video endpoint on either seat, so there
+        // is no transport for an ingredient, character, environment, style,
+        // reference-video or reference-audio input.
+        //
+        // This has to be an EXPLICIT refusal rather than a silent no-op: accepting
+        // reference ids we cannot send is the exact "no error, no warning, no
+        // images in the request" failure `seedance-2.5-edit` shipped with. Start
+        // and end FRAMES are unaffected — image-to-video carries `image_url` plus
+        // an optional `end_image_url`, which is what `features.lastFrame` records.
+        if (LTX_MODELS.has(input.model)) {
+            const refImages = (input.ingredientAssetIds?.length ?? 0) +
+                (input.characterAssetIds?.length ?? 0) +
+                (input.environmentAssetIds?.length ?? 0) +
+                (input.styleAssetIds?.length ?? 0);
+            const refMedia = (input.videoReferenceAssetIds?.length ?? 0) +
+                (input.audioReferenceAssetIds?.length ?? 0) +
+                (input.videoReferenceAssetId ? 1 : 0) +
+                (input.audioReferenceAssetId ? 1 : 0);
+            if (refImages > 0 || refMedia > 0) {
+                return ok({
+                    requires_clarification: true,
+                    missing: [],
+                    message: `${input.model} takes a prompt and up to two frames (start and/or end) — it has no reference endpoint at all, so reference images, video and audio cannot be sent. Drop them, or switch to minimax-h3, which reads ${getModelCapability('minimax-h3')?.maxIngredientImages ?? 9} images plus reference video and audio.`,
+                });
+            }
+        }
         // MiniMax H3's SHAPE constraints. Counts and caps are read from the
         // capability SSOT; only the endpoint SHAPE is stated here, because it is
         // not a number the registry models: fal publishes text-to-video,
@@ -2033,6 +2207,20 @@ export const generateVideo = {
                     message: `${input.model} takes at most ${maxTotal} reference files across all modalities (you passed ${refImages + refMedia}).`,
                 });
             }
+            // A misaligned spoken-text array would attach one clip's line to another
+            // and send the model the wrong words with nothing on screen to say so.
+            // Refuse rather than truncate: the whole point of the field is that the
+            // WORDS are exact.
+            if (input.audioReferenceSpokenText &&
+                input.audioReferenceSpokenText.length !== (input.audioReferenceAssetIds?.length ?? 0)) {
+                return ok({
+                    requires_clarification: true,
+                    missing: [],
+                    message: `audioReferenceSpokenText must be the same length as audioReferenceAssetIds ` +
+                        `(${input.audioReferenceSpokenText.length} vs ${input.audioReferenceAssetIds?.length ?? 0}) ` +
+                        `— it pairs by position. Use "" for a clip with no speech.`,
+                });
+            }
             // fal: "Audio cannot be the only reference input; provide at least one
             // reference image or video with it."
             const audioRefs = (input.audioReferenceAssetIds?.length ?? 0) + (input.audioReferenceAssetId ? 1 : 0);
@@ -2225,6 +2413,7 @@ export const generateVideo = {
                 text: `Pre-flight for ${input.duration}s ${input.model} (${costKey}): ` +
                     `${fmtCredits(totalCents)}.` +
                     refSummary +
+                    (promptWarning ? `\n\n${promptWarning}` : '') +
                     `\n\nWhen ready, re-call slates_generate_video with confirm=true and the (possibly revised) prompt.`,
                 images: refImages,
                 data: {
@@ -2269,6 +2458,13 @@ export const generateVideo = {
             audioReferenceAssetId: input.audioReferenceAssetId,
             videoReferenceAssetIds: input.videoReferenceAssetIds,
             audioReferenceAssetIds: input.audioReferenceAssetIds,
+            // The route keys this by ASSET ID, not by position, because its own
+            // singular/plural merge appends to the END of the list — an index would
+            // mean different clips depending on which shape the caller used. The op
+            // takes the friendlier positional array and re-keys it here, AFTER
+            // `rids()` has resolved badge codes, so the keys are the ids the route
+            // will resolve. A blank entry is dropped rather than sent as "".
+            audioReferenceSpokenText: spokenTextByAssetId(input.audioReferenceAssetIds, input.audioReferenceSpokenText),
             sound: input.sound,
             audioLanguage: input.audioLanguage,
             generateMusic: input.generateMusic,
@@ -2296,7 +2492,12 @@ export const generateVideo = {
             }, refEcho);
         }
         return {
-            text: `Generated ${input.duration}s ${input.model} video into project ${input.projectId} ` +
+            text: 
+            // No frames come back with a video generation, so unlike the image op
+            // this one has to name the op that fetches them.
+            `${VIDEO_REVIEW_POINTER} ` +
+                (promptWarning ? `${promptWarning} ` : '') +
+                `Generated ${input.duration}s ${input.model} video into project ${input.projectId} ` +
                 `for ${fmtCredits(totalCents)}. ` +
                 `Prompt: "${input.prompt.slice(0, 60)}${input.prompt.length > 60 ? '...' : ''}"` +
                 (refEcho ? ` ${refEcho}` : ''),
@@ -2325,7 +2526,10 @@ export const generateAudio = {
         projectId: z.string().uuid().describe('Slates project the audio asset lands in. Required — the renderer refreshes live.'),
         model: z
             .enum(AUDIO_MODELS)
-            .describe('Audio surface. seed-audio = scene/ambience/beds/dialogue (default choice), eleven-sfx = one precise effect or a seamless loop. Routing doctrine: slates-model-selection skill.'),
+            .describe(
+        // GENERATED from MODEL_FACTS — the audio lane's routing lived only in the
+        // system prompt and in a one-line paraphrase here.
+        `Audio surface.\n${describeRouting('audio')}\nFull table: the slates-model-selection skill.`),
         prompt: z
             .string()
             .min(1)
@@ -2693,7 +2897,13 @@ export const editVideo = {
         sourceVideoAssetId: z.string().describe('The VIDEO asset to edit — UUID or badge code ("VID-V3", bare "V3"); codes resolve against the project at call time. Kling: 3–15s clips; omni-flash-edit: 3–10s.'),
         prompt: z.string().min(1).max(2500).describe('The change, not the whole scene — e.g. "replace the man with @marcus", "make it a rainy night", "turn the street into a neon Tokyo alley". Mention subjects with @name; the transport compiles them to Kling\'s @ElementN notation (Kling models). For omni-flash-edit keep it simple and add "Keep everything else the same."'),
         // Clip windows and resolutions GENERATED from MODEL_CAPABILITIES.
-        model: zEnum(EDIT_VIDEO_MODELS).optional().describe(`Default kling-v3.0-omni-edit. Pro (~25¢/s vs ~19¢/s) only for hero shots where fidelity matters. omni-flash-edit (~19¢/s) for prompt-only edits — it takes NO character/style refs. seedance-2.5-edit is the ONLY engine that accepts a clip longer than 15s; it also takes NO character/style refs on this op. Source-clip length per engine: ${describeDurations(EDIT_VIDEO_MODELS)}. Output resolution: ${describeVideoResolutions(EDIT_VIDEO_MODELS)}`),
+        model: zEnum(EDIT_VIDEO_MODELS).optional().describe(
+        // Routing GENERATED from MODEL_FACTS; the paragraph that stood here was
+        // hand-written and carried per-second prices, which drift and which the
+        // agent's own REAL NUMBERS ONLY rule forbids it repeating.
+        `Default kling-v3.0-omni-edit. Neither omni-flash-edit nor seedance-2.5-edit takes character/style refs on this op.\n` +
+            `${describeRouting('video', 'edit')}\n` +
+            `Source-clip length per engine: ${describeDurations(EDIT_VIDEO_MODELS)}. Output resolution: ${describeVideoResolutions(EDIT_VIDEO_MODELS)}`),
         characterAssetIds: z.array(z.string()).max(4).optional().describe('Subject/element image assets to swap IN (UUIDs or badge codes). Each becomes a Kling element (@ElementN). KLING MODELS ONLY — rejected on omni-flash-edit.'),
         styleAssetIds: z.array(z.string()).max(4).optional().describe('Style/appearance reference images (@ImageN). Max 4 combined with characterAssetIds. KLING MODELS ONLY — rejected on omni-flash-edit.'),
         keepAudio: z.boolean().optional().describe('Preserve the original audio track (default true; Kling models only — omni-flash-edit and seedance-2.5-edit output carry their own audio).'),
@@ -3472,6 +3682,33 @@ function resolveGuideTopic(topic) {
     if (t === 'slates-character-turnaround' || t === 'character-turnaround') {
         return 'slates-character-identity';
     }
+    // ⚠️ Previs aliases sit HIGH, before the model-prefix rules below. `dialogue`
+    // already resolves to the Seed Audio guide, and `style`/`camera` words are a
+    // hair away from the style-prompting and model blocks — anchoring these here
+    // keeps a previs ask out of an audio guide.
+    if (t === 'previs' ||
+        t === 'pre-vis' ||
+        t === 'previz' ||
+        t === 'blocking' ||
+        t === 'blockout' ||
+        t === 'greybox' ||
+        t === 'grey-box' ||
+        t === 'graybox' ||
+        t === 'blender') {
+        return 'slates-previs-blocking';
+    }
+    if (t === 'camera' || t === 'camera-moves' || t === 'camera moves' || t === 'shot-list' || t === 'shot list') {
+        return 'slates-camera-language';
+    }
+    if (t === 'blocking-to-prompt' || t === 'previs-prompt' || t === 'reference-video' || t === 'video-to-video' || t === 'v2v') {
+        return 'slates-blocking-to-prompt';
+    }
+    if (t === 'dialogue-blocking' || t === 'dialogue blocking' || t === '180-rule' || t === 'eyelines' || t === 'seating') {
+        return 'slates-dialogue-blocking';
+    }
+    if (t === 'restyle' || t === 're-style' || t === 'style-swap' || t === 'style swap' || t === 'style-variants') {
+        return 'slates-restyle-from-blocking';
+    }
     if (t === 'model-selection' ||
         t === 'model selection' ||
         t === 'which-model' ||
@@ -3501,6 +3738,12 @@ function resolveGuideTopic(topic) {
         t.startsWith('h3-')) {
         return 'slates-prompting-minimax-h3';
     }
+    // LTX-2.5 — both seats share one skill. A PREFIX is right HERE (unlike every
+    // rate, key and endpoint lookup, which must be exact) precisely because both
+    // rows resolve to the same guide: `ltx-2-5-pro` matching the `ltx` prefix is
+    // the intended outcome, not a collision.
+    if (t.startsWith('ltx') || t === 'lightricks')
+        return 'slates-prompting-ltx-2-5';
     if (t.startsWith('kling-mc'))
         return 'slates-prompting-motion-transfer';
     if (t === 'edit-video' || t === 'video-edit' || t === 'edit video' || t === 'video edit')
@@ -3553,6 +3796,27 @@ function resolveGuideTopic(topic) {
     }
     return null;
 }
+/**
+ * The guide index, GENERATED from SKILLS.
+ *
+ * The list here was hand-typed and had drifted to 25 of 32 names — the prompting
+ * guides for GPT Image 2, MiniMax H3, LTX-2.5, Seedance 2.5 and Omni Flash were
+ * all missing, so an agent reading this description could not learn they exist.
+ * A hand-typed index of a generated corpus is a stale index; it is only a matter
+ * of when.
+ *
+ * Per-model guides are listed as BARE NAMES: the name is the description, and
+ * `resolveGuideTopic()` resolves a model id to the right one anyway.
+ */
+function describeGuideTopics() {
+    const names = Object.keys(SKILLS).sort();
+    const perModel = names.filter((n) => n.startsWith('slates-prompting-'));
+    const rest = names.filter((n) => !n.startsWith('slates-prompting-'));
+    return (`Workflow and cross-cutting guides: ${rest.join(', ')}. ` +
+        `Per-model prompting guides (or just pass the model id, which resolves to one of these): ` +
+        `${perModel.join(', ')}. ` +
+        `Style names (photoreal, anime, painterly, 3d-render) resolve to slates-style-prompting.`);
+}
 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', '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.",
@@ -3560,7 +3824,7 @@ export const getPromptingGuide = {
         topic: z
             .string()
             .min(1)
-            .describe('Guide name, model id, or style name. Guides: slates-model-selection (which model for which job — read before choosing any model), slates-cost-discipline, slates-content-policy, slates-style-prompting, slates-prompting-nano-banana-2, slates-prompting-veo-3, slates-prompting-kling-v3, slates-prompting-seedance, slates-prompting-seed-audio, slates-prompting-elevenlabs, slates-prompting-lip-sync, slates-prompting-motion-transfer, slates-prompting-flux-2-max, slates-prompting-seedream-5-lite, slates-edit-and-iterate, slates-vision-feedback-loop, slates-character-identity, slates-storyboard-from-script, slates-direct-response-ad, slates-one-prompt-film. Style names (photoreal, anime, painterly, 3d-render) resolve to slates-style-prompting.'),
+            .describe(`Guide name, model id, or style name. ${describeGuideTopics()}`),
     }),
     async run(input) {
         const resolved = resolveGuideTopic(input.topic);
@@ -3574,6 +3838,159 @@ export const getPromptingGuide = {
         };
     },
 };
+// ── Blender previs ──────────────────────────────────────────────
+//
+// The only ops that talk to a third transport: a localhost socket into a
+// running Blender carrying the Slates add-on. They exist to produce ONE
+// artifact — a grey-box blocking clip whose asset id goes straight into
+// `slates_generate_video`'s `videoReferenceAssetIds`, so the model renders a
+// world around a camera path instead of inventing one.
+//
+// 🚨 There is deliberately no camera-move library here. Camera work is written
+// as `bpy` by the agent through `slates_blender_execute`, against the Blender
+// API reference the add-on ships. A fixed menu of moves would cap the workflow
+// at whatever we thought of; code execution plus real docs does not.
+// The setup sentence and the download URL live in `clients/blender.ts`, beside
+// the port range they belong to — one home, so a moved page is one edit.
+const BLENDER_UNAVAILABLE_HINT = `Blender previs needs the Slates Blender add-on running. ${BLENDER_SETUP_HINT}`;
+export const blenderStatus = {
+    id: 'slates_blender_status',
+    description: 'Check whether a Blender running the Slates add-on is reachable, and if so return its scene summary (timing, camera, collection tree). Call this FIRST in any previs workflow — every other Blender op fails with the same setup message when the bridge is down, and knowing the frame range and fps up front is what keeps the blocking and the prompt timings in agreement.',
+    input: z.object({}),
+    async run() {
+        const client = new BlenderBridgeClient();
+        if (!(await client.isReachable())) {
+            return ok({ connected: false, hint: BLENDER_UNAVAILABLE_HINT });
+        }
+        return ok({ connected: true, scene: await client.call('result = _mod("scene").summary()') });
+    },
+};
+export const blenderExecute = {
+    id: 'slates_blender_execute',
+    description: 'Run Python (`bpy`) inside the connected Blender and return whatever the code assigns to a dict named `result`. This is how blocking gets built: primitives, empties, constraints, camera rigs, keyframes, markers. Anything Blender can do, this can do. Assign a dict to `result` to get data back (e.g. `result = {"camera": cam.name}`); print() output comes back separately as stdout. On an exception you get the full traceback — read it, fix the code, retry. Before writing an unfamiliar call, look up its real signature with slates_blender_docs rather than guessing: the add-on ships the Blender 5.1 API reference precisely so you do not have to recall it.',
+    input: z.object({
+        code: z
+            .string()
+            .min(1)
+            .describe('Python source. Assign a JSON-serialisable dict to `result` to return data.'),
+        timeoutSeconds: z
+            .number()
+            .int()
+            .min(5)
+            .max(900)
+            .optional()
+            .describe('How long to wait for Blender (default 60). Raise it for heavy geometry.'),
+    }),
+    async run(input) {
+        const client = new BlenderBridgeClient();
+        const { result, stdout, stderr } = await client.execute(input.code, {
+            timeoutMs: input.timeoutSeconds ? input.timeoutSeconds * 1000 : undefined,
+        });
+        return ok({ result, ...(stdout ? { stdout } : {}), ...(stderr ? { stderr } : {}) });
+    },
+};
+export const blenderScene = {
+    id: 'slates_blender_scene',
+    description: 'Scene summary from the connected Blender: frame range, fps, duration, render resolution, the active camera with its keyframe times in both frames and seconds, and the full collection/object tree with transforms and constraints. Cheap — call it freely between edits. The camera keyframe times ARE the cut structure, so read them before writing any shot-by-shot prompt.',
+    input: z.object({}),
+    async run() {
+        return ok(await new BlenderBridgeClient().call('result = _mod("scene").summary()'));
+    },
+};
+export const blenderDocs = {
+    id: 'slates_blender_docs',
+    description: 'Look up a dotted Blender Python API identifier in the bundled 5.1 reference — e.g. "bpy.ops.object", "bpy.types.Camera", "bpy.types.FollowPathConstraint". Pass "*" for top-level modules or "bpy.ops.*" to list a namespace. Use this instead of recalling a signature from memory: invented operator names and wrong enum values are the most common way previs code fails, and they fail silently often enough to be worth the lookup.',
+    input: z.object({
+        identifier: z.string().min(1).describe('Dotted identifier, or a namespace wildcard like "bpy.ops.*".'),
+    }),
+    async run(input) {
+        const code = `result = _mod("docs").lookup(${JSON.stringify(input.identifier)})`;
+        return ok(await new BlenderBridgeClient().call(code));
+    },
+};
+export const blenderSearchDocs = {
+    id: 'slates_blender_search_docs',
+    description: 'Full-text search of the bundled Blender documentation for when you do not know the identifier yet. scope "api" searches the Python reference; "manual" searches the user manual for concepts and workflow ("how does Follow Path work", "bezier interpolation handles"). Use slates_blender_docs when you know the name and this when you do not.',
+    input: z.object({
+        query: z.string().min(2),
+        scope: z.enum(['api', 'manual']).optional().describe('Default "api".'),
+        maxResults: z.number().int().min(1).max(20).optional().describe('Default 8.'),
+    }),
+    async run(input) {
+        const args = [
+            JSON.stringify(input.query),
+            JSON.stringify(input.scope ?? 'api'),
+            String(input.maxResults ?? 8),
+        ].join(', ');
+        return ok(await new BlenderBridgeClient().call(`result = _mod("docs").search(${args})`));
+    },
+};
+export const blenderRenderBlocking = {
+    id: 'slates_blender_render_blocking',
+    description: "Render the connected Blender scene camera to a grey-box mp4 — the blocking clip that locks camera motion for generation — and, when projectId is given, import it into that Slates project as a video asset in the same call. The returned asset id goes into slates_generate_video's videoReferenceAssetIds and the returned durationSeconds into videoReferenceSecondsEach. Renders through the SCENE camera using scene render settings, never the user's viewport, so output does not depend on where they left their mouse. Untextured is correct: the clip supplies camera path and timing, the references supply the look. Colour in the blocking is NOTATION, not look — a distinct viewport colour per character is what binds a proxy to its reference image across cuts, and a marked face encodes which way a featureless proxy is facing. State every such mapping in the generation prompt AND state that the colours themselves are not inherited, or the model renders a literally red person. See the slates-previs-blocking and slates-blocking-to-prompt skills. Keep it at or under 30s — seedance-2.5 accepts reference videos up to 30s, the other reference-video models up to 15s.",
+    input: z.object({
+        projectId: z
+            .string()
+            .uuid()
+            .optional()
+            .describe('Import the clip into this project and return its asset. Omit to just get a file path.'),
+        resolutionX: z.number().int().min(256).max(4096).optional().describe('Default 1920.'),
+        resolutionY: z.number().int().min(256).max(4096).optional().describe('Default 1080.'),
+        fps: z.number().int().min(1).max(120).optional().describe('Default 24. Match what the shot list assumes.'),
+        frameStart: z.number().int().optional().describe("Default: the scene's own frame_start."),
+        frameEnd: z.number().int().optional().describe("Default: the scene's own frame_end."),
+        basename: z.string().min(1).max(64).optional().describe('Filename stem. Default "blocking".'),
+    }),
+    async run(input, ctx) {
+        const kwargs = [];
+        if (input.resolutionX !== undefined)
+            kwargs.push(`resolution_x=${input.resolutionX}`);
+        if (input.resolutionY !== undefined)
+            kwargs.push(`resolution_y=${input.resolutionY}`);
+        if (input.fps !== undefined)
+            kwargs.push(`fps=${input.fps}`);
+        if (input.frameStart !== undefined)
+            kwargs.push(`frame_start=${input.frameStart}`);
+        if (input.frameEnd !== undefined)
+            kwargs.push(`frame_end=${input.frameEnd}`);
+        if (input.basename !== undefined)
+            kwargs.push(`basename=${JSON.stringify(input.basename)}`);
+        // 🚨 THE RENDER IS DEFERRED, AND THAT IS WHY THIS IS NOT ONE LINE.
+        // In an interactive Blender `render_blocking` INVOKES the render rather
+        // than executing it — a synchronous animation render driven from the
+        // bridge's own `bpy.app.timers` callback would re-enter the main loop
+        // running it. So it hands back a `check_is_finished` callable instead of
+        // the clip, and assigning that to `check_is_finished` is the bridge's
+        // documented convention for "hold the socket open and answer when the job
+        // lands" (see the add-on's `bridge/deferred.py`). The deferred path wraps
+        // the eventual dict in the SAME `{status, result}` envelope, so everything
+        // downstream of this call is identical either way. Headless Blender has no
+        // job system to poll, renders synchronously, and takes the `else`.
+        const render = (await new BlenderBridgeClient().call(`_previs_result = _mod("previs").render_blocking(${kwargs.join(', ')})\n` +
+            'if callable(_previs_result):\n' +
+            '    check_is_finished = _previs_result\n' +
+            'else:\n' +
+            '    result = _previs_result\n', { timeoutMs: RENDER_TIMEOUT_MS }));
+        if (!input.projectId) {
+            return ok({
+                ...render,
+                next: 'Pass projectId to import this into a Slates project, or call slates_upload_reference_image with type "video".',
+            });
+        }
+        // The same desktop route slates_upload_reference_image uses — the file is
+        // probed on ingest, so duration and dimensions are known immediately.
+        const uploaded = await ctx.desktop().post('/agent/assets/upload', {
+            projectId: input.projectId,
+            filePath: render.filePath,
+            type: 'video',
+        });
+        return ok({
+            ...render,
+            asset: uploaded.asset ?? uploaded,
+            next: "Pass the asset's id in slates_generate_video videoReferenceAssetIds, with videoReferenceSecondsEach set to durationSeconds.",
+        });
+    },
+};
 // ── Aggregation ─────────────────────────────────────────────────
 export const ALL_OPERATIONS = [
     getWorkspaceState,
@@ -3652,5 +4069,18 @@ export const ALL_OPERATIONS = [
     batchUpdateFrames,
     deleteFrame,
     getPromptingGuide,
+    // ── Blender previs, LAST and deliberately ────────────────────────────
+    // This order is not cosmetic: `slate/src/main/studio-agent/ops.ts` maps this
+    // array straight into the Anthropic `tools` array, and that block sits inside
+    // the desktop Studio Agent's PROMPT-CACHED PREFIX. These six landed at the
+    // TOP, which put a third transport nobody without Blender can reach ahead of
+    // `slates_get_workspace_state` in every conversation the app has. They are a
+    // niche lane off the end of the surface, and the list should read that way.
+    blenderStatus,
+    blenderExecute,
+    blenderScene,
+    blenderDocs,
+    blenderSearchDocs,
+    blenderRenderBlocking,
 ];
 //# sourceMappingURL=index.js.map