@slatesvideo/shared 0.5.5 → 0.5.7

package/dist/operations/index.js

@@ -13,6 +13,9 @@ import { z } from 'zod';
 import { SlatesCloudClient } from '../clients/cloud.js';
 import { SlatesDesktopClient } from '../clients/desktop.js';
 import { SKILLS } from '../skills/content.js';
+// Reference-capacity prose is DERIVED, never hand-typed — root CLAUDE.md:
+// "never hand-type a fact an LLM will read". These helpers read MODEL_FACTS.
+import { multimodalRefSummary, multimodalRefModels, seedanceTaskIntentWords } from '../prompts/model-facts.js';
 export function defaultContext() {
     return {
         cloud: () => new SlatesCloudClient(),
@@ -120,8 +123,11 @@ export const listAvailableModels = {
         const table = models.map((m) => `${m.model} ${creditCost(m)}`).join('\n');
         return {
             text: `${models.length} COST keys (credits per generation)${input.filter ? ` matching "${input.filter}"` : ''}. ` +
-                `NOTE: these are billing keys for cost lookup ONLY — the \`model\` param on slates_generate_video takes a BASE id ` +
-                `(kling-v3.0-std | kling-v3.0-pro | kling-v3.0-omni | seedance-2 | veo-3.1-fast | veo-3.1-standard) with duration/videoResolution as separate params:\n` +
+                `NOTE: these are billing keys for cost lookup ONLY — the \`model\` param on the generate ops takes a BASE id. ` +
+                // Derived from the SSOT arrays, not restated: a hand-written list here
+                // drifts the moment a model lands (it already omitted omni-flash).
+                `slates_generate_video: ${VIDEO_MODELS.join(' | ')} (duration/videoResolution as separate params). ` +
+                `slates_generate_audio: ${AUDIO_MODELS.join(' | ')} (durationSeconds as a separate param):\n` +
                 table,
             data: { count: models.length },
         };
@@ -133,7 +139,7 @@ export const estimateGenerationCost = {
     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(3).max(15).optional().describe('Video only — seconds. Cost scales linearly; required with a video base id.'),
+        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.'),
         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).'),
@@ -152,6 +158,42 @@ export const estimateGenerationCost = {
             if (img)
                 key = imageCostKey(img, input.resolution ?? (img === 'nano-banana-2-lite' ? '1k' : '2k'), input.quality ?? 'medium');
         }
+        // 2a) audio base id → seconds. Both surfaces bill per second, so a
+        //     duration is always required. Runs BEFORE the video resolver: it is
+        //     forgiving by design and "seed-audio" would otherwise be mistaken for
+        //     a seedance spelling.
+        if (!key && AUDIO_MODELS.includes(input.model)) {
+            const m = input.model;
+            if (!input.duration) {
+                return ok({
+                    requires_clarification: true,
+                    missing: ['duration'],
+                    message: m === 'seed-audio'
+                        ? 'Seed Audio cost scales with the REQUESTED duration — and that duration is what the user is billed regardless of what comes back (it has no duration parameter; the number is written into the prompt). Pass duration in seconds (3-120).'
+                        : 'Sound Effects bills per second — pass duration in seconds (1-22).',
+                });
+            }
+            // REFUSE an out-of-range duration rather than quoting the clamped price.
+            // audioCostKey clamps (it has to — it mirrors the desktop, which clamps),
+            // so without this an agent asking for 2s of Seed Audio would be handed a
+            // real 3s price and no hint that 2s is not a thing it can order. The
+            // generate op gates the same way; the two must agree or the quote is a
+            // promise the generation refuses to keep.
+            const audioBounds = {
+                'seed-audio': { min: SEED_AUDIO_MIN_SECONDS, max: SEED_AUDIO_MAX_SECONDS },
+                'eleven-sfx': { min: ELEVEN_SFX_MIN_SECONDS, max: ELEVEN_SFX_MAX_SECONDS },
+            };
+            const bounds = audioBounds[m];
+            if (input.duration < bounds.min || input.duration > bounds.max) {
+                return ok({
+                    requires_clarification: true,
+                    missing: ['duration'],
+                    message: `${m} accepts ${bounds.min}-${bounds.max} seconds — ${input.duration}s is outside that range and would be refused at generation time. ` +
+                        'Re-ask with a duration in range.',
+                });
+            }
+            key = audioCostKey({ model: m, durationSeconds: input.duration });
+        }
         // 2b) Kling O3 edit base id + duration (ceiled source-clip length)
         if (!key && (input.model === 'kling-v3.0-omni-edit' || input.model === 'kling-v3.0-omni-pro-edit')) {
             if (!input.duration) {
@@ -181,7 +223,12 @@ export const estimateGenerationCost = {
                     duration,
                     videoResolution: input.videoResolution ??
                         resolved.videoResolution ??
-                        (resolved.model.startsWith('seedance') ? '1080p' : undefined),
+                        // 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),
                     sound: input.sound ?? resolved.sound,
                     seedanceFace: input.seedanceFace ?? resolved.seedanceFace,
                     seedanceRealFace: input.seedanceRealFace,
@@ -190,7 +237,7 @@ export const estimateGenerationCost = {
         }
         const perCredits = key != null ? byKey.get(key) : undefined;
         if (key == null || perCredits == null) {
-            throw new Error(`Unknown model: ${input.model}. Pass a base id (${VIDEO_MODELS.join(' | ')} | nano-banana-2 | flux-2-max | seedream-5-lite) plus duration/resolution params, or use slates_list_available_models with a filter.`);
+            throw new Error(`Unknown model: ${input.model}. Pass a base id (${VIDEO_MODELS.join(' | ')} | ${AUDIO_MODELS.join(' | ')} | nano-banana-2 | flux-2-max | seedream-5-lite) plus duration/resolution params, or use slates_list_available_models with a filter.`);
         }
         const qty = input.quantity ?? 1;
         const totalCredits = perCredits * qty;
@@ -439,16 +486,16 @@ export const getAssetVideoFrames = {
 };
 export const uploadReferenceImage = {
     id: 'slates_upload_reference_image',
-    description: 'Add a reference image OR video clip to a Slates project. Pass either filePath (absolute path to a local file) or dataUrl (base64 data: URL) — exactly one. Set type:"video" on a filePath import to bring in a clip (the user\'s own footage to edit/relocate/trim); imported videos are probed on ingest, so duration + dimensions are available immediately. Default type is "image". dataUrl is image-only.',
+    description: 'Add a reference image, video clip, or audio file to a Slates project from disk. Pass either filePath (absolute path to a local file) or dataUrl (base64 data: URL) — exactly one. Set type:"video" to bring in a clip (the user\'s own footage to edit/relocate/trim) or type:"audio" for music/VO/SFX they already have; both are probed on ingest, so duration (and for video, dimensions) are available immediately, and audio gets its waveform. Default type is "image". dataUrl is image-only.',
     input: z
         .object({
         projectId: z.string().uuid(),
         filePath: z.string().optional(),
         dataUrl: z.string().optional(),
         type: z
-            .enum(['image', 'video'])
+            .enum(['image', 'video', 'audio'])
             .optional()
-            .describe('Asset kind for a filePath import — "image" (default) or "video". A dataUrl is always an image.'),
+            .describe('Asset kind for a filePath import — "image" (default), "video", or "audio". A dataUrl is always an image.'),
     })
         .refine((d) => !!d.filePath !== !!d.dataUrl, {
         message: 'Pass exactly one of filePath or dataUrl',
@@ -463,8 +510,8 @@ export const uploadReferenceImage = {
             });
             return ok(r);
         }
-        if (input.type === 'video') {
-            throw new Error('dataUrl uploads are image-only — pass a filePath to import a video clip.');
+        if (input.type === 'video' || input.type === 'audio') {
+            throw new Error(`dataUrl uploads are image-only — pass a filePath to import ${input.type === 'audio' ? 'an audio file' : 'a video clip'}.`);
         }
         const r = await desktop.post('/agent/assets/upload-base64', {
             projectId: input.projectId,
@@ -506,6 +553,82 @@ export const moveAssetsToFolder = {
         return ok(await ctx.desktop().post('/agent/folders/move-assets', input));
     },
 };
+export const moveAssetsToProject = {
+    id: 'slates_move_assets_to_project',
+    description: 'Move assets (images, videos, audio) out of one project into another. The media files move on disk into the destination project folder — this is a real re-home, not a copy. Moved assets leave whatever gallery folder they were in and are issued fresh badge codes in the destination.',
+    input: z.object({
+        sourceProjectId: z.string().uuid(),
+        // Badge codes ("IMG-A8") resolve against sourceProjectId at call time.
+        assetIds: z.array(z.string().min(1)).min(1),
+        targetProjectId: z.string().uuid(),
+    }),
+    async run(input, ctx) {
+        if (input.sourceProjectId === input.targetProjectId) {
+            throw new Error('sourceProjectId and targetProjectId are the same — nothing to move.');
+        }
+        const resolved = await resolveAssetRefs(ctx, input.sourceProjectId, input.assetIds);
+        const assetIds = input.assetIds.map((ref) => resolved.get(ref)?.id ?? ref);
+        const result = await ctx.desktop().post('/agent/assets/move-to-project', {
+            assetIds,
+            targetProjectId: input.targetProjectId,
+            // Sent so the route can ENFORCE it. resolveAssetRefs only validates
+            // badge codes against the source project — a raw UUID passes straight
+            // through, so without this a caller could move an asset out of a
+            // project it never named.
+            sourceProjectId: input.sourceProjectId,
+        });
+        // Timeline clips key media by PATH, so the move repointed edits in OTHER
+        // projects at files that now live inside the destination — and deleting the
+        // destination deletes those files. Say it in the TEXT, not just the data:
+        // an agent summarising this result must be able to pass the warning on.
+        const refs = result.externalClipRefs ?? [];
+        if (refs.length > 0) {
+            const clips = refs.reduce((n, r) => n + r.clipCount, 0);
+            const where = refs.map((r) => `"${r.projectName}"`).join(', ');
+            return ok(result, `${JSON.stringify(result)}\n\n⚠️ ${clips} timeline clip(s) in ${where} now reference the moved ` +
+                `file(s) inside the destination project. Deleting the destination project would break those ` +
+                `edits. Tell the user — this is the one cross-project reference Slates allows.`);
+        }
+        return ok(result);
+    },
+};
+export const copyAssetsToProject = {
+    id: 'slates_copy_assets_to_project',
+    description: 'Copy assets (images, videos, audio) from one project into another. The originals stay exactly where they are — new files, new rows, new badge codes in the destination. Use this instead of slates_move_assets_to_project when the asset is already in use where it lives: an image that is a character/environment/style identity or sits in a storyboard frame CANNOT be moved out (that would leave the other project pointing at a file it no longer owns), but it can always be copied. Lineage is not copied; the copy starts clean.',
+    input: z.object({
+        sourceProjectId: z.string().uuid(),
+        // Badge codes ("IMG-A8") resolve against sourceProjectId at call time.
+        assetIds: z.array(z.string().min(1)).min(1),
+        targetProjectId: z.string().uuid(),
+    }),
+    async run(input, ctx) {
+        if (input.sourceProjectId === input.targetProjectId) {
+            throw new Error('sourceProjectId and targetProjectId are the same — nothing to copy.');
+        }
+        const resolved = await resolveAssetRefs(ctx, input.sourceProjectId, input.assetIds);
+        const assetIds = input.assetIds.map((ref) => resolved.get(ref)?.id ?? ref);
+        return ok(await ctx.desktop().post('/agent/assets/copy-to-project', {
+            assetIds,
+            targetProjectId: input.targetProjectId,
+            // Enforced route-side for the same reason as the move op: resolveAssetRefs
+            // only validates badge codes, so a raw UUID would otherwise let a caller
+            // copy out of a project it never named.
+            sourceProjectId: input.sourceProjectId,
+        }));
+    },
+};
+export const moveEntityToProject = {
+    id: 'slates_move_entity_to_project',
+    description: "Move a character, environment, or style into another project, taking every image it references with it. This is the fix when slates_move_assets_to_project refuses an asset because an entity still uses it: the identity image can't leave on its own, but the whole entity can. Refuses (rather than cascading) if one of its images is ALSO used by something else — copy the images instead in that case. Storyboard frames are not movable this way; moving a frame's image out would empty the shot.",
+    input: z.object({
+        kind: z.enum(['character', 'environment', 'style']),
+        entityId: z.string().uuid(),
+        targetProjectId: z.string().uuid(),
+    }),
+    async run(input, ctx) {
+        return ok(await ctx.desktop().post('/agent/entities/move-to-project', input));
+    },
+};
 // ── Characters ──────────────────────────────────────────────────
 export const listCharacters = {
     id: 'slates_list_characters',
@@ -1197,6 +1320,11 @@ export const VIDEO_MODELS = [
     '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',
 ];
 // Model → registry cost-key. Each provider's keys ship with their own
@@ -1220,16 +1348,24 @@ const KLING_TIER_MAP = {
 // asserts this builder byte-matches the desktop's klingCreditKey/seedanceCreditKey.
 export function videoCostKey(input) {
     if (input.model.startsWith('seedance')) {
-        // Mirrors seedanceCreditKey() in slate/src/shared/pricing.ts (face × vref ×
-        // res × duration). AI-face route bills the `-face-` key (~45% over faceless);
-        // consented real-person route bills the premium `-realface-` key (fal partner
-        // endpoint). A reference video flips to `-vref-{res}-{T}s`, T = in + out (6..30).
-        const res = input.videoResolution ?? '1080p';
+        // Mirrors seedanceCreditKey() in slate/src/shared/pricing.ts (version × face
+        // × vref × res × duration). AI-face route bills the `-face-` key (~45% over
+        // faceless); consented real-person route bills the premium `-realface-` key
+        // (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.
+        const v25 = input.model.startsWith('seedance-2.5');
+        const res = input.videoResolution ?? (v25 ? '720p' : '1080p');
         const face = input.seedanceRealFace ? '-realface' : input.seedanceFace ? '-face' : '';
         const vrefSecs = input.videoRefSeconds ?? 0;
         if (vrefSecs > 0) {
             // ceil(x - 0.05) matches the server's probe rounding — quote = bill.
-            const total = Math.min(30, Math.max(6, Math.ceil(vrefSecs - 0.05) + input.duration));
+            const maxTotal = v25 ? SEEDANCE_25_VREF_MAX_TOTAL : SEEDANCE_20_VREF_MAX_TOTAL;
+            const total = Math.min(maxTotal, Math.max(6, Math.ceil(vrefSecs - 0.05) + input.duration));
             return `${input.model}${face}-vref-${res}-${total}s`;
         }
         return `${input.model}${face}-${res}-${input.duration}s`;
@@ -1279,6 +1415,91 @@ export function klingEditCostKey(model, duration) {
 export function omniFlashEditCostKey(duration) {
     return `omni-flash-edit-${duration}s`;
 }
+/** Max billed (input + output) seconds on a Seedance video-reference gen.
+ *  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 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
+// keys this one carries a RESOLUTION and a FACE ROUTE, because Seedance's edit
+// price moves with both. Duration is the CEILED source-clip length: the edit
+// task type forces `duration: -1` on the wire, so the source clip is the only
+// honest quote.
+export function seedanceEditCostKey(input) {
+    const res = input.videoResolution ?? '720p';
+    const face = input.seedanceRealFace ? '-realface' : input.seedanceFace ? '-face' : '';
+    return `seedance-2.5-edit${face}-${res}-${input.duration}s`;
+}
+// ── Audio ───────────────────────────────────────────────────────
+// Exported: the exact `model` ids slates_generate_audio accepts — consumed
+// by the desktop Studio Agent system prompt (SSOT; never restate these ids
+// in prose that can drift). Mirrors VIDEO_MODELS for the third media type.
+export const AUDIO_MODELS = ['seed-audio', 'eleven-sfx'];
+/**
+ * Per-surface bounds and defaults.
+ *
+ * 🚨 THESE FOUR NUMBERS PER SURFACE LIVE IN THREE REPOS. A change is a
+ * three-site edit, every time:
+ *   1. HERE (`audioCostKey`, the agent's pre-flight quote)
+ *   2. `slate/src/shared/pricing.ts` → MODEL_REGISTRY `audio.durationSeconds`
+ *      (min/max/default), read by `clampAudioDuration` + `audioCreditKey`
+ *   3. `slates-api/src/lib/audio-keys.ts` → the server's fail-closed bounds
+ * `slates-api/scripts/pricing-consistency-check.mjs` §4 asserts 1 and 2 agree
+ * at EVERY value including out-of-range ones; the gate check covers 3.
+ *
+ * The MINs used to be missing here, and the clamp floor was a hardcoded 1. That
+ * made `slates_estimate_generation_cost({model:'seed-audio', duration:2})`
+ * quote a real `seed-audio-2s` price for a generation the desktop would bill as
+ * 3s and the proxy would REJECT outright. Same for an omitted duration, which
+ * quoted `seed-audio-1s` against the desktop's `seed-audio-15s`.
+ */
+export const SEED_AUDIO_MIN_SECONDS = 3;
+export const SEED_AUDIO_MAX_SECONDS = 120;
+export const SEED_AUDIO_DEFAULT_SECONDS = 15;
+export const ELEVEN_SFX_MIN_SECONDS = 1;
+export const ELEVEN_SFX_MAX_SECONDS = 22;
+export const ELEVEN_SFX_DEFAULT_SECONDS = 4;
+/**
+ * Byte-for-byte the desktop's `clampAudioDuration` in slate/src/shared/pricing.ts,
+ * INCLUDING the non-finite arm — that one matters: `Math.max(min, NaN)` is NaN,
+ * so without it a NaN duration produces the key `seed-audio-NaNs` here while the
+ * desktop quotes the default. Divergence at a value neither side can bill is
+ * still divergence; the checker sweeps for it.
+ */
+function clampAudioSeconds(value, min, max, fallback) {
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.ceil(value)));
+}
+function clampInt(value, min, max) {
+    return Math.min(max, Math.max(min, Math.ceil(value)));
+}
+// Exported for scripts/pricing-consistency-check.mjs (slates-api repo), which
+// asserts this builder byte-matches the desktop's audioCreditKey().
+//
+// Seed Audio has NO duration parameter — length is driven by the prompt text.
+// We bill the REQUESTED duration (shape B, locked 2026-07-31): the desktop
+// injects "... N seconds" into the prompt and bills seed-audio-{N}s, so
+// display == billing with no amendment to the pricing law. The server probes
+// the returned audio.duration afterwards and logs SEED AUDIO BILLING DRIFT.
+export function audioCostKey(input) {
+    if (input.model === 'seed-audio') {
+        // `?? default` before the clamp, not `?? 0` — the desktop resolves a missing
+        // duration to the registry DEFAULT, and a quote that doesn't match what the
+        // desktop would bill is the whole bug class this mirrors away.
+        const secs = clampAudioSeconds(input.durationSeconds ?? SEED_AUDIO_DEFAULT_SECONDS, SEED_AUDIO_MIN_SECONDS, SEED_AUDIO_MAX_SECONDS, SEED_AUDIO_DEFAULT_SECONDS);
+        return `seed-audio-${secs}s`;
+    }
+    if (input.model === 'eleven-sfx') {
+        const secs = clampAudioSeconds(input.durationSeconds ?? ELEVEN_SFX_DEFAULT_SECONDS, ELEVEN_SFX_MIN_SECONDS, ELEVEN_SFX_MAX_SECONDS, ELEVEN_SFX_DEFAULT_SECONDS);
+        return `eleven-sfx-${secs}s`;
+    }
+    throw new Error(`Unknown audio model: ${input.model}`);
+}
 /**
  * Forgiving model-id resolver. Agents routinely paste registry COST keys
  * ("kling-v3-standard-8s", "seedance-2-1080p-8s") into the `model` param —
@@ -1323,6 +1544,13 @@ function resolveVideoModel(raw) {
         'kling-v3.0-omni-pro': 'kling-v3.0-omni',
         'seedance-2.0': 'seedance-2',
         'seedance-2-0': 'seedance-2',
+        // ⚠️ The 2.5 spellings must resolve to 2.5, and the BARE `seedance` must keep
+        // resolving to 2.0 — 2.0 is the default video model and holds 1080p/4K, which
+        // 2.5 does not have at all.
+        'seedance-2.5': 'seedance-2.5',
+        'seedance-25': 'seedance-2.5',
+        'seedance-2-5': 'seedance-2.5',
+        'seedance2.5': 'seedance-2.5',
         seedance: 'seedance-2',
         'veo-3.1': 'veo-3.1-fast',
         'veo-3': 'veo-3.1-fast',
@@ -1345,6 +1573,11 @@ function promptingSkillFor(model) {
         return 'slates-prompting-kling-v3';
     if (model.startsWith('veo'))
         return 'slates-prompting-veo-3';
+    // 2.5 BEFORE the generic seedance test — "seedance-2.5" also starts with
+    // "seedance", and falling through hands 2.0's guide to a model with different
+    // limits, a different resolution ladder and an extra task type.
+    if (model.startsWith('seedance-2.5'))
+        return 'slates-prompting-seedance-2-5';
     if (model.startsWith('seedance'))
         return 'slates-prompting-seedance';
     if (model.startsWith('omni-flash'))
@@ -1353,23 +1586,30 @@ 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-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) — 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 | 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, 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.'),
+        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.'),
         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(15).optional().describe('Seconds. Kling: 5-15. Veo: 4, 6, or 8 only (4K only at 8s). Seedance: 4-15. Omni Flash: 3-10. Default 5 if omitted but always be explicit (cost scales linearly).'),
-        videoResolution: z.enum(['480p', '720p', '1080p', '4k']).optional().describe('Veo + Seedance. Seedance: 480p/720p/1080p/4K (default 1080p; 4K is native, the most expensive). Veo: 720p/1080p same price, 4K more (8s only).'),
+        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) — it has no 1080p and no 4K on any provider, so asking for one is rejected, not downgraded. Veo: 720p/1080p same price, 4K more (8s only).'),
         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(9).optional().describe('Visual reference / ingredient assets (UUIDs or badge codes) for Kling Omni, Seedance, or Omni Flash. Up to 9 (Seedance), 4 (Kling), or 7 (Omni Flash, combined across all ref params).'),
+        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.'),
         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.'),
-        videoReferenceAssetId: z.string().optional().describe('Seedance ONLY: an existing VIDEO asset (UUID or badge code) to use as a reference — edit/relocate a clip, or MOTION TRANSFER (pair with a subject in ingredientAssetIds and a prompt like "the character from image 1 performs the motion from video 1"). 2-15s. Billing switches to input+output seconds (the vref key) — pass videoReferenceSeconds so the quote is right. If the clip contains a human/AI character, pair with seedanceFace=true (the default Seedance route blocks people). Ignored by Kling/Veo.'),
-        videoReferenceSeconds: z.number().optional().describe('REQUIRED with videoReferenceAssetId: the reference clip\'s duration in seconds (from the asset listing). Feeds the vref cost key — a video-reference gen bills combined input+output seconds; the server re-derives this by probing the clip, so an understated value just gets corrected upward.'),
-        audioReferenceAssetId: z.string().optional().describe('Seedance ONLY: an AUDIO asset (UUID or badge code), ≤15s, used as a reference — e.g. lip-sync a character to this audio ("the character in image 1 speaks the dialogue from audio 1"). No billing surcharge (Seedance audio is included). Requires at least one image or video reference alongside.'),
+        videoReferenceAssetId: z.string().optional().describe('DEPRECATED — forwarded into videoReferenceAssetIds; prefer that for anything new. A single VIDEO asset (UUID or badge code) used as a reference. Kept working forever: installed CLI and MCP builds send this shape.'),
+        videoReferenceSeconds: z.number().optional().describe('DEPRECATED — the singular partner of videoReferenceSecondsEach. Required with videoReferenceAssetId: that clip\'s duration in seconds.'),
+        audioReferenceAssetId: z.string().optional().describe('DEPRECATED — forwarded into audioReferenceAssetIds; prefer that. A single AUDIO asset (UUID or badge code) used as a reference.'),
+        // ── Multimodal references, the plural surface ──
+        // The capacity sentences are DERIVED from MODEL_FACTS (see
+        // multimodalRefSummary) rather than hand-typed, so a cap change in one
+        // place cannot leave a stale number in a description an LLM reads.
+        videoReferenceAssetIds: z.array(z.string()).optional().describe(`Reference VIDEOS (UUIDs or badge codes) read alongside the images and audio in the same generation — own-footage restyle, MOTION TRANSFER ("the character from image 1 performs the motion from video 1"), or dialogue conditioning. Cited in the prompt as "video 1", "video 2"… in the order given. ${multimodalRefModels().join(' / ')} only; ignored elsewhere. ${multimodalRefSummary('seedance-2')} ${multimodalRefSummary('seedance-2.5')} Billing switches to combined input+output seconds (the vref key) — pass videoReferenceSecondsEach so the quote is right. If any clip contains a human/AI character, pair with seedanceFace=true (the default Seedance route blocks people). Over the cap is REFUSED, never trimmed: a dropped clip would already have been priced in.`),
+        videoReferenceSecondsEach: z.array(z.number()).optional().describe('REQUIRED with videoReferenceAssetIds, same order and length: each reference clip\'s duration in seconds (from the asset listing). Feeds the vref cost key — the bill is Σceil(each) + output seconds. The server re-derives this by probing every uploaded clip, so an understated value just gets corrected upward.'),
+        audioReferenceAssetIds: z.array(z.string()).optional().describe(`Reference AUDIO clips (UUIDs or badge codes) read alongside the images and video — e.g. lip-sync a character to a line ("the character in image 1 speaks the dialogue from audio 1"). Cited as "audio 1", "audio 2"… in the order given. No billing surcharge (Seedance audio is included). ${multimodalRefSummary('seedance-2')} ${multimodalRefSummary('seedance-2.5')}`),
         sound: z.boolean().optional().describe('Kling Omni / Veo / Seedance: enable audio generation. Default true.'),
         audioLanguage: z.enum(['EN', 'ZH', 'JA', 'KO', 'ES']).optional().describe('Kling Omni only — language for dialogue.'),
         generateMusic: z.boolean().optional().describe('Kling Omni only — auto-generate background music.'),
@@ -1438,7 +1678,10 @@ export const generateVideo = {
                     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) {
+            if (input.lastFrameAssetId ||
+                input.videoReferenceAssetId || input.audioReferenceAssetId ||
+                (input.videoReferenceAssetIds?.length ?? 0) > 0 ||
+                (input.audioReferenceAssetIds?.length ?? 0) > 0) {
                 return ok({
                     requires_clarification: true,
                     missing: [],
@@ -1499,6 +1742,10 @@ export const generateVideo = {
             refInputs.push({ ref: input.videoReferenceAssetId, role: 'video reference' });
         if (input.audioReferenceAssetId)
             refInputs.push({ ref: input.audioReferenceAssetId, role: 'audio reference' });
+        for (const r of input.videoReferenceAssetIds ?? [])
+            refInputs.push({ ref: r, role: 'video reference' });
+        for (const r of input.audioReferenceAssetIds ?? [])
+            refInputs.push({ ref: r, role: 'audio reference' });
         const resolvedRefs = await resolveAssetRefs(ctx, input.projectId, refInputs.map((r) => r.ref));
         const rid = (v) => v ? (resolvedRefs.get(v)?.id ?? v) : v;
         const rids = (a) => a?.map((v) => resolvedRefs.get(v)?.id ?? v);
@@ -1506,6 +1753,8 @@ export const generateVideo = {
         input.lastFrameAssetId = rid(input.lastFrameAssetId);
         input.videoReferenceAssetId = rid(input.videoReferenceAssetId);
         input.audioReferenceAssetId = rid(input.audioReferenceAssetId);
+        input.videoReferenceAssetIds = rids(input.videoReferenceAssetIds);
+        input.audioReferenceAssetIds = rids(input.audioReferenceAssetIds);
         input.ingredientAssetIds = rids(input.ingredientAssetIds);
         input.characterAssetIds = rids(input.characterAssetIds);
         input.environmentAssetIds = rids(input.environmentAssetIds);
@@ -1514,13 +1763,59 @@ export const generateVideo = {
         // A video reference bills combined input+output seconds (the vref key) —
         // the quote needs the clip's length. The server probes the uploaded ref
         // and corrects the key anyway, so this only gates quote accuracy.
-        if (input.videoReferenceAssetId && input.model.startsWith('seedance') && !input.videoReferenceSeconds) {
+        // 🚨 Seedance 2.5 PROMPT-INTENT PRE-FLIGHT. With references attached, the
+        // provider sorts a request into one of five task types from the roles PLUS
+        // the prompt's intent, then fails a mismatch ASYNCHRONOUSLY — after the task
+        // queues and credits are reserved. Catch it before the spend, NAME the words,
+        // and never rewrite the prompt (the prompt-transparency invariant).
+        if (input.model === 'seedance-2.5') {
+            // 🚨 EVERY reference shape counts, singular AND plural. The classifier
+            // engages on the presence of reference ROLES, and the plural arrays are
+            // the surface new callers use — listing only the deprecated singular ones
+            // meant the modern call path got no warning at all, which is precisely
+            // backwards.
+            const hasRefs = !!input.firstFrameAssetId || !!input.lastFrameAssetId ||
+                (input.ingredientAssetIds?.length ?? 0) > 0 ||
+                (input.characterAssetIds?.length ?? 0) > 0 ||
+                (input.environmentAssetIds?.length ?? 0) > 0 ||
+                (input.styleAssetIds?.length ?? 0) > 0 ||
+                !!input.videoReferenceAssetId || !!input.audioReferenceAssetId ||
+                (input.videoReferenceAssetIds?.length ?? 0) > 0 ||
+                (input.audioReferenceAssetIds?.length ?? 0) > 0;
+            // Trigger words are DERIVED from the model-facts SSOT, not retyped here —
+            // a local literal had already lost 'continue the story'.
+            const hits = hasRefs ? seedanceTaskIntentWords(input.prompt) : [];
+            if (hits.length > 0 && !input.confirm) {
+                return ok({
+                    requires_clarification: true,
+                    missing: ['prompt'],
+                    message: `Seedance 2.5 reads ${hits.map((w) => `"${w}"`).join(', ')} in this prompt as an EDIT or EXTEND instruction and may run it as a video edit, ` +
+                        `which fails after the job has queued. If you mean to edit an existing clip, call slates_edit_video with model "seedance-2.5-edit". ` +
+                        `If you mean a fresh shot, describe the finished frame instead of an instruction to change one ("the workshop bench, clear and uncluttered" rather than "remove the tripod"). ` +
+                        `Pass confirm=true to send it as written.`,
+                });
+            }
+        }
+        // The quote needs a length for EVERY reference clip, in both shapes. A
+        // missing one doesn't fail the generation (the server probes and corrects
+        // upward) — it silently under-quotes, which is worse than asking.
+        const isSeedance = input.model.startsWith('seedance');
+        if (input.videoReferenceAssetId && isSeedance && !input.videoReferenceSeconds) {
             return ok({
                 requires_clarification: true,
                 missing: ['videoReferenceSeconds'],
                 message: 'A Seedance video reference bills on combined input+output seconds. Pass videoReferenceSeconds (the reference clip\'s duration, shown in slates_list_assets) so the pre-flight quote matches the bill.',
             });
         }
+        const pluralRefCount = input.videoReferenceAssetIds?.length ?? 0;
+        if (pluralRefCount > 0 && isSeedance &&
+            (input.videoReferenceSecondsEach?.length ?? 0) !== pluralRefCount) {
+            return ok({
+                requires_clarification: true,
+                missing: ['videoReferenceSecondsEach'],
+                message: `A Seedance video reference bills on combined input+output seconds. Pass videoReferenceSecondsEach with exactly ${pluralRefCount} duration${pluralRefCount === 1 ? '' : 's'}, in the same order as videoReferenceAssetIds (durations are shown in slates_list_assets), so the pre-flight quote matches the bill.`,
+            });
+        }
         const cloud = ctx.cloud();
         const registry = await cloud.get('/api/agent/models');
         const costKey = videoCostKey({
@@ -1530,7 +1825,13 @@ export const generateVideo = {
             sound: input.sound,
             seedanceFace: input.seedanceFace,
             seedanceRealFace: input.seedanceRealFace,
-            videoRefSeconds: input.videoReferenceAssetId ? input.videoReferenceSeconds : 0,
+            // Σ 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.
+            videoRefSeconds: (input.videoReferenceAssetId && input.videoReferenceSeconds
+                ? Math.ceil(input.videoReferenceSeconds - 0.05)
+                : 0) +
+                (input.videoReferenceSecondsEach ?? []).reduce((n, d) => n + (d > 0 ? Math.ceil(d - 0.05) : 0), 0),
         });
         // Hard consent gate, checked before any spend: the real-face route is
         // consent-attested by design (the desktop enforces it too).
@@ -1624,8 +1925,13 @@ export const generateVideo = {
             characterAssetIds: input.characterAssetIds ?? [],
             environmentAssetIds: input.environmentAssetIds ?? [],
             styleAssetIds: input.styleAssetIds ?? [],
+            // Both shapes on the wire. The route merges and dedupes them, so an old
+            // client sending only the singular and a new one sending only the plural
+            // reach the identical handler params.
             videoReferenceAssetId: input.videoReferenceAssetId,
             audioReferenceAssetId: input.audioReferenceAssetId,
+            videoReferenceAssetIds: input.videoReferenceAssetIds,
+            audioReferenceAssetIds: input.audioReferenceAssetIds,
             sound: input.sound,
             audioLanguage: input.audioLanguage,
             generateMusic: input.generateMusic,
@@ -1671,30 +1977,179 @@ export const generateVideo = {
         };
     },
 };
+// ── Generate audio ──────────────────────────────────────────────
+export const generateAudio = {
+    id: 'slates_generate_audio',
+    description: 'Generate AUDIO via Slates credits — the third media type, saved as a project asset you can drop on an audio track. Two surfaces: seed-audio (default; a whole audio SCENE — dialogue + SFX + ambience — from one plain sentence, 3-120s) and eleven-sfx (ONE effect with an exact 1-22s duration, or a seamless loop). Which surface for which job: read the slates-model-selection skill. ' +
+        '🚨 seed-audio has NO duration parameter — the length you pass is written INTO THE PROMPT and is what the user is BILLED, whatever comes back. Choose it deliberately. ' +
+        'REQUIRED before calling: read slates-cost-discipline and the matching prompting skill (slates-prompting-seed-audio | slates-prompting-elevenlabs). Kling\'s "SFX:" / "Ambient noise:" prompt syntax does NOT transfer to seed-audio and makes results worse. ' +
+        'projectId is REQUIRED (no headless path). Cost > 17 credits returns requires_confirm — pass confirm=true after explicit user OK. No skill files installed? Call slates_get_prompting_guide first.',
+    input: z.object({
+        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.'),
+        prompt: z
+            .string()
+            .min(1)
+            .max(5000)
+            .describe('seed-audio: ONE plain sentence describing the scene (no production jargon, no "SFX:" prefixes; name the crowd/room size). eleven-sfx: the effect described by its physical CAUSE ("heavy oak door slams shut in a stone hallway"), max 450 chars.'),
+        durationSeconds: z
+            .number()
+            .optional()
+            .describe('seed-audio 3-120 (default 15) — ⚠️ THIS IS THE BILL: it is appended to the prompt and charged regardless of the returned length. eleven-sfx 1-22 (default 4) — always sent explicitly so the per-second charge is deterministic.'),
+        voice: z
+            .string()
+            .optional()
+            .describe('seed-audio only — a preset voice id (e.g. "cedric_en_zh"). Leave unset to let the scene cast itself, which is usually right for background dialogue. Agent-facing only: there is no user-facing voice picker.'),
+        speed: z.number().min(0.5).max(2).optional().describe('seed-audio only — 0.5-2.0. Reach for it when dialogue races or drags against picture.'),
+        volume: z.number().min(0.5).max(2).optional().describe('seed-audio only — output gain, 0.5-2.0 (1 = unchanged). Prefer the timeline track fader for mix decisions; this is for when the model itself renders a scene too hot or too quiet.'),
+        pitch: z.number().int().min(-12).max(12).optional().describe('seed-audio only — semitones. Small moves; ±3 is already a lot.'),
+        multilingual: z.boolean().optional().describe('seed-audio only — better non-English / mixed-language handling.'),
+        loop: z.boolean().optional().describe('eleven-sfx only — produce a seamless loop (rain, engine hum, crowd murmur).'),
+        promptInfluence: z.number().min(0).max(1).optional().describe('eleven-sfx only — 0-1, default 0.3. Higher hugs your wording with less variation between takes.'),
+        audioReferenceAssetIds: z
+            .array(z.string())
+            .max(3)
+            .optional()
+            .describe('seed-audio only — up to 3 AUDIO assets (UUIDs or badge codes like "AUD-S1"), each ≤30s, referenced in the prompt as @Audio1-@Audio3 ("match the room tone of @Audio1"). MUTUALLY EXCLUSIVE with imageReferenceAssetId — the API rejects both.'),
+        imageReferenceAssetId: z
+            .string()
+            .optional()
+            .describe('seed-audio only — ONE image asset to score what is in frame. MUTUALLY EXCLUSIVE with audioReferenceAssetIds.'),
+        background: z.boolean().optional().describe(BACKGROUND_DESCRIBE),
+        confirm: z.boolean().optional().describe('Set true to bypass the confirm gate after explicit user OK.'),
+    }),
+    run: async (input, ctx) => {
+        // ── Per-surface clarification + constraint gates ──
+        const cfgDefaults = {
+            'seed-audio': SEED_AUDIO_DEFAULT_SECONDS,
+            'eleven-sfx': ELEVEN_SFX_DEFAULT_SECONDS,
+        };
+        const seconds = input.durationSeconds ?? cfgDefaults[input.model];
+        if (input.model === 'seed-audio') {
+            if (seconds < SEED_AUDIO_MIN_SECONDS || seconds > SEED_AUDIO_MAX_SECONDS) {
+                return ok({
+                    requires_clarification: true,
+                    missing: ['durationSeconds'],
+                    message: `Seed Audio needs a durationSeconds of ${SEED_AUDIO_MIN_SECONDS}-${SEED_AUDIO_MAX_SECONDS}. It has NO duration parameter — the number is written into the prompt AND is what the user is billed, so it must be a deliberate choice. Ask the user how long the bed should be (a few seconds longer than the clip it sits under, so the edit has handles).`,
+                });
+            }
+            if ((input.audioReferenceAssetIds?.length ?? 0) > 0 && input.imageReferenceAssetId) {
+                throw new Error('Seed Audio takes audio references OR one image reference, never both — the provider rejects the combination.');
+            }
+        }
+        if (input.model === 'eleven-sfx') {
+            if (seconds < ELEVEN_SFX_MIN_SECONDS || seconds > ELEVEN_SFX_MAX_SECONDS) {
+                return ok({
+                    requires_clarification: true,
+                    missing: ['durationSeconds'],
+                    message: `Sound Effects needs a durationSeconds of ${ELEVEN_SFX_MIN_SECONDS}-${ELEVEN_SFX_MAX_SECONDS}. It is billed per second and is never left for the model to pick (that would make the charge non-deterministic). Roughly: 0.5-1s for an impact, 2-4s for a whoosh, 8-22s for a loopable bed.`,
+                });
+            }
+            if (input.prompt.length > 450) {
+                throw new Error(`Sound Effects accepts up to 450 characters — this prompt is ${input.prompt.length}.`);
+            }
+        }
+        await ctx.desktop().requireCapability('audio-generation', 'audio generation');
+        // ── Resolve asset refs at CALL time (UUIDs or badge codes) ──
+        const refInputs = [];
+        for (const ref of input.audioReferenceAssetIds ?? [])
+            refInputs.push({ ref, role: 'audio reference' });
+        if (input.imageReferenceAssetId)
+            refInputs.push({ ref: input.imageReferenceAssetId, role: 'image reference' });
+        const resolvedRefs = refInputs.length > 0
+            ? await resolveAssetRefs(ctx, input.projectId, refInputs.map((r) => r.ref))
+            : new Map();
+        const rid = (v) => (v ? (resolvedRefs.get(v)?.id ?? v) : v);
+        const refEcho = refInputs.length > 0 ? describeResolvedRefs(refInputs, resolvedRefs) : '';
+        // ── Cost — from the CLOUD registry, keyed by the SAME builder the desktop
+        //    and the proxy use. Never quote a price from memory. ──
+        const cloud = ctx.cloud();
+        const registry = await cloud.get('/api/agent/models');
+        const costKey = audioCostKey({
+            model: input.model,
+            durationSeconds: seconds,
+        });
+        const entry = registry.models.find((m) => m.model === costKey);
+        if (!entry) {
+            throw new Error(`Audio variant not in registry: ${costKey}. Available audio models: ${AUDIO_MODELS.join(' | ')}.`);
+        }
+        const totalCents = creditCost(entry);
+        if (!input.confirm && totalCents > CONFIRM_CREDITS) {
+            return ok({
+                requires_confirm: true,
+                model: input.model,
+                variant: costKey,
+                cost_credits: totalCents,
+                cost_display: fmtCredits(totalCents),
+                message: `${input.model} audio will cost ${fmtCredits(totalCents)}. ` +
+                    (input.model === 'seed-audio'
+                        ? `You are billed for the ${seconds}s you requested regardless of the returned length. `
+                        : '') +
+                    'Confirm with the user, then call again with confirm: true.',
+            });
+        }
+        // ── Submit through the DESKTOP so the progress card, the project save,
+        //    and recovery all behave exactly like a UI-triggered run. ──
+        const desktop = ctx.desktop();
+        if (input.background) {
+            await desktop.requireCapability('background-generation', 'background generation');
+        }
+        const result = await desktop.post('/agent/generation/audio', {
+            projectId: input.projectId,
+            model: input.model,
+            prompt: input.prompt,
+            durationSeconds: seconds,
+            voice: input.voice,
+            speed: input.speed,
+            volume: input.volume,
+            pitch: input.pitch,
+            multilingual: input.multilingual,
+            loop: input.loop,
+            promptInfluence: input.promptInfluence,
+            audioReferenceAssetIds: (input.audioReferenceAssetIds ?? []).map((r) => rid(r)),
+            imageReferenceAssetId: rid(input.imageReferenceAssetId),
+            background: input.background,
+        });
+        if (!result.success)
+            throw new Error(result.error ?? 'Audio generation failed');
+        if (result.background) {
+            return backgroundSubmitted(`${input.model} audio generation`, [result.generationId].filter(Boolean), { model: input.model, variant: costKey, projectId: input.projectId, cost_credits: totalCents }, refEcho);
+        }
+        return {
+            text: `Generated ${input.model} audio into project ${input.projectId} for ${fmtCredits(totalCents)}` +
+                `. Prompt: "${input.prompt.slice(0, 60)}${input.prompt.length > 60 ? '...' : ''}"` +
+                (refEcho ? ` ${refEcho}` : ''),
+            data: {
+                model: input.model,
+                variant: costKey,
+                projectId: input.projectId,
+                durationSeconds: seconds,
+                cost_cents: totalCents,
+                cost_credits: totalCents,
+                asset: result.asset,
+                generationId: result.generationId,
+            },
+        };
+    },
+};
 // ── Generate lip-sync ───────────────────────────────────────────
 export const generateLipSync = {
     id: 'slates_generate_lip_sync',
-    description: 'Lip-sync a still image (avatar) or a video clip to audio. Two engines — route per slates-model-selection: (1) engine=kling (default, cheap utility lane): sourceType=video re-syncs a clip (~$0.11 / 5s); sourceType=image animates a still avatar (avatar-standard ~$0.42 / 5s; avatar-pro ~$0.86 / 5s). Audio from TTS (ttsText + ttsVoice) or an uploaded file. Always 5 seconds. (2) engine=seedance-2 (premium single-pass): the speech is generated IN the video itself — natural delivery, a video source keeps its OWN voice (native voice clone), audio included; ttsText becomes the spoken line (no voice/speed params), or an uploaded ≤15s audio file drives the speech as a reference. Seedance sources must be 2-15s videos or images; bills seedance keys (video sources bill input+output seconds — pass sourceSeconds). Faces route via seedanceFace (default true) / seedanceRealFace+realFaceConsent for real people. REQUIRED before calling: slates-cost-discipline + slates-prompting-lip-sync skills. projectId is REQUIRED.',
+    description: 'Lip-sync a still image (avatar) or a video clip to audio. KLING-ONLY — this tool wraps Kling\'s dedicated lip-sync endpoints and nothing else: sourceType=video re-syncs a clip (~$0.11 / 5s); sourceType=image animates a still avatar (avatar-standard ~$0.42 / 5s; avatar-pro ~$0.86 / 5s). Audio from TTS (ttsText + ttsVoice) or an uploaded file. Always 5 seconds. For a Seedance version, do NOT look for an engine switch here — run a normal slates_generate_video on seedance-2 with the clip attached as a video reference and the dialogue written into the prompt; that is the same call, with the prompt visible and editable. REQUIRED before calling: slates-cost-discipline + slates-prompting-lip-sync skills. projectId is REQUIRED.',
     input: z.object({
         projectId: z.string().uuid().describe('Slates project the source asset lives in. The new lip-synced video lands here.'),
         sourceAssetId: z.string().uuid().describe('Asset id of the still image (avatar flow) or video clip (lip-sync flow). Must already exist in the project — use slates_upload_reference_image or slates_generate_image / slates_generate_video first if needed.'),
         sourceType: z.enum(['image', 'video']).describe('"image" = animate a still portrait (avatar). "video" = re-sync an existing talking-head clip. Determines pricing — be deliberate.'),
-        audioMethod: z.enum(['tts', 'upload']).describe('"tts" = generate speech from ttsText (on Seedance the line is spoken natively in the generation). "upload" = use the file at audioFilePath (absolute path on the user\'s machine; ≤15s on Seedance).'),
+        audioMethod: z.enum(['tts', 'upload']).describe('"tts" = generate speech from ttsText. "upload" = use the file at audioFilePath (absolute path on the user\'s machine).'),
         ttsText: z.string().min(1).max(2000).optional().describe('Required when audioMethod=tts. The exact words the avatar/clip will speak.'),
-        ttsVoice: z.string().optional().describe('Kling engine only — voice id (e.g. "oversea_male1"). See slates-prompting-lip-sync skill for the voice catalog. Ignored on Seedance (a video source keeps its own voice; otherwise describe the voice in ttsText context).'),
-        ttsLanguage: z.enum(['EN', 'ZH', 'JA', 'KO', 'ES']).optional().describe('Kling engine only — TTS language. Default EN.'),
-        ttsSpeed: z.number().min(0.5).max(2).optional().describe('Kling engine only — TTS speech rate. Default 1.0. Range 0.5-2.0.'),
+        ttsVoice: z.string().optional().describe('Voice id (e.g. "oversea_male1"). See slates-prompting-lip-sync skill for the voice catalog.'),
+        ttsLanguage: z.enum(['EN', 'ZH', 'JA', 'KO', 'ES']).optional().describe('TTS language. Default EN.'),
+        ttsSpeed: z.number().min(0.5).max(2).optional().describe('TTS speech rate. Default 1.0. Range 0.5-2.0.'),
         audioFilePath: z.string().optional().describe('Required when audioMethod=upload. Absolute path to the audio file on the user\'s machine (mp3, wav, m4a).'),
-        avatarModel: z.enum(['avatar-standard', 'avatar-pro']).optional().describe('Kling engine, image-source only. avatar-standard (~14 credits/5s) for general use. avatar-pro (~29 credits/5s) for sharper face fidelity.'),
-        klingProvider: z.enum(['fal', 'kling']).optional().describe('Kling engine only — provider routing. Leave unset: all agent generations bill Slates credits (BYOK is retired).'),
-        engine: z.enum(['kling', 'seedance-2']).optional().describe('Default kling (cheap utility). seedance-2 = premium single-pass: natural speech generated in the video, voice cloned from a video source, audio included. Credits only.'),
-        videoResolution: z.enum(['480p', '720p', '1080p', '4k']).optional().describe('Seedance engine only. Default 1080p.'),
-        aspectRatio: z.string().optional().describe('Seedance engine only. Default 16:9.'),
-        seedanceFace: z.boolean().optional().describe('Seedance engine only — a character\'s face is in the source (default TRUE for lip-sync; the faceless route would reject it). Bills the -face key.'),
-        seedanceRealFace: z.boolean().optional().describe('Seedance engine only — the source shows a REAL person. Premium -realface key; REQUIRES realFaceConsent=true.'),
-        realFaceConsent: z.boolean().optional().describe('MANDATORY with seedanceRealFace — set true only after the user explicitly confirms they hold rights/consent to the likeness.'),
-        sourceSeconds: z.number().optional().describe('Seedance engine + sourceType=video: the source clip\'s duration in seconds (from the asset listing). Feeds the vref cost key (input+output billing).'),
-        audioSeconds: z.number().optional().describe('Seedance engine + audioMethod=upload: the audio file\'s duration in seconds — sets the output length (4-15s).'),
+        avatarModel: z.enum(['avatar-standard', 'avatar-pro']).optional().describe('Image-source only. avatar-standard (~14 credits/5s) for general use. avatar-pro (~29 credits/5s) for sharper face fidelity.'),
+        klingProvider: z.enum(['fal', 'kling']).optional().describe('Provider routing. Leave unset: all agent generations bill Slates credits (BYOK is retired).'),
         background: z.boolean().optional().describe(BACKGROUND_DESCRIBE),
         confirm: z.boolean().optional().describe('Set true to bypass the confirm gate. Required for avatar-pro.'),
     }),
@@ -1713,41 +2168,8 @@ export const generateLipSync = {
                 message: 'audioMethod=upload requires audioFilePath. Pass an absolute path to the audio file on the user\'s machine.',
             });
         }
-        const isSeedance = input.engine === 'seedance-2';
         let costKey;
-        let seedanceDuration = 0;
-        if (isSeedance) {
-            // Consent gate before any spend, mirroring slates_generate_video.
-            if (input.seedanceRealFace && !input.realFaceConsent) {
-                return ok({
-                    requires_clarification: true,
-                    missing: ['realFaceConsent'],
-                    message: 'Real-person lip-sync needs consent: confirm with the user that they hold the rights/consent to this likeness, then retry with realFaceConsent=true.',
-                });
-            }
-            if (input.sourceType === 'video' && !input.sourceSeconds) {
-                return ok({
-                    requires_clarification: true,
-                    missing: ['sourceSeconds'],
-                    message: 'Seedance lip-sync on a video source bills combined input+output seconds. Pass sourceSeconds (the clip\'s duration from slates_list_assets, must be 2-15s).',
-                });
-            }
-            const clamp = (n) => Math.min(15, Math.max(4, Math.ceil(n)));
-            seedanceDuration = clamp(input.sourceType === 'video' && input.sourceSeconds
-                ? input.sourceSeconds
-                : input.audioSeconds ?? (input.ttsText ? input.ttsText.length / 13 : 5));
-            costKey = videoCostKey({
-                model: 'seedance-2',
-                duration: seedanceDuration,
-                videoResolution: input.videoResolution ?? '1080p',
-                // Lip-sync sources are faces by definition — face route unless
-                // explicitly disabled or escalated to realface.
-                seedanceFace: input.seedanceFace !== false && input.seedanceRealFace !== true,
-                seedanceRealFace: input.seedanceRealFace === true,
-                videoRefSeconds: input.sourceType === 'video' ? input.sourceSeconds ?? 0 : 0,
-            });
-        }
-        else if (input.sourceType === 'video') {
+        if (input.sourceType === 'video') {
             costKey = 'kling-lip-sync-video-5s';
         }
         else {
@@ -1776,7 +2198,7 @@ export const generateLipSync = {
                 estimated_cents: totalCents,
                 estimated_credits: totalCents,
                 source_ref: sourceRef,
-                message: `Cost: ${fmtCredits(totalCents)} for ${isSeedance ? `${seedanceDuration}s Seedance` : '5s'} lip-sync (${costKey}). ` +
+                message: `Cost: ${fmtCredits(totalCents)} for 5s lip-sync (${costKey}). ` +
                     `Source: ${sourceRef}. ${audioPreview}. ` +
                     `Re-call with confirm=true after the user explicitly OKs the spend. ` +
                     `When discussing with the user, refer to the source by its code (matches the gallery badge).`,
@@ -1799,28 +2221,12 @@ export const generateLipSync = {
             klingProvider: input.klingProvider,
             estimatedCost: totalCents,
             background: input.background,
-            // Seedance engine passthrough — the desktop delegates to the seedance
-            // ref-to-video path (vref billing, face cascade, consent gate). The
-            // durations ride along so the desktop bills exactly what was quoted.
-            ...(isSeedance
-                ? {
-                    lipSyncEngine: 'seedance-2',
-                    duration: seedanceDuration,
-                    videoResolution: input.videoResolution,
-                    aspectRatio: input.aspectRatio,
-                    seedanceFace: input.seedanceFace !== false && input.seedanceRealFace !== true,
-                    seedanceRealFace: input.seedanceRealFace === true,
-                    realFaceConsent: input.realFaceConsent === true,
-                    sourceDurationSeconds: input.sourceSeconds,
-                    audioDurationSeconds: input.audioSeconds,
-                }
-                : {}),
         });
         if (!result.success)
             throw new Error(result.error ?? 'Lip-sync generation failed');
         if (result.background) {
             const ids = result.generationIds ?? (result.generationId ? [result.generationId] : []);
-            return backgroundSubmitted(`${isSeedance ? `${seedanceDuration}s` : '5s'} lip-sync (${costKey})`, ids, {
+            return backgroundSubmitted(`5s lip-sync (${costKey})`, ids, {
                 variant: costKey,
                 projectId: input.projectId,
                 sourceAssetId: input.sourceAssetId,
@@ -1829,7 +2235,7 @@ export const generateLipSync = {
             });
         }
         return {
-            text: `Generated ${isSeedance ? `${seedanceDuration}s` : '5s'} lip-sync (${costKey}) into project ${input.projectId} ` +
+            text: `Generated 5s lip-sync (${costKey}) into project ${input.projectId} ` +
                 `for ${fmtCredits(totalCents)}. ` +
                 (input.audioMethod === 'tts'
                     ? `Spoken: "${(input.ttsText ?? '').slice(0, 60)}${(input.ttsText ?? '').length > 60 ? '...' : ''}"`
@@ -1850,58 +2256,21 @@ export const generateLipSync = {
 // ── Generate motion transfer ────────────────────────────────────
 export const generateMotionTransfer = {
     id: 'slates_generate_motion_transfer',
-    description: 'Transfer the motion from a reference video onto a target image character. Two engines — route per slates-model-selection: (1) kling-mc-std ($0.95 / 5s) / kling-mc-pro ($1.26 / 5s) — the cheap utility lane, structured skeleton/depth retargeting, always 5s. (2) motionModel=seedance-2 — the PREMIUM lane: single-pass generation with the driving clip as a native conditioning signal (better motion fidelity + native audio), prompt-driven (write what the character does, e.g. "the character from image 1 performs the exact motion from video 1"), bills input+output seconds on seedance vref keys (pass sourceVideoSeconds; driving clip must be 2-15s). Faces: seedanceFace defaults true; a REAL person needs seedanceRealFace+realFaceConsent (premium route). REQUIRED before calling: slates-cost-discipline + slates-prompting-motion-transfer skills. projectId is REQUIRED — both assets must exist in the project. All tiers hit the >$0.50 confirm gate.',
+    description: 'Transfer the motion from a reference video onto a target image character. KLING-ONLY — this tool wraps Kling Motion Control and nothing else: kling-mc-std ($0.95 / 5s) or kling-mc-pro ($1.26 / 5s), structured skeleton/depth retargeting, always 5s. For a Seedance version, do NOT look for an engine switch here — run a normal slates_generate_video on seedance-2 with the driving clip attached as a video reference and the motion described in the prompt ("the character from image 1 performs the exact motion from video 1"); that is the same call, with the prompt visible and editable. REQUIRED before calling: slates-cost-discipline + slates-prompting-motion-transfer skills. projectId is REQUIRED — both assets must exist in the project. Both tiers hit the >$0.50 confirm gate.',
     input: z.object({
         projectId: z.string().uuid().describe('Slates project. Both source and target assets must live here.'),
-        sourceVideoAssetId: z.string().uuid().describe('Asset id of the reference video — its motion will be retargeted onto the target image. Must already exist in the project. Seedance engine: 2-15s clips only.'),
+        sourceVideoAssetId: z.string().uuid().describe('Asset id of the reference video — its motion will be retargeted onto the target image. Must already exist in the project. Up to 30s.'),
         targetImageAssetId: z.string().uuid().describe('Asset id of the target image (the character that will perform the motion). Must already exist in the project.'),
-        motionModel: z.enum(['kling-mc-std', 'kling-mc-pro', 'seedance-2']).optional().describe('kling-mc-std (~32 credits) general motion; kling-mc-pro (~42 credits) cleaner anatomy — default. seedance-2 = premium single-pass lane (prompt-driven, native audio, input+output-second billing) — pick when motion fidelity or audio matters.'),
-        characterOrientation: z.enum(['video', 'image']).optional().describe('Kling only. "video" = use the source video\'s framing. "image" = use the target image\'s framing. Default video.'),
-        prompt: z.string().optional().describe('Kling: optional refinement. Seedance: THE driver — describe what the character does with the motion from the clip (ordinal references: "the character from image 1 performs the motion from video 1"). A sensible default recipe is used if omitted. Read slates-prompting-motion-transfer.'),
-        klingProvider: z.enum(['fal', 'kling']).optional().describe('Kling engine only — provider routing. "fal" (default) uses Slates credits.'),
-        duration: z.number().int().min(4).max(15).optional().describe('Seedance engine only — output duration in seconds (4-15). Defaults to the driving clip\'s length.'),
-        videoResolution: z.enum(['480p', '720p', '1080p', '4k']).optional().describe('Seedance engine only. Default 1080p.'),
-        aspectRatio: z.string().optional().describe('Seedance engine only. Default 16:9.'),
-        seedanceFace: z.boolean().optional().describe('Seedance engine only — a character\'s face is in the clip/image (default TRUE for motion transfer). Bills the -face key.'),
-        seedanceRealFace: z.boolean().optional().describe('Seedance engine only — the driving clip/subject shows a REAL person. Premium -realface key; REQUIRES realFaceConsent=true.'),
-        realFaceConsent: z.boolean().optional().describe('MANDATORY with seedanceRealFace — set true only after the user explicitly confirms they hold rights/consent to the likeness.'),
-        sourceVideoSeconds: z.number().optional().describe('Seedance engine: the driving clip\'s duration in seconds (from the asset listing, 2-15s). Feeds the vref cost key (input+output billing).'),
+        motionModel: z.enum(['kling-mc-std', 'kling-mc-pro']).optional().describe('kling-mc-std (~32 credits) general motion; kling-mc-pro (~42 credits) cleaner anatomy — default.'),
+        characterOrientation: z.enum(['video', 'image']).optional().describe('"video" = use the source video\'s framing. "image" = use the target image\'s framing. Default video.'),
+        prompt: z.string().optional().describe('Optional refinement. Read slates-prompting-motion-transfer.'),
+        klingProvider: z.enum(['fal', 'kling']).optional().describe('Provider routing. "fal" (default) uses Slates credits.'),
         background: z.boolean().optional().describe(BACKGROUND_DESCRIBE),
         confirm: z.boolean().optional().describe('Set true to bypass the confirm gate. Required — both tiers exceed.'),
     }),
     async run(input, ctx) {
         const motionModel = input.motionModel ?? 'kling-mc-pro';
-        const isSeedance = motionModel === 'seedance-2';
-        let costKey;
-        let seedanceDuration = 0;
-        if (isSeedance) {
-            if (input.seedanceRealFace && !input.realFaceConsent) {
-                return ok({
-                    requires_clarification: true,
-                    missing: ['realFaceConsent'],
-                    message: 'Real-person motion transfer needs consent: confirm with the user that they hold the rights/consent to this likeness, then retry with realFaceConsent=true.',
-                });
-            }
-            if (!input.sourceVideoSeconds) {
-                return ok({
-                    requires_clarification: true,
-                    missing: ['sourceVideoSeconds'],
-                    message: 'Seedance motion transfer bills combined input+output seconds. Pass sourceVideoSeconds (the driving clip\'s duration from slates_list_assets, must be 2-15s).',
-                });
-            }
-            seedanceDuration = input.duration ?? Math.min(15, Math.max(4, Math.ceil(input.sourceVideoSeconds)));
-            costKey = videoCostKey({
-                model: 'seedance-2',
-                duration: seedanceDuration,
-                videoResolution: input.videoResolution ?? '1080p',
-                seedanceFace: input.seedanceFace !== false && input.seedanceRealFace !== true,
-                seedanceRealFace: input.seedanceRealFace === true,
-                videoRefSeconds: input.sourceVideoSeconds,
-            });
-        }
-        else {
-            costKey = motionModel === 'kling-mc-std' ? 'kling-mc-std-5s' : 'kling-mc-pro-5s';
-        }
+        const costKey = motionModel === 'kling-mc-std' ? 'kling-mc-std-5s' : 'kling-mc-pro-5s';
         const cloud = ctx.cloud();
         const registry = await cloud.get('/api/agent/models');
         const entry = registry.models.find((m) => m.model === costKey);
@@ -1925,9 +2294,9 @@ export const generateMotionTransfer = {
                 estimated_credits: totalCents,
                 source_ref: source,
                 target_ref: target,
-                message: `Cost: ${fmtCredits(totalCents)} for ${isSeedance ? `${seedanceDuration}s Seedance motion transfer` : `5s ${motionModel}`} (${costKey}). ` +
+                message: `Cost: ${fmtCredits(totalCents)} for 5s ${motionModel} (${costKey}). ` +
                     `Transferring motion from ${source} onto ${target}. ` +
-                    `Re-call with confirm=true after the user explicitly OKs the spend${isSeedance ? '' : ', or pick kling-mc-std to save ~10 credits'}. ` +
+                    `Re-call with confirm=true after the user explicitly OKs the spend, or pick kling-mc-std to save ~10 credits. ` +
                     `When discussing with the user, refer to the assets by those codes — they'll match the gallery badges.`,
             });
         }
@@ -1945,27 +2314,12 @@ export const generateMotionTransfer = {
             klingProvider: input.klingProvider,
             estimatedCost: totalCents,
             background: input.background,
-            // Seedance engine passthrough — the desktop delegates to the seedance
-            // ref-to-video path (vref billing, face cascade, consent gate).
-            ...(isSeedance
-                ? {
-                    duration: seedanceDuration,
-                    videoResolution: input.videoResolution,
-                    aspectRatio: input.aspectRatio,
-                    seedanceFace: input.seedanceFace !== false && input.seedanceRealFace !== true,
-                    seedanceRealFace: input.seedanceRealFace === true,
-                    realFaceConsent: input.realFaceConsent === true,
-                    // Ride the caller-supplied clip duration through — the asset row's
-                    // duration can be null for imported clips.
-                    sourceVideoDurationSeconds: input.sourceVideoSeconds,
-                }
-                : {}),
         });
         if (!result.success)
             throw new Error(result.error ?? 'Motion transfer generation failed');
         if (result.background) {
             const ids = result.generationIds ?? (result.generationId ? [result.generationId] : []);
-            return backgroundSubmitted(`${isSeedance ? `${seedanceDuration}s` : '5s'} motion transfer (${motionModel})`, ids, {
+            return backgroundSubmitted(`5s motion transfer (${motionModel})`, ids, {
                 variant: costKey,
                 motionModel,
                 projectId: input.projectId,
@@ -1976,7 +2330,7 @@ export const generateMotionTransfer = {
             });
         }
         return {
-            text: `Generated ${isSeedance ? `${seedanceDuration}s` : '5s'} motion transfer (${motionModel}) into project ${input.projectId} ` +
+            text: `Generated 5s motion transfer (${motionModel}) into project ${input.projectId} ` +
                 `for ${fmtCredits(totalCents)}.` +
                 (input.prompt ? ` Prompt: "${input.prompt.slice(0, 60)}${input.prompt.length > 60 ? '...' : ''}"` : ''),
             data: {
@@ -1996,15 +2350,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) or omni-flash-edit (Gemini Omni Flash; 3–10s clips, 720p output, PROMPT-ONLY — no refs, cheapest seat). 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. 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; 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.',
     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']).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.'),
+        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.'),
         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 output carries its own audio).'),
+        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.'),
+        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.'),
     }),
@@ -2016,10 +2372,13 @@ export const editVideo = {
         }
         const model = input.model ?? 'kling-v3.0-omni-edit';
         const isOmniFlashEdit = model === 'omni-flash-edit';
-        // Kling edit: 3–15s source clips; Omni Flash edit: 3–10s.
-        const maxClipSeconds = isOmniFlashEdit ? 10 : 15;
-        if (isOmniFlashEdit && ((input.characterAssetIds?.length ?? 0) > 0 || (input.styleAssetIds?.length ?? 0) > 0)) {
-            throw new Error('omni-flash-edit is prompt-only — it takes no character/style reference images. Drop the refs, or switch to kling-v3.0-omni-edit which supports elements.');
+        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;
+        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.`);
         }
         // Resolve refs (UUIDs or badge codes) against the project AT CALL TIME.
         const refInputs = [
@@ -2048,12 +2407,24 @@ export const editVideo = {
         if (!Number.isFinite(clipSeconds) || clipSeconds <= 0) {
             throw new Error('Source clip has no recorded duration — cannot quote the edit. Re-import the clip or pick another.');
         }
-        if (clipSeconds > maxClipSeconds + 0.05 || clipSeconds < 2.95) {
-            throw new Error(`Source clip is ${clipSeconds.toFixed(1)}s — ${model} accepts 3–${maxClipSeconds}s. ` +
-                `Trim it first with slates_trim_video (e.g. inSec 0, outSec ${maxClipSeconds}), then edit the trimmed clip.`);
-        }
-        const billedSeconds = Math.min(maxClipSeconds, Math.max(3, Math.ceil(clipSeconds - 0.05)));
-        const costKey = isOmniFlashEdit ? omniFlashEditCostKey(billedSeconds) : klingEditCostKey(model, billedSeconds);
+        if (clipSeconds > maxClipSeconds + 0.05 || clipSeconds < minClipSeconds - 0.05) {
+            throw new Error(`Source clip is ${clipSeconds.toFixed(1)}s — ${model} accepts ${minClipSeconds}–${maxClipSeconds}s. ` +
+                `Trim it first with slates_trim_video (e.g. inSec 0, outSec ${maxClipSeconds}), then edit the trimmed clip` +
+                (maxClipSeconds < SEEDANCE_25_EDIT_MAX_SECONDS ? ', or switch to seedance-2.5-edit which accepts up to 30s' : '') +
+                '.');
+        }
+        const billedSeconds = Math.min(maxClipSeconds, Math.max(minClipSeconds, Math.ceil(clipSeconds - 0.05)));
+        // Three engines, three key shapes — only Seedance's carries a resolution and
+        // a face route, because only its price moves with them.
+        const costKey = isSeedanceEdit
+            ? seedanceEditCostKey({
+                duration: billedSeconds,
+                videoResolution: input.videoResolution ?? '720p',
+                seedanceFace: input.seedanceFace === true,
+            })
+            : isOmniFlashEdit
+                ? omniFlashEditCostKey(billedSeconds)
+                : klingEditCostKey(model, billedSeconds);
         const cloud = ctx.cloud();
         const registry = await cloud.get('/api/agent/models');
         const entry = registry.models.find((m) => m.model === costKey);
@@ -2092,6 +2463,8 @@ export const editVideo = {
             characterAssetIds,
             styleAssetIds,
             keepAudio: input.keepAudio !== false,
+            videoResolution: input.videoResolution,
+            seedanceFace: input.seedanceFace,
             background: input.background,
         });
         if (!result.success)
@@ -2694,6 +3067,53 @@ export const updateFrame = {
         }));
     },
 };
+/**
+ * Batch form of `slates_update_frame`.
+ *
+ * Writing a scene's worth of frames — motion prompts, shot labels — is ONE
+ * logical edit. Doing it as N `slates_update_frame` calls costs N LLM
+ * round-trips and makes the desktop refetch the whole storyboard N times for a
+ * single intent. This is also where the storyboard's deleted "generate motion
+ * prompts" button's capability went: the agent can be told "redo scene 3,
+ * handheld", which that fixed-shape button never could.
+ *
+ * Hits `POST /agent/frames/batch-update`, which validates every id BEFORE the
+ * first write and emits one broadcast for the batch.
+ */
+export const batchUpdateFrames = {
+    id: 'slates_batch_update_frames',
+    description: 'Update MANY frames in one call — motion prompts, shot labels, notes, asset binding, scene/position, frameType. Prefer this over repeated slates_update_frame when writing a scene or a whole storyboard: it is one round-trip and one UI refresh. Every id is validated before anything is written, so the batch never lands half-applied.',
+    input: z.object({
+        updates: z
+            .array(z.object({
+            frameId: z.string().uuid(),
+            shotLabel: z.string().optional(),
+            notes: z.string().optional(),
+            assetId: z.string().uuid().nullable().optional(),
+            sceneId: z.string().uuid().nullable().optional(),
+            position: z.number().int().min(0).optional(),
+            frameType: z.enum(['first', 'last', 'ingredient']).nullable().optional(),
+            motionPrompt: z.string().nullable().optional(),
+        }))
+            .min(1),
+    }),
+    async run(input, ctx) {
+        return ok(await ctx.desktop().post('/agent/frames/batch-update', {
+            updates: input.updates.map((u) => ({
+                id: u.frameId,
+                data: {
+                    shotLabel: u.shotLabel,
+                    notes: u.notes,
+                    assetId: u.assetId,
+                    sceneId: u.sceneId,
+                    position: u.position,
+                    frameType: u.frameType,
+                    motionPrompt: u.motionPrompt,
+                },
+            })),
+        }));
+    },
+};
 export const deleteFrame = {
     id: 'slates_delete_frame',
     description: 'Delete a frame from its scene (the referenced asset is untouched).',
@@ -2738,6 +3158,33 @@ function resolveGuideTopic(topic) {
         return 'slates-prompting-kling-v3';
     if (t.startsWith('kling-v3'))
         return 'slates-prompting-kling-v3';
+    // Audio — seed-audio BEFORE the seedance check: "seed-audio" also starts
+    // with "seed", and falling through would hand the video guide to the audio
+    // model (the exact class of aliasing bug this comment block warns about).
+    // Speech, dialogue and scratch VO all live on Seed Audio now — the TTS
+    // surface is gone, so "tts"/"voiceover" must NOT land on the ElevenLabs
+    // guide, which is SFX-only.
+    if (t.startsWith('seed-audio') ||
+        t === 'seed audio' ||
+        t === 'audio' ||
+        t === 'tts' ||
+        t === 'voiceover' ||
+        t === 'dialogue') {
+        return 'slates-prompting-seed-audio';
+    }
+    if (t.startsWith('eleven') || t.startsWith('elevenlabs') || t === 'sfx' || t === 'sound-effects' || t === 'sound effects') {
+        return 'slates-prompting-elevenlabs';
+    }
+    // ⚠️ 2.5 BEFORE the generic `seedance` prefix — the same ordering trap as
+    // seed-audio-before-seedance above. Falling through silently hands the 2.0
+    // guide to 2.5, whose limits, resolutions and task types are all different.
+    if (t.startsWith('seedance-2.5') ||
+        t.startsWith('seedance-25') ||
+        t.startsWith('seedance-2-5') ||
+        t.startsWith('seedance2.5') ||
+        t === 'seedance 2.5') {
+        return 'slates-prompting-seedance-2-5';
+    }
     if (t.startsWith('seedance'))
         return 'slates-prompting-seedance';
     if (t.startsWith('avatar-') || t.includes('lip-sync'))
@@ -2764,7 +3211,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-lip-sync, slates-prompting-motion-transfer, slates-prompting-flux-2-max, slates-prompting-seedream-5-lite, slates-edit-and-iterate, slates-vision-feedback-loop, slates-character-identity, slates-storyboard-from-script, slates-direct-response-ad, slates-one-prompt-film. Style names (photoreal, anime, painterly, 3d-render) resolve to slates-style-prompting.'),
+            .describe('Guide name, model id, or style name. Guides: slates-model-selection (which model for which job — read before choosing any model), slates-cost-discipline, slates-content-policy, slates-style-prompting, slates-prompting-nano-banana-2, slates-prompting-veo-3, slates-prompting-kling-v3, slates-prompting-seedance, slates-prompting-seed-audio, slates-prompting-elevenlabs, slates-prompting-lip-sync, slates-prompting-motion-transfer, slates-prompting-flux-2-max, slates-prompting-seedream-5-lite, slates-edit-and-iterate, slates-vision-feedback-loop, slates-character-identity, slates-storyboard-from-script, slates-direct-response-ad, slates-one-prompt-film. Style names (photoreal, anime, painterly, 3d-render) resolve to slates-style-prompting.'),
     }),
     async run(input) {
         const resolved = resolveGuideTopic(input.topic);
@@ -2796,6 +3243,9 @@ export const ALL_OPERATIONS = [
     listFolders,
     createFolder,
     moveAssetsToFolder,
+    moveAssetsToProject,
+    copyAssetsToProject,
+    moveEntityToProject,
     listCharacters,
     createCharacter,
     setCharacterIdentity,
@@ -2810,6 +3260,7 @@ export const ALL_OPERATIONS = [
     addFrame,
     generateImage,
     generateVideo,
+    generateAudio,
     generateLipSync,
     generateMotionTransfer,
     editVideo,
@@ -2849,6 +3300,7 @@ export const ALL_OPERATIONS = [
     deleteScene,
     reorderScenes,
     updateFrame,
+    batchUpdateFrames,
     deleteFrame,
     getPromptingGuide,
 ];