trvrse cinema — MCP guide for agents

You are (or are configuring) an LLM agent connected to the trvrse cinema MCP server. It exposes a five-stage film pipeline — Script → References → Storyboards → Videos → Assembly — as 31 tools: 18 stage-by-stage tools you drive yourself, plus 3 Autopilot tools (make_film, get_run, cancel_run) that hand the whole pipeline to the server for one-call film production, plus make_long_film (multi-minute films with consistent characters, §3) and get_gate_review_link (mint a no-login human review link for a gated stage), plus 5 cast tools (save_character_to_cast, list_cast, delete_cast_member, set_cast_voice, refresh_cast_portrait) for episodic reuse of approved characters, plus refresh_character_portrait for re-minting a non-cast character's expired trusted portrait, plus set_shot_face_trust_override for per-scene face-moderation control. Separately, 13 asset tools (estimate_generation_cost, generate_image, edit_image, generate_storyboard, promote_storyboard_panel, upload_image, list_images, generate_video, get_video_job, get_tool_call, list_videos, cancel_video_job, get_credit_balance) generate reference images and Seedance 2.5 videos without a cinema project (§4). A third surface, 6 video-plan tools (estimate_video_plan_cost, create_video_plan, get_video_plan, list_video_plans, approve_video_plan, reject_video_plan, §5), builds a full Seedance 2.x manifest — brief, refs, prompt, cost — that a human OR the agent itself approves before it dispatches. This guide is the complete playbook: connecting, the workflow loop, Autopilot, standalone assets, video plans, cost and error contracts, and a worked end-to-end transcript.

Endpoint: https://www.trvrse.com/api/mcp/mcp · Keys: minted by a human at Settings → Agent access · Raw markdown version of this page: https://www.trvrse.com/docs/agents.md

1. Quick start

Mint a key

1. Sign in to the app and go to Settings → Agent access (https://www.trvrse.com/settings/agent).
2. Click New key, give it a name (and, optionally, a spend cap in credits — leave blank for uncapped).
3. The plaintext key is shown exactly once in a modal you must explicitly dismiss with Done. Copy it now — it is never shown again (only a trv_ + 8-char prefix is kept for display). If you lose it, revoke the key and mint a new one.

The key looks like trv_ followed by 43 base64url characters, e.g. trv_9F2k7q....

Endpoint

https://www.trvrse.com/api/mcp/mcp

(mcp-handler's basePath is /api/mcp; it appends the mcp transport segment itself. Streamable HTTP only — SSE is disabled.)

Claude Code

claude mcp add --transport http --scope user trvrse https://www.trvrse.com/api/mcp/mcp \
  -H "Authorization: Bearer trv_YOUR_KEY_HERE"

Every per-client recipe (Claude Code, Claude.ai, ChatGPT, Cursor, mcpServers JSON) with the key pre-filled lives on Settings → Agent access → Connect and at https://www.trvrse.com/docs/agents/connect.

Generic MCP client (JSON config)

Most MCP clients (Claude Desktop, other agent runtimes) accept a config block like:

{
  "mcpServers": {
    "trvrse": {
      "url": "https://www.trvrse.com/api/mcp/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer trv_YOUR_KEY_HERE"
      }
    }
  }
}

The exact key name/shape (url vs command, headers vs env) varies by client — anything that supports a streamable-HTTP MCP transport with a custom header works. The same canonical endpoint also supports the OAuth flow used by the OpenAI Plugins Directory; existing trv_ keys remain valid.

claude.ai and legacy ChatGPT custom connectors

claude.ai and ChatGPT custom connectors support only OAuth or "no authentication" — never a custom Authorization header, so the two connect methods above don't work there. Use the keyed-URL endpoint instead (shown alongside the plaintext key when a new one is minted, on Settings → Agent access):

https://www.trvrse.com/api/mcp/k/trv_YOUR_KEY_HERE/mcp

claude.ai — Settings → Customize → Connectors → Add custom connector → paste the URL above, leave authentication as None.

For a legacy ChatGPT developer-mode custom connector, the same keyed URL continues to work with authentication None. The Plugins Directory uses the canonical /api/mcp/mcp URL and OAuth instead; never submit a keyed URL.

The key rides in the URL path; the endpoint injects it as the bearer token internally and forwards to the same authed handler above — no second server, no different tool catalog. The URL is bearer-equivalent: treat it like a password (don't paste it somewhere public), prefer a spend-capped key per connector, and revoke it any time from Settings → Agent access if it leaks.

Sanity-check the connection

A malformed, unknown or revoked key is refused at initialize, so claude mcp list shows ✗ immediately. To see WHY, and what the key has left:

curl -sS https://www.trvrse.com/api/mcp/health -H "Authorization: Bearer trv_YOUR_KEY_HERE"
# 200 {"ok":true,"keyName":"…","spendCap":500,"spent":0,"remaining":500,"lastSeen":null,"lastSeenClient":null}
# 401 {"ok":false,"reason":"malformed"|"unknown"|"revoked"}   429 rate-limited

Then ask the agent to call list_projects. A working connection returns real JSON; a key revoked mid-session returns an isError result naming BRIDGE_AUTH_FAILED (see the error contract below).

Install this guide as a skill (optional)

Claude Code and other skills-capable agents can carry this playbook in-context instead of re-reading it each session:

SKILLS_DIR=~/.claude
mkdir -p "$SKILLS_DIR/skills/trvrse-cinema" && \
  curl -fsSL https://www.trvrse.com/docs/agents/skill.md \
  -o "$SKILLS_DIR/skills/trvrse-cinema/SKILL.md"

2. The workflow loop

Every film follows the same loop per stage:

1. Check state — get_project_status: read the five stage statuses and nextActions (it names exactly the tool calls the pipeline admits next; trust it over guessing).
2. Quote — get_cost_estimate for the stage you are about to generate.
3. Generate — call the stage's generate_* tool with confirmedCost set to the quote's exact total.
4. Poll — get_project_status every 15–30 seconds until the stage's entities leave GENERATING (typically 1–3 minutes).
5. Review & approve — inspect results (statuses, failure reasons), regenerate anything that failed, then call the stage's approve_* tool to unlock the next stage.

Script is the exception: generate_script and rewrite_scenes run the LLM in-request and return the full screenplay synchronously (~30–60 seconds), and script work is free — no quote needed.

3. One-call films (Autopilot)

Instead of driving the five-stage loop above yourself, make_film hands the whole pipeline to the server: submit a brief and a budget, then poll get_run until the film is done.

make_film

• briefText (required) — the production brief the whole film is generated from.
• profile (required) — "cinematic" (16:9 default) or "short" (see below).
• budgetCredits (required) — a hard ceiling for the run's total spend (see "Budget is a hard ceiling" below).
• gates (optional, default [] = fully unattended) — which of "script", "references", "storyboards", "videos", "assembly" pause the run for human review (see "Gates" below).
• webhookUrl (optional, https:// only) — receives run events (see "Webhooks" below).
• title, aspectRatio, videoModel (optional) — same shapes as create_project; profile supplies defaults you can override.

Returns {runId, projectId, webhookSecret?}. webhookSecret is present only when webhookUrl was set, and is shown exactly once, here — save it immediately, it is never returned again and you need it to verify webhook deliveries.

make_long_film — multi-minute films with consistent characters

Use this instead of make_film when the user wants a long-form piece whose characters must stay recognisably the same person throughout.

It runs the same pipeline, but changes how video is generated. make_film renders one independent clip per storyboard page and concatenates them, so a 3-minute film is 20–40 separate generations — each an independent roll of the dice on character identity. make_long_film renders each page as ONE continuous multi-shot Seedance 2.5 generation and continues the previous page through native video extension, so the same film is about 6 generations. Every segment re-sends the same approved character portraits: the extension carries continuity, the portraits carry identity.

• Pinned to seedance-2.5-reference. videoModel is not selectable.
• Total runtime is capped at 180 seconds. A storyboard that plans more is refused with the exact overage — cut scenes and regenerate.
• gates defaults to all four review points ("script", "references", "storyboards", "videos"), because the point of this tool is that a human signs off on the cast and the plot before the expensive video leg. Pass [] only if the user explicitly asks for an unattended run.
• Other arguments match make_film: briefText, budgetCredits, title, castIds, webhookUrl, aspectRatio.

Budget guidance: a 3-minute film at 720p is roughly 4,500 credits of video alone, before reference images.

Set expectations about the cuts. Extension preserves each character's appearance and the surrounding location across segments, but every segment boundary is a cut — the model continues the story, not the exact frame. The result reads as a normally edited film, not a single unbroken take.

get_gate_review_link — hand a human a no-login review link

When a gated stage is waiting (get_run reports WAITING_GATE, or a stage sits in REVIEW), call this to mint a review URL and give it to whoever is deciding. The page opens without a login and shows exactly what that gate covers — the scenes, the character portraits, the boards, or the generated segments — with Approve and Reject.

• projectId and stage ("script" | "references" | "storyboards" | "videos").
• The URL is returned exactly once and is not recoverable afterwards. It is deliberately never written into run events or webhook payloads, so pass it straight to the user rather than expecting to find it later.
• Minting supersedes any earlier link for that stage, so a URL you handed out before regenerating cannot approve the new work. Unlocking a stage supersedes outstanding links too.
• Valid 7 days. Refused with CINEMA_INVALID_STATE if that stage is not awaiting review, since a link would approve nothing.

You may still clear a gate yourself with approve_script, approve_references, approve_storyboards or approve_videos when the user has delegated the decision to you.

Refusals: AUTOPILOT_RUN_LIMIT (this key already has 3 active runs — cancel_run one or wait for it to finish), BRIDGE_SPEND_CAP (budgetCredits exceeds the key's remaining spend cap), CINEMA_INVALID_INPUT (unknown gate name, non-https webhookUrl, or budgetCredits <= 0).

Poll with get_run

Call get_run({ runId }) every 30–60 seconds instead of get_project_status while a run is active. It returns status, currentStage, attentionReason?, spentCredits/budgetCredits, profile, gates, per-stage project detail (the same shape get_project_status returns), film (once COMPLETED), the last 20 events, and nextActions.

status meanings:

• RUNNING — actively progressing; nothing to do but poll.
• WAITING_GATE — paused at currentStage for human approval in the trvrse app (see "Gates" below).
• NEEDS_ATTENTION — paused on the budget ceiling, an error, or exhausted retries; read attentionReason and events.
• COMPLETED / FAILED / CANCELLED — terminal.

Budget is a hard ceiling

budgetCredits caps the run's entire spend, not just one stage. Before dispatching any stage's paid work, the server checks whether that stage's cost would push the run's spend over budgetCredits; if it would, the run pauses NEEDS_ATTENTION instead — it never overspends and it never silently truncates or downgrades work to fit under the ceiling. There is no tool to raise budgetCredits on an existing run: a budget-paused run resumes only if the blocking stage's cost drops (e.g. a cheaper model chosen for that stage in the app) or you cancel_run it.

Retries

Each stage gets one automatic retry wave before pausing NEEDS_ATTENTION — this includes the LLM generation steps (script, visual bible, storyboard plan), which get 2 attempts total (the original try + the one retry) the same as every other stage. After the retry wave is used, a further failure pauses the run for a human to fix (regenerate or approve in the app) or cancel_run.

Paused runs (WAITING_GATE or NEEDS_ATTENTION) are not stuck waiting on you to nudge them: the server automatically re-checks every paused run on a short interval and resumes it within roughly 2 minutes of the blocker clearing (a gate being approved, a retry-eligible fix landing) — you never need to call anything to "wake" a run yourself.

Your own retries are safe too — if you pass idempotencyKey. make_film and make_long_film book a whole budget the moment they run, so a call whose response was lost to a client timeout and then blindly re-sent would start a SECOND full-budget run. Pass a unique idempotencyKey (e.g. a UUID) on every call: a retry with the same key replays the original {runId, projectId, webhookSecret?} verbatim and starts nothing; a retry while the original is still running is refused IDEMPOTENCY_IN_PROGRESS (keep the key, try again shortly); a same-key call with a changed brief is refused IDEMPOTENCY_ARGS_CHANGED (use a fresh key for the new request). get_tool_call reads any key's stored result back without re-sending the args — check it before ever re-firing after a timeout. generate_script and rewrite_scenes take the same idempotencyKey and replay their original screenplay/scenes instead of paying for a second generation.

Gates

gates lists which stages pause the run WAITING_GATE for human review before continuing — approval happens in the trvrse app, not through this bridge (there is no MCP "approve this gate" tool). Once approved there, the orchestrator resumes automatically (poll get_run to see the pause and the resume). Omit gates (or pass []) for a fully unattended run.

"assembly" is the final-review gate: when it's included, the run pauses WAITING_GATE with the finished film already rendered, and completes only once a human approves the assembly stage in the app.

Webhooks

When webhookUrl (https:// only) is set, the server POSTs a JSON body to it after every run-visible event:

{ "runId": "...", "type": "stage.completed", "stage": "references", "detail": "...", "timestamp": 1732000000000 }

Event types: stage.completed, gate.pending, needs_attention, run.completed, run.failed, run.cancelled.

Every delivery carries X-Trvrse-Signature: sha256=<hex>, an HMAC-SHA256 of the raw POST body keyed with the webhookSecret make_film returned. Verify against the raw bytes you received — not a JSON.parse'd-then-JSON.stringify'd copy, which is not guaranteed to byte-match:

import crypto from "node:crypto";

function verifyTrvrseWebhook(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

Delivery is retried at 0s / 30s / 5min after a non-2xx response or a network failure; if the final attempt still fails, deliveries stop for that run (a "dead letter") — the events themselves remain readable via get_run, only the push channel goes quiet.

cancel_run

Stops future spend and dispatch only (RUNNING/WAITING_GATE/ NEEDS_ATTENTION → CANCELLED). Anything already dispatched settles normally and its credits stand — nothing is refunded, and a cancelled run cannot be resumed. Refused with AUTOPILOT_NOT_ACTIVE if the run is already COMPLETED/FAILED/CANCELLED.

Short profile

profile: "short" is the vertical-clip profile: aspectRatio defaults to 9:16 (still overridable), the script targets 2–4 scenes and a 15–60 second film, and videoModel defaults to a budget model chosen for cost (pass videoModel yourself to override it). Everything else — character and location consistency across shots, face-trust routing, review gates — is identical to the "cinematic" profile; "short" only changes length, pacing, and the default model, never the consistency guarantees.

Persistent cast (episodic films)

The cast library holds frozen snapshots of APPROVED characters — portrait, sheets, identity prompt, face-trust flag — reusable across films for identical faces every episode. The loop:

1. Save: once a character is APPROVED with a portrait in any project, call save_character_to_cast with its projectId + characterId (from get_project_status refs). The snapshot is immutable — a new look means a new cast entry. Cast names are unique per account (case-insensitive); pass name to override on collision.
2. List: list_cast returns every member (castId, name, role, containsRealFace, usageCount) — text only, no image URLs.
3. Reuse: pass the ids as make_film's castIds (up to 15). Each member is written into the screenplay prompt by name, then seeded into the film's roster with its exact saved look — references for seeded characters cost 0 credits and are never regenerated.

Two boundaries to know:

• The guarantee is the roster row + frozen face, NOT screen time. If the screenplay leaves a cast member out of every scene, the run reports a cast.unfulfilled event in get_run and continues — give the member screen time by naming it in the brief (or accept the roster-only presence).
• Deletion is guarded. delete_cast_member is refused while any of your ACTIVE runs lists the member in castIds (CINEMA_INVALID_STATE) — cancel_run the run or wait for it to finish first. Renaming a member in the app is guarded the same way, because runs match cast by name.
• Trusted portraits expire (~24h). A member reused days later can park your run NEEDS_ATTENTION with a "stale cast portrait" reason. The fix loop: list_cast → any member with portraitStale: true carries its exact portraitRefreshCost → call refresh_cast_portrait with that number as confirmedCost (one portrait charge; the same frozen face re-rendered and fanned out to every film using it) → the run resumes on its own next sweep.
• A cast member can carry a locked voice. set_cast_voice binds one of your voice samples to the member; generate_voiceover with castMemberId then always speaks in it (model chatterbox, quote with that model). It locks voiceovers only: the voices a video model invents in a shot's own dialogue are not locked yet. Only where the deployment has switched locked voices on.
• Non-cast portraits expire too. The same staleness applies to characters that were never saved to the cast: get_project_status → refs.characters[] carries portraitStale/portraitRefreshCost per character → call refresh_character_portrait with the project's id, the character's id, and that cost as confirmedCost (same one-portrait charge, same confirmed-cost contract).
• Real-face characters on animated projects trip Seedance face moderation (an untrusted gpt-image-2 portrait), and a keyframe-less scene has no kling fallback. Scenes featuring one are auto-seeded a "require-trusted" face-trust override at materialization — generate_videos/regenerate_scene then REFUSE pre-charge (free, no wasted submission) naming the character and its remedies: refresh that portrait via refresh_character_portrait (the likeness-preserving fix), or call set_shot_face_trust_override with "exclude-untrusted" to drop the untrusted reference (identity rides the shot text — a deliberate likeness sacrifice), or regenerate with a non-Seedance model. Read the current value from get_project_status → video.scenes[].faceTrustOverride (hasRealFaceCharacter marks the affected scenes); "auto" clears it.

4. Reference assets + Seedance 2.5 videos

These tools work without a cinema project: generate reference images into your library, then feed their ids to Seedance 2.5 video generation. This is the surface for one-off viral shorts; the five-stage pipeline above is for scripted films.

The loop

1. Quote — estimate_generation_cost with kind:"image" (model, numImages) or kind:"video" (model, duration, multiPromptShots, resolution, aspectRatio, generateAudio, hasReferenceVideos). Set hasReferenceVideos:true when the generate_video call this quote is for will attach referenceVideoUrls — Seedance 2.x billing floors at 5s whenever reference videos are attached, even for a shorter requested duration, and this flag is what lets the quote see that floor ahead of time. Free.

2. Generate refs — generate_image (text-to-image); use edit_image to iterate on a library image you already have instead of re-rolling from scratch.

   Content checkers differ by model. A refusal {success:false, error:"ASSET_CONTENT_REFUSED: …"} means THIS model's checker said no — not that the picture is unacceptable everywhere. On one real job a cartoon bee holding a shield, drawn for a children's immunisation leaflet, was refused by nanobanana-pro-img2img and rendered without complaint by gpt-image-2-img2img, so an edit_image refusal names that model and it is worth retrying there rather than guessing down the catalog. For generate_image no alternative is named: only that one image-to-image pair has been observed, and the obvious text-to-image candidate uses a STRICTER checker, so reword the prompt instead. Nothing is charged for a refused render, and no model is ever substituted for you.

3. upload_image imports an image into the library, free — pass either imageUrl (a public http(s) URL, ≤50MB, fetched server-side) or imageBase64 (the raw base64 / a data: URI of a local file that isn't publicly hosted, ≤5MB decoded); exactly one, never both. Use imageBase64 for files on disk (e.g. upload_image({ imageBase64: "iVBORw0KGgo…" })); for anything over 5MB decoded, host it and use imageUrl. list_images reads the library back as {success:true, images:[…], nextCursor?} (newest first, limit ≤50, default 20); when nextCursor is present, pass it back as cursor for the next page, and filter with status:"PENDING"|"PROCESSING"|"COMPLETED"|"FAILED" (a cursor is opaque and bound to its status filter — a malformed or mismatched one is refused ASSET_INVALID_INPUT). Chat attachments: an image the user attaches in claude.ai / ChatGPT is NOT delivered to you as bytes or as a public URL, so it cannot be imported by upload_image — never pass the attachment's in-app handle as imageUrl and never invent a URL. Instead give the user this exact one-step instruction: open https://www.trvrse.com/workspace/drop, drop the image, and paste the image id back here — the page uploads it into their library and shows a copyable imageId. That id is directly usable as sourceImageIds on edit_image, or as sourceImageId / referenceImageIds on generate_video, so no list_images call is needed. (Images dropped there are NOT face-scanned: a real person's photo may still be refused as a video reference — use a containsRealFace:true generate ref for real people.) Alternatives, if they prefer: paste a public https:// link to the image (then upload_image with imageUrl), or — only when YOU can read the file's bytes yourself (Claude Code / a local agent) — pass them as imageBase64. What a generation returns: {imageId, images:[{imageId, url, width, height, status}], creditsCharged, reservedCredits} — imageId is the first successful image, images lists every billed row (a FAILED row carries an empty url), and creditsCharged is what was actually charged after refunds for failed rows, which can be below reservedCredits (the quote reserved against your key's cap). Timeouts: generate_image and edit_image are synchronous by default — the call blocks until the render finishes, which can exceed 60s (2K renders have been observed at ~120s) while many MCP clients give up at a 60s default per-request timeout. Prefer async:true (it requires idempotencyKey): the call returns {success:true, accepted:true, idempotencyKey, reservedCredits} immediately; poll get_tool_call with that key every 10–15 seconds until status is COMPLETED — its result is then exactly the payload a synchronous call returns, or {success:false, error:"ASYNC_JOB_FAILED: …"} if the render failed (credits refunded; that key is settled and replays the failure, so retry with a fresh idempotencyKey). quality:"medium" is the speed lever for drafts on gpt-image-2 (same price, a fraction of the render time). If you stay synchronous: raise your client's per-request timeout to 180s+, always pass idempotencyKey, and treat a client-side timeout as an UNKNOWN outcome, not a failure: the credits may already be spent and the image in the library. Check get_tool_call with the same key (or list_images, or re-call with the same idempotencyKey, which replays the original result) before dispatching a fresh attempt — a blind retry double-spends.

4. Generate the video — generate_video with the image ids and confirmedCost set to the quote's exact total.

5. Poll — get_video_job every 15–30 seconds until COMPLETED (videoId + videoUrl) or FAILED (errorMessage, refunded:true). An unknown or foreign jobId returns {success:false, error:"ASSET_JOB_NOT_FOUND"}.

6. Iterate — tweak the keyframe with edit_image, re-quote, re-render.

The cost contract is the same shape as the cinema pipeline: echo the estimate's total as confirmedCost; a drifted quote is refused with {success:false, error:"COST_CHANGED", newEstimate} — re-quote and retry. Domain refusals (BRIDGE_SPEND_CAP when the key's cap is exhausted, insufficient credits, validation, provider errors) come back as readable {success:false, error} results, never protocol errors.

Asset strategy

• gpt-image-2 (the generate_image default, 20 credits per image) for hero keyframes, style frames, and scene refs. Use resolution:"2K" for the keyframe — it's the first frame the viewer sees. It is also the most expensive option here, so it is worth knowing what the alternatives cost before boarding a whole film with it: nano-banana-2 (10), gpt-image-1.5 (10), seedream-4.5 (10), flux-2-pro (10), flux-2-klein (5), seedream-5-0-pro (9). estimate_generation_cost is free and authoritative.
• A Seedream 5.0 model is REQUIRED for any ref showing a real person's face — seedream-5-0-lite (4 credits) or seedream-5-0-pro (9 credits). Either lands the BytePlus trust URL Seedance 2.x needs to accept a real-face reference; Lite is the default and the cheap one, Pro is the higher-fidelity opt-in. The trust window is ~24h; list_images surfaces it per image as seedanceReady — check it before spending video credits on a stale face ref.
• seedream-5-0-pro caveats: resolution is 1K/1.5K/2K only (higher values clamp to 2K, and 1.5K is accepted for this model alone), and it returns exactly ONE image per call no matter what numImages says.
• edit_image (image-to-image from owned library image ids) to iterate: gpt-image-2-img2img (default, ≤4 sources), nanobanana-pro-img2img (≤14), seedream-5-0-lite-img2img, seedream-4.5-img2img, flux-2-pro-img2img.
• characterRefImageIds on generate_video carries a character's identity across videos — reuse the same character ref image in every render of a series.

Storyboards: board the sequence in ONE render

Do not render one image per panel to decide a direction. Twenty single-panel renders at 20 credits each is 400 credits spent answering a question a single sheet answers for 20.

• generate_storyboard renders 2–9 shot sketches as ONE numbered grid with a caption strip under each panel — one provider call, one image's credits, ≈ 1/N the cost of N single renders. Quote it as one image (kind:"image", numImages:1, the same model). Leave layout on "auto": it picks the smallest grid that holds your beats with no wasted cells, laid out for the sheet aspect — on 16:9, 1 beat is 1x1, 2 is 1x2, 3 is 1x3 (one row of three, each panel twice as tall), 4 is 2x2, 5–6 a 2x3, 7–9 a 3x3; on 1:1 the same shapes stack. Layouts read ROWS x COLS. Naming "2x3" for three beats renders a blank bottom row you paid full price for. The sheet is 16:9 or 1:1 (a 3-wide grid at 9:16 squeezes the captions past legibility, so vertical sheets are refused). quality:"medium" is the right draft setting.
• The panel numbers are the interface. A human reads "panel 4" off the sheet and hands that number back. The response's panels array carries each panel's bbox as fractions of the sheet — real grid geometry, not a guess from the picture — so you can also crop client-side.
• promote_storyboard_panel then takes the panels that survived the pick. mode:"crop" is FREE (no provider, no credits); mode:"rerender" redraws that panel standalone at the shot's aspect for one standard image-to-image edit. Feed the returned imageId into generate_video like any other reference.
• When NOT to use it. A sheet panel is a sketch on a shared canvas: it is smaller and looser than a dedicated render, and it can carry a hint of the caption lettering at its edges. For the hero keyframe a viewer actually sees — and for any real-person face ref, which must come from a Seedream 5.0 model — render it properly with generate_image.

The walkthrough, call by call

Six beats, board them, keep one panel, redraw it vertical:

1  get_cost_estimate is for PROJECTS — an asset sheet is quoted as one image:
   estimate_generation_cost({kind:"image", numImages:1, aspectRatio:"16:9"})
      -> {total: N}                                       # N credits, one image
2  generate_storyboard({beats:[b1..b6], layout:"auto", aspect:"16:9",
                        confirmedCost:N, idempotencyKey:"board-1"})
      -> {imageId, layout:"2x3", aspect:"16:9",
          panels:[{index:1..6, bbox}], creditsCharged:N}   # N credits, ONE render
3  show the sheet, ask WHICH PANEL. The human answers with a number.
4  promote_storyboard_panel({storyboardImageId, panel:3})  # mode defaults to crop
      -> {imageId, mode:"crop", creditsCharged:0}          # 0 credits, no provider
5  estimate_generation_cost({kind:"image", model:"gpt-image-2-img2img",
                             numImages:1, numSourceImages:1}) -> {total:M}
   promote_storyboard_panel({storyboardImageId, panel:3, mode:"rerender",
                             aspect:"9:16", confirmedCost:M})
      -> {imageId, mode:"rerender", croppedImageId, creditsCharged:M}

The credits are exactly N + 0 + M — one image plus one edit — against 6 × N for boarding the same six beats one render at a time. Read N and M from the quote rather than assuming: both tools refuse COST_CHANGED if the price moved under you, and a same-key retry replays instead of re-rendering. Every panel is promote-able for 0 credits, so crop all the keepers before you pay to redraw any of them.

Cinema projects: contact sheet first (opt-in)

The same idea exists inside the cinema pipeline. By default stage 3 renders every page of every scene before a human has seen one — 20 credits a page, so a 20-page film is 400 credits sunk before the first "that's the wrong look". Create the project with storyboardMode:"contact_sheet_first" and stage 3 changes shape while the default stays exactly as it was:

1. generate_storyboards first renders the film's signature panel per scene as one or two contact sheets (≤ 9 scenes each, the same numbered grid generate_storyboard draws, 20 credits a sheet). Quote it with get_cost_estimate(stage:"storyboards") as usual; breakdown.phase is "sheets_pending".
2. Poll get_project_status: storyboards.contactPhase becomes "awaiting_decision" and storyboards.contactSheets[] carries each sheet's imageUrl plus entries[] mapping the printed panel number to a sceneNumber. Show the human the sheet.
3. Quote the decision — get_cost_estimate(stage:"storyboards", decisions:[{sceneNumber, decision:"keep"|"drop"|"redo"}, …]) — and pass the same array plus its total to approve_storyboards. Unlisted scenes are kept. keep renders that scene's full page boards through the normal page path; drop removes the scene for good (stage 4 never shoots it); redo re-sheets its signature panel once (a second pass, never a third).
4. Poll until the kept pages reach REVIEW, then approve_storyboards again without decisions — from here stage 3 and stage 4 are the ordinary pipeline.

The arithmetic for the 20-page job above: 400 credits up front becomes 40 credits to decide (two sheets, 20 scenes), then 20 credits per page you actually keep — keep half and the whole stage costs 240 instead of 400; keep everything and it costs 440, the 40 being the price of having looked first. The sheet is a staging artefact, not an identity one: character drift on it is expected and is not a stage-2 problem.

Legibility is the caveat, and you should check it, not assume it. A panel of a 2x3 16:9 sheet is a third of the sheet wide and 41% of it tall (≈ 512×420 on a 1536×1024 render); on a 3x3 it is ≈ 512×273, with a caption strip of 18% of the cell under it and captions cut to 56 characters — at a word boundary, with an …, so a caption never ends mid-word, and a caption you pass yourself is cut the same way. That is small type. When you show a sheet, ask the human whether they can read the panel numbers — if not, board fewer beats (2x3 beats 3x3), raise quality, or fall back to individual generate_image renders. The panels[].bbox geometry is exact regardless of how the lettering came out, so promote_storyboard_panel still cuts the right rectangle even from a sheet whose numbers are mushy.

Viral video craft

• 9:16 vertical (aspectRatio:"9:16") for TikTok/Reels/Shorts.
• The hook is the FIRST second. Put the most striking visual/motion up front — when you pass a keyframe, the keyframe IS the hook, so make the keyframe the most arresting frame of the clip, not a neutral pose.
• One clear subject + one camera move per shot. Seedance follows simple, declarative direction better than multi-action choreography.
• multiPromptShots (≤10 shots) renders a 2–4 beat multi-scene story in a single 10–15s video — each shot gets its own prompt (and optional duration).
• generateAudio:true (the default) — sound is half the scroll-stop.
• Name refs in the prompt as @Image N with their role — refs bind in ref-pool order (@Image 1, @Image 2, …; a combined keyframe takes slot 1). Say what each one is: "@Image 1 is the opening frame; @Image 2 is the dog's identity."

generate_video models: seedance-2.5-reference (default — text-to- video plus the full multimodal ref pool) and seedance-2.5-fast (keyframe image-to-video / first-last-frame — pass sourceImageId, or firstImageId+lastImageId as a pair; a lone frame is REFUSED, not ignored, because it cannot be interpolated). Reference caps are per-model: seedance-2.5 accepts up to 30 reference images, 10 referenceVideoUrls, 10 referenceAudioUrls; seedance-2.0 accepts 9/3/3. Two combinations refuse rather than silently dropping what you attached: referenceAudioUrls require an accompanying image or video ref (the provider rejects audio-only requests), and first+last frames are mutually exclusive with multimodal refs (the keyframes carry the identity). Every one of these refusals is free — it lands before the quote, the cap reservation and the debit. Duration "5s"…"30s" (Seedance 2.5 renders 4–30s; a "3s" request clamps to "4s"); resolution 480p/720p/1080p with 1080p coerced to 720p on Seedance 2.x. Attaching referenceVideoUrls floors the BILLED duration at 5s regardless of the requested duration — pass hasReferenceVideos:true to estimate_generation_cost to see this reflected in the quote before spending. The call is async — it returns {jobId} (plus reservedCredits and the normalized effectiveDurationSeconds); poll get_video_job. (Seedance 2.5 is GA. A MODEL_UNAVAILABLE refusal exists only as an operator rollback lever and always fires before any charge.)

Worked example (viral short)

> estimate_generation_cost({ kind: "image", model: "gpt-image-2", numImages: 1 })
< { success: true, estimate: { kind: "image", model: "gpt-image-2", numImages: 1, creditsPerImage: 20, total: 20 } }

> generate_image({ prompt: "Low-angle hero shot of a golden retriever wearing aviator goggles, neon sunset, cinematic, mid-head-turn", aspectRatio: "9:16", resolution: "2K", confirmedCost: 20 })
< { success: true, imageId: "img_key1", reservedCredits: 20 }

> generate_image({ prompt: "Clean studio portrait of the same golden retriever, face clearly visible", model: "seedream-5-0-lite", confirmedCost: 4 })
< { success: true, imageId: "img_face1", reservedCredits: 4 }

# seedream-5-0-lite lands the BytePlus trust URL Seedance wants for
# real-face refs — verify with list_images → seedanceReady before spending.
> estimate_generation_cost({ kind: "video", model: "seedance-2.5-reference", duration: "10s", aspectRatio: "9:16", generateAudio: true })
< { success: true, estimate: { kind: "video", total: 230, ... } }

> generate_video({ prompt: "@Image 1 is the opening keyframe; @Image 2 is the dog's identity. Slow push-in as the dog snaps its head to camera, ears flapping, synth sting hits.", sourceImageId: "img_key1", characterRefImageIds: ["img_face1"], aspectRatio: "9:16", duration: "10s", generateAudio: true, confirmedCost: 230 })
< { success: true, jobId: "job_1", reservedCredits: 230, effectiveDurationSeconds: 10, generateAudio: true }

# poll every 15–30s...
> get_video_job({ jobId: "job_1" })
< { success: true, status: "COMPLETED", videoId: "vid_1", videoUrl: "https://.../goggles.mp4", ... }

5. Human-approved video plans

Six more tools (estimate_video_plan_cost, create_video_plan, get_video_plan, list_video_plans, approve_video_plan, reject_video_plan) build a full Seedance 2.x video plan — a brief, a model, and a reference manifest that mixes library assets, not-yet- generated images, and external video/audio URLs — quote and reserve its entire cost up front, let the server assemble the missing references and compose the final prompt asynchronously, and only dispatch the actual video job once the plan is approved. This is the multi-step, higher-ceremony sibling of §4's single-shot generate_video: use it when you want a reviewable manifest — and, optionally, human sign-off — before credits are spent on the video itself, not just the refs.

Policy note: the five-stage cinema pipeline's gates (§2 step 5) are human-only — there is no MCP tool to approve a cinema stage. Video plans are different on purpose: approve_video_plan/reject_video_plan let the agent itself decide, alongside the hosted approval page. Prefer routing the approvalUrl to a human when one is available; call approve_video_plan yourself only when running unattended.

The loop

1. Quote — estimate_video_plan_cost with the full manifest (brief, model, durationSeconds, resolution, aspectRatio, generateAudio, prompt?, refs). Free.
2. Create — create_video_plan with the IDENTICAL args plus confirmedCost set to the quote's exact total. A drifted quote is refused with {success:false, error:"COST_CHANGED", newEstimate} — re-quote and retry. On success this reserves the full grand total and returns {planId, approvalUrl, expiresAt, reservedCredits}. approvalUrl is shown exactly once, in this response — save it immediately. get_video_plan never re-surfaces it.
3. Poll — get_video_plan({ planId }) every 15–30 seconds. While status:"ASSEMBLING_REFS", refs[].status and refsCompleted/refsTotal show reference-generation progress.
4. Approve — once status:"READY_FOR_REVIEW" (approvalPending:true), surface the saved approvalUrl to a human, or call approve_video_plan({ planId }) yourself. First decision wins — whichever happens first (a human opening the page, or an agent calling the tool) resolves the plan; the other is refused ALREADY_DECIDED. reject_video_plan({ planId, reason? }) releases the reservation instead — it also works mid-ASSEMBLING_REFS, cancelling assembly in flight.
5. Poll to completion — after approval, status moves APPROVED → GENERATING → COMPLETED/FAILED; get_video_plan's video.jobId/jobStatus/videoId/videoUrl appear once generation starts (jobStatus mirrors get_video_job's QUEUED/PROCESSING/COMPLETED/FAILED).
6. Discover — list_video_plans({ limit?, statusFilter? }) returns newest-first summaries (planId, status, truncated brief, model, createdAt, grandTotal) to rediscover a plan id later. Free.

The reference manifest

Each refs[] entry is { kind, source, imageId?, videoId?, url?, generateSpec?, declaredDurationSeconds? }:

• kind: "image", "video", or "audio".
• source: "library" (an existing image/video you own — set imageId/videoId), "generate" (an image the assembly pipeline will create from generateSpec — image refs only), or "url" (an external http(s) URL — video/audio refs only; raw image URLs are unsupported — kind:"image" + source:"url" refuses IMAGE_URL_REFS_UNSUPPORTED; use "library" or "generate" instead).
• generateSpec (source:"generate" only): { prompt, model?, containsRealFace }. containsRealFace:true routes generation to a Seedream 5.0 model for BytePlus face-trust — seedream-5-0-lite by default, or seedream-5-0-pro if you pin it, the same requirement as §4's asset tools — and refuses REAL_FACE_REQUIRES_SEEDREAM if paired with an explicit model:"gpt-image-2".
• declaredDurationSeconds: required for url-sourced video/audio refs on a Seedance 2.5 plan (2–30s each, ≤30s total per kind, server-enforced). Library video refs read their own known duration instead and don't need this.
• Caps (Seedance 2.5, the default model family): up to 50 total refs, ≤30 images / ≤10 videos / ≤10 audio. create_video_plan only accepts Seedance 2.x models with multimodal reference support — a non-qualifying model refuses MODEL_UNSUPPORTED.
• Refs bind into the final prompt in manifest order, per kind — @Image 1, @Video 1, @Audio 1, … — the same label get_video_plan reports per ref.

Prompt sourcing

Omit prompt (promptSource:"composer") to let assembly write the final Seedance prompt from brief + the resolved reference manifest once every ref is done — this is the default and the recommended path. Pass a pre-written prompt yourself (promptSource:"agent") to skip composition entirely; a lint failure on an agent-supplied prompt fails the plan outright (no retry, since you authored it) with the lint errors surfaced in get_video_plan's errorMessage — recreate the plan with a fixed prompt.

Lifecycle and expiry

ASSEMBLING_REFS → READY_FOR_REVIEW → APPROVED/REJECTED → (APPROVED only) GENERATING → COMPLETED/FAILED, or EXPIRED if a READY_FOR_REVIEW plan sits undecided past its expiresAt (12 hours after creation). Rejection, expiry, and any assembly/dispatch failure all release the plan's unspent reserved credits back to the key's spend cap automatically — nothing above confirmedCost is ever charged, and nothing is left permanently reserved on a dead plan.

Worked example

> estimate_video_plan_cost({ brief: "A neon-drenched courier weaves through a rain-slick night market, glancing back at pursuers.", model: "seedance-2.5-reference", durationSeconds: 10, resolution: "720p", aspectRatio: "9:16", generateAudio: true, refs: [
    { kind: "image", source: "generate", generateSpec: { prompt: "Courier character sheet: leather jacket, neon-lit face, determined expression", containsRealFace: false } }
  ] })
< { success: true, total: 75, breakdown: { refGeneration: [{ label: "Image 1", model: "gpt-image-2", credits: 20 }], video: { model: "seedance-2.5-reference", durationSeconds: 10, resolution: "720p", credits: 55 } } }

> create_video_plan({ /* identical args */, confirmedCost: 75 })
< { success: true, planId: "plan_1", status: "ASSEMBLING_REFS", approvalUrl: "https://www.trvrse.com/approve/tok_9F2k...", expiresAt: 1732050000000, reservedCredits: 75 }
# approvalUrl saved locally — it will not be shown again.

# poll every 15-30s...
> get_video_plan({ planId: "plan_1" })
< { success: true, plan: { status: "READY_FOR_REVIEW", refs: [{ label: "Image 1", status: "DONE" }], refsCompleted: 1, refsTotal: 1, prompt: "...", promptSource: "composer", ... }, approvalPending: true }

# a human opens approvalUrl and approves it there — OR, running unattended:
> approve_video_plan({ planId: "plan_1" })
< { success: true, decidedBy: "agent", status: "APPROVED" }

# poll until COMPLETED...
> get_video_plan({ planId: "plan_1" })
< { success: true, plan: { status: "COMPLETED", video: { jobId: "job_1", jobStatus: "COMPLETED", videoId: "vid_1", videoUrl: "https://.../courier.mp4" }, ... } }

6. The tool catalog

57 tools (31 cinema + 14 asset + 6 video-plan + 6 audio), one call = one pipeline action. Every result is either:

• A domain payload (including {success:false, error} refusals — these are readable, non-error results the agent should react to), or
• An isError tool result — auth failures or malformed input (see the error contract below).

An MCP client that lists tools sees each tool's full argument schema and description — those are authoritative for exact shapes; this catalog and the contracts below cover what the schemas cannot say. Every tool also carries MCP annotations: the free reads (estimate_*, list_*, get_*, get_credit_balance, get_tool_call) are readOnlyHint:true, the four delete/cancel tools (delete_cast_member, cancel_run, cancel_video_job, reject_video_plan) are destructiveHint:true, and every spending or stage-advancing tool is left at the spec's default (may be destructive) — credits spent and stages advanced are not reversible, so a client that prompts before those is prompting at the right moment.

Async / polling pattern

generate_references, generate_storyboards, generate_videos, regenerate_scene, and render_film enqueue work and return immediately. After calling one:

1. Call get_project_status (or get_film for render) repeatedly.
2. Stop polling once the relevant stage/entity leaves GENERATING (typically 1–3 minutes).
3. get_project_status's nextActions field always names the tool calls the pipeline legally admits next — trust it over guessing.

generate_script and rewrite_scenes are the exception: they call an LLM in-request and return synchronously (~30–60s) with the full script content already in the result — no polling needed for those two.

generate_image and edit_image are synchronous by default but accept async:true (with an idempotencyKey): the call returns {success:true, accepted:true, idempotencyKey, reservedCredits} at once, and get_tool_call with that key — polled every 10–15 seconds — is where the finished payload (or an ASYNC_JOB_FAILED refusal) appears. See §4.

Cost contract

• Call get_cost_estimate before any paid generate_*/render_film call and pass its exact total back as that tool's confirmedCost. The server recomputes at execution time and refuses a mismatch with {success:false, error:"COST_CHANGED", newEstimate} — re-quote and retry with the fresh total.
• stage:"references" quotes are ALL-IN only once an APPROVED bible exists: characters + locations + the visual bible's pending style frames. With a bible already in place, that total is the exact ceiling generate_references will spend. Caveat: a quote taken before any bible exists doesn't yet know it needs one — and when generate_references itself creates the bible, creating it settles the project render style (and can demote character face flags), which re-prices the entity legs. Your quote is stale at that point, so the enqueue refuses with COST_CHANGED having enqueued nothing, and the result carries repricedConfirmedCost — the fresh ALL-IN total. Call generate_references again with that value; the bible persists, so the retry goes straight to the enqueue. Nothing is ever auto-spent above your confirmedCost.
• scopeIds, model, durationSeconds, forRegen are videos-only. Passing any of them for stage:"references" or stage:"storyboards" is refused, not silently ignored — the bridge would rather tell you a scoping arg doesn't apply than let you believe it scoped something it didn't.
• resolution is not a parameter anywhere on this bridge. All quotes and generations are 720p; there is no way to request a different resolution through MCP.
• regenerate_scene quotes must set forRegen:true. Regeneration snaps durations server-side, so a quote taken without forRegen:true diverges from what regenerate_scene will actually charge — always quote with the same model/durationSeconds you intend to pass to the write call.

Spend-cap behavior

• Each key can carry an optional spendCapCredits (set at mint time or edited later in Settings → Agent access). It is a safety valve, not a ledger — the bridge checks-then-reserves against the cap atomically before spending, and reservations only ever move up (or up-then-back-down when a multi-leg call ends up doing zero billable work). There is no reconciliation against actual per-entity failures.
• When a call would push spentCredits over spendCapCredits, the bridge action returns (never throws) {success:false, error:"BRIDGE_SPEND_CAP"} — a domain refusal, not a protocol error. Raise the cap in Settings → Agent access, or use a different key, to proceed.
• Reservations happen per-leg against each leg's own server-computed estimate (not the caller's shared confirmedCost), so a multi-leg call (e.g. references' characters + locations + frames) can't over-reserve by reserving the same total three times.

Error contract

Two, and only two, shapes an agent needs to distinguish:

1. Domain refusal — a normal (non-error) tool result whose JSON payload is {success:false, error, ...}. Covers stage-gate violations, COST_CHANGED (+ newEstimate), BRIDGE_SPEND_CAP, materialization errors, and — notably — a mid-flight key revocation surfacing from some enqueue actions as {success:false, error:"BRIDGE_AUTH_FAILED"} (still a return, not a throw). Read the error field and react; this is not a protocol failure. Ownership and not-found are domain refusals too: every cinema tool that takes a projectId (or runId) returns {success:false, error:"CINEMA_NOT_FOUND: unknown projectId, or not yours"} for an id that does not exist or belongs to someone else — the two are deliberately indistinguishable (so a key cannot enumerate other tenants' ids), and the reaction is the same either way: check the id (list_projects / list_runs) rather than retrying. The same holds for every other id argument, naming the one you passed: unknown scriptId, or not yours (rewrite_scenes, approve_script), and likewise for characterId, locationId and pageId. Coded failures from inside the pipeline come back the same way, and there are exactly four codes:

   Code	Means	Do
   CINEMA_NOT_FOUND	The id does not exist, or is not yours — indistinguishable on purpose.	Re-read the id from list_projects / get_project_status / list_runs. Never retry the same id.
   CINEMA_INVALID_INPUT	An argument is malformed or violates a documented bound (too many scenes, a deleted page, a cost mismatch).	Fix the argument. The message names the bound.
   CINEMA_INVALID_STATE	The pipeline is busy or an entity is not in a usable state (generating, no portrait, stage not awaiting review).	Usually wait and retry, or do the one thing the message names first.
   CINEMA_STAGE_BLOCKED	A stage gate: you asked for stage N while stage N−1 is not APPROVED.	Read get_project_status.nextActions; approve the named upstream stage, then retry.

2. Auth/malformed-input failure — an isError:true tool result. Pre-flight auth failures (malformed/unknown/revoked key, rate limit) are thrown by the Convex auth check and mapped to an McpError naming BRIDGE_AUTH_FAILED explicitly, with a pointer back to Settings → Agent access. Missing the bearer token entirely fails the same way before any Convex call happens. Schema-level malformed input (a non-id string where an id is required, a missing required arg) surfaces as isError too, with its message intact. Anything else that arrives as an opaque [Request ID: …] Server Error is a genuine server fault, not something your call caused.

The underlying MCP SDK converts every handler throw into an isError tool result — there is no separate JSON-RPC protocol-error channel reachable from a tool handler. So in practice: readable non-error result = domain refusal you can act on; isError result = something is wrong with the call itself (bad key, bad input) and retrying the same call won't help without fixing that.

Stage preconditions map

Calling a tool before its precondition holds is a domain refusal (readable {success:false}), not a crash — get_project_status.nextActions is the fastest way to confirm what's legal right now.

7. Worked end-to-end transcript

A representative agent session (abbreviated JSON; ids/values illustrative).

> create_project({ briefText: "A lighthouse keeper discovers the tide brings back what the sea took.", aspectRatio: "16:9" })
< { projectId: "proj_abc123" }

> generate_script({ projectId: "proj_abc123", logline: "A lighthouse keeper discovers the tide brings back what the sea took.", genre: "drama", tone: "melancholic, hopeful" })
< { saved: { scriptId: "scr_1" }, screenplay: { title: "The Tide Keeper", scenes: [ /* 6 scenes */ ], characters: [...], locations: [...] } }

# Agent reviews the screenplay JSON, decides scene 3 is too on-the-nose.
> rewrite_scenes({ projectId: "proj_abc123", targets: [{ sceneNumber: 3, revisionNotes: "Cut the dialogue in half; let the silence carry it." }] })
< { applied: { scriptId: "scr_1" }, scenes: [ /* only scene 3, rewritten */ ] }

> approve_script({ scriptId: "scr_1" })
< { approved: true }

> get_project_status({ projectId: "proj_abc123" })
< { stages: { script: { status: "APPROVED" }, refs: { status: "DRAFT" }, ... },
    refs: { bibleApproved: false, characters: [{ id: "char_1", name: "Mara" }] },
    nextActions: ["set_character_face_flag (optional)", "generate_references"] }

> set_character_face_flag({ characterId: "char_1", value: true })
< { updated: true }

> get_cost_estimate({ projectId: "proj_abc123", stage: "references" })
< { total: 40, breakdown: { characters: 10, locations: 10, styleFrames: 20 } }

> generate_references({ projectId: "proj_abc123", confirmedCost: 40 })
< { bible: { created: true, renderStyle: "photoreal", renderStyleDecision: "confirmed" },
    references: { enqueued: true } }

# poll...
> get_project_status({ projectId: "proj_abc123" })
< { refs: { characters: [{ id: "char_1", status: "REVIEW" }], locations: [{ id: "loc_1", status: "REVIEW" }] } }

> approve_references({ projectId: "proj_abc123", scope: "all_pending" })
< { approved: true, stage: { approved: true } }

> get_cost_estimate({ projectId: "proj_abc123", stage: "storyboards" })
< { total: 60, breakdown: { pages: 6 } }

> generate_storyboards({ projectId: "proj_abc123", confirmedCost: 60 })
< { plan: { pages: 6, panels: 12, unresolvedNames: [] }, generation: { enqueued: true } }

# poll until pages leave REVIEW...
> approve_storyboards({ projectId: "proj_abc123", scope: "all_pending" })
< { approved: true, stage: { approved: true } }

# poll get_project_status until video scenes appear (materialization)...
> get_cost_estimate({ projectId: "proj_abc123", stage: "videos" })
< { total: 180, breakdown: { shots: 6, perShot: 30 } }

> generate_videos({ projectId: "proj_abc123", confirmedCost: 180 })
< { enqueued: true }

# poll...
> get_project_status({ projectId: "proj_abc123" })
< { video: { scenes: [
    { pageId: "pg_4", status: "FAILED", suggestedAction: "REPHRASE_PROMPT" },
    /* the other 5 COMPLETED */
  ] } }

> get_cost_estimate({ projectId: "proj_abc123", stage: "videos", scopeIds: ["pg_4"], forRegen: true })
< { total: 30 }

> regenerate_scene({ projectId: "proj_abc123", pageId: "pg_4", confirmedCost: 30, tweakPrompt: "Remove the storm — calm sea, wide shot." })
< { enqueued: true }

# poll until pg_4 is COMPLETED...
> approve_videos({ projectId: "proj_abc123" })
< { approvedCount: 6 }

> render_film({ projectId: "proj_abc123" })
< { status: "GENERATING" }

# poll get_film...
> get_film({ projectId: "proj_abc123" })
< { status: "REVIEW", videoUrl: "https://.../the-tide-keeper.mp4", durationSeconds: 96 }

8. Gotchas

• Approving a stage exits it. After a stage-level approve you cannot regenerate that stage's entities unless an upstream edit marks the stage STALE — in that case review and re-approve.
• Keys are shown once. If a key is lost there is no recovery: a human must revoke it and mint a new one at Settings → Agent access.
• regenerate_scene re-charges the scene's cost on every attempt — quote with forRegen: true first.
• Resolution is fixed at 720p through this bridge; no parameter changes it.
• Rate limit: 60 tool calls/min per key (burst 10). Poll at 15–30 second intervals. A rate-limited call surfaces as BRIDGE_AUTH_FAILED — back off and retry the same key; do not treat it as revocation.
• make_film's budgetCredits cannot be raised later. A run paused NEEDS_ATTENTION for budget stays paused until the blocking stage gets cheaper (fixed in the app) or you cancel_run it — there is no "increase the budget" call.
• Gate approvals happen in the app, not the bridge. gates pauses a run WAITING_GATE; there is no MCP tool to approve a gate — a human approves the stage in the trvrse app and the run resumes on its own within a couple of minutes.