@starreel/mcp 0.1.221 → 0.1.223

package/SKILL.md

@@ -104,6 +104,7 @@ announces a condensed version as MCP `instructions` at connect time.
 | Lyrics only, no song (MV) | `create_drama` (`project_type: "mv"`) → `set_mv_lyrics` → `suggest_mv_song_styles` → `quote_mv_song` → `generate_mv_song` → `get_mv_song` → `select_mv_song` → `generate_mv_story` → `generate_mv_script` | Confirming lyric rights on the user's behalf (`lyrics_rights_confirmed` must come from the user); picking a candidate by QC text alone without letting the user listen |
 | 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 |
+| One person at several ages built as separate characters, and their portraits look like different people (or a mole switches sides) | pick the character whose portrait is right as the reference: `quote_derive_character_portrait` (`reference_character_id`, `age_stage`) → customer agrees → `derive_character_portrait` → `get_derived_portrait_candidates` (inspect each) → `adopt_derived_portrait` → `generate_character_sheet`. Check the target's `appearance` describes clothing for that age first — cross-character derivation dresses the target from its own profile, not the reference image | re-running batch portraits hoping the faces line up; editing the reference image elsewhere and uploading it |
 | 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 |
@@ -997,7 +998,11 @@ the frame; writing a marker for an unbound character pulls that character's imag
 in; a `#variant` marker is the only source of that variant image. To take someone
 out of a shot, change `character_ids` (it is a full overwrite — read the current
 list first). If they only speak off-screen, keep them bound and mark them
-`voice_only` through `update_shot`'s `character_presence`. The prompt body
+`voice_only` through `update_shot`'s `character_presence`. Prop images work the
+same way: they follow the shot's `prop_ids`. A prop that the storyboard import
+missed is fixed with `update_shot`'s `prop_ids` (also a full overwrite — read the
+current list, add to it, send the whole list back), not by re-importing the
+episode, which would discard the autofilled fields. The prompt body
 is only the part you write: the platform still layers identity anchors and
 consistency constraints on top at generation time. Editing a prompt does not
 re-generate anything — regenerate the shot afterwards.

package/dist/i18n/tools.en.json

@@ -8,12 +8,12 @@
   "edit_rewritten_script": "★Preferred channel for revisions: edit the AI-rewritten shootable script(write script_content). Free, instant, deterministic—**after one successful rewrite, all modifications go here; do not rerun rewrite_script**(that restarts from raw source, loses fixes, may revert improvements). ★Point-edit method(3 steps, do not skip): ① get_script to fetch **full** rewritten_script; ② **only edit target scenes**—within them change wording/split scenes/delete wrong motif/add [SFX]/move hand-held objects to [道具], and copy all other scenes byte-for-byte including punctuation; ③ submit the **entire** modified script here(this is full overwrite; do not send snippets or let model “also polish” untouched parts). Typical fixes: scene too long/split needed, dialogue line breaks across shots, wrong time/era, motif attached to scene without element, [角色档案] clothing mixed with held object, missing [SFX]/[BGM]. Only edits AI-rewritten output; if rewrite_script has not run, 400—this is not a bypass. Recover with get_script(include_previous=1). Free.",
   "get_script_format_spec": "Fetch the platform-accepted **script format contract**: full markdown template + external_prompt(can forward verbatim to any external AI) + skeleton(with 〈…〉 placeholders) + filled_example. Free · static · no credits. ★Since template v2, **production-layer annotations** are included([角色档案] six-part format/[外貌] line prefix/[道具]/[SFX][BGM][VFX]/motif/fourth lighting segment in scene header/end metadata). v1 only covered story layer, causing external AI drafts to fail checks. When forwarding, **include filled_example**—LLM format accuracy depends on complete examples, not rules. ★Use when client wants to control rewrite degree, use another AI platform, or says “your AI changed my script too much”. ★Two exits(ask client first; determines whether external AI should write annotations): 【A Direct adoption】external AI produces complete script **with production annotations** → check_script_format all green → adopt_external_script as shootable script, no StarReel AI, instant, free, client [角色档案] preserved. For clients requiring zero changes. 【B Send to AI rewrite】external AI produces story layer only(**no annotations**) → set_script as raw → rewrite_script two-pass fidelity to add annotations. ★In B, client-written annotations **are stripped and rebuilt by G1**, so tell external AI not to write them. ★Workflow: ① get external_prompt + filled_example + markdown and send with raw script to other platform; ② run check_script_format on returned draft until errors=0; ③ use adopt_external_script for A, or set_script + rewrite_script for B. ★Contract includes scene header three-part format/location naming/environment first sentence three elements/first-appearance appearance line/sound line prefixes/single-line dialogue length/ban on camera moves and end-credit edit markers, plus four fidelity requirements(keep dialogue line by line, do not drop characters, do not drop action beats, do not add scenes) already in external_prompt.",
   "check_script_format": "**Format self-check before backfill**: run script text against platform rules and return issues. Free · rules-only · no model · no database write · repeatable. ★errors = unconditional rejection(empty/too short/no scene headers/contains camera-move terms/contains end-credit edit markers); must clear before import. warnings = warning by default(strictOnly=true becomes rejection if strict mode enabled): scene too long/short, no sound line, dialogue line over limit, incomplete scene header segments, skipped scene numbers, wrong [角色档案] segment count, profile exists but missing [外貌] line, speaker slot mixed with age/identity. ★placeholder_left(residual 〈…〉 template placeholders) is **error**: system gate may not catch it, but placeholders would enter script as visual content—worse than rejection. ★Scene length counts **story-layer** characters only([角色档案]/[外貌]/[道具]/[SFX] etc. excluded), so full annotations do not push scenes over 120 chars; do not delete annotations just to pass. ★Typical use: external AI draft → self-check → send returned message list back to that platform with “fix only these, copy rest exactly” → check again → all green then set_script. ★Only checks **format**; fidelity like dialogue preservation and missing characters is checked during rewrite_script against original source.",
-  "import_storyboard_table": "【Use for existing storyboard tables】Directly create storyboards from the client’s **finished storyboard table**, skipping rewrite and shot breakdown—no agent in between. Free. ★Three steps, do not import directly: ① get_storyboard_table_spec for template(shot type/camera-move whitelist, body placement, text-card syntax, external AI prompt); ② check_storyboard_table until errors=0 and inspect warnings(missing duration/unrecognized shot type/no visual description are imported as-is); ③ call this tool. ★Use when client provides finished storyboard table(per-shot duration/shot type/camera move, common for TV/brand samples). The set_script→rewrite_script→generate_storyboards path strips production params(test: 8 shots 36s became 20 shots 109s; STYLE blocks/data cards lost). ★Declaration format(one line per shot, fields separated by | or fullwidth ｜): `[镜 001 | 4s | 微距 | 固定]`; also recognizes bold form `**镜 001 ｜ 4″ ｜ 微距 ｜ 摄影机固定不动**`(no need to retype). Order = shot number|duration|shot type|camera move|markers; marker `不切` means must not split further, `★` key shot. Camera move “横移” maps tracking, “摇” maps pan(do not mix; reflections behave differently). `[字卡 9s] line one | line two` creates a text-card shot(final cut renders black card directly, no image/video). ★Props: `[道具] NameA、NameB` binds prop_ids by exact names in drama prop library; prop names fully appearing in body also bind automatically. Receipt prop_names_unresolved lists unbound names(create props first or rename). ★If content omitted, reads episode raw content. If no per-shot declarations, 400(that is a script, use normal breakdown). ★If storyboards already exist, returns 409 with shot count; pass confirm_replace:true only after confirmation(old shots marked deleted, recoverable). Shots missing duration/shot type still import but issues list them—system will not guess; wrong duration means wrong final cut length. ★After import, **auto_complete defaults on**(follows project “auto-fill auxiliary assets” switch): one background batch fills empty professional fields(shot intent/beat/subtext/J-L cut/voice line etc., fill-empty only) and expands platform base description into full image/video prompts. Text step postpaid by token, **tell client before call**. To import only, pass auto_complete:false(**cost: no composition contract generated**—visible count, subject person/partial/prop, shot type inferred only from text; hand insert and offscreen voice shots may render as full characters and fail review. Receipt contract_coverage lists missing shots and current viable fix; follow its note—if contract auto-fill is on, use autofill_storyboards). If auto_complete.started=true, poll get_autofill_status until done(each shot tens of seconds) **before** review_storyboards; autofill changes shots and invalidates prior token.",
+  "import_storyboard_table": "【Use for existing storyboard tables】Directly create storyboards from the client’s **finished storyboard table**, skipping rewrite and shot breakdown—no agent in between. Free. ★Three steps, do not import directly: ① get_storyboard_table_spec for template(shot type/camera-move whitelist, body placement, text-card syntax, external AI prompt); ② check_storyboard_table until errors=0 and inspect warnings(missing duration/unrecognized shot type/no visual description are imported as-is); ③ call this tool. ★Use when client provides finished storyboard table(per-shot duration/shot type/camera move, common for TV/brand samples). The set_script→rewrite_script→generate_storyboards path strips production params(test: 8 shots 36s became 20 shots 109s; STYLE blocks/data cards lost). ★Declaration format(one line per shot, fields separated by | or fullwidth ｜): `[镜 001 | 4s | 微距 | 固定]`; also recognizes bold form `**镜 001 ｜ 4″ ｜ 微距 ｜ 摄影机固定不动**`(no need to retype). Order = shot number|duration|shot type|camera move|markers; marker `不切` means must not split further, `★` key shot. Camera move “横移” maps tracking, “摇” maps pan(do not mix; reflections behave differently). `[字卡 9s] line one | line two` creates a text-card shot(final cut renders black card directly, no image/video). ★Props: `[道具] NameA、NameB` binds prop_ids by exact names in drama prop library; prop names fully appearing in body also bind automatically. Receipt prop_names_unresolved lists unbound names(create props first or rename). ★If content omitted, reads episode raw content. If no per-shot declarations, 400(that is a script, use normal breakdown). ★If storyboards already exist, returns 409 with shot count; pass confirm_replace:true only after confirmation(old shots marked deleted, recoverable). Shots missing duration/shot type still import but issues list them—system will not guess; wrong duration means wrong final cut length. ★★Check bindings first, then auto-complete: re-importing after autofill has run discards the auto-completion results and you pay again. If you are not sure characters/props/scenes will bind by name, import with auto_complete:false → check each shot's character_ids / scene_id / prop_ids from get_storyboards against the **customer's original script/storyboard** (receipt props_possibly_unbound lists shots whose visual text looks like it has an object but has no prop bound) → fix with update_shot → only then quote_autofill / autofill_storyboards. If you find a missing binding after import, fix it with update_shot (prop_ids / character_ids); **do not re-import the episode**. ★After import, **auto_complete defaults on**(follows project “auto-fill auxiliary assets” switch): one background batch fills empty professional fields(shot intent/beat/subtext/J-L cut/voice line etc., fill-empty only) and expands platform base description into full image/video prompts. Text step postpaid by token, **tell client before call**. To import only, pass auto_complete:false(**cost: no composition contract generated**—visible count, subject person/partial/prop, shot type inferred only from text; hand insert and offscreen voice shots may render as full characters and fail review. Receipt contract_coverage lists missing shots and current viable fix; follow its note—if contract auto-fill is on, use autofill_storyboards). If auto_complete.started=true, poll get_autofill_status until done(each shot tens of seconds) **before** review_storyboards; autofill changes shots and invalidates prior token.",
   "get_storyboard_table_spec": "Fetch the platform-accepted **storyboard table format contract**: full markdown template + external_prompt(can forward verbatim to external AI) + skeleton(〈…〉 placeholders) + filled_example + checklist + shot_types(shot-type whitelist) + movements(camera-move whitelist and recognized Chinese forms). Free · static · no credits. ★Use when client has a finished storyboard table(per-shot duration/shot type/camera move) or wants external AI/own tool to format shot design for us—call **before import_storyboard_table**. ★Contract essentials: one shot per line `[镜 001 | 4s | 特写 | 固定]`(bold/fullwidth bars/traditional forms accepted); shot type and camera move only accept whitelist terms(other terms left blank); text after declaration = visual description(at least one line or no image) + `Character: dialogue` + [SFX:]/[BGM:]/[VFX:] tags; full-screen text uses `[字卡 9s] line one | line two`; STYLE/NEG global style blocks **do not go in table**(put in project settings); `## non-scene heading` ends current shot. When forwarding to external AI, **include filled_example**—format correctness comes from examples.",
   "check_storyboard_table": "**Storyboard-table self-check before import**: run the exact same parser as the import endpoint, returning errors / warnings / stats / shots(per-shot parse preview: duration, shot type, camera move, markers, body length). Free · rules-only · no model · no DB write · repeatable. ★errors = import will 400(empty / no per-shot declaration = not a storyboard table) + residual 〈…〉 placeholders; must clear. ★warnings = import proceeds but result lacks data: missing duration(default 4s), unrecognized shot type(blank), unrecognized camera move(blank), no visual description after declaration(dead shot, cannot image), no scene header(no scene binding), data card not using text-card syntax(not in final cut), single shot >15s, STYLE block, duplicate shot numbers—send message list back to external AI and ask it to fix only these. ★If this is green, import_storyboard_table will have no issues(same code).",
   "get_bulk_import_spec": "Get the **bulk-import JSON format contract**: full markdown template + template(placeholder template; every <...> must be replaced) + filled_example(finished reference; copy the structure directly) + external_prompt(task prompt to forward to an external AI/your own tool) + checklist + enums(valid values for mode/role/char_type/shot_type/action_motion_class; same source as validator) + limits(array and field caps). Free · static · no credits. ★When to use: before **bulk_import_storyboards**, when the client can export structured data from their own tool/spreadsheet, or wants an external AI to output JSON that creates this episode’s storyboards in one pass. ★Difference from import_storyboard_table(one text line per shot): use JSON if the data is already structured; use that tool if the client has a text storyboard table. ★Contract basics: top level { mode, episode_meta?, characters?[], scenes?[], storyboards[] }; characters[]/scenes[] are **reference declarations only, not persisted**(characters/scenes/props are extracted from the script by extract_assets; import binds by name to existing assets, so extract first, then import; props are not characters—do not put them in characters[]); storyboards dedupe by storyboard_number; bound_characters references characters[].name(or existing character name in this drama), bound_props references prop names in this drama’s prop library(if omitted, prop names appearing in body text are auto-bound), scene_ref references scenes[] location+time—unresolved references are **silently skipped**; each shot needs at least one of action/description; dialogue is `speaker: line`, no stage directions(they will be spoken); image_prompt/video_prompt may be empty(platform builds a base description from shot size + scene + lighting + action); if supplied, they are used **verbatim** and never overwritten. frame_visual_contract is an internal frame contract and ignored on import.",
   "check_bulk_import": "**Pre-import JSON self-check**: validates with the **same zod schema** as the import endpoint, then converts the import route’s \"silent behavior\" into warnings. Returns errors / warnings / stats(shot count · total seconds · characters · scenes · mode · promptsToBuild). Free · not persisted · repeatable. ★errors = import would 400 or overwrite incorrectly: invalid JSON / schema failure(with per-item path, e.g. storyboards[2].shot_type) / duplicate shot numbers + leftover <...> placeholders; must be zero. ★warnings = import continues but something will be missing or have side effects: unresolved bound_characters/scene_ref(silently skipped) / no action+description(dead shot) / dialogue contains camera language(will be spoken) / single shot >15 seconds / action_overload(too many independent actions for the duration—about 2 beats in 3 seconds, 3 beats in 5 seconds; one main action per shot; split new events into next shot; can ignore if multiple people each do one thing) / shot-number gaps / mode=replace(replaces all storyboards in this episode) / no character binding at all(characters will drift). ★If this is green, bulk_import_storyboards should pass in one call.",
-  "bulk_import_storyboards": "Create/update this episode’s storyboards from one structured JSON payload in a single pass(dedupe/update by storyboard_number). **Does not create characters/scenes/props**—they are extracted from the script by extract_assets; import only binds by name to existing ones(receipt characters_unmatched / char_refs_unresolved lists unbound refs; extract first, then import). Free · deterministic · no AI call. ★Three steps: ① get_bulk_import_spec for contract and finished example; ② check_bulk_import until errors=0; ③ call this tool. ★mode=merge(default) keeps shots not mentioned; mode=replace replaces **all** storyboards in this episode(old shots and generated images/videos are archived and recoverable, not auto-relinked)—replace requires explicit client consent in any execution mode, including autopilot. ★If you want to write image_prompt / video_prompt yourself, put them on each shot; they are used **verbatim and not overwritten**. Empty shots get platform-built base descriptions(receipt base_prompts_built says how many); after import use get_shot_prompts to read and update_shot to edit. (frame_visual_contract is an internal frame contract and ignored on import.) ★After import: speech timing may raise durations for shots whose dialogue does not fit(receipt speech_duration_raised / speech_duration_overflow). ★After import, **auto-completion is on by default**(auto_complete, follows the drama’s \"auto-complete auxiliary assets\" switch, default on): one background batch fills empty professional fields across all shots(AI, fill-empty only) and expands full image/video prompts only for shots with no image_prompt that used a platform base description(client-written prompts are never overwritten; receipt auto_complete.prompt_shots). Text step is postpaid by token; **tell the client before calling**. If you only want import, pass auto_complete:false(**cost: no composition contract is generated**—visible headcount, subject type character/part/prop, and shot size can only be inferred from text; hand insert shots and off-screen narration shots are easily rendered/audited as full characters; receipt contract_coverage lists missing shots **and gives current viable fixes; trust its note**—when contract auto-complete is enabled it calls autofill_storyboards). If receipt started=true, poll get_autofill_status until done **before** review_storyboards.",
+  "bulk_import_storyboards": "Create/update this episode’s storyboards from one structured JSON payload in a single pass(dedupe/update by storyboard_number). **Does not create characters/scenes/props**—they are extracted from the script by extract_assets; import only binds by name to existing ones(receipt characters_unmatched / char_refs_unresolved lists unbound refs; extract first, then import). Free · deterministic · no AI call. ★Three steps: ① get_bulk_import_spec for contract and finished example; ② check_bulk_import until errors=0; ③ call this tool. ★mode=merge(default) keeps shots not mentioned; mode=replace replaces **all** storyboards in this episode(old shots and generated images/videos are archived and recoverable, not auto-relinked)—replace requires explicit client consent in any execution mode, including autopilot. ★If you want to write image_prompt / video_prompt yourself, put them on each shot; they are used **verbatim and not overwritten**. Empty shots get platform-built base descriptions(receipt base_prompts_built says how many); after import use get_shot_prompts to read and update_shot to edit. (frame_visual_contract is an internal frame contract and ignored on import.) ★After import: speech timing may raise durations for shots whose dialogue does not fit(receipt speech_duration_raised / speech_duration_overflow). ★★Check bindings first, then auto-complete: re-importing after autofill has run discards the auto-completion results and you pay again. If you are not sure characters/props/scenes will bind by name, import with auto_complete:false → check each shot's character_ids / scene_id / prop_ids from get_storyboards against the **customer's original script/storyboard** (receipt props_possibly_unbound lists shots whose visual text looks like it has an object but has no prop bound) → fix with update_shot → only then quote_autofill / autofill_storyboards. If you find a missing binding after import, fix it with update_shot (prop_ids / character_ids); **do not re-import the episode**. ★After import, **auto-completion is on by default**(auto_complete, follows the drama’s \"auto-complete auxiliary assets\" switch, default on): one background batch fills empty professional fields across all shots(AI, fill-empty only) and expands full image/video prompts only for shots with no image_prompt that used a platform base description(client-written prompts are never overwritten; receipt auto_complete.prompt_shots). Text step is postpaid by token; **tell the client before calling**. If you only want import, pass auto_complete:false(**cost: no composition contract is generated**—visible headcount, subject type character/part/prop, and shot size can only be inferred from text; hand insert shots and off-screen narration shots are easily rendered/audited as full characters; receipt contract_coverage lists missing shots **and gives current viable fixes; trust its note**—when contract auto-complete is enabled it calls autofill_storyboards). If receipt started=true, poll get_autofill_status until done **before** review_storyboards.",
   "get_autofill_status": "Check progress and receipt of this episode’s background completion batch (import auto_complete / autofill_storyboards AI one-click fill-empty): { status: running|done|failed|idle, total, done, ok, fail, skipped_no_gap, fields_written_counts, contract_coverage }. Free. ★The receipt is the evidence of what completion wrote: it writes internal narrative fields and composition contracts that get_storyboards / get_shot_prompts **do not return**, so seeing no change on read-back is normal—use these counts instead. skipped_no_gap = shots with no gaps that were skipped (no AI call, no charge); fields_written_counts = number of shots written per field name (e.g. {shot_intent: 44}); contract_coverage = {total, missing_contract} = image-generating shots in this episode and how many still lack a composition contract. Counts only, never field contents—tell the customer these numbers as-is. ★After import with auto-complete, wait for status=done before review_storyboards / generate_frames—the batch rewrites shot fields one by one, so any earlier review_token becomes invalid when content changes. Each shot takes tens of seconds; a full episode can take 10+ minutes. Poll interval ≥10 seconds; do not tight-loop. If status=failed or fail>0, inspect fail count; a few failed shots can be rerun with autofill_storyboards (in fill-empty mode, shots already filled are skipped with no AI call and no charge; only unfilled shots are billed).",
   "adopt_external_script": "[Exit A] Adopt a draft produced by an external AI from the template **directly as the shootable script**; StarReel AI does not intervene. Seconds, no charge. ★Hard pre-gate: server first runs a format self-check; non-empty errors return 400 with the list unchanged—use check_script_format until fully green before this tool. warnings do not block(same strictness as default lenient save_script). ★When to use: client demands \"do not change a single word\" and the external AI already produced a complete draft with production-layer annotations. ★When **not** to use: client only organized the story layer(no [角色档案]/[外貌])—direct adoption would leave downstream without character profiles and appearance anchors; use Exit B(set_script + rewrite_script) so the platform adds annotations. ★Difference from edit_rewritten_script: that is a point-edit channel for an **existing rewritten script**(400 if rewrite was never run). This tool is the **first script ingestion** channel, only for \"the script was prepared externally\". It is not a backdoor around rewriting—the server gate decides; if it fails, it fails. Old script is saved into previous_script; if adopted by mistake, recover with get_script(include_previous=1).",
   "extract_assets": "Extract characters/scenes/props from the shootable script (writes three tables in one pass; the foundation for downstream consistency). Backend async; text step postpaid, no arrears. Prerequisite: rewrite_script has produced the rewritten script (mandatory for new projects; character profiles must be extracted from the rewritten script to stay self-consistent with script and storyboards). ★Minute-level backend task; use get_run_status to decide whether it is still running; do not treat 60 seconds as failure.\n★【Rewritten-script review hard gate · free】Before this step, you must call review_script first: report every returned finding to the customer verbatim (each with code=issue type, shots=hit shot numbers, action=which tool to use to fix), then pass review_token into this tool. Skipping review will be rejected with 400. If content changed after review → token auto-invalidates; review again once (still free). If there is error, block by default; only if the customer is informed and insists on continuing as-is may you pass acknowledge_review:true—pushing forward with known issues will likely produce unusable footage and is still charged normally (acknowledge_review only means the customer personally agreed; every execution mode still requires explicit customer consent, including managed mode); in managed steps, only allowlisted heuristic error can pass with auto_acknowledge:true (platform decides; if not allowlisted returns 400 AUTOPILOT_MUST_ASK:must_ask_customer=true then pause and ask customer, false = self-fix per action then review again). ★Gray-release dramas also require you (agent) to QC personally: inspect assets item by item per agent_qc returned by review_script, answer the checklist, and submit via submit_qc_report before this token can be used (not submitted → 400 agent_qc_required; bad report → blocked by default like error).★★【Execution-mode master rules · read before starting】For dramas with a confirmed opening plan, first get_production_plan and read autopilot: pro mode (pro, or autopilot.enabled=false, or no confirmed plan) → every later 'tell customer, proceed only after customer agrees' is literal; one-click (auto) / hybrid (custom) managed steps → do not ask customer: follow get_pipeline_status next_action in order, self-confirm quotes within the hard budget cap, after each layer still run review_* + agent QC, and let review/QC autopilot.next_step tell you how to proceed at this layer (allowlisted error with auto_acknowledge:true / which self-fix round / pause to ask customer); for choices follow autopilot.default_decisions; autopilot.never_auto_actions(mode=replace, deleting assets, overwriting customer-uploaded images, allow_era_ref_conflict, cloning voices, delivery acceptance) always require customer consent in every mode. ★In managed steps, regenerating frames for the same shot (generate_shot_frame) max 3 rounds, regenerating video (regenerate_shot_video / edit_video_shot) max 3 times; at the limit the platform returns 409 AUTOPILOT_SHOT_REGEN_LIMIT (not charged)—do not bypass with another tool; stop and ask customer: if customer approves more, quote normally and pass customer_approved_more_regens:true when generating (grants another limit); if customer accepts current state, continue, and pass acknowledge_review:true on the next paid call to record confirmation. 402 BUDGET_WOULD_EXCEED / 409 MODEL_UNAVAILABLE / 409 AUTOPILOT_SHOT_REGEN_LIMIT / 400 AUTOPILOT_MUST_ASK with must_ask_customer=true / non-empty pending_questions → pause and ask the customer the pending_questions from get_autopilot_log **summarized all at once**; customer-controlled steps follow pro mode. After final output, deliver to customer using the get_autopilot_log report. ★Three-tier execution strategy (do not mix the three when asking customer):①【Basic project settings · free · mandatory foundation · set when creating drama, do not create an empty shell】project_type/setting_brief(worldview · ERA LOCK)/ethnicity/aspect ratio resolution, plus consistency anchors cinematography_prompt(photography DNA)·art_bible(art bible)·visual_lock(visual lock)—all free, foundation for full-pipeline consistency; if not set properly, all later generation drifts and rework costs again. Set directly via create_drama/update_project_settings. ★visual_lock/art_bible only write image-level/world-level locks (shot language · environment · art tone · forbidden elements), **never pin clothing/hairstyle/appearance details for specific characters**—the single source of truth for character appearance is the character profiles produced by extract_assets (change via update_character); writing both places inevitably conflicts, character sheet vs profile, concept image vs visual lock, consistency gate rejects by character sheet → concept images/shot frames get **structurally rejected in chains**, no amount of rerolls passes, pure waste.★★【Era contract · free · required before image generation for non-contemporary or surreal subjects】The worldview in setting_brief is **free text**; it can provide background but cannot constrain images. The real override over visual_lock is the **structured era contract**: use set_era_contract to set this episode’s tier (modern/republican/historical/fantasy/surreal), get_era_contract to read current value. **Unset means empty**—the platform can only rely on prompt text to fight drift; modern objects entering ancient images or scene images drawn in the wrong era is usually caused by this being empty. ★Xianxia/fantasy/immortal-realm content **must use fantasy, not historical**: historical requires textual realistic accuracy and will classify glowing aura, floating landforms, and non-human transformations as 'era-inconsistent', pulling images toward realistic ancient style. To make an exception for one scene (e.g. a modern flashback inside a fantasy world), use update_scene era_contract to override at scene level; scene-level beats episode-level.★★【Per-stage review protocol · all free · main line to prevent unusable film, not optional】After every stage output, review first, report conclusions verbatim to customer, then proceed. **Five hard gates (not passing causes 400; ④⑤ and agent QC below)**:① after rewritten script → review_script (before extract_assets / generate_storyboards);② after storyboards → review_storyboards (before generate_frames);③ after shot images → review_frames (before generate_videos). Each review returns review_token; pass it with downstream paid tools; explain findings one by one to customer (code=issue type · shots=hit shot numbers · action=which tool to fix), fix per action, then **review again** before proceeding. If content changed after review → token auto-invalidates; review once again (free). If error exists, block by default; only if customer explicitly understands and insists may pass acknowledge_review:true (acknowledge_review only means customer personally agreed; every execution mode still needs explicit customer consent, including managed mode); in managed steps, only allowlisted heuristic error can pass auto_acknowledge:true (see 【Execution-mode master rules】). **Soft guidance (non-blocking but strongly recommended, also free)**: before image/video generation run run_precheck (catches shots vendors will definitely reject, preventing wasted credits)—★**to run whole-drama first use run_drama_precheck** (drama-level summary · free · read-only): get issue counts per episode and attention (which episodes to fix first), prioritize by it, then run run_precheck on those episodes for details; do not blindly scan episode by episode. Note not_covered—drama-level skips the only lint that requires images, so '0 whole-drama issues' ≠ 'everything checked'. ★After findings, do not blindly edit yourself: plan_precheck_fix lets platform compute proposals → apply_precheck_fix writes them (choose which to adopt; managed=adopt all per execution mode: pro mode / no confirmed plan / this step customer-controlled → tell customer and proceed only after consent; do not decide for customer; managed step → do not ask, follow get_production_plan autopilot.default_decisions, platform logs in get_autopilot_log); after storyboards run get_health_report; after character sheets use get_characters to verify every appearing character has image/sheet; after frames use get_storyboards to inspect frame_status and fail_reason/fail_hint (fix failed shots before continuing; do not make video from bad frames); after videos inspect video_status similarly; before final cut use get_pipeline_status to confirm no missing shots. ★**Never generate straight through**: pushing layer after layer without review amplifies issues at every layer, and the whole episode may need redoing—every repeated image/video generation is real charged. Reviews are all free; catching issues costs nothing. ★Clothing changes are structured bindings: update_shot active_wardrobe_id (whole shot) / appearance_wardrobes (multi-character per role), can override or clear—editing text descriptions does not change clothes, and do not send customer to web UI.②【Production mainline · sequential, no skipping · ★storyboards before assets】set_script→rewrite_script→★review_script→extract_assets→storyboards(first storyboards · pure-text shot breakdown)→★review_storyboards→★Script discipline (endpoint-enforced, cannot bypass): all raw material (synopsis/outline/finished script all count) goes into set_script, **must go through rewrite_script to produce AI rewritten script**—pasting your own finished script directly into edit_rewritten_script to bypass rewrite will be rejected 400 (no rewritten script means nothing to edit); extract_assets likewise requires the rewritten script. All post-rewrite changes must use the structured format of AI output: edit script via edit_rewritten_script (polish/correct), character profiles via update_character, storyboards via update_shot/replace_shot_dialogue—do not go back and replace the whole script or write another truth source in settings; dueling truth sources are the top cause of consistency failures.★★**After rewrite_script succeeds once, do not rerun rewrite_script**: it restarts from the original full manuscript, discarding all current edits, and the new version is not guaranteed to preserve prior fixes (three-version tests oscillate). To fix, use edit_rewritten_script point edits (get_script full text → change only those scenes, copy the rest verbatim → submit whole text), free, seconds-level, deterministic; if rerun by mistake use get_script(include_previous=1) to recover previous version. generate_portraits_and_sheets(character sheet + concept images · build after storyboards: first use delete_character to delete appearing characters who **do not appear in any episode of the whole drama and are not planned for later episodes** before image generation—characters are drama-level; once deleted, no episode’s frame assembly includes them; this cannot be judged from current episode storyboards alone, keep if unsure (one character sheet costs far less than losing identity anchors in a later episode); the character sheet step generates images for **all undeleted appearing characters**, ignoring storyboard bindings, so kept characters are charged normally; voiceover characters (char_type=voiceover narrators/phone voices) are not image-generated and have no storyboard binding; **do not delete** them, dubbing relies on them)→★generate_color_script(color script · unified grading)→assign_voices(assign voice types; if narrator/character library has no fit → design_voice by description, then set_character_voice after sample approval)→★quote_scene_images+generate_scene_images(empty scene plates · required before frames)→frames(default first frames only)→★tail_frame_plan(free · which shots need independent last frames)→frames(frame_type=last_frame)→★chain_frames(seams · dry_run:true first)→★review_frames→videos→generate_tts→compose;★★【Do not skip seams · after last-frame completion, before review_frames】After first/last frames are ready, call chain_frames(dry_run:true, free) to view platform seam plan and estimated_points (copy free, reframe one image per seam), tell customer and execute without dry_run after confirmation; already chained seams are not planned, repeated calls do not charge again. ★After execution, reframe is **async image generation**: use get_jobs to watch first_frame generation rows for planned shots; wait until all pending/processing finish (failed: check error_msg; use chain_shot_from to rechains a single seam), then review_frames—while old first frame remains, get_storyboards frame_status is still ready, so it cannot show whether the new image is generating or failed. After get_jobs is clear, use get_storyboards to verify seam_state: replacement images rejected from promotion will not remain in get_jobs; that seam remains unchained (review_frames also reports seam_unchained); rechains per its action. If you review before landing, you reviewed old first frames; the token becomes invalid after new first frames land. Episodes generated shot-by-shot/batch likely were not auto-chained (get_storyboards seam_state=unchained means so); skipping does not error—the cost is mismatch between adjacent shots and jump cuts throughout final cut.★★【Do not skip last frames · frames are two passes】generate_frames defaults to first frames only. About 30% of shots have **end state ≠ start state** (large camera moves/object released/state changes) and need an independent last frame; the criterion is platform-side and cannot be guessed from storyboard text—therefore after first frames finish, you must call the free tail_frame_plan once to get per-shot list, then fill frame_type=last_frame (shots_needing_last_frame in generate_frames response is this count; if not 0 do not go straight to review_frames). Skipping does not error or block—the cost is that videos for those shots have only one anchor, so the model invents the end state: actions fail, large camera moves end back at the starting composition. Production tests: in 32 episodes, 30 generated only first frames for the whole episode, and 23 went all the way through video.★★【When last frame is blocked by TERMINAL_DESC_GATE: edit text, do not retry】For shots reporting 'this shot is marked as state-changing, but nowhere describes what it looks like at the end', use update_shot to write **what the image looks like at the end** into that shot’s last_frame_prompt, then regenerate last frame. ★Better: **avoid hitting it**—before last-frame generation, first inspect get_storyboards; shots with terminal_desc_missing=true are listed for the whole episode at once (free), fill their last_frame_prompt before generating and avoid any rejection. Per-shot query also exists (get_shot_prompts same field), but do not do that for dozens of shots. Retrying without filling the description is useless—the vendor prompt has no terminal-state section, so it still draws the first-frame pose and will be rejected again by terminal review, and each attempt is charged normally (production tests: last-frame success 9.4% without terminal description, 40.2% with it). Only use generate_shot_frame allow_missing_terminal for shots that truly should be 'almost unchanged'.★★【Do not skip empty scene plates · this step is often missed by third parties】Scene images are **background anchors**: every shot frame in the same scene anchors on it. Frames can still generate without plates, with no error and no block—the cost is **the first shot of every scene has no background anchor at all** (platform fallback is 'if missing image is discovered, generate one in background'; that plate is used by subsequent shots in the same scene, but the triggering first shot cannot wait for it), and the first shot is often the tone-setter; later backgrounds drift too. It is paired with character sheets: character sheets anchor people, scene images anchor locations; whichever is missing drifts. Progress self-check: get_pipeline_status generate_scene_images step (completed/total); review_storyboards also reports scene_plate_missing before frame generation.★★【Do not skip concept images · character sheet ≠ concept image】A character sheet is a single-person identity anchor; concept image is the platform-generated multi-angle turnaround from the character sheet, the root consistency anchor for shot frames/videos (angles, lighting, clothing rely on it). Frames can still generate with only character sheets, with no error—the cost is characters drift when angle changes and clothing differs every shot. Use generate_portraits_and_sheets for one-click two-step (each call advances one step; after character sheets are complete, call again to create concept images), or generate_character_sheets after character sheets. Progress self-check: get_pipeline_status generate_character_sheets step (completed/total, portrait_only=characters with character sheet only). ★Customer images: character sheet must be single person, single image, single angle, no text; scene image must be empty location with no people and no overlaid text—set_character_portrait/upload_scene_image auto-checks and rejects invalid with 422. ★Do not create character visuals/prop concept images/action templates before storyboards—storyboards are pure text and do not depend on any images; after storyboards the cast is known, delete non-appearing characters before image generation to save cost (action templates must be after storyboards anyway). Paid steps follow existing quote confirmation flow. Ads additionally need add_product+generate_product_sheet; MV uses set_mv_lyrics→generate_mv_story→generate_mv_script (if no finished song: after set_mv_lyrics first suggest_mv_song_styles→quote_mv_song→generate_mv_song→get_mv_song→select_mv_song).★★【④⑤ two new hard gates + agent personal QC】④Asset layer: after character sheets/concept images/scene images/prop images finish → review_assets (before generate_frames / generate_shot_frame; its token is asset_review_token and passed together with storyboard-layer review_token);⑤Video and dubbing layer: after video/dubbing/music finish → review_videos (before compose_episode); after final cut, run review_final_cut. ★After every review layer you must also **personally QC**: inspect assets item by item per returned agent_qc (download images, sample video frames, read text), answer checklist item by item, submit via submit_qc_report; for gray-release dramas, a review_token cannot enter the next step without the report; bad report is blocked by default like error. Platform judges existence; you judge likeness and correctness.★★【Single-shot path is also gated by reviews】: generate_shot_frame also requires storyboard-layer review_token; regenerate_shot_video also requires shot-image-layer review_token—do not expect single-shot tools to bypass review (production observed a workflow generating all 25 shots with single-shot frame tools and no gates; all final rework was fully charged). Generated frames **do not** invalidate the storyboard-layer token (fingerprint only covers storyboard content); only storyboard content edits—update_shot / import / add-delete shots / change character bindings—require one more review (free, seconds). Generating one shot’s frames invalidates the **shot-image-layer** token; before regenerating the next shot video, review_frames once.★★【For native-audio dramas, lock voices before batch video】When use_clip_audio=true(default), each shot’s voice is sampled independently by the video vendor; if not locked it will drift, and unifying after the fact requires per-shot regeneration. If customer-authorized voice source exists → clone_voice+set_character_voice before generate_videos; if not → for each speaking character first use single-shot quote_regenerate_shot_video→regenerate_shot_video on a shot with longer dialogue (generate_videos has no per-shot parameters and only batch-fills missing-video shots; single-shot regeneration also works for shots without video), then use set_voice_anchor_from_shot to select the voice from that shot, then generate remaining shots. get_pipeline_status native_voice_anchor lists unanchored_speakers not yet locked and stale_shots generated before locking that need regeneration. ★Worldview concept image = required by default (improves whole-drama consistency; many third-party platforms miss it): after storyboards, call generate_world_concept by default; still follows quote confirmation (tell customer estimated credits, confirm before charging)—do not charge silently and do not skip.★★【Color script】generate_color_script unifies grading across the whole film; run after storyboards and before frames; text step has no quote_*, postpaid by usage. Progress self-check: get_pipeline_status generate_color_script; review_storyboards reports color-script gaps. ★Action templates are optional experimental: call generate_motion_templates(action template extraction) after storyboards only if customer explicitly requests; text step postpaid by usage. First/last frames do not inject action templates by default; missing templates need not be made up and do not block image/video/final cut. Video templates may be cropped; delivery or quality gain is not guaranteed. ★Scene Bible(detailed per-scene setting) comes **after scene image generation**—refine based on generated scene images (no MCP tool yet; do on official site); do not make Scene Bible before scene images. ★Audio defaults to video native audio (use_clip_audio default on; skip TTS and use AI video’s built-in audio): when creating/updating drama settings, AI should proactively tell customer 'default uses video native audio; set use_clip_audio false if TTS dubbing is needed' and let customer choose. ★Default image model is ChatGPT Image 2.5 Flare(gpt-image-2.5-flare · unified whole-drama style): set image_model in create_drama/update_project_settings; omitted means default. Options: gpt-image-2.5-sunburst(same price · better Chinese glyphs/details)/gemini-3.1-flash-image(Banana 2 · 71 credits)/gemini-3-pro-image(Banana Pro · finer · 175 credits)/gemini-3.1-flash-lite-image(Banana 2 Lite · cheap · 31 credits)/doubao-seedream-5-0-260128(Seedream5.0); generate_frames can temporarily override one run. ★2.5 charges by input volume (base 11 credits + 18 credits per reference image); Banana/Seedream are flat price—shots with many reference images must include this in budget. ★Four video engine choices (drama-level · when AI creates a drama it must proactively guide engine choice by drama type and quote price differences for customer decision):【Decision tree】★Call get_production_menu first: whether each engine is currently available for realistic live-action / anime and other subject classes is decided by the availability it returns (unavailable entries carry customer_note and expected_until—relay them to the customer verbatim); do not assume from this description that any model is unavailable, and do not recommend models the menu marks unavailable. ①Realistic live-action drama→seedance-2.5 (strongest instruction following / face detail · pricing baseline 720p = 1×), or hailuo-3 when budget-sensitive (about 1/3 cost, 720p ≈0.33× · strong fidelity editing · can output 2K · but about 6 minutes per shot); ★After choosing, pass video_engine explicitly in create_drama / update_project_settings (the one the menu lists as available for this subject class)—if omitted, the platform only applies a style-based fallback stamp that is not guaranteed to be an engine the menu marks available; ②Stylized/animation/3D cartoon dramas · empty shots · product shots→wan3.0(about 40% price, 720p ≈0.4× · max 30 sec · minimum 2 sec billing · about 2 minutes per shot), use wan3.0-prime for rush delivery (720p ≈0.6× · about 1 minute); ★Always quote prices as relative multiples (seedance-2.5 720p = 1×); call quote_* before giving the customer absolute credits;③★Never choose wan3.0/prime for realistic live-action dramas—WAN output-side human-face review consistently rejects at 720p+, retry cannot fix;④★★For narrative dramas (dialogue, continuous story, stable shot rhythm), choose wan3.0/prime cautiously: WAN may **hard-cut camera positions inside a single storyboard shot** (tests: 11/12 shots had intra-shot jump cuts, versus seedance-2.5 1/6 and hailuo-3 0/5); final cut feels like 'the image jumps around within one shot, cuts too fast'. This is weak vendor instruction following and cannot be blocked at prompt level (our negative constraints are already included and tested ineffective); afterwards the only fix is regenerating with another engine. WAN fits stylized/empty/product shots that are inherently short and fast; for stable single-shot narrative choose seedance-2.5 or hailuo-3. After generation use scan_intra_shot_cuts to check;④b★★Dialogue-heavy dramas should choose hailuo-3 cautiously (different from above 'intra-shot self-cut'; this is about **whether all lines are spoken**): native-audio engine stops speaking at shot end and may ad-lib; tests show 'dialogue not fully spoken' rates hailuo-3 **50%** (26 shots, all generated after 8-30 native-audio repair, so engine itself), seedance-2.5 **23%** (294 shots); wan3.0 sample **insufficient, untested** for this dimension (26 samples all before same repair, only 2 after)—do not infer WAN is bad. When customer reports 'line not finished', first run scan_dialogue_coverage by family; do not default to lengthening shots (even among sufficiently long shots, 32% still missed full lines);⑤★Shot length control (all engines, especially WAN): keep each shot 3~5 seconds. The longer the shot, the more room the model has to improvise—test: one 16-second shot (neighbors all 3~5 sec) changed scenes 4 times within the shot; character disappeared for 4 sec then grew back from frame edge; customer sees 'a person appeared from nowhere'. For long performances, split into multiple short shots and connect with frame chains; do not write single shots over 15 sec;【Resolution decision】Draft/iteration: WAN dramas 480p (≈0.2× cheapest), others 720p; final delivery: seedance dramas 720p (for HD delivery choose 1080p, about 2.5× 720p), hailuo-3 dramas 1080p(=2K · ≈0.53×), WAN dramas 1080p(≈0.8×); hailuo-3 has no separate 480p tier (if selected, billed as 768P); set video_engine/video_resolution in create_drama/update_project_settings, ★must be decided before video generation—switching does not retroactively affect generated shots, and mixing within one drama causes style/identity drift. ★Slow image generation ≠ failure: each image takes tens of seconds to minutes; whole episode may take 10+ minutes. Poll get_storyboards frame_status—pending=still generating (wait patiently; do not call generate_frames again and waste credits), ready=done, failed=real failure. ★To change one shot’s image / make new character sheet take effect, use **single-shot regeneration generate_shot_frame** (platform automatically includes identity anchors, scene/prop references, style anchors for that shot to preserve whole-film consistency); generate_frames only batch-fills shots with **missing frames** and skips shots that already have first frames (normal, not 'rejected'). ★After first frames finish, call free tail_frame_plan to see which shots need independent last frames, then batch-fill with frame_type=last_frame. After changing a character sheet (set_character_portrait), stale_frames in the response are shots polluted by the old image and must be regenerated shot by shot. ★Never use external tools to make first/last frames and upload_shot_frame to 'change the image'—external images lack identity/style anchors, so characters/clothing/style will drift; that is the real source of unusable film. upload_shot_frame is only for customer-owned real footage.③【Optional enhancements · AI proactively informs customer · do only after quote confirmation】Art bible generation / visual lock extraction / scene groups / lip sync / posters / sound effects / music / subtitle translation—these improve consistency/quality and are mostly paid. ★AI should proactively tell customer these are available and provide quote (whether to run depends on execution mode: pro mode / no confirmed plan / this step customer-controlled → tell customer and proceed only after consent; do not decide for customer; managed step → do not ask, follow get_production_plan autopilot.default_decisions, platform logs in get_autopilot_log); neither silently skip nor charge without authorization. ★Two locking rules:①**Aspect ratio** is set at create_drama, locked at drama level; all later image/video/final cut use it, **do not change midstream** (generated content will have inconsistent aspect ratio and drift); default 9:16 if unset.②**5-7 sec per shot in shot breakdown is normal length optimized for AI video**, do not wrongly re-split because 'shots are long'—generate_storyboards **replaces all storyboards in the episode**, wasting generated images; backend blocks when storyboards already exist unless confirm_replace is supplied. ★Rewrite fidelity (default auto smart routing): when the set_script original is **already script-shaped** (scene headers/dialogue-line structure), rewrite_script automatically uses two-pass fidelity—customer dialogue is machine-gate locked line by line (missing one line causes internal rejection and redo), AI never adds plot; dramaturgical gaps (hooks/emotional anchors) are not auto-filled, but written into dramaturgy_suggestions returned by get_script (whether to adopt follows execution mode: pro mode / no confirmed plan / this step customer-controlled → tell customer and proceed only after consent; do not decide for customer; managed step → do not ask, follow get_production_plan autopilot.default_decisions, platform logs in get_autopilot_log). If original is novel/outline, it auto uses creative rewrite (AI lays hooks/emotional beats); both customer types get intended behavior, no manual switch needed. To override default use update_project_settings rewrite_pipeline(auto/two_pass/single_forced) and fidelity_enforce(1=hard fidelity gate). When customer says 'AI changed my script too much':①confirm full original entered set_script;②set rewrite_pipeline two_pass to force fidelity, then rerun rewrite_script;③after customer confirms character appearance, use update_character profile_locked=1 to lock profiles and prevent later extraction from overwriting appearance and changing faces in character sheets. ★If customer wants to rewrite script on **another AI platform** (common: third-party model says our rewrite 'changed too much', customer wants control): first call get_script_format_spec to obtain platform-accepted format contract (markdown template + external_prompt directly forwardable to external model + blank skeleton), give external_prompt+template+customer original to that platform; after receiving organized draft, **first call check_script_format** self-check (free · rule-only · no model); after errors are zero, two exits:【A】adopt_external_script directly adopts as shootable script (our AI not involved · seconds · no charge, requires external draft contains production-layer annotations);【B】set_script puts it back into original slot + rewrite_script two-pass fidelity (choose when external only handles story layer; platform fills annotations; customer-written annotations are stripped and rewritten on this path). ★Do not put external organized draft into edit_rewritten_script (400 if rewrite not run), and do not skip check_script_format before ingestion—noncompliant scripts are still blocked by gates, wasting a run.★★If the customer’s material is **already a finished storyboard table** (per-shot durations/framing/camera moves), neither path applies—use import_storyboard_table directly to create storyboards and skip rewrite and shot breakdown. The rewrite path will strip durations/framing/camera moves/STYLE/text cards as non-story content (production test: 8 shots 36 sec → 20 shots 109 sec). ★Both import channels are deterministic—wrong input is created as-is, so **get contract, self-check, then import**: storyboard table path uses get_storyboard_table_spec → check_storyboard_table → import_storyboard_table; if customer tools/spreadsheets can export structured data, or external AI can directly produce JSON, use get_bulk_import_spec → check_bulk_import → bulk_import_storyboards (only creates storyboards; characters/scenes/props are extracted from script by extract_assets; import binds by name to existing ones—extract first, then import). Both imports default with auto_complete(background AI fills professional fields + image/video prompts, text step postpaid; tell customer before call): if receipt started=true, poll get_autofill_status until done, then review_storyboards—autofill changes shots, so any earlier review token invalidates. Use get_pipeline_status for progress (returns project-type-specific steps).★★【Opening plan · first thing after creating drama · free】First ask basic video parameters (project type/aspect ratio/episodes × minutes per episode/subject: realistic_human realistic live-action · stylized anime/stylized · product/empty shots · native audio or dubbing), then call get_production_menu to get **currently available** three packages (effect description + real-time estimate including text steps + recommended budget + excluded items) and explain to customer—do not recommend models from memory; some models may be temporarily unavailable for some subjects, menu already filters them. Then let customer choose execution mode (pro self-control every step / auto one-click final cut / custom managed selected steps), budget budget_points, and automatic overrun cap (0/10/20/30/50%): **default recommendation** budget=selected package recommended_budget (upper bound excluding text ×1.2 plus text estimate), overrun=menu recommended_overrun_pct(30%)—QC regenerations are not in upper bound and are covered by overrun; recommendation is only recommendation, final numbers are customer’s, and if customer changes them use customer values. Explain summary clearly; only after explicit customer consent call confirm_production_plan(customer_confirmed:true)—never confirm for customer. For dramas with confirmed plan: before paid dispatch the platform rechecks model availability and quote upper bound ≤ budget×(1+overrun%); if blocked (402 BUDGET_WOULD_EXCEED / 409 MODEL_UNAVAILABLE), stop and ask customer; do not change model or budget yourself. confirm returns 403 PRODUCTION_PLAN_NOT_OPEN = this drama not open (gray release), follow original step-by-step confirmation flow.\n★【Post-completion QC】After extraction, use get_characters / get_scenes / get_props to verify profiles (names, appearance, era) match the customer script; after character sheets/concept images/scene images/prop images finish, review_assets handles coverage and quality review uniformly.",
@@ -33,7 +33,7 @@
   "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_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 prop bindings with update_shot prop_ids (also full overwrite, [] clears); 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.",
   "run_precheck": "(★recommended · free quality gate) Run pre-generation precheck before image/video generation to catch shots that would be rejected. Free, no credits charged. Strongly recommended before generate_frames/generate_videos to avoid wasting money on rejections.\nChecks these categories: ① live-action portrait / cloned voice authorization ② high-risk image-review words ③ voiceover coverage and large gaps ④ **self-contradictory instructions (kind=prompt-conflict)**—mutually exclusive requirements within the same shot (e.g. wide shot but close-up subject marked, standing and sitting at once). No correct image can satisfy these shots; if not fixed they will be rejected repeatedly and charge repeatedly. When present, first edit the storyboard per hints, then generate images, rather than retrying.\n★**You do not need to guess how to fix**: call plan_precheck_fix for platform proposals (which shot, change what to what), then apply_precheck_fix to persist (choose which items to accept; autopilot=accept all per execution mode: professional mode / unconfirmed plan / this step controlled by customer → explain to customer and only do it after customer agrees, do not decide for them; this step autopilot → do not ask customer, execute per get_production_plan autopilot.default_decisions, platform records it in get_autopilot_log)—more stable than blindly using update_shot yourself, which bypasses optimistic lock and pre-persist recheck. Some categories are not auto-fixed by system (blocked in proposals); only those require manual handling.\n★★**Also come back and run this when a shot repeatedly cannot be generated**—this tool is not only a preflight check. It also reports “same-shot same-cause repeated rejection circuit-broken (repeat-reject, auto-clears in 24h)” and “frame contract contradiction”; that is exactly the answer to “why this shot never works no matter how we reroll”. **Do not blindly reroll**: while circuit break is active, every reroll repeats the same full-price rejection.\n⚠️ It does **not** check whether the first frame is “before the action happens” (platform has no contract field for this yet), and does not replace get_health_report.",
   "run_drama_precheck": "(★free · read-only) **Whole-drama** health summary: get in one call how many issues each episode has and which episodes to fix first. run_precheck is episode-level; for dozens of episodes you would need dozens of calls and manual aggregation—call this first when scanning the full drama.\nReturns: episodes[] with per-episode blockers/warnings/by_kind (counts by rule code), totals for whole drama, attention[] = episodes most worth fixing first (sorted by blocker count, warning count descending).\n★**How to use**: inspect attention to set priority → call run_precheck on those episodes for itemized details → use plan_precheck_fix / update_shot to fix → rerun this tool to confirm totals decreased.\n⚠️ **“whole drama 0 issues” does not mean “everything was checked”**: to finish in one request, drama-level forcibly skips the only lint that needs image inspection (25s wall-clock per episode). not_covered in response lists skipped categories; to check those, run run_precheck on the corresponding episode.\n⚠️ episodes[].failed=true means that episode **was not checked successfully** (not “no issues”); just retry. truncated=true means episode count exceeded limit and scan is incomplete.",
@@ -48,7 +48,7 @@
   "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\").",
   "quote_autofill": "Quote: credits for autofill_storyboards. No charge, changes no data. Same basis as the completion itself: in fill-empty mode, shots with no gaps are skipped and not billed; overwrite:true bills every shot. Returns { shots_to_fill (shots that will actually call AI), shots_skipped_no_gap (shots with no gaps, skipped and not charged), estimated_points (budget upper bound; prepare balance by this), typical_points (usual cost) }—tell the customer both point figures, and after consent call autofill_storyboards with the **same** overwrite / storyboard_ids. Completion is a postpaid text step; this quote issues no quote_id and does not lock the price.",
-  "autofill_storyboards": "(Recommended) AI one-click fills missing storyboard fields across the episode (or only the shots in storyboard_ids); 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 (billed per shot that actually calls AI). ★**Quote first with quote_autofill** (same overwrite / storyboard_ids), tell the customer shots_to_fill and estimated_points / typical_points, and **run this tool only after the customer agrees**. ★When done, read the receipt from get_autofill_status (which fields were written on how many shots, how many skipped, how many still lack contracts) and tell the customer—the internal fields written here are not readable via get_storyboards, so don’t let the customer think they were charged for nothing. ★The platform already completed one round when storyboards were saved: in fill-empty mode, shots with no gaps left (all six narrative text fields present, vocal direction present on shots with dialogue, and contract present when contract auto-fill is on) are skipped with no AI call and no charge; only overwrite:true reruns the whole episode and bills every shot. ★Completion writes narrative/rhythm internal fields and composition contracts; get_storyboards / get_shot_prompts do not return these fields, so no visible change on read-back is normal—check the counts in the get_autofill_status receipt; it **does not change** image/video prompt text. ★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. ★To trial a small range first: pass storyboard_ids (1–50 shot ids of this episode, from get_storyboards); only those shots are filled, others make no AI call and are not charged; omit = whole episode. If a completion is already running in this episode, the subset does not start: the receipt returns started=false, reason=fill batch already running; call again after get_autofill_status reaches done.",
+  "autofill_storyboards": "(Recommended) AI one-click fills missing storyboard fields across the episode (or only the shots in storyboard_ids); 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 (billed per shot that actually calls AI). ★Before running, confirm character/scene/prop bindings (check get_storyboards character_ids / scene_id / prop_ids shot by shot against the customer's original). If a missing binding turns up after auto-completion, just fix it with update_shot; **do not re-import the episode**—re-import replaces the storyboards, discards the auto-completion and charges again. ★**Quote first with quote_autofill** (same overwrite / storyboard_ids), tell the customer shots_to_fill and estimated_points / typical_points, and **run this tool only after the customer agrees**. ★When done, read the receipt from get_autofill_status (which fields were written on how many shots, how many skipped, how many still lack contracts) and tell the customer—the internal fields written here are not readable via get_storyboards, so don’t let the customer think they were charged for nothing. ★The platform already completed one round when storyboards were saved: in fill-empty mode, shots with no gaps left (all six narrative text fields present, vocal direction present on shots with dialogue, and contract present when contract auto-fill is on) are skipped with no AI call and no charge; only overwrite:true reruns the whole episode and bills every shot. ★Completion writes narrative/rhythm internal fields and composition contracts; get_storyboards / get_shot_prompts do not return these fields, so no visible change on read-back is normal—check the counts in the get_autofill_status receipt; it **does not change** image/video prompt text. ★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. ★To trial a small range first: pass storyboard_ids (1–50 shot ids of this episode, from get_storyboards); only those shots are filled, others make no AI call and are not charged; omit = whole episode. If a completion is already running in this episode, the subset does not start: the receipt returns started=false, reason=fill batch already running; call again after get_autofill_status reaches done.",
   "enhance_shot_prompts": "(Optional enhancement · ★not required · has side effects) AI batch-enhances the whole episode's image_prompt. ★It **rewrites existing prompts** (including manually edited ones); and **must be done before generate_frames**—changing prompts after image generation makes images stale and requires paid regeneration. Not required to get a film through the pipeline; do only if the customer explicitly requests it. Async in background, postpaid text step.",
   "complete_ending_motifs": "(Optional enhancement·★not required·conditional) Complete missing visual motifs in the ending segment (graft visual echoes onto ending shots). ★Prerequisite: this drama already has motifs (none = no-op); this will **modify ending shot action/descriptions**, so do it before generating images (otherwise already-generated ending shots become stale). Backend async, billed after the text step.",
   "tail_frame_plan": "★Free read-only: which shots in this episode **need independent last frames** (shots whose terminal state ≠ initial state—large camera move/object released/state change). It uses the same criteria the platform uses for video generation; you cannot guess this yourself, so call it once after first frames are done. Returns shots_needing_last_frame(total), ready(shots with first frames already available and can get last frames now), pending_first_frame(shots that need last frames but whose first frames are not ready yet—call this tool again after first frames finish). After getting the ready list: use quote_frames + generate_frames with frame_type=last_frame to batch-fill. ★After last frames are filled (or this tool reports 0), the next step is seams: chain_frames(dry_run:true) to view plan and estimate, execute after customer confirmation, then review_frames. ★Skipping last frames will not error, but those shots have only one first-frame anchor during video generation, so the model improvises the terminal state—bad action completion, large camera moves ending back at the starting composition, etc. usually come from this. Zero cost, callable anytime.",
@@ -100,6 +100,10 @@
   "generate_scene_images": "After confirmation, batch generate **empty scene plates** (one character-free background image per scene): backend async, only fills scenes that \"do not yet have images\". ★Do this **before generating shot frames**. Skipping will not error or block you, but the cost is real: the platform fallback is \"when frame generation finds the scene has no image → generate one in the background\"; that generated image only benefits **subsequent** shots in the same scene. The triggering shot cannot wait for it, so **the first shot of each scene has no background anchor**—and the first shot is often the tone-setting shot; backgrounds will also drift across subsequent shots. It pairs with character sheets: character sheets anchor people, scene images anchor settings. ★If the output is wrong, do not rerun this tool (it only fills missing scene images and skips all existing ones): `get_scene_prompt` read the text → `update_scene` edit image_prompt → `regenerate_scene_image` regenerate one scene. ★For non-contemporary or surreal genres, set `set_era_contract` first, otherwise plates may be drawn in the wrong era and all downstream shot frames in that scene will follow. ★Check progress via get_pipeline_status generate_scene_images step. ⚠️ 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 is customer-controlled → explain to the customer and run only after customer approval; do not decide for them. This step in autopilot → do not ask the customer; follow get_production_plan autopilot.default_decisions, and the platform records it in get_autopilot_log). For autopilot steps, the quote must be within the hard budget cap; if blocked by 402 BUDGET_WOULD_EXCEED, stop and ask the customer. ★**Image-generation quotes (character sheets/scene images/frames) provide two numbers**: estimated_points is the **upper bound** (estimated by that model’s maximum reference-image count, ensuring you do not start with too-low a budget and get interrupted by 402 halfway); typical_points in the same response is the **typical cost**. Tell the customer both—only saying the upper bound makes it seem much more expensive (the full-reference upper bound can exceed the typical value by more than 2×), while only saying the typical value may leave insufficient balance. Under fixed-price models they are equal, in which case one number is enough. Video quotes and charges use the same function; this interval does not exist there.\n★【Post-completion QC·free】After generation, wait for images to be saved (poll corresponding get_* status; do not call again while pending), then call review_assets for asset-layer review (missing images / generating / failed / rejected by consistency gate / prop era conflict / color script). Tell the customer the findings verbatim, fix according to action, then re-review; then personally inspect each image according to the returned agent_qc (whether it resembles the profile, whether it is the same person, whether the era is correct; for character sheets, whether all angles are complete and proportions/structure are correct; whether props and scene images make sense in the story—check the referenced used_in_shots shots), submit_qc_report to submit the QC report; when generating shot frames, pass its review_token as asset_review_token to generate_frames / generate_shot_frame.",
   "upload_image": "Upload a local image to our COS and return image_url (browser/client uploads bytes directly to COS, not through the business server). Used as a reference image for video editing, or to get a URL before registration. Free.",
   "set_character_portrait": "Use the customer's own image as the character sheet (identity anchor, higher priority than AI-generated; later AI regeneration will not overwrite it by default). ★★Image requirements (platform auto-checks before registration; noncompliance returns 422 and does not register): **only this one character** (no other people/group photo/background passersby); **single image, single angle** (not a collage/nine-grid/multi-view turnaround—the platform generates turnarounds from the character sheet); front or 3/4 view, clear unobstructed face, clean background; **no text anywhere on the image** (watermarks/subtitles/name labels/logo/text on clothing are all forbidden; text will be replicated into every shot). Before uploading, first inspect the customer's image; if noncompliant, ask the customer to replace it first, do not upload directly. If rejected, tell the customer the issue in message verbatim; only if the customer has seen the issue and explicitly insists on using this image should you retransmit with allow_issues:true (auto-check may be wrong). ★Changing the image invalidates existing derived assets (turnarounds/multi-angle avatars/hair·body references) and rebuilds the face lock, but **the turnaround is not automatically regenerated**—after changing, you must run generate_character_sheet(character_id) to regenerate the turnaround from the new character sheet (next_step in the response will prompt this), otherwise the character has only the character sheet as an anchor. ★After changing the image, the response contains stale_frames=[{storyboard_id,storyboard_number,frames}]—the first frames of these shots were generated from the old character sheet and are contaminated. To make the new character sheet take effect: for each stale_frame, use quote_shot_frame+generate_shot_frame to regenerate that shot (the platform will automatically use the new character sheet/turnaround/face lock as anchors to preserve full-film consistency). No need to specify model/first/last frames shot by shot yourself. ★Never self-make first/last frames and then upload_shot_frame—external images lack character identity anchors/style anchors, so people·costumes·style will drift; that is the root cause of unusable films (not \"preventing unusable films\"). ★Changing the image only **unlinks references**; files for the old character sheet/turnaround are not deleted. old_assets in the response lists unlinked old assets item by item: unlinked=[{kind,url,in_history}] (in_history=false means the platform kept no record—typical for a customer's uploaded old character sheet; save the url yourself if you need to keep it), physically_deleted is always empty. If the customer says \"delete the old image\", tell them truthfully that it is no longer used but the file still exists; do not say it has been deleted. Pass either a local file (file_path, auto-upload to COS) or an already-hosted image URL (image_url). Registration is free; content checking is a small visual audit charged postpaid by usage.\n★【Post-completion QC · free】After generation, wait for images to be stored (poll the corresponding get_* for status; if pending, do not call again), then call review_assets to audit the asset layer (missing image / generating / failed / rejected by consistency gate / prop-era conflict / color script), tell the customer findings verbatim, fix according to action and re-audit; then personally inspect each image according to the returned agent_qc (whether it matches the profile, is the same person, era is correct; for the turnaround itself, whether all angles are complete and proportions/structure are correct; whether prop and scene images make sense in the plot—compare the shots listed in used_in_shots), submit_qc_report to submit the QC report; when generating shot images, pass its review_token as asset_review_token to generate_frames / generate_shot_frame.",
+  "quote_derive_character_portrait": "Quote for deriving a character sheet (free, no image generation). Uses one character's sheet as the reference for image-to-image: keeps facial proportions, face shape, eye shape and the position of facial marks (moles/scars), and only progresses the age to age_stage. ★Typical use: **the same person at different ages was created as several separate characters**—batch sheet generation gives them no shared identity anchor, so faces come out as different people and moles switch sides; pick the one whose sheet is correct as the reference (reference_character_id) and derive the other ages one by one. In cross-character derivation, clothing and hairstyle follow the **target character's profile** appearance and wardrobe lock, not the reference image's outfit—before deriving, check with get_characters that the target's appearance describes clothing for that age, and fix it with update_character if not; omitting reference_character_id = use the target's own sheet as the reference, change age only, no clothing injected. Pricing: each candidate = the drama's image model price with 1 reference image (e.g. gpt-image-2.5-flare: 11+18=29 credits) × count. Pass the returned quote_id to derive_character_portrait. ⚠️ Batch quote confirmation flow: first call the corresponding quote_* tool to get estimated_points and quote_id, then use quote_id to call this tool (quote confirmation follows execution mode: professional mode / unconfirmed plan / customer-controlled stage → explain to the customer and proceed only after customer consent, do not decide for the customer; autopilot stage → do not ask the customer, follow get_production_plan autopilot.default_decisions, and the platform records it in get_autopilot_log). Autopilot-stage quotes must fit 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) give two numbers**: estimated_points is the **upper bound** (estimated by the max number of reference images for that model, ensuring you don't start with an under-budget and hit 402 halfway); typical_points in the same response is the **typical cost**. Tell the customer both—only stating the upper bound makes it look much more expensive (the full-reference upper bound can exceed typical by over 2x), while only stating typical may leave insufficient balance. For fixed-price models they are equal, so one number is enough. Video-generation quote and charging use the same function, so this range does not exist.",
+  "derive_character_portrait": "Derive character sheet candidates per the quote (generated in the background, charged by usage). Only produces candidates and **does not replace** the target character's current sheet; returns image_generation_ids—poll get_derived_portrait_candidates until completed, show the candidates to the customer, and after they pick one call adopt_derived_portrait to register it. Parameters always follow the quote (passing quote_id alone is enough; passing different parameters returns 409). If the reference character's sheet changed or the drama's image model was changed after quoting ⇒ 409, quote again.",
+  "get_derived_portrait_candidates": "Check progress and images of derived character sheet candidates (free). Returns {id,status,image_url,error_msg} for each; pending/processing means still generating—do not derive again (double charge). Once all are completed, **inspect each image yourself**: is it the same person as the reference character (features, facial mark positions), is the age right, does the clothing match the target character's profile—then let the customer choose.",
+  "adopt_derived_portrait": "Register the derived candidate chosen by the customer as the target character's sheet (registration is free; the content check is a small visual review, postpaid by usage). Same effect as set_character_portrait: later AI regeneration will not overwrite it by default; the old design sheet/multi-angle headshots/full-body reference are invalidated and **not regenerated automatically**—after registering, follow next_step in the response and run generate_character_sheet(character_id) first; stale_frames in the response are shots whose first frame still uses the old sheet, regenerate them shot by shot with quote_shot_frame + generate_shot_frame. If the content check fails it returns 422 without registering; relay the issues to the customer verbatim and only pass allow_issues:true if the customer insists.\n★【Post-completion QC · free】After generation, wait for the image to land in the DB (poll the corresponding get_* status; if pending, do not call again), then call review_assets to review the asset layer (missing image / generating / failed / rejected by consistency gate / prop-era conflict / color script), relay findings to the customer verbatim, fix per action and review again; then personally inspect each image according to the returned agent_qc (whether it matches the profile, is the same person, era is correct; whether the design image itself has complete angles and correct proportions/structure; whether props and scene images make sense in the plot—check the shots in material used_in_shots), submit_qc_report to submit the QC report; when generating shot images, pass its review_token as asset_review_token to generate_frames / generate_shot_frame.",
   "upload_shot_frame": "Use a **customer-owned image** as a shot's first_frame or last_frame. last_frame is optional—only pass it when you want to fix a shot's ending image (large camera move/reveal shot); normally only first_frame is needed. Marks any existing video for that shot as stale and awaiting regeneration. Auto-upload + registration. Free. ⚠️ Only use for customer-provided material, or **local repair of this shot's platform candidate** (recovery_options upload_fixed: crop/color-grade/fix small defects on the original image returned by get_frame_candidates, then upload after customer confirmation). To \"redraw a shot\", use generate_shot_frame to let the platform regenerate it—images generated from scratch by external tools do not carry this film's identity anchors and style anchors, so people/costumes/style will drift.",
   "register_external_delivery": "Register an externally post-produced final cut; the server verifies sha256, size, and duration. Free. If you have the original export, pass the export-time handoff_pack_id and handoff_manifest_sha256; the platform uses the original frozen manifest and does not guess the source from the latest materials at registration time. Without the original export, the source is marked unknown. Registration does not mean customer acceptance; after traceability is enabled, you still need set_current_delivery to choose the current version and confirm_delivery_acceptance to record the customer's explicit confirmation. Pass either file_path or file_url.",
   "list_deliveries": "List **all final cut versions** for this episode (new→old; platform final cuts and external deliveries share one version sequence). Each entry includes sha256, duration, is_current, and full manifest. Free.\n★source=platform: every platform final cut version (compose_episode / rerender_episode / multi-aspect) is **automatically registered**; the manifest records **the exact timeline used for rendering**—for each shot, whether it used original footage/composited footage/retracked output/lip-sync output (source_kind), which files were used for dialogue/music/SFX, subtitle count and text hash, file sha256, and dialogue audit family counts at registration time. Use this as the authority for delivery notes and for verifying \"which version was delivered\"; do not rely on memory. Platform versions **do not automatically become the current delivery version**; when the customer selects a version, use set_current_delivery to point to it.\n★source=external: external post-produced final cut registered by register_external_delivery.",
@@ -134,7 +138,7 @@
   "scan_voice_consistency": "★For original-voice dramas (video has built-in human speech), run this when the customer reports \"the same character's voice differs across shots / voice drifted\". Free (local inference, no vendor call). For each shot with dialogue, listens to vendor-generated human speech: whether the dialogue was fully spoken, and whether the voice resembles the timbre anchor bound to that character. **Async**: returns immediately; background full-episode scan takes about 10 minutes. Only one scan per episode can run at the same time (repeat calls return started=false). By default skips shots already scanned for the current video; rescan=true rescans all. Use get_voice_consistency to check progress and per-shot results.",
   "get_voice_consistency": "Check progress and per-shot results of the voice consistency scan (started by scan_voice_consistency). Free. summary.voice_mismatch = shot numbers whose voice does not resemble the character timbre anchor (focus on these); dialogue_issues = shots where dialogue was incomplete/wrong/extra speech appeared; not_scanned_or_stale = not scanned yet or video changed and needs rescan. speaker_verdict=uncertain means the human speech is too short to judge; it is not an issue. For shots with inconsistent voice: first use get_pipeline_status native_voice_anchor to confirm the character has a bound voice, then regenerate_shot_video.",
   "scan_dialogue_coverage": "★When the customer reports \"cut before the line finished / only half the dialogue was spoken\", run this first. Default **free, zero charge** (read-only access to persisted transcription audit results). Compares each original-voice shot's video audio track against the dialogue at word level, and reports conclusions by family: truncated (stops halfway through the line) / off_script (most spoken content is not the dialogue: improvising, repeating previous shot, only ambience) / extra_speech (dialogue is fully spoken but extra speech is added) / minor_gap (sporadic missing words, transcription error, ignore) / ok. ★Interpretation: the three reportable families have **different remedies**; do not simply lengthen every shot—measurements show 21% of shots with sufficient length still fail to finish the line, so \"too short\" is rarely the real cause (the platform already auto-raises duration by dialogue when saving storyboards). The correct fix for truncated/off_script is regenerate_shot_video (how much the vendor says is random each time; rerolling often gets the full line); if the same drama repeatedly has off_script, switch engine. ★never_audited is the most important section of this report: those shots have never been checked; \"not checked\" does not mean \"no issue\". rescan=true will run ASR comparison for them (compute-intensive, not instant; limit controls per-run cap), default does not run. TTS-dubbed shots are out of scope (TTS necessarily reads the full line; low coverage can only be transcription error). If the same episode also has \"cuts too fast\", that is a separate issue; run scan_intra_shot_cuts.",
-  "update_shot": "Shot-by-shot edit: change a single storyboard shot's text content (shot size/action/dialogue/visual description/camera movement, etc.), facial expression (expression_hint), duration (duration), final cut speed (speed_factor), character binding (character_ids), voice-over marker (character_presence), and wardrobe binding (active_wardrobe_id / appearance_wardrobes). Send only fields to change; all others stay unchanged. ★Any shot edit (accepted or rejected) invalidates unconsumed quotes covering this shot; generation then returns 409 QUOTE_INVALIDATED—edit first, read back to verify, then quote. **Free** (pure text DB write). ★Changing dialogue automatically invalidates generated TTS voice-over and subtitles for this shot (tts must be regenerated); text edits do not auto-regenerate images/video. To make visuals follow text changes, edit then regen the corresponding shot. Use get_storyboards to inspect results (each shot includes character_ids / character_bindings / scene_id / prop_ids / active_wardrobe_id / appearance_wardrobes). ★★【Change clothes here, not in text】What appears in image generation is determined by **wardrobe binding**: single-character shots use active_wardrobe_id (one outfit for the whole shot); multi-character shots use appearance_wardrobes (per character). Writing \"wearing X clothes\" in description/action will not change clothes. Use list_wardrobe for wardrobe id; edits do not auto-regenerate images. To update visuals, regenerate this shot's first frame then video. ★★For native-audio shots (vendor-native audio), after changing dialogue the shot video is marked \"needs regeneration\"—because spoken lines are **baked into the video audio**. If you final-compose without regeneration, the final cut still speaks the old line (typical symptom: dialogue seems to have moved to another shot). compose_episode lists these shots under advisory `stale_video_after_edit`; correct handling is regenerate_shot_video before final compose. ★You may also directly edit this shot's four prompt bodies (image_prompt/video_prompt/first_frame_prompt/last_frame_prompt): read current values with get_shot_prompts first; do not overwrite from scratch. @char:N / @scene:M in the body are supplemental reference markers for image generation; keep them unchanged. ★Which character sheet is injected is determined by character_ids, and background by scene_id: deleting markers will not remove already-bound people from the image. To make someone not appear, edit character_ids; if they are voice-only, set character_presence to voice_only. Conversely, do not write @char markers for unbound characters—this will inject their image. ★★【If last-frame generation is blocked, edit here】If last-frame generation reports \"this shot is marked as a state change, but nowhere describes what it looks like at the end\" (TERMINAL_DESC_GATE), fix by writing **what the final image should look like** into this shot's last_frame_prompt, then regenerate the last frame. Do not retry image generation—shots of this type (action_motion_class=state_change without terminal state) historically succeed at 9.4%, versus 40.2% with terminal-state description; without adding the description, the vendor prompt has no terminal-state section, so it still draws the same as the first frame, is rejected again, and each regeneration still charges normally. terminal_desc_missing=true from get_shot_prompts is this signal.",
+  "update_shot": "Shot-by-shot edit: change a single storyboard shot's text content (shot size/action/dialogue/visual description/camera movement, etc.), facial expression (expression_hint), duration (duration), final cut speed (speed_factor), character binding (character_ids), prop binding (prop_ids; full overwrite, [] clears—use it to fix a prop missed at import instead of re-importing the whole episode; edits do not auto-regenerate frames/video), voice-over marker (character_presence), and wardrobe binding (active_wardrobe_id / appearance_wardrobes). Send only fields to change; all others stay unchanged. ★Any shot edit (accepted or rejected) invalidates unconsumed quotes covering this shot; generation then returns 409 QUOTE_INVALIDATED—edit first, read back to verify, then quote. **Free** (pure text DB write). ★Changing dialogue automatically invalidates generated TTS voice-over and subtitles for this shot (tts must be regenerated); text edits do not auto-regenerate images/video. To make visuals follow text changes, edit then regen the corresponding shot. Use get_storyboards to inspect results (each shot includes character_ids / character_bindings / scene_id / prop_ids / active_wardrobe_id / appearance_wardrobes). ★★【Change clothes here, not in text】What appears in image generation is determined by **wardrobe binding**: single-character shots use active_wardrobe_id (one outfit for the whole shot); multi-character shots use appearance_wardrobes (per character). Writing \"wearing X clothes\" in description/action will not change clothes. Use list_wardrobe for wardrobe id; edits do not auto-regenerate images. To update visuals, regenerate this shot's first frame then video. ★★For native-audio shots (vendor-native audio), after changing dialogue the shot video is marked \"needs regeneration\"—because spoken lines are **baked into the video audio**. If you final-compose without regeneration, the final cut still speaks the old line (typical symptom: dialogue seems to have moved to another shot). compose_episode lists these shots under advisory `stale_video_after_edit`; correct handling is regenerate_shot_video before final compose. ★You may also directly edit this shot's four prompt bodies (image_prompt/video_prompt/first_frame_prompt/last_frame_prompt): read current values with get_shot_prompts first; do not overwrite from scratch. @char:N / @scene:M in the body are supplemental reference markers for image generation; keep them unchanged. ★Which character sheet is injected is determined by character_ids, and background by scene_id: deleting markers will not remove already-bound people from the image. To make someone not appear, edit character_ids; if they are voice-only, set character_presence to voice_only. Conversely, do not write @char markers for unbound characters—this will inject their image. ★★【If last-frame generation is blocked, edit here】If last-frame generation reports \"this shot is marked as a state change, but nowhere describes what it looks like at the end\" (TERMINAL_DESC_GATE), fix by writing **what the final image should look like** into this shot's last_frame_prompt, then regenerate the last frame. Do not retry image generation—shots of this type (action_motion_class=state_change without terminal state) historically succeed at 9.4%, versus 40.2% with terminal-state description; without adding the description, the vendor prompt has no terminal-state section, so it still draws the same as the first frame, is rejected again, and each regeneration still charges normally. terminal_desc_missing=true from get_shot_prompts is this signal.",
   "rederive_shot_contract": "Using this shot's **current** prompt body and character binding, let the platform re-derive the composition contract (how many visible people, whether the subject is a person or a partial/object, shot size). The contract itself is internal: cannot be read or edited directly. This tool only returns outcome: updated (changed and effective) / unchanged (derived result same as current) / rejected (derived result self-contradictory, not adopted, original contract kept) / no_candidate (no usable result, original contract kept) / stale (shot changed during derivation, result not written; call again after edits), plus note for next step. Insufficient credits returns 402. ★When to use: image generation/precheck/review repeatedly says the number of people is wrong, or a partial shot (hand/prop close-up) is treated as a full-person shot in generation or review, and you have already edited text or bindings—the autofiller only fills blanks and does not overwrite existing contracts; without this tool, edits will not enter the contract. ★Correct order: first update_shot to make the image text correct (who is visible, who is voice-only via character_presence voice_only, unbind anyone who should not appear from character_ids), then call this tool; calling without text edits usually returns unchanged. ★One text AI call, postpaid by token (same chain as autofill_storyboards); inform the customer before calling. ★Only changes this one contract field; does not touch dialogue/prompts/other specialized fields. Generated first/last frames are not auto-regenerated; to update visuals, regenerate frames for this shot (quote first). ★updated invalidates unconsumed frame/video quotes for this shot and the same episode; quote again afterward.",
   "get_shot_prompts": "Read the four prompt **bodies** for one shot (image_prompt=first-frame image / video_prompt=dynamic performance / first_frame_prompt=what it looks like at start / last_frame_prompt=what it looks like at end), for direct fine-tuning then writing back with update_shot. Free. ★terminal_desc_missing=true in the response means this shot is marked as a \"state change\" but none of the three places describes the terminal state—last-frame generation will be blocked by the pre-gate. Fix by writing the end state into last_frame_prompt (do not retry image generation; retry will inevitably be rejected again and still charged). ★Also returns the current description (visual description) and lighting (shot lighting)—review_storyboards forbidden-term matches are often in description, so read it here before editing; write lighting into lighting. ★Also returns expression_hint (author-specified facial expression for this shot; null=unspecified, platform infers from dialogue). Edit it with update_shot. expression_inferred is the storyboard AI's inferred expression when the script did not specify expression (read-only; null=no inference, or this shot's dialogue/action/mood/description/intensity changed and the inference is expired and no longer used); it has lower priority than expression_hint—if inference is unsatisfactory, write expression_hint with update_shot to override it. ★Per-shot on demand: read only the shot you edit (episode list get_storyboards does not include prompts). ★Returned asset_tokens are supplemental reference markers in the body (@char:N / @scene:M); keep them unchanged when rewriting. Which character sheet is injected is determined by bindings (character_ids / scene_id in get_storyboards); deleting markers will not remove bound characters. Markers with #variant are the only source for that variant image. Writing a marker for an unbound character will inject that character's image. ★This is the body layer in the storyboard sheet; during image/video generation the platform also appends identity anchors, consistency constraints, and reference-image instructions (not here, and you do not need to write them). Changing prompts does not auto-regenerate images/video; to update visuals, regen the corresponding shot.",
   "rerender_episode": "Recompose the final cut from the current timeline (use after shot edits/cropping). **Free** (pure ffmpeg+COS), asynchronous in background.",