@slatesvideo/shared 0.6.3 → 0.6.5

package/dist/operations/index.js

@@ -14,6 +14,7 @@ import { SlatesCloudClient } from '../clients/cloud.js';
 import { SlatesDesktopClient } from '../clients/desktop.js';
 import { BlenderBridgeClient, BLENDER_SETUP_HINT, RENDER_TIMEOUT_MS } from '../clients/blender.js';
 import { SKILLS } from '../skills/content.js';
+import { appManualSections } from '../manual/index.js';
 // Reference-capacity prose is DERIVED, never hand-typed — root CLAUDE.md:
 // "never hand-type a fact an LLM will read". These helpers read MODEL_FACTS.
 import { multimodalRefSummary, multimodalRefModels, seedanceTaskIntentWords, 
@@ -38,13 +39,42 @@ import { AGENT_ROUTE_PROVIDER, aspectRatioUnion, videoResolutionUnion, durationB
 // no call to skip, no discretion. `bannedTokenWarning` then reports what the
 // submitted prompt actually contained, in the result, without blocking it.
 // Never hand-type one of these tokens here; edit the skill.
-import { describeBannedTokens, bannedTokenWarning } from '../prompts/banned-tokens.js';
+import { describeBannedTokens, bannedTokenWarning, describeBannedTokensForSkill, } from '../prompts/banned-tokens.js';
+// 🚨 THE OTHER HALF OF THE SAME LESSON. The banned list is the NEGATIVE half and
+// it rides an op description. The CRAFT CARD is the POSITIVE half — the levers
+// that make a shot good rather than merely un-bad — and it rides the estimate
+// RESULT, which the doctrine already makes the agent call before generating.
+// Zero prefix bytes, present at the moment the model has just been named.
+import { describeCraftCard } from '../prompts/craft-cards.js';
+// ONE captioning rule for a generated asset, shared with the desktop gallery.
+import { assetCaption } from '../prompts/asset-label.js';
+// 🚨 THE ONE ROLE LIST + the Shot shape, mirrored into the desktop. The op
+// surface DERIVES its per-role params from these rather than naming roles by
+// hand — a hand-typed bucket name is what `attachmentRoles` exists to kill.
+import { ORDERED_ATTACHMENT_ROLES, ATTACHMENT_ROLE_DESCRIPTION, SCRIPT_FIELD_DESCRIPTION, SCRIPT_TEXT_FIELDS, } from '../prompts/shot-spec.js';
+import { SHOT_SIZE_BUCKETS, CAMERA_MOVE_BUCKETS, SPEECH_RATE, } from '../prompts/shot-grammar.js';
+// Annotations, tiers and the ONE schema renderer. Declared next door so this
+// module never hand-sets a hint or a tier per op: `annotate()` derives all four
+// from the id and the lockstep check re-derives them from the transport verbs.
+import { annotate, groupFor, tierFor, toolDefinitions, GROUP_SUMMARY, OPERATION_GROUPS, } from './surface.js';
 export function defaultContext() {
     return {
         cloud: () => new SlatesCloudClient(),
         desktop: () => new SlatesDesktopClient(),
     };
 }
+/** Thrown by an op that noticed `ctx.signal` had aborted mid-work. */
+export class OperationCancelledError extends Error {
+    code = 'OPERATION_CANCELLED';
+    constructor(detail) {
+        super(`Cancelled by the user${detail ? ` — ${detail}` : ''}.`);
+    }
+}
+/** Throw if the caller has cancelled. Call between billable items, never inside one. */
+function throwIfCancelled(ctx, detail) {
+    if (ctx.signal?.aborted)
+        throw new OperationCancelledError(detail);
+}
 // ── Helpers ─────────────────────────────────────────────────────
 /**
  * `z.enum` over a GENERATED list. Zod's signature wants a non-empty tuple
@@ -72,8 +102,97 @@ function ok(data, text) {
 // the same credit value); balances the same. Read via creditCost(); display
 // via fmtCredits(). The confirm gate fires above CONFIRM_CREDITS (≈ the old
 // $0.50 gate at the 3¢/credit peg).
-const CONFIRM_CREDITS = 17;
+export const CONFIRM_CREDITS = 17;
 const CENTS_PER_CREDIT = 3; // peg: 1 credit = 3¢ billed = 2¢ COGS (mirror of slates-api)
+/**
+ * The desktop deviation guard's ceiling multiplier: the Studio Agent pauses and
+ * re-asks when projected generation spend exceeds the approved ledger by more
+ * than this factor.
+ *
+ * 🚨 EXPORTED BECAUSE THE NUMBER IS QUOTED DOWNSTREAM. `slates-cost-discipline`
+ * told the agent the threshold was 25% while `loop.ts` paused at 20% — a skill
+ * contradicting the code on the one number that decides whether a run stops.
+ * The skill now renders it from here through `_partials/thresholds.md`; the
+ * desktop loop imports it instead of declaring its own.
+ */
+export const DEVIATION_FACTOR = 1.2;
+/**
+ * The confirm-gate sentence, rendered ONCE from CONFIRM_CREDITS.
+ *
+ * It was hand-typed three different ways for the same constant — "$0.50" on the
+ * image and video ops, "17 credits" on audio — so a rate change would have had
+ * to find three wordings. Byte-stable (a template over a literal), so the
+ * desktop's prompt-cached prefix is unaffected.
+ */
+const CONFIRM_GATE_SENTENCE = `Cost above ${CONFIRM_CREDITS} credits returns requires_confirm — pass confirm=true after explicit user OK.`;
+// Declared HERE, above every op, because `slates_estimate_generation_cost`
+// renders them into its `duration` description at MODULE LOAD — a const
+// declared below the first schema that reads it is a temporal-dead-zone
+// crash, not a lint nit (the same rule the VIDEO_MODELS block states).
+/**
+ * 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;
+// ── The TTS character bucket ────────────────────────────────────────────────
+//
+// TTS is the ONE audio surface that does not bill per second: speech length
+// falls out of the text, so there is no duration to charge for. It bills on a
+// bucket of CHARACTERS instead, and the bucket exists because of the minimum
+// billable floor rather than for tidiness.
+//
+// At $20.8/M characters and a 1.5× markup, a 200-character line is $0.006 of
+// basis — under `MIN_AUDIO_BILLABLE_DOLLARS` ($0.01), so it bills the floor.
+// The floor stops biting at 321 characters. A bucket SMALLER than that would be
+// entirely floor-bound (every bucket the same price, so the displayed rate stops
+// tracking cost and becomes a lie); a much LARGER one over-bills the short lines
+// this feature is mostly for. 250 splits that difference and divides 2,000
+// exactly, giving eight buckets and no ragged last one.
+//
+// 🚨 THE CAP IS READ FROM THE CAPABILITY SSOT, NEVER TYPED. 2,000 is the
+// vendor's MEASURED limit (the API rejects 2,001 by name), and this module
+// already imports MODEL_CAPABILITIES — so typing the number here would be a
+// second copy of a fact one file away, which is exactly what that SSOT exists
+// to delete. `getModelCapability` throws nothing on a miss, so the `??` would
+// hide a renamed model: assert instead, at module load, where it fails the
+// build rather than shipping a bucket ceiling of `undefined`.
+export const TTS_MODEL = 'inworld-tts-2';
+export const TTS_BUCKET_CHARS = 250;
+export const TTS_MAX_CHARACTERS = (() => {
+    const max = getModelCapability(TTS_MODEL)?.maxCharacters;
+    if (!max)
+        throw new Error(`MODEL_CAPABILITIES['${TTS_MODEL}'] must declare maxCharacters`);
+    return max;
+})();
+export const TTS_BUCKET_COUNT = TTS_MAX_CHARACTERS / TTS_BUCKET_CHARS; // 8
+/** The seat's cloning spec — reference-clip bounds, the design-prompt bounds
+ *  and the workspace-wide clone rate — read from the SSOT for the same reason
+ *  as the cap: every number in it was MEASURED and lives in exactly one row. */
+export const TTS_VOICE_CLONE = (() => {
+    const spec = getModelCapability(TTS_MODEL)?.voiceClone;
+    if (!spec)
+        throw new Error(`MODEL_CAPABILITIES['${TTS_MODEL}'] must declare voiceClone`);
+    return spec;
+})();
 function creditCost(m) {
     if (!m)
         return 0;
@@ -89,9 +208,10 @@ function creditsFromDollars(dollars) {
     const cents = Math.round(dollars * 100);
     return cents <= 0 ? 0 : Math.max(1, Math.ceil(cents / CENTS_PER_CREDIT));
 }
-// Shared describe-text for the background flag on every generate_* op.
-const BACKGROUND_DESCRIBE = 'Submit and return immediately with generationId(s) instead of blocking until the file is saved. ' +
-    'Poll with slates_get_generation_status. Recommended for video (1-5 min renders).';
+// Shared describe-text for the background flag on every generate_* op. ONE
+// sentence: it is repeated verbatim on seven ops, so every word costs seven
+// times, and `slates_get_generation_status` explains the polling itself.
+const BACKGROUND_DESCRIBE = 'Return generationId(s) immediately instead of blocking; poll slates_get_generation_status. Recommended for video.';
 // ── Vision QC pointers (the "quality-check with vision" rule, made structural) ──
 //
 // QUALITY-CHECK is a POST-condition, so it cannot be gated the way a
@@ -109,7 +229,7 @@ const IMAGE_INLINE_REVIEW = 'The image is attached to this result — look at it
 const VIDEO_REVIEW_POINTER = 'You have NOT seen this clip: call slates_get_asset_video_frames on the asset id above before ' +
     'describing how it looks. A quality claim you cannot point to a tool result for is a REAL NUMBERS ONLY violation.';
 const BACKGROUND_REVIEW_POINTER = 'When it completes, look at it before you describe it — slates_get_asset_image for images, ' +
-    'slates_get_asset_video_frames for video.';
+    'slates_get_asset_video_frames for video. For audio, audition the saved file; metadata alone does not establish voice similarity or delivery quality.';
 // The image saved, but reading it back off disk failed (best-effort fetch). The
 // agent has an asset and NO pixels, which is the one state where a quality
 // claim would be pure invention — so this branch has to say so rather than
@@ -133,17 +253,40 @@ function backgroundSubmitted(kind, ids, extra, note) {
 // ── Workspace + identity ────────────────────────────────────────
 export const getWorkspaceState = {
     id: 'slates_get_workspace_state',
-    description: 'Snapshot of the user\'s Slates workspace: projects list, optional active project detail. Call once at the start of a workflow to seed your understanding.',
-    input: z.object({ projectId: z.string().optional() }),
+    description: 'Snapshot of the user\'s Slates workspace: the project list (most recent first) plus the active project in full when you name one. Call once at the start of a workflow to seed your understanding.',
+    input: z.object({
+        projectId: z.string().optional(),
+        limit: z.number().int().min(1).max(200).optional().describe('How many projects to list, newest first. Default 40.'),
+    }),
     async run(input, ctx) {
         const desktop = ctx.desktop();
         const { projects } = await desktop.get('/agent/projects');
+        // 🚨 COMPACT ROWS, AND A CAP. This returned every project's FULL row — fine
+        // at fourteen projects and unbounded by construction, on the one op the
+        // doctrine tells the agent to call first in every session. The fields kept
+        // are the ones a routing decision actually uses; the full row is one
+        // slates_get_project away.
+        const limit = input.limit ?? 40;
+        const rows = (projects ?? []);
+        const compact = rows.slice(0, limit).map((p) => ({
+            id: p.id,
+            name: p.name,
+            asset_count: p.assetCount ?? p.asset_count ?? undefined,
+            updated_at: p.updatedAt ?? p.updated_at ?? undefined,
+        }));
         let activeProject = undefined;
         if (input.projectId) {
             const r = await desktop.get('/agent/projects/get', { id: input.projectId });
             activeProject = r.project;
         }
-        return ok({ projects, activeProject });
+        return ok({
+            projects: compact,
+            project_count: rows.length,
+            ...(rows.length > compact.length
+                ? { truncated: `${rows.length - compact.length} more — raise limit or call slates_list_projects.` }
+                : {}),
+            activeProject,
+        });
     },
 };
 export const getMe = {
@@ -351,8 +494,14 @@ export const estimateGenerationCost = {
         // hand-typed "Video 3-15" here was wrong the day seedance-2.5 (4-30s)
         // shipped, and "Seedance defaults to 1080p" was wrong for 2.5, which has no
         // 1080p at all.
-        duration: z.number().int().min(1).max(360).optional().describe(`Seconds; cost scales linearly. Required with a video or audio base id. Video per model: ${describeDurations(VIDEO_MODELS)}. Audio: seed-audio 3-120 (⚠️ the requested duration IS the bill), eleven-sfx 1-22.`),
-        videoResolution: zEnum(VIDEO_RESOLUTIONS).optional().describe(`Video only. Omitted, each model quotes at its own default. Per model: ${describeVideoResolutions(VIDEO_MODELS)}`),
+        // 🚨 THE PER-MODEL TABLES ARE NOT REPEATED HERE. `slates_generate_video`
+        // carries `describeDurations` and `describeVideoResolutions` and is always
+        // in context beside this op; a second copy is 1.2 KB of the same generated
+        // text on every turn, and it would go stale in exactly one direction — the
+        // one where someone edits a table and forgets there were two.
+        duration: z.number().int().min(1).max(360).optional().describe(`Seconds; cost scales linearly. Required with a video or PER-SECOND audio base id. Per-model windows: see slates_generate_video's duration. Audio: seed-audio ${SEED_AUDIO_MIN_SECONDS}-${SEED_AUDIO_MAX_SECONDS} (⚠️ the requested duration IS the bill), eleven-sfx ${ELEVEN_SFX_MIN_SECONDS}-${ELEVEN_SFX_MAX_SECONDS}. ⛔ NOT for ${TTS_MODEL} — pass \`characters\`.`),
+        characters: z.number().int().min(1).max(TTS_MAX_CHARACTERS).optional().describe(`${TTS_MODEL} only — the LENGTH OF THE TEXT to speak (${TTS_BUCKET_CHARS}-char buckets).`),
+        videoResolution: zEnum(VIDEO_RESOLUTIONS).optional().describe('Video only. Omitted, each model quotes at its own default. Per-model ladders: see slates_generate_video\'s videoResolution.'),
         resolution: z.enum(['1k', '2k', '3k', '4k']).optional().describe('Image only (default 2k; 3k = gpt-image-2 1440p class).'),
         quality: z.enum(['medium', 'high']).optional().describe('gpt-image-2 only — quality tier (default medium).'),
         sound: z.boolean().optional().describe('Veo only — audio flag changes the cost key.'),
@@ -367,7 +516,11 @@ export const estimateGenerationCost = {
         let key = byKey.has(input.model) ? input.model : null;
         // 2) image base id + resolution (+ quality for gpt-image-2)
         if (!key) {
-            const img = ['nano-banana-2', 'nano-banana-2-lite', 'nano-banana-pro', 'gpt-image-2', 'flux-2-max', 'seedream-5-lite'].find((m) => m === input.model);
+            // IMAGE_MODELS, never a second hand-typed copy: this list is declared
+            // below (a runtime read, so no temporal-dead-zone hazard) and is the same
+            // enum `slates_generate_image` accepts. Two copies is how the estimate op
+            // would quietly stop pricing the seventh image model.
+            const img = IMAGE_MODELS.find((m) => m === input.model);
             if (img)
                 key = imageCostKey(img, input.resolution ?? (img === 'nano-banana-2-lite' ? '1k' : '2k'), input.quality ?? 'medium');
         }
@@ -377,7 +530,27 @@ export const estimateGenerationCost = {
         //     a seedance spelling.
         if (!key && AUDIO_MODELS.includes(input.model)) {
             const m = input.model;
-            if (!input.duration) {
+            // The TTS seat prices on CHARACTERS, so it leaves this per-second lane
+            // entirely. Asking for a duration here would quote a number that does not
+            // exist for it.
+            if (m === TTS_MODEL) {
+                if (!input.characters) {
+                    return ok({
+                        requires_clarification: true,
+                        missing: ['characters'],
+                        message: `${TTS_MODEL} bills per character, not per second — there is no duration to pass. Send the LENGTH OF THE TEXT to be spoken as \`characters\` (1-${TTS_MAX_CHARACTERS}).`,
+                    });
+                }
+                if (input.characters > TTS_MAX_CHARACTERS) {
+                    return ok({
+                        requires_clarification: true,
+                        missing: ['characters'],
+                        message: `${TTS_MODEL} accepts up to ${TTS_MAX_CHARACTERS} characters in one take — ${input.characters} would be refused at generation time. Split the text and quote each line.`,
+                    });
+                }
+                key = audioCostKey({ model: m, characters: input.characters });
+            }
+            if (!key && !input.duration) {
                 return ok({
                     requires_clarification: true,
                     missing: ['duration'],
@@ -392,20 +565,26 @@ export const estimateGenerationCost = {
             // 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.
+            // Only the PER-SECOND surfaces have duration bounds. Keyed by those two
+            // ids rather than by AudioModel so adding a third surface on a different
+            // unit is a compile error here instead of a silent `undefined` bounds
+            // lookup that would throw at quote time.
             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.',
-                });
+            if (!key && m !== TTS_MODEL && input.duration) {
+                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 });
             }
-            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')) {
@@ -461,10 +640,23 @@ 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(' | ')} | ${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.`);
+            // Every id in the error comes from the SSOT arrays. The image half was
+            // hand-typed and named three of six, so an agent that mis-spelled
+            // `gpt-image-2` was told the model did not exist.
+            throw new Error(`Unknown model: ${input.model}. Pass a base id (${VIDEO_MODELS.join(' | ')} | ${AUDIO_MODELS.join(' | ')} | ${IMAGE_MODELS.join(' | ')}) plus duration/resolution params, or use slates_list_available_models with a filter.`);
         }
         const qty = input.quantity ?? 1;
         const totalCredits = perCredits * qty;
+        // 🚨 THE CRAFT CARD RIDES THIS RESULT. Measured 2026-08-30: the never-use
+        // list inlined where the agent could not skip it moved compliance 0/8 →
+        // 30/32, while the same guidance behind `slates_get_prompting_guide` sat at
+        // 13% before AND after. This is that placement applied to the POSITIVE half.
+        // It is here rather than in a param description because a description is
+        // paid for on every turn of every session and read once — this is paid for
+        // only by the call that is about to use the model.
+        const skill = promptingSkillFor(input.model);
+        const card = describeCraftCard(skill);
+        const banned = describeBannedTokensForSkill(skill);
         return ok({
             model: input.model,
             cost_key: key,
@@ -472,7 +664,11 @@ export const estimateGenerationCost = {
             cost_per_credits: perCredits,
             total_credits: totalCredits,
             requires_confirm: totalCredits > CONFIRM_CREDITS,
-        }, `${input.model}${qty > 1 ? ` ×${qty}` : ''}: ${fmtCredits(totalCredits)} (${key}).`);
+            ...(card ? { craft_card: card, craft_card_skill: skill } : {}),
+            ...(banned ? { banned_tokens: banned } : {}),
+        }, `${input.model}${qty > 1 ? ` ×${qty}` : ''}: ${fmtCredits(totalCredits)} (${key}).` +
+            (card ? `\n\n--- HOW TO PROMPT ${input.model} ---\n${card}` : '') +
+            (banned ? `\n\n${banned}` : ''));
     },
 };
 // ── Projects ────────────────────────────────────────────────────
@@ -510,11 +706,17 @@ export const getProject = {
  * tool result). Every op that embeds asset lists uses this. */
 function compactAsset(a) {
     const r = a;
-    const prompt = typeof r.prompt === 'string' ? r.prompt : '';
     return {
         id: r.id,
         code: r.code ?? null,
-        label: r.label ?? (prompt ? prompt.slice(0, 40) : null),
+        // ONE captioning rule, shared with the desktop gallery — see
+        // prompts/asset-label.ts for why the first 40 characters of a prompt is not
+        // a label on reference-driven work.
+        label: assetCaption({
+            label: typeof r.label === 'string' ? r.label : null,
+            shotName: typeof r.shotName === 'string' ? r.shotName : null,
+            prompt: typeof r.prompt === 'string' ? r.prompt : null,
+        }),
         type: r.type,
         created_at: r.createdAt ?? r.created_at ?? undefined,
     };
@@ -913,6 +1115,7 @@ export const createEnvironment = {
 };
 export const generateCharacterIdentity = {
     id: 'slates_generate_character_identity',
+    billable: true,
     description: "Generate one character identity sheet from a base portrait asset and bind it as the character's canonical reference. Call after slates_create_character. Read slates-character-identity before calling and quote the cost from slates_estimate_generation_cost.",
     input: z.object({
         characterId: z.string().uuid(),
@@ -936,6 +1139,7 @@ export const generateCharacterIdentity = {
 };
 export const generateEnvironmentPlate = {
     id: 'slates_generate_environment_plate',
+    billable: true,
     description: "Generate one clean establishing image from an optional base image and bind it as the environment's canonical reference. Call after slates_create_environment and quote the cost from slates_estimate_generation_cost.",
     input: z.object({
         environmentId: z.string().uuid(),
@@ -979,7 +1183,11 @@ export const createStoryboard = {
 };
 export const getStoryboardWithFrames = {
     id: 'slates_get_storyboard_with_frames',
-    description: 'Deep-fetch a storyboard with all scenes and frames.',
+    // 🚨 ONE BOARD, TWO READERS. Every frame carries its Shots — the same rows,
+    // in the same order, that the user is looking at. Before this the agent got
+    // scenes and frames with no Shots, so the user read an arranged board while
+    // the agent read an unordered pile.
+    description: "Deep-fetch a storyboard: every scene, every slot, and the SHOT in each slot — its script line, references, model, params and takes — plus the piece's variety distribution. This is the same board, in the same order, that the user is reading.",
     input: z.object({ storyboardId: z.string().uuid() }),
     async run(input, ctx) {
         const desktop = ctx.desktop();
@@ -987,7 +1195,7 @@ export const getStoryboardWithFrames = {
             desktop.get('/agent/storyboards/get', { id: input.storyboardId }),
             desktop.get('/agent/scenes/full', { storyboardId: input.storyboardId }),
         ]);
-        return ok({ ...storyboard, scenes: scenes.scenes });
+        return ok({ ...storyboard, scenes: scenes.scenes, variety: scenes.variety }, describeVarietyReport(scenes.variety));
     },
 };
 export const addScene = {
@@ -1004,7 +1212,11 @@ export const addScene = {
 };
 export const addFrame = {
     id: 'slates_add_frame',
-    description: 'Add a frame (asset reference) to a scene.',
+    // ⚠️ THIS OP AND `slates_create_shot({ frameId })` NOW OVERLAP: two doors to
+    // "put something in a scene". Naming the wart is cheaper than merging them
+    // mid-release. Use THIS one only to park an existing picture; use
+    // slates_create_shot to write a beat, which is almost always what you want.
+    description: 'Park an EXISTING image in a scene as a new slot. It creates a Shot for that picture automatically, because a scene is a list of Shots. To write a beat — line, references, model, prompt — use slates_create_shot instead; it needs no image and files itself.',
     input: z.object({
         projectId: z.string().uuid(),
         storyboardId: z.string().uuid(),
@@ -1140,13 +1352,16 @@ function imageCostKey(model, resolution, quality = 'medium') {
 }
 export const generateImage = {
     id: 'slates_generate_image',
+    billable: true,
     description: 'Generate an image via Slates credits.\n' +
         // GENERATED from MODEL_FACTS — the hand-typed model list that stood here
         // was a third copy of the routing doctrine, and it had already gone stale
         // (it still described nano-banana-2-lite by a capability the param owns).
         `${describeRouting('image')}\n` +
         'Full table: the slates-model-selection skill. ' +
-        'Pass projectId to save into a Slates project (recommended — asset appears live in the desktop UI). All models except nano-banana-2 REQUIRE projectId (no headless path). REQUIRED before calling: read the slates-cost-discipline skill (and the model\'s slates-prompting-* skill). You MUST pass aspectRatio and resolution explicitly (the server returns requires_clarification when missing — defaults waste credits). Cost > $0.50 returns requires_confirm — pass confirm=true after explicit user OK. MCP/CLI generation always charges credits. No skill files installed? Call slates_get_prompting_guide with the model\'s topic (and \'slates-cost-discipline\') before first use. ' +
+        'Pass projectId to save into a Slates project (recommended — asset appears live in the desktop UI). All models except nano-banana-2 REQUIRE projectId (no headless path). REQUIRED before calling: read the slates-cost-discipline skill (and the model\'s slates-prompting-* skill). You MUST pass aspectRatio and resolution explicitly (the server returns requires_clarification when missing — defaults waste credits). ' +
+        CONFIRM_GATE_SENTENCE +
+        ' MCP/CLI generation always charges credits. No skill files installed? Call slates_get_prompting_guide with the model\'s topic (and \'slates-cost-discipline\') before first use. ' +
         // GENERATED from the skill file's own never-use list -- the one piece of
         // prompting doctrine that is ALWAYS in context, because the agent has
         // demonstrably skipped the call that would have taught it.
@@ -1257,7 +1472,7 @@ export const generateImage = {
         if (!entry)
             throw new Error(`Model not in registry: ${costKey}`);
         const totalCents = creditCost(entry) * (input.count ?? 1);
-        // Confirm gate. Fires on cost > $0.50, AND (look-first, mirroring
+        // Confirm gate. Fires above CONFIRM_CREDITS, AND (look-first, mirroring
         // slates_generate_video) whenever reference assets are involved
         // regardless of cost — the LLM must see what it's referencing before
         // committing spend.
@@ -1481,6 +1696,7 @@ async function pollProxyJob(cloud, jobId, options = {}) {
 // ── Edit image ──────────────────────────────────────────────────
 export const editImage = {
     id: 'slates_edit_image',
+    billable: true,
     description: 'Surgically edit an existing image asset with a text instruction (e.g. \'remove the lamppost\', \'make the jacket red\') instead of regenerating from scratch — use when ~90% of the image is already right. The edited result is saved as a NEW asset in the project (prompt prefixed \'[Edit]\'); the source is untouched. Default model nano-banana-2 (only model that also accepts referenceAssetIds); flux-2-max / seedream-5-lite use their own edit endpoints and ignore references. Before first use call slates_get_prompting_guide with topic \'slates-edit-and-iterate\'.',
     input: z.object({
         projectId: z.string().uuid(),
@@ -1763,31 +1979,7 @@ export function seedanceEditCostKey(input) {
 // 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;
+export const AUDIO_MODELS = ['seed-audio', 'eleven-sfx', 'inworld-tts-2'];
 /**
  * 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,
@@ -1811,6 +2003,21 @@ function clampInt(value, min, max) {
 // 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.
+/**
+ * Characters → the billed bucket, byte-identical to the desktop's
+ * `clampTtsCharacters`. Rounds UP to the next 250 and clamps to [250, 2000].
+ *
+ * The non-finite arm matters for the same reason it does on the duration side:
+ * `Math.ceil(NaN)` is NaN, which would build the key `inworld-tts-2-NaNc` here
+ * while the desktop quotes the first bucket. Divergence at a value neither side
+ * can bill is still divergence.
+ */
+function clampTtsCharacters(value) {
+    if (value == null || !Number.isFinite(value))
+        return TTS_BUCKET_CHARS;
+    const buckets = Math.ceil(value / TTS_BUCKET_CHARS);
+    return Math.min(TTS_BUCKET_COUNT, Math.max(1, buckets)) * TTS_BUCKET_CHARS;
+}
 export function audioCostKey(input) {
     if (input.model === 'seed-audio') {
         // `?? default` before the clamp, not `?? 0` — the desktop resolves a missing
@@ -1823,6 +2030,11 @@ export function audioCostKey(input) {
         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`;
     }
+    if (input.model === TTS_MODEL) {
+        // `c` for characters, so the key can never be mistaken for a seconds key by
+        // the `-\d+s$` tests the proxy and the desktop both run.
+        return `${TTS_MODEL}-${clampTtsCharacters(input.characters)}c`;
+    }
     throw new Error(`Unknown audio model: ${input.model}`);
 }
 /**
@@ -1941,33 +2153,36 @@ function spokenTextByAssetId(assetIds, spoken) {
     });
     return Object.keys(out).length > 0 ? out : undefined;
 }
-// Maps a video model id to its bundled prompting skill (frontmatter `name:`),
-// so guidance text points at a skill that actually exists. Deriving the name
-// via model.split('-')[0] produced 'slates-prompting-kling' / '...-veo', which
-// match no file — only seedance happened to line up.
+// Maps a model id to its bundled prompting skill (frontmatter `name:`), so
+// guidance text points at a skill that actually exists.
+//
+// 🚨 ONE RESOLVER. This was a second hand-typed alias table beside
+// `resolveGuideTopic()`, and it had already fallen behind: it knew nothing
+// about LTX-2.5, so every LTX generation was told to read the cost skill
+// instead of its own guide. Delegate; the ordering traps (2.5 before seedance,
+// seed-audio before seedance, minimax before both) are solved once, there.
 function promptingSkillFor(model) {
-    if (model.startsWith('kling'))
-        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'))
-        return 'slates-prompting-omni-flash';
-    // ONE skill covers both H3 seats — the prompt grammar is identical and only
-    // the ladder and the reference transport differ — so a prefix is right here.
-    if (model.startsWith('minimax-h3'))
-        return 'slates-prompting-minimax-h3';
-    return 'slates-cost-discipline';
+    return resolveGuideTopic(model) ?? 'slates-cost-discipline';
 }
+/**
+ * The per-model prompting guides for the whole video roster, DERIVED.
+ *
+ * `slates_generate_video`'s description hand-typed five of them and omitted
+ * `slates-prompting-ltx-2-5` for as long as LTX shipped — an agent reading the
+ * description could not learn the guide existed. A hand-typed index of a
+ * generated corpus is a stale index; it is only a matter of when.
+ */
+const VIDEO_MODEL_GUIDES = [
+    ...new Set(VIDEO_MODELS.map((m) => promptingSkillFor(m))),
+].join(' / ');
 export const generateVideo = {
     id: 'slates_generate_video',
-    description: 'Generate video via Slates credits. REQUIRED before calling: read slates-model-selection (the routing doctrine), slates-cost-discipline, and the matching per-model prompting skill (slates-prompting-seedance / slates-prompting-seedance-2-5 / slates-prompting-kling-v3 / slates-prompting-veo-3 / slates-prompting-minimax-h3) — video models prompt very differently; load them via slates_get_prompting_guide if no skill files are installed. Read slates-content-policy when the scene involves conflict, creatures, crowds, destruction, weapons, or young characters. projectId, aspectRatio, and duration are required (requires_clarification otherwise). Cost > $0.50 returns requires_confirm — pass confirm=true after explicit user OK. Image-to-video via firstFrameAssetId; first+last frames = Veo/Seedance only; ingredients via ingredientAssetIds (Kling Omni / Seedance). Asset params take UUIDs or badge codes ("IMG-A8"). ' +
+    billable: true,
+    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 (' +
+        VIDEO_MODEL_GUIDES +
+        ') — 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). ' +
+        CONFIRM_GATE_SENTENCE +
+        ' Image-to-video via firstFrameAssetId; first+last frames = Veo/Seedance only; ingredients via ingredientAssetIds (Kling Omni / Seedance). Asset params take UUIDs or badge codes ("IMG-A8"). ' +
         // GENERATED from the skill's own slop-token list. Always in context on both
         // surfaces, so it survives an agent that skips slates_get_prompting_guide.
         describeBannedTokens('video'),
@@ -1996,32 +2211,39 @@ export const generateVideo = {
         aspectRatio: zEnum(VIDEO_ASPECT_RATIOS).optional().describe(`NOT every model takes every value — an out-of-set ratio is REFUSED before submit, not silently ignored. Per model: ${describeAspectRatios(VIDEO_MODELS, AGENT_ROUTE_PROVIDER)}`),
         duration: z.number().int().min(VIDEO_DURATION_BOUNDS.min).max(VIDEO_DURATION_BOUNDS.max).optional().describe(`Seconds. Cost scales linearly — a 30s seedance-2.5 take is several hundred credits, so be explicit rather than defaulting. Per model: ${describeDurations(VIDEO_MODELS)}`),
         videoResolution: zEnum(VIDEO_RESOLUTIONS).optional().describe(`An unsupported resolution is REJECTED, never downgraded. Per model: ${describeVideoResolutions(VIDEO_MODELS)}. 4K video is Pro-only (the server returns PRO_REQUIRED for a base-tier account).`),
-        firstFrameAssetId: z.string().optional().describe('Starting frame for image-to-video: asset UUID or badge code ("IMG-A8") — codes resolve against the project at call time, so a code the user just spoke is always safe to pass.'),
-        lastFrameAssetId: z.string().optional().describe('Ending frame (UUID or badge code). Veo and Seedance only. Pairs with firstFrameAssetId for guided transitions.'),
+        // 🚨 EVERY DESCRIPTION BELOW IS A CONSTRAINT OR A GENERATED TABLE — never
+        // craft, never rationale, never a worked example. This op is the single
+        // largest thing in the desktop's prompt-cached prefix (measured 15,357 of
+        // 112,114 bytes on 2026-09-02, 13.7%), and almost all of the excess was
+        // reasoning that belongs in slates-prompting-* where it is read once, on
+        // demand, by the one session that needs it. If you are about to explain
+        // WHY here, you are writing the skill in the wrong file.
+        firstFrameAssetId: z.string().optional().describe('Starting frame for image-to-video (UUID or badge code, resolved at call time).'),
+        lastFrameAssetId: z.string().optional().describe('Ending frame. Veo and Seedance only; pairs with firstFrameAssetId.'),
         ingredientAssetIds: z.array(z.string()).max(30).optional().describe(
         // Caps DERIVED from MODEL_CAPABILITIES — the hand-typed list omitted
         // kling-v3.0-omni-pro entirely and read as if 7 were an Omni Flash-only rule.
-        `Visual reference / ingredient assets (UUIDs or badge codes). Cap per model (combined across ingredient/character/environment/style params): ${describeReferenceImageCaps(VIDEO_MODELS)}. More is not better: 2-4 strong references beat both extremes, and past 4 reference PEOPLE output stability drops on Seedance regardless of the cap.`),
-        characterAssetIds: z.array(z.string()).optional().describe('Character sheet assets (UUIDs or badge codes) — keeps a character consistent across the shot.'),
-        environmentAssetIds: z.array(z.string()).optional().describe('Environment reference assets (UUIDs or badge codes) — keeps a location/setting consistent across the shot.'),
-        styleAssetIds: z.array(z.string()).optional().describe('Style reference assets (UUIDs or badge codes) — locks the visual style of the shot.'),
-        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.'),
+        `Visual reference / ingredient assets. Cap per model, combined across the ingredient/character/environment/style params: ${describeReferenceImageCaps(VIDEO_MODELS)}. 2-4 strong references beat both extremes.`),
+        characterAssetIds: z.array(z.string()).optional().describe('Character sheet assets — keeps a character consistent.'),
+        environmentAssetIds: z.array(z.string()).optional().describe('Environment references — keeps a location consistent.'),
+        styleAssetIds: z.array(z.string()).optional().describe('Style references — locks the look.'),
+        videoReferenceAssetId: z.string().optional().describe('DEPRECATED — use videoReferenceAssetIds. Kept working: shipped CLI/MCP builds send this shape.'),
+        videoReferenceSeconds: z.number().optional().describe('DEPRECATED — the singular partner of videoReferenceSecondsEach.'),
+        audioReferenceAssetId: z.string().optional().describe('DEPRECATED — use audioReferenceAssetIds. Carries no spoken text.'),
         // ── 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')}`),
-        audioReferenceSpokenText: z.array(z.string()).optional().describe('STRONGLY RECOMMENDED whenever a reference clip contains SPEECH. Same order and length as audioReferenceAssetIds; use "" for a clip with no words (music, ambience, room tone). The model RE-TRANSCRIBES a supplied take rather than using it verbatim — a field test heard "an app called Slates" come back as "a map called Slates" — so the audio decides the VOICE, the ACCENT and the TIMING while only text decides the WORDS. Give the exact line here and it is quoted into the prompt beside the citation. Omit it and the words are a guess. Pairs with the plural audioReferenceAssetIds; the deprecated singular audioReferenceAssetId carries no text.'),
+        videoReferenceAssetIds: z.array(z.string()).optional().describe(`Reference VIDEOS, cited in the prompt as "video 1", "video 2"… in the order given. ${multimodalRefModels().join(' / ')} only. ${multimodalRefSummary('seedance-2')} ${multimodalRefSummary('seedance-2.5')} Billing switches to the vref key (input+output seconds) — pass videoReferenceSecondsEach. Over the cap is REFUSED, never trimmed.`),
+        videoReferenceSecondsEach: z.array(z.number()).optional().describe('REQUIRED with videoReferenceAssetIds, same order and length: each clip\'s duration in seconds. Feeds the vref cost key; the server re-probes and corrects an understated value upward.'),
+        audioReferenceAssetIds: z.array(z.string()).optional().describe(`Reference AUDIO, cited as "audio 1", "audio 2"… in the order given. No billing surcharge. ${multimodalRefSummary('seedance-2')} ${multimodalRefSummary('seedance-2.5')}`),
+        audioReferenceSpokenText: z.array(z.string()).optional().describe('The exact words in each reference clip — same order and length as audioReferenceAssetIds, "" for a clip with no speech. The model RE-TRANSCRIBES a take rather than using it verbatim, so audio decides voice/accent/timing and only this decides the WORDS. Omit it and the words are a guess.'),
         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.'),
-        seedanceFace: z.boolean().optional().describe('Seedance ONLY: set true when a reference/ingredient shows an AI-character\'s FACE. Faces are blocked on the default (cheaper) Seedance route, so this reroutes the gen to a face-capable provider at ~45% more (the cost key becomes seedance-2-face-*). Leave false/unset for faceless or object-only references. No effect on Kling/Veo. A REAL person\'s photo is rejected on this route — the failure message contains [REAL_FACE_DETECTED]; see seedanceRealFace.'),
-        seedanceRealFace: z.boolean().optional().describe('Seedance ONLY: the reference shows a REAL person (a photo of an actual human, not an AI character). Routes to the premium real-face provider (cost key seedance-2-realface-*, roughly 2x the AI-face price — quote it via slates_estimate_generation_cost first). REQUIRES realFaceConsent=true. Typical flow: a seedanceFace gen fails with [REAL_FACE_DETECTED] → ask the user to confirm consent + the higher price → retry with seedanceRealFace=true + realFaceConsent=true.'),
-        realFaceConsent: z.boolean().optional().describe('MANDATORY with seedanceRealFace: set true ONLY after the user has explicitly confirmed they hold the rights/consent to this person\'s likeness and it doesn\'t impersonate or misrepresent them. The generation is refused without it. Public figures/celebrities fail on every route.'),
+        seedanceFace: z.boolean().optional().describe('Seedance ONLY: a reference shows an AI CHARACTER\'s face. Faces are blocked on the default route, so this reroutes to a face-capable provider at ~45% more. A REAL person fails here with [REAL_FACE_DETECTED] — see seedanceRealFace.'),
+        seedanceRealFace: z.boolean().optional().describe('Seedance ONLY: a reference shows a REAL person. Premium route, roughly 2x the AI-face price — quote it first. REQUIRES realFaceConsent=true.'),
+        realFaceConsent: z.boolean().optional().describe('MANDATORY with seedanceRealFace: true ONLY after the user has explicitly confirmed they hold rights/consent to this likeness and it does not impersonate or misrepresent them. Refused without it; public figures fail on every route.'),
         negativePrompt: z.string().optional(),
         background: z.boolean().optional().describe(BACKGROUND_DESCRIBE),
         confirm: z.boolean().optional().describe('Set true after explicit user OK to bypass the confirm gate (which fires for almost every video gen since they\'re expensive).'),
@@ -2374,7 +2596,7 @@ export const generateVideo = {
         }
         const totalCents = creditCost(entry);
         // Pre-flight confirm gate. Fires when:
-        //   (a) cost > $0.50 (the cost gate), OR
+        //   (a) cost above CONFIRM_CREDITS (the cost gate), OR
         //   (b) any reference assets are involved (the look-first gate)
         // When references are present, the response inlines them as image
         // content blocks (and video keyframes for video refs) so the LLM
@@ -2515,13 +2737,70 @@ export const generateVideo = {
         };
     },
 };
+// ── The preset voice shelf ──────────────────────────────────────
+/**
+ * AGENT PARITY for the voice picker. The desktop browses stock voices by
+ * gender, accent and age and plays each one; until this op the agent could
+ * only pass a `voiceId` it had no way to discover. Disk reads on the desktop,
+ * never a vendor call — browsing is free on every surface.
+ */
+export const listVoices = {
+    id: 'slates_list_voices',
+    description: `Browse ${TTS_MODEL} preset voices. Pass a returned voiceId to slates_generate_audio. Filters AND together.`,
+    input: z.object({
+        gender: z.string().optional().describe('male | female'),
+        accent: z.string().optional().describe('Region ("GB") or languageCode ("en-GB"); available accents come from the shelf.'),
+        age: z.string().optional().describe('young | middle_aged | elderly'),
+        query: z.string().optional().describe('Free text over name, description, tags.'),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('voices', 'the preset voice shelf');
+        const shelf = await desktop.get('/agent/voices');
+        if (!shelf.available) {
+            return ok({ available: false, voices: [], message: 'This desktop build shipped without the preset shelf.' });
+        }
+        const terms = (input.query ?? '').toLowerCase().split(/\s+/).filter(Boolean);
+        const region = input.accent?.includes('-') ? input.accent.split('-')[1] : input.accent;
+        const voices = shelf.voices
+            .filter((v) => !input.gender || v.gender === input.gender)
+            .filter((v) => !region || v.languageCode.split('-')[1]?.toUpperCase() === region.toUpperCase())
+            .filter((v) => !input.age || v.ageGroup === input.age)
+            .filter((v) => {
+            if (terms.length === 0)
+                return true;
+            const hay = [v.displayName, v.description, v.gender, v.ageGroup, v.languageCode, ...(v.tags ?? [])]
+                .join(' ')
+                .toLowerCase();
+            return terms.every((t) => hay.includes(t));
+        })
+            .map(({ voiceId, displayName, description, tags, gender, ageGroup, languageCode }) => ({
+            voiceId,
+            displayName,
+            description,
+            tags,
+            gender,
+            ageGroup,
+            languageCode,
+        }));
+        return ok({
+            available: true,
+            line: shelf.line,
+            count: voices.length,
+            voices,
+            next: `Pass a voiceId to slates_generate_audio (model ${TTS_MODEL}) as voiceId. To keep one on a character for reuse, generate a clip with it and set slates_update_character voiceAssetId.`,
+        });
+    },
+};
 // ── Generate audio ──────────────────────────────────────────────
 export const generateAudio = {
     id: 'slates_generate_audio',
-    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.',
+    billable: true,
+    description: `Generate project audio using credits. Choose the surface via the model routing below. ` +
+        'Read slates-cost-discipline and the matching prompting skill first (slates-prompting-seed-audio | slates-prompting-elevenlabs | slates-prompting-inworld-tts). ' +
+        'Seed Audio bills the requested duration, which is appended to the prompt regardless of output length. Kling "SFX:" / "Ambient noise:" syntax does not transfer. ' +
+        CONFIRM_GATE_SENTENCE +
+        ' No skill files installed? Call slates_get_prompting_guide first.',
     input: z.object({
         projectId: z.string().uuid().describe('Slates project the audio asset lands in. Required — the renderer refreshes live.'),
         model: z
@@ -2534,17 +2813,31 @@ export const generateAudio = {
             .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.'),
+            .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. inworld-tts-2: THE WORDS TO SPEAK, verbatim, max ' + TTS_MAX_CHARACTERS + ' — its length is the bill.'),
         durationSeconds: z
             .number()
             .optional()
-            .describe('seed-audio 3-120 (default 15) — ⚠️ THIS IS THE BILL: it is appended to the prompt and charged regardless of the returned length. eleven-sfx 1-22 (default 4) — always sent explicitly so the per-second charge is deterministic.'),
+            .describe(`seed-audio ${SEED_AUDIO_MIN_SECONDS}-${SEED_AUDIO_MAX_SECONDS} (default ${SEED_AUDIO_DEFAULT_SECONDS}) — ⚠️ THIS IS THE BILL: appended to the prompt and charged whatever comes back. eleven-sfx ${ELEVEN_SFX_MIN_SECONDS}-${ELEVEN_SFX_MAX_SECONDS} (default ${ELEVEN_SFX_DEFAULT_SECONDS}) — always sent explicitly so the per-second charge is deterministic. Not for ${TTS_MODEL}.`),
         voice: z
             .string()
             .optional()
-            .describe('seed-audio only — a preset voice id (e.g. "cedric_en_zh"). Leave unset to let the scene cast itself, which is usually right for background dialogue. Agent-facing only: there is no user-facing voice picker.'),
+            .describe('seed-audio only — a preset voice id (e.g. "cedric_en_zh"). Leave unset to let the scene cast itself. Agent-facing only.'),
+        voiceId: z
+            .string()
+            .optional()
+            .describe(`${TTS_MODEL} — a preset voiceId from slates_list_voices, not a character or asset id. Exactly one voice source is required.`),
+        voiceReferenceAssetId: z
+            .string()
+            .optional()
+            .describe(`${TTS_MODEL} — clone this AUDIO asset's voice for the take (${TTS_VOICE_CLONE.minSeconds}-${TTS_VOICE_CLONE.maxSeconds}s, one clean speaker). To speak AS a character pass its voiceAssetId. Cloning: ${TTS_VOICE_CLONE.clonesPerMinute} new voices/min across all of Slates; a burst waits.`),
+        voiceDescription: z
+            .string()
+            .min(TTS_VOICE_CLONE.designPromptChars.min)
+            .max(TTS_VOICE_CLONE.designPromptChars.max)
+            .optional()
+            .describe(`${TTS_MODEL} — a voice from words (${TTS_VOICE_CLONE.designPromptChars.min}-${TTS_VOICE_CLONE.designPromptChars.max} chars) for a character with no recording; keep it via slates_update_character voiceAssetId.`),
         speed: z.number().min(0.5).max(2).optional().describe('seed-audio only — 0.5-2.0. Reach for it when dialogue races or drags against picture.'),
-        volume: z.number().min(0.5).max(2).optional().describe('seed-audio only — output gain, 0.5-2.0 (1 = unchanged). Prefer the timeline track fader for mix decisions; this is for when the model itself renders a scene too hot or too quiet.'),
+        volume: z.number().min(0.5).max(2).optional().describe('seed-audio only — output gain, 0.5-2.0 (1 = unchanged). Prefer the timeline fader for mix decisions.'),
         pitch: z.number().int().min(-12).max(12).optional().describe('seed-audio only — semitones. Small moves; ±3 is already a lot.'),
         multilingual: z.boolean().optional().describe('seed-audio only — better non-English / mixed-language handling.'),
         loop: z.boolean().optional().describe('eleven-sfx only — produce a seamless loop (rain, engine hum, crowd murmur).'),
@@ -2553,7 +2846,7 @@ export const generateAudio = {
             .array(z.string())
             .max(3)
             .optional()
-            .describe('seed-audio only — up to 3 AUDIO assets (UUIDs or badge codes like "AUD-S1"), each ≤30s, referenced in the prompt as @Audio1-@Audio3 ("match the room tone of @Audio1"). MUTUALLY EXCLUSIVE with imageReferenceAssetId — the API rejects both.'),
+            .describe('seed-audio only — up to 3 AUDIO assets (UUIDs or badge codes like "AUD-S1"), each ≤30s, referenced in the prompt as @Audio1-@Audio3 ("match the room tone of @Audio1"). MUTUALLY EXCLUSIVE with imageReferenceAssetId.'),
         imageReferenceAssetId: z
             .string()
             .optional()
@@ -2563,13 +2856,48 @@ export const generateAudio = {
     }),
     run: async (input, ctx) => {
         // ── Per-surface clarification + constraint gates ──
+        //
+        // `null` for the TTS seat is load-bearing rather than a placeholder: that
+        // surface has NO duration dimension at all (speech length falls out of the
+        // text), so there is no default that would be honest. A number here would
+        // flow into `audioCostKey` and quote a per-second price for a per-character
+        // generation.
         const cfgDefaults = {
             'seed-audio': SEED_AUDIO_DEFAULT_SECONDS,
             'eleven-sfx': ELEVEN_SFX_DEFAULT_SECONDS,
+            'inworld-tts-2': null,
         };
-        const seconds = input.durationSeconds ?? cfgDefaults[input.model];
+        const seconds = input.durationSeconds ?? cfgDefaults[input.model] ?? undefined;
+        if (input.model === TTS_MODEL) {
+            // The text IS the prompt on this surface — there is no separate field,
+            // because "the words that get spoken" and "what you asked for" are the
+            // same thing here. That also means the character count is knowable
+            // client-side, which is what makes the quote below exact.
+            if (input.prompt.length > TTS_MAX_CHARACTERS) {
+                throw new Error(`${TTS_MODEL} accepts up to ${TTS_MAX_CHARACTERS} characters in one take — this text is ${input.prompt.length}. Split it into separate lines and generate each one.`);
+            }
+            if (input.durationSeconds != null) {
+                throw new Error(`${TTS_MODEL} has no duration parameter — speech length falls out of the text, and it bills per character. Drop durationSeconds.`);
+            }
+            // EXACTLY ONE voice source. Zero is a clarification (the agent should ask
+            // who is speaking, not guess); two or more is an error, because the three
+            // paths are genuinely different generations and silently picking one would
+            // spend credits on a voice the caller did not ask for.
+            const voiceSources = [input.voiceId, input.voiceReferenceAssetId, input.voiceDescription]
+                .filter((v) => typeof v === 'string' && v.length > 0);
+            if (voiceSources.length === 0) {
+                return ok({
+                    requires_clarification: true,
+                    missing: ['voiceId'],
+                    message: `${TTS_MODEL} needs a voice — exactly one of three. Speaking AS a character: pass its voiceAssetId (slates_list_characters) as voiceReferenceAssetId. A stock voice: slates_list_voices lists presets by gender, accent and age; pass one's voiceId. No recording of the voice: voiceDescription (words), or voiceReferenceAssetId with any clean clip of one speaker. A voice worth reusing can be kept on a character with slates_update_character, but nothing requires that — ask the user which they want only when the request does not say.`,
+                });
+            }
+            if (voiceSources.length > 1) {
+                throw new Error(`${TTS_MODEL} takes exactly one voice source — pass voiceId OR voiceReferenceAssetId OR voiceDescription, not ${voiceSources.length} of them.`);
+            }
+        }
         if (input.model === 'seed-audio') {
-            if (seconds < SEED_AUDIO_MIN_SECONDS || seconds > SEED_AUDIO_MAX_SECONDS) {
+            if (seconds == null || seconds < SEED_AUDIO_MIN_SECONDS || seconds > SEED_AUDIO_MAX_SECONDS) {
                 return ok({
                     requires_clarification: true,
                     missing: ['durationSeconds'],
@@ -2581,7 +2909,7 @@ export const generateAudio = {
             }
         }
         if (input.model === 'eleven-sfx') {
-            if (seconds < ELEVEN_SFX_MIN_SECONDS || seconds > ELEVEN_SFX_MAX_SECONDS) {
+            if (seconds == null || seconds < ELEVEN_SFX_MIN_SECONDS || seconds > ELEVEN_SFX_MAX_SECONDS) {
                 return ok({
                     requires_clarification: true,
                     missing: ['durationSeconds'],
@@ -2597,6 +2925,10 @@ export const generateAudio = {
         const refInputs = [];
         for (const ref of input.audioReferenceAssetIds ?? [])
             refInputs.push({ ref, role: 'audio reference' });
+        // Resolved through the SAME resolver as every other asset ref, so a badge
+        // code ("AUD-S1") works here exactly as it does everywhere else.
+        if (input.voiceReferenceAssetId)
+            refInputs.push({ ref: input.voiceReferenceAssetId, role: 'voice reference' });
         if (input.imageReferenceAssetId)
             refInputs.push({ ref: input.imageReferenceAssetId, role: 'image reference' });
         const resolvedRefs = refInputs.length > 0
@@ -2611,6 +2943,7 @@ export const generateAudio = {
         const costKey = audioCostKey({
             model: input.model,
             durationSeconds: seconds,
+            characters: input.model === TTS_MODEL ? input.prompt.length : undefined,
         });
         const entry = registry.models.find((m) => m.model === costKey);
         if (!entry) {
@@ -2643,6 +2976,9 @@ export const generateAudio = {
             prompt: input.prompt,
             durationSeconds: seconds,
             voice: input.voice,
+            voiceId: input.voiceId,
+            voiceReferenceAssetId: rid(input.voiceReferenceAssetId),
+            voiceDescription: input.voiceDescription,
             speed: input.speed,
             volume: input.volume,
             pitch: input.pitch,
@@ -2678,7 +3014,8 @@ export const generateAudio = {
 // ── Generate lip-sync ───────────────────────────────────────────
 export const generateLipSync = {
     id: 'slates_generate_lip_sync',
-    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.',
+    billable: true,
+    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, sourceType=image animates a still avatar (avatar-standard, or avatar-pro for the premium seat). Quote each with slates_estimate_generation_cost rather than from memory. 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.'),
@@ -2797,12 +3134,14 @@ 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. 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.',
+    billable: true,
+    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 or kling-mc-pro, 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. ' +
+        CONFIRM_GATE_SENTENCE,
     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. 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']).optional().describe('kling-mc-std (~32 credits) general motion; kling-mc-pro (~42 credits) cleaner anatomy — default.'),
+        motionModel: z.enum(['kling-mc-std', 'kling-mc-pro']).optional().describe('kling-mc-std general motion; kling-mc-pro cleaner anatomy — default. Quote both with slates_estimate_generation_cost.'),
         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.'),
@@ -2837,7 +3176,15 @@ export const generateMotionTransfer = {
                 target_ref: target,
                 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, or pick kling-mc-std to save ~10 credits. ` +
+                    // The saving is READ from the registry, never guessed: "~10 credits"
+                    // was hand-typed and is a rate change away from being a lie.
+                    `Re-call with confirm=true after the user explicitly OKs the spend${motionModel === 'kling-mc-pro'
+                        ? (() => {
+                            const std = registry.models.find((m) => m.model === 'kling-mc-std-5s');
+                            const saving = std ? totalCents - creditCost(std) : 0;
+                            return saving > 0 ? `, or pick kling-mc-std to save ${fmtCredits(saving)}` : '';
+                        })()
+                        : ''}. ` +
                     `When discussing with the user, refer to the assets by those codes — they'll match the gallery badges.`,
             });
         }
@@ -2891,7 +3238,15 @@ export const generateMotionTransfer = {
 // ── Edit video (Kling O3 video-to-video) ────────────────────────
 export const editVideo = {
     id: 'slates_edit_video',
-    description: 'Edit an EXISTING video clip with one instruction — character swap, environment change, style transfer — in one pass, no masking. Original motion, camera, and audio are preserved; only what the prompt names changes. Use when a clip is ~90% right (fix it, don\'t re-roll it) or to AI-edit the user\'s own footage. Engines: Kling O3 edit (default; 3–15s clips, 720–3840px, subject/style refs via elements), omni-flash-edit (Gemini Omni Flash; 3–10s clips, 720p output, PROMPT-ONLY — no refs, cheapest seat), or seedance-2.5-edit (4–30s clips — the ONLY engine that takes a clip over 15s; up to 1080p, seedanceFace:true for AI-character faces). Cost = per second of OUTPUT (≈ clip length, rounded UP to the next second): omni-flash-edit ≈ 19¢/s ≈ kling-v3.0-omni-edit ≈ 19¢/s, kling-v3.0-omni-pro-edit ≈ 25¢/s. Subjects to swap IN go as characterAssetIds (frontal + angle images become Kling elements — Kling models only); style refs as styleAssetIds; max 4 combined. seedance-2.5-edit is priced per second of output on the video-reference tier and bills roughly double a plain 2.5 generation of the same length, because every provider charges an edit on input + output seconds — always read the quote from the confirm gate rather than assuming. The edited clip saves as a NEW asset linked to its parent (chain edits freely). Routing: Kling edit is the default edit tool (element lock + audio intact); omni-flash-edit for cheap prompt-only footage-synced swaps; prefer Seedance edit/relocate only for style-transfer-heavy jobs — see slates-model-selection. Prompting: slates-prompting-kling-v3 §Edit / slates-prompting-omni-flash.',
+    billable: true,
+    description: 
+    // 🚨 NO PRICES, NO HAND-TYPED WINDOWS. This description carried five dollar
+    // figures and three duration/resolution claims. The prices contradicted the
+    // agent's own REAL NUMBERS ONLY rule (it may not repeat a figure it cannot
+    // point to in a tool result) and go stale on the next rate change; the
+    // windows are owned by MODEL_CAPABILITIES and are generated below into the
+    // params that enforce them.
+    '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 — subject/style refs via elements), omni-flash-edit (PROMPT-ONLY, no refs, the cheapest seat), or seedance-2.5-edit (the only engine that takes a clip over 15s; seedanceFace:true for AI-character faces). Clip-length and resolution windows per engine are on the `model` param. Cost is per second of OUTPUT (≈ clip length, rounded up), and an edit bills input + output seconds on every provider — read the quote from the confirm gate or slates_estimate_generation_cost, never from memory. 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 (element lock + audio intact); omni-flash-edit for cheap prompt-only footage-synced swaps; Seedance edit/relocate 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.'),
@@ -3436,17 +3791,33 @@ export const setFolderCover = {
 };
 export const updateCharacter = {
     id: 'slates_update_character',
-    description: 'Update a character\'s name, description, or style. Use slates_set_character_identity_asset for its canonical image.',
+    description: 'Update a character\'s name, description, style, or voice. Use slates_set_character_identity_asset for its canonical image.',
     input: z.object({
         characterId: z.string().uuid(),
         name: z.string().min(1).max(120).optional(),
         description: z.string().optional(),
         style: z.string().max(200).optional().describe("Art style. Omit to inherit the reference's style (the default). Canonical styles: photoreal, anime, painterly, 3d-render, comic. Or pass any free-text instruction, e.g. 'turn this into a real person'."),
+        // Agent parity for the character card's voice slot: the desktop route has
+        // taken this since 2026-08-28; the op never exposed it, so an agent could
+        // render a voice and had no way to keep it on the character.
+        voiceAssetId: z
+            .string()
+            .uuid()
+            .nullable()
+            .optional()
+            .describe("The AUDIO asset that is this character's voice (what inworld-tts-2 clones for its lines); null detaches, the clip stays."),
     }),
     async run(input, ctx) {
         return ok(await ctx.desktop().post('/agent/characters/update', {
             id: input.characterId,
-            data: { name: input.name, description: input.description, style: input.style },
+            data: {
+                name: input.name,
+                description: input.description,
+                style: input.style,
+                // Sent only when given: the route treats presence as intent, and an
+                // explicit null is the detach.
+                ...(input.voiceAssetId !== undefined ? { voiceAssetId: input.voiceAssetId } : {}),
+            },
         }));
     },
 };
@@ -3591,7 +3962,12 @@ export const reorderScenes = {
 };
 export const updateFrame = {
     id: 'slates_update_frame',
-    description: 'Update a frame: shot label, notes, bound asset (assetId=null unbinds), scene, position, frameType (first/last/ingredient, null clears), or motion prompt (null clears).',
+    description: 
+    // ⚠️ `frameType` and `motionPrompt` are GONE. They were a weaker duplicate
+    // of what the Shot in this slot already encodes — the image's role and the
+    // beat's words — and they were backfilled into Shots on 2026-08-31. Use
+    // slates_update_shot for either.
+    'Update a slot: its shot label, notes, bound asset (assetId=null unbinds), scene or position. The BEAT — its line, references, model, prompt and framing — lives on the Shot in this slot; use slates_update_shot for that.',
     input: z.object({
         frameId: z.string().uuid(),
         shotLabel: z.string().optional(),
@@ -3599,8 +3975,6 @@ export const updateFrame = {
         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(),
     }),
     async run(input, ctx) {
         return ok(await ctx.desktop().post('/agent/frames/update', {
@@ -3611,8 +3985,6 @@ export const updateFrame = {
                 assetId: input.assetId,
                 sceneId: input.sceneId,
                 position: input.position,
-                frameType: input.frameType,
-                motionPrompt: input.motionPrompt,
             },
         }));
     },
@@ -3632,7 +4004,7 @@ export const updateFrame = {
  */
 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.',
+    description: 'Update MANY slots in one call — shot labels, notes, asset binding, scene/position. Prefer this over repeated slates_update_frame when re-arranging a scene: it is one round-trip and one UI refresh, and every id is validated before anything is written, so the batch never lands half-applied. To write the BEATS themselves, use slates_create_shot / slates_update_shot.',
     input: z.object({
         updates: z
             .array(z.object({
@@ -3642,8 +4014,6 @@ export const batchUpdateFrames = {
             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),
     }),
@@ -3657,8 +4027,6 @@ export const batchUpdateFrames = {
                     assetId: u.assetId,
                     sceneId: u.sceneId,
                     position: u.position,
-                    frameType: u.frameType,
-                    motionPrompt: u.motionPrompt,
                 },
             })),
         }));
@@ -3675,6 +4043,779 @@ export const deleteFrame = {
 // ── Prompting guides (local lookup — no transport) ──────────────
 // Model-id → guide-name aliasing. Order matters: kling-mc-* (motion
 // transfer) must match before the generic kling-v3* check.
+// ── Shots — the prompt bar, serialized ──────────────────────────
+//
+// A Shot is a NAMED generation recipe: what to make, with what, on which model,
+// at what settings. It exists to remove one pipeline constraint from this
+// surface — `slates_add_frame` requires a non-null `assetId`, so an agent could
+// not plan a shot before its image existed. A Shot takes no asset at all.
+//
+// 🚨 IT STORES A RAW PROMPT AND REFERENCES, NEVER A COMPOSED PROMPT. The
+// composer is the only thing that numbers anything; a stored "image 3" is a lie
+// the moment a reference moves. `slates_get_shot` returns the composed prompt so
+// the agent can audit its own work through the exact resolver the request uses.
+/** Role → its `string[]` param, GENERATED from the role list. Never hand-typed:
+ *  `attachmentRoles`/`shot-spec` is the ONE role list, and a sixth role has to
+ *  appear here without anyone remembering to add it. */
+function shotRefShape(described) {
+    return Object.fromEntries(ORDERED_ATTACHMENT_ROLES.map((role) => [
+        role,
+        described
+            ? z
+                .array(z.string())
+                .optional()
+                .describe(`${ATTACHMENT_ROLE_DESCRIPTION[role]} UUIDs or badge codes ("IMG-A8").`)
+            : z.array(z.string()).optional(),
+    ]));
+}
+const SHOT_REFS_LEAD = 'Attachments by ROLE, ordered within each role. The role decides the sentence the model is told, so a subject reference and a plain one are not interchangeable.';
+const shotRefsSchema = z.object(shotRefShape(true)).optional().describe(SHOT_REFS_LEAD);
+/**
+ * 🚨 THE SAME SHAPE, DESCRIBED ONCE.
+ *
+ * `params`, `refs` and the script fields are identical across create / update /
+ * duplicate, and `zodToJsonSchema` inlines every description into all three —
+ * 2.7 KB of the same prose, three times, in the desktop's prompt-cached prefix
+ * on every turn. `slates_create_shot` is the op that documents the shape and it
+ * is always in context beside these; repeating the table here bought nothing
+ * but bytes. The Zod ENUMS stay on both, so enforcement is unchanged — only the
+ * prose is deduplicated.
+ */
+const SEE_CREATE_SHOT = 'Same shape as slates_create_shot — see it for what each field means. ';
+const shotRefsSchemaTerse = z
+    .object(shotRefShape(false))
+    .optional()
+    .describe(SEE_CREATE_SHOT + SHOT_REFS_LEAD);
+// The full ratio vocabulary a Shot can hold — image OR video, because a Shot is
+// any generation. Per-model narrowing happens at create time for video (the same
+// `assertVideoCapabilities` gate `slates_generate_video` uses) and at generate
+// time for everything.
+const SHOT_ASPECT_RATIOS = [...new Set([...VIDEO_ASPECT_RATIOS, ...IMAGE_ASPECT_RATIOS])];
+// 🚨 THE PER-MODEL CAPABILITY TABLES ARE DELIBERATELY NOT REPEATED HERE.
+// `slates_generate_video`'s param descriptions already carry them and are always
+// in context on both surfaces; embedding them again — in three shot ops, each
+// taking these same params — would put FOUR more copies of a table that grows on
+// every model addition into the desktop's cached prefix. Measured: it was 15.3%
+// of the whole tool surface, almost all of it those three strings.
+// The vocabulary is still ENFORCED (a Zod enum built from MODEL_CAPABILITIES),
+// and the per-model narrowing is enforced by `assertShotCapabilities` at save
+// time — which is stronger than prose, not weaker.
+function shotParamsShape(described) {
+    const d = (node, text) => (described ? node.describe(text) : node);
+    return {
+        aspectRatio: d(zEnum(SHOT_ASPECT_RATIOS).optional(), 'Validated against the model; see slates_generate_video.'),
+        duration: d(z.number().int().min(1).max(360).optional(), 'Seconds for video or duration-based audio; TTS uses text length.'),
+        videoResolution: d(zEnum(VIDEO_RESOLUTIONS).optional(), 'Validated against the chosen model when the Shot is saved.'),
+        imageResolution: d(z.enum(['1k', '2k', '3k', '4k']).optional(), 'Image models only.'),
+        gptQuality: d(z.enum(['medium', 'high']).optional(), 'gpt-image-2 only.'),
+        imageQuantity: d(z.number().int().min(1).max(4).optional(), 'Image models only — how many to make per fire.'),
+        negativePrompt: z.string().optional(),
+        sound: d(z.boolean().optional(), 'Video models that co-generate audio.'),
+        seedanceFace: d(z.boolean().optional(), "Seedance only — a reference shows an AI character's FACE; reroutes to a face-capable provider at ~45% more."),
+        audioDurationSeconds: d(z.number().int().min(1).max(120).optional(), 'Audio lane. On seed-audio the requested duration IS the bill.'),
+        // The TTS voice — the same three fields slates_generate_audio takes, so a
+        // Shot is the audio call, serialized. Exactly one of them, enforced at fire.
+        voiceId: d(z.string().optional(), `${TTS_MODEL}: preset voiceId (slates_list_voices).`),
+        voiceReferenceAssetId: d(z.string().optional(), `${TTS_MODEL}: audio asset to clone.`),
+        voiceDescription: d(z.string().optional(), `${TTS_MODEL}: the voice in words.`),
+    };
+}
+const shotParamsSchema = z.object(shotParamsShape(true)).optional();
+const shotParamsSchemaTerse = z
+    .object(shotParamsShape(false))
+    .optional()
+    .describe(SEE_CREATE_SHOT + 'Generation settings for the Shot.');
+/**
+ * The script layer, as op params — GENERATED from `SCRIPT_FIELD_DESCRIPTION`.
+ *
+ * 🚨 THE PROSE IS NEVER HAND-TYPED HERE. `shot-spec.ts` owns what each field
+ * MEANS, with `satisfies Record<ScriptField, string>` making a ninth field a
+ * compile error in the descriptions too. An op that spelled these out would
+ * ship a field with no explanation — the same failure as a column nothing
+ * renders.
+ *
+ * Script fields supply prompt prose when no authored prompt exists (shot-spec.ts).
+ */
+function shotScriptShape(described) {
+    const text = Object.fromEntries(SCRIPT_TEXT_FIELDS.map((field) => [
+        field,
+        described
+            ? z.string().max(2000).nullable().optional().describe(SCRIPT_FIELD_DESCRIPTION[field])
+            : z.string().max(2000).nullable().optional(),
+    ]));
+    return {
+        ...text,
+        continues: described
+            ? z.boolean().optional().describe(SCRIPT_FIELD_DESCRIPTION.continues)
+            : z.boolean().optional(),
+    };
+}
+const shotScriptSchema = shotScriptShape(true);
+/** Same fields, described on `slates_create_shot` only — see SEE_CREATE_SHOT. */
+const shotScriptSchemaTerse = shotScriptShape(false);
+/** The framing vocabulary an agent should know about — generated from the
+ *  bucket lists so a seventh bucket cannot ship undescribed, and worded so it
+ *  is unmistakably a COUNTING aid rather than a closed set. */
+const FRAMING_NOTE = `shotSize and camera are FREE TEXT and are never rejected or rewritten. ` +
+    `They are bucketed only for the variety count — shot size into ` +
+    `${SHOT_SIZE_BUCKETS.join(' / ')}, camera into ${CAMERA_MOVE_BUCKETS.join(' / ')} — ` +
+    `and anything unrecognised counts as "other", which is a fine answer.`;
+/** What the caller actually sent for the script half, by omission. Same rule
+ *  as `shotParamsPatch`: an `undefined` value is not an absent key, and a
+ *  spread of undefineds is silent data loss on a merging route. */
+function shotScriptPatch(input) {
+    const out = {};
+    const raw = input;
+    for (const field of SCRIPT_TEXT_FIELDS) {
+        if (raw[field] !== undefined)
+            out[field] = raw[field];
+    }
+    if (input.continues !== undefined)
+        out.continues = input.continues;
+    return out;
+}
+/**
+ * The `params` half of a spec patch — ONLY the keys the caller actually named.
+ *
+ * 🚨 AN `undefined` VALUE IS NOT AN ABSENT KEY, AND THE DIFFERENCE IS SILENT
+ * DATA LOSS. `/agent/shots/update` merges `params` one level deep so that
+ * "anything you omit is left exactly as it was" — but a spread copies keys
+ * whose value is `undefined` too, so a hand-built object listing all ten fields
+ * overwrote the nine the caller never mentioned with `undefined`, and the
+ * tolerant reader on the far side then dropped them. `params: { duration: 9 }`
+ * silently cleared the aspect ratio, the resolution, the negative prompt and
+ * the face route. Building the object by omission is what keeps that promise.
+ *
+ * ONE builder, three callers (create / update / duplicate) — the ten field
+ * names were hand-listed twice before this, which is the same near-miss in
+ * waiting.
+ */
+function shotParamsPatch(p) {
+    const out = {};
+    if (!p)
+        return out;
+    for (const [k, v] of Object.entries(p))
+        if (v !== undefined)
+            out[k] = v;
+    return out;
+}
+/**
+ * `audioRefSpokenText` pairs POSITIONALLY with the audio references, so it can
+ * only be sent alongside them.
+ *
+ * Refused rather than truncated or silently re-keyed: the whole point of the
+ * field is that the WORDS are exact, and a misaligned array attaches one clip's
+ * line to another clip with nothing on screen to say so. Same rule
+ * `slates_generate_video` already applies.
+ */
+function checkSpokenTextAlignment(input) {
+    if (input.audioRefSpokenText === undefined)
+        return null;
+    const clips = input.refs?.['audio-reference'];
+    if (!clips || clips.length !== input.audioRefSpokenText.length) {
+        return ok({
+            requires_clarification: true,
+            missing: ['refs["audio-reference"]'],
+            message: `audioRefSpokenText pairs by position with refs["audio-reference"], so send both together ` +
+                `and at the same length (${input.audioRefSpokenText.length} line(s) vs ${clips?.length ?? 0} clip(s)). ` +
+                `Use "" for a clip with no speech.`,
+        });
+    }
+    return null;
+}
+/** Every asset reference a Shot input carries, flat, for one `resolveAssetRefs`
+ *  pass. Derived from the role list so a new role resolves badge codes too. */
+function shotRefInputs(input) {
+    const out = [];
+    for (const role of ORDERED_ATTACHMENT_ROLES) {
+        for (const r of input.refs?.[role] ?? [])
+            out.push({ ref: r, role });
+    }
+    if (input.firstFrameAssetId)
+        out.push({ ref: input.firstFrameAssetId, role: 'first frame' });
+    if (input.lastFrameAssetId)
+        out.push({ ref: input.lastFrameAssetId, role: 'last frame' });
+    if (input.params?.voiceReferenceAssetId)
+        out.push({ ref: input.params.voiceReferenceAssetId, role: 'voice reference' });
+    return out;
+}
+/**
+ * Op input → the `ShotSpec` shape the desktop stores.
+ *
+ * Badge codes resolve to ids HERE, at call time, against the project as it
+ * stands — never a mapping remembered from earlier in the conversation. A Shot
+ * that recorded a guessed id would look fine in a listing and compose to
+ * something else entirely.
+ */
+async function buildShotSpecInput(ctx, projectId, input) {
+    const refInputs = shotRefInputs(input);
+    const resolvedRefs = await resolveAssetRefs(ctx, projectId, refInputs.map((r) => r.ref));
+    const rid = (v) => (v ? (resolvedRefs.get(v)?.id ?? v) : null);
+    const refs = {};
+    for (const role of ORDERED_ATTACHMENT_ROLES) {
+        refs[role] = (input.refs?.[role] ?? []).map((v) => resolvedRefs.get(v)?.id ?? v);
+    }
+    // Positional in, KEYED out — the same re-keying `slates_generate_video` does,
+    // and for the same reason: an index means different clips depending on how the
+    // list was assembled, while an asset id cannot drift.
+    const audioIds = refs['audio-reference'] ?? [];
+    const spoken = {};
+    (input.audioRefSpokenText ?? []).forEach((text, i) => {
+        const id = audioIds[i];
+        if (id && text?.trim())
+            spoken[id] = text.trim();
+    });
+    return {
+        spec: {
+            prompt: input.prompt,
+            model: input.model ?? null,
+            // The prompt is recorded as written FOR this model. Swapping the model
+            // later diverges from it and the desktop card says so — the prompt is
+            // never rewritten (that is prompt enhancement, deleted 2026-08-01).
+            authoredFor: input.model ?? null,
+            params: {
+                ...shotParamsPatch(input.params),
+                ...(input.params?.voiceReferenceAssetId ? { voiceReferenceAssetId: rid(input.params.voiceReferenceAssetId) } : {}),
+            },
+            mentions: {
+                characterIds: input.characterIds ?? [],
+                environmentIds: input.environmentIds ?? [],
+                styleIds: input.styleIds ?? [],
+            },
+            refs,
+            firstFrameAssetId: rid(input.firstFrameAssetId),
+            lastFrameAssetId: rid(input.lastFrameAssetId),
+            audioRefSpokenText: spoken,
+        },
+        refEcho: describeResolvedRefs(refInputs, resolvedRefs),
+    };
+}
+/**
+ * The capability gate, applied to a SAVED recipe.
+ *
+ * It enforces exactly what the matching generate op enforces and no more: video
+ * goes through `assertVideoCapabilities` (the MODEL_CAPABILITIES SSOT), image
+ * does not, because `slates_generate_image`'s own per-model ratio check is the
+ * named open follow-up in the capability plan. A Shot that refused what
+ * `slates_generate_image` accepts would be a THIRD opinion about the same
+ * model, which is worse than the gap.
+ */
+function assertShotCapabilities(model, params) {
+    if (!model || !VIDEO_MODELS.includes(model))
+        return null;
+    const err = assertVideoCapabilities({
+        model,
+        aspectRatio: params?.aspectRatio,
+        videoResolution: params?.videoResolution,
+        duration: params?.duration,
+    });
+    return err ? ok(err) : null;
+}
+/**
+ * The registry cost key for a saved Shot, through the SAME builders every quote
+ * in this file uses (`videoCostKey` / `imageCostKey` / `audioCostKey`).
+ *
+ * Returns null when the Shot cannot be priced — no model, or a model this
+ * surface does not carry. The caller REPORTS that rather than quoting zero: a
+ * missing price displayed as free is the failure mode the whole pricing
+ * contract exists to prevent.
+ */
+function shotCostKey(detail) {
+    const model = detail.model;
+    if (!model)
+        return null;
+    const p = detail.params;
+    // Prefer the CLAMPED values the desktop will actually fire with; a listing row
+    // has none, so it falls back to the raw ones and is announced as a floor.
+    const fires = detail.firesWith;
+    if (AUDIO_MODELS.includes(model)) {
+        if (model === TTS_MODEL) {
+            const text = detail.composedPrompt ?? (detail.rawPrompt.trim() || detail.line?.trim() || '');
+            if (!text || text.length > TTS_MAX_CHARACTERS)
+                return null;
+            return audioCostKey({ model, characters: text.length });
+        }
+        const seconds = fires?.audioDurationSeconds ?? p.audioDurationSeconds;
+        if (!seconds)
+            return null;
+        return audioCostKey({ model: model, durationSeconds: seconds });
+    }
+    if (VIDEO_MODELS.includes(model)) {
+        const duration = fires?.duration ?? p.duration;
+        if (!duration)
+            return null;
+        const billed = (d) => (d > 0 ? Math.ceil(d - 0.05) : 0);
+        return videoCostKey({
+            model: model,
+            duration,
+            videoResolution: fires?.videoResolution ??
+                p.videoResolution ??
+                defaultVideoResolutionFor(model),
+            sound: p.sound,
+            seedanceFace: p.seedanceFace,
+            // `references` is absent on a LISTING row (it does not compose), so both
+            // of these read 0 there. That is why a listing quote is announced as a
+            // floor and `slates_get_shot` is the exact one.
+            referenceImages: (detail.references ?? []).filter((r) => r.kind === 'image').length,
+            videoRefSeconds: (detail.references ?? [])
+                .filter((r) => r.kind === 'video')
+                .reduce((n, r) => n + billed(r.durationSeconds ?? 0), 0),
+        });
+    }
+    if (IMAGE_MODELS.includes(model)) {
+        return imageCostKey(model, (fires?.imageResolution ?? p.imageResolution) ??
+            (model === 'nano-banana-2-lite' ? '1k' : '2k'), p.gptQuality ?? 'medium');
+    }
+    return null;
+}
+/** Credits for one Shot, and how many generations it fires.
+ *
+ *  `imageQuantity` multiplies IMAGE models only — the same condition the
+ *  desktop's `estimateCostFor` applies and the only lane `/agent/shots/*` sends
+ *  a `count` for. Multiplying it blindly would quote a video Shot 3× for a
+ *  param its request never carries, and the card beside it would say ×1. */
+function shotQuote(detail, byKey) {
+    const key = shotCostKey(detail);
+    const isImage = !!detail.model && IMAGE_MODELS.includes(detail.model);
+    const quantity = isImage ? (detail.params.imageQuantity ?? 1) || 1 : 1;
+    const per = key != null ? byKey.get(key) : undefined;
+    return { key, credits: (per ?? 0) * quantity, quantity };
+}
+export const createShot = {
+    id: 'slates_create_shot',
+    description: 'Write one beat of the piece — a Shot: its script line, its references with their roles, its model and params, and the prompt that fires. It needs NO image to exist, so a whole film can be written, arranged and priced before anything is generated. It lands in the storyboard automatically (the open scene, else the most recent storyboard) — never unfiled. ' +
+        FRAMING_NOTE,
+    input: z.object({
+        projectId: z.string().uuid(),
+        name: z.string().max(120).optional().describe('What to call it. Shown on the card; the prompt supplies one if you omit it.'),
+        prompt: z.string().min(1).max(4000).describe('The RAW prompt, @mentions intact. Never write "image 1" yourself — the composer numbers references, and a hand-written number is wrong the moment one moves.'),
+        model: z.string().optional().describe('Model id — the same ids slates_generate_image / slates_generate_video / slates_generate_audio take, and their descriptions carry the routing. Optional: a Shot can be planned before the model is decided.'),
+        params: shotParamsSchema,
+        refs: shotRefsSchema,
+        firstFrameAssetId: z.string().optional().describe('Starting frame for image-to-video (UUID or badge code).'),
+        lastFrameAssetId: z.string().optional().describe('Ending frame (UUID or badge code).'),
+        audioRefSpokenText: z.array(z.string()).optional().describe('Same order and length as refs["audio-reference"]; use "" for a clip with no words. The model RE-TRANSCRIBES a supplied take, so only text decides the words.'),
+        characterIds: z.array(z.string().uuid()).optional().describe('Characters the prompt @mentions — stored as ENTITY ids, so updating the character updates every Shot that names it.'),
+        environmentIds: z.array(z.string().uuid()).optional(),
+        styleIds: z.array(z.string().uuid()).optional(),
+        frameId: z.string().uuid().optional().describe('Put it in this exact frame. Optional — omit it and the Shot files itself into a scene, creating a storyboard named after the project if there is none.'),
+        sceneId: z.string().uuid().optional().describe('File it into this scene. Optional; ignored when frameId is given.'),
+        ...shotScriptSchema,
+    }),
+    async run(input, ctx) {
+        const capErr = assertShotCapabilities(input.model, input.params);
+        if (capErr)
+            return capErr;
+        const alignErr = checkSpokenTextAlignment(input);
+        if (alignErr)
+            return alignErr;
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('shots', 'saved Shots');
+        const { spec, refEcho } = await buildShotSpecInput(ctx, input.projectId, input);
+        const r = await desktop.post('/agent/shots', {
+            projectId: input.projectId,
+            name: input.name,
+            spec: { ...spec, ...shotScriptPatch(input) },
+            frameId: input.frameId ?? null,
+            sceneId: input.sceneId ?? null,
+        });
+        // The CODE is the address the user sees on the row — say it back so the
+        // next call, and the next sentence to the user, can point at it.
+        return ok(r.shot, `${r.shot?.code || 'Shot'} — "${r.shot?.name || 'Untitled'}". ${refEcho}`.trim());
+    },
+};
+export const updateShot = {
+    id: 'slates_update_shot',
+    description: 'Change part of a Shot, or attach/detach it from a storyboard frame — anything you omit is left exactly as it was. ' +
+        FRAMING_NOTE,
+    input: z.object({
+        shotId: z.string().describe('The Shot id, or its SHOT-A code as shown on the row.'),
+        projectId: z.string().uuid().describe('The Shot\'s project — badge codes and entity ids resolve against it.'),
+        name: z.string().max(120).optional(),
+        prompt: z.string().max(4000).optional(),
+        model: z.string().optional(),
+        params: shotParamsSchemaTerse,
+        refs: shotRefsSchemaTerse,
+        firstFrameAssetId: z.string().optional(),
+        lastFrameAssetId: z.string().optional(),
+        audioRefSpokenText: z.array(z.string()).optional(),
+        characterIds: z.array(z.string().uuid()).optional(),
+        environmentIds: z.array(z.string().uuid()).optional(),
+        styleIds: z.array(z.string().uuid()).optional(),
+        attachFrameId: z.string().uuid().optional().describe('Attach this Shot to a storyboard frame.'),
+        detachFrameId: z.string().uuid().optional().describe('Detach it from a frame. The Shot itself survives.'),
+        posterAssetId: z.string().nullable().optional().describe('Which reference represents this Shot as a thumbnail. Defaulted automatically (first frame, else the first image reference, else the newest take) — only set it to OVERRIDE, and pass null to go back to the default.'),
+        ...shotScriptSchemaTerse,
+    }),
+    async run(input, ctx) {
+        const capErr = assertShotCapabilities(input.model, input.params);
+        if (capErr)
+            return capErr;
+        const alignErr = checkSpokenTextAlignment(input);
+        if (alignErr)
+            return alignErr;
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('shots', 'saved Shots');
+        const { spec } = await buildShotSpecInput(ctx, input.projectId, input);
+        // Only send the halves the caller actually named; the route merges a PARTIAL
+        // spec over the stored one, so an omitted field is never silently cleared.
+        const patch = {};
+        if (input.prompt !== undefined)
+            patch.prompt = input.prompt;
+        if (input.model !== undefined) {
+            patch.model = input.model;
+            // 🚨 `authoredFor` is NOT re-stamped on a model swap. The whole point of
+            // recording it is that the prompt stays written for the model it was
+            // written for — the grammars genuinely differ — so the card can say so.
+        }
+        if (input.params !== undefined)
+            patch.params = spec.params;
+        // 🚨 ONLY THE ROLES THE CALLER NAMED. `buildShotSpecInput` always returns a
+        // COMPLETE refs record, and the route merges one level deep — so sending all
+        // five would clear every role the caller never mentioned. Clearing a role is
+        // explicit: send `[]`.
+        if (input.refs !== undefined) {
+            const built = spec.refs;
+            const named = {};
+            for (const role of ORDERED_ATTACHMENT_ROLES) {
+                if (input.refs[role] !== undefined)
+                    named[role] = built[role];
+            }
+            if (Object.keys(named).length > 0)
+                patch.refs = named;
+        }
+        if (input.firstFrameAssetId !== undefined)
+            patch.firstFrameAssetId = spec.firstFrameAssetId;
+        if (input.lastFrameAssetId !== undefined)
+            patch.lastFrameAssetId = spec.lastFrameAssetId;
+        if (input.audioRefSpokenText !== undefined)
+            patch.audioRefSpokenText = spec.audioRefSpokenText;
+        Object.assign(patch, shotScriptPatch(input));
+        // Same rule for the three mention lists — naming one must not clear the
+        // other two.
+        {
+            const built = spec.mentions;
+            const named = {};
+            if (input.characterIds !== undefined)
+                named.characterIds = built.characterIds;
+            if (input.environmentIds !== undefined)
+                named.environmentIds = built.environmentIds;
+            if (input.styleIds !== undefined)
+                named.styleIds = built.styleIds;
+            if (Object.keys(named).length > 0)
+                patch.mentions = named;
+        }
+        const r = await desktop.post('/agent/shots/update', {
+            id: input.shotId,
+            data: {
+                name: input.name,
+                ...(Object.keys(patch).length > 0 ? { spec: patch } : {}),
+                attachFrameId: input.attachFrameId,
+                detachFrameId: input.detachFrameId,
+                posterAssetId: input.posterAssetId,
+            },
+        });
+        return ok(r.shot);
+    },
+};
+export const duplicateShot = {
+    id: 'slates_duplicate_shot',
+    description: 'Fork a saved Shot, changing the prompt, the model or any param on the COPY in the same call — make one, fork it five times, change one thing on each. The original is never touched.',
+    input: z.object({
+        shotId: z.string().describe('The Shot id, or its SHOT-A code.'),
+        name: z.string().max(120).optional().describe('Name for the copy (default: the original plus "copy").'),
+        prompt: z.string().max(4000).optional().describe('Replace the prompt on the copy. Omit to keep the original\'s.'),
+        model: z.string().optional().describe('Point the copy at a different model — the A/B lever. The prompt is NOT rewritten, and the copy records which model it was written for.'),
+        params: shotParamsSchemaTerse,
+        frameId: z.string().uuid().nullable().optional().describe('Attach the copy to this frame. Omit to keep the original\'s frame; pass null to leave it unattached.'),
+    }),
+    async run(input, ctx) {
+        const capErr = assertShotCapabilities(input.model, input.params);
+        if (capErr)
+            return capErr;
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('shots', 'saved Shots');
+        // Only the halves actually named. The route merges two levels deep, so an
+        // omitted param on the copy keeps the original's value rather than clearing it.
+        const spec = {};
+        if (input.prompt !== undefined)
+            spec.prompt = input.prompt;
+        if (input.model !== undefined)
+            spec.model = input.model;
+        if (input.params !== undefined) {
+            const voiceRef = input.params.voiceReferenceAssetId;
+            if (voiceRef && !UUID_RE.test(voiceRef)) {
+                const { shot } = await desktop.get('/agent/shots/get', { id: input.shotId });
+                const built = await buildShotSpecInput(ctx, shot.projectId, { params: input.params });
+                spec.params = built.spec.params;
+            }
+            else {
+                spec.params = shotParamsPatch(input.params);
+            }
+        }
+        const r = await desktop.post('/agent/shots/duplicate', {
+            id: input.shotId,
+            name: input.name,
+            ...(Object.keys(spec).length > 0 ? { spec } : {}),
+            frameId: input.frameId,
+        });
+        return ok(r.shot, `Forked into "${r.shot?.name || 'Untitled'}".`);
+    },
+};
+/**
+ * The variety strip, in words. GENERATED from the report — never hand-typed,
+ * and never a judgement: it states what is there and stops.
+ *
+ * 🔑 IT RIDES THE OP RESULT, NOT A SKILL. Measured on the 2026-08-30 eval
+ * harness: a rule inlined into an op description moved compliance from 0/8 to
+ * 30/32, while the same guidance behind `slates_get_prompting_guide` sat at 13%
+ * before and 13% after. Guidance the agent must CHOOSE to fetch does not reach
+ * it — so the counts arrive in the result it is already reading.
+ *
+ * Slates counts; the agent judges. No suggested shot size, no auto-varied
+ * camera, no "we changed this for you".
+ */
+function describeVarietyReport(v) {
+    if (!v || v.cuts === 0)
+        return '';
+    const parts = [];
+    const topSize = v.shotSizes.find((b) => b.bucket !== 'other');
+    if (topSize && topSize.count >= 2)
+        parts.push(`${topSize.count}/${v.cuts} ${topSize.bucket}`);
+    const topMove = v.cameraMoves.find((b) => b.bucket !== 'other');
+    if (topMove && topMove.count >= 2)
+        parts.push(`${topMove.count} ${topMove.bucket}`);
+    for (const run of v.runs)
+        parts.push(`${run.length} ${run.bucket} in a row`);
+    // 🚨 TWO DENOMINATORS, NAMED. Rhythm is counted in CUTS and money in
+    // GENERATIONS; several cuts routinely live inside one generation.
+    const head = `${v.generations} generation(s) · ${v.cuts} cut(s) · ` +
+        `${v.runtimeSeconds == null ? 'no runtime yet' : `${v.runtimeSeconds}s`}` +
+        (v.cutsWithoutDuration > 0 ? ` (${v.cutsWithoutDuration} cut(s) have no duration)` : '');
+    const variety = parts.length > 0 ? `\nVARIETY: ${parts.join(' · ')}` : '';
+    const words = v.words > 0
+        ? `\nWORDS: ${v.words} written` +
+            (v.wordBudget != null
+                ? `, ~${v.wordBudget} fit the runtime at ${SPEECH_RATE.conversational.wpm} wpm` +
+                    ` (measured across ${SPEECH_RATE.conversational.n} real ads)`
+                : '')
+        : '';
+    const overLong = v.overLongLines.length > 0
+        ? `\n⚠ ${v.overLongLines.length} line(s) cannot fit their cut at ANY plausible delivery` +
+            ` (over ${SPEECH_RATE.ceiling.wpm} wpm, the fastest read in the corpus).` +
+            ` Split the line or merge the cut — slates_split_shot / slates_merge_shots.`
+        : '';
+    return `${head}${variety}${words}${overLong}`;
+}
+export const listShots = {
+    id: 'slates_list_shots',
+    description: "Read the shot list — every Shot as a compact row IN BOARD ORDER (scene, then position), with the piece's cut count, runtime, credit floor and its variety distribution. Read this before firing a set: if one shot size is the plurality or three cuts in a row share a camera move, the batch is wrong before a credit is spent.",
+    input: z.object({
+        projectId: z.string().uuid(),
+        storyboardId: z.string().uuid().optional().describe('Only Shots attached to a frame in this storyboard.'),
+        frameId: z.string().uuid().optional().describe('Only Shots attached to this frame.'),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('shots', 'saved Shots');
+        const r = await desktop.get('/agent/shots', {
+            projectId: input.projectId,
+            storyboardId: input.storyboardId,
+            frameId: input.frameId,
+        });
+        const rows = r.shots ?? [];
+        // Deliberately does NOT compose each Shot — that is what slates_get_shot is
+        // for. A listing that composed every row would make browsing cost as much as
+        // auditing.
+        const registry = await ctx.cloud().get('/api/agent/models');
+        const byKey = new Map(registry.models.map((m) => [m.model, creditCost(m)]));
+        let total = 0;
+        let unpriced = 0;
+        const shots = rows.map((s) => {
+            const q = shotQuote(s, byKey);
+            if (q.key == null || !byKey.has(q.key))
+                unpriced += 1;
+            total += q.credits;
+            return {
+                id: s.id,
+                code: s.code,
+                name: s.name,
+                scene: s.sceneName,
+                position: s.position,
+                model: s.model,
+                references: s.referenceCount,
+                cuts: s.cuts,
+                runtime_seconds: s.runtimeSeconds,
+                speaker: s.speaker,
+                line: s.line,
+                delivery: s.delivery,
+                action: s.action,
+                prop: s.prop,
+                shot_size: s.shotSize,
+                camera: s.camera,
+                continues: s.continues,
+                credits: q.credits,
+            };
+        });
+        return ok({ shots, total_credits: total, unpriced, variety: r.variety }, `${shots.length} shot(s), at least ${fmtCredits(total)} to fire them all` +
+            (unpriced > 0 ? ` (${unpriced} could not be priced — no model or no duration set).` : '.') +
+            ' 🚨 That is a FLOOR, not the bill: a listing does not compose, so the two dimensions that' +
+            ' depend on the reference set — Seedance reference-clip seconds and MiniMax reference images' +
+            ' past the free five — are missing from it. slates_get_shot prices one exactly, and' +
+            ' slates_generate_from_shots quotes the set exactly before it fires anything.' +
+            (describeVarietyReport(r.variety) ? `
+
+${describeVarietyReport(r.variety)}` : ''));
+    },
+};
+export const getShot = {
+    id: 'slates_get_shot',
+    description: 'Read one Shot in full — the COMPOSED prompt the request will actually carry, its numbered references, anything it points at that no longer exists, and its exact credit quote. Audit your own work here before firing.',
+    input: z.object({
+        shotId: z.string().describe('The Shot id, or its SHOT-A code as shown on the row.'),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('shots', 'saved Shots');
+        const r = await desktop.get('/agent/shots/get', { id: input.shotId });
+        const registry = await ctx.cloud().get('/api/agent/models');
+        const byKey = new Map(registry.models.map((m) => [m.model, creditCost(m)]));
+        const q = shotQuote(r.shot, byKey);
+        return ok({ ...r.shot, cost_key: q.key, credits: q.credits }, `"${r.shot.name || 'Untitled'}" — ${r.shot.model ?? 'no model set'}, ` +
+            (q.key && !r.shot.blocked
+                ? `${fmtCredits(q.credits)} (${q.key}).`
+                : `CANNOT FIRE YET: ${r.shot.blocked ?? 'not priceable — set a model and a duration.'}`) +
+            (r.shot.blocked ? '' : ` Fires with ${JSON.stringify(r.shot.firesWith)}.`) +
+            `\nCOMPOSED PROMPT (what the model is told): ${r.shot.composedPrompt}`);
+    },
+};
+/**
+ * SPLIT and MERGE — the chop decision, and the only two cross-row operations on
+ * this surface.
+ *
+ * 🔑 THIS IS THE EXECUTIVE CALL, AND IT IS WHY THEY ARE OPS. *"Sometimes you
+ * might be using more dialogue in one single 30-second generation. Sometimes it
+ * might just be a 4-second generation of one line."* Merging five lines into
+ * one long take or splitting them into five short ones changes the rhythm AND
+ * the price, and the agent has to be able to re-chop what it wrote.
+ *
+ * 🚨 NEITHER EDITS TEXT AS A SIDE EFFECT. Split moves the text after a caret
+ * the caller placed; merge joins two texts at their boundary. Nothing else in
+ * either row is rewritten. That property is what keeps a finished script
+ * finished, and it is the acceptance test for anything added here later.
+ */
+export const splitShot = {
+    id: 'slates_split_shot',
+    description: 'Split one Shot into two at a caret in its line. The text after the caret moves to the new Shot, which INHERITS the model, params and references and lands directly after it in the scene. A mid-sentence split marks the second row as continuing the first — one sentence, two cuts, which is the signature voiceover move. Takes stay with the first row. Omit the caret to add a sibling cut with the same visuals and no words moved.',
+    input: z.object({
+        shotId: z.string().describe('The Shot id, or its SHOT-A code.'),
+        caret: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe("Character offset into the Shot's `line` to cut at. Omitted = the end of the line."),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('shots', 'saved Shots');
+        const r = await desktop.post('/agent/shots/split', { id: input.shotId, caret: input.caret });
+        return ok(r, `Split into ${r.first?.code || 'the first Shot'} and ` +
+            `${r.second?.code || 'a new Shot'}. Duration was INHERITED, not divided — ` +
+            `set it on each if the chop changed how long they run.`);
+    },
+};
+export const mergeShots = {
+    id: 'slates_merge_shots',
+    description: "Merge two adjacent Shots into one. Texts join, references union, the FIRST Shot's model and params win, and the durations SUM — which may exceed the model's window, in which case it is shown and never blocked. Lossy in one direction: the second Shot's model and params are discarded, and there is no undo (the takes are the history).",
+    input: z.object({
+        firstId: z.string().describe('The Shot that survives — its model and params win. Id or SHOT-A code.'),
+        secondId: z.string().describe('The Shot folded into it. Id or SHOT-A code.'),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('shots', 'saved Shots');
+        const r = await desktop.post('/agent/shots/merge', {
+            firstId: input.firstId,
+            secondId: input.secondId,
+        });
+        return ok(r.shot, `Merged into ${r.shot?.code || 'one Shot'} — ` +
+            `${r.shot?.cuts ?? 1} cut(s), ${r.shot?.runtimeSeconds ?? 'no'} second(s).`);
+    },
+};
+export const generateFromShots = {
+    id: 'slates_generate_from_shots',
+    billable: true,
+    description: 'Generate from saved Shots, ONE AFTER ANOTHER, with a single quote and a single approval for the whole set. It blocks until the last one lands, so a set of video Shots can outlast the HTTP timeout while the run keeps going — if that happens, poll slates_get_shot for each Shot\'s generationIds instead of re-firing, which double-spends.',
+    input: z.object({
+        shotIds: z.array(z.string()).min(1).max(20).describe('The Shots to fire, in order — ids or SHOT-A codes.'),
+        confirm: z.boolean().optional().describe('Set true after explicit user OK on the TOTAL below.'),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('shots', 'saved Shots');
+        // Resolve and price every Shot BEFORE anything fires. A dead id found
+        // halfway through a batch means a partially-fired, partially-BILLED run.
+        const details = [];
+        for (const id of input.shotIds) {
+            const r = await desktop.get('/agent/shots/get', { id });
+            details.push(r.shot);
+        }
+        const registry = await ctx.cloud().get('/api/agent/models');
+        const byKey = new Map(registry.models.map((m) => [m.model, creditCost(m)]));
+        const quotes = details.map((d) => ({ detail: d, ...shotQuote(d, byKey) }));
+        const total = quotes.reduce((n, q) => n + q.credits, 0);
+        const largest = quotes.reduce((m, q) => (q.credits > m ? q.credits : m), 0);
+        const unpriced = quotes.filter((q) => q.key == null || !byKey.has(q.key));
+        const blockedShots = details.filter((d) => d.blocked);
+        if (!input.confirm) {
+            // ONE approval for the set, itemised. N approvals would re-introduce the
+            // friction the batch exists to remove; the safety is the STATED TOTAL,
+            // prominent — count, total, and the largest single Shot.
+            const lines = quotes.map((q) => `  - ${q.detail.name || 'Untitled'} · ${q.detail.model ?? 'no model'} · ` +
+                (q.key ? fmtCredits(q.credits) : 'NOT PRICEABLE'));
+            const blockedLines = blockedShots.map((d) => `  ✖ ${d.name || 'Untitled'} WILL NOT FIRE: ${d.blocked}`);
+            const warnings = details
+                .filter((d) => d.missing || d.unresolvedTokens?.length)
+                .map((d) => `  ! ${d.name || 'Untitled'}: ${d.missing ? 'references something that no longer exists' : ''}` +
+                `${d.unresolvedTokens?.length ? ` ${d.unresolvedTokens.join(', ')} match nothing saved (sent as written, no reference attached)` : ''}`);
+            return ok({
+                requires_confirm: true,
+                count: quotes.length,
+                total_credits: total,
+                largest_single_credits: largest,
+                blocked_count: blockedShots.length,
+                shots: quotes.map((q) => ({
+                    id: q.detail.id,
+                    name: q.detail.name,
+                    model: q.detail.model,
+                    cost_key: q.key,
+                    credits: q.credits,
+                    blocked: q.detail.blocked,
+                })),
+            }, `Firing ${quotes.length} Shot(s) SEQUENTIALLY.\n` +
+                `TOTAL ${fmtCredits(total)} · largest single ${fmtCredits(largest)}\n` +
+                lines.join('\n') +
+                (blockedLines.length > 0 ? `\n${blockedLines.join('\n')}` : '') +
+                (unpriced.length > 0
+                    ? `\n  ! ${unpriced.length} shot(s) could not be priced — they will still be attempted and may fail.`
+                    : '') +
+                (warnings.length > 0 ? `\n${warnings.join('\n')}` : '') +
+                `\n\nRe-call with confirm: true after explicit user OK on that total.`);
+        }
+        const r = await desktop.post('/agent/shots/batch-generate', { shotIds: input.shotIds });
+        const failedLines = (r.results ?? [])
+            .filter((x) => x.status === 'failed')
+            .map((x) => `  ✗ ${x.name || 'Untitled'}: ${x.error ?? 'failed'}`);
+        return ok(r, `${r.succeeded} of ${r.total} generated for about ${fmtCredits(total)}.` +
+            (failedLines.length > 0
+                ? // Reported, never retried: an agent that treats a failed render as
+                    // something to try again spends credits before anyone notices.
+                    `\n${failedLines.join('\n')}\nThese were NOT retried. Read each error, fix the Shot, and re-fire only what you meant to.`
+                : '') +
+            ` ${BACKGROUND_REVIEW_POINTER}`);
+    },
+};
 function resolveGuideTopic(topic) {
     const t = topic.trim().toLowerCase();
     if (SKILLS[t])
@@ -3750,17 +4891,29 @@ 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.
+    // Audio — the TTS seat FIRST, then seed-audio, then eleven-sfx.
+    //
+    // 🚨 "tts"/"voiceover" ROUTE HERE AGAIN (2026-09-05). They used to land on
+    // seed-audio because there was no TTS surface at all; there is one now, so
+    // leaving them there would hand a scene-renderer's guide to someone asking
+    // about speech. They must still never reach the ElevenLabs guide, which is
+    // SFX-only.
+    if (t.startsWith('inworld') ||
+        t === 'tts' ||
+        t === 'text-to-speech' ||
+        t === 'text to speech' ||
+        t === 'voiceover' ||
+        t === 'voice') {
+        return 'slates-prompting-inworld-tts';
+    }
+    // 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). `dialogue`
+    // stays here: dialogue inside a SCENE is what seed-audio is for, while a
+    // single voice saying a single line is the TTS seat above.
     if (t.startsWith('seed-audio') ||
         t === 'seed audio' ||
         t === 'audio' ||
-        t === 'tts' ||
-        t === 'voiceover' ||
         t === 'dialogue') {
         return 'slates-prompting-seed-audio';
     }
@@ -3819,25 +4972,72 @@ function describeGuideTopics() {
 }
 export const getPromptingGuide = {
     id: 'slates_get_prompting_guide',
-    description: "Return the full markdown of a bundled Slates prompting/workflow guide. MCP-only clients (Claude Desktop, Smithery) don't get the CLI-installed skill files — call this instead. Accepts a guide name or a model id (e.g. 'veo-3.1-fast', 'kling-v3.0-pro', 'seedance-2', 'nano-banana-2') which maps to the right guide. ALWAYS read 'slates-cost-discipline' plus the relevant model guide before your first generation in a session.",
+    description: 'For app help and exact UI instructions use topic "app-manual" with a query such as "voice recording". This returns the canonical product manual, shared by every agent surface. ' +
+        // 🚨 NO "ALWAYS READ THIS FIRST" SENTENCE. It stood here for months and was
+        // MEASURED at 13% compliance before and after the enforcement work — pointer
+        // prose is the shape that does not move the agent. What replaced it is
+        // structural: the never-use list rides the generate ops' descriptions and
+        // the craft card rides the estimate result, so the facts arrive whether or
+        // not this op is ever called.
+        "Return a bundled Slates prompting/workflow guide. MCP-only clients (Claude Desktop, Smithery) don't get the CLI-installed skill files — call this instead. Accepts a guide name or a model id ('veo-3.1-fast', 'kling-v3.0-pro', 'seedance-2', 'nano-banana-2'), which maps to the right guide. Reach for it when a card is not enough: the failure modes, the worked examples and the sources are only in the full text.",
     input: z.object({
+        query: z.string().max(200).optional().describe('For app-manual: keywords to retrieve relevant UI sections. Omit for the entire manual.'),
         topic: z
             .string()
             .min(1)
             .describe(`Guide name, model id, or style name. ${describeGuideTopics()}`),
+        depth: z.enum(['card', 'full']).optional().describe('"card" returns just the levers block (a few hundred words — the same card slates_estimate_generation_cost already attached, so usually redundant). "full" (default) returns the whole guide, up to several thousand words.'),
     }),
     async run(input) {
+        if (input.topic.trim().toLowerCase() === 'app-manual') {
+            const content = appManualSections(input.query);
+            return { text: content, data: { topic: 'app-manual', bytes: Buffer.byteLength(content, 'utf8') } };
+        }
         const resolved = resolveGuideTopic(input.topic);
         const content = resolved ? SKILLS[resolved] : undefined;
         if (!resolved || content === undefined) {
             throw new Error(`Unknown guide topic: ${input.topic}. Valid topics: ${Object.keys(SKILLS).sort().join(', ')}`);
         }
+        if (input.depth === 'card') {
+            const card = describeCraftCard(resolved);
+            if (card) {
+                return { text: card, data: { topic: resolved, depth: 'card', bytes: Buffer.byteLength(card, 'utf8') } };
+            }
+            // No card on this guide — returning nothing would read as "no guidance",
+            // which is worse than a fall-through the result names.
+        }
         return {
             text: content,
-            data: { topic: resolved, bytes: Buffer.byteLength(content, 'utf8') },
+            data: { topic: resolved, depth: 'full', bytes: Buffer.byteLength(content, 'utf8') },
         };
     },
 };
+/**
+ * The one op that changes what OTHER ops are visible.
+ *
+ * 🚨 IT EXISTS BECAUSE THE SURFACE IS 112 KB AND EVERY TURN PAYS FOR ALL OF IT.
+ * The desktop Studio Agent sends `core` plus this; a group arrives when the
+ * work needs it and stays for the rest of the run. On the MCP surface every op
+ * is registered up front (a stdio server has no run to append to), so this
+ * returns the same definitions as a plain listing — useful either way, since
+ * it is also how an agent asks "what else can you do".
+ */
+export const loadTools = {
+    id: 'slates_load_tools',
+    description: 'Load a deferred group of tools for the rest of this session. The core surface is always present; these four groups are held back so every turn does not pay for the whole registry. ' +
+        Object.entries(GROUP_SUMMARY)
+            .map(([g, s]) => `"${g}": ${s}`)
+            .join('. ') +
+        '. Call it the moment the work needs one of those — the tools arrive in the same turn\'s result and stay loaded. On MCP clients every tool is already registered and this just lists the group.',
+    input: z.object({
+        group: z.enum(['library', 'timeline', 'admin', 'blender']).describe('Which group to load.'),
+    }),
+    async run(input) {
+        const defs = toolDefinitions(ALL_OPERATIONS.filter((op) => groupFor(op.id) === input.group), { surface: 'mcp' });
+        return ok({ group: input.group, tools: defs }, `Loaded the "${input.group}" group — ${defs.length} tool(s) now available:\n` +
+            defs.map((d) => `${d.name}: ${d.description.split(/(?<=\.)\s/)[0]}`).join('\n'));
+    },
+};
 // ── Blender previs ──────────────────────────────────────────────
 //
 // The only ops that talk to a third transport: a localhost socket into a
@@ -4027,6 +5227,7 @@ export const ALL_OPERATIONS = [
     generateImage,
     generateVideo,
     generateAudio,
+    listVoices,
     generateLipSync,
     generateMotionTransfer,
     editVideo,
@@ -4068,14 +5269,31 @@ export const ALL_OPERATIONS = [
     updateFrame,
     batchUpdateFrames,
     deleteFrame,
+    // ── Shots: the prompt bar, serialized ────────────────────────────────
+    // Beside the storyboard ops because that is the neighbourhood they belong to
+    // — structure, not spend. The one that spends sits last in the group.
+    createShot,
+    updateShot,
+    duplicateShot,
+    // Split and merge are the CHOP decision — where the rhythm and the price are
+    // actually decided. They sit beside the writers, not with the spender.
+    splitShot,
+    mergeShots,
+    listShots,
+    getShot,
+    generateFromShots,
     getPromptingGuide,
+    loadTools,
     // ── Blender previs, LAST and deliberately ────────────────────────────
-    // This order is not cosmetic: `slate/src/main/studio-agent/ops.ts` maps this
-    // array straight into the Anthropic `tools` array, and that block sits inside
-    // the desktop Studio Agent's PROMPT-CACHED PREFIX. These six landed at the
-    // TOP, which put a third transport nobody without Blender can reach ahead of
-    // `slates_get_workspace_state` in every conversation the app has. They are a
-    // niche lane off the end of the surface, and the list should read that way.
+    // These six landed at the TOP once, which put a third transport nobody
+    // without Blender can reach ahead of `slates_get_workspace_state` in every
+    // conversation the app has. They are a niche lane off the end of the surface,
+    // and the list should read that way.
+    //
+    // ⚠️ POSITION NO LONGER CONTROLS COST. They are the `blender` tier group (see
+    // surface.ts), so the desktop does not send them at all until
+    // `slates_load_tools` asks for them. Order here is now the READING order on
+    // the MCP surface, which sends everything — still last, same reason.
     blenderStatus,
     blenderExecute,
     blenderScene,
@@ -4083,4 +5301,32 @@ export const ALL_OPERATIONS = [
     blenderSearchDocs,
     blenderRenderBlocking,
 ];
+// ── Surface metadata, stamped once at load ──────────────────────
+//
+// 🚨 DERIVED, NEVER HAND-SET PER OP. Every op gets all four MCP annotations and
+// its tier here, from the rules in `surface.ts`, so a new op cannot ship
+// un-annotated (which a host reads as "not destructive") or accidentally
+// deferred. The lockstep check re-derives the hints INDEPENDENTLY from each
+// op's own transport verbs, so a read-only claim on an op that posts is caught
+// rather than trusted.
+for (const op of ALL_OPERATIONS) {
+    const mutable = op;
+    mutable.annotations = annotate(mutable.id, mutable.billable);
+    mutable.tier = tierFor(mutable.id);
+    mutable.group = groupFor(mutable.id);
+}
+// A group naming an op that does not exist would silently defer nothing, and
+// the tool it meant to hold back would keep costing prefix bytes forever.
+{
+    const ids = new Set(ALL_OPERATIONS.map((o) => o.id));
+    for (const [group, members] of Object.entries(OPERATION_GROUPS)) {
+        for (const id of members) {
+            if (!ids.has(id)) {
+                throw new Error(`[operations] OPERATION_GROUPS.${group} names "${id}", which is not in ALL_OPERATIONS. ` +
+                    `Fix the id or drop the entry — a phantom member defers nothing.`);
+            }
+        }
+    }
+}
+export { toolDefinitions, toolDefinition, groupFor, tierFor, OPERATION_GROUPS, GROUP_SUMMARY } from './surface.js';
 //# sourceMappingURL=index.js.map