@starreel/mcp 0.1.200 → 0.1.202

package/SKILL.md

@@ -48,6 +48,9 @@ create_drama → set_script(raw) → rewrite_script(AI draft, user may edit)
   → seams(chain_frames dry_run → confirm → run → get_jobs until its reframe images finish;
     per-shot fixes via chain_shot_from*)
   → [review_frames] → videos → generate_tts(voiceover) → [review_videos]
+  → pre-compose checks(assets changed? get_stale_portrait_frames / get_asset_versions
+    → scan_intra_shot_cuts → per shot recommend_trim_window → trim_shot
+    → audit_seams dry_run, run only after the customer accepts token billing)
   → compose_episode → final cut (.mp4 link) → review_final_cut
 ```
 
@@ -101,6 +104,7 @@ announces a condensed version as MCP `instructions` at connect time.
 | A product / brand | `create_drama` (`project_type: "ad"` or `"brand_film"`) → `add_product` → `generate_product_sheet` | writing brand copy as dialogue (it gets spoken) |
 | Generated shots / a cut that needs changes | `scan_dialogue_coverage` / `scan_intra_shot_cuts` first, then `get_shot_prompts` · `update_shot` · `replace_shot_dialogue` · `repair_episode_dialogue` · `split_shot` · `trim_shot` · `regenerate_shot_video` · `edit_video_shot` → `rerender_episode`. To put **specific shots on a different video engine** in a whole-episode run, pass `shot_engines` (`{storyboard_id: engine}`) to `quote_videos` (a scene group that contains a picked shot is **split into per-shot generation** — listed in `shot_engines_ungrouped`; its other shots stay on the drama engine but lose the group's one-take continuity, so don't break a good group for one shot; a shot that already has a video is not re-run by the episode run, so picking an engine for it is rejected). Re-quoting after a partial run prices only the shots that will actually be dispatched (`shots_total`; already-finished ones are counted in `shots_already_done`, except that a scene group with any unfinished shot is re-run whole). To make a shot **always** use a different engine (single, batch and regen alike), set `video_engine` with `update_shot` (stored on the shot, shown in the web workbench; such a shot is never put in a scene group; explicit per-call parameters still win). To re-run **one scene group** (one request, keeps in-group continuity) — optionally on a different engine for that run — use `quote_regenerate_scene_group` (`shot_numbers` = exactly one group from `get_scene_group_plan`, optional `video_engine`; the whole group must fit that engine's single-clip limit) → `regenerate_scene_group`. To retry **one shot on a different video engine**, pass `model` to `quote_regenerate_shot_video` (that shot, that regeneration only — the drama's `video_engine` is untouched; the quote pins the engine, so changing it means re-quoting) | re-composing to fix what a clip *says*; switching the whole drama's `video_engine` just to fix one shot |
 | Wants old portraits / sheets / a shot's old tail frame "deleted" | `set_character_portrait` (old assets listed in `old_assets`) · `clear_shot_frame` (old tail frame) → `regenerate_shot_video`; `list_unlinked_assets` lists the drama's unlinked old assets (a history list, not proof of ownership). Both only **unlink** — files are not deleted (`physically_deleted` is always empty; `in_history: false` means the platform kept no record, so save that URL if it matters). Tell the customer exactly that | telling the customer the old image was deleted; writing `last_frame_image: null` through the internal API |
+| Customer explicitly accepted a shot's video, then its frames / scene / character changed (the platform now flags that video stale) | `lock_shot_video` (only after the customer confirms; locks the **current** video plus the inputs it was made from — frames, prompt, reference list). While locked: `review_videos` stops reporting `video_stale` for it (a `video_locked_frames_changed` warning instead), `get_asset_versions` shows `acceptance_locked`, native-voice `stale_shots` skip it, and every call that would replace it (`regenerate_shot_video`, `edit_video_shot`, repaint / reskin, footage upload / clear, a whole-episode `generate_videos` that would re-run its scene group) is refused with **409 VIDEO_LOCKED**. To replace it later, get the customer's OK and `unlock_shot_video` first. If the video is swapped by another path the lock lapses on its own (`video_lock.broken`) | regenerating an accepted shot just because it shows as stale; locking on your own judgement or because generation finished |
 | Wants an old image **permanently** deleted from storage (not just unlinked) | `preview_delete_asset` → show the customer exactly what it says (blocking references, history that will break, copies) → only after an explicit "confirm delete" → `delete_asset` with the `confirm_token`. Irreversible; only the drama owner; only files with trusted provenance (generated for this drama, or uploaded through the platform with a grant record) | deleting without showing the preview; retrying automatically; treating `list_unlinked_assets` as proof the file is unused |
 | Cross-era drama (scenes in different periods) — checking props fit their period | `get_props` → read each prop's `era_audit` (`form_consistent`, `conflicting_scopes`, `violations`); `audit_prop_era` to re-check after a new sheet. On a conflict: `update_prop` with a precise `era_lock` (dynasty + physical form) → `generate_prop_sheet`, or bind a different prop to those shots. `run_precheck` also lists shots whose bound prop conflicts (`prop-era-conflict`) | trusting the prop's name or description alone; regenerating shot frames before the prop sheet is fixed |
 | Wants to assemble the cut themselves | `export_handoff_pack` → `get_handoff_toolchain` → **`register_external_delivery`** when the cut is final | `compose_episode` (pick one); delivering a cut the platform has no record of |
@@ -706,6 +710,21 @@ content that will be rejected.
     lets it through). Relay your QC findings to the user verbatim. Listing a
     `ref` you never opened is signing off on the user's money.
 
+    **The user's specific requirements are not covered by "the review passed".**
+    When the user asks for something specific about a shot or the whole episode
+    (identity, wardrobe, prop color, lip sync, visual artifacts…), register it in
+    their own words with `add_acceptance_criteria`. `review_frames` /
+    `review_videos` then append each item to `agent_qc.checklist` (ids start with
+    `req:`) and return `acceptance_criteria`; answer every one of them in
+    `submit_qc_report` after checking it yourself. Each item keeps three separate
+    states — `auto_review` (the platform's own checks; `not_covered` means it has
+    no check for that category, `no_related_finding` does not mean "met"),
+    `agent_qc` (your answer, per layer) and `client` (the user's own word,
+    recorded with `confirm_acceptance_criterion` and
+    `confirm_client_statement: true` only after they say so). Read them back with
+    `get_acceptance_criteria` before delivery. Registering or editing an item
+    invalidates that layer's `review_token` — re-review.
+
     **Edited a shot or two? Re-review incrementally, not the whole episode.**
     The single-shot tools (`generate_shot_frame`, `regenerate_shot_video`) only
     check the target shot and its two neighbours, so edits elsewhere do not
@@ -1535,6 +1554,21 @@ to close") tells the vendor to fit that entire sequence into each 3-second shot.
 - **Cut QA (all free)**: `scan_intra_shot_cuts` (vendor cutting inside a shot —
   run this first on any "切太快" report), `recommend_trim_window` (action ends up
   outside the kept window)
+- **Pre-compose checks — after `review_videos` passes, before `compose_episode`**:
+  don't locate problems by exporting the whole cut again and again or trying
+  transitions by hand. In order: ① if portraits / turnarounds / scene images /
+  frames changed in this episode, `get_stale_portrait_frames(episode_id)` lists
+  shots whose in-use frames still rest on old assets, and
+  `get_asset_versions(storyboard_id)` shows which version a shot uses (both free;
+  `unknown` ≠ stale; regenerating is paid — the customer decides);
+  ② `scan_intra_shot_cuts(episode_id)`; ③ per shot `recommend_trim_window`
+  (frozen tail, effective action window; scene-group shots return
+  `applicable=false`) → `trim_shot`; ④ `audit_seams(episode_id)` for continuity
+  between adjacent shots — the default `dry_run` is free, running it is billed by
+  text tokens, so only pass `dry_run:false` + `confirm_usage_billing:true` after the
+  customer accepts; ⑤ `compose_episode`. When the cut shows a problem, come back to
+  these tools to find the shot instead of re-exporting. Advisory only, not a gate;
+  trims and seam audits don't invalidate the `review_videos` token.
 
 Full reference: https://api.shortreelai.com/docs/mcp
 

package/dist/i18n/instructions.en.md

@@ -17,7 +17,7 @@ StarReel = prepaid AI short-drama production pipeline (script → AI rewrite →
 · Wants to edit themselves: needs per-shot asset pack (raw video / dialogue tracks / SFX / music / subtitles) → export_handoff_pack → get_handoff_toolchain → save_handoff_toolchain
 · Multilingual distribution → translate_subtitles → update_project_settings
 
-Pipeline order (do not skip steps): create_drama(create drama and set setting_brief/aspect ratio/video_engine/image_model/consistency anchors, all free) → set_script → rewrite_script → ★review_script → extract_assets → quote/generate_storyboards → ★review_storyboards → character sheets + turnarounds (generate_character_sheets) / scene images / prop images / color script → ★review_assets → run_precheck → quote/generate_frames(default only first frame) → tail_frame_plan(which shots need independent last frames) → quote/generate_frames(last_frame) → chain_frames (dry_run first, run it after confirmation) → get_jobs (wait for its reframe image jobs to finish) → ★review_frames → quote/generate_videos → audio → ★review_videos → compose_episode → get_final_cut → review_final_cut. Use get_pipeline_status to check progress.
+Pipeline order (do not skip steps): create_drama(create drama and set setting_brief/aspect ratio/video_engine/image_model/consistency anchors, all free) → set_script → rewrite_script → ★review_script → extract_assets → quote/generate_storyboards → ★review_storyboards → character sheets + turnarounds (generate_character_sheets) / scene images / prop images / color script → ★review_assets → run_precheck → quote/generate_frames(default only first frame) → tail_frame_plan(which shots need independent last frames) → quote/generate_frames(last_frame) → chain_frames (dry_run first, run it after confirmation) → get_jobs (wait for its reframe image jobs to finish) → ★review_frames → quote/generate_videos → audio → ★review_videos → pre-compose checks (get_stale_portrait_frames/get_asset_versions→scan_intra_shot_cuts→recommend_trim_window→audit_seams dry_run) → compose_episode → get_final_cut → review_final_cut. Use get_pipeline_status to check progress.
 Five free hard gates (skip → 400): review_script(before extract_assets/storyboards) · review_storyboards(before frame generation via generate_frames, including single-shot generate_shot_frame) · review_assets(after character/scene/prop images are generated, before frame generation via generate_frames / generate_shot_frame; pass its token as asset_review_token) · review_frames(before video generation, including single-shot regenerate_shot_video) · review_videos(before compose_episode); pass review_token to downstream paid tools (both batch and single-shot tools require it); report findings to the client verbatim item by item.
 ★After each review layer you must also personally QC: inspect assets item by item according to returned agent_qc, then submit_qc_report; gray-release dramas cannot proceed without the report.
 Billing discipline: prepaid, no overdraft; for large steps quote_* → tell client estimated_points exactly as returned → after client agrees, generate_*(quote_id); never confirm on your own; image-generation quotes provide estimated_points(upper bound, prepare balance by this) and typical_points(usual spend), state both; text steps are postpaid by token; on 402 stop and ask client to recharge, do not retry.

package/dist/i18n/instructions.zh-CN.md

@@ -17,12 +17,12 @@ StarReel = 预付费 AI 短剧产线(剧本 → AI 改写 → 资产 → 分镜
 · 想自己剪:要逐镜素材包(裸片 / 对白轨 / 音效 / 配乐 / 字幕) → export_handoff_pack → get_handoff_toolchain → save_handoff_toolchain
 · 多语言发行 → translate_subtitles → update_project_settings
 
-产线顺序(不跳步):create_drama(建剧即设好 setting_brief/画幅/video_engine/image_model/一致性锚,全免费) → set_script → rewrite_script → ★review_script → extract_assets → quote/generate_storyboards → ★review_storyboards → 定妆图+设定图 / 场景图 / 道具图 / 色彩脚本 → ★review_assets → run_precheck → quote/generate_frames(默认只出首帧) → tail_frame_plan(哪几镜要独立尾帧) → quote/generate_frames(last_frame) → chain_frames(dry_run→确认后执行)→get_jobs → ★review_frames → quote/generate_videos → 音频 → ★review_videos → compose_episode → get_final_cut → review_final_cut。用 get_pipeline_status 查进度。
+产线顺序(不跳步):create_drama(建剧即设好世界观/画幅/引擎/模型/一致性锚,全免费) → set_script → rewrite_script → ★review_script → extract_assets → quote/generate_storyboards → ★review_storyboards → 定妆图+设定图 / 场景图 / 道具图 / 色彩脚本 → ★review_assets → run_precheck → quote/generate_frames(默认只出首帧) → tail_frame_plan(哪几镜要独立尾帧) → quote/generate_frames(last_frame) → chain_frames(dry_run→确认后执行)→get_jobs → ★review_frames → quote/generate_videos → 音频 → ★review_videos → 成片前自检(recommend_trim_window/audit_seams) → compose_episode → get_final_cut → review_final_cut。用 get_pipeline_status 查进度。
 五道免费硬闸(跳过 → 400):review_script(extract_assets/分镜前)· review_storyboards(出图前,含单镜 generate_shot_frame)· review_assets(出图前,token 作 asset_review_token)· review_frames(出视频前,含单镜 regenerate_shot_video)· review_videos(compose_episode 前);review_token 随下游收费工具传(批量与单镜工具都要),findings 逐条原样告诉客户。
 ★每层审查之后你还要亲自质检:按返回的 agent_qc 逐件看素材,submit_qc_report 提交报告;灰度剧没交报告进不了下一步。
 计费纪律:预付费不透支;大额步 quote_* → 把 estimated_points 原样告诉客户 → 客户同意后 generate_*(quote_id),绝不擅自确认;出图类报价给 estimated_points(上界,按它准备余额)与 typical_points(通常花费),两个都说;文本步按 token 后付;402 就停下让客户充值,别重试。
-长任务异步:generate_* 立即返回,用 get_pipeline_status / get_storyboards / get_run_status 轮询;图片 pending = 还在生成,别重复调(重复扣费)。
+长任务异步:generate_* 立即返回,用 get_pipeline_status / get_storyboards / get_run_status 轮询;图片 pending=还在生成,别重复调(重复扣费)。
 改写成功后只 edit_rewritten_script 点改,别重跑 rewrite_script;角色外观唯一真相源是人物档案(update_character),别写进 visual_lock/art_bible。
 选图片模型/视频引擎、客户问「哪个模型好 / 怎么更省」→ get_capabilities_guide(section=model_guide):各模型实测优劣、价格、决策步骤与推荐组合;建剧时就主动讲给客户定。
 做动作 / 打斗 / 技能展示片 → get_capabilities_guide(section=action_film):分镜表直通道、首帧停在起势、并组与节奏剪裁。
-不确定该用哪个工具、客户问「你们能做什么」→ 先调 get_capabilities_guide(免费、本地、不联网)。
+不确定该用哪个工具、客户问「你们能做什么」→ get_capabilities_guide(免费、本地)。

package/dist/i18n/tools.en.json

@@ -29,7 +29,9 @@
   "get_frame_candidates": "Free read-only: **all candidates** for a shot’s first frame/last frame (same data as the image acceptance workbench). Each candidate includes original image URL (rejected ones too; can open directly at original size), status, whether currently in use (adopted), rejection reason reject (main primary code / code specific cause / details / class routing: needs_content_fix=content must change, content_retryable=content issue but reroll succeeds about 1/3, transient=audit did not complete or incidental—not image disqualification), audit evidence audit (warnings Chinese conclusion, expected design requirements, derived_shot_type inferred shot size with rationale, boxes positions of subjects/body parts in frame; candidates before 2026-10-07 have no archived evidence and are null, not proof they were audited), and which reference images were actually used (references: purpose/character ownership/whether delivered). storyboard.tail_endstate is the “last frame≈first frame” check conclusion (current=false means the conclusion is not for the current two images). ★When a shot is repeatedly rejected, or the customer asks “what did those rejected images look like / why not adopt them”, call this first: inspect each original image and evidence, then decide whether to change storyboard, references, or reroll—do not blindly pay to regenerate. To see a specific image’s final prompt use get_image_dispatch(generation_id). If the customer has seen the original image and confirms the image is fine and the audit was wrong, use adopt_frame_candidate for manual adoption (free); manual_adoption non-empty = this candidate was manually approved. recovery_options gives the three choices after failure by frame position (pick false rejection / patch and upload / regenerate), same criteria as get_frame_retry_diagnosis.",
   "adopt_frame_candidate": "Free: manually adopt a completed first-frame/last-frame candidate (rejected by audit rejected, unselected dismissed, or completed but previously in use then replaced) as the active frame for this shot—manual fallback for audit misjudgment (e.g. setting explicitly specified by author contract was judged conflicting), and can switch back to a previous one at any time. ★You must first use get_frame_candidates so the customer has seen the original image and rejection reason, and only call after explicit customer consent (adopting a rejected candidate requires explicit customer consent in every execution mode, autopilot included); do not self-approve just to move the process along. Can only adopt this shot’s same frame position, completed, has image, and not currently active. Manual approval is recorded on the candidate (who/when/original rejection reason); original rejection reason is retained for statistics. If this shot already has video, it will be marked pending regeneration (video was generated from old frames; need regenerate_shot_video). If this frame is customer-uploaded or finalized, pass replace_user_frame:true to replace it (and unfinalize). If same frame position has image generation in progress or this shot has video in progress, returns 409; wait for it to finish before adopting.",
   "get_stale_portrait_frames": "Free read-only query for which active first frames/last frames in an episode were drawn using old assets for characters that have since been replaced (old character sheet, old turnaround, old body/hair image). Use after changing a character sheet to confirm impact scope, then let the customer decide which shots to regenerate (regeneration costs credits; this tool changes no data). verdict=stale must include evidence: ledger-old-asset (dispatch ledger directly recorded use of old image) / references-previous-asset (references include that character’s previous old asset) / portrait-born-after-frame (current character sheet was created after this frame). If not provable, mark unknown with reason; do not treat as stale. has_video=true means this shot’s video is also based on old frame; after regenerating frames, video must be regenerated.",
-  "get_asset_versions": "Read-only query for all image/video versions of a shot, historical view links, dependency IDs and version hashes, plus four independent facts: generated → consistent with current input → audit valid → adopted. If historical dependency records are missing, show unknown; do not fabricate snapshots. Free.",
+  "get_asset_versions": "Read-only query for all image/video versions of a shot, historical view links, dependency IDs and version hashes, plus four independent facts: generated → consistent with current input → audit valid → adopted. If historical dependency records are missing, show unknown; do not fabricate snapshots. Free. video_lock is the customer-accepted video lock (lock_shot_video): when locked=true that video counts as current by choice; frames_changed_since_lock=true means frames changed after the lock but no regeneration is needed.",
+  "lock_shot_video": "Lock a shot's current video as the customer-accepted version (free; generates nothing, changes no asset). Use it when the customer has explicitly said \"keep this take\" and the shot's frames / scene / character were changed afterwards. While locked, asset changes no longer mark the shot stale: review_videos stops reporting video_stale (a warning video_locked_frames_changed instead), get_asset_versions shows acceptance_locked=true with the drift listed in drift_while_locked, native-voice stale_shots skip it, and the compose preflight does not flag it; regenerate_shot_video / edit_video_shot / repaint / reskin / footage upload or clear / a whole-episode generate_videos that would replace it all return 409 VIDEO_LOCKED. The lock freezes the video generation id and the inputs it was made from (first/last frame URLs, prompt, reference list). Only the video currently in use can be locked (a generation_id that is not it returns 409 NOT_CURRENT_VIDEO; no video returns 409 NO_VIDEO). If the video is swapped by another path, the lock lapses (video_lock.broken=true in get_asset_versions). Lock only after the customer explicitly confirms; never treat generation finishing or a model judgement as acceptance. To regenerate, get the customer's OK and call unlock_shot_video first.",
+  "unlock_shot_video": "Remove a shot's accepted-video lock (free). The original verdict comes back immediately: a shot whose frames changed reports video_stale again and can be regenerated with regenerate_shot_video. Call only when the customer agrees to give up the locked take. Returns was_locked.",
   "get_asset_binding_repair_plan": "Read-only generation of an auditable repair proposal for missing historical scene bindings in an episode. Returns original location/time, candidate ID, match basis, ambiguity, and proposed_scene_id; applied=false, never auto-backfills by name. Only after item-by-item verification does the customer decide whether to rebind. Free.",
   "get_storyboards": "Read an episode’s storyboard list (for review/progress). Includes readiness of each shot’s first frame (first_frame_image) and video (video_url). asset_versions separately reports for first frame/last frame/video: generated, input_consistent, review_valid, adopted, current_effective. null=missing evidence; ready only means an artifact exists, not that it is currently effective. Old assets remain viewable. ★Each shot includes **dialogue and speaker**: dialogue (raw text, null if no dialogue), dialogue_lines([{speaker,text}] line by line, split by the same parser as subtitles/voiceover—the speaker here is the one voiced in the final cut; stage directions removed), plus is_key_moment (1=key shot, uses high-end image model) and emotion_intensity (1-10). Use this single call to verify “whether dialogue is missing / who speaks / which shots are key / emotion curve”; no need to fetch per shot. After update_shot changes dialogue, verify here too. Visual/video/first-last-frame prompts are still only read per shot with get_shot_prompts. ★Each shot also includes **structured status**: frame_status/video_status (ready/pending/authorizing/rejected/failed/none/not_required). ★video_status=ready only means video generated, not that visual acceptance passed. If video_quality_issues contains terminal_cut: status=suspected means suspected abrupt end cut; cut_at_s/tail_duration_s give position; status=unavailable means detection not complete, not a pass. Both pause this run’s automatic last-frame writeback and continuation; review the video first. Field absence does not mean detection was performed, and do not directly retry paid generation. ★not_required=narration/end-card shot: frames and video are rendered at final-cut layer; this shot does not need generation—count it as completed when filling progress, do not retry. fail_reason (sensitive/text_sensitive/copyright/face_mismatch/account_overdue/quota_full/authorizing/insufficient_credits/transient/repeat_rejected/diagnosis_required/pair_collateral/model_unavailable/requote_required/needs_content_fix/contract_rejected/unknown), retryable (true=can retry; false=handle per fail_hint first, do not retry unchanged), fail_hint (human-readable). ★Failed video shots also carry video_charge_status (charged=video_charged_points were deducted / no_charge_recorded=the local ledger records no deduction / pending=billing not settled yet; field absent=charge state unknown). Only charged is definitive; no_charge_recorded does not mean refunded — do not promise a refund, confirm with get_drama_bill. ★requote_required=quote conditions changed, the shot was not dispatched or charged: re-quote with quote_videos (free) first. ★model_unavailable=selected image/video model vendor has paused or is temporarily unavailable: fail_hint lists currently available alternative models (whether credits were charged depends on error text; do not promise refunds on behalf of platform). Ask user, then use update_project_settings to change video_engine/image_model (or per shot use regenerate_shot_video model / generate_shot_frame image_model) before generating; retrying unchanged will only fail again. ★diagnosis_required=same input and same detailed cause failed repeatedly or existing candidates await judgment: inspect existing candidates and audit evidence first. For audit failure, re-review the same candidate first; for unknown reason, recheck first; do not directly change script or regenerate. Follow retryable to decide retry vs content change; do not parse Chinese. ★pair_collateral=other frame in same shot failed, this frame ended with the batch—**this frame itself was not judged bad, do not modify it**: if reopen_pair_id exists, use it to reroll only the faulty side; otherwise regenerate this shot directly. ★If a shot has degraded_frames:[{frame_type,reason,reason_label,since,hint}], this frame was **allowed through** by the system after same-cause repeated-rejection circuit break (criteria recorded, not rejected); URL is indistinguishable from a clean frame but requires manual review. If unsatisfied, follow hint to fix input then generate_shot_frame to regenerate that frame. ★terminal_desc_missing=true: this shot is marked as “state change” but none of three places says what it looks like at the end—this can be detected **before last-frame generation**, now for the whole episode at once (previously only get_shot_prompts could query per shot; nobody queries dozens of shots one by one). First use update_shot to write the ending state into last_frame_prompt, then generate the last frame: historical success rate when forced as-is is 9.4%, with terminal state written 40.2%, and each rejection still charges normally. Only for shots truly “almost unchanged” use generate_shot_frame allow_missing_terminal to pass. ★first_frame_source/last_frame_source='upload' means this frame is an **externally uploaded image** (bypassing identity anchors/style anchors/best-of-N/frame audit quality chain)—check these shots first when diagnosing character/clothing/style drift. Drift caused by external images is not a platform generation quality issue; correct fix is delete the external image and use generate_shot_frame for platform regeneration. ★If a shot has reopen_pair_id: when first/last frames were generated together, only one side truly had an issue and the other was innocent collateral rejection; pass it unchanged to generate_shot_frame parameter reopen_pair_id to reroll only the faulty side (saves half compute/cost; will not generate an image not intended for this rerun). If absent, follow fail_reason/retryable normal retry. Free. ★Each shot also includes **bindings** (IDs only): character_ids (characters bound to this shot), character_bindings[{character_id,presence}] (presence=on_screen visible in frame / voice_only voice only, not in frame), scene_id, prop_ids, active_wardrobe_id (shot-wide wardrobe), appearance_wardrobes[{character_id,wardrobe_id}] (per-character wardrobe anchor; only lists characters with declared wardrobe). These determine whose character sheet/which scene image/which prop images are injected for image generation; use get_characters for character-name lookup, get_props for prop-name lookup. Change bindings with update_shot character_ids (★full overwrite; read current values here before editing, omitted means unbind) and character_presence; change wardrobe with update_shot active_wardrobe_id / appearance_wardrobes (can overwrite, can pass null to clear); read this tool again after edits to verify. character_bindings absent = not read this time (not unbound); empty array means no bindings. ★When bilateral version review is enabled, seam_review.status is passed/failed/not_checked/stale; stale means evidence expired, not image failure, do not pay to regenerate for that alone. continuity_intent can be made explicit with update_shot. ★Each shot includes **seam_state** (seam between this shot and previous shot, same criteria as official site frame timeline): ok=chained (first frame is previous shot’s last frame, or platform performed first-last frame continuation, landed, and neither side regenerated afterward) / unchained=should be continuous but not connected (marked continuous but never connected, or platform-initiated continuation regeneration did not land: rejected/failed/still generating—this shot frame_status will be failed/processing; or after continuation passed, this shot’s first frame was regenerated) / broken=connected but discontinuous (seam_failed_dims gives discontinuous dimensions: characters/wardrobe/props/lighting/scene; seam_audit_status=stale with no dimensions = previous shot’s last frame regenerated after continuation, while this shot’s first frame still connects to old last frame) / intended=intentional cut (hard cut/scene change/time jump/large shot-size jump/insert shot/external uploaded frame), ignore / missing=frames missing on either side / unknown=no intent marked and never connected (system did not judge, not an issue) / na=first shot or narration card. seam_audit_status=pending means continuation landed but platform continuity audit not concluded yet. Before video generation only handle unchained and broken: episode-wide use chain_frames (dry_run first), single shot use chain_shot_from_prev / chain_shot_from.",
   "get_run_status": "(★free · mandatory after long-running operations) Check whether an agent is currently running for this episode. rewrite_script / extract_assets / generate_storyboards are all **minute-level** background tasks; they only return status:\"generating\". This tool is the only way to distinguish “still running” from “finished”.\n★Typical duration (production measured): rewrite 2~4 minutes, storyboard splitting 5~10 minutes—**a single LLM call may take 3~7 minutes**. So no result within 60 seconds is completely normal, definitely not failure.\nUsage: after starting, call every 30~60 seconds. running:true = still running, keep waiting, **never resend** (resending storyboard splitting replaces the entire episode’s storyboards; all tuned/generated images are lost and must be paid again); running:false = that run has ended, only then call get_storyboards / get_script to see whether artifacts were persisted.\n⚠️ Service restart clears in-flight registration; runs started during restart may also show as no in-flight.",
@@ -38,11 +40,11 @@
   "plan_precheck_fix": "Let the platform **compute** how to fix \"instruction self-contradiction\" issues caught by run_precheck (step ①, compute only, do not modify). Billed by text usage (tiny), no quote confirmation.\n★Two-step flow; this step changes no data: after receiving proposals, **explain them to the customer one by one** (which shot, change what to what, why), then pass the accepted items **unchanged** to apply_precheck_fix to persist (only the accepted items. Autopilot = accept all per execution mode: professional mode / unconfirmed plan / this step customer-controlled → explain to customer and only proceed after approval; do not decide for the customer. This step autopilot → do not ask customer; follow get_production_plan autopilot.default_decisions, and the platform records it in get_autopilot_log).\n★**In professional mode, do not decide for the customer**: these rules have false positives; the platform intentionally does not offer \"one-click auto-fix\"—tests found nearly half the proposals in the same batch were rule false positives, and silent edits would break originally correct storyboards.\n★Returned blocked lists categories the \"system will not fix for you\": those must be manually adjusted per run_precheck hints. Seeing blocked does not mean there is no problem; it is exactly the part that **must be handled manually**.\nOmit shot_id to compute the whole episode; pass it if you only want to fix one shot.",
   "apply_precheck_fix": "Persist proposals the customer has **confirmed** (step ②). Free (pure text DB write). Input is the proposal object returned by plan_precheck_fix; just **pass it back unchanged**—only the items the customer checked for acceptance.\n★Before persisting, the platform applies three gates again: optimistic lock (if the DB value changed, skip; never overwrite others' changes), admission recheck, and self-healing gate (if the rule is not green after the edit, skip). So some items entering skipped is normal, not a failure.\n★Returned remaining = how many precheck issues **remain in this episode**, not \"how many fields were changed\". After fixing, rerun run_precheck to confirm, then proceed to image generation.",
   "get_health_report": "(★Recommended · free diagnosis) Read storyboards and output a health report: overlong duration / insufficient motif coverage / problematic shots. Read-only, free. Check before image generation; identify issues, fix first, and avoid discovering them only after the film is produced.",
-  "review_script": "【Hard Gate ① · Free】Review the AI rewritten script: dialogue line length, completeness of emotional turns, opening hook, final-scene cliffhanger. ★Before extract_assets and generate_storyboards, this tool must run first—character profiles and storyboards are derived from the rewritten script; issues in the script will be amplified layer by layer into character sheets / image generation / video generation, and discovering them at final cut means redoing the whole episode. Tell the client each item in findings one by one, fix by action (use edit_rewritten_script for script edits), then re-review and proceed with the review_token.\n★【Agent manual QC · Free】The returned agent_qc contains this-layer checklist and the episode materials to inspect (materials, each with a ref; images/videos include links). The platform only judges “exists / present / rejected”; “looks alike / correct / good” must be checked by you: download and open images, sample at least beginning/middle/end frames for videos, read text through with tools. Answer each checklist item (ok / issue / na; for issue, specify which item and what problem), list every inspected ref in inspected, and call submit_qc_report to submit; relay the QC conclusion to the client verbatim. If agent_qc.required=true and no report is submitted, this review_token cannot enter the next step (400 agent_qc_required); a problematic report blocks by default just like a platform error.\n★【Script evaluation and suggestions】materials contains the client original script (script:original) and the rewritten script (script): first evaluate the client’s script itself (mainline, motivation, conflict, pacing, plot holes, filmability), then check the rewritten script; for each issue, provide concrete fixes in submit_qc_report suggestions (if wording can be directly changed, provide before/after). After submission, tell the client the evaluation and suggestions item by item and let the client choose: adopt some / execute all directly / continue without changes (which path to take follows the execution mode: professional mode / unconfirmed plan / this stage controlled by client → tell the client and proceed only after client approval; do not decide for the client; if this stage is autopiloted → do not ask the client, execute according to get_production_plan autopilot.default_decisions, and the platform records it in get_autopilot_log); autopiloted stages by default execute only priority=must items that do not change the client’s original dialogue; all others go into the delivery report.",
-  "review_storyboards": "【Hard gate ② · free】Review storyboards: forbidden terms (will be rejected by vendors and waste credits), shot duration distribution, repeated adjacent composition, character blocking drift in the same scene, emotional curve peaks/valleys, key-shot markers. ★Must run this tool before generate_frames—storyboard issues become a whole episode of wasted images once generated and cannot be fixed shot by shot. Fix per findings.action using update_shot/split_shot, then review again. ★A finding with code=forbidden_term includes `terms` (specific matched terms, e.g. \"background music\", \"strong light\") and `shots` (shot numbers); use those two to update_shot and remove them, no need to guess word by word. ★Forbidden terms are judged with **negative semantics**: writing \"no background music\" or \"do not add music\" is not a violation (it is obeying the constraint), so no edit is needed. ★\"Action overload\" in warnings (action_overload, advisory only, non-blocking): one shot contains more independent actions than its duration can support; before video generation, use split_shot to split it or delete actions—slow motion/dissolves cannot rescue it after final cut. Ignore if multiple people each do one thing or it is a naturally continuous action chain.\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors.",
-  "review_frames": "【Hard gate ③ · free】Review the shot image layer: character identity-anchor coverage (characters without character sheets will drift in shots), image-generation failure rate, orphan character variants, scene images polluted by people. ★Must run this tool before generate_videos—video generation is the most expensive step in the whole chain, and generating a whole episode of video from drifting first frames is the most typical wasted-film failure. Fix per findings.action (mostly generate_character_portraits / generate_shot_frame single-shot regeneration), then review again. ★Also reports **inter-shot seams** (warning, non-blocking): code=seam_unchained (marked continuous but never did first/last-frame chaining, or initiated chained regeneration never landed / first frame was regenerated again after chaining) / seam_broken (chained but not connected, or previous shot's last frame was regenerated after chaining); shots is the shot whose \"seam with previous shot\" has the issue. Cheapest to fix before video generation—videos are generated from first frames; if a first frame does not match the previous shot's last frame, the final cut has a jump cut. See action for fixes (whole episode chain_frames dry_run first; single seam chain_shot_from_prev / chain_shot_from).\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors.",
-  "review_assets": "【Asset-layer hard gate · free】Review character appearance images, scene images, and prop images used **on screen** in this episode—coverage and quality: on-screen character missing character sheet / missing reference image / still generating / generation failed / reference image rejected by consistency gate (hint includes rejection reason); scene missing empty-scene base plate; prop referenced by storyboard missing prop image / rejected; prop image conflicts with this shot's era/form; missing color script (warning). ★Call once after producing character sheets, reference images, scene images, and prop images; must review before generate_frames / generate_shot_frame—pass the returned review_token as **asset_review_token**, together with the storyboard-layer review_token (both are required). Only checks the assets themselves: generating shot images later will not invalidate it; changing character sheets / scene images / prop images will invalidate it, just review again (free, seconds). Explain findings to the customer one by one (code=issue type, names=which character/scene/prop, shots=affected shot numbers, action=which tool to call to fix).\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors.",
-  "review_videos": "【Video and dubbing-layer hard gate · free】Review this episode's videos and dubbing—coverage and quality: missing video / still generating / generation failed / vendor rejected; first frame changed but video was generated from an old frame (video_stale); suspected hard cut at clip end, unexpected human voice in no-dialogue shots (warning); dubbed drama: dialogue shot missing dubbing, speaking character has no voice, missing narrator role; original-audio drama: shots not attached to current voice line at export time, characters without locked voice lines; missing music (warning). ★Call once after video, dubbing (generate_tts), and music are produced; must review before compose_episode, passing the returned review_token. Finer checks (requiring decoding picture/audio tracks) are available via scan_intra_shot_cuts / scan_dialogue_coverage / audit_silent_shot_audio; after assembling the final cut, run review_final_cut.\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors. ★If the response includes post_production_advisory = narrative-required effects that the script marks as post-production are still unhandled (the platform will not composite them): tell the client verbatim and use get_post_production_checklist to see the list.",
+  "review_script": "【Hard Gate ① · Free】Review the AI rewritten script: dialogue line length, completeness of emotional turns, opening hook, final-scene cliffhanger. ★Before extract_assets and generate_storyboards, this tool must run first—character profiles and storyboards are derived from the rewritten script; issues in the script will be amplified layer by layer into character sheets / image generation / video generation, and discovering them at final cut means redoing the whole episode. Tell the client each item in findings one by one, fix by action (use edit_rewritten_script for script edits), then re-review and proceed with the review_token.\n★【Agent manual QC · Free】The returned agent_qc contains this-layer checklist and the episode materials to inspect (materials, each with a ref; images/videos include links). The platform only judges “exists / present / rejected”; “looks alike / correct / good” must be checked by you: download and open images, sample at least beginning/middle/end frames for videos, read text through with tools. Answer each checklist item (ok / issue / na; for issue, specify which item and what problem), list every inspected ref in inspected, and call submit_qc_report to submit; relay the QC conclusion to the client verbatim. If agent_qc.required=true and no report is submitted, this review_token cannot enter the next step (400 agent_qc_required); a problematic report blocks by default just like a platform error.\n★【Script evaluation and suggestions】materials contains the client original script (script:original) and the rewritten script (script): first evaluate the client’s script itself (mainline, motivation, conflict, pacing, plot holes, filmability), then check the rewritten script; for each issue, provide concrete fixes in submit_qc_report suggestions (if wording can be directly changed, provide before/after). After submission, tell the client the evaluation and suggestions item by item and let the client choose: adopt some / execute all directly / continue without changes (which path to take follows the execution mode: professional mode / unconfirmed plan / this stage controlled by client → tell the client and proceed only after client approval; do not decide for the client; if this stage is autopiloted → do not ask the client, execute according to get_production_plan autopilot.default_decisions, and the platform records it in get_autopilot_log); autopiloted stages by default execute only priority=must items that do not change the client’s original dialogue; all others go into the delivery report. ★[Customer acceptance items] review_frames / review_videos append the customer's registered specific requirements (add_acceptance_criteria) to the checklist (ids start with req:) together with acceptance_criteria: the platform's generic review does not know these requirements, so passing it does not mean they are met. Check each one with your own eyes, answer it in submit_qc_report, tell the customer the result, and let the customer confirm via confirm_acceptance_criterion.",
+  "review_storyboards": "【Hard gate ② · free】Review storyboards: forbidden terms (will be rejected by vendors and waste credits), shot duration distribution, repeated adjacent composition, character blocking drift in the same scene, emotional curve peaks/valleys, key-shot markers. ★Must run this tool before generate_frames—storyboard issues become a whole episode of wasted images once generated and cannot be fixed shot by shot. Fix per findings.action using update_shot/split_shot, then review again. ★A finding with code=forbidden_term includes `terms` (specific matched terms, e.g. \"background music\", \"strong light\") and `shots` (shot numbers); use those two to update_shot and remove them, no need to guess word by word. ★Forbidden terms are judged with **negative semantics**: writing \"no background music\" or \"do not add music\" is not a violation (it is obeying the constraint), so no edit is needed. ★\"Action overload\" in warnings (action_overload, advisory only, non-blocking): one shot contains more independent actions than its duration can support; before video generation, use split_shot to split it or delete actions—slow motion/dissolves cannot rescue it after final cut. Ignore if multiple people each do one thing or it is a naturally continuous action chain.\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors. ★[Customer acceptance items] review_frames / review_videos append the customer's registered specific requirements (add_acceptance_criteria) to the checklist (ids start with req:) together with acceptance_criteria: the platform's generic review does not know these requirements, so passing it does not mean they are met. Check each one with your own eyes, answer it in submit_qc_report, tell the customer the result, and let the customer confirm via confirm_acceptance_criterion.",
+  "review_frames": "【Hard gate ③ · free】Review the shot image layer: character identity-anchor coverage (characters without character sheets will drift in shots), image-generation failure rate, orphan character variants, scene images polluted by people. ★Must run this tool before generate_videos—video generation is the most expensive step in the whole chain, and generating a whole episode of video from drifting first frames is the most typical wasted-film failure. Fix per findings.action (mostly generate_character_portraits / generate_shot_frame single-shot regeneration), then review again. ★Also reports **inter-shot seams** (warning, non-blocking): code=seam_unchained (marked continuous but never did first/last-frame chaining, or initiated chained regeneration never landed / first frame was regenerated again after chaining) / seam_broken (chained but not connected, or previous shot's last frame was regenerated after chaining); shots is the shot whose \"seam with previous shot\" has the issue. Cheapest to fix before video generation—videos are generated from first frames; if a first frame does not match the previous shot's last frame, the final cut has a jump cut. See action for fixes (whole episode chain_frames dry_run first; single seam chain_shot_from_prev / chain_shot_from).\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors. ★[Customer acceptance items] review_frames / review_videos append the customer's registered specific requirements (add_acceptance_criteria) to the checklist (ids start with req:) together with acceptance_criteria: the platform's generic review does not know these requirements, so passing it does not mean they are met. Check each one with your own eyes, answer it in submit_qc_report, tell the customer the result, and let the customer confirm via confirm_acceptance_criterion.",
+  "review_assets": "【Asset-layer hard gate · free】Review character appearance images, scene images, and prop images used **on screen** in this episode—coverage and quality: on-screen character missing character sheet / missing reference image / still generating / generation failed / reference image rejected by consistency gate (hint includes rejection reason); scene missing empty-scene base plate; prop referenced by storyboard missing prop image / rejected; prop image conflicts with this shot's era/form; missing color script (warning). ★Call once after producing character sheets, reference images, scene images, and prop images; must review before generate_frames / generate_shot_frame—pass the returned review_token as **asset_review_token**, together with the storyboard-layer review_token (both are required). Only checks the assets themselves: generating shot images later will not invalidate it; changing character sheets / scene images / prop images will invalidate it, just review again (free, seconds). Explain findings to the customer one by one (code=issue type, names=which character/scene/prop, shots=affected shot numbers, action=which tool to call to fix).\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors. ★[Customer acceptance items] review_frames / review_videos append the customer's registered specific requirements (add_acceptance_criteria) to the checklist (ids start with req:) together with acceptance_criteria: the platform's generic review does not know these requirements, so passing it does not mean they are met. Check each one with your own eyes, answer it in submit_qc_report, tell the customer the result, and let the customer confirm via confirm_acceptance_criterion.",
+  "review_videos": "【Video and dubbing-layer hard gate · free】Review this episode's videos and dubbing—coverage and quality: missing video / still generating / generation failed / vendor rejected; first frame changed but video was generated from an old frame (video_stale); suspected hard cut at clip end, unexpected human voice in no-dialogue shots (warning); dubbed drama: dialogue shot missing dubbing, speaking character has no voice, missing narrator role; original-audio drama: shots not attached to current voice line at export time, characters without locked voice lines; missing music (warning). ★Call once after video, dubbing (generate_tts), and music are produced; must review before compose_episode, passing the returned review_token. Finer checks (requiring decoding picture/audio tracks) are available via scan_intra_shot_cuts / scan_dialogue_coverage / audit_silent_shot_audio; after assembling the final cut, run review_final_cut.\n★★【Pre-compose checks · after review_videos passes, before compose_episode】Don't hunt for problems by repeatedly exporting the whole cut and trying transitions by hand — per-shot and seam problems have dedicated tools; run them in order before stitching: ① portraits / turnarounds / scene images / shot frames were changed in this episode → first get_stale_portrait_frames(episode_id, free) to see which shots' in-use frames are still based on old assets; for shots where it is unclear which version to use, get_asset_versions(storyboard_id, free) shows each shot's versions and dependencies (unknown means insufficient evidence, not stale; regenerating is paid, so give the list to the customer and let them decide); ② scan_intra_shot_cuts(episode_id, free) finds shots where the vendor hard-cut inside a single shot; ③ per shot, recommend_trim_window(storyboard_id, free) shows a frozen tail and the effective action window (shots inside a scene group return applicable=false — skip them); apply a recommendation with trim_shot (free); ④ audit_seams(episode_id) checks editing continuity at seams between adjacent shots: by default dry_run only lists what would be audited (free); actually running it is billed by real text-token usage — tell the customer, and only after they explicitly accept pass dry_run:false + confirm_usage_billing:true; read the result from seam_review in get_storyboards; ⑤ then compose_episode. If the final cut shows jump cuts / dragging tails / seams that don't match, go back to these tools to locate the shots and fix only those — don't keep re-exporting the whole cut by trial and error. These checks are advisory, not gates; trimming and seam audits don't invalidate the review_videos token. The response's pre_compose_checks carries the same list in structured form (tool/scope/when/cost per item).\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors. ★If the response includes post_production_advisory = narrative-required effects that the script marks as post-production are still unhandled (the platform will not composite them): tell the client verbatim and use get_post_production_checklist to see the list. ★[Customer acceptance items] review_frames / review_videos append the customer's registered specific requirements (add_acceptance_criteria) to the checklist (ids start with req:) together with acceptance_criteria: the platform's generic review does not know these requirements, so passing it does not mean they are met. Check each one with your own eyes, answer it in submit_qc_report, tell the customer the result, and let the customer confirm via confirm_acceptance_criterion.",
   "submit_qc_report": "Submit the QC report made by you (agent) after personally inspecting materials. Free. First call the corresponding review_* layer (script / storyboards / assets / frames / videos), open each returned agent_qc material in materials, answer every checklist item, then call this tool. ★The platform only verifies the report is **complete**, not whether your conclusions are correct: every checklist id must be answered (ok / issue / na; issue must include note explaining which item has what problem); every ref in materials must be listed in inspected (omit one and it is rejected with the missing refs named); if there are issues, set verdict=issues and list them in issues; reporting pass when issues exist will be rejected. ★Do not go through the motions: listing something in inspected without opening it means you signed off for the customer—wasted output will still be charged. ★When verdict=issues, this token cannot proceed to the next step by default: explain the problems to the customer, fix, then review + QC again; only if the customer is clearly informed and insists on proceeding as-is should the next step include acknowledge_review:true. ★suggestions (change suggestions): required at script layer when agent_qc.suggestions_required=true and issues were reported; optional for other layers. Each item includes problem + proposal; if text can be directly changed, also provide before/after; the response assigns each suggestion an id (s1…). Explain suggestions to the customer; the customer chooses accept some / execute all directly / proceed without changes (which route; autopilot = only execute priority=must suggestions that do not change the customer's original lines per execution mode: professional mode / unconfirmed plan / this step customer-controlled → explain to customer and only proceed after approval; do not decide for the customer. This step autopilot → do not ask customer; follow get_production_plan autopilot.default_decisions, recorded by the platform in get_autopilot_log). If content changes after the review, the report will be rejected; review again and QC against the new agent_qc.",
   "review_all": "(Recommended · free) Overall health check running three layers at once: script + storyboards + shot images. Use for initial assessment before work starts and recheck before delivery. ★It **does not issue review_token**—before paid steps, still run the corresponding review_script / review_storyboards / review_frames once each (the gate recognizes \"just reviewed against the current output\", not \"reviewed once sometime before\").",
   "autofill_storyboards": "(Recommended) AI one-click fills missing fields across all episode storyboards; by default it **only fills blanks and does not overwrite existing values** (only overwrites when overwrite=true). Improves storyboard completeness; do before image generation. Async in background, postpaid text step. ★When platform contract auto-fill is enabled, it also tries to add contracts to shots **without composition contracts** (whether enabled is indicated by the note in the import receipt contract_coverage; visible headcount / subject range / shot size are judged by it for both image generation and review; with default overwrite:false, existing contracts are untouched; **overwrite:true also rewrites existing contracts**)—if auto_complete was off during import and the contract_coverage note points to this tool, call it once before image generation. If this episode already has autofill running, this run **will not queue** (prevents duplicate-click duplicate charges); newly imported shots must wait until get_autofill_status is done before calling again.",
@@ -55,7 +57,7 @@
   "generate_shot_frame": "After confirmation, generate or regenerate the frame for **one shot** (async). This is the proper path to fix a shot image: the platform will carry this shot’s character identity anchors, scene/prop reference images, style anchor, and frame audit; regenerated images stay consistent with the whole film. Using external tools to generate then upload bypasses this entire chain, so character/clothing/style will inevitably drift. Regeneration overwrites the shot’s existing frame image (including prior uploads) and marks this shot’s video as needing regeneration. A last frame requires this shot’s first frame to be ready (otherwise use first_frame or both first). Completion criterion: poll get_storyboards and watch this shot’s first_frame_image/last_frame_image change.\n★Inherited reopen (reopen_pair_id): if get_storyboards returns this field on a shot, pass it through unchanged to reroll only the actually problematic side among first/last frames—the other previously generated candidate is preserved as-is, not regenerated and not charged again. When passing it, you no longer need frame_type (it will be ignored; the platform decides which side to regenerate); quote_id still must come from quote_shot_frame (frame_type may be first_frame or last_frame; single-frame price is the same). If the shot has no reopen_pair_id field (inheritance conditions not met), do not pass this parameter; use normal frame_type retry.\n★★If generating a last frame is blocked with “this shot is marked as state changed, but nowhere says what it looks like at the end”: the correct fix is to use update_shot to write the ending state into last_frame_prompt, then generate—**do not simply add allow_missing_terminal and force it**. For this type of shot, generating a last frame as-is historically succeeds only 9.4% of the time (40.2% when an end-state description exists), so forcing it will mostly waste one charge. Only pass that parameter when you confirm this shot is intended to look “almost unchanged”.\n★One-click final cut hosted flow: the same shot may regenerate frames at most 3 rounds (one call counts as one round; both also counts as one round). At the limit, returns **409 AUTOPILOT_SHOT_REGEN_LIMIT** (not dispatched, not charged, quote not consumed)—do not bypass with another tool. Stop and ask the customer: if the customer agrees to more regeneration, quote and generate normally with customer_approved_more_regens:true (grants another limit); if the customer accepts the current state, proceed downward, and the next paid call must include acknowledge_review:true to record confirmation. Professional mode and customer-controlled stages are not subject to this limit.\n★【Storyboard review hard gate · free】Before this step you must call review_storyboards: tell the customer every returned finding verbatim (each with code=issue type, shots=hit shot numbers, action=which tool to use for fixing), then pass review_token into this tool. If not reviewed, it will be rejected with 400. If content changes after review → token auto-invalidates; just re-review once (still free). error findings block by default; only when the customer is informed and insists on continuing as-is may you pass acknowledge_review:true—pushing ahead with known issues is likely to produce unusable footage and still charges normally (acknowledge_review only means the customer personally agreed; every execution mode requires explicit customer consent, hosted included). In hosted stages, only allowlisted heuristic errors may pass with auto_acknowledge:true (platform decides; if not allowlisted, returns 400 AUTOPILOT_MUST_ASK: must_ask_customer=true means pause and ask the customer, false = self-fix according to action and re-review). ★Grayscale dramas also require you (agent) to personally QC: inspect assets item by item per agent_qc returned by review_storyboards, answer the checklist line by line, and submit via submit_qc_report before this token can be used (not submitted → 400 agent_qc_required; problematic report → blocks by default just like error).\n★【Asset-layer hard gate · free】You must also run review_assets first (character sheet images / scene images / prop images), and pass its review_token as asset_review_token (coexists with the storyboard-layer review_token; both are required; grayscale dramas missing it get 400 naming review_assets). Generating frames does not invalidate the asset token. ⚠️ Batch quote confirmation flow: first call the corresponding quote_* tool to get estimated_points and quote_id, then call this tool with quote_id (quote confirmation depends on execution mode: professional mode / unconfirmed plan / customer-controlled stage → explain to the customer and proceed only after customer approval; hosted stage → do not ask the customer, follow get_production_plan autopilot.default_decisions, and the platform records it in get_autopilot_log). Hosted-stage quotes must stay within the hard budget cap; if blocked by 402 BUDGET_WOULD_EXCEED, stop and ask the customer. ★**Image-generation quotes (character sheet / scene image / frame generation) return two numbers**: estimated_points is the **upper bound** (estimated using that model’s maximum reference-image count, ensuring you do not start with an underbudgeted run that hits 402 midway); typical_points in the same response is the **typical cost**. Tell the customer both—only saying the upper bound makes it look much more expensive (the max-reference upper bound can exceed 2× the typical value), while only saying the typical value may leave insufficient balance. For fixed-price models they are equal, so one number is enough. Video-generation quote and charge use the same function; no such range exists.",
   "quote_videos": "Quote: how many credits to batch-generate videos for an episode (same function as actual charge, relatively accurate). Returns estimated_points, quote_id. Zero cost. ⚠️ Video is a large expense; clearly tell the user the credits and wait for confirmation.\n★**Only counts shots actually dispatched this time**: shots that already have video are skipped during whole-episode resume, not regenerated and not priced—shots_total = shots priced this time (not total shots in episode), shots_already_done = shots with video skipped this time. Exception: if any shot in a scene group lacks video, the **entire group is regenerated**, and already-generated shots inside the group are also priced. All shots already have video ⇒ 400(no dispatchable shots; use regenerate_shot_video to regenerate a shot). If any shot's video is cleared after quoting (becomes pending video), generate_videos returns 409 requiring a new quote; it will not charge for shots outside the quote.\n★**Specify video engine per shot**: pass shot_engines={storyboard id: engine} to switch engines only for those shots and only for this whole-episode generation (does not change drama-level video_engine; other shots unchanged). Quote prices per shot accordingly; quote_id pins the engines, and generate_videos dispatches exactly them—changing engine requires a new quote. Receipt shot_engines = actual applied mapping; shot_engines_ungrouped = scene groups **split into per-shot generation** because they include specified shots (scene-group duration and multi-keyframes are planned for the drama engine; generating the whole group with a changed engine would lose shots/keyframes; after splitting, other shots in the group still generate per-shot with the drama engine, losing group-level one-pass continuity, so do not split a good group for one shot—check get_scene_group_plan first). Selected engine must support this drama's resolution (seedance-2.5 only 480p/720p; hailuo-3 only 720p/1080p; wan3.0/wan3.0-prime 480p~1080p), and shot duration must not exceed that engine's single-shot limit (seedance-2.5/wan3.0 30s, hailuo-3 15s), otherwise 400 (vendors truncate overlong shots; either switch engine or split_shot). Shots with specified engines must be generated this time: whole-episode generation will not regenerate shots already having video, so specifying an engine for one ⇒ 400; a split per-shot scene group only counts group members without video. If you only want to regenerate a few shots that already have video, using quote_regenerate_shot_video with model is cheaper.",
   "generate_videos": "After confirmation, batch-generate videos: one backend chain runs the full episode; if balance is insufficient it auto-aborts the whole chain (prevents duplicate charging). Requires first frames already generated for this episode (otherwise rejected). Poll get_storyboards; completion = video_url filled shot by shot.\n★【Hard gate: shot image review · free】Before this step you must call review_frames first: report the returned findings to the customer verbatim, item by item (each with code=issue type, shots=hit shot numbers, action=which tool to use to fix), then pass review_token into this tool. No review → 400 rejection. If content changes after review → token auto-invalidates; review once again (still free). If there is error, block by default; only if the customer is informed and insists on continuing as-is, pass acknowledge_review:true—pushing ahead with issues will very likely produce unusable footage and still charges normally (acknowledge_review only means the customer personally agreed; every execution mode requires explicit customer consent, including autopilot). In autopilot steps, only whitelisted heuristic errors may be released with auto_acknowledge:true (platform decides; if not whitelisted, returns 400 AUTOPILOT_MUST_ASK: must_ask_customer=true means pause and ask customer, false = self-fix per action then re-review). ★ Gray-release dramas also require you (agent) to personally QC: per review_frames returned agent_qc, inspect assets item by item, answer every checklist item, and submit via submit_qc_report before this token can be used (not submitted → 400 agent_qc_required; report has problems → blocked by default same as error). ⚠️ Batch quote confirmation flow: first call the corresponding quote_* tool to get estimated_points and quote_id, then call this tool with quote_id (quote confirmation follows execution mode: professional mode / unconfirmed plan / this step controlled by customer → explain to customer and proceed only after customer agrees; do not decide for customer; this step autopilot → do not ask customer, execute per get_production_plan autopilot.default_decisions, platform records it in get_autopilot_log). Autopilot-step quotes must stay within the hard budget cap; if blocked by 402 BUDGET_WOULD_EXCEED, stop and ask customer. ★ **Image-generation quotes (character sheet / scene image / frame generation) give two numbers**: estimated_points is the **upper bound** (estimated using that model's max reference-image count, ensuring you do not start with too-low budget and hit 402 mid-run); typical_points in the same response is the **usual cost**. Tell the customer both—only stating the upper bound makes it look much more expensive (with max reference images, the upper bound can exceed 2x the typical value); only stating the typical value may leave balance insufficient. For fixed-price models the two are equal; then one number is enough. Video-generation quote and charge use the same function; no range exists.\n★【Post-completion QC · free】After generation, wait for it to persist (check video_status in get_storyboards / get_pipeline_status), then call review_videos to review video and dubbing layers (missing video / video made from old frames / hard cut at ending / unexpected human voice / missing dubbing / voice timbre unassigned / original voice line expired); fix and re-review; then personally inspect each shot and listen to dubbing per agent_qc (action correct, face stable, lines complete, voice right), submit via submit_qc_report; compose_episode must carry its review_token.",
-  "compose_episode": "Stitch all shot videos of one episode into one final cut (final stitching). **Free** (pure stitching, no quote confirmation required), async in backend. Before starting, a final-stitch precheck runs: shots missing video or video tasks still generating will hard-block with 400 and list the problem shots (blockers); fix them and retry. If you really want a partial final cut, pass force=true (shots missing video are skipped, final cut lacks shots, logged). advisories in the response (duration drift/orphan tasks/missing TTS/post_production_pending unfinished post-production effects) are warnings only, not blockers; handle them one by one before stitching. After starting, poll with get_final_cut.\n★【Video and dubbing review hard gate · Free】Before this step you must call review_videos: relay the returned findings to the customer verbatim one by one (each with code=issue type, shots=hit shot numbers, action=which tool to use to fix), then pass the review_token into this tool. If not reviewed, 400 rejection. If content changed after review → token auto-invalidates; just review again (still free). error blocks by default; only if the customer is informed and insists on proceeding as-is may you pass acknowledge_review:true — proceeding with known issues will likely produce unusable video and still charge credits as usual (acknowledge_review only means the customer personally agreed; every execution mode requires explicit customer consent, autopilot included). In autopilot, only whitelisted heuristic errors may pass with auto_acknowledge:true (platform decides; if not whitelisted, returns 400 AUTOPILOT_MUST_ASK: must_ask_customer=true means pause to ask customer, false = self-fix per action and re-review). ★ For gray rollout dramas, you (agent) must personally QC: inspect materials item by item per agent_qc from review_videos, answer every checklist item, and submit via submit_qc_report before this token can be used (not submitted → 400 agent_qc_required; report has issues → blocked by default like error).\n★【Post-completion QC · Free】After the final cut is ready, run review_final_cut (missing shots/subtitles not fitting/identity anchors/axis jumps/typos; proofread=false means no credits charged), tell the customer the conclusion; call confirm_delivery_acceptance only after customer confirmation (delivery acceptance requires explicit customer consent in every execution mode, autopilot included). force only bypasses the final-stitch precheck, not the review gate.",
+  "compose_episode": "Stitch all shot videos of one episode into one final cut (final stitching). **Free** (pure stitching, no quote confirmation required), async in backend. Before starting, a final-stitch precheck runs: shots missing video or video tasks still generating will hard-block with 400 and list the problem shots (blockers); fix them and retry. If you really want a partial final cut, pass force=true (shots missing video are skipped, final cut lacks shots, logged). advisories in the response (duration drift/orphan tasks/missing TTS/post_production_pending unfinished post-production effects) are warnings only, not blockers; handle them one by one before stitching. After starting, poll with get_final_cut.\n★【Video and dubbing review hard gate · Free】Before this step you must call review_videos: relay the returned findings to the customer verbatim one by one (each with code=issue type, shots=hit shot numbers, action=which tool to use to fix), then pass the review_token into this tool. If not reviewed, 400 rejection. If content changed after review → token auto-invalidates; just review again (still free). error blocks by default; only if the customer is informed and insists on proceeding as-is may you pass acknowledge_review:true — proceeding with known issues will likely produce unusable video and still charge credits as usual (acknowledge_review only means the customer personally agreed; every execution mode requires explicit customer consent, autopilot included). In autopilot, only whitelisted heuristic errors may pass with auto_acknowledge:true (platform decides; if not whitelisted, returns 400 AUTOPILOT_MUST_ASK: must_ask_customer=true means pause to ask customer, false = self-fix per action and re-review). ★ For gray rollout dramas, you (agent) must personally QC: inspect materials item by item per agent_qc from review_videos, answer every checklist item, and submit via submit_qc_report before this token can be used (not submitted → 400 agent_qc_required; report has issues → blocked by default like error).\n★★【Pre-compose checks · after review_videos passes, before compose_episode】Don't hunt for problems by repeatedly exporting the whole cut and trying transitions by hand — per-shot and seam problems have dedicated tools; run them in order before stitching: ① portraits / turnarounds / scene images / shot frames were changed in this episode → first get_stale_portrait_frames(episode_id, free) to see which shots' in-use frames are still based on old assets; for shots where it is unclear which version to use, get_asset_versions(storyboard_id, free) shows each shot's versions and dependencies (unknown means insufficient evidence, not stale; regenerating is paid, so give the list to the customer and let them decide); ② scan_intra_shot_cuts(episode_id, free) finds shots where the vendor hard-cut inside a single shot; ③ per shot, recommend_trim_window(storyboard_id, free) shows a frozen tail and the effective action window (shots inside a scene group return applicable=false — skip them); apply a recommendation with trim_shot (free); ④ audit_seams(episode_id) checks editing continuity at seams between adjacent shots: by default dry_run only lists what would be audited (free); actually running it is billed by real text-token usage — tell the customer, and only after they explicitly accept pass dry_run:false + confirm_usage_billing:true; read the result from seam_review in get_storyboards; ⑤ then compose_episode. If the final cut shows jump cuts / dragging tails / seams that don't match, go back to these tools to locate the shots and fix only those — don't keep re-exporting the whole cut by trial and error. These checks are advisory, not gates; trimming and seam audits don't invalidate the review_videos token.\n★【Post-completion QC · Free】After the final cut is ready, run review_final_cut (missing shots/subtitles not fitting/identity anchors/axis jumps/typos; proofread=false means no credits charged), tell the customer the conclusion; call confirm_delivery_acceptance only after customer confirmation (delivery acceptance requires explicit customer consent in every execution mode, autopilot included). force only bypasses the final-stitch precheck, not the review gate.",
   "get_final_cut": "Check an episode final cut status and download link. When status=completed, returns download_url(our COS direct link, downloadable directly). Free. ★bgm_stale=true means BGM was generated/modified after the final cut and is not yet in the final cut: just compose_episode again (free), do not re-render. ★If a current delivery version has been set (external version registered by register_external_delivery, or platform version specified by set_current_delivery), also returns delivery—that is the version the customer actually received; download_url remains the platform's latest stitched final cut. To see what every final-cut version used and its hash, use list_deliveries.",
   "get_export": "Check an episode export/master status (downloadable master after final assembly). Free.",
   "review_final_cut": "**Final cut checkup**: Before export, run through the whole episode—shots with no generated frame, subtitles that do not fit on one screen, characters without identity anchors, shot continuity (axis jump), plus one typo proofread pass.\n★**Advisory, non-blocking**: can_export=false only means there are block-level issues worth checking first; the platform will not stop you from running compose_episode / get_export. Explain findings to the client one by one (code=issue type, shots=hit shot numbers, action=which tool to use to fix), and **let the client decide whether to fix or publish as-is**.\n★Cost: the check itself is free, but by default it runs one LLM typo proofread pass—**that step costs credits**. If proofreading is not needed, pass proofread=false (faster and no credits charged).\n★For subtitles and typo items, view the **original text** in the official website checkup panel; here only conclusions and shot numbers are returned.",
@@ -241,5 +243,10 @@
   "get_post_production_checklist": "Read this episode's **post-production effects checklist** (free). Items marked in the script as [VFX: …] or written in shot prompts as \"post-production / composited later\" are **not composited by the platform**—image and video generation leave them out and the final cut does not add them, so the finished episode lacks these story elements unless handled. Per item: shot_number, time start_s~end_s, content, source (vfx_tag shot annotation / prompt / script_unassigned = in the rewritten script but not attached to any shot), narrative_required (story-critical; cosmetic items such as color grading are false), status (pending / done_external / waived). ★Review before composing; tell the client about narrative_required pending items and ask: do it in external post (then mark_post_production_item done_external), change the shot so the platform draws it (update_shot then regenerate that shot), or drop it (waived). review_videos / compose_episode give an advisory for unhandled items.",
   "mark_post_production_item": "Mark one item of the post-production checklist (free): status=done_external (client finished it outside the platform) / waived (client decided not to do it) / pending (undo). key comes from get_post_production_checklist; it changes after the shot or prompt is edited—on 400, re-read the checklist. (Marking post-production items requires explicit client consent in every execution mode, including autopilot.) Marking is bookkeeping only and does not change the final cut; if the client wants the externally finished version delivered, use register_external_delivery.",
   "get_drama_logo": "Read this drama's final-cut logo settings (image URL / width / corner / margins / opacity). Free. null = no logo set.",
-  "set_drama_logo": "Set an image logo (corner bug) for this drama's final cut; it is overlaid above subtitles for the whole video. Free, no video regeneration. Upload the logo first with upload_image (transparent PNG recommended) and pass its URL as src. Size/margins are in px on a 720p-height baseline and scale with the output height (e.g. ~260px wide on 1080x1920 portrait -> width≈98). Takes effect on the next compose_episode / rerender_episode. Pass logo:null to clear."
+  "set_drama_logo": "Set an image logo (corner bug) for this drama's final cut; it is overlaid above subtitles for the whole video. Free, no video regeneration. Upload the logo first with upload_image (transparent PNG recommended) and pass its URL as src. Size/margins are in px on a 720p-height baseline and scale with the output height (e.g. ~260px wide on 1080x1920 portrait -> width≈98). Takes effect on the next compose_episode / rerender_episode. Pass logo:null to clear.",
+  "get_acceptance_criteria": "Read this episode's **customer acceptance items** (free): specific requirements the customer set for a shot or the whole episode. Each item keeps three separate states — auto_review (platform automatic review, per stage; not_covered = the platform has no check for this category, no_related_finding does NOT mean the requirement is met), agent_qc (your per-item conclusion from submit_qc_report, per stage), and client (the customer's own confirmation). ★Passing the platform review or your generic QC does not mean the customer's specific requirements pass — walk the customer through these items before delivery. orphan=true means the bound shot was deleted.",
+  "add_acceptance_criteria": "Register customer acceptance items (free): when the customer states a **specific requirement** for a shot or the whole episode (identity, wardrobe, prop color, lip sync, visual artifacts, etc.), record it in the customer's own words. review_frames / review_videos will then append it to agent_qc.checklist (ids start with req:) for you to check item by item, and the result is recorded separately. ★One requirement per item; for a shot use shot_number (current shot number) or storyboard_id, omit both for the whole episode. Registering invalidates review_tokens already issued for that stage — re-review. ★Only register what the customer actually said; never invent requirements.",
+  "update_acceptance_criterion": "Edit a customer acceptance item (free). Changing the text / category / shot / stages resets all three states of that item (the requirement changed, old conclusions no longer count); re-run the review to check it. To delete, use delete_acceptance_criterion. item_id comes from get_acceptance_criteria. (Editing customer acceptance items requires explicit client consent in every execution mode, including autopilot.)",
+  "confirm_acceptance_criterion": "Record the **customer's own** confirmation of an acceptance item (free): accepted / rejected / pending (undo). Only the client state is written; the platform auto review and your QC conclusion are untouched. ★Call it only after the customer has explicitly stated their decision, with confirm_client_statement:true; you must never confirm on the customer's behalf, autopilot included.",
+  "delete_acceptance_criterion": "Delete a customer acceptance item (free; its three states go with it). item_id comes from get_acceptance_criteria. (Deleting customer acceptance items requires explicit client consent in every execution mode, including autopilot.)"
 }