@cueframe/kernel 0.1.0 → 0.1.2

package/dist/_members/mcp/generated/operations.js

@@ -1,131 +0,0 @@
-/**
- * AUTO-GENERATED — do not edit by hand.
- *
- * Source: docs/api/openapi.json
- * Generator: packages/mcp/scripts/generate-tools.mjs
- * Re-run: `pnpm generate:mcp-tools` from the repo root.
- *
- * Transport-agnostic operation manifest. One entry per OpenAPI operation;
- * consumed by the generic raw-tool registrar and the curated tools (for paths)
- * in src/server.ts, executed through the per-transport Executor. CI fails if
- * this file drifts from the current spec.
- */
-/** 116 operations derived from docs/api/openapi.json. */
-export const GENERATED_OPERATIONS = [
-    { operationId: "analyzeTranscript", toolName: "cueframe_api_analyzeTranscript", title: "Analyze Transcript", method: "POST", pathTemplate: "/v1/media/{id}/transcript/analyze", pathParams: ["id"], bodyKey: "analyzeTranscriptBody", description: "Analyse a media item's transcript — Ask ONE editorial question of a transcript and get the answer as text: `summary` (what is actually said, plus the takeaways), `chapters` (where the subject changes), or `highlights` (the moments that stand alone as a short). PRECISION: timestamps are ABSOLUTE seconds from the start of the media and every one is verified against the transcript before you see it (a fabricated timestamp fails the call rather than shipping) — but they are LINE-START markers roughly 15s apart, so a boundary can sit up to 15s BEFORE the moment you asked for. Treat every span as APPROXIMATE: use it to LOCATE the moment, then refine the in/out against the word timings from GET /v1/media/{id}/context before you cut. Feeding a raw span straight into a clip trim will start it mid-sentence. Pass `window` to analyse one slice; omit it for the whole thing. This is a METERED LLM call, not a read: it bills on measured token spend, and a recording too long to analyse in one pass is rejected with 422 `transcript_too_long` (over ~100k characters, roughly two hours of speech) rather than silently summarising only its first half — narrow it with `window`. 422 `media_no_transcript` means the item has no speech on file (or none inside your window); GET /v1/media/{id}/context shows transcript state, and GET /v1/media/{id}/transcript returns the raw words. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "applyComposition", toolName: "cueframe_api_applyComposition", title: "Apply Composition", method: "POST", pathTemplate: "/v1/projects/{id}/composition/apply", pathParams: ["id"], bodyKey: "applyCompositionBody", description: "Apply a batch of operations to a project's composition (or dry-run validate) — Atomically applies an array of CompositionOps. All ops succeed or none do (transactional). Pass `if_match` for optimistic-concurrency control (409 stale_etag on mismatch). Pass `dry_run: true` to validate the batch — runs the same apply + projection accept/reject guards WITHOUT persisting, returning `{ valid, errors }` with `locator.op_index` on the first failing op. Both modes may carry `warnings[]` — non-fatal authoring advisories (e.g. a card whose html reads a CSS custom property no token defines). Warnings never block. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "applyCompositionOp", toolName: "cueframe_api_applyCompositionOp", title: "Apply Composition Op", method: "POST", pathTemplate: "/v1/projects/{id}/composition/ops", pathParams: ["id"], bodyKey: "applyCompositionOpBody", description: "Apply one operation to a project's composition — Required permission: projects:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "cancelCompose", toolName: "cueframe_api_cancelCompose", title: "Cancel Compose", method: "POST", pathTemplate: "/v1/projects/{id}/compose/jobs/{composeJobId}/cancel", pathParams: ["id", "composeJobId"], bodyKey: null, description: "Cancel an in-flight compose job — Cancel a running compose so an agent (or a cost guard) can abort a mis-priced or runaway ensemble without waiting out its budget or TTL. The director-worker cancel is confirmed BEFORE the row flips; the terminal seam fires compose.cancelled and releases any linked charge. Already-terminal jobs are rejected (422 compose_not_cancellable). — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "cancelExport", toolName: "cueframe_api_cancelExport", title: "Cancel Export", method: "POST", pathTemplate: "/v1/projects/{id}/exports/{exportId}/cancel", pathParams: ["id", "exportId"], bodyKey: null, description: "Cancel an in-flight export — Required permission: renders:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "cancelJob", toolName: "cueframe_api_cancelJob", title: "Cancel Job", method: "POST", pathTemplate: "/v1/jobs/{jobId}/cancel", pathParams: ["jobId"], bodyKey: null, description: "Cancel an async job — Cancel a running async job so an agent can abort a mis-priced/runaway operation without waiting out its TTL. For box-backed kinds (verify, preview) the warm box is reaped best-effort. Cancel never meters. Already-terminal jobs are rejected (422 job_not_cancellable). — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "cancelRender", toolName: "cueframe_api_cancelRender", title: "Cancel Render", method: "POST", pathTemplate: "/v1/projects/{id}/renders/{renderId}/cancel", pathParams: ["id", "renderId"], bodyKey: null, description: "Cancel a render — Required permission: renders:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "closeComposeSession", toolName: "cueframe_api_closeComposeSession", title: "Close Compose Session", method: "DELETE", pathTemplate: "/v1/projects/{id}/compose-session/{sessionId}", pathParams: ["id", "sessionId"], bodyKey: null, description: "Close a compose session — Required permission: projects:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false } },
-    { operationId: "commitComposeSession", toolName: "cueframe_api_commitComposeSession", title: "Commit Compose Session", method: "POST", pathTemplate: "/v1/projects/{id}/compose-session/{sessionId}/commit", pathParams: ["id", "sessionId"], bodyKey: null, description: "Commit the session scratch onto the project's active composition — Required permission: projects:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "compose", toolName: "cueframe_api_compose", title: "Compose", method: "POST", pathTemplate: "/v1/projects/{id}/compose", pathParams: ["id"], bodyKey: "composeBody", description: "Start an async Director compose workflow — Async sibling of `composeFromSuggestion`. The Director Temporal workflow authors a canonical wire-shape Composition and saves it to `projects.composition`. Watch progress via the SSE stream at `/v1/projects/:id/compose/:composeJobId/stream`. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "composeFromSuggestion", toolName: "cueframe_api_composeFromSuggestion", title: "Compose From Suggestion", method: "POST", pathTemplate: "/v1/projects/{id}/composition/from-suggestion", pathParams: ["id"], bodyKey: "composeFromSuggestionBody", description: "Build and persist a composition from a clip suggestion — Required permission: projects:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "consult", toolName: "cueframe_api_consult", title: "Consult", method: "POST", pathTemplate: "/v1/projects/{id}/consult", pathParams: ["id"], bodyKey: "consultBody", description: "Ask the multi-agent Director for editing advice (never writes) — Ask the Director for editing advice on the project's current composition — it NEVER saves; you stay the decider. Async: poll the returned job for the advisory envelope. Modes: 'advise' = the planner agent (fast, ~30s-2min) returns a PLAN (framing/cuts/captions/graphics intents) as guidance you re-author from — no grounded scores; 'amend' = the full author→judge→refine loop (minutes) returns a GRADED assessment + an adoptable fix candidate (adopt via POST /compose/jobs/:jobId/select with its candidateIndex). ('explore' — a ranked slate of directions — is coming soon.) — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "createApiKey", toolName: "cueframe_api_createApiKey", title: "Create Api Key", method: "POST", pathTemplate: "/v1/api-keys", pathParams: [], bodyKey: "createApiKeyBody", description: "Create a scoped API key (session credential only) — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "createBrandKit", toolName: "cueframe_api_createBrandKit", title: "Create Brand Kit", method: "POST", pathTemplate: "/v1/brand-kits", pathParams: [], bodyKey: "createBrandKitBody", description: "Create (or upsert) a brand kit — Create or upsert a brand kit. Gated on the `brand_kits` boolean entitlement, which the FREE plan grants — brand-first authoring is deliberately never paywalled — so this is available to every account and costs no credits. A plan without it returns 402 billing_required (`details.featureId: \"brand_kits\"`). Discover the gate WITHOUT a failed round-trip via GET /v1/me — its `entitlements.brand_kits.included` tells you up front. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "createBrief", toolName: "cueframe_api_createBrief", title: "Create Brief", method: "POST", pathTemplate: "/v1/briefs", pathParams: [], bodyKey: "createBriefBody", description: "Create a brief (the persisted intent the Director composes from) — Persist the video's intent — goal/audience/format/tone/CTA, beats with optional moment pinning ({mediaId, startSec, endSec}), captions (style + emphasis phrases), seeded graphics (carried VERBATIM as locked clips), exclusions (hard negatives the Director must never author), and gate config (holdAt / autoApprove). Then compose it with POST /projects/:id/compose {briefId} — every field is honored or the compose is refused loudly naming the field. The response carries the brief-time quote (compose + estimated render) to relay BEFORE any metered call. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "createCheckout", toolName: "cueframe_api_createCheckout", title: "Create Checkout", method: "POST", pathTemplate: "/v1/billing/checkout", pathParams: [], bodyKey: "createCheckoutBody", description: "Start a hosted Stripe checkout for a plan/interval — Body `{ plan, interval }` → returns a hosted Stripe checkout `url` to open in a browser to complete payment. Upgrades the CURRENT org (server-resolved from your key/identity, NEVER the body). Always a hosted URL — an existing saved card is NEVER charged without the human confirming on Stripe. `interval:\"year\"` selects the annual plan. Discover valid combos with GET /v1/billing/plans. Requires `billing:write`. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "createComponent", toolName: "cueframe_api_createComponent", title: "Create Component", method: "POST", pathTemplate: "/v1/components", pathParams: [], bodyKey: "createComponentBody", description: "Author (create) a component — Required permission: projects:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "createCritic", toolName: "cueframe_api_createCritic", title: "Create Critic", method: "POST", pathTemplate: "/v1/critics", pathParams: [], bodyKey: "createCriticBody", description: "Register a compose critic — Required permission: projects:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "createExemplarUploads", toolName: "cueframe_api_createExemplarUploads", title: "Create Exemplar Uploads", method: "POST", pathTemplate: "/v1/brand-kits/exemplar-uploads", pathParams: [], bodyKey: "createExemplarUploadsBody", description: "Reserve presigned PUT slots for inspiration exemplar frames — Returns presigned PUT URLs under this org's `brand-inspiration/…` prefix — the only namespace the brand-kit upsert accepts `exemplarKeys` from. PUT each curated reference frame (≤720px jpeg recommended — the frames become vision input downstream), then upsert the kit with the returned keys. This is the ingest door for agent-driven kit extraction (the `extracting-brand-kits` skill on GET /skills). — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "createFcpxmlExport", toolName: "cueframe_api_createFcpxmlExport", title: "Create Fcpxml Export", method: "POST", pathTemplate: "/v1/projects/{id}/exports/fcpxml", pathParams: ["id"], bodyKey: "createFcpxmlExportBody", description: "Create a Final Cut Pro export — Export the project as a Final Cut Pro XML (FCPXML) timeline — eject the agent-authored edit into a professional NLE for human finishing, preserving clips, trims, and timeline structure. Async: poll GET /projects/:id/exports/:exportId for the download URL. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "createMediaUpload", toolName: "cueframe_api_createMediaUpload", title: "Create Media Upload", method: "POST", pathTemplate: "/v1/media", pathParams: [], bodyKey: "createMediaUploadBody", description: "Initiate a direct upload (presigned PUT URL) — Required permission: media:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "createPremiereExport", toolName: "cueframe_api_createPremiereExport", title: "Create Premiere Export", method: "POST", pathTemplate: "/v1/projects/{id}/exports/premiere", pathParams: ["id"], bodyKey: "createPremiereExportBody", description: "Create a Premiere Pro export — Export the project to Adobe Premiere Pro — eject the agent-authored edit into a professional NLE for human finishing, preserving clips, trims, and timeline structure. Async: poll GET /projects/:id/exports/:exportId for the download URL. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "createProject", toolName: "cueframe_api_createProject", title: "Create Project", method: "POST", pathTemplate: "/v1/projects", pathParams: [], bodyKey: "createProjectBody", description: "Create a project — Create a video project — the container for a composition (the editable timeline), its media, brand kit, and renders. Every other authoring call (import or generate media, apply composition ops, compose, render, export) takes this project's id. Set the output format here (aspectRatio, fps, resolution). — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "createRender", toolName: "cueframe_api_createRender", title: "Create Render", method: "POST", pathTemplate: "/v1/projects/{id}/renders", pathParams: ["id"], bodyKey: "createRenderBody", description: "Create a render job — Render the project's composition to a finished MP4. Async: returns a render id; poll GET /projects/:id/renders/:renderId or stream progress over SSE, then download the signed output URL once status is complete. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "createSession", toolName: "cueframe_api_createSession", title: "Create Session", method: "POST", pathTemplate: "/v1/sessions", pathParams: [], bodyKey: "createSessionBody", description: "Create a session — Required permission: sessions:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "createUploadToken", toolName: "cueframe_api_createUploadToken", title: "Create Upload Token", method: "POST", pathTemplate: "/v1/uploads/token", pathParams: [], bodyKey: "createUploadTokenBody", description: "Mint a short-lived token for the signed upload lane — Required permission: media:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "createWebhook", toolName: "cueframe_api_createWebhook", title: "Create Webhook", method: "POST", pathTemplate: "/v1/webhooks", pathParams: [], bodyKey: "createWebhookBody", description: "Register a webhook endpoint — Register a webhook so long-running jobs (render/compose/media) notify you instead of blocking on wait_job. Body: `url` (https, must pass SSRF checks) + `events` (see the WebhookEvent enum). DELIVERY: each event is a POST with body `{ event, timestamp, projectId?, data }` and Standard-Webhooks headers `webhook-id`, `webhook-timestamp`, `webhook-signature: v1,<base64>` (+ `x-cueframe-event`). The `secret` (`whsec_<base64>`) is returned ONCE here — verify the raw body with `new Webhook(secret).verify(rawBody, headers)`. ACTIVATION (synchronous, no separate step): on create, CueFrame POSTs a signed `webhook.verify` challenge; your endpoint must reply 2xx echoing `data.token` (raw body === token, or JSON `{token}`/`{challenge}`). On success the response is `status:\"active\"`; otherwise `status:\"pending\"` with `verification.reason` and the webhook receives NO events until it verifies (recover with POST /webhooks/:id/verify — no delete/recreate). Full contract + per-event `data` shapes: GET /webhooks/events. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } },
-    { operationId: "createWorkspace", toolName: "cueframe_api_createWorkspace", title: "Create Workspace", method: "POST", pathTemplate: "/v1/workspace", pathParams: [], bodyKey: "createWorkspaceBody", description: "Mint a workspace (project + imported source) in one call — The one-call editing handle: create a project and import the source video URL into it. Returns { projectId, mediaId, importWorkflowId } — the handle a (paying or keyed) agent threads through the compose/render loop. The import is async; poll GET /v1/media/:mediaId for readiness. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "deleteBrief", toolName: "cueframe_api_deleteBrief", title: "Delete Brief", method: "DELETE", pathTemplate: "/v1/briefs/{id}", pathParams: ["id"], bodyKey: null, description: "Delete a brief — Required permission: projects:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false } },
-    { operationId: "deleteComposition", toolName: "cueframe_api_deleteComposition", title: "Delete Composition", method: "DELETE", pathTemplate: "/v1/projects/{id}/compositions/{compositionId}", pathParams: ["id", "compositionId"], bodyKey: null, description: "Delete a composition — Delete a composition and its version history. REFUSES the project's ACTIVE composition (409 composition_active) — make another one active first, or delete the project. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false } },
-    { operationId: "deleteCritic", toolName: "cueframe_api_deleteCritic", title: "Delete Critic", method: "DELETE", pathTemplate: "/v1/critics/{criticId}", pathParams: ["criticId"], bodyKey: null, description: "Delete a registered critic — Required permission: projects:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false } },
-    { operationId: "deleteMedia", toolName: "cueframe_api_deleteMedia", title: "Delete Media", method: "DELETE", pathTemplate: "/v1/media/{id}", pathParams: ["id"], bodyKey: null, description: "Delete a media item — Required permission: media:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false } },
-    { operationId: "deleteProject", toolName: "cueframe_api_deleteProject", title: "Delete Project", method: "DELETE", pathTemplate: "/v1/projects/{id}", pathParams: ["id"], bodyKey: null, description: "Delete a project — Required permission: projects:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false } },
-    { operationId: "deleteSession", toolName: "cueframe_api_deleteSession", title: "Delete Session", method: "DELETE", pathTemplate: "/v1/sessions/{id}", pathParams: ["id"], bodyKey: null, description: "Delete a session — Required permission: sessions:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false } },
-    { operationId: "deleteWebhook", toolName: "cueframe_api_deleteWebhook", title: "Delete Webhook", method: "DELETE", pathTemplate: "/v1/webhooks/{id}", pathParams: ["id"], bodyKey: null, description: "Delete a webhook endpoint — Required permission: webhooks:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false } },
-    { operationId: "deriveComposition", toolName: "cueframe_api_deriveComposition", title: "Derive Composition", method: "POST", pathTemplate: "/v1/projects/{id}/compositions/derive", pathParams: ["id"], bodyKey: "deriveCompositionBody", description: "Derive a reframed sibling composition for a new aspect (multi-format) — Required permission: projects:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "extractBrandKit", toolName: "cueframe_api_extractBrandKit", title: "Extract Brand Kit", method: "POST", pathTemplate: "/v1/brand-kits/extract", pathParams: [], bodyKey: "extractBrandKitBody", description: "Extract brand tokens from a website URL — Queue brand-token extraction from a website URL — ASYNC: returns a 202 job receipt; poll GET /v1/jobs/{jobId} (or MCP wait_job kind=brand_kit_extract) for the tokens (colors, fonts, title, description) on the succeeded result. The executor fetches the site's HTML/CSS (20s cap) and regex-parses tokens — NOT a screenshot/vision pipeline; it does NOT persist a kit (pass the result to POST /brand-kits). A blocked (SSRF/private), non-2xx, non-HTML, or slow URL degrades to EMPTY token arrays on a SUCCEEDED terminal rather than erroring; succeeded extractions are reused for 5 minutes per URL. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } },
-    { operationId: "finalizeMedia", toolName: "cueframe_api_finalizeMedia", title: "Finalize Media", method: "POST", pathTemplate: "/v1/media/{id}/finalize", pathParams: ["id"], bodyKey: "finalizeMediaBody", description: "Finalize a direct upload (trigger processing after the bytes are PUT) — Required permission: media:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "generateMedia", toolName: "cueframe_api_generateMedia", title: "Generate Media", method: "POST", pathTemplate: "/v1/media/generate", pathParams: [], bodyKey: "generateMediaBody", description: "Generate media with AI (video, image, or Manim animation) — Generate a new media item from a text prompt: text-to-video, text-to-image, image-to-video, or a programmatic Manim animation (generator 'auto' picks the best one for the prompt). Async — returns a media id that flips to ready when generation finishes; poll GET /media/:id or register a media.completed webhook. Priced on what the model actually costs; refused with 402 if your balance cannot cover the quote (see GET /me). — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "getAccount", toolName: "cueframe_api_getAccount", title: "Get Account", method: "GET", pathTemplate: "/v1/me", pathParams: [], bodyKey: null, description: "Return the caller's account: identity, plan, entitlements, cost ceilings — Returns the org this key is bound to (server-resolved from auth, never the body), the current plan, a per-feature `entitlements` map, and `costCeilings` (e.g. the generate_media per-call USD ceiling). Read it BEFORE a metered call (create_render / compose / generate_media / create_brand_kit) to budget without burning a round-trip on a 402. READ `balance`, NOT `included`: most capabilities are credit-funded — rendering, generation, previews, the judge and the Director carry no separate per-plan allowance and instead spend the shared wallet named in `fundedBy`, so each `balance` is that one wallet restated in the feature's own `unit`. A positive balance means the call will go through; `included:false` means the plan genuinely lacks the feature. Plan/entitlement values come from the billing backend best-effort; unknown values are `null` and `billingConfigured:false` flags an environment where billing isn't configured. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getBillingPlans", toolName: "cueframe_api_getBillingPlans", title: "Get Billing Plans", method: "GET", pathTemplate: "/v1/billing/plans", pathParams: [], bodyKey: null, description: "List the plan catalog: tiers, intervals, product ids, prices — Returns every purchasable {tier, interval} and its Autumn product id — discovery to read BEFORE POST /v1/billing/checkout so an agent requests a real plan/interval instead of guessing. `priceUsd` is best-effort (null if unavailable); `billingConfigured:false` flags an env without billing. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getBrandKit", toolName: "cueframe_api_getBrandKit", title: "Get Brand Kit", method: "GET", pathTemplate: "/v1/brand-kits/{id}", pathParams: ["id"], bodyKey: null, description: "Get a brand kit by id — Required permission: projects:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getBrandKitExemplars", toolName: "cueframe_api_getBrandKitExemplars", title: "Get Brand Kit Exemplars", method: "POST", pathTemplate: "/v1/brand-kits/{id}/exemplars", pathParams: ["id"], bodyKey: "getBrandKitExemplarsBody", description: "Presign a brand kit's inspiration exemplar frames — Returns short-lived URLs for the kit's exemplar frames (the pixels the maker and judge condition on). Filter to one motif's evidence frames with `motifId`. Vision-budget-bounded consumers should keep `limit` small (default 6). — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "getBrief", toolName: "cueframe_api_getBrief", title: "Get Brief", method: "GET", pathTemplate: "/v1/briefs/{id}", pathParams: ["id"], bodyKey: null, description: "Get a brief by id — Required permission: projects:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getCheckpoint", toolName: "cueframe_api_getCheckpoint", title: "Get Checkpoint", method: "GET", pathTemplate: "/v1/checkpoints/{id}", pathParams: ["id"], bodyKey: null, description: "Get a checkpoint packet — The full approval packet: the stage artifact under review, presigned storyboard/eval stills, critic verdicts (incl. lock_violation entries), the money triple {thisStep, jobSpendSoFar, estimatedJourneyTotal}, and the recorded decision once resolved. Answer an `awaiting` packet with POST /v1/checkpoints/{id}/resume. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getComponent", toolName: "cueframe_api_getComponent", title: "Get Component", method: "GET", pathTemplate: "/v1/components/{id}", pathParams: ["id"], bodyKey: null, description: "Get a component entry — Required permission: projects:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getComponentSource", toolName: "cueframe_api_getComponentSource", title: "Get Component Source", method: "GET", pathTemplate: "/v1/components/{id}/source", pathParams: ["id"], bodyKey: null, description: "Get a component's source — Required permission: projects:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getComposeJob", toolName: "cueframe_api_getComposeJob", title: "Get Compose Job", method: "GET", pathTemplate: "/v1/projects/{id}/compose/jobs/{composeJobId}", pathParams: ["id", "composeJobId"], bodyKey: null, description: "Fetch a compose job's full ensemble state — Required permission: projects:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getComposeSessionComposition", toolName: "cueframe_api_getComposeSessionComposition", title: "Get Compose Session Composition", method: "GET", pathTemplate: "/v1/projects/{id}/compose-session/{sessionId}/composition", pathParams: ["id", "sessionId"], bodyKey: null, description: "Read the session's scratch composition — Pure read: returns the composition currently held in the session's SCRATCH (what the author LLM has been editing over this session), NOT the project's active composition. The Director ensemble reads this back per candidate and returns it as the authored composition — the winner is saved downstream, so a candidate never commits its scratch to active. 404 when the session is unknown/foreign or has never written a scratch. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getComposition", toolName: "cueframe_api_getComposition", title: "Get Composition", method: "GET", pathTemplate: "/v1/projects/{id}/composition", pathParams: ["id"], bodyKey: null, description: "Get a project's composition — Required permission: projects:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getExport", toolName: "cueframe_api_getExport", title: "Get Export", method: "GET", pathTemplate: "/v1/projects/{id}/exports/{exportId}", pathParams: ["id", "exportId"], bodyKey: null, description: "Get an export job — Required permission: renders:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getJob", toolName: "cueframe_api_getJob", title: "Get Job", method: "GET", pathTemplate: "/v1/jobs/{jobId}", pathParams: ["jobId"], bodyKey: null, description: "Get an async job's status and result — Read one async job — the uniform status/result resource behind every long-running operation. Poll until `status` is terminal (`succeeded` | `failed`), then read `result` (kind-specific payload) or `error` (stable code + message). `job_timeout` means the executor died mid-run and the stall sweep reaped the job — re-enqueue the operation to retry. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getMedia", toolName: "cueframe_api_getMedia", title: "Get Media", method: "GET", pathTemplate: "/v1/media/{id}", pathParams: ["id"], bodyKey: null, description: "Get a media item by id — Required permission: media:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getMediaContext", toolName: "cueframe_api_getMediaContext", title: "Get Media Context", method: "GET", pathTemplate: "/v1/media/{id}/context", pathParams: ["id"], bodyKey: null, description: "Get authoring context for a media item (faces + transcript + beat/word grids) — The read-only context an agent needs to author a composition over this source: the detected face/subject roster (face-0 = primary speaker, with normalized bbox + active-speaker share), the transcript, the temporal grids — `beatGrid` (a MUSIC bed's rhythm: bpm, beatTimesMs in milliseconds, confidence, method) and `wordGrid` (VO word-onset timings in milliseconds, from the transcript) — and a presigned `thumbnail` (~the footage at a glance). For stills at CHOSEN timestamps, call preview_frame with a one-clip composition over this media. Call this before authoring crop intents (reframe) and overlay/caption timing. Faces are lazily detected — `faces.status` is `not_detected` until a compose/detect pass has run over the source, never a faked empty roster. `beatGrid` is null until beat analysis has run: generated music beds are analyzed automatically at delivery; an uploaded/imported bed may not carry a grid yet (on-demand analysis is not client-triggerable today). `audioRole` is the DECLARED role of an audio asset (vo | music | sfx | ambience) — author the clip source's `audioRole` from it; `envelope` carries the coarse `envelopeClass` (transient | sweep | ambient) plus any probed attack/centroid/volume stats. Both are null for footage/images or an undeclared audio asset. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getMediaPerformance", toolName: "cueframe_api_getMediaPerformance", title: "Get Media Performance", method: "GET", pathTemplate: "/v1/media/{id}/performance", pathParams: ["id"], bodyKey: null, description: "Per-media performance breakdown (Axiom workflow + activity spans) — Required permission: media:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getMediaTranscript", toolName: "cueframe_api_getMediaTranscript", title: "Get Media Transcript", method: "GET", pathTemplate: "/v1/media/{id}/transcript", pathParams: ["id"], bodyKey: null, description: "Get a media transcript (paginated) — Required permission: media:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getMuxJob", toolName: "cueframe_api_getMuxJob", title: "Get Mux Job", method: "GET", pathTemplate: "/v1/sessions/{id}/mux-job", pathParams: ["id"], bodyKey: null, description: "Poll mux job status — Required permission: sessions:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getOpenAPISpec", toolName: "cueframe_api_getOpenAPISpec", title: "Get Open API Spec", method: "GET", pathTemplate: "/openapi.json", pathParams: [], bodyKey: null, description: "OpenAPI 3.1 document for the v1 API — Returns the generated OpenAPI 3.1 document. Unauthenticated so SDK tooling (Orval, Postman, redocly) can fetch without a key. Cacheable for 5 minutes. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getProfile", toolName: "cueframe_api_getProfile", title: "Get Profile", method: "GET", pathTemplate: "/v1/profile", pathParams: [], bodyKey: null, description: "Read the org's Profile — its legible taste — One read for everything the platform knows about this org's taste: brand kits, registered critics (the machine-checkable standard both the Director's gates and score_composition enforce), the critics' reference media with presigned thumbnails, and the recent checkpoint-decision log (what was approved/revised/abandoned, where). Read this before composing for an org you haven't worked with — it is the house style. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getProject", toolName: "cueframe_api_getProject", title: "Get Project", method: "GET", pathTemplate: "/v1/projects/{id}", pathParams: ["id"], bodyKey: null, description: "Get a project by id — Required permission: projects:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getProjectContext", toolName: "cueframe_api_getProjectContext", title: "Get Project Context", method: "GET", pathTemplate: "/v1/projects/{id}/context", pathParams: ["id"], bodyKey: null, description: "One-call agent context: composition + media + transcript + brand — Everything an authoring agent needs to open a project, in ONE read: the active composition (with its format and markers hoisted), the org's media pool with a `hasTranscript` flag per item, the first transcribed item's word-timed transcript, and the brand kit bound to the project. Replaces the get_composition + get_media_context + get_profile opening sequence. A freshly created project reads back with `composition: null` — that is the empty state, not an error; 404 means the project doesn't exist for your org. Transcript BODIES are never inlined per media item — read another item's with GET /v1/media/{id}/transcript, and its faces/beat/word grids with GET /v1/media/{id}/context. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getRender", toolName: "cueframe_api_getRender", title: "Get Render", method: "GET", pathTemplate: "/v1/projects/{id}/renders/{renderId}", pathParams: ["id", "renderId"], bodyKey: null, description: "Get a render job — Required permission: renders:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getReviewPacket", toolName: "cueframe_api_getReviewPacket", title: "Get Review Packet", method: "GET", pathTemplate: "/v1/review/{id}", pathParams: ["id"], bodyKey: null, description: "Read a hosted review packet (token-authenticated page data) — The checkpoint page's data: stage artifact (rendered from the packet's own snapshot), presigned stills, critic verdicts, the money triple, the recorded decision once resolved, and the run's v1→vN version stack. Authenticated by the packet's reviewToken (?token=) — the URL from the checkpoint.ready webhook / get_checkpoint. Expired or already-answered packets still render (with their decision), never an error page. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getSession", toolName: "cueframe_api_getSession", title: "Get Session", method: "GET", pathTemplate: "/v1/sessions/{id}", pathParams: ["id"], bodyKey: null, description: "Get a session — Required permission: sessions:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getSkill", toolName: "cueframe_api_getSkill", title: "Get Skill", method: "GET", pathTemplate: "/v1/skills/{name}", pathParams: ["name"], bodyKey: null, description: "Get a skill's SKILL.md (markdown) — Returns the raw SKILL.md for the named skill as `text/markdown`, ready to load into an agent. 404 if the skill name is unknown. Unauthenticated. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getUsage", toolName: "cueframe_api_getUsage", title: "Get Usage", method: "GET", pathTemplate: "/v1/usage", pathParams: [], bodyKey: null, description: "List metered usage events (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 (the invoice may zero it inside a plan allowance). Filter by projectId, jobId, and/or a [from, to) epoch-ms period. Events appear moments after the job's success terminal (the meter is scheduler-dispatched). — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getWebhook", toolName: "cueframe_api_getWebhook", title: "Get Webhook", method: "GET", pathTemplate: "/v1/webhooks/{id}", pathParams: ["id"], bodyKey: null, description: "Get a webhook endpoint — Required permission: webhooks:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "getWebhookEvents", toolName: "cueframe_api_getWebhookEvents", title: "Get Webhook Events", method: "GET", pathTemplate: "/v1/webhooks/events", pathParams: [], bodyKey: null, description: "Get the webhook delivery contract — The machine-readable webhook contract: the delivery envelope, Standard-Webhooks signing (secret format, signed content, how to verify), the synchronous echo-the-token ownership handshake, and every subscribable event with its exact `data` fields. Read this before building a receiver — it answers 'what's the payload shape / how do I verify the signature / how does activation work' without guessing. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "health", toolName: "cueframe_api_health", title: "Health", method: "GET", pathTemplate: "/v1/health", pathParams: [], bodyKey: null, description: "Shallow + deep health check — Shallow (default) returns 200 with a minimal liveness payload for load balancers. Append `?deep=1` to exercise component bindings (rate-limiter). Unauthenticated. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "importMedia", toolName: "cueframe_api_importMedia", title: "Import Media", method: "POST", pathTemplate: "/v1/media/import", pathParams: [], bodyKey: "importMediaBody", description: "Import media from a URL (server-side fetch) — Import media into the project from a public https URL — the server fetches and mirrors the bytes (SSRF-filtered), then processes it (transcode + transcribe). Async: returns a media id that flips to ready when the mirror and processing finish; poll GET /media/:id or use a media.completed webhook. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } },
-    { operationId: "importResource", toolName: "cueframe_api_importResource", title: "Import Resource", method: "POST", pathTemplate: "/v1/resources/import", pathParams: [], bodyKey: "importResourceBody", description: "Import a stock candidate or a curated SFX-pack sound — Two lanes. STOCK { projectId, candidateId }: import a candidate returned by search_resources into a project as an org-owned media item (preserving provider/externalId/license provenance; bytes deduped across orgs). Async: returns { id, status:'importing' }; the row flips to complete when the mirror finishes (poll GET /media/:id). A candidate whose 7-day search cache has expired returns 422 — re-search. PACK { kind:\"sfx-pack\", id:<soundId> }: mint/return the org media item for a curated CC0 SFX-pack sound (soundId from list_catalog's sfx[]) — bytes pre-seeded, so returns { id, status:'ready' } immediately to place as a normal sfx clip. Idempotent per (org, soundId); an unknown soundId is a 422. Pack imports are FREE: no plan feature required, and an x402 payment is released unsettled (no charge). — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } },
-    { operationId: "listBrandKits", toolName: "cueframe_api_listBrandKits", title: "List Brand Kits", method: "GET", pathTemplate: "/v1/brand-kits", pathParams: [], bodyKey: null, description: "List brand kits (read-only) — Required permission: projects:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "listBriefs", toolName: "cueframe_api_listBriefs", title: "List Briefs", method: "GET", pathTemplate: "/v1/briefs", pathParams: [], bodyKey: null, description: "List briefs (optionally scoped to a project) — DEFAULT lists human-authored briefs only. Machine-minted clip briefs (suggest_briefs output) are opt-in: ?kind=clip lists just them, ?kind=all lists everything. Any other kind value is a 400, never silently empty. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "listCatalog", toolName: "cueframe_api_listCatalog", title: "List Catalog", method: "GET", pathTemplate: "/v1/components", pathParams: [], bodyKey: null, description: "List component catalog (defaults + installed) — Discover the built-in primitive catalog (87 primitives + 7 scenes) plus your installed components. Narrow with facet filters (category, kind, tier, useCase, mood) or free-text (q / intent); when ANY filter is set, results are ordered recommended-tier-first. With NO `limit` the WHOLE (filtered) catalog returns in one page — pass `limit` only to page. Each entry carries a `placement` hint telling you exactly how to author it on the timeline. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "listCheckpoints", toolName: "cueframe_api_listCheckpoints", title: "List Checkpoints", method: "GET", pathTemplate: "/v1/checkpoints", pathParams: [], bodyKey: null, description: "List checkpoints (scope to a compose job or project) — The version stack of approval packets, newest first. Scope with ?composeJobId= to see one run's gate history (v1→vN with per-version status + decisions) or ?projectId= for everything reviewable in a project. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "listComposeJobs", toolName: "cueframe_api_listComposeJobs", title: "List Compose Jobs", method: "GET", pathTemplate: "/v1/projects/{id}/compose/jobs", pathParams: ["id"], bodyKey: null, description: "List recent compose jobs for a project — Required permission: projects:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "listCompositions", toolName: "cueframe_api_listCompositions", title: "List Compositions", method: "GET", pathTemplate: "/v1/projects/{id}/compositions", pathParams: ["id"], bodyKey: null, description: "List a project's compositions — Required permission: projects:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "listCritics", toolName: "cueframe_api_listCritics", title: "List Critics", method: "GET", pathTemplate: "/v1/critics", pathParams: [], bodyKey: null, description: "List registered critics (Profile family) — Every enabled critic: id, label, tier, phase, floor, and reference media. Rubric text, rules, and evaluator URLs are write-only — registration config comes back, payloads don't. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "listMedia", toolName: "cueframe_api_listMedia", title: "List Media", method: "GET", pathTemplate: "/v1/media", pathParams: [], bodyKey: null, description: "List media items — Paginated library list. Filter with ?kind= (video|audio|image|gif|asset|source|stock), ?source= (upload|generated|import-url|stock), ?tag= (exact tag) so a real library isn't an undifferentiated soup. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "listMediaSuggestions", toolName: "cueframe_api_listMediaSuggestions", title: "List Media Suggestions", method: "GET", pathTemplate: "/v1/media/{id}/suggestions", pathParams: ["id"], bodyKey: null, description: "List clip suggestions for a media item — Required permission: media:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "listProjectRenders", toolName: "cueframe_api_listProjectRenders", title: "List Project Renders", method: "GET", pathTemplate: "/v1/projects/{id}/renders", pathParams: ["id"], bodyKey: null, description: "List renders for a project — Required permission: renders:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "listProjects", toolName: "cueframe_api_listProjects", title: "List Projects", method: "GET", pathTemplate: "/v1/projects", pathParams: [], bodyKey: null, description: "List projects — Required permission: projects:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "listRegistryOverlays", toolName: "cueframe_api_listRegistryOverlays", title: "List Registry Overlays", method: "GET", pathTemplate: "/v1/registry/overlays", pathParams: [], bodyKey: null, description: "List built-in primitive registry entries (deprecated; use GET /v1/components) — Required permission: projects:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "listSelectorCandidates", toolName: "cueframe_api_listSelectorCandidates", title: "List Selector Candidates", method: "GET", pathTemplate: "/v1/projects/{id}/selector/candidates", pathParams: ["id"], bodyKey: null, description: "List switch (multicam) candidates + recommendation for a synced-angle group — Required permission: media:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "listSessions", toolName: "cueframe_api_listSessions", title: "List Sessions", method: "GET", pathTemplate: "/v1/sessions", pathParams: [], bodyKey: null, description: "List sessions — Required permission: sessions:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "listSkills", toolName: "cueframe_api_listSkills", title: "List Skills", method: "GET", pathTemplate: "/v1/skills", pathParams: [], bodyKey: null, description: "List available CueFrame agent skills — Returns the agent skills CueFrame publishes (e.g. `cueframe-cli`). Metadata only — fetch the markdown body from GET /skills/{name}. Unauthenticated, like /openapi.json. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "listWebhooks", toolName: "cueframe_api_listWebhooks", title: "List Webhooks", method: "GET", pathTemplate: "/v1/webhooks", pathParams: [], bodyKey: null, description: "List webhook endpoints — Required permission: webhooks:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "newComposition", toolName: "cueframe_api_newComposition", title: "New Composition", method: "POST", pathTemplate: "/v1/projects/{id}/compositions", pathParams: ["id"], bodyKey: "newCompositionBody", description: "Create a new composition (video) in a project — Required permission: projects:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "openComposeSession", toolName: "cueframe_api_openComposeSession", title: "Open Compose Session", method: "POST", pathTemplate: "/v1/projects/{id}/compose-session", pathParams: ["id"], bodyKey: "openComposeSessionBody", description: "Open a live compose session — Boot a warm reactive render session for the project. Render frames on demand via the session's /render endpoint; closed automatically after idle TTL or explicitly via DELETE. Optionally seed the session scratch FROM a supplied composition (seedComposition) instead of the project's active — the body is optional (a bodyless open derives from active). — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "patchProject", toolName: "cueframe_api_patchProject", title: "Patch Project", method: "PATCH", pathTemplate: "/v1/projects/{id}", pathParams: ["id"], bodyKey: "patchProjectBody", description: "Update a project — Required permission: projects:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "patchWebhook", toolName: "cueframe_api_patchWebhook", title: "Patch Webhook", method: "PATCH", pathTemplate: "/v1/webhooks/{id}", pathParams: ["id"], bodyKey: "patchWebhookBody", description: "Update a webhook endpoint — Required permission: webhooks:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true } },
-    { operationId: "previewClip", toolName: "cueframe_api_previewClip", title: "Preview Clip", method: "POST", pathTemplate: "/v1/projects/{id}/preview-clip", pathParams: ["id"], bodyKey: "previewClipBody", description: "Render a scoped motion preview of the composition — A cheap, watchable MP4 of ONLY [fromSec, toSec) of the composition at preview quality (capped resolution, lighter encode). The way to judge motion — a cut, a transition, a component's animation — with real fidelity BEFORE paying for a full render. Async: returns a render job; wait_job(kind='render') or webhook render.completed for the URL. Meters the capture feature, never an exports credit. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "previewComponent", toolName: "cueframe_api_previewComponent", title: "Preview Component", method: "POST", pathTemplate: "/v1/projects/{id}/component-preview", pathParams: ["id"], bodyKey: "previewComponentBody", description: "Render one component's motion-clip preview — Queue a MOTION-clip render of ONE org-installed component (VP9-alpha webm). It is the SAME content-addressed bake the production render composites — so what you preview is literally the object that ships, and previewing an unchanged component is free. Returns a jobId — wait_job(kind='preview') for the clip. Compile/runtime failures land on the job terminal with the sanitized author-fixable message. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "previewFrame", toolName: "cueframe_api_previewFrame", title: "Preview Frame", method: "POST", pathTemplate: "/v1/projects/{id}/preview-frame", pathParams: ["id"], bodyKey: "previewFrameBody", description: "Render still frame(s) of a composition — Render presigned still(s) of the composition at the given timestamps — the live preview for layout/copy judgment (a still cannot show motion: judge motion with preview_clip or preview_component). Stateless: nothing to open, warm, or close, and concurrent previews no longer contend. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "previewSelector", toolName: "cueframe_api_previewSelector", title: "Preview Selector", method: "POST", pathTemplate: "/v1/projects/{id}/selector/preview", pathParams: ["id"], bodyKey: "previewSelectorBody", description: "Re-resolve a switch advisory under a hand-supplied policy (A/B taste; not persisted) — Required permission: media:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "putComposition", toolName: "cueframe_api_putComposition", title: "Put Composition", method: "PUT", pathTemplate: "/v1/projects/{id}/composition", pathParams: ["id"], bodyKey: "putCompositionBody", description: "Replace a project's composition — Required permission: projects:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false } },
-    { operationId: "recordReviewDecision", toolName: "cueframe_api_recordReviewDecision", title: "Record Review Decision", method: "POST", pathTemplate: "/v1/review/{id}/decision", pathParams: ["id"], bodyKey: null, description: "Record a hosted review decision (the same resume rail) — Record approve / revise / abandon from the hosted page. Server-side this IS POST /v1/checkpoints/{id}/resume — one implementation; the driving agent learns of the decision via the checkpoint webhooks / wait_job. 409 when the packet is no longer awaiting (superseded, expired, or already decided). — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "refreshRenderUrl", toolName: "cueframe_api_refreshRenderUrl", title: "Refresh Render Url", method: "POST", pathTemplate: "/v1/projects/{id}/renders/{renderId}/refresh-url", pathParams: ["id", "renderId"], bodyKey: null, description: "Refresh a render's output URL — Required permission: renders:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "resetMediaSuggestions", toolName: "cueframe_api_resetMediaSuggestions", title: "Reset Media Suggestions", method: "DELETE", pathTemplate: "/v1/media/{id}/suggestions", pathParams: ["id"], bodyKey: null, description: "Reset clip suggestions for a media item — Required permission: media:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false } },
-    { operationId: "resumeCheckpoint", toolName: "cueframe_api_resumeCheckpoint", title: "Resume Checkpoint", method: "POST", pathTemplate: "/v1/checkpoints/{id}/resume", pathParams: ["id"], bodyKey: "resumeCheckpointBody", description: "Answer a held checkpoint (approve / revise / abandon) — The A1 review grammar: one `decision` for the gate, optionally carrying anchored `comments` ({beatId} or {timecodeMs} anchors; per-anchor verdict approve|revise|lock — lock freezes the element contractually) and/or `edits` (your revised stage artifact). `revise` loops IN-JOB: the director revises and re-presents this same gate with a new packet (version+1); the brief quote states the included revision cycles — beyond them, revise is refused 402 with the path forward. `abandon` ends the run. Approve-with-comments is legal: the notes record without gating. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "retryRender", toolName: "cueframe_api_retryRender", title: "Retry Render", method: "POST", pathTemplate: "/v1/projects/{id}/renders/{renderId}/retry", pathParams: ["id", "renderId"], bodyKey: null, description: "Re-render against an existing renderJob's snapshot — Required permission: renders:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "scoreComposition", toolName: "cueframe_api_scoreComposition", title: "Score Composition", method: "POST", pathTemplate: "/v1/projects/{id}/score-composition", pathParams: ["id"], bodyKey: "scoreCompositionBody", description: "Score a composition (the standalone sighted judge) — Queue the server-side judge: it samples eval beats, renders them, and grades editorial/spatial/brand/caption (0–10 + weighted composite + worst-first critique). Your REGISTERED CRITICS run too (register_critic) — rules + rubric verdicts ride the result as clientScores, exactly like the Director's gates evaluate them (evaluator-webhook critics run in the Director lane only). Returns a jobId — wait_job(kind='verify') for the result, which ALSO carries a checkpointId: the verdicts mint a durable kind:'score' Checkpoint (the same evidence noun the Director's gates produce). Stateless — nothing to open, warm or close; the compose_verify meter fires on the job's success terminal. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "searchFonts", toolName: "cueframe_api_searchFonts", title: "Search Fonts", method: "POST", pathTemplate: "/v1/fonts/search", pathParams: [], bodyKey: "searchFontsBody", description: "Search web font families by name/style — Search the Google Fonts web-font catalog by keyword. Returns matching font families (family name + category + available variants + a css2 stylesheet URL) — use a returned `family` in composition/component text params. Read-only and free; results are cached server-side. An empty `results` array means no match (or the upstream catalog was unavailable). — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } },
-    { operationId: "searchLibrary", toolName: "cueframe_api_searchLibrary", title: "Search Library", method: "GET", pathTemplate: "/v1/media/search", pathParams: [], bodyKey: null, description: "Semantic search over the org's own footage — Find MOMENTS in your library by describing what they look like. The query is embedded with the same CLIP model that embedded every indexed frame, so it matches on visual content — \"wide shot of a speaker at a whiteboard\", \"hands on a keyboard\", \"city skyline at dusk\" — including shots nobody talks about (which is where transcript search fails). Results are time-ranged: feed `mediaId` + `startSec`/`endSec` straight into apply_composition as a clip. `q` is required; `limit` defaults to 10 and caps at 25. `indexing` is COVERAGE, not emptiness: it is true whenever some of the org's footage is not in the visual index yet (media that predates it, or still processing), and it can be true ALONGSIDE results — then read them as \"the best moments among what we have looked at so far\". Empty `results` with `indexing: true` is a state, not a failure; re-run the item through processing to index it. TIMING: the text encoder scales to zero, so the first search after an idle period can take up to ~90s while it cold-starts — that is a documented wait, not a hang; subsequent searches are fast. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "searchResources", toolName: "cueframe_api_searchResources", title: "Search Resources", method: "POST", pathTemplate: "/v1/resources/search", pathParams: [], bodyKey: "searchResourcesBody", description: "Search stock media (Pexels / Pixabay / Freesound / Klipy) — Search licensed stock media by keyword. Pass `query` for one search, or `queries[]` (≤10) to run a batch in ONE call — the batch returns `results[]`, one entry per query in order, each with its own `candidates` (and an `error` string if that single query failed; one bad query never discards the rest). `kind` selects the corpus (video/photo → Pexels+Pixabay, sfx → Freesound CC0-only, gif → Klipy); defaults to video. Returns ranked candidates each carrying an opaque `candidateId` — pass it to import_resource to bring the asset into a project. Free + rate-limited; results are cached for 7 days, after which a candidateId must be refreshed by searching again. For sfx, bound the result by clip length with `durationSec` — impacts/ticks ≈ 0–2s, risers/whooshes ≈ 2–8s, ambients unbounded. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } },
-    { operationId: "selectComposeCandidate", toolName: "cueframe_api_selectComposeCandidate", title: "Select Compose Candidate", method: "POST", pathTemplate: "/v1/projects/{id}/compose/jobs/{composeJobId}/select", pathParams: ["id", "composeJobId"], bodyKey: "selectComposeCandidateBody", description: "Promote a compose candidate to projects.composition — Selects one candidate from a finished compose ensemble and writes it to the project's composition. `selectStrategy` decides how the editor draft interacts with the write (per compose-api-contract.md). — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "streamCompose", toolName: "cueframe_api_streamCompose", title: "Stream Compose", method: "GET", pathTemplate: "/v1/projects/{id}/compose/jobs/{composeJobId}/stream", pathParams: ["id", "composeJobId"], bodyKey: null, description: "Stream compose progress (SSE) — Server-Sent Events stream emitting typed `compose_event` frames (per `2026-05-23-compose-api-contract.md` § SSE event types — job_started, candidate_phase_started, candidate_phase_evaluated, candidate_completed, critique_retry_started, winner_selected, job_completed, job_failed). The stream closes once the composeJobs row reaches a terminal status. Required scope: projects:read — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-    { operationId: "suggestBriefs", toolName: "cueframe_api_suggestBriefs", title: "Suggest Briefs", method: "POST", pathTemplate: "/v1/media/{id}/suggestions", pathParams: ["id"], bodyKey: null, description: "Trigger clip-suggestion analysis — Analyze a video for its best short-form moments — returns ranked clip suggestions with trims, hooks, titles, captions, hashtags, and platform fit for turning long footage into shorts. Async: returns 202; poll GET /media/:id/suggestions for the ranked results. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "testWebhook", toolName: "cueframe_api_testWebhook", title: "Test Webhook", method: "POST", pathTemplate: "/v1/webhooks/{id}/test", pathParams: ["id"], bodyKey: null, description: "Fire a webhook.test delivery — Required permission: webhooks:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } },
-    { operationId: "triggerMuxJob", toolName: "cueframe_api_triggerMuxJob", title: "Trigger Mux Job", method: "POST", pathTemplate: "/v1/sessions/{id}/mux-job", pathParams: ["id"], bodyKey: null, description: "Trigger mux-audio-onto-video workflow — Required permission: sessions:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "triggerSubjectDetection", toolName: "cueframe_api_triggerSubjectDetection", title: "Trigger Subject Detection", method: "POST", pathTemplate: "/v1/media/{id}/detect-subjects", pathParams: ["id"], bodyKey: null, description: "Trigger standalone subject/face detection — Required permission: media:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "updateBrief", toolName: "cueframe_api_updateBrief", title: "Update Brief", method: "PATCH", pathTemplate: "/v1/briefs/{id}", pathParams: ["id"], bodyKey: "updateBriefBody", description: "Edit a brief — Partial update. While an ACTIVE compose job references this brief the edit is refused (409 conflict) — finish, resume, or abandon the job first; the Director never has its input edited out from under it. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "updateComponent", toolName: "cueframe_api_updateComponent", title: "Update Component", method: "PUT", pathTemplate: "/v1/components/{id}", pathParams: ["id"], bodyKey: "updateComponentBody", description: "Update an authored component — Required permission: projects:write — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false } },
-    { operationId: "validateComposition", toolName: "cueframe_api_validateComposition", title: "Validate Composition", method: "POST", pathTemplate: "/v1/composition/validate", pathParams: [], bodyKey: "validateCompositionBody", description: "Validate a composition body without saving it (dry-run) — Dry-run the FULL save-time authoring guard set against a Composition body WITHOUT persisting it and without a project. Runs the same pure, DB-free guards saveComposition enforces — wire shape, 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) — and returns ONE shape, `200 { valid, errors[] }`, for BOTH wire-shape and deep-invariant failures (no 400-vs-200 split). `valid:false` lists every authoring error (sanitized envelopes) to fix before save/render. The ONLY checks NOT run here are the two DB-bound ones — trim-bounds (media duration) and image/asset-on-video-track (media kind) — which can only be caught at save/render. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } },
-    { operationId: "verifyWebhook", toolName: "cueframe_api_verifyWebhook", title: "Verify Webhook", method: "POST", pathTemplate: "/v1/webhooks/{id}/verify", pathParams: ["id"], bodyKey: null, description: "Re-run webhook ownership verification — Re-send the signed `webhook.verify` ownership challenge to a PENDING webhook's url and, if the endpoint now echoes `data.token` in a 2xx, flip it active — IN PLACE (id + secret preserved; no delete/recreate). Use it to recover after fixing a receiver that failed the challenge at create time. An already-verified webhook returns `status:\"active\"` unchanged (idempotent). Returns the same `{ status, verification? }` shape as create. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } },
-    { operationId: "whoami", toolName: "cueframe_api_whoami", title: "Whoami", method: "GET", pathTemplate: "/v1/whoami", pathParams: [], bodyKey: null, description: "Return the caller identity + permissions — Echoes the `orgId`, `permissions`, and key metadata derived from the Authorization header (or x402 payment). Useful for SDKs to confirm which org a key is bound to and what permissions it carries. — Advanced (expert layer) — prefer the curated high-level tools (compose, apply_composition, create_render, wait_job, get_media_context) when they fit your task.", annotations: { "readOnlyHint": true, "openWorldHint": false } },
-];

package/dist/_members/mcp/index.js

@@ -1,50 +0,0 @@
-/**
- * CueFrame MCP — stdio entry point.
- *
- * Run with: CUEFRAME_API_KEY=cf_live_... npx cueframe-mcp
- *
- * This file is THIN: it builds a network `Executor` (fetch against the public
- * API with the env key, single-tenant) and hands it to the transport-agnostic
- * core in ./server.ts, then opens a StdioServerTransport. The hosted MCP route
- * (services/convex/api/routes/mcp.ts) builds the SAME server from ./server.ts
- * with an in-process executor — one surface, two transports.
- *
- * Layers (all from ./server.ts, gated by check:sdk-drift):
- *   - curated front-door  (registerCuratedTools)
- *   - read resources      (registerResources)
- *   - raw expert layer    (registerRawTools — only when CUEFRAME_MCP_EXPERT is set)
- *   - skills-as-prompts   (registerSkillPrompts; fail-loud at boot)
- *   - SERVER_INSTRUCTIONS harness (generated from director.md)
- */
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { buildServer } from './server.js';
-import { SERVER_INSTRUCTIONS } from './generated/harness.js';
-import { registerSkillPrompts } from './prompts.js';
-import { API_URLS, makeNetworkExecutor } from './executor.js';
-export { buildServer, registerCuratedTools, registerRawTools } from './server.js';
-// The network executor + URL table now live in ./executor.ts (boot-free) so
-// services can import them without triggering the stdio boot below; re-export
-// keeps the stdio entry's public API unchanged.
-export { makeNetworkExecutor, makePlatformExecutor, API_URLS } from './executor.js';
-async function main() {
-    const apiKey = process.env.CUEFRAME_API_KEY;
-    if (!apiKey)
-        throw new Error('CUEFRAME_API_KEY environment variable is required');
-    const target = process.env.CUEFRAME_TARGET ?? 'prod';
-    const baseUrl = process.env.CUEFRAME_API_URL ?? API_URLS[target] ?? API_URLS.prod;
-    const executor = makeNetworkExecutor(baseUrl, apiKey);
-    const server = buildServer({
-        executor,
-        expert: Boolean(process.env.CUEFRAME_MCP_EXPERT),
-        instructions: SERVER_INSTRUCTIONS,
-    });
-    // Skills-as-prompts needs the API at boot; fail-loud (a stdio server with no
-    // reachable API is useless).
-    await registerSkillPrompts(server, executor, { failLoud: true });
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-}
-// Boot stdio when run as the entrypoint. Skip under the test runner.
-if (!process.env.VITEST) {
-    await main();
-}

package/dist/_members/mcp/internalLoopTools.js

@@ -1,109 +0,0 @@
-export const INTERNAL_LOOP_TOOLS = [
-    {
-        name: 'render_frame',
-        // Sessionless — the same op the public `preview_frame` uses.
-        operationId: 'previewFrame',
-        pathArgs: { projectId: 'id' },
-        description: 'Render still(s) of the WHOLE composition at the given timestamps, returning presigned image(s) — the in-loop full-composition preview. `body.timestamps` is an array of clip-relative SECONDS: pass EVERY beat you want to inspect in ONE call — a call is flat-cost and one budget unit however many timestamps it carries, and all render in a single pass (a contact sheet), so never spend calls one frame at a time. Stills are content-addressed: re-rendering an unchanged composition is free, and the judge grades the EXACT frames you looked at. (One component instead of the whole composition? use preview_component.)',
-        annotations: { readOnlyHint: true },
-    },
-    {
-        name: 'verify_composition',
-        operationId: 'scoreComposition',
-        pathArgs: { projectId: 'id' },
-        description: 'Queue the server-side judge for this composition — ASYNC: returns a jobId (the judge samples eval beats, renders them, and grades editorial/spatial/brand/caption). The in-loop wrapper blocks until terminal and returns per-criterion scores 0–10, a weighted composite, and a worst-first critique; fix the lowest criterion via apply_composition and re-verify. Idempotent per composition state.',
-        annotations: { idempotentHint: true },
-    },
-    {
-        name: 'preview_component',
-        operationId: 'previewComponent',
-        pathArgs: { projectId: 'id' },
-        description: 'Queue a MOTION-clip render of ONE org-installed component — ASYNC; the in-loop wrapper blocks until terminal and returns the clip. It is the SAME content-addressed bake the production render composites, so what you preview is literally the object that ships, and previewing an unchanged component is free. Failures carry typed codes (component_does_not_compile / component_runtime_error) with the sanitized author-fixable message — read it, fix the tsxSource via create_component, and re-preview. Idempotent per (componentId, params, dims).',
-        annotations: { idempotentHint: true },
-    },
-    {
-        name: 'commit_session',
-        operationId: 'commitComposeSession',
-        pathArgs: { projectId: 'id', sessionId: 'sessionId' },
-        description: "Promote this run's scratch composition to the project's active composition. DENIED to ensemble author/designer candidates (only the WINNER saves downstream); buildable only via an explicit allowedNames.",
-    },
-    {
-        // ADAPTER-ONLY (brand-kit-from-inspiration, spec D9: the public MCP gains NO
-        // new tools). The director's author/designer loops reach it via allowedNames
-        // + `opts.brandKitId` (the director injects the bound kit); a public hosted
-        // caller has no way to name a kit, so the {id} path param would resolve to
-        // String(undefined) → POST /v1/brand-kits/undefined/exemplars → always 404.
-        // Living here (not in CURATED_TOOLS) keeps it OFF the public server —
-        // server.ts:registerCuratedTools iterates CURATED_TOOLS only — while
-        // buildCuratedToolSet iterates INTERNAL_LOOP_TOOLS + CURATED_TOOLS, so the
-        // designer/author allow-lists still build it. The kit id comes from
-        // opts.brandKitId, never the LLM, so it has no path/query args here.
-        name: 'view_style_reference',
-        operationId: 'getBrandKitExemplars',
-        description: 'SEE the brand kit\'s inspiration exemplar frames (the reference pixels). ' +
-            'Call with {motifId} to see the frames a specific motif was observed in ' +
-            'before authoring that graphic. Frames are the ground truth the judge ' +
-            'grades against — match their language, not the house style.',
-    },
-    // ── One-vocabulary merge (2026-08-07) ───────────────────────────────────
-    // `get_context`, `search_library` and `analyze_transcript` are the names the
-    // DESKTOP agent already speaks; the /v1 twins landed in tasks 2-4 so one tool
-    // vocabulary can serve local and cloud through one Executor seam. They live
-    // HERE, not in CURATED_TOOLS, on purpose: server.ts:registerCuratedTools
-    // iterates CURATED_TOOLS procedurally, so membership there IS publication on
-    // the hosted MCP server. These three are internal-lane only until the desktop
-    // merge lands and the surface is deliberately widened. `buildCuratedToolSet`
-    // iterates INTERNAL_LOOP_TOOLS + CURATED_TOOLS (adapter.ts), so the editor
-    // agent and the Director build them without server.ts changing at all.
-    {
-        name: 'get_context',
-        operationId: 'getProjectContext',
-        pathArgs: { projectId: 'id' },
-        description: "OPEN THE PROJECT in one read: the active composition (format + markers hoisted), the org's media pool with a `hasTranscript` flag per item, the first transcribed item's word-timed transcript, and the brand kit bound to the project. Call it FIRST — it replaces the get_composition + get_media_context + get_profile opening sequence, so the whole orientation costs one round-trip. `composition: null` is the EMPTY STATE of a freshly created project, not an error (mint one with new_composition); 404 means no such project for your org. Transcript BODIES are not inlined per media item — for a second item read GET /v1/media/{id}/transcript, and its faces/beat grids with get_media_context.",
-        annotations: { readOnlyHint: true },
-    },
-    {
-        name: 'search_library',
-        operationId: 'searchLibrary',
-        // The op takes NO path params and NO body — `q`/`limit` are QUERY params,
-        // and `queryArgs` is the only mechanism that puts them on the wire (the raw
-        // registrar drops query params entirely, which is why its raw twin is
-        // excluded in server.ts). Without this block the tool would call
-        // GET /v1/media/search with no `q` and 400 on every invocation.
-        queryArgs: {
-            q: 'REQUIRED. What the moment should LOOK like, in plain language — describe the IMAGE, not the words spoken ("wide shot of a speaker at a whiteboard", "hands on a keyboard"). Omitting it is a 400.',
-            limit: 'Maximum moments to return. Default 10, maximum 25.',
-        },
-        description: 'FIND MOMENTS IN YOUR OWN FOOTAGE by describing what they look like. The query is embedded with the same CLIP model that embedded every indexed frame, so it matches on VISUAL content — including shots nobody talks about, which is exactly where transcript search fails. Returns time-ranged moments best-first: feed `mediaId` + `startSec`/`endSec` straight into apply_composition as a clip. To SEE a hit rather than trust its score, place it and call preview_frame at its `startSec` — a result row carries the media item\'s poster, never a frame of the matched moment. `indexing` is COVERAGE, not emptiness — true whenever some of the org\'s footage is not in the visual index yet (media that predates it, or still processing), and it can be true ALONGSIDE results; read those as "the best moments among what we have looked at so far". Empty `results` with `indexing: true` is a state, not a failure. TIMING: the text encoder scales to zero, so the first search after an idle period can take up to ~90s while it cold-starts — a documented wait, not a hang. Reach for search_resources instead when you need STOCK rather than the org\'s own footage.',
-        annotations: { readOnlyHint: true },
-        // NO `preview` block, deliberately. `thumbUrl` is the ITEM's poster frame
-        // (schemas.ts: "the media item's poster"), not the matched moment's — and a
-        // result row is a CHUNK, so a 10-hit search over ONE video inlines the same
-        // unrelated poster ten times, uncaptioned. That is the confabulation class
-        // previews exist to fix, running backwards: the agent would judge moments
-        // against a frame none of them contains. The right eye on a hit is
-        // preview_frame at its startSec, which the description points at.
-    },
-    {
-        name: 'analyze_transcript',
-        operationId: 'analyzeTranscript',
-        pathArgs: { mediaItemId: 'id' },
-        description: "Ask ONE editorial question of a media item's transcript and get the answer as text. `body.task`: 'summary' (what is actually said, plus the takeaways), 'chapters' (where the subject changes), or 'highlights' (the moments that stand alone as a short). Pass `body.window` {startSec, endSec} to analyse one slice; omit it for the whole thing. PRECISION — READ THIS BEFORE YOU CUT: timestamps are ABSOLUTE seconds from the start of the media and every one is verified against the transcript before you see it (a fabricated timestamp fails the call rather than shipping), but they are LINE-START markers roughly 15s apart, so a boundary can sit up to 15s BEFORE the moment you asked for. Treat every span as APPROXIMATE — use it to LOCATE the moment, then refine the in/out against the word timings from get_context / get_media_context. Feeding a raw span straight into a clip trim WILL start it mid-sentence. This is a METERED LLM call, not a read: it bills on measured token spend. 422 `transcript_too_long` (over ~100k characters, roughly two hours of speech) means narrow it with `window` — it refuses rather than silently summarising only the first half; 422 `media_no_transcript` means no speech on file (or none inside your window) — get_media_context shows the transcript state.",
-    },
-    // `wait_job` is the ONE infrastructure verb on the adapter surface. The hosted
-    // MCP server registers its own copy procedurally (server.ts:registerWaitJob),
-    // so it must NEVER appear in CURATED_TOOLS — registerCuratedTools would then
-    // register the name twice and the whole server would fail to build. It lives
-    // here so `buildCuratedToolSet` can build it too: without it an allow-list
-    // carrying an ASYNC verb (create_render, score_composition, generate_media)
-    // hands the agent a receipt it can never resolve — the 2026-07-07 prod run
-    // that scored into the void. `operationId` is the representative status op;
-    // buildWaitJobTool resolves the real one PER KIND (wait.ts KINDS).
-    {
-        name: 'wait_job',
-        operationId: 'getJob',
-        title: 'Wait for Job',
-        description: 'Wait for a long-running job and return the resolved result — a BOUNDED long-poll. Polls the job status (render / compose / consult / clip-suggestions / verify / preview / brand-kit extract) and blocks up to the caller\'s window; if the job is still running when the window closes it returns a `Still running` continuation — call wait_job again with the SAME arguments to keep waiting (the job keeps executing server-side; nothing is lost between calls). Call this right after create_render / compose / consult / suggest_briefs / score_composition / preview_component — the enqueue call returns only a receipt, and the RESULT (download URL, scores, critique) arrives here.',
-        annotations: { readOnlyHint: true },
-    },
-];

package/dist/_members/mcp/prompts.js

@@ -1,45 +0,0 @@
-import { opById, buildPath, isOk, apiErrorFrom } from './core.js';
-// INVARIANT: this module-global cache is shared across ALL hosted requests/tenants
-// and is keyed on NOTHING. It is safe ONLY because GET /v1/skills is public and
-// tenant-independent (build-time static skill metadata, mounted before auth). If
-// skills ever become org-scoped / entitlement-filtered, this MUST move to a
-// per-request fetch (or be keyed by orgId) — otherwise one tenant's list leaks.
-let skillListCache = null;
-async function fetchSkillList(ex) {
-    if (skillListCache)
-        return skillListCache;
-    const op = opById('listSkills');
-    const res = await ex.invoke({ method: 'GET', path: buildPath(op, () => '') });
-    if (!isOk(res.status))
-        throw apiErrorFrom(res);
-    const parsed = JSON.parse(res.text);
-    skillListCache = parsed.skills ?? [];
-    return skillListCache;
-}
-export async function registerSkillPrompts(server, ex, opts = {}) {
-    let list;
-    try {
-        list = await fetchSkillList(ex);
-    }
-    catch (err) {
-        if (opts.failLoud)
-            throw err;
-        return; // best-effort on hosted — never break a tool call over skill prompts
-    }
-    const getSkillOp = opById('getSkill');
-    for (const s of list) {
-        server.registerPrompt(s.name, { title: s.title, description: s.description }, async () => {
-            const res = await ex.invoke({
-                method: 'GET',
-                path: buildPath(getSkillOp, () => s.name),
-            });
-            if (!isOk(res.status))
-                throw apiErrorFrom(res);
-            return { messages: [{ role: 'user', content: { type: 'text', text: res.text } }] };
-        });
-    }
-}
-/** Test seam — reset the memoized skill list. */
-export function __resetSkillCache() {
-    skillListCache = null;
-}