@slatesvideo/shared 0.6.1 → 0.6.3

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

@@ -0,0 +1,36 @@
+/**
+ * Which agent surface is being briefed.
+ *
+ * `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.
+ */
+export type AgentSurface = 'desktop' | 'mcp';
+interface SkillIndexEntry {
+    name: string;
+    description: string;
+}
+/** Parse `name:`/`description:` out of each embedded skill's frontmatter. */
+export declare function buildSkillIndex(): SkillIndexEntry[];
+export declare const WORKING_METHOD: ReadonlyArray<Record<AgentSurface, string>>;
+export declare const HARD_RULES: ReadonlyArray<Record<AgentSurface, string>>;
+/**
+ * THE doctrine string for a surface. The desktop's whole system prompt and the
+ * MCP server's `instructions` are both exactly this — neither consumer adds
+ * doctrine prose of its own.
+ *
+ * SENTINEL: the literal below must appear in this workspace in exactly ONE
+ * file — this one. scripts/agent-surface-lockstep-check.mjs assembles the same
+ * string from its parts rather than writing it out, precisely so that grepping
+ * for it stays a meaningful question. It is how "no consumer grew a private
+ * copy of the doctrine" is proved rather than assumed.
+ * SLATES-AGENT-DOCTRINE-SSOT
+ */
+export declare function buildAgentDoctrine({ surface }: {
+    surface: AgentSurface;
+}): string;
+export {};
+//# sourceMappingURL=agent-doctrine.d.ts.map

package/dist/prompts/agent-doctrine.js

@@ -0,0 +1,194 @@
+// ============================================================
+// AGENT GUIDANCE SSOT — one doctrine, both surfaces.
+//
+// `ALL_OPERATIONS` has been the SSOT for what the agent CAN DO since the ops
+// registry was built, and it held. The guidance layer — the working method,
+// the hard rules, the guide index — never was, and it drifted the moment a
+// second surface existed: a 37K-character system prompt reached ONLY the
+// desktop Studio Agent, while the MCP server shipped no `instructions` at all.
+// A Claude Code user got tool descriptions and nothing else: no working
+// method, no REAL NUMBERS rule, no guide index.
+//
+// This module is that missing SSOT. Both surfaces compose from it:
+//   slate/src/main/studio-agent/context.ts  buildSystemPrompt()
+//   slates-mcp/packages/mcp/src/server.ts   `instructions` on the Server
+//
+// 🚨 RULES
+//
+// 1. ONE DOCTRINE STRING, ONE FILE. Any working-method or hard-rule prose
+//    living in a consumer after this is a bug. `context.ts` composes; it does
+//    not author.
+// 2. SURFACE-AWARE, NOT SURFACE-FORKED. A step or rule forks ONLY where the
+//    mechanism genuinely differs (the desktop's `present_plan` gate does not
+//    exist on MCP; the desktop's loop auto-polls generation status and MCP's
+//    does not). Everything else is one string used by both. Two hand-maintained
+//    copies is the drift this file exists to kill — so `both()` is the default
+//    and `fork()` needs a reason you could defend in review.
+// 3. PROSE IS EXPLANATION, NOT ENFORCEMENT. The two rules the agent actually
+//    breaks — "load the guide" and "quality-check with vision" — are enforced
+//    STRUCTURALLY in the op layer (generated banned-token lists inlined into
+//    the generate ops' descriptions, non-blocking warnings on the submitted
+//    prompt, and a review pointer on every generation result). A rule with no
+//    check is a suggestion, and an LLM is the least reliable enforcer you
+//    could pick. Do not "fix" a skipped rule by adding a sentence here.
+// 4. NEVER BLOCK. PRODUCT_PHILOSOPHY.md → the Sandbox Doctrine: make state
+//    visible, never block. Enforcement means the guidance is already present
+//    and violations are reported back — never a refused call or a wizard step.
+// 5. CACHE DISCIPLINE. This output is the desktop's cached prompt prefix and
+//    its byte-stability IS the cache mechanism (measured 97.4% steady-state
+//    cache hit). No timestamps, no balances, no project names, no per-session
+//    anything. Dynamic state reaches the brain through ops, never through here.
+//
+// SSOT DISCIPLINE: this module no longer renders model routing AT ALL. Routing
+// rides `describeRouting()` on the four ops that choose a model, because that is
+// where the choice is made; all the doctrine says is that the three KINDS are
+// disjoint, which is the one part no single op can say. The guide index is
+// DERIVED from SKILLS. Never hand-type either.
+//
+// Not exported from ./prompts on purpose: that subpath is bundled by the
+// desktop RENDERER and must stay small and Node-free, and this module pulls in
+// the whole embedded SKILLS record. Root barrel only.
+// ============================================================
+import { SKILLS } from '../skills/content.js';
+import { VIDEO_MODELS, AUDIO_MODELS } from '../operations/index.js';
+/** A line that is identical on both surfaces. The default. */
+function both(text) {
+    return { desktop: text, mcp: text };
+}
+/** A line whose MECHANISM differs between surfaces. Needs a reason in-comment. */
+function fork(desktop, mcp) {
+    return { desktop, mcp };
+}
+/** Parse `name:`/`description:` out of each embedded skill's frontmatter. */
+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;
+}
+// ── Preamble ───────────────────────────────────────────────────────
+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, through its MCP tool surface. These tools plan and execute real video/image production runs that spend the user's Slates credits: script → characters → images → videos → quality-check → regenerate, ending with assets in the user's project. Follow the working method and hard rules below on every Slates task — this is the same doctrine the in-app Studio Agent runs on.`);
+// ── The working method ─────────────────────────────────────────────
+export const WORKING_METHOD = [
+    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.`),
+    both(`3. LOAD KNOWLEDGE ON DEMAND: before prompting any model or running a multi-step workflow, load the matching guide with slates_get_prompting_guide (index below). Only the guides the task needs, when it needs them.`),
+    // 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
+    // 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(`7. REPORT: when done, summarize what was made and where it landed. Concise and concrete.`),
+];
+// ── Hard rules ─────────────────────────────────────────────────────
+//
+// Each entry is a COMPLETE line including its leading "- ". MODEL ROUTING is
+// the exception: it is multi-line and generated, and supplies its own bullet.
+export const HARD_RULES = [
+    // FORKED: "outside an approved plan" names the desktop's code-level gate.
+    fork(`- COST DISCIPLINE (slates-cost-discipline): never fire a billable generation outside an approved plan. Estimate before you promise. Batch related generations into one plan.`, `- COST DISCIPLINE (slates-cost-discipline): never fire a billable generation the user has not agreed to. Estimate before you promise. Batch related generations into one quote so the user approves a total, not a drip.`),
+    both(`- CONTENT POLICY: before writing prompts involving real people/celebrities, minors, brands/logos, weapons, or gore, load slates-content-policy and build the scene safe from the first word. If a provider rejects (e.g. real-face detection), explain in plain language — refunds for provider rejections are automatic.`),
+    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(`- RESOLUTION DEFAULT IS UNIFORM: 1080p on the best available video model. 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
+    // now rides the op that actually makes the decision: describeRouting('image')
+    // in slates_generate_image, ('video','generate') in slates_generate_video's
+    // model param, ('video','edit') in slates_edit_video, ('audio') in
+    // slates_generate_audio. An op description is always in context on both
+    // surfaces, so nothing was lost in reach — it moved next to the choice.
+    //
+    // The measured argument for doing this: the never-use token list went from 0%
+    // to 94% compliance when it moved from prose into an op description, while
+    // the same guidance in prose moved nothing. Placement beats presence.
+    // 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(`- 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. 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(`- 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
+    // polling for you" would strand a job nobody is watching.
+    fork(`- TOKEN DISCIPLINE: every tool result you read costs the user money. generate_* results already return the new asset ids/codes — NEVER call slates_list_assets to find something you just created. When you do list, pass search/type/limit filters. Poll generation status ONCE with waitSeconds: 45 — the app keeps auto-polling for you and returns the terminal status; do not narrate between polls or call status in a loop. Use slates_estimate_generation_cost for known models instead of dumping the registry; if you need the registry, pass a filter.`, `- TOKEN DISCIPLINE: every tool result you read costs the user money. generate_* results already return the new asset ids/codes — NEVER call slates_list_assets to find something you just created. When you do list, pass search/type/limit filters. Poll generation status with waitSeconds: 45 — one long poll per check, no tight loops and no narration between polls. Use slates_estimate_generation_cost for known models instead of dumping the registry; if you need the registry, pass a filter.`),
+    // FORKED: the desktop app renders orchestration cost itself; there is no such
+    // display on MCP, so that clause would point at nothing. The MCP variant
+    // spends the saved words on the claim an MCP client is most likely to
+    // fabricate: what the generation LOOKS like.
+    fork(`- REAL NUMBERS ONLY — NEVER approximate, estimate, or recall any figure. Every cost, balance, count, or duration you state must be copied verbatim from a tool result IN THIS SESSION: generation costs come from the cost_credits field in generate/status results (whole credits); the balance comes from a fresh slates_get_credit_balance call at summary time (never arithmetic you did yourself); orchestration cost is displayed by the app automatically — NEVER state or estimate it. No "approx", no "~", no rounded guesses. A number you cannot point to in a tool result is a number you do not say.`, `- REAL NUMBERS ONLY — NEVER approximate, estimate, or recall any figure. Every cost, balance, count, or duration you state must be copied verbatim from a tool result IN THIS SESSION: generation costs come from the cost_credits field in generate/status results (whole credits); the balance comes from a fresh slates_get_credit_balance call at summary time (never arithmetic you did yourself). No "approx", no "~", no rounded guesses. A number you cannot point to in a tool result is a number you do not say. The same rule covers what you SAW: never describe how a generation looks unless you fetched it this session with slates_get_asset_image / slates_get_asset_video_frames.`),
+    both(`- MODEL IDS ARE FIXED: slates_generate_video takes exactly ${VIDEO_MODELS.join(' | ')}, with duration + videoResolution as separate params. slates_generate_audio takes exactly ${AUDIO_MODELS.join(' | ')}. Registry entries like "kling-v3-standard-8s" or "seed-audio-15s" are billing keys, not model ids.`),
+    both(`- AUDIO LENGTH IS PROMPT-DRIVEN ON SEED AUDIO: it has no duration parameter, so the durationSeconds you pass is written into the prompt AND is what the user is charged, whatever comes back. Choose it deliberately and load slates-prompting-seed-audio before the first call.`),
+];
+// ── 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
+// 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.
+`;
+/**
+ * THE doctrine string for a surface. The desktop's whole system prompt and the
+ * MCP server's `instructions` are both exactly this — neither consumer adds
+ * doctrine prose of its own.
+ *
+ * SENTINEL: the literal below must appear in this workspace in exactly ONE
+ * file — this one. scripts/agent-surface-lockstep-check.mjs assembles the same
+ * string from its parts rather than writing it out, precisely so that grepping
+ * for it stays a meaningful question. It is how "no consumer grew a private
+ * copy of the doctrine" is proved rather than assumed.
+ * SLATES-AGENT-DOCTRINE-SSOT
+ */
+export function buildAgentDoctrine({ surface }) {
+    // COMPRESSED on purpose (2026-08-30). The full frontmatter descriptions were
+    // 14,556 characters — 38% of the doctrine — and they are DISCOVERY blurbs,
+    // written in Claude Code's "Use when X, or when Y" style for a fuzzy matcher
+    // choosing among skills. Here the mapping is close to deterministic:
+    // `resolveGuideTopic()` turns a model id into the right guide in code.
+    //
+    // So the per-model guides are listed as bare names (the name IS the
+    // description) and everything else keeps its FIRST SENTENCE, which is the
+    // part that says when to reach for it. The complete list with full
+    // descriptions is one `slates_get_prompting_guide` call away.
+    const entries = buildSkillIndex();
+    const firstSentence = (d) => {
+        const m = /^(.*?[.!?])(\s|$)/.exec(d.trim());
+        return (m ? m[1] : d.trim()).slice(0, 180);
+    };
+    const perModel = entries.filter((s) => s.name.startsWith('slates-prompting-'));
+    const rest = entries.filter((s) => !s.name.startsWith('slates-prompting-'));
+    const skillIndex = rest.map((s) => `- ${s.name}: ${firstSentence(s.description)}`).join('\n') +
+        `\n- PER-MODEL PROMPTING GUIDES — pass the model id, or the name: ` +
+        perModel.map((s) => s.name).join(', ');
+    return `${PREAMBLE[surface]}
+
+## How you work
+
+${WORKING_METHOD.map((s) => s[surface]).join('\n')}
+
+## Hard rules
+
+${HARD_RULES.map((r) => r[surface]).join('\n')}
+
+## Guide index (load via slates_get_prompting_guide)
+
+${skillIndex}
+${surface === 'mcp' ? `\n${MCP_FOOTER}` : ''}`;
+}
+//# sourceMappingURL=agent-doctrine.js.map

package/dist/prompts/banned-tokens.d.ts

@@ -0,0 +1,28 @@
+/** Which generate op a list applies to. */
+export type BannedTokenScope = 'image' | 'video';
+export interface BannedToken {
+    /** The literal phrase, verbatim from the skill. */
+    token: string;
+    /** Skill file it was read from — cited in every warning. */
+    skill: string;
+    scope: BannedTokenScope;
+}
+/** Every banned token, in skill-document order. Integrity asserted at load. */
+export declare const BANNED_PROMPT_TOKENS: readonly BannedToken[];
+export declare function bannedTokensFor(scope: BannedTokenScope): readonly BannedToken[];
+/** The tokens a submitted prompt actually contains. */
+export declare function findBannedTokens(prompt: string, scope: BannedTokenScope): BannedToken[];
+/**
+ * The list as it appears INSIDE an op description — always in context, on both
+ * surfaces, with no call required to see it. Generated, never hand-typed.
+ */
+export declare function describeBannedTokens(scope: BannedTokenScope): string;
+/**
+ * Non-blocking warning for a submitted prompt. Empty string when clean.
+ *
+ * Returned in the op RESULT — the one place the agent cannot avoid reading —
+ * rather than raised as an error. The generation proceeds either way: the
+ * sandbox doctrine says make state visible, never block.
+ */
+export declare function bannedTokenWarning(prompt: string, scope: BannedTokenScope): string;
+//# sourceMappingURL=banned-tokens.d.ts.map

package/dist/prompts/banned-tokens.js

@@ -0,0 +1,152 @@
+// ============================================================
+// BANNED PROMPT TOKENS — the "load the guide" rule, made structural.
+//
+// THE PROBLEM: "before prompting any model, load the matching guide" is a
+// sentence in a system prompt with nothing checking it. Measured 2026-08-30 in
+// a real Studio Agent session: slates_get_prompting_guide was called ZERO
+// times, and the prompt that shipped tripped the skill's own never-use list
+// twice (`photorealistic`, `cinematic`). A rule with no check is a suggestion,
+// and an LLM is the least reliable enforcer you could pick.
+//
+// THE FIX, in two halves, neither of which the model can skip:
+//   (a) the never-use list is INLINED into the generate ops' descriptions.
+//       Op descriptions are always in context on BOTH surfaces — there is no
+//       call to omit and no discretion to exercise.
+//   (b) the submitted prompt is MATCHED against the list and a warning comes
+//       back in the op result. Non-blocking: the generation proceeds
+//       (PRODUCT_PHILOSOPHY.md → make state visible, never block).
+//
+// 🚨 THE LIST IS NEVER HAND-TYPED HERE. It is extracted from the skill files
+// themselves, between `<!-- @banned:start -->` / `<!-- @banned:end -->`
+// markers. That is this workspace's LLM-docs doctrine — never hand-type a fact
+// an LLM will read — and it is the only way the op description and the skill
+// cannot drift apart. Change the skill; the description follows on the next
+// build. scripts/agent-surface-lockstep-check.mjs fails the build if a token
+// in a description no longer appears in its source skill.
+//
+// Deterministic by construction (document order, no sorting, no dedupe
+// reshuffle) because these strings land in the desktop's prompt-cached tool
+// prefix, whose byte-stability IS the cache mechanism.
+// ============================================================
+import { SKILLS } from '../skills/content.js';
+/**
+ * Where each scope's list lives.
+ *
+ * One skill per scope on purpose: these are the two lists that are GENERIC to
+ * their modality (Stable-Diffusion-era tag soup for images, quality
+ * incantations for video), not model-specific quirks. A per-model list would
+ * mean the op description changed with the `model` argument, which it cannot —
+ * a description is one static string for every call.
+ */
+const BANNED_TOKEN_SOURCES = [
+    { skill: 'slates-prompting-nano-banana-2', scope: 'image' },
+    { skill: 'slates-prompting-seedance', scope: 'video' },
+];
+const FENCE_RE = /<!--\s*@banned:start\s*-->([\s\S]*?)<!--\s*@banned:end\s*-->/g;
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+const BACKTICKED_RE = /`([^`\n]+)`/g;
+/**
+ * Pull every backticked phrase out of a skill's fenced block(s).
+ *
+ * HTML comments are stripped FIRST: the fence carries a "MACHINE-READ" note to
+ * whoever edits the skill next, and that note itself contains backticks.
+ */
+function extractFromSkill(skill) {
+    const content = SKILLS[skill];
+    if (content === undefined) {
+        throw new Error(`[banned-tokens] no such skill: ${skill}. BANNED_TOKEN_SOURCES must name files in packages/shared/skills/.`);
+    }
+    const out = [];
+    let fence;
+    FENCE_RE.lastIndex = 0;
+    let fences = 0;
+    while ((fence = FENCE_RE.exec(content)) !== null) {
+        fences += 1;
+        const body = fence[1].replace(HTML_COMMENT_RE, '');
+        let m;
+        BACKTICKED_RE.lastIndex = 0;
+        while ((m = BACKTICKED_RE.exec(body)) !== null) {
+            const token = m[1].trim();
+            if (token && !out.includes(token))
+                out.push(token);
+        }
+    }
+    if (fences === 0) {
+        throw new Error(`[banned-tokens] ${skill}.md has no <!-- @banned:start --> / <!-- @banned:end --> block. ` +
+            `The op description and the prompt warnings are GENERATED from it — restore the markers, ` +
+            `or drop the skill from BANNED_TOKEN_SOURCES.`);
+    }
+    if (out.length === 0) {
+        throw new Error(`[banned-tokens] ${skill}.md has a @banned block with no backticked tokens in it. ` +
+            `An empty list would silently disable the check instead of failing it.`);
+    }
+    return out;
+}
+/** Every banned token, in skill-document order. Integrity asserted at load. */
+export const BANNED_PROMPT_TOKENS = BANNED_TOKEN_SOURCES.flatMap(({ skill, scope }) => extractFromSkill(skill).map((token) => ({ token, skill, scope })));
+const byScope = new Map();
+for (const entry of BANNED_PROMPT_TOKENS) {
+    const list = byScope.get(entry.scope) ?? [];
+    list.push(entry);
+    byScope.set(entry.scope, list);
+}
+export function bannedTokensFor(scope) {
+    return byScope.get(scope) ?? [];
+}
+/** Regex cache — one word-boundary matcher per token, built once. */
+const matchers = new Map();
+function matcherFor(token) {
+    let re = matchers.get(token);
+    if (!re) {
+        const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        // \b at both ends so `4k` does not fire inside "84king" and `flawless`
+        // does not fire inside "flawlessly". Every token starts and ends with a
+        // word character today; if one ever starts with punctuation, \b would
+        // anchor wrong — the load-time check below is what would catch it.
+        re = new RegExp(`\\b${escaped}\\b`, 'i');
+        matchers.set(token, re);
+    }
+    return re;
+}
+for (const { token, skill } of BANNED_PROMPT_TOKENS) {
+    if (!/^\w/.test(token) || !/\w$/.test(token)) {
+        throw new Error(`[banned-tokens] ${skill}: token ${JSON.stringify(token)} does not start and end with a word ` +
+            `character, so the \\b word-boundary match would never fire. Rewrite the entry or teach ` +
+            `matcherFor() the new shape.`);
+    }
+}
+/** The tokens a submitted prompt actually contains. */
+export function findBannedTokens(prompt, scope) {
+    return bannedTokensFor(scope).filter((b) => matcherFor(b.token).test(prompt));
+}
+/**
+ * The list as it appears INSIDE an op description — always in context, on both
+ * surfaces, with no call required to see it. Generated, never hand-typed.
+ */
+export function describeBannedTokens(scope) {
+    const list = bannedTokensFor(scope);
+    if (list.length === 0)
+        return '';
+    const skills = [...new Set(list.map((b) => b.skill))].join(' / ');
+    return (`NEVER put these in a prompt (they measurably degrade output — full rationale in ${skills}): ` +
+        list.map((b) => `"${b.token}"`).join(', ') +
+        `. Describe specifically instead.`);
+}
+/**
+ * Non-blocking warning for a submitted prompt. Empty string when clean.
+ *
+ * Returned in the op RESULT — the one place the agent cannot avoid reading —
+ * rather than raised as an error. The generation proceeds either way: the
+ * sandbox doctrine says make state visible, never block.
+ */
+export function bannedTokenWarning(prompt, scope) {
+    const hits = findBannedTokens(prompt, scope);
+    if (hits.length === 0)
+        return '';
+    const skills = [...new Set(hits.map((b) => b.skill))].join(', ');
+    return (`⚠️ PROMPT WARNING: your prompt contains ${hits.map((b) => `"${b.token}"`).join(', ')} — ` +
+        `on the never-use list in ${skills}. Not blocked, and this generation ran as submitted. ` +
+        `Load that guide with slates_get_prompting_guide and rewrite with specific description ` +
+        `(named lens, light direction, stock, composition) before the next generation.`);
+}
+//# sourceMappingURL=banned-tokens.js.map

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

@@ -6,8 +6,20 @@ export type AspectRatio = '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '5:4'
  * and prices between 480p and 2K ($0.060/s vs 720p Seedance's $0.15/s — a
  * different tier of a different model, not a rename); 2K is H3's upscaled tier.
  * Aliasing either onto 720p/1080p would build a cost key that does not exist.
+ *
+ * 🚨 `1440p` entered with LTX-2.5 (2026-08-29) and is likewise NOT an alias —
+ * specifically it is NOT `2k`, despite both being ~1440 lines tall. `2k` is
+ * H3's UPSCALED tier ($0.130/s, an H3-Regenerate-2K pass over a 768p base);
+ * `1440p` is LTX's NATIVELY GENERATED tier ($0.190/s). Different models,
+ * different mechanisms, different prices, and `ltx-2-5-2k-6s` is a key that
+ * exists nowhere. Co-height is not sameness.
+ *
+ * ⚠️ Our `4k` is LTX's `2160p` ON THE WIRE. fal's enum literal for that tier is
+ * `2160p` while its own pricing copy calls it "4K". `4k` stays the token here
+ * because it is what every cost key, `is4kVideoKey` and the Pro gate already
+ * speak; the handler translates at the request boundary.
  */
-export type VideoResolution = '480p' | '720p' | '768p' | '1080p' | '2k' | '4k';
+export type VideoResolution = '480p' | '720p' | '768p' | '1080p' | '1440p' | '2k' | '4k';
 /**
  * The full ten, in display order. `9:21` was in the MCP op's enum and in NO
  * model — it was invented downstream. Do not add a ratio here that no model

package/dist/prompts/model-capabilities.js

@@ -88,6 +88,18 @@ const SEEDANCE_ASPECT_RATIOS = ['21:9', '16:9', '4:3', '1:1', '3:4', '9:16'];
  *     is not an AspectRatio in this vocabulary.
  */
 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.
+ *
+ * `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 —
+ * identical treatment to H3's `adaptive`, and for the identical reason: the
+ * composer always holds an explicit ratio, so `auto` would only ever be a way
+ * to lose track of what was actually generated.
+ */
+const LTX_2_5_ASPECT_RATIOS = ['16:9', '9:16'];
 /**
  * The provider every AGENT generation actually lands on for Kling and Veo.
  *
@@ -371,6 +383,87 @@ export const MODEL_CAPABILITIES = {
         // above what the handler sends is a SILENT DROP — the exact failure
         // `seedance-2.5-edit` shipped with. Absent means the composer refuses.
     },
+    // ── LTX-2.5 (both seats on fal — added 2026-08-29) ─────────────────────────
+    //
+    // Every value below is READ OFF fal's live OpenAPI, fetched 2026-08-29:
+    //   lightricks/ltx-2.5/{text-to-video,image-to-video}/{fast,pro}
+    // Note the owner namespace — no `fal-ai/` prefix, exactly like `minimax/h3/`.
+    //
+    // 🚨 SAME PREFIX COLLISION AS THE MINIMAX PAIR, AND IT IS WORSE HERE.
+    // `ltx-2-5-pro` starts with `ltx-2-5`, so ANY `startsWith('ltx-2-5')` swallows
+    // the Pro row into the Fast row's branch — a shorter ladder, a shorter
+    // duration list AND a 31-33% higher price at both tiers they share. Every
+    // lookup downstream is an exact-id map, never a prefix test.
+    //
+    // 🚨 THE CHEAP ROW IS THE ONE WITH THE LONGER REACH. Counter to how every
+    // other Fast/Pro pair in this file behaves, `ltx-2-5` (the distilled 8-step
+    // build) reaches 1440p, 4K and 20s while `ltx-2-5-pro` (full diffusion) stops
+    // at 1080p and 10s. Pro buys fidelity on a NARROWER ladder. Do not "fix" this
+    // by assuming Pro is a superset — it is not, on either axis.
+    //
+    // ⛔ `audio-to-video/{fast,pro}` EXIST AND ARE DELIBERATELY ABSENT from this
+    // file. They carry no `resolution` and no `duration` parameter at all: output
+    // length is dictated by the uploaded audio, so they bill per second of INPUT
+    // while every credit key we own bills OUTPUT. That is a billing-SHAPE change,
+    // not a missing row. See slates-api/PRICING.md.
+    'ltx-2-5': {
+        aspectRatios: LTX_2_5_ASPECT_RATIOS,
+        // Full ladder, all four tiers NATIVELY generated (no upscale pass anywhere
+        // — the contrast with H3's 2K/4K is the whole reason `1440p` is its own
+        // token). DEFAULT 1080p, which is also fal's own schema default: unusually
+        // for this file the default tier is not the floor. It is the cheapest
+        // native 1080p second in the roster at $0.130/s.
+        videoResolution: { options: ['720p', '1080p', '1440p', '4k'], default: '1080p' },
+        // 🚨 DISCRETE AND EVEN-ONLY. There is NO 5s LTX clip and no odd duration of
+        // any length — fal's enum is literally [6,8,10,12,14,16,18,20]. A
+        // `{ min: 6, max: 20, mode: 'continuous' }` here would offer 7s in the
+        // composer, quote a `ltx-2-5-1080p-7s` key that exists on no server, and
+        // fail at the proxy after the user had already chosen it.
+        //
+        // The evenness is also what makes all 28 cost keys round exactly (every
+        // basis is a multiple of CENTS_PER_CREDIT=3) — see PRICING.md. If fal ever
+        // admits odd seconds, the rounding proof must be re-verified.
+        duration: {
+            min: 6,
+            max: 20,
+            mode: 'discrete',
+            values: [6, 8, 10, 12, 14, 16, 18, 20],
+            // fal: "At 720p and 1080p, 24 or 25 FPS supports up to 20 seconds […] At
+            // 1440p and 2160p, all frame rates support up to 10 seconds."
+            //
+            // ⚠️ THE REAL CEILING IS A FUNCTION OF RESOLUTION *AND* FPS, and this
+            // field can only express the resolution half. It is correct ONLY because
+            // we pin fps to fal's default of 25 and never expose the control. If fps
+            // is ever exposed, 48/50 drops the 720p/1080p ceiling to 10s too, and
+            // that needs a second override axis — not a wider window here.
+            resolutionOverrides: {
+                '1440p': { min: 6, max: 10, mode: 'discrete', values: [6, 8, 10] },
+                '4k': { min: 6, max: 10, mode: 'discrete', values: [6, 8, 10] },
+            },
+        },
+        // NO reference caps of any kind, deliberately. fal publishes text-to-video
+        // and image-to-video for LTX and NOTHING else — there is no
+        // `reference-to-video` endpoint, so there is no transport for an ingredient
+        // or a multimodal reference, and a cap declared above what the handler
+        // sends is a SILENT DROP (the failure `seedance-2.5-edit` shipped with).
+        // The start/end frames i2v does carry are FRAME SLOTS, not references, and
+        // live in MODEL_REGISTRY.features.lastFrame — not here.
+    },
+    'ltx-2-5-pro': {
+        aspectRatios: LTX_2_5_ASPECT_RATIOS,
+        // 720p/1080p ONLY. Declaring the shorter ladder here IS the whole Pro-seat
+        // mechanism: `assertVideoCapabilities` refuses 1440p/4K on this id, the
+        // desktop picker renders only what this entry declares, and the agent's Zod
+        // enum stays the union while the per-model guard narrows. Anything shaped
+        // like "hide the top tiers when Pro is selected" re-implements a guard that
+        // already exists.
+        videoResolution: { options: ['720p', '1080p'], default: '1080p' },
+        // Three values, full stop — fal's enum is [6,8,10] on both Pro endpoints,
+        // with no resolution override needed because the ceiling is already 10s at
+        // both tiers this row reaches.
+        duration: { min: 6, max: 10, mode: 'discrete', values: [6, 8, 10] },
+        // No reference caps — same reasoning as the Fast row above.
+    },
     // ── Audio ──────────────────────────────────────────────────────────────────
     //
     // `aspectRatios: []` is deliberate, not an oversight: audio has no frame, and
@@ -461,8 +554,10 @@ export function aspectRatioUnion(models, provider) {
 /** Union of every resolution the given models accept. */
 export function videoResolutionUnion(models) {
     // Ascending by output height, so an enum reads as a ladder. 768p sits between
-    // 720p and 1080p; 2k (≈2560×1440) between 1080p and 4k.
-    const order = ['480p', '720p', '768p', '1080p', '2k', '4k'];
+    // 720p and 1080p; 1440p and 2k (≈2560×1440) are CO-HEIGHT and sit together
+    // between 1080p and 4k — their relative order here is cosmetic, because no
+    // model declares both (1440p is LTX-only, 2k is H3-only).
+    const order = ['480p', '720p', '768p', '1080p', '1440p', '2k', '4k'];
     const seen = new Set();
     for (const m of models)
         for (const r of videoResolutionsFor(m))

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

@@ -2,6 +2,14 @@ export interface ModelFact {
     id: string;
     label: string;
     kind: 'image' | 'video' | 'audio';
+    /**
+     * Which op this seat is reachable through. `edit` rows live on
+     * slates_edit_video and must never appear in slates_generate_video's routing
+     * list — they were mixed into one VIDEO block with nothing marking them.
+     * Explicit rather than an id-suffix test: a structural test on "-edit" holds
+     * only while that substring is unique, which is how isOmniFlashModel broke.
+     */
+    route: 'generate' | 'edit';
     /** Max reference images (image models) — null if not applicable. */
     maxRefImages: number | null;
     /** Max ingredient images (video models) — null if not applicable. */
@@ -59,6 +67,18 @@ export declare function seedanceTaskIntentWords(prompt: string): string[];
 /** Every model that reads reference video and/or audio, for op descriptions. */
 export declare function multimodalRefModels(): string[];
 export declare const MODEL_FACTS: ModelFact[];
+/**
+ * Routing prose for one lane, generated from the SSOT.
+ *
+ * THE ONE RENDERER. The Studio Agent's system prompt, the MCP server's
+ * instructions and the generate/edit ops' `model` descriptions all call this —
+ * so "never restate model routing in an op description" (slates-mcp/CLAUDE.md)
+ * is now enforced by there being nothing to restate. Before this, the video op
+ * carried 1,282 characters of hand-written routing that repeated MODEL_FACTS
+ * phrase for phrase ("SECOND SEAT", "AUTHORED-AUDIO", "never the default"),
+ * in the same file that forbids exactly that.
+ */
+export declare function describeRouting(kind: ModelFact['kind'], route?: ModelFact['route']): string;
 export declare function getModelFact(id: string): ModelFact | undefined;
 /** The official NB2 / general image prompt formula (subject-first). */
 export declare const IMAGE_PROMPT_FORMULA = "[Subject] + [Action] + [Location/context] + [Composition] + [Style]";