@cueframe/kernel 0.2.23 → 0.2.24

package/dist/{chunk-RGKDDR7H.js → chunk-PNJ7DACK.js}

@@ -20,8 +20,13 @@ var ApiError = class extends Error {
 
 // ../sdk/src/errors.ts
 var ERROR_ADVICE = {
-  unauthorized: "The API key is invalid or expired for this target. Run `cueframe login` (or `cueframe auth <api-key>`), and check the key matches the target environment.",
-  forbidden: "The key's scopes don't allow this operation. Create a key with the needed preset (`cueframe keys create --preset ...`) or use a key with wider scopes.",
+  // These two are read by MCP agents as often as by CLI users (`fmtErr` in
+  // @cueframe/mcp appends them verbatim), so they name the remedy, not one
+  // transport's spelling of it — a CLI command handed to an agent that has no
+  // shell is a dead end, and routing an MCP caller back to the CLI contradicts
+  // the MCP-first surface (CUE-15 P0).
+  unauthorized: "The credential is invalid or expired for this target, or it belongs to a different environment. Re-authenticate the way you connected: reconnect the MCP server, run `cueframe login` in a terminal, or supply a current API key.",
+  forbidden: "The credential's permissions don't cover this operation. The server message above names the exact missing ones and the `permissions` body that grants them; a key's permissions are fixed at creation, so this needs a NEW key, not a change to this one.",
   not_found: "No such resource in this org (cross-org access also reads as 404). Check the id, or enumerate with the matching list command/tool.",
   media_not_ready: "Media is still processing. Wait for the `media.transcribed` webhook or retry after ~30s.",
   suggestions_already_complete: "Suggestions already exist for this media item. To re-run, call DELETE /v1/media/:id/suggestions first to reset state.",
@@ -6032,7 +6037,7 @@ var CompositionOp = zod66.union([zod66.strictObject({
   "scene": SceneShotSpecV2,
   "assets": zod66.record(zod66.string(), zod66.string()),
   "transitionIn": TransitionSpec.optional()
-}), zod66.strictObject({
+}).describe('Author a scene shot and place it on a dedicated overlay track. The host validates the scene, generates and registers an immutable wrapper component source, and emits the ordinary track/clip operations carrying `props.componentRef` \u2014 you edit a scene SPEC, never wrapper TSX or a source hash. Registration and the composition update are ONE undoable edit; a failure publishes nothing and leaves no clip pointing at an unresolved source. Pass EXACTLY ONE of `trackId` (an existing dedicated scene track) or `newTrack: true` (mint one). That track holds scene-shot clips and gaps only \u2014 no generic component/primitive/media clips in v1 \u2014 and existing generic overlay tracks are unaffected. Scene clips use front zPlane and full-frame placement: outer per-clip `region`, `position`, `scale`, `rotation`, `fit`, `effects`, `animate`, `params.transition`, `params.sequenceGroup` and internal fadeIn/fadeOut are REFUSED with a path, because the shot\'s own layer transforms are the single transform owner. TEXT: `space: "screen"` text is composed above the world result, stays fixed in the frame and stays sharp through focus; `space: "world"` text is rasterized into the 3D scene, moves with the camera and is occluded by geometry. Screenshots and world text are UNLIT and colour-managed so product UI colours are not tinted by the studio lighting, while device bodies are lit and cast shadows; an unlit surface still occludes. SCOPE GAP (pre-existing, neither closed nor changed by scene shots): global wrap effects \u2014 composition-level grades and camera effects \u2014 do not reach front-overlay clips, so they do not affect a scene shot. Author the look INSIDE the shot (`post.grain`, `post.vignette`, `post.focus`, `backdrop`, `environment`) instead. DISCOVERY: there is no built-in scene primitive to look up in list_catalog; the wrapper this operation registers appears afterwards as an ordinary INSTALLED component under the existing catalog rules.'), zod66.strictObject({
   "type": zod66.literal("scene.update"),
   "clipId": zod66.string(),
   "startTime": zod66.number().min(compositionOpTwoStartTimeMin).optional(),
@@ -6040,7 +6045,7 @@ var CompositionOp = zod66.union([zod66.strictObject({
   "scene": SceneShotSpecV2.optional(),
   "assets": zod66.record(zod66.string(), zod66.string()).optional(),
   "transitionIn": TransitionSpec.optional()
-}), zod66.strictObject({
+}).describe("Revise a scene shot in place by clip id. Send a replacement `scene` and/or `assets`; timing changes use the ordinary clip timing fields (`startTime`, `duration`, `transitionIn`). Omitted fields keep their persisted values and the MERGED result is re-validated as a whole, so a partial edit cannot leave the shot invalid. Changing only values or asset IDs updates props and bindings and REUSES the pinned source; changing the referenced SLOT SET regenerates the wrapper manifest and registers a new immutable source version atomically. Undo restores the source reference, spec, bindings and timing together. Topology, asset bindings, text content, font properties, device kind and colours are STATIC within a shot's animation \u2014 change them here (a revised spec) rather than trying to animate them. This is not a source trim or slip: a shortened or extended clip resamples the SAME normalized animation over its new duration, and trim/slip requests on generated animation are rejected rather than reinterpreted as media trims. In one batch, `scene.update` may target a shot added by an earlier `scene.add`."), zod66.strictObject({
   "type": zod66.literal("clip.add"),
   "clip": zod66.strictObject({
     "id": zod66.string().min(1),
@@ -6695,7 +6700,7 @@ var CompositionOp = zod66.union([zod66.strictObject({
   "type": zod66.literal("removeExcludedRange"),
   "clipId": zod66.string(),
   "rangeIdx": zod66.number()
-}).describe("Server-authoritative: remove a clip's previously-added excluded range by index (re-includes that span, ripples downstream).")]).describe("One scoped composition operation. Discriminated by `type` \u2014 `clip.add` / `clip.remove` / `clip.update` patch clips across any family; the rest cover markers, reframe, effects, captions, format, tracks, and the server-authoritative ripple recomputes. Validated strictly server-side against the runtime CompositionOp vocabulary.");
+}).describe("Server-authoritative: remove a clip's previously-added excluded range by index (re-includes that span, ripples downstream).")]).describe("One scoped composition operation. Discriminated by `type` \u2014 `clip.add` / `clip.remove` / `clip.update` patch clips across any family; the rest cover markers, reframe, effects, captions, format, tracks, and the server-authoritative ripple recomputes. Every variant is `.strict()`: an unknown field is refused, not ignored.");
 
 // ../sdk/src/generated/zod/models/compositionApplyRequest.zod.ts
 var CompositionApplyRequest = zod67.strictObject({
@@ -9201,35 +9206,35 @@ var CreateWorkspaceResponse = zod235.object({
 
 // ../mcp/src/generated/operations.ts
 var GENERATED_OPERATIONS = [
-  { operationId: "analyzeTimeline", toolName: "cueframe_api_analyzeTimeline", title: "Analyze Timeline", method: "POST", pathTemplate: "/v1/timeline-analysis", pathParams: [], queryParams: [], bodyKey: "analyzeTimelineBody", description: "Analyze a timeline transcript for edit decisions \u2014 Returns filler, silence-gap, and emphasis word indices for an editor timeline. Analysis settings are selected server-side and cannot be overridden. \u2014 Advanced (expert layer) \u2014 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: "analyzeTranscript", toolName: "cueframe_api_analyzeTranscript", title: "Analyze Transcript", method: "POST", pathTemplate: "/v1/media/{id}/transcript/analyze", pathParams: ["id"], queryParams: [], bodyKey: "analyzeTranscriptBody", description: "Analyse a media item's transcript \u2014 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) \u2014 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 \u2014 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. \u2014 Advanced (expert layer) \u2014 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: "analyzeTimeline", toolName: "cueframe_api_analyzeTimeline", title: "Analyze Timeline", method: "POST", pathTemplate: "/v1/timeline-analysis", pathParams: [], queryParams: [], bodyKey: "analyzeTimelineBody", description: "Analyze a timeline transcript for edit decisions \u2014 Returns filler, silence-gap, and emphasis word indices for an editor timeline. Analysis settings are selected server-side and cannot be overridden. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "fillers": { "type": "array" }, "silenceGaps": { "type": "array" }, "emphasis": { "type": "array" } }, "additionalProperties": true } },
+  { operationId: "analyzeTranscript", toolName: "cueframe_api_analyzeTranscript", title: "Analyze Transcript", method: "POST", pathTemplate: "/v1/media/{id}/transcript/analyze", pathParams: ["id"], queryParams: [], bodyKey: "analyzeTranscriptBody", description: "Analyse a media item's transcript \u2014 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) \u2014 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 \u2014 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. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "task": { "type": "string", "description": "Echo of the requested task \u2014 so a batched caller can pair answers to asks.", "enum": ["summary", "chapters", "highlights"] }, "result": { "type": "string", "description": "The answer, as text. `summary` is prose; `chapters` and `highlights` are one record per LINE in the shape documented on the request's `task` field \u2014 split on newlines to parse them. Timestamps are absolute seconds from the start of the media and every one is CHECKED against the transcript before the response is returned (a fabricated timestamp fails the call rather than shipping), but they are line-start markers about 15s apart \u2014 a boundary can sit up to 15s BEFORE the moment you want. Use them to locate, not to cut: refine against the word timings in GET /v1/media/{id}/context." } }, "additionalProperties": true } },
   { operationId: "applyComposition", toolName: "cueframe_api_applyComposition", title: "Apply Composition", method: "POST", pathTemplate: "/v1/projects/{id}/composition/apply", pathParams: ["id"], queryParams: [], bodyKey: "applyCompositionBody", description: "Apply a batch of operations to a project's composition (or dry-run validate) \u2014 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 \u2014 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[]` \u2014 non-fatal authoring advisories (e.g. a card whose html reads a CSS custom property no token defines). Warnings never block. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "applyCompositionOpBody", description: "Apply one operation to a project's composition \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Cancel an in-flight compose job \u2014 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. Cancellation is confirmed before the job becomes terminal; the compose.cancelled event is then emitted and any linked charge is released. Already-terminal jobs are rejected (422 compose_not_cancellable). \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Cancel an in-flight export \u2014 Required permission: renders:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Cancel an async job \u2014 Cancel a running async job so an agent can abort a mis-priced/runaway operation without waiting out its TTL. Cancellation is durable and never meters. Already-terminal jobs are rejected (422 job_not_cancellable). \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Cancel a render \u2014 Required permission: renders:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Close a compose session \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Commit the session scratch onto the project's active composition \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "composeBody", description: "Start an async Director compose workflow \u2014 Async sibling of `composeFromSuggestion`. The Director execution authors a canonical wire-shape Composition and saves it as the project's active composition. Watch progress via the SSE stream at `/v1/projects/:id/compose/:composeJobId/stream`. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Cancel an in-flight compose job \u2014 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. Cancellation is confirmed before the job becomes terminal; the compose.cancelled event is then emitted and any linked charge is released. Already-terminal jobs are rejected (422 compose_not_cancellable). \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "composeJobId": { "type": "string" }, "projectId": { "type": "string" }, "status": { "type": "string", "enum": ["queued", "running", "awaiting_input", "complete", "failed", "cancelled"] }, "error": { "type": "string" }, "request": { "type": "object" }, "candidates": { "type": "array" }, "winner": {}, "listUsd": { "type": "number" }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" }, "advisoryResult": { "type": "object", "description": "The advisory envelope returned by a completed consult job (on ComposeJobDetailResponse.advisoryResult)." }, "checkpoint": { "type": "object" } }, "additionalProperties": true } },
+  { operationId: "cancelExport", toolName: "cueframe_api_cancelExport", title: "Cancel Export", method: "POST", pathTemplate: "/v1/projects/{id}/exports/{exportId}/cancel", pathParams: ["id", "exportId"], queryParams: [], bodyKey: null, description: "Cancel an in-flight export \u2014 Required permission: renders:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "format": { "type": "string", "enum": ["fcpxml", "premiere"] }, "status": { "type": "string", "enum": ["queued", "trimming", "building", "uploading", "complete", "error", "cancelled"] }, "progress": { "type": "number", "description": "Fractional progress 0..1 across the trim/build/upload pipeline. Reaches 1 only on `complete`." }, "outputUrl": { "type": "string" }, "outputExpiresAt": { "type": "string" }, "outputSizeBytes": { "type": "number" }, "outputDurationSec": { "type": "number" }, "error": { "description": "Set when status is `error`; null otherwise. The phase field localizes the failure to trim / build / upload / trigger." }, "trimCacheHit": { "type": "boolean" }, "clipSuggestionId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "cancelJob", toolName: "cueframe_api_cancelJob", title: "Cancel Job", method: "POST", pathTemplate: "/v1/jobs/{jobId}/cancel", pathParams: ["jobId"], queryParams: [], bodyKey: null, description: "Cancel an async job \u2014 Cancel a running async job so an agent can abort a mis-priced/runaway operation without waiting out its TTL. Cancellation is durable and never meters. Already-terminal jobs are rejected (422 job_not_cancellable). \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string", "description": "Job id \u2014 pass to GET /v1/jobs/{id} / wait_job." }, "jobKey": { "type": "string", "description": "Deterministic identity of the work (idempotency key, e.g. `verify-<sessionId>-<contentHash>` \u2014 the hash covers the composition AND grading inputs). Re-enqueueing the same key returns the same job while it runs." }, "kind": { "type": "string", "description": "Job family, e.g. `verify`." }, "status": { "type": "string", "description": "Poll until terminal (`succeeded` | `failed` | `cancelled`).", "enum": ["running", "succeeded", "failed", "cancelled"] }, "progress": { "description": "Executor heartbeat while running; null when none reported." }, "result": { "description": "Kind-specific payload when status is `succeeded`; null otherwise." }, "error": { "description": "Stable failure code + human message when status is `failed`; null otherwise. `job_timeout` = the executor died mid-run and the stall sweep reaped the job \u2014 re-enqueue to retry." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "completedAt": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "cancelRender", toolName: "cueframe_api_cancelRender", title: "Cancel Render", method: "POST", pathTemplate: "/v1/projects/{id}/renders/{renderId}/cancel", pathParams: ["id", "renderId"], queryParams: [], bodyKey: null, description: "Cancel a render \u2014 Required permission: renders:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["queued", "pending", "rendering", "complete", "error", "cancelled"] }, "progress": { "type": "object", "description": "Non-terminal render progress; phase is one of the worker's emitted stages." }, "outputUrl": { "type": "string" }, "outputExpiresAt": { "type": "string" }, "error": { "type": "string", "description": "Human-readable failure message. Pair with `errorCode` for a stable, machine-readable code an agent runner can branch on." }, "errorCode": { "type": "string", "description": "Stable, machine-readable error code (e.g. `render_pipeline_unavailable`, `render_route_missing`, `render_pipeline_failed`). Null when status is not `error` or unavailable for an older render." }, "errorDetails": { "description": "Structured failure context \u2014 `{ targetUrl?, upstreamStatus?, upstreamCode?, attemptedAt? }`. Surfaced so agent runners can distinguish operator-config issues from upstream-down vs route-missing without parsing `error`." }, "category": { "description": "Failure taxonomy when status is `error`; null otherwise. `authoring` = deterministic defect in YOUR composition/request \u2014 fix it, retrying is futile; `transient` = temporary pipeline/infra failure \u2014 safe to retry_render; `internal` = unexpected server fault \u2014 retry once then escalate. Mirrors the render.failed webhook's `category`." }, "retryable": { "type": "boolean", "description": "Whether re-attempting the SAME render can succeed (status `error`); null otherwise. true \u2192 call retry_render. false \u2192 deterministic (category authoring/internal); fix the composition first \u2014 retry_render alone reproduces it. Mirrors the render.failed webhook's `retryable`." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the render's most recent progress update. Compute staleness = now \u2212 updatedAt to distinguish a wedged render from a slow one and decide whether to wait, cancel, or retry." }, "listUsd": { "type": "number", "description": "A2 money stamp: the metered event's LIST price (USD), stamped at the success terminal (exports for deliverable renders, compose_capture for A8 previews). A plan allowance may zero the actual invoice line \u2014 this is the list price, never a Stripe charge. Absent while running, on failure, and for x402 orgs (on-chain receipts). Mirrors the get_usage ledger." }, "warnings": { "type": "array", "description": "Non-fatal advisories surfaced at render-CREATE (omitted when none, and on GET \u2014 create-time only)." } }, "additionalProperties": true } },
+  { operationId: "closeComposeSession", toolName: "cueframe_api_closeComposeSession", title: "Close Compose Session", method: "DELETE", pathTemplate: "/v1/projects/{id}/compose-session/{sessionId}", pathParams: ["id", "sessionId"], queryParams: [], bodyKey: null, description: "Close a compose session \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true } },
+  { operationId: "commitComposeSession", toolName: "cueframe_api_commitComposeSession", title: "Commit Compose Session", method: "POST", pathTemplate: "/v1/projects/{id}/compose-session/{sessionId}/commit", pathParams: ["id", "sessionId"], queryParams: [], bodyKey: null, description: "Commit the session scratch onto the project's active composition \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "etag": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "compose", toolName: "cueframe_api_compose", title: "Compose", method: "POST", pathTemplate: "/v1/projects/{id}/compose", pathParams: ["id"], queryParams: [], bodyKey: "composeBody", description: "Start an async Director compose workflow \u2014 Async sibling of `composeFromSuggestion`. The Director execution authors a canonical wire-shape Composition and saves it as the project's active composition. Watch progress via the SSE stream at `/v1/projects/:id/compose/:composeJobId/stream`. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "composeJobId": { "type": "string", "description": "Opaque compose job id; pass to the SSE stream URL." }, "projectId": { "type": "string" }, "status": { "type": "string", "description": "queued = normal; failed = startup failed and the job is already terminal (the SSE stream will emit a single `job_failed` frame and close).", "enum": ["queued", "failed"] }, "streamUrl": { "type": "string", "description": "Relative SSE endpoint to stream this job's events (per compose-api-contract.md)." } }, "additionalProperties": true } },
   { operationId: "composeFromSuggestion", toolName: "cueframe_api_composeFromSuggestion", title: "Compose From Suggestion", method: "POST", pathTemplate: "/v1/projects/{id}/composition/from-suggestion", pathParams: ["id"], queryParams: [], bodyKey: "composeFromSuggestionBody", description: "Build and persist a composition from a clip suggestion \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "consultBody", description: "Ask the multi-agent Director for editing advice (never writes) \u2014 Ask the Director for editing advice on the project's current composition \u2014 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 \u2014 no grounded scores; 'amend' = the full author\u2192judge\u2192refine loop (minutes) returns a GRADED assessment + an adoptable fix candidate (adopt via POST /compose/jobs/:jobId/select with its candidateIndex). ('explore' \u2014 a ranked slate of directions \u2014 is coming soon.) \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "createApiKeyBody", description: "Create a scoped API key (session credential only) \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "createBrandKitBody", description: 'Create (or upsert) a brand kit \u2014 Create or upsert a brand kit. Gated on the `brand_kits` boolean entitlement, which the FREE plan grants \u2014 brand-first authoring is deliberately never paywalled \u2014 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 \u2014 its `entitlements.brand_kits.included` tells you up front. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "createBriefBody", description: "Create a brief (the persisted intent the Director composes from) \u2014 Persist the video's intent \u2014 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} \u2014 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. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "createCheckoutBody", description: 'Start a hosted Stripe checkout for a plan/interval \u2014 Body `{ plan, interval }` \u2192 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 \u2014 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`. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "createComponentBody", description: "Author (create) a component \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "createCriticBody", description: "Register a compose critic \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "createExemplarUploadsBody", description: "Reserve presigned PUT slots for inspiration exemplar frames \u2014 Returns presigned PUT URLs under this org's `brand-inspiration/\u2026` prefix \u2014 the only namespace the brand-kit upsert accepts `exemplarKeys` from. PUT each curated reference frame (\u2264720px jpeg recommended \u2014 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). \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "createFcpxmlExportBody", description: "Create a Final Cut Pro export \u2014 Export the project as a Final Cut Pro XML (FCPXML) timeline \u2014 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. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "createMediaUploadBody", description: "Initiate a direct upload (presigned PUT URL) \u2014 Required permission: media:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "createPremiereExportBody", description: "Create a Premiere Pro export \u2014 Export the project to Adobe Premiere Pro \u2014 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. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "createProjectBody", description: "Create a project \u2014 Create a video project \u2014 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). \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "createRenderBody", description: "Create a render job \u2014 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. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "createSessionBody", description: "Create a session \u2014 Required permission: sessions:write \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "createUploadTokenBody", description: "Mint a short-lived token for the signed upload lane \u2014 Required permission: media:write \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "createWebhookBody", description: 'Register a webhook endpoint \u2014 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 \u2014 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 \u2014 no delete/recreate). Full contract + per-event `data` shapes: GET /webhooks/events. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "createWorkspaceBody", description: "Mint a workspace (project + imported source) in one call \u2014 The one-call editing handle: create a project and import the source video URL into it. Returns { projectId, mediaId } \u2014 the handle a (paying or keyed) agent threads through the compose/render loop. The import is async; poll GET /v1/media/:mediaId for readiness. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "consultBody", description: "Ask the multi-agent Director for editing advice (never writes) \u2014 Ask the Director for editing advice on the project's current composition \u2014 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 \u2014 no grounded scores; 'amend' = the full author\u2192judge\u2192refine loop (minutes) returns a GRADED assessment + an adoptable fix candidate (adopt via POST /compose/jobs/:jobId/select with its candidateIndex). ('explore' \u2014 a ranked slate of directions \u2014 is coming soon.) \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "consultJobId": { "type": "string", "description": "Opaque consult job id; poll it for the advisory result." }, "projectId": { "type": "string" }, "status": { "type": "string", "description": "queued = normal; failed = startup failed and the job is already terminal.", "enum": ["queued", "failed"] }, "streamUrl": { "type": "string", "description": "Relative SSE endpoint to stream this job's events." } }, "additionalProperties": true } },
+  { operationId: "createApiKey", toolName: "cueframe_api_createApiKey", title: "Create Api Key", method: "POST", pathTemplate: "/v1/api-keys", pathParams: [], queryParams: [], bodyKey: "createApiKeyBody", description: "Create a scoped API key (session credential only) \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "key": { "type": "string", "description": "The full secret key (cf_test_\u2026 / cf_live_\u2026). Shown ONCE \u2014 store it now." }, "id": { "type": "string" }, "prefix": { "type": "string" }, "start": { "type": "string", "description": "First chars of the key, for later identification." } }, "additionalProperties": true } },
+  { operationId: "createBrandKit", toolName: "cueframe_api_createBrandKit", title: "Create Brand Kit", method: "POST", pathTemplate: "/v1/brand-kits", pathParams: [], queryParams: [], bodyKey: "createBrandKitBody", description: 'Create (or upsert) a brand kit \u2014 Create or upsert a brand kit. Gated on the `brand_kits` boolean entitlement, which the FREE plan grants \u2014 brand-first authoring is deliberately never paywalled \u2014 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 \u2014 its `entitlements.brand_kits.included` tells you up front. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tagline": { "type": "string" }, "colors": { "type": "object" }, "extraColors": { "type": "array" }, "fonts": { "type": "object" }, "voiceGuidelines": { "type": "string" }, "captions": { "type": "object" }, "motion": { "type": "object" }, "logo": { "type": "object" }, "intro": { "type": "object" }, "outro": { "type": "object" }, "watermark": { "type": "object" }, "spacing": { "type": "object" }, "sizing": { "type": "object" }, "audio": { "type": "object" }, "exemplarKeys": { "type": "array" }, "contactSheetKey": { "type": "string" }, "motifs": { "type": "array" }, "styleRubric": { "type": "string" }, "density": { "type": "object" }, "inspiration": { "type": "object" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "createBrief", toolName: "cueframe_api_createBrief", title: "Create Brief", method: "POST", pathTemplate: "/v1/briefs", pathParams: [], queryParams: [], bodyKey: "createBriefBody", description: "Create a brief (the persisted intent the Director composes from) \u2014 Persist the video's intent \u2014 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} \u2014 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. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "kind": { "type": "string", "description": "authored = create_brief; clip = minted by suggest_briefs from an AI clip suggestion.", "enum": ["authored", "clip"] }, "sourceSuggestionId": { "type": "string", "description": "kind:'clip' provenance \u2014 the suggestion this Brief was minted from." }, "name": { "type": "string" }, "goal": { "type": "string", "description": "What the video must accomplish." }, "audience": { "type": "string" }, "platform": { "type": "string" }, "format": { "type": "object", "description": "Output-format spec per \xA7Format." }, "durationSec": { "type": "number", "description": "Target output duration. HONOR-OR-REFUSE: compose validates it against the beat-source window (\xB11.5s) and refuses a brief it cannot honor." }, "tone": { "type": "string" }, "cta": { "type": "string" }, "locale": { "type": "string", "description": "Output language (BCP-47 tag, e.g. 'es-419'): ALL on-screen copy + captions." }, "hook": { "type": "string" }, "caption": { "type": "string" }, "beats": { "type": "array" }, "mustIncludes": { "type": "array" }, "references": { "type": "array" }, "captions": { "type": "object" }, "motionStyle": { "type": "object" }, "seededGraphics": { "type": "array", "description": "Client-authored graphic clips the Director must carry VERBATIM: seeded into the design loop's base composition as LOCKED clips (never re-authored, never discarded)." }, "exclusions": { "type": "array" }, "gates": { "type": "object" }, "audio": { "type": "object" }, "quote": { "type": "object" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "additionalProperties": true } },
+  { operationId: "createCheckout", toolName: "cueframe_api_createCheckout", title: "Create Checkout", method: "POST", pathTemplate: "/v1/billing/checkout", pathParams: [], queryParams: [], bodyKey: "createCheckoutBody", description: 'Start a hosted Stripe checkout for a plan/interval \u2014 Body `{ plan, interval }` \u2192 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 \u2014 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`. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "url": { "type": "string", "description": "Hosted Stripe checkout URL to open in a browser to complete payment. Always present on success \u2014 an existing saved card is never charged without confirming here." }, "plan": { "type": "string" }, "interval": { "type": "string" }, "productId": { "type": "string", "description": "Resolved billing catalog product id." } }, "additionalProperties": true } },
+  { operationId: "createComponent", toolName: "cueframe_api_createComponent", title: "Create Component", method: "POST", pathTemplate: "/v1/components", pathParams: [], queryParams: [], bodyKey: "createComponentBody", description: "Author (create) a component \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "source": { "type": "string", "description": "'default' = built-in primitive (place by primitiveId); 'installed' = org-authored component (place by componentId).", "enum": ["default", "installed"] }, "category": { "type": "string", "enum": ["text", "effects", "transitions", "layouts", "backgrounds", "ui-blocks", "scenes"] }, "kind": { "type": "string", "description": "RENDER kind (component | transition | scene). NOT the ClipSource variant \u2014 see `placement` for how to author it on the timeline.", "enum": ["component", "transition", "scene"] }, "version": { "type": "string" }, "propSchema": { "type": "object" }, "propDefaults": { "type": "object" }, "textParam": { "type": "string", "description": "The param field that carries this primitive's primary text; null = no single text slot." }, "subtextParam": { "type": "string", "description": "The param field for secondary text (subtitle/byline); null = none." }, "format": { "type": "object" }, "durationInFrames": { "type": "number" }, "intent": { "type": "string", "description": "Selection signal: a verb naming what this primitive accomplishes (e.g. 'product-trailer'). Match it to the beat you are authoring." }, "useWhen": { "type": "string", "description": "When to use this \u2014 AND when not to. The negative guidance is load-bearing; read it before picking." }, "pairsWith": { "type": "array", "description": "Authoring guidance: ids of primitives that COMPOSE well with this one in the same edit." }, "avoidWith": { "type": "array", "description": "Authoring guidance: ids of primitives that CONFLICT with this one \u2014 do not place together." }, "tags": { "type": "array", "description": "Free-text search keywords." }, "mood": { "type": "array", "description": "Vibe/tone tags (e.g. 'cinematic', 'minimal'). Filter to match the edit's mood." }, "tier": { "type": "string", "description": "Quality/applicability RANKING (a preference, not a flag). Prefer 'recommended'; reach for 'niche' only when its specific use-case is exactly the beat.", "enum": ["recommended", "standard", "niche"] }, "useCase": { "type": "array", "description": "The edit ROLE(s) this primitive fills \u2014 the dimension to filter by for a beat (e.g. 'intro', 'title-over-footage', 'grade')." }, "examples": { "type": "array" }, "fixedCopy": { "type": "array", "description": "On-screen strings this primitive BAKES \u2014 the read-side counterpart to propSchema. These literals render REGARDLESS of params (no param can change them); fork the source via get_component_source to edit them. Use this to see at author time what fixed copy (someone-else's marketing text, faux-code, faux-data) will appear before you render." }, "brandBindings": { "type": "array", "description": "Params that can follow the project brand kit. Each {param, brandToken} says: set `param` to `brandToken` (a `$brand:` ref, e.g. '$brand:colors.accent') to track the brand instead of a literal. See the list response's `brandTokens` for the full ref vocabulary. Omitted when nothing is brand-bound." }, "placement": { "type": "object" }, "warnings": { "type": "array", "description": "Non-blocking save-time advisories \u2014 the create/update SUCCEEDED. Currently: a `fontFamily` string literal referencing a NON-vendored font (a bare CSS generic like 'serif', or an unknown named family like 'Arial') whose LIVE-lane pixels vary by render host \u2014 re-author with a vendored family or 'Georgia'. Omitted when there is nothing to flag; only present on the create/update responses." } }, "additionalProperties": true } },
+  { operationId: "createCritic", toolName: "cueframe_api_createCritic", title: "Create Critic", method: "POST", pathTemplate: "/v1/critics", pathParams: [], queryParams: [], bodyKey: "createCriticBody", description: "Register a compose critic \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "criticId": { "type": "string" }, "tier": { "type": "string", "enum": ["rules", "rubric", "evaluator"] }, "secret": { "type": "string", "description": "evaluator tier: Standard-Webhooks signing secret, returned ONCE." } }, "additionalProperties": true } },
+  { operationId: "createExemplarUploads", toolName: "cueframe_api_createExemplarUploads", title: "Create Exemplar Uploads", method: "POST", pathTemplate: "/v1/brand-kits/exemplar-uploads", pathParams: [], queryParams: [], bodyKey: "createExemplarUploadsBody", description: "Reserve presigned PUT slots for inspiration exemplar frames \u2014 Returns presigned PUT URLs under this org's `brand-inspiration/\u2026` prefix \u2014 the only namespace the brand-kit upsert accepts `exemplarKeys` from. PUT each curated reference frame (\u2264720px jpeg recommended \u2014 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). \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "batchId": { "type": "string" }, "uploads": { "type": "array" }, "contactSheetUpload": { "type": "object" }, "expiresAt": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "createFcpxmlExport", toolName: "cueframe_api_createFcpxmlExport", title: "Create Fcpxml Export", method: "POST", pathTemplate: "/v1/projects/{id}/exports/fcpxml", pathParams: ["id"], queryParams: [], bodyKey: "createFcpxmlExportBody", description: "Create a Final Cut Pro export \u2014 Export the project as a Final Cut Pro XML (FCPXML) timeline \u2014 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. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "format": { "type": "string", "enum": ["fcpxml", "premiere"] }, "status": { "type": "string", "enum": ["queued", "trimming", "building", "uploading", "complete", "error", "cancelled"] }, "progress": { "type": "number", "description": "Fractional progress 0..1 across the trim/build/upload pipeline. Reaches 1 only on `complete`." }, "outputUrl": { "type": "string" }, "outputExpiresAt": { "type": "string" }, "outputSizeBytes": { "type": "number" }, "outputDurationSec": { "type": "number" }, "error": { "description": "Set when status is `error`; null otherwise. The phase field localizes the failure to trim / build / upload / trigger." }, "trimCacheHit": { "type": "boolean" }, "clipSuggestionId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "createMediaUpload", toolName: "cueframe_api_createMediaUpload", title: "Create Media Upload", method: "POST", pathTemplate: "/v1/media", pathParams: [], queryParams: [], bodyKey: "createMediaUploadBody", description: "Initiate a direct upload (presigned PUT URL) \u2014 Required permission: media:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "uploadUrl": { "type": "string" }, "expiresAt": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "createPremiereExport", toolName: "cueframe_api_createPremiereExport", title: "Create Premiere Export", method: "POST", pathTemplate: "/v1/projects/{id}/exports/premiere", pathParams: ["id"], queryParams: [], bodyKey: "createPremiereExportBody", description: "Create a Premiere Pro export \u2014 Export the project to Adobe Premiere Pro \u2014 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. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "format": { "type": "string", "enum": ["fcpxml", "premiere"] }, "status": { "type": "string", "enum": ["queued", "trimming", "building", "uploading", "complete", "error", "cancelled"] }, "progress": { "type": "number", "description": "Fractional progress 0..1 across the trim/build/upload pipeline. Reaches 1 only on `complete`." }, "outputUrl": { "type": "string" }, "outputExpiresAt": { "type": "string" }, "outputSizeBytes": { "type": "number" }, "outputDurationSec": { "type": "number" }, "error": { "description": "Set when status is `error`; null otherwise. The phase field localizes the failure to trim / build / upload / trigger." }, "trimCacheHit": { "type": "boolean" }, "clipSuggestionId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "createProject", toolName: "cueframe_api_createProject", title: "Create Project", method: "POST", pathTemplate: "/v1/projects", pathParams: [], queryParams: [], bodyKey: "createProjectBody", description: "Create a project \u2014 Create a video project \u2014 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). \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "format": {}, "brandKitId": { "type": "string" }, "activeCompositionId": { "type": "string" }, "composition": { "type": "object", "description": "Summary of a project's stored composition." }, "lastRender": { "description": "Most recent render for a project, if any." }, "webUrl": { "type": "string", "description": "A browser URL that opens THIS project, or null when CueFrame exposes no web view for a project. Null today: the console serves account surfaces (keys, usage, billing) and has no per-project page, so there is no link to give. Do NOT synthesise one \u2014 a guessed console path 404s. Show the user rendered output (create_render \u2192 outputUrl) or a preview still instead. This field becoming non-null is the signal that a real project view exists." }, "createdAt": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "createRender", toolName: "cueframe_api_createRender", title: "Create Render", method: "POST", pathTemplate: "/v1/projects/{id}/renders", pathParams: ["id"], queryParams: [], bodyKey: "createRenderBody", description: "Create a render job \u2014 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. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["queued", "pending", "rendering", "complete", "error", "cancelled"] }, "progress": { "type": "object", "description": "Non-terminal render progress; phase is one of the worker's emitted stages." }, "outputUrl": { "type": "string" }, "outputExpiresAt": { "type": "string" }, "error": { "type": "string", "description": "Human-readable failure message. Pair with `errorCode` for a stable, machine-readable code an agent runner can branch on." }, "errorCode": { "type": "string", "description": "Stable, machine-readable error code (e.g. `render_pipeline_unavailable`, `render_route_missing`, `render_pipeline_failed`). Null when status is not `error` or unavailable for an older render." }, "errorDetails": { "description": "Structured failure context \u2014 `{ targetUrl?, upstreamStatus?, upstreamCode?, attemptedAt? }`. Surfaced so agent runners can distinguish operator-config issues from upstream-down vs route-missing without parsing `error`." }, "category": { "description": "Failure taxonomy when status is `error`; null otherwise. `authoring` = deterministic defect in YOUR composition/request \u2014 fix it, retrying is futile; `transient` = temporary pipeline/infra failure \u2014 safe to retry_render; `internal` = unexpected server fault \u2014 retry once then escalate. Mirrors the render.failed webhook's `category`." }, "retryable": { "type": "boolean", "description": "Whether re-attempting the SAME render can succeed (status `error`); null otherwise. true \u2192 call retry_render. false \u2192 deterministic (category authoring/internal); fix the composition first \u2014 retry_render alone reproduces it. Mirrors the render.failed webhook's `retryable`." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the render's most recent progress update. Compute staleness = now \u2212 updatedAt to distinguish a wedged render from a slow one and decide whether to wait, cancel, or retry." }, "listUsd": { "type": "number", "description": "A2 money stamp: the metered event's LIST price (USD), stamped at the success terminal (exports for deliverable renders, compose_capture for A8 previews). A plan allowance may zero the actual invoice line \u2014 this is the list price, never a Stripe charge. Absent while running, on failure, and for x402 orgs (on-chain receipts). Mirrors the get_usage ledger." }, "warnings": { "type": "array", "description": "Non-fatal advisories surfaced at render-CREATE (omitted when none, and on GET \u2014 create-time only)." } }, "additionalProperties": true } },
+  { operationId: "createSession", toolName: "cueframe_api_createSession", title: "Create Session", method: "POST", pathTemplate: "/v1/sessions", pathParams: [], queryParams: [], bodyKey: "createSessionBody", description: "Create a session \u2014 Required permission: sessions:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "files": { "type": "array" }, "mux": { "type": "object" }, "createdAt": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "createUploadToken", toolName: "cueframe_api_createUploadToken", title: "Create Upload Token", method: "POST", pathTemplate: "/v1/uploads/token", pathParams: [], queryParams: [], bodyKey: "createUploadTokenBody", description: "Mint a short-lived token for the signed upload lane \u2014 Required permission: media:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "token": { "type": "string" }, "expiresAt": { "type": "integer", "description": "Expiry, ms since epoch (~30 min TTL)." } }, "additionalProperties": true } },
+  { operationId: "createWebhook", toolName: "cueframe_api_createWebhook", title: "Create Webhook", method: "POST", pathTemplate: "/v1/webhooks", pathParams: [], queryParams: [], bodyKey: "createWebhookBody", description: 'Register a webhook endpoint \u2014 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 \u2014 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 \u2014 no delete/recreate). Full contract + per-event `data` shapes: GET /webhooks/events. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array" }, "settleMs": { "type": "integer" }, "enabled": { "type": "boolean" }, "status": { "type": "string", "description": "active = ownership verified + receiving events; pending = challenge not echoed, inactive.", "enum": ["active", "pending"] }, "secret": { "type": "string", "description": "Standard Webhooks signing secret, format `whsec_<base64>`. Returned ONCE at create; rotate = delete + recreate. Every delivery carries `webhook-id`, `webhook-timestamp` (unix seconds), and `webhook-signature: v1,<base64>` (HMAC-SHA256 over `{id}.{timestamp}.{rawBody}`). Verify with any Standard-Webhooks library (`standardwebhooks` / `svix`): `new Webhook(secret).verify(rawBody, headers)`." }, "verification": { "type": "object", "description": 'Present ONLY when ownership verification did not complete (status:"pending"). CueFrame POSTs a signed `webhook.verify` challenge whose `data.token` your endpoint must echo in a 2xx to activate; `reason` is one of token_not_echoed | non_2xx_<code> | unreachable | ssrf_blocked. A pending webhook receives no events \u2014 fix the receiver and POST /webhooks/:id/verify (no delete/recreate needed). See GET /webhooks/events for the full contract.' } }, "additionalProperties": true } },
+  { operationId: "createWorkspace", toolName: "cueframe_api_createWorkspace", title: "Create Workspace", method: "POST", pathTemplate: "/v1/workspace", pathParams: [], queryParams: [], bodyKey: "createWorkspaceBody", description: "Mint a workspace (project + imported source) in one call \u2014 The one-call editing handle: create a project and import the source video URL into it. Returns { projectId, mediaId } \u2014 the handle a (paying or keyed) agent threads through the compose/render loop. The import is async; poll GET /v1/media/:mediaId for readiness. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "projectId": { "type": "string" }, "mediaId": { "type": "string" } }, "additionalProperties": true } },
   { operationId: "deleteBrief", toolName: "cueframe_api_deleteBrief", title: "Delete Brief", method: "DELETE", pathTemplate: "/v1/briefs/{id}", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Delete a brief \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Delete a composition \u2014 Delete a composition and its version history. REFUSES the project's ACTIVE composition (409 composition_active) \u2014 make another one active first, or delete the project. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Delete a registered critic \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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 } },
@@ -9237,90 +9242,90 @@ var GENERATED_OPERATIONS = [
   { operationId: "deleteProject", toolName: "cueframe_api_deleteProject", title: "Delete Project", method: "DELETE", pathTemplate: "/v1/projects/{id}", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Delete a project \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Delete a session \u2014 Required permission: sessions:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Delete a webhook endpoint \u2014 Required permission: webhooks:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "deriveCompositionBody", description: "Derive a reframed sibling composition for a new aspect (multi-format) \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "extractBrandKitBody", description: "Extract brand tokens from a website URL \u2014 Queue brand-token extraction from a website URL \u2014 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 service inspects the site under a 20-second limit and does NOT persist a kit (pass the result to POST /brand-kits). A blocked (private-network), 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. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "finalizeMediaBody", description: "Finalize a direct upload (trigger processing after the bytes are PUT) \u2014 Required permission: media:write \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "generateMediaBody", description: "Generate media with AI (video, image, or Manim animation) \u2014 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 \u2014 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). \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: null, description: "Return the caller's account: identity, plan, entitlements, cost ceilings \u2014 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 \u2014 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`. Generation is also bounded by the disclosed generationLimit for accounts that have not purchased credits; `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. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: null, description: "List the plan catalog: tiers, intervals, product ids, prices \u2014 Returns every purchasable {tier, interval} and its billing catalog product id \u2014 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. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Get a brand kit by id \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "getBrandKitExemplarsBody", description: "Presign a brand kit's inspiration exemplar frames \u2014 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). \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Get a brief by id \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Get a checkpoint packet \u2014 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. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Get a component entry \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Get a component's source \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Fetch a compose job's full ensemble state \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Read the session's scratch composition \u2014 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 \u2014 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. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Get a project's composition \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Get an export job \u2014 Required permission: renders:read \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Get an async job's status and result \u2014 Read one async job \u2014 the uniform status/result resource behind every long-running operation. Poll until `status` is terminal (`succeeded` | `failed` | `cancelled`), 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 \u2014 re-enqueue the operation to retry. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Get a media item by id \u2014 Required permission: media:read \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Get authoring context for a media item (faces + transcript + beat/word grids) \u2014 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 \u2014 `beatGrid` (a MUSIC bed's rhythm: bpm, beatTimesMs in milliseconds, confidence, method) and `wordGrid` (VO word-onset timings in milliseconds, from the transcript) \u2014 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 \u2014 `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) \u2014 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. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [{ "name": "after", "required": false, "description": "Zero-based utterance cursor returned as pagination.nextCursor.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "before", "required": false, "description": "Zero-based utterance cursor for a backward page. Do not combine with after.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "required": false, "description": "Utterances per page.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }], bodyKey: null, description: "Get a media transcript (paginated) \u2014 Required permission: media:read \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Poll mux job status \u2014 Required permission: sessions:read \u2014 Advanced (expert layer) \u2014 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: "deriveComposition", toolName: "cueframe_api_deriveComposition", title: "Derive Composition", method: "POST", pathTemplate: "/v1/projects/{id}/compositions/derive", pathParams: ["id"], queryParams: [], bodyKey: "deriveCompositionBody", description: "Derive a reframed sibling composition for a new aspect (multi-format) \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "compositionId": { "type": "string", "description": "The new sibling composition's id." } }, "additionalProperties": true } },
+  { operationId: "extractBrandKit", toolName: "cueframe_api_extractBrandKit", title: "Extract Brand Kit", method: "POST", pathTemplate: "/v1/brand-kits/extract", pathParams: [], queryParams: [], bodyKey: "extractBrandKitBody", description: "Extract brand tokens from a website URL \u2014 Queue brand-token extraction from a website URL \u2014 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 service inspects the site under a 20-second limit and does NOT persist a kit (pass the result to POST /brand-kits). A blocked (private-network), 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. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "jobId": { "type": "string", "description": "Poll GET /v1/jobs/{jobId} / wait_job until terminal." }, "jobKey": { "type": "string", "description": "Deterministic identity of the work (content hash of every input the result depends on). Re-enqueueing the same key returns the same job while it runs; a failed key revives as a fresh attempt." }, "kind": { "type": "string", "description": "Job family, e.g. `verify` | `preview` | `brand_kit_extract`." }, "status": { "type": "string", "description": "running on a fresh/deduped enqueue; succeeded when an identical request already completed. Cancelled is part of the shared status vocabulary; identical cancelled work revives to running.", "enum": ["running", "succeeded", "cancelled"] } }, "additionalProperties": true } },
+  { operationId: "finalizeMedia", toolName: "cueframe_api_finalizeMedia", title: "Finalize Media", method: "POST", pathTemplate: "/v1/media/{id}/finalize", pathParams: ["id"], queryParams: [], bodyKey: "finalizeMediaBody", description: "Finalize a direct upload (trigger processing after the bytes are PUT) \u2014 Required permission: media:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["processing", "complete"] }, "processingPhase": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "generateMedia", toolName: "cueframe_api_generateMedia", title: "Generate Media", method: "POST", pathTemplate: "/v1/media/generate", pathParams: [], queryParams: [], bodyKey: "generateMediaBody", description: "Generate media with AI (video, image, or Manim animation) \u2014 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 \u2014 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). \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "estimateUsd": { "type": "number" } }, "additionalProperties": true } },
+  { operationId: "getAccount", toolName: "cueframe_api_getAccount", title: "Get Account", method: "GET", pathTemplate: "/v1/me", pathParams: [], queryParams: [], bodyKey: null, description: "Return the caller's account: identity, plan, entitlements, cost ceilings \u2014 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 \u2014 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`. Generation is also bounded by the disclosed generationLimit for accounts that have not purchased credits; `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. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "generationLimit": { "description": "Separate lifetime generation cap before a credit-pack purchase. Wallet balance is still shared; generation must also fit this remaining provider-cost allowance. null means unknown." }, "orgId": { "type": "string", "description": "The org this API key is bound to \u2014 resolved server-side from the Authorization credential, NEVER from the request body/query." }, "displayName": { "type": "string", "description": "Org/customer display name from the billing record; null when not set or unknown." }, "plan": { "description": "The customer's current base plan/tier. null = unknown (billing not configured, or no active plan resolvable yet)." }, "entitlements": { "type": "object", "description": "Per-feature entitlements keyed by featureId. Covers the billing-gated capabilities: `exports` gates create_render AND generate_media output; `compose` gates compose; `brand_kits` gates create_brand_kit; `resource_import` gates import_resource (a boolean grant: `listUsdPerUnit` 0 \u2014 stock search and import cost no credits for a keyed caller); plus ai_tokens/storage/compose_verify/compose_capture/etc. Read `listUsdPerUnit` for what one unit costs before you spend it. Most capabilities are CREDIT-FUNDED \u2014 `included` is true and the real limit is `balance`, drawn from the shared wallet named in `fundedBy` (`credits` \u2014 generation included; a free org is additionally bounded by a generation cap). So read `balance`, not `included`, to decide whether you can afford a call; `included:false` means the plan genuinely lacks the feature. Check BEFORE a metered call to avoid a mid-workflow 402 billing_required (whose error `details.featureId` names the gating feature)." }, "costCeilings": { "type": "object", "description": "Discoverable per-call cost ceilings so an agent can price/right-size a request before a guaranteed 402." }, "billingConfigured": { "type": "boolean", "description": "false = billing is not configured in this environment, so plan/entitlement values are best-effort and may be null (unknown), not authoritative." } }, "additionalProperties": true } },
+  { operationId: "getBillingPlans", toolName: "cueframe_api_getBillingPlans", title: "Get Billing Plans", method: "GET", pathTemplate: "/v1/billing/plans", pathParams: [], queryParams: [], bodyKey: null, description: "List the plan catalog: tiers, intervals, product ids, prices \u2014 Returns every purchasable {tier, interval} and its billing catalog product id \u2014 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. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "plans": { "type": "array", "description": "Every purchasable {tier, interval} and its product id." }, "billingConfigured": { "type": "boolean" } }, "additionalProperties": true } },
+  { operationId: "getBrandKit", toolName: "cueframe_api_getBrandKit", title: "Get Brand Kit", method: "GET", pathTemplate: "/v1/brand-kits/{id}", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Get a brand kit by id \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tagline": { "type": "string" }, "colors": { "type": "object" }, "extraColors": { "type": "array" }, "fonts": { "type": "object" }, "voiceGuidelines": { "type": "string" }, "captions": { "type": "object" }, "motion": { "type": "object" }, "logo": { "type": "object" }, "intro": { "type": "object" }, "outro": { "type": "object" }, "watermark": { "type": "object" }, "spacing": { "type": "object" }, "sizing": { "type": "object" }, "audio": { "type": "object" }, "exemplarKeys": { "type": "array" }, "contactSheetKey": { "type": "string" }, "motifs": { "type": "array" }, "styleRubric": { "type": "string" }, "density": { "type": "object" }, "inspiration": { "type": "object" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "getBrandKitExemplars", toolName: "cueframe_api_getBrandKitExemplars", title: "Get Brand Kit Exemplars", method: "POST", pathTemplate: "/v1/brand-kits/{id}/exemplars", pathParams: ["id"], queryParams: [], bodyKey: "getBrandKitExemplarsBody", description: "Presign a brand kit's inspiration exemplar frames \u2014 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). \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "exemplars": { "type": "array" }, "contactSheetUrl": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "getBrief", toolName: "cueframe_api_getBrief", title: "Get Brief", method: "GET", pathTemplate: "/v1/briefs/{id}", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Get a brief by id \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "kind": { "type": "string", "description": "authored = create_brief; clip = minted by suggest_briefs from an AI clip suggestion.", "enum": ["authored", "clip"] }, "sourceSuggestionId": { "type": "string", "description": "kind:'clip' provenance \u2014 the suggestion this Brief was minted from." }, "name": { "type": "string" }, "goal": { "type": "string", "description": "What the video must accomplish." }, "audience": { "type": "string" }, "platform": { "type": "string" }, "format": { "type": "object", "description": "Output-format spec per \xA7Format." }, "durationSec": { "type": "number", "description": "Target output duration. HONOR-OR-REFUSE: compose validates it against the beat-source window (\xB11.5s) and refuses a brief it cannot honor." }, "tone": { "type": "string" }, "cta": { "type": "string" }, "locale": { "type": "string", "description": "Output language (BCP-47 tag, e.g. 'es-419'): ALL on-screen copy + captions." }, "hook": { "type": "string" }, "caption": { "type": "string" }, "beats": { "type": "array" }, "mustIncludes": { "type": "array" }, "references": { "type": "array" }, "captions": { "type": "object" }, "motionStyle": { "type": "object" }, "seededGraphics": { "type": "array", "description": "Client-authored graphic clips the Director must carry VERBATIM: seeded into the design loop's base composition as LOCKED clips (never re-authored, never discarded)." }, "exclusions": { "type": "array" }, "gates": { "type": "object" }, "audio": { "type": "object" }, "quote": { "type": "object" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "additionalProperties": true } },
+  { operationId: "getCheckpoint", toolName: "cueframe_api_getCheckpoint", title: "Get Checkpoint", method: "GET", pathTemplate: "/v1/checkpoints/{id}", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Get a checkpoint packet \u2014 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. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "composeJobId": { "type": "string" }, "briefId": { "type": "string" }, "kind": { "type": "string", "enum": ["gate", "score"] }, "stage": { "type": "string", "enum": ["content", "layout", "motion"] }, "version": { "type": "integer" }, "status": { "type": "string", "enum": ["awaiting", "approved", "revised", "abandoned", "expired", "superseded"] }, "artifact": { "description": "The stage artifact under review: the locked ComposePlan at content; the composition wire shape at layout/motion; the judged composition snapshot on kind:'score'." }, "stillUrls": { "type": "array", "description": "Presigned storyboard/eval stills \u2014 the packet's visual evidence (may be GC'd by the retention sweep after the job goes terminal; the decision record is immortal)." }, "criticVerdicts": { "description": "Per-criterion scores + critique from the design loop / judge, incl. lock_violation entries." }, "quote": { "type": "object" }, "revisionCycle": { "type": "integer", "description": "Revise cycles this gate has consumed. The brief quote states the included count (revisionCyclesIncluded); beyond it, resume(revise) is refused with a typed error." }, "decision": { "description": "The recorded decision {decision, comments?, globalNote?, decidedAt} once resolved." }, "reviewMode": { "type": "string", "description": "How this packet is decided (from the Brief's gates). 'hosted' = the review PAGE captures the decision; absent/'agent' = the decision flows back through the driving agent.", "enum": ["agent", "hosted"] }, "reviewUrl": { "type": "string", "description": "Hosted review-page URL (present when reviewMode is 'hosted') \u2014 a human decides from this link, no account or agent session; the recorded decision rides the SAME resume rail, and the agent learns of it via checkpoint webhooks / wait_job." }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "additionalProperties": true } },
+  { operationId: "getComponent", toolName: "cueframe_api_getComponent", title: "Get Component", method: "GET", pathTemplate: "/v1/components/{id}", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Get a component entry \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "source": { "type": "string", "description": "'default' = built-in primitive (place by primitiveId); 'installed' = org-authored component (place by componentId).", "enum": ["default", "installed"] }, "category": { "type": "string", "enum": ["text", "effects", "transitions", "layouts", "backgrounds", "ui-blocks", "scenes"] }, "kind": { "type": "string", "description": "RENDER kind (component | transition | scene). NOT the ClipSource variant \u2014 see `placement` for how to author it on the timeline.", "enum": ["component", "transition", "scene"] }, "version": { "type": "string" }, "propSchema": { "type": "object" }, "propDefaults": { "type": "object" }, "textParam": { "type": "string", "description": "The param field that carries this primitive's primary text; null = no single text slot." }, "subtextParam": { "type": "string", "description": "The param field for secondary text (subtitle/byline); null = none." }, "format": { "type": "object" }, "durationInFrames": { "type": "number" }, "intent": { "type": "string", "description": "Selection signal: a verb naming what this primitive accomplishes (e.g. 'product-trailer'). Match it to the beat you are authoring." }, "useWhen": { "type": "string", "description": "When to use this \u2014 AND when not to. The negative guidance is load-bearing; read it before picking." }, "pairsWith": { "type": "array", "description": "Authoring guidance: ids of primitives that COMPOSE well with this one in the same edit." }, "avoidWith": { "type": "array", "description": "Authoring guidance: ids of primitives that CONFLICT with this one \u2014 do not place together." }, "tags": { "type": "array", "description": "Free-text search keywords." }, "mood": { "type": "array", "description": "Vibe/tone tags (e.g. 'cinematic', 'minimal'). Filter to match the edit's mood." }, "tier": { "type": "string", "description": "Quality/applicability RANKING (a preference, not a flag). Prefer 'recommended'; reach for 'niche' only when its specific use-case is exactly the beat.", "enum": ["recommended", "standard", "niche"] }, "useCase": { "type": "array", "description": "The edit ROLE(s) this primitive fills \u2014 the dimension to filter by for a beat (e.g. 'intro', 'title-over-footage', 'grade')." }, "examples": { "type": "array" }, "fixedCopy": { "type": "array", "description": "On-screen strings this primitive BAKES \u2014 the read-side counterpart to propSchema. These literals render REGARDLESS of params (no param can change them); fork the source via get_component_source to edit them. Use this to see at author time what fixed copy (someone-else's marketing text, faux-code, faux-data) will appear before you render." }, "brandBindings": { "type": "array", "description": "Params that can follow the project brand kit. Each {param, brandToken} says: set `param` to `brandToken` (a `$brand:` ref, e.g. '$brand:colors.accent') to track the brand instead of a literal. See the list response's `brandTokens` for the full ref vocabulary. Omitted when nothing is brand-bound." }, "placement": { "type": "object" }, "warnings": { "type": "array", "description": "Non-blocking save-time advisories \u2014 the create/update SUCCEEDED. Currently: a `fontFamily` string literal referencing a NON-vendored font (a bare CSS generic like 'serif', or an unknown named family like 'Arial') whose LIVE-lane pixels vary by render host \u2014 re-author with a vendored family or 'Georgia'. Omitted when there is nothing to flag; only present on the create/update responses." } }, "additionalProperties": true } },
+  { operationId: "getComponentSource", toolName: "cueframe_api_getComponentSource", title: "Get Component Source", method: "GET", pathTemplate: "/v1/components/{id}/source", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Get a component's source \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "source": { "type": "string", "enum": ["default", "installed"] }, "tsxSource": { "type": "string" }, "propSchema": { "type": "object" }, "origin": { "type": "string", "enum": ["customer-owned", "server-native"] }, "ejectedFrom": { "type": "string" }, "tokens": { "type": "object" }, "examples": { "type": "array" }, "durationInFrames": { "type": "number" }, "manifest": { "type": "object" } }, "additionalProperties": true } },
+  { operationId: "getComposeJob", toolName: "cueframe_api_getComposeJob", title: "Get Compose Job", method: "GET", pathTemplate: "/v1/projects/{id}/compose/jobs/{composeJobId}", pathParams: ["id", "composeJobId"], queryParams: [], bodyKey: null, description: "Fetch a compose job's full ensemble state \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "composeJobId": { "type": "string" }, "projectId": { "type": "string" }, "status": { "type": "string", "enum": ["queued", "running", "awaiting_input", "complete", "failed", "cancelled"] }, "error": { "type": "string" }, "request": { "type": "object" }, "candidates": { "type": "array" }, "winner": {}, "listUsd": { "type": "number" }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" }, "advisoryResult": { "type": "object", "description": "The advisory envelope returned by a completed consult job (on ComposeJobDetailResponse.advisoryResult)." }, "checkpoint": { "type": "object" } }, "additionalProperties": true } },
+  { operationId: "getComposeSessionComposition", toolName: "cueframe_api_getComposeSessionComposition", title: "Get Compose Session Composition", method: "GET", pathTemplate: "/v1/projects/{id}/compose-session/{sessionId}/composition", pathParams: ["id", "sessionId"], queryParams: [], bodyKey: null, description: "Read the session's scratch composition \u2014 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 \u2014 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. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "composition": {} }, "additionalProperties": true } },
+  { operationId: "getComposition", toolName: "cueframe_api_getComposition", title: "Get Composition", method: "GET", pathTemplate: "/v1/projects/{id}/composition", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Get a project's composition \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "v": { "type": "number" }, "format": { "type": "object" }, "tracks": { "type": "array" }, "markers": { "type": "array" }, "captions": { "type": "object" }, "license": { "type": "object" }, "accessibility": { "type": "object" } }, "additionalProperties": true } },
+  { operationId: "getExport", toolName: "cueframe_api_getExport", title: "Get Export", method: "GET", pathTemplate: "/v1/projects/{id}/exports/{exportId}", pathParams: ["id", "exportId"], queryParams: [], bodyKey: null, description: "Get an export job \u2014 Required permission: renders:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "format": { "type": "string", "enum": ["fcpxml", "premiere"] }, "status": { "type": "string", "enum": ["queued", "trimming", "building", "uploading", "complete", "error", "cancelled"] }, "progress": { "type": "number", "description": "Fractional progress 0..1 across the trim/build/upload pipeline. Reaches 1 only on `complete`." }, "outputUrl": { "type": "string" }, "outputExpiresAt": { "type": "string" }, "outputSizeBytes": { "type": "number" }, "outputDurationSec": { "type": "number" }, "error": { "description": "Set when status is `error`; null otherwise. The phase field localizes the failure to trim / build / upload / trigger." }, "trimCacheHit": { "type": "boolean" }, "clipSuggestionId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "getJob", toolName: "cueframe_api_getJob", title: "Get Job", method: "GET", pathTemplate: "/v1/jobs/{jobId}", pathParams: ["jobId"], queryParams: [], bodyKey: null, description: "Get an async job's status and result \u2014 Read one async job \u2014 the uniform status/result resource behind every long-running operation. Poll until `status` is terminal (`succeeded` | `failed` | `cancelled`), 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 \u2014 re-enqueue the operation to retry. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string", "description": "Job id \u2014 pass to GET /v1/jobs/{id} / wait_job." }, "jobKey": { "type": "string", "description": "Deterministic identity of the work (idempotency key, e.g. `verify-<sessionId>-<contentHash>` \u2014 the hash covers the composition AND grading inputs). Re-enqueueing the same key returns the same job while it runs." }, "kind": { "type": "string", "description": "Job family, e.g. `verify`." }, "status": { "type": "string", "description": "Poll until terminal (`succeeded` | `failed` | `cancelled`).", "enum": ["running", "succeeded", "failed", "cancelled"] }, "progress": { "description": "Executor heartbeat while running; null when none reported." }, "result": { "description": "Kind-specific payload when status is `succeeded`; null otherwise." }, "error": { "description": "Stable failure code + human message when status is `failed`; null otherwise. `job_timeout` = the executor died mid-run and the stall sweep reaped the job \u2014 re-enqueue to retry." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "completedAt": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "getMedia", toolName: "cueframe_api_getMedia", title: "Get Media", method: "GET", pathTemplate: "/v1/media/{id}", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Get a media item by id \u2014 Required permission: media:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string", "enum": ["upload", "generated", "stock"] }, "name": { "type": "string" }, "mimeType": { "type": "string" }, "fileSize": { "type": "number" }, "duration": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "frameRate": { "type": "number" }, "progress": {}, "analysis": {}, "listUsd": { "type": "number", "description": "A2 money stamp \u2014 GENERATED media only: the generate meter's LIST price (USD) at the success terminal. A plan allowance may zero the invoice line. Absent for uploads/imports, failures, x402 (on-chain receipts)." }, "thumbnailUrl": { "type": "string", "description": "Presigned GET URL for the item's thumbnail (an uploaded image is its own thumbnail), valid ~7 days \u2014 fetch it directly, no auth header. null when no thumbnail exists yet (still processing, stock imports, audio)." }, "kind": { "type": "string" }, "tags": {}, "attribution": {}, "processingStatus": {}, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "getMediaContext", toolName: "cueframe_api_getMediaContext", title: "Get Media Context", method: "GET", pathTemplate: "/v1/media/{id}/context", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Get authoring context for a media item (faces + transcript + beat/word grids) \u2014 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 \u2014 `beatGrid` (a MUSIC bed's rhythm: bpm, beatTimesMs in milliseconds, confidence, method) and `wordGrid` (VO word-onset timings in milliseconds, from the transcript) \u2014 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 \u2014 `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) \u2014 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. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "mediaId": { "type": "string" }, "durationSec": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "thumbnail": { "description": "Presigned processing thumbnail (~1 week) \u2014 the footage at a glance. For stills at chosen timestamps, use preview_frame with a one-clip composition over this media." }, "faces": { "type": "object" }, "transcript": { "type": "object" }, "beatGrid": { "description": "The MUSIC-role rhythm grid (audio-substrate MVP). Present only for a music bed that carries a computed beat grid; null otherwise. For a music-driven film, cut on these beats (transition midpoints on beats, risers resolving on downbeats)." }, "wordGrid": { "description": "The VO-role rhythm grid: word onsets surfaced from the transcript (pure exposure). Present only when a transcript exists; null otherwise. For a VO-driven (narration) film, cut every beat boundary to the voice \u2014 the film-spine rule." }, "audioRole": { "description": "DECLARED audio role of this asset (audio-substrate P0): 'vo' (narration), 'music' (bed that ducks under speech), 'sfx' (one-shot hit), 'ambience' (a bed that HOLDS under VO \u2014 never ducks). Author the clip source's `audioRole` from this. Null for footage/images or an undeclared audio asset." }, "envelope": { "description": "Envelope evidence (audio-substrate P0). `envelopeClass` is always present when an envelope exists (the SFX pack carries it); the numeric probe stats are present only when an audio probe has run. Null when no envelope is stored." }, "facts": { "type": "array", "description": "Derived facts about this source (subject tracks, mattes): what has been computed, its status, and what it was billed. Same shape as GET /media/{id}/facts." }, "offers": { "type": "array", "description": "Enhancements this source does not have yet, with a server quote. Same shape as GET /media/{id}/facts. Mattes are quoted per-window via POST /media/{id}/matte, never here." } }, "additionalProperties": true } },
+  { operationId: "getMediaTranscript", toolName: "cueframe_api_getMediaTranscript", title: "Get Media Transcript", method: "GET", pathTemplate: "/v1/media/{id}/transcript", pathParams: ["id"], queryParams: [{ "name": "after", "required": false, "description": "Zero-based utterance cursor returned as pagination.nextCursor.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "before", "required": false, "description": "Zero-based utterance cursor for a backward page. Do not combine with after.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "required": false, "description": "Utterances per page.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }], bodyKey: null, description: "Get a media transcript (paginated) \u2014 Required permission: media:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "mediaItemId": { "type": "string" }, "language": { "type": "string" }, "fullText": { "type": "string" }, "utterances": { "type": "array" }, "data": { "type": "array" }, "pagination": { "type": "object", "description": "Cursor pagination metadata." } }, "additionalProperties": true } },
+  { operationId: "getMuxJob", toolName: "cueframe_api_getMuxJob", title: "Get Mux Job", method: "GET", pathTemplate: "/v1/sessions/{id}/mux-job", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Poll mux job status \u2014 Required permission: sessions:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "type": "string" }, "muxedItems": {}, "error": { "type": "string" }, "startedAt": { "type": "string" }, "completedAt": { "type": "string" } }, "additionalProperties": true } },
   { operationId: "getOpenAPISpec", toolName: "cueframe_api_getOpenAPISpec", title: "Get Open API Spec", method: "GET", pathTemplate: "/openapi.json", pathParams: [], queryParams: [], bodyKey: null, description: "OpenAPI 3.1 document for the v1 API \u2014 Returns the generated OpenAPI 3.1 document. Unauthenticated so SDK tooling (Orval, Postman, redocly) can fetch without a key. Cacheable for 5 minutes. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: null, description: "Read the org's Profile \u2014 its legible taste \u2014 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 \u2014 it is the house style. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Get a project by id \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "One-call agent context: composition + media + transcript + brand \u2014 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` \u2014 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 \u2014 read another item's with GET /v1/media/{id}/transcript, and its faces/beat/word grids with GET /v1/media/{id}/context. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Get a render job \u2014 Required permission: renders:read \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Read a hosted review packet (token-authenticated page data) \u2014 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\u2192vN version stack. Authenticated by the packet's reviewToken (?token=) \u2014 the URL from the checkpoint.ready webhook / get_checkpoint. Expired or already-answered packets still render (with their decision), never an error page. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Get a session \u2014 Required permission: sessions:read \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: null, description: "Read the org's Profile \u2014 its legible taste \u2014 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 \u2014 it is the house style. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "brandKits": { "type": "array", "description": "The org's brand kits (bind one to a project via update_project). `audio` carries the brand sound kit when set." }, "critics": { "type": "array", "description": "Registered critics \u2014 run in the Director's gates AND score_composition." }, "references": { "type": "array", "description": "The union of critic reference media \u2014 the org's visual standard, with provenance." }, "recentDecisions": { "type": "array", "description": "The last recorded checkpoint decisions \u2014 the raw taste log phase 2 will distill." } }, "additionalProperties": true } },
+  { operationId: "getProject", toolName: "cueframe_api_getProject", title: "Get Project", method: "GET", pathTemplate: "/v1/projects/{id}", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Get a project by id \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "format": {}, "brandKitId": { "type": "string" }, "activeCompositionId": { "type": "string" }, "composition": { "type": "object", "description": "Summary of a project's stored composition." }, "lastRender": { "description": "Most recent render for a project, if any." }, "webUrl": { "type": "string", "description": "A browser URL that opens THIS project, or null when CueFrame exposes no web view for a project. Null today: the console serves account surfaces (keys, usage, billing) and has no per-project page, so there is no link to give. Do NOT synthesise one \u2014 a guessed console path 404s. Show the user rendered output (create_render \u2192 outputUrl) or a preview still instead. This field becoming non-null is the signal that a real project view exists." }, "createdAt": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "getProjectContext", toolName: "cueframe_api_getProjectContext", title: "Get Project Context", method: "GET", pathTemplate: "/v1/projects/{id}/context", pathParams: ["id"], queryParams: [], bodyKey: null, description: "One-call agent context: composition + media + transcript + brand \u2014 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` \u2014 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 \u2014 read another item's with GET /v1/media/{id}/transcript, and its faces/beat/word grids with GET /v1/media/{id}/context. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "composition": { "description": "The project's ACTIVE composition wire shape \u2014 identical to GET /v1/projects/{id}/composition. NULL when the project has no composition yet (a freshly created project): mint one with new_composition, or let the first apply_composition create it." }, "format": { "description": "The composition's format, hoisted \u2014 the pixel frame every card/graphic must be authored against. Null whenever `composition` is null." }, "media": { "type": "array", "description": "The org's media library (most recent first, capped) \u2014 the pool this project can draw clips from." }, "transcript": { "description": 'The FIRST transcribed media item\'s word-timed transcript, flattened \u2014 the spine a VO-driven film cuts to. `status:"ready"` carries the words; `status:"unavailable"` means the transcript exists but its body could not be fetched (retry); null means nothing in `media` is transcribed. For any OTHER transcribed item (see each entry\'s `hasTranscript`), read GET /v1/media/{id}/transcript.' }, "brandKit": { "description": "The kit BOUND to this project (`projects.brandKitId` is the brand SSOT \u2014 bind one via update_project). Null when the project has no kit bound; enumerate the org's kits with GET /v1/brand-kits." }, "markers": { "type": "array", "description": "The composition's markers \u2014 hoisted alongside `format`. Empty when the composition carries none AND when there is no composition yet." } }, "additionalProperties": true } },
+  { operationId: "getRender", toolName: "cueframe_api_getRender", title: "Get Render", method: "GET", pathTemplate: "/v1/projects/{id}/renders/{renderId}", pathParams: ["id", "renderId"], queryParams: [], bodyKey: null, description: "Get a render job \u2014 Required permission: renders:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["queued", "pending", "rendering", "complete", "error", "cancelled"] }, "progress": { "type": "object", "description": "Non-terminal render progress; phase is one of the worker's emitted stages." }, "outputUrl": { "type": "string" }, "outputExpiresAt": { "type": "string" }, "error": { "type": "string", "description": "Human-readable failure message. Pair with `errorCode` for a stable, machine-readable code an agent runner can branch on." }, "errorCode": { "type": "string", "description": "Stable, machine-readable error code (e.g. `render_pipeline_unavailable`, `render_route_missing`, `render_pipeline_failed`). Null when status is not `error` or unavailable for an older render." }, "errorDetails": { "description": "Structured failure context \u2014 `{ targetUrl?, upstreamStatus?, upstreamCode?, attemptedAt? }`. Surfaced so agent runners can distinguish operator-config issues from upstream-down vs route-missing without parsing `error`." }, "category": { "description": "Failure taxonomy when status is `error`; null otherwise. `authoring` = deterministic defect in YOUR composition/request \u2014 fix it, retrying is futile; `transient` = temporary pipeline/infra failure \u2014 safe to retry_render; `internal` = unexpected server fault \u2014 retry once then escalate. Mirrors the render.failed webhook's `category`." }, "retryable": { "type": "boolean", "description": "Whether re-attempting the SAME render can succeed (status `error`); null otherwise. true \u2192 call retry_render. false \u2192 deterministic (category authoring/internal); fix the composition first \u2014 retry_render alone reproduces it. Mirrors the render.failed webhook's `retryable`." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the render's most recent progress update. Compute staleness = now \u2212 updatedAt to distinguish a wedged render from a slow one and decide whether to wait, cancel, or retry." }, "listUsd": { "type": "number", "description": "A2 money stamp: the metered event's LIST price (USD), stamped at the success terminal (exports for deliverable renders, compose_capture for A8 previews). A plan allowance may zero the actual invoice line \u2014 this is the list price, never a Stripe charge. Absent while running, on failure, and for x402 orgs (on-chain receipts). Mirrors the get_usage ledger." }, "warnings": { "type": "array", "description": "Non-fatal advisories surfaced at render-CREATE (omitted when none, and on GET \u2014 create-time only)." } }, "additionalProperties": true } },
+  { operationId: "getReviewPacket", toolName: "cueframe_api_getReviewPacket", title: "Get Review Packet", method: "GET", pathTemplate: "/v1/review/{id}", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Read a hosted review packet (token-authenticated page data) \u2014 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\u2192vN version stack. Authenticated by the packet's reviewToken (?token=) \u2014 the URL from the checkpoint.ready webhook / get_checkpoint. Expired or already-answered packets still render (with their decision), never an error page. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "composeJobId": { "type": "string" }, "briefId": { "type": "string" }, "kind": { "type": "string", "enum": ["gate", "score"] }, "stage": { "type": "string", "enum": ["content", "layout", "motion"] }, "version": { "type": "integer" }, "status": { "type": "string", "enum": ["awaiting", "approved", "revised", "abandoned", "expired", "superseded"] }, "artifact": { "description": "The stage artifact under review: the locked ComposePlan at content; the composition wire shape at layout/motion; the judged composition snapshot on kind:'score'." }, "stillUrls": { "type": "array", "description": "Presigned storyboard/eval stills \u2014 the packet's visual evidence (may be GC'd by the retention sweep after the job goes terminal; the decision record is immortal)." }, "criticVerdicts": { "description": "Per-criterion scores + critique from the design loop / judge, incl. lock_violation entries." }, "quote": { "type": "object" }, "revisionCycle": { "type": "integer", "description": "Revise cycles this gate has consumed. The brief quote states the included count (revisionCyclesIncluded); beyond it, resume(revise) is refused with a typed error." }, "decision": { "description": "The recorded decision {decision, comments?, globalNote?, decidedAt} once resolved." }, "reviewMode": { "type": "string", "description": "How this packet is decided (from the Brief's gates). 'hosted' = the review PAGE captures the decision; absent/'agent' = the decision flows back through the driving agent.", "enum": ["agent", "hosted"] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "versionStack": { "type": "array", "description": "The run's v1\u2192vN gate history \u2014 per-version status + decision summaries." } }, "additionalProperties": true } },
+  { operationId: "getSession", toolName: "cueframe_api_getSession", title: "Get Session", method: "GET", pathTemplate: "/v1/sessions/{id}", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Get a session \u2014 Required permission: sessions:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "files": { "type": "array" }, "mux": { "type": "object" }, "createdAt": { "type": "string" } }, "additionalProperties": true } },
   { operationId: "getSkill", toolName: "cueframe_api_getSkill", title: "Get Skill", method: "GET", pathTemplate: "/v1/skills/{name}", pathParams: ["name"], queryParams: [], bodyKey: null, description: "Get a skill's SKILL.md (markdown) \u2014 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. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "projectId", "required": false, "description": "Only events attributed to this project.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "jobId", "required": false, "description": 'Only events produced by this job \u2014 how to answer "did my failed render post a charge?" for one run.', "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "from", "required": false, "description": "Period start, epoch milliseconds, INCLUSIVE.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "to", "required": false, "description": "Period end, epoch milliseconds, EXCLUSIVE.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }], bodyKey: null, description: "List metered usage events (the A2 usage ledger) \u2014 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). \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Get a webhook endpoint \u2014 Required permission: webhooks:read \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: null, description: "Get the webhook delivery contract \u2014 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 \u2014 it answers 'what's the payload shape / how do I verify the signature / how does activation work' without guessing. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [{ "name": "deep", "required": false, "description": "Pass `1` to run the deep dependency checks instead of the shallow liveness probe.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "const": "1" } }], bodyKey: null, description: "Shallow + deep health check \u2014 Shallow (default) returns 200 with a minimal liveness payload for load balancers. Append `?deep=1` to exercise component bindings (rate-limiter). Unauthenticated. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "importMediaBody", description: "Import media from a URL (server-side fetch) \u2014 Import media into the project from a public https URL \u2014 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. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "importResourceBody", description: "Import a stock candidate or a curated SFX-pack sound \u2014 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' }; status flips to complete when the import finishes (poll GET /media/:id). A candidate whose 7-day search cache has expired returns 422 \u2014 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[]) \u2014 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). PRICE of a stock import for a keyed (API-key / session) caller: 0 credits \u2014 the resource_import entitlement is a plan grant, not a meter (get_account reports `entitlements.resource_import.listUsdPerUnit: 0`); the imported bytes count toward the `storage` gauge. Only an unkeyed x402 caller pays the $0.01 import tier. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }], bodyKey: null, description: "List brand kits (read-only) \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "projectId", "required": false, "description": "Scope to one project. Omit for every brief in the org.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "kind", "required": false, "description": "Which briefs to list. `authored` (default) = human-authored only; `clip` = the machine-minted clip briefs from suggest_briefs; `all` = both.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "enum": ["authored", "clip", "all"] } }], bodyKey: null, description: "List briefs (optionally scoped to a project) \u2014 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. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [{ "name": "category", "required": false, "description": "Filter to one category bucket (text|effects|transitions|layouts|backgrounds|ui-blocks|scenes).", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "enum": ["text", "effects", "transitions", "layouts", "backgrounds", "ui-blocks", "scenes"] } }, { "name": "kind", "required": false, "description": "Filter by render kind (component|transition|scene).", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "enum": ["component", "transition", "scene"] } }, { "name": "tier", "required": false, "description": "Filter by curation tier (recommended|standard|niche).", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "enum": ["recommended", "standard", "niche"] } }, { "name": "useCase", "required": false, "description": "Filter to entries whose useCase includes this edit role (e.g. intro, title-over-footage, grade).", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "enum": ["intro", "outro", "full-scene", "title-over-footage", "transition", "background", "grade", "emphasis", "explainer", "social-cut"] } }, { "name": "mood", "required": false, "description": "Filter to entries whose mood tags include this value (e.g. cinematic, minimal).", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "q", "required": false, "description": "Free-text match across id/name/description/intent/useWhen/tags/mood. Recommend-orders results.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "intent", "required": false, "description": "Alias of `q` framed as recommend-by-intent (e.g. intent=intro). Recommend-orders results.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "limit", "required": false, "description": "Page size (1..100). Omit to return the whole filtered catalog in one page.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from a previous page's nextCursor (forward-only).", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }], bodyKey: null, description: "List component catalog (defaults + installed) \u2014 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 \u2014 pass `limit` only to page. Each entry carries a `placement` hint telling you exactly how to author it on the timeline. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "composeJobId", "required": false, "description": "Scope to ONE compose run \u2014 its v1\u2192vN gate history with per-version status and decisions.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "projectId", "required": false, "description": "Scope to everything reviewable in one project.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }], bodyKey: null, description: "List checkpoints (scope to a compose job or project) \u2014 The version stack of approval packets, newest first. Scope with ?composeJobId= to see one run's gate history (v1\u2192vN with per-version status + decisions) or ?projectId= for everything reviewable in a project. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "List recent compose jobs for a project \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "List a project's compositions \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: null, description: "List registered critics (Profile family) \u2014 Every enabled critic: id, label, tier, phase, floor, and reference media. Rubric text, rules, and evaluator URLs are write-only \u2014 registration config comes back, payloads don't. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "kind", "required": false, "description": "Filter to one media kind.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "enum": ["video", "audio", "image", "gif", "asset", "source", "stock"] } }, { "name": "source", "required": false, "description": "Filter by how the item entered the library.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "enum": ["upload", "generated", "import-url", "stock"] } }, { "name": "tag", "required": false, "description": "Filter to items carrying this EXACT tag (not a prefix or substring match).", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }], bodyKey: null, description: "List media items \u2014 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. \u2014 Advanced (expert layer) \u2014 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: "listMediaFacts", toolName: "cueframe_api_listMediaFacts", title: "List Media Facts", method: "GET", pathTemplate: "/v1/media/{id}/facts", pathParams: ["id"], queryParams: [{ "name": "kind", "required": false, "description": "Resolve one exact editor prerequisite. Requires startSec and endSec; the response includes the server-selected `exact` result.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "enum": ["subjectTrack", "matte"] } }, { "name": "startSec", "required": false, "description": "Source-in of the clip's trim, in seconds. Must be sent WITH endSec \u2014 one without the other is a 400, never a silent whole-source default.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "number" } }, { "name": "endSec", "required": false, "description": "Source-out of the clip's trim, in seconds. Must be sent WITH startSec.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "number" } }], bodyKey: null, description: "List derived facts for a media item, with quotes for what is missing \u2014 The enhancement menu. `facts` is everything expensive we have already computed about this source \u2014 subject tracks, mattes \u2014 with its status, a small summary a caller can act on without fetching the artifact, and `charge` (what it was billed; absent when it cost nothing, e.g. a matte produced as a side effect of a compose you already paid for, or one delivered below the behind-subject presence floor). `offers` is what is NOT present yet, with a real server quote. A matte is offered ONLY when you pass `startSec`+`endSec` \u2014 the clip's SOURCE window \u2014 because a matte's price is a function of its duration and a whole-source quote for a three-second clip is not a price. Pass the window from the editor and you get a per-clip matte quote plus the status of that window's matte; omit it from the library and you get everything except the matte. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "platform", "required": false, "description": "Only suggestions cut for this delivery platform.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "format", "required": false, "description": "Only suggestions in this output format.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "topic", "required": false, "description": "Only suggestions matching this topic label.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }], bodyKey: null, description: "List clip suggestions for a media item \u2014 Required permission: media:read \u2014 Advanced (expert layer) \u2014 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"], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "status", "required": false, "description": "Comma-separated render statuses to include (e.g. `error,cancelled`). Omit for every status.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }], bodyKey: null, description: "List renders for a project \u2014 Required permission: renders:read \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }], bodyKey: null, description: "List projects \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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: "listRenderFonts", toolName: "cueframe_api_listRenderFonts", title: "List Render Fonts", method: "GET", pathTemplate: "/v1/fonts", pathParams: [], queryParams: [], bodyKey: null, description: "List the font faces the renderer can actually draw \u2014 The renderer's admitted font set: per family the exact name authoring accepts, the weight ranges a shipped file declares, the styles bytes exist for, the caption default weights, and whether the bytes are bundled or an aliased metric-compatible stand-in. Choose from here and validate_composition will not refuse the face. Unlike POST /fonts/search (which searches the GOOGLE catalog) this is what the render page can rasterize. `manifestVersion` identifies the exact table and moves only when the admitted set does. Covers the BUNDLED set only \u2014 a brand kit's sealed faces are per-org and per-render, and a real italic can come only from one. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [{ "name": "groupId", "required": true, "description": "The synced-angle group to score.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "minLength": 1 } }], bodyKey: null, description: "List switch (multicam) candidates + recommendation for a synced-angle group \u2014 Required permission: media:read \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }], bodyKey: null, description: "List sessions \u2014 Required permission: sessions:read \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: null, description: "List available CueFrame agent skills \u2014 Returns the agent skills CueFrame publishes (e.g. `cueframe-cli`). Metadata only \u2014 fetch the markdown body from GET /skills/{name}. Unauthenticated, like /openapi.json. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }], bodyKey: null, description: "List webhook endpoints \u2014 Required permission: webhooks:read \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "projectId", "required": false, "description": "Only events attributed to this project.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "jobId", "required": false, "description": 'Only events produced by this job \u2014 how to answer "did my failed render post a charge?" for one run.', "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "from", "required": false, "description": "Period start, epoch milliseconds, INCLUSIVE.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "to", "required": false, "description": "Period end, epoch milliseconds, EXCLUSIVE.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }], bodyKey: null, description: "List metered usage events (the A2 usage ledger) \u2014 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). \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "data": { "type": "array" }, "pagination": { "type": "object", "description": "Cursor pagination metadata." } }, "additionalProperties": true } },
+  { operationId: "getWebhook", toolName: "cueframe_api_getWebhook", title: "Get Webhook", method: "GET", pathTemplate: "/v1/webhooks/{id}", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Get a webhook endpoint \u2014 Required permission: webhooks:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array" }, "settleMs": { "type": "integer" }, "enabled": { "type": "boolean" }, "verificationStatus": { "type": "string", "description": "pending = callback URL has not echoed the ownership challenge (receives no events); verified = ownership proven.", "enum": ["pending", "verified"] }, "createdAt": { "type": "string" }, "lastDeliveredAt": { "type": "string" }, "lastFailedAt": { "type": "string" }, "consecutiveFailures": { "type": "integer" } }, "additionalProperties": true } },
+  { operationId: "getWebhookEvents", toolName: "cueframe_api_getWebhookEvents", title: "Get Webhook Events", method: "GET", pathTemplate: "/v1/webhooks/events", pathParams: [], queryParams: [], bodyKey: null, description: "Get the webhook delivery contract \u2014 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 \u2014 it answers 'what's the payload shape / how do I verify the signature / how does activation work' without guessing. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "delivery": { "type": "object", "description": "The shared HTTP envelope + headers + retry semantics." }, "signing": { "type": "object", "description": "Standard Webhooks signing: secret format, signed content, how to verify." }, "ownershipVerification": { "type": "object", "description": "The synchronous echo-the-token activation handshake + recovery." }, "events": { "type": "array", "description": "Every subscribable event with its exact delivery `data` fields." }, "sample": { "type": "object", "description": "A fully-worked example delivery (headers + body)." } }, "additionalProperties": true } },
+  { operationId: "health", toolName: "cueframe_api_health", title: "Health", method: "GET", pathTemplate: "/v1/health", pathParams: [], queryParams: [{ "name": "deep", "required": false, "description": "Pass `1` to run the deep dependency checks instead of the shallow liveness probe.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "const": "1" } }], bodyKey: null, description: "Shallow + deep health check \u2014 Shallow (default) returns 200 with a minimal liveness payload for load balancers. Append `?deep=1` to exercise component bindings (rate-limiter). Unauthenticated. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "status": { "type": "string", "enum": ["ok", "degraded"] }, "version": { "type": "string" }, "checks": { "type": "object" } }, "additionalProperties": true } },
+  { operationId: "importMedia", toolName: "cueframe_api_importMedia", title: "Import Media", method: "POST", pathTemplate: "/v1/media/import", pathParams: [], queryParams: [], bodyKey: "importMediaBody", description: "Import media from a URL (server-side fetch) \u2014 Import media into the project from a public https URL \u2014 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. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "importResource", toolName: "cueframe_api_importResource", title: "Import Resource", method: "POST", pathTemplate: "/v1/resources/import", pathParams: [], queryParams: [], bodyKey: "importResourceBody", description: "Import a stock candidate or a curated SFX-pack sound \u2014 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' }; status flips to complete when the import finishes (poll GET /media/:id). A candidate whose 7-day search cache has expired returns 422 \u2014 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[]) \u2014 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). PRICE of a stock import for a keyed (API-key / session) caller: 0 credits \u2014 the resource_import entitlement is a plan grant, not a meter (get_account reports `entitlements.resource_import.listUsdPerUnit: 0`); the imported bytes count toward the `storage` gauge. Only an unkeyed x402 caller pays the $0.01 import tier. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["importing", "ready"] } }, "additionalProperties": true } },
+  { operationId: "listBrandKits", toolName: "cueframe_api_listBrandKits", title: "List Brand Kits", method: "GET", pathTemplate: "/v1/brand-kits", pathParams: [], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }], bodyKey: null, description: "List brand kits (read-only) \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "data": { "type": "array" }, "pagination": { "type": "object", "description": "Cursor pagination metadata." } }, "additionalProperties": true } },
+  { operationId: "listBriefs", toolName: "cueframe_api_listBriefs", title: "List Briefs", method: "GET", pathTemplate: "/v1/briefs", pathParams: [], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "projectId", "required": false, "description": "Scope to one project. Omit for every brief in the org.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "kind", "required": false, "description": "Which briefs to list. `authored` (default) = human-authored only; `clip` = the machine-minted clip briefs from suggest_briefs; `all` = both.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "enum": ["authored", "clip", "all"] } }], bodyKey: null, description: "List briefs (optionally scoped to a project) \u2014 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. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "data": { "type": "array" }, "pagination": { "type": "object", "description": "Cursor pagination metadata." } }, "additionalProperties": true } },
+  { operationId: "listCatalog", toolName: "cueframe_api_listCatalog", title: "List Catalog", method: "GET", pathTemplate: "/v1/components", pathParams: [], queryParams: [{ "name": "category", "required": false, "description": "Filter to one category bucket (text|effects|transitions|layouts|backgrounds|ui-blocks|scenes).", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "enum": ["text", "effects", "transitions", "layouts", "backgrounds", "ui-blocks", "scenes"] } }, { "name": "kind", "required": false, "description": "Filter by render kind (component|transition|scene).", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "enum": ["component", "transition", "scene"] } }, { "name": "tier", "required": false, "description": "Filter by curation tier (recommended|standard|niche).", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "enum": ["recommended", "standard", "niche"] } }, { "name": "useCase", "required": false, "description": "Filter to entries whose useCase includes this edit role (e.g. intro, title-over-footage, grade).", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "enum": ["intro", "outro", "full-scene", "title-over-footage", "transition", "background", "grade", "emphasis", "explainer", "social-cut"] } }, { "name": "mood", "required": false, "description": "Filter to entries whose mood tags include this value (e.g. cinematic, minimal).", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "q", "required": false, "description": "Free-text match across id/name/description/intent/useWhen/tags/mood. Recommend-orders results.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "intent", "required": false, "description": "Alias of `q` framed as recommend-by-intent (e.g. intent=intro). Recommend-orders results.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "limit", "required": false, "description": "Page size (1..100). Omit to return the whole filtered catalog in one page.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from a previous page's nextCursor (forward-only).", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }], bodyKey: null, description: "List component catalog (defaults + installed) \u2014 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 \u2014 pass `limit` only to page. Each entry carries a `placement` hint telling you exactly how to author it on the timeline. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "data": { "type": "array" }, "pagination": { "type": "object", "description": "Cursor pagination metadata." }, "brandTokens": { "type": "array", "description": "Catalog-level reference: the valid `$brand:` token refs a param value may carry (e.g. accentColor: \"$brand:colors.accent\"). Colors + fonts are the common bindings; the full design-token vocabulary is listed. Derived from the brand kit resolver so it can't drift. See each entry's `brandBindings` for which params are brand-bound by default." }, "sfx": { "type": "array", "description": "Catalog-level reference: the curated CC0 SFX pack (closed, versioned). The compose sfx pass places these deterministically; this is the pack-only structural inventory to pick a `soundId` by family. Present on the first page only." }, "audio": { "type": "array", "description": `The UNIFIED org sound palette (audio-substrate Phase 2): the curated packs (SFX + music beds) unioned with THIS org's own uploads/imports (source:"org") and generated audio (source:"generated"), one uniform entry shape carrying role + envelopeClass + provenance + license; music entries carry bpm. Prefer an org sound when it fits \u2014 an org that uploads its product's real UI sounds hears ITS product. Present on the first page only.` } }, "additionalProperties": true } },
+  { operationId: "listCheckpoints", toolName: "cueframe_api_listCheckpoints", title: "List Checkpoints", method: "GET", pathTemplate: "/v1/checkpoints", pathParams: [], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "composeJobId", "required": false, "description": "Scope to ONE compose run \u2014 its v1\u2192vN gate history with per-version status and decisions.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "projectId", "required": false, "description": "Scope to everything reviewable in one project.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }], bodyKey: null, description: "List checkpoints (scope to a compose job or project) \u2014 The version stack of approval packets, newest first. Scope with ?composeJobId= to see one run's gate history (v1\u2192vN with per-version status + decisions) or ?projectId= for everything reviewable in a project. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "data": { "type": "array" }, "pagination": { "type": "object", "description": "Cursor pagination metadata." } }, "additionalProperties": true } },
+  { operationId: "listComposeJobs", toolName: "cueframe_api_listComposeJobs", title: "List Compose Jobs", method: "GET", pathTemplate: "/v1/projects/{id}/compose/jobs", pathParams: ["id"], queryParams: [], bodyKey: null, description: "List recent compose jobs for a project \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "jobs": { "type": "array" } }, "additionalProperties": true } },
+  { operationId: "listCompositions", toolName: "cueframe_api_listCompositions", title: "List Compositions", method: "GET", pathTemplate: "/v1/projects/{id}/compositions", pathParams: ["id"], queryParams: [], bodyKey: null, description: "List a project's compositions \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "data": { "type": "array" } }, "additionalProperties": true } },
+  { operationId: "listCritics", toolName: "cueframe_api_listCritics", title: "List Critics", method: "GET", pathTemplate: "/v1/critics", pathParams: [], queryParams: [], bodyKey: null, description: "List registered critics (Profile family) \u2014 Every enabled critic: id, label, tier, phase, floor, and reference media. Rubric text, rules, and evaluator URLs are write-only \u2014 registration config comes back, payloads don't. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "critics": { "type": "array" } }, "additionalProperties": true } },
+  { operationId: "listMedia", toolName: "cueframe_api_listMedia", title: "List Media", method: "GET", pathTemplate: "/v1/media", pathParams: [], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "kind", "required": false, "description": "Filter to one media kind.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "enum": ["video", "audio", "image", "gif", "asset", "source", "stock"] } }, { "name": "source", "required": false, "description": "Filter by how the item entered the library.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "enum": ["upload", "generated", "import-url", "stock"] } }, { "name": "tag", "required": false, "description": "Filter to items carrying this EXACT tag (not a prefix or substring match).", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }], bodyKey: null, description: "List media items \u2014 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. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "data": { "type": "array" }, "pagination": { "type": "object", "description": "Cursor pagination metadata." } }, "additionalProperties": true } },
+  { operationId: "listMediaFacts", toolName: "cueframe_api_listMediaFacts", title: "List Media Facts", method: "GET", pathTemplate: "/v1/media/{id}/facts", pathParams: ["id"], queryParams: [{ "name": "kind", "required": false, "description": "Resolve one exact editor prerequisite. Requires startSec and endSec; the response includes the server-selected `exact` result.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "enum": ["subjectTrack", "matte"] } }, { "name": "startSec", "required": false, "description": "Source-in of the clip's trim, in seconds. Must be sent WITH endSec \u2014 one without the other is a 400, never a silent whole-source default.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "number" } }, { "name": "endSec", "required": false, "description": "Source-out of the clip's trim, in seconds. Must be sent WITH startSec.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "number" } }], bodyKey: null, description: "List derived facts for a media item, with quotes for what is missing \u2014 The enhancement menu. `facts` is everything expensive we have already computed about this source \u2014 subject tracks, mattes \u2014 with its status, a small summary a caller can act on without fetching the artifact, and `charge` (what it was billed; absent when it cost nothing, e.g. a matte produced as a side effect of a compose you already paid for, or one delivered below the behind-subject presence floor). `offers` is what is NOT present yet, with a real server quote. A matte is offered ONLY when you pass `startSec`+`endSec` \u2014 the clip's SOURCE window \u2014 because a matte's price is a function of its duration and a whole-source quote for a three-second clip is not a price. Pass the window from the editor and you get a per-clip matte quote plus the status of that window's matte; omit it from the library and you get everything except the matte. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "facts": { "type": "array" }, "offers": { "type": "array", "description": "What is NOT yet present and could be bought. A `matte` offer appears ONLY when the request carried `startSec`+`endSec` (the clip's SOURCE window) \u2014 a matte's price is a function of its duration, so there is no honest whole-source matte quote. `transcript` is never offered: it is produced by the ingest pipeline, not bought here." }, "exact": { "type": "object", "description": "The server-selected fact or offer for one exact source window. Present when kind, startSec, and endSec are supplied; clients consume this instead of recreating the fact hash." } }, "additionalProperties": true } },
+  { operationId: "listMediaSuggestions", toolName: "cueframe_api_listMediaSuggestions", title: "List Media Suggestions", method: "GET", pathTemplate: "/v1/media/{id}/suggestions", pathParams: ["id"], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "platform", "required": false, "description": "Only suggestions cut for this delivery platform.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "format", "required": false, "description": "Only suggestions in this output format.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "topic", "required": false, "description": "Only suggestions matching this topic label.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }], bodyKey: null, description: "List clip suggestions for a media item \u2014 Required permission: media:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "status": { "type": "string", "enum": ["idle", "generating", "completed", "failed"] }, "createdAt": { "type": "string" }, "analyzedAt": { "type": "string" }, "jobId": { "type": "string" }, "topics": { "type": "array" }, "suggestions": { "type": "array" }, "pagination": { "type": "object", "description": "Cursor pagination metadata." } }, "additionalProperties": true } },
+  { operationId: "listProjectRenders", toolName: "cueframe_api_listProjectRenders", title: "List Project Renders", method: "GET", pathTemplate: "/v1/projects/{id}/renders", pathParams: ["id"], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }, { "name": "status", "required": false, "description": "Comma-separated render statuses to include (e.g. `error,cancelled`). Omit for every status.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }], bodyKey: null, description: "List renders for a project \u2014 Required permission: renders:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "data": { "type": "array" }, "pagination": { "type": "object", "description": "Cursor pagination metadata." } }, "additionalProperties": true } },
+  { operationId: "listProjects", toolName: "cueframe_api_listProjects", title: "List Projects", method: "GET", pathTemplate: "/v1/projects", pathParams: [], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }], bodyKey: null, description: "List projects \u2014 Required permission: projects:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "data": { "type": "array" }, "pagination": { "type": "object", "description": "Cursor pagination metadata." } }, "additionalProperties": true } },
+  { operationId: "listRenderFonts", toolName: "cueframe_api_listRenderFonts", title: "List Render Fonts", method: "GET", pathTemplate: "/v1/fonts", pathParams: [], queryParams: [], bodyKey: null, description: "List the font faces the renderer can actually draw \u2014 The renderer's admitted font set: per family the exact name authoring accepts, the weight ranges a shipped file declares, the styles bytes exist for, the caption default weights, and whether the bytes are bundled or an aliased metric-compatible stand-in. Choose from here and validate_composition will not refuse the face. Unlike POST /fonts/search (which searches the GOOGLE catalog) this is what the render page can rasterize. `manifestVersion` identifies the exact table and moves only when the admitted set does. Covers the BUNDLED set only \u2014 a brand kit's sealed faces are per-org and per-render, and a real italic can come only from one. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "manifestVersion": { "type": "string", "description": "Identifies this exact face table. Derived from the table's own content, so it moves when and only when the admitted set moves. Record it beside a composition to state which face table a font choice was validated against." }, "families": { "type": "array" } }, "additionalProperties": true } },
+  { operationId: "listSelectorCandidates", toolName: "cueframe_api_listSelectorCandidates", title: "List Selector Candidates", method: "GET", pathTemplate: "/v1/projects/{id}/selector/candidates", pathParams: ["id"], queryParams: [{ "name": "groupId", "required": true, "description": "The synced-angle group to score.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "minLength": 1 } }], bodyKey: null, description: "List switch (multicam) candidates + recommendation for a synced-angle group \u2014 Required permission: media:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "projectId": { "type": "string" }, "groupId": { "type": "string" }, "selectorVersion": { "type": "string" }, "signalVersions": { "type": "object" }, "moments": { "type": "array" }, "recommendation": { "type": "object" }, "divergesFromComposition": { "type": "boolean" } }, "additionalProperties": true } },
+  { operationId: "listSessions", toolName: "cueframe_api_listSessions", title: "List Sessions", method: "GET", pathTemplate: "/v1/sessions", pathParams: [], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }], bodyKey: null, description: "List sessions \u2014 Required permission: sessions:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "data": { "type": "array" }, "pagination": { "type": "object", "description": "Cursor pagination metadata." } }, "additionalProperties": true } },
+  { operationId: "listSkills", toolName: "cueframe_api_listSkills", title: "List Skills", method: "GET", pathTemplate: "/v1/skills", pathParams: [], queryParams: [], bodyKey: null, description: "List available CueFrame agent skills \u2014 Returns the agent skills CueFrame publishes (e.g. `cueframe-cli`). Metadata only \u2014 fetch the markdown body from GET /skills/{name}. Unauthenticated, like /openapi.json. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "skills": { "type": "array" } }, "additionalProperties": true } },
+  { operationId: "listWebhooks", toolName: "cueframe_api_listWebhooks", title: "List Webhooks", method: "GET", pathTemplate: "/v1/webhooks", pathParams: [], queryParams: [{ "name": "limit", "required": false, "description": "Page size (1..100), default 20. Out-of-range or unparseable clamps into the range.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "required": false, "description": "Opaque cursor from the previous page's `pagination.nextCursor`. Forward-only.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string" } }], bodyKey: null, description: "List webhook endpoints \u2014 Required permission: webhooks:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "data": { "type": "array" }, "pagination": { "type": "object", "description": "Cursor pagination metadata." } }, "additionalProperties": true } },
   { operationId: "newComposition", toolName: "cueframe_api_newComposition", title: "New Composition", method: "POST", pathTemplate: "/v1/projects/{id}/compositions", pathParams: ["id"], queryParams: [], bodyKey: "newCompositionBody", description: "Create a new composition (video) in a project \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "openComposeSessionBody", description: "Open an isolated scratch composition \u2014 Mint isolated scratch state for project authoring. This returns immediately and starts no sandbox or render provider; use /preview-frame-jobs and /score-composition for durable preview and verification work. The scratch closes automatically after its idle TTL or explicitly via DELETE. Optionally seed it from a supplied composition (seedComposition); a bodyless open derives from the project's active composition. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "patchProjectBody", description: "Update a project \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "patchWebhookBody", description: "Update a webhook endpoint \u2014 Required permission: webhooks:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "previewClipBody", description: "Render a scoped motion preview of the composition \u2014 A cheap, watchable MP4 of ONLY [fromSec, toSec) of the composition at preview quality (capped resolution, lighter encode). The way to judge motion \u2014 a cut, a transition, a component's animation \u2014 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. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "previewComponentBody", description: "Render one component preview \u2014 Queue a preview of ONE org-installed component. It returns the SAME content-addressed VP9-alpha motion clip the production render composites. Returns a jobId \u2014 wait_job(kind='preview') for the artifact. Compile/runtime failures land on the job terminal with the sanitized author-fixable message. \u2014 Advanced (expert layer) \u2014 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: "previewFrameJob", toolName: "cueframe_api_previewFrameJob", title: "Preview Frame Job", method: "POST", pathTemplate: "/v1/projects/{id}/preview-frame-jobs", pathParams: ["id"], queryParams: [], bodyKey: "previewFrameJobBody", description: "Queue still-frame evidence for a composition \u2014 Resolve and freeze the exact authored target, then queue durable still capture. Returns immediately; poll the generic job with wait_job(kind='preview_frame'). One successful request is one compose_capture operation regardless of timestamp count. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "previewSelectorBody", description: "Re-resolve a switch advisory under a hand-supplied policy (A/B taste; not persisted) \u2014 Required permission: media:read \u2014 Advanced (expert layer) \u2014 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: "purchaseMediaFact", toolName: "cueframe_api_purchaseMediaFact", title: "Purchase Media Fact", method: "POST", pathTemplate: "/v1/media/{id}/facts", pathParams: ["id"], queryParams: [], bodyKey: "purchaseMediaFactBody", description: "Buy a derived fact (subject track or behind-subject matte) \u2014 Purchases one enhancement for this source. `matte` REQUIRES `intent:{startSec,endSec}` \u2014 the clip's SOURCE window \u2014 because a matte's cost scales with its duration. For `subjectTrack` the same `intent` is OPTIONAL: give the clip's source window to buy the track the render will look up for THAT clip (and pay only for its duration); omit it for the whole source. If the fact already exists (pending or ready) this returns it with `alreadyExisted:true` and charges nothing. Charging happens on DELIVERY, never here: a job that never lands is never billed. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "openComposeSessionBody", description: "Open an isolated scratch composition \u2014 Mint isolated scratch state for project authoring. This returns immediately and starts no sandbox or render provider; use /preview-frame-jobs and /score-composition for durable preview and verification work. The scratch closes automatically after its idle TTL or explicitly via DELETE. Optionally seed it from a supplied composition (seedComposition); a bodyless open derives from the project's active composition. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "sessionId": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "patchProject", toolName: "cueframe_api_patchProject", title: "Patch Project", method: "PATCH", pathTemplate: "/v1/projects/{id}", pathParams: ["id"], queryParams: [], bodyKey: "patchProjectBody", description: "Update a project \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "format": {}, "brandKitId": { "type": "string" }, "activeCompositionId": { "type": "string" }, "composition": { "type": "object", "description": "Summary of a project's stored composition." }, "lastRender": { "description": "Most recent render for a project, if any." }, "webUrl": { "type": "string", "description": "A browser URL that opens THIS project, or null when CueFrame exposes no web view for a project. Null today: the console serves account surfaces (keys, usage, billing) and has no per-project page, so there is no link to give. Do NOT synthesise one \u2014 a guessed console path 404s. Show the user rendered output (create_render \u2192 outputUrl) or a preview still instead. This field becoming non-null is the signal that a real project view exists." }, "createdAt": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "patchWebhook", toolName: "cueframe_api_patchWebhook", title: "Patch Webhook", method: "PATCH", pathTemplate: "/v1/webhooks/{id}", pathParams: ["id"], queryParams: [], bodyKey: "patchWebhookBody", description: "Update a webhook endpoint \u2014 Required permission: webhooks:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array" }, "settleMs": { "type": "integer" }, "enabled": { "type": "boolean" }, "verificationStatus": { "type": "string", "description": "pending = callback URL has not echoed the ownership challenge (receives no events); verified = ownership proven.", "enum": ["pending", "verified"] }, "createdAt": { "type": "string" }, "lastDeliveredAt": { "type": "string" }, "lastFailedAt": { "type": "string" }, "consecutiveFailures": { "type": "integer" } }, "additionalProperties": true } },
+  { operationId: "previewClip", toolName: "cueframe_api_previewClip", title: "Preview Clip", method: "POST", pathTemplate: "/v1/projects/{id}/preview-clip", pathParams: ["id"], queryParams: [], bodyKey: "previewClipBody", description: "Render a scoped motion preview of the composition \u2014 A cheap, watchable MP4 of ONLY [fromSec, toSec) of the composition at preview quality (capped resolution, lighter encode). The way to judge motion \u2014 a cut, a transition, a component's animation \u2014 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. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["queued", "pending", "rendering", "complete", "error", "cancelled"] }, "progress": { "type": "object", "description": "Non-terminal render progress; phase is one of the worker's emitted stages." }, "outputUrl": { "type": "string" }, "outputExpiresAt": { "type": "string" }, "error": { "type": "string", "description": "Human-readable failure message. Pair with `errorCode` for a stable, machine-readable code an agent runner can branch on." }, "errorCode": { "type": "string", "description": "Stable, machine-readable error code (e.g. `render_pipeline_unavailable`, `render_route_missing`, `render_pipeline_failed`). Null when status is not `error` or unavailable for an older render." }, "errorDetails": { "description": "Structured failure context \u2014 `{ targetUrl?, upstreamStatus?, upstreamCode?, attemptedAt? }`. Surfaced so agent runners can distinguish operator-config issues from upstream-down vs route-missing without parsing `error`." }, "category": { "description": "Failure taxonomy when status is `error`; null otherwise. `authoring` = deterministic defect in YOUR composition/request \u2014 fix it, retrying is futile; `transient` = temporary pipeline/infra failure \u2014 safe to retry_render; `internal` = unexpected server fault \u2014 retry once then escalate. Mirrors the render.failed webhook's `category`." }, "retryable": { "type": "boolean", "description": "Whether re-attempting the SAME render can succeed (status `error`); null otherwise. true \u2192 call retry_render. false \u2192 deterministic (category authoring/internal); fix the composition first \u2014 retry_render alone reproduces it. Mirrors the render.failed webhook's `retryable`." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the render's most recent progress update. Compute staleness = now \u2212 updatedAt to distinguish a wedged render from a slow one and decide whether to wait, cancel, or retry." }, "listUsd": { "type": "number", "description": "A2 money stamp: the metered event's LIST price (USD), stamped at the success terminal (exports for deliverable renders, compose_capture for A8 previews). A plan allowance may zero the actual invoice line \u2014 this is the list price, never a Stripe charge. Absent while running, on failure, and for x402 orgs (on-chain receipts). Mirrors the get_usage ledger." }, "warnings": { "type": "array", "description": "Non-fatal advisories surfaced at render-CREATE (omitted when none, and on GET \u2014 create-time only)." } }, "additionalProperties": true } },
+  { operationId: "previewComponent", toolName: "cueframe_api_previewComponent", title: "Preview Component", method: "POST", pathTemplate: "/v1/projects/{id}/component-preview", pathParams: ["id"], queryParams: [], bodyKey: "previewComponentBody", description: "Render one component preview \u2014 Queue a preview of ONE org-installed component. It returns the SAME content-addressed VP9-alpha motion clip the production render composites. Returns a jobId \u2014 wait_job(kind='preview') for the artifact. Compile/runtime failures land on the job terminal with the sanitized author-fixable message. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "jobId": { "type": "string", "description": "Poll GET /v1/jobs/{jobId} / wait_job until terminal." }, "jobKey": { "type": "string", "description": "Deterministic identity of the work (content hash of every input the result depends on). Re-enqueueing the same key returns the same job while it runs; a failed key revives as a fresh attempt." }, "kind": { "type": "string", "description": "Job family, e.g. `verify` | `preview` | `brand_kit_extract`." }, "status": { "type": "string", "description": "running on a fresh/deduped enqueue; succeeded when an identical request already completed. Cancelled is part of the shared status vocabulary; identical cancelled work revives to running.", "enum": ["running", "succeeded", "cancelled"] } }, "additionalProperties": true } },
+  { operationId: "previewFrameJob", toolName: "cueframe_api_previewFrameJob", title: "Preview Frame Job", method: "POST", pathTemplate: "/v1/projects/{id}/preview-frame-jobs", pathParams: ["id"], queryParams: [], bodyKey: "previewFrameJobBody", description: "Queue still-frame evidence for a composition \u2014 Resolve and freeze the exact authored target, then queue durable still capture. Returns immediately; poll the generic job with wait_job(kind='preview_frame'). One successful request is one compose_capture operation regardless of timestamp count. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "jobId": { "type": "string", "description": "Poll GET /v1/jobs/{jobId} / wait_job until terminal." }, "jobKey": { "type": "string", "description": "Deterministic identity of the work (content hash of every input the result depends on). Re-enqueueing the same key returns the same job while it runs; a failed key revives as a fresh attempt." }, "kind": { "type": "string", "description": "Job family, e.g. `verify` | `preview` | `brand_kit_extract`." }, "status": { "type": "string", "description": "running on a fresh/deduped enqueue; succeeded when an identical request already completed. Cancelled is part of the shared status vocabulary; identical cancelled work revives to running.", "enum": ["running", "succeeded", "cancelled"] } }, "additionalProperties": true } },
+  { operationId: "previewSelector", toolName: "cueframe_api_previewSelector", title: "Preview Selector", method: "POST", pathTemplate: "/v1/projects/{id}/selector/preview", pathParams: ["id"], queryParams: [], bodyKey: "previewSelectorBody", description: "Re-resolve a switch advisory under a hand-supplied policy (A/B taste; not persisted) \u2014 Required permission: media:read \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "projectId": { "type": "string" }, "groupId": { "type": "string" }, "selectorVersion": { "type": "string" }, "signalVersions": { "type": "object" }, "moments": { "type": "array" }, "recommendation": { "type": "object" }, "divergesFromComposition": { "type": "boolean" } }, "additionalProperties": true } },
+  { operationId: "purchaseMediaFact", toolName: "cueframe_api_purchaseMediaFact", title: "Purchase Media Fact", method: "POST", pathTemplate: "/v1/media/{id}/facts", pathParams: ["id"], queryParams: [], bodyKey: "purchaseMediaFactBody", description: "Buy a derived fact (subject track or behind-subject matte) \u2014 Purchases one enhancement for this source. `matte` REQUIRES `intent:{startSec,endSec}` \u2014 the clip's SOURCE window \u2014 because a matte's cost scales with its duration. For `subjectTrack` the same `intent` is OPTIONAL: give the clip's source window to buy the track the render will look up for THAT clip (and pay only for its duration); omit it for the whole source. If the fact already exists (pending or ready) this returns it with `alreadyExisted:true` and charges nothing. Charging happens on DELIVERY, never here: a job that never lands is never billed. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "factId": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "ready", "failed"] }, "quotedUsd": { "type": "number" }, "alreadyExisted": { "type": "boolean", "description": "True when this exact fact was already pending or ready. Nothing was dispatched and nothing will be charged." } }, "additionalProperties": true } },
   { operationId: "putComposition", toolName: "cueframe_api_putComposition", title: "Put Composition", method: "PUT", pathTemplate: "/v1/projects/{id}/composition", pathParams: ["id"], queryParams: [], bodyKey: "putCompositionBody", description: "Replace a project's composition \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Record a hosted review decision (the same resume rail) \u2014 Record approve / revise / abandon from the hosted page. Server-side this IS POST /v1/checkpoints/{id}/resume \u2014 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). \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Refresh a render's output URL \u2014 Required permission: renders:write \u2014 Advanced (expert layer) \u2014 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: "recordReviewDecision", toolName: "cueframe_api_recordReviewDecision", title: "Record Review Decision", method: "POST", pathTemplate: "/v1/review/{id}/decision", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Record a hosted review decision (the same resume rail) \u2014 Record approve / revise / abandon from the hosted page. Server-side this IS POST /v1/checkpoints/{id}/resume \u2014 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). \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "ok": { "type": "boolean" }, "stage": { "type": "string", "enum": ["content", "layout", "motion"] }, "version": { "type": "integer" }, "composeJobId": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "refreshRenderUrl", toolName: "cueframe_api_refreshRenderUrl", title: "Refresh Render Url", method: "POST", pathTemplate: "/v1/projects/{id}/renders/{renderId}/refresh-url", pathParams: ["id", "renderId"], queryParams: [], bodyKey: null, description: "Refresh a render's output URL \u2014 Required permission: renders:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "outputUrl": { "type": "string" }, "outputExpiresAt": { "type": "string" } }, "additionalProperties": true } },
   { operationId: "resetMediaSuggestions", toolName: "cueframe_api_resetMediaSuggestions", title: "Reset Media Suggestions", method: "DELETE", pathTemplate: "/v1/media/{id}/suggestions", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Reset clip suggestions for a media item \u2014 Required permission: media:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "resumeCheckpointBody", description: "Answer a held checkpoint (approve / revise / abandon) \u2014 The A1 review grammar: one `decision` for the gate, optionally carrying anchored `comments` ({beatId} or {timecodeMs} anchors; per-anchor verdict approve|revise|lock \u2014 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 \u2014 beyond them, revise is refused 402 with the path forward. `abandon` ends the run. Approve-with-comments is legal: the notes record without gating. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Re-render against an existing renderJob's snapshot \u2014 Required permission: renders:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "scoreCompositionBody", description: "Score a composition (the standalone sighted judge) \u2014 Queue the server-side judge: it samples eval beats, renders them, and grades editorial/spatial/brand/caption (0\u201310 + weighted composite + worst-first critique). Your REGISTERED CRITICS run too (register_critic) \u2014 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 \u2014 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 \u2014 nothing to open, warm or close; the compose_verify meter fires on the job's success terminal. \u2014 Advanced (expert layer) \u2014 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: "scoreTrace", toolName: "cueframe_api_scoreTrace", title: "Score Trace", method: "POST", pathTemplate: "/v1/traces/{traceId}/scores", pathParams: ["traceId"], queryParams: [], bodyKey: "scoreTraceBody", description: "Attach production scores to one of your director traces \u2014 Record 1\u201310 named scores (0..1) on a trace the CueFrame gateway produced for YOUR director run \u2014 the trace id is the `trace_id` the client stamped on that run's requests. Only the trace's own user may score it; any other trace id answers 404. Scores are accepted asynchronously and acknowledged with 202. Free. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "searchFontsBody", description: "Search web font families by name/style \u2014 Search the Google Fonts web-font catalog by keyword. Returns matching font families (family name + category + available variants + a css2 stylesheet URL). DISCOVERY ONLY, and this is NOT the set the renderer can draw: a cloud render draws only the faces GET /v1/fonts lists, or a face sealed in a brand kit font asset. Naming any other family in captions/params fails validate_composition with font_not_reproducible. Read GET /v1/fonts to choose a family AND an admitted weight before authoring \u2014 it also states that no bundled family ships an italic. Read-only and free; results are cached server-side. An empty `results` array means no match (or the upstream catalog was unavailable). \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [{ "name": "q", "required": true, "description": "What the moment should look like, in plain language. Describe the IMAGE, not the words spoken.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "required": false, "description": "Maximum moments to return. Default 10, maximum 25.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } }], bodyKey: null, description: 'Semantic search over the org\'s own footage \u2014 Find MOMENTS in your library by describing what they look like. The query uses the same visual-semantic index as the footage, so it matches on visual content \u2014 "wide shot of a speaker at a whiteboard", "hands on a keyboard", "city skyline at dusk" \u2014 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 \u2014 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. The first search after an idle period can take up to ~90s; subsequent searches are typically faster. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "searchResourcesBody", description: "Search stock media (Pexels / Pixabay / Freesound / Klipy) \u2014 Search licensed stock media by keyword. Pass `query` for one search, or `queries[]` (\u226410) to run a batch in ONE call \u2014 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 default to Pexels; Pixabay is explicitly selectable; sfx \u2192 Freesound CC0-only; gif \u2192 Klipy); defaults to video. Returns ranked candidates each carrying an opaque `candidateId` \u2014 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` \u2014 impacts/ticks \u2248 0\u20132s, risers/whooshes \u2248 2\u20138s, ambients unbounded. For video, use minWidth/minHeight to exclude smaller renditions. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "selectComposeCandidateBody", description: "Promote a compose candidate to the active composition \u2014 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). \u2014 Advanced (expert layer) \u2014 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: "resumeCheckpoint", toolName: "cueframe_api_resumeCheckpoint", title: "Resume Checkpoint", method: "POST", pathTemplate: "/v1/checkpoints/{id}/resume", pathParams: ["id"], queryParams: [], bodyKey: "resumeCheckpointBody", description: "Answer a held checkpoint (approve / revise / abandon) \u2014 The A1 review grammar: one `decision` for the gate, optionally carrying anchored `comments` ({beatId} or {timecodeMs} anchors; per-anchor verdict approve|revise|lock \u2014 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 \u2014 beyond them, revise is refused 402 with the path forward. `abandon` ends the run. Approve-with-comments is legal: the notes record without gating. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true } },
+  { operationId: "retryRender", toolName: "cueframe_api_retryRender", title: "Retry Render", method: "POST", pathTemplate: "/v1/projects/{id}/renders/{renderId}/retry", pathParams: ["id", "renderId"], queryParams: [], bodyKey: null, description: "Re-render against an existing renderJob's snapshot \u2014 Required permission: renders:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["queued", "pending", "rendering", "complete", "error", "cancelled"] }, "progress": { "type": "object", "description": "Non-terminal render progress; phase is one of the worker's emitted stages." }, "outputUrl": { "type": "string" }, "outputExpiresAt": { "type": "string" }, "error": { "type": "string", "description": "Human-readable failure message. Pair with `errorCode` for a stable, machine-readable code an agent runner can branch on." }, "errorCode": { "type": "string", "description": "Stable, machine-readable error code (e.g. `render_pipeline_unavailable`, `render_route_missing`, `render_pipeline_failed`). Null when status is not `error` or unavailable for an older render." }, "errorDetails": { "description": "Structured failure context \u2014 `{ targetUrl?, upstreamStatus?, upstreamCode?, attemptedAt? }`. Surfaced so agent runners can distinguish operator-config issues from upstream-down vs route-missing without parsing `error`." }, "category": { "description": "Failure taxonomy when status is `error`; null otherwise. `authoring` = deterministic defect in YOUR composition/request \u2014 fix it, retrying is futile; `transient` = temporary pipeline/infra failure \u2014 safe to retry_render; `internal` = unexpected server fault \u2014 retry once then escalate. Mirrors the render.failed webhook's `category`." }, "retryable": { "type": "boolean", "description": "Whether re-attempting the SAME render can succeed (status `error`); null otherwise. true \u2192 call retry_render. false \u2192 deterministic (category authoring/internal); fix the composition first \u2014 retry_render alone reproduces it. Mirrors the render.failed webhook's `retryable`." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the render's most recent progress update. Compute staleness = now \u2212 updatedAt to distinguish a wedged render from a slow one and decide whether to wait, cancel, or retry." }, "listUsd": { "type": "number", "description": "A2 money stamp: the metered event's LIST price (USD), stamped at the success terminal (exports for deliverable renders, compose_capture for A8 previews). A plan allowance may zero the actual invoice line \u2014 this is the list price, never a Stripe charge. Absent while running, on failure, and for x402 orgs (on-chain receipts). Mirrors the get_usage ledger." }, "warnings": { "type": "array", "description": "Non-fatal advisories surfaced at render-CREATE (omitted when none, and on GET \u2014 create-time only)." } }, "additionalProperties": true } },
+  { operationId: "scoreComposition", toolName: "cueframe_api_scoreComposition", title: "Score Composition", method: "POST", pathTemplate: "/v1/projects/{id}/score-composition", pathParams: ["id"], queryParams: [], bodyKey: "scoreCompositionBody", description: "Score a composition (the standalone sighted judge) \u2014 Queue the server-side judge: it samples eval beats, renders them, and grades editorial/spatial/brand/caption (0\u201310 + weighted composite + worst-first critique). Your REGISTERED CRITICS run too (register_critic) \u2014 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 \u2014 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 \u2014 nothing to open, warm or close; the compose_verify meter fires on the job's success terminal. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "jobId": { "type": "string", "description": "Poll GET /v1/jobs/{jobId} / wait_job until terminal." }, "jobKey": { "type": "string", "description": "Deterministic identity of the work (content hash of every input the result depends on). Re-enqueueing the same key returns the same job while it runs; a failed key revives as a fresh attempt." }, "kind": { "type": "string", "description": "Job family, e.g. `verify` | `preview` | `brand_kit_extract`." }, "status": { "type": "string", "description": "running on a fresh/deduped enqueue; succeeded when an identical request already completed. Cancelled is part of the shared status vocabulary; identical cancelled work revives to running.", "enum": ["running", "succeeded", "cancelled"] } }, "additionalProperties": true } },
+  { operationId: "scoreTrace", toolName: "cueframe_api_scoreTrace", title: "Score Trace", method: "POST", pathTemplate: "/v1/traces/{traceId}/scores", pathParams: ["traceId"], queryParams: [], bodyKey: "scoreTraceBody", description: "Attach production scores to one of your director traces \u2014 Record 1\u201310 named scores (0..1) on a trace the CueFrame gateway produced for YOUR director run \u2014 the trace id is the `trace_id` the client stamped on that run's requests. Only the trace's own user may score it; any other trace id answers 404. Scores are accepted asynchronously and acknowledged with 202. Free. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "accepted": { "type": "integer" } }, "additionalProperties": true } },
+  { operationId: "searchFonts", toolName: "cueframe_api_searchFonts", title: "Search Fonts", method: "POST", pathTemplate: "/v1/fonts/search", pathParams: [], queryParams: [], bodyKey: "searchFontsBody", description: "Search web font families by name/style \u2014 Search the Google Fonts web-font catalog by keyword. Returns matching font families (family name + category + available variants + a css2 stylesheet URL). DISCOVERY ONLY, and this is NOT the set the renderer can draw: a cloud render draws only the faces GET /v1/fonts lists, or a face sealed in a brand kit font asset. Naming any other family in captions/params fails validate_composition with font_not_reproducible. Read GET /v1/fonts to choose a family AND an admitted weight before authoring \u2014 it also states that no bundled family ships an italic. Read-only and free; results are cached server-side. An empty `results` array means no match (or the upstream catalog was unavailable). \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "results": { "type": "array" } }, "additionalProperties": true } },
+  { operationId: "searchLibrary", toolName: "cueframe_api_searchLibrary", title: "Search Library", method: "GET", pathTemplate: "/v1/media/search", pathParams: [], queryParams: [{ "name": "q", "required": true, "description": "What the moment should look like, in plain language. Describe the IMAGE, not the words spoken.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "required": false, "description": "Maximum moments to return. Default 10, maximum 25.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } }], bodyKey: null, description: 'Semantic search over the org\'s own footage \u2014 Find MOMENTS in your library by describing what they look like. The query uses the same visual-semantic index as the footage, so it matches on visual content \u2014 "wide shot of a speaker at a whiteboard", "hands on a keyboard", "city skyline at dusk" \u2014 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 \u2014 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. The first search after an idle period can take up to ~90s; subsequent searches are typically faster. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "results": { "type": "array", "description": "Matching moments, best first. Empty means nothing matched (when `indexing` is false) \u2014 the library was searched and came back empty-handed." }, "indexing": { "type": "boolean", "description": 'TRUE when some of the org\'s footage is NOT in the visual index yet \u2014 media that predates it, or is still processing. This is COVERAGE, not emptiness: it can be true ALONGSIDE results, and then it means "these are the best moments among what we have looked at so far", not "these are the best moments". An empty `results` with `indexing: true` means "not looked at yet", NOT "no match" \u2014 re-run the media through processing (reprocess) to index it, then search again. FALSE with empty `results` is a real miss: the library was searched and nothing matched.' } }, "additionalProperties": true } },
+  { operationId: "searchResources", toolName: "cueframe_api_searchResources", title: "Search Resources", method: "POST", pathTemplate: "/v1/resources/search", pathParams: [], queryParams: [], bodyKey: "searchResourcesBody", description: "Search stock media (Pexels / Pixabay / Freesound / Klipy) \u2014 Search licensed stock media by keyword. Pass `query` for one search, or `queries[]` (\u226410) to run a batch in ONE call \u2014 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 default to Pexels; Pixabay is explicitly selectable; sfx \u2192 Freesound CC0-only; gif \u2192 Klipy); defaults to video. Returns ranked candidates each carrying an opaque `candidateId` \u2014 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` \u2014 impacts/ticks \u2248 0\u20132s, risers/whooshes \u2248 2\u20138s, ambients unbounded. For video, use minWidth/minHeight to exclude smaller renditions. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "provider": { "type": "string", "enum": ["pexels", "pixabay", "freesound", "klipy"] }, "kind": { "type": "string", "enum": ["video", "photo", "sfx", "gif"] }, "candidates": { "type": "array" }, "results": { "type": "array" } }, "additionalProperties": true } },
+  { operationId: "selectComposeCandidate", toolName: "cueframe_api_selectComposeCandidate", title: "Select Compose Candidate", method: "POST", pathTemplate: "/v1/projects/{id}/compose/jobs/{composeJobId}/select", pathParams: ["id", "composeJobId"], queryParams: [], bodyKey: "selectComposeCandidateBody", description: "Promote a compose candidate to the active composition \u2014 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). \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "newCompositionEtag": { "type": "string" }, "mergeResult": { "type": "object" } }, "additionalProperties": true } },
   { operationId: "streamCompose", toolName: "cueframe_api_streamCompose", title: "Stream Compose", method: "GET", pathTemplate: "/v1/projects/{id}/compose/jobs/{composeJobId}/stream", pathParams: ["id", "composeJobId"], queryParams: [], bodyKey: null, description: "Stream compose progress (SSE) \u2014 Server-Sent Events stream emitting typed `compose_event` frames (per `2026-05-23-compose-api-contract.md` \xA7 SSE event types \u2014 job_started, candidate_phase_started, candidate_phase_evaluated, candidate_completed, critique_retry_started, winner_selected, job_completed, job_failed). The stream closes once the compose job reaches a terminal status. Required scope: projects:read \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Trigger clip-suggestion analysis \u2014 Analyze a video for its best short-form moments \u2014 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. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Fire a webhook.test delivery \u2014 Required permission: webhooks:write \u2014 Advanced (expert layer) \u2014 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: "triggerMatteBake", toolName: "cueframe_api_triggerMatteBake", title: "Trigger Matte Bake", method: "POST", pathTemplate: "/v1/media/{id}/matte", pathParams: ["id"], queryParams: [], bodyKey: "triggerMatteBakeBody", description: "Buy a behind-subject matte for one source window \u2014 Bakes the alpha matte that lets a graphic sit BEHIND the subject for a specific source window. The window is the clip's SOURCE trim (`startSec`/`endSec` in seconds into the underlying file), not timeline time, and it is required \u2014 a matte's cost scales with its duration. Async: poll `GET /media/{id}/facts` for the matte fact's status. If a matte for this exact window already exists (bought earlier, or baked by a compose that put a graphic behind the subject) this returns 200 with the existing state and charges NOTHING. `summary.presenceFraction` on the delivered fact is the viability signal: below 0.6 there is no reliable silhouette, and that matte is delivered free. \u2014 Advanced (expert layer) \u2014 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: "triggerMuxJob", toolName: "cueframe_api_triggerMuxJob", title: "Trigger Mux Job", method: "POST", pathTemplate: "/v1/sessions/{id}/mux-job", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Trigger mux-audio-onto-video workflow \u2014 Required permission: sessions:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [{ "name": "detector", "required": false, "description": "Which detector to run. Defaults to `face`; an unknown value is refused, never defaulted.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "enum": ["face", "person"] } }], bodyKey: null, description: "Trigger standalone subject/face detection \u2014 Required permission: media:write \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "updateBriefBody", description: "Edit a brief \u2014 Partial update. While an ACTIVE compose job references this brief the edit is refused (409 conflict) \u2014 finish, resume, or abandon the job first; the Director never has its input edited out from under it. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: "updateComponentBody", description: "Update an authored component \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: "validateCompositionBody", description: "Validate a composition body without saving it (dry-run) \u2014 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 \u2014 wire shape, primitive membership (unknown_primitive / custom_missing_sourcecode), required-param shape (invalid_primitive_params), clip\u2194track family (clip_source_track_mismatch), reframe coverage (reframe_coverage_gap), and font admission (font_not_reproducible: a caption/param face that is neither bundled nor sealed in a brand font asset) \u2014 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 \u2014 trim-bounds (media duration) and image/asset-on-video-track (media kind) \u2014 which can only be caught at save/render. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: 'Re-run webhook ownership verification \u2014 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 \u2014 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. \u2014 Advanced (expert layer) \u2014 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: [], queryParams: [], bodyKey: null, description: "Return the caller identity + permissions \u2014 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. \u2014 Advanced (expert layer) \u2014 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"], queryParams: [], bodyKey: null, description: "Trigger clip-suggestion analysis \u2014 Analyze a video for its best short-form moments \u2014 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. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "status": { "type": "string", "enum": ["queued", "running", "complete", "failed"] }, "alreadyRunning": { "type": "boolean" } }, "additionalProperties": true } },
+  { operationId: "testWebhook", toolName: "cueframe_api_testWebhook", title: "Test Webhook", method: "POST", pathTemplate: "/v1/webhooks/{id}/test", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Fire a webhook.test delivery \u2014 Required permission: webhooks:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "deliveryId": { "type": "string" }, "status": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "triggerMatteBake", toolName: "cueframe_api_triggerMatteBake", title: "Trigger Matte Bake", method: "POST", pathTemplate: "/v1/media/{id}/matte", pathParams: ["id"], queryParams: [], bodyKey: "triggerMatteBakeBody", description: "Buy a behind-subject matte for one source window \u2014 Bakes the alpha matte that lets a graphic sit BEHIND the subject for a specific source window. The window is the clip's SOURCE trim (`startSec`/`endSec` in seconds into the underlying file), not timeline time, and it is required \u2014 a matte's cost scales with its duration. Async: poll `GET /media/{id}/facts` for the matte fact's status. If a matte for this exact window already exists (bought earlier, or baked by a compose that put a graphic behind the subject) this returns 200 with the existing state and charges NOTHING. `summary.presenceFraction` on the delivered fact is the viability signal: below 0.6 there is no reliable silhouette, and that matte is delivered free. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "factId": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "ready", "failed"] }, "quotedUsd": { "type": "number", "description": "The server's price for this matte, in USD, quoted from the window duration." }, "alreadyExisted": { "type": "boolean", "description": "True when a matte for this exact window was already pending or ready. Nothing was dispatched and nothing will be charged." } }, "additionalProperties": true } },
+  { operationId: "triggerMuxJob", toolName: "cueframe_api_triggerMuxJob", title: "Trigger Mux Job", method: "POST", pathTemplate: "/v1/sessions/{id}/mux-job", pathParams: ["id"], queryParams: [], bodyKey: null, description: "Trigger mux-audio-onto-video workflow \u2014 Required permission: sessions:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "type": "string" }, "muxedItems": {}, "error": { "type": "string" }, "startedAt": { "type": "string" }, "completedAt": { "type": "string" } }, "additionalProperties": true } },
+  { operationId: "triggerSubjectDetection", toolName: "cueframe_api_triggerSubjectDetection", title: "Trigger Subject Detection", method: "POST", pathTemplate: "/v1/media/{id}/detect-subjects", pathParams: ["id"], queryParams: [{ "name": "detector", "required": false, "description": "Which detector to run. Defaults to `face`; an unknown value is refused, never defaulted.", "style": "form", "explode": true, "allowReserved": false, "schema": { "type": "string", "enum": ["face", "person"] } }], bodyKey: null, description: "Trigger standalone subject/face detection \u2014 Required permission: media:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "factId": { "type": "string", "description": "Opaque identifier for the derived fact." }, "status": { "type": "string", "description": "State of the fact right now. `ready` with `alreadyExisted` means the detection was already computed and is available immediately.", "enum": ["pending", "ready", "failed"] }, "quotedUsd": { "type": "number", "description": "The server's price for this detection, in USD, quoted from the source duration. Zero is charged when `alreadyExisted` is true." }, "alreadyExisted": { "type": "boolean", "description": "True when this exact detection was already pending or ready. Nothing was dispatched and nothing will be charged \u2014 the same fact is served twice for one price." } }, "additionalProperties": true } },
+  { operationId: "updateBrief", toolName: "cueframe_api_updateBrief", title: "Update Brief", method: "PATCH", pathTemplate: "/v1/briefs/{id}", pathParams: ["id"], queryParams: [], bodyKey: "updateBriefBody", description: "Edit a brief \u2014 Partial update. While an ACTIVE compose job references this brief the edit is refused (409 conflict) \u2014 finish, resume, or abandon the job first; the Director never has its input edited out from under it. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "kind": { "type": "string", "description": "authored = create_brief; clip = minted by suggest_briefs from an AI clip suggestion.", "enum": ["authored", "clip"] }, "sourceSuggestionId": { "type": "string", "description": "kind:'clip' provenance \u2014 the suggestion this Brief was minted from." }, "name": { "type": "string" }, "goal": { "type": "string", "description": "What the video must accomplish." }, "audience": { "type": "string" }, "platform": { "type": "string" }, "format": { "type": "object", "description": "Output-format spec per \xA7Format." }, "durationSec": { "type": "number", "description": "Target output duration. HONOR-OR-REFUSE: compose validates it against the beat-source window (\xB11.5s) and refuses a brief it cannot honor." }, "tone": { "type": "string" }, "cta": { "type": "string" }, "locale": { "type": "string", "description": "Output language (BCP-47 tag, e.g. 'es-419'): ALL on-screen copy + captions." }, "hook": { "type": "string" }, "caption": { "type": "string" }, "beats": { "type": "array" }, "mustIncludes": { "type": "array" }, "references": { "type": "array" }, "captions": { "type": "object" }, "motionStyle": { "type": "object" }, "seededGraphics": { "type": "array", "description": "Client-authored graphic clips the Director must carry VERBATIM: seeded into the design loop's base composition as LOCKED clips (never re-authored, never discarded)." }, "exclusions": { "type": "array" }, "gates": { "type": "object" }, "audio": { "type": "object" }, "quote": { "type": "object" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } }, "additionalProperties": true } },
+  { operationId: "updateComponent", toolName: "cueframe_api_updateComponent", title: "Update Component", method: "PUT", pathTemplate: "/v1/components/{id}", pathParams: ["id"], queryParams: [], bodyKey: "updateComponentBody", description: "Update an authored component \u2014 Required permission: projects:write \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "source": { "type": "string", "description": "'default' = built-in primitive (place by primitiveId); 'installed' = org-authored component (place by componentId).", "enum": ["default", "installed"] }, "category": { "type": "string", "enum": ["text", "effects", "transitions", "layouts", "backgrounds", "ui-blocks", "scenes"] }, "kind": { "type": "string", "description": "RENDER kind (component | transition | scene). NOT the ClipSource variant \u2014 see `placement` for how to author it on the timeline.", "enum": ["component", "transition", "scene"] }, "version": { "type": "string" }, "propSchema": { "type": "object" }, "propDefaults": { "type": "object" }, "textParam": { "type": "string", "description": "The param field that carries this primitive's primary text; null = no single text slot." }, "subtextParam": { "type": "string", "description": "The param field for secondary text (subtitle/byline); null = none." }, "format": { "type": "object" }, "durationInFrames": { "type": "number" }, "intent": { "type": "string", "description": "Selection signal: a verb naming what this primitive accomplishes (e.g. 'product-trailer'). Match it to the beat you are authoring." }, "useWhen": { "type": "string", "description": "When to use this \u2014 AND when not to. The negative guidance is load-bearing; read it before picking." }, "pairsWith": { "type": "array", "description": "Authoring guidance: ids of primitives that COMPOSE well with this one in the same edit." }, "avoidWith": { "type": "array", "description": "Authoring guidance: ids of primitives that CONFLICT with this one \u2014 do not place together." }, "tags": { "type": "array", "description": "Free-text search keywords." }, "mood": { "type": "array", "description": "Vibe/tone tags (e.g. 'cinematic', 'minimal'). Filter to match the edit's mood." }, "tier": { "type": "string", "description": "Quality/applicability RANKING (a preference, not a flag). Prefer 'recommended'; reach for 'niche' only when its specific use-case is exactly the beat.", "enum": ["recommended", "standard", "niche"] }, "useCase": { "type": "array", "description": "The edit ROLE(s) this primitive fills \u2014 the dimension to filter by for a beat (e.g. 'intro', 'title-over-footage', 'grade')." }, "examples": { "type": "array" }, "fixedCopy": { "type": "array", "description": "On-screen strings this primitive BAKES \u2014 the read-side counterpart to propSchema. These literals render REGARDLESS of params (no param can change them); fork the source via get_component_source to edit them. Use this to see at author time what fixed copy (someone-else's marketing text, faux-code, faux-data) will appear before you render." }, "brandBindings": { "type": "array", "description": "Params that can follow the project brand kit. Each {param, brandToken} says: set `param` to `brandToken` (a `$brand:` ref, e.g. '$brand:colors.accent') to track the brand instead of a literal. See the list response's `brandTokens` for the full ref vocabulary. Omitted when nothing is brand-bound." }, "placement": { "type": "object" }, "warnings": { "type": "array", "description": "Non-blocking save-time advisories \u2014 the create/update SUCCEEDED. Currently: a `fontFamily` string literal referencing a NON-vendored font (a bare CSS generic like 'serif', or an unknown named family like 'Arial') whose LIVE-lane pixels vary by render host \u2014 re-author with a vendored family or 'Georgia'. Omitted when there is nothing to flag; only present on the create/update responses." } }, "additionalProperties": true } },
+  { operationId: "validateComposition", toolName: "cueframe_api_validateComposition", title: "Validate Composition", method: "POST", pathTemplate: "/v1/composition/validate", pathParams: [], queryParams: [], bodyKey: "validateCompositionBody", description: "Validate a composition body without saving it (dry-run) \u2014 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 \u2014 wire shape, primitive membership (unknown_primitive / custom_missing_sourcecode), required-param shape (invalid_primitive_params), clip\u2194track family (clip_source_track_mismatch), reframe coverage (reframe_coverage_gap), and font admission (font_not_reproducible: a caption/param face that is neither bundled nor sealed in a brand font asset) \u2014 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 \u2014 trim-bounds (media duration) and image/asset-on-video-track (media kind) \u2014 which can only be caught at save/render. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array" }, "advisories": { "type": "array", "description": "Deterministic, render-free QUALITY floors (the SAME named defects the Director's in-loop verify and score_composition surface: static-hold, caption-spine, sfx-density, sfx-speech-collision, bed-coverage, audio-role). NON-blocking \u2014 they never flip `valid` (an editorially-weak composition still renders); fix them for quality, not to save. Empty when the composition is clean or the wire shape failed (they need a parsed composition)." }, "warnings": { "type": "array", "description": "Non-blocking render-fidelity warnings detected before enqueue, including unavailable font families." }, "quote": { "type": "object", "description": "The A2 money triple for the commodity lane: validate is free; estimatedJourneyTotalUsd is the render price to finish from a valid composition \u2014 relay it BEFORE create_render." } }, "additionalProperties": true } },
+  { operationId: "verifyWebhook", toolName: "cueframe_api_verifyWebhook", title: "Verify Webhook", method: "POST", pathTemplate: "/v1/webhooks/{id}/verify", pathParams: ["id"], queryParams: [], bodyKey: null, description: 'Re-run webhook ownership verification \u2014 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 \u2014 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. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "description": "active = ownership verified + receiving events; pending = challenge not echoed.", "enum": ["active", "pending"] }, "verification": { "type": "object", "description": "Present only when the re-challenge did not verify; `reason` names why (see WebhookCreateResponse.verification)." } }, "additionalProperties": true } },
+  { operationId: "whoami", toolName: "cueframe_api_whoami", title: "Whoami", method: "GET", pathTemplate: "/v1/whoami", pathParams: [], queryParams: [], bodyKey: null, description: "Return the caller identity + permissions \u2014 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. \u2014 Advanced (expert layer) \u2014 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 }, outputSchema: { "type": "object", "properties": { "orgId": { "type": "string" }, "permissions": { "type": "object" }, "keyId": { "type": "string" }, "keyName": { "type": "string" } }, "additionalProperties": true } }
 ];
 
 // ../mcp/src/x402Meta.ts