@slatesvideo/shared 0.6.2 → 0.6.4

package/dist/operations/surface.d.ts

@@ -0,0 +1,69 @@
+import type { z } from 'zod';
+import type { OperationAnnotations, OperationGroup, OperationTier } from './index.js';
+/** Structural shape of an op, declared locally so this module never imports a
+ *  VALUE from the registry (which imports this one). */
+export interface SurfaceOp {
+    id: string;
+    description: string;
+    input: z.ZodType<unknown>;
+    billable?: boolean;
+    tier?: OperationTier;
+    group?: OperationGroup;
+    annotations?: OperationAnnotations;
+}
+/**
+ * Derive an op's four hints.
+ *
+ * `openWorldHint` means "reaches something outside this system": every billable
+ * op hits a provider, and every Blender op hits a separate process over a
+ * socket. Everything else touches only the user's own workspace.
+ */
+export declare function annotate(id: string, billable: boolean | undefined): OperationAnnotations;
+/**
+ * The deferred groups, by op id. Everything NOT listed here is `core`.
+ *
+ * The cut is "what a session needs to do the work" versus "what it needs once,
+ * when the user asks for that thing". Creating, generating, reviewing and
+ * shot-listing are core; tidying the library, cutting a timeline, renaming and
+ * deleting, and driving Blender are not — and each is a coherent thing a user
+ * asks for by name, which is what makes a group loadable in one call.
+ *
+ * 🚨 A GROUP IS A BUDGET, NOT A LAW. If `final_state` falls on timeline or
+ * library tasks after this shipped, move those ops back to core. The point is
+ * the per-turn byte count, and a deferral that costs a turn every time is not
+ * paying for itself.
+ */
+export declare const OPERATION_GROUPS: Record<OperationGroup, readonly string[]>;
+export declare function groupFor(id: string): OperationGroup | undefined;
+/** `extended` iff the op names a group. Absent from every group ⇒ `core`, so a
+ *  new op is visible until someone deliberately defers it. */
+export declare function tierFor(id: string): OperationTier;
+/** One-line summary of each group, for `slates_load_tools`' own description. */
+export declare const GROUP_SUMMARY: Record<OperationGroup, string>;
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    /** JSON Schema. Both surfaces read the same object under their own key name. */
+    inputSchema: Record<string, unknown>;
+    annotations: OperationAnnotations;
+}
+/**
+ * Render one op's tool definition.
+ *
+ * `$refStrategy: 'none'` is the shape both surfaces now emit: inlined, so no
+ * client has to resolve a `$ref`, and byte-identical between them — which is
+ * what makes "the two surfaces expose the same tools" checkable rather than
+ * merely asserted about the id set.
+ */
+export declare function toolDefinition(op: SurfaceOp): ToolDefinition;
+/**
+ * Render a tool surface.
+ *
+ * `desktop` sends `core` plus whatever groups have been loaded this run; `mcp`
+ * sends everything, because a stdio server has no run to append to.
+ */
+export declare function toolDefinitions(ops: readonly SurfaceOp[], opts: {
+    surface: 'desktop' | 'mcp';
+    groups?: readonly OperationGroup[];
+}): ToolDefinition[];
+//# sourceMappingURL=surface.d.ts.map

package/dist/operations/surface.js

@@ -0,0 +1,227 @@
+// ============================================================
+// THE TOOL SURFACE: annotations, tiers, and the ONE schema renderer.
+//
+// Three jobs that all answer "what does a client see, and when":
+//
+//   1. ANNOTATIONS (MCP spec 2025-06-18). `readOnlyHint` / `destructiveHint` /
+//      `idempotentHint` / `openWorldHint`, so a host can auto-approve a read
+//      and warn on a delete. Without them `slates_list_assets` prompts exactly
+//      like `slates_delete_project`, every prompt looks the same, and the user
+//      learns to click through all of them.
+//
+//   2. TIERS. 90 ops is 112 KB of descriptions and JSON schemas on EVERY
+//      desktop Studio Agent turn. `core` is what a session needs to work;
+//      `extended` is deferred behind `slates_load_tools` and appended to the
+//      run's tool list once a group loads. The MCP server still registers
+//      everything — a stdio server has no run to append to, and Claude Code
+//      already defers stdio tool schemas through its own tool search.
+//
+//   3. ONE SCHEMA RENDERER. The desktop rendered `$refStrategy: 'none'` and
+//      the MCP server rendered `target: 'openApi3'`, so "the two surfaces
+//      expose the same tools" was true of the ID SET and unproven of the
+//      BYTES. `toolDefinitions()` is now the only renderer either one calls.
+//
+// 🚨 NOTHING HERE IS HAND-SET PER OP. Annotations are derived from the op id
+// by the rules below, and `scripts/agent-surface-lockstep-check.mjs` re-derives
+// them INDEPENDENTLY from each op's own transport verbs — a `readOnlyHint` on
+// 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 { zodToJsonSchema } from 'zod-to-json-schema';
+// ── 1. Annotations ──────────────────────────────────────────────────────────
+/** Ops that only read. Prefixes, because the verb IS the first word of the id. */
+const READ_ONLY_PREFIXES = [
+    'slates_get_',
+    'slates_list_',
+    'slates_estimate_',
+    'slates_blender_status',
+    'slates_blender_scene',
+    'slates_blender_docs',
+    'slates_blender_search_docs',
+];
+/**
+ * Ops whose effect a user cannot undo from inside Slates.
+ *
+ * Moves are here on purpose: `slates_move_assets_to_project` relocates files on
+ * disk, and an agent that guessed the wrong project has no "put it back"
+ * without knowing where they came from. A rename is recoverable; a move across
+ * projects, in practice, is not.
+ */
+const DESTRUCTIVE_IDS = new Set([
+    'slates_delete_project',
+    'slates_delete_asset',
+    'slates_delete_folder',
+    'slates_delete_character',
+    'slates_delete_environment',
+    'slates_delete_style',
+    'slates_delete_storyboard',
+    'slates_delete_scene',
+    'slates_delete_frame',
+    'slates_move_assets_to_folder',
+    'slates_move_assets_to_project',
+    'slates_move_entity_to_project',
+    'slates_merge_shots',
+    'slates_split_shot',
+]);
+/** Same input, same end state — `update`/`set`/`reorder`/`rename` all overwrite
+ *  rather than append, so re-running one is a no-op rather than a second edit. */
+const IDEMPOTENT_PREFIXES = [
+    'slates_update_',
+    'slates_set_',
+    'slates_reorder_',
+    'slates_rename_',
+    'slates_batch_update_',
+];
+const startsWithAny = (id, prefixes) => prefixes.some((p) => id.startsWith(p));
+/**
+ * Derive an op's four hints.
+ *
+ * `openWorldHint` means "reaches something outside this system": every billable
+ * op hits a provider, and every Blender op hits a separate process over a
+ * socket. Everything else touches only the user's own workspace.
+ */
+export function annotate(id, billable) {
+    const readOnlyHint = startsWithAny(id, READ_ONLY_PREFIXES);
+    return {
+        readOnlyHint,
+        // A read is never destructive, whatever the id looks like.
+        destructiveHint: !readOnlyHint && DESTRUCTIVE_IDS.has(id),
+        idempotentHint: readOnlyHint || startsWithAny(id, IDEMPOTENT_PREFIXES),
+        openWorldHint: !!billable || id.startsWith('slates_blender_'),
+    };
+}
+// ── 2. Tiers ────────────────────────────────────────────────────────────────
+/**
+ * The deferred groups, by op id. Everything NOT listed here is `core`.
+ *
+ * The cut is "what a session needs to do the work" versus "what it needs once,
+ * when the user asks for that thing". Creating, generating, reviewing and
+ * shot-listing are core; tidying the library, cutting a timeline, renaming and
+ * deleting, and driving Blender are not — and each is a coherent thing a user
+ * asks for by name, which is what makes a group loadable in one call.
+ *
+ * 🚨 A GROUP IS A BUDGET, NOT A LAW. If `final_state` falls on timeline or
+ * library tasks after this shipped, move those ops back to core. The point is
+ * the per-turn byte count, and a deferral that costs a turn every time is not
+ * paying for itself.
+ */
+export const OPERATION_GROUPS = {
+    // Folders, styles, and moving assets around. Reached when the user says
+    // "tidy this up", never while making the thing.
+    library: [
+        'slates_list_folders',
+        'slates_create_folder',
+        'slates_rename_folder',
+        'slates_delete_folder',
+        'slates_set_folder_cover',
+        'slates_move_assets_to_folder',
+        'slates_move_assets_to_project',
+        'slates_copy_assets_to_project',
+        'slates_move_entity_to_project',
+        'slates_list_styles',
+        'slates_create_style',
+        'slates_update_style',
+        'slates_delete_style',
+        'slates_get_project_directory',
+        'slates_reveal_file',
+    ],
+    // The cut and the export. A generation session never touches these.
+    timeline: [
+        'slates_get_timeline',
+        'slates_add_clip_to_timeline',
+        'slates_reorder_clips',
+        'slates_remove_clip',
+        'slates_add_timeline_track',
+        'slates_update_timeline_track',
+        'slates_remove_timeline_track',
+        'slates_update_timeline_settings',
+        'slates_export_video',
+        'slates_export_timeline_xml',
+        'slates_trim_video',
+    ],
+    // Rename, delete, reorder. The 63-op CRUD tail the review measured at 39.5 KB.
+    admin: [
+        'slates_update_project',
+        'slates_delete_project',
+        'slates_delete_asset',
+        'slates_update_character',
+        'slates_delete_character',
+        'slates_update_environment',
+        'slates_delete_environment',
+        'slates_update_storyboard',
+        'slates_delete_storyboard',
+        'slates_update_scene',
+        'slates_delete_scene',
+        'slates_reorder_scenes',
+        'slates_delete_frame',
+        'slates_batch_update_frames',
+        'slates_duplicate_shot',
+        'slates_split_shot',
+        'slates_merge_shots',
+    ],
+    // A third transport nobody without Blender installed can reach.
+    blender: [
+        'slates_blender_status',
+        'slates_blender_execute',
+        'slates_blender_scene',
+        'slates_blender_docs',
+        'slates_blender_search_docs',
+        'slates_blender_render_blocking',
+    ],
+};
+const GROUP_BY_OP = new Map();
+for (const [group, ids] of Object.entries(OPERATION_GROUPS)) {
+    for (const id of ids)
+        GROUP_BY_OP.set(id, group);
+}
+export function groupFor(id) {
+    return GROUP_BY_OP.get(id);
+}
+/** `extended` iff the op names a group. Absent from every group ⇒ `core`, so a
+ *  new op is visible until someone deliberately defers it. */
+export function tierFor(id) {
+    return GROUP_BY_OP.has(id) ? 'extended' : 'core';
+}
+/** One-line summary of each group, for `slates_load_tools`' own description. */
+export const GROUP_SUMMARY = {
+    library: 'folders, styles, moving and copying assets between projects, revealing files on disk',
+    timeline: 'the timeline (tracks, clips, settings), video export and NLE XML export, clip trimming',
+    admin: 'rename / delete / reorder for projects, characters, environments, storyboards, scenes and frames; shot duplicate, split and merge',
+    blender: 'the Blender previs bridge — scene inspection, bpy execution, API docs, grey-box render',
+};
+/**
+ * Render one op's tool definition.
+ *
+ * `$refStrategy: 'none'` is the shape both surfaces now emit: inlined, so no
+ * client has to resolve a `$ref`, and byte-identical between them — which is
+ * what makes "the two surfaces expose the same tools" checkable rather than
+ * merely asserted about the id set.
+ */
+export function toolDefinition(op) {
+    const schema = zodToJsonSchema(op.input, { $refStrategy: 'none' });
+    delete schema.$schema;
+    return {
+        name: op.id,
+        description: op.description,
+        inputSchema: schema,
+        annotations: op.annotations ?? annotate(op.id, op.billable),
+    };
+}
+/**
+ * Render a tool surface.
+ *
+ * `desktop` sends `core` plus whatever groups have been loaded this run; `mcp`
+ * sends everything, because a stdio server has no run to append to.
+ */
+export function toolDefinitions(ops, opts) {
+    const loaded = new Set(opts.groups ?? []);
+    return ops
+        .filter((op) => {
+        if (opts.surface === 'mcp')
+            return true;
+        const group = groupFor(op.id);
+        return group === undefined || loaded.has(group);
+    })
+        .map(toolDefinition);
+}
+//# sourceMappingURL=surface.js.map

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,201 @@
+// ============================================================
+// 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(`- NAMES AND DESCRIPTIONS ARE THE USER'S UI, NOT YOUR NOTEPAD. A project, storyboard 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(`- 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.`),
+    // ONE LINE, NOT A SECTION. The counts themselves ride the op RESULT, where
+    // the agent is already reading — measured: a rule inlined into an op moved
+    // compliance 0/8 → 30/32, while the same guidance behind a guide fetch sat at
+    // 13% before and after. This sentence exists only to say the numbers are
+    // there and must be looked at; the craft is the skill.
+    both(`- READ THE VARIETY COUNTS BEFORE FIRING A SET: slates_list_shots and slates_get_storyboard_with_frames return the distribution (shot sizes, camera moves, runs of three or more) with the rows. If one bucket is the plurality, fix the board before you spend — slates-shot-variety is the craft.`),
+    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/asset-label.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A readable label for a generated asset, from its prompt.
+ *
+ * Strips a reference preamble, then takes the first CLAUSE rather than a fixed
+ * character slice — so the label ends on a word instead of mid-syllable.
+ * Returns null for a prompt with nothing usable in it; the caller decides what
+ * to show instead (a Shot name, "Untitled").
+ */
+export declare function labelFromPrompt(prompt: string | null | undefined): string | null;
+/**
+ * The caption for one asset row, in priority order: the label it was given, the
+ * Shot it came from, then the prompt reduced to a clause.
+ *
+ * The Shot name sits second because an author who named a Shot chose that word
+ * on purpose, and it is the word on the row in the storyboard — so the gallery
+ * and the document call the same thing the same thing.
+ */
+export declare function assetCaption(a: {
+    label?: string | null;
+    shotName?: string | null;
+    prompt?: string | null;
+}): string;
+//# sourceMappingURL=asset-label.d.ts.map

package/dist/prompts/asset-label.js

@@ -0,0 +1,70 @@
+// ============================================================
+// ASSET LABELS — what a generated thing is CALLED in a list.
+//
+// 🚨 THE FIRST 40 CHARACTERS OF A PROMPT IS NOT A LABEL, and on
+// reference-driven work it is actively misleading: every one of those prompts
+// opens with the same composed preamble, so a whole gallery reads
+// "Reference image 1 is a character ide" — the same string on every row, which
+// is worse than no label because it looks like information.
+//
+// One rule, two consumers: the op surface's `compactAsset` (what an agent reads
+// back from `slates_list_assets`) and the desktop gallery caption. A second
+// copy of this would drift the way every other hand-mirrored rule in this
+// workspace has.
+//
+// Dependency-free LEAF, same as `shot-grammar`: the desktop RENDERER imports it
+// directly, so it may never reach for `node:` anything.
+// ============================================================
+/**
+ * A composed prompt's reference preamble.
+ *
+ * The composer writes "Reference image 1 is a character identity sheet." — so
+ * the optional leading "Reference" has to be matched SEPARATELY from the noun,
+ * or the pattern only catches the bare "Image 1 is …" form and every real
+ * composed prompt walks straight past it. (It did, until the labels were
+ * exercised on actual prompts.)
+ */
+const REFERENCE_PREAMBLE_RE = /^\s*(?:reference\s*)?(?:image|video|audio|clip)?\s*\d*\s*is\b[^.;]*[.;]\s*/i;
+/** A sentence boundary always ends the label. */
+const SENTENCE_BOUNDARY_RE = /(?<=[.;:])\s/;
+/**
+ * An em-dash ends it too — but only once there is enough label to be worth
+ * keeping. Composed prompts join a subject to its treatment with one, and the
+ * subject alone is the label; a hand-written "wide shot — the barn at dawn"
+ * would otherwise be cut down to "wide shot", which names nothing.
+ */
+const DASH_BOUNDARY_RE = /\s—\s/;
+const MIN_BEFORE_DASH = 25;
+const MAX = 60;
+/**
+ * A readable label for a generated asset, from its prompt.
+ *
+ * Strips a reference preamble, then takes the first CLAUSE rather than a fixed
+ * character slice — so the label ends on a word instead of mid-syllable.
+ * Returns null for a prompt with nothing usable in it; the caller decides what
+ * to show instead (a Shot name, "Untitled").
+ */
+export function labelFromPrompt(prompt) {
+    if (!prompt)
+        return null;
+    const body = (prompt.replace(REFERENCE_PREAMBLE_RE, '').trim() || prompt).trim();
+    let clause = body.split(SENTENCE_BOUNDARY_RE)[0].trim();
+    const dash = clause.split(DASH_BOUNDARY_RE)[0].trim();
+    if (dash.length >= MIN_BEFORE_DASH)
+        clause = dash;
+    if (!clause)
+        return null;
+    return clause.length > MAX ? `${clause.slice(0, MAX - 1).trimEnd()}…` : clause;
+}
+/**
+ * The caption for one asset row, in priority order: the label it was given, the
+ * Shot it came from, then the prompt reduced to a clause.
+ *
+ * The Shot name sits second because an author who named a Shot chose that word
+ * on purpose, and it is the word on the row in the storyboard — so the gallery
+ * and the document call the same thing the same thing.
+ */
+export function assetCaption(a) {
+    return a.label?.trim() || a.shotName?.trim() || labelFromPrompt(a.prompt) || 'Untitled';
+}
+//# sourceMappingURL=asset-label.js.map