@slatesvideo/shared 0.7.1 → 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. */
@@ -145,6 +145,9 @@ export const OPERATION_GROUPS = {
         'slates_relocate_project',
         'slates_undo_relocate_project',
         'slates_reveal_file',
+        'slates_reorder_folders',
+        'slates_reorder_pins',
+        'slates_link_asset_source',
     ],
     // The cut and the export. A generation session never touches these.
     script: ['slates_get_script_document', 'slates_update_script_document', 'slates_get_script_sections', 'slates_update_script_section', 'slates_get_script_suggestions', 'slates_update_script_suggestions', 'slates_get_script_uses', 'slates_preview_script_variation', 'slates_create_script_variation', 'slates_get_shot_inputs', 'slates_reuse_shot_take'],
@@ -182,6 +185,9 @@ export const OPERATION_GROUPS = {
         'slates_duplicate_shot',
         'slates_split_shot',
         'slates_merge_shots',
+        'slates_get_usage',
+        'slates_get_app_settings',
+        'slates_set_app_settings',
     ],
     // A third transport nobody without Blender installed can reach.
     blender: [
@@ -215,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',
 };
@@ -241,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 ?? []);
@@ -255,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,35 +72,35 @@ 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 = [
-    both(`For HOW/WHERE questions, load slates_get_prompting_guide with topic "app-manual" and relevant query keywords. Teach the documented buttons and tabs, preserving model-specific conditions; do not invent UI paths or mutate the project when the user only asks for instructions. Slates is a sandbox of optional tools, not a required pipeline.`),
+    both(`For HOW/WHERE questions, load slates_get_prompting_guide with topic "app-manual" and relevant query keywords. Teach the documented buttons and tabs, preserving model-specific conditions; do not invent UI paths or mutate the project when the user only asks for instructions. When the control is on screen, offer to point at it (slates_highlight_control); show a picture of a screen (slates_get_manual_picture) only when the user cannot find something or asks what it looks like. Slates is a sandbox of optional tools, not a required pipeline.`),
     both(`1. UNDERSTAND the outcome the user wants. If intent is clear, act with sane defaults — don't interrogate. If genuinely ambiguous, batch every question into ONE message.`),
     both(`2. ORIENT: call slates_get_workspace_state once at the start of a workflow. Work in the user's CURRENT project — this chat lives inside it. NEVER create a new project unless explicitly asked; if there's no current project, ask which to use.`),
     // FORKED: the desktop sends core tools plus what `slates_load_tools` loaded,
     // 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/generation-policy.d.ts

@@ -2,7 +2,7 @@
  * This is NOT a model capability or provider batch limit. Desktop mirror is
  * generated by slate/scripts/sync-generation-policy.mjs; never edit it there. */
 export declare const IMAGE_QUANTITIES: readonly [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
-export declare const MAX_IMAGE_VARIATIONS: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
+export declare const MAX_IMAGE_VARIATIONS: 1 | 2 | 4 | 5 | 3 | 10 | 8 | 7 | 6 | 9;
 export type ImageQuantity = typeof IMAGE_QUANTITIES[number];
 export declare const clampImageQuantity: (count?: number) => ImageQuantity;
 /** Default saved-recipe framing, shared by composer restore, quote and dispatch. */

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