@starreel/mcp 0.1.175 → 0.1.189

package/SKILL.md

@@ -702,6 +702,19 @@ content that will be rejected.
     lets it through). Relay your QC findings to the user verbatim. Listing a
     `ref` you never opened is signing off on the user's money.
 
+    **Edited a shot or two? Re-review incrementally, not the whole episode.**
+    The single-shot tools (`generate_shot_frame`, `regenerate_shot_video`) only
+    check the target shot and its two neighbours, so edits elsewhere do not
+    invalidate the token for them. When they do get rejected (the shot, a
+    neighbour or a shared asset changed), call the same `review_storyboards` /
+    `review_frames` / `review_assets` with `base_review_token` set to the
+    previous token of that layer (its QC report must already be in with
+    `verdict: "pass"`). Only the changed shots and their neighbours are listed
+    in `agent_qc.materials` and `findings` (`incremental.applied: true`), and
+    your report only has to cover those. If shared assets changed or the base
+    is not eligible, the server falls back to a full review and says why in
+    `incremental.reason`.
+
     **Script QC is an assessment with suggestions the user decides on.** At the
     script layer the materials include the user's own draft (`script:original`)
     as well as the rewrite (`script`). Assess the user's draft itself first —

package/dist/i18n/tools.en.json

@@ -42,7 +42,7 @@
   "review_storyboards": "【Hard gate ② · free】Review storyboards: forbidden terms (will be rejected by vendors and waste credits), shot duration distribution, repeated adjacent composition, character blocking drift in the same scene, emotional curve peaks/valleys, key-shot markers. ★Must run this tool before generate_frames—storyboard issues become a whole episode of wasted images once generated and cannot be fixed shot by shot. Fix per findings.action using update_shot/split_shot, then review again. ★A finding with code=forbidden_term includes `terms` (specific matched terms, e.g. \"background music\", \"strong light\") and `shots` (shot numbers); use those two to update_shot and remove them, no need to guess word by word. ★Forbidden terms are judged with **negative semantics**: writing \"no background music\" or \"do not add music\" is not a violation (it is obeying the constraint), so no edit is needed. ★\"Action overload\" in warnings (action_overload, advisory only, non-blocking): one shot contains more independent actions than its duration can support; before video generation, use split_shot to split it or delete actions—slow motion/dissolves cannot rescue it after final cut. Ignore if multiple people each do one thing or it is a naturally continuous action chain.\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors.",
   "review_frames": "【Hard gate ③ · free】Review the shot image layer: character identity-anchor coverage (characters without character sheets will drift in shots), image-generation failure rate, orphan character variants, scene images polluted by people. ★Must run this tool before generate_videos—video generation is the most expensive step in the whole chain, and generating a whole episode of video from drifting first frames is the most typical wasted-film failure. Fix per findings.action (mostly generate_character_portraits / generate_shot_frame single-shot regeneration), then review again. ★Also reports **inter-shot seams** (warning, non-blocking): code=seam_unchained (marked continuous but never did first/last-frame chaining, or initiated chained regeneration never landed / first frame was regenerated again after chaining) / seam_broken (chained but not connected, or previous shot's last frame was regenerated after chaining); shots is the shot whose \"seam with previous shot\" has the issue. Cheapest to fix before video generation—videos are generated from first frames; if a first frame does not match the previous shot's last frame, the final cut has a jump cut. See action for fixes (whole episode chain_frames dry_run first; single seam chain_shot_from_prev / chain_shot_from).\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors.",
   "review_assets": "【Asset-layer hard gate · free】Review character appearance images, scene images, and prop images used **on screen** in this episode—coverage and quality: on-screen character missing character sheet / missing reference image / still generating / generation failed / reference image rejected by consistency gate (hint includes rejection reason); scene missing empty-scene base plate; prop referenced by storyboard missing prop image / rejected; prop image conflicts with this shot's era/form; missing color script (warning). ★Call once after producing character sheets, reference images, scene images, and prop images; must review before generate_frames / generate_shot_frame—pass the returned review_token as **asset_review_token**, together with the storyboard-layer review_token (both are required). Only checks the assets themselves: generating shot images later will not invalidate it; changing character sheets / scene images / prop images will invalidate it, just review again (free, seconds). Explain findings to the customer one by one (code=issue type, names=which character/scene/prop, shots=affected shot numbers, action=which tool to call to fix).\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors.",
-  "review_videos": "【Video and dubbing-layer hard gate · free】Review this episode's videos and dubbing—coverage and quality: missing video / still generating / generation failed / vendor rejected; first frame changed but video was generated from an old frame (video_stale); suspected hard cut at clip end, unexpected human voice in no-dialogue shots (warning); dubbed drama: dialogue shot missing dubbing, speaking character has no voice, missing narrator role; original-audio drama: shots not attached to current voice line at export time, characters without locked voice lines; missing music (warning). ★Call once after video, dubbing (generate_tts), and music are produced; must review before compose_episode, passing the returned review_token. Finer checks (requiring decoding picture/audio tracks) are available via scan_intra_shot_cuts / scan_dialogue_coverage / audit_silent_shot_audio; after assembling the final cut, run review_final_cut.\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors.",
+  "review_videos": "【Video and dubbing-layer hard gate · free】Review this episode's videos and dubbing—coverage and quality: missing video / still generating / generation failed / vendor rejected; first frame changed but video was generated from an old frame (video_stale); suspected hard cut at clip end, unexpected human voice in no-dialogue shots (warning); dubbed drama: dialogue shot missing dubbing, speaking character has no voice, missing narrator role; original-audio drama: shots not attached to current voice line at export time, characters without locked voice lines; missing music (warning). ★Call once after video, dubbing (generate_tts), and music are produced; must review before compose_episode, passing the returned review_token. Finer checks (requiring decoding picture/audio tracks) are available via scan_intra_shot_cuts / scan_dialogue_coverage / audit_silent_shot_audio; after assembling the final cut, run review_final_cut.\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors. ★If the response includes post_production_advisory = narrative-required effects that the script marks as post-production are still unhandled (the platform will not composite them): tell the client verbatim and use get_post_production_checklist to see the list.",
   "submit_qc_report": "Submit the QC report made by you (agent) after personally inspecting materials. Free. First call the corresponding review_* layer (script / storyboards / assets / frames / videos), open each returned agent_qc material in materials, answer every checklist item, then call this tool. ★The platform only verifies the report is **complete**, not whether your conclusions are correct: every checklist id must be answered (ok / issue / na; issue must include note explaining which item has what problem); every ref in materials must be listed in inspected (omit one and it is rejected with the missing refs named); if there are issues, set verdict=issues and list them in issues; reporting pass when issues exist will be rejected. ★Do not go through the motions: listing something in inspected without opening it means you signed off for the customer—wasted output will still be charged. ★When verdict=issues, this token cannot proceed to the next step by default: explain the problems to the customer, fix, then review + QC again; only if the customer is clearly informed and insists on proceeding as-is should the next step include acknowledge_review:true. ★suggestions (change suggestions): required at script layer when agent_qc.suggestions_required=true and issues were reported; optional for other layers. Each item includes problem + proposal; if text can be directly changed, also provide before/after; the response assigns each suggestion an id (s1…). Explain suggestions to the customer; the customer chooses accept some / execute all directly / proceed without changes (which route; autopilot = only execute priority=must suggestions that do not change the customer's original lines per execution mode: professional mode / unconfirmed plan / this step customer-controlled → explain to customer and only proceed after approval; do not decide for the customer. This step autopilot → do not ask customer; follow get_production_plan autopilot.default_decisions, recorded by the platform in get_autopilot_log). If content changes after the review, the report will be rejected; review again and QC against the new agent_qc.",
   "review_all": "(Recommended · free) Overall health check running three layers at once: script + storyboards + shot images. Use for initial assessment before work starts and recheck before delivery. ★It **does not issue review_token**—before paid steps, still run the corresponding review_script / review_storyboards / review_frames once each (the gate recognizes \"just reviewed against the current output\", not \"reviewed once sometime before\").",
   "autofill_storyboards": "(Recommended) AI one-click fills missing fields across all episode storyboards; by default it **only fills blanks and does not overwrite existing values** (only overwrites when overwrite=true). Improves storyboard completeness; do before image generation. Async in background, postpaid text step. ★When platform contract auto-fill is enabled, it also tries to add contracts to shots **without composition contracts** (whether enabled is indicated by the note in the import receipt contract_coverage; visible headcount / subject range / shot size are judged by it for both image generation and review; with default overwrite:false, existing contracts are untouched; **overwrite:true also rewrites existing contracts**)—if auto_complete was off during import and the contract_coverage note points to this tool, call it once before image generation. If this episode already has autofill running, this run **will not queue** (prevents duplicate-click duplicate charges); newly imported shots must wait until get_autofill_status is done before calling again.",
@@ -55,7 +55,7 @@
   "generate_shot_frame": "After confirmation, generate or regenerate the frame for **one shot** (async). This is the proper path to fix a shot image: the platform will carry this shot’s character identity anchors, scene/prop reference images, style anchor, and frame audit; regenerated images stay consistent with the whole film. Using external tools to generate then upload bypasses this entire chain, so character/clothing/style will inevitably drift. Regeneration overwrites the shot’s existing frame image (including prior uploads) and marks this shot’s video as needing regeneration. A last frame requires this shot’s first frame to be ready (otherwise use first_frame or both first). Completion criterion: poll get_storyboards and watch this shot’s first_frame_image/last_frame_image change.\n★Inherited reopen (reopen_pair_id): if get_storyboards returns this field on a shot, pass it through unchanged to reroll only the actually problematic side among first/last frames—the other previously generated candidate is preserved as-is, not regenerated and not charged again. When passing it, you no longer need frame_type (it will be ignored; the platform decides which side to regenerate); quote_id still must come from quote_shot_frame (frame_type may be first_frame or last_frame; single-frame price is the same). If the shot has no reopen_pair_id field (inheritance conditions not met), do not pass this parameter; use normal frame_type retry.\n★★If generating a last frame is blocked with “this shot is marked as state changed, but nowhere says what it looks like at the end”: the correct fix is to use update_shot to write the ending state into last_frame_prompt, then generate—**do not simply add allow_missing_terminal and force it**. For this type of shot, generating a last frame as-is historically succeeds only 9.4% of the time (40.2% when an end-state description exists), so forcing it will mostly waste one charge. Only pass that parameter when you confirm this shot is intended to look “almost unchanged”.\n★One-click final cut hosted flow: the same shot may regenerate frames at most 3 rounds (one call counts as one round; both also counts as one round). At the limit, returns **409 AUTOPILOT_SHOT_REGEN_LIMIT** (not dispatched, not charged, quote not consumed)—do not bypass with another tool. Stop and ask the customer: if the customer agrees to more regeneration, quote and generate normally with customer_approved_more_regens:true (grants another limit); if the customer accepts the current state, proceed downward, and the next paid call must include acknowledge_review:true to record confirmation. Professional mode and customer-controlled stages are not subject to this limit.\n★【Storyboard review hard gate · free】Before this step you must call review_storyboards: tell the customer every returned finding verbatim (each with code=issue type, shots=hit shot numbers, action=which tool to use for fixing), then pass review_token into this tool. If not reviewed, it will be rejected with 400. If content changes after review → token auto-invalidates; just re-review once (still free). error findings block by default; only when the customer is informed and insists on continuing as-is may you pass acknowledge_review:true—pushing ahead with known issues is likely to produce unusable footage and still charges normally (acknowledge_review only means the customer personally agreed; every execution mode requires explicit customer consent, hosted included). In hosted stages, only allowlisted heuristic errors may pass with auto_acknowledge:true (platform decides; if not allowlisted, returns 400 AUTOPILOT_MUST_ASK: must_ask_customer=true means pause and ask the customer, false = self-fix according to action and re-review). ★Grayscale dramas also require you (agent) to personally QC: inspect assets item by item per agent_qc returned by review_storyboards, answer the checklist line by line, and submit via submit_qc_report before this token can be used (not submitted → 400 agent_qc_required; problematic report → blocks by default just like error).\n★【Asset-layer hard gate · free】You must also run review_assets first (character sheet images / scene images / prop images), and pass its review_token as asset_review_token (coexists with the storyboard-layer review_token; both are required; grayscale dramas missing it get 400 naming review_assets). Generating frames does not invalidate the asset token. ⚠️ Batch quote confirmation flow: first call the corresponding quote_* tool to get estimated_points and quote_id, then call this tool with quote_id (quote confirmation depends on execution mode: professional mode / unconfirmed plan / customer-controlled stage → explain to the customer and proceed only after customer approval; hosted stage → do not ask the customer, follow get_production_plan autopilot.default_decisions, and the platform records it in get_autopilot_log). Hosted-stage quotes must stay within the hard budget cap; if blocked by 402 BUDGET_WOULD_EXCEED, stop and ask the customer. ★**Image-generation quotes (character sheet / scene image / frame generation) return two numbers**: estimated_points is the **upper bound** (estimated using that model’s maximum reference-image count, ensuring you do not start with an underbudgeted run that hits 402 midway); typical_points in the same response is the **typical cost**. Tell the customer both—only saying the upper bound makes it look much more expensive (the max-reference upper bound can exceed 2× the typical value), while only saying the typical value may leave insufficient balance. For fixed-price models they are equal, so one number is enough. Video-generation quote and charge use the same function; no such range exists.",
   "quote_videos": "Quote: how many credits to batch-generate videos for an episode (same function as actual charge, relatively accurate). Returns estimated_points, quote_id. Zero cost. ⚠️ Video is a large expense; clearly tell the user the credits and wait for confirmation.\n★**Only counts shots actually dispatched this time**: shots that already have video are skipped during whole-episode resume, not regenerated and not priced—shots_total = shots priced this time (not total shots in episode), shots_already_done = shots with video skipped this time. Exception: if any shot in a scene group lacks video, the **entire group is regenerated**, and already-generated shots inside the group are also priced. All shots already have video ⇒ 400(no dispatchable shots; use regenerate_shot_video to regenerate a shot). If any shot's video is cleared after quoting (becomes pending video), generate_videos returns 409 requiring a new quote; it will not charge for shots outside the quote.\n★**Specify video engine per shot**: pass shot_engines={storyboard id: engine} to switch engines only for those shots and only for this whole-episode generation (does not change drama-level video_engine; other shots unchanged). Quote prices per shot accordingly; quote_id pins the engines, and generate_videos dispatches exactly them—changing engine requires a new quote. Receipt shot_engines = actual applied mapping; shot_engines_ungrouped = scene groups **split into per-shot generation** because they include specified shots (scene-group duration and multi-keyframes are planned for the drama engine; generating the whole group with a changed engine would lose shots/keyframes; after splitting, other shots in the group still generate per-shot with the drama engine, losing group-level one-pass continuity, so do not split a good group for one shot—check get_scene_group_plan first). Selected engine must support this drama's resolution (seedance-2.5 only 480p/720p; hailuo-3 only 720p/1080p; wan3.0/wan3.0-prime 480p~1080p), and shot duration must not exceed that engine's single-shot limit (seedance-2.5/wan3.0 30s, hailuo-3 15s), otherwise 400 (vendors truncate overlong shots; either switch engine or split_shot). Shots with specified engines must be generated this time: whole-episode generation will not regenerate shots already having video, so specifying an engine for one ⇒ 400; a split per-shot scene group only counts group members without video. If you only want to regenerate a few shots that already have video, using quote_regenerate_shot_video with model is cheaper.",
   "generate_videos": "After confirmation, batch-generate videos: one backend chain runs the full episode; if balance is insufficient it auto-aborts the whole chain (prevents duplicate charging). Requires first frames already generated for this episode (otherwise rejected). Poll get_storyboards; completion = video_url filled shot by shot.\n★【Hard gate: shot image review · free】Before this step you must call review_frames first: report the returned findings to the customer verbatim, item by item (each with code=issue type, shots=hit shot numbers, action=which tool to use to fix), then pass review_token into this tool. No review → 400 rejection. If content changes after review → token auto-invalidates; review once again (still free). If there is error, block by default; only if the customer is informed and insists on continuing as-is, pass acknowledge_review:true—pushing ahead with issues will very likely produce unusable footage and still charges normally (acknowledge_review only means the customer personally agreed; every execution mode requires explicit customer consent, including autopilot). In autopilot steps, only whitelisted heuristic errors may be released with auto_acknowledge:true (platform decides; if not whitelisted, returns 400 AUTOPILOT_MUST_ASK: must_ask_customer=true means pause and ask customer, false = self-fix per action then re-review). ★ Gray-release dramas also require you (agent) to personally QC: per review_frames returned agent_qc, inspect assets item by item, answer every checklist item, and submit via submit_qc_report before this token can be used (not submitted → 400 agent_qc_required; report has problems → blocked by default same as error). ⚠️ Batch quote confirmation flow: first call the corresponding quote_* tool to get estimated_points and quote_id, then call this tool with quote_id (quote confirmation follows execution mode: professional mode / unconfirmed plan / this step controlled by customer → explain to customer and proceed only after customer agrees; do not decide for customer; this step autopilot → do not ask customer, execute per get_production_plan autopilot.default_decisions, platform records it in get_autopilot_log). Autopilot-step quotes must stay within the hard budget cap; if blocked by 402 BUDGET_WOULD_EXCEED, stop and ask customer. ★ **Image-generation quotes (character sheet / scene image / frame generation) give two numbers**: estimated_points is the **upper bound** (estimated using that model's max reference-image count, ensuring you do not start with too-low budget and hit 402 mid-run); typical_points in the same response is the **usual cost**. Tell the customer both—only stating the upper bound makes it look much more expensive (with max reference images, the upper bound can exceed 2x the typical value); only stating the typical value may leave balance insufficient. For fixed-price models the two are equal; then one number is enough. Video-generation quote and charge use the same function; no range exists.\n★【Post-completion QC · free】After generation, wait for it to persist (check video_status in get_storyboards / get_pipeline_status), then call review_videos to review video and dubbing layers (missing video / video made from old frames / hard cut at ending / unexpected human voice / missing dubbing / voice timbre unassigned / original voice line expired); fix and re-review; then personally inspect each shot and listen to dubbing per agent_qc (action correct, face stable, lines complete, voice right), submit via submit_qc_report; compose_episode must carry its review_token.",
-  "compose_episode": "Stitch all shot videos of one episode into one final cut (final stitching). **Free** (pure stitching, no quote confirmation required), async in backend. Before starting, a final-stitch precheck runs: shots missing video or video tasks still generating will hard-block with 400 and list the problem shots (blockers); fix them and retry. If you really want a partial final cut, pass force=true (shots missing video are skipped, final cut lacks shots, logged). advisories in the response (duration drift/orphan tasks/missing TTS) are warnings only, not blockers; handle them one by one before stitching. After starting, poll with get_final_cut.\n★【Video and dubbing review hard gate · Free】Before this step you must call review_videos: relay the returned findings to the customer verbatim one by one (each with code=issue type, shots=hit shot numbers, action=which tool to use to fix), then pass the review_token into this tool. If not reviewed, 400 rejection. If content changed after review → token auto-invalidates; just review again (still free). error blocks by default; only if the customer is informed and insists on proceeding as-is may you pass acknowledge_review:true — proceeding with known issues will likely produce unusable video and still charge credits as usual (acknowledge_review only means the customer personally agreed; every execution mode requires explicit customer consent, autopilot included). In autopilot, only whitelisted heuristic errors may pass with auto_acknowledge:true (platform decides; if not whitelisted, returns 400 AUTOPILOT_MUST_ASK: must_ask_customer=true means pause to ask customer, false = self-fix per action and re-review). ★ For gray rollout dramas, you (agent) must personally QC: inspect materials item by item per agent_qc from review_videos, answer every checklist item, and submit via submit_qc_report before this token can be used (not submitted → 400 agent_qc_required; report has issues → blocked by default like error).\n★【Post-completion QC · Free】After the final cut is ready, run review_final_cut (missing shots/subtitles not fitting/identity anchors/axis jumps/typos; proofread=false means no credits charged), tell the customer the conclusion; call confirm_delivery_acceptance only after customer confirmation (delivery acceptance requires explicit customer consent in every execution mode, autopilot included). force only bypasses the final-stitch precheck, not the review gate.",
+  "compose_episode": "Stitch all shot videos of one episode into one final cut (final stitching). **Free** (pure stitching, no quote confirmation required), async in backend. Before starting, a final-stitch precheck runs: shots missing video or video tasks still generating will hard-block with 400 and list the problem shots (blockers); fix them and retry. If you really want a partial final cut, pass force=true (shots missing video are skipped, final cut lacks shots, logged). advisories in the response (duration drift/orphan tasks/missing TTS/post_production_pending unfinished post-production effects) are warnings only, not blockers; handle them one by one before stitching. After starting, poll with get_final_cut.\n★【Video and dubbing review hard gate · Free】Before this step you must call review_videos: relay the returned findings to the customer verbatim one by one (each with code=issue type, shots=hit shot numbers, action=which tool to use to fix), then pass the review_token into this tool. If not reviewed, 400 rejection. If content changed after review → token auto-invalidates; just review again (still free). error blocks by default; only if the customer is informed and insists on proceeding as-is may you pass acknowledge_review:true — proceeding with known issues will likely produce unusable video and still charge credits as usual (acknowledge_review only means the customer personally agreed; every execution mode requires explicit customer consent, autopilot included). In autopilot, only whitelisted heuristic errors may pass with auto_acknowledge:true (platform decides; if not whitelisted, returns 400 AUTOPILOT_MUST_ASK: must_ask_customer=true means pause to ask customer, false = self-fix per action and re-review). ★ For gray rollout dramas, you (agent) must personally QC: inspect materials item by item per agent_qc from review_videos, answer every checklist item, and submit via submit_qc_report before this token can be used (not submitted → 400 agent_qc_required; report has issues → blocked by default like error).\n★【Post-completion QC · Free】After the final cut is ready, run review_final_cut (missing shots/subtitles not fitting/identity anchors/axis jumps/typos; proofread=false means no credits charged), tell the customer the conclusion; call confirm_delivery_acceptance only after customer confirmation (delivery acceptance requires explicit customer consent in every execution mode, autopilot included). force only bypasses the final-stitch precheck, not the review gate.",
   "get_final_cut": "Check an episode final cut status and download link. When status=completed, returns download_url(our COS direct link, downloadable directly). Free. ★bgm_stale=true means BGM was generated/modified after the final cut and is not yet in the final cut: just compose_episode again (free), do not re-render. ★If a current delivery version has been set (external version registered by register_external_delivery, or platform version specified by set_current_delivery), also returns delivery—that is the version the customer actually received; download_url remains the platform's latest stitched final cut. To see what every final-cut version used and its hash, use list_deliveries.",
   "get_export": "Check an episode export/master status (downloadable master after final assembly). Free.",
   "review_final_cut": "**Final cut checkup**: Before export, run through the whole episode—shots with no generated frame, subtitles that do not fit on one screen, characters without identity anchors, shot continuity (axis jump), plus one typo proofread pass.\n★**Advisory, non-blocking**: can_export=false only means there are block-level issues worth checking first; the platform will not stop you from running compose_episode / get_export. Explain findings to the client one by one (code=issue type, shots=hit shot numbers, action=which tool to use to fix), and **let the client decide whether to fix or publish as-is**.\n★Cost: the check itself is free, but by default it runs one LLM typo proofread pass—**that step costs credits**. If proofreading is not needed, pass proofread=false (faster and no credits charged).\n★For subtitles and typo items, view the **original text** in the official website checkup panel; here only conclusions and shot numbers are returned.",
@@ -237,5 +237,7 @@
   "set_voice_anchor_from_shot": "Select a character’s voice line (voice baseline) from a shot in this episode. Free. No external audio source is required from the client—use the voice this character has already spoken in the video.\n★★【In native-audio dramas (use_clip_audio=true, default), this is “voice locking”】After selection, later video generation will pass this audio to the video vendor as reference audio, so the same character’s voice across shots follows it; without locking, the vendor samples each shot independently and the voice may drift across shots.\n★Which shot to choose: a shot where the character **speaks alone, has a longer line, and has no background music or interruptions by others**; start_s/dur_s can clip only part of it (if omitted, the default window is used, and duration is automatically clamped to each engine’s limit).\n★Only affects videos generated **afterward**. Shots already generated before locking will appear in get_pipeline_status under native_voice_anchor.stale_shots; regenerate them with regenerate_shot_video to unify the voice. The cheapest workflow is: generate one shot for each speaking character first, select the voice line, then batch-generate the remaining shots.\n★Works even if the dialogue field is empty: actual audio is authoritative—the platform uses calibrated voice activity detection to confirm there is speech in the selected interval, and uses the transcription text as anchor text; if no speech is detected or no usable text can be transcribed, it rejects (a wrong anchor would pollute all later shots’ voices, so reject rather than guess). The response field text_source indicates whether text came from dialogue or transcription.\n★Preview first with preview:true: only clips and returns preview_url plus anchor text, **without writing to the character**; if it sounds right, remove preview and formally submit with the same start_s/dur_s.\n★Noise removal and acceptance check (effective when enabled by the platform for the episode; response contains hygiene): automatically removes pure environmental-noise pauses between two lines and measures sample noise floor (noise_floor_before/after, threshold threshold). In preview, preview_url is the **cleaned** sample and raw_preview_url is the original—**ask the client to compare both before/after by listening**. verdict=fail means obvious environmental noise or music is under the voice (removing pauses cannot fix it; cloning and the video vendor will learn it as part of the timbre), and formal submission will be rejected: choose a cleaner shot, or adjust start_s/dur_s to avoid background sound; only pass allow_issues:true to write it if the client has listened and explicitly insists.\n★If the client has an authorized external audio source, use clone_voice + set_character_voice instead; choose one of the two, and the later setting overrides the earlier one.",
   "export_handoff_pack": "After delivery traceability is enabled, an immutable export manifest is saved (assets are not modified). Keep pack_id and manifest_sha256, and reference them when returning an external final cut. Export the “asset handoff package” manifest for this episode: downloadable URLs for each-shot raw clips + dialogue tracks + sound effects + music + subtitles, for you to complete transition decisions, stitching, mixing, and subtitle burn-in **on your own side**—the platform does not participate in final assembly. Free, zero credits.\n★Local color grading / third-party AI post: purpose=local_color; when there are only images, pass media_type=images, no need to generate video. This mode preserves source files, disables the export package’s automatic LUT, and includes post-production notes and a local comparison-page flow; it does not upload to third parties, charge for generation, or backfill the platform. Image sources may already have been processed, so not all exported images can be promised as ungraded originals.\n\n【Recommended workflow】① Call this tool to get manifest; ② Download raw clips locally via clips[].url; ③ Watch the clips yourself and decide which transition to use at each seam (manifest provides scene_boundary as a scene-boundary criterion), write a plan.json; ④ Use get_handoff_toolchain to get compile_timeline.py to expand the timeline and assemble.sh to assemble the final cut. The toolchain already calculates how subtitles/dialogue/SFX shift after overlapping transitions are added.\n\n【Three facts that will break things if ignored】\n① **Where the voice is must be read per shot from `shots[].voice_track.location`, not from the episode-level audio_contract.mode**—the latter is an episode-level declaration, while in all-offscreen-narration shots the narration is mixed into the raw clip on the platform completion side, so it can differ per shot within the same episode. The four values require different handling: `separate_file`=dialogue is in dialogue_audio; if you do not lay it in, this shot has no lines; `baked_in_clip`=already in the raw clip audio track; overlaying it again causes double voice; `missing`=**platform side confirmed missing** (narration compensation failed); subtitles still exist but the sound is nowhere—regenerate this shot on the platform; extending a transition cannot hide it; `unknown`=there are lines but the source cannot be found, **you must listen to the raw clip** before deciding. ★Subtitles never imply there is sound: subtitles are per sentence, audio is per shot. For shots with `conflicts_with_contract=true`, trust measurement; notes already name them by shot number.\n② Each shot must be trimmed using trim_head_ms / duration_ms before use; directly stitching the full raw clip will include head/tail deformed frames that the platform already QC’d out.\n③ Subtitle cues, dialogue_audio.offset_ms, and sfx[].offset_ms are all based on “millisecond 0 after this shot’s trim”, not absolute final-cut time. No matter how many overlapping transitions you add, do not modify them—let compile_timeline.py expand them; do not manually accumulate times.\n\nIf you want the platform to assemble it, or need platform-level quality gates (final assembly precheck / equal audio-video duration / loudness mastering), use compose_episode.",
   "get_handoff_toolchain": "Get the source code for the asset handoff package assembly toolchain (compile_timeline.py timeline compiler / assemble.sh ffmpeg assembly script). Free. This tool only returns source text and **will not** write files on your machine—save it to your working directory yourself before running.\ncompile_timeline.py expands “shot-relative” subtitle/dialogue/SFX anchors into absolute timecodes on your own timeline and handles global offsets caused by overlapping transitions; assemble.sh is a complete ffmpeg assembly baseline from raw clips to final cut (trim → normalize → concat/xfade → music sidechain → subtitles → two-pass master). Dependencies: ffmpeg (with libass for subtitle burn-in), ffprobe, jq, python3.",
-  "save_handoff_toolchain": "Write the assembly toolchain (fetch_pack.py / compile_timeline.py / assemble.sh) directly to a local directory, avoiding manual copy/paste. Free. The directory must **already exist** and be an absolute path; filenames are fixed and cannot be customized.\nRefuses to write into hidden directories (~/.ssh, ~/.config, .git…) and system directories—this is disk writing, not reading, and overwriting the wrong place is irreversible.\nFull workflow after writing to disk:\n  python3 fetch_pack.py manifest.json -o ./pack   # Download assets and materialize inline subtitles as SRT\n  python3 compile_timeline.py ./pack [--transitions plan.json]\n  ./assemble.sh ./pack out.mp4 [plan.json]"
+  "save_handoff_toolchain": "Write the assembly toolchain (fetch_pack.py / compile_timeline.py / assemble.sh) directly to a local directory, avoiding manual copy/paste. Free. The directory must **already exist** and be an absolute path; filenames are fixed and cannot be customized.\nRefuses to write into hidden directories (~/.ssh, ~/.config, .git…) and system directories—this is disk writing, not reading, and overwriting the wrong place is irreversible.\nFull workflow after writing to disk:\n  python3 fetch_pack.py manifest.json -o ./pack   # Download assets and materialize inline subtitles as SRT\n  python3 compile_timeline.py ./pack [--transitions plan.json]\n  ./assemble.sh ./pack out.mp4 [plan.json]",
+  "get_post_production_checklist": "Read this episode's **post-production effects checklist** (free). Items marked in the script as [VFX: …] or written in shot prompts as \"post-production / composited later\" are **not composited by the platform**—image and video generation leave them out and the final cut does not add them, so the finished episode lacks these story elements unless handled. Per item: shot_number, time start_s~end_s, content, source (vfx_tag shot annotation / prompt / script_unassigned = in the rewritten script but not attached to any shot), narrative_required (story-critical; cosmetic items such as color grading are false), status (pending / done_external / waived). ★Review before composing; tell the client about narrative_required pending items and ask: do it in external post (then mark_post_production_item done_external), change the shot so the platform draws it (update_shot then regenerate that shot), or drop it (waived). review_videos / compose_episode give an advisory for unhandled items.",
+  "mark_post_production_item": "Mark one item of the post-production checklist (free): status=done_external (client finished it outside the platform) / waived (client decided not to do it) / pending (undo). key comes from get_post_production_checklist; it changes after the shot or prompt is edited—on 400, re-read the checklist. (Marking post-production items requires explicit client consent in every execution mode, including autopilot.) Marking is bookkeeping only and does not change the final cut; if the client wants the externally finished version delivered, use register_external_delivery."
 }