@slatesvideo/shared 0.5.9 → 0.6.0

package/dist/operations/index.js

@@ -16,6 +16,16 @@ 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';
+// 🚨 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
+// again. It did until 2026-08-16, and every axis had drifted: an invented
+// `9:21`, "Kling/Seedance support all" (Seedance takes 6 of 11 and has no
+// `4:5`), "Veo locks to 16:9" (two on fal), "Kling: 5-15" (min is 3), a
+// `videoResolution` line that never mentioned Kling, and 4s quoted for Veo at
+// 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';
 export function defaultContext() {
     return {
         cloud: () => new SlatesCloudClient(),
@@ -23,6 +33,18 @@ export function defaultContext() {
     };
 }
 // ── Helpers ─────────────────────────────────────────────────────
+/**
+ * `z.enum` over a GENERATED list. Zod's signature wants a non-empty tuple
+ * literal, which is exactly what you can't write when the values come from the
+ * capability SSOT — and writing them out is how the enums drifted in the first
+ * place. Callers must pass a non-empty array; every call site derives from
+ * `MODEL_CAPABILITIES`, which never yields an empty union for a real model set.
+ */
+function zEnum(values) {
+    if (values.length === 0)
+        throw new Error('zEnum: empty value list');
+    return z.enum(values);
+}
 function ok(data, text) {
     return {
         // Compact JSON — pretty-printing (indent 2) cost ~10-15% extra tokens
@@ -133,19 +155,146 @@ export const listAvailableModels = {
         };
     },
 };
+// ── Video model vocabulary ──────────────────────────────────────
+//
+// Declared HERE, above every op, because both `slates_estimate_generation_cost`
+// and `slates_generate_video` build their Zod schemas from it at module load —
+// and a schema is evaluated in source order, so a list declared below the first
+// op that reads it is a temporal-dead-zone crash, not a lint nit.
+// Exported: the exact `model` ids slates_generate_video accepts — consumed
+// by the desktop Studio Agent system prompt (SSOT; never restate these ids
+// in prose that can drift).
+export const VIDEO_MODELS = [
+    '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 is a SECOND SEAT, not a replacement: 30s takes, 30 image
+    // references, audio-only references, up to 1080p (2026-08-24) — but no 4K,
+    // and dearer than 2.0 at every shared tier, so 2.0 stays the default. Its
+    // EDIT row is not here; edit models live on slates_edit_video, same as the
+    // Kling and Omni Flash ones.
+    'seedance-2.5',
+    'omni-flash',
+    // MiniMax H3, two seats in one family (2026-08-27). Base H3 is the AUTHORED-
+    // AUDIO seat — three directable sound layers in one pass, declared reference
+    // relationships, 480p to 4K, and the cheapest 768-class second we sell.
+    // H3 Max is fal's self-hosted post-train: faster, capped at 768p, takes NO
+    // references, and costs MORE than base H3 at the tier they share — a
+    // premium-speed seat, never a cheap H3.
+    //
+    // NEVER PREFIX-MATCH: 'minimax-h3-max' starts with 'minimax-h3'. Every
+    // branch keyed on these ids matches EXACTLY; a prefix test silently bills
+    // the Max row at base rates and offers it 2K/4K it cannot render.
+    'minimax-h3',
+    'minimax-h3-max',
+];
+// ── Capability-derived param vocabulary + guard ─────────────────
+//
+// 🚨 EVERYTHING BELOW IS GENERATED FROM `MODEL_CAPABILITIES`. Not one aspect
+// ratio, resolution or duration is typed into this file any more, and none may
+// be again. The enums are the UNION of what the video models accept (so the
+// JSON schema still advertises the legal universe to the LLM) and
+// `assertVideoCapabilities` does the PER-MODEL narrowing.
+/** Union of the ratios every video model accepts on the agent's route. */
+const VIDEO_ASPECT_RATIOS = aspectRatioUnion(VIDEO_MODELS, AGENT_ROUTE_PROVIDER);
+/** Union of the resolutions every video model renders at. */
+const VIDEO_RESOLUTIONS = videoResolutionUnion(VIDEO_MODELS);
+/** Widest legal duration window across every video model. */
+const VIDEO_DURATION_BOUNDS = durationBounds(VIDEO_MODELS);
+/** Omni Flash's combined reference-image cap, read from the SSOT (7). */
+const omniFlashRefCap = getModelCapability('omni-flash')?.maxIngredientImages ?? 0;
+/** Every resolution token any video model speaks, for the forgiving cost-key
+ *  parser. Derived, so 768p and 2k arrived with the models rather than with a
+ *  later bug report. */
+const VIDEO_RESOLUTION_VOCAB = VIDEO_RESOLUTIONS;
+// ── MiniMax H3: the reference-image surcharge, as a KEY DIMENSION ────────────
+//
+// fal charges $0.080 per reference image PAST THE FIRST FIVE on
+// `minimax/h3/reference-to-video`, and nowhere else — not on image-to-video
+// start/end frames (those are FL2VA inputs, not Ref2VA references), and not on
+// h3-max, which has no reference endpoint at all. Left unmodelled it inverts
+// the margin: a 10s 768p clip earns $0.30 and four extra images cost $0.32.
+//
+// `/proxy/generate` resolves ONE key to ONE integer, so a surcharge has to live
+// IN the key — exactly the shape Kling's `-audio` suffix uses. The bare key
+// stays identical to every other model's; the suffix appears only when the
+// option costs money.
+//
+// The rounding is EXACT and worth knowing before anyone changes the rate:
+// $0.080 x 1.5 x 100 = 12 cents, and 12 is divisible by CENTS_PER_CREDIT (3),
+// so every extra image is 4 credits at every resolution and every duration with
+// zero drift. A rate that is not a multiple of 2 cents breaks that property.
+const MINIMAX_MODELS = new Set(['minimax-h3', 'minimax-h3-max']);
+/** Reference images fal does not charge for. */
+const MINIMAX_FREE_REF_IMAGES = 5;
+/** 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
+ *  slate/src/shared/pricing.ts. */
+/** Reference IMAGES a generate_video call carries — the four free-reference
+ *  arrays, combined, exactly as the desktop composer counts them. */
+function minimaxRefImageCount(input) {
+    return ((input.ingredientAssetIds?.length ?? 0) +
+        (input.characterAssetIds?.length ?? 0) +
+        (input.environmentAssetIds?.length ?? 0) +
+        (input.styleAssetIds?.length ?? 0));
+}
+function minimaxRefSurchargeCount(model, referenceImages) {
+    if (!MINIMAX_MODELS.has(model))
+        return 0;
+    const cap = getModelCapability(model)?.maxIngredientImages ?? 0;
+    const n = Math.floor(referenceImages ?? 0);
+    if (!Number.isFinite(n) || n <= 0)
+        return 0;
+    return Math.max(0, Math.min(n, cap) - MINIMAX_FREE_REF_IMAGES);
+}
+/** The exact `model` ids `slates_edit_video` accepts. Edit rows are deliberately
+ *  NOT in VIDEO_MODELS — they take a source clip, not frames. */
+export const EDIT_VIDEO_MODELS = [
+    'kling-v3.0-omni-edit',
+    'kling-v3.0-omni-pro-edit',
+    'omni-flash-edit',
+    'seedance-2.5-edit',
+];
+/**
+ * Source-clip length an edit engine accepts, read from the SSOT.
+ *
+ * On an edit row the output length FOLLOWS the source clip, so the model's
+ * declared duration window is exactly the legal clip window — Kling 3-15s,
+ * Omni Flash 3-10s, Seedance 2.5 4-30s. These three pairs used to be typed
+ * inline as `isSeedanceEdit ? 4 : 3` / `isSeedanceEdit ? 30 : isOmniFlashEdit ?
+ * 10 : 15`, i.e. a fourth copy of registry data keyed on model-id comparisons.
+ */
+function editClipBounds(model) {
+    const d = getModelCapability(model)?.duration;
+    if (!d)
+        throw new Error(`editClipBounds: no duration capability for "${model}"`);
+    return { min: d.min, max: d.max };
+}
+/** Resolutions any edit engine exposes as a PARAM. Only Seedance's edit price
+ *  moves with resolution; the Kling and Omni Flash rows are fixed to the source. */
+const EDIT_VIDEO_RESOLUTIONS = videoResolutionUnion(['seedance-2.5-edit']);
 export const estimateGenerationCost = {
     id: 'slates_estimate_generation_cost',
     description: 'Pre-flight cost estimate. Call before any generate_* op so the user sees "this will cost N credits" up front. Takes the SAME base model ids as the generate ops (video: "seedance-2" + duration + videoResolution; image: "nano-banana-2" + resolution) — exact registry cost keys also work. Pairs with the confirm gate.',
     input: z.object({
         model: z.string().describe('Base model id as passed to the generate op (e.g. "seedance-2", "kling-v3.0-std", "nano-banana-2") or an exact registry cost key ("nano-banana-2-2k", "seedance-2-1080p-8s")'),
         quantity: z.number().int().min(1).max(10).optional().describe('Number of generations (default 1)'),
-        duration: z.number().int().min(1).max(360).optional().describe('Seconds. Video 3-15 (cost scales linearly; required with a video base id). Audio: seed-audio 3-120 (⚠️ the requested duration IS the bill), eleven-sfx 1-22 — required with either audio base id.'),
-        videoResolution: z.enum(['480p', '720p', '1080p', '4k']).optional().describe('Video only. Seedance defaults to 1080p.'),
+        // Video windows and resolutions GENERATED from MODEL_CAPABILITIES. The
+        // hand-typed "Video 3-15" here was wrong the day seedance-2.5 (4-30s)
+        // shipped, and "Seedance defaults to 1080p" was wrong for 2.5, which has no
+        // 1080p at all.
+        duration: z.number().int().min(1).max(360).optional().describe(`Seconds; cost scales linearly. Required with a video or audio base id. Video per model: ${describeDurations(VIDEO_MODELS)}. Audio: seed-audio 3-120 (⚠️ the requested duration IS the bill), eleven-sfx 1-22.`),
+        videoResolution: zEnum(VIDEO_RESOLUTIONS).optional().describe(`Video only. Omitted, each model quotes at its own default. Per model: ${describeVideoResolutions(VIDEO_MODELS)}`),
         resolution: z.enum(['1k', '2k', '3k', '4k']).optional().describe('Image only (default 2k; 3k = gpt-image-2 1440p class).'),
         quality: z.enum(['medium', 'high']).optional().describe('gpt-image-2 only — quality tier (default medium).'),
         sound: z.boolean().optional().describe('Veo only — audio flag changes the cost key.'),
         seedanceFace: z.boolean().optional().describe('Seedance AI-face route (pricier key).'),
         seedanceRealFace: z.boolean().optional().describe('Seedance consented real-face route (premium key).'),
+        referenceImages: z.number().int().min(0).optional().describe(`minimax-h3 only — how many reference IMAGES the generation will carry. The first ${MINIMAX_FREE_REF_IMAGES} are free and each one after that is a paid dimension of the cost key, so a quote that omits this UNDER-REPORTS a reference-heavy job. Ignored by every other model (minimax-h3-max takes no references at all).`),
     }),
     async run(input, ctx) {
         const registry = await ctx.cloud().get('/api/agent/models');
@@ -218,20 +367,31 @@ export const estimateGenerationCost = {
                         message: `"${resolved.model}" cost scales with duration — pass duration (seconds) to estimate.`,
                     });
                 }
+                // Refuse an out-of-range combination rather than quoting a key that does
+                // not exist — the generate op gates the same way, from the same data, so
+                // a quote can never promise something generation then refuses.
+                const capErr = assertVideoCapabilities({
+                    model: resolved.model,
+                    videoResolution: input.videoResolution ?? resolved.videoResolution,
+                    duration,
+                });
+                if (capErr)
+                    return ok(capErr);
                 key = videoCostKey({
                     model: resolved.model,
                     duration,
                     videoResolution: input.videoResolution ??
                         resolved.videoResolution ??
                         // Seedance quotes are resolution-scaled, so a missing resolution has
-                        // to fall back to the model's OWN default — 2.5 has no 1080p at all,
-                        // and a blanket '1080p' here quoted a key that does not exist.
-                        (resolved.model === 'seedance-2.5' ? '720p'
-                            : resolved.model.startsWith('seedance') ? '1080p'
-                                : undefined),
+                        // to fall back to the model's OWN default — the ladders differ per
+                        // row (2.5 has no 4K) and a blanket literal quotes a key that does
+                        // not exist. Read from the SSOT; this used to be a hand-typed
+                        // model-id ternary.
+                        defaultVideoResolutionFor(resolved.model),
                     sound: input.sound ?? resolved.sound,
                     seedanceFace: input.seedanceFace ?? resolved.seedanceFace,
                     seedanceRealFace: input.seedanceRealFace,
+                    referenceImages: input.referenceImages ?? resolved.referenceImages,
                 });
             }
         }
@@ -872,6 +1032,30 @@ async function previewAssets(ctx, refs) {
     }
     return out;
 }
+/** The exact `model` ids `slates_generate_image` accepts. */
+export const IMAGE_MODELS = [
+    'nano-banana-2',
+    'nano-banana-2-lite',
+    'nano-banana-pro',
+    'gpt-image-2',
+    'flux-2-max',
+    'seedream-5-lite',
+];
+/**
+ * The aspect ratios an image generation can carry — the UNION over what these
+ * models declare in `MODEL_CAPABILITIES`, generated so the enum cannot hold a
+ * value no model accepts. It used to be a hand-typed eleven-value list whose
+ * `9:21` exists in ZERO models; that phantom is gone by construction.
+ *
+ * ⚠️ STILL A UNION, NOT A PER-MODEL CHECK. `gpt-image-2` takes five of these
+ * ten and the other five would be accepted here. The image param surface has
+ * not been audited (aspect ratios, resolution classes, per-model reference
+ * caps) — that audit is the named follow-up in
+ * `slate/docs/plan-docs/2026-08-16-MODEL-CAPABILITY-SSOT.md` §5. The machinery
+ * to close it already exists: call `checkAspectRatio(model, ratio)` the way
+ * `assertVideoCapabilities` does below.
+ */
+const IMAGE_ASPECT_RATIOS = aspectRatioUnion(IMAGE_MODELS);
 // Registry cost-key for an image model+resolution. Mirrors imageCreditKey()
 // in slate/src/shared/pricing.ts — MUST byte-match it (the same hard rule as
 // videoCostKey): NB2/NB Pro price per resolution, FLUX.2 Max prices per
@@ -895,11 +1079,11 @@ export const generateImage = {
     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.',
     input: z.object({
         prompt: z.string().min(1).max(4000),
-        model: z.enum(['nano-banana-2', 'nano-banana-2-lite', 'nano-banana-pro', 'gpt-image-2', 'flux-2-max', 'seedream-5-lite']).optional().describe('Image model. Default nano-banana-2. Routing doctrine: slates-model-selection skill. All except nano-banana-2 require projectId.'),
+        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.'),
         projectId: z.string().uuid().optional().describe('Save into this Slates project. Renderer refreshes live. Required for every model except nano-banana-2.'),
         resolution: z.enum(['1k', '2k', '3k', '4k']).optional().describe('Pick deliberately: 1k drafts, 2k hero shots, 4k print/final. nano-banana-2-lite is 1k-only. gpt-image-2 classes: 1k=1024², 2k=1080p, 3k=1440p, 4k=2160p (3k is gpt-image-2 only). Never default this.'),
         quality: z.enum(['medium', 'high']).optional().describe('gpt-image-2 only. medium (default) = sharp text, fast, the value seat; high = max text precision + reasoning at ~4× the price. Ignored by other models.'),
-        aspectRatio: z.enum(['1:1', '16:9', '9:16', '4:3', '3:4', '21:9', '9:21', '4:5', '5:4', '2:3', '3:2']).optional().describe('Pick deliberately from the use case. Cinematic → 16:9. TikTok/Reels/Story → 9:16. IG square → 1:1. Ultra-wide → 21:9. Ask the user when ambiguous.'),
+        aspectRatio: zEnum(IMAGE_ASPECT_RATIOS).optional().describe(`Pick deliberately from the use case. Cinematic → 16:9. TikTok/Reels/Story → 9:16. IG square → 1:1. Ultra-wide → 21:9. Ask the user when ambiguous. Per model: ${describeAspectRatios(IMAGE_MODELS)}`),
         count: z.number().int().min(1).max(4).optional(),
         referenceImageUrls: z.array(z.string().url()).max(14).optional().describe('Headless (no-projectId) nano-banana-2 only: up to 14 ref URLs. For projectId runs, upload refs with slates_upload_reference_image first. Always label each image\'s role in the prompt text.'),
         referenceAssetIds: z.array(z.string()).max(14).optional().describe("Project assets to use as reference/ingredient images — asset UUIDs or badge codes (\"IMG-A8\"); codes resolve against the project at call time. Requires projectId. For nano-banana-2 up to 14 refs; FLUX/Seedream route to their edit endpoints with lower per-model caps. Label each reference's role in the prompt text."),
@@ -922,7 +1106,8 @@ export const generateImage = {
                 missing,
                 message: `Missing required field(s): ${missing.join(', ')}. ` +
                     `Read the slates-prompting-nano-banana-2 + slates-cost-discipline skills, ` +
-                    `or ask the user. Aspect ratio options: 1:1 16:9 9:16 4:3 3:4 21:9 9:21 4:5 5:4 2:3 3:2. ` +
+                    // Generated from MODEL_CAPABILITIES — never retype a ratio list.
+                    `or ask the user. Aspect ratio by model: ${describeAspectRatios(IMAGE_MODELS)}. ` +
                     `Resolution options: 1k 2k 4k (same price band — pick by need, not cost).`,
             });
         }
@@ -1310,23 +1495,52 @@ export const editImage = {
     },
 };
 // ── Generate video ──────────────────────────────────────────────
-// Exported: the exact `model` ids slates_generate_video accepts — consumed
-// by the desktop Studio Agent system prompt (SSOT; never restate these ids
-// in prose that can drift).
-export const VIDEO_MODELS = [
-    '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 is a SECOND SEAT, not a replacement: 30s takes, 30 image
-    // references, audio-only references — and 480p/720p ONLY. 2.0 keeps the
-    // ladder to native 4K and stays the default. Its EDIT row is not here; edit
-    // models live on slates_edit_video, same as the Kling and Omni Flash ones.
-    'seedance-2.5',
-    'omni-flash',
-];
+//
+// VIDEO_MODELS and the capability-derived param vocabulary are declared near the
+// top of this file: `slates_estimate_generation_cost`'s schema is evaluated at
+// module load and reads them, so they have to initialise before it.
+/**
+ * Reject an illegal aspectRatio / videoResolution / duration BEFORE submit,
+ * naming the legal set. Returns a `requires_clarification` payload or null.
+ *
+ * ⚠️ WHY THIS IS A RUN()-TIME GUARD AND NOT A SCHEMA `superRefine`. The op
+ * accepts registry COST-KEY spellings as `model` ("seedance-2-1080p-8s") and
+ * `resolveVideoModel()` unpacks them into base id + duration + resolution at
+ * the top of `run()`. A schema-level refinement runs BEFORE that, so it would
+ * see an unnormalised model id and a `duration` that is still undefined — it
+ * would reject legal calls and wave illegal ones through. The check has to sit
+ * after normalisation, which is here. It also lets the failure arrive as the
+ * same teaching `requires_clarification` shape as every other gate in this op,
+ * rather than a raw Zod error the agent has to guess its way out of.
+ *
+ * `promptMode` matters: Veo's reference-to-video endpoint is 8s only, declared
+ * as `duration.modeOverrides.ingredients`. Free reference images with no
+ * first/last frame IS ingredients mode — the same condition
+ * `buildFalVeoRequest` uses to pick the ref2v endpoint.
+ */
+function assertVideoCapabilities(input) {
+    const freeRefs = (input.ingredientAssetIds?.length ?? 0) +
+        (input.characterAssetIds?.length ?? 0) +
+        (input.environmentAssetIds?.length ?? 0) +
+        (input.styleAssetIds?.length ?? 0);
+    const promptMode = freeRefs > 0 && !input.firstFrameAssetId && !input.lastFrameAssetId ? 'ingredients' : undefined;
+    const ratioErr = checkAspectRatio(input.model, input.aspectRatio, AGENT_ROUTE_PROVIDER);
+    if (ratioErr)
+        return { requires_clarification: true, missing: ['aspectRatio'], message: ratioErr };
+    const resErr = checkVideoResolution(input.model, input.videoResolution);
+    if (resErr)
+        return { requires_clarification: true, missing: ['videoResolution'], message: resErr };
+    // Duration LAST: its legal window depends on the resolution, so a bad
+    // resolution must be reported first or the duration message names a window
+    // derived from a value the model never had.
+    const durErr = checkDuration(input.model, input.duration, {
+        videoResolution: input.videoResolution,
+        promptMode,
+    });
+    if (durErr)
+        return { requires_clarification: true, missing: ['duration'], message: durErr };
+    return null;
+}
 // Model → registry cost-key. Each provider's keys ship with their own
 // shape (verified against /api/agent/models):
 //   Kling: kling-v3-{standard|pro|omni}-{N}s — note the user-facing
@@ -1347,6 +1561,13 @@ const KLING_TIER_MAP = {
 // Exported for scripts/pricing-consistency-check.mjs (slates-api repo), which
 // asserts this builder byte-matches the desktop's klingCreditKey/seedanceCreditKey.
 export function videoCostKey(input) {
+    // EXACT-ID MAP, NEVER A PREFIX: 'minimax-h3-max' starts with 'minimax-h3'.
+    // Mirrors minimaxCreditKey() in slate/src/shared/pricing.ts.
+    if (MINIMAX_MODELS.has(input.model)) {
+        const res = input.videoResolution ?? defaultVideoResolutionFor(input.model);
+        const k = minimaxRefSurchargeCount(input.model, input.referenceImages);
+        return `${input.model}-${res}-${input.duration}s${k > 0 ? `-ref${k}` : ''}`;
+    }
     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
@@ -1354,10 +1575,11 @@ export function videoCostKey(input) {
         // (fal partner endpoint). A reference video flips to `-vref-{res}-{T}s`,
         // T = in + out.
         //
-        // ⚠️ EVERY BOUND HERE IS VERSION-SCOPED. 2.5 is 480p/720p only, runs to 30s,
-        // and takes references to 30s combined — so its vref total reaches 60, DOUBLE
-        // 2.0's ceiling of 30. Clamping a 2.5 quote at 30 would quote a real key at a
-        // fraction of the real bill.
+        // ⚠️ EVERY BOUND HERE IS VERSION-SCOPED. 2.5 runs 480p/720p/1080p (no 4K),
+        // reaches 30s, and takes references to 30s combined — so its vref total
+        // reaches 60, DOUBLE 2.0's ceiling of 30. Clamping a 2.5 quote at 30 would
+        // quote a real key at a fraction of the real bill. The ladder itself lives in
+        // MODEL_CAPABILITIES; only the per-version DEFAULT is stated below.
         const v25 = input.model.startsWith('seedance-2.5');
         const res = input.videoResolution ?? (v25 ? '720p' : '1080p');
         const face = input.seedanceRealFace ? '-realface' : input.seedanceFace ? '-face' : '';
@@ -1419,9 +1641,11 @@ export function omniFlashEditCostKey(duration) {
  *  2.0: refs 2–15s + output 4–15s. 2.5: refs to 30s + output to 30s. */
 const SEEDANCE_20_VREF_MAX_TOTAL = 30;
 const SEEDANCE_25_VREF_MAX_TOTAL = 60;
-/** Seedance 2.5 source-clip bounds for the edit task type. */
-export const SEEDANCE_25_EDIT_MIN_SECONDS = 4;
-export const SEEDANCE_25_EDIT_MAX_SECONDS = 30;
+/** Seedance 2.5 source-clip bounds for the edit task type — READ from the
+ *  capability SSOT, not typed. Kept as named exports because published builds
+ *  import them. */
+export const SEEDANCE_25_EDIT_MIN_SECONDS = editClipBounds('seedance-2.5-edit').min;
+export const SEEDANCE_25_EDIT_MAX_SECONDS = editClipBounds('seedance-2.5-edit').max;
 // Seedance 2.5 video-edit cost key — mirrors seedanceCreditKey() in
 // slate/src/shared/pricing.ts for the edit row (must byte-match; checked by the
 // slates-api pricing-consistency script). Unlike the Kling and Omni Flash edit
@@ -1515,10 +1739,22 @@ function resolveVideoModel(raw) {
         out.duration = parseInt(dur[1], 10);
         s = s.replace(/-(\d+)s\b/, '');
     }
-    const res = /-(480p|720p|1080p|4k)\b/.exec(s);
+    // MiniMax H3's paid-reference suffix, stripped like every other key dimension
+    // so a pasted `minimax-h3-768p-10s-ref2` resolves instead of erroring. The
+    // number it carries is K (images PAST the free five), so it is converted back
+    // to a TOTAL before anything can re-surcharge it.
+    const ref = /-ref(\d+)\b/.exec(s);
+    if (ref) {
+        out.referenceImages = MINIMAX_FREE_REF_IMAGES + parseInt(ref[1], 10);
+        s = s.replace(/-ref(\d+)\b/, '');
+    }
+    // The RESOLUTION vocabulary is GENERATED from MODEL_CAPABILITIES — the
+    // hand-typed list that stood here went stale the day 768p and 2k shipped.
+    const resRe = new RegExp(`-(${VIDEO_RESOLUTION_VOCAB.join('|')})\\b`);
+    const res = resRe.exec(s);
     if (res) {
         out.videoResolution = res[1];
-        s = s.replace(/-(480p|720p|1080p|4k)\b/, '');
+        s = s.replace(resRe, '');
     }
     if (/-audio\b/.test(s)) {
         out.sound = true;
@@ -1557,6 +1793,19 @@ function resolveVideoModel(raw) {
         'gemini-omni-flash': 'omni-flash',
         'gemini-omni-flash-preview': 'omni-flash',
         'omni-flash-preview': 'omni-flash',
+        // The MAX spellings must come out as MAX. Bare `minimax`, `h3` and
+        // `hailuo-3` all mean the BASE row — it holds the full ladder and the
+        // references, and it is cheaper at the tier they share.
+        'minimax-h3-max': 'minimax-h3-max',
+        'minimax-h3max': 'minimax-h3-max',
+        'h3-max': 'minimax-h3-max',
+        'hailuo-3-max': 'minimax-h3-max',
+        minimax: 'minimax-h3',
+        'minimax-h3': 'minimax-h3',
+        h3: 'minimax-h3',
+        'hailuo-3': 'minimax-h3',
+        'hailuo-3.0': 'minimax-h3',
+        hailuo: 'minimax-h3',
     };
     if (aliases[s]) {
         out.model = aliases[s];
@@ -1582,21 +1831,39 @@ function promptingSkillFor(model) {
         return 'slates-prompting-seedance';
     if (model.startsWith('omni-flash'))
         return 'slates-prompting-omni-flash';
+    // ONE skill covers both H3 seats — the prompt grammar is identical and only
+    // the ladder and the reference transport differ — so a prefix is right here.
+    if (model.startsWith('minimax-h3'))
+        return 'slates-prompting-minimax-h3';
     return 'slates-cost-discipline';
 }
 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) — 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").',
     input: z.object({
         prompt: z.string().min(1).max(4000),
-        model: z.string().describe('One of: kling-v3.0-std | kling-v3.0-pro | kling-v3.0-omni | seedance-2 | seedance-2.5 | veo-3.1-fast | veo-3.1-standard | omni-flash. 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 (4-30s takes, 30 image refs, audio-only refs — but 480p/720p ONLY, so stay on seedance-2 whenever resolution matters), Veo = native-synced-audio niche only (16:9, 4/6/8s) — never the default, omni-flash = cheap 720p tier with audio included (3-10s, 16:9/9:16; t2v, single-start-frame i2v, or up to 7 reference images; no last frame / video / audio refs). All are VIDEO-only. For per-call cost, call slates_estimate_generation_cost — never quote prices from memory.'),
+        // ROUTING doctrine only. Every capability number was stripped on 2026-08-16
+        // and now lives in the aspectRatio / duration / videoResolution descriptions
+        // below, generated from MODEL_CAPABILITIES. "Veo = 16:9 only" and
+        // "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, no references of any kind, and DEARER than minimax-h3 at the tier they share — a deliberate pick, never a default and never the cheap H3. 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.`),
         projectId: z.string().uuid().optional().describe('Save into this Slates project. Strongly recommended — the desktop UI shows a progress card live and the asset appears when complete.'),
-        aspectRatio: z.enum(['1:1', '16:9', '9:16', '4:3', '3:4', '21:9', '9:21', '4:5', '5:4', '2:3', '3:2']).optional().describe('Veo locks to 16:9 — passing anything else will be ignored or fail. Kling/Seedance support all.'),
-        duration: z.number().int().min(3).max(30).optional().describe('Seconds. Kling: 5-15. Veo: 4, 6, or 8 only (4K only at 8s). Seedance 2: 4-15. Seedance 2.5: 4-30 (the only model that reaches 30). Omni Flash: 3-10. Default 5 if omitted but always be explicit — cost scales linearly, and a 30s seedance-2.5 take is several hundred credits.'),
-        videoResolution: z.enum(['480p', '720p', '1080p', '4k']).optional().describe('Veo + Seedance. Seedance 2: 480p/720p/1080p/4K (default 1080p; 4K is native, the most expensive, and Pro-only). Seedance 2.5: 480p/720p ONLY (default 720p) — no 1080p and no 4K on any route Slates offers, so asking for one is rejected, not downgraded. Veo: 720p/1080p same price, 4K more (8s only).'),
+        // 🚨 THESE THREE DESCRIPTIONS ARE GENERATED FROM `MODEL_CAPABILITIES`.
+        // Never hand-write a ratio, resolution or duration into them again — every
+        // one of the hand-written claims that stood here had drifted, and an
+        // out-of-set value is accepted by the client and rejected by the provider
+        // ASYNCHRONOUSLY, after the job queues and credits reserve.
+        aspectRatio: zEnum(VIDEO_ASPECT_RATIOS).optional().describe(`NOT every model takes every value — an out-of-set ratio is REFUSED before submit, not silently ignored. Per model: ${describeAspectRatios(VIDEO_MODELS, AGENT_ROUTE_PROVIDER)}`),
+        duration: z.number().int().min(VIDEO_DURATION_BOUNDS.min).max(VIDEO_DURATION_BOUNDS.max).optional().describe(`Seconds. Cost scales linearly — a 30s seedance-2.5 take is several hundred credits, so be explicit rather than defaulting. Per model: ${describeDurations(VIDEO_MODELS)}`),
+        videoResolution: zEnum(VIDEO_RESOLUTIONS).optional().describe(`An unsupported resolution is REJECTED, never downgraded. Per model: ${describeVideoResolutions(VIDEO_MODELS)}. 4K video is Pro-only (the server returns PRO_REQUIRED for a base-tier account).`),
         firstFrameAssetId: z.string().optional().describe('Starting frame for image-to-video: asset UUID or badge code ("IMG-A8") — codes resolve against the project at call time, so a code the user just spoke is always safe to pass.'),
         lastFrameAssetId: z.string().optional().describe('Ending frame (UUID or badge code). Veo and Seedance only. Pairs with firstFrameAssetId for guided transitions.'),
-        ingredientAssetIds: z.array(z.string()).max(30).optional().describe('Visual reference / ingredient assets (UUIDs or badge codes) for Kling Omni, Seedance, or Omni Flash. Up to 30 (Seedance 2.5), 9 (Seedance 2), 4 (Kling), or 7 (Omni Flash, combined across all ref params). More is not better: 2-4 strong references beat both extremes, and past 4 reference PEOPLE output stability drops on Seedance regardless of the cap.'),
+        ingredientAssetIds: z.array(z.string()).max(30).optional().describe(
+        // Caps DERIVED from MODEL_CAPABILITIES — the hand-typed list omitted
+        // kling-v3.0-omni-pro entirely and read as if 7 were an Omni Flash-only rule.
+        `Visual reference / ingredient assets (UUIDs or badge codes). Cap per model (combined across ingredient/character/environment/style params): ${describeReferenceImageCaps(VIDEO_MODELS)}. More is not better: 2-4 strong references beat both extremes, and past 4 reference PEOPLE output stability drops on Seedance regardless of the cap.`),
         characterAssetIds: z.array(z.string()).optional().describe('Character sheet assets (UUIDs or badge codes) — keeps a character consistent across the shot.'),
         environmentAssetIds: z.array(z.string()).optional().describe('Environment reference assets (UUIDs or badge codes) — keeps a location/setting consistent across the shot.'),
         styleAssetIds: z.array(z.string()).optional().describe('Style reference assets (UUIDs or badge codes) — locks the visual style of the shot.'),
@@ -1662,22 +1929,28 @@ export const generateVideo = {
                 missing,
                 message: `Missing required field(s): ${missing.join(', ')}. ` +
                     `Read the slates-cost-discipline + ${promptingSkillFor(input.model)} skills, ` +
-                    `or ask the user. Veo locks to 16:9. Kling/Seedance support 1:1 16:9 9:16 4:3 3:4 21:9. Omni Flash: 16:9/9:16 only. ` +
-                    `Duration: Kling 5-15s, Veo 4/6/8s (4K only at 8s), Seedance 4-15s, Omni Flash 3-10s. Cost scales linearly with duration.`,
+                    // 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
+                    // 21:9" and "Kling 5-15s" — three wrong claims in one sentence.
+                    `or ask the user. ` +
+                    `Aspect ratio for ${input.model}: ${aspectRatiosFor(input.model, AGENT_ROUTE_PROVIDER).join(', ')}. ` +
+                    `Duration: ${describeDurations([input.model])}. ` +
+                    `Cost scales linearly with duration.`,
             });
         }
-        // Omni Flash: 3-10s, 720p only — t2v, single-start-frame i2v, or ref2v
-        // with up to 7 reference IMAGES. No last frame, no video/audio refs.
-        // Validate up front so the agent gets an actionable message instead of
-        // a registry throw.
+        // 🚨 CAPABILITY GATE — the one that stops a client-side accept of a
+        // server-side reject. Registry-driven and model-keyed: an aspect ratio,
+        // resolution or duration the chosen model does not take is refused HERE,
+        // before the job queues and credits reserve. Runs after normalisation so it
+        // sees the resolved model and any params a cost key back-filled.
+        const capErr = assertVideoCapabilities(input);
+        if (capErr)
+            return ok(capErr);
+        // Omni Flash's SHAPE constraints — t2v, single-start-frame i2v, or ref2v
+        // with reference IMAGES. No last frame, no video/audio refs. (Its duration
+        // and resolution are covered by the capability gate above; the 3-10s check
+        // that used to live here was a hand-typed duplicate of registry data.)
         if (input.model === 'omni-flash') {
-            if (input.duration < 3 || input.duration > 10) {
-                return ok({
-                    requires_clarification: true,
-                    missing: ['duration'],
-                    message: `Omni Flash supports 3-10 seconds (you passed ${input.duration}s). Pick a duration in that range.`,
-                });
-            }
             if (input.lastFrameAssetId ||
                 input.videoReferenceAssetId || input.audioReferenceAssetId ||
                 (input.videoReferenceAssetIds?.length ?? 0) > 0 ||
@@ -1685,40 +1958,98 @@ export const generateVideo = {
                 return ok({
                     requires_clarification: true,
                     missing: [],
-                    message: 'Omni Flash takes a prompt, an optional start frame, and up to 7 reference IMAGES — last frames and video/audio references are not supported. Drop those, or switch to seedance-2 (video/audio refs, last frame) or veo (last frame).',
+                    message: `Omni Flash takes a prompt, an optional start frame, and up to ${omniFlashRefCap} reference IMAGES — last frames and video/audio references are not supported. Drop those, or switch to seedance-2 (video/audio refs, last frame) or veo (last frame).`,
                 });
             }
             const refCount = (input.ingredientAssetIds?.length ?? 0) +
                 (input.characterAssetIds?.length ?? 0) +
                 (input.environmentAssetIds?.length ?? 0) +
                 (input.styleAssetIds?.length ?? 0);
-            if (refCount > 7) {
+            if (refCount > omniFlashRefCap) {
                 return ok({
                     requires_clarification: true,
                     missing: [],
-                    message: `Omni Flash takes at most 7 reference images combined (you passed ${refCount}). Trim the list.`,
+                    message: `Omni Flash takes at most ${omniFlashRefCap} reference images combined (you passed ${refCount}). Trim the list.`,
                 });
             }
         }
-        // Veo exists only at discrete durations 4/6/8s, and 4K only at 8s.
-        // Validate up front so the agent gets an actionable message instead of
-        // a generic "Model variant not in registry" throw from the cost lookup.
-        if (input.model.startsWith('veo')) {
-            if (![4, 6, 8].includes(input.duration)) {
+        // 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,
+        // image-to-video and reference-to-video for `minimax/h3`, and only the
+        // first two for `minimax/h3-max` (its reference-to-video 404s). The
+        // reference endpoint has no frame parameters at all, so frames and
+        // references are mutually exclusive — a shape mismatch, not a preference.
+        if (MINIMAX_MODELS.has(input.model)) {
+            const cap = getModelCapability(input.model);
+            const refImages = minimaxRefImageCount(input);
+            const refMedia = (input.videoReferenceAssetIds?.length ?? 0) +
+                (input.audioReferenceAssetIds?.length ?? 0) +
+                (input.videoReferenceAssetId ? 1 : 0) +
+                (input.audioReferenceAssetId ? 1 : 0);
+            const maxImages = cap?.maxIngredientImages ?? 0;
+            const maxVideos = cap?.maxReferenceVideos ?? 0;
+            const maxAudio = cap?.maxReferenceAudio ?? 0;
+            const maxTotal = cap?.maxReferenceFilesTotal ?? 0;
+            if (maxImages === 0 && (refImages > 0 || refMedia > 0)) {
                 return ok({
                     requires_clarification: true,
-                    missing: ['duration'],
-                    message: `Veo 3.1 supports only 4s, 6s, or 8s (you passed ${input.duration}s). Pick one of those.`,
+                    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.`,
                 });
             }
-            if (input.videoResolution === '4k' && input.duration !== 8) {
+            if ((refImages > 0 || refMedia > 0) && (input.firstFrameAssetId || input.lastFrameAssetId)) {
                 return ok({
                     requires_clarification: true,
-                    missing: ['duration'],
-                    message: `Veo 3.1 4K renders only at 8s (you passed ${input.duration}s at 4k). Use duration=8 for 4K, or drop to 720p/1080p for 4s/6s.`,
+                    missing: [],
+                    message: `${input.model} can use first/last frames OR references, not both — they are different endpoints and the reference one has no frame slots. Drop one side.`,
+                });
+            }
+            if (refImages > maxImages) {
+                return ok({
+                    requires_clarification: true,
+                    missing: [],
+                    message: `${input.model} takes at most ${maxImages} reference images combined (you passed ${refImages}). Trim the list — and note the first ${MINIMAX_FREE_REF_IMAGES} are free while each one after that adds a paid dimension to the cost key.`,
+                });
+            }
+            if ((input.videoReferenceAssetIds?.length ?? 0) + (input.videoReferenceAssetId ? 1 : 0) > maxVideos) {
+                return ok({
+                    requires_clarification: true,
+                    missing: [],
+                    message: `${input.model} takes at most ${maxVideos} reference videos.`,
+                });
+            }
+            if ((input.audioReferenceAssetIds?.length ?? 0) + (input.audioReferenceAssetId ? 1 : 0) > maxAudio) {
+                return ok({
+                    requires_clarification: true,
+                    missing: [],
+                    message: `${input.model} takes at most ${maxAudio} reference audio clips.`,
+                });
+            }
+            if (maxTotal > 0 && refImages + refMedia > maxTotal) {
+                return ok({
+                    requires_clarification: true,
+                    missing: [],
+                    message: `${input.model} takes at most ${maxTotal} reference files across all modalities (you passed ${refImages + refMedia}).`,
+                });
+            }
+            // 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);
+            const videoRefs = (input.videoReferenceAssetIds?.length ?? 0) + (input.videoReferenceAssetId ? 1 : 0);
+            if (audioRefs > 0 && refImages === 0 && videoRefs === 0) {
+                return ok({
+                    requires_clarification: true,
+                    missing: [],
+                    message: `${input.model} rejects an audio-only reference set — add at least one reference image or video alongside it.`,
                 });
             }
         }
+        // ⛔ The hand-written Veo duration block that stood here is GONE. It read
+        // `![4,6,8].includes(duration)` plus "4K only at 8s" — and the registry
+        // forces 8s at 1080p TOO, so it happily quoted a 4s 1080p Veo the provider
+        // rejects. `assertVideoCapabilities` above covers both, plus the
+        // reference-to-video 8s rule it never knew about, from the SSOT.
         // Resolve every asset reference (UUID or badge code) against the
         // project AT CALL TIME. Codes the user just spoke ("a8 is the one")
         // resolve to whatever exists NOW — including assets created in the UI
@@ -1825,6 +2156,10 @@ export const generateVideo = {
             sound: input.sound,
             seedanceFace: input.seedanceFace,
             seedanceRealFace: input.seedanceRealFace,
+            // MiniMax H3 base: reference images past the fifth are a PAID key
+            // dimension. Counted from the same four arrays the request sends, so the
+            // quote and the server's own re-derivation see the same number.
+            referenceImages: minimaxRefImageCount(input),
             // Σ ceil(d - 0.05) over every reference clip, both shapes — the same
             // expression the desktop's estimateCost and the handler's key builder
             // use. Quoting only the singular would understate a multi-clip call.
@@ -1845,7 +2180,9 @@ export const generateVideo = {
         const entry = registry.models.find((m) => m.model === costKey);
         if (!entry) {
             throw new Error(`Model variant not in registry: ${costKey}. ` +
-                `Available video models: ${registry.models.filter((m) => m.model.startsWith('kling') || m.model.startsWith('veo') || m.model.startsWith('seedance') || m.model.startsWith('omni-flash')).map((m) => m.model).slice(0, 20).join(', ')}`);
+                // Prefixes DERIVED from the model list, so a new family cannot be
+                // missing from the hint the way minimax-h3 was on day one.
+                `Available video models: ${registry.models.filter((m) => VIDEO_MODELS.some((v) => m.model.startsWith(v.split('.')[0]))).map((m) => m.model).slice(0, 20).join(', ')}`);
         }
         const totalCents = creditCost(entry);
         // Pre-flight confirm gate. Fires when:
@@ -2350,16 +2687,17 @@ export const generateMotionTransfer = {
 // ── Edit video (Kling O3 video-to-video) ────────────────────────
 export const editVideo = {
     id: 'slates_edit_video',
-    description: 'Edit an EXISTING video clip with one instruction — character swap, environment change, style transfer — in one pass, no masking. Original motion, camera, and audio are preserved; only what the prompt names changes. Use when a clip is ~90% right (fix it, don\'t re-roll it) or to AI-edit the user\'s own footage. Engines: Kling O3 edit (default; 3–15s clips, 720–3840px, subject/style refs via elements), omni-flash-edit (Gemini Omni Flash; 3–10s clips, 720p output, PROMPT-ONLY — no refs, cheapest seat), or seedance-2.5-edit (4–30s clips — the ONLY engine that takes a clip over 15s; 480p/720p, seedanceFace:true for AI-character faces). Cost = per second of OUTPUT (≈ clip length, rounded UP to the next second): omni-flash-edit ≈ 19¢/s ≈ kling-v3.0-omni-edit ≈ 19¢/s, kling-v3.0-omni-pro-edit ≈ 25¢/s. Subjects to swap IN go as characterAssetIds (frontal + angle images become Kling elements — Kling models only); style refs as styleAssetIds; max 4 combined. seedance-2.5-edit is priced per second of output on the video-reference tier and bills roughly double a plain 2.5 generation of the same length, because every provider charges an edit on input + output seconds — always read the quote from the confirm gate rather than assuming. The edited clip saves as a NEW asset linked to its parent (chain edits freely). Routing: Kling edit is the default edit tool (element lock + audio intact); omni-flash-edit for cheap prompt-only footage-synced swaps; prefer Seedance edit/relocate only for style-transfer-heavy jobs — see slates-model-selection. Prompting: slates-prompting-kling-v3 §Edit / slates-prompting-omni-flash.',
+    description: 'Edit an EXISTING video clip with one instruction — character swap, environment change, style transfer — in one pass, no masking. Original motion, camera, and audio are preserved; only what the prompt names changes. Use when a clip is ~90% right (fix it, don\'t re-roll it) or to AI-edit the user\'s own footage. Engines: Kling O3 edit (default; 3–15s clips, 720–3840px, subject/style refs via elements), omni-flash-edit (Gemini Omni Flash; 3–10s clips, 720p output, PROMPT-ONLY — no refs, cheapest seat), or seedance-2.5-edit (4–30s clips — the ONLY engine that takes a clip over 15s; up to 1080p, seedanceFace:true for AI-character faces). Cost = per second of OUTPUT (≈ clip length, rounded UP to the next second): omni-flash-edit ≈ 19¢/s ≈ kling-v3.0-omni-edit ≈ 19¢/s, kling-v3.0-omni-pro-edit ≈ 25¢/s. Subjects to swap IN go as characterAssetIds (frontal + angle images become Kling elements — Kling models only); style refs as styleAssetIds; max 4 combined. seedance-2.5-edit is priced per second of output on the video-reference tier and bills roughly double a plain 2.5 generation of the same length, because every provider charges an edit on input + output seconds — always read the quote from the confirm gate rather than assuming. The edited clip saves as a NEW asset linked to its parent (chain edits freely). Routing: Kling edit is the default edit tool (element lock + audio intact); omni-flash-edit for cheap prompt-only footage-synced swaps; prefer Seedance edit/relocate only for style-transfer-heavy jobs — see slates-model-selection. Prompting: slates-prompting-kling-v3 §Edit / slates-prompting-omni-flash.',
     input: z.object({
         projectId: z.string().uuid().describe('Project the source clip lives in.'),
         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."'),
-        model: z.enum(['kling-v3.0-omni-edit', 'kling-v3.0-omni-pro-edit', 'omni-flash-edit', 'seedance-2.5-edit']).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, 720p, 3–10s) for prompt-only edits — it takes NO character/style refs. seedance-2.5-edit (480p/720p, 4–30s) is the ONLY engine that accepts a clip longer than 15s; it also takes NO character/style refs on this op.'),
+        // 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)}`),
         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).'),
-        videoResolution: z.enum(['480p', '720p']).optional().describe('seedance-2.5-edit ONLY (default 720p). Ignored by the Kling and Omni Flash engines, whose output follows the source clip.'),
+        videoResolution: zEnum(EDIT_VIDEO_RESOLUTIONS).optional().describe(`seedance-2.5-edit ONLY (default ${defaultVideoResolutionFor('seedance-2.5-edit')}). Ignored by the Kling and Omni Flash engines, whose output follows the source clip.`),
         seedanceFace: z.boolean().optional().describe('seedance-2.5-edit ONLY: set true when a CHARACTER FACE is visible in the clip. Faceless edits run on BytePlus; faces are blocked there and must route to the relaxed provider, which costs ~35% more. A face edit submitted without this flag is rejected by the provider, not silently downgraded.'),
         background: z.boolean().optional().describe(BACKGROUND_DESCRIBE),
         confirm: z.boolean().optional().describe('Set true to bypass the cost confirm gate after the user OKs the spend.'),
@@ -2373,10 +2711,9 @@ export const editVideo = {
         const model = input.model ?? 'kling-v3.0-omni-edit';
         const isOmniFlashEdit = model === 'omni-flash-edit';
         const isSeedanceEdit = model === 'seedance-2.5-edit';
-        // Kling edit: 3–15s source clips; Omni Flash edit: 3–10s; Seedance 2.5
-        // edit: 4–30s — the only engine that takes a clip over 15s.
-        const minClipSeconds = isSeedanceEdit ? SEEDANCE_25_EDIT_MIN_SECONDS : 3;
-        const maxClipSeconds = isSeedanceEdit ? SEEDANCE_25_EDIT_MAX_SECONDS : isOmniFlashEdit ? 10 : 15;
+        // Source-clip window, read from the capability SSOT per engine — never a
+        // model-id ternary. (Kling 3–15s, Omni Flash 3–10s, Seedance 2.5 4–30s.)
+        const { min: minClipSeconds, max: maxClipSeconds } = editClipBounds(model);
         if ((isOmniFlashEdit || isSeedanceEdit) && ((input.characterAssetIds?.length ?? 0) > 0 || (input.styleAssetIds?.length ?? 0) > 0)) {
             throw new Error(`${model} takes the prompt and the source clip only on this op — no character/style reference images. Drop the refs, or switch to kling-v3.0-omni-edit which supports elements.`);
         }
@@ -2419,7 +2756,10 @@ export const editVideo = {
         const costKey = isSeedanceEdit
             ? seedanceEditCostKey({
                 duration: billedSeconds,
-                videoResolution: input.videoResolution ?? '720p',
+                // Cast to the full union, never to the row's current two-or-three
+                // values: MODEL_CAPABILITIES is the narrowing authority and that list
+                // moves (1080p landed on the 2.5 edit row 2026-08-24).
+                videoResolution: (input.videoResolution ?? defaultVideoResolutionFor('seedance-2.5-edit')),
                 seedanceFace: input.seedanceFace === true,
             })
             : isOmniFlashEdit
@@ -3152,6 +3492,15 @@ function resolveGuideTopic(topic) {
         return 'slates-prompting-veo-3';
     if (t.startsWith('omni-flash') || t.startsWith('gemini-omni') || t === 'omni flash')
         return 'slates-prompting-omni-flash';
+    // MiniMax H3 — both seats share one skill. Placed BEFORE the seed/seedance
+    // block for the same reason seed-audio is: no prefix collision exists today,
+    // but a `minimax-*` id must never fall through to a Seedance guide.
+    if (t.startsWith('minimax') ||
+        t.startsWith('hailuo') ||
+        t === 'h3' ||
+        t.startsWith('h3-')) {
+        return 'slates-prompting-minimax-h3';
+    }
     if (t.startsWith('kling-mc'))
         return 'slates-prompting-motion-transfer';
     if (t === 'edit-video' || t === 'video-edit' || t === 'edit video' || t === 'video edit')