@slatesvideo/shared 0.7.1 → 0.7.3

package/dist/operations/index.js

@@ -1,5 +1,6 @@
 import { MAX_IMAGE_VARIATIONS } from '../prompts/generation-policy.js';
-import { retrieveGuide, guideSections } from '../prompts/guide-retrieval.js';
+import { discoverGuides, guideCatalog } from '../prompts/guide-discovery.js';
+import { retrieveGuide } 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
@@ -13,11 +14,11 @@ import { MINIMAX_MAX_REFERENCE, minimaxMaxReferenceTokens, MODEL_CAPABILITIES, G
 //   - chooses its transport (cloud vs desktop) internally — callers
 //     don't need to know which side a given op talks to
 import { z } from 'zod';
-import { SlatesCloudClient } from '../clients/cloud.js';
+import { SlatesCloudClient, SlatesCloudHttpError } from '../clients/cloud.js';
 import { SlatesDesktopClient } from '../clients/desktop.js';
 import { BlenderBridgeClient, BLENDER_SETUP_HINT, RENDER_TIMEOUT_MS } from '../clients/blender.js';
 import { SKILLS } from '../skills/content.js';
-import { appManualSections } from '../manual/index.js';
+import { appManualIndex, appManualSections } from '../manual/index.js';
 // Reference-capacity prose is DERIVED, never hand-typed — root CLAUDE.md:
 // "never hand-type a fact an LLM will read". These helpers read MODEL_FACTS.
 import { multimodalRefSummary, multimodalRefModels, seedanceTaskIntentWords, 
@@ -59,10 +60,12 @@ import { SHOT_SIZE_BUCKETS, CAMERA_MOVE_BUCKETS, SPEECH_RATE, } from '../prompts
 // Annotations, tiers and the ONE schema renderer. Declared next door so this
 // module never hand-sets a hint or a tier per op: `annotate()` derives all four
 // from the id and the lockstep check re-derives them from the transport verbs.
-import { annotate, groupFor, tierFor, toolDefinitions, GROUP_SUMMARY, OPERATION_GROUPS, } from './surface.js';
+import { annotate, groupFor, tierFor, toolDefinitions, searchTools, GROUP_SUMMARY, OPERATION_GROUPS, } from './surface.js';
+// One factory for every default context, so per-connection caches can key on it.
+const defaultCloud = () => new SlatesCloudClient();
 export function defaultContext() {
     return {
-        cloud: () => new SlatesCloudClient(),
+        cloud: defaultCloud,
         desktop: () => new SlatesDesktopClient(),
     };
 }
@@ -127,7 +130,10 @@ export const DEVIATION_FACTOR = 1.2;
  * to find three wordings. Byte-stable (a template over a literal), so the
  * desktop's prompt-cached prefix is unaffected.
  */
-const CONFIRM_GATE_SENTENCE = `Cost above ${CONFIRM_CREDITS} credits returns requires_confirm — pass confirm=true after explicit user OK.`;
+// The consent half rides every generation tool because a host may drop the
+// server instructions: Codex CLI 0.159.1 passed none to the model (probes
+// 2026-09-30 and 2026-10-02), so a small spend had no approval rule in view.
+const CONFIRM_GATE_SENTENCE = `Show the user the estimate and wait for their OK before any generation, however small. Cost above ${CONFIRM_CREDITS} credits (and, on image and video, any attached reference) also returns requires_confirm — pass confirm=true only to relay that OK.`;
 // Declared HERE, above every op, because `slates_estimate_generation_cost`
 // renders them into its `duration` description at MODULE LOAD — a const
 // declared below the first schema that reads it is a temporal-dead-zone
@@ -216,6 +222,14 @@ function creditsFromDollars(dollars) {
 // sentence: it is repeated verbatim on seven ops, so every word costs seven
 // times, and `slates_get_generation_status` explains the polling itself.
 const BACKGROUND_DESCRIBE = 'Return generationId(s) now instead of blocking; poll slates_get_generation_status. Recommended for video.';
+// `folderId` on the generate and upload ops (1.6.1, decision 17 in second-brain
+// plans/2026-09-30-slates-manual-for-llms-1-6-1-decisions.md). The folder dot in Media means "new pictures go
+// here", the user's own generations and drops follow it, and so does an agent's: the DESKTOP resolves an absent
+// folderId to the folder chosen in the window, so every op and the Studio Agent get it at once.
+const FOLDER_DESCRIBE = "Folder the result lands in (slates_list_folders). Omit it to follow the folder chosen in the user's Slates window, else the project root; null is the root, on purpose.";
+const folderIdField = z.string().uuid().nullable().optional().describe(FOLDER_DESCRIBE);
+/** The `folderId` part of a generate or upload body: present only when the caller named one (null is the root). */
+const folderBody = (folderId) => (folderId === undefined ? {} : { folderId });
 // ── Vision QC pointers (the "quality-check with vision" rule, made structural) ──
 //
 // QUALITY-CHECK is a POST-condition, so it cannot be gated the way a
@@ -231,9 +245,9 @@ const BACKGROUND_DESCRIBE = 'Return generationId(s) now instead of blocking; pol
 const IMAGE_INLINE_REVIEW = 'The image is attached to this result — look at it against the brief before you describe it. ' +
     'Any claim about how it LOOKS must come from pixels you actually received (slates-vision-feedback-loop).';
 const VIDEO_REVIEW_POINTER = 'You have NOT seen this clip: call slates_get_asset_video_frames on the asset id above before ' +
-    'describing how it looks. A quality claim you cannot point to a tool result for is a REAL NUMBERS ONLY violation.';
+    'describing visible composition or identity. Sampled stills do not establish continuous motion, lip sync or sound; use actual playback through a capable host for those, or report them unreviewed.';
 const BACKGROUND_REVIEW_POINTER = 'When it completes, look at it before you describe it — slates_get_asset_image for images, ' +
-    'slates_get_asset_video_frames for video. For audio, audition the saved file; metadata alone does not establish voice similarity or delivery quality.';
+    'slates_get_asset_video_frames for video. For audio, audition the saved file only through a host that can receive/listen to audio; otherwise report it unreviewed. Metadata does not establish voice similarity or delivery quality.';
 // The image saved, but reading it back off disk failed (best-effort fetch). The
 // agent has an asset and NO pixels, which is the one state where a quality
 // claim would be pure invention — so this branch has to say so rather than
@@ -356,14 +370,95 @@ export const getSelection = {
         };
     },
 };
+// 1.6.1: what is ticked. Mirrors slate's `SELECTION_TARGETS` and `SELECTION_MODES` in `@shared/types/view`
+// (lockstep check 12), which this package cannot import.
+const SELECTION_TARGETS = ['media', 'board'];
+const SELECTION_MODES = ['replace', 'add', 'remove', 'clear', 'all'];
+/**
+ * SET what is selected, as the user's clicks do: the cards ticked in Media, the Shots ticked on the Board.
+ * Pairs with `slates_get_selection`, which reads it: "tick the shots with no clip, then price them" is this op
+ * and then the quote. The desktop applies it through the stores the grids write and answers with what SETTLED.
+ */
+export const setSelection = {
+    id: 'slates_set_selection',
+    description: "Tick or untick cards in Media or Shots on the Board, as clicks, Shift-click, Escape and Ctrl/Cmd+A do: replace makes the ids the whole selection, add and remove change only them, clear empties it, all ticks everything the tab shows (Media: the grid as filtered, folded rounds left out; Board: every Shot on the open board). Media needs its grid showing and the Board needs the Board or Script tab; slates_set_view switches. Ids are asset ids or badge codes (Media) or Shot ids or SHOT-A codes (Board). Answers with the selection as it settled and names any id it could not tick. slates_get_selection reads it back; what is selected is what the user means by 'these'.",
+    input: z
+        .object({
+        surface: z.enum(SELECTION_TARGETS),
+        mode: z.enum(SELECTION_MODES),
+        ids: z.array(z.string().min(1)).max(500).optional().describe('Asset ids or codes (media) or Shot ids or codes (board). Not used by clear or all.'),
+    })
+        .strict(),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('selection-set', 'setting what is selected');
+        if ((input.mode === 'add' || input.mode === 'remove') && !input.ids?.length)
+            throw new Error(`${input.mode} needs ids.`);
+        const r = await ctx.desktop().post('/agent/selection', input);
+        if (!r.selection)
+            return { text: `Nothing was changed (${r.reason ?? 'no answer'}).`, data: { selection: null } };
+        const where = r.selection.surface === 'media' ? 'Media' : 'the Board';
+        const named = (row) => (row.code ? (row.label ? `${row.code} — ${row.label}` : row.code) : row.id);
+        const notes = r.notes?.length ? ` Not applied: ${r.notes.join('; ')}.` : '';
+        return {
+            text: (r.selection.items.length ? `${r.selection.items.length} selected on ${where}: ${r.selection.items.map(named).join(', ')}.` : `Nothing is selected on ${where}.`) + notes,
+            data: { selection: r.selection, notes: r.notes ?? [] },
+        };
+    },
+};
 // 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'];
+// 1.6.1: what the user is looking at. Mirrors slate's `@shared/types/view` (lockstep check 12).
+const VIEW_BOARD_LEVELS = ['film', 'scenes', 'shot'];
+const VIEW_BOARD_FILTERS = ['all', 'with-clip', 'without-clip'];
+const VIEW_MEDIA_TABS = ['all', 'images', 'videos', 'audio'];
+const VIEW_SETTINGS_PANES = ['account', 'ai', 'storage', 'logs', 'general', 'keys'];
 /** What each dock section is called on screen. */
 const DOCK_SECTION_NAMES = { storyboards: 'Boards', library: 'Library', folders: 'Folders', pinned: 'Pinned' };
+/** 1.6.1: what the user is looking at, in the words on screen. Empty parts are left out. */
+const describeLooking = (v) => {
+    const parts = [];
+    if (!v.projectId)
+        parts.push('Home (the project list) is showing.');
+    if (v.board?.id) {
+        const level = v.board.level === 'film' ? 'Film' : v.board.level === 'shot' ? 'Shot' : 'Scenes';
+        const filter = v.board.filter === 'with-clip' ? ', Filter: With a linked clip' : v.board.filter === 'without-clip' ? ', Filter: Without a linked clip' : '';
+        parts.push(`The open board is ${v.board.id} (View: ${level}${filter}).`);
+    }
+    if (v.library?.categoryId)
+        parts.push(`A Library page is in Media's place (category ${v.library.categoryId}).`);
+    else if (v.media) {
+        const narrowing = [
+            v.media.unfiledOnly && 'No folder only',
+            v.media.search && `search "${v.media.search}"`,
+            v.media.favoritesOnly && 'favorites only',
+            v.media.linkedOnly && 'only with linked videos',
+        ].filter(Boolean);
+        parts.push(`Media's tab is ${v.media.tab}${narrowing.length ? `, narrowed to ${narrowing.join(', ')}` : ''}.`);
+    }
+    if (v.media?.folderId)
+        parts.push(`Folder ${v.media.folderId} is chosen: new pictures land in it.`);
+    if (v.viewer?.assetId)
+        parts.push(`The picture viewer is open on ${v.viewer.assetId}.`);
+    if (v.compare?.open)
+        parts.push(`Compare is open on ${v.compare.assetIds.length} items.`);
+    if (v.animatic?.open)
+        parts.push('The animatic is up.');
+    if (v.settings?.open)
+        parts.push('Settings is open.');
+    if (v.composer && !v.composer.open)
+        parts.push("The prompt box is hidden (the ' key shows it).");
+    if (v.script?.panelShotId)
+        parts.push(`The Script page's shot panel is open on Shot ${v.script.panelShotId}.`);
+    if (v.layers?.length)
+        parts.push(`Open over the page: ${v.layers.join(', ')}.`);
+    if (v.notes?.length)
+        parts.push(`Not applied: ${v.notes.join('; ')}.`);
+    return parts.length ? ' ' + parts.join(' ') : '';
+};
 const describeView = (v) => {
     const where = v.cut.full
         ? 'filling the workspace'
@@ -380,7 +475,8 @@ const describeView = (v) => {
     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)'}.` : ''));
+        (v.script ? ` The Script page shows ${v.script.details ? 'Words + shots (each shot\'s picture beside its words)' : 'Words (the words alone)'}.` : '') +
+        describeLooking(v));
 };
 /**
  * How the Slates window is ARRANGED right now — which lens is showing, where
@@ -389,7 +485,7 @@ const describeView = (v) => {
  */
 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.",
+    description: "What the user is looking at in Slates: Home or a project, the tab (Media, Script or Board), the open board and its View and Filter, Media's tab, chosen folder and narrowing, a Library page, the picture viewer, Compare, the animatic, Settings, whether the prompt box is hidden, the timeline and the side panels, and any dialog or menu open over the page. Read it before telling the user where to click.",
     input: z.object({}).strict(),
     async run(_input, ctx) {
         await ctx.desktop().requireCapability('view', 'the window layout');
@@ -417,9 +513,10 @@ export const getView = {
  */
 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.",
+    description: "Change what the user is looking at, as their own clicks would: open a project or go Home, switch tab, open a board, jump to a scene, set the Board's View and Filter, set Media's tab, folder and narrowing, jump to a card in Media, open a Library page, the picture viewer, Compare, the animatic or Settings on a pane, show or hide the prompt box, open or park the timeline or switch the cut on it, open a Shot's panel on Script. Only the fields you name change; the app clamps sizes, answers with what it settled on, and names any field it could not apply. A project change is applied alone (it restores that project's own view). Use it when the user asks you to show or open something, not to answer a question they can see for themselves.",
     input: z
         .object({
+        projectId: z.string().nullable().optional().describe('Open this project, or null for Home. Applied alone.'),
         lens: z.enum(VIEW_LENSES).optional().describe('Which tab the centre shows.'),
         cut: z
             .object({
@@ -429,8 +526,9 @@ export const setView = {
                 .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.'),
+            height: z.number().optional().describe("The bottom band's height in px."),
+            width: z.number().optional().describe("The side column's width in px."),
+            timelineId: z.string().optional().describe('The named cut to show on the timeline (slates_list_timelines).'),
         })
             .strict()
             .optional(),
@@ -456,21 +554,67 @@ export const setView = {
             .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.'),
+            details: z.boolean().optional().describe("Words + shots (true): each shot's picture beside its words on the Script page. Words (false): the words alone."),
+            textScale: z.number().optional().describe("The page's text size; 1 is the default."),
+            panelShotId: z.string().nullable().optional().describe("Open this Shot's details panel on the Script page (it binds the Shot to the prompt box, as a click does); null closes it."),
         })
             .strict()
             .optional()
             .describe('The Script page.'),
+        board: z
+            .object({
+            id: z.string().optional().describe('Open this board (on Board and Script).'),
+            sceneId: z.string().optional().describe('Scroll the Board to this scene.'),
+            level: z.enum(VIEW_BOARD_LEVELS).optional().describe('View: Film (posters), Scenes (the working card) or Shot (each card open).'),
+            cardWidth: z.number().optional().describe('Card width in px, anywhere between the stops.'),
+            filter: z.enum(VIEW_BOARD_FILTERS).optional().describe('Filter: every shot, only shots with a linked clip, or only shots without one.'),
+            linkedClips: z.boolean().optional().describe('Show the row of linked clips under each shot.'),
+            scriptFollowsDrag: z.boolean().optional().describe("The board menu's Script follows a drag."),
+            collapsedSceneIds: z.array(z.string()).optional().describe('Every scene to fold; a scene not named unfolds.'),
+        })
+            .strict()
+            .optional(),
+        media: z
+            .object({
+            tab: z.enum(VIEW_MEDIA_TABS).optional(),
+            folderId: z.string().nullable().optional().describe('Choose this folder (new pictures land in it), or null for all media.'),
+            unfiledOnly: z.boolean().optional().describe('Show only media in no folder.'),
+            search: z.string().optional().describe("Media's search box (matches prompts)."),
+            favoritesOnly: z.boolean().optional(),
+            linkedOnly: z.boolean().optional().describe('Images tab: only pictures with a linked video.'),
+            rounds: z.boolean().optional().describe('Group by generation.'),
+            cardSize: z.number().optional().describe('Card size in px.'),
+            revealAssetId: z.string().optional().describe('Jump to this card in Media, undoing only what hides it (the app says what it changed).'),
+        })
+            .strict()
+            .optional(),
+        library: z.object({ categoryId: z.string().nullable() }).strict().optional().describe("Open a Library category's page in Media's place; null goes back to the grid."),
+        viewer: z.object({ assetId: z.string().nullable() }).strict().optional().describe('Open the picture viewer on a picture; null closes it.'),
+        compare: z
+            .object({ open: z.boolean().optional(), assetIds: z.array(z.string()).max(4).optional().describe('The compare set, two to four items.') })
+            .strict()
+            .optional(),
+        animatic: z.object({ open: z.boolean(), fromShotId: z.string().optional() }).strict().optional().describe('Play the board as a rough cut from a Shot (the Board or Script tab must be showing).'),
+        settings: z.object({ open: z.boolean(), pane: z.enum(VIEW_SETTINGS_PANES).optional() }).strict().optional().describe('Open Settings, on a pane (ai is AI tools, keys is API keys).'),
+        composer: z.object({ open: z.boolean() }).strict().optional().describe('Show or hide the prompt box.'),
     })
         .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.');
+            throw new Error('Name at least one field to change, e.g. lens, board, media, viewer or settings.');
         }
+        // The 1.6.1 fields need a desktop that knows them; an older one would drop them without a word.
+        const LOOKING = ['projectId', 'board', 'media', 'library', 'viewer', 'compare', 'animatic', 'settings', 'composer'];
+        const widened = LOOKING.some((k) => input[k] !== undefined) ||
+            input.cut?.timelineId !== undefined ||
+            input.script?.textScale !== undefined ||
+            input.script?.panelShotId !== undefined;
+        if (widened)
+            await ctx.desktop().requireCapability('view-v2', 'showing and opening things in the window');
         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 } };
+            return { text: r.reason ? `Nothing was changed (${r.reason}).` : 'Nothing was changed.', 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
@@ -479,6 +623,288 @@ export const setView = {
         return { text: describeView(r.view) + noFolds, data: { view: r.view } };
     },
 };
+/**
+ * SHOW AND POINT (1.6.1). The manual's pictures and a ring around a live control, so an agent can
+ * answer "where is it?" with the thing itself instead of a paragraph. Neither changes the project or
+ * the view. The pictures come from the INSTALLED app (it ships them), so they show the user's version;
+ * the public URL is for a client that renders only links. Decisions 13-16 in second-brain
+ * plans/2026-09-30-slates-manual-for-llms-1-6-1-decisions.md.
+ */
+export const getManualPicture = {
+    id: 'slates_get_manual_picture',
+    description: 'A picture of a Slates screen from the app manual, with numbered callouts and their legend, taken from the version the user runs. Pass the picture id the manual names (app-manual sections show "Picture `id`"); no id lists them. Show one when the user cannot find something or asks what a screen looks like; never unasked. When the control is on screen, slates_highlight_control points at the real thing instead.',
+    input: z
+        .object({ id: z.string().min(1).optional().describe('Picture id from the manual, e.g. "window-overview". Omit to list.') })
+        .strict(),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('manual-pictures', "the manual's pictures");
+        if (!input.id) {
+            const r = await ctx.desktop().get('/agent/manual/pictures');
+            return ok(r, r.pictures.length ? r.pictures.map((p) => `${p.id}: ${p.title}`).join('\n') : 'This Slates ships no manual pictures.');
+        }
+        const p = await ctx.desktop().get('/agent/manual/picture', { id: input.id });
+        const legend = p.callouts.length ? '\n' + p.callouts.map((c) => `${c.n}. ${c.name} (${c.target})`).join('\n') : '';
+        return {
+            text: `${p.title} (Slates ${p.appVersion}). Link: ${p.url}${legend}`,
+            images: [{ data: p.data, mimeType: p.mimeType }],
+            data: { id: p.id, title: p.title, url: p.url, appVersion: p.appVersion, callouts: p.callouts },
+        };
+    },
+};
+export const highlightControl = {
+    id: 'slates_highlight_control',
+    description: "Point at a control in the user's Slates window: a grey outline around it for a few seconds, with your caption beside it. It clicks nothing and never changes the view; the user's next click clears it. Target ids are listed at the end of each app-manual surface section (\"controls you can point at\"), or pass list:true to get every id with whether it is on screen now. shown:false means it is not on screen: tell the user the way there, or open that view with slates_set_view if they want you to.",
+    input: z
+        .object({
+        target: z.string().min(1).optional().describe('Control id, e.g. "shell.titlebar.search".'),
+        caption: z.string().max(140).optional().describe('A few words shown beside it, e.g. "Click here to open the timeline".'),
+        list: z.boolean().optional().describe('Return every target id, its on-screen name, where it is, and whether it is on screen now.'),
+    })
+        .strict(),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('ui-pointer', 'pointing at controls');
+        if (input.list || !input.target) {
+            const r = await ctx.desktop().get('/agent/ui/targets');
+            const on = r.targets.filter((t) => t.onScreen);
+            return ok(r, `${r.targets.length} controls; on screen now: ${on.map((t) => `${t.id} (${t.name})`).join(', ') || 'none reported'}.`);
+        }
+        const r = await ctx.desktop().post('/agent/ui/highlight', {
+            target: input.target,
+            caption: input.caption,
+        });
+        return ok(r, r.shown
+            ? `Pointing at ${r.name} (${r.where}) in the user's window.`
+            : `${r.name} is not on screen (${r.reason ?? 'not shown'}). It is at: ${r.where}. Tell the user the way there, or open that view with slates_set_view if they ask you to.`);
+    },
+};
+const COMPOSER_ROLES = Object.keys(ATTACHMENT_ROLE_DESCRIPTION);
+function describeComposer(r) {
+    const lines = [];
+    const where = r.bound
+        ? `editing Shot ${r.bound.code ?? r.bound.shotId}${r.bound.name ? ` "${r.bound.name}"` : ''} (every change is saved to it)`
+        : r.draftFrom
+            ? `a draft from ${r.draftFrom.code ?? r.draftFrom.assetId}`
+            : 'an unsaved draft';
+    lines.push(`Prompt box (${r.open ? 'showing' : 'hidden'}), ${r.lane} lane, ${r.model.label}${r.destination === 'chatgpt' ? ' (ChatGPT)' : ''}; ${where}.`);
+    lines.push(`Words (${r.prompt.length}${r.promptMax ? `/${r.promptMax}` : ''}): ${r.prompt ? JSON.stringify(r.prompt) : 'none'}`);
+    if (r.params.length)
+        lines.push(`Settings: ${r.params.map((p) => `${p.label} ${p.value || '(none)'}`).join(' · ')}`);
+    if (r.tiles.length) {
+        const tiles = r.tiles.map((t) => `${t.badge} ${t.code ?? t.name}${t.role ? ` (${t.role})` : t.token ? ` (${t.token})` : ''}${t.voice ? ' voice' : ''}${t.sent ? '' : ' NOT SENT'}`);
+        lines.push(`References: ${tiles.join(', ')}`);
+    }
+    const ti = r.toolInputs;
+    if (ti && r.tool === 'lip-sync')
+        lines.push(`Lip Sync source: ${ti.sourceAssetId ?? 'none'}${ti.sourceType ? ` (${ti.sourceType})` : ''}; Speech Text: ${ti.speechText ? JSON.stringify(ti.speechText) : 'none'}`);
+    if (ti && r.tool === 'motion-transfer')
+        lines.push(`Motion: ${ti.drivingVideoAssetId ?? 'none'}; Character: ${ti.characterImageAssetId ?? 'none'}`);
+    if (r.composedPrompt !== r.prompt)
+        lines.push(`Sent as: ${JSON.stringify(r.composedPrompt)}`);
+    if (r.unresolved.length)
+        lines.push(`Match nothing (sent as plain words): ${r.unresolved.join(', ')}`);
+    if (r.dangling.length)
+        lines.push(`Point past what is sent: ${r.dangling.join(', ')}`);
+    if (r.notice)
+        lines.push(`Notice line: ${r.notice.text}`);
+    lines.push(`Button: ${r.generate}.${r.running ? ` ${r.running} generating.` : ''}`);
+    return lines.join('\n');
+}
+export const getComposer = {
+    id: 'slates_get_composer',
+    description: "What the prompt box holds right now, as the user sees it: the lane and model, whether it is editing a Shot or a draft, the words, every setting with the values it offers, each reference tile with its number, role and whether the model's limit leaves it out, the exact text the model receives (See what gets sent), mentions that match nothing, the notice line, and the Generate button's price. Read it before telling the user what a press will do, or before staging with slates_set_composer.",
+    input: z.object({}).strict(),
+    async run(_input, ctx) {
+        await ctx.desktop().requireCapability('composer', 'reading the prompt box');
+        const r = await ctx.desktop().get('/agent/composer');
+        if (!r.report)
+            return { text: r.reason ?? 'The prompt box did not answer.', data: { report: null } };
+        return { text: describeComposer(r.report), data: r.report };
+    },
+};
+export const setComposer = {
+    id: 'slates_set_composer',
+    description: "Stage a request in the user's prompt box, as their own clicks would, and leave it for them to press Generate: edit a Shot in it or stop, clear or restore the draft, reuse a result's prompt, edit a clip, pick the lane and model, write the words, attach pictures, clips or audio with roles, re-file or remove them, set settings and the voice, fill Lip Sync or Motion Control's inputs. It never generates and never spends; the answer is the box as it settled (the same report as slates_get_composer) plus a line for anything it could not apply and why. Use it when the user wants a setup ready to look at; to generate yourself, quote with slates_estimate_generation_cost and use the generate ops.",
+    input: z
+        .object({
+        projectId: z.string().uuid().optional().describe('The project you expect the box to be in; refused if another is open.'),
+        bindShotId: z
+            .string()
+            .min(1)
+            .nullable()
+            .optional()
+            .describe('Edit this Shot in the box (id or code; every change is saved to it); null stops editing and brings the draft back.'),
+        clear: z.boolean().optional().describe('Empty the unsaved draft; restoreDraft undoes it. Not while a Shot is bound.'),
+        restoreDraft: z.boolean().optional().describe('Put back the draft that Clear, Reuse prompt or Edit with AI replaced (they swap).'),
+        restoreSetup: z.boolean().optional().describe('On a bound Shot, swap back the setup Continue replaced (writes the Shot; again swaps back).'),
+        fromAssetId: z.string().min(1).optional().describe("Reuse prompt: this result's recipe replaces the box (id or code)."),
+        editSourceAssetId: z.string().min(1).optional().describe('Edit with AI: this clip becomes the canvas and the box starts clean.'),
+        lane: z.enum(['image', 'video', 'audio']).optional().describe('The Image / Video / Audio tab; it lands on the last model used there.'),
+        model: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('A model id (slates_list_available_models), `<id>::face` for a face route, `chatgpt`, `lip-sync` or `motion-transfer`.'),
+        prompt: z.string().optional().describe('Replaces the words. @name and #name attach what they name, as typing does.'),
+        addMentions: z
+            .array(z.string().regex(/^[@#]\S+$/))
+            .optional()
+            .describe('@name / #name added at the end of the words (slates_list_library gives each item its mention).'),
+        attach: z
+            .array(z.object({ assetId: z.string().min(1), role: z.enum(COMPOSER_ROLES).optional() }).strict())
+            .optional()
+            .describe('Pictures, clips or audio from the project (id or code). A picture with no role goes in as a dropped one does; a clip is a video-reference, audio an audio-reference.'),
+        detach: z
+            .array(z.string().min(1))
+            .optional()
+            .describe("Take these out of the box: asset ids or codes, or a character's id to drop the voice her @mention brought."),
+        setRole: z
+            .array(z.object({ assetId: z.string().min(1), role: z.enum(COMPOSER_ROLES) }).strict())
+            .optional()
+            .describe("Re-file pictures already in the box, as a tile's role menu does."),
+        params: z
+            .record(z.union([z.string(), z.number(), z.boolean()]))
+            .optional()
+            .describe('Settings by id, each to a value it offers (slates_get_composer lists both), applied after the model.'),
+        voice: z
+            .union([
+            z.object({ presetId: z.string().min(1) }).strict(),
+            z.object({ clipAssetId: z.string().min(1) }).strict(),
+            z.object({ description: z.string().min(1) }).strict(),
+        ])
+            .optional()
+            .describe('The voice on a voice model: a preset (slates_list_voices), an audio clip in the project, or described in words.'),
+        tool: z
+            .object({
+            sourceAssetId: z.string().min(1).nullable().optional().describe('Lip Sync: the picture or clip with the face; null clears it.'),
+            speechText: z.string().max(120).optional().describe('Lip Sync, Text to speech: the words spoken (Speech Text).'),
+            drivingVideoAssetId: z.string().min(1).nullable().optional().describe('Motion Control: the clip whose motion is copied (Motion).'),
+            characterImageAssetId: z.string().min(1).nullable().optional().describe('Motion Control: the picture to animate (Character).'),
+        })
+            .strict()
+            .optional()
+            .describe('Lip Sync and Motion Control inputs (pick model lip-sync or motion-transfer first). An uploaded audio file is only the user.'),
+    })
+        .strict(),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('composer', 'staging the prompt box');
+        if (Object.keys(input).filter((k) => k !== 'projectId').length === 0) {
+            throw new Error('Name at least one change, e.g. model, prompt, attach or params. To read the box, use slates_get_composer.');
+        }
+        const r = await ctx.desktop().post('/agent/composer', input);
+        if (!r.report)
+            return { text: `Nothing was staged (${r.reason ?? 'no answer'}).`, data: { report: null } };
+        const skipped = r.skipped?.length ? `\nNot applied:\n- ${r.skipped.join('\n- ')}` : '';
+        return { text: `${describeComposer(r.report)}${skipped}`, data: { report: r.report, skipped: r.skipped ?? [] } };
+    },
+};
+/**
+ * AGENT PARITY (1.6.1): what a user could do in the window and an agent could not. Each calls a desktop
+ * route that runs the window's own function (`slate/src/main/agent/routes-parity.ts`). Plan step 5b,
+ * second-brain plans/2026-09-30-slates-manual-for-llms-1-6-1.md.
+ */
+export const reorderFolders = {
+    id: 'slates_reorder_folders',
+    description: "Reorder the Folders section of the left dock, as dragging a row does. Pass folder ids in the new order; ones you leave out keep their order after them.",
+    input: z.object({ projectId: z.string().uuid(), folderIds: z.array(z.string().min(1)).min(1) }).strict(),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('reorder', 'reordering folders and pins');
+        return ok(await ctx.desktop().post('/agent/folders/reorder', input));
+    },
+};
+export const reorderPins = {
+    id: 'slates_reorder_pins',
+    description: "Reorder the Pinned section of the left dock, as dragging a pin does. Pass the pinned images (UUIDs or badge codes) in the new order; ones you leave out keep their order after them.",
+    input: z.object({ projectId: z.string().uuid(), assetIds: z.array(z.string().min(1)).min(1) }).strict(),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('reorder', 'reordering folders and pins');
+        const resolved = await resolveAssetRefs(ctx, input.projectId, input.assetIds);
+        return ok(await ctx.desktop().post('/agent/pins/reorder', { projectId: input.projectId, assetIds: input.assetIds.map((r) => resolved.get(r).id) }));
+    },
+};
+export const getUsage = {
+    id: 'slates_get_usage',
+    description: 'What Settings → Account → Usage shows: estimated spend across every project for this month (default), the last 7 days or all time, the image and video counts, video seconds and the models spent on most.',
+    input: z.object({ period: z.enum(['week', 'month', 'all']).optional() }).strict(),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('usage', 'usage');
+        return ok(await ctx.desktop().get('/agent/usage', { period: input.period ?? 'month' }));
+    },
+};
+export const getAppSettings = {
+    id: 'slates_get_app_settings',
+    description: "The app's own settings an agent may read: the app version, the projects folder, which tab a never-opened project lands on (newProjectLens), whether ChatGPT images is on, and (from Slates 1.6.1) who does the Studio Agent's thinking (studioAgentHost: slates, codex or claude) with each host's model and thinking level ('' is its default). Never keys or sign-in.",
+    input: z.object({}).strict(),
+    async run(_input, ctx) {
+        await ctx.desktop().requireCapability('app-settings', 'app settings');
+        return ok(await ctx.desktop().get('/agent/app-settings'));
+    },
+};
+const HOST_KEYS = ['studioAgentHost', 'studioAgentCodexModel', 'studioAgentCodexEffort', 'studioAgentClaudeModel', 'studioAgentClaudeEffort'];
+export const setAppSettings = {
+    id: 'slates_set_app_settings',
+    description: "Change an app setting the user asked you to: newProjectLens (the tab a never-opened project lands on: media, script or board), chatGptImagesEnabled (Settings → AI tools → ChatGPT images), or who does the Studio Agent's thinking: studioAgentHost (slates, codex for the user's own Codex on their ChatGPT plan, claude for their own Claude Code on their Claude plan) and each host's model and thinking level, ids from the host's own list or '' for its default. The projects folder, keys and sign-in are the user's to change.",
+    input: z
+        .object({
+        newProjectLens: z.enum(['media', 'script', 'board']).optional(),
+        chatGptImagesEnabled: z.boolean().optional(),
+        studioAgentHost: z.enum(['slates', 'codex', 'claude']).optional(),
+        studioAgentCodexModel: z.string().max(120).optional(),
+        studioAgentCodexEffort: z.string().max(120).optional(),
+        studioAgentClaudeModel: z.string().max(120).optional(),
+        studioAgentClaudeEffort: z.string().max(120).optional(),
+    })
+        .strict(),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('app-settings', 'app settings');
+        // An older desktop has the route but not these keys: ask it by capability, so it says "update Slates".
+        if (HOST_KEYS.some((key) => input[key] !== undefined)) {
+            await ctx.desktop().requireCapability('agent-host', "choosing who does the Studio Agent's thinking");
+        }
+        return ok(await ctx.desktop().post('/agent/app-settings', input));
+    },
+};
+export const getAsset = {
+    id: 'slates_get_asset',
+    description: 'One asset in full (UUID or badge code): its recorded prompt, model, settings and inputs, its source picture and linked clips, and how many clips and board shots use it. slates_list_assets rows are compact; read this before reusing or explaining one card.',
+    input: z.object({ projectId: z.string().uuid(), assetId: z.string().min(1) }).strict(),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('asset-detail', 'reading one asset in full');
+        const id = (await resolveAssetRefs(ctx, input.projectId, [input.assetId])).get(input.assetId).id;
+        return ok(await ctx.desktop().get('/agent/assets/get', { id }));
+    },
+};
+export const linkAssetSource = {
+    id: 'slates_link_asset_source',
+    description: "Link a clip to the picture it came from, as the clip card's Link video to image does (it adds a link; a clip can have several), or pass imageAssetId null to unlink it from every picture. UUIDs or badge codes.",
+    input: z
+        .object({ projectId: z.string().uuid(), assetId: z.string().min(1).describe('The clip.'), imageAssetId: z.string().min(1).nullable().describe('The picture, or null to unlink.') })
+        .strict(),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('asset-link', 'linking a clip to its picture');
+        const refs = [input.assetId, ...(input.imageAssetId ? [input.imageAssetId] : [])];
+        const resolved = await resolveAssetRefs(ctx, input.projectId, refs);
+        return ok(await ctx.desktop().post('/agent/assets/link-source', {
+            assetId: resolved.get(input.assetId).id,
+            imageAssetId: input.imageAssetId ? resolved.get(input.imageAssetId).id : null,
+        }));
+    },
+};
+export const extractVideoFrame = {
+    id: 'slates_extract_video_frame',
+    description: "Save one frame of a clip as a new picture in Media, as the clip card's camera does: at 'first', 'last' (default 'first') or a second. Free. The usual continuity move: extract a clip's last frame and use it as the next clip's first frame.",
+    input: z
+        .object({
+        projectId: z.string().uuid(),
+        assetId: z.string().min(1).describe('The clip, UUID or badge code.'),
+        at: z.union([z.enum(['first', 'last']), z.number().min(0)]).optional(),
+    })
+        .strict(),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('frame-extract', 'extracting a frame');
+        const id = (await resolveAssetRefs(ctx, input.projectId, [input.assetId])).get(input.assetId).id;
+        return ok(await ctx.desktop().post('/agent/assets/extract-frame', { assetId: id, at: input.at ?? 'first' }));
+    },
+};
 export const getMe = {
     id: 'slates_get_me',
     description: 'Identity, license tier, and credit balance for the connected Slates account.',
@@ -539,8 +965,8 @@ export const VIDEO_MODELS = [
     'kling-v3.0-std',
     'kling-v3.0-pro',
     'kling-v3.0-omni',
-    'veo-3.1-fast',
-    'veo-3.1-standard',
+    // Veo 3.1 Fast and Standard were retired on 2026-10-02 (Eric). The server
+    // keeps their keys for older desktops only; nothing here offers them.
     'seedance-2',
     // Seedance 2.5 is the DEFAULT video model (Eric, 2026-09-13): 30s takes, 30
     // image references, audio-only references, up to 1080p (2026-08-24). 2.0 stays
@@ -565,8 +991,8 @@ export const VIDEO_MODELS = [
     '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).
+    // cheapest 1080p second with sound included, free native audio at every tier,
+    // the only row reaching 1440p, and clips up to 20s.
     // Pro is the fidelity seat and is NOT a superset: shorter ladder (no
     // 1440p/4K), shorter clips (6/8/10 only) and ~1/3 dearer.
     //
@@ -688,7 +1114,7 @@ function editClipBounds(model) {
 const EDIT_VIDEO_RESOLUTIONS = videoResolutionUnion(['seedance-2.5-edit']);
 export const estimateGenerationCost = {
     id: 'slates_estimate_generation_cost',
-    description: 'Quote credits before any generate_* op. Accepts the same base model ids and parameters as generation, or an exact registry cost key. Pairs with the confirm gate.',
+    description: 'Quote credits before any generate_* op. Accepts the generation model ids and parameters (edit seats other than Kling, lip-sync and motion-transfer engines need an exact registry cost key), or an exact registry cost key. Pairs with the confirm gate.',
     input: z.object({
         model: z.string().describe('Base model id as passed to the generate op (e.g. "seedance-2", "kling-v3.0-std", "nano-banana-2") or an exact registry cost key ("nano-banana-2-2k", "seedance-2-1080p-8s")'),
         quantity: z.number().int().min(1).max(10).optional().describe('Number of generations (default 1)'),
@@ -706,8 +1132,8 @@ export const estimateGenerationCost = {
         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. 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.'),
+        aspectRatio: z.string().optional().describe('GPT Image only: 1:1, 4:3 and 3:4 cost more than 16:9.'),
+        sound: z.boolean().optional().describe('Kling 3.0: the audio flag changes the cost key. Omitted means sound on, as generation bills it; pass false to price a silent take. Kling 4K keys include audio.'),
         seedanceFace: z.boolean().optional().describe('Seedance AI-face route (pricier key).'),
         seedanceRealFace: z.boolean().optional().describe('Seedance consented real-face route (premium key).'),
         videoRefSeconds: z.number().nonnegative().optional().describe('Combined reference-video seconds, measured from the clips.'),
@@ -1094,7 +1520,7 @@ export const getAssetsBatch = {
 };
 export const getAssetVideoFrames = {
     id: 'slates_get_asset_video_frames',
-    description: 'Extract N evenly-spaced keyframes from a video asset and return them inline as base64 JPEGs. This is the "see the video" path — LLMs can\'t consume video natively, so frames are the next best thing. Default 3 frames (start / middle / end). Bump to 5-8 for longer clips or when motion is the whole story. Use this before writing a motion-transfer prompt, a lip-sync refinement, or any iteration on a video clip. Response carries the asset\'s code (e.g. VID-V3) + label — name them when discussing the clip with the user.',
+    description: 'Extract evenly-spaced sampled still frames from a video asset and return them inline as JPEGs. Inspect visible appearance, composition and identity before revising a prompt. Stills do not verify continuous motion, timing, lip sync or sound; actual playback through a capable host is needed for those claims. Default 3 samples; count can request more. The response includes the asset code and label; use them when discussing the clip.',
     input: z.object({
         id: z.string().uuid(),
         count: z.number().int().min(1).max(8).optional().describe('Number of frames to extract. Default 3.'),
@@ -1149,10 +1575,13 @@ export const generateChatGptImage = {
     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() }),
+        referenceAssetIds: z.array(z.string().min(1)).optional(), background: z.boolean().optional(), folderId: folderIdField }),
     async run(input, ctx) {
         const desktop = ctx.desktop();
         await desktop.requireCapability('chatgpt-image-generation', 'ChatGPT image generation');
+        // A desktop before the folder rule ignores folderId and files at the root.
+        if (input.folderId !== undefined)
+            await desktop.requireCapability('media-folder', 'choosing the folder a result lands in');
         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),
@@ -1203,17 +1632,22 @@ export const uploadReferenceImage = {
             .enum(['image', 'video', 'audio'])
             .optional()
             .describe('Asset kind for a filePath import — "image" (default), "video", or "audio". A dataUrl is always an image.'),
+        folderId: folderIdField,
     })
         .refine((d) => !!d.filePath !== !!d.dataUrl, {
         message: 'Pass exactly one of filePath or dataUrl',
     }),
     async run(input, ctx) {
         const desktop = ctx.desktop();
+        // A desktop before the folder rule ignores folderId and files at the root.
+        if (input.folderId !== undefined)
+            await desktop.requireCapability('media-folder', 'choosing the folder a result lands in');
         if (input.filePath) {
             const r = await desktop.post('/agent/assets/upload', {
                 projectId: input.projectId,
                 filePath: input.filePath,
                 type: input.type ?? 'image',
+                ...folderBody(input.folderId),
             });
             return ok(r);
         }
@@ -1223,6 +1657,7 @@ export const uploadReferenceImage = {
         const r = await desktop.post('/agent/assets/upload-base64', {
             projectId: input.projectId,
             dataUrl: input.dataUrl,
+            ...folderBody(input.folderId),
         });
         return ok(r);
     },
@@ -1761,19 +2196,21 @@ const LEGACY_DESKTOP_IMAGE_BATCH = 4;
 export const generateImage = {
     id: 'slates_generate_image',
     billable: true,
-    description: 'Generate an image via Slates credits.\n' +
-        // GENERATED from MODEL_FACTS — the hand-typed model list that stood here
-        // was a third copy of the routing doctrine, and it had already gone stale
-        // (it still described nano-banana-2-lite by a capability the param owns).
-        `${describeRouting('image')}\n` +
-        'Full table: the slates-model-selection skill. ' +
-        'Pass projectId to save into a Slates project (asset appears live in the desktop UI). All models except nano-banana-2 REQUIRE projectId (no headless path). REQUIRED before calling: read the slates-cost-discipline skill (and the model\'s slates-prompting-* skill). You MUST pass aspectRatio and resolution explicitly (the server returns requires_clarification when missing — defaults waste credits). ' +
+    description: 
+    // Rules first: Claude Code keeps only the first 2,048 characters of a tool
+    // description, and the generated roster below runs past that cut.
+    'Generate an image via Slates credits. Pass projectId to save into a Slates project (asset appears live in the desktop UI). All models except nano-banana-2 REQUIRE projectId (no headless path). You MUST pass aspectRatio (the server returns requires_clarification when missing); resolution defaults to the model\'s own. ' +
         CONFIRM_GATE_SENTENCE +
-        ' MCP/CLI generation always charges credits. No skills installed? Call slates_get_prompting_guide with the model\'s topic and \'slates-cost-discipline\' first. ' +
+        ' MCP/CLI generation always charges credits. The estimate returns the model\'s prompting card; load its slates-prompting-* guide with slates_get_prompting_guide for anything the card leaves out. ' +
         // GENERATED from the skill file's own never-use list -- the one piece of
         // prompting doctrine that is ALWAYS in context, because the agent has
         // demonstrably skipped the call that would have taught it.
-        describeBannedTokens('image'),
+        describeBannedTokens('image') +
+        // GENERATED from MODEL_FACTS — the hand-typed model list that stood here
+        // was a third copy of the routing doctrine, and it had already gone stale
+        // (it still described nano-banana-2-lite by a capability the param owns).
+        `\n${describeRouting('image')}\n` +
+        'Full table: the slates-model-selection skill.',
     input: z.object({
         prompt: z.string().min(1).max(4000),
         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.`),
@@ -1787,8 +2224,12 @@ export const generateImage = {
         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),
         confirm: z.boolean().optional().describe('Set true to bypass the confirm gate.'),
+        folderId: z.string().uuid().nullable().optional().describe(`${FOLDER_DESCRIBE} Needs projectId.`),
     }),
     async run(input, ctx) {
+        // A desktop before the folder rule ignores folderId and files at the root.
+        if (input.folderId !== undefined)
+            await ctx.desktop().requireCapability('media-folder', 'choosing the folder a result lands in');
         // Clarification gate: aspectRatio + resolution must be deliberate.
         // Mirrors the cost confirm gate — defaults silently wasted credits
         // (1:1 when user wanted 16:9, 4k when 1k would have done). The LLM
@@ -1970,6 +2411,7 @@ export const generateImage = {
                 count: input.count ?? 1,
                 ...(isGptImageModel(imageModel) ? { gptQuality: input.quality ?? DEFAULT_GPT_QUALITY, gptBackground: input.backgroundMode } : {}),
                 ...(referenceAssetIds.length > 0 ? { referenceAssetIds } : {}),
+                ...folderBody(input.folderId),
                 background: input.background,
             });
             // Partial multi-image failure: the desktop attaches an error message
@@ -2043,7 +2485,7 @@ export const generateImage = {
             };
         }
         // /proxy/generate kicks off a credit-aware job and returns a jobId
-        // for fal/Veo (async providers). We poll /proxy/jobs/{jobId} until
+        // for fal (async providers). We poll /proxy/jobs/{jobId} until
         // the status is `completed` or `failed`, then fetch each image URL
         // and inline as base64 so the calling LLM sees the pixels.
         // The fal endpoint differs by mode: bare model id for text-to-image,
@@ -2156,7 +2598,7 @@ const LEGACY_EDIT_REFERENCE_MODELS = ['nano-banana-2', 'nano-banana-2-lite', 'na
 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 ' + 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\'.',
+    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. Use slates-edit-and-iterate for missing edit craft; reuse current guidance already in context.',
     input: z.object({
         projectId: z.string().uuid(),
         sourceAssetId: z.string().uuid().describe('Image asset to edit. Must exist in the project.'),
@@ -2282,6 +2724,105 @@ export const editImage = {
         };
     },
 };
+/**
+ * The picture viewer's EXTRACT (its Cells tab): a 2x2 or 3x3 grid picture, cells cropped out and re-rendered
+ * at full resolution, each as its own new picture. BILLABLE, and priced by the DESKTOP: its quote is the
+ * `imageCost` the viewer's Extract button prints, for this seat, rung and cell count, so the price an agent
+ * is shown cannot differ from the button's. The confirm gate is every billable op's: above CONFIRM_CREDITS
+ * with no `confirm`, the op answers with the price and the exact prompt, and spends nothing.
+ */
+/** The seats the viewer's Cells box offers. Mirrors slate's `GRID_EXTRACT_MODELS` (`shared/prompts/storyboard-grids.ts`), which this package cannot import. */
+const GRID_EXTRACT_SEATS = ['nano-banana-2', 'flux-2-max', 'seedream-5-lite'];
+export const extractGridCells = {
+    id: 'slates_extract_grid_cells',
+    billable: true,
+    description: "Pull cells out of a 2x2 or 3x3 grid picture, as the picture viewer's Cells tab does: each named cell is cropped and re-rendered at full resolution as its own NEW picture (the grid is untouched). Name cells as they read on screen, row number then column letter: 1A top-left, 2C second row third column. Default seat " +
+        toolModelFor('grid-extract') +
+        " (the grid-extract tool seat, what the viewer opens on); resolution and aspect ratio default as the viewer does (the seat's own rung, the ratio nearest the grid's shape). prompt adds words to every cell; on the default seat @name and #look in it attach their pictures, and referenceAssetIds adds pictures, as in the viewer. " +
+        CONFIRM_GATE_SENTENCE +
+        " The confirm answer carries the price the viewer's Extract button prints and the exact prompt that will be sent.",
+    input: z.object({
+        projectId: z.string().uuid(),
+        assetId: z.string().min(1).describe('The grid picture — UUID or badge code. Must be a 2x2 or 3x3 grid.'),
+        cells: z.array(z.string().regex(/^[1-3][A-Ca-c]$/, 'a cell is its row number then column letter, e.g. 1A')).min(1).max(9).describe('Cells to extract, e.g. ["1A","2C"].'),
+        model: zEnum(GRID_EXTRACT_SEATS).optional(),
+        resolution: z.enum(['1k', '2k', '3k', '4k']).optional().describe("Default and ceiling are the seat's own, as in the viewer."),
+        aspectRatio: z.string().optional().describe("Output aspect ratio, one the seat offers. Default: the ratio nearest the grid's own shape."),
+        prompt: z.string().max(2500).optional().describe('Words for every cell (what the shot is). On the default seat @name and #look attach their pictures; the crop is image 1.'),
+        referenceAssetIds: z.array(z.string()).max(13).optional().describe('Pictures added beside the crop (default seat only), UUIDs or badge codes.'),
+        confirm: z.boolean().optional().describe('Set true to bypass the confirm gate after explicit user OK.'),
+        background: z.boolean().optional().describe(BACKGROUND_DESCRIBE),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('grid-extract', 'extracting grid cells');
+        if (input.background)
+            await desktop.requireCapability('background-generation', 'background generation');
+        const refs = await resolveAssetRefs(ctx, input.projectId, [input.assetId, ...(input.referenceAssetIds ?? [])]);
+        const grid = refs.get(input.assetId);
+        const request = {
+            projectId: input.projectId,
+            assetId: grid.id,
+            cells: input.cells.map((c) => c.toUpperCase()),
+            model: input.model,
+            resolution: input.resolution,
+            aspectRatio: input.aspectRatio,
+            prompt: input.prompt,
+            referenceAssetIds: input.referenceAssetIds?.map((r) => refs.get(r).id),
+        };
+        // The desktop prices it: the viewer's own `imageCost`, for this seat, rung and cell count. The desktop also
+        // refuses what the viewer would (not a grid, a cell the grid lacks, a seat it does not offer) before any spend.
+        const quote = await desktop.get('/agent/generation/extract-quote', { request: JSON.stringify(request) });
+        const gridName = grid.code ?? grid.id;
+        if (quote.credits > CONFIRM_CREDITS && !input.confirm) {
+            return ok({
+                requires_confirm: true,
+                estimated_credits: quote.credits,
+                estimated_cents: quote.credits,
+                cells: quote.cells,
+                model: quote.model,
+                resolution: quote.resolution,
+                aspectRatio: quote.aspectRatio,
+                credits_per_cell: quote.creditsPerCell,
+                prompt_sent: quote.prompt,
+                ...(quote.notes.length ? { notes: quote.notes } : {}),
+                message: `Cost: ${fmtCredits(quote.credits)} to extract ${quote.cells.length} cell${quote.cells.length === 1 ? '' : 's'} (${quote.cells.join(', ')}) of ${gridName} with ${quote.modelLabel} at ${quote.resolution}, ${fmtCredits(quote.creditsPerCell)} each. ` +
+                    (quote.notes.length ? `${quote.notes.join('. ')}. ` : '') +
+                    `Re-call with confirm=true after the user explicitly OKs the spend. When discussing with the user, refer to the grid by its code (matches the gallery badge).`,
+            });
+        }
+        const result = await desktop.post('/agent/generation/extract-cells', { ...request, background: input.background });
+        if (result.background) {
+            return backgroundSubmitted(`extraction of ${quote.cells.join(', ')} from ${gridName}`, result.generationIds ?? [], {
+                projectId: input.projectId,
+                gridAssetId: grid.id,
+                cells: quote.cells,
+                model: quote.model,
+                cost_credits: quote.credits,
+            });
+        }
+        const assets = result.assets ?? [];
+        if (assets.length === 0)
+            throw new Error(result.error ?? 'Extraction failed');
+        const codes = assets.map((a) => a.code ?? a.id).join(', ');
+        const partial = result.success === false ? ` Only ${assets.length} of ${quote.cells.length} cells came back; the rest failed (slates_list_generations shows why).` : '';
+        return {
+            text: `Extracted ${assets.length} cell${assets.length === 1 ? '' : 's'} (${quote.cells.join(', ')}) of ${gridName} as ${codes} via ${quote.modelLabel} at ${quote.resolution}, ${fmtCredits(quote.credits)}.${partial} ` +
+                BACKGROUND_REVIEW_POINTER,
+            data: {
+                projectId: input.projectId,
+                gridAssetId: grid.id,
+                cells: quote.cells,
+                model: quote.model,
+                resolution: quote.resolution,
+                aspectRatio: quote.aspectRatio,
+                cost_credits: quote.credits,
+                assets,
+                generationIds: result.generationIds,
+            },
+        };
+    },
+};
 // ── Generate video ──────────────────────────────────────────────
 //
 // VIDEO_MODELS and the capability-derived param vocabulary are declared near the
@@ -2301,10 +2842,9 @@ export const editImage = {
  * same teaching `requires_clarification` shape as every other gate in this op,
  * rather than a raw Zod error the agent has to guess its way out of.
  *
- * `promptMode` matters: Veo's reference-to-video endpoint is 8s only, declared
- * as `duration.modeOverrides.ingredients`. Free reference images with no
- * first/last frame IS ingredients mode — the same condition
- * `buildFalVeoRequest` uses to pick the ref2v endpoint.
+ * `promptMode` matters for any row that declares `duration.modeOverrides.ingredients`
+ * (retired Veo's reference-to-video endpoint was 8s only). Free reference images
+ * with no first/last frame IS ingredients mode.
  */
 function assertVideoCapabilities(input) {
     const freeRefs = (input.ingredientAssetIds?.length ?? 0) +
@@ -2333,7 +2873,6 @@ function assertVideoCapabilities(input) {
 // shape (verified against /api/agent/models):
 //   Kling: kling-v3-{standard|pro|omni}-{N}s — note the user-facing
 //     model id `kling-v3.0-std` maps to registry key `kling-v3-standard`.
-//   Veo:   veo-3.1-{fast|standard}[-4k]-{N}s[-audio]
 //   Seedance: seedance-2-{res}-{N}s (BytePlus ModelArk, sole provider). The
 //     cost key encodes resolution (480p/720p/1080p/4k) — price scales with
 //     resolution, so the key MUST carry it or the pre-flight quote is wrong.
@@ -2399,29 +2938,21 @@ export function videoCostKey(input) {
         }
         return `${input.model}${face}-${res}-${input.duration}s`;
     }
-    if (input.model.startsWith('veo')) {
-        const is4k = input.videoResolution === '4k';
-        const audio = input.sound !== false; // default audio on for Veo
-        const parts = [input.model];
-        if (is4k)
-            parts.push('4k');
-        parts.push(`${input.duration}s`);
-        if (audio)
-            parts.push('audio');
-        return parts.join('-');
-    }
     if (input.model.startsWith('kling-v3.0')) {
         // Mirrors klingCreditKey() in slate/src/shared/pricing.ts. Kling native 4K
         // bills flat-rate keys: std/pro/omni all get a `-4k` tier key, and omni-pro
         // shares kling-v3-omni-4k (the o3/4k endpoint has one flat rate, audio
         // included). At 1080p AUDIO IS A KEY DIMENSION (credits = COGS × markup,
-        // locked 2026-07-05): sound → `-audio` variant. Kling sound defaults OFF.
+        // locked 2026-07-05): sound → `-audio` variant. An OMITTED sound is ON: the
+        // desktop agent route sends `sound ?? true` and bills the audio key, so a
+        // quote that read omitted as silent under-quoted every default Kling take
+        // (21 credits quoted, 32 billed at std 5s; found 2026-10-02).
         const tier = KLING_TIER_MAP[input.model] ?? input.model;
         if (input.videoResolution === '4k') {
             const tier4k = tier === 'kling-v3-omni-pro' ? 'kling-v3-omni' : tier;
             return `${tier4k}-4k-${input.duration}s`;
         }
-        return `${tier}-${input.duration}s${input.sound === true ? '-audio' : ''}`;
+        return `${tier}-${input.duration}s${input.sound !== false ? '-audio' : ''}`;
     }
     if (input.model === 'omni-flash') {
         // Mirrors omniFlashCreditKey() in slate/src/shared/pricing.ts — flat 720p
@@ -2546,13 +3077,19 @@ function resolveVideoModel(raw) {
     // so a pasted `minimax-h3-768p-10s-ref2` resolves instead of erroring. The
     // number it carries is K (images PAST the free five), so it is converted back
     // to a TOTAL before anything can re-surcharge it.
+    // The free allowance differs per row (H3 five, H3 Max four), so the total is
+    // computed once the model is known, in `withRefTotal`; reading `out.model`
+    // here read the placeholder and gave every row five.
     const ref = /-ref(\d+)\b/.exec(s);
-    if (ref) {
-        out.referenceImages =
-            (MINIMAX_FREE_REF_IMAGES_BY_MODEL[out.model] ?? MINIMAX_FREE_REF_IMAGES) +
-                parseInt(ref[1], 10);
+    const paidRefs = ref ? parseInt(ref[1], 10) : null;
+    if (ref)
         s = s.replace(/-ref(\d+)\b/, '');
-    }
+    const withRefTotal = (resolved) => {
+        if (paidRefs !== null) {
+            resolved.referenceImages = (MINIMAX_FREE_REF_IMAGES_BY_MODEL[resolved.model] ?? MINIMAX_FREE_REF_IMAGES) + paidRefs;
+        }
+        return resolved;
+    };
     // The RESOLUTION vocabulary is GENERATED from MODEL_CAPABILITIES — the
     // hand-typed list that stood here went stale the day 768p and 2k shipped.
     const resRe = new RegExp(`-(${VIDEO_RESOLUTION_VOCAB.join('|')})\\b`);
@@ -2578,7 +3115,7 @@ function resolveVideoModel(raw) {
     const direct = VIDEO_MODELS.find((m) => m === s);
     if (direct) {
         out.model = direct;
-        return out;
+        return withRefTotal(out);
     }
     const aliases = {
         'kling-v3-standard': 'kling-v3.0-std',
@@ -2600,8 +3137,6 @@ function resolveVideoModel(raw) {
         'seedance-2-5': 'seedance-2.5',
         'seedance2.5': 'seedance-2.5',
         seedance: 'seedance-2',
-        'veo-3.1': 'veo-3.1-fast',
-        'veo-3': 'veo-3.1-fast',
         'gemini-omni-flash': 'omni-flash',
         'gemini-omni-flash-preview': 'omni-flash',
         'omni-flash-preview': 'omni-flash',
@@ -2626,7 +3161,7 @@ function resolveVideoModel(raw) {
     };
     if (aliases[s]) {
         out.model = aliases[s];
-        return out;
+        return withRefTotal(out);
     }
     return null;
 }
@@ -2682,11 +3217,11 @@ const VIDEO_MODEL_GUIDES = [
 export const generateVideo = {
     id: 'slates_generate_video',
     billable: true,
-    description: 'Generate video via Slates credits. REQUIRED before calling: read slates-model-selection (the routing doctrine), slates-cost-discipline, and the matching per-model prompting skill (' +
+    description: 'Generate video via Slates credits. Choose the model with slates-model-selection. Video models prompt very differently: the estimate returns the chosen model\'s prompting card, and its full guide (' +
         VIDEO_MODEL_GUIDES +
-        ') — video models prompt very differently; load them via slates_get_prompting_guide if no skill files are installed. Read slates-content-policy when the scene involves conflict, creatures, crowds, destruction, weapons, or young characters. projectId, aspectRatio, and duration are required (requires_clarification otherwise). ' +
+        ') covers modes the card leaves out, via slates_get_prompting_guide. Read slates-content-policy when the scene involves conflict, creatures, crowds, destruction, weapons, or young characters. projectId, aspectRatio, and duration are required (requires_clarification otherwise). ' +
         CONFIRM_GATE_SENTENCE +
-        ' Image-to-video via firstFrameAssetId; first+last frames = Veo/Seedance only; ingredients via ingredientAssetIds (Kling Omni / Seedance). Asset params take UUIDs or badge codes ("IMG-A8"). ' +
+        ' Image-to-video via firstFrameAssetId; first+last frames on every model except Omni Flash; ingredients via ingredientAssetIds (Kling Omni, Seedance, Omni Flash, H3 and H3 Max; Kling Std/Pro only with a first frame). Asset params take UUIDs or badge codes ("IMG-A8"). ' +
         // GENERATED from the skill's own slop-token list. Always in context on both
         // surfaces, so it survives an agent that skips slates_get_prompting_guide.
         describeBannedTokens('video'),
@@ -2706,7 +3241,7 @@ export const generateVideo = {
             `Full table: the slates-model-selection skill. Each model's legal aspect ratios, durations and ` +
             `resolutions are in those params' own descriptions — read them there, not from memory. ` +
             `For per-call cost, call slates_estimate_generation_cost.`),
-        projectId: z.string().uuid().optional().describe('Save into this Slates project. Strongly recommended — the desktop UI shows a progress card live and the asset appears when complete.'),
+        projectId: z.string().uuid().optional().describe('Save into this Slates project. Required — the desktop UI shows a progress card live and the asset appears when complete.'),
         // 🚨 THESE THREE DESCRIPTIONS ARE GENERATED FROM `MODEL_CAPABILITIES`.
         // Never hand-write a ratio, resolution or duration into them again — every
         // one of the hand-written claims that stood here had drifted, and an
@@ -2723,7 +3258,7 @@ export const generateVideo = {
         // demand, by the one session that needs it. If you are about to explain
         // WHY here, you are writing the skill in the wrong file.
         firstFrameAssetId: z.string().optional().describe('Starting frame for image-to-video (UUID or badge code, resolved at call time).'),
-        lastFrameAssetId: z.string().optional().describe('Ending frame. Veo and Seedance only; pairs with firstFrameAssetId.'),
+        lastFrameAssetId: z.string().optional().describe('Ending frame; every model except Omni Flash. Pairs with firstFrameAssetId.'),
         ingredientAssetIds: z.array(z.string()).max(30).optional().describe(
         // Caps DERIVED from MODEL_CAPABILITIES — the hand-typed list omitted
         // kling-v3.0-omni-pro entirely and read as if 7 were an Omni Flash-only rule.
@@ -2738,21 +3273,25 @@ export const generateVideo = {
         // The capacity sentences are DERIVED from MODEL_FACTS (see
         // multimodalRefSummary) rather than hand-typed, so a cap change in one
         // place cannot leave a stale number in a description an LLM reads.
-        videoReferenceAssetIds: z.array(z.string()).optional().describe(`Reference VIDEOS, cited in the prompt as "video 1", "video 2"… in the order given. ${multimodalRefModels().join(' / ')} only; per-model caps are on audioReferenceAssetIds. Billing switches to the vref key (input+output seconds) — pass videoReferenceSecondsEach. Over the cap is REFUSED, never trimmed.`),
+        videoReferenceAssetIds: z.array(z.string()).optional().describe(`Reference VIDEOS, cited in the prompt as "video 1", "video 2"… in the order given. ${multimodalRefModels().join(' / ')} only; per-model caps are on audioReferenceAssetIds. On Seedance, billing switches to the vref key (input+output seconds) — pass videoReferenceSecondsEach. Over the cap is REFUSED, never trimmed.`),
         videoReferenceSecondsEach: z.array(z.number()).optional().describe('REQUIRED with videoReferenceAssetIds, same order and length: each clip\'s duration in seconds. Feeds the vref cost key; the server re-probes and corrects an understated value upward.'),
-        audioReferenceAssetIds: z.array(z.string()).optional().describe(`Reference AUDIO, cited as "audio 1", "audio 2"… in the order given. ${multimodalRefModels().join(' / ')} only. No billing surcharge. ${multimodalRefModels().map(multimodalRefSummary).join(' ')}`),
+        audioReferenceAssetIds: z.array(z.string()).optional().describe(`Reference AUDIO, cited as "audio 1", "audio 2"… in the order given. ${multimodalRefModels().join(' / ')} only. No surcharge on Seedance; on H3 Max, audio counts toward the reference-token pool. ${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: 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.'),
+        sound: z.boolean().optional().describe('Kling (every tier) and LTX: sound on (default) or silent (false); Kling bills audio as its own key. Seedance, Omni Flash and H3 always generate audio.'),
+        audioLanguage: z.enum(['EN', 'ZH', 'JA', 'KO', 'ES']).optional().describe('Any Kling model with sound on — language for dialogue.'),
+        generateMusic: z.boolean().optional().describe('Any Kling model with sound on — 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. Real-person 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, about 1.4x the AI-face price (about 2x faceless) — quote it first. REQUIRES realFaceConsent=true.'),
         realFaceConsent: z.boolean().optional().describe('MANDATORY with seedanceRealFace: true ONLY after the user has explicitly confirmed they hold rights/consent to this likeness and it does not impersonate or misrepresent them. Refused without it; public figures fail on every route.'),
         negativePrompt: z.string().optional(),
         background: z.boolean().optional().describe(BACKGROUND_DESCRIBE),
         confirm: z.boolean().optional().describe('Set true after explicit user OK to bypass the confirm gate (which fires for almost every video gen since they\'re expensive).'),
+        folderId: folderIdField,
     }),
     async run(input, ctx) {
+        // A desktop before the folder rule ignores folderId and files at the root.
+        if (input.folderId !== undefined)
+            await ctx.desktop().requireCapability('media-folder', 'choosing the folder a result lands in');
         // Resolve the model FIRST — forgiving normalization (cost keys, alias
         // spellings) with a teaching error, so a wrong id never costs the agent
         // a retry spiral. Anything the key encoded (duration/res/audio) fills
@@ -2832,7 +3371,7 @@ export const generateVideo = {
                 return ok({
                     requires_clarification: true,
                     missing: [],
-                    message: `Omni Flash takes a prompt, an optional start frame, and up to ${omniFlashRefCap} reference IMAGES — last frames and video/audio references are not supported. Drop those, or switch to seedance-2 (video/audio refs, last frame) or veo (last frame).`,
+                    message: `Omni Flash takes a prompt, an optional start frame, and up to ${omniFlashRefCap} reference IMAGES — last frames and video/audio references are not supported. Drop those, or switch to seedance-2.5 (video/audio refs, last frame).`,
                 });
             }
             const refCount = (input.ingredientAssetIds?.length ?? 0) +
@@ -3206,6 +3745,7 @@ export const generateVideo = {
             seedanceRealFace: input.seedanceRealFace,
             realFaceConsent: input.realFaceConsent,
             negativePrompt: input.negativePrompt,
+            ...folderBody(input.folderId),
             background: input.background,
         });
         if (!result.success) {
@@ -3309,10 +3849,9 @@ export const generateAudio = {
     id: 'slates_generate_audio',
     billable: true,
     description: `Generate project audio using credits. Choose the surface via the model routing below. ` +
-        'Read slates-cost-discipline and the matching prompting skill first (slates-prompting-seed-audio | slates-prompting-elevenlabs | slates-prompting-inworld-tts). ' +
+        'The estimate returns the chosen surface\'s prompting card; its full guide (slates-prompting-seed-audio | slates-prompting-elevenlabs | slates-prompting-inworld-tts) covers what the card leaves out. ' +
         'Seed Audio bills the requested duration, which is appended to the prompt regardless of output length. Kling "SFX:" / "Ambient noise:" syntax does not transfer. ' +
-        CONFIRM_GATE_SENTENCE +
-        ' No skill files installed? Call slates_get_prompting_guide first.',
+        CONFIRM_GATE_SENTENCE,
     input: z.object({
         projectId: z.string().uuid().describe('Slates project the audio asset lands in. Required — the renderer refreshes live.'),
         model: z
@@ -3365,8 +3904,12 @@ export const generateAudio = {
             .describe('seed-audio only — ONE image asset to score what is in frame. MUTUALLY EXCLUSIVE with audioReferenceAssetIds.'),
         background: z.boolean().optional().describe(BACKGROUND_DESCRIBE),
         confirm: z.boolean().optional().describe('Set true to bypass the confirm gate after explicit user OK.'),
+        folderId: folderIdField,
     }),
     run: async (input, ctx) => {
+        // A desktop before the folder rule ignores folderId and files at the root.
+        if (input.folderId !== undefined)
+            await ctx.desktop().requireCapability('media-folder', 'choosing the folder a result lands in');
         // ── Per-surface clarification + constraint gates ──
         //
         // `null` for the TTS seat is load-bearing rather than a placeholder: that
@@ -3500,6 +4043,7 @@ export const generateAudio = {
             promptInfluence: input.promptInfluence,
             audioReferenceAssetIds: (input.audioReferenceAssetIds ?? []).map((r) => rid(r)),
             imageReferenceAssetId: rid(input.imageReferenceAssetId),
+            ...folderBody(input.folderId),
             background: input.background,
         });
         if (!result.success)
@@ -3559,7 +4103,8 @@ async function quoteToolBlocks(ctx, stem, seconds, voiceStep) {
 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. 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.',
+    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. The craft is slates-prompting-lip-sync; the confirm response shows the exact cost before anything is charged. projectId is REQUIRED. ' +
+        CONFIRM_GATE_SENTENCE,
     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.'),
@@ -3682,11 +4227,11 @@ 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, 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. ' +
+    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. The craft is slates-prompting-motion-transfer; the confirm response shows the exact cost before anything is charged. projectId is REQUIRED — both assets must exist in the project. ' +
         CONFIRM_GATE_SENTENCE,
     input: z.object({
         projectId: z.string().uuid().describe('Slates project. Both source and target assets must live here.'),
-        sourceVideoAssetId: z.string().uuid().describe('Asset id of the reference video — its motion will be retargeted onto the target image. Must already exist in the project. Up to 30s.'),
+        sourceVideoAssetId: z.string().uuid().describe('Asset id of the reference video — its motion will be retargeted onto the target image. Must already exist in the project. Up to 30s with characterOrientation video, 10s with image; billed per 5s block.'),
         targetImageAssetId: z.string().uuid().describe('Asset id of the target image (the character that will perform the motion). Must already exist in the project.'),
         motionModel: z.enum(['kling-mc-std', 'kling-mc-pro']).optional().describe('kling-mc-std general motion; kling-mc-pro cleaner anatomy — default. Quote both with slates_estimate_generation_cost.'),
         characterOrientation: z.enum(['video', 'image']).optional().describe('"video" = use the source video\'s framing. "image" = use the target image\'s framing. Default video.'),
@@ -3793,7 +4338,7 @@ export const editVideo = {
     // point to in a tool result) and go stale on the next rate change; the
     // windows are owned by MODEL_CAPABILITIES and are generated below into the
     // params that enforce them.
-    'Edit an EXISTING video clip with one instruction — character swap, environment change, style transfer — in one pass, no masking. Original motion, camera, and audio are preserved; only what the prompt names changes. Use when a clip is ~90% right (fix it, don\'t re-roll it) or to AI-edit the user\'s own footage. Engines: Kling O3 edit (default — subject/style refs via elements), omni-flash-edit (PROMPT-ONLY, no refs, the cheapest seat), or seedance-2.5-edit (the only engine that takes a clip over 15s; seedanceFace:true for AI-character faces). Clip-length and resolution windows per engine are on the `model` param. Cost is per second of OUTPUT (≈ clip length, rounded up), and an edit bills input + output seconds on every provider — read the quote from the confirm gate or slates_estimate_generation_cost, never from memory. Subjects to swap IN go as characterAssetIds (frontal + angle images become Kling elements — Kling models only); style refs as styleAssetIds; max 4 combined. The edited clip saves as a NEW asset linked to its parent (chain edits freely). Routing: Kling edit is the default (element lock + audio intact); omni-flash-edit for cheap prompt-only footage-synced swaps; Seedance edit/relocate for style-transfer-heavy jobs — see slates-model-selection. Prompting: slates-prompting-kling-v3 §Edit / slates-prompting-omni-flash.',
+    'Edit an EXISTING video clip with one instruction — character swap, environment change, style transfer — in one pass, no masking. Original motion, camera, and audio are preserved; only what the prompt names changes. Use when a clip is ~90% right (fix it, don\'t re-roll it) or to AI-edit the user\'s own footage. Engines: Kling O3 edit (default — subject/style refs via elements), omni-flash-edit (PROMPT-ONLY, no refs, priced level with Kling O3 Edit Standard; the first pick in the routing guide for footage-synced edits), or seedance-2.5-edit (the only engine that takes a clip over 15s; seedanceFace:true for AI-character faces). Clip-length and resolution windows per engine are on the `model` param. Cost is per second of OUTPUT (≈ clip length, rounded up), and an edit bills input + output seconds on Seedance and output seconds on Kling and Omni Flash — read the quote from the confirm gate or slates_estimate_generation_cost, never from memory. Subjects to swap IN go as characterAssetIds (frontal + angle images become Kling elements — Kling models only); style refs as styleAssetIds; max 4 combined. The edited clip saves as a NEW asset linked to its parent (chain edits freely). Routing: Kling edit is the default (element lock + audio intact); omni-flash-edit for cheap prompt-only footage-synced swaps; Seedance edit for style-transfer-heavy jobs — see slates-model-selection. Prompting: slates-prompting-kling-v3 §Edit / slates-prompting-omni-flash.',
     input: z.object({
         projectId: z.string().uuid().describe('Project the source clip lives in.'),
         sourceVideoAssetId: z.string().describe('The VIDEO asset to edit — UUID or badge code ("VID-V3", bare "V3"); codes resolve against the project at call time. Kling: 3–15s clips; omni-flash-edit: 3–10s.'),
@@ -3810,12 +4355,16 @@ export const editVideo = {
         styleAssetIds: z.array(z.string()).max(4).optional().describe('Style/appearance reference images (@ImageN). Max 4 combined with characterAssetIds. KLING MODELS ONLY — rejected on omni-flash-edit.'),
         keepAudio: z.boolean().optional().describe('Preserve the original audio track (default true; Kling models only — omni-flash-edit and seedance-2.5-edit output carry their own audio).'),
         videoResolution: zEnum(EDIT_VIDEO_RESOLUTIONS).optional().describe(`seedance-2.5-edit ONLY (default ${defaultVideoResolutionFor('seedance-2.5-edit')}). Ignored by the Kling and Omni Flash engines, whose output follows the source clip.`),
-        seedanceFace: z.boolean().optional().describe('seedance-2.5-edit ONLY: set true when a CHARACTER FACE is visible in the clip. Faceless edits run on BytePlus; faces are blocked there and must route to the relaxed provider, which costs ~35% more. A face edit submitted without this flag is rejected by the provider, not silently downgraded.'),
+        seedanceFace: z.boolean().optional().describe('seedance-2.5-edit ONLY: set true when a CHARACTER FACE is visible in the clip. Faceless edits run on BytePlus; faces are blocked there and must route to the relaxed provider, which costs about 40-50% more. A face edit submitted without this flag is rejected by the provider, not silently downgraded.'),
         background: z.boolean().optional().describe(BACKGROUND_DESCRIBE),
         confirm: z.boolean().optional().describe('Set true to bypass the cost confirm gate after the user OKs the spend.'),
+        folderId: folderIdField,
     }),
     async run(input, ctx) {
         const desktop = ctx.desktop();
+        // A desktop before the folder rule ignores folderId and files at the root.
+        if (input.folderId !== undefined)
+            await desktop.requireCapability('media-folder', 'choosing the folder a result lands in');
         await desktop.requireCapability('edit-video', 'video editing (Kling O3 edit)');
         if (input.background) {
             await desktop.requireCapability('background-generation', 'background generation');
@@ -3918,6 +4467,7 @@ export const editVideo = {
             keepAudio: input.keepAudio !== false,
             videoResolution: input.videoResolution,
             seedanceFace: input.seedanceFace,
+            ...folderBody(input.folderId),
             background: input.background,
         });
         if (!result.success)
@@ -3955,7 +4505,7 @@ export const editVideo = {
 // ── Trim a video to an exact window (fit-to-model primitive) ────
 export const trimVideo = {
     id: 'slates_trim_video',
-    description: 'Trim a video asset to an exact [inSec, outSec] window and save the result as a NEW clip linked to the original (the original is untouched). This is the fit-to-model primitive: an 11s clip will not run on omni-flash-edit (3–10s) or Kling edit (3–15s), and a Seedance video reference must be 2–15s — trim it first, then edit/relocate the trimmed clip. EXACT re-encode (not a keyframe-snapped cut) so the result honors hard duration caps to the frame; any phone rotation flag is baked into the pixels in the same pass. The new clip lands with correct duration/width/height immediately. inSec defaults to 0.',
+    description: 'Trim a video asset to an exact [inSec, outSec] window and save the result as a NEW clip linked to the original (the original is untouched). This is the fit-to-model primitive: an 11s clip will not run on omni-flash-edit (3–10s), a 16s one not on Kling edit (3–15s), and a Seedance 2.0 video reference must be 2–15s (2.5 takes up to 30s combined) — trim it first, then edit the trimmed clip. EXACT re-encode (not a keyframe-snapped cut) so the result honors hard duration caps to the frame; any phone rotation flag is baked into the pixels in the same pass. The new clip lands with correct duration/width/height immediately. inSec defaults to 0. Pass pieces to cut the window into SEVERAL clips in one call, as the Trim & split dialog does (split points, or Auto-split by longest piece, with seconds shared between neighbours); every new clip comes back.',
     input: z.object({
         projectId: z.string().uuid().describe('Project the clip lives in.'),
         assetId: z
@@ -3963,6 +4513,15 @@ export const trimVideo = {
             .describe('The VIDEO asset to trim — UUID or badge code ("VID-V3", bare "V3"); resolves against the project at call time.'),
         inSec: z.number().min(0).optional().describe('Trim start in seconds (default 0).'),
         outSec: z.number().positive().describe('Trim end in seconds. Must be greater than inSec.'),
+        pieces: z
+            .object({
+            splitsAtSec: z.array(z.number().positive()).max(60).optional().describe('Cut the window at these seconds of the clip (Split here): each at least 0.15 s inside inSec and outSec and 0.2 s from the next.'),
+            longestSec: z.number().min(1).max(60).optional().describe('Auto-split: even pieces, none longer than this (Longest piece). Use instead of splitsAtSec.'),
+            shareSec: z.number().min(0).max(5).optional().describe('Pieces share: each piece also holds this many seconds of the next (default 0), so an edit can carry on into the next clip.'),
+        })
+            .strict()
+            .optional()
+            .describe('Cut the window into several clips instead of one. Needs splitsAtSec or longestSec.'),
     }),
     async run(input, ctx) {
         const desktop = ctx.desktop();
@@ -3972,6 +4531,24 @@ export const trimVideo = {
         if (input.outSec - inSec < 0.05) {
             throw new Error('outSec must be at least ~0.1s after inSec.');
         }
+        if (input.pieces) {
+            // 1.6.0 would cut the one window and ignore pieces without a word.
+            await desktop.requireCapability('trim-pieces', 'cutting a clip into pieces');
+            if (input.pieces.splitsAtSec === undefined && input.pieces.longestSec === undefined) {
+                throw new Error('pieces needs splitsAtSec (where to cut) or longestSec (Auto-split by longest piece).');
+            }
+            const cut = await desktop.post('/agent/assets/trim-video', {
+                assetId,
+                inSec,
+                outSec: input.outSec,
+                pieces: input.pieces,
+            });
+            const named = cut.assets.map((a, i) => `${a.code ?? a.id} (${cut.pieces[i].start.toFixed(1)}–${cut.pieces[i].end.toFixed(1)}s)`);
+            return {
+                text: `Cut ${cut.assets.length} clip${cut.assets.length === 1 ? '' : 's'} from the ${inSec.toFixed(1)}–${input.outSec.toFixed(1)}s window: ${named.join(', ')}. Edit or generate from them by id/code.`,
+                data: { assets: cut.assets, pieces: cut.pieces },
+            };
+        }
         const r = await desktop.post('/agent/assets/trim-video', {
             assetId,
             inSec,
@@ -4284,7 +4861,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 'Export for DaVinci, Premiere or Final Cut' 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. Use this for DaVinci Resolve or Premiere; current Final Cut Pro requires FCPXML, which this tool does not export. Pass an absolute outputPath ending in .xml; fails if the file exists unless overwrite=true.",
     input: z
         .object({
         projectId: z.string().uuid().optional(),
@@ -4792,7 +5369,7 @@ 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. 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.',
+    '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. preferredClipId picks the clip the timeline takes for this slot (a video asset id or VID code; null goes back to the slot\'s most recent linked clip), as the take menu\'s "Use in the timeline" does. 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(),
@@ -4800,8 +5377,12 @@ export const updateFrame = {
         assetId: z.string().uuid().nullable().optional(),
         sceneId: z.string().uuid().optional(),
         position: z.number().int().min(0).optional(),
+        preferredClipId: z.string().min(1).nullable().optional().describe('The clip the timeline takes for this slot: a video asset id or badge code in the project; null clears it.'),
     }),
     async run(input, ctx) {
+        // 1.6.0 takes the call and drops preferredClipId without a word.
+        if (input.preferredClipId !== undefined)
+            await ctx.desktop().requireCapability('frame-preferred-clip', 'choosing the clip a slot uses');
         return ok(await ctx.desktop().post('/agent/frames/update', {
             id: input.frameId,
             data: {
@@ -4810,6 +5391,7 @@ export const updateFrame = {
                 assetId: input.assetId,
                 sceneId: input.sceneId,
                 position: input.position,
+                preferredClipId: input.preferredClipId,
             },
         }));
     },
@@ -4829,7 +5411,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. 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.',
+    description: 'Update MANY slots in one call — shot labels, notes, asset binding, scene/position, and preferredClipId (the clip the timeline takes for the slot: a video asset id or VID code, null to clear). 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({
@@ -4839,10 +5421,14 @@ export const batchUpdateFrames = {
             assetId: z.string().uuid().nullable().optional(),
             sceneId: z.string().uuid().optional(),
             position: z.number().int().min(0).optional(),
+            preferredClipId: z.string().min(1).nullable().optional().describe('A video asset id or badge code in the project; null clears it.'),
         }))
             .min(1),
     }),
     async run(input, ctx) {
+        // 1.6.0 takes the call and drops preferredClipId without a word.
+        if (input.updates.some((u) => u.preferredClipId !== undefined))
+            await ctx.desktop().requireCapability('frame-preferred-clip', 'choosing the clip a slot uses');
         return ok(await ctx.desktop().post('/agent/frames/batch-update', {
             updates: input.updates.map((u) => ({
                 id: u.frameId,
@@ -4852,6 +5438,7 @@ export const batchUpdateFrames = {
                     assetId: u.assetId,
                     sceneId: u.sceneId,
                     position: u.position,
+                    preferredClipId: u.preferredClipId,
                 },
             })),
         }));
@@ -5143,6 +5730,60 @@ async function buildShotSpecInput(ctx, projectId, input) {
         refEcho: describeResolvedRefs(refInputs, resolvedRefs),
     };
 }
+/**
+ * The spec fields the caller NAMED, read out of the COMPLETE spec `buildShotSpecInput` built from the whole
+ * input. Only those go to a route that merges a partial spec over a stored one (`slates_update_shot`, and
+ * `slates_create_shot` from a result), so anything the caller omitted is left exactly as it was.
+ */
+function namedSpecPatch(input, spec) {
+    const patch = {};
+    if (input.prompt !== undefined)
+        patch.prompt = input.prompt;
+    if (input.model !== undefined) {
+        patch.model = input.model;
+        // 🚨 `authoredFor` is NOT re-stamped on a model swap. The whole point of
+        // recording it is that the prompt stays written for the model it was
+        // written for — the grammars genuinely differ — so the card can say so.
+    }
+    if (input.params !== undefined)
+        patch.params = spec.params;
+    // 🚨 ONLY THE ROLES THE CALLER NAMED. `buildShotSpecInput` always returns a
+    // COMPLETE refs record, and the route merges one level deep — so sending all
+    // five would clear every role the caller never mentioned. Clearing a role is
+    // explicit: send `[]`.
+    if (input.refs !== undefined) {
+        const built = spec.refs;
+        const named = {};
+        for (const role of ORDERED_ATTACHMENT_ROLES) {
+            if (input.refs[role] !== undefined)
+                named[role] = built[role];
+        }
+        if (Object.keys(named).length > 0)
+            patch.refs = named;
+    }
+    if (input.firstFrameAssetId !== undefined)
+        patch.firstFrameAssetId = spec.firstFrameAssetId;
+    if (input.lastFrameAssetId !== undefined)
+        patch.lastFrameAssetId = spec.lastFrameAssetId;
+    if (input.audioRefSpokenText !== undefined)
+        patch.audioRefSpokenText = spec.audioRefSpokenText;
+    Object.assign(patch, shotScriptPatch(input));
+    // Same rule for the three mention lists — naming one must not clear the
+    // other two.
+    {
+        const built = spec.mentions;
+        const named = {};
+        if (input.characterIds !== undefined)
+            named.characterIds = built.characterIds;
+        if (input.environmentIds !== undefined)
+            named.environmentIds = built.environmentIds;
+        if (input.styleIds !== undefined)
+            named.styleIds = built.styleIds;
+        if (Object.keys(named).length > 0)
+            patch.mentions = named;
+    }
+    return patch;
+}
 /**
  * The capability gate, applied to a SAVED recipe.
  *
@@ -5179,7 +5820,8 @@ export const createShot = {
     input: z.object({
         projectId: z.string().uuid(),
         name: z.string().max(120).optional().describe('What to call it. Shown on the card; the prompt supplies one if you omit it.'),
-        prompt: z.string().min(1).max(4000).describe('The RAW prompt, @mentions intact. Never write "image 1" yourself — the composer numbers references, and a hand-written number is wrong the moment one moves.'),
+        prompt: z.string().min(1).max(4000).optional().describe('The RAW prompt, @mentions intact. Never write "image 1" yourself — the composer numbers references, and a hand-written number is wrong the moment one moves. Required unless fromAssetId supplies the recipe.'),
+        fromAssetId: z.string().optional().describe("Save as shot: start from this asset's RECORDED recipe (UUID or badge code) — its prompt, model, settings and references — as Media's Save as shot does. That result becomes the Shot's first take unless another Shot already holds it. Anything else you pass overrides the recipe."),
         model: z.string().optional().describe('Model id — the same ids slates_generate_image / slates_generate_video / slates_generate_audio take, and their descriptions carry the routing. Optional: a Shot can be planned before the model is decided.'),
         params: shotParamsSchema,
         refs: shotRefsSchema,
@@ -5196,6 +5838,8 @@ export const createShot = {
         ...shotScriptSchema,
     }),
     async run(input, ctx) {
+        if (!input.prompt && !input.fromAssetId)
+            throw new Error('Pass a prompt, or fromAssetId to save a result\'s recorded recipe as the Shot.');
         const capErr = assertShotCapabilities(input.model, input.params);
         if (capErr)
             return capErr;
@@ -5204,6 +5848,9 @@ export const createShot = {
             return alignErr;
         const desktop = ctx.desktop();
         await desktop.requireCapability('shots', 'saved Shots');
+        // 1.6.0 ignores fromAssetId, and would then refuse the missing prompt.
+        if (input.fromAssetId)
+            await desktop.requireCapability('shot-from-asset', 'saving a result as a Shot');
         // 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');
@@ -5211,15 +5858,21 @@ export const createShot = {
         const r = await desktop.post('/agent/shots', {
             projectId: input.projectId,
             name: input.name,
-            spec: { ...spec, ...shotScriptPatch(input) },
+            // From a result, only what the caller NAMED goes over its recorded recipe: the route merges it.
+            spec: input.fromAssetId ? namedSpecPatch(input, spec) : { ...spec, ...shotScriptPatch(input) },
+            fromAssetId: input.fromAssetId,
             frameId: input.frameId ?? null,
             sceneId: input.sceneId ?? null,
             storyboardId: input.storyboardId ?? null,
             position: input.position,
         });
+        const fromNote = input.fromAssetId
+            ? ` Saved from ${input.fromAssetId}: its recorded recipe is the Shot's, and that result is its first take (unless another Shot already holds it).` +
+                (r.unsavedPaths?.length ? ` ${r.unsavedPaths.length} recorded attachment(s) are not project assets and are not on the Shot.` : '')
+            : '';
         // The CODE is the address the user sees on the row — say it back so the
         // next call, and the next sentence to the user, can point at it.
-        return ok(r.shot, `${r.shot?.code || 'Shot'} — "${r.shot?.name || 'Untitled'}". ${refEcho}`.trim());
+        return ok(r.shot, `${r.shot?.code || 'Shot'} — "${r.shot?.name || 'Untitled'}". ${refEcho}${fromNote}`.trim());
     },
 };
 export const updateShot = {
@@ -5257,52 +5910,7 @@ export const updateShot = {
         const { spec } = await buildShotSpecInput(ctx, input.projectId, input);
         // Only send the halves the caller actually named; the route merges a PARTIAL
         // spec over the stored one, so an omitted field is never silently cleared.
-        const patch = {};
-        if (input.prompt !== undefined)
-            patch.prompt = input.prompt;
-        if (input.model !== undefined) {
-            patch.model = input.model;
-            // 🚨 `authoredFor` is NOT re-stamped on a model swap. The whole point of
-            // recording it is that the prompt stays written for the model it was
-            // written for — the grammars genuinely differ — so the card can say so.
-        }
-        if (input.params !== undefined)
-            patch.params = spec.params;
-        // 🚨 ONLY THE ROLES THE CALLER NAMED. `buildShotSpecInput` always returns a
-        // COMPLETE refs record, and the route merges one level deep — so sending all
-        // five would clear every role the caller never mentioned. Clearing a role is
-        // explicit: send `[]`.
-        if (input.refs !== undefined) {
-            const built = spec.refs;
-            const named = {};
-            for (const role of ORDERED_ATTACHMENT_ROLES) {
-                if (input.refs[role] !== undefined)
-                    named[role] = built[role];
-            }
-            if (Object.keys(named).length > 0)
-                patch.refs = named;
-        }
-        if (input.firstFrameAssetId !== undefined)
-            patch.firstFrameAssetId = spec.firstFrameAssetId;
-        if (input.lastFrameAssetId !== undefined)
-            patch.lastFrameAssetId = spec.lastFrameAssetId;
-        if (input.audioRefSpokenText !== undefined)
-            patch.audioRefSpokenText = spec.audioRefSpokenText;
-        Object.assign(patch, shotScriptPatch(input));
-        // Same rule for the three mention lists — naming one must not clear the
-        // other two.
-        {
-            const built = spec.mentions;
-            const named = {};
-            if (input.characterIds !== undefined)
-                named.characterIds = built.characterIds;
-            if (input.environmentIds !== undefined)
-                named.environmentIds = built.environmentIds;
-            if (input.styleIds !== undefined)
-                named.styleIds = built.styleIds;
-            if (Object.keys(named).length > 0)
-                patch.mentions = named;
-        }
+        const patch = namedSpecPatch(input, spec);
         const r = await desktop.post('/agent/shots/update', {
             id: input.shotId,
             data: {
@@ -5407,7 +6015,7 @@ 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, 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.",
+    description: "Read the shot list — every Shot as a compact row IN BOARD ORDER (scene, then position), with its place on the board (2C: scene number and slot letter, as the window shows it and the user says it), 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 board.'),
@@ -5448,6 +6056,7 @@ export const listShots = {
                 name: s.name,
                 scene: s.sceneName,
                 position: s.position,
+                ...(s.place !== undefined ? { place: s.place } : {}),
                 model: s.model,
                 references: s.referenceCount,
                 cuts: s.cuts,
@@ -5472,7 +6081,7 @@ ${describeVarietyReport(r.variety)}` : ''));
 };
 export const getShot = {
     id: 'slates_get_shot',
-    description: 'Read one Shot in full — the COMPOSED prompt the request will actually carry, its numbered references, anything it points at that no longer exists, and its exact credit quote. Audit your own work here before firing.',
+    description: 'Read one Shot in full — the COMPOSED prompt the request will actually carry, its numbered references, anything it points at that no longer exists, its exact credit quote, and its place on the board (2C, as the window shows it). Audit your own work here before firing.',
     input: z.object({
         shotId: z.string().describe('The Shot id, or its SHOT-A code as shown on the row.'),
     }),
@@ -5484,7 +6093,7 @@ export const getShot = {
         const r = await desktop.get('/agent/shots/get', { id: input.shotId });
         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'}, ` +
+        return ok({ ...r.shot, credits: q.credits, quoteFingerprint: quote.fingerprint }, `${r.shot.place ? `${r.shot.place} ` : ''}"${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.'}`) +
@@ -5492,6 +6101,31 @@ export const getShot = {
             `\nCOMPOSED PROMPT (what the model is told): ${r.shot.composedPrompt}`);
     },
 };
+/**
+ * The Board's "Use pictures as first frames": each video Shot with a picture and no first frame starts its
+ * video from that picture. The desktop runs the command's own pick and write (`firstFrameCandidate`,
+ * `withFirstFrame`), so the recipe changes exactly as a click changes it. Free: nothing is generated.
+ */
+export const usePicturesAsFirstFrames = {
+    id: 'slates_use_pictures_as_first_frames',
+    description: "The Board's 'Use pictures as first frames': each video Shot that has a picture and no first frame starts its video from that picture (its tile picture, else its newest picture take; a picture that was its only plain Reference moves into the frame slot). Nothing is generated and nothing is charged. Pass shotIds (ids or SHOT-A codes) to act on those Shots; omit them to act on every Shot of the board open in the window, as the command does (open one with slates_set_view first). Returns, per Shot, the picture it set or why it had none.",
+    input: z
+        .object({
+        projectId: z.string().uuid(),
+        shotIds: z.array(z.string().min(1)).min(1).max(200).optional().describe('Only these Shots. Omit for every Shot of the board open in the window.'),
+    })
+        .strict(),
+    async run(input, ctx) {
+        await ctx.desktop().requireCapability('first-frames', 'using pictures as first frames');
+        const r = await ctx.desktop().post('/agent/shots/first-frames', input);
+        const name = (row) => row.place ?? row.code ?? row.shotId;
+        const lines = r.results.map((row) => `${name(row)}: ${row.set ? 'first frame set' : (row.reason ?? 'nothing to set')}`);
+        return {
+            text: `${r.set} of ${r.results.length} Shot${r.results.length === 1 ? '' : 's'} now start from their picture.${lines.length ? `\n${lines.join('\n')}` : ''}`,
+            data: r,
+        };
+    },
+};
 /**
  * SPLIT and MERGE — the chop decision, and the only two cross-row operations on
  * this surface.
@@ -5944,7 +6578,7 @@ export const editCut = {
 };
 export function resolveGuideTopic(topic) {
     const t = topic.trim().toLowerCase();
-    if (SKILLS[t])
+    if (Object.hasOwn(SKILLS, t))
         return t;
     if (t === 'slates-character-turnaround' || t === 'character-turnaround') {
         return 'slates-character-identity';
@@ -6018,8 +6652,6 @@ export function resolveGuideTopic(topic) {
         return 'slates-prompting-flux-2-max';
     if (t.startsWith('seedream'))
         return 'slates-prompting-seedream-5-lite';
-    if (t.startsWith('veo'))
-        return 'slates-prompting-veo-3';
     if (t.startsWith('omni-flash') || t.startsWith('gemini-omni') || t === 'omni flash')
         return 'slates-prompting-omni-flash';
     // MiniMax H3 — both seats share one skill. Placed BEFORE the seed/seedance
@@ -6040,7 +6672,7 @@ export function resolveGuideTopic(topic) {
     if (t.startsWith('kling-mc'))
         return 'slates-prompting-motion-transfer';
     if (t === 'edit-video' || t === 'video-edit' || t === 'edit video' || t === 'video edit')
-        return 'slates-prompting-kling-v3';
+        return resolveGuideTopic(defaultModelFor('video', 'edit'));
     if (t.startsWith('kling-v3'))
         return 'slates-prompting-kling-v3';
     // Audio — the TTS seat FIRST, then seed-audio, then eleven-sfx.
@@ -6101,70 +6733,96 @@ export function resolveGuideTopic(topic) {
     }
     return null;
 }
-/**
- * The guide index, GENERATED from SKILLS.
- *
- * The list here was hand-typed and had drifted to 25 of 32 names — the prompting
- * guides for GPT Image, MiniMax H3, LTX-2.5, Seedance 2.5 and Omni Flash were
- * all missing, so an agent reading this description could not learn they exist.
- * A hand-typed index of a generated corpus is a stale index; it is only a matter
- * of when.
- *
- * Per-model guides are listed as BARE NAMES: the name is the description, and
- * `resolveGuideTopic()` resolves a model id to the right one anyway.
- */
-function describeGuideTopics() {
-    const names = Object.keys(SKILLS).sort();
-    const perModel = names.filter((n) => n.startsWith('slates-prompting-'));
-    const rest = names.filter((n) => !n.startsWith('slates-prompting-'));
-    return (`Workflow and cross-cutting guides: ${rest.join(', ')}. ` +
-        `Per-model prompting guides (or just pass the model id, which resolves to one of these): ` +
-        `${perModel.join(', ')}. ` +
-        `Style names (photoreal, anime, painterly, 3d-render) resolve to slates-style-prompting.`);
+// Discovery is the first call of most briefs: a slow or unentitled member check
+// must not cost every call a round trip, or hang free craft behind a 30s read.
+const MEMBER_CATALOG_TTL_MS = 60_000;
+const MEMBER_CATALOG_TIMEOUT_MS = 5_000;
+const memberCatalogCache = new WeakMap();
+/** Private bodies stay on the entitled member feed, never in public packages. */
+function memberGuideCatalog(ctx) {
+    const cached = memberCatalogCache.get(ctx.cloud);
+    if (cached && Date.now() - cached.at < MEMBER_CATALOG_TTL_MS)
+        return cached.value;
+    const value = fetchMemberGuideCatalog(ctx);
+    memberCatalogCache.set(ctx.cloud, { at: Date.now(), value });
+    return value;
+}
+async function fetchMemberGuideCatalog(ctx) {
+    try {
+        // Request first: a missing token throws here, before any timer exists.
+        const request = ctx.cloud().get('/members/manifest.json');
+        let timer;
+        const timeout = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('Member guide check timed out')), MEMBER_CATALOG_TIMEOUT_MS); });
+        const manifest = await Promise.race([request, timeout]).finally(() => clearTimeout(timer));
+        if (!Array.isArray(manifest?.skills))
+            throw new Error('Invalid member guide manifest');
+        // A malformed entry is skipped; it never hides the account's other playbooks.
+        const entries = manifest.skills
+            .filter(entry => entry.tier === 'paid' && typeof entry.name === 'string' && /^slates-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(entry.name) && entry.name.length <= 64 && typeof entry.description === 'string' && entry.description.length <= 1024)
+            .map(entry => ({ name: entry.name, description: entry.description, tier: 'paid' }));
+        return { entries, access: 'available' };
+    }
+    catch (error) {
+        if (error.code === 'CLOUD_TOKEN_MISSING')
+            return { entries: [], access: 'not connected; bundled guides available' };
+        if (error instanceof SlatesCloudHttpError && error.status === 402)
+            return { entries: [], access: 'no active skills entitlement; bundled guides available' };
+        if (error instanceof SlatesCloudHttpError && error.status === 404)
+            return { entries: [], access: 'member feed unavailable on this API version; bundled guides available' };
+        // Keep free craft usable during a cloud outage, but expose the failed access check.
+        return { entries: [], access: error instanceof SlatesCloudHttpError && error.status === 401 ? 'reconnect Slates to access member guides; bundled guides available' : 'member access check failed; retry for private guides; bundled guides available' };
+    }
 }
 export const getPromptingGuide = {
     id: 'slates_get_prompting_guide',
-    description: 'For app help and exact UI instructions use topic "app-manual" with a query such as "voice recording". This returns the canonical product manual, shared by every agent surface. ' +
-        // 🚨 NO "ALWAYS READ THIS FIRST" SENTENCE. It stood here for months and was
-        // MEASURED at 13% compliance before and after the enforcement work — pointer
-        // prose is the shape that does not move the agent. What replaced it is
-        // structural: the never-use list rides the generate ops' descriptions and
-        // the craft card rides the estimate result, so the facts arrive whether or
-        // not this op is ever called.
-        "Return a bundled Slates prompting/workflow guide. MCP-only clients (Claude Desktop, Smithery) don't get the CLI-installed skill files — call this instead. Accepts a guide name or a model id ('veo-3.1-fast', 'kling-v3.0-pro', 'seedance-2', 'nano-banana-2'), which maps to the right guide. Reach for it when a card is not enough: the failure modes, the worked examples and the sources are only in the full text.",
+    description: 'Find production craft from the user vision: pass query alone with the brief (for example "two friends talking in a rainy diner") for keyword-ranked guides with matching sections, followed by every other guide\'s description so you choose by judgment. Omit topic and query, or use topic "catalog", for the whole catalog. Then request a guide name, model id or style name with card/index/section/full depth. Cards are short; query with a topic selects one section or cinematic technique; full returns worked examples, failure modes and sources. Reuse current guidance already in context. Entitled member playbooks are fetched privately through the connected Slates account. For exact buttons and UI paths use topic "app-manual" with relevant question keywords; no query returns its surface map. Users supply the vision; you find the guides.',
     input: z.object({
-        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', '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.'),
+        query: z.string().min(1).max(1000).optional().describe('Without topic: creative brief or craft need to discover guides. With topic: section keywords, heading or technique ID.'),
+        topic: z.string().min(1).optional().describe('Optional guide name, model id, style name, catalog, or app-manual. Omit to search by intent or browse.'),
+        depth: z.enum(['card', 'index', 'section', 'full']).optional().describe('Default card is a short overview; index lists sections; query selects a section; full returns the complete guide.'),
+        limit: z.number().int().min(1).max(20).optional().describe('Page size: a search returns 8 ranked matches by default, browsing the whole catalog. Does not change guide bodies.'),
+        offset: z.number().int().min(0).optional().describe('Catalog/search offset from nextOffset in the preceding result.'),
     }),
-    async run(input) {
-        if (input.topic.trim().toLowerCase() === 'app-manual') {
-            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');
+    async run(input, ctx) {
+        const topic = input.topic?.trim().toLowerCase();
+        if (topic === 'app-manual') {
+            const content = input.query || input.depth === 'full' ? appManualSections(input.query) : appManualIndex();
             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(', ')}`);
+        const resolved = topic ? resolveGuideTopic(topic) : null;
+        if (resolved) {
+            const depth = input.depth ?? 'card';
+            const guide = retrieveGuide(resolved, SKILLS[resolved], depth, input.query);
+            return { text: guide, data: { topic: resolved, tier: 'free', depth, bytes: Buffer.byteLength(guide, 'utf8'), guide } };
         }
-        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 } };
+        const member = await memberGuideCatalog(ctx);
+        const privateEntry = member.entries.find(entry => entry.name === topic);
+        if (privateEntry) {
+            // The feed's 402/404 bodies are purchase pages; the agent needs the fact, not the page.
+            const result = await ctx.cloud().get(`/members/skills/${encodeURIComponent(privateEntry.name)}.md?format=json`).catch((error) => {
+                if (error instanceof SlatesCloudHttpError && error.status === 402)
+                    throw new SlatesCloudHttpError(`${privateEntry.name} needs an active skills entitlement; bundled guides remain available.`, 402);
+                if (error instanceof SlatesCloudHttpError && error.status === 404)
+                    throw new SlatesCloudHttpError(`${privateEntry.name} is no longer in the member feed.`, 404);
+                throw error;
+            });
+            if (typeof result?.markdown !== 'string')
+                throw new Error('Invalid member guide body');
+            const depth = input.depth ?? 'card';
+            const guide = retrieveGuide(privateEntry.name, result.markdown, depth, input.query);
+            return { text: guide, data: { topic: privateEntry.name, tier: 'paid', depth, bytes: Buffer.byteLength(guide, 'utf8'), guide } };
+        }
+        const catalog = [...guideCatalog(SKILLS), ...member.entries].sort((a, b) => a.name.localeCompare(b.name));
+        const result = discoverGuides(catalog, SKILLS, input.query ?? (topic && topic !== 'catalog' && topic !== 'index' ? input.topic : undefined), input.limit, input.offset);
+        const guide = result.guides.map(entry => `${entry.name} (${entry.tier}): ${entry.description}${entry.sections.length ? `\n  Matching sections: ${entry.sections.join('; ')}` : ''}`).join('\n\n');
+        const rest = result.rest.length ? `\n\nEvery other guide (keyword hints above only see shared words; choose by the brief):\n${result.rest.map(entry => `- ${entry.name} (${entry.tier}): ${entry.description}`).join('\n')}` : '';
+        const text = `${result.fallback ? 'No keyword match; choose relevant craft from the catalog.\n\n' : ''}${guide}${rest}\n\n${result.total} ${result.query && !result.fallback ? 'keyword matches' : 'guides'}; nextOffset: ${result.nextOffset ?? 'none'}. Member guides: ${member.access}. Retrieve a name with depth card/index or query for a section. The user does not need to choose guides.`;
+        return { text, data: { ...result, memberAccess: member.access, bytes: Buffer.byteLength(text, 'utf8') } };
     },
 };
 /**
- * The one op that changes what OTHER ops are visible.
- *
- * 🚨 IT EXISTS BECAUSE THE SURFACE IS 112 KB AND EVERY TURN PAYS FOR ALL OF IT.
- * Both surfaces start with the shared core set. Search returns compact metadata;
- * names/group returns exact schemas and replaces the optional selection.
+ * Task discovery and exact schemas share one operation. The desktop uses
+ * names/group to replace its optional selection; MCP keeps its full list fixed.
  */
 export const loadTools = {
     id: 'slates_load_tools',
@@ -6179,9 +6837,7 @@ export const loadTools = {
     }).refine((v) => [v.group, v.query, v.names].filter(Boolean).length === 1, 'Pass exactly one of query, names, or group.'),
     async run(input) {
         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 ranked = searchTools(ALL_OPERATIONS, input.query);
             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.');
         }
@@ -6350,8 +7006,21 @@ export const blenderRenderBlocking = {
 export const ALL_OPERATIONS = [
     getWorkspaceState,
     getSelection,
+    setSelection,
     getView,
     setView,
+    getManualPicture,
+    highlightControl,
+    getComposer,
+    setComposer,
+    reorderFolders,
+    reorderPins,
+    getUsage,
+    getAppSettings,
+    setAppSettings,
+    getAsset,
+    linkAssetSource,
+    extractVideoFrame,
     getMe,
     getCreditBalance,
     listAvailableModels,
@@ -6400,6 +7069,7 @@ export const ALL_OPERATIONS = [
     editVideo,
     trimVideo,
     editImage,
+    extractGridCells,
     getGenerationStatus,
     listGenerations,
     listTimelines,
@@ -6485,6 +7155,7 @@ export const ALL_OPERATIONS = [
     pasteScript,
     listShots,
     getShot,
+    usePicturesAsFirstFrames,
     generateFromShots,
     quoteBoard,
     getBoardProgress,