CueFrame

ORIENT FIRST — show THIS key's account before you spend a metered call: the org it is bound to, the current plan, a per-feature entitlements map, and per-call cost ceilings. READ `balance`, NOT `included`. CueFrame is credit-funded: rendering (entitlements.exports), generation (generate), preview stills (compose_capture), the judge (compose_verify) and the Director (compose) have NO separate per-plan allowance — they all spend one shared wallet, named in `fundedBy` (`credits`; generation is metered in provider-cost units against that wallet). Each `balance` restates that ONE wallet in that feature's own unit at `creditCost` credits per unit, so they are alternative ways to spend the same money, not four budgets. Each entitlement also carries `listUsdPerUnit`: the dollar quote for ONE unit before you call (0 = a plan grant that draws no credits, e.g. resource_import — stock search + import are free; null = not quotable up front). Check the requested cost against the balance. For generation, also check generationLimit: free accounts have a separate provider-cost cap even with a positive wallet. A billing_required error with reason free_generation_cap requires a credit-pack purchase through normal checkout. `included:false` means the plan genuinely lacks the feature. Every new org starts with a free credit grant, so an account with an empty usage history can still render, generate, preview and score. costCeilings.generateMediaUsdPerCall is the generate_media per-call USD cap. No args — identity is resolved from your key (never echoed from input).

Read a brief by id — the persisted intent plus its current quote (compose + estimated render).

Read a checkpoint packet — the durable approval unit a held compose pauses at (wait_job reports awaiting_input with {checkpointId, stage, version}). Carries the stage artifact, presigned storyboard stills (REVIEW THE EVIDENCE, not raw JSON), critic verdicts, the money triple {thisStepUsd, jobSpendSoFarUsd, estimatedJourneyTotalUsd} to relay to your human, and the recorded decision once resolved. When the Brief's gates set reviewMode:'hosted' the packet also carries reviewUrl — a browser review page where your human decides directly (relay THAT link instead of raw stills; you learn the decision via checkpoint webhooks / wait_job). Answer an awaiting packet with resume(checkpointId, ...).

Read an exact component source as complete JSON. Supply sourceVersionId from the selected catalog card to read that immutable revision, retaining sourceSnapshot with its complete versioned definition, manifest and template beside its exact pin and schema metadata. For an explicitly selected builtin, also supply builtinCollection:'native'|'curated-definitions' and its exact sourceVersionId; without builtinCollection resolution is scoped to the authenticated org. An unavailable exact pin refuses; never retry a head or another scope. To fork, keep the version-4 snapshot whole, change its componentId (the template root's data-composition-id too) and template, and send it to create_component. Builtins always require an exact collection and pin; ID-only builtin reads are refused. Declared slots are bound per placement in execution.assets, never caller params.

Read a compact structural composition view by default, preserving observed ETag, authority metadata, clip timing, token values and source pins without large HTML bodies. Ordinary exact-ETag reads can omit includeDependencies. With includeDependencies=true, compact returns a dependency key/size index, not executable tokens; these tokens can contain full sources. Request explicit dependencyKeys for exact selected tokens, or response:"full" for all tokens. Selection does not establish a sufficient operation basis. Use clipIds:[id] with response:"full" for complete exact selected sources; unknown IDs are refused. Use response:"full" without clipIds for the original full backend JSON. Local response/clipIds/dependencyKeys arguments never reach the backend. READ BACK a composition as JSON — the edit itself: tracks, clips, card HTML, reframe segments, captions, markers, format. This is what create_render encodes, so it is also what you hand to validate_composition (which needs a full inline composition body), what you diff after an edit, and what you archive/share so someone else can re-render the SAME video. Read-only and free. Authoring stays op-based (apply_composition) — do not round-trip this object back as a write. A composition too large for routine model context can be read selectively with clipIds and response:"full"; the compact view explicitly identifies omitted source bodies. Defaults to the project's ACTIVE composition; pass `compositionId` to read a specific one (the same id apply_composition takes as `composition_id`, and preview_frame / create_render take as compositionId) so an A/B variant can be read back, not just written. The result includes the exact HTTP etag string; copy it to apply_composition.body.if_match (the numeric revision is not an ETag). In a compose session this reads the session's scratch, the composition its edits, previews and renders target. Pass includeDependencies="true" on a v1 guarded endpoint to read composition_id, revision and d…

Fetch bounded authoring context for a media item: dimensions/thumbnail, compact face roster, transcript counts/sample, temporal grids, and fact readiness. Transcript and word-grid counts cover one page only (default 20 utterances); pass transcript.data.pagination.nextCursor as after to get_media_context for the next context page, or use get_transcript for exact paginated word timings.

Read prepared subject tracks and behind-subject mattes for one media item. For an exact readiness check, pass kind + startSec + endSec together using the same SOURCE window sent to prepare_media; exact.state is pending | ready | failed | available | unavailable. If subjectTrack was prepared without intent, omit all three filters and check the whole-source subjectTrack in facts instead. Wait for the required fact to be ready before preview_frame / score_composition.

The org's legible taste in ONE read: brand kits, registered critics (the machine-checkable standard both the Director's gates and score_composition enforce), their reference media (presigned thumbnails), the recent checkpoint-decision log, and the learned `taste` (style preferences saved with remember_taste). Read this BEFORE composing for an org you haven't worked with — it is the house style. Learned taste is advice: the current request, brief, project, brand kit, exclusions and critics take precedence; name any conflict.

Recover an organization-owned immutable acquisition receipt, exact raw/transformed file descriptors, bounded source text and an expiring archive link. Retain the bundle digest and distinguish original upstream bytes, installer transformations and later CueFrame adaptations. Binary/large files are explicitly identified; omitted text is not empty source. Foreign live references refuse. Saved provenance supports owned forks; it never grants compatibility, ownership of another organization’s objects, or a fresh rendered preview.

Inspect one exact external registry item manifest, including examples. Supply all snapshot fields returned by discovery together, or omit all to inspect current. Unknown upstream metadata is preserved. Inspect actual source and requirements before adaptation; an upstream poster/movie is unverified reference evidence. This read never invokes add/init or executes downloaded source. An example can be inspectable while its init acquisition remains explicitly unsupported.

Read ONE render's record without waiting on it: status, progress while it runs, outputUrl + outputExpiresAt once complete, the typed failure (errorCode / category / retryable) if it failed, and WHAT RENDERED — compositionId (the composition it froze), format (aspect/fps/resolution it encoded at), engine, createdAt / completedAt, outputDurationSec, and the preview window for a preview_clip. Free, read-only, instant — use it to audit or correlate a past render (which composition, when, how long) where wait_job would block; wait_job remains the way to block until a running render finishes. An expired outputUrl is refreshed with refresh_render_url.

Read a saved organization template by id or a known public catalog template by slug. The answer is a summary: the media and value parameters with their kinds and options, presets with their values and brand kit, the brand kit, rubric, components (id, version, asset slots) and an outline of the tracks and clips; never component sources (read one with get_component_source, or pass full: true for the whole document). Use the exact reference with start_template or apply_template. Do not invent a slug from a component-library card.

Read exact durable template preparation status. For library-import or library-export, ready means a saved organization template and destination-owned package receipt; projectId remains null. Preserve templateId/templateVersion, documentSha256 and package receipt; refresh its URL with get_template_package_download. Export sourceProjectId identifies the original saved project; projectId remains null. For ordinary instantiation/apply, read the returned projectId. Failed/cancelled states include the retained reason. Do not treat preparing as successful import.

Refresh the short-lived download URL for an exact organization-owned portable template package receipt. Supply the receiptId from a ready import/export template job. Server verifies retained immutable package/document authority; never pass bucket keys or arbitrary archive URLs. Project-bound editors must also pass the exact ready export jobId for their bound source project and this receipt; an unrelated job or receipt refuses.

Read exact source-time transcript words in bounded utterance pages. Word start/end values are seconds from the source media start. Default limit is 20; pass pagination.nextCursor as after for later pages. The formatter omits the unbounded fullText duplicate.

The A2 usage ledger: every metered billing event newest-first with attribution — featureId, amount, the project/job that produced it, and the event's LIST price in USD (a plan allowance may zero it on the invoice). Answer "what did project X cost this period?" with a query instead of summing your own quotes. Filter by projectId, jobId, and/or a [from, to) epoch-ms window. Requires the billing:read scope.

Import a media item into your library from a public URL — the agent-friendly ingest path (single call, no upload protocol). Pass url (https) + filename (+ optional contentType). Returns { id, status:"importing" }. Processing is async: call wait_job(kind="media", id=mediaItemId), or register a webhook (create_webhook on media.completed — status: complete|failed rides the payload). Use the returned id with get_media_context, suggest_briefs, or as a composition source.

Import a stock candidate (candidateId from search_resources) into a project as an ORG-OWNED media item — provider/externalId/license provenance preserved, bytes deduped across orgs. Pass projectId + candidateId. Returns { id, status:"importing"|"ready" }; processing is async — call wait_job(kind="media", id=mediaItemId), then use the returned id as a composition source. Gated on the resource_import plan feature (402 billing_required if your plan lacks it). COST: 0 credits — search and import are both free for a keyed caller (get_account → entitlements.resource_import.listUsdPerUnit is 0); imported bytes count toward the storage gauge. 422 candidate_mismatch if the candidate expired — re-run search_resources.

Import an uploaded portable template package using only uploadId and idempotencyKey. The reservation binds archive bytes and ownership; never supply storage keys, document bodies or provenance assertions. Optional destinationSlug/name creates an explicit fork. Updating an existing slug requires both expectedVersion and expectedDocumentSha256. Returns a durable library-import job; use get_template_job until ready. Read its destination templateId/templateVersion and package receipt. Organization-library operation; project-bound editor credentials are refused.

List briefs. DEFAULT shows human-authored briefs only; kind:"clip" shows the machine-minted clip briefs (suggest_briefs output), kind:"all" shows everything. Each carries its quote.

Use projection:'component-library' for the unified source-free library page, returned as complete JSON with exact scoped definition/preset/recipe cards and pagination. Choose origin:'builtin' for the maintained builtins or origin:'library' for the authenticated serving home; use libraryKind, category, q, limit and after to filter/page. Preserve each card identity.scope and identity.revision, its source/definition pin or exact recipe document identity; same names/IDs in different scopes remain distinct. Resolve the selected exact source with sourceVersionId (plus builtinCollection for an explicitly selected builtin), never a latest-head or another-home lookup. Presets identify their exact presetVersionId, definition pin and historical document witness; recipes identify their complete exact document and member source pins. This projection contains no source bodies or legacy thumbnail substitution. Omit projection for the historical catalog protocol below. DISCOVER WHAT TO BUILD WITH — list the component catalog: the one built-in primitive (heroText, the behind-subject overlay) plus your org-installed components. Desktop also includes bundled kind:'component-package' entries: these are complete reusable authored packages; insert them with the desktop apply_template tool using placement.template and explicit insert.startTime/idPrefix, media bindings and parameter values. Do not pass their ids to clip.add, get_component_source, or cueframe://component resources. Their draft status does not certify visual review or licensing. For hosted builtin preset/recipe cards, call resolve_builtin_component with the exact collection, id and revision, then apply_template with template:<builtin id> and body:{projectId,documentSha256,insert:{startTime,idPrefix},...}. Hosted tool request fields live under body; desktop tool shapes may differ. The agent-safe default page is 20 entries; use pagination.nextCursor as `after`, or narrow with category, kind, tier, useCase, mood, q, or intent.…

List checkpoint packets newest-first (filter with composeJobId for one run's v1→vN gate history, or projectId). The version stack with per-version status + decisions IS the review history — nothing is deleted.

List every composition (video) in a project, with its format and which one is active. Use a returned compositionId with create_render(compositionId=...) to render a specific video, or apply_composition to edit it.

List registered critics: criticId, label, tier (rules|rubric|evaluator), phase, floor, referenceMediaIds. Rubric text / rules / evaluator URLs are write-only — never echoed. Manage with register_critic (upsert) / delete_critic.

List the media in your CueFrame library. Filter a real library with kind (video|audio|image|gif|asset|source|stock), source (upload|generated|import-url|stock), or tag — so you find YOUR footage, not e2e debris. Returns media item IDs and metadata; use an ID with get_media_context, suggest_briefs, or as a composition source.

List the plan catalog (tiers, intervals, product ids, prices) BEFORE a checkout, so create_checkout requests a real {plan, interval} instead of guessing an id. No args — reads the platform catalog.

List your projects — re-orient in an existing workspace instead of minting duplicates (steady-state entry, A9). Each row carries the id every other tool needs.

The fonts the RENDERER can actually draw — read this BEFORE authoring type, not after a refusal. Per family: the exact family name authoring accepts, the weight RANGES a shipped file declares (a static face has min===max; a variable face gives its axis range), the caption default weights, and whether the bytes are bundled or an aliased metric-compatible stand-in. Anything listed here passes validation by construction: it is derived from the same table the font gate refuses by. Two facts worth reading off it — every family's `styles` is ["normal"], because NO bundled family ships an italic FILE (a real italic comes only from a brand-kit font asset), and a weight outside every range is REFUSED, never synthesised. Contrast search_fonts, which searches the GOOGLE catalog and will happily return families the renderer cannot draw. `manifestVersion` identifies this exact face table; record it beside a composition to state what a font choice was validated against. Covers the bundled set only — a brand kit's sealed faces are per-org and per-render. No args, read-only, free.

Read the org's learned taste: whether the owner has it on (`enabled`) and its saved entries, oldest first. While `enabled` is false, do not apply the entries. Learned taste is advice: the current request, brief, project, brand kit, exclusions and critics take precedence.

List this organization's saved templates. Follow pagination.nextCursor with after to read further pages. Public catalog slugs are not enumerated here; read a known public slug with get_template.

Create a NEW composition (a new video) inside a project — a project is a workspace that holds many videos. Returns { compositionId, format, etag }. Pass an optional name and format (aspectRatio/fps/resolution); format defaults to the project's compositionFormat. The first composition becomes the project's active default. To author it, seed with apply_composition then compose({ fromComposition: true }) — your authored graphics ride as locked clips, carried verbatim; to render a specific one, pass its compositionId to create_render. (For a reframed sibling in another aspect, use derive_composition.)

Prepare the perception artifact an authored edit needs BEFORE sighted review. Pass body.kind="subjectTrack" for face/active-speaker reframing, or body.kind="matte" for a true zPlane:"behind-subject" graphic. Pass body.intent {startSec,endSec} using SOURCE time (the media trim, not timeline time); it is required for mattes and strongly recommended for subject tracks so the prepared fact exactly matches the clip and quote. This is the supported product path — never accept a preview that silently flattens depth or ignores speaker tracking. Returns a fact receipt; with intent, poll get_media_facts using the same kind/window until exact.state is ready; without intent, omit all three filters and find the whole-source subjectTrack in facts until status is ready (failed is terminal). Existing pending/ready facts are reused without another charge.

Render ONE authored card on its own and SEE it, before placing it in a composition. Pass the same `html` (+ optional `tokens`) you would put in a {kind:"card"} clip; you get the still back as an image. Use this while writing a card — it is the fast loop for catching type that overflows the frame, a headline that collides with a logo, or tokens that did not resolve. Sized to the format you name, so what you see is what that aspect ratio will show. To judge MOTION rather than layout, shell the card with a motion preset and use preview_clip.

Render a scoped, cheap MOTION preview — ONLY body.fromSec→body.toSec of the composition (max 60s) at preview quality (capped resolution, lighter encode) through the real render pipeline. THE way to judge motion — a cut, a transition, a component's animation — at full fidelity BEFORE paying for a full render (a still cannot show motion; a full render costs the export). ASYNC: returns a render job; wait_job(kind="render", id=renderId) or a render.completed webhook for the URL. Meters the capture feature, never an exports credit.

Queue a typed preview artifact for ONE org-installed component — ASYNC: returns a jobId immediately; then wait_job(kind="preview", id=jobId). The preview and production compositor consume the same content-addressed component bundle and verified artifact contract. `body.componentId` selects the component; pass `body.params` to render it with props (the mount's `params`); declared manifest slots are bound separately and reach the scene's `assets`, never params. Admission/runtime/capability failures land on the job terminal with sanitized author-fixable messages. Idempotent per immutable render key.

Queue durable still-frame evidence for layout/copy judgment. Returns immediately with {jobId, kind:'preview_frame', status}; then call wait_job(kind="preview_frame", id=jobId) for artifact metadata and up to four embedded frame images; fetch failures or payload limits may return fewer. Use wait_job imageIndices to read other original image artifacts from the completed job, at most four indices per call, without rendering again. Repeating the same arguments repeats the same selection. Artifact URLs alone are not observed pixels. The immutable snapshot records geometry, layers, warnings, and whether the target was persisted, inline, or session scratch. A still cannot prove motion — use preview_clip or preview_component for animation.

Explicitly refresh external registry metadata: resolve moving main once to a full commit, then capture one coherent fixed inventory/manifest snapshot using the qualified client. Pass body:{commandId,expectedSnapshot,expectedRevision}; both expected values are null only for first selection. Preserve the observed snapshotRevision returned by current discovery and the exact snapshot as the CAS witness. Native author sessions inject their existing replay-stable top-level commandId. Stale head/revision refuses rather than rebasing silently. Refresh does not change customer sources, local forks or timeline placements. Preview/variable/dependency metadata changes remain separate, and actual source-byte differences require explicit acquisition before adaptation, review and guarded adoption.

Re-sign a COMPLETE render's output URL. A render's presigned MP4 link lasts ~7 days, so wait_job / getRender on an old render hands back a link that 403s; this mints a fresh one for the same file and returns { outputUrl, outputExpiresAt }. Needs projectId + renderId (from create_render). 422 render_not_complete while the render is still running or failed — wait_job for it first. Requires renders:write (the row's stored URL is updated).

Register a custom eval into the compose critic panel — the critic contract is { rubric (or rules/evaluator), referenceMediaIds?, floor }. Three tiers: rules (declarative constraints — keep-out regions, required elements, max overlays, brand colors), rubric (a text criterion scored by the judge as an extra column), or evaluator (your HTTPS webhook — CueFrame POSTs the composition+stills+facts, you return { score, critique }). referenceMediaIds (≤6 org media ids) attach YOUR reference frames as the standard — the judge scores candidates for consistency with them, so "indistinguishable from mine" is a machine check. Lane scope: rules + rubric critics run in BOTH lanes (the Director's gates AND standalone score_composition); evaluator webhooks run in the Director lane only. Use phase 'static' (the default) — 'temporal' (final-render evaluation) is accepted but not yet wired, so a temporal critic produces no verdicts today. A low client score drives a refine like a built-in criterion. You see your eval output + our scores, never our rubric. Re-registering the same criticId upserts (list_critics / delete_critic manage the set). Evaluator tier returns a signing secret ONCE.

Save one durable style preference to the org's learned taste, with its source (the job, checkpoint or chat, plus the date). Only for a preference the user stated: a revise comment, a chat correction or an explicit "remember this"; never one-off brief content, footage facts or secrets. Tell the user what you saved and that they can say undo (forget_taste). Saving text the org already holds changes nothing. Refused, never truncated, past 2,048 bytes per entry or 4,000 characters per org, or while the owner has learned taste off; a refusal is final. get_profile returns the saved entries as `taste`.