@slatesvideo/shared 0.6.5 → 0.6.6

package/dist/operations/index.js

@@ -211,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
@@ -502,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).'),
@@ -514,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
@@ -642,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;
@@ -1123,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,
@@ -1309,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
@@ -1335,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')
@@ -1346,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 = {
@@ -1359,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.
@@ -1370,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.'),
     }),
@@ -1408,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
@@ -1445,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');
@@ -1461,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);
@@ -1534,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,
             });
@@ -1627,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 }
@@ -1697,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),
@@ -1718,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);
@@ -1752,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,
         });
@@ -4105,13 +4215,14 @@ function shotParamsShape(described) {
     return {
         aspectRatio: d(zEnum(SHOT_ASPECT_RATIOS).optional(), 'Validated against the model; see slates_generate_video.'),
         duration: d(z.number().int().min(1).max(360).optional(), 'Seconds for video or duration-based audio; TTS uses text length.'),
-        videoResolution: d(zEnum(VIDEO_RESOLUTIONS).optional(), 'Validated against the chosen model when the Shot is saved.'),
+        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.
@@ -4364,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;
 }
@@ -4663,8 +4782,8 @@ export const listShots = {
             ' depend on the reference set — Seedance reference-clip seconds and MiniMax reference images' +
             ' past the free five — are missing from it. slates_get_shot prices one exactly, and' +
             ' slates_generate_from_shots quotes the set exactly before it fires anything.' +
-            (describeVarietyReport(r.variety) ? `
-
+            (describeVarietyReport(r.variety) ? `
+
 ${describeVarietyReport(r.variety)}` : ''));
     },
 };
@@ -4861,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'))
@@ -4953,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.

package/dist/prompts/character-sheet.js

@@ -78,6 +78,16 @@
 //      without the absence clause. If that happens, the fix is a
 //      model-conditional phrasing, not restoring the 422.
 //
+//      2026-09-09 — THE MODEL IT WAS MEASURED ON IS RETIRED; THE RULE IS NOT.
+//      GPT Image 2.5 replaced gpt-image-2 in the picker. The 422 above was
+//      measured on gpt-image-2 and that wording is left exactly as recorded,
+//      because a receipt names what was actually tested. What carries over is
+//      the MECHANISM, not the measurement: the classifier belongs to OpenAI,
+//      not to a model version, so phrase exclusions as framing on 2.5 too.
+//      ⚠️ INHERITED, NOT RE-MEASURED — nobody has re-run the 422 on Flare or
+//      Sunburst. If one of them accepts the absence clause, that is a new
+//      receipt to write down, not a reason to delete this one.
+//
 //      2026-07-30 (b) — THE GENRE ANCHOR HAS TO BE SCOPED TO THE FACE, and
 //      this one cost real generations. "an invisible-mannequin presentation
 //      WHERE THE CLOTHING HOLDS ITS OWN SHAPE" is the e-commerce genre stated

package/dist/prompts/model-capabilities.js

@@ -133,10 +133,48 @@ export const MODEL_CAPABILITIES = {
         aspectRatios: FULL_ASPECT_RATIOS,
         maxRefImages: 14,
     },
-    'gpt-image-2': {
-        // FIVE, not ten. The op's flat enum offered eleven for every image model.
+    // `gpt-image-2` WAS HERE AND IS DELIBERATELY GONE (retired 2026-09-09).
+    //
+    // An earlier pass kept the row so that a Shot saved before the swap could
+    // still resolve its caps by stored id. That was the wrong fix and the
+    // desktop refuses it: `pricing.ts` throws at MODULE LOAD for any capability
+    // row with no MODEL_REGISTRY entry, because an orphan row makes THIS op
+    // advertise, validate and quote a model the desktop can no longer render —
+    // the agent passes every gate and then hits 'Unsupported model' at the
+    // handler.
+    //
+    // Old Shots are handled where they are READ instead: `migrateGptImageModel`
+    // in slate/src/shared/pricing.ts rewrites the stored id to Flare inside
+    // `transform` (slate/src/main/storage/shots.ts), the one place a DB row
+    // becomes a Shot. That is strictly better than keeping the row — the Shot
+    // comes back FIREABLE on a live model, rather than merely openable on a dead
+    // one. Do not re-add this row to make a stale id resolve; migrate it.
+    // GPT Image 2.5 — 16 references, which IS fal's documented ceiling rather
+    // than a number of ours: `image_urls` carries `maxItems: 16` on both 2.5
+    // endpoints AND on both gpt-image-2 endpoints (schema, read 2026-09-09,
+    // ripped verbatim to second-brain/business/projects/slates/research/
+    // gpt-image-2-5-fal-api-docs.md).
+    //
+    // 🚨 IT WAS 10 UNTIL 2026-09-09, AND 10 WAS NEVER ANYBODY'S LIMIT. The
+    // comment here used to call it "the 10-reference ceiling ... unchanged by the
+    // version bump", which reads as a verified fal constraint and was not one —
+    // nobody had checked. Six reference slots were being given away, worst on
+    // Sunburst, whose entire reason for shipping is multi-reference edit work.
+    // Raised by Eric 2026-09-09 ("did we go completely full-on with all of the
+    // options on fal?").
+    //
+    // The five aspect ratios ARE a product choice; fal takes any custom size
+    // inside its own bounds (see GPT_IMAGE_25_SIZES in slate/src/shared/
+    // pricing.ts). Two SLATES caps sit outside this file and are not model
+    // limits either: the MCP's 4,000-character prompt against fal's 32,000, and
+    // image quantity, which is a fan-out and has no provider ceiling at all.
+    'gpt-image-2-5-flare': {
         aspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4'],
-        maxRefImages: 10,
+        maxRefImages: 16,
+    },
+    'gpt-image-2-5-sunburst': {
+        aspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4'],
+        maxRefImages: 16,
     },
     'flux-2-max': {
         aspectRatios: FULL_ASPECT_RATIOS,
@@ -368,6 +406,17 @@ export const MODEL_CAPABILITIES = {
     },
     'minimax-h3-max': {
         aspectRatios: MINIMAX_H3_ASPECT_RATIOS,
+        // 🚨 ZERO, DECLARED — not omitted. `minimax/h3-max/reference-to-video`
+        // returns 404, so there is no transport for a reference of any modality.
+        // Leaving this undeclared does NOT mean "none": `getMaxRefImages` falls
+        // back to `?? 3` for the ingredients mode, which handed this row three
+        // reference slots it cannot send. Measured 2026-09-09 — a pinned image on
+        // an h3-max generation was accepted by the composer, dropped in transit,
+        // and the model rendered the prompt text alone, returning a different
+        // person than the reference. Frames (start/end) remain the ONLY image
+        // transport on this seat.
+        maxIngredientImages: 0,
+        maxRefImages: 0,
         // 480p/768p ONLY — fal's post-train of the open weights, and the 2K
         // upscaler was never open-sourced. Declaring the shorter ladder here IS the
         // whole Max-seat mechanism: `assertVideoCapabilities` refuses 2K/4K on this

package/dist/prompts/model-facts.js

@@ -146,12 +146,20 @@ export const MODEL_FACTS = [
         notes: 'HERO-FRAME / typography PREMIUM image tier. NB2 is about 95% of Pro — escalate only when spatial composition, cinematic lighting/skin, fine typography-in-scene or deep multi-element reasoning must be perfect, and say why.',
     },
     {
-        id: 'gpt-image-2',
+        id: 'gpt-image-2-5-flare',
         route: 'generate',
-        label: 'GPT Image 2',
+        label: 'GPT Image 2.5 Flare',
         kind: 'image',
-        ...caps('gpt-image-2'),
-        notes: 'TEXT / DIAGRAM / PANEL king — near-perfect character-level text, ordered panels, exact placement. Route here for character sheets, shot grids and text-bearing panels. ALSO THE PHOTOREAL FRONT-RUNNER (Eric, 2026-08-24): at quality high it beat both Nano Banana rails head-to-head on skin realism, so route photoreal people HERE rather than away. Banana still owns edit-heavy work and the largest reference ceiling. Its own content filter, distinct from Gemini\'s. Killed if a head-to-head at the intended crop goes the other way — re-run the evidence test, never carry this forward on reputation.',
+        ...caps('gpt-image-2-5-flare'),
+        notes: 'THE FAST GPT IMAGE SEAT — OpenAI\'s small model, optimized for SPEED, quality COMPARABLE to GPT Image 2 (not better) at roughly half the latency. Route here when speed matters: drafts, exploration, volume. TEXT / DIAGRAM / PANEL work — character sheets, shot grids, text-bearing panels. When quality outranks speed, escalate to Sunburst. Own content filter, distinct from Gemini\'s. Killed by a head-to-head at the intended crop going the other way.',
+    },
+    {
+        id: 'gpt-image-2-5-sunburst',
+        route: 'generate',
+        label: 'GPT Image 2.5 Sunburst',
+        kind: 'image',
+        ...caps('gpt-image-2-5-sunburst'),
+        notes: 'THE QUALITY GPT IMAGE SEAT — OpenAI\'s most capable image model, higher quality than GPT Image 2, same price as Flare, deliberately SLOWER. Route here whenever quality outranks speed: finals, hero frames, photoreal people, and multi-reference edits where every reference must survive into one frame — its widest lead. Not for drafts; you pay latency on every frame. Explore on Flare, finish on Sunburst.',
     },
     {
         id: 'flux-2-max',

package/dist/prompts/prompting-tips.js

@@ -83,8 +83,14 @@ const SEEDANCE = {
             },
             {
                 heading: 'Images, clips and audio in ONE generation',
-                example: 'Marcus (image 1) performs the motion from video 1, speaking the line in audio 1.',
-                note: 'Attaching a clip does NOT mean "edit this clip". A video or audio attachment is a REFERENCE, numbered in the rail exactly like an image, and it sits alongside your images in the same generation — the composer cites them as "image N", "video N", "audio N", in rail order, and shows you the exact sentence before you press Generate. Reorder the tiles to change what those numbers mean. To actually rewrite a clip, use Edit with AI instead — that is a different, deliberate choice.',
+                example: 'Marcus (image 1) performs the motion from video 1 and uses the voice timbre from audio 1.',
+                note: 'Attaching a clip does NOT mean "edit this clip". A video or audio attachment is a REFERENCE, numbered in the rail exactly like an image, and it sits alongside your images in the same generation — the composer cites them as "image N", "video N", "audio N", in rail order, and shows you the exact sentence before you press Generate. Reorder the tiles to change what those numbers mean. To actually rewrite a clip, use Edit with AI instead — that is a different, deliberate choice. EACH MODALITY IS NUMBERED SEPARATELY, from 1 — two images and one clip are "image 1", "image 2" and "video 1", never a single running count, so an audio reference is "audio 1" no matter how many images sit in front of it.',
+                critical: true,
+            },
+            {
+                heading: 'Give a character a voice',
+                example: 'Sarah (image 1) uses the voice timbre from audio 1. She says, "We open in ten minutes."',
+                note: 'An audio reference can mean five different things to Seedance — music, dialogue, voice, tone or timbre — so SAY WHICH. Name it as the voice timbre and the clip supplies the voice while your prompt supplies the words; leave it unroled and the model falls back to dialogue, re-transcribes the clip and speaks ITS words instead (a real take came back as "a map called Slates" for "an app called Slates"). Bind each speaker in a sentence rather than by attachment order — position carries nothing: "Images 1-2 are Character 1 and correspond to Audio 1; Images 3-4 are Character 2 and correspond to Audio 2." Verbatim from ByteDance. Audio-alone works on 2.5; on 2.0 pair it with at least one image or video.',
                 critical: true,
             },
             {
@@ -613,7 +619,7 @@ const MINIMAX_H3 = {
             {
                 heading: 'Cite references by number',
                 example: 'Marcus (image 1) walks into the workshop (image 2)...',
-                note: `H3 takes references as typed slots and expects plain numbered prose — image 1, video 1, audio 1. Do not hand-write angle-bracket tags. ${PARTIALS['reference-tips-short']}`,
+                note: `H3 takes references as typed slots and expects plain numbered prose — image 1, video 1, audio 1, each modality counted separately from 1. fal's own prompt-field description: "Refer to reference assets by their modality and order in the reference lists: Image 1, Image 2, Video 1, Audio 1, and so on." Do not hand-write angle-bracket tags — MiniMax's guides use \`<Subject N>\` / \`<Audio N>\` as DOCUMENTATION notation and typing them puts literal brackets in the prompt. An audio reference binds as a voice timbre to a named speaker, the same primitive Seedance uses. ${PARTIALS['reference-tips-short']}`,
             },
             {
                 heading: 'Say how much of a reference survives',

package/dist/prompts/reference-composer.js

@@ -107,6 +107,20 @@ export function isHexColorToken(sigil, token) {
 }
 export function composeReferences(rawPrompt, groups, opts = {}) {
     // ── 1. Assign global numbers by walking the list in order ──
+    //
+    // 🚨 ONE COUNTER PER MODALITY, EACH STARTING AT 1 — never a single running
+    // count across the attachments. `audio 1` is the first AUDIO, however many
+    // images precede it. This is the vendors' scheme, not a convenience:
+    // BytePlus states it ("The numbering should correspond to the upload order of
+    // the assets, such as Image 1 / Video 1 / Audio 1") and PROVES it in a mixed
+    // example that numbers two audios 1 and 2 behind four images — a global
+    // counter would make them 5 and 6. fal says the same for MiniMax H3 in its
+    // own prompt-field description. Receipts and line refs:
+    // second-brain/business/projects/slates/research/model-prompting-research.md
+    // § 2026-09-09 Multimodal reference GRAMMAR.
+    //
+    // Collapsing these into one counter would renumber every citation the prompt
+    // makes, silently — the model would be told "audio 1" about an image.
     let imageNum = opts.startImageNumber ?? 0;
     let videoNum = opts.startVideoNumber ?? 0;
     let audioNum = opts.startAudioNumber ?? 0;

package/dist/prompts/shot-spec.d.ts

@@ -60,8 +60,15 @@ export interface ShotParams {
     imageResolution?: string;
     videoResolution?: string;
     quality?: string;
-    /** gpt-image-2's tier. Always sent explicitly: fal's own default is `high`. */
-    gptQuality?: 'medium' | 'high';
+    /** GPT Image 2.5's tier. Always sent explicitly: fal's own default is
+     *  `high`, which is the third of five rungs, not the top of two. */
+    gptQuality?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    /** GPT Image's alpha switch. `auto` is fal's default and ours; `transparent`
+     *  asks for a real alpha channel rather than a painted backdrop. Costs
+     *  nothing — fal prices this family on size × quality only, so it is NOT a
+     *  cost-key segment. Named `gptBackground` because `background` already
+     *  means "generate asynchronously" on every op that carries a Shot. */
+    gptBackground?: 'auto' | 'transparent' | 'opaque';
     duration?: number;
     imageQuantity?: number;
     gridMode?: 'off' | '2x2' | '3x3';