@cueframe/kernel 0.0.1

package/dist/chunk-HI4UTTPS.js

@@ -0,0 +1,954 @@
+// ../mcp/src/format.ts
+function fmtClock(sec) {
+  return `${Math.floor(sec / 60)}:${String(Math.floor(sec % 60)).padStart(2, "0")}`;
+}
+
+// ../mcp/src/generated/catalogPreviews.ts
+var CATALOG_PREVIEWS = {
+  "animated-bar-chart": "https://cdn.cueframe.ai/previews/animated-bar-chart@0.2.1.jpg",
+  "animated-line-chart": "https://cdn.cueframe.ai/previews/animated-line-chart@0.2.1.jpg",
+  "dither-gradient-bg": "https://cdn.cueframe.ai/previews/dither-gradient-bg@0.1.1.jpg",
+  "ecosystem-constellation": "https://cdn.cueframe.ai/previews/ecosystem-constellation@0.1.1.jpg",
+  "mesh-gradient-bg": "https://cdn.cueframe.ai/previews/mesh-gradient-bg@0.2.1.jpg",
+  "silk-flow-bg": "https://cdn.cueframe.ai/previews/silk-flow-bg@0.1.1.jpg",
+  "volumetric-rays": "https://cdn.cueframe.ai/previews/volumetric-rays@0.1.1.jpg",
+  "blur": "https://cdn.cueframe.ai/previews/blur@0.1.0.jpg",
+  "color-grade": "https://cdn.cueframe.ai/previews/color-grade@0.1.0.jpg",
+  "grain": "https://cdn.cueframe.ai/previews/grain@0.1.0.jpg",
+  "parallax": "https://cdn.cueframe.ai/previews/parallax@0.1.0.jpg",
+  "particles": "https://cdn.cueframe.ai/previews/particles@0.1.1.jpg",
+  "spotlight-card": "https://cdn.cueframe.ai/previews/spotlight-card@0.1.1.jpg",
+  "spring-pop-in": "https://cdn.cueframe.ai/previews/spring-pop-in@0.1.2.jpg",
+  "success-confetti": "https://cdn.cueframe.ai/previews/success-confetti@0.1.1.jpg",
+  "vignette": "https://cdn.cueframe.ai/previews/vignette@0.1.0.jpg",
+  "chat-to-preview-layout": "https://cdn.cueframe.ai/previews/chat-to-preview-layout@0.1.1.jpg",
+  "infinite-bento-pan": "https://cdn.cueframe.ai/previews/infinite-bento-pan@0.1.1.jpg",
+  "letterbox": "https://cdn.cueframe.ai/previews/letterbox@0.1.0.jpg",
+  "photo-grid": "https://cdn.cueframe.ai/previews/photo-grid@0.1.0.jpg",
+  "picture-in-picture": "https://cdn.cueframe.ai/previews/picture-in-picture@0.1.1.jpg",
+  "split-screen": "https://cdn.cueframe.ai/previews/split-screen@0.1.0.jpg",
+  "staggered-bento-grid": "https://cdn.cueframe.ai/previews/staggered-bento-grid@0.1.1.jpg",
+  "changelog-bite": "https://cdn.cueframe.ai/previews/changelog-bite@0.1.1.jpg",
+  "hero-device-assemble": "https://cdn.cueframe.ai/previews/hero-device-assemble@0.1.1.jpg",
+  "landing-code-showcase": "https://cdn.cueframe.ai/previews/landing-code-showcase@0.1.1.jpg",
+  "live-code-compilation": "https://cdn.cueframe.ai/previews/live-code-compilation@0.1.1.jpg",
+  "pricing-tier-focus": "https://cdn.cueframe.ai/previews/pricing-tier-focus@0.1.1.jpg",
+  "product-launch-trailer": "https://cdn.cueframe.ai/previews/product-launch-trailer@0.1.2.jpg",
+  "terminal-to-browser-deploy": "https://cdn.cueframe.ai/previews/terminal-to-browser-deploy@0.1.1.jpg",
+  "blur-reveal": "https://cdn.cueframe.ai/previews/blur-reveal@0.1.1.jpg",
+  "cinematic-title": "https://cdn.cueframe.ai/previews/cinematic-title@0.1.1.jpg",
+  "inline-highlight": "https://cdn.cueframe.ai/previews/inline-highlight@0.1.1.jpg",
+  "kinetic-type": "https://cdn.cueframe.ai/previews/kinetic-type@0.2.1.jpg",
+  "lower-third": "https://cdn.cueframe.ai/previews/lower-third@0.1.2.jpg",
+  "marker-highlight": "https://cdn.cueframe.ai/previews/marker-highlight@0.1.1.jpg",
+  "masked-slide-reveal": "https://cdn.cueframe.ai/previews/masked-slide-reveal@0.1.0.jpg",
+  "matrix-decode": "https://cdn.cueframe.ai/previews/matrix-decode@0.1.1.jpg",
+  "quote-card": "https://cdn.cueframe.ai/previews/quote-card@0.1.1.jpg",
+  "shimmer-sweep": "https://cdn.cueframe.ai/previews/shimmer-sweep@0.1.1.jpg",
+  "slot-machine-roll": "https://cdn.cueframe.ai/previews/slot-machine-roll@0.1.0.jpg",
+  "staggered-fade-up": "https://cdn.cueframe.ai/previews/staggered-fade-up@0.1.0.jpg",
+  "stat-counter": "https://cdn.cueframe.ai/previews/stat-counter@0.1.1.jpg",
+  "strikethrough-replace": "https://cdn.cueframe.ai/previews/strikethrough-replace@0.1.0.jpg",
+  "text-fade-replace": "https://cdn.cueframe.ai/previews/text-fade-replace@0.1.0.jpg",
+  "token-stream": "https://cdn.cueframe.ai/previews/token-stream@0.1.1.jpg",
+  "tracking-in": "https://cdn.cueframe.ai/previews/tracking-in@0.1.0.jpg",
+  "typewriter": "https://cdn.cueframe.ai/previews/typewriter@0.1.1.jpg",
+  "chromatic-aberration-wipe": "https://cdn.cueframe.ai/previews/chromatic-aberration-wipe@0.2.0.jpg",
+  "code-diff-wipe": "https://cdn.cueframe.ai/previews/code-diff-wipe@0.1.1.jpg",
+  "directional-wipe": "https://cdn.cueframe.ai/previews/directional-wipe@0.2.0.jpg",
+  "frosted-glass-wipe": "https://cdn.cueframe.ai/previews/frosted-glass-wipe@0.2.0.jpg",
+  "glitch-cut": "https://cdn.cueframe.ai/previews/glitch-cut@0.1.0.jpg",
+  "grid-pixelate-wipe": "https://cdn.cueframe.ai/previews/grid-pixelate-wipe@0.2.0.jpg",
+  "ink-wipe": "https://cdn.cueframe.ai/previews/ink-wipe@0.1.1.jpg",
+  "kinetic-type-mask": "https://cdn.cueframe.ai/previews/kinetic-type-mask@0.2.0.jpg",
+  "light-leak": "https://cdn.cueframe.ai/previews/light-leak@0.1.0.jpg",
+  "luma-matte": "https://cdn.cueframe.ai/previews/luma-matte@0.1.0.jpg",
+  "morph": "https://cdn.cueframe.ai/previews/morph@0.1.0.jpg",
+  "spatial-push": "https://cdn.cueframe.ai/previews/spatial-push@0.2.0.jpg",
+  "swipe-transition-wipe": "https://cdn.cueframe.ai/previews/swipe-transition-wipe@0.2.1.jpg",
+  "zoom-through": "https://cdn.cueframe.ai/previews/zoom-through@0.1.0.jpg",
+  "zoom-through-transition": "https://cdn.cueframe.ai/previews/zoom-through-transition@0.1.2.jpg",
+  "ai-generate-overlay": "https://cdn.cueframe.ai/previews/ai-generate-overlay@0.1.2.jpg",
+  "ai-generation-canvas": "https://cdn.cueframe.ai/previews/ai-generation-canvas@0.1.1.jpg",
+  "badge-pop": "https://cdn.cueframe.ai/previews/badge-pop@0.1.1.jpg",
+  "before-after-slider": "https://cdn.cueframe.ai/previews/before-after-slider@0.1.1.jpg",
+  "benchmark-bars": "https://cdn.cueframe.ai/previews/benchmark-bars@0.1.1.jpg",
+  "browser-flow": "https://cdn.cueframe.ai/previews/browser-flow@0.1.1.jpg",
+  "chat-exchange": "https://cdn.cueframe.ai/previews/chat-exchange@0.1.1.jpg",
+  "code-accordion": "https://cdn.cueframe.ai/previews/code-accordion@0.1.1.jpg",
+  "context-meter": "https://cdn.cueframe.ai/previews/context-meter@0.1.1.jpg",
+  "dashboard-populate": "https://cdn.cueframe.ai/previews/dashboard-populate@0.1.1.jpg",
+  "data-flow-pipes": "https://cdn.cueframe.ai/previews/data-flow-pipes@0.1.2.jpg",
+  "device-mockup-zoom": "https://cdn.cueframe.ai/previews/device-mockup-zoom@0.1.1.jpg",
+  "drag-and-drop-flow": "https://cdn.cueframe.ai/previews/drag-and-drop-flow@0.1.1.jpg",
+  "eval-scorecard": "https://cdn.cueframe.ai/previews/eval-scorecard@0.1.1.jpg",
+  "glass-code-block": "https://cdn.cueframe.ai/previews/glass-code-block@0.1.1.jpg",
+  "image-expand-to-fullscreen": "https://cdn.cueframe.ai/previews/image-expand-to-fullscreen@0.1.1.jpg",
+  "metric-gauge": "https://cdn.cueframe.ai/previews/metric-gauge@0.1.1.jpg",
+  "morphing-modal": "https://cdn.cueframe.ai/previews/morphing-modal@0.1.1.jpg",
+  "pipeline-journey": "https://cdn.cueframe.ai/previews/pipeline-journey@0.1.1.jpg",
+  "reasoning-trace": "https://cdn.cueframe.ai/previews/reasoning-trace@0.1.1.jpg",
+  "terminal-simulator": "https://cdn.cueframe.ai/previews/terminal-simulator@0.1.1.jpg",
+  "toast-notification": "https://cdn.cueframe.ai/previews/toast-notification@0.1.1.jpg",
+  "tool-call-stack": "https://cdn.cueframe.ai/previews/tool-call-stack@0.1.1.jpg",
+  "tool-menu-slide-in": "https://cdn.cueframe.ai/previews/tool-menu-slide-in@0.1.1.jpg",
+  "visual-docs-snippet": "https://cdn.cueframe.ai/previews/visual-docs-snippet@0.1.1.jpg",
+  "voice-waveform": "https://cdn.cueframe.ai/previews/voice-waveform@0.1.1.jpg"
+};
+
+// ../mcp/src/curation.ts
+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" : ""}:
+
+${lines.join("\n")}`;
+}
+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(" \xB7 ");
+    const uc = Array.isArray(e.useCase) && e.useCase.length ? ` useCase:${e.useCase.join("/")}` : "";
+    const place = e.placement ? `  \u2192 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 \u2014 pass `after` to page)" : "";
+  return `${data.length} component${data.length !== 1 ? "s" : ""} (recommended-tier first when filtered):
+
+${lines.join("\n")}${more}`;
+}
+function formatResourceCandidates(json) {
+  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 = `\u2500\u2500 "${r?.query}"`;
+      if (r?.error) return `${head}
+  \u2717 ${r.error}`;
+      return `${head}
+${formatResourceCandidates(r)}`;
+    });
+    return `${json.results.length} queries, ${total} candidate(s) total:
+
+${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}\xD7${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}
+    ${cand.kind}${dims}${dur}${by}${lic}  preview: ${cand.previewUrl}`;
+  });
+  const seeMore = items.length === 1 ? "\n\n(no preview attached for a single result \u2014 re-run with limit \u22652 to SEE candidates side by side)" : "";
+  return `${items.length} ${kind} candidate${items.length !== 1 ? "s" : ""} from ${provider} (import one with import_resource({ projectId, candidateId })):
+
+${lines.join("\n")}${seeMore}`;
+}
+var COMPOSITION_VERBATIM_BUDGET = 24e3;
+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)}\u2192${(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") {
+    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(", ")})` : ""}`;
+}
+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 \u2014 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 ?? "?"} \u2014 ${contents.length} clip(s):`);
+    for (const c of contents) lines.push(describeClip(c));
+  }
+  return lines.join("\n");
+}
+function formatWarnings(json) {
+  const warns = Array.isArray(json?.warnings) ? json.warnings : [];
+  return warns.length > 0 ? `
+
+\u26A0 ${warns.join("\n\u26A0 ")}` : "";
+}
+var 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` \u2014 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` \u2014 author from the project\'s CURRENT composition (the GENERAL path: seed it with apply_composition first \u2014 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` \u2014 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.
+
+composeJobId: ${j.composeJobId}
+workflowId: ${j.workflowId}
+status: ${j.status}${j.streamUrl ? `
+streamUrl: ${j.streamUrl}` : ""}
+
+Call 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?} \u2014 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 \u2014 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)` \u2014 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) => {
+      const warns = formatWarnings(j);
+      if (j && typeof j.valid === "boolean") {
+        const r = j;
+        return r.valid ? `Dry-run OK \u2014 composition is valid (nothing persisted).${warns}` : `Dry-run FAILED \u2014 ${(r.errors ?? []).length} error(s), nothing persisted:
+${JSON.stringify(r.errors ?? [], null, 2)}${warns}`;
+      }
+      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\u2194track family (clip_source_track_mismatch), and reframe coverage (reframe_coverage_gap). Always returns ONE shape \u2014 200 { valid, errors, quote } \u2014 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 \u2014 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? } \u2014 `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 \u2014 status rides the payload).",
+    okFormat: (j, a) => `Render queued.
+
+renderId: ${j.id}
+projectId: ${a.projectId}
+status: ${j.status}${formatWarnings(j)}
+
+Call 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 \u2014 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` \u21D2 the project's ACTIVE composition \u2014 exactly what create_render will encode; pass `body.compositionId` to target a specific persisted composition (stale/foreign id \u21D2 404, never a silent fallback). The response's `previewed` field names what was rendered ({source: 'persisted'|'inline'|'scratch', compositionId?, etag?}) \u2014 trust a preview as render-truth ONLY when source is 'persisted'. `body.timestamps` = seconds to sample. A still cannot show motion \u2014 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}.
+source: ${p.source ?? "unknown"}${p.compositionId ? ` \xB7 compositionId: ${p.compositionId}` : ""}${p.etag ? ` \xB7 etag: ${p.etag}` : ""}${p.source !== "persisted" ? ' \u2014 NOT render-truth (only source "persisted" is what create_render will encode)' : ""}`;
+      const lines = stills.map((st, i) => {
+        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}
+${lines.join("\n")}
+
+The frames ride with this result as images \u2014 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 \u2014 ASYNC: returns a jobId immediately; then wait_job(kind="preview", id=jobId) for a presigned short clip (VP9-alpha webm, ~3s \u2014 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\u2192preview\u2192fix loop for a graphic. SESSIONLESS: the warm box is a server detail (a cold first call returns 409 box_warming \u2014 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 \u2014 read it, fix the tsxSource via create_component, and re-preview. Idempotent per (componentId, params, dims).',
+    okFormat: (j) => `Preview job queued.
+
+jobId: ${j.jobId}
+status: ${j.status}
+
+Call 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 \u2014 ONLY body.fromSec\u2192body.toSec of the composition (max 60s) at preview quality (capped resolution, lighter encode) through the real render pipeline. THE way to judge motion \u2014 a cut, a transition, a component's animation \u2014 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.
+
+renderId: ${j.renderId ?? j.id}
+status: ${j.status}
+
+wait_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 \u2014 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\u201310, a weighted composite, a worst-first critique, AND a checkpointId \u2014 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 \u2014 retry in a few seconds. \`body.composition\` optional (absent \u21D2 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.
+
+jobId: ${j.jobId}
+status: ${j.status}
+
+Call 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 \u2014 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 \u2014 no grounded scores, nothing to adopt; 'amend' (default) = the full author\u2192judge\u2192refine loop (minutes) returns a graded `assessment` + a fix candidate you ADOPT via select_candidate with its candidateIndex. ('explore' is coming soon \u2192 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 \u2192 a plan to re-author from; amend \u2192 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} \u2014 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 \u2014 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 \u2014 in-job, no new charge; the brief quote states the included revision cycles, beyond them revise is refused 402), or 'abandon' (end the run \u2014 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", \u2026) to continue \u2014 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 \u2014 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 \u2014 all on-screen copy + captions), hook, caption, beats[] (each with an editorial intent and optional MOMENT PINNING {mediaId, startSec, endSec} \u2014 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 \u2014 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) \u2014 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}) \u2014 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 \u2014 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 \u2014 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 \u2014 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\u2192vN gate history, or projectId). The version stack with per-version status + decisions IS the review history \u2014 nothing is deleted.",
+    queryArgs: {
+      composeJobId: "One compose run's gate history (v1\u2192vN).",
+      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 \u2014 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" } \u2014 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 \u2014 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 \u2014 components are tenant-scoped."
+  },
+  {
+    name: "list_catalog",
+    operationId: "listCatalog",
+    description: "DISCOVER WHAT TO BUILD WITH \u2014 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, \u2026) PLUS your org-installed components. Use it for UTILITY furniture (captions, grades, transitions, backgrounds, scenes) and as REFERENCE CODE (get_component_source) \u2014 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 \u2014 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 \u2014 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, \u2026 }; 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 ? ` \u2014 origin: ${j.origin}` : ""}${j.ejectedFrom ? `, ejectedFrom: ${j.ejectedFrom}` : ""}.
+Edit this tsxSource and create_component it back to own a fork.
+
+${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 \u2014 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 \u2014 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 \u2014 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 }) \u2014 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}.
+
+compositionId: ${j.compositionId}
+format: ${JSON.stringify(j.format)}
+etag: ${j.etag}`
+  },
+  {
+    name: "get_composition",
+    operationId: "getComposition",
+    pathArgs: { projectId: "id" },
+    description: "READ BACK the project's active composition as JSON \u2014 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) \u2014 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 \u2014 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) \u2014 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 \u2014 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 } \u2014 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 \u2014 that is a scale-only export override, not a new composition.)",
+    okFormat: (j, a) => `Derived a reframed sibling composition.
+
+compositionId: ${j.compositionId}
+projectId: ${a.projectId}
+
+Render 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 \u2014 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 \u2014 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 \u2014 poll list_media or use a webhook (media.completed \u2014 status rides the payload). Use the returned id like any other media item.'
+  },
+  {
+    name: "create_upload",
+    operationId: "createMediaUpload",
+    description: "Ingest a LOCAL file \u2014 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 } \u2014 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; \u2264 ~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 \u2014 video/photo (Pexels + Pixabay fallback), sfx (Freesound, CC0-only), gif (Klipy). Pass query for ONE search, or queries[] (\u226410) to run them all in a SINGLE call \u2014 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 \u226450 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 \u2014 reach for this before generate_media when real footage beats synthesis. TO SEE the candidates rather than read about them, pass limit \u22652: 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 \u2014 returns family names to use in composition/component params. Pass query (+ optional perPage \u226450). 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 \u2014 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 \u2014 provider/externalId/license provenance preserved, bytes deduped across orgs. Pass projectId + candidateId. Returns { id, status:"importing"|"ready" }; processing is async \u2014 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 \u2014 re-run search_resources.'
+  },
+  {
+    name: "suggest_briefs",
+    operationId: "suggestBriefs",
+    pathArgs: { mediaItemId: "id" },
+    description: `Run AI clip-suggestion analysis on a long-form media item \u2014 the CLIPPING path (find the best short-form moments). Returns { workflowId, status }; then wait_job(kind="suggestions", id=mediaItemId) \u2014 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) \u2014 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 \u2014 the right pattern for fan-out/async agents. Pass url + events \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 the critic contract is { rubric (or rules/evaluator), referenceMediaIds?, floor }. Three tiers: rules (declarative constraints \u2014 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 \u2014 CueFrame POSTs the composition+stills+facts, you return { score, critique }). referenceMediaIds (\u22646 org media ids) attach YOUR reference frames as the standard \u2014 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) \u2014 '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 \u2014 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 \u2014 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) \u2014 the correct verb for the author\u2192preview\u2192fix 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 \u2014 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 \u2014 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 \u2014 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"` \u2014 a flaky pipeline/infra fault): re-attempting the same snapshot may succeed. For a DETERMINISTIC failure (`retryable:false` / `category:"authoring"` \u2014 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 \u2014 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 \u2014 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 \u2014 `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 \u2014 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 \u2014 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 \u2014 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" } \u2192 returns { url }: a hosted Stripe checkout page to open in a browser and confirm payment. There are no subscription tiers \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 NOT a screenshot/vision pass). It does NOT persist \u2014 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 \u2014 JS-rendered SPAs typically extract empty; author the kit manually from the compiled CSS in that case.`,
+    okFormat: (j) => `Brand-extract job queued.
+
+jobId: ${j.jobId}
+status: ${j.status}
+
+Call wait_job(kind="brand_kit_extract", id="${j.jobId}") for the tokens (re-call it if it returns still-running).`,
+    annotations: { idempotentHint: true }
+  }
+];
+var 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"
+];
+var KNOWN_BACKEND_GAPS = /* @__PURE__ */ 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)
+]);
+var 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) \u2014 no public create",
+      update: "answer via resume (the A1 decision grammar); rows are never deleted",
+      delete: "history is immortal \u2014 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 \u2014 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) \u2014 a family is referenced by name, not created",
+      update: "external catalog \u2014 immutable upstream",
+      delete: "external catalog \u2014 nothing to delete (referencing a family is free)"
+    }
+  }
+];
+
+export {
+  formatMediaList,
+  formatComponentList,
+  formatResourceCandidates,
+  formatComposition,
+  formatWarnings,
+  CURATED_TOOLS,
+  INTERNAL_EDITOR_TOOLS,
+  KNOWN_BACKEND_GAPS,
+  CRUD_COVERAGE
+};