@slatesvideo/shared 0.6.9 → 0.6.11

package/dist/prompts/model-capabilities.js

@@ -100,6 +100,105 @@ const MINIMAX_H3_ASPECT_RATIOS = ['21:9', '16:9', '4:3', '1:1', '3:4', '9:16'];
  * to lose track of what was actually generated.
  */
 const LTX_2_5_ASPECT_RATIOS = ['16:9', '9:16'];
+export const GPT_QUALITY_TIERS = ['low', 'medium', 'high', 'xhigh', 'max'];
+export const GPT_BACKGROUNDS = ['auto', 'transparent', 'opaque'];
+// Product output sizes; schema bounds and metering receipt live in the GPT harvest.
+export const GPT_IMAGE_25_SIZES = {
+    '1k': {
+        '1:1': { width: 1024, height: 1024 },
+        '16:9': { width: 1360, height: 768 },
+        '9:16': { width: 768, height: 1360 },
+        '4:3': { width: 1168, height: 880 },
+        '3:4': { width: 880, height: 1168 },
+    },
+    '2k': {
+        '1:1': { width: 1440, height: 1440 },
+        '16:9': { width: 1920, height: 1080 },
+        '9:16': { width: 1080, height: 1920 },
+        '4:3': { width: 1664, height: 1248 },
+        '3:4': { width: 1248, height: 1664 },
+    },
+    '3k': {
+        '1:1': { width: 1920, height: 1920 },
+        '16:9': { width: 2560, height: 1440 },
+        '9:16': { width: 1440, height: 2560 },
+        '4:3': { width: 2224, height: 1664 },
+        '3:4': { width: 1664, height: 2224 },
+    },
+    '4k': {
+        // 1:1 and 16:9 sit EXACTLY on the 8,294,400 ceiling — 3840×2160 is one of
+        // fal's own priced sizes, so the bound is inclusive. 4:3 / 3:4 are the two
+        // that had to move; see the constraint note above.
+        '1:1': { width: 2880, height: 2880 },
+        '16:9': { width: 3840, height: 2160 },
+        '9:16': { width: 2160, height: 3840 },
+        '4:3': { width: 3264, height: 2448 },
+        '3:4': { width: 2448, height: 3264 },
+    },
+};
+/**
+ * fal's named ~1MP presets per aspect ratio, with custom dims where fal has no
+ * preset. The `1k` rung of every non-GPT image model resolves through this.
+ */
+export const FAL_1MP_SIZES = {
+    '1:1': 'square_hd',
+    '4:3': 'landscape_4_3',
+    '3:4': 'portrait_4_3',
+    '16:9': 'landscape_16_9',
+    '9:16': 'portrait_16_9',
+    '2:3': { width: 832, height: 1248 },
+    '3:2': { width: 1248, height: 832 },
+    '4:5': { width: 896, height: 1120 },
+    '5:4': { width: 1120, height: 896 },
+    '21:9': { width: 1344, height: 576 },
+};
+/** Pixel dims for a megapixel target at an aspect ratio, rounded to multiples of 8. */
+export function computeFalDimensions(aspectRatio, targetMP) {
+    const parts = aspectRatio.split(':').map(Number);
+    const w = parts[0] || 16;
+    const h = parts[1] || 9;
+    const ratio = w / h;
+    const targetPixels = targetMP * 1_000_000;
+    return {
+        width: Math.round(Math.sqrt(targetPixels * ratio) / 8) * 8,
+        height: Math.round(Math.sqrt(targetPixels / ratio) / 8) * 8,
+    };
+}
+/**
+ * The `image_size` a non-GPT fal image request carries, for one model × aspect ×
+ * resolution rung.
+ *
+ * 🚨 THIS IS A BILLING INPUT, WHICH IS WHY IT LIVES HERE (moved out of
+ * slate/src/main/api/fal.ts, 2026-09-10). The resolution rung is a segment of
+ * every image cost key, and nothing in the REQUEST names it — fal is told pixel
+ * dimensions, not "2k". The proxy therefore recovers the rung by running this
+ * function over the model's declared `imageResolutions` × `aspectRatios` and
+ * matching the body's `image_size`, exactly as it recovers a GPT Image rung from
+ * `GPT_IMAGE_25_SIZES`. A second copy of this arithmetic would mean the desktop
+ * and the server could disagree about what a request is worth, silently.
+ *
+ * GPT Image does NOT come through here — that family carries explicit pixel
+ * classes in `GPT_IMAGE_25_SIZES` and an explicit `quality` rung.
+ */
+export function falImageSize(model, aspectRatio, resolution) {
+    const ar = aspectRatio || '16:9';
+    const isSeedream5 = model === 'seedream-5-lite';
+    const res = resolution || (isSeedream5 ? '2k' : '1k');
+    // 1K (~1MP): fal's named presets, or small custom dims where there is none.
+    if (res === '1k') {
+        return FAL_1MP_SIZES[ar] || 'landscape_16_9';
+    }
+    // Seedream 5 Lite: custom dims must be ≥3.69MP (2560×1440) and ≤9.44MP
+    // (3072×3072), so its three rungs target 4 / 7 / 9 MP — all inside that band.
+    if (isSeedream5) {
+        if (res === '4k')
+            return computeFalDimensions(ar, 9);
+        return res === '3k' ? computeFalDimensions(ar, 7) : computeFalDimensions(ar, 4);
+    }
+    if (res === '2k')
+        return computeFalDimensions(ar, 2);
+    return computeFalDimensions(ar, 4);
+}
 /**
  * The provider every AGENT generation actually lands on for Kling and Veo.
  *
@@ -122,14 +221,22 @@ export const AGENT_ROUTE_PROVIDER = 'fal';
 export const MODEL_CAPABILITIES = {
     // ── Image models ───────────────────────────────────────────────────────────
     'nano-banana-2': {
+        imageResolutions: ['1k', '2k', '4k'],
+        // fal's nano-banana-2 schema caps `num_images` at 4 (read 2026-09-09). This
+        // is the ONLY model that batches: the MCP's headless path (no projectId) asks
+        // fal for one batch, and every other route — desktop and agent alike — fires
+        // N separate single-image generations. The proxy bills the batch size.
+        maxBatchImages: 4,
         aspectRatios: FULL_ASPECT_RATIOS,
         maxRefImages: 14,
     },
     'nano-banana-2-lite': {
+        imageResolutions: ['1k'],
         aspectRatios: FULL_ASPECT_RATIOS,
         maxRefImages: 4, // fal edit endpoint caps input images at 4
     },
     'nano-banana-pro': {
+        imageResolutions: ['1k', '2k', '4k'],
         aspectRatios: FULL_ASPECT_RATIOS,
         maxRefImages: 14,
     },
@@ -169,18 +276,22 @@ export const MODEL_CAPABILITIES = {
     // 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': {
+        imageResolutions: ['2k', '3k', '4k'],
         aspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4'],
         maxRefImages: 16,
     },
     'gpt-image-2-5-sunburst': {
+        imageResolutions: ['2k', '3k', '4k'],
         aspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4'],
         maxRefImages: 16,
     },
     'flux-2-max': {
+        imageResolutions: ['1k', '2k', '4k'],
         aspectRatios: FULL_ASPECT_RATIOS,
         maxRefImages: 4,
     },
     'seedream-5-lite': {
+        imageResolutions: ['2k', '3k', '4k'],
         aspectRatios: FULL_ASPECT_RATIOS,
         maxRefImages: 10,
     },
@@ -377,6 +488,9 @@ export const MODEL_CAPABILITIES = {
     // the base row's branch — a different ladder AND a different price at the one
     // tier they share. Every lookup downstream is an exact-id map, not a prefix.
     'minimax-h3': {
+        // fal reference-to-video schema, 2026-09-09: each audio clip is 2-15s.
+        referenceAudioDuration: { min: 2, max: 15 },
+        referenceVideoDuration: { min: 2, max: 15 },
         aspectRatios: MINIMAX_H3_ASPECT_RATIOS,
         // The full ladder. 480p/768p are NATIVE generation modes; 2K and 4K upscale
         // a 768p base result through H3-Regenerate-2K, which is API-only and not in
@@ -408,6 +522,9 @@ export const MODEL_CAPABILITIES = {
         maxReferenceAudioSeconds: 15,
     },
     'minimax-h3-max': {
+        // fal reference-to-video schema, 2026-09-09: each audio clip is 2-15s.
+        referenceAudioDuration: { min: 2, max: 15 },
+        referenceVideoDuration: { min: 2, max: 15 },
         aspectRatios: MINIMAX_H3_ASPECT_RATIOS,
         // 🚨 REFERENCES LANDED 2026-09-09, AFTER A FALSE CLAIM WAS RETIRED. This row
         // shipped from v1.5.5 declaring zero reference capacity because a comment
@@ -431,15 +548,7 @@ export const MODEL_CAPABILITIES = {
         // arms — quoted off this endpoint, not inherited.
         maxReferenceVideoSeconds: 15,
         maxReferenceAudioSeconds: 15,
-        // 1080P IS REAL ON THIS ROW and was missing until 2026-09-09. The schema's
-        // resolution enum is ["480P","768P","1080P"] on all three h3-max endpoints.
-        // 2K/4K genuinely are absent: the H3-Regenerate-2K upscaler is API-only and
-        // is not in the open weights fal self-hosts, which is the actual mechanism
-        // behind the shorter ladder — 1080p was never part of that story.
-        //
-        // DEFAULT stays 768p: it is the tier the model natively generates, and
-        // 1080p is a 2x price step ($0.160/s against $0.080/s).
-        videoResolution: { options: ['480p', '768p', '1080p'], default: '768p' },
+        videoResolution: { options: ['480p', '768p'], default: '768p' },
         duration: { min: 5, max: 15, mode: 'continuous' },
     },
     // ── LTX-2.5 (both seats on fal — added 2026-08-29) ─────────────────────────
@@ -817,4 +926,28 @@ export function describeReferenceImageCaps(models) {
         return n === 0 ? '0 (prompt + source clip only)' : String(n);
     });
 }
+/** H3 Max reference accounting, fal's worked tables read 2026-09-09.
+ * https://fal.ai/models/minimax/h3-max/reference-to-video
+ * 1080p video-reference pricing is unpublished; never infer it from output rates.
+ */
+export const MINIMAX_MAX_REFERENCE = {
+    freeTokens: 4096,
+    imagePixelsPerToken: 1024,
+    normalizedImageEdge: 1024,
+    audioTokensPerSecond: 80,
+    videoTokensPerSecond: { '480p': 2886, '768p': 7459.2 },
+};
+export function minimaxMaxReferenceTokens(input) {
+    const rate = MINIMAX_MAX_REFERENCE.videoTokensPerSecond[input.resolution];
+    if (input.videoSeconds > 0 && rate === undefined) {
+        throw new Error(`H3 Max video-reference pricing is unavailable at ${input.resolution}; choose a priced resolution.`);
+    }
+    for (const n of [input.imagePixels, input.videoSeconds, input.audioSeconds]) {
+        if (!Number.isFinite(n) || n < 0)
+            throw new Error('Reference metadata must be finite and nonnegative');
+    }
+    return Math.max(0, Math.ceil(input.imagePixels / MINIMAX_MAX_REFERENCE.imagePixelsPerToken +
+        input.videoSeconds * (rate ?? 0) + input.audioSeconds * MINIMAX_MAX_REFERENCE.audioTokensPerSecond -
+        MINIMAX_MAX_REFERENCE.freeTokens));
+}
 //# sourceMappingURL=model-capabilities.js.map

package/dist/prompts/model-facts.d.ts

@@ -10,6 +10,33 @@ export interface ModelFact {
      * only while that substring is unique, which is how isOmniFlashModel broke.
      */
     route: 'generate' | 'edit';
+    /**
+     * Where this seat sits in the routing story, as DATA rather than as a word
+     * inside `notes`. `default` is the seat an agent (or a web page) reaches for
+     * when nothing about the shot argues otherwise: exactly ONE per kind per
+     * route, asserted at module load below. `specialist` is picked for a named
+     * reason the notes give (premium, speed, volume, audio, cheapest, edit fidelity).
+     * `niche` is never the default and never headlines; the notes say why.
+     *
+     * WHY A FIELD: "DEFAULT" lived only as a word inside notes. The 2026-08-10
+     * Seedance 2.5 commit wrote "the DEFAULT video model" into Seedance 2.0's note
+     * meaning the default SEEDANCE seat (a bare "seedance" resolves to 2.0), and for
+     * a month two rows read as the default while the routing doctrine then in force
+     * (Eric, 2026-07-03: Kling 3.0 the general-purpose default, Seedance the premium
+     * escalation) never changed. The marketing site meanwhile headlined Veo, a
+     * `niche` row, because no check could read a tier out of prose. The tier is
+     * DATA now; the notes describe, they do not rank.
+     *
+     * CURRENT DOCTRINE (Eric, 2026-09-13, superseding 2026-07-03): SEEDANCE 2.5 IS
+     * THE DEFAULT VIDEO MODEL, in the app picker and in agent routing — "it's the
+     * best in the world". 2.0 is the specialist for native 4K and for the same
+     * resolution cheaper; Kling is the specialist for cost-effective start-frame,
+     * performance and lip-sync work and the only engine behind Motion Transfer and
+     * Lip Sync. Recorded in the vault's prompting-ssot.md the same day. Changing the
+     * default again lands there first, then here, then in slates-model-selection.md. slates-web reads this to order its model lineup
+     * and to fail its build when a niche seat is named more often than the default.
+     */
+    tier: 'default' | 'specialist' | 'niche';
     /** Max reference images (image models) — null if not applicable. */
     maxRefImages: number | null;
     /** Max ingredient images (video models) — null if not applicable. */

package/dist/prompts/model-facts.js

@@ -69,14 +69,14 @@ export function multimodalRefSummary(id) {
         return '';
     const parts = [];
     if (v > 0)
-        parts.push(`${v} reference video${v === 1 ? '' : 's'} (${f.maxReferenceVideoSeconds}s combined)`);
+        parts.push(`${v} video${v === 1 ? '' : 's'} (${f.maxReferenceVideoSeconds}s total)`);
     if (a > 0)
-        parts.push(`${a} reference audio clip${a === 1 ? '' : 's'} (${f.maxReferenceAudioSeconds}s combined)`);
-    const total = f.maxReferenceFilesTotal ? `, ${f.maxReferenceFilesTotal} files max across all modalities` : '';
+        parts.push(`${a} audio clip${a === 1 ? '' : 's'} (${f.maxReferenceAudioSeconds}s total)`);
+    const total = f.maxReferenceFilesTotal ? `, ${f.maxReferenceFilesTotal} files max` : '';
     const companion = f.audioRefNeedsCompanion
-        ? ' Audio needs at least one image or video reference alongside it.'
-        : ' Audio-only references are allowed.';
-    return `${f.label}: up to ${parts.join(' and ')}${total}.${companion}`;
+        ? '; audio needs an image or video alongside.'
+        : '; audio-only is allowed.';
+    return `${f.label}: up to ${parts.join(' + ')}${total}${companion}`;
 }
 /**
  * The prompt words that make Seedance 2.5 reclassify a reference-carrying
@@ -120,6 +120,7 @@ export const MODEL_FACTS = [
     {
         id: 'nano-banana-2',
         route: 'generate',
+        tier: 'default',
         // Gemini 3.1 FLASH Image — verified against the runtime slug map in
         // slate/src/main/api/google.ts. Nano Banana PRO is a different model
         // (gemini-3-pro-image-preview); do not conflate them.
@@ -132,6 +133,7 @@ export const MODEL_FACTS = [
     {
         id: 'nano-banana-2-lite',
         route: 'generate',
+        tier: 'specialist',
         label: 'Nano Banana 2 Lite',
         kind: 'image',
         ...caps('nano-banana-2-lite'),
@@ -140,6 +142,7 @@ export const MODEL_FACTS = [
     {
         id: 'nano-banana-pro',
         route: 'generate',
+        tier: 'specialist',
         label: 'Nano Banana Pro',
         kind: 'image',
         ...caps('nano-banana-pro'),
@@ -148,6 +151,7 @@ export const MODEL_FACTS = [
     {
         id: 'gpt-image-2-5-flare',
         route: 'generate',
+        tier: 'specialist',
         label: 'GPT Image 2.5 Flare',
         kind: 'image',
         ...caps('gpt-image-2-5-flare'),
@@ -156,6 +160,7 @@ export const MODEL_FACTS = [
     {
         id: 'gpt-image-2-5-sunburst',
         route: 'generate',
+        tier: 'specialist',
         label: 'GPT Image 2.5 Sunburst',
         kind: 'image',
         ...caps('gpt-image-2-5-sunburst'),
@@ -164,6 +169,7 @@ export const MODEL_FACTS = [
     {
         id: 'flux-2-max',
         route: 'generate',
+        tier: 'specialist',
         label: 'FLUX.2 Max',
         kind: 'image',
         ...caps('flux-2-max'),
@@ -172,6 +178,7 @@ export const MODEL_FACTS = [
     {
         id: 'seedream-5-lite',
         route: 'generate',
+        tier: 'specialist',
         label: 'Seedream 5 Lite',
         kind: 'image',
         ...caps('seedream-5-lite'),
@@ -180,25 +187,28 @@ export const MODEL_FACTS = [
     {
         id: 'seedance-2',
         route: 'generate',
+        tier: 'specialist',
         label: 'Seedance 2.0',
         kind: 'video',
         ...caps('seedance-2'),
         audioRefNeedsCompanion: true,
-        notes: 'PREMIUM video tier and the DEFAULT video model — route here the moment physics, effects, destruction or scale matter, and for hero shots. VIDEO-ONLY. Strong image-to-video and own-footage restyle. 4K is Pro-gated (base accounts get PRO_REQUIRED). Stays the default over 2.5: it is the only Seedance with native 4K and it is cheaper at every tier the two share.',
+        notes: 'THE 4K AND VALUE SEAT beside the 2.5 default — the only Seedance with native 4K (Pro-gated; base accounts get PRO_REQUIRED) and cheaper than 2.5 at every resolution they share, with the same physics, effects and scale strengths; shorter takes, fewer references, no timestamps. VIDEO-ONLY. A bare "seedance" still resolves here for older CLIs that expect 4K.',
     },
     {
         id: 'seedance-2.5',
         route: 'generate',
+        tier: 'default',
         label: 'Seedance 2.5',
         kind: 'video',
         ...caps('seedance-2.5'),
         // No companion requirement — audio-only references are one of the things
         // the second seat actually buys.
-        notes: 'A SECOND SEAT NEXT TO 2.0, NOT AN UPGRADE — and the dearer one at every tier they share. Pick 2.5 when the shot needs LENGTH, MANY references, an AUDIO-ONLY reference, TIMED BEATS, or tighter prompt adherence; pick 2.0 for 4K and for the same resolution cheaper. VIDEO-ONLY. Timestamp grammar, and the edit/extend words that make the provider reclassify a fresh generation and fail it, are in slates-prompting-seedance-2-5.',
+        notes: 'DEFAULT VIDEO MODEL — the strongest seat for physics, effects, scale and hero shots, and the only Seedance that takes long single takes, many references, audio-only references and integer-second timestamps. No 4K, and dearer than 2.0 at every shared resolution: go to 2.0 for 4K or the same resolution cheaper. LENGTH is the price dial — quote long takes first. VIDEO-ONLY. Timestamp grammar and the edit/extend words that make the provider reclassify and fail a generation are in slates-prompting-seedance-2-5.',
     },
     {
         id: 'seedance-2.5-edit',
         route: 'edit',
+        tier: 'specialist',
         label: 'Seedance 2.5 Edit',
         kind: 'video',
         // 0 ingredients: prompt + source clip only on slates_edit_video.
@@ -208,15 +218,17 @@ export const MODEL_FACTS = [
     {
         id: 'kling-v3',
         route: 'generate',
+        tier: 'specialist',
         label: 'Kling 3.0',
         kind: 'video',
         // Family-level fact — caps are identical across std/pro/omni/omni-pro.
         ...caps('kling-v3.0-std'),
-        notes: 'DEFAULT general-purpose video model — cost-effective, strong start-frame adherence (identity, layout, text), acting, dialogue, lip-sync, and the widest aspect-ratio set. Escalate to Seedance for physics. Kling is also the ONLY engine behind the Motion Transfer and Lip Sync tools.',
+        notes: 'THE COST-EFFECTIVE SEAT — strong start-frame adherence (identity, layout, text), acting, dialogue, lip-sync and the widest aspect-ratio set; pick it when the budget matters and the shot is a performance or a start-frame animation. Kling is also the ONLY engine behind the Motion Transfer and Lip Sync tools.',
     },
     {
         id: 'kling-v3-edit',
         route: 'edit',
+        tier: 'specialist',
         label: 'Kling O3 Video Edit',
         kind: 'video',
         // Family-level fact; 4 = combined subject elements + style refs per edit.
@@ -226,15 +238,17 @@ export const MODEL_FACTS = [
     {
         id: 'veo-3.1',
         route: 'generate',
+        tier: 'niche',
         label: 'Veo 3.1',
         kind: 'video',
         // Family-level fact — fast and standard declare the same caps.
         ...caps('veo-3.1-fast'),
-        notes: 'NICHE, never the default — pick only when native synchronized audio must generate WITH the video in one pass, and the narrowest aspect-ratio and duration sets in the catalogue are acceptable. Otherwise Kling (default) or Seedance (physics/premium) win.',
+        notes: 'NICHE, never the default — pick only when native synchronized audio must generate WITH the video in one pass, and the narrowest aspect-ratio and duration sets in the catalogue are acceptable. Otherwise Seedance 2.5 (the default) or Kling (cost-effective performance) win.',
     },
     {
         id: 'omni-flash',
         route: 'generate',
+        tier: 'specialist',
         label: 'Gemini Omni Flash',
         kind: 'video',
         // 7 ref2v image_urls — mirrors Google's own reference limit.
@@ -244,6 +258,7 @@ export const MODEL_FACTS = [
     {
         id: 'omni-flash-edit',
         route: 'edit',
+        tier: 'default',
         label: 'Omni Flash Edit',
         kind: 'video',
         // 0: prompt + source clip ONLY — no element/style refs on this endpoint.
@@ -253,6 +268,7 @@ export const MODEL_FACTS = [
     {
         id: 'minimax-h3',
         route: 'generate',
+        tier: 'specialist',
         label: 'MiniMax H3',
         kind: 'video',
         ...caps('minimax-h3'),
@@ -265,16 +281,24 @@ export const MODEL_FACTS = [
     {
         id: 'minimax-h3-max',
         route: 'generate',
+        tier: 'specialist',
         label: 'MiniMax H3 Max',
         kind: 'video',
-        // No reference caps: fal publishes no reference-to-video endpoint for this
-        // row, so `caps()` returns nulls and the composer refuses references.
+        // References landed 2026-09-09 when the "h3-max/reference-to-video returns
+        // 404" claim was retired against the fetched schema (caps come from
+        // model-capabilities.ts; the rip is second-brain/business/projects/slates/
+        // provider-docs/fal-minimax-h3-openapi-schemas.md, section 6).
         ...caps('minimax-h3-max'),
-        notes: 'THE SPEED SEAT, and the DEARER one at the tier they share — never the cheap H3 and never the default. fal\'s post-train of the H3 weights: MEASURED 2026-08-27 at about 12x faster than base H3 on the same prompt and params, queue to finished file, plus a thin vendor-reported quality edge. It gives up the upper resolution tiers and the REFERENCE endpoint, so the omni-reference set is base-H3 only — but it still animates start and end frames, which is one of the two things it is FOR. Never describe this row as taking no image input. Route here when a fast turnaround on text-to-video or a start-frame shot is worth the premium.',
+        // Quoted off THAT endpoint's reference_audio_urls description, not copied
+        // from the base row: "Audio cannot be the only reference input; provide at
+        // least one reference image or video with it."
+        audioRefNeedsCompanion: true,
+        notes: 'THE SPEED SEAT, and the DEARER one at the tier they share — never the cheap H3 and never the default. fal\'s post-train of the H3 weights: MEASURED 2026-08-27 at about 12x faster than base H3 on the same prompt and params, queue to finished file, plus a thin vendor-reported quality edge. It gives up the upper resolution tiers. It takes the same omni-reference set as base H3 and animates start and end frames — but not both in one call: its reference endpoint has no start/end-frame fields, where base H3\'s does. Never describe this row as taking no image or reference input. Route here when a fast turnaround on text-to-video or a start-frame shot is worth the premium.',
     },
     {
         id: 'ltx-2-5',
         route: 'generate',
+        tier: 'specialist',
         label: 'LTX-2.5',
         kind: 'video',
         // No reference caps: fal publishes text-to-video and image-to-video for LTX
@@ -286,6 +310,7 @@ export const MODEL_FACTS = [
     {
         id: 'ltx-2-5-pro',
         route: 'generate',
+        tier: 'specialist',
         label: 'LTX-2.5 Pro',
         kind: 'video',
         ...caps('ltx-2-5-pro'),
@@ -294,6 +319,7 @@ export const MODEL_FACTS = [
     {
         id: 'seed-audio',
         route: 'generate',
+        tier: 'default',
         label: 'Seed Audio 1.0',
         kind: 'audio',
         // ONE image XOR up to 3 audio clips — the two inputs are mutually exclusive.
@@ -303,6 +329,7 @@ export const MODEL_FACTS = [
     {
         id: 'eleven-sfx',
         route: 'generate',
+        tier: 'specialist',
         label: 'ElevenLabs Sound Effects v2',
         kind: 'audio',
         ...caps('eleven-sfx'),
@@ -311,12 +338,30 @@ export const MODEL_FACTS = [
     {
         id: 'inworld-tts-2',
         route: 'generate',
+        tier: 'specialist',
         label: 'Inworld Realtime TTS-2',
         kind: 'audio',
         ...caps('inworld-tts-2'),
         notes: 'THE VOICE SEAT — one named voice saying one line, billed per CHARACTER not per second. Route here when WHO is speaking matters. NOT scene audio — that is seed-audio; a single effect is eleven-sfx.',
     },
 ];
+/**
+ * One default per lane, asserted where the data is declared. Two rows both
+ * reading "DEFAULT" is exactly the drift `tier` exists to make impossible, and
+ * a lane with no default leaves an agent (and slates-web) nothing to lead with.
+ */
+for (const kind of ['image', 'video', 'audio']) {
+    for (const route of ['generate', 'edit']) {
+        const lane = MODEL_FACTS.filter((f) => f.kind === kind && f.route === route);
+        if (lane.length === 0)
+            continue;
+        const defaults = lane.filter((f) => f.tier === 'default').map((f) => f.id);
+        if (defaults.length !== 1) {
+            throw new Error(`MODEL_FACTS: ${kind}/${route} must have exactly one tier: 'default' row, found ${defaults.length}` +
+                (defaults.length ? ` (${defaults.join(', ')})` : ''));
+        }
+    }
+}
 const FACT_BY_ID = new Map(MODEL_FACTS.map((m) => [m.id, m]));
 /**
  * Routing prose for one lane, generated from the SSOT.

package/dist/prompts/prompting-tips.js

@@ -115,7 +115,7 @@ const SEEDANCE_25 = {
     ...SEEDANCE,
     label: 'Seedance 2.5',
     intro: [
-        'Seedance 2.5 is a SECOND SEAT next to 2.0, not an upgrade of it. It buys one 30-second take instead of 15, up to 30 image references (plus 10 video and 10 audio), audio-only references and integer-second timestamps — and it gives up 4K. It runs at 480p, 720p or 1080p, and it costs more than 2.0 at every tier they share, so pick 2.0 when you want the same resolution cheaper or you want 4K.',
+        'Seedance 2.5 is the default video model. Against 2.0 it buys one 30-second take instead of 15, up to 30 image references (plus 10 video and 10 audio), audio-only references and integer-second timestamps — and it gives up 4K. It runs at 480p, 720p or 1080p, and it costs more than 2.0 at every tier they share, so pick 2.0 when you want the same resolution cheaper or you want 4K.',
         "ByteDance's official advanced formula has 8 slots: precise subject + action details + scene/environment + lighting & color tone + camera movement + visual style + image quality + constraints. Sweet spot 60-150 words for a single shot, longer for multi-shot.",
     ],
     columns: [
@@ -348,7 +348,7 @@ const OMNI_FLASH = {
             },
             {
                 heading: 'Know its seat',
-                note: 'Cheap drafts, iteration volume, and audio-in-one-gen at low cost. For hero shots, Kling 3.0 (general default) or Seedance 2.0 (premium/physics) still win.',
+                note: 'Cheap drafts, iteration volume, and audio-in-one-gen at low cost. For hero shots, Seedance 2.5 (the default) or Seedance 2.0 (4K, cheaper) still win.',
             },
         ],
     ],

package/dist/prompts/reference-composer.d.ts

@@ -14,7 +14,21 @@ export interface ReferenceGroup {
     /** Display + citation name: 'Marcus' | 'the cafe' | 'noir'. Used verbatim. */
     name: string;
     kind: ReferenceKind;
-    /** A group can carry several images for workflows that genuinely need them. */
+    /**
+     * A group can carry several images for workflows that genuinely need them.
+     *
+     * 🚨 A `character` GROUP MAY ALSO CARRY ONE `audio` MEDIUM — that character's
+     * assigned VOICE (2026-09-09). It is the same idea as the identity image, on
+     * the other axis of identity: the mention attaches what the character IS, and
+     * a voice is part of that. The audio takes its number from the audio counter,
+     * so adding one renumbers no image, and it is cited INLINE beside her name
+     * ("Sarah (image 1, voice timbre from audio 1)") rather than as the neutral
+     * `audio-ref` sentence — step 3e holds the receipt for why that is legal.
+     *
+     * A character group with a voice and NO identity image is a real state, not a
+     * defect: `voice-without-photo` is legal on any model that reads audio alone
+     * (Seedance 2.5). It cites no image and the timbre line carries the binding.
+     */
     media: ReferenceMedia[];
     /**
      * What is SAID in this group's reference audio, typed by the user.