@slatesvideo/shared 0.7.2 → 0.7.3

package/dist/operations/surface.d.ts

@@ -61,12 +61,16 @@ export declare function toolDefinition(op: SurfaceOp): ToolDefinition;
  * Render a tool surface.
  *
  * `desktop` sends `core` plus whatever groups have been loaded this run; `mcp`
- * renders all definitions, and the MCP server lists all of them unless started with
- * `--tools=compact`.
+ * renders every definition for the fixed MCP list.
  */
 export declare function toolDefinitions(ops: readonly SurfaceOp[], opts: {
     surface: 'desktop' | 'mcp';
     groups?: readonly OperationGroup[];
     names?: readonly string[];
 }): ToolDefinition[];
+/** Rank exact task words by rarity across the current registry, returning at most ten. */
+export declare function searchTools<T extends Pick<SurfaceOp, 'id' | 'description'>>(operations: readonly T[], query: string): Array<{
+    op: T;
+    score: number;
+}>;
 //# sourceMappingURL=surface.d.ts.map

package/dist/operations/surface.js

@@ -15,8 +15,7 @@
 //      mechanism: we build every turn there, so a load reaches the model. The
 //      MCP server lists every op and leaves hiding definitions to the host
 //      (tiering there left Claude and Codex users unable to generate in 0.6.0;
-//      see the TOOLS comment in packages/mcp/src/server.ts). `--tools=compact`
-//      is the opt-in exception.
+//      see the TOOLS comment in packages/mcp/src/server.ts).
 //
 //   3. ONE SCHEMA RENDERER. The desktop rendered `$refStrategy: 'none'` and
 //      the MCP server rendered `target: 'openApi3'`, so "the two surfaces
@@ -29,6 +28,7 @@
 // an op whose `run` body posts is a lie that lets a host auto-approve a
 // mutation, so the check has to be able to catch it, and it is mutation-tested.
 // ============================================================
+import { searchTerms } from '../prompts/search-terms.js';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 // ── 1. Annotations ──────────────────────────────────────────────────────────
 /** Ops that only read. Prefixes, because the verb IS the first word of the id. */
@@ -221,7 +221,7 @@ export function tierFor(id) {
 export const GROUP_SUMMARY = {
     library: 'folders, the Library (user-named categories of saved references: characters, locations, products, looks), moving and copying assets and Library items between projects, moving a project into the current projects folder, revealing files on disk',
     script: 'rich script documents, anchored sections and their saved versions, reusable passages, variations and take input history',
-    timeline: 'named cuts and selected exports; the timeline (tracks, clips, markers, settings), video export and export for DaVinci, Premiere or Final Cut (XML), clip trimming',
+    timeline: 'named cuts and selected exports; the timeline (tracks, clips, markers, settings), video export and FCP7 XML export for DaVinci Resolve or Premiere, clip trimming',
     admin: 'rename / delete / reorder for projects, characters, locations, looks, boards, scenes and frames; shot duplicate, split and merge',
     blender: 'the Blender previs bridge — scene inspection, bpy execution, API docs, grey-box render',
 };
@@ -247,8 +247,7 @@ export function toolDefinition(op) {
  * Render a tool surface.
  *
  * `desktop` sends `core` plus whatever groups have been loaded this run; `mcp`
- * renders all definitions, and the MCP server lists all of them unless started with
- * `--tools=compact`.
+ * renders every definition for the fixed MCP list.
  */
 export function toolDefinitions(ops, opts) {
     const loaded = new Set(opts.groups ?? []);
@@ -261,4 +260,29 @@ export function toolDefinitions(ops, opts) {
     })
         .map(toolDefinition);
 }
+// Natural brief words for capabilities whose API names use technical terms.
+const TASK_ALIASES = {
+    slates_generate_video: 'create animate photo picture film movie ad advert advertisement',
+    slates_generate_from_shots: 'create make film movie ad advert advertisement',
+    slates_generate_image: 'photo picture illustration',
+    slates_edit_image: 'photo picture',
+    slates_use_pictures_as_first_frames: 'photo animate',
+    slates_generate_audio: 'voiceover narration speech ambience sound effect',
+};
+/** Rank exact task words by rarity across the current registry, returning at most ten. */
+export function searchTools(operations, query) {
+    const terms = searchTerms(query);
+    const documents = operations.map(op => ({
+        op,
+        name: new Set(searchTerms(op.id)),
+        words: new Set(searchTerms(`${op.description} ${TASK_ALIASES[op.id] ?? ''}`)),
+    }));
+    const frequency = new Map(terms.map(term => [term, documents.filter(doc => doc.name.has(term) || doc.words.has(term)).length]));
+    return documents.map(doc => ({
+        op: doc.op,
+        score: terms.reduce((sum, term) => sum + (doc.name.has(term) || doc.words.has(term)
+            ? Math.log(1 + documents.length / (1 + (frequency.get(term) ?? 0))) * (doc.name.has(term) ? 2 : 1)
+            : 0), 0),
+    })).filter(match => match.score > 0).sort((a, b) => b.score - a.score || a.op.id.localeCompare(b.op.id)).slice(0, 10);
+}
 //# sourceMappingURL=surface.js.map

package/dist/prompts/agent-doctrine.d.ts

@@ -4,16 +4,16 @@
  * `desktop` — the in-app Studio Agent. Its loop enforces plan approval in
  * code, auto-polls generation status, and displays orchestration cost itself.
  * `mcp` — Claude Code / Claude Desktop / Cursor / Codex over stdio. No
- * `present_plan` tool, no auto-poll, no app chrome; the consent gate is the
- * op-level `requires_confirm` threshold plus the host client's own per-call
- * tool approval. The asymmetry is DELIBERATE — see slates-mcp/CLAUDE.md.
+ * `present_plan` tool, no auto-poll, no app chrome. The user approves the
+ * itemized spend in chat; op-level `requires_confirm` is a threshold backstop.
+ * Host tool approval depends on the client. See slates-mcp/CLAUDE.md.
  */
 export type AgentSurface = 'desktop' | 'mcp';
 interface SkillIndexEntry {
     name: string;
     description: string;
 }
-/** Parse `name:`/`description:` out of each embedded skill's frontmatter. */
+/** Generated from the same validated metadata used by discovery and installation. */
 export declare function buildSkillIndex(): SkillIndexEntry[];
 export declare const WORKING_METHOD: ReadonlyArray<Record<AgentSurface, string>>;
 export declare const HARD_RULES: ReadonlyArray<Record<AgentSurface, string>>;

package/dist/prompts/agent-doctrine.js

@@ -50,6 +50,7 @@
 // the whole embedded SKILLS record. Root barrel only.
 // ============================================================
 import { SKILLS } from '../skills/content.js';
+import { guideCatalog } from './guide-discovery.js';
 import { VIDEO_MODELS, AUDIO_MODELS } from '../operations/index.js';
 /** A line that is identical on both surfaces. The default. */
 function both(text) {
@@ -59,21 +60,9 @@ function both(text) {
 function fork(desktop, mcp) {
     return { desktop, mcp };
 }
-/** Parse `name:`/`description:` out of each embedded skill's frontmatter. */
+/** Generated from the same validated metadata used by discovery and installation. */
 export function buildSkillIndex() {
-    const entries = [];
-    for (const key of Object.keys(SKILLS).sort()) {
-        const content = SKILLS[key];
-        const fm = /^---\n([\s\S]*?)\n---/.exec(content);
-        let description = '';
-        if (fm) {
-            const m = /^description:\s*(.+)$/m.exec(fm[1]);
-            if (m)
-                description = m[1].trim().replace(/^['"]|['"]$/g, '');
-        }
-        entries.push({ name: key, description });
-    }
-    return entries;
+    return guideCatalog(SKILLS).map(({ name, description }) => ({ name, description }));
 }
 // ── Preamble ───────────────────────────────────────────────────────
 // FORKED, and the MCP side is a SUMMARY THAT MUST FIT IN THE CUT. Claude Code
@@ -83,16 +72,16 @@ export function buildSkillIndex() {
 // find a tool when the host shows names only, the spend gate, real numbers, the
 // current project — sits here; the sections below expand it for clients that
 // read everything. mcp-instructions-smoke asserts these lines land inside the
-// cut with the UPDATE AVAILABLE notice in front of them.
-const PREAMBLE = fork(`You are the Slates Studio Agent — a production assistant living inside Slates, the AI video creation studio. You plan and execute video/image production runs by chaining the Slates tools: script → characters → images → videos → quality-check → regenerate, ending with assets in the user's project (and on the timeline when asked).`, `You are connected to Slates, the AI video creation studio. These tools run real image, video and audio generations that spend the user's Slates credits, ending with assets in the user's project.
+// cut when UPDATE AVAILABLE follows the first doctrine paragraph.
+const PREAMBLE = fork(`You are the Slates Studio Agent — a production assistant living inside Slates, the AI video creation studio. Turn the user's vision into finished work using the optional Slates tools and relevant production craft. Choose the workflow for the brief; start from the user's existing material and bring results into their project or timeline when asked.`, `Turn the user's vision into finished work in Slates. Find craft with slates_get_prompting_guide(query: the brief); reuse current guidance. Tools generate real media and spend credits. Before generation, estimate every step, show the itemized total and wait for approval. Work in the current project. Choose tools to fit the brief.
 
 ## Essentials (the sections below expand on these)
 
-- FINDING TOOLS: every Slates capability is its own slates_* tool. If your client shows tool names only, search your tools for the task (for example "slates generate video") and load that tool before calling it. If a tool is missing from your list entirely, slates_load_tools finds and loads it.
+- FINDING TOOLS: every Slates capability is its own slates_* tool. If your client shows tool names only, search your tools for the task (for example "slates generate video") and load that tool before calling it. slates_load_tools searches Slates tools by task and returns exact schemas.
 - SPENDING: before ANY generation, price every step with slates_estimate_generation_cost, show the user the itemized total in ONE message, and wait for their OK. Pass confirm: true only to relay an explicit user OK for that exact spend.
 - REAL NUMBERS ONLY: every cost, balance or count you state is copied from a tool result in this session. Never describe how a generation looks unless you fetched it this session.
 - PROJECT: call slates_get_workspace_state once, work in the user's current project, and never create a project unless asked.
-- CRAFT: before prompting a model, read its guide with slates_get_prompting_guide (pass the model id). For how or where in the app, use topic "app-manual".
+- CRAFT: discover relevant guides with slates_get_prompting_guide(query: the brief). Reuse current cards and guidance; fetch sections for missing craft. For UI help, use topic "app-manual".
 - Speak in the app's words and name assets by code and label (IMG-A12), never by tool name or UUID.`);
 // ── The working method ─────────────────────────────────────────────
 export const WORKING_METHOD = [
@@ -103,15 +92,15 @@ export const WORKING_METHOD = [
     // so its agent must load before calling. The MCP server lists every tool and
     // the host decides what to show (Essentials, FINDING TOOLS), so telling an MCP
     // client to load first costs it a turn for a tool it already has.
-    fork(`3. LOAD KNOWLEDGE ON DEMAND: slates_get_prompting_guide returns a short card by default; query a section or technique when needed. Use slates_load_tools with query to find a capability, then names to load its exact schema. A load replaces the previous optional selection. Before quoting a model, load its tool schema or routing guide. Use workspace generationDefaults when the user has no preference. Read the model card delivered by the estimate; fetch a section or full guide for an unfamiliar mode or missing detail. Reuse guidance already in context; retrieve it again when omitted or stale.`, `3. LOAD KNOWLEDGE ON DEMAND: slates_get_prompting_guide returns a short card by default; query a section or technique when needed. Before quoting a model, read its tool schema or routing guide. Use workspace generationDefaults when the user has no preference. Read the model card delivered by the estimate; fetch a section or full guide for an unfamiliar mode or missing detail. Reuse guidance already in context; retrieve it again when omitted or stale.`),
+    fork(`3. LOAD KNOWLEDGE ON DEMAND: discover craft from the brief with slates_get_prompting_guide(query: the need); no topic returns ranked guides, no query returns the catalog. With a topic, read a short card or query a section/technique when needed. Use slates_load_tools with query to find a capability, then names to load its exact schema. A load replaces the previous optional selection. Before quoting a model, load its tool schema or routing guide. Use workspace generationDefaults when the user has no preference. Read the model card delivered by the estimate; fetch a section or full guide for an unfamiliar mode or missing detail. Reuse guidance already in context; retrieve it again when omitted or stale.`, `3. LOAD KNOWLEDGE ON DEMAND: discover craft from the brief with slates_get_prompting_guide(query: the need); no topic returns ranked guides, no query returns the catalog. With a topic, read a short card or query a section/technique when needed. Before quoting a model, read its tool schema or routing guide. Use workspace generationDefaults when the user has no preference. Read the model card delivered by the estimate; fetch a section or full guide for an unfamiliar mode or missing detail. Reuse guidance already in context; retrieve it again when omitted or stale.`),
     // FORKED: `present_plan` is a loop-level DESKTOP tool, deliberately not in
     // ALL_OPERATIONS, so MCP never sees it and has no plan gate at all. Its
-    // substitute is the per-op `requires_confirm` threshold plus the host
-    // client's own per-call approval UI. Describing the desktop gate to an MCP
+    // substitute is the itemized quote and explicit user approval in chat,
+    // backed by per-op `requires_confirm`. Describing the desktop gate to an MCP
     // client would name a tool that does not exist.
     fork(`4. PLAN + GET APPROVAL: before ANY generation, call present_plan with itemized credit costs (slates_estimate_generation_cost per step). One approval covers the plan's listed steps ONLY. Generation tools are rejected without an approved plan — and any user revision, question, or new instruction after an approval means you MUST re-present the plan BEFORE the next generation call (calling a generation op first just gets BLOCKED and wastes a turn).`, `4. PLAN + GET APPROVAL: before ANY generation, price every step with slates_estimate_generation_cost and put the itemized total in front of the user in ONE message, then wait for their answer. There is no present_plan tool on this surface — consent is per call: a generation over the confirm threshold returns requires_confirm, and confirm: true is only ever a relay of an explicit user OK for that exact spend. Never pass confirm: true to clear a gate the user has not seen.`),
     fork(`5. EXECUTE: after approval, pass confirm: true (the approval IS the consent — never re-ask per step). Use background: true + status polling for video.`, `5. EXECUTE: run the approved steps, passing confirm: true only for the spend the user actually OK'd. Use background: true + status polling for video.`),
-    both(`6. QUALITY-CHECK: you have vision. After key generations, fetch the result (slates_get_asset_image / slates_get_asset_video_frames) and review it against the brief (slates-vision-feedback-loop). Fix real problems; don't churn credits polishing what works. Change ONE variable per regeneration.`),
+    both(`6. QUALITY-CHECK: you have vision. Inspect images or sampled video frames against the brief (slates-vision-feedback-loop). Frames establish visible appearance, not continuous motion, lip sync or sound: review those through actual playback or an audio-capable host when available; otherwise state they remain unreviewed. Fix real problems and change ONE variable per regeneration.`),
     both(`7. REPORT: when done, summarize what was made and where it landed. Concise and concrete.`),
 ];
 // ── Hard rules ─────────────────────────────────────────────────────
@@ -125,7 +114,7 @@ export const HARD_RULES = [
     both(`- PROMPT IS LAW (reference doctrine): references are cited inline by name and image number ("Marcus (images 1 and 2)"); the prompt text leads. Never write role-essays about what each reference is "for".`),
     both(`- NAMES AND DESCRIPTIONS ARE THE USER'S UI, NOT YOUR NOTEPAD. A project, board or shot name is rendered at the top of the user's screen at all times. Name it after the piece ("Kaiju selfie"), never after your process, and NEVER append your own status or housekeeping — no "shot list", no "v2", no "Written from IMG-A172 and IMG-A182", no "Delete freely", no "scratch". Leave the description empty unless the user gave you one worth keeping: a note-to-self at the top of the screen reads as part of the product, and the user has to look at it every day. Say that kind of thing in your reply to them instead.`),
     both(`- SAY THE APP'S WORDS. Tool and parameter names keep older nouns; the screen does not, and the user only ever sees the screen. Say board (not storyboard), location (not environment) and look (not style) for Library items, timeline (a saved version of it is a cut), version (a saved rewrite of a script section; not alternative), Words or Words + shots (the Script page's switch), the Generate panel (not the quote), and tab (Media, Script and Board; not lens). Describe what you did in plain words ("Checked your project", "Priced 6 clips"), never a tool or parameter name.`),
-    both(`- RESOLUTION DEFAULT IS UNIFORM: 1080p on the best available video model. Do not crank resolution the user didn't ask for.`),
+    both(`- RESOLUTION DEFAULT: each model's own default. Do not crank resolution the user didn't ask for.`),
     // ⛔ THE MODEL ROUTING BLOCK IS GONE FROM HERE, DELIBERATELY (2026-08-30).
     //
     // It was 17,700 characters — 47% of the whole doctrine — and every lane of it
@@ -141,9 +130,9 @@ export const HARD_RULES = [
     // The old `buildModelRouting()` renderer was DELETED rather than left
     // exported "in case": an export nothing calls is an export nothing keeps
     // honest. `describeRouting()` in model-facts.ts is the renderer now.
-    both(`- MODEL KINDS: image, video and audio models are disjoint — no image model makes a video, no video model makes a standalone image, no image or video model makes audio. Which SEAT to pick inside a kind is on each generate op's own \`model\` description, and the full table is the slates-model-selection skill.`),
+    both(`- MODEL KINDS: image, video and audio models are disjoint — no image model makes a video, no video model makes a standalone image, no image or video model makes a standalone audio file (video models can generate sound inside the clip). Which SEAT to pick inside a kind is on each generate op's own \`model\` description, and the full table is the slates-model-selection skill.`),
     both(`- ASSET CODES + STALENESS: every asset carries a badge code (IMG-A12 / VID-V3 / AUD-S1, top-left of its gallery card); speak about assets by code + label. When the user says "these" or "this one", call slates_get_selection rather than asking which. Asset lists go STALE — the user creates assets in the Slates UI mid-conversation. When the user names a code you have NOT seen in a tool result this session, resolve it with slates_list_assets (use the search filter) BEFORE using it. NEVER guess an asset id or reuse a nearby UUID — pass the exact id a tool returned for that exact code. A wrong start frame burns real credits.`),
-    both(`- CREDITS ONLY: every generation you drive bills Slates credits (your tool calls enforce this). Never suggest BYOK keys for agent work.`),
+    both(`- CREDITS ONLY: every generation you drive bills Slates credits (your tool calls enforce this), except ChatGPT images, which use the person's ChatGPT account. Never suggest BYOK keys for agent work.`),
     both(`- Do not invent tools, asset ids, or credit prices. If a tool errors, read the error and fix that exact issue; don't repeat the same call unchanged and never switch models to route around a parameter mistake.`),
     // FORKED: only the desktop loop auto-polls generation status
     // (loop.ts → autoPollUntilTerminal). Telling an MCP client "the app keeps
@@ -166,12 +155,12 @@ export const HARD_RULES = [
 // ── Surface-only footers ───────────────────────────────────────────
 //
 // MCP clients have no Slates chrome and may have no skill FILES installed
-// (`slates install-skills` covers Claude Code; Claude Desktop, Cursor and
-// Codex have no equivalent mechanism). The desktop always has the embedded
+// (`slates install-skills` covers Claude Code and Codex; other hosts may
+// use different native skill locations). The desktop always has the embedded
 // record, so this paragraph would be dead weight in its cached prefix.
 const MCP_FOOTER = `## Working without skill files
 
-If slates-* skill files are not installed in this client, every one of them is still reachable as data: call slates_get_prompting_guide with the skill name (or a model id — it resolves aliases). The guide index above is the complete list. "No skill installed" is never a reason to prompt a model blind.
+If slates-* skill files are not installed in this client, every one of them is still reachable as data: call slates_get_prompting_guide with the skill name (or a model id — it resolves aliases). Query the brief or browse topic "catalog" for generated discovery and entitled member playbooks. "No skill installed" is never a reason to prompt a model blind.
 `;
 /**
  * THE doctrine string for a surface. The desktop's whole system prompt and the

package/dist/prompts/guide-discovery.d.ts

@@ -0,0 +1,23 @@
+export interface GuideCatalogEntry {
+    name: string;
+    description: string;
+    tier: 'free' | 'paid';
+}
+/** Metadata is the catalog; headings supply technique vocabulary without returning whole guides. */
+export declare function guideCatalog(skills: Readonly<Record<string, string>>): GuideCatalogEntry[];
+export declare function discoverGuides(entries: readonly GuideCatalogEntry[], skills: Readonly<Record<string, string>>, query?: string, limit?: number, offset?: number): {
+    query: string | null;
+    fallback: boolean;
+    total: number;
+    offset: number;
+    nextOffset: number | null;
+    guides: {
+        matched: string[];
+        sections: string[];
+        name: string;
+        description: string;
+        tier: "free" | "paid";
+    }[];
+    rest: GuideCatalogEntry[];
+};
+//# sourceMappingURL=guide-discovery.d.ts.map

package/dist/prompts/guide-discovery.js

@@ -0,0 +1,39 @@
+import { parseSkillMetadata } from '../skills/metadata.js';
+import { guideSections } from './guide-retrieval.js';
+import { searchTerms } from './search-terms.js';
+// Brief filler that matches guides by accident ("30 second", "how much", "I need").
+const GUIDE_FILLER = ['create', 'make', 'use', 'video', 'image', 'need', 'how', 'much', 'turn', 'keep', 'get', 'like', 'just', 'about', 'every', 'second', 'minute'];
+const words = (text) => searchTerms(text, GUIDE_FILLER).filter(word => !/^\d{1,2}$/.test(word));
+/** Metadata is the catalog; headings supply technique vocabulary without returning whole guides. */
+export function guideCatalog(skills) {
+    return Object.keys(skills).sort().map(name => ({ ...parseSkillMetadata(skills[name], name), tier: 'free' }));
+}
+export function discoverGuides(entries, skills, query, limit, offset = 0) {
+    const terms = words(query ?? '');
+    const documents = entries.map(entry => {
+        const sections = skills[entry.name] ? guideSections(skills[entry.name]) : [];
+        const metadata = new Set(words(`${entry.name.replace(/-/g, ' ')} ${entry.description}`));
+        const headings = sections.map(section => ({ heading: section.title, terms: new Set(words(section.title)) }));
+        return { entry, metadata, headings };
+    });
+    // Rare terms in the corpus carry more weight than generic production vocabulary.
+    const frequency = new Map(terms.map(term => [term, documents.filter(doc => doc.metadata.has(term) || doc.headings.some(section => section.terms.has(term))).length]));
+    const ranked = documents.map(doc => {
+        const matched = terms.filter(term => doc.metadata.has(term) || doc.headings.some(section => section.terms.has(term)));
+        const score = matched.reduce((sum, term) => sum + Math.log(1 + documents.length / (1 + (frequency.get(term) ?? 0))) * (doc.metadata.has(term) ? 3 : 1), 0);
+        const sections = doc.headings.filter(section => matched.some(term => section.terms.has(term))).slice(0, 3).map(section => section.heading);
+        return { ...doc.entry, matched, sections, score };
+    }).filter(entry => !terms.length || entry.score > 0).sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+    // An unfamiliar brief still exposes the catalog and its pagination; it never asks the user to route it.
+    const fallback = terms.length > 0 && ranked.length === 0;
+    const candidates = fallback ? documents.map(doc => ({ ...doc.entry, matched: [], sections: [], score: 0 })) : ranked;
+    // Browsing, or a brief with no keyword match, returns the whole catalog unless the caller pages it.
+    const size = limit ?? (terms.length && !fallback ? 8 : candidates.length);
+    const page = candidates.slice(offset, offset + size).map(({ score: _score, ...entry }) => entry);
+    // Keyword ranking only sees shared words, so the first page of a search also carries
+    // every other guide's description: the model chooses by the brief, as with native skills.
+    const shown = new Set(page.map(entry => entry.name));
+    const rest = terms.length && !fallback && offset === 0 ? entries.filter(entry => !shown.has(entry.name)) : [];
+    return { query: query ?? null, fallback, total: candidates.length, offset, nextOffset: offset + page.length < candidates.length ? offset + page.length : null, guides: page, rest };
+}
+//# sourceMappingURL=guide-discovery.js.map

package/dist/prompts/guide-retrieval.js

@@ -1,7 +1,7 @@
 import { craftCard } from './craft-cards.js';
 /** Parse headings outside code fences; maintainer comments never reach agents. */
 export function guideSections(content) {
-    const clean = content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '').replace(/<!--[\s\S]*?-->/g, '').trim();
+    const clean = content.replace(/<!--[\s\S]*?-->/g, '').trimStart().replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '').trim();
     const sections = [];
     let current = { title: 'Overview', body: '' };
     let fenced = false;

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

@@ -35,9 +35,9 @@ export interface DurationCapability {
     mode: 'continuous' | 'discrete';
     /** For discrete mode: the exact allowed durations. */
     values?: number[];
-    /** Resolution-dependent narrowing (Veo forces 8s at 1080p AND 4k). */
+    /** Resolution-dependent narrowing (retired Veo forced 8s at 1080p AND 4k). */
     resolutionOverrides?: Record<string, Pick<DurationCapability, 'min' | 'max' | 'mode' | 'values'>>;
-    /** Prompt-mode narrowing (Veo's reference-to-video endpoint is 8s only). */
+    /** Prompt-mode narrowing (retired Veo's reference-to-video endpoint was 8s only). */
     modeOverrides?: Record<string, Pick<DurationCapability, 'min' | 'max' | 'mode' | 'values'>>;
 }
 /** Video resolution constraints. */
@@ -188,15 +188,14 @@ export interface ModelCapability {
     voiceClone?: VoiceCloneCapability;
 }
 /**
- * The provider every AGENT generation actually lands on for Kling and Veo.
+ * The provider every AGENT generation actually lands on for Kling.
  *
  * 🚨 THIS IS WHY `providerAspectRatios` MATTERS TO THE OP. MCP/CLI/Studio-Agent
  * generations are credits-only (BYOK is retired on the agent surface), and the
- * credits route carries Kling and Veo on fal: `slate/src/main/agent/routes.ts`
- * never sends `klingProvider`, so `handlers/video.ts` defaults it to `'fal'`,
- * and `generateVeoVideo`'s proxy arm builds a fal request
- * (`buildFalVeoRequest`). So an agent gets Kling's THREE fal ratios and Veo's
- * TWO — not the eight and ten those models take on their direct APIs. Validating
+ * credits route carries Kling on fal: `slate/src/main/agent/routes.ts`
+ * never sends `klingProvider`, so `handlers/video.ts` defaults it to `'fal'`.
+ * So an agent gets Kling's THREE fal ratios, not the eight it takes on its
+ * direct API (retired Veo had the same split, two against ten). Validating
  * against the direct sets would accept a ratio fal rejects, which is the exact
  * failure this module exists to delete.
  */
@@ -257,7 +256,7 @@ export declare function checkDuration(model: string, duration: number | undefine
 export declare function describeAspectRatios(models: readonly string[], provider?: string): string;
 /** e.g. "seedance-2: 480p, 720p, 1080p, 4k (default 1080p) · omni-flash: 720p only (fixed)" */
 export declare function describeVideoResolutions(models: readonly string[]): string;
-/** e.g. "kling-v3.0-std: 3-15s · veo-3.1-fast: 4s/6s/8s (1080p/4k: 8s only; with reference images: 8s only)" */
+/** e.g. "kling-v3.0-std: 3-15s · ltx-2-5: 6s/8s/10s/12s/14s/16s/18s/20s (1440p/4k: 6s/8s/10s only)" */
 export declare function describeDurations(models: readonly string[]): string;
 /** e.g. "seedance-2: 9 · seedance-2.5: 30 · omni-flash: 7 · seedance-2.5-edit: 0 (prompt + source clip only)" */
 export declare function describeReferenceImageCaps(models: readonly string[]): string;

package/dist/prompts/model-capabilities.js

@@ -67,8 +67,6 @@ const KLING_DIRECT_ASPECT_RATIOS = [
 ];
 /** Kling carried on fal: three. This is the set the CREDITS route uses. */
 const KLING_FAL_ASPECT_RATIOS = ['16:9', '9:16', '1:1'];
-/** Veo carried on fal: two. The credits route again — Veo direct takes all ten. */
-const VEO_FAL_ASPECT_RATIOS = ['16:9', '9:16'];
 /** Gemini Omni Flash (fal schema, 16:9 default): two. */
 const OMNI_FLASH_ASPECT_RATIOS = ['16:9', '9:16'];
 /** Seedance (both seats, and the edit row): six — notably NO `4:5`. */
@@ -91,7 +89,7 @@ const MINIMAX_H3_ASPECT_RATIOS = ['21:9', '16:9', '4:3', '1:1', '3:4', '9:16'];
 /**
  * LTX-2.5, all four integrated endpoints: TWO. Read off fal's live OpenAPI
  * 2026-08-29 — `text-to-video/{fast,pro}` declare exactly `['16:9','9:16']`,
- * the narrowest video set in the roster alongside Veo-on-fal.
+ * the narrowest video set in the roster.
  *
  * `image-to-video/{fast,pro}` additionally offer `auto` (follow the start
  * frame). We never send it and it is not an `AspectRatio` in this vocabulary —
@@ -201,15 +199,14 @@ export function falImageSize(model, aspectRatio, resolution) {
     return computeFalDimensions(ar, 4);
 }
 /**
- * The provider every AGENT generation actually lands on for Kling and Veo.
+ * The provider every AGENT generation actually lands on for Kling.
  *
  * 🚨 THIS IS WHY `providerAspectRatios` MATTERS TO THE OP. MCP/CLI/Studio-Agent
  * generations are credits-only (BYOK is retired on the agent surface), and the
- * credits route carries Kling and Veo on fal: `slate/src/main/agent/routes.ts`
- * never sends `klingProvider`, so `handlers/video.ts` defaults it to `'fal'`,
- * and `generateVeoVideo`'s proxy arm builds a fal request
- * (`buildFalVeoRequest`). So an agent gets Kling's THREE fal ratios and Veo's
- * TWO — not the eight and ten those models take on their direct APIs. Validating
+ * credits route carries Kling on fal: `slate/src/main/agent/routes.ts`
+ * never sends `klingProvider`, so `handlers/video.ts` defaults it to `'fal'`.
+ * So an agent gets Kling's THREE fal ratios, not the eight it takes on its
+ * direct API (retired Veo had the same split, two against ten). Validating
  * against the direct sets would accept a ratio fal rejects, which is the exact
  * failure this module exists to delete.
  */
@@ -366,43 +363,6 @@ export const MODEL_CAPABILITIES = {
         duration: { min: 3, max: 10, mode: 'continuous' },
         maxIngredientImages: 0,
     },
-    // ── Veo ────────────────────────────────────────────────────────────────────
-    'veo-3.1-fast': {
-        aspectRatios: FULL_ASPECT_RATIOS,
-        providerAspectRatios: { fal: VEO_FAL_ASPECT_RATIOS },
-        videoResolution: { options: ['720p', '1080p', '4k'] },
-        duration: {
-            min: 4, max: 8, mode: 'discrete',
-            values: [4, 6, 8],
-            // BOTH 1080p and 4k force 8s. The op said "4K only at 8s" and quoted 4s
-            // at 1080p, which the provider rejects.
-            resolutionOverrides: {
-                '1080p': { min: 8, max: 8, mode: 'discrete', values: [8] },
-                '4k': { min: 8, max: 8, mode: 'discrete', values: [8] },
-            },
-            modeOverrides: {
-                ingredients: { min: 8, max: 8, mode: 'discrete', values: [8] },
-            },
-        },
-        maxIngredientImages: 3,
-    },
-    'veo-3.1-standard': {
-        aspectRatios: FULL_ASPECT_RATIOS,
-        providerAspectRatios: { fal: VEO_FAL_ASPECT_RATIOS },
-        videoResolution: { options: ['720p', '1080p', '4k'] },
-        duration: {
-            min: 4, max: 8, mode: 'discrete',
-            values: [4, 6, 8],
-            resolutionOverrides: {
-                '1080p': { min: 8, max: 8, mode: 'discrete', values: [8] },
-                '4k': { min: 8, max: 8, mode: 'discrete', values: [8] },
-            },
-            modeOverrides: {
-                ingredients: { min: 8, max: 8, mode: 'discrete', values: [8] },
-            },
-        },
-        maxIngredientImages: 3,
-    },
     // ── Seedance ───────────────────────────────────────────────────────────────
     'seedance-2': {
         aspectRatios: SEEDANCE_ASPECT_RATIOS,
@@ -933,7 +893,7 @@ export function describeVideoResolutions(models) {
 function fmtWindow(d) {
     return d.mode === 'discrete' && d.values ? `${d.values.join('s/')}s` : `${d.min}-${d.max}s`;
 }
-/** e.g. "kling-v3.0-std: 3-15s · veo-3.1-fast: 4s/6s/8s (1080p/4k: 8s only; with reference images: 8s only)" */
+/** e.g. "kling-v3.0-std: 3-15s · ltx-2-5: 6s/8s/10s/12s/14s/16s/18s/20s (1440p/4k: 6s/8s/10s only)" */
 export function describeDurations(models) {
     return groupBy(models, (m) => {
         const d = MODEL_CAPABILITIES[m]?.duration;
@@ -963,10 +923,10 @@ export function describeReferenceImageCaps(models) {
         const cap = MODEL_CAPABILITIES[m];
         if (!cap)
             return '';
-        const n = cap.maxIngredientImages ?? cap.maxRefImages;
-        if (n == null)
-            return '';
-        return n === 0 ? '0 (prompt + source clip only)' : String(n);
+        // A generate row with no reference cap (LTX) takes none: say so rather than
+        // dropping the row, which read as "no limit stated".
+        const n = cap.maxIngredientImages ?? cap.maxRefImages ?? 0;
+        return n === 0 ? '0 (prompt and frames only)' : String(n);
     });
 }
 /** H3 Max reference accounting, fal's worked tables read 2026-09-09.

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

@@ -112,12 +112,12 @@ export declare function seedanceTaskIntentWords(prompt: string): string[];
 export declare function multimodalRefModels(): string[];
 export declare const MODEL_FACTS: ModelFact[];
 /**
- * The one `default` seat for a kind on the generate route, READ from `tier`.
+ * The one `default` seat for a kind and route, READ from `tier`.
  * Anything that needs "the default image model" calls this instead of naming
  * one: the op surface and slates-web both hand-typed nano-banana-2 for six days
  * after the app picker moved to Sunburst.
  */
-export declare function defaultModelFor(kind: ModelFact['kind']): string;
+export declare function defaultModelFor(kind: ModelFact['kind'], route?: ModelFact['route']): string;
 /**
  * The seat a built-in tool renders on when its caller names no model. Resolves
  * `TOOL_SEAT` (generation-policy.ts, THE home): `'default-image'` follows the

package/dist/prompts/model-facts.js

@@ -49,11 +49,10 @@ export function composeChatGptFraming(prompt, aspectRatio) {
  * Reference caps for a fact, read out of the capability SSOT.
  *
  * The argument is a `MODEL_CAPABILITIES` key, which is a REGISTRY model id — and
- * three facts here are FAMILY-level (`kling-v3`, `kling-v3-edit`, `veo-3.1`)
+ * two facts here are FAMILY-level (`kling-v3`, `kling-v3-edit`)
  * with no registry row of their own, so they name a representative variant.
  * That is safe because the caps are identical across the variants in each
- * family (std/pro/omni/omni-pro all take 4; both edit rows take 4; both Veo
- * seats take 3) — and if a future variant diverges, this becomes a wrong number
+ * family (std/pro/omni/omni-pro all take 4; both edit rows take 4) — and if a future variant diverges, this becomes a wrong number
  * rather than a crash, so split the fact rather than picking a side.
  *
  * Throws on an unknown id: a typo must fail the build, not ship as `null` caps
@@ -201,7 +200,7 @@ export const MODEL_FACTS = [
         label: 'Seedream 5 Lite',
         kind: 'image',
         ...caps('seedream-5-lite'),
-        notes: 'CHEAPEST image seat, flat-priced. Less censored. Routes to its edit endpoint when references are present.',
+        notes: 'Cheapest flat-priced image seat (GPT Image 2.5 at low quality costs less per image). Less censored. Routes to its edit endpoint when references are present.',
     },
     {
         id: 'seedance-2',
@@ -232,7 +231,7 @@ export const MODEL_FACTS = [
         kind: 'video',
         // 0 ingredients: prompt + source clip only on slates_edit_video.
         ...caps('seedance-2.5-edit'),
-        notes: 'VIDEO-TO-VIDEO EDIT via slates_edit_video, and the only edit engine that takes a clip longer than the other two reach — that length is the whole reason to route here. Inside their range, compare on fidelity instead: Omni Flash edit won the prompt-only head-to-head, and Kling edit is the one that takes reference images. Edits audio on the same row (re-voice, re-accent, translate with re-fitted lips, replace BGM). Costs roughly double a plain 2.5 generation of the same length, because an edit bills input plus output seconds.',
+        notes: 'VIDEO-TO-VIDEO EDIT via slates_edit_video, and the only edit engine that takes a clip longer than the other two reach — that length is the whole reason to route here. Inside their range, compare on fidelity instead: Omni Flash edit won the prompt-only head-to-head, and Kling edit is the one that takes reference images. Edits audio on the same row (re-voice, re-accent, translate with re-fitted lips, replace BGM). Costs about 1.2x a plain 2.5 generation of the same length: an edit bills at twice the reduced video-reference rate.',
     },
     {
         id: 'kling-v3',
@@ -242,7 +241,7 @@ export const MODEL_FACTS = [
         kind: 'video',
         // Family-level fact — caps are identical across std/pro/omni/omni-pro.
         ...caps('kling-v3.0-std'),
-        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.',
+        notes: 'THE COST-EFFECTIVE SEAT — strong start-frame adherence (identity, layout, text), acting, dialogue and lip-sync; 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',
@@ -252,17 +251,7 @@ export const MODEL_FACTS = [
         kind: 'video',
         // Family-level fact; 4 = combined subject elements + style refs per edit.
         ...caps('kling-v3.0-omni-edit'),
-        notes: 'VIDEO-TO-VIDEO EDIT, the REF-DRIVEN one: it is the only edit seat that takes element/style reference images to lock subject identity, and its keep_audio preserves the original audio verbatim. Route here when an edit NEEDS reference images or bit-exact audio; for prompt-only footage-synced VFX, omni-flash-edit won the fidelity head-to-head. One instruction beat per pass — multi-beat prompts get under-executed.',
-    },
-    {
-        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 Seedance 2.5 (the default) or Kling (cost-effective performance) win.',
+        notes: 'VIDEO-TO-VIDEO EDIT, the REF-DRIVEN one: it is the only edit seat that takes element/style reference images to lock subject identity, and its keepAudio preserves the original audio verbatim. Route here when an edit NEEDS reference images or bit-exact audio; for prompt-only footage-synced VFX, omni-flash-edit won the fidelity head-to-head. One instruction beat per pass — multi-beat prompts get under-executed.',
     },
     {
         id: 'omni-flash',
@@ -272,7 +261,7 @@ export const MODEL_FACTS = [
         kind: 'video',
         // 7 ref2v image_urls — mirrors Google's own reference limit.
         ...caps('omni-flash'),
-        notes: 'CHEAP tier with native synced audio included. Route here for cheap drafts, audio-in-one-pass at low cost, and reference-to-video character-consistency trials. VIDEO-ONLY. Quality against Kling/Seedance is unproven — do not route hero shots here.',
+        notes: '720p seat with native synced audio included. Route here for drafts with sound in one pass and reference-to-video character-consistency trials; LTX, H3 and H3 Max Turbo cost less per second. VIDEO-ONLY. Quality against Kling/Seedance is unproven — do not route hero shots here.',
     },
     {
         id: 'omni-flash-edit',
@@ -282,7 +271,7 @@ export const MODEL_FACTS = [
         kind: 'video',
         // 0: prompt + source clip ONLY — no element/style refs on this endpoint.
         ...caps('omni-flash-edit'),
-        notes: 'VIDEO-TO-VIDEO EDIT, prompt-only — THE EDIT-FIDELITY WINNER (head-to-head vs Kling edit on real talking footage: lips held, audio near-identical, both action beats landed) and the cheapest edit seat. Footage-synced prop, effect, environment and lighting swaps. Takes NO reference images — identity swaps needing refs go to Kling edit. Fidelity is EARNED by prompt discipline; the exact form is in slates-prompting-omni-flash.',
+        notes: 'VIDEO-TO-VIDEO EDIT, prompt-only — THE EDIT-FIDELITY WINNER (head-to-head vs Kling edit on real talking footage: lips held, audio near-identical, both action beats landed), priced level with Kling O3 Edit Standard. Footage-synced prop, effect, environment and lighting swaps. Takes NO reference images — identity swaps needing refs go to Kling edit. Fidelity is EARNED by prompt discipline; the exact form is in slates-prompting-omni-flash.',
     },
     {
         id: 'minimax-h3',
@@ -295,7 +284,7 @@ export const MODEL_FACTS = [
         // be the only reference input; provide at least one reference image or
         // video with it." Same behavioural rule as Seedance 2.0.
         audioRefNeedsCompanion: true,
-        notes: 'THE AUTHORED-AUDIO SEAT — reach for H3 when the sound is part of the shot rather than a switch on it: synchronised dialogue, scene sound and an audience-only score directed as three separate layers in ONE pass, across eleven languages. Kling and Seedance treat audio as on/off; Veo generates it but gives you no way to direct the layers. Only H3 also carries a DECLARED REFERENCE RELATIONSHIP (kept whole, partly kept, transferred, or a loose echo). VIDEO-ONLY. Its top two resolution tiers are UPSCALES of the native render, not larger generations — judge at native and upscale in post. Reference images past the fifth are a PAID key dimension: pass referenceImages when quoting.',
+        notes: 'THE AUTHORED-AUDIO SEAT — reach for H3 when the sound is part of the shot rather than a switch on it: synchronised dialogue, scene sound and an audience-only score directed as three separate layers in ONE pass, across eleven languages. Kling and Seedance treat audio as on/off. Only H3 also carries a DECLARED REFERENCE RELATIONSHIP (kept whole, partly kept, transferred, or a loose echo). VIDEO-ONLY. Its top two resolution tiers are UPSCALES of the native render, not larger generations — judge at native and upscale in post. Reference images past the fifth are a PAID key dimension: pass referenceImages when quoting.',
     },
     {
         id: 'minimax-h3-max',
@@ -312,7 +301,7 @@ export const MODEL_FACTS = [
         // 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 tops out at a 1080p refinement of its 768p render. 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.',
+        notes: 'THE SPEED SEAT, dearer than base H3 at 768p and equal at 480p — 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 tops out at a 1080p refinement of its 768p render. It takes the same omni-reference set as base H3 and animates start and end frames — but not both in one call, the same as base H3: frames and references go to different endpoints. 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: 'minimax-h3-max-turbo',
@@ -336,7 +325,7 @@ export const MODEL_FACTS = [
         // and no reference endpoint at all, so `caps()` returns nulls and the
         // composer refuses references. Start/end FRAMES are unaffected.
         ...caps('ltx-2-5'),
-        notes: 'THE VOLUME SEAT — the cheapest native 1080p second in the catalogue, and the row for MANY takes rather than one hero shot. Native synced audio is included free at every tier, unlike Kling where sound is a paid key dimension. It also reaches the highest resolution tier below 4K and makes the LONGEST clips in the catalogue. VIDEO-ONLY. INPUTS ARE FRAMES, NOT REFERENCES: start frame plus an optional end frame, and no reference endpoint at all — for character consistency across shots use H3 or Kling. Route here for batch coverage, long takes, and anything where the credit budget is the binding constraint.',
+        notes: 'THE VOLUME SEAT — the cheapest 1080p second with sound included, and the row for MANY takes rather than one hero shot. Native synced audio is included free at every tier, unlike Kling where sound is a paid key dimension. It supports native high-resolution output and longer takes than most seats; use the capability surface for its resolution-dependent duration limits. VIDEO-ONLY. INPUTS ARE FRAMES, NOT REFERENCES: start frame plus an optional end frame, and no reference endpoint at all — for character consistency across shots use H3 or Kling. Route here for batch coverage, long takes, and anything where the credit budget is the binding constraint.',
     },
     {
         id: 'ltx-2-5-pro',
@@ -394,15 +383,15 @@ for (const kind of ['image', 'video', 'audio']) {
     }
 }
 /**
- * The one `default` seat for a kind on the generate route, READ from `tier`.
+ * The one `default` seat for a kind and route, READ from `tier`.
  * Anything that needs "the default image model" calls this instead of naming
  * one: the op surface and slates-web both hand-typed nano-banana-2 for six days
  * after the app picker moved to Sunburst.
  */
-export function defaultModelFor(kind) {
-    const fact = MODEL_FACTS.find((f) => f.kind === kind && f.route === 'generate' && f.tier === 'default');
+export function defaultModelFor(kind, route = 'generate') {
+    const fact = MODEL_FACTS.find((f) => f.kind === kind && f.route === route && f.tier === 'default');
     if (!fact)
-        throw new Error(`MODEL_FACTS: no default ${kind} seat on the generate route`);
+        throw new Error(`MODEL_FACTS: no default ${kind} seat on the ${route} route`);
     return fact.id;
 }
 /**