@slatesvideo/shared 0.6.11 → 0.7.1

package/dist/operations/index.js

@@ -1,4 +1,6 @@
-import { MINIMAX_MAX_REFERENCE, minimaxMaxReferenceTokens, MODEL_CAPABILITIES, GPT_QUALITY_TIERS, GPT_BACKGROUNDS } from '../prompts/model-capabilities.js';
+import { MAX_IMAGE_VARIATIONS } from '../prompts/generation-policy.js';
+import { retrieveGuide, guideSections } from '../prompts/guide-retrieval.js';
+import { MINIMAX_MAX_REFERENCE, minimaxMaxReferenceTokens, MODEL_CAPABILITIES, GPT_QUALITY_TIERS, DEFAULT_GPT_QUALITY, GPT_BACKGROUNDS } from '../prompts/model-capabilities.js';
 // Operations layer — the ONE place every Slates agent tool is defined.
 // Both the MCP server and the CLI register these as their tool / command
 // surface. Every operation:
@@ -23,7 +25,11 @@ import { multimodalRefSummary, multimodalRefModels, seedanceTaskIntentWords,
 // slates-mcp/CLAUDE.md forbids restating it in an op description, and this
 // file did it anyway for 1,282 characters that repeated MODEL_FACTS phrase
 // for phrase. Edit model-facts.ts; both surfaces follow.
-describeRouting, } from '../prompts/model-facts.js';
+describeRouting, 
+// The default seat per kind, READ from `tier` — never a literal model id.
+defaultModelFor, 
+// The seat a built-in tool renders on, READ from TOOL_SEAT (generation-policy.ts).
+toolModelFor, CHATGPT_FRAMING_RATIOS, } from '../prompts/model-facts.js';
 // 🚨 MODEL CAPABILITY SSOT. Aspect ratios, video resolutions and durations are
 // VALIDATED against and DESCRIBED from `MODEL_CAPABILITIES` — this file must
 // never re-state one of those constraints as a literal enum or a sentence
@@ -33,16 +39,12 @@ describeRouting, } from '../prompts/model-facts.js';
 // `videoResolution` line that never mentioned Kling, and 4s quoted for Veo at
 // 1080p. A customer burned a round trip on `4:5` + Seedance: accepted here,
 // queued, credits reserved, rejected by the provider asynchronously.
-import { AGENT_ROUTE_PROVIDER, aspectRatioUnion, videoResolutionUnion, durationBounds, aspectRatiosFor, getModelCapability, defaultVideoResolutionFor, checkAspectRatio, checkVideoResolution, checkDuration, describeAspectRatios, describeVideoResolutions, describeDurations, describeReferenceImageCaps, } from '../prompts/model-capabilities.js';
-// 🚨 "LOAD THE GUIDE" MADE STRUCTURAL. The never-use token lists are EXTRACTED
-// from the skill files (between `@banned` markers) and inlined into the two
-// generate ops' descriptions, which are always in context on both surfaces —
-// no call to skip, no discretion. `bannedTokenWarning` then reports what the
-// submitted prompt actually contained, in the result, without blocking it.
-// Never hand-type one of these tokens here; edit the skill.
+import { AGENT_ROUTE_PROVIDER, defaultImageResolutionFor, aspectRatioUnion, videoResolutionUnion, durationBounds, aspectRatiosFor, getModelCapability, defaultVideoResolutionFor, checkAspectRatio, checkVideoResolution, checkDuration, describeAspectRatios, describeVideoResolutions, describeDurations, describeReferenceImageCaps, } from '../prompts/model-capabilities.js';
+// Per-model warnings are extracted from skill @banned blocks. They ride the
+// selected model's estimate and submitted-prompt result, never another model's schema.
 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
+// it rides the selected estimate. 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.
@@ -161,13 +163,14 @@ export const ELEVEN_SFX_DEFAULT_SECONDS = 4;
 // 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.
+// At $25/M characters (Inworld On-Demand, read 2026-09-28) and a 1.5× markup,
+// a 200-character line is $0.0075 of basis — under `MIN_AUDIO_BILLABLE_DOLLARS`
+// ($0.01), so it bills the floor. The floor stops biting at 267 characters, so
+// the 250 bucket is floor-bound. A narrower bucket would put several buckets on
+// the one floor price, and the displayed rate would stop tracking cost; a much
+// WIDER 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
@@ -254,7 +257,7 @@ function backgroundSubmitted(kind, ids, extra, note) {
 // ── Workspace + identity ────────────────────────────────────────
 export const getWorkspaceState = {
     id: 'slates_get_workspace_state',
-    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.',
+    description: 'Snapshot of the user\'s Slates workspace: the project list (most recent first) plus the active project in full when you name one.',
     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.'),
@@ -287,9 +290,195 @@ export const getWorkspaceState = {
                 ? { truncated: `${rows.length - compact.length} more — raise limit or call slates_list_projects.` }
                 : {}),
             activeProject,
+            generationDefaults: {
+                imageModel: defaultModelFor('image'),
+                imageResolution: defaultImageResolutionFor(defaultModelFor('image')),
+                gptQuality: DEFAULT_GPT_QUALITY,
+                videoModel: defaultModelFor('video'),
+            },
         });
     },
 };
+/**
+ * What the user has selected in the app RIGHT NOW. The selection band in every
+ * grid (images, clips, audio, storyboard shots) reports its ids to the desktop,
+ * and the image viewer reports what is open; the desktop looks codes and labels
+ * up at request time. Exists so "make these into videos" needs no codes typed.
+ */
+export const getSelection = {
+    id: 'slates_get_selection',
+    description: 
+    // Lean on purpose: WHEN to call it is the doctrine's ASSET CODES line, and
+    // this description is paid on every desktop turn (lockstep § 7).
+    'The user\'s live selection in the Slates app: ticked cards (with codes) and the image open in the viewer.',
+    input: z.object({}).strict(),
+    async run(_input, ctx) {
+        await ctx.desktop().requireCapability('selection', 'reading the live selection');
+        const r = await ctx.desktop().get('/agent/selection');
+        const describe = (row) => row.code ? (row.label ? `${row.code} — ${row.label}` : String(row.code)) : String(row.id);
+        const selected = r.selection
+            ? r.selection.items.map((i) => {
+                const row = i;
+                return row.type === 'shot'
+                    ? { id: row.id, code: row.code ?? null, label: row.label ?? null, type: 'shot' }
+                    : compactAsset(row);
+            })
+            : [];
+        const viewed = r.viewing ? compactAsset(r.viewing.item) : null;
+        const lines = [];
+        if (r.selection) {
+            const where = r.selection.projectName ? ` in project "${r.selection.projectName}"` : '';
+            lines.push(`${selected.length} selected on the ${r.selection.surface} tab${where} (projectId ${r.selection.projectId}): ` +
+                selected.map(describe).join(', ') +
+                '.');
+        }
+        if (viewed)
+            lines.push(`Open in the viewer: ${describe(viewed)}.`);
+        if (lines.length === 0) {
+            lines.push('Nothing is selected and no image is open in the viewer. Ask the user to select the cards in Slates (click or drag), or to name the codes.');
+        }
+        return {
+            text: lines.join(' '),
+            data: {
+                selection: r.selection
+                    ? {
+                        surface: r.selection.surface,
+                        project_id: r.selection.projectId,
+                        project_name: r.selection.projectName,
+                        items: selected,
+                        updated_at: r.selection.updatedAt,
+                    }
+                    : null,
+                viewing: viewed
+                    ? { project_id: r.viewing.projectId, item: viewed, updated_at: r.viewing.updatedAt }
+                    : null,
+            },
+        };
+    },
+};
+// The view's three lists, mirrored from the desktop's `@shared/types/view`
+// (`LENSES`, `CUT_SIDES`, `DOCK_SECTIONS`), which this package cannot import.
+// Lockstep check 12 fails when they differ.
+const VIEW_LENSES = ['board', 'media', 'script'];
+const VIEW_CUT_SIDES = ['bottom', 'left', 'right'];
+const VIEW_DOCK_SECTIONS = ['storyboards', 'library', 'folders', 'pinned'];
+/** What each dock section is called on screen. */
+const DOCK_SECTION_NAMES = { storyboards: 'Boards', library: 'Library', folders: 'Folders', pinned: 'Pinned' };
+const describeView = (v) => {
+    const where = v.cut.full
+        ? 'filling the workspace'
+        : v.cut.open
+            ? v.cut.side === 'bottom'
+                ? `a ${v.cut.height}px band under the ${v.lens} tab`
+                : `a ${v.cut.width}px column on the ${v.cut.side} of the ${v.lens} tab`
+            : 'closed, resting as one line at the bottom';
+    const agent = v.studioAgent.enabled
+        ? v.studioAgent.open
+            ? `the Studio Agent panel is open (${v.studioAgent.width}px)`
+            : 'the Studio Agent panel is closed'
+        : 'the Studio Agent is switched off in Settings';
+    return (`The ${v.lens} tab is showing. The timeline is ${where}. ` +
+        `The project navigator is ${v.leftDock.open ? `open (${v.leftDock.width}px)` : 'closed'}, and ${agent}.` +
+        (v.leftDock.folded?.length ? ` Folded in the navigator: ${v.leftDock.folded.map((f) => DOCK_SECTION_NAMES[f] ?? f).join(', ')}.` : '') +
+        (v.script ? ` The Script page shows ${v.script.details ? 'Words + shots (each shot\'s picture beside its words)' : 'Words (the words alone)'}.` : ''));
+};
+/**
+ * How the Slates window is ARRANGED right now — which lens is showing, where
+ * the timeline sits, which side panels are open. Read it before rearranging
+ * anything, so you change one thing and leave the rest as the user had it.
+ */
+export const getView = {
+    id: 'slates_get_view',
+    description: "How the Slates window is arranged: the tab showing (Media, Script or Board), where the timeline sits, which side panels are open, and whether the Script page shows Words or Words + shots.",
+    input: z.object({}).strict(),
+    async run(_input, ctx) {
+        await ctx.desktop().requireCapability('view', 'the window layout');
+        const r = await ctx.desktop().get('/agent/view');
+        if (!r.view) {
+            return {
+                text: r.reason
+                    ? `Slates has not reported a window layout yet (${r.reason}).`
+                    : 'Slates has not reported a window layout yet.',
+                data: { view: null },
+            };
+        }
+        return { text: describeView(r.view), data: { view: r.view } };
+    },
+};
+/**
+ * Rearrange the window. Every field is optional and only what you name moves,
+ * so parking the timeline does not also change the lens.
+ *
+ * 🚨 THE APP ANSWERS, NOT THE REQUEST. Sizes are clamped by the app's own
+ * rules and the reply reports what it settled on — ask for a 10px timeline and
+ * you are told 420, because that is what is on the user's screen. A window too
+ * small to show the timeline beside the board will not split at all; it shows
+ * the timeline full-screen instead, and says so.
+ */
+export const setView = {
+    id: 'slates_set_view',
+    description: "Rearrange the Slates window: switch tab (Media, Script or Board), open/close the timeline or park it along the bottom or as a left/right column, open/close or resize the side panels, fold the navigator's sections, and switch the Script page between Words and Words + shots. Only the fields you name change; sizes are clamped by the app and the reply says what it settled on.",
+    input: z
+        .object({
+        lens: z.enum(VIEW_LENSES).optional().describe('Which tab the centre shows.'),
+        cut: z
+            .object({
+            open: z.boolean().optional().describe('Show or hide the timeline.'),
+            full: z.boolean().optional().describe('Give the timeline the whole workspace.'),
+            side: z
+                .enum(VIEW_CUT_SIDES)
+                .optional()
+                .describe('Where the timeline is parked. A column suits a wide monitor; picking a side opens the timeline.'),
+            height: z.number().optional().describe('The bottom band\'s height in px.'),
+            width: z.number().optional().describe('The side column\'s width in px.'),
+        })
+            .strict()
+            .optional(),
+        leftDock: z
+            .object({
+            open: z.boolean().optional(),
+            width: z.number().optional().describe('Width in px.'),
+            folded: z
+                .array(z.enum(VIEW_DOCK_SECTIONS))
+                .optional()
+                .describe('Every section to fold to its title (storyboards is Boards); a section not named unfolds. Applies to the open project.'),
+        })
+            .strict()
+            .optional()
+            .describe('The project navigator on the left.'),
+        studioAgent: z
+            .object({
+            open: z.boolean().optional(),
+            width: z.number().optional().describe('Width in px.'),
+        })
+            .strict()
+            .optional()
+            .describe('The Studio Agent panel on the right. It cannot be opened while the agent is off in Settings.'),
+        script: z
+            .object({
+            details: z.boolean().optional().describe('Words + shots (true): each shot\'s picture beside its words on the Script page. Words (false): the words alone.'),
+        })
+            .strict()
+            .optional()
+            .describe('The Script page.'),
+    })
+        .strict(),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('view', 'the window layout');
+        if (Object.keys(input).length === 0) {
+            throw new Error('Name at least one of lens, cut, leftDock, studioAgent or script — there is nothing to change otherwise.');
+        }
+        const r = await ctx.desktop().post('/agent/view', input);
+        if (!r.view) {
+            return { text: r.reason ? `Nothing was rearranged (${r.reason}).` : 'Nothing was rearranged.', data: { view: null } };
+        }
+        // A desktop whose view predates folding takes the patch and ignores `folded`.
+        const noFolds = input.leftDock?.folded !== undefined && r.view.leftDock.folded === undefined
+            ? " This Slates cannot fold the navigator's sections; update Slates."
+            : '';
+        return { text: describeView(r.view) + noFolds, data: { view: r.view } };
+    },
+};
 export const getMe = {
     id: 'slates_get_me',
     description: 'Identity, license tier, and credit balance for the connected Slates account.',
@@ -360,18 +549,21 @@ export const VIDEO_MODELS = [
     // Flash ones.
     'seedance-2.5',
     'omni-flash',
-    // MiniMax H3, two seats in one family (2026-08-27). Base H3 is the AUTHORED-
-    // AUDIO seat — three directable sound layers in one pass, declared reference
-    // relationships, 480p to 4K, and the cheapest 768-class second we sell.
-    // H3 Max is fal's self-hosted post-train: faster, capped at 768p, takes NO
-    // references, and costs MORE than base H3 at the tier they share — a
-    // premium-speed seat, never a cheap H3.
+    // MiniMax H3, three seats in one family. Base H3 (2026-08-27) is the
+    // AUTHORED-AUDIO seat — three directable sound layers in one pass, declared
+    // reference relationships, 480p to 4K. H3 Max (2026-08-27) is fal's
+    // self-hosted post-train: faster, 480p to a 1080p refinement, the same
+    // omni-reference set, and dearer than base H3 at the tier they share. H3 Max
+    // Turbo (2026-09-29) is a second fal post-train at half Max's rate, with NO
+    // reference endpoint.
     //
-    // NEVER PREFIX-MATCH: 'minimax-h3-max' starts with 'minimax-h3'. Every
-    // branch keyed on these ids matches EXACTLY; a prefix test silently bills
-    // the Max row at base rates and offers it 2K/4K it cannot render.
+    // NEVER PREFIX-MATCH: 'minimax-h3-max-turbo' starts with 'minimax-h3-max',
+    // which starts with 'minimax-h3'. Every branch keyed on these ids matches
+    // EXACTLY; a prefix test bills one row at another's rates and offers it a
+    // ladder it cannot render.
     'minimax-h3',
     'minimax-h3-max',
+    'minimax-h3-max-turbo',
     // LTX-2.5, two seats in one family (2026-08-29). Base is the VOLUME seat —
     // cheapest native 1080p second we sell, free native audio at every tier, the
     // only row reaching 1440p, and the longest clips in the catalogue (20s).
@@ -425,7 +617,7 @@ const VIDEO_RESOLUTION_VOCAB = VIDEO_RESOLUTIONS;
 // $0.080 x 1.5 x 100 = 12 cents, and 12 is divisible by CENTS_PER_CREDIT (3),
 // so every extra image is 4 credits at every resolution and every duration with
 // zero drift. A rate that is not a multiple of 2 cents breaks that property.
-const MINIMAX_MODELS = new Set(['minimax-h3', 'minimax-h3-max']);
+const MINIMAX_MODELS = new Set(['minimax-h3', 'minimax-h3-max', 'minimax-h3-max-turbo']);
 /** Reference images fal does not charge for. */
 const MINIMAX_FREE_REF_IMAGES = 5;
 /** Per-row free allowance. The Max row's is FOUR — fal prices its references by
@@ -512,8 +704,8 @@ export const estimateGenerationCost = {
         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/seedream-5-lite).'),
-        quality: z.enum(GPT_QUALITY_TIERS).optional().describe('GPT Image tier; default high.'),
+        resolution: z.enum(['1k', '2k', '3k', '4k']).optional().describe('Image only. Omit for the model default; pass the same value to generation.'),
+        quality: z.enum(GPT_QUALITY_TIERS).optional().describe(`GPT Image tier; default ${DEFAULT_GPT_QUALITY}.`),
         aspectRatio: z.string().optional().describe('Image only. 1:1/4:3/3:4 cost more than 16:9.'),
         sound: z.boolean().optional().describe('Veo only — audio flag changes the cost key.'),
         seedanceFace: z.boolean().optional().describe('Seedance AI-face route (pricier key).'),
@@ -541,7 +733,7 @@ export const estimateGenerationCost = {
             // generation quoted 1 cr for a 2 cr job. Four separate copies of one
             // default is what made that possible; there are now none.
             if (img)
-                key = imageCostKey(img, input.resolution ?? (img === 'nano-banana-2-lite' ? '1k' : '2k'), input.quality, input.aspectRatio);
+                key = imageCostKey(img, input.resolution ?? defaultImageResolutionFor(img), input.quality, input.aspectRatio);
         }
         // 2a) audio base id → seconds. Both surfaces bill per second, so a
         //     duration is always required. Runs BEFORE the video resolver: it is
@@ -652,7 +844,7 @@ export const estimateGenerationCost = {
                         defaultVideoResolutionFor(resolved.model),
                     sound: input.sound ?? resolved.sound,
                     seedanceFace: input.seedanceFace ?? resolved.seedanceFace,
-                    seedanceRealFace: input.seedanceRealFace,
+                    seedanceRealFace: input.seedanceRealFace ?? resolved.seedanceRealFace,
                     referenceImages: input.referenceImages ?? resolved.referenceImages,
                     videoRefSeconds: input.videoRefSeconds, audioRefSeconds: input.audioRefSeconds,
                 });
@@ -739,6 +931,9 @@ function compactAsset(a) {
             prompt: typeof r.prompt === 'string' ? r.prompt : null,
         }),
         type: r.type,
+        // Only when it IS one. A compact row pays for every key on every asset,
+        // and "not a favorite" is the default the app writes — absent says it.
+        ...(r.isFavorite === true ? { isFavorite: true } : {}),
         created_at: r.createdAt ?? r.created_at ?? undefined,
     };
 }
@@ -807,7 +1002,7 @@ function describeResolvedRefs(refInputs, resolved) {
 }
 export const listAssets = {
     id: 'slates_list_assets',
-    description: 'List assets in a Slates project as COMPACT rows (id, code, label, type) — newest first, default limit 50. Each asset carries its short code (IMG-A12 / VID-V3 / AUD-S1 — the badge the user sees on the gallery card) and label. When the user names an asset by code ("use IMG-A36 as the reference"), pass it as `search` to resolve the assetId. Always speak about assets by code + label, never by UUID. NOTE: generate_* results already return the new asset ids — do NOT call this to find an asset you just created.',
+    description: 'List assets in a Slates project as COMPACT rows (id, code, label, type) — newest first, default limit 50. Each asset carries its short code (IMG-A12 / VID-V3 / AUD-S1 — the badge the user sees on the gallery card) and label. When the user names an asset by code ("use IMG-A36 as the reference"), pass it as `search` to resolve the assetId. Always speak about assets by code + label, never by UUID. A favorited asset carries `isFavorite: true` (absent means not favorited). NOTE: generate_* results already return the new asset ids — do NOT call this to find an asset you just created.',
     input: z.object({
         projectId: z.string().uuid(),
         type: z.enum(['image', 'video', 'audio']).optional().describe('Only this asset type'),
@@ -868,7 +1063,7 @@ export const getAssetImage = {
 };
 export const getAssetsBatch = {
     id: 'slates_get_assets_batch',
-    description: 'Fetch up to 8 image-asset thumbnails inline in a single call. Use this when picking the right reference from a project gallery — one round trip beats N. Each returned image carries its short code (IMG-A12) and label so you can speak about candidates in the user\'s shared vocabulary ("between IMG-A12 and IMG-A14, the second has the right composition"). Video assets are not supported here — call slates_get_asset_video_frames for those.',
+    description: 'Fetch up to 8 image-asset thumbnails inline in a single call. Use this when picking the right reference from a project gallery — one round trip beats N. Each returned image carries its short code (IMG-A12) and label. Video assets are not supported here — call slates_get_asset_video_frames for those.',
     input: z.object({
         ids: z.array(z.string().uuid()).min(1).max(8).describe('1-8 image-asset ids. Order is preserved in the response.'),
     }),
@@ -931,6 +1126,71 @@ export const getAssetVideoFrames = {
         };
     },
 };
+export const getChatGptStatus = {
+    id: 'slates_get_chatgpt_status',
+    description: 'Check whether the local Codex host is installed, signed in with ChatGPT, and supports built-in image generation. Does not generate or charge Slates credits.',
+    input: z.object({}),
+    async run(_input, ctx) {
+        await ctx.desktop().requireCapability('chatgpt-image-generation', 'ChatGPT image generation');
+        return ok(await ctx.desktop().get('/agent/chatgpt/status'));
+    },
+};
+export const connectChatGpt = {
+    id: 'slates_connect_chatgpt',
+    description: 'Start Codex-managed ChatGPT sign-in and return a browser sign-in URL for the user. Call only when the user requests connecting their account. Never ask for credentials or tokens.',
+    input: z.object({}),
+    async run(_input, ctx) {
+        await ctx.desktop().requireCapability('chatgpt-image-generation', 'ChatGPT image generation');
+        return ok(await ctx.desktop().post('/agent/chatgpt/connect', {}));
+    },
+};
+export const generateChatGptImage = {
+    id: 'slates_generate_chatgpt_image',
+    description: 'Generate an image through the local Codex host using the connected ChatGPT account, then save it in Slates with its exact submitted prompt, reference lineage and measured dimensions. Uses ChatGPT account limits, never Slates credits or a paid API fallback. Check slates_get_chatgpt_status first. Supply a new UUID requestId once per intended generation; reuse it for retries to avoid duplicate generation/import. No explicit image model, quality or size controls are exposed. Prompt may request visual properties without guaranteeing them. Background returns a generationId for slates_get_generation_status.',
+    input: z.object({ projectId: z.string().uuid(), requestId: z.string().uuid(), prompt: z.string().min(1),
+        aspectRatio: z.enum(CHATGPT_FRAMING_RATIOS).optional().describe('Optional framing request appended verbally to the prompt, not an exact output-size guarantee.'),
+        referenceAssetIds: z.array(z.string().min(1)).optional(), background: z.boolean().optional() }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('chatgpt-image-generation', 'ChatGPT image generation');
+        const refs = await resolveAssetRefs(ctx, input.projectId, input.referenceAssetIds ?? []);
+        const result = await desktop.post('/agent/generation/chatgpt-image', {
+            ...input, referenceAssetIds: (input.referenceAssetIds ?? []).map(id => refs.get(id).id),
+        });
+        return ok(result, JSON.stringify(result) + '\n' + describeResolvedRefs((input.referenceAssetIds ?? []).map(ref => ({ ref, role: 'reference image' })), refs));
+    },
+};
+export const saveExternalImage = {
+    id: 'slates_save_external_image',
+    description: 'Save an image generated by an external host with its exact prompt, generator, reference images and measured dimensions. This does not generate or spend Slates credits. Pass filePath or dataUrl for a new result, or assetId to annotate an existing upload in place. Ordinary pasted or dragged files belong to slates_upload_reference_image. Only name a model if the host reported it; requestedSettings records requests, not verified output settings.',
+    input: z.object({
+        projectId: z.string().uuid(),
+        filePath: z.string().min(1).optional(),
+        dataUrl: z.string().min(1).optional(),
+        assetId: z.string().min(1).optional(),
+        prompt: z.string().min(1),
+        generator: z.string().min(1),
+        model: z.string().min(1).optional(),
+        negativePrompt: z.string().min(1).optional(),
+        referenceAssetIds: z.array(z.string().min(1)).optional(),
+        requestedSettings: z.record(z.union([z.string(), z.number().finite(), z.boolean()])).optional(),
+    }).refine(d => [d.filePath, d.dataUrl, d.assetId].filter(Boolean).length === 1, {
+        message: 'Pass exactly one of filePath, dataUrl or assetId',
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('external-image-metadata', 'external image generation metadata');
+        const refs = await resolveAssetRefs(ctx, input.projectId, [
+            ...(input.referenceAssetIds ?? []), ...(input.assetId ? [input.assetId] : []),
+        ]);
+        const result = await desktop.post('/agent/assets/external-image', {
+            ...input,
+            assetId: input.assetId ? refs.get(input.assetId).id : undefined,
+            referenceAssetIds: (input.referenceAssetIds ?? []).map(id => refs.get(id).id),
+        });
+        return ok(result, JSON.stringify(result) + '\n' + describeResolvedRefs((input.referenceAssetIds ?? []).map(ref => ({ ref, role: 'reference image' })), refs));
+    },
+};
 export const uploadReferenceImage = {
     id: 'slates_upload_reference_image',
     description: 'Add a reference image, video clip, or audio file to a Slates project from disk. Pass either filePath (absolute path to a local file) or dataUrl (base64 data: URL) — exactly one. Set type:"video" to bring in a clip (the user\'s own footage to edit/relocate/trim) or type:"audio" for music/VO/SFX they already have; both are probed on ingest, so duration (and for video, dimensions) are available immediately, and audio gets its waveform. Default type is "image". dataUrl is image-only.',
@@ -1000,6 +1260,62 @@ export const moveAssetsToFolder = {
         return ok(await ctx.desktop().post('/agent/folders/move-assets', input));
     },
 };
+export const setAssetFavorite = {
+    id: 'slates_set_asset_favorite',
+    description: 'Mark or unmark one asset as a favorite. The heart persists on the card in the app, and slates_list_assets reports it as isFavorite.',
+    input: z.object({
+        assetId: z.string().uuid(),
+        favorite: z.boolean(),
+    }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('asset-favorite', 'favorites');
+        return ok(await ctx.desktop().post('/agent/assets/favorite', input));
+    },
+};
+export const exportAssets = {
+    id: 'slates_export_assets',
+    description: 'Copy the ORIGINAL files of one or more assets (images, clips or audio) into a directory on this machine, named by their codes (IMG-A12.png). Never overwrites: a clash gets -2, -3. The project is untouched. Works for an image-only project with no shot, video or timeline. Returns each exported path and any asset whose file is missing.',
+    input: z.object({
+        assetIds: z.array(z.string().uuid()).min(1),
+        directory: z.string().min(1).describe('Absolute path; created if it does not exist.'),
+    }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('asset-export', 'exporting media');
+        return ok(await ctx.desktop().post('/agent/assets/export', input));
+    },
+};
+export const listPins = {
+    id: 'slates_list_pins',
+    description: "List a project's pinned references: the images kept in the dock's Pinned section, one click from the prompt. A pin attaches nothing to a generation by itself.",
+    input: z.object({ projectId: z.string().uuid() }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('pins', 'pinned references');
+        return ok(await ctx.desktop().get('/agent/pins', { projectId: input.projectId }));
+    },
+};
+export const pinReferences = {
+    id: 'slates_pin_references',
+    description: 'Pin one or more images to the dock\'s Pinned section (UUIDs or badge codes like IMG-A8). Already-pinned ones are reported, not doubled. Pinning keeps a picture at hand; pass it as a reference to a generation to actually use it.',
+    input: z.object({
+        projectId: z.string().uuid(),
+        assetIds: z.array(z.string().min(1)).min(1).describe('Image assets, UUIDs or badge codes.'),
+    }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('pins', 'pinned references');
+        const resolved = await resolveAssetRefs(ctx, input.projectId, input.assetIds);
+        return ok(await ctx.desktop().post('/agent/pins', { projectId: input.projectId, assetIds: input.assetIds.map((r) => resolved.get(r).id) }));
+    },
+};
+export const unpinReference = {
+    id: 'slates_unpin_reference',
+    description: 'Take one image off the dock\'s Pinned section. The image stays in the project.',
+    input: z.object({ projectId: z.string().uuid(), assetId: z.string().min(1).describe('UUID or badge code.') }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('pins', 'pinned references');
+        const resolved = await resolveAssetRefs(ctx, input.projectId, [input.assetId]);
+        return ok(await ctx.desktop().post('/agent/pins/remove', { projectId: input.projectId, assetId: resolved.get(input.assetId).id }));
+    },
+};
 export const moveAssetsToProject = {
     id: 'slates_move_assets_to_project',
     description: 'Move assets (images, videos, audio) out of one project into another. The media files move on disk into the destination project folder — this is a real re-home, not a copy. Moved assets leave whatever gallery folder they were in and are issued fresh badge codes in the destination.',
@@ -1041,7 +1357,7 @@ export const moveAssetsToProject = {
 };
 export const copyAssetsToProject = {
     id: 'slates_copy_assets_to_project',
-    description: 'Copy assets (images, videos, audio) from one project into another. The originals stay exactly where they are — new files, new rows, new badge codes in the destination. Use this instead of slates_move_assets_to_project when the asset is already in use where it lives: an image that is a character/environment/style identity or sits in a storyboard frame CANNOT be moved out (that would leave the other project pointing at a file it no longer owns), but it can always be copied. Lineage is not copied; the copy starts clean.',
+    description: 'Copy assets (images, videos, audio) from one project into another. The originals stay exactly where they are — new files, new rows, new badge codes in the destination. Use this instead of slates_move_assets_to_project when the asset is already in use where it lives: an image that is a character, location or look picture, or sits in a board frame, CANNOT be moved out (that would leave the other project pointing at a file it no longer owns), but it can always be copied. Lineage is not copied; the copy starts clean.',
     input: z.object({
         sourceProjectId: z.string().uuid(),
         // Badge codes ("IMG-A8") resolve against sourceProjectId at call time.
@@ -1066,13 +1382,20 @@ export const copyAssetsToProject = {
 };
 export const moveEntityToProject = {
     id: 'slates_move_entity_to_project',
-    description: "Move a character, environment, or style into another project, taking every image it references with it. This is the fix when slates_move_assets_to_project refuses an asset because an entity still uses it: the identity image can't leave on its own, but the whole entity can. Refuses (rather than cascading) if one of its images is ALSO used by something else — copy the images instead in that case. Storyboard frames are not movable this way; moving a frame's image out would empty the shot.",
+    description: "Move a Library item (a character, location, product, look…) into another project, taking every image it references with it; it lands in the target's category of the same name. This is the fix when slates_move_assets_to_project refuses an asset because a Library item still uses it: the image can't leave on its own, but the whole item can. Refuses (rather than cascading) if one of its images is ALSO used by something else — copy the images instead in that case. mentioningShots lists this project's Shots that mention it: they keep the words and fire without it until it comes back. Board frames are not movable this way; moving a frame's image out would empty the shot.",
     input: z.object({
-        kind: z.enum(['character', 'environment', 'style']),
+        kind: z
+            .enum(['library', 'character', 'environment', 'style'])
+            .optional()
+            .describe('Optional and ignored: every value means a Library item. Kept for older callers.'),
         entityId: z.string().uuid(),
         targetProjectId: z.string().uuid(),
     }),
     async run(input, ctx) {
+        // 1.5.8 refuses an omitted or 'library' kind; only a legacy kind reaches it.
+        if (input.kind === undefined || input.kind === 'library') {
+            await ctx.desktop().requireCapability('library', 'the Library');
+        }
         return ok(await ctx.desktop().post('/agent/entities/move-to-project', input));
     },
 };
@@ -1115,7 +1438,7 @@ export const setCharacterIdentity = {
 // ── Environments ────────────────────────────────────────────────
 export const listEnvironments = {
     id: 'slates_list_environments',
-    description: 'List environments in a Slates project.',
+    description: 'List the locations (environments) in a Slates project.',
     input: z.object({ projectId: z.string().uuid() }),
     async run(input, ctx) {
         return ok(await ctx.desktop().get('/agent/environments', { projectId: input.projectId }));
@@ -1123,7 +1446,7 @@ export const listEnvironments = {
 };
 export const createEnvironment = {
     id: 'slates_create_environment',
-    description: 'Create a new environment in a Slates project.',
+    description: 'Create a new location (environment) in a Slates project.',
     input: z.object({
         projectId: z.string().uuid(),
         name: z.string().min(1).max(120),
@@ -1139,14 +1462,14 @@ export const generateCharacterIdentity = {
     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(),
+        characterId: z.string().uuid().describe('A character, or the id of any Library thing: both sheet tools run on any thing, and the result binds as its image.'),
         projectId: z.string().uuid(),
         baseAssetId: z.string().uuid().describe('The base portrait asset the identity is generated from.'),
         userNotes: z.string().optional().describe('Extra instruction, e.g. "use the woman on the left".'),
         model: z
             .enum(['nano-banana-2', 'nano-banana-2-lite', 'nano-banana-pro', 'gpt-image-2-5-flare', 'gpt-image-2-5-sunburst'])
             .optional()
-            .describe('Image model for the sheet. Omit for the default (nano-banana-2). Exists so the layout-vs-face tradeoff can be tested with comparison gens — do not switch without a receipt.'),
+            .describe(`Image model for the sheet. Omit for the sheet tool's seat (${toolModelFor('character-sheet')}), which is what the app's own button uses. Pass another only to compare seats side by side.`),
     }),
     async run(input, ctx) {
         // 🚨 THE ROSTER GATE, WHICH THIS OP NEVER HAD. Its `model` enum offers
@@ -1161,6 +1484,11 @@ export const generateCharacterIdentity = {
         else if (input.model === 'nano-banana-pro' || input.model === 'nano-banana-2-lite') {
             await ctx.desktop().requireCapability('image-models-v2', `${input.model} character identity`);
         }
+        // 1.5.8 renders an unnamed model as Nano Banana 2 and every model at 2k, so
+        // only an explicit Nano Banana model runs there as quoted.
+        if (!input.model || isGptImageModel(input.model)) {
+            await ctx.desktop().requireCapability('sheet-tool-seats', 'sheet tools on the default image seat');
+        }
         return ok(await ctx.desktop().post('/agent/characters/generate-identity', {
             characterId: input.characterId,
             projectId: input.projectId,
@@ -1173,9 +1501,9 @@ 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.",
+    description: "Generate one clean establishing image from an optional base image and bind it as the location's canonical reference. Call after slates_create_environment and quote the cost from slates_estimate_generation_cost.",
     input: z.object({
-        environmentId: z.string().uuid(),
+        environmentId: z.string().uuid().describe('A location, or the id of any Library thing: both sheet tools run on any thing, and the result binds as its image.'),
         projectId: z.string().uuid(),
         baseAssetId: z
             .string()
@@ -1185,6 +1513,8 @@ export const generateEnvironmentPlate = {
         userNotes: z.string().optional(),
     }),
     async run(input, ctx) {
+        // 1.5.8 always renders the plate on Nano Banana 2 at 2k, never the seat quoted.
+        await ctx.desktop().requireCapability('sheet-tool-seats', 'sheet tools on the default image seat');
         return ok(await ctx.desktop().post('/agent/environments/generate-plate', {
             environmentId: input.environmentId,
             projectId: input.projectId,
@@ -1196,7 +1526,7 @@ export const generateEnvironmentPlate = {
 // ── Storyboards ─────────────────────────────────────────────────
 export const listStoryboards = {
     id: 'slates_list_storyboards',
-    description: 'List storyboards in a Slates project.',
+    description: 'List the boards (storyboards) in a Slates project.',
     input: z.object({ projectId: z.string().uuid() }),
     async run(input, ctx) {
         return ok(await ctx.desktop().get('/agent/storyboards', { projectId: input.projectId }));
@@ -1204,7 +1534,7 @@ export const listStoryboards = {
 };
 export const createStoryboard = {
     id: 'slates_create_storyboard',
-    description: 'Create a new storyboard with a default first scene. Returns the storyboard record.',
+    description: 'Create a new board (storyboard) with a default first scene. Returns the board record.',
     input: z.object({
         projectId: z.string().uuid(),
         name: z.string().min(1).max(120),
@@ -1220,7 +1550,7 @@ export const getStoryboardWithFrames = {
     // 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.",
+    description: "Deep-fetch a board: 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();
@@ -1233,7 +1563,7 @@ export const getStoryboardWithFrames = {
 };
 export const addScene = {
     id: 'slates_add_scene',
-    description: 'Add a new scene to a storyboard.',
+    description: 'Add a new scene to a board.',
     input: z.object({
         storyboardId: z.string().uuid(),
         name: z.string().min(1).max(120),
@@ -1368,7 +1698,7 @@ export function isGptImageModel(model) {
  * ten and the other five would be accepted here. The image param surface has
  * not been audited (aspect ratios, resolution classes, per-model reference
  * caps) — that audit is the named follow-up in
- * `slate/docs/plan-docs/2026-08-16-MODEL-CAPABILITY-SSOT.md` §5. The machinery
+ * `second-brain/plans/2026-08-16-slates-model-capability-ssot.md` §5. The machinery
  * to close it already exists: call `checkAspectRatio(model, ratio)` the way
  * `assertVideoCapabilities` does below.
  */
@@ -1404,7 +1734,7 @@ function gptKeyAspect(aspectRatio) {
 // imports it and asserts, key by key, that it equals the desktop's
 // `imageCreditKey`. Before that check existed the byte-match was a comment and
 // a hope — the two are in different repos and nothing compared them.
-export function imageCostKey(model, resolution, quality = 'high', aspectRatio) {
+export function imageCostKey(model, resolution, quality = DEFAULT_GPT_QUALITY, aspectRatio) {
     if (model === 'flux-2-max')
         return resolution === '1k' ? 'flux-2-max' : `flux-2-max-${resolution}`;
     if (model === 'seedream-5-lite')
@@ -1417,6 +1747,17 @@ export function imageCostKey(model, resolution, quality = 'high', aspectRatio) {
         return `${model}-${gptKeyTier(quality)}-${resolution}${gptKeyAspect(aspectRatio)}`;
     return `nano-banana-2-${resolution}`;
 }
+// The default image seat with a project to route through, READ from MODEL_FACTS
+// `tier`. Asserted at load so a default moved to a seat this op cannot send
+// fails the build instead of every omitted-model call.
+const DEFAULT_IMAGE_MODEL = defaultModelFor('image');
+if (!IMAGE_MODELS.includes(DEFAULT_IMAGE_MODEL)) {
+    throw new Error(`slates_generate_image: default image seat ${DEFAULT_IMAGE_MODEL} is not in IMAGE_MODELS`);
+}
+/** The headless path's one fal batch: `maxBatchImages` owns it (nano-banana-2 is the only batching model). */
+const HEADLESS_BATCH_CAP = MODEL_CAPABILITIES['nano-banana-2']?.maxBatchImages ?? 1;
+/** A 1.5.8 desktop's own clamp on a project batch, frozen with that build. */
+const LEGACY_DESKTOP_IMAGE_BATCH = 4;
 export const generateImage = {
     id: 'slates_generate_image',
     billable: true,
@@ -1435,13 +1776,13 @@ export const generateImage = {
         describeBannedTokens('image'),
     input: z.object({
         prompt: z.string().min(1).max(4000),
-        model: zEnum(IMAGE_MODELS).optional().describe('Image model. Default nano-banana-2. Routing doctrine: slates-model-selection skill. All except nano-banana-2 require projectId.'),
+        model: zEnum(IMAGE_MODELS).optional().describe(`Image model. Omitted: ${DEFAULT_IMAGE_MODEL} with projectId, nano-banana-2 (the only headless seat) without. Routing: slates-model-selection skill.`),
         projectId: z.string().uuid().optional().describe('Save into this Slates project. Renderer refreshes live. Required for every model except nano-banana-2.'),
-        resolution: z.enum(['1k', '2k', '3k', '4k']).optional().describe('1k drafts, 2k hero, 4k final. nano-banana-2-lite: 1k only. GPT Image classes 1024²/1080p/1440p/2160p. Never default this.'),
-        quality: z.enum(GPT_QUALITY_TIERS).optional().describe('GPT Image only. UNEVEN ladder: max=4× high, xhigh~1.8×. medium drafts; default high.'),
+        resolution: z.enum(['1k', '2k', '3k', '4k']).optional().describe('Omit for the selected model default. Override for a specific delivery size; use the same setting when estimating.'),
+        quality: z.enum(GPT_QUALITY_TIERS).optional().describe(`GPT Image only. Default ${DEFAULT_GPT_QUALITY}; estimate the chosen tier before generation.`),
         backgroundMode: z.enum(GPT_BACKGROUNDS).optional().describe('GPT Image only. transparent = alpha channel. Free.'),
         aspectRatio: zEnum(IMAGE_ASPECT_RATIOS).optional().describe(`Pick from the use case: cinematic 16:9 · TikTok/Reels 9:16 · IG square 1:1 · ultra-wide 21:9. 1:1 costs most on GPT Image. Per model: ${describeAspectRatios(IMAGE_MODELS)}`),
-        count: z.number().int().min(1).max(10).optional().describe('Up to 10 with projectId; headless caps at 4.'),
+        count: z.number().int().min(1).max(MAX_IMAGE_VARIATIONS).optional().describe(`Up to ${MAX_IMAGE_VARIATIONS} with projectId; headless caps at ${HEADLESS_BATCH_CAP}.`),
         referenceImageUrls: z.array(z.string().url()).max(14).optional().describe('Headless (no projectId) nano-banana-2 only. With a projectId, upload via slates_upload_reference_image. Label every image role in the prompt.'),
         referenceAssetIds: z.array(z.string()).max(16).optional().describe("Project assets as references — UUIDs or badge codes (\"IMG-A8\"), resolved at call time. Requires projectId. Caps: GPT Image 16, nano-banana-2 14, FLUX/Seedream lower. Label every reference role in the prompt."),
         background: z.boolean().optional().describe(BACKGROUND_DESCRIBE),
@@ -1455,7 +1796,13 @@ export const generateImage = {
         // Non-blocking prompt hygiene. Computed once, reported on every exit path
         // that echoes a prompt -- the clarification and confirm gates are PRE-spend,
         // which is where a rewrite is still free.
-        const promptWarning = bannedTokenWarning(input.prompt, 'image');
+        // Omitted model: the default seat when there is a project to route through,
+        // nano-banana-2 without one, because it is the only headless seat. The
+        // desktop's pre-flight guard (`estimateOpCostCents`, src/main/studio-agent/
+        // ops.ts) picks the same seat: change both together.
+        const imageModel = input.model ?? (input.projectId ? DEFAULT_IMAGE_MODEL : 'nano-banana-2');
+        const promptWarning = bannedTokenWarning(input.prompt, 'image', promptingSkillFor(imageModel));
+        input = { ...input, resolution: input.resolution ?? defaultImageResolutionFor(imageModel) };
         if (!input.aspectRatio || !input.resolution) {
             const missing = [];
             if (!input.aspectRatio)
@@ -1468,14 +1815,13 @@ export const generateImage = {
                 ...(promptWarning ? { prompt_warning: promptWarning } : {}),
                 message: (promptWarning ? `${promptWarning}\n\n` : '') +
                     `Missing required field(s): ${missing.join(', ')}. ` +
-                    `Read the slates-prompting-nano-banana-2 + slates-cost-discipline skills, ` +
-                    // Generated from MODEL_CAPABILITIES — never retype a ratio list.
+                    `Read the ${promptingSkillFor(imageModel)} + slates-cost-discipline skills, ` +
+                    // Generated from MODEL_CAPABILITIES — never retype a ratio or resolution list.
                     `or ask the user. Aspect ratio by model: ${describeAspectRatios(IMAGE_MODELS)}. ` +
-                    `Resolution options: 1k 2k 4k (same price band — pick by need, not cost).`,
+                    `Resolution options for ${imageModel}: ${(MODEL_CAPABILITIES[imageModel]?.imageResolutions ?? []).join(' ')}.`,
             });
         }
         const resolution = input.resolution;
-        const imageModel = input.model ?? 'nano-banana-2';
         const resolutions = MODEL_CAPABILITIES[imageModel]?.imageResolutions ?? [];
         if (resolution && !resolutions.includes(resolution)) {
             return ok({ requires_clarification: true, missing: ['resolution'],
@@ -1514,11 +1860,11 @@ export const generateImage = {
         // `num_images` maximum is 4 (fal schema, 2026-09-09). Refused rather than
         // clamped: a silent clamp would make four images against a request for ten
         // and read to the caller as a partial failure it should retry.
-        if (!input.projectId && (input.count ?? 1) > 4) {
+        if (!input.projectId && (input.count ?? 1) > HEADLESS_BATCH_CAP) {
             return ok({
                 requires_clarification: true,
                 missing: ['projectId'],
-                message: 'count above 4 needs a projectId. The headless path asks fal for one batch and nano-banana-2 caps a batch at 4; with a projectId the desktop fires them as separate generations and the limit is 10.',
+                message: `count above ${HEADLESS_BATCH_CAP} needs a projectId. The headless path asks fal for one batch and nano-banana-2 caps a batch at ${HEADLESS_BATCH_CAP}; with a projectId the desktop fires them as separate generations and the limit is ${MAX_IMAGE_VARIATIONS}.`,
             });
         }
         let refEcho = '';
@@ -1548,6 +1894,10 @@ export const generateImage = {
             (imageModel === 'nano-banana-pro' || imageModel === 'nano-banana-2-lite')) {
             await ctx.desktop().requireCapability('image-models-v2', `${imageModel} generation`);
         }
+        // 1.5.8 clamps a project batch to its own 4 and bills 4 against this op's quote for all of them.
+        if (input.projectId && (input.count ?? 1) > LEGACY_DESKTOP_IMAGE_BATCH) {
+            await ctx.desktop().requireCapability('image-variations', 'more than 4 images per call');
+        }
         const costKey = imageCostKey(imageModel, resolution, input.quality, input.aspectRatio ?? '1:1');
         const cloud = ctx.cloud();
         const registry = await cloud.get('/api/agent/models');
@@ -1618,7 +1968,7 @@ export const generateImage = {
                 resolution,
                 aspectRatio: input.aspectRatio ?? '1:1',
                 count: input.count ?? 1,
-                ...(isGptImageModel(imageModel) ? { gptQuality: input.quality, gptBackground: input.backgroundMode } : {}),
+                ...(isGptImageModel(imageModel) ? { gptQuality: input.quality ?? DEFAULT_GPT_QUALITY, gptBackground: input.backgroundMode } : {}),
                 ...(referenceAssetIds.length > 0 ? { referenceAssetIds } : {}),
                 background: input.background,
             });
@@ -1799,18 +2149,22 @@ async function pollProxyJob(cloud, jobId, options = {}) {
     throw new Error(`Generation timed out after ${Math.round(timeoutMs / 1000)}s.`);
 }
 // ── Edit image ──────────────────────────────────────────────────
+/** References an edit carries beside the source, which is image 1 of the same request. */
+const editReferenceCap = (model) => Math.max(0, (MODEL_CAPABILITIES[model]?.maxRefImages ?? 1) - 1);
+/** The models a 1.5.8 desktop sends edit references on, frozen with that build: on every other model it drops them and bills the edit in full. */
+const LEGACY_EDIT_REFERENCE_MODELS = ['nano-banana-2', 'nano-banana-2-lite', 'nano-banana-pro'];
 export const editImage = {
     id: 'slates_edit_image',
     billable: true,
-    description: 'Surgically edit an image asset with a text instruction (e.g. \'make the jacket red\') instead of regenerating from scratch — use when ~90% of the image is already right. The result is a NEW asset (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\'.',
+    description: 'Surgically edit an image asset with a text instruction (e.g. \'make the jacket red\') instead of regenerating from scratch — use when ~90% of the image is already right. The result is a NEW asset (prompt prefixed \'[Edit]\'); the source is untouched. Default model ' + toolModelFor('image-edit') + ' (the image-edit tool seat, the model the app\'s Edit box opens on). Every model also takes referenceAssetIds, up to its reference cap less one: the source is image 1 of the request. Before first use call slates_get_prompting_guide with topic \'slates-edit-and-iterate\'.',
     input: z.object({
         projectId: z.string().uuid(),
         sourceAssetId: z.string().uuid().describe('Image asset to edit. Must exist in the project.'),
         prompt: z.string().min(1).max(4000).describe('The change, not the whole image.'),
-        editModel: z.enum(['nano-banana-2', 'nano-banana-2-lite', 'nano-banana-pro', 'gpt-image-2-5-flare', 'gpt-image-2-5-sunburst', 'flux-2-max', 'seedream-5-lite']).optional(),
-        referenceAssetIds: z.array(z.string().uuid()).max(13).optional().describe('Nano-Banana only (NB Pro 13, NB2 Lite 3).'),
+        editModel: zEnum(IMAGE_MODELS).optional(),
+        referenceAssetIds: z.array(z.string().uuid()).max(Math.max(...IMAGE_MODELS.map(editReferenceCap))).optional().describe(`Images beside the source, which is image 1. Each model's own cap: ${IMAGE_MODELS.map((m) => `${m} ${editReferenceCap(m)}`).join(', ')}.`),
         resolution: z.enum(['1k', '2k', '3k', '4k']).optional().describe('3k = GPT Image/seedream-5-lite; nano-banana-2-lite is 1k only.'),
-        quality: z.enum(GPT_QUALITY_TIERS).optional().describe('GPT Image tier; default high.'),
+        quality: z.enum(GPT_QUALITY_TIERS).optional().describe(`GPT Image tier; default ${DEFAULT_GPT_QUALITY}.`),
         backgroundMode: z.enum(GPT_BACKGROUNDS).optional().describe('GPT Image only. transparent = alpha channel. Free.'),
         aspectRatio: z.string().optional(),
         confirm: z.boolean().optional().describe('Set true to bypass the confirm gate.'),
@@ -1822,8 +2176,9 @@ export const editImage = {
         if (input.background) {
             await desktop.requireCapability('background-generation', 'background generation');
         }
-        const editModel = input.editModel ?? 'nano-banana-2';
-        const resolution = input.resolution ?? (editModel === 'nano-banana-2-lite' ? '1k' : '2k');
+        // The image-edit tool's seat (TOOL_SEAT), the model the app's own Edit uses.
+        const editModel = input.editModel ?? toolModelFor('image-edit');
+        const resolution = input.resolution ?? defaultImageResolutionFor(editModel);
         if (isGptImageModel(editModel)) {
             // 🚨 v3, LIKE generateImage — this site was missed once already.
             // A pre-2.5 desktop advertises v2, so gating the 2.5 seats on v2 lets it
@@ -1835,8 +2190,15 @@ export const editImage = {
         else if (editModel === 'nano-banana-pro' || editModel === 'nano-banana-2-lite') {
             await desktop.requireCapability('image-models-v2', `${editModel} editing`);
         }
+        if (input.referenceAssetIds?.length && !LEGACY_EDIT_REFERENCE_MODELS.includes(editModel)) {
+            await desktop.requireCapability('edit-references-all-models', `references on a ${editModel} edit`);
+        }
+        // Past the model's cap the desktop sends the first ones and says so in its reply (`note`).
+        const referencesOver = (input.referenceAssetIds?.length ?? 0) - editReferenceCap(editModel);
         // Nano-Banana family + GPT Image 2.5 edits charge the same key as gen;
         // FLUX / Seedream route to dedicated edit endpoints priced under '-edit' keys.
+        // Mirrors `editCreditKey` in the desktop's src/shared/imageEdit.ts, which
+        // this package cannot import: change both together.
         const costKey = editModel === 'flux-2-max' || editModel === 'seedream-5-lite'
             ? `${imageCostKey(editModel, resolution)}-edit`
             : imageCostKey(editModel, resolution, input.quality, input.aspectRatio);
@@ -1856,6 +2218,7 @@ export const editImage = {
                 estimated_credits: totalCents,
                 source_ref: sourceRef,
                 message: `Cost: ${fmtCredits(totalCents)} to edit ${sourceRef} with ${editModel} (${costKey}). ` +
+                    (referencesOver > 0 ? `${editModel} takes ${editReferenceCap(editModel)} references beside the source; ${referencesOver} would not be sent. ` : '') +
                     `Re-call with confirm=true after the user explicitly OKs the spend. ` +
                     `When discussing with the user, refer to the source by its code (matches the gallery badge).`,
             });
@@ -1867,7 +2230,7 @@ export const editImage = {
             editModel,
             referenceAssetIds: input.referenceAssetIds,
             resolution,
-            ...(isGptImageModel(editModel) ? { gptQuality: input.quality, gptBackground: input.backgroundMode } : {}),
+            ...(isGptImageModel(editModel) ? { gptQuality: input.quality ?? DEFAULT_GPT_QUALITY, gptBackground: input.backgroundMode } : {}),
             aspectRatio: input.aspectRatio,
             background: input.background,
         });
@@ -1882,7 +2245,8 @@ export const editImage = {
                 sourceAssetId: input.sourceAssetId,
                 cost_cents: totalCents,
                 cost_credits: totalCents,
-            });
+                ...(result.note ? { note: result.note } : {}),
+            }, result.note ? `${result.note}.` : undefined);
         }
         // Inline the edited result so the LLM sees whether the surgery landed —
         // same best-effort pattern as slates_generate_image.
@@ -1900,7 +2264,8 @@ export const editImage = {
         return {
             text: `Edited image saved as a new asset in project ${input.projectId} ` +
                 `for ${fmtCredits(totalCents)} via ${editModel}. ` +
-                `Edit: "${input.prompt.slice(0, 60)}${input.prompt.length > 60 ? '...' : ''}"`,
+                `Edit: "${input.prompt.slice(0, 60)}${input.prompt.length > 60 ? '...' : ''}"` +
+                (result.note ? ` ${result.note}.` : ''),
             images,
             data: {
                 editModel,
@@ -1912,6 +2277,7 @@ export const editImage = {
                 cost_credits: totalCents,
                 asset: result.asset,
                 generationId: result.generationId,
+                ...(result.note ? { note: result.note } : {}),
             },
         };
     },
@@ -2010,7 +2376,7 @@ export function videoCostKey(input) {
         // × vref × res × duration). AI-face route bills the `-face-` key (~45% over
         // faceless); consented real-person route bills the premium `-realface-` key
         // (fal partner endpoint). A reference video flips to `-vref-{res}-{T}s`,
-        // T = in + out.
+        // T = in + out, or max(in, out) + out on the AI-face route.
         //
         // ⚠️ EVERY BOUND HERE IS VERSION-SCOPED. 2.5 runs 480p/720p/1080p (no 4K),
         // reaches 30s, and takes references to 30s combined — so its vref total
@@ -2024,7 +2390,11 @@ export function videoCostKey(input) {
         if (vrefSecs > 0) {
             // ceil(x - 0.05) matches the server's probe rounding — quote = bill.
             const maxTotal = v25 ? SEEDANCE_25_VREF_MAX_TOTAL : SEEDANCE_20_VREF_MAX_TOTAL;
-            const total = Math.min(maxTotal, Math.max(6, Math.ceil(vrefSecs - 0.05) + input.duration));
+            // EvoLink (the AI-face rail) bills a reference on max(input, output) +
+            // output on 2.0 and 2.5. Mirrors seedanceBilledRefSeconds in slate pricing.ts.
+            const inSecs = Math.ceil(vrefSecs - 0.05);
+            const billedIn = face === '-face' ? Math.max(inSecs, input.duration) : inSecs;
+            const total = Math.min(maxTotal, Math.max(6, billedIn + input.duration));
             return `${input.model}${face}-vref-${res}-${total}s`;
         }
         return `${input.model}${face}-${res}-${input.duration}s`;
@@ -2195,9 +2565,15 @@ function resolveVideoModel(raw) {
         out.sound = true;
         s = s.replace(/-audio\b/, '');
     }
-    if (/-(realface|face)\b/.test(s)) {
-        out.seedanceFace = true;
-        s = s.replace(/-(realface|face)\b/, '');
+    // Two routes, two keys: `-realface` is the real-person route (still refused
+    // without realFaceConsent), `-face` the AI-face one.
+    const face = /-(realface|face)\b/.exec(s);
+    if (face) {
+        if (face[1] === 'realface')
+            out.seedanceRealFace = true;
+        else
+            out.seedanceFace = true;
+        s = s.replace(face[0], '');
     }
     const direct = VIDEO_MODELS.find((m) => m === s);
     if (direct) {
@@ -2211,8 +2587,8 @@ function resolveVideoModel(raw) {
         'kling-v3': 'kling-v3.0-std',
         'kling-v3-pro': 'kling-v3.0-pro',
         'kling-v3-omni': 'kling-v3.0-omni',
-        'kling-v3-omni-pro': 'kling-v3.0-omni',
-        'kling-v3.0-omni-pro': 'kling-v3.0-omni',
+        // No Omni Pro spelling here: Omni Pro is not a seat on this surface, and
+        // aliasing it to Omni ran a cheaper model after a Pro quote.
         'seedance-2.0': 'seedance-2',
         'seedance-2-0': 'seedance-2',
         // ⚠️ The 2.5 spellings must resolve to 2.5, and the BARE `seedance` keeps
@@ -2229,9 +2605,14 @@ function resolveVideoModel(raw) {
         'gemini-omni-flash': 'omni-flash',
         'gemini-omni-flash-preview': 'omni-flash',
         'omni-flash-preview': 'omni-flash',
-        // The MAX spellings must come out as MAX. Bare `minimax`, `h3` and
-        // `hailuo-3` all mean the BASE row — it holds the full ladder and the
-        // references, and it is cheaper at the tier they share.
+        // The MAX and TURBO spellings must come out as themselves. Bare `minimax`,
+        // `h3` and `hailuo-3` all mean the BASE row — it holds the full ladder and
+        // the references, and it is cheaper than Max at the tier they share.
+        'minimax-h3-max-turbo': 'minimax-h3-max-turbo',
+        'minimax-h3-turbo': 'minimax-h3-max-turbo',
+        'h3-max-turbo': 'minimax-h3-max-turbo',
+        'h3-turbo': 'minimax-h3-max-turbo',
+        'hailuo-3-max-turbo': 'minimax-h3-max-turbo',
         'minimax-h3-max': 'minimax-h3-max',
         'minimax-h3max': 'minimax-h3-max',
         'h3-max': 'minimax-h3-max',
@@ -2348,7 +2729,7 @@ export const generateVideo = {
         // kling-v3.0-omni-pro entirely and read as if 7 were an Omni Flash-only rule.
         `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.'),
+        environmentAssetIds: z.array(z.string()).optional().describe('Location 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.'),
@@ -2361,11 +2742,11 @@ export const generateVideo = {
         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. ${multimodalRefModels().join(' / ')} only. No billing surcharge. ${multimodalRefModels().map(multimodalRefSummary).join(' ')}`),
         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.'),
+        sound: z.boolean().optional().describe('Kling Omni / Veo / Seedance: Sound on (true) or Silent (false). 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: 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.'),
+        seedanceRealFace: z.boolean().optional().describe('Seedance ONLY: a reference shows a REAL person. Real-person 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),
@@ -2391,13 +2772,15 @@ export const generateVideo = {
             input.sound = resolved.sound;
         if (input.seedanceFace == null && resolved.seedanceFace != null)
             input.seedanceFace = resolved.seedanceFace;
+        if (input.seedanceRealFace == null && resolved.seedanceRealFace != null)
+            input.seedanceRealFace = resolved.seedanceRealFace;
         // projectId is required for video — without it there's no UI feedback,
         // no asset to reference later, and a failed gen leaves the user with
         // nothing. The MCP-only headless path that exists for image gen is
         // not reasonable for video given the cost.
         // Non-blocking prompt hygiene, computed once. Reported on the gates that
         // fire BEFORE any spend, where a rewrite is still free.
-        const promptWarning = bannedTokenWarning(input.prompt, 'video');
+        const promptWarning = bannedTokenWarning(input.prompt, 'video', promptingSkillFor(resolved.model));
         if (!input.projectId) {
             return ok({
                 requires_clarification: true,
@@ -2497,7 +2880,9 @@ export const generateVideo = {
         // not a number the registry models: fal publishes text-to-video,
         // image-to-video and reference-to-video for `minimax/h3`, and only the
         // all three for `minimax/h3-max` as well (corrected 2026-09-09 — its
-        // reference-to-video was wrongly believed to 404). The
+        // reference-to-video was wrongly believed to 404). `minimax/h3-max-turbo`
+        // has text-to-video and image-to-video only; its caps declare no references,
+        // so the first branch below refuses them. The
         // reference endpoint has no frame parameters at all, so frames and
         // references are mutually exclusive — a shape mismatch, not a preference.
         if (MINIMAX_MODELS.has(input.model)) {
@@ -2669,7 +3054,7 @@ export const generateVideo = {
             return ok({
                 requires_clarification: true,
                 missing: ['videoReferenceSeconds'],
-                message: 'A Seedance video reference bills on combined input+output seconds. Pass videoReferenceSeconds (the reference clip\'s duration, shown in slates_list_assets) so the pre-flight quote matches the bill.',
+                message: 'A Seedance video reference bills on combined input+output seconds (on 2.5 AI-face, max(input, output) + output). Pass videoReferenceSeconds (the reference clip\'s duration, shown in slates_list_assets) so the pre-flight quote matches the bill.',
             });
         }
         const pluralRefCount = input.videoReferenceAssetIds?.length ?? 0;
@@ -2678,7 +3063,7 @@ export const generateVideo = {
             return ok({
                 requires_clarification: true,
                 missing: ['videoReferenceSecondsEach'],
-                message: `A Seedance video reference bills on combined input+output seconds. Pass videoReferenceSecondsEach with exactly ${pluralRefCount} duration${pluralRefCount === 1 ? '' : 's'}, in the same order as videoReferenceAssetIds (durations are shown in slates_list_assets), so the pre-flight quote matches the bill.`,
+                message: `A Seedance video reference bills on combined input+output seconds (on 2.5 AI-face, max(input, output) + output). Pass videoReferenceSecondsEach with exactly ${pluralRefCount} duration${pluralRefCount === 1 ? '' : 's'}, in the same order as videoReferenceAssetIds (durations are shown in slates_list_assets), so the pre-flight quote matches the bill.`,
             });
         }
         const cloud = ctx.cloud();
@@ -3139,11 +3524,42 @@ export const generateAudio = {
         };
     },
 };
+// ── The Kling tools' quote (lip-sync, motion transfer) ─────────
+/** The server bills the tools in blocks of this many seconds (slates-api `TOOL_BLOCK_SECONDS`). */
+const TOOL_BLOCK_SECONDS = 5;
+/** A project asset's recorded length in seconds, or null when its row has none. */
+async function recordedSeconds(desktop, projectId, assetId) {
+    const { assets } = await desktop.get('/agent/assets', { projectId });
+    const row = (assets ?? []).find((a) => String(a.id).toLowerCase() === assetId.toLowerCase());
+    const seconds = Number(row?.duration);
+    return Number.isFinite(seconds) && seconds > 0 ? seconds : null;
+}
+/**
+ * Whole blocks of the media the output follows, priced as the server bills
+ * them: `${stem}-${blocks × 5}s` measured from that media (slates-api
+ * `tool-keys.ts`), plus one flat block for a voice step. An unknown length
+ * quotes one block, the floor. A flat one-block quote approved a 30s Motion
+ * Control Pro at 42 credits that billed 252.
+ */
+async function quoteToolBlocks(ctx, stem, seconds, voiceStep) {
+    const blocks = Math.max(1, Math.ceil((seconds ?? 0) / TOOL_BLOCK_SECONDS));
+    const costKey = `${stem}-${blocks * TOOL_BLOCK_SECONDS}s`;
+    const byKey = new Map();
+    const price = async (key) => {
+        await loadDynamicPrice(ctx, byKey, key);
+        const credits = byKey.get(key);
+        if (credits == null)
+            throw new Error(`Model variant not in registry: ${key}`);
+        return credits;
+    };
+    const totalCents = (await price(costKey)) + (voiceStep ? await price(`${stem}-${TOOL_BLOCK_SECONDS}s`) : 0);
+    return { costKey, totalCents, blocks };
+}
 // ── Generate lip-sync ───────────────────────────────────────────
 export const generateLipSync = {
     id: 'slates_generate_lip_sync',
     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.',
+    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. Billed per 5s of the output (the clip, or on a still the voice track). 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.'),
@@ -3174,27 +3590,28 @@ export const generateLipSync = {
                 message: 'audioMethod=upload requires audioFilePath. Pass an absolute path to the audio file on the user\'s machine.',
             });
         }
-        let costKey;
-        if (input.sourceType === 'video') {
-            costKey = 'kling-lip-sync-video-5s';
-        }
-        else {
-            costKey = input.avatarModel === 'avatar-pro'
-                ? 'kling-lip-sync-avatar-pro-5s'
-                : 'kling-lip-sync-avatar-5s';
-        }
-        const cloud = ctx.cloud();
-        const registry = await cloud.get('/api/agent/models');
-        const entry = registry.models.find((m) => m.model === costKey) ??
-            (await cloud.get(`/api/agent/models?costKey=${encodeURIComponent(costKey)}`)).models[0];
-        if (!entry)
-            throw new Error(`Model variant not in registry: ${costKey}`);
-        const totalCents = creditCost(entry);
+        const stem = input.sourceType === 'video'
+            ? 'kling-lip-sync-video'
+            : input.avatarModel === 'avatar-pro' ? 'kling-lip-sync-avatar-pro' : 'kling-lip-sync-avatar';
+        // Billed per 5s block of the output: the clip's length on a video source;
+        // on a still, the voice track's — typed words at the desktop's reading pace
+        // (`lipSyncEstimate`, 13 characters a second, so this quote is the Generate
+        // button's), an uploaded file unknown until the desktop measures it. Typed
+        // words on a still are two billed calls: the voice step adds one flat block.
+        const seconds = input.sourceType === 'video'
+            ? await recordedSeconds(ctx.desktop(), input.projectId, input.sourceAssetId)
+            : input.audioMethod === 'tts'
+                ? (input.ttsText ?? '').trim().length / (13 * (input.ttsSpeed ?? 1))
+                : null;
+        const voiceStep = input.sourceType === 'image' && input.audioMethod === 'tts';
+        const { costKey, totalCents, blocks } = await quoteToolBlocks(ctx, stem, seconds, voiceStep);
+        const length = `${blocks * TOOL_BLOCK_SECONDS}s${voiceStep ? ' + voice' : ''}`;
         // Cost confirm gate. Lip-sync is mechanical — the model re-syncs the
         // user-chosen source to the user-chosen audio. The agent doesn't
         // write a prompt that depends on what the source looks like, so we
         // skip the inline preview and just announce the source code in text.
-        if (totalCents > CONFIRM_CREDITS && !input.confirm) {
+        // An unknown length quotes one block, a floor, so it always asks.
+        if ((totalCents > CONFIRM_CREDITS || seconds == null) && !input.confirm) {
             const sourceRef = await lookupAssetRef(ctx.desktop(), input.sourceAssetId);
             const audioPreview = input.audioMethod === 'tts'
                 ? `Audio: TTS — "${(input.ttsText ?? '').slice(0, 120)}"`
@@ -3205,7 +3622,7 @@ export const generateLipSync = {
                 estimated_cents: totalCents,
                 estimated_credits: totalCents,
                 source_ref: sourceRef,
-                message: `Cost: ${fmtCredits(totalCents)} for 5s lip-sync (${costKey}). ` +
+                message: `Cost: ${fmtCredits(totalCents)}${seconds == null ? ' or more' : ''} for ${length} lip-sync (${costKey}). ` +
                     `Source: ${sourceRef}. ${audioPreview}. ` +
                     `Re-call with confirm=true after the user explicitly OKs the spend. ` +
                     `When discussing with the user, refer to the source by its code (matches the gallery badge).`,
@@ -3226,14 +3643,15 @@ export const generateLipSync = {
             audioFilePath: input.audioFilePath,
             avatarModel: input.avatarModel,
             klingProvider: input.klingProvider,
-            estimatedCost: totalCents,
+            // No estimatedCost: the desktop prices the media itself, in dollars.
+            // This op's figure is CREDITS, which a 1.5.8 desktop recorded as dollars.
             background: input.background,
         });
         if (!result.success)
             throw new Error(result.error ?? 'Lip-sync generation failed');
         if (result.background) {
             const ids = result.generationIds ?? (result.generationId ? [result.generationId] : []);
-            return backgroundSubmitted(`5s lip-sync (${costKey})`, ids, {
+            return backgroundSubmitted(`${length} lip-sync (${costKey})`, ids, {
                 variant: costKey,
                 projectId: input.projectId,
                 sourceAssetId: input.sourceAssetId,
@@ -3242,7 +3660,7 @@ export const generateLipSync = {
             });
         }
         return {
-            text: `Generated 5s lip-sync (${costKey}) into project ${input.projectId} ` +
+            text: `Generated ${length} lip-sync (${costKey}) into project ${input.projectId} ` +
                 `for ${fmtCredits(totalCents)}. ` +
                 (input.audioMethod === 'tts'
                     ? `Spoken: "${(input.ttsText ?? '').slice(0, 60)}${(input.ttsText ?? '').length > 60 ? '...' : ''}"`
@@ -3264,7 +3682,7 @@ export const generateLipSync = {
 export const generateMotionTransfer = {
     id: 'slates_generate_motion_transfer',
     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. ' +
+    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, billed per 5s of the driving clip. 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.'),
@@ -3279,19 +3697,17 @@ export const generateMotionTransfer = {
     }),
     async run(input, ctx) {
         const motionModel = input.motionModel ?? 'kling-mc-pro';
-        const costKey = motionModel === 'kling-mc-std' ? 'kling-mc-std-5s' : 'kling-mc-pro-5s';
-        const cloud = ctx.cloud();
-        const registry = await cloud.get('/api/agent/models');
-        const entry = registry.models.find((m) => m.model === costKey) ??
-            (await cloud.get(`/api/agent/models?costKey=${encodeURIComponent(costKey)}`)).models[0];
-        if (!entry)
-            throw new Error(`Model variant not in registry: ${costKey}`);
-        const totalCents = creditCost(entry);
+        // Billed per 5s block of the driving clip, which the output follows, up to
+        // the orientation's maximum (the desktop's `motionTransferEstimate`).
+        const clipSeconds = await recordedSeconds(ctx.desktop(), input.projectId, input.sourceVideoAssetId);
+        const seconds = clipSeconds == null ? null : Math.min(clipSeconds, (input.characterOrientation ?? 'video') === 'video' ? 30 : 10);
+        const { costKey, totalCents, blocks } = await quoteToolBlocks(ctx, motionModel, seconds, false);
         // Cost confirm gate. Motion transfer is mechanical — the model
         // applies source motion to target image deterministically. We don't
         // burn tokens previewing assets the user already chose; codes in the
-        // text are enough to keep the chat unambiguous.
-        if (totalCents > CONFIRM_CREDITS && !input.confirm) {
+        // text are enough to keep the chat unambiguous. A clip with no recorded
+        // length quotes one block, a floor, so it always asks.
+        if ((totalCents > CONFIRM_CREDITS || seconds == null) && !input.confirm) {
             const desktop = ctx.desktop();
             const [source, target] = await Promise.all([
                 lookupAssetRef(desktop, input.sourceVideoAssetId),
@@ -3304,14 +3720,14 @@ export const generateMotionTransfer = {
                 estimated_credits: totalCents,
                 source_ref: source,
                 target_ref: target,
-                message: `Cost: ${fmtCredits(totalCents)} for 5s ${motionModel} (${costKey}). ` +
+                message: `Cost: ${fmtCredits(totalCents)}${seconds == null ? ' or more' : ''} for ${blocks * TOOL_BLOCK_SECONDS}s ${motionModel} (${costKey}). ` +
                     `Transferring motion from ${source} onto ${target}. ` +
                     // 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;
+                        ? await (async () => {
+                            const std = await quoteToolBlocks(ctx, 'kling-mc-std', seconds, false);
+                            const saving = totalCents - std.totalCents;
                             return saving > 0 ? `, or pick kling-mc-std to save ${fmtCredits(saving)}` : '';
                         })()
                         : ''}. ` +
@@ -3330,14 +3746,15 @@ export const generateMotionTransfer = {
             characterOrientation: input.characterOrientation ?? 'video',
             prompt: input.prompt,
             klingProvider: input.klingProvider,
-            estimatedCost: totalCents,
+            // No estimatedCost: the desktop prices the media itself, in dollars.
+            // This op's figure is CREDITS, which a 1.5.8 desktop recorded as dollars.
             background: input.background,
         });
         if (!result.success)
             throw new Error(result.error ?? 'Motion transfer generation failed');
         if (result.background) {
             const ids = result.generationIds ?? (result.generationId ? [result.generationId] : []);
-            return backgroundSubmitted(`5s motion transfer (${motionModel})`, ids, {
+            return backgroundSubmitted(`motion transfer (${motionModel})`, ids, {
                 variant: costKey,
                 motionModel,
                 projectId: input.projectId,
@@ -3348,7 +3765,7 @@ export const generateMotionTransfer = {
             });
         }
         return {
-            text: `Generated 5s motion transfer (${motionModel}) into project ${input.projectId} ` +
+            text: `Generated motion transfer (${motionModel}) into project ${input.projectId} ` +
                 `for ${fmtCredits(totalCents)}.` +
                 (input.prompt ? ` Prompt: "${input.prompt.slice(0, 60)}${input.prompt.length > 60 ? '...' : ''}"` : ''),
             data: {
@@ -3633,15 +4050,53 @@ export const listGenerations = {
         }));
     },
 };
+const exportCutsInput = z.object({ projectId: z.string().uuid(), directory: z.string(), manifestId: z.string().min(1),
+    action: z.enum(['start', 'status', 'cancel']).optional().describe('start (default) begins, or re-attaches to a running export; status reads it; cancel stops after the output being rendered.'),
+    items: z.array(z.object({ timelineId: z.string().uuid(), format: z.enum(['mp4', 'xml']) })).min(1).optional().describe('Required to start.') });
+export const exportCuts = {
+    id: 'slates_export_cuts', description: 'Export explicit named cuts to distinct local files with a frozen manifest of timeline settings, media, script revisions and generation provenance. Returns at once while rendering continues; poll with action status. Starting again with the same manifestId and selection retries unfinished outputs under the same filenames and skips finished ones. Existing outputs are never overwritten, and export never generates media. Uses current video/XML fidelity limits.',
+    input: exportCutsInput,
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('named-cuts', 'named cuts');
+        return ok(await ctx.desktop().post('/agent/timeline/export-cuts', input));
+    },
+};
+export const listTimelines = {
+    id: 'slates_list_timelines', description: 'List the independent named cuts in a project. Use the selected timelineId for edits, builds and exports.',
+    input: z.object({ projectId: z.string().uuid() }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('named-cuts', 'named cuts');
+        return ok(await ctx.desktop().get('/agent/timelines', input));
+    },
+};
+export const saveTimeline = {
+    id: 'slates_save_timeline', description: 'Create a named cut, or rename the explicit timelineId. Existing cuts and the legacy default stay intact.',
+    input: z.object({ projectId: z.string().uuid(), timelineId: z.string().uuid().optional(), name: z.string().min(1) }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('named-cuts', 'named cuts');
+        return ok(await ctx.desktop().post('/agent/timelines', input));
+    },
+};
+/**
+ * A `timelineId` names a cut only on a desktop with named cuts. Its read, clip,
+ * track and settings routes predate them and ignore the field, so a 1.5.8
+ * desktop would act on the default timeline instead of the one named. The
+ * exports resolved a timeline id before named cuts and need no gate.
+ */
+async function requireNamedCut(desktop, timelineId) {
+    if (timelineId)
+        await desktop.requireCapability('named-cuts', 'named cuts');
+}
 export const getTimeline = {
     id: 'slates_get_timeline',
-    description: 'Get (or lazily create) the single editing timeline for a Slates project, with all tracks, clips, markers, and a flat clipIndex mapping every clip back to its source asset (assetId + code + label). Frames are the unit of time; durationSec is provided. Call this before adding, reordering, or removing clips, and before exporting — it tells you the timeline id, frame rate, resolution, and current end frame.',
-    input: z.object({ projectId: z.string().uuid() }),
+    description: 'Get (or lazily create) a named editing timeline, or the stable legacy default when timelineId is omitted, with all tracks, clips, markers, and a flat clipIndex mapping every clip back to its source asset (assetId + code + label). Frames are the unit of time; durationSec is provided. Call this before adding, reordering, or removing clips, and before exporting — it tells you the timeline id, frame rate, resolution, and current end frame.',
+    input: z.object({ projectId: z.string().uuid(), timelineId: z.string().uuid().optional() }),
     async run(input, ctx) {
         const desktop = ctx.desktop();
         await desktop.requireCapability('timeline', 'timeline editing');
+        await requireNamedCut(desktop, input.timelineId);
         const r = await desktop.get('/agent/timeline', {
-            projectId: input.projectId,
+            projectId: input.projectId, timelineId: input.timelineId,
         });
         const t = r.timeline ?? {};
         const clipCount = r.clipIndex?.length ??
@@ -3657,7 +4112,7 @@ export const addClipToTimeline = {
     id: 'slates_add_clip_to_timeline',
     description: "Append a video or audio asset from the project to the project's timeline (or place it at an explicit startFrame). Defaults match the desktop UI: video clips go to the end of the first video track; audio clips (music, voiceover, AI audio) go after the last clip on the first AUDIO track and are mixed under the video on export. An empty timeline auto-adopts the first video clip's resolution and frame rate; later higher-resolution clips raise the canvas. Overlapping video clips resolve top-track-wins. Optionally trim with sourceInFrame/sourceOutFrame (frames at the SOURCE fps). Use slates_get_timeline first to see current clips and pick positions.",
     input: z.object({
-        projectId: z.string().uuid(),
+        projectId: z.string().uuid(), timelineId: z.string().uuid().optional(),
         assetId: z.string().uuid().describe('Video or audio asset already in the project.'),
         trackId: z.string().uuid().optional().describe('Target track (type must match the asset: video asset → video track, audio asset → audio track). Default: the first track of the matching type.'),
         startFrame: z.number().int().min(0).optional().describe('Timeline frame to place the clip at. Default: append after the last clip.'),
@@ -3667,8 +4122,9 @@ export const addClipToTimeline = {
     async run(input, ctx) {
         const desktop = ctx.desktop();
         await desktop.requireCapability('timeline', 'timeline editing');
+        await requireNamedCut(desktop, input.timelineId);
         const r = await desktop.post('/agent/timeline/add-clip', {
-            projectId: input.projectId,
+            projectId: input.projectId, timelineId: input.timelineId,
             assetId: input.assetId,
             trackId: input.trackId,
             startFrame: input.startFrame,
@@ -3710,17 +4166,40 @@ export const removeClip = {
         return ok(await desktop.post('/agent/timeline/remove-clip', input));
     },
 };
+export const manageTimelineMarker = {
+    id: 'slates_manage_timeline_marker',
+    description: "Add, change or delete a marker on the timeline, as the Cut's ruler and marker menus do (slates_get_timeline lists them under timeline.markers). create: frame, optional name and color. update: markerId plus any of frame, name, color. delete: markerId. The color is one of the app's marker colours by name (e.g. Red); any other is refused with the list. The open Cut shows the change.",
+    input: z.object({
+        action: z.enum(['create', 'update', 'delete']),
+        projectId: z.string().uuid(),
+        timelineId: z.string().uuid().optional().describe("A named cut; omit for the project's timeline."),
+        markerId: z.string().uuid().optional(),
+        frame: z.number().int().min(0).optional().describe('Where the marker sits, in timeline frames.'),
+        name: z.string().max(120).optional(),
+        color: z.string().optional(),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('timeline-markers', 'timeline markers');
+        if (input.action === 'create' && input.frame === undefined)
+            throw new Error('create needs a frame.');
+        if (input.action !== 'create' && !input.markerId)
+            throw new Error(`${input.action} needs a markerId (slates_get_timeline lists them).`);
+        return ok(await desktop.post('/agent/timeline/markers', input));
+    },
+};
 export const addTimelineTrack = {
     id: 'slates_add_timeline_track',
     description: "Add a track to the project's timeline (default: an audio track, for layering voiceover + music + AI audio). The new track is appended below existing tracks. Returns the new track and the full timeline.",
     input: z.object({
-        projectId: z.string().uuid(),
+        projectId: z.string().uuid(), timelineId: z.string().uuid().optional(),
         type: z.enum(['video', 'audio']).optional().describe('Default: audio.'),
         name: z.string().optional().describe("Default: 'Audio N' / 'Video N'."),
     }),
     async run(input, ctx) {
         const desktop = ctx.desktop();
         await desktop.requireCapability('timeline-tracks', 'timeline tracks + audio mixing');
+        await requireNamedCut(desktop, input.timelineId);
         return ok(await desktop.post('/agent/timeline/add-track', input));
     },
 };
@@ -3758,7 +4237,7 @@ export const updateTimelineSettings = {
     id: 'slates_update_timeline_settings',
     description: "Update the project timeline's output settings: resolution, frame rate (24/30/60 — all clips are conformed to it on export), and masterVolume, the output fader (linear gain, -∞ to +12 dB) applied to the final mix in both preview and MP4 export (use it to prevent clipping when stacking loud tracks). Note these are normally auto-managed: the first video clip sets fps + resolution, and higher-res clips raise the canvas. Changing frameRate after clips are placed retimes them — avoid unless the timeline is empty.",
     input: z.object({
-        projectId: z.string().uuid(),
+        projectId: z.string().uuid(), timelineId: z.string().uuid().optional(),
         width: z.number().int().min(16).optional(),
         height: z.number().int().min(16).optional(),
         frameRate: z.union([z.literal(24), z.literal(30), z.literal(60)]).optional(),
@@ -3767,6 +4246,7 @@ export const updateTimelineSettings = {
     async run(input, ctx) {
         const desktop = ctx.desktop();
         await desktop.requireCapability('timeline-tracks', 'timeline tracks + audio mixing');
+        await requireNamedCut(desktop, input.timelineId);
         return ok(await desktop.post('/agent/timeline/update-settings', input));
     },
 };
@@ -3804,7 +4284,7 @@ export const exportVideo = {
 };
 export const exportTimelineXml = {
     id: 'slates_export_timeline_xml',
-    description: "Export the project's timeline as FCP7/XMEML XML — the file DaVinci Resolve imports directly (File → Import → Timeline) to recreate the edit with references to the original clip media on disk. This is the 'open in DaVinci' handoff path. Pass an absolute outputPath ending in .xml; fails if the file exists unless overwrite=true.",
+    description: "Export the project's timeline as FCP7/XMEML XML — the file DaVinci Resolve imports directly (File → Import → Timeline) to recreate the edit with references to the original clip media on disk. This is the 'Export for DaVinci, Premiere or Final Cut' path. Pass an absolute outputPath ending in .xml; fails if the file exists unless overwrite=true.",
     input: z
         .object({
         projectId: z.string().uuid().optional(),
@@ -3859,7 +4339,7 @@ export const updateProject = {
 };
 export const deleteProject = {
     id: 'slates_delete_project',
-    description: 'Delete a Slates project. DESTRUCTIVE — permanently removes the project with all its assets, storyboards, and media files. Requires confirm=true after explicit user OK.',
+    description: 'Delete a Slates project. DESTRUCTIVE — permanently removes the project with all its assets, boards, and media files. Requires confirm=true after explicit user OK.',
     input: z.object({
         id: z.string().uuid(),
         confirm: z.boolean().optional().describe('Set true only after the user explicitly OKs the deletion.'),
@@ -3868,7 +4348,7 @@ export const deleteProject = {
         if (!input.confirm) {
             return ok({
                 requires_confirm: true,
-                message: 'Deleting a project permanently removes all its assets, storyboards, and media files. Re-call with confirm=true after explicit user OK.',
+                message: 'Deleting a project permanently removes all its assets, boards, and media files. Re-call with confirm=true after explicit user OK.',
             });
         }
         return ok(await ctx.desktop().post('/agent/projects/delete', { id: input.id }));
@@ -3882,6 +4362,36 @@ export const getProjectDirectory = {
         return ok(await ctx.desktop().get('/agent/projects/location', { id: input.id }));
     },
 };
+/** What both relocation routes answer: the folder the project now uses, and
+ *  the one its files could not all be removed from, when that happened. */
+function relocated(r, done) {
+    const text = r.leftBehind
+        ? `${done} to ${r.directory}. Some files could not be removed from ${r.leftBehind}, so both folders exist and the project uses the new one; tell the user, and delete the old folder once nothing holds it open. There is no undo for this move.`
+        : `${done} to ${r.directory}.`;
+    return ok(r, text);
+}
+export const relocateProject = {
+    id: 'slates_relocate_project',
+    description: "Move a project stored in an older folder into the current projects folder (Settings › Storage's move): its files are copied, every path is pointed at the copy, then the old folder is removed. slates_get_project_directory says where it is now. slates_undo_relocate_project puts it back while Slates stays open. Refused while the project is generating.",
+    input: z.object({ id: z.string().uuid() }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('project-relocate', 'moving a project into the current projects folder');
+        const r = await desktop.post('/agent/projects/relocate', { id: input.id });
+        const moved = relocated(r, 'Moved the project');
+        return r.leftBehind ? moved : { ...moved, text: `${moved.text} slates_undo_relocate_project puts it back until Slates quits.` };
+    },
+};
+export const undoRelocateProject = {
+    id: 'slates_undo_relocate_project',
+    description: "Put a project moved by slates_relocate_project (or Settings › Storage) back in the folder it came from. Works only for the last move, in the same run of Slates, and only while nothing has moved it since.",
+    input: z.object({ id: z.string().uuid() }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('project-relocate', 'moving a project back');
+        return relocated(await desktop.post('/agent/projects/relocate-undo', { id: input.id }), 'Moved the project back');
+    },
+};
 export const deleteAsset = {
     id: 'slates_delete_asset',
     description: 'Delete an asset from its project. Permanent — also deletes the media file from disk.',
@@ -3962,7 +4472,7 @@ export const deleteCharacter = {
 };
 export const updateEnvironment = {
     id: 'slates_update_environment',
-    description: 'Update an environment\'s name, description, style, or bound reference image (referenceAssetId=null clears it).',
+    description: 'Update a location\'s name, description, style, or bound reference image (referenceAssetId=null clears it).',
     input: z.object({
         environmentId: z.string().uuid(),
         name: z.string().min(1).max(120).optional(),
@@ -3984,7 +4494,7 @@ export const updateEnvironment = {
 };
 export const deleteEnvironment = {
     id: 'slates_delete_environment',
-    description: 'Delete an environment from its project.',
+    description: 'Delete a location from its project.',
     input: z.object({ environmentId: z.string().uuid() }),
     async run(input, ctx) {
         return ok(await ctx.desktop().post('/agent/environments/delete', { id: input.environmentId }));
@@ -3992,7 +4502,7 @@ export const deleteEnvironment = {
 };
 export const listStyles = {
     id: 'slates_list_styles',
-    description: 'List visual styles in a Slates project.',
+    description: 'List the looks (styles) in a Slates project.',
     input: z.object({ projectId: z.string().uuid() }),
     async run(input, ctx) {
         return ok(await ctx.desktop().get('/agent/styles', { projectId: input.projectId }));
@@ -4000,7 +4510,7 @@ export const listStyles = {
 };
 export const createStyle = {
     id: 'slates_create_style',
-    description: 'Create a new visual style in a Slates project.',
+    description: 'Create a new look (style) in a Slates project.',
     input: z.object({
         projectId: z.string().uuid(),
         name: z.string().min(1).max(120),
@@ -4012,7 +4522,7 @@ export const createStyle = {
 };
 export const updateStyle = {
     id: 'slates_update_style',
-    description: 'Update a style\'s name, description, or bound reference image (imageAssetId=null clears it).',
+    description: 'Update a look\'s name, description, or bound reference image (imageAssetId=null clears it).',
     input: z.object({
         styleId: z.string().uuid(),
         name: z.string().min(1).max(120).optional(),
@@ -4028,15 +4538,199 @@ export const updateStyle = {
 };
 export const deleteStyle = {
     id: 'slates_delete_style',
-    description: 'Delete a visual style from its project.',
+    description: 'Delete a look from its project.',
     input: z.object({ styleId: z.string().uuid() }),
     async run(input, ctx) {
         return ok(await ctx.desktop().post('/agent/styles/delete', { id: input.styleId }));
     },
 };
+// ── The Library ─────────────────────────────────────────────────
+// One saved reference in a category the USER names (characters, locations,
+// products, looks…). The character / environment / style ops above read and
+// write the same rows and stay for published clients; new work uses these.
+export const listLibrary = {
+    id: 'slates_list_library',
+    description: "List a project's Library: its categories (user-named; each is kind 'thing' = used as @name in prompts, or 'look' = used as #name) and every saved reference in them. Each item carries `mention` — exactly what to type in a prompt to attach it (a bare name is prose and attaches nothing) — plus its image, source and voice asset ids.",
+    input: z.object({ projectId: z.string().uuid() }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('library', 'the Library');
+        return ok(await ctx.desktop().get('/agent/library', { projectId: input.projectId }));
+    },
+};
+export const createLibraryItem = {
+    id: 'slates_create_library_item',
+    description: 'Save a reference to the Library in one of the project\'s categories (ids from slates_list_library) — a person, a location, a product, a prop, a look. Names share ONE namespace per sigil: a name whose handle is already taken comes back suffixed ("Candle 2"), so read `mention` from the result instead of assuming it. Pass imageAssetId (UUID or badge code) to bind its picture in the same call.',
+    input: z.object({
+        projectId: z.string().uuid(),
+        categoryId: z.string().uuid(),
+        name: z.string().min(1).max(120),
+        description: z.string().optional(),
+        style: z.string().max(200).optional().describe('Optional free-text style instruction the sheet tools read.'),
+        imageAssetId: z.string().min(1).optional().describe('The one image a mention attaches. UUID or badge code ("IMG-A8").'),
+    }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('library', 'the Library');
+        const { imageAssetId, ...body } = input;
+        // Resolved BEFORE the create, so an unknown code fails without leaving an
+        // item behind.
+        const resolved = imageAssetId ? await resolveAssetRefs(ctx, input.projectId, [imageAssetId]) : null;
+        const created = await ctx.desktop().post('/agent/library/items', body);
+        if (!imageAssetId || !resolved)
+            return ok(created);
+        return ok(await ctx.desktop().post('/agent/library/items/update', {
+            id: created.item.id,
+            data: { imageAssetId: resolved.get(imageAssetId).id },
+        }));
+    },
+};
+export const updateLibraryItem = {
+    id: 'slates_update_library_item',
+    description: "Update a Library item: rename it, move it to another category (categoryId), bind its picture (imageAssetId) or its voice (voiceAssetId, an audio asset; a thing in a location category composes as an environment and carries none). null clears an asset; the asset itself stays. Moving between a 'thing' and a 'look' category flips the sigil (@ ↔ #), and moving a thing into or out of a 'location'-template category changes what it composes as. A rename changes its handle. In every case each saved Shot that mentions the item is rewritten to match (the mention in its prompt, and its mention id), and the result's `move` reports `shotsMentioning`, `shotsRetagged` and the old and new `mention`: tell the user what changed. Pass retagShots:false to leave Shots alone; they then show the item as missing until it is mentioned again. Moving it back, or renaming it back, undoes the rewrite.",
+    input: z.object({
+        projectId: z.string().uuid().describe('The project the item is in — asset codes resolve against it.'),
+        itemId: z.string().uuid(),
+        name: z.string().min(1).max(120).optional(),
+        description: z.string().optional(),
+        style: z.string().max(200).optional(),
+        categoryId: z.string().uuid().optional(),
+        retagShots: z.boolean().optional().describe('Only with categoryId or name. Default true: Shots that mention the item follow a move or a rename that changes how it is mentioned.'),
+        imageAssetId: z.string().min(1).nullable().optional().describe('UUID or badge code; null clears.'),
+        voiceAssetId: z.string().min(1).nullable().optional().describe('An AUDIO asset, UUID or badge code; null detaches.'),
+    }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('library', 'the Library');
+        const refs = [input.imageAssetId, input.voiceAssetId].filter((r) => typeof r === 'string');
+        const resolved = await resolveAssetRefs(ctx, input.projectId, refs);
+        const asset = (ref) => typeof ref === 'string' ? resolved.get(ref).id : ref;
+        return ok(await ctx.desktop().post('/agent/library/items/update', {
+            id: input.itemId,
+            retagShots: input.retagShots,
+            data: {
+                name: input.name,
+                description: input.description,
+                style: input.style,
+                categoryId: input.categoryId,
+                // Sent only when given: the route treats presence as intent, and an
+                // explicit null is the clear.
+                ...(input.imageAssetId !== undefined ? { imageAssetId: asset(input.imageAssetId) } : {}),
+                ...(input.voiceAssetId !== undefined ? { voiceAssetId: asset(input.voiceAssetId) } : {}),
+            },
+        }));
+    },
+};
+export const deleteLibraryItem = {
+    id: 'slates_delete_library_item',
+    description: 'Delete a Library item. Its images and voice clip stay in the project as ordinary assets.',
+    input: z.object({ itemId: z.string().uuid() }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('library', 'the Library');
+        return ok(await ctx.desktop().post('/agent/library/items/delete', { id: input.itemId }));
+    },
+};
+export const manageLibraryCategory = {
+    id: 'slates_manage_library_category',
+    description: "Create, rename, change what it is (set-behaviour), reorder or delete a Library category. Categories are the USER's labels (\"Products\", \"Mascots\"); never invent ones they did not ask for. create: projectId + name + kind ('thing' = used as @name in prompts, 'look' = used as #name), optional template ('person' | 'location'; the app asks \"Is this a subject, a place, or a look?\" — a 'location' category's things compose as environments and carry no voice; every other thing composes as a character). set-behaviour: categoryId + kind + template (null for no template); retagShots defaults to true and rewrites affected shot mentions to match. The result reports affected items and rewritten shots. rename: categoryId + name. reorder: projectId + orderedIds (every category id, in the new order). delete: categoryId — refused while the category holds items.",
+    input: z.object({
+        action: z.enum(['create', 'rename', 'set-behaviour', 'reorder', 'delete']),
+        projectId: z.string().uuid().optional(),
+        categoryId: z.string().uuid().optional(),
+        name: z.string().min(1).max(80).optional(),
+        kind: z.enum(['thing', 'look']).optional(),
+        template: z.enum(['person', 'location']).nullable().optional(),
+        retagShots: z.boolean().optional(),
+        orderedIds: z.array(z.string().uuid()).optional(),
+    }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('library', 'the Library');
+        switch (input.action) {
+            case 'create':
+                return ok(await ctx.desktop().post('/agent/library/categories', { projectId: input.projectId, name: input.name, kind: input.kind, template: input.template }));
+            case 'set-behaviour':
+                if (!input.categoryId || !input.kind || input.template === undefined)
+                    throw new Error('set-behaviour requires categoryId, kind and template (null for none)');
+                return ok(await ctx.desktop().post('/agent/library/categories/update', { id: input.categoryId, kind: input.kind, template: input.template, retagShots: input.retagShots }));
+            case 'reorder':
+                return ok(await ctx.desktop().post('/agent/library/categories/update', { projectId: input.projectId, orderedIds: input.orderedIds }));
+            case 'delete':
+                return ok(await ctx.desktop().post('/agent/library/categories/delete', { id: input.categoryId }));
+            default:
+                return ok(await ctx.desktop().post('/agent/library/categories/update', { id: input.categoryId, name: input.name }));
+        }
+    },
+};
+export const copyLibraryItemToProject = {
+    id: 'slates_copy_library_item_to_project',
+    description: "Copy a Library item into another project: the item AND duplicates of its picture, source and voice, filed in the target's category of the same name (made when missing). The original is untouched. Use this to reuse a character or product across projects; use slates_move_entity_to_project to take it out of this one instead.",
+    input: z.object({ itemId: z.string().uuid(), targetProjectId: z.string().uuid() }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('library', 'the Library');
+        return ok(await ctx.desktop().post('/agent/library/items/copy-to-project', { id: input.itemId, targetProjectId: input.targetProjectId }));
+    },
+};
+// ── Templates ───────────────────────────────────────────────────────────
+// A `.slatestemplate` file is a portable storyboard, scene or single Shot: the
+// recipes, their script words, their references and the Library items they
+// mention. It holds no takes, and importing one generates and spends nothing.
+export const getTemplate = {
+    id: 'slates_get_template',
+    description: "Read a Slates template file without changing anything. With `path`: what it holds (scenes, shots, library items, the models its shots are set to) and its SWAP SLOTS — every Library item (`item:i1`, labelled with its mention, e.g. @candle) and every directly attached reference (`asset:a3`, with its roles) that slates_import_template can point at one of the project's own assets instead. Without `path`: the saved templates on this machine (the app's starter set and the user's own folder).",
+    input: z.object({ path: z.string().min(1).optional().describe('Absolute path of a .slatestemplate file. Omit to list saved templates.') }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('templates', 'templates');
+        if (!input.path)
+            return ok(await ctx.desktop().get('/agent/templates'));
+        return ok(await ctx.desktop().get('/agent/templates/inspect', { path: input.path }));
+    },
+};
+export const exportTemplate = {
+    id: 'slates_export_template',
+    description: "Save a board, a scene or one Shot as a template file someone else can start from. Give exactly one of storyboardId, sceneId or shotId. The file carries each Shot's full recipe (prompt, model, settings, reference roles, script words) plus the reference files and the Library items the Shots mention; it carries no takes. The project is untouched. Returns the path, the counts, and a warning for any reference whose file is missing.",
+    input: z.object({
+        projectId: z.string().uuid(),
+        path: z.string().min(1).describe('Absolute path to write, ending in .slatestemplate. Its folder is created if needed.'),
+        storyboardId: z.string().uuid().optional(),
+        sceneId: z.string().uuid().optional(),
+        shotId: z.string().min(1).optional().describe('A Shot id or code (SHOT-A3).'),
+        name: z.string().optional().describe("The template's name. Defaults to the board's, scene's or Shot's."),
+        description: z.string().optional(),
+    }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('templates', 'templates');
+        const named = [input.storyboardId, input.sceneId, input.shotId].filter(Boolean).length;
+        if (named !== 1)
+            throw new Error('Give exactly one of storyboardId, sceneId or shotId.');
+        return ok(await ctx.desktop().post('/agent/templates/export', input));
+    },
+};
+export const importTemplate = {
+    id: 'slates_import_template',
+    description: "Add a template to a project. A board template becomes a new board; a scene template becomes a new scene of `storyboardId` (default: the most recently edited board); a single-Shot template is filed like any new Shot (into `sceneId` when given). Its reference files become new assets of this project and its Library items are created here (a taken name is suffixed and the imported prompts are rewritten to match; see `renamed`). `swaps` maps a slot key from slates_get_template to an asset of THIS project (id or code) of the slot's type: the item takes that picture, or every Shot that attached the template's reference attaches it instead, and the template's own file for that slot is not imported. Generates nothing and spends nothing: price and fire the returned shotIds with slates_generate_from_shots, after the user approves the prices.",
+    input: z.object({
+        projectId: z.string().uuid(),
+        path: z.string().min(1).describe('Absolute path of the .slatestemplate file.'),
+        sceneIndices: z.array(z.number().int().min(0)).min(1).optional().describe('Import only these scene indices from the inspected parts, preserving their order. Omit for the whole template.'),
+        storyboardId: z.string().uuid().optional(),
+        sceneId: z.string().uuid().optional(),
+        swaps: z.record(z.string().min(1)).optional().describe('{ "item:i1": "IMG-A12", "asset:a3": "<asset id>" }'),
+        useTemplateCategories: z
+            .boolean()
+            .optional()
+            .describe("Remove the project's untouched default Library categories the template does not use. Only acts on a project whose Library is empty; defaults to true on a project with no board."),
+    }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('templates', 'templates');
+        const swaps = {};
+        if (input.swaps) {
+            const resolved = await resolveAssetRefs(ctx, input.projectId, Object.values(input.swaps));
+            for (const [slot, ref] of Object.entries(input.swaps))
+                swaps[slot] = resolved.get(ref)?.id ?? ref;
+        }
+        return ok(await ctx.desktop().post('/agent/templates/import', { ...input, swaps }));
+    },
+};
 export const updateStoryboard = {
     id: 'slates_update_storyboard',
-    description: 'Update a storyboard\'s name and/or description.',
+    description: 'Update a board\'s name and/or description.',
     input: z.object({
         storyboardId: z.string().uuid(),
         name: z.string().min(1).max(120).optional(),
@@ -4051,7 +4745,7 @@ export const updateStoryboard = {
 };
 export const deleteStoryboard = {
     id: 'slates_delete_storyboard',
-    description: 'Delete a storyboard with all its scenes and frames (the referenced assets are untouched).',
+    description: 'Delete a board with all its scenes and frames (the referenced assets are untouched).',
     input: z.object({ storyboardId: z.string().uuid() }),
     async run(input, ctx) {
         return ok(await ctx.desktop().post('/agent/storyboards/delete', { id: input.storyboardId }));
@@ -4059,7 +4753,7 @@ export const deleteStoryboard = {
 };
 export const updateScene = {
     id: 'slates_update_scene',
-    description: 'Update a scene\'s name and/or position within its storyboard.',
+    description: 'Update a scene\'s name and/or position within its board.',
     input: z.object({
         sceneId: z.string().uuid(),
         name: z.string().min(1).max(120).optional(),
@@ -4074,7 +4768,7 @@ export const updateScene = {
 };
 export const deleteScene = {
     id: 'slates_delete_scene',
-    description: 'Delete a scene (and its frames) from a storyboard.',
+    description: 'Delete a scene (and its frames) from a board.',
     input: z.object({ sceneId: z.string().uuid() }),
     async run(input, ctx) {
         return ok(await ctx.desktop().post('/agent/scenes/delete', { id: input.sceneId }));
@@ -4082,7 +4776,7 @@ export const deleteScene = {
 };
 export const reorderScenes = {
     id: 'slates_reorder_scenes',
-    description: 'Reorder the scenes of a storyboard. Pass the COMPLETE list of the storyboard\'s scene ids in the desired order.',
+    description: 'Reorder the scenes of a board. Pass the COMPLETE list of the board\'s scene ids in the desired order.',
     input: z.object({
         storyboardId: z.string().uuid(),
         sceneIds: z.array(z.string().uuid()).min(1),
@@ -4098,13 +4792,13 @@ export const updateFrame = {
     // 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.',
+    'Update a slot: its shot label, notes, bound asset (assetId=null unbinds), scene or position. A scene or position change carries the words in this slot with it on the Script page. 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(),
         notes: z.string().optional(),
         assetId: z.string().uuid().nullable().optional(),
-        sceneId: z.string().uuid().nullable().optional(),
+        sceneId: z.string().uuid().optional(),
         position: z.number().int().min(0).optional(),
     }),
     async run(input, ctx) {
@@ -4135,7 +4829,7 @@ export const updateFrame = {
  */
 export const batchUpdateFrames = {
     id: 'slates_batch_update_frames',
-    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.',
+    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. A scene or position change carries the words in each slot with it on the Script page. To write the BEATS themselves, use slates_create_shot / slates_update_shot.',
     input: z.object({
         updates: z
             .array(z.object({
@@ -4143,7 +4837,7 @@ export const batchUpdateFrames = {
             shotLabel: z.string().optional(),
             notes: z.string().optional(),
             assetId: z.string().uuid().nullable().optional(),
-            sceneId: z.string().uuid().nullable().optional(),
+            sceneId: z.string().uuid().optional(),
             position: z.number().int().min(0).optional(),
         }))
             .min(1),
@@ -4231,6 +4925,10 @@ const SHOT_ASPECT_RATIOS = [...new Set([...VIDEO_ASPECT_RATIOS, ...IMAGE_ASPECT_
 // 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.
+//
+// 🚨 EVERY `ShotParams` FIELD, OR A COMPILE ERROR. A plain `z.object` strips
+// what it does not declare, so a field missing here was dropped on save while
+// the op reported success; `satisfies` makes the next new param fail to build.
 function shotParamsShape(described) {
     const d = (node, text) => (described ? node.describe(text) : node);
     return {
@@ -4251,6 +4949,22 @@ function shotParamsShape(described) {
         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.`),
+        quality: z.string().optional(),
+        gridMode: d(z.enum(['off', '2x2', '3x3']).optional(), 'Image models: a grid of takes in one picture.'),
+        audioLanguage: d(z.enum(['en', 'zh', 'ja', 'ko', 'es']).optional(), 'Kling with sound: dialogue language.'),
+        audioAccent: d(z.enum(['american', 'british', 'indian']).optional(), 'Kling with sound: English accent.'),
+        generateMusic: d(z.boolean().optional(), 'Kling Omni: background music.'),
+        multiShot: d(z.boolean().optional(), 'Several cuts in one take (multiShotSegments).'),
+        multiShotSegments: z
+            .array(z.object({ prompt: z.string(), duration: z.number(), camera: z.string(), shotSize: z.string() }))
+            .nullable()
+            .optional(),
+        cameraControls: z
+            .object({ horizontal: z.number(), vertical: z.number(), pan: z.number(), tilt: z.number(), roll: z.number(), zoom: z.number() })
+            .optional(),
+        audioLoop: d(z.boolean().optional(), 'eleven-sfx: seamless loop.'),
+        audioPromptInfluence: d(z.number().min(0).max(1).optional(), 'eleven-sfx: how literally the prompt is followed.'),
+        audioMultilingual: d(z.boolean().optional(), 'seed-audio: mixed-language casting.'),
     };
 }
 const shotParamsSchema = z.object(shotParamsShape(true)).optional();
@@ -4278,6 +4992,8 @@ function shotScriptShape(described) {
     ]));
     return {
         ...text,
+        recipeMode: z.enum(['script', 'custom']).optional().describe('Script mode compiles active words with production fields. Custom keeps the authored prompt exactly.'),
+        promptScriptLine: z.string().nullable().optional().describe('The exact script line reviewed when authoring this custom prompt.'),
         continues: described
             ? z.boolean().optional().describe(SCRIPT_FIELD_DESCRIPTION.continues)
             : z.boolean().optional(),
@@ -4299,6 +5015,10 @@ const FRAMING_NOTE = `shotSize and camera are FREE TEXT and are never rejected o
 function shotScriptPatch(input) {
     const out = {};
     const raw = input;
+    if (input.recipeMode === 'script' || input.recipeMode === 'custom')
+        out.recipeMode = input.recipeMode;
+    if (typeof input.promptScriptLine === 'string' || input.promptScriptLine === null)
+        out.promptScriptLine = input.promptScriptLine;
     for (const field of SCRIPT_TEXT_FIELDS) {
         if (raw[field] !== undefined)
             out[field] = raw[field];
@@ -4444,73 +5164,7 @@ function assertShotCapabilities(model, params) {
     });
     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) => model === 'minimax-h3-max' ? Math.max(0, 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,
-            audioRefSeconds: (detail.references ?? []).filter((r) => r.kind === 'audio').reduce((n, r) => n + (r.durationSeconds ?? 0), 0),
-            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'), 
-        // No inline default — see the note at the estimate op. Firing a Shot with
-        // no stored tier lands on `high` via the desktop's `normalizeGptQuality`,
-        // and `imageCostKey`'s parameter default is pinned to match it.
-        p.gptQuality, 
-        // The aspect the Shot will fire at — on GPT Image it moves the key, so
-        // quoting without it under-prices every square Shot. `fires` carries
-        // only the clamped resolution/duration axes, never the aspect.
-        p.aspectRatio);
-    }
-    return null;
-}
-/** Dynamic reference keys are priced by the same server calculator that debits them. */
+/** Fetch a dynamic cloud cost key for the standalone generation estimate. */
 async function loadDynamicPrice(ctx, byKey, key) {
     if (!key || byKey.has(key))
         return;
@@ -4518,22 +5172,9 @@ async function loadDynamicPrice(ctx, byKey, key) {
     for (const row of response.models)
         byKey.set(row.model, creditCost(row));
 }
-/** 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. ' +
+    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 board automatically (the open scene, else the most recent board) — never unfiled. ' +
         FRAMING_NOTE,
     input: z.object({
         projectId: z.string().uuid(),
@@ -4548,8 +5189,10 @@ export const createShot = {
         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.'),
+        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 board if there is none.'),
         sceneId: z.string().uuid().optional().describe('File it into this scene. Optional; ignored when frameId is given.'),
+        storyboardId: z.string().uuid().optional().describe('File it into this board (its last scene, or a new one). Optional; ignored when frameId or sceneId is given.'),
+        position: z.number().int().min(0).optional().describe('Slot in the scene it files into, 0 = first. Omit to file it last.'),
         ...shotScriptSchema,
     }),
     async run(input, ctx) {
@@ -4561,6 +5204,9 @@ export const createShot = {
             return alignErr;
         const desktop = ctx.desktop();
         await desktop.requireCapability('shots', 'saved Shots');
+        // 1.5.8 ignores `position` and files the Shot last.
+        if (input.position !== undefined)
+            await desktop.requireCapability('shot-position', 'placing a new Shot at a slot');
         const { spec, refEcho } = await buildShotSpecInput(ctx, input.projectId, input);
         const r = await desktop.post('/agent/shots', {
             projectId: input.projectId,
@@ -4568,6 +5214,8 @@ export const createShot = {
             spec: { ...spec, ...shotScriptPatch(input) },
             frameId: input.frameId ?? null,
             sceneId: input.sceneId ?? null,
+            storyboardId: input.storyboardId ?? null,
+            position: input.position,
         });
         // 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.
@@ -4576,7 +5224,7 @@ export const createShot = {
 };
 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. ' +
+    description: 'Change part of a Shot, or attach/detach it from a board 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.'),
@@ -4592,8 +5240,8 @@ export const updateShot = {
         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.'),
+        attachFrameId: z.string().uuid().optional().describe('Attach this Shot to a board frame.'),
+        detachFrameId: z.string().uuid().optional().describe('Detach it from a frame. Not its last one: pass attachFrameId too, or delete the Shot.'),
         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,
     }),
@@ -4759,35 +5407,41 @@ function describeVarietyReport(v) {
 }
 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.",
+    description: "Read the shot list — every Shot as a compact row IN BOARD ORDER (scene, then position), with the piece's cut count, runtime, saved-recipe price 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.'),
+        storyboardId: z.string().uuid().optional().describe('Only Shots attached to a frame in this board.'),
         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');
+        // Prices come only from the desktop's quote; a 1.5.8 desktop has none.
+        await desktop.requireCapability('board-quote', 'Shot prices');
         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)]));
-        for (const row of rows)
-            await loadDynamicPrice(ctx, byKey, shotCostKey(row));
+        const projectId = input.projectId;
+        // The quote is a GET with every id in its query string, and Node refuses a
+        // request head over 16 KiB (about 345 ids), so a long board is quoted in
+        // chunks. Each Shot's price is its own; only this listing reads them.
+        const QUOTE_CHUNK = 150;
+        const chunks = [];
+        for (let i = 0; i < rows.length; i += QUOTE_CHUNK)
+            chunks.push(rows.slice(i, i + QUOTE_CHUNK).map(r => r.id));
+        const quote = projectId && rows.length
+            ? { items: (await Promise.all(chunks.map((shotIds) => desktop.get('/agent/shots/quote', { input: JSON.stringify({ projectId, shotIds }) })))).flatMap((q) => q.items) }
+            : null;
         let total = 0;
         let unpriced = 0;
         const shots = rows.map((s) => {
-            const q = shotQuote(s, byKey);
-            if (q.key == null || !byKey.has(q.key))
+            const q = quote?.items.find(i => i.shotId === s.id);
+            if (q?.credits == null)
                 unpriced += 1;
-            total += q.credits;
+            total += q?.credits ?? 0;
             return {
                 id: s.id,
                 code: s.code,
@@ -4806,15 +5460,11 @@ export const listShots = {
                 shot_size: s.shotSize,
                 camera: s.camera,
                 continues: s.continues,
-                credits: q.credits,
+                credits: q?.credits ?? null,
             };
         });
         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)}` : ''));
@@ -4829,14 +5479,14 @@ export const getShot = {
     async run(input, ctx) {
         const desktop = ctx.desktop();
         await desktop.requireCapability('shots', 'saved Shots');
+        // Prices come only from the desktop's quote; a 1.5.8 desktop has none.
+        await desktop.requireCapability('board-quote', 'Shot prices');
         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)]));
-        await loadDynamicPrice(ctx, byKey, shotCostKey(r.shot));
-        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}).`
+        const quote = await desktop.get('/agent/shots/quote', { input: JSON.stringify({ projectId: r.shot.projectId, shotIds: [r.shot.id] }) });
+        const q = quote.items[0];
+        return ok({ ...r.shot, credits: q.credits, quoteFingerprint: quote.fingerprint }, `"${r.shot.name || 'Untitled'}" — ${r.shot.model ?? 'no model set'}, ` +
+            (q.credits != null && !r.shot.blocked
+                ? `${fmtCredits(q.credits ?? 0)}.`
                 : `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}`);
@@ -4878,6 +5528,43 @@ export const splitShot = {
             `set it on each if the chop changed how long they run.`);
     },
 };
+export const splitTake = {
+    id: 'slates_split_take',
+    description: "A take founds its own Shot. The result (a take under `shotId`) moves to a NEW Shot whose recipe is the take's RECORDED one — the prompt, model, params and references it was actually made from, which may differ from what the source Shot says now. The new Shot lands directly after the source by default; the source keeps its other takes and its recipe untouched, and is never deleted when emptied. Script fields (line, speaker) start empty on the new row.",
+    input: z.object({
+        shotId: z.string().describe('The source Shot id, or its SHOT-A code.'),
+        assetId: z.string().describe('The take to move — an asset id or its IMG-A / VID-A code. Must be a take of `shotId`.'),
+        sceneId: z.string().uuid().optional().describe("Scene for the new Shot. Omitted = the source's scene."),
+        position: z.number().int().min(0).optional().describe('Frame position in that scene. Omitted = directly after the source.'),
+        name: z.string().optional().describe("The new Shot's name. Omitted = the take's label or the first 60 characters of its prompt."),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('takes', 'moving takes between Shots');
+        const r = await desktop.post('/agent/shots/split-take', input);
+        const unsaved = r.unsavedPaths?.length
+            ? ` ${r.unsavedPaths.length} recorded attachment(s) are not project assets and were not carried.`
+            : '';
+        return ok(r, `${r.shot?.code || 'A new Shot'} founded from that take, after ${r.source?.code || 'the source'}, with the take's recorded recipe.${unsaved}`);
+    },
+};
+export const refileTake = {
+    id: 'slates_refile_take',
+    description: 'Move a take (a result) from one Shot to another in the same project. Only the attribution moves: neither Shot\'s recipe changes, the asset stays where it is in Media, and a clip that a frame prefers keeps that role. `fromShotId` is a guard — the take moves only if it still hangs under that Shot (omit it to claim an unattributed result). An emptied Shot is kept, never deleted.',
+    input: z.object({
+        assetId: z.string().describe('The take — an asset id or its IMG-A / VID-A code.'),
+        fromShotId: z.string().nullable().optional().describe('The Shot it hangs under now (id or SHOT-A code). Omitted or null = an unattributed result.'),
+        toShotId: z.string().describe('The Shot to move it to (id or SHOT-A code).'),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('takes', 'moving takes between Shots');
+        const r = await desktop.post('/agent/shots/refile-take', input);
+        return ok(r, r.moved > 0
+            ? `Moved to ${r.shot?.code || 'that Shot'}.`
+            : `Nothing moved — that result is not under the Shot you named (or is already under ${r.shot?.code || 'the target'}).`);
+    },
+};
 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).",
@@ -4896,81 +5583,366 @@ export const mergeShots = {
             `${r.shot?.cuts ?? 1} cut(s), ${r.shot?.runtimeSeconds ?? 'no'} second(s).`);
     },
 };
+// ── The script (overhaul §4.9 "The script IS the shots", P2.4a) ───────
+// A scene owns ONE continuous text and a Shot with words is a RANGE of it;
+// the Shot's `line` mirrors the range. The agent edits the same document
+// through the same operations the Script page uses (rule 8). Offsets are
+// character positions into the scene's script as `slates_get_script` returns
+// it; read before you write, because every edit moves what follows it.
+export const getScript = {
+    id: 'slates_get_script',
+    description: "A scene's script — the ONE text its Shots' lines are ranges of — with every ranged Shot's [start, end) offsets and code. Read this before slates_edit_script or slates_make_shot_from_script: offsets are character positions into exactly this text. Text no Shot holds is unshot; a Shot listed by slates_list_shots but absent here has no words on the page yet. `rev` names this exact text and `revision` the whole script document: pass either to slates_edit_script so an edit measured on it is refused, not misplaced, if the words changed in between (1.6.0 desktops; older ones return neither).",
+    input: z.object({
+        sceneId: z.string().uuid().describe('The scene (slates_get_storyboard_with_frames lists them, each with its script).'),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('script', 'the Script page');
+        const r = await desktop.get('/agent/script', { sceneId: input.sceneId });
+        return ok(r, `${r.script.length} characters, ${r.shots.length} ranged Shot(s).`);
+    },
+};
+const variationSchema = z.object({
+    storyboardId: z.string().uuid(), expectedRevision: z.number().int().nonnegative(), name: z.string().min(1),
+    choices: z.array(z.object({ sectionId: z.string().uuid(), alternativeId: z.string().uuid() })),
+    arrangement: z.array(z.object({ sectionId: z.string().uuid(), alternativeId: z.string().uuid() })).optional(),
+    itemOverrides: z.array(z.object({ from: z.string().uuid(), to: z.string().uuid(), voice: z.enum(['keep', 'replace']) })).optional(),
+    assetOverrides: z.array(z.object({ from: z.string().min(1), to: z.string().min(1) })).optional(),
+    idempotencyKey: z.string().min(1).optional(),
+});
+export const previewScriptVariation = {
+    id: 'slates_preview_script_variation', description: 'Preview explicit version choices (one saved version per section) and independent ID-based reference replacements without writes or generation. An optional ordered arrangement supports repetition and omission. Returns composed requests, custom-prompt/reference warnings, a quote, and a plan marking each shot reuse (a finished take with matching inputs exists) or new. Inspect only the combinations you need.',
+    input: variationSchema,
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('script-documents', 'script documents and variations');
+        return ok(await ctx.desktop().post('/agent/script/variation-preview', await resolveVariationRefs(input, ctx)));
+    },
+};
+export const createScriptVariation = {
+    id: 'slates_create_script_variation', description: 'Materialize one reviewed variation as an independent Board with local shot IDs and lineage. Requires idempotencyKey; retry returns the same Board. Returns a quote through the normal request service. No media generation or implicit take reuse.',
+    input: variationSchema,
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('script-documents', 'script documents and variations');
+        return ok(await ctx.desktop().post('/agent/script/variation-create', await resolveVariationRefs(input, ctx)));
+    },
+};
+async function resolveVariationRefs(input, ctx) {
+    if (!input.assetOverrides?.length)
+        return input;
+    const { storyboard } = await ctx.desktop().get('/agent/storyboards/get', { id: input.storyboardId });
+    const assets = await resolveAssetRefs(ctx, storyboard.projectId, input.assetOverrides.flatMap(o => [o.from, o.to]));
+    return { ...input, assetOverrides: input.assetOverrides.map(o => ({ from: assets.get(o.from).id, to: assets.get(o.to).id })) };
+}
+export const getScriptUses = {
+    id: 'slates_get_script_uses',
+    description: 'Review each reused passage before updating it: current and proposed words, destination revision, and local-edit conflicts. Pass only explicitly selected non-conflicting uses to slates_update_script_section.',
+    input: z.object({ sectionId: z.string().uuid() }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('script-documents', 'script documents');
+        return ok(await ctx.desktop().get('/agent/script/uses', input));
+    },
+};
+export const getShotInputs = {
+    id: 'slates_get_shot_inputs',
+    description: 'Read take input history and compatible reusable media. Earlier and unknown inputs remain playable; they are never treated as a fresh match. No generation.',
+    input: z.object({ projectId: z.string().uuid(), shotId: z.string() }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('script-documents', 'script documents');
+        return ok(await ctx.desktop().get('/agent/shots/inputs', input));
+    },
+};
+export const reuseShotTake = {
+    id: 'slates_reuse_shot_take',
+    description: 'Explicitly link a take with matching saved request and recipe inputs to this shot. Keeps the original generation and independent shot recipe. Input changes are rechecked before reuse; costs no credits.',
+    input: z.object({ projectId: z.string().uuid(), shotId: z.string(), assetId: z.string().describe('Asset UUID or badge code from compatibleTakes.') }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('script-documents', 'script documents');
+        const assets = await resolveAssetRefs(ctx, input.projectId, [input.assetId]);
+        return ok(await ctx.desktop().post('/agent/shots/reuse-take', { ...input, assetId: assets.get(input.assetId).id }));
+    },
+};
+export const getScriptSections = {
+    id: 'slates_get_script_sections', description: 'Read free-named script sections, anchored fragments, saved versions and local-change state.',
+    input: z.object({ storyboardId: z.string().uuid() }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('script-documents', 'script documents');
+        const data = await ctx.desktop().get('/agent/script/sections', input);
+        return ok(data, 'Script sections read.');
+    },
+};
+const sectionInput = z.object({
+    storyboardId: z.string().uuid(), expectedRevision: z.number().int().min(0), action: z.enum(['create', 'alternative', 'choose', 'save', 'reuse', 'updateUses', 'rename', 'archive', 'tags']),
+    sectionId: z.string().uuid().optional(), alternativeId: z.string().uuid().optional(), parentId: z.string().uuid().optional(), label: z.string().optional(),
+    tags: z.array(z.string()).max(20).optional().describe('Free tags for action tags; replaces the list.'),
+    target: z.object({ sceneId: z.string().uuid(), at: z.number().int().min(0), expectedRevision: z.number().int().min(0) }).optional(),
+    uses: z.array(z.object({ sectionId: z.string().uuid(), expectedRevision: z.number().int().min(0) })).optional(),
+    fragments: z.array(z.object({ sceneId: z.string().uuid(), start: z.number().int().min(0), end: z.number().int().min(0) })).optional(),
+});
+export const changeScriptSection = {
+    id: 'slates_update_script_section', description: 'Create a free-named section from a selected passage, save the words now on the page as a new version (action alternative), save changes to the shown version (save) or choose another (choose), insert an editable copy (reuse), update unedited copies (updateUses), rename or archive a section or one version (alternativeId), or set its free tags. Choosing, archiving a section, reuse and updateUses first save the page\'s words and shot bindings into the version that was showing (the page is never unsaved; save remains for an explicit save), and only alternative starts a new version; archiving a section keeps its words, shots and media on the page. Uses the current document revision and never generates media. Partial crossing sections are refused.',
+    input: sectionInput,
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('script-documents', 'script documents');
+        const data = await ctx.desktop().post('/agent/script/sections', input);
+        return ok(data, 'Script section updated.');
+    },
+};
+export const getScriptSuggestions = {
+    id: 'slates_get_script_suggestions', description: 'Read suggested replacements on a script: pending ones first (stale when their words changed since), then recent accepted or dismissed ones.',
+    input: z.object({ storyboardId: z.string().uuid() }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('script-documents', 'script documents');
+        return ok(await ctx.desktop().get('/agent/script/suggestions', input), 'Script suggestions read.');
+    },
+};
+const suggestionInput = z.object({
+    storyboardId: z.string().uuid(), expectedRevision: z.number().int().min(0), action: z.enum(['create', 'accept', 'dismiss']),
+    suggestions: z.array(z.object({ sceneId: z.string().uuid(), start: z.number().int().min(0), end: z.number().int().min(0),
+        original: z.string().describe('The exact words now at start to end.'), replacement: z.string(), note: z.string().max(500).optional().describe('One line on why.') })).min(1).max(20).optional(),
+    suggestionId: z.string().uuid().optional(),
+});
+export const changeScriptSuggestions = {
+    id: 'slates_update_script_suggestions', description: 'Propose replacements for exact passages without editing the script (create), or accept or dismiss one. Use create when asked to suggest or improve a passage; the creator reviews and accepts it in the document. Each quotes the words it replaces; one whose words change later is stale and will not apply. Accepting is one undoable write. Never generates media.',
+    input: suggestionInput,
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('script-documents', 'script documents');
+        return ok(await ctx.desktop().post('/agent/script/suggestions', input), 'Script suggestions updated.');
+    },
+};
+const documentBlocks = z.array(z.object({
+    id: z.string().min(1), kind: z.enum(['paragraph', 'heading', 'direction']),
+    start: z.number().int().min(0), end: z.number().int().min(0), label: z.string().optional(), level: z.union([z.literal(2), z.literal(3)]).optional(),
+    marks: z.array(z.object({ start: z.number().int().min(0), end: z.number().int().min(0), type: z.enum(['strong', 'em']) })),
+}));
+export const getScriptDocument = {
+    id: 'slates_get_script_document',
+    description: 'Read the whole script document: scene strings, UTF-16 block/shot anchors, non-spoken headings/directions and a revision for safe writes. Formatting metadata contains no second copy of paragraph text.',
+    input: z.object({ storyboardId: z.string().uuid() }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('script-documents', 'script documents');
+        const data = await ctx.desktop().get('/agent/script/document', input);
+        return ok(data, 'Script document read.');
+    },
+};
+const writeScriptDocumentInput = z.object({
+    storyboardId: z.string().uuid(), expectedRevision: z.number().int().min(0),
+    edits: z.array(z.object({ sceneId: z.string().uuid(), at: z.number().int().min(0), removed: z.number().int().min(0), text: z.string() })),
+    structures: z.array(z.object({ sceneId: z.string().uuid(), blocks: documentBlocks })).optional(),
+    move: z.object({ sceneId: z.string().uuid(), blockId: z.string(), delta: z.union([z.literal(-1), z.literal(1)]) }).optional(),
+    makeShots: z.array(z.object({ sceneId: z.string().uuid(), start: z.number().int().min(0), end: z.number().int().min(0), waitingShotId: z.string().uuid().optional() })).optional(),
+    restoreRevision: z.number().int().min(0).optional(), ensureScene: z.boolean().optional(),
+    sceneAction: z.discriminatedUnion('kind', [z.object({ kind: z.literal('split'), sceneId: z.string().uuid(), at: z.number().int().min(0) }), z.object({ kind: z.literal('merge'), sceneId: z.string().uuid() })]).optional(),
+});
+export const writeScriptDocument = {
+    id: 'slates_update_script_document',
+    description: 'Apply ordered script edits and optional formatting in one revision-checked transaction. Read the document first. Stale writes are refused without replacing either author’s work. A move carries contained shot anchors; restoreRevision restores an existing text/structure revision. No generation side effect. ensureScene creates an empty scene only if needed.',
+    input: writeScriptDocumentInput,
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('script-documents', 'script documents');
+        const data = await ctx.desktop().post('/agent/script/document', input);
+        return ok(data, 'Script document updated.');
+    },
+};
+export const editScript = {
+    id: 'slates_edit_script',
+    description: "Edit a scene's script: ONE contiguous replacement — `removed` characters at `at` become `text` (insert: removed 0; delete: text ''). Every Shot's range follows the way comment anchors follow a document: text before a Shot moves it, text after leaves it, an edit inside grows or shrinks it, typing at its end extends it unless the text starts a new line, and deleting all of a Shot's words leaves it with no words and no place on the page. Every affected Shot's `line` changes at once — this IS editing the Shots. Read slates_get_script first; offsets are into that text. Pass its `rev` (or the document `revision` as `expectedRevision`): when the Script page or anything else changed the words since, the edit is refused ('the script changed since you read it', or SCRIPT_CONFLICT for a stale revision), and you re-read and measure again. The result carries the new `rev` and `revision` for a following edit.",
+    input: z.object({
+        sceneId: z.string().uuid(),
+        expectedRevision: z.number().int().nonnegative().optional().describe('The document `revision` slates_get_script or slates_get_script_document returned. The edit is refused if the document changed since.'),
+        at: z.number().int().min(0).describe('Character offset the replacement starts at.'),
+        removed: z.number().int().min(0).describe('How many characters to remove there (0 to insert).'),
+        text: z.string().describe("What goes in their place ('' to delete). A blank line (\\n\\n) separates paragraphs."),
+        rev: z.string().optional().describe('The `rev` slates_get_script (or the previous edit) returned. The edit is refused if the text changed since.'),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('script', 'the Script page');
+        const r = await desktop.post('/agent/script/edit', input);
+        return ok(r, `Script is now ${r.script.length} characters; every Shot's line follows.`);
+    },
+};
+export const makeShotFromScript = {
+    id: 'slates_make_shot_from_script',
+    description: "Do the ONE thing a selection of the script can mean, exactly as the Script page's popover does: Make shot when the selection touches no Shot; Split when it lies inside one Shot (the Shot keeps its first piece and its takes, every other piece becomes a new Shot after it); Extend when it crosses one Shot's edge; Merge when it spans several (the first takes the span — unshot text between them included, nothing deleted — the others give up their words: one holding a take (finished or generating), a prompt, a reference or a picture stays and waits for text; only a completely blank one is removed). Pass `waitingShotId` to give a Shot that has no words yet (made on the Board, split off a take) the selected text instead. `perParagraph: true` over several unshot paragraphs makes one Shot per paragraph. A new Shot is filed after every ranged Shot whose words start before it.",
+    input: z.object({
+        sceneId: z.string().uuid(),
+        start: z.number().int().min(0),
+        end: z.number().int().min(0),
+        waitingShotId: z.string().nullable().optional().describe('A Shot with no words (id or SHOT-A code) that should take the selection.'),
+        perParagraph: z.boolean().optional().describe('Over unshot text spanning several paragraphs: one Shot per paragraph.'),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('script', 'the Script page');
+        const r = await desktop.post('/agent/script/make-shot', input);
+        const kept = r.kept?.length ? ` ${r.kept.join(', ')} kept ${r.kept.length === 1 ? 'its takes and waits' : 'their takes and wait'} for text.` : '';
+        const removed = r.removed?.length ? ` ${r.removed.length} empty Shot(s) removed.` : '';
+        const made = r.shotIds ? `${r.shotIds.length} Shot(s) made, one per paragraph.` : `${r.action.label}: ${r.shot?.code || r.shotId || 'done'}.`;
+        return ok(r, `${made}${kept}${removed}`);
+    },
+};
+export const breakScriptIntoShots = {
+    id: 'slates_break_script_into_shots',
+    description: '"Break the script into shots": a Shot for every piece of text no Shot holds — one per paragraph — across a whole board, or one scene. Shots that already exist keep their words. This is the cut after the script is right; slates_paste_script is the step before it.',
+    input: z.object({
+        storyboardId: z.string().uuid().optional().describe('Every scene of this board.'),
+        sceneId: z.string().uuid().optional().describe('Only this scene.'),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('script', 'the Script page');
+        const r = await desktop.post('/agent/script/break', input);
+        return ok(r, `${r.shotIds.length} Shot(s) made from the unshot text.`);
+    },
+};
+export const splitScene = {
+    id: 'slates_split_scene',
+    description: "Open a scene at a heading line, the Notion way: the text from `lineEnd` on moves into a NEW scene directly after this one, with its Shots and their slots; the heading line [lineStart, lineEnd) itself is consumed and `name` becomes the new scene's name. Use slates_paste_script to do this for every SCENE / INT. / EXT. / # line of a pasted script at once.",
+    input: z.object({
+        sceneId: z.string().uuid(),
+        lineStart: z.number().int().min(0).describe('Offset where the heading line starts.'),
+        lineEnd: z.number().int().min(0).describe('Offset just past the heading line (the newline after it is consumed too).'),
+        name: z.string().nullable().optional().describe("The new scene's name. Omitted = 'Scene N'."),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('script', 'the Script page');
+        const r = await desktop.post('/agent/script/split-scene', input);
+        return ok(r, `Opened "${r.scene?.name ?? 'a scene'}" there; the text below moved into it.`);
+    },
+};
+export const mergeScene = {
+    id: 'slates_merge_scene',
+    description: "Join a scene to the one before it (Backspace in an emptied heading): the texts join with a blank line, every Shot keeps its words and its slot appends after the previous scene's. Only the scene row goes — no Shot does. Returns the offset in the joined script where this scene's text now starts.",
+    input: z.object({ sceneId: z.string().uuid() }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('script', 'the Script page');
+        const r = await desktop.post('/agent/script/merge-scene', input);
+        return ok(r, `Joined into "${r.scene?.name ?? 'the previous scene'}" at offset ${r.at}.`);
+    },
+};
+export const pasteScript = {
+    id: 'slates_paste_script',
+    description: "Dump a script in as TEXT, not Shots: the text lands in the scene's script (at its end by default), and lines reading `SCENE …`, `INT.` / `EXT.` / `I/E.` or `# Name` open scenes. No Shot is made — cutting is the writer's act or yours: slates_break_script_into_shots for one per paragraph, or slates_make_shot_from_script per selection. With no sceneId, a new scene at the end of the board takes the text (dropped again if the script opens with its own heading). Prefer this over slates_create_shot per paragraph: see the whole script, get it right, then cut it.",
+    input: z.object({
+        storyboardId: z.string().uuid().optional().describe('The board, when no scene is named.'),
+        sceneId: z.string().uuid().nullable().optional().describe('The scene to paste into. Omitted = a new scene at the end.'),
+        text: z.string().describe('The script. Blank lines separate paragraphs.'),
+        at: z.number().int().min(0).optional().describe("Offset in the scene's script to paste at. Omitted = the end."),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('script', 'the Script page');
+        const r = await desktop.post('/agent/script/paste', input);
+        return ok(r, `Pasted as text; the board now has ${r.scenes.length} scene(s). No Shot was made — break it into shots when it reads right.`);
+    },
+};
+/** The draft mode both quote ops accept: one picture per Shot in scope that has none. */
+const DRAFT_INPUT = z
+    .object({ model: z.enum(IMAGE_MODELS).optional().describe('The image model to draft on. Omit it for the default image model.') })
+    .optional();
 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.',
+    description: 'Preview the itemized prices the Generate panel shows for saved Shots. After explicit approval, pass confirm and the returned fingerprint. Changed recipes require a fresh price. Runs sequentially; after a timeout inspect generations instead of re-firing. Pass draft to generate previews instead: one picture for each Shot that has none, never saved to the Shot.',
     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.'),
+        shotIds: z.array(z.string()).min(1).max(20),
+        confirm: z.boolean().optional(),
+        fingerprint: z.string().optional(),
+        draft: DRAFT_INPUT.describe('Generate previews: pass {} to price ONE picture for each Shot in scope that has no picture, instead of each Shot recipe, at the chosen image model’s default settings. Works on a Shot with no model. No Shot row changes; the picture becomes a take of that Shot. Pass the same value when confirming.'),
     }),
     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)]));
-        await Promise.all(details.map((d) => loadDynamicPrice(ctx, byKey, shotCostKey(d))));
-        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.`);
+        // Prices come only from the desktop's quote; a 1.5.8 desktop has none.
+        await desktop.requireCapability('board-quote', 'Shot prices');
+        // Resolved first so a SHOT-A code fails here, not halfway through a billed run.
+        const details = await Promise.all(input.shotIds.map((id) => desktop.get('/agent/shots/get', { id })));
+        const quote = await desktop.get('/agent/shots/quote', {
+            input: JSON.stringify({ projectId: details[0].shot.projectId, shotIds: details.map((d) => d.shot.id), draft: input.draft }),
+        });
+        const total = quote.items.reduce((n, i) => n + (i.credits ?? 0), 0);
+        const largest = Math.max(0, ...quote.items.map((i) => i.credits ?? 0));
+        // ONE approval for the set, on the STATED total; a stale fingerprint is a
+        // changed recipe and never reaches generation.
+        if (!input.confirm || input.fingerprint !== quote.fingerprint) {
+            return ok({ ...quote, requires_confirm: true, total_credits: total, largest_single_credits: largest }, `TOTAL ${fmtCredits(total)} · largest ${fmtCredits(largest)}.\n` +
+                quote.items
+                    .map((i) => `${i.code ?? i.name}: ${i.credits == null ? 'unpriced' : fmtCredits(i.credits)}${i.blocked ? ` — ${i.blocked}` : ''}`)
+                    .join('\n') +
+                '\nGet approval for these prices, then pass their fingerprint with confirm: true.');
         }
-        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) {
+        return ok(await desktop.post('/agent/shots/batch-generate', {
+            shotIds: quote.items.map((i) => i.shotId),
+            fingerprint: quote.fingerprint,
+            draft: input.draft,
+        }));
+    },
+};
+export const quoteBoard = {
+    id: 'slates_get_board_quote',
+    description: 'Read the itemized prices the Generate panel shows for a board, scene or shot selection, optionally only missing results. No generation. Uses the desktop composer pricing source and returns a fingerprint for slates_generate_from_shots. Pass draft to price previews (one picture per Shot that has none).',
+    input: z.object({
+        projectId: z.string().uuid(),
+        storyboardId: z.string().uuid().optional(),
+        sceneId: z.string().uuid().optional(),
+        shotIds: z.array(z.string()).optional(),
+        missingOnly: z.boolean().optional(),
+        draft: DRAFT_INPUT.describe('Generate previews: pass {} to price one picture for each Shot in scope with no picture, instead of each Shot recipe.'),
+    }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('board-quote', 'the board prices');
+        return ok(await ctx.desktop().get('/agent/shots/quote', { input: JSON.stringify(input) }));
+    },
+};
+export const getBoardProgress = {
+    id: 'slates_get_board_progress',
+    description: 'Read per-shot spend from generation history, surviving take counts, running/failed counts and recorded-round progress. Deleted takes do not reduce spend.',
+    input: z.object({ projectId: z.string().uuid() }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('board-progress', 'board progress');
+        return ok(await ctx.desktop().get('/agent/shots/progress', input));
+    },
+};
+export const editCut = {
+    id: 'slates_edit_cut',
+    description: 'Read pending preferred-take changes, explicitly replace one clip, sync a board’s preferred clips, or build a cut in board order. Read changes first for the count. Swaps keep timeline starts and source timing when possible; shorter takes are visibly marked. Never changes a shot recipe or poster. Undo swaps with restore and the returned before snapshots; undo a build with undo-build and its clipIds/markerIds.',
+    input: z.object({
+        projectId: z.string().uuid(), timelineId: z.string().uuid().optional(),
+        action: z.enum(['changes', 'replace', 'sync', 'build', 'restore', 'undo-build']),
+        storyboardId: z.string().uuid().optional(),
+        clipId: z.string().uuid().optional(),
+        assetId: z.string().optional(),
+        before: z
+            .array(z
+            .object({
+            id: z.string().uuid(),
+            assetPath: z.string(),
+            assetId: z.string().nullable().optional(),
+            shotId: z.string().nullable().optional(),
+            thumbnailPath: z.string().optional(),
+            sourceDuration: z.number().positive(),
+            sourceFps: z.number().positive(),
+            sourceInFrame: z.number().int().min(0),
+            sourceOutFrame: z.number().int().positive(),
+            endFrame: z.number().int().positive(),
+            shortened: z.boolean().optional(),
+        })
+            .passthrough())
+            .optional()
+            .describe('Exact before snapshots returned by replace/sync, for restore.'),
+        clipIds: z.array(z.string().uuid()).optional(),
+        markerIds: z.array(z.string().uuid()).optional(),
+        skipPresent: z.boolean().optional().describe('build: add only Shots this cut does not already hold, so a repeated build appends nothing twice. Default appends the whole board.'),
+    }),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('cut-edit', 'editing a cut');
+        const refs = input.assetId ? await resolveAssetRefs(ctx, input.projectId, [input.assetId]) : new Map();
+        return ok(await ctx.desktop().post('/agent/timeline/cut', { ...input, assetId: input.assetId ? refs.get(input.assetId)?.id : undefined }));
+    },
+};
+export function resolveGuideTopic(topic) {
     const t = topic.trim().toLowerCase();
     if (SKILLS[t])
         return t;
@@ -4995,6 +5967,32 @@ function resolveGuideTopic(topic) {
     if (t === 'camera' || t === 'camera-moves' || t === 'camera moves' || t === 'shot-list' || t === 'shot list') {
         return 'slates-camera-language';
     }
+    // The cinematic-look catalogue: light, exposure, grade, what a lens does to the
+    // picture, imperfection. Above the model prefixes like the blocks before it;
+    // `camera` stays with camera-language, `lens` and `lighting` are look words.
+    if (t === 'cinematic' ||
+        t === 'cinematic-look' ||
+        t === 'cinematic look' ||
+        t === 'film-look' ||
+        t === 'film look' ||
+        t === 'look' ||
+        t === 'lighting' ||
+        t === 'light' ||
+        t === 'exposure' ||
+        t === 'grade' ||
+        t === 'grading' ||
+        t === 'color-grade' ||
+        t === 'colour-grade' ||
+        t === 'silhouette' ||
+        t === 'lens' ||
+        t === 'lenses' ||
+        t === 'realism' ||
+        t === 'natural-light' ||
+        t === 'natural light' ||
+        t === 'too-perfect' ||
+        t === 'imperfection') {
+        return 'slates-cinematic-look';
+    }
     if (t === 'blocking-to-prompt' || t === 'previs-prompt' || t === 'reference-video' || t === 'video-to-video' || t === 'v2v') {
         return 'slates-blocking-to-prompt';
     }
@@ -5014,7 +6012,7 @@ function resolveGuideTopic(topic) {
     }
     if (t.startsWith('nano-banana'))
         return 'slates-prompting-nano-banana-2';
-    if (t.startsWith('gpt-image') || t.startsWith('gpt image'))
+    if (t === 'sunburst' || t === 'flare' || t.startsWith('gpt-image') || t.startsWith('gpt image'))
         return 'slates-prompting-gpt-image-2-5';
     if (t.startsWith('flux'))
         return 'slates-prompting-flux-2-max';
@@ -5135,61 +6133,64 @@ export const getPromptingGuide = {
         // 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.'),
+        query: z.string().max(200).optional().describe('Keywords, section heading, or exact cinematic technique ID. Returns only the matching section or technique.'),
         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.'),
+        depth: z.enum(['card', 'index', 'section', 'full']).optional().describe('Default "card" is a short overview. "index" lists sections; query selects one section or technique; "full" explicitly returns the complete guide.'),
     }),
     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 content = input.query || input.depth === 'full'
+                ? appManualSections(input.query)
+                : 'App manual sections. Pass query to read a section, or depth "full" for the complete manual.\n\n' +
+                    guideSections(appManualSections()).map((s) => `- ${s.title}`).join('\n');
+            return { text: content, data: { topic: 'app-manual', bytes: Buffer.byteLength(content, 'utf8'), guide: content } };
         }
         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, depth: 'full', bytes: Buffer.byteLength(content, 'utf8') },
-        };
+        const depth = input.depth ?? 'card';
+        const guide = retrieveGuide(resolved, content, depth, input.query);
+        // Both fields carry the body: some native clients expose structured data only.
+        return { text: guide, data: { topic: resolved, depth, bytes: Buffer.byteLength(guide, 'utf8'), guide } };
     },
 };
 /**
  * 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".
+ * Both surfaces start with the shared core set. Search returns compact metadata;
+ * names/group returns exact schemas and replaces the optional selection.
  */
 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.',
+    // Worded to be true on both surfaces: the desktop agent must load an
+    // extended tool before calling it, while the MCP server lists every tool, so
+    // "missing from your list" never happens there by default.
+    description: 'Find Slates tools by task. query searches tool names and descriptions and returns a compact list. names returns up to five exact tools with their schemas; group returns a whole task group. Call the tools by their own names. If a tool you need is missing from your tool list, a names or group load adds it; a load replaces the previous optional selection, and query alone does not change it. Groups: ' + Object.entries(GROUP_SUMMARY).map(([g, s]) => `${g}: ${s}`).join('; '),
     input: z.object({
-        group: z.enum(['library', 'timeline', 'admin', 'blender']).describe('Which group to load.'),
-    }),
+        group: z.enum(['script', 'library', 'timeline', 'admin', 'blender']).optional(),
+        query: z.string().min(1).max(160).optional().describe('Search for a task such as generate image, create shot, or edit video.'),
+        names: z.array(z.string()).min(1).max(5).optional().describe('Exact operation names to load after discovery. Their permission annotations remain separate.'),
+    }).refine((v) => [v.group, v.query, v.names].filter(Boolean).length === 1, 'Pass exactly one of query, names, or group.'),
     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'));
+        if (input.query) {
+            const words = input.query.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+            const ranked = ALL_OPERATIONS.map((op) => ({ op, score: words.reduce((n, w) => n + (op.id.includes(w) ? 4 : op.description.toLowerCase().includes(w) ? 1 : 0), 0) }))
+                .filter((x) => x.score > 0).sort((a, b) => b.score - a.score).slice(0, 10);
+            const matches = ranked.map(({ op }) => ({ name: op.id, description: op.description.split(/(?<=\.)\s/)[0], billable: !!op.billable, annotations: op.annotations }));
+            return ok({ matches }, matches.map((o) => `${o.name}: ${o.description}`).join('\n') || 'No matching tools. Try another task description.');
+        }
+        const names = input.names ?? OPERATION_GROUPS[input.group];
+        const unknown = names.filter((id) => !ALL_OPERATIONS.some((op) => op.id === id));
+        if (unknown.length)
+            throw new Error(`Unknown operation(s): ${unknown.join(', ')}`);
+        const defs = toolDefinitions(ALL_OPERATIONS.filter((op) => names.includes(op.id)), { surface: 'mcp' });
+        return ok({ group: input.group, tools: defs }, `Loaded tools (call by name):\n${JSON.stringify(defs)}`);
     },
 };
 // ── Blender previs ──────────────────────────────────────────────
@@ -5348,6 +6349,9 @@ export const blenderRenderBlocking = {
 // ── Aggregation ─────────────────────────────────────────────────
 export const ALL_OPERATIONS = [
     getWorkspaceState,
+    getSelection,
+    getView,
+    setView,
     getMe,
     getCreditBalance,
     listAvailableModels,
@@ -5360,9 +6364,18 @@ export const ALL_OPERATIONS = [
     getAssetsBatch,
     getAssetVideoFrames,
     uploadReferenceImage,
+    saveExternalImage,
+    getChatGptStatus,
+    connectChatGpt,
+    generateChatGptImage,
     listFolders,
     createFolder,
     moveAssetsToFolder,
+    setAssetFavorite,
+    exportAssets,
+    listPins,
+    pinReferences,
+    unpinReference,
     moveAssetsToProject,
     copyAssetsToProject,
     moveEntityToProject,
@@ -5389,10 +6402,14 @@ export const ALL_OPERATIONS = [
     editImage,
     getGenerationStatus,
     listGenerations,
+    listTimelines,
+    saveTimeline,
+    exportCuts,
     getTimeline,
     addClipToTimeline,
     reorderClips,
     removeClip,
+    manageTimelineMarker,
     addTimelineTrack,
     updateTimelineTrack,
     removeTimelineTrack,
@@ -5403,6 +6420,8 @@ export const ALL_OPERATIONS = [
     updateProject,
     deleteProject,
     getProjectDirectory,
+    relocateProject,
+    undoRelocateProject,
     deleteAsset,
     renameFolder,
     deleteFolder,
@@ -5415,6 +6434,15 @@ export const ALL_OPERATIONS = [
     createStyle,
     updateStyle,
     deleteStyle,
+    listLibrary,
+    createLibraryItem,
+    updateLibraryItem,
+    deleteLibraryItem,
+    manageLibraryCategory,
+    copyLibraryItemToProject,
+    getTemplate,
+    exportTemplate,
+    importTemplate,
     updateStoryboard,
     deleteStoryboard,
     updateScene,
@@ -5433,9 +6461,34 @@ export const ALL_OPERATIONS = [
     // actually decided. They sit beside the writers, not with the spender.
     splitShot,
     mergeShots,
+    // A take founding its own Shot, or moving between Shots (P2.3).
+    splitTake,
+    refileTake,
+    // The script IS the shots (P2.4a): one text per scene, Shots as ranges of it.
+    getScript,
+    getScriptUses,
+    getShotInputs,
+    reuseShotTake,
+    previewScriptVariation,
+    createScriptVariation,
+    getScriptSections,
+    changeScriptSection,
+    getScriptSuggestions,
+    changeScriptSuggestions,
+    getScriptDocument,
+    writeScriptDocument,
+    editScript,
+    makeShotFromScript,
+    breakScriptIntoShots,
+    splitScene,
+    mergeScene,
+    pasteScript,
     listShots,
     getShot,
     generateFromShots,
+    quoteBoard,
+    getBoardProgress,
+    editCut,
     getPromptingGuide,
     loadTools,
     // ── Blender previs, LAST and deliberately ────────────────────────────
@@ -5482,5 +6535,5 @@ for (const op of ALL_OPERATIONS) {
         }
     }
 }
-export { toolDefinitions, toolDefinition, groupFor, tierFor, OPERATION_GROUPS, GROUP_SUMMARY } from './surface.js';
+export { toolDefinitions, toolDefinition, groupFor, tierFor, OPERATION_GROUPS, GROUP_SUMMARY, STARTUP_TOOL_IDS } from './surface.js';
 //# sourceMappingURL=index.js.map