@slatesvideo/shared 0.6.2 → 0.6.3

package/dist/index.d.ts

@@ -4,7 +4,9 @@ export { SlatesDesktopClient, type DesktopHealth } from './clients/desktop.js';
 export { SKILLS } from './skills/content.js';
 export * as operations from './operations/index.js';
 export { ALL_OPERATIONS, VIDEO_MODELS, AUDIO_MODELS, defaultContext, type Operation, type OperationContext, type OperationResult } from './operations/index.js';
-export { MODEL_FACTS, getModelFact, multimodalRefSummary, multimodalRefModels, SEEDANCE_TASK_INTENT_WORDS, seedanceTaskIntentWords, type ModelFact, } from './prompts/model-facts.js';
+export { MODEL_FACTS, getModelFact, multimodalRefSummary, multimodalRefModels, describeRouting, SEEDANCE_TASK_INTENT_WORDS, seedanceTaskIntentWords, type ModelFact, } from './prompts/model-facts.js';
 export { MODEL_CAPABILITIES, ALL_ASPECT_RATIOS, AGENT_ROUTE_PROVIDER, getModelCapability, aspectRatiosFor, videoResolutionsFor, defaultVideoResolutionFor, durationsFor, durationValuesFor, aspectRatioUnion, videoResolutionUnion, durationBounds, checkAspectRatio, checkVideoResolution, checkDuration, describeAspectRatios, describeVideoResolutions, describeDurations, describeReferenceImageCaps, type AspectRatio, type VideoResolution, type ModelCapability, type DurationCapability, type VideoResolutionCapability, } from './prompts/model-capabilities.js';
+export { buildAgentDoctrine, type AgentSurface } from './prompts/agent-doctrine.js';
+export { BANNED_PROMPT_TOKENS, describeBannedTokens, findBannedTokens, bannedTokenWarning, type BannedToken, type BannedTokenScope, } from './prompts/banned-tokens.js';
 export { PROMPTING_TIPS, getPromptingTips, type PromptingTipsEntry, type PromptingTipCard, type PromptingTipsKey } from './prompts/prompting-tips.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -8,6 +8,9 @@ export { ALL_OPERATIONS, VIDEO_MODELS, AUDIO_MODELS, defaultContext } from './op
 // prompt derives its MODEL ROUTING doctrine from (kind: image | video | audio,
 // default/premium/niche notes). Edit model-facts.ts, never prose copies.
 export { MODEL_FACTS, getModelFact, multimodalRefSummary, multimodalRefModels, 
+// THE routing renderer — the system prompt, the MCP instructions and the
+// generate ops all call this one function, so routing prose exists once.
+describeRouting, 
 // Mirrored in slate/src/shared/pricing.ts — see the constant's own header for
 // why the mirror exists and why it must never drive a prompt rewrite.
 SEEDANCE_TASK_INTENT_WORDS, seedanceTaskIntentWords, } from './prompts/model-facts.js';
@@ -17,6 +20,29 @@ SEEDANCE_TASK_INTENT_WORDS, seedanceTaskIntentWords, } from './prompts/model-fac
 // the op surface validates against them and GENERATES its `.describe()` prose
 // from them. Never hand-type a capability fact an LLM will read.
 export { MODEL_CAPABILITIES, ALL_ASPECT_RATIOS, AGENT_ROUTE_PROVIDER, getModelCapability, aspectRatiosFor, videoResolutionsFor, defaultVideoResolutionFor, durationsFor, durationValuesFor, aspectRatioUnion, videoResolutionUnion, durationBounds, checkAspectRatio, checkVideoResolution, checkDuration, describeAspectRatios, describeVideoResolutions, describeDurations, describeReferenceImageCaps, } from './prompts/model-capabilities.js';
+// 🚨 AGENT GUIDANCE SSOT — the working method, the hard rules and the guide
+// index, as ONE string both surfaces consume: the desktop Studio Agent's whole
+// system prompt (slate/src/main/studio-agent/context.ts) and the MCP server's
+// `instructions`. Neither may author doctrine prose of its own; the guidance
+// layer drifted for exactly as long as it had no single home.
+//
+// Exported from the ROOT barrel only, never from ./prompts — that subpath is
+// bundled by the desktop RENDERER and must stay small and Node-free, and this
+// module pulls in the whole embedded SKILLS record.
+// Only what a CONSUMER calls. `buildSkillIndex`, `WORKING_METHOD` and
+// `HARD_RULES` are used inside agent-doctrine.ts and by nothing else, so they
+// stay off the public surface — an export nothing calls is an export nothing
+// keeps honest, which is why `buildModelRouting` was deleted rather than left
+// here "in case".
+export { buildAgentDoctrine } from './prompts/agent-doctrine.js';
+// Banned prompt tokens — EXTRACTED from the skills' own never-use lists and
+// inlined into the generate ops' descriptions. Enforcement of "load the guide"
+// that the model cannot skip, because a description is always in context.
+export { 
+// BANNED_PROMPT_TOKENS + describeBannedTokens: the lockstep checker and the
+// ops. findBannedTokens: the eval harness scorer. bannedTokenWarning: the ops.
+// `bannedTokensFor` is internal to the module and stays there.
+BANNED_PROMPT_TOKENS, describeBannedTokens, findBannedTokens, bannedTokenWarning, } from './prompts/banned-tokens.js';
 // Per-model prompting tips — the SSOT for the desktop "See prompting tips"
 // modals. The desktop renders these; it never hand-writes tips content.
 export { PROMPTING_TIPS, getPromptingTips } from './prompts/prompting-tips.js';

package/dist/operations/index.d.ts

@@ -29,7 +29,7 @@ export declare const getCreditBalance: Operation<Record<string, never>>;
 export declare const listAvailableModels: Operation<{
     filter?: string;
 }>;
-export 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", "seedance-2.5", "omni-flash", "minimax-h3", "minimax-h3-max"];
+export 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", "seedance-2.5", "omni-flash", "minimax-h3", "minimax-h3-max", "ltx-2-5", "ltx-2-5-pro"];
 type VideoModel = (typeof VIDEO_MODELS)[number];
 /** The exact `model` ids `slates_edit_video` accepts. Edit rows are deliberately
  *  NOT in VIDEO_MODELS — they take a source clip, not frames. */

package/dist/operations/index.js

@@ -16,7 +16,12 @@ import { BlenderBridgeClient, BLENDER_SETUP_HINT, RENDER_TIMEOUT_MS } from '../c
 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
@@ -27,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(),
@@ -80,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.
@@ -88,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 },
     };
@@ -191,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 ─────────────────
 //
@@ -231,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
@@ -1077,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.'),
@@ -1096,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)
@@ -1105,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)}. ` +
@@ -1189,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' })));
@@ -1201,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,
@@ -1276,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,
@@ -1352,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: {
@@ -1569,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
@@ -1867,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
@@ -1876,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
@@ -1940,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) {
@@ -1956,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
@@ -2002,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,
@@ -2268,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: {
@@ -2346,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}` : ''),
@@ -2375,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)
@@ -2743,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).'),
@@ -3578,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')
@@ -3630,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.",
@@ -3637,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. Blender previs (3D-blocked camera control): slates-previs-blocking (start here), slates-camera-language, slates-blocking-to-prompt, slates-dialogue-blocking, slates-restyle-from-blocking. 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);

package/dist/prompts/agent-doctrine.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Which agent surface is being briefed.
+ *
+ * `desktop` — the in-app Studio Agent. Its loop enforces plan approval in
+ * code, auto-polls generation status, and displays orchestration cost itself.
+ * `mcp` — Claude Code / Claude Desktop / Cursor / Codex over stdio. No
+ * `present_plan` tool, no auto-poll, no app chrome; the consent gate is the
+ * op-level `requires_confirm` threshold plus the host client's own per-call
+ * tool approval. The asymmetry is DELIBERATE — see slates-mcp/CLAUDE.md.
+ */
+export type AgentSurface = 'desktop' | 'mcp';
+interface SkillIndexEntry {
+    name: string;
+    description: string;
+}
+/** Parse `name:`/`description:` out of each embedded skill's frontmatter. */
+export declare function buildSkillIndex(): SkillIndexEntry[];
+export declare const WORKING_METHOD: ReadonlyArray<Record<AgentSurface, string>>;
+export declare const HARD_RULES: ReadonlyArray<Record<AgentSurface, string>>;
+/**
+ * THE doctrine string for a surface. The desktop's whole system prompt and the
+ * MCP server's `instructions` are both exactly this — neither consumer adds
+ * doctrine prose of its own.
+ *
+ * SENTINEL: the literal below must appear in this workspace in exactly ONE
+ * file — this one. scripts/agent-surface-lockstep-check.mjs assembles the same
+ * string from its parts rather than writing it out, precisely so that grepping
+ * for it stays a meaningful question. It is how "no consumer grew a private
+ * copy of the doctrine" is proved rather than assumed.
+ * SLATES-AGENT-DOCTRINE-SSOT
+ */
+export declare function buildAgentDoctrine({ surface }: {
+    surface: AgentSurface;
+}): string;
+export {};
+//# sourceMappingURL=agent-doctrine.d.ts.map