@slatesvideo/shared 0.6.4 → 0.6.6

package/dist/operations/index.js

@@ -14,6 +14,7 @@ import { SlatesCloudClient } from '../clients/cloud.js';
 import { SlatesDesktopClient } from '../clients/desktop.js';
 import { BlenderBridgeClient, BLENDER_SETUP_HINT, RENDER_TIMEOUT_MS } from '../clients/blender.js';
 import { SKILLS } from '../skills/content.js';
+import { appManualSections } from '../manual/index.js';
 // Reference-capacity prose is DERIVED, never hand-typed — root CLAUDE.md:
 // "never hand-type a fact an LLM will read". These helpers read MODEL_FACTS.
 import { multimodalRefSummary, multimodalRefModels, seedanceTaskIntentWords, 
@@ -183,6 +184,15 @@ export const TTS_MAX_CHARACTERS = (() => {
     return max;
 })();
 export const TTS_BUCKET_COUNT = TTS_MAX_CHARACTERS / TTS_BUCKET_CHARS; // 8
+/** The seat's cloning spec — reference-clip bounds, the design-prompt bounds
+ *  and the workspace-wide clone rate — read from the SSOT for the same reason
+ *  as the cap: every number in it was MEASURED and lives in exactly one row. */
+export const TTS_VOICE_CLONE = (() => {
+    const spec = getModelCapability(TTS_MODEL)?.voiceClone;
+    if (!spec)
+        throw new Error(`MODEL_CAPABILITIES['${TTS_MODEL}'] must declare voiceClone`);
+    return spec;
+})();
 function creditCost(m) {
     if (!m)
         return 0;
@@ -201,7 +211,7 @@ function creditsFromDollars(dollars) {
 // Shared describe-text for the background flag on every generate_* op. ONE
 // sentence: it is repeated verbatim on seven ops, so every word costs seven
 // times, and `slates_get_generation_status` explains the polling itself.
-const BACKGROUND_DESCRIBE = 'Return generationId(s) immediately instead of blocking; poll slates_get_generation_status. Recommended for video.';
+const BACKGROUND_DESCRIBE = 'Return generationId(s) now instead of blocking; poll slates_get_generation_status. Recommended for video.';
 // ── Vision QC pointers (the "quality-check with vision" rule, made structural) ──
 //
 // QUALITY-CHECK is a POST-condition, so it cannot be gated the way a
@@ -219,7 +229,7 @@ const IMAGE_INLINE_REVIEW = 'The image is attached to this result — look at it
 const VIDEO_REVIEW_POINTER = 'You have NOT seen this clip: call slates_get_asset_video_frames on the asset id above before ' +
     'describing how it looks. A quality claim you cannot point to a tool result for is a REAL NUMBERS ONLY violation.';
 const BACKGROUND_REVIEW_POINTER = 'When it completes, look at it before you describe it — slates_get_asset_image for images, ' +
-    'slates_get_asset_video_frames for video.';
+    'slates_get_asset_video_frames for video. For audio, audition the saved file; metadata alone does not establish voice similarity or delivery quality.';
 // The image saved, but reading it back off disk failed (best-effort fetch). The
 // agent has an asset and NO pixels, which is the one state where a quality
 // claim would be pure invention — so this branch has to say so rather than
@@ -492,8 +502,9 @@ export const estimateGenerationCost = {
         duration: z.number().int().min(1).max(360).optional().describe(`Seconds; cost scales linearly. Required with a video or PER-SECOND audio base id. Per-model windows: see slates_generate_video's duration. Audio: seed-audio ${SEED_AUDIO_MIN_SECONDS}-${SEED_AUDIO_MAX_SECONDS} (⚠️ the requested duration IS the bill), eleven-sfx ${ELEVEN_SFX_MIN_SECONDS}-${ELEVEN_SFX_MAX_SECONDS}. ⛔ NOT for ${TTS_MODEL} — pass \`characters\`.`),
         characters: z.number().int().min(1).max(TTS_MAX_CHARACTERS).optional().describe(`${TTS_MODEL} only — the LENGTH OF THE TEXT to speak (${TTS_BUCKET_CHARS}-char buckets).`),
         videoResolution: zEnum(VIDEO_RESOLUTIONS).optional().describe('Video only. Omitted, each model quotes at its own default. Per-model ladders: see slates_generate_video\'s videoResolution.'),
-        resolution: z.enum(['1k', '2k', '3k', '4k']).optional().describe('Image only (default 2k; 3k = gpt-image-2 1440p class).'),
-        quality: z.enum(['medium', 'high']).optional().describe('gpt-image-2 only — quality tier (default medium).'),
+        resolution: z.enum(['1k', '2k', '3k', '4k']).optional().describe('Image only (default 2k; 3k: GPT Image/seedream-5-lite).'),
+        quality: z.enum(['low', 'medium', 'high', 'xhigh', 'max']).optional().describe('GPT Image tier; default high.'),
+        aspectRatio: z.string().optional().describe('Image only. 1:1/4:3/3:4 cost more than 16:9.'),
         sound: z.boolean().optional().describe('Veo only — audio flag changes the cost key.'),
         seedanceFace: z.boolean().optional().describe('Seedance AI-face route (pricier key).'),
         seedanceRealFace: z.boolean().optional().describe('Seedance consented real-face route (premium key).'),
@@ -504,15 +515,21 @@ export const estimateGenerationCost = {
         const byKey = new Map(registry.models.map((m) => [m.model, creditCost(m)]));
         // 1) exact registry cost key
         let key = byKey.has(input.model) ? input.model : null;
-        // 2) image base id + resolution (+ quality for gpt-image-2)
+        // 2) image base id + resolution (+ quality for GPT Image 2.5)
         if (!key) {
             // IMAGE_MODELS, never a second hand-typed copy: this list is declared
             // below (a runtime read, so no temporal-dead-zone hazard) and is the same
             // enum `slates_generate_image` accepts. Two copies is how the estimate op
             // would quietly stop pricing the seventh image model.
             const img = IMAGE_MODELS.find((m) => m === input.model);
+            // ⚙ NO INLINE DEFAULT. `imageCostKey`'s own parameter default is the ONE
+            // home for the fallback tier, and `pricing-consistency-check.mjs` pins it
+            // to the desktop's. This line read `?? 'medium'` while every generate path
+            // billed `high`, so the op the doctrine tells agents to call before every
+            // generation quoted 1 cr for a 2 cr job. Four separate copies of one
+            // default is what made that possible; there are now none.
             if (img)
-                key = imageCostKey(img, input.resolution ?? (img === 'nano-banana-2-lite' ? '1k' : '2k'), input.quality ?? 'medium');
+                key = imageCostKey(img, input.resolution ?? (img === 'nano-banana-2-lite' ? '1k' : '2k'), input.quality, input.aspectRatio);
         }
         // 2a) audio base id → seconds. Both surfaces bill per second, so a
         //     duration is always required. Runs BEFORE the video resolver: it is
@@ -632,7 +649,7 @@ export const estimateGenerationCost = {
         if (key == null || perCredits == null) {
             // Every id in the error comes from the SSOT arrays. The image half was
             // hand-typed and named three of six, so an agent that mis-spelled
-            // `gpt-image-2` was told the model did not exist.
+            // `gpt-image-2-5-flare` was told the model did not exist.
             throw new Error(`Unknown model: ${input.model}. Pass a base id (${VIDEO_MODELS.join(' | ')} | ${AUDIO_MODELS.join(' | ')} | ${IMAGE_MODELS.join(' | ')}) plus duration/resolution params, or use slates_list_available_models with a filter.`);
         }
         const qty = input.quantity ?? 1;
@@ -1113,11 +1130,23 @@ export const generateCharacterIdentity = {
         baseAssetId: z.string().uuid().describe('The base portrait asset the identity is generated from.'),
         userNotes: z.string().optional().describe('Extra instruction, e.g. "use the woman on the left".'),
         model: z
-            .enum(['nano-banana-2', 'nano-banana-2-lite', 'nano-banana-pro', 'gpt-image-2'])
+            .enum(['nano-banana-2', 'nano-banana-2-lite', 'nano-banana-pro', 'gpt-image-2-5-flare', 'gpt-image-2-5-sunburst'])
             .optional()
             .describe('Image model for the sheet. Omit for the default (nano-banana-2). Exists so the layout-vs-face tradeoff can be tested with comparison gens — do not switch without a receipt.'),
     }),
     async run(input, ctx) {
+        // 🚨 THE ROSTER GATE, WHICH THIS OP NEVER HAD. Its `model` enum offers
+        // seats an older desktop does not know, and the handler resolves an unknown
+        // id by falling back to the Google/Banana path — so the op would quote one
+        // model's price and generate another, silently. Same failure `generateImage`
+        // and `editImage` gate against; this op was simply missed when the gate was
+        // introduced, and the 2.5 swap is what makes it reachable in practice.
+        if (isGptImageModel(input.model)) {
+            await ctx.desktop().requireCapability('image-models-v3', `${input.model} character identity`);
+        }
+        else if (input.model === 'nano-banana-pro' || input.model === 'nano-banana-2-lite') {
+            await ctx.desktop().requireCapability('image-models-v2', `${input.model} character identity`);
+        }
         return ok(await ctx.desktop().post('/agent/characters/generate-identity', {
             characterId: input.characterId,
             projectId: input.projectId,
@@ -1299,21 +1328,39 @@ async function previewAssets(ctx, refs) {
     return out;
 }
 /** The exact `model` ids `slates_generate_image` accepts. */
+/**
+ * The image models whose ladder includes the 3k (1440p) class — a MIRROR of
+ * `imageResolutions` in slate's MODEL_REGISTRY, which this package cannot read.
+ * Exported so `pricing-consistency-check.mjs` can prove the mirror still
+ * matches; without that proof a model that gains 3k in the registry just goes
+ * quietly unreachable through the op.
+ */
+export const THREE_K_IMAGE_MODELS = [
+    'gpt-image-2-5-flare',
+    'gpt-image-2-5-sunburst',
+    'seedream-5-lite',
+];
 export const IMAGE_MODELS = [
     'nano-banana-2',
     'nano-banana-2-lite',
     'nano-banana-pro',
-    'gpt-image-2',
+    'gpt-image-2-5-flare',
+    'gpt-image-2-5-sunburst',
     'flux-2-max',
     'seedream-5-lite',
 ];
+/** True for either GPT Image 2.5 seat. Flare and Sunburst differ in latency
+ *  and routing advice, never in pricing shape or param surface. */
+export function isGptImageModel(model) {
+    return model === 'gpt-image-2-5-flare' || model === 'gpt-image-2-5-sunburst';
+}
 /**
  * The aspect ratios an image generation can carry — the UNION over what these
  * models declare in `MODEL_CAPABILITIES`, generated so the enum cannot hold a
  * value no model accepts. It used to be a hand-typed eleven-value list whose
  * `9:21` exists in ZERO models; that phantom is gone by construction.
  *
- * ⚠️ STILL A UNION, NOT A PER-MODEL CHECK. `gpt-image-2` takes five of these
+ * ⚠️ STILL A UNION, NOT A PER-MODEL CHECK. GPT Image 2.5 takes five of these
  * ten and the other five would be accepted here. The image param surface has
  * not been audited (aspect ratios, resolution classes, per-model reference
  * caps) — that audit is the named follow-up in
@@ -1325,9 +1372,35 @@ const IMAGE_ASPECT_RATIOS = aspectRatioUnion(IMAGE_MODELS);
 // Registry cost-key for an image model+resolution. Mirrors imageCreditKey()
 // in slate/src/shared/pricing.ts — MUST byte-match it (the same hard rule as
 // videoCostKey): NB2/NB Pro price per resolution, FLUX.2 Max prices per
-// resolution (1k is the bare key), NB2 Lite/Seedream are flat, GPT Image 2 is
-// quality × resolution-class (med|high; low deliberately not exposed).
-function imageCostKey(model, resolution, quality = 'medium') {
+// resolution (1k is the bare key), NB2 Lite/Seedream are flat, GPT Image 2.5 is
+// quality × resolution-class over ALL FIVE exposed tiers.
+//
+// 🚨 THE KEY SUFFIX IS `med` WHILE THE WIRE VALUE IS `medium` — the one
+// tier name that differs between fal's enum and our cost keys, inherited from
+// GPT Image 2 (`gpt-image-2-med-4k`). `gptKeyTier` is that whole translation,
+// and it must stay byte-identical to `gptKeyTier` in
+// slate/src/shared/pricing.ts — pricing-consistency-check.mjs enforces it.
+function gptKeyTier(quality) {
+    return quality === 'medium' ? 'med' : quality;
+}
+// 🚨 THE ASPECT RATIO IS PART OF THE PRICE ON GPT IMAGE. fal bills image
+// OUTPUT TOKENS and the count tracks the frame's SHAPE — metered 2026-09-09,
+// 4:3/3:4 cost ~4/3 of the class rate and 1:1 ~16/9 of it. Quoting one price
+// for every aspect sold 1:1 below cost at `high` and above. Byte-identical to
+// `gptKeyAspect` in slate/src/shared/pricing.ts; pricing-consistency-check
+// proves it key by key. 16:9 and 9:16 keep the bare key they always had.
+function gptKeyAspect(aspectRatio) {
+    if (aspectRatio === '1:1')
+        return '-sq';
+    if (aspectRatio === '4:3' || aspectRatio === '3:4')
+        return '-43';
+    return '';
+}
+// EXPORTED for the same reason `videoCostKey` is: `pricing-consistency-check.mjs`
+// imports it and asserts, key by key, that it equals the desktop's
+// `imageCreditKey`. Before that check existed the byte-match was a comment and
+// a hope — the two are in different repos and nothing compared them.
+export function imageCostKey(model, resolution, quality = 'high', aspectRatio) {
     if (model === 'flux-2-max')
         return resolution === '1k' ? 'flux-2-max' : `flux-2-max-${resolution}`;
     if (model === 'seedream-5-lite')
@@ -1336,8 +1409,8 @@ function imageCostKey(model, resolution, quality = 'medium') {
         return 'nano-banana-2-lite';
     if (model === 'nano-banana-pro')
         return `nano-banana-pro-${resolution}`;
-    if (model === 'gpt-image-2')
-        return `gpt-image-2-${quality === 'high' ? 'high' : 'med'}-${resolution}`;
+    if (isGptImageModel(model))
+        return `${model}-${gptKeyTier(quality)}-${resolution}${gptKeyAspect(aspectRatio)}`;
     return `nano-banana-2-${resolution}`;
 }
 export const generateImage = {
@@ -1349,9 +1422,9 @@ export const generateImage = {
         // (it still described nano-banana-2-lite by a capability the param owns).
         `${describeRouting('image')}\n` +
         'Full table: the slates-model-selection skill. ' +
-        'Pass projectId to save into a Slates project (recommended — asset appears live in the desktop UI). All models except nano-banana-2 REQUIRE projectId (no headless path). REQUIRED before calling: read the slates-cost-discipline skill (and the model\'s slates-prompting-* skill). You MUST pass aspectRatio and resolution explicitly (the server returns requires_clarification when missing — defaults waste credits). ' +
+        '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). ' +
         CONFIRM_GATE_SENTENCE +
-        ' MCP/CLI generation always charges credits. No skill files installed? Call slates_get_prompting_guide with the model\'s topic (and \'slates-cost-discipline\') before first use. ' +
+        ' MCP/CLI generation always charges credits. No skills installed? Call slates_get_prompting_guide with the model\'s topic and \'slates-cost-discipline\' first. ' +
         // 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.
@@ -1360,12 +1433,13 @@ export const generateImage = {
         prompt: z.string().min(1).max(4000),
         model: zEnum(IMAGE_MODELS).optional().describe('Image model. Default nano-banana-2. Routing doctrine: slates-model-selection skill. All except nano-banana-2 require projectId.'),
         projectId: z.string().uuid().optional().describe('Save into this Slates project. Renderer refreshes live. Required for every model except nano-banana-2.'),
-        resolution: z.enum(['1k', '2k', '3k', '4k']).optional().describe('Pick deliberately: 1k drafts, 2k hero shots, 4k print/final. nano-banana-2-lite is 1k-only. gpt-image-2 classes: 1k=1024², 2k=1080p, 3k=1440p, 4k=2160p (3k is gpt-image-2 only). Never default this.'),
-        quality: z.enum(['medium', 'high']).optional().describe('gpt-image-2 only. medium (default) = sharp text, fast, the value seat; high = max text precision + reasoning at ~4× the price. Ignored by other models.'),
-        aspectRatio: zEnum(IMAGE_ASPECT_RATIOS).optional().describe(`Pick deliberately from the use case. Cinematic → 16:9. TikTok/Reels/Story → 9:16. IG square → 1:1. Ultra-wide → 21:9. Ask the user when ambiguous. Per model: ${describeAspectRatios(IMAGE_MODELS)}`),
-        count: z.number().int().min(1).max(4).optional(),
-        referenceImageUrls: z.array(z.string().url()).max(14).optional().describe('Headless (no-projectId) nano-banana-2 only: up to 14 ref URLs. For projectId runs, upload refs with slates_upload_reference_image first. Always label each image\'s role in the prompt text.'),
-        referenceAssetIds: z.array(z.string()).max(14).optional().describe("Project assets to use as reference/ingredient images — asset UUIDs or badge codes (\"IMG-A8\"); codes resolve against the project at call time. Requires projectId. For nano-banana-2 up to 14 refs; FLUX/Seedream route to their edit endpoints with lower per-model caps. Label each reference's role in the prompt text."),
+        resolution: z.enum(['1k', '2k', '3k', '4k']).optional().describe('1k drafts, 2k hero, 4k final. nano-banana-2-lite: 1k only. GPT Image classes 1024²/1080p/1440p/2160p. Never default this.'),
+        quality: z.enum(['low', 'medium', 'high', 'xhigh', 'max']).optional().describe('GPT Image only. UNEVEN ladder: max=4× high, xhigh~1.8×. medium drafts; default high.'),
+        backgroundMode: z.enum(['auto', 'transparent', 'opaque']).optional().describe('GPT Image only. transparent = alpha channel. Free.'),
+        aspectRatio: zEnum(IMAGE_ASPECT_RATIOS).optional().describe(`Pick from the use case: cinematic 16:9 · TikTok/Reels 9:16 · IG square 1:1 · ultra-wide 21:9. 1:1 costs most on GPT Image. Per model: ${describeAspectRatios(IMAGE_MODELS)}`),
+        count: z.number().int().min(1).max(10).optional().describe('Up to 10 with projectId; headless caps at 4.'),
+        referenceImageUrls: z.array(z.string().url()).max(14).optional().describe('Headless (no projectId) nano-banana-2 only. With a projectId, upload via slates_upload_reference_image. Label every image role in the prompt.'),
+        referenceAssetIds: z.array(z.string()).max(16).optional().describe("Project assets as references — UUIDs or badge codes (\"IMG-A8\"), resolved at call time. Requires projectId. Caps: GPT Image 16, nano-banana-2 14, FLUX/Seedream lower. Label every reference role in the prompt."),
         background: z.boolean().optional().describe(BACKGROUND_DESCRIBE),
         confirm: z.boolean().optional().describe('Set true to bypass the confirm gate.'),
     }),
@@ -1398,13 +1472,24 @@ export const generateImage = {
         }
         const resolution = input.resolution;
         const imageModel = input.model ?? 'nano-banana-2';
-        // The '3k' class exists only on gpt-image-2 (2560×1440); other models
-        // would mis-key the registry lookup.
-        if (resolution === '3k' && imageModel !== 'gpt-image-2') {
+        // 🚨 SEEDREAM HAS A 3k CLASS TOO, AND THIS GUARD USED TO DENY IT.
+        // It read `!== 'gpt-image-2'` and rejected every other model at 3k — but
+        // `seedream-5-lite` declares ['2k','3k','4k'] in the desktop registry and
+        // has a real `seedream-5-lite` cost key, so the op was refusing a request
+        // the desktop would have served. Pre-existing; found by the 2026-09-09
+        // audit, not introduced by the 2.5 swap.
+        //
+        // The ladder itself is owned by MODEL_REGISTRY in slate/src/shared/pricing.ts
+        // and is not readable from here, so THREE_K_IMAGE_MODELS is a MIRROR — declared
+        // and exported below so `pricing-consistency-check.mjs` compares it against
+        // the desktop registry's own `imageResolutions`. It used to be an inline
+        // literal with a comment admitting nothing checked it, which is how it came
+        // to deny `seedream-5-lite` a class the desktop had always served.
+        if (resolution === '3k' && !THREE_K_IMAGE_MODELS.includes(imageModel)) {
             return ok({
                 requires_clarification: true,
                 missing: ['resolution'],
-                message: `3k (1440p) is a gpt-image-2 resolution class — pick 1k/2k/4k for ${imageModel}.`,
+                message: `3k (1440p) exists on ${THREE_K_IMAGE_MODELS.join(', ')} — pick 1k/2k/4k for ${imageModel}.`,
             });
         }
         // Only nano-banana-2 has a headless path — everything else routes through
@@ -1435,6 +1520,18 @@ export const generateImage = {
                 message: 'background=true routes through the desktop generation pipeline (so slates_get_generation_status can poll it) — pass a projectId, or drop background for a blocking headless run.',
             });
         }
+        // 🚨 THE HEADLESS PATH ASKS FAL FOR A BATCH, so a provider ceiling binds
+        // here and nowhere else. It is nano-banana-2 only, and Nano Banana's
+        // `num_images` maximum is 4 (fal schema, 2026-09-09). Refused rather than
+        // clamped: a silent clamp would make four images against a request for ten
+        // and read to the caller as a partial failure it should retry.
+        if (!input.projectId && (input.count ?? 1) > 4) {
+            return ok({
+                requires_clarification: true,
+                missing: ['projectId'],
+                message: 'count above 4 needs a projectId. The headless path asks fal for one batch and nano-banana-2 caps a batch at 4; with a projectId the desktop fires them as separate generations and the limit is 10.',
+            });
+        }
         let refEcho = '';
         if (referenceAssetIds.length > 0) {
             await ctx.desktop().requireCapability('image-references', 'reference images on image generation');
@@ -1451,11 +1548,18 @@ export const generateImage = {
         // New-roster models need a desktop that knows them — an older desktop's
         // allowlist would silently fall back to nano-banana-2 while we quote the
         // new model's price.
-        if (input.projectId &&
-            (imageModel === 'gpt-image-2' || imageModel === 'nano-banana-pro' || imageModel === 'nano-banana-2-lite')) {
+        if (input.projectId && isGptImageModel(imageModel)) {
+            // 🚨 v3, NOT v2. GPT Image 2.5 landed 2026-09-09 with new ids and a
+            // five-rung ladder; a desktop that only knows v2 has neither, so it would
+            // fall back to nano-banana-2 while this op quotes a 2.5 price — precisely
+            // the failure the gate was built to stop. Reusing v2 reintroduces it.
+            await ctx.desktop().requireCapability('image-models-v3', `${imageModel} generation`);
+        }
+        else if (input.projectId &&
+            (imageModel === 'nano-banana-pro' || imageModel === 'nano-banana-2-lite')) {
             await ctx.desktop().requireCapability('image-models-v2', `${imageModel} generation`);
         }
-        const costKey = imageCostKey(imageModel, resolution, input.quality ?? 'medium');
+        const costKey = imageCostKey(imageModel, resolution, input.quality, input.aspectRatio ?? '1:1');
         const cloud = ctx.cloud();
         const registry = await cloud.get('/api/agent/models');
         const entry = registry.models.find((m) => m.model === costKey);
@@ -1524,7 +1628,7 @@ export const generateImage = {
                 resolution,
                 aspectRatio: input.aspectRatio ?? '1:1',
                 count: input.count ?? 1,
-                ...(imageModel === 'gpt-image-2' ? { gptQuality: input.quality ?? 'medium' } : {}),
+                ...(isGptImageModel(imageModel) ? { gptQuality: input.quality, gptBackground: input.backgroundMode } : {}),
                 ...(referenceAssetIds.length > 0 ? { referenceAssetIds } : {}),
                 background: input.background,
             });
@@ -1617,6 +1721,13 @@ export const generateImage = {
             params: {
                 prompt: input.prompt,
                 aspect_ratio: input.aspectRatio ?? '1:1',
+                // 🚨 THE HEADLESS PATH IS THE ONE PLACE WE ASK FAL FOR A BATCH, so it
+                // is the one place a provider's own `num_images` ceiling binds — and
+                // Nano Banana's is 4 (fal schema, read 2026-09-09), against the op's
+                // limit of 10. Everything else fans out through the desktop as N
+                // separate single-image generations, where no batch ceiling exists.
+                // Guarded above rather than clamped here: silently making 4 when 10
+                // were asked for would bill 4 and look like a partial failure.
                 num_images: input.count ?? 1,
                 ...(hasReferenceImages
                     ? { image_urls: input.referenceImageUrls }
@@ -1687,15 +1798,16 @@ async function pollProxyJob(cloud, jobId, options = {}) {
 export const editImage = {
     id: 'slates_edit_image',
     billable: true,
-    description: 'Surgically edit an existing image asset with a text instruction (e.g. \'remove the lamppost\', \'make the jacket red\') instead of regenerating from scratch — use when ~90% of the image is already right. The edited result is saved as a NEW asset in the project (prompt prefixed \'[Edit]\'); the source is untouched. Default model nano-banana-2 (only model that also accepts referenceAssetIds); flux-2-max / seedream-5-lite use their own edit endpoints and ignore references. Before first use call slates_get_prompting_guide with topic \'slates-edit-and-iterate\'.',
+    description: 'Surgically edit an image asset with a text instruction (e.g. \'make the jacket red\') instead of regenerating from scratch — use when ~90% of the image is already right. The result is a NEW asset (prompt prefixed \'[Edit]\'); the source is untouched. Default model nano-banana-2 (only model that also accepts referenceAssetIds); flux-2-max / seedream-5-lite use their own edit endpoints and ignore references. Before first use call slates_get_prompting_guide with topic \'slates-edit-and-iterate\'.',
     input: z.object({
         projectId: z.string().uuid(),
-        sourceAssetId: z.string().uuid().describe('Image asset to edit. Must already exist in the project.'),
-        prompt: z.string().min(1).max(4000).describe('The edit instruction — describe the change, not the whole image.'),
-        editModel: z.enum(['nano-banana-2', 'nano-banana-2-lite', 'nano-banana-pro', 'gpt-image-2', 'flux-2-max', 'seedream-5-lite']).optional(),
-        referenceAssetIds: z.array(z.string().uuid()).max(13).optional().describe('Nano-Banana family only: extra reference images (NB Pro takes up to 13, NB2 Lite up to 3).'),
-        resolution: z.enum(['1k', '2k', '3k', '4k']).optional().describe('3k (1440p class) is gpt-image-2 only; nano-banana-2-lite is 1k only.'),
-        quality: z.enum(['medium', 'high']).optional().describe('gpt-image-2 only — quality tier (default medium).'),
+        sourceAssetId: z.string().uuid().describe('Image asset to edit. Must exist in the project.'),
+        prompt: z.string().min(1).max(4000).describe('The change, not the whole image.'),
+        editModel: z.enum(['nano-banana-2', 'nano-banana-2-lite', 'nano-banana-pro', 'gpt-image-2-5-flare', 'gpt-image-2-5-sunburst', 'flux-2-max', 'seedream-5-lite']).optional(),
+        referenceAssetIds: z.array(z.string().uuid()).max(13).optional().describe('Nano-Banana only (NB Pro 13, NB2 Lite 3).'),
+        resolution: z.enum(['1k', '2k', '3k', '4k']).optional().describe('3k = GPT Image/seedream-5-lite; nano-banana-2-lite is 1k only.'),
+        quality: z.enum(['low', 'medium', 'high', 'xhigh', 'max']).optional().describe('GPT Image tier; default high.'),
+        backgroundMode: z.enum(['auto', 'transparent', 'opaque']).optional().describe('GPT Image only. transparent = alpha channel. Free.'),
         aspectRatio: z.string().optional(),
         confirm: z.boolean().optional().describe('Set true to bypass the confirm gate.'),
         background: z.boolean().optional().describe(BACKGROUND_DESCRIBE),
@@ -1708,14 +1820,22 @@ export const editImage = {
         }
         const editModel = input.editModel ?? 'nano-banana-2';
         const resolution = input.resolution ?? (editModel === 'nano-banana-2-lite' ? '1k' : '2k');
-        if ((editModel === 'gpt-image-2' || editModel === 'nano-banana-pro' || editModel === 'nano-banana-2-lite')) {
+        if (isGptImageModel(editModel)) {
+            // 🚨 v3, LIKE generateImage — this site was missed once already.
+            // A pre-2.5 desktop advertises v2, so gating the 2.5 seats on v2 lets it
+            // through; `isFalImageModel` is then false for these ids on that build and
+            // handleEditImage falls through to the nano-banana path — NB2 output billed
+            // at a quoted 2.5 price. Exactly the bug the gate exists to stop.
+            await desktop.requireCapability('image-models-v3', `${editModel} editing`);
+        }
+        else if (editModel === 'nano-banana-pro' || editModel === 'nano-banana-2-lite') {
             await desktop.requireCapability('image-models-v2', `${editModel} editing`);
         }
-        // Nano-Banana family + GPT Image 2 edits charge the same key as gen;
+        // Nano-Banana family + GPT Image 2.5 edits charge the same key as gen;
         // FLUX / Seedream route to dedicated edit endpoints priced under '-edit' keys.
         const costKey = editModel === 'flux-2-max' || editModel === 'seedream-5-lite'
             ? `${imageCostKey(editModel, resolution)}-edit`
-            : imageCostKey(editModel, resolution, input.quality ?? 'medium');
+            : imageCostKey(editModel, resolution, input.quality, input.aspectRatio);
         const cloud = ctx.cloud();
         const registry = await cloud.get('/api/agent/models');
         const entry = registry.models.find((m) => m.model === costKey);
@@ -1742,7 +1862,7 @@ export const editImage = {
             editModel,
             referenceAssetIds: input.referenceAssetIds,
             resolution,
-            ...(editModel === 'gpt-image-2' ? { gptQuality: input.quality ?? 'medium' } : {}),
+            ...(isGptImageModel(editModel) ? { gptQuality: input.quality, gptBackground: input.backgroundMode } : {}),
             aspectRatio: input.aspectRatio,
             background: input.background,
         });
@@ -2727,14 +2847,68 @@ export const generateVideo = {
         };
     },
 };
+// ── The preset voice shelf ──────────────────────────────────────
+/**
+ * AGENT PARITY for the voice picker. The desktop browses stock voices by
+ * gender, accent and age and plays each one; until this op the agent could
+ * only pass a `voiceId` it had no way to discover. Disk reads on the desktop,
+ * never a vendor call — browsing is free on every surface.
+ */
+export const listVoices = {
+    id: 'slates_list_voices',
+    description: `Browse ${TTS_MODEL} preset voices. Pass a returned voiceId to slates_generate_audio. Filters AND together.`,
+    input: z.object({
+        gender: z.string().optional().describe('male | female'),
+        accent: z.string().optional().describe('Region ("GB") or languageCode ("en-GB"); available accents come from the shelf.'),
+        age: z.string().optional().describe('young | middle_aged | elderly'),
+        query: z.string().optional().describe('Free text over name, description, tags.'),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('voices', 'the preset voice shelf');
+        const shelf = await desktop.get('/agent/voices');
+        if (!shelf.available) {
+            return ok({ available: false, voices: [], message: 'This desktop build shipped without the preset shelf.' });
+        }
+        const terms = (input.query ?? '').toLowerCase().split(/\s+/).filter(Boolean);
+        const region = input.accent?.includes('-') ? input.accent.split('-')[1] : input.accent;
+        const voices = shelf.voices
+            .filter((v) => !input.gender || v.gender === input.gender)
+            .filter((v) => !region || v.languageCode.split('-')[1]?.toUpperCase() === region.toUpperCase())
+            .filter((v) => !input.age || v.ageGroup === input.age)
+            .filter((v) => {
+            if (terms.length === 0)
+                return true;
+            const hay = [v.displayName, v.description, v.gender, v.ageGroup, v.languageCode, ...(v.tags ?? [])]
+                .join(' ')
+                .toLowerCase();
+            return terms.every((t) => hay.includes(t));
+        })
+            .map(({ voiceId, displayName, description, tags, gender, ageGroup, languageCode }) => ({
+            voiceId,
+            displayName,
+            description,
+            tags,
+            gender,
+            ageGroup,
+            languageCode,
+        }));
+        return ok({
+            available: true,
+            line: shelf.line,
+            count: voices.length,
+            voices,
+            next: `Pass a voiceId to slates_generate_audio (model ${TTS_MODEL}) as voiceId. To keep one on a character for reuse, generate a clip with it and set slates_update_character voiceAssetId.`,
+        });
+    },
+};
 // ── Generate audio ──────────────────────────────────────────────
 export const generateAudio = {
     id: 'slates_generate_audio',
     billable: true,
-    description: 'Generate AUDIO via Slates credits — the third media type, saved as a project asset you can drop on an audio track. Three surfaces: seed-audio (default; a whole audio SCENE — dialogue + SFX + ambience — from one plain sentence, 3-120s), eleven-sfx (ONE effect with an exact 1-22s duration, or a seamless loop), and inworld-tts-2 (one named voice saying one line; the prompt IS the words, billed per character). Which surface for which job: read the slates-model-selection skill. ' +
-        '🚨 seed-audio has NO duration parameter — the length you pass is written INTO THE PROMPT and is what the user is BILLED, whatever comes back. Choose it deliberately. ' +
-        'REQUIRED before calling: read slates-cost-discipline and the matching prompting skill (slates-prompting-seed-audio | slates-prompting-elevenlabs | slates-prompting-inworld-tts). Kling\'s "SFX:" / "Ambient noise:" prompt syntax does NOT transfer to seed-audio and makes results worse. ' +
-        'projectId is REQUIRED (no headless path). ' +
+    description: `Generate project audio using credits. Choose the surface via the model routing below. ` +
+        'Read slates-cost-discipline and the matching prompting skill first (slates-prompting-seed-audio | slates-prompting-elevenlabs | slates-prompting-inworld-tts). ' +
+        'Seed Audio bills the requested duration, which is appended to the prompt regardless of output length. Kling "SFX:" / "Ambient noise:" syntax does not transfer. ' +
         CONFIRM_GATE_SENTENCE +
         ' No skill files installed? Call slates_get_prompting_guide first.',
     input: z.object({
@@ -2753,25 +2927,27 @@ export const generateAudio = {
         durationSeconds: z
             .number()
             .optional()
-            .describe('seed-audio 3-120 (default 15) — ⚠️ THIS IS THE BILL: it is appended to the prompt and charged regardless of the returned length. eleven-sfx 1-22 (default 4) — always sent explicitly so the per-second charge is deterministic.'),
+            .describe(`seed-audio ${SEED_AUDIO_MIN_SECONDS}-${SEED_AUDIO_MAX_SECONDS} (default ${SEED_AUDIO_DEFAULT_SECONDS}) — ⚠️ THIS IS THE BILL: appended to the prompt and charged whatever comes back. eleven-sfx ${ELEVEN_SFX_MIN_SECONDS}-${ELEVEN_SFX_MAX_SECONDS} (default ${ELEVEN_SFX_DEFAULT_SECONDS}) — always sent explicitly so the per-second charge is deterministic. Not for ${TTS_MODEL}.`),
         voice: z
             .string()
             .optional()
-            .describe('seed-audio only — a preset voice id (e.g. "cedric_en_zh"). Leave unset to let the scene cast itself, which is usually right for background dialogue. Agent-facing only: there is no user-facing voice picker.'),
+            .describe('seed-audio only — a preset voice id (e.g. "cedric_en_zh"). Leave unset to let the scene cast itself. Agent-facing only.'),
         voiceId: z
             .string()
             .optional()
-            .describe('inworld-tts-2 — the voice to speak in. One of these three is required there.'),
+            .describe(`${TTS_MODEL} — a preset voiceId from slates_list_voices, not a character or asset id. Exactly one voice source is required.`),
         voiceReferenceAssetId: z
             .string()
             .optional()
-            .describe('inworld-tts-2 — clone the voice from this AUDIO asset (5-15s of one clean speaker).'),
+            .describe(`${TTS_MODEL} — clone this AUDIO asset's voice for the take (${TTS_VOICE_CLONE.minSeconds}-${TTS_VOICE_CLONE.maxSeconds}s, one clean speaker). To speak AS a character pass its voiceAssetId. Cloning: ${TTS_VOICE_CLONE.clonesPerMinute} new voices/min across all of Slates; a burst waits.`),
         voiceDescription: z
             .string()
+            .min(TTS_VOICE_CLONE.designPromptChars.min)
+            .max(TTS_VOICE_CLONE.designPromptChars.max)
             .optional()
-            .describe('inworld-tts-2 — build a voice from this description, for a character with no recording.'),
+            .describe(`${TTS_MODEL} — a voice from words (${TTS_VOICE_CLONE.designPromptChars.min}-${TTS_VOICE_CLONE.designPromptChars.max} chars) for a character with no recording; keep it via slates_update_character voiceAssetId.`),
         speed: z.number().min(0.5).max(2).optional().describe('seed-audio only — 0.5-2.0. Reach for it when dialogue races or drags against picture.'),
-        volume: z.number().min(0.5).max(2).optional().describe('seed-audio only — output gain, 0.5-2.0 (1 = unchanged). Prefer the timeline track fader for mix decisions; this is for when the model itself renders a scene too hot or too quiet.'),
+        volume: z.number().min(0.5).max(2).optional().describe('seed-audio only — output gain, 0.5-2.0 (1 = unchanged). Prefer the timeline fader for mix decisions.'),
         pitch: z.number().int().min(-12).max(12).optional().describe('seed-audio only — semitones. Small moves; ±3 is already a lot.'),
         multilingual: z.boolean().optional().describe('seed-audio only — better non-English / mixed-language handling.'),
         loop: z.boolean().optional().describe('eleven-sfx only — produce a seamless loop (rain, engine hum, crowd murmur).'),
@@ -2780,7 +2956,7 @@ export const generateAudio = {
             .array(z.string())
             .max(3)
             .optional()
-            .describe('seed-audio only — up to 3 AUDIO assets (UUIDs or badge codes like "AUD-S1"), each ≤30s, referenced in the prompt as @Audio1-@Audio3 ("match the room tone of @Audio1"). MUTUALLY EXCLUSIVE with imageReferenceAssetId — the API rejects both.'),
+            .describe('seed-audio only — up to 3 AUDIO assets (UUIDs or badge codes like "AUD-S1"), each ≤30s, referenced in the prompt as @Audio1-@Audio3 ("match the room tone of @Audio1"). MUTUALLY EXCLUSIVE with imageReferenceAssetId.'),
         imageReferenceAssetId: z
             .string()
             .optional()
@@ -2823,7 +2999,7 @@ export const generateAudio = {
                 return ok({
                     requires_clarification: true,
                     missing: ['voiceId'],
-                    message: `${TTS_MODEL} needs a voice. Ask the user WHICH CHARACTER is speaking and pass that character's voice as voiceId — a voice is a field on a character, not a thing to pick at generation time. To make a NEW voice, pass voiceReferenceAssetId (a clip to clone) or voiceDescription (words, for a character with no recording).`,
+                    message: `${TTS_MODEL} needs a voice — exactly one of three. Speaking AS a character: pass its voiceAssetId (slates_list_characters) as voiceReferenceAssetId. A stock voice: slates_list_voices lists presets by gender, accent and age; pass one's voiceId. No recording of the voice: voiceDescription (words), or voiceReferenceAssetId with any clean clip of one speaker. A voice worth reusing can be kept on a character with slates_update_character, but nothing requires that — ask the user which they want only when the request does not say.`,
                 });
             }
             if (voiceSources.length > 1) {
@@ -3725,17 +3901,33 @@ export const setFolderCover = {
 };
 export const updateCharacter = {
     id: 'slates_update_character',
-    description: 'Update a character\'s name, description, or style. Use slates_set_character_identity_asset for its canonical image.',
+    description: 'Update a character\'s name, description, style, or voice. Use slates_set_character_identity_asset for its canonical image.',
     input: z.object({
         characterId: z.string().uuid(),
         name: z.string().min(1).max(120).optional(),
         description: z.string().optional(),
         style: z.string().max(200).optional().describe("Art style. Omit to inherit the reference's style (the default). Canonical styles: photoreal, anime, painterly, 3d-render, comic. Or pass any free-text instruction, e.g. 'turn this into a real person'."),
+        // Agent parity for the character card's voice slot: the desktop route has
+        // taken this since 2026-08-28; the op never exposed it, so an agent could
+        // render a voice and had no way to keep it on the character.
+        voiceAssetId: z
+            .string()
+            .uuid()
+            .nullable()
+            .optional()
+            .describe("The AUDIO asset that is this character's voice (what inworld-tts-2 clones for its lines); null detaches, the clip stays."),
     }),
     async run(input, ctx) {
         return ok(await ctx.desktop().post('/agent/characters/update', {
             id: input.characterId,
-            data: { name: input.name, description: input.description, style: input.style },
+            data: {
+                name: input.name,
+                description: input.description,
+                style: input.style,
+                // Sent only when given: the route treats presence as intent, and an
+                // explicit null is the detach.
+                ...(input.voiceAssetId !== undefined ? { voiceAssetId: input.voiceAssetId } : {}),
+            },
         }));
     },
 };
@@ -4021,16 +4213,22 @@ const SHOT_ASPECT_RATIOS = [...new Set([...VIDEO_ASPECT_RATIOS, ...IMAGE_ASPECT_
 function shotParamsShape(described) {
     const d = (node, text) => (described ? node.describe(text) : node);
     return {
-        aspectRatio: d(zEnum(SHOT_ASPECT_RATIOS).optional(), 'Validated against the chosen model when the Shot is saved — see slates_generate_video for the per-model sets.'),
-        duration: d(z.number().int().min(1).max(360).optional(), 'Seconds — video or audio. Required before a video Shot can be priced or fired; validated against the model when saved.'),
-        videoResolution: d(zEnum(VIDEO_RESOLUTIONS).optional(), 'Validated against the chosen model when the Shot is saved.'),
+        aspectRatio: d(zEnum(SHOT_ASPECT_RATIOS).optional(), 'Validated against the model; see slates_generate_video.'),
+        duration: d(z.number().int().min(1).max(360).optional(), 'Seconds for video or duration-based audio; TTS uses text length.'),
+        videoResolution: d(zEnum(VIDEO_RESOLUTIONS).optional(), 'Validated against the model when the Shot is saved.'),
         imageResolution: d(z.enum(['1k', '2k', '3k', '4k']).optional(), 'Image models only.'),
-        gptQuality: d(z.enum(['medium', 'high']).optional(), 'gpt-image-2 only.'),
-        imageQuantity: d(z.number().int().min(1).max(4).optional(), 'Image models only — how many to make per fire.'),
+        gptQuality: d(z.enum(['low', 'medium', 'high', 'xhigh', 'max']).optional(), 'GPT Image 2.5 only.'),
+        gptBackground: d(z.enum(['auto', 'transparent', 'opaque']).optional(), 'GPT Image only.'),
+        imageQuantity: d(z.number().int().min(1).max(10).optional(), 'Image models only.'),
         negativePrompt: z.string().optional(),
         sound: d(z.boolean().optional(), 'Video models that co-generate audio.'),
-        seedanceFace: d(z.boolean().optional(), "Seedance only — a reference shows an AI character's FACE; reroutes to a face-capable provider at ~45% more."),
+        seedanceFace: d(z.boolean().optional(), "Seedance only — a reference shows an AI character's FACE; reroutes to a face-capable provider, ~45% more."),
         audioDurationSeconds: d(z.number().int().min(1).max(120).optional(), 'Audio lane. On seed-audio the requested duration IS the bill.'),
+        // The TTS voice — the same three fields slates_generate_audio takes, so a
+        // Shot is the audio call, serialized. Exactly one of them, enforced at fire.
+        voiceId: d(z.string().optional(), `${TTS_MODEL}: preset voiceId (slates_list_voices).`),
+        voiceReferenceAssetId: d(z.string().optional(), `${TTS_MODEL}: audio asset to clone.`),
+        voiceDescription: d(z.string().optional(), `${TTS_MODEL}: the voice in words.`),
     };
 }
 const shotParamsSchema = z.object(shotParamsShape(true)).optional();
@@ -4047,10 +4245,7 @@ const shotParamsSchemaTerse = z
  * ship a field with no explanation — the same failure as a column nothing
  * renders.
  *
- * 🚨 AND NONE OF THEM IS SENT TO A MODEL. They are a planning and counting
- * surface; the prompt is the only thing the request carries. The one exception
- * is pre-existing: a multiShotSegment still prepends its own camera and
- * shotSize to its own segment prompt.
+ * Script fields supply prompt prose when no authored prompt exists (shot-spec.ts).
  */
 function shotScriptShape(described) {
     const text = Object.fromEntries(SCRIPT_TEXT_FIELDS.map((field) => [
@@ -4151,6 +4346,8 @@ function shotRefInputs(input) {
         out.push({ ref: input.firstFrameAssetId, role: 'first frame' });
     if (input.lastFrameAssetId)
         out.push({ ref: input.lastFrameAssetId, role: 'last frame' });
+    if (input.params?.voiceReferenceAssetId)
+        out.push({ ref: input.params.voiceReferenceAssetId, role: 'voice reference' });
     return out;
 }
 /**
@@ -4187,7 +4384,10 @@ async function buildShotSpecInput(ctx, projectId, input) {
             // later diverges from it and the desktop card says so — the prompt is
             // never rewritten (that is prompt enhancement, deleted 2026-08-01).
             authoredFor: input.model ?? null,
-            params: shotParamsPatch(input.params),
+            params: {
+                ...shotParamsPatch(input.params),
+                ...(input.params?.voiceReferenceAssetId ? { voiceReferenceAssetId: rid(input.params.voiceReferenceAssetId) } : {}),
+            },
             mentions: {
                 characterIds: input.characterIds ?? [],
                 environmentIds: input.environmentIds ?? [],
@@ -4240,12 +4440,12 @@ function shotCostKey(detail) {
     // has none, so it falls back to the raw ones and is announced as a floor.
     const fires = detail.firesWith;
     if (AUDIO_MODELS.includes(model)) {
-        // The TTS seat prices on the TEXT, and a Shot carries no text field — so a
-        // Shot cannot be a TTS generation and cannot be quoted as one. Explicit,
-        // because the `!seconds` line below would also return null here and that
-        // would read as "duration missing" for a surface that has no duration.
-        if (model === TTS_MODEL)
-            return null;
+        if (model === TTS_MODEL) {
+            const text = detail.composedPrompt ?? (detail.rawPrompt.trim() || detail.line?.trim() || '');
+            if (!text || text.length > TTS_MAX_CHARACTERS)
+                return null;
+            return audioCostKey({ model, characters: text.length });
+        }
         const seconds = fires?.audioDurationSeconds ?? p.audioDurationSeconds;
         if (!seconds)
             return null;
@@ -4275,7 +4475,15 @@ function shotCostKey(detail) {
     }
     if (IMAGE_MODELS.includes(model)) {
         return imageCostKey(model, (fires?.imageResolution ?? p.imageResolution) ??
-            (model === 'nano-banana-2-lite' ? '1k' : '2k'), p.gptQuality ?? 'medium');
+            (model === 'nano-banana-2-lite' ? '1k' : '2k'), 
+        // No inline default — see the note at the estimate op. Firing a Shot with
+        // no stored tier lands on `high` via the desktop's `normalizeGptQuality`,
+        // and `imageCostKey`'s parameter default is pinned to match it.
+        p.gptQuality, 
+        // The aspect the Shot will fire at — on GPT Image it moves the key, so
+        // quoting without it under-prices every square Shot. `fires` carries
+        // only the clamped resolution/duration axes, never the aspect.
+        p.aspectRatio);
     }
     return null;
 }
@@ -4453,8 +4661,17 @@ export const duplicateShot = {
             spec.prompt = input.prompt;
         if (input.model !== undefined)
             spec.model = input.model;
-        if (input.params !== undefined)
-            spec.params = shotParamsPatch(input.params);
+        if (input.params !== undefined) {
+            const voiceRef = input.params.voiceReferenceAssetId;
+            if (voiceRef && !UUID_RE.test(voiceRef)) {
+                const { shot } = await desktop.get('/agent/shots/get', { id: input.shotId });
+                const built = await buildShotSpecInput(ctx, shot.projectId, { params: input.params });
+                spec.params = built.spec.params;
+            }
+            else {
+                spec.params = shotParamsPatch(input.params);
+            }
+        }
         const r = await desktop.post('/agent/shots/duplicate', {
             id: input.shotId,
             name: input.name,
@@ -4715,7 +4932,7 @@ export const generateFromShots = {
                     // something to try again spends credits before anyone notices.
                     `\n${failedLines.join('\n')}\nThese were NOT retried. Read each error, fix the Shot, and re-fire only what you meant to.`
                 : '') +
-            ` ${VIDEO_REVIEW_POINTER}`);
+            ` ${BACKGROUND_REVIEW_POINTER}`);
     },
 };
 function resolveGuideTopic(topic) {
@@ -4763,7 +4980,7 @@ function resolveGuideTopic(topic) {
     if (t.startsWith('nano-banana'))
         return 'slates-prompting-nano-banana-2';
     if (t.startsWith('gpt-image') || t.startsWith('gpt image'))
-        return 'slates-prompting-gpt-image-2';
+        return 'slates-prompting-gpt-image-2-5';
     if (t.startsWith('flux'))
         return 'slates-prompting-flux-2-max';
     if (t.startsWith('seedream'))
@@ -4855,7 +5072,7 @@ function resolveGuideTopic(topic) {
  * 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 2, MiniMax H3, LTX-2.5, Seedance 2.5 and Omni Flash were
+ * 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.
@@ -4874,15 +5091,16 @@ function describeGuideTopics() {
 }
 export const getPromptingGuide = {
     id: 'slates_get_prompting_guide',
-    description: 
-    // 🚨 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: 'For app help and exact UI instructions use topic "app-manual" with a query such as "voice recording". This returns the canonical product manual, shared by every agent surface. ' +
+        // 🚨 NO "ALWAYS READ THIS FIRST" SENTENCE. It stood here for months and was
+        // MEASURED at 13% compliance before and after the enforcement work — pointer
+        // prose is the shape that does not move the agent. What replaced it is
+        // structural: the never-use list rides the generate ops' descriptions and
+        // the craft card rides the estimate result, so the facts arrive whether or
+        // not this op is ever called.
+        "Return a bundled Slates prompting/workflow guide. MCP-only clients (Claude Desktop, Smithery) don't get the CLI-installed skill files — call this instead. Accepts a guide name or a model id ('veo-3.1-fast', 'kling-v3.0-pro', 'seedance-2', 'nano-banana-2'), which maps to the right guide. Reach for it when a card is not enough: the failure modes, the worked examples and the sources are only in the full text.",
     input: z.object({
+        query: z.string().max(200).optional().describe('For app-manual: keywords to retrieve relevant UI sections. Omit for the entire manual.'),
         topic: z
             .string()
             .min(1)
@@ -4890,6 +5108,10 @@ export const getPromptingGuide = {
         depth: z.enum(['card', 'full']).optional().describe('"card" returns just the levers block (a few hundred words — the same card slates_estimate_generation_cost already attached, so usually redundant). "full" (default) returns the whole guide, up to several thousand words.'),
     }),
     async run(input) {
+        if (input.topic.trim().toLowerCase() === 'app-manual') {
+            const content = appManualSections(input.query);
+            return { text: content, data: { topic: 'app-manual', bytes: Buffer.byteLength(content, 'utf8') } };
+        }
         const resolved = resolveGuideTopic(input.topic);
         const content = resolved ? SKILLS[resolved] : undefined;
         if (!resolved || content === undefined) {
@@ -5124,6 +5346,7 @@ export const ALL_OPERATIONS = [
     generateImage,
     generateVideo,
     generateAudio,
+    listVoices,
     generateLipSync,
     generateMotionTransfer,
     editVideo,