@cueframe/kernel 0.0.1

package/dist/_members/mcp/curation.js

@@ -0,0 +1,792 @@
+/**
+ * Curation SSOT — the hand-picked, agent-legible front-door over the generated
+ * operation manifest. This file owns WHICH operations are curated, their
+ * friendly names, agent guidance, success formatting, MCP annotations, and the
+ * per-resource CRUD coverage map. server.ts iterates CURATED_TOOLS; curation.test.ts
+ * gates it against the generated manifest. NO transport/server import lives here.
+ */
+import { fmtClock } from './format.js';
+import { CATALOG_PREVIEWS } from './generated/catalogPreviews.js';
+export function formatMediaList(json) {
+    const data = Array.isArray(json?.data) ? json.data : [];
+    if (data.length === 0)
+        return 'No media items found. Import a video first (import_media) or generate one (generate_media).';
+    const lines = data.map((m) => {
+        const dur = m?.duration != null ? ` (${fmtClock(m.duration)})` : '';
+        const phase = m?.processingStatus?.phase ?? m?.status ?? 'unknown';
+        return `- ${m.id}  ${m.name}${dur}  [${phase}]`;
+    });
+    return `${data.length} media item${data.length !== 1 ? 's' : ''}:\n\n${lines.join('\n')}`;
+}
+export function formatComponentList(json) {
+    const data = Array.isArray(json?.data) ? json.data : [];
+    if (data.length === 0) {
+        return 'No components match. Drop a filter, or browse unfiltered (list_catalog with no args returns the whole built-in catalog).';
+    }
+    const lines = data.map((e) => {
+        const facets = [e.category, e.kind, e.tier].filter(Boolean).join(' · ');
+        const uc = Array.isArray(e.useCase) && e.useCase.length ? ` useCase:${e.useCase.join('/')}` : '';
+        const place = e.placement ? `  → place as {kind:'${e.placement.clipSourceKind}', ${e.placement.refField}:'${e.id}'}` : '';
+        const baked = Array.isArray(e.fixedCopy) && e.fixedCopy.length ? `  [bakes fixed copy]` : '';
+        return `- ${e.id}  ${e.name} (${facets})${uc}${baked}${place}`;
+    });
+    const more = json?.pagination?.hasMore ? '\n\n(more — pass `after` to page)' : '';
+    return `${data.length} component${data.length !== 1 ? 's' : ''} (recommended-tier first when filtered):\n\n${lines.join('\n')}${more}`;
+}
+export function formatResourceCandidates(json) {
+    // BATCH shape: one section per query. Rendered here rather than as N tool
+    // results so the agent pays ONE round-trip's context for the whole set.
+    if (Array.isArray(json?.results)) {
+        const total = json.results.reduce((n, r) => n + (Array.isArray(r?.candidates) ? r.candidates.length : 0), 0);
+        const sections = json.results.map((r) => {
+            const head = `── "${r?.query}"`;
+            if (r?.error)
+                return `${head}\n  ✗ ${r.error}`;
+            return `${head}\n${formatResourceCandidates(r)}`;
+        });
+        return `${json.results.length} queries, ${total} candidate(s) total:\n\n${sections.join('\n\n')}`;
+    }
+    const items = Array.isArray(json?.candidates) ? json.candidates : [];
+    const provider = json?.provider ?? 'unknown';
+    const kind = json?.kind ?? '';
+    if (items.length === 0) {
+        return `No ${kind} stock results from ${provider}. Try a different query, kind, or provider.`;
+    }
+    const lines = items.map((cand) => {
+        const dims = cand.width && cand.height ? ` ${cand.width}×${cand.height}` : '';
+        const dur = cand.duration != null ? ` ${fmtClock(cand.duration)}` : '';
+        const lic = cand.license ? ` [${cand.license}]` : '';
+        const by = cand.author ? ` by ${cand.author}` : '';
+        return `- ${cand.candidateId}\n    ${cand.kind}${dims}${dur}${by}${lic}  preview: ${cand.previewUrl}`;
+    });
+    // One candidate = no choice, so no thumbnail was attached (see the `attach`
+    // gate). Say so, or the agent cannot tell "you may not look" from "nothing to
+    // look at" — and the whole point is that looking stays one arg away.
+    const seeMore = items.length === 1
+        ? '\n\n(no preview attached for a single result — re-run with limit ≥2 to SEE candidates side by side)'
+        : '';
+    return `${items.length} ${kind} candidate${items.length !== 1 ? 's' : ''} from ${provider} (import one with import_resource({ projectId, candidateId })):\n\n${lines.join('\n')}${seeMore}`;
+}
+/**
+ * Char budget for returning a composition VERBATIM. Past this, `formatComposition`
+ * degrades to a structural summary rather than emitting a body the MCP host will
+ * refuse outright: a 128-clip composition serialized to 69,788 chars and the host
+ * rejected the whole result ("exceeds maximum"), so the agent could not read back
+ * the composition it had just written and fell back to shelling out to python3 to
+ * read a file it had authored itself. Comfortably under the ~25k-token host cap
+ * while leaving normal compositions untouched.
+ */
+const COMPOSITION_VERBATIM_BUDGET = 24_000;
+/** One line per clip: what it is, when it is, and what it points at. */
+function describeClip(c) {
+    const id = c?.id ?? '?';
+    const start = typeof c?.startTime === 'number' ? c.startTime : 0;
+    const dur = typeof c?.duration === 'number' ? c.duration : 0;
+    const when = `${start.toFixed(2)}→${(start + dur).toFixed(2)}s`;
+    const s = c?.source;
+    if (!s)
+        return `- ${id}  [gap]      ${when}`;
+    const family = c?.kind ?? s.kind ?? '?';
+    const extra = [];
+    if (c.region)
+        extra.push('region');
+    if (c.fit)
+        extra.push(`fit:${c.fit}`);
+    if (c.transitionIn?.type)
+        extra.push(`in:${c.transitionIn.type}`);
+    let what = s.kind;
+    if (s.kind === 'media') {
+        what = `media ${s.mediaId}`;
+        const segs = s.reframe?.segments?.length;
+        if (segs)
+            extra.push(`reframe:${segs}seg`);
+        if (s.kenBurns)
+            extra.push('kenBurns');
+        if (s.audioRole)
+            extra.push(`role:${s.audioRole}`);
+        if (s.muted)
+            extra.push('muted');
+    }
+    else if (s.kind === 'card') {
+        // The html is the whole reason a composition blows the budget — elide the
+        // body, keep the facts an agent needs to decide whether to re-read it.
+        const tokens = Object.keys(s.tokens ?? {});
+        what = `card html:${(s.html?.length ?? 0)}ch${tokens.length ? ` tokens:{${tokens.join(',')}}` : ''}`;
+    }
+    else if (s.kind === 'component' || s.kind === 'alpha-layer') {
+        what = `${s.kind} ${s.componentId ?? '?'}`;
+    }
+    else if (s.kind === 'overlay') {
+        what = `overlay ${s.primitiveId ?? s.overlayId ?? '?'}`;
+    }
+    else if (s.kind === 'effect') {
+        what = `effect ${s.effectId ?? s.type ?? '?'}`;
+    }
+    return `- ${id}  [${family}]  ${when}  ${what}${extra.length ? `  (${extra.join(', ')})` : ''}`;
+}
+/**
+ * Render a composition for reading. Verbatim JSON while it fits — that is the
+ * documented contract (it is what you hand to validate_composition) — and a
+ * STRUCTURAL SUMMARY when the full body would exceed what the host will accept.
+ * Every clip is still listed; only the unbounded blobs (card html, caption
+ * words) are elided, and the header says so explicitly. Degrading loudly beats
+ * returning nothing, and beats a silent truncation that reads like the whole
+ * composition.
+ */
+export function formatComposition(json) {
+    const full = JSON.stringify(json, null, 2);
+    if (full.length <= COMPOSITION_VERBATIM_BUDGET)
+        return full;
+    const tracks = Array.isArray(json?.tracks) ? json.tracks : [];
+    const clips = tracks.flatMap((t) => (Array.isArray(t?.contents) ? t.contents : []));
+    const f = json?.format ?? {};
+    const lines = [
+        `Composition SUMMARIZED — the full JSON is ${full.length.toLocaleString()} chars, past what ` +
+            `an MCP result can carry. Structure below is complete (every track and clip is listed); ` +
+            `card html bodies and caption words are elided as lengths/counts. For a verbatim copy, ` +
+            `GET /v1/projects/{id}/composition over REST.`,
+        '',
+        `format: ${f.aspectRatio ?? '?'} ${f.fps ?? '?'}fps ${f.resolution ?? ''}`.trim(),
+        `tracks: ${tracks.length}   clips: ${clips.length}`,
+    ];
+    if (json?.captions) {
+        const segs = json.captions.segments?.length ?? 0;
+        const words = json.captions.words?.length ?? 0;
+        lines.push(`captions: ${segs} segment(s), ${words} word(s) [text elided]`);
+    }
+    if (Array.isArray(json?.markers) && json.markers.length) {
+        lines.push(`markers: ${json.markers.map((m) => m?.kind ?? '?').join(', ')}`);
+    }
+    for (const t of tracks) {
+        const contents = Array.isArray(t?.contents) ? t.contents : [];
+        lines.push('', `${t?.kind ?? '?'} track ${t?.id ?? '?'} — ${contents.length} clip(s):`);
+        for (const c of contents)
+            lines.push(describeClip(c));
+    }
+    return lines.join('\n');
+}
+/**
+ * The `warnings[]` advisory channel, rendered for the reader. One idiom across
+ * every verb that carries it (create_render, apply_composition) so an agent
+ * learns to look for `⚠` exactly once.
+ */
+export function formatWarnings(json) {
+    const warns = Array.isArray(json?.warnings) ? json.warnings : [];
+    return warns.length > 0 ? `\n\n⚠ ${warns.join('\n⚠ ')}` : '';
+}
+export const CURATED_TOOLS = [
+    {
+        name: 'compose',
+        operationId: 'compose',
+        pathArgs: { projectId: 'id' },
+        description: 'Start the async Director compose workflow: it authors an ensemble of full composition candidates, verifies each, and saves the winner to the project. Body must set EXACTLY ONE source (mutually exclusive): `briefId` — author FROM a persisted Brief (the PLANNED path: create_brief first; every Brief field is honored or the compose is refused loudly naming the field); `fromComposition: true` — author from the project\'s CURRENT composition (the GENERAL path: seed it with apply_composition first — your media clips are the intent, and any graphics you authored are CARRIED VERBATIM as locked clips the Director authors around, never re-authors or drops); or `suggestionId` — author from an AI clip suggestion (the CLIPPING path, paired with suggest_briefs). Returns { composeJobId, workflowId, status, streamUrl }. Then call wait_job(kind="compose", id=composeJobId, projectId=...) to block until the winner is selected.',
+        okFormat: (j, a) => `Compose workflow started.\n\ncomposeJobId: ${j.composeJobId}\nworkflowId: ${j.workflowId}\nstatus: ${j.status}${j.streamUrl ? `\nstreamUrl: ${j.streamUrl}` : ''}\n\nCall wait_job(kind="compose", id="${j.composeJobId}", projectId="${a.projectId}") to block until the Director picks a winner.`,
+    },
+    {
+        name: 'apply_composition',
+        operationId: 'applyComposition',
+        pathArgs: { projectId: 'id' },
+        description: 'Atomically apply an array of CompositionOps to a project composition. All ops succeed or none do (transactional). Pass `if_match` for optimistic-concurrency control (409 stale_etag on mismatch) and `dry_run: true` to validate the batch without persisting. Use this to seed a composition (add media clips) or make targeted edits (set a crop intent, reorder clips, set the format). CAPTIONS: attach content with {type:"captions.fromTranscript", mediaId, window?} — the server slices the cached word-timed transcript, rebases times, and sentence-splits into segments (no pasting words; 422 media_no_transcript if the media has no speech); style it with {type:"setCaptionStyle", style}; or set explicit words with {type:"setCaptions", segments, style?} (e.g. translations or your own VO timings). Brand is NOT set here — it lives on the project (create_project / PATCH /projects/:id with brandKitId). CARDS: a {kind:"card", html, tokens} clip projects each `tokens` KEY `x` to the CSS custom property `--cf-x`, so the html must read it as `var(--cf-x)` — write `tokens:{"plate":"#0af"}` + `background:var(--cf-plate)`. Do NOT put dashes in the key: `"--plate"` becomes `--cf---plate` and your `var(--plate)` then resolves to NOTHING, which CSS silently degrades to a transparent background and black text. Responses carry `warnings[]` when a card reads a var nothing defines.',
+        // A dry_run returns HTTP 200 { valid, errors } — branch on it so a FAILED
+        // validation is never reported as "applied" (the route returns 200 either way).
+        okFormat: (j, a) => {
+            // `warnings[]` rides BOTH shapes — a dry-run that validates clean can
+            // still be about to render a broken card, and that is the cheapest
+            // possible moment to say so.
+            const warns = formatWarnings(j);
+            if (j && typeof j.valid === 'boolean') {
+                const r = j;
+                return r.valid
+                    ? `Dry-run OK — composition is valid (nothing persisted).${warns}`
+                    : `Dry-run FAILED — ${(r.errors ?? []).length} error(s), nothing persisted:\n${JSON.stringify(r.errors ?? [], null, 2)}${warns}`;
+            }
+            // The project clause is CONDITIONAL because `buildCuratedToolSet(ex,
+            // {session})` strips `projectId` from the schema and injects it into the
+            // path — so on every session-built lane (the Director's author + graphics
+            // designer, and the local bench) `a.projectId` is undefined and this line
+            // told the agent it had just edited "project undefined". Naming a project
+            // the model never supplied is the only thing this clause can get wrong;
+            // omitting it costs nothing, because on that lane there is exactly one
+            // composition being edited. The sessionless surfaces (raw MCP server,
+            // expert layer) are byte-identical.
+            return `Ops applied${a.projectId ? ` to project ${a.projectId}` : ''}.${warns}`;
+        },
+        // Teach the TARGETED patch: one clip, only the fields that change. The
+        // measured anti-pattern is re-emitting a whole card source per tweak
+        // (44-92s turns); a patch of position/opacity/params is seconds.
+        inputExamples: [
+            {
+                input: {
+                    body: {
+                        ops: [
+                            {
+                                type: 'clip.update',
+                                clipId: 'g1',
+                                patch: { position: { x: 0.5, y: 0.82 }, opacity: 0.95 },
+                            },
+                        ],
+                    },
+                },
+            },
+        ],
+    },
+    {
+        name: 'validate_composition',
+        operationId: 'validateComposition',
+        description: 'Dry-run a full Composition object against the SAME pure, DB-free authoring guards saveComposition enforces, WITHOUT persisting it (no project needed). Checks: wire shape (Zod), primitive membership (unknown_primitive / custom_missing_sourcecode), required-param shape (invalid_primitive_params), clip↔track family (clip_source_track_mismatch), and reframe coverage (reframe_coverage_gap). Always returns ONE shape — 200 { valid, errors, quote } — for BOTH malformed wire shapes and deep-invariant failures (so branch on `valid`, not on HTTP status); errors[] lists every problem at once as a sanitized envelope { code, stage, category, retryable, message, fix } you can fix before composing/rendering. The `quote` triple states the render price to finish from a valid composition — relay it to your human BEFORE create_render. `valid:true` means save-safe EXCEPT for the two genuinely DB-bound checks that can only run at save/render: trim-bounds (needs the media duration) and image/asset-on-a-video-track (needs the media kind). Pass the Composition as `body`.',
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'create_render',
+        operationId: 'createRender',
+        pathArgs: { projectId: 'id' },
+        description: "Queue an MP4 render of a project's composition. Returns { id (renderId), status, warnings? } — `warnings[]` carries non-fatal advisories (omitted when none). The render themes from the project's brand kit (bind one via create_project / PATCH /projects/:id with brandKitId; without one the output is unbranded). Then call wait_job(kind=\"render\", id=renderId, projectId=...) to block until the file is ready and get the download URL, or register a webhook (create_webhook on render.completed — status rides the payload).",
+        okFormat: (j, a) => `Render queued.\n\nrenderId: ${j.id}\nprojectId: ${a.projectId}\nstatus: ${j.status}${formatWarnings(j)}\n\nCall wait_job(kind="render", id="${j.id}", projectId="${a.projectId}") to block until it completes and get the download URL.`,
+    },
+    {
+        name: 'preview_frame',
+        operationId: 'previewFrame',
+        pathArgs: { projectId: 'id' },
+        description: "Render presigned PNG still(s) of the composition at the given timestamps — the live preview for layout/copy judgment. STATELESS: nothing to open, warm, or close; concurrent previews don't contend. Defaults to the PERSISTED state: absent `body.composition` ⇒ the project's ACTIVE composition — exactly what create_render will encode; pass `body.compositionId` to target a specific persisted composition (stale/foreign id ⇒ 404, never a silent fallback). The response's `previewed` field names what was rendered ({source: 'persisted'|'inline'|'scratch', compositionId?, etag?}) — trust a preview as render-truth ONLY when source is 'persisted'. `body.timestamps` = seconds to sample. A still cannot show motion — judge motion with preview_clip (a window of the composition) or preview_component (one graphic).",
+        // The most-called visual tool, and it returned a JSON blob of presigned
+        // links: the agent was told to judge layout and copy it could not see.
+        preview: {
+            urls: (j) => (Array.isArray(j?.stills) ? j.stills : []).map((st) => st?.url),
+            kind: 'image',
+            cap: 12,
+        },
+        // WITHOUT THIS, THE PIXELS SHIP TWICE — ONCE AS TEXT.
+        //
+        // The generic path falls back to `res.text` when a spec has no okFormat, so
+        // the model saw the WHOLE response JSON, `stills[].url` included, ALONGSIDE
+        // the image blocks. On the cloud lane that is a presigned link per still —
+        // wasteful. On the desktop lane (LocalExecutor serves this route out of the
+        // webview and has no R2, so it answers with `data:` URLs carrying the bytes
+        // inline) it is the ENTIRE IMAGE duplicated as base64 TEXT: 12 stills ≈
+        // hundreds of thousands of junk tokens, and the text copy is the one the
+        // model cannot see.
+        //
+        // So: a `data:` url is DROPPED (the bytes are already arriving as a media
+        // block — the text copy is pure waste). A real http(s) url is KEPT, because
+        // there it is 200 characters and an MCP host can open it.
+        okFormat: (j, a) => {
+            const stills = Array.isArray(j?.stills) ? j.stills : [];
+            const p = j?.previewed ?? {};
+            const head = `Previewed ${stills.length} still(s) of project ${a.projectId}.\n` +
+                `source: ${p.source ?? 'unknown'}` +
+                `${p.compositionId ? ` · compositionId: ${p.compositionId}` : ''}` +
+                `${p.etag ? ` · etag: ${p.etag}` : ''}` +
+                `${p.source !== 'persisted' ? ' — NOT render-truth (only source "persisted" is what create_render will encode)' : ''}`;
+            const lines = stills.map((st, i) => {
+                // `beatSec` is what the route ACTUALLY emits — it returns
+                // sightedAction.seeComposition's `SightedEvidence[]`
+                // ({beatSec, r2Key, url, bytesOut}) verbatim. `t`/`timestamp` are
+                // accepted too (an older hand-written fixture used `t`), so a rename on
+                // either lane degrades to a positional label rather than a lie.
+                const secs = typeof st?.beatSec === 'number'
+                    ? st.beatSec
+                    : typeof st?.t === 'number'
+                        ? st.t
+                        : typeof st?.timestamp === 'number'
+                            ? st.timestamp
+                            : null;
+                const t = secs === null ? `#${i}` : `${secs.toFixed(2)}s`;
+                const url = typeof st?.url === 'string' && !st.url.startsWith('data:') ? ` ${st.url}` : '';
+                return `  ${t}${url}`;
+            });
+            return `${head}\n${lines.join('\n')}\n\nThe frames ride with this result as images — judge the layout from the pixels, not from this text.`;
+        },
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'preview_component',
+        operationId: 'previewComponent',
+        pathArgs: { projectId: 'id' },
+        description: 'Queue a MOTION-clip render of ONE org-installed component — ASYNC: returns a jobId immediately; then wait_job(kind="preview", id=jobId) for a presigned short clip (VP9-alpha webm, ~3s — the SAME alpha bake the production render composites, so what you preview is what ships). Motion is the point of components; a still is one frame and lies about animation (A8). The author→preview→fix loop for a graphic. SESSIONLESS: the warm box is a server detail (a cold first call returns 409 box_warming — retry in a few seconds). `body.componentId` selects the component; pass `body.params` to render it with props. Failures land on the job terminal with typed codes: component_does_not_compile / component_runtime_error carry the sanitized author-fixable message — read it, fix the tsxSource via create_component, and re-preview. Idempotent per (componentId, params, dims).',
+        okFormat: (j) => `Preview job queued.\n\njobId: ${j.jobId}\nstatus: ${j.status}\n\nCall wait_job(kind="preview", id="${j.jobId}") for the presigned motion clip (re-call it if it returns still-running).`,
+        annotations: { idempotentHint: true },
+    },
+    {
+        name: 'preview_clip',
+        operationId: 'previewClip',
+        pathArgs: { projectId: 'id' },
+        description: "Render a scoped, cheap MOTION preview — ONLY body.fromSec→body.toSec of the composition (max 60s) at preview quality (capped resolution, lighter encode) through the real render pipeline. THE way to judge motion — a cut, a transition, a component's animation — at full fidelity BEFORE paying for a full render (a still cannot show motion; a full render costs the export). ASYNC: returns a render job; wait_job(kind=\"render\", id=renderId) or a render.completed webhook for the URL. Meters the capture feature, never an exports credit.",
+        okFormat: (j) => `Preview render queued.\n\nrenderId: ${j.renderId ?? j.id}\nstatus: ${j.status}\n\nwait_job(kind="render", id="${j.renderId ?? j.id}", projectId=...) for the watchable preview URL.`,
+    },
+    {
+        name: 'score_composition',
+        operationId: 'scoreComposition',
+        pathArgs: { projectId: 'id' },
+        description: 'Queue the server-side judge — the standalone sighted check. ASYNC: returns a jobId (the judge takes minutes: it samples eval beats, renders them in a server-managed warm box, and grades editorial/spatial/brand/caption). Then wait_job(kind="verify", id=jobId) for per-criterion scores 0–10, a weighted composite, a worst-first critique, AND a checkpointId — the verdicts mint a durable kind:\'score\' Checkpoint, the same evidence noun the Director\'s gates produce (get_checkpoint re-reads it later). SESSIONLESS: a cold first call returns 409 box_warming — retry in a few seconds. `body.composition` optional (absent ⇒ the ACTIVE composition). Fix the lowest criterion via apply_composition and re-score. Score answers "how good IS this" (grounded numbers); consult answers "what SHOULD I change" (advice + a fix candidate). Idempotent per composition state; the compose_verify meter fires on the job\'s success terminal.',
+        okFormat: (j) => `Score job queued.\n\njobId: ${j.jobId}\nstatus: ${j.status}\n\nCall wait_job(kind="verify", id="${j.jobId}") to block until the scores + checkpointId are ready (re-call it if it returns still-running).`,
+        annotations: { idempotentHint: true },
+    },
+    {
+        name: 'consult',
+        operationId: 'consult',
+        pathArgs: { projectId: 'id' },
+        description: "Ask the Director for editing advice on the project's CURRENT composition — it NEVER writes your composition (you stay the decider). Async: returns a consultJobId; then wait_job(kind=\"consult\", id=consultJobId, projectId=...) surfaces the advisory envelope (assessment / proposals / principles / plan). `body.mode`: 'advise' = the planner agent (fast, ~30s-2min) returns a `plan` (framing/cuts/captions/graphics intents) as GUIDANCE you re-author from — no grounded scores, nothing to adopt; 'amend' (default) = the full author→judge→refine loop (minutes) returns a graded `assessment` + a fix candidate you ADOPT via select_candidate with its candidateIndex. ('explore' is coming soon → use amend.) `body.intent` = your goal in plain English; optional `body.focus` (editorial|spatial|brand|caption); `body.ifMatch` binds to your current etag. Use advise for a fast directional nudge, amend for a grounded, adoptable fix.",
+        okFormat: (j) => `Consult job ${j.consultJobId} queued (${j.status}). wait_job(kind="consult", id="${j.consultJobId}", projectId=...) for the advisory envelope (advise → a plan to re-author from; amend → a graded fix to adopt via select_candidate).`,
+    },
+    {
+        name: 'resume',
+        operationId: 'resumeCheckpoint',
+        pathArgs: { checkpointId: 'id' },
+        description: "Answer the checkpoint packet wait_job reported as awaiting_input (its {checkpointId} — read the packet FIRST with get_checkpoint and relay the stills + money triple to your human). ONE `body.decision` per gate: 'approve' (proceed; comments allowed — they record as taste without gating), 'revise' (the director revises per your `body.comments` [{anchor: {beatId}|{timecodeMs}, verdict: 'approve'|'revise'|'lock', note}] and/or `body.edits`, then RE-PRESENTS this same gate as a new packet — in-job, no new charge; the brief quote states the included revision cycles, beyond them revise is refused 402), or 'abandon' (end the run — the only terminal refusal). 'lock' freezes an element contractually: the director touching it surfaces as a lock_violation verdict on the next packet. On approve/revise the Director rehydrates its warm box and continues; then wait_job again.",
+        okFormat: () => `Decision recorded. wait_job(kind="compose", …) to continue — a revise re-presents this gate as a NEW packet (version+1); an approve proceeds to the next gate or the winner.`,
+    },
+    {
+        name: 'create_brief',
+        operationId: 'createBrief',
+        description: "Persist the video's INTENT as a Brief — the Director's rich input contract (spec: the storyboard skill's output lands here). Fields: goal (required), audience, platform, format, durationSec, tone, cta, locale (output language — all on-screen copy + captions), hook, caption, beats[] (each with an editorial intent and optional MOMENT PINNING {mediaId, startSec, endSec} — honored to-the-frame or refused), mustIncludes, captions {styleId, emphasisPhrases} (the big-serif emphasis treatment), motionStyle, seededGraphics (your authored overlay/component/card clips, carried VERBATIM as locked clips — never re-authored), exclusions (hard negatives: graphic kinds the Director must NEVER author + 'no-transitions'), gates {holdAt, autoApprove}. Then compose it: compose with {briefId}. The response carries the QUOTE (compose + estimated render) — relay it to your human BEFORE composing.",
+        okFormat: (j) => `Brief ${j.id} created. Quote: compose $${j.quote?.composeUsd} + ~$${j.quote?.renderUsdPerExport}/render (est. journey $${j.quote?.estimatedJourneyUsd}) — relay before composing. Compose it: compose(projectId, body: { briefId: "${j.id}" }).`,
+    },
+    {
+        name: 'get_brief',
+        operationId: 'getBrief',
+        pathArgs: { briefId: 'id' },
+        description: 'Read a brief by id — the persisted intent plus its current quote (compose + estimated render).',
+    },
+    {
+        name: 'list_briefs',
+        operationId: 'listBriefs',
+        description: 'List briefs. DEFAULT shows human-authored briefs only; kind:"clip" shows the machine-minted clip briefs (suggest_briefs output), kind:"all" shows everything. Each carries its quote.',
+        queryArgs: {
+            projectId: 'Scope to one project.',
+            kind: "'authored' (default) | 'clip' | 'all'.",
+        },
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'get_checkpoint',
+        operationId: 'getCheckpoint',
+        pathArgs: { checkpointId: 'id' },
+        description: "Read a checkpoint packet — the durable approval unit a held compose pauses at (wait_job reports awaiting_input with {checkpointId, stage, version}). Carries the stage artifact, presigned storyboard stills (REVIEW THE EVIDENCE, not raw JSON), critic verdicts, the money triple {thisStepUsd, jobSpendSoFarUsd, estimatedJourneyTotalUsd} to relay to your human, and the recorded decision once resolved. When the Brief's gates set reviewMode:'hosted' the packet also carries reviewUrl — a browser review page where your human decides directly (relay THAT link instead of raw stills; you learn the decision via checkpoint webhooks / wait_job). Answer an awaiting packet with resume(checkpointId, ...).",
+        // The packet grades stills the agent was never shown: it got a score and a
+        // text critique and was told to 'fix the lowest criterion' sight-unseen.
+        preview: {
+            urls: (j) => (Array.isArray(j?.stillUrls) ? j.stillUrls : []),
+            kind: 'image',
+            cap: 12,
+        },
+    },
+    {
+        name: 'list_checkpoints',
+        operationId: 'listCheckpoints',
+        description: "List checkpoint packets newest-first (filter with composeJobId for one run's v1→vN gate history, or projectId). The version stack with per-version status + decisions IS the review history — nothing is deleted.",
+        queryArgs: {
+            composeJobId: "One compose run's gate history (v1→vN).",
+            projectId: 'Scope to one project.',
+        },
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'update_brief',
+        operationId: 'updateBrief',
+        pathArgs: { briefId: 'id' },
+        description: "Edit a brief (partial). REFUSED with 409 while an ACTIVE compose job references it — finish, resume, or abandon the job first (the Director never has its input edited mid-run). Edits apply to the NEXT compose.",
+    },
+    {
+        name: 'delete_brief',
+        operationId: 'deleteBrief',
+        pathArgs: { briefId: 'id' },
+        description: 'Delete a brief. Compose jobs already run from it are unaffected (they snapshot).',
+    },
+    {
+        // A12 cutover note: 'adopt_candidate' is BURNED (tombstoned); the
+        // capability survives as select_candidate because consult(amend) proposals
+        // carry only a candidateIndex — without a curated select the amend mode is
+        // a dead-end (the exact defect plan-1 fixed). The full fold into the
+        // checkpoint review model (consult minting a score packet you resume) is
+        // plan-5 scope.
+        name: 'select_candidate',
+        operationId: 'selectComposeCandidate',
+        pathArgs: { projectId: 'id', composeJobId: 'composeJobId' },
+        description: "Select one candidate from a finished compose/consult ensemble as the project's saved composition (whole-candidate replace). Body REQUIRES both fields: { candidateIndex, selectStrategy: \"agent-authoritative\" } — candidateIndex from wait_job(kind=\"consult\") proposals (mode=amend) or the compose winner report; selectStrategy is required and API keys must use 'agent-authoritative' (editor-merge/editor-replace need an editor-session token and 403 on an API key). After selecting, render with create_render.",
+        okFormat: () => 'Candidate selected — it is now the saved composition. Render it with create_render.',
+    },
+    {
+        name: 'create_component',
+        operationId: 'createComponent',
+        description: 'Create and store a custom graphic component (a reusable overlay/title/lower-third etc.) for the tenant. Returns the ComponentResponse (id + metadata) you can then reference from a composition. No project arg — components are tenant-scoped.',
+    },
+    {
+        name: 'list_catalog',
+        operationId: 'listCatalog',
+        description: "DISCOVER WHAT TO BUILD WITH — list the component catalog: the FULL built-in primitive catalog (text, effects, transitions, layouts, backgrounds, and scenes: lower-third, cinematic-title, color-grade, product-launch-trailer, …) PLUS your org-installed components. Use it for UTILITY furniture (captions, grades, transitions, backgrounds, scenes) and as REFERENCE CODE (get_component_source) — for BRAND or text graphics, default to authoring your OWN `kind:'card'` clip (your HTML + tokens, poster-grade typography) shelled with `applyMotionPreset`; a catalog text primitive is the quick generic fallback, not the identity path. Narrow with filters: `category` (text|effects|transitions|layouts|backgrounds|ui-blocks|scenes), `kind` (component|transition|scene), `tier` (recommended|standard|niche), `useCase` (intro|outro|full-scene|title-over-footage|transition|background|grade|emphasis|explainer|social-cut), `mood`, or free-text `q`/`intent` (e.g. intent='intro'). When any filter is set, results are recommended-tier-first. With NO `limit` the whole filtered catalog returns in one page. Each entry carries a `placement` hint = exactly how to author it via apply_composition ({kind:'overlay'|'effect', primitiveId} for built-ins; {kind:'component', componentId} for installed), `tier`/`useCase` to pick by, and `fixedCopy` (on-screen strings it BAKES that no param changes — fork via get_component_source to edit). Read cueframe://component/{id} for the full prop schema.",
+        okFormat: (j) => formatComponentList(j),
+        annotations: { readOnlyHint: true },
+        // 103 visual primitives described in PROSE — an agent picked silk-flow-bg
+        // over vector-field from a sentence. The renders and the CDN have existed
+        // for a while; this is the join. Best-effort by design: org-installed
+        // components have no published preview, and a miss yields no thumbnail.
+        preview: {
+            urls: (j) => (Array.isArray(j?.data) ? j.data : []).map((e) => CATALOG_PREVIEWS[e?.id]),
+            kind: 'image',
+            cap: 12,
+        },
+    },
+    {
+        name: 'get_component_source',
+        operationId: 'getComponentSource',
+        pathArgs: { componentId: 'id' },
+        description: 'Read a component\'s editable TSX source. Pass a BUILT-IN primitive id (e.g. "cinematic-title", "lower-third", "kinetic-type") to get it as a SINGLE self-contained module — the server-native FORK path: edit the returned tsxSource, then create_component it back to own a customized copy. Also returns an org-installed component\'s own authored source. Returns { id, name, tsxSource, origin, ejectedFrom, propSchema, … }; 404 if the id is neither a known primitive nor an installed component carrying source.',
+        okFormat: (j) => `Component source for ${j.id} (${j.name})${j.origin ? ` — origin: ${j.origin}` : ''}${j.ejectedFrom ? `, ejectedFrom: ${j.ejectedFrom}` : ''}.\nEdit this tsxSource and create_component it back to own a fork.\n\n${j.tsxSource}`,
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'get_media_context',
+        operationId: 'getMediaContext',
+        pathArgs: { mediaItemId: 'id' },
+        description: 'Fetch the authoring context for a media item: detected faces (subject boxes per frame) and the transcript. Use this before composing/applying so your crop intents, captions, and timing line up with what is actually in the footage.',
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'list_media',
+        operationId: 'listMedia',
+        description: 'List the media in your CueFrame library. Filter a real library with kind (video|audio|image|gif|asset|source|stock), source (upload|generated|import-url|stock), or tag — so you find YOUR footage, not e2e debris. Returns media item IDs and metadata; use an ID with get_media_context, suggest_briefs, or as a composition source.',
+        queryArgs: {
+            kind: 'video | audio | image | gif | asset | source | stock.',
+            source: 'upload | generated | import-url | stock.',
+            tag: 'Exact tag match.',
+        },
+        okFormat: (j) => formatMediaList(j),
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'create_project',
+        operationId: 'createProject',
+        description: 'Create a new project — the unit you compose and render into. compose / apply_composition / create_render / the preview family all require a projectId; this mints one. Pass name (required) plus optionally a format (aspectRatio/fps/resolution) and brandKitId. brandKitId binds a brand kit to the PROJECT (pass the kitId from create_brand_kit): colors/fonts/motion theme every render of this project automatically (omit it and the output is unbranded). Bind or change it later via PATCH /projects/:id. Returns the ProjectResponse (id + metadata).',
+    },
+    {
+        name: 'new_composition',
+        operationId: 'newComposition',
+        pathArgs: { projectId: 'id' },
+        description: 'Create a NEW composition (a new video) inside a project — a project is a workspace that holds many videos. Returns { compositionId, format, etag }. Pass an optional name and format (aspectRatio/fps/resolution); format defaults to the project\'s compositionFormat. The first composition becomes the project\'s active default. To author it, seed with apply_composition then compose({ fromComposition: true }) — your authored graphics ride as locked clips, carried verbatim; to render a specific one, pass its compositionId to create_render. (For a reframed sibling in another aspect, use derive_composition.)',
+        okFormat: (j, a) => `New video created in project ${a.projectId}.\n\ncompositionId: ${j.compositionId}\nformat: ${JSON.stringify(j.format)}\netag: ${j.etag}`,
+    },
+    {
+        name: 'get_composition',
+        operationId: 'getComposition',
+        pathArgs: { projectId: 'id' },
+        description: "READ BACK the project's active composition as JSON — the edit itself: tracks, clips, " +
+            'card HTML, reframe segments, captions, markers, format. This is what create_render ' +
+            'encodes, so it is also what you hand to validate_composition (which needs a full inline ' +
+            'composition body), what you diff after an edit, and what you archive/share so someone ' +
+            'else can re-render the SAME video. Read-only and free. Authoring stays op-based ' +
+            '(apply_composition) — do not round-trip this object back as a write. A composition too ' +
+            'large to fit one MCP result degrades to a STRUCTURAL SUMMARY (every track and clip still ' +
+            'listed; card html and caption words elided as lengths) with a header saying so — read it ' +
+            'over REST if you need the verbatim body.',
+        okFormat: (j) => formatComposition(j),
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'list_compositions',
+        operationId: 'listCompositions',
+        pathArgs: { projectId: 'id' },
+        description: 'List every composition (video) in a project, with its format and which one is active. Use a returned compositionId with create_render(compositionId=...) to render a specific video, or apply_composition to edit it.',
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'delete_composition',
+        operationId: 'deleteComposition',
+        pathArgs: { projectId: 'id', compositionId: 'compositionId' },
+        description: "Delete a composition (and its version history) from a project. REFUSES the ACTIVE composition (409) — make another one active first, or delete the project. Use list_compositions to see which is active.",
+        annotations: { destructiveHint: true },
+    },
+    {
+        name: 'list_projects',
+        operationId: 'listProjects',
+        description: 'List your projects — re-orient in an existing workspace instead of minting duplicates (steady-state entry, A9). Each row carries the id every other tool needs.',
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'derive_composition',
+        operationId: 'deriveComposition',
+        pathArgs: { projectId: 'id' },
+        description: 'Derive a reframed SIBLING composition for a different aspect ratio (the agent-native Auto-Reframe / Magic-Resize). Pass projectId + body { fromCompositionId, targetFormat: { aspectRatio, fps?, resolution? } }. CueFrame copies the source composition\'s authored intent and content-aware-reframes every clip for the new aspect (point/face/active-speaker focus), then saves a new independent composition in the same project. Returns { compositionId } — render it with create_render, or refine it with apply_composition. Use this to make 9:16 + 1:1 + 4:5 cuts from one 16:9 edit. (To only change resolution within the SAME aspect, pass create_render.format instead — that is a scale-only export override, not a new composition.)',
+        okFormat: (j, a) => `Derived a reframed sibling composition.\n\ncompositionId: ${j.compositionId}\nprojectId: ${a.projectId}\n\nRender it with create_render(projectId="${a.projectId}", body={ compositionId: "${j.compositionId}" }) or refine it with apply_composition.`,
+    },
+    {
+        name: 'import_media',
+        operationId: 'importMedia',
+        description: 'Import a media item into your library from a public URL — the agent-friendly ingest path (single call, no upload protocol). Pass url (https) + filename (+ optional contentType). Returns { id, status:"importing" }. Processing is async: poll list_media for processingStatus, or register a webhook (create_webhook on media.completed — status: complete|failed rides the payload). Use the returned id with get_media_context, suggest_briefs, or as a composition source.',
+    },
+    {
+        name: 'generate_media',
+        operationId: 'generateMedia',
+        description: 'Generate a media item from a prompt (generator: text-to-video | text-to-image | image-to-video | auto). Returns { id, status:"generating", estimateUsd? }; returns 402 if the estimate exceeds the per-call ceiling. Async — poll list_media or use a webhook (media.completed — status rides the payload). Use the returned id like any other media item.',
+    },
+    {
+        name: 'create_upload',
+        operationId: 'createMediaUpload',
+        description: 'Ingest a LOCAL file — bytes you hold, when there is no public URL to hand import_media (prefer import_media whenever the bytes already sit at an https URL). TWO steps: (1) this tool reserves a media row and returns { id, uploadUrl, expiresAt } — a short-lived presigned PUT URL. PUT the raw file bytes straight to uploadUrl over HTTPS with your declared Content-Type (the bytes go direct to R2, never through MCP; ≤ ~5 GB per PUT). (2) call finalize_upload({ mediaItemId: id }) to start processing. Body: filename, contentType (allowed enum), size (bytes). Thereafter it is async exactly like import_media: poll list_media for processingStatus, or register a webhook (create_webhook on media.completed). Use the returned id with get_media_context, suggest_briefs, or as a composition source.',
+    },
+    {
+        name: 'finalize_upload',
+        operationId: 'finalizeMedia',
+        pathArgs: { mediaItemId: 'id' },
+        description: 'Finalize a direct upload once you have PUT the bytes to the uploadUrl from create_upload. Confirms the bytes landed and starts ingest: image/asset become ready immediately (status "complete"); audio/video enter processing (status "processing"). Returns { id, status, processingPhase }. 400 if no bytes were uploaded (PUT first) or the item is not awaiting finalize; 404 if the id is not yours. Then poll list_media / get_media_context, or use a media.completed webhook.',
+    },
+    {
+        name: 'search_resources',
+        operationId: 'searchResources',
+        description: 'Search licensed STOCK media to compose with — video/photo (Pexels + Pixabay fallback), sfx (Freesound, CC0-only), gif (Klipy). Pass query for ONE search, or queries[] (≤10) to run them all in a SINGLE call — strongly prefer the batch when you know several things you need (a 64-search session spent 5m10s on serial round-trips). A batch returns results[], one per query in order, each with its own candidates; a query that fails carries an error and never discards the others. Optional kind [default video], provider pin, limit ≤50 apply to every query in the batch. Returns ranked candidates, each with an opaque candidateId + attribution (author, assetUrl) + license, and a preview URL in the text. FREE + rate-limited + 7-day cached — reach for this before generate_media when real footage beats synthesis. TO SEE the candidates rather than read about them, pass limit ≥2: thumbnails/audio are attached only when you asked for options to compare, because a preview of a single forced choice is pure cost. Import a chosen candidate into a project with import_resource. Candidates expire after 7 days (re-search to refresh a candidateId).',
+        okFormat: (j) => formatResourceCandidates(j),
+        // Stock was picked from resolution, duration and author name — eight
+        // near-identical clips in one session. Thumbnails end that. But ONLY when
+        // there is something to pick BETWEEN: see `attach` on CuratedTool.preview.
+        preview: {
+            urls: (j) => (Array.isArray(j?.results)
+                ? j.results.flatMap((r) => (Array.isArray(r?.candidates) ? r.candidates : []))
+                : Array.isArray(j?.candidates)
+                    ? j.candidates
+                    : []).map((c) => c?.previewUrl),
+            kind: (j) => ((j?.kind ?? j?.results?.[0]?.kind) === 'sfx' ? 'audio' : 'image'),
+            cap: 12,
+            // A batch is by definition a comparison, so its previews are earned. A
+            // single-query search returning one candidate still gets none.
+            attach: (j) => Array.isArray(j?.results)
+                ? true
+                : (Array.isArray(j?.candidates) ? j.candidates.length : 0) > 1,
+        },
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'search_fonts',
+        operationId: 'searchFonts',
+        description: 'Search web font families by name/style — returns family names to use in composition/component params. Pass query (+ optional perPage ≤50). Read-only + free; surfaces the Google Fonts catalog (family + category + variants + css2 stylesheet URL). IMPORTANT: this searches the GOOGLE catalog, not what the render can actually draw. Only the faces vendored into the render page are guaranteed to rasterize; naming any other family gets you the generic fallback (Liberation Sans) with no error. create_render returns a `font_not_available` warning naming the guaranteed set — treat that set, not this catalog, as the list you may choose from. An empty result set here means no match, or the upstream catalog was unavailable.',
+        okFormat: (j) => `${(j.results || []).length} fonts: ${(j.results || []).map((r) => r.family).slice(0, 10).join(', ')}`,
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'import_resource',
+        operationId: 'importResource',
+        description: 'Import a stock candidate (candidateId from search_resources) into a project as an ORG-OWNED media item — provider/externalId/license provenance preserved, bytes deduped across orgs. Pass projectId + candidateId. Returns { id, status:"importing"|"ready" }; processing is async — poll list_media / get_media_context, then use the returned id as a composition source. Gated on the resource_import plan feature (402 billing_required if your plan lacks it). 422 candidate_mismatch if the candidate expired — re-run search_resources.',
+    },
+    {
+        name: 'suggest_briefs',
+        operationId: 'suggestBriefs',
+        pathArgs: { mediaItemId: 'id' },
+        description: 'Run AI clip-suggestion analysis on a long-form media item — the CLIPPING path (find the best short-form moments). Returns { workflowId, status }; then wait_job(kind="suggestions", id=mediaItemId) — its terminal lists each suggestion WITH its briefId. When the media belongs to a PROJECT, each finalized suggestion is promoted to a kind-\'clip\' BRIEF (its window pinned as a beat) — list_briefs {kind:"clip"} shows them and compose({ briefId }) runs the flagship path from one. Project-less media: pass the suggestion id to compose({ suggestionId }) directly. Clipping is a vertical, NOT the general path.',
+    },
+    {
+        name: 'create_webhook',
+        operationId: 'createWebhook',
+        description: 'Register a webhook so long-running jobs notify you instead of blocking on wait_job — the right pattern for fan-out/async agents. Pass url + events — ONE terminal event per job kind with status INSIDE the payload (render.completed, compose.completed, media.completed, suggest.completed) plus checkpoint.ready (a held compose paused for review). DELIVERY: a POST { event, timestamp, projectId?, data } with Standard-Webhooks headers (webhook-id, webhook-timestamp, webhook-signature: v1,<base64>); the secret (whsec_<base64>) is returned ONCE — verify the RAW body with new Webhook(secret).verify(rawBody, headers). ACTIVATION is synchronous: CueFrame POSTs a signed webhook.verify challenge and your endpoint must reply 2xx echoing data.token — otherwise it returns status:"pending" and receives NO events (recover with verify_webhook, no delete/recreate). Read the cueframe://webhook-events resource (or GET /webhooks/events) for the full contract + every event\'s data shape BEFORE building your receiver.',
+    },
+    {
+        name: 'verify_webhook',
+        operationId: 'verifyWebhook',
+        pathArgs: { webhookId: 'id' },
+        description: 'Re-run ownership verification on a PENDING webhook — one whose endpoint did not echo the challenge at create time (check its verification.reason: token_not_echoed / non_2xx_<code> / unreachable / ssrf_blocked). After you fix the receiver to reply 2xx echoing data.token, call this to re-send the signed webhook.verify challenge and flip it active IN PLACE (id + secret preserved — no delete/recreate). Returns { id, status:"active"|"pending", verification? }. An already-active webhook returns active unchanged.',
+        annotations: { idempotentHint: true },
+    },
+    {
+        name: 'get_profile',
+        operationId: 'getProfile',
+        description: "The org's legible taste in ONE read: brand kits, registered critics (the machine-checkable standard both the Director's gates and score_composition enforce), their reference media (presigned thumbnails), and the recent checkpoint-decision log. Read this BEFORE composing for an org you haven't worked with — it is the house style.",
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'list_critics',
+        operationId: 'listCritics',
+        description: 'List registered critics: criticId, label, tier (rules|rubric|evaluator), phase, floor, referenceMediaIds. Rubric text / rules / evaluator URLs are write-only — never echoed. Manage with register_critic (upsert) / delete_critic.',
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'delete_critic',
+        operationId: 'deleteCritic',
+        pathArgs: { criticId: 'criticId' },
+        description: 'Delete a registered critic by its criticId. It stops running in the Director gates and score_composition immediately.',
+        annotations: { destructiveHint: true, idempotentHint: true },
+    },
+    {
+        name: 'register_critic',
+        operationId: 'createCritic',
+        description: "Register a custom eval into the compose critic panel — the critic contract is { rubric (or rules/evaluator), referenceMediaIds?, floor }. Three tiers: rules (declarative constraints — keep-out regions, required elements, max overlays, brand colors), rubric (a text criterion scored by the judge as an extra column), or evaluator (your HTTPS webhook — CueFrame POSTs the composition+stills+facts, you return { score, critique }). referenceMediaIds (≤6 org media ids) attach YOUR reference frames as the standard — the judge scores candidates for consistency with them, so \"indistinguishable from mine\" is a machine check. Lane scope: rules + rubric critics run in BOTH lanes (the Director's gates AND standalone score_composition); evaluator webhooks run in the Director lane only. Use phase 'static' (the default) — 'temporal' (final-render evaluation) is accepted but not yet wired, so a temporal critic produces no verdicts today. A low client score drives a refine like a built-in criterion. You see your eval output + our scores, never our rubric. Re-registering the same criticId upserts (list_critics / delete_critic manage the set). Evaluator tier returns a signing secret ONCE.",
+        annotations: { idempotentHint: true },
+    },
+    {
+        name: 'update_project', operationId: 'patchProject', pathArgs: { projectId: 'id' },
+        description: 'Update a project\'s mutable fields (e.g. name, format, brandKitId). Pass projectId + the changed fields as `body`. Setting brandKitId binds/changes the project brand kit so every render of this project themes from it. Returns the updated ProjectResponse.',
+    },
+    {
+        name: 'delete_project', operationId: 'deleteProject', pathArgs: { projectId: 'id' },
+        description: 'Permanently delete a project you created (cleanup). Removes its composition and render history. Irreversible — only call on a project you own and no longer need.',
+        okText: (a) => `Project ${a.projectId} deleted.`,
+        annotations: { destructiveHint: true },
+    },
+    {
+        name: 'delete_media', operationId: 'deleteMedia', pathArgs: { mediaItemId: 'id' },
+        description: 'Permanently delete a media item from your library (cleanup). Irreversible. Compositions referencing it will fail to render — only delete media no composition still needs.',
+        okText: (a) => `Media ${a.mediaItemId} deleted.`,
+        annotations: { destructiveHint: true },
+    },
+    {
+        name: 'update_component', operationId: 'updateComponent', pathArgs: { componentId: 'id' },
+        description: 'Update an authored component\'s tsxSource/metadata IN PLACE (same id) — the correct verb for the author→preview→fix loop (preview_component returns the compiler error; fix the source here and re-preview, instead of creating a new component each iteration). Pass componentId + the changed fields as `body`.',
+    },
+    {
+        name: 'update_webhook', operationId: 'patchWebhook', pathArgs: { webhookId: 'id' },
+        description: 'Update a webhook subscription (its url or event list). Pass webhookId + changed fields as `body`. The signing secret is NOT rotated here.',
+    },
+    {
+        name: 'delete_webhook', operationId: 'deleteWebhook', pathArgs: { webhookId: 'id' },
+        description: 'Delete a webhook subscription (stop receiving its deliveries). Irreversible — the signing secret is invalidated.',
+        okText: (a) => `Webhook ${a.webhookId} deleted.`,
+        annotations: { destructiveHint: true },
+    },
+    {
+        name: 'cancel_render', operationId: 'cancelRender', pathArgs: { projectId: 'id', renderId: 'renderId' },
+        description: 'Cancel an in-flight render (stop a runaway/queued job). Needs projectId + renderId (from create_render). No-op if already terminal.',
+        okText: (a) => `Render ${a.renderId} cancelled.`,
+        annotations: { idempotentHint: true },
+    },
+    {
+        name: 'cancel_compose', operationId: 'cancelCompose', pathArgs: { projectId: 'id', composeJobId: 'composeJobId' },
+        description: 'Cancel an in-flight compose job (stop a runaway/mis-priced ensemble). Needs projectId + composeJobId (from compose). The director cancel is confirmed before the row flips; any linked charge is released. No-op-reject (422) if already terminal.',
+        okText: (a) => `Compose job ${a.composeJobId} cancelled.`,
+        annotations: { idempotentHint: true },
+    },
+    {
+        name: 'cancel_job', operationId: 'cancelJob', pathArgs: { jobId: 'jobId' },
+        description: 'Cancel a running async job (verify / preview / brand-kit-extract) returned by an enqueue call — abort a mis-priced job instead of waiting out its TTL. For box-backed jobs the warm box is reaped best-effort; cancel never meters. No-op-reject (422) if already terminal.',
+        okText: (a) => `Job ${a.jobId} cancelled.`,
+        annotations: { idempotentHint: true },
+    },
+    {
+        name: 'cancel_export', operationId: 'cancelExport', pathArgs: { projectId: 'id', exportId: 'exportId' },
+        description: 'Cancel an in-flight NLE export (fcpxml/premiere). Needs projectId + exportId (from the export enqueue). No-op-reject (422) if already terminal.',
+        okText: (a) => `Export ${a.exportId} cancelled.`,
+        annotations: { idempotentHint: true },
+    },
+    {
+        name: 'retry_render', operationId: 'retryRender', pathArgs: { projectId: 'id', renderId: 'renderId' },
+        description: 'Re-render an existing render job\'s FROZEN composition snapshot — it inherits that job\'s exact composition/intent/priority and queues a fresh renderJob; it does NOT re-read the project\'s current composition. So it only helps a TRANSIENT failure (the failed render\'s `retryable:true` / `category:"transient"` — a flaky pipeline/infra fault): re-attempting the same snapshot may succeed. For a DETERMINISTIC failure (`retryable:false` / `category:"authoring"` — a bad param, an unresolvable media/brand ref), retry_render reproduces the SAME failure: FIX the composition first via apply_composition, then create_render (a retry alone is futile). Check `retryable` on getRender / wait_job to pick the path. Returns the new render; then wait_job(kind="render", id=<new id>).',
+    },
+    {
+        name: 'get_account', operationId: 'getAccount',
+        description: 'ORIENT FIRST — show THIS key\'s account before you spend a metered call: the org it is bound to, the current plan, a per-feature entitlements map, and per-call cost ceilings. READ `balance`, NOT `included`. CueFrame is credit-funded: rendering (entitlements.exports), generation (generate), preview stills (compose_capture), the judge (compose_verify) and the Director (compose) have NO separate per-plan allowance — they all spend one shared wallet, named in `fundedBy` (`credits`; generation spends `premium_credits`). Each `balance` restates that ONE wallet in that feature\'s own unit at `creditCost` credits per unit, so they are alternative ways to spend the same money, not four budgets. A positive balance means proceed — `create_render`, `compose`, `generate_media` and `create_brand_kit` all succeed on a funded wallet and only 402 `billing_required` once it is spent, so do NOT tell the user a capability is missing, and do not send them to checkout, while balance > 0. `included:false` means the plan genuinely lacks the feature. Every new org starts with a free credit grant, so an account with an empty usage history can still render, generate, preview and score. costCeilings.generateMediaUsdPerCall is the generate_media per-call USD cap. No args — identity is resolved from your key (never echoed from input).',
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'list_plans', operationId: 'getBillingPlans',
+        description: 'List the plan catalog (tiers, intervals, product ids, prices) BEFORE a checkout, so create_checkout requests a real {plan, interval} instead of guessing an id. No args — reads the platform catalog.',
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'get_usage', operationId: 'getUsage',
+        description: "The A2 usage ledger: every metered billing event newest-first with attribution — featureId, amount, the project/job that produced it, and the event's LIST price in USD (a plan allowance may zero it on the invoice). Answer \"what did project X cost this period?\" with a query instead of summing your own quotes. Filter by projectId, jobId, and/or a [from, to) epoch-ms window. Requires the billing:read scope.",
+        queryArgs: {
+            projectId: 'Scope to one project.',
+            jobId: 'One job/render/compose/media id.',
+            from: 'Period start, epoch-ms (inclusive).',
+            to: 'Period end, epoch-ms (exclusive).',
+        },
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: 'create_checkout', operationId: 'createCheckout',
+        description: 'Top up the CURRENT org\'s credit wallet. Body { plan: "credit_pack_10"|"credit_pack_30"|"credit_pack_100" } → returns { url }: a hosted Stripe checkout page to open in a browser and confirm payment. There are no subscription tiers — a pack is a one-off top-up, and it is also the only thing that raises the generation (premium_credits) allowance. Always a URL — an existing saved card is NEVER charged silently; the human confirms on Stripe. The org is resolved from your key, never the body. Requires the billing:write scope. Only send a user here when get_account shows the relevant `balance` at or near zero. Discover the packs with list_plans.',
+    },
+    {
+        name: 'create_brand_kit', operationId: 'createBrandKit',
+        description: 'Create or UPSERT a brand kit (re-POSTing the same kitId updates it in place — this is also the brand-kit UPDATE path). Sets fonts/colors/logo. This is brand step 0 of the workflow: author the kit, then bind it to a PROJECT so colors/fonts/motion theme the output AUTOMATICALLY — pass its kitId as brandKitId to create_project, or attach it to an existing project via PATCH /projects/:id. Without a bound kit, create_render produces UNBRANDED output. Tenant-scoped (no project arg).',
+    },
+    {
+        name: 'extract_brand_kit', operationId: 'extractBrandKit',
+        description: 'Queue brand-token extraction from a website URL — ASYNC: returns a jobId immediately; then wait_job(kind="brand_kit_extract", id=jobId) for the tokens (colors/fonts/title/description, fetched + regex-parsed from the site\'s HTML/CSS — NOT a screenshot/vision pass). It does NOT persist — review the tokens, then call create_brand_kit to save a kit. A blocked (private/SSRF), non-2xx, non-HTML, or slow (>20s) URL degrades to EMPTY token arrays (a succeeded job) rather than erroring — JS-rendered SPAs typically extract empty; author the kit manually from the compiled CSS in that case.',
+        okFormat: (j) => `Brand-extract job queued.\n\njobId: ${j.jobId}\nstatus: ${j.status}\n\nCall wait_job(kind="brand_kit_extract", id="${j.jobId}") for the tokens (re-call it if it returns still-running).`,
+        annotations: { idempotentHint: true },
+    },
+];
+/**
+ * THE editor allowlist — the ONE tool vocabulary an editing agent speaks,
+ * whichever side of the Executor seam it runs on (the Convex editor agent over
+ * the platform executor; the desktop agent over the local one). Passed as
+ * `buildCuratedToolSet(executor, { allowedNames: INTERNAL_EDITOR_TOOLS })`, so
+ * every name here MUST resolve in `[...INTERNAL_LOOP_TOOLS, ...CURATED_TOOLS]` —
+ * the builder SILENTLY SKIPS an unknown name (adapter.ts), which is how a
+ * renamed tool becomes a quietly missing capability. curation.test.ts gates the
+ * subset relation; services/convex/agent/editor/index.ts re-checks at module
+ * load so the failure is loud at boot, not at the turn that needed the tool.
+ *
+ * INTERNAL, as in "not the hosted MCP server's list": three of these
+ * (`get_context`, `search_library`, `analyze_transcript`) live in
+ * INTERNAL_LOOP_TOOLS precisely so they stay OFF that server, and `wait_job` is
+ * registered there by its own procedure. Membership here is NOT publication.
+ */
+export const INTERNAL_EDITOR_TOOLS = [
+    // Read — orient, then look. get_context is the one-call opener.
+    'get_context', 'get_composition', 'get_media_context', 'search_library',
+    'search_resources', 'list_catalog', 'get_profile', 'get_component_source',
+    'preview_frame', 'score_composition', 'validate_composition', 'analyze_transcript',
+    // Mutate — the L1 op union is the ONLY way an edit happens.
+    'apply_composition', 'new_composition', 'derive_composition',
+    // Assets
+    'import_media', 'import_resource', 'create_component', 'generate_media', 'search_fonts',
+    // Jobs + account
+    'create_render', 'wait_job', 'get_usage', 'get_account',
+];
+/**
+ * Resources whose CRUD is INTENTIONALLY incomplete because the backend op does
+ * not exist yet. The coverage gate treats `${resource}.${verb}` keys here as a
+ * documented absence — but `known backend gaps are real` in curation.test.ts
+ * also asserts no generated op exists for them, so a gap CANNOT silently linger
+ * after a backend route ships: the day the op appears, curate it and DELETE the
+ * key. These are follow-up specs, not permanent design.
+ */
+export const KNOWN_BACKEND_GAPS = new Set([
+    'components.delete', // no deleteComponent op — needs route + referential-integrity design (follow-up spec)
+    'brand-kits.delete', // no deleteBrandKit op — needs route + "pinned by project" check (follow-up spec)
+    'media.update', // no patchMedia op — metadata edit; necessity TBD (follow-up spec)
+]);
+/**
+ * Per-resource CRUD coverage map — completeness as an invariant. The coverage
+ * tests in curation.test.ts gate this: every referenced tool must be a real
+ * CURATED_TOOLS name, and every absent verb must be either curated, justified
+ * in `notes`, or a KNOWN_BACKEND_GAPS entry. It fails loud the day a curated
+ * tool references a renamed op or a new resource verb lands unjustified.
+ */
+export const CRUD_COVERAGE = [
+    { resource: 'projects', create: ['create_project'], update: 'update_project', delete: 'delete_project',
+        read: null, notes: { read: 'read via cueframe://project resource' } },
+    { resource: 'compositions', create: ['new_composition', 'derive_composition'], read: ['list_compositions', 'get_composition'],
+        update: null, delete: 'delete_composition',
+        notes: { update: 'edit via apply_composition / putComposition (ops surface, not a CRUD verb)' } },
+    { resource: 'media', create: ['create_upload', 'import_media', 'generate_media'], read: ['list_media', 'get_media_context'],
+        update: null, delete: 'delete_media',
+        notes: { update: 'no patchMedia op yet (KNOWN_BACKEND_GAPS)', create: 'create_upload reserves + presigns a PUT; finalize_upload completes the direct-PUT flow' } },
+    { resource: 'components', create: ['create_component'], update: 'update_component', delete: null,
+        read: ['list_catalog', 'get_component_source'],
+        notes: { read: 'catalog (built-ins + installed, filterable) via list_catalog + cueframe://component resource; source via get_component_source (forkable primitives + installed source)', delete: 'no deleteComponent op yet (KNOWN_BACKEND_GAPS)' } },
+    { resource: 'brand-kits', create: ['create_brand_kit'], update: 'create_brand_kit', delete: null,
+        read: null, notes: { read: 'read via cueframe://brand-kit resource', update: 'create_brand_kit is an upsert', delete: 'no deleteBrandKit op yet (KNOWN_BACKEND_GAPS)' } },
+    { resource: 'briefs', create: ['create_brief'], read: ['get_brief', 'list_briefs'],
+        update: 'update_brief', delete: 'delete_brief' },
+    { resource: 'checkpoints', create: null, read: ['get_checkpoint', 'list_checkpoints'],
+        update: null, delete: null, notes: {
+            create: 'minted server-side at held compose gates (and by verify) — no public create',
+            update: 'answer via resume (the A1 decision grammar); rows are never deleted',
+            delete: 'history is immortal — the retention sweep GCs stills only'
+        } },
+    { resource: 'webhooks', create: ['create_webhook'], update: 'update_webhook', delete: 'delete_webhook',
+        read: null, notes: {
+            read: 'delivery/signing/verification contract via cueframe://webhook-events resource (+ GET /webhooks/events); list/get a specific endpoint via the raw expert layer',
+            update: 'update_webhook (url/events); verify_webhook re-runs the ownership challenge on a pending endpoint in place'
+        } },
+    { resource: 'critics', create: ['register_critic'], update: 'register_critic',
+        read: ['list_critics', 'get_profile'], delete: 'delete_critic',
+        notes: { update: 'register_critic is an upsert (re-register the same criticId)' } },
+    { resource: 'renders', create: ['create_render'], read: null, update: null, delete: null,
+        notes: { read: 'read via cueframe://render resource + wait_job', update: 'lifecycle via cancel_render/retry_render (not a CRUD update)', delete: 'renders are immutable history; no delete by design' } },
+    { resource: 'resources', create: ['import_resource'], read: ['search_resources'], update: null, delete: null,
+        notes: { update: 'stock candidates are immutable upstream provider results — nothing to update',
+            delete: 'an imported resource becomes a mediaItems row; delete it via delete_media' } },
+    { resource: 'fonts', read: ['search_fonts'], create: null, update: null, delete: null,
+        notes: { create: 'fonts are a read-only external catalog (Google Fonts) — a family is referenced by name, not created',
+            update: 'external catalog — immutable upstream',
+            delete: 'external catalog — nothing to delete (referencing a family is free)' } },
+];