[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6BY3JVDFQC0DT5C6TDD0YJ7":3,"skill-same:01M6BY3JVDFQC0DT5C6TDD0YJ7":76},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":42,"linkOnly":43,"markdownContent":44,"markdownBody":45,"frontMatter":46,"refName":48,"commitSha":49,"skillDirectory":50,"forksCount":51,"repositoryHtmlUrl":52,"repositoryHomepageUrl":53,"ownerHtmlUrl":54,"ownerBlogUrl":12,"ownerDescription":55,"updatedAt":56,"install":57,"resources":69},"01M6BY3JVDFQC0DT5C6TDD0YJ7","storyboard-core",null,"Use NodeTool storyboard, entity-casting, rendering, and timeline-assembly tools for video production or debugging their contracts.","nodetool-ai\u002Fnodetool","nodetool-ai","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F164873569?v=4","01M6BXPFDW36K9K1MR8ZH63HG2","nodetool.ai","01M6BXPFJ893XM219GQN60B0WK",635,"AGPL-3.0","https:\u002F\u002Fgithub.com\u002Fnodetool-ai\u002Fnodetool\u002Fblob\u002Fmain\u002Fpackages\u002Fsystem-skills\u002Fstoryboard-core\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000016","图像与多媒体","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41],"core","storyboard core","storyboard","for","debugging","entity","true","rendering","casting","contracts","assembly","video production","use","nodetool","Video","timeline","Tools","Production","2026-11-10 10:12:30",false,"---\nname: storyboard-core\ndescription: \"Use NodeTool storyboard, entity-casting, rendering, and timeline-assembly tools for video production or debugging their contracts.\"\nfeatured: true\n---\n\nThe shared half of every NodeTool video job. The use-case skills carry the style,\nthe shot pattern and the briefs; this carries the machinery they all assume.\n\nDirect video on the **storyboard** surface, then finish in the **timeline**. Use a node graph when the user requests one or needs a reusable template, as\ndescribed in `video-workflow`.\n\nRead the relevant part of **Tool contract** below before the first call in\nthat tool family. Use the live tool schema when it differs\nfrom an example. Load other sections only when the task reaches them.\n\n## Pick the use-case skill\n\n| Job | Skill |\n|---|---|\n| Phone-shot video with a person: UGC ad, testimonial, comedy, day-in-the-life, vlog | `\u002Fugc-video` |\n| Product film: pack shot, hero, brand spot, with or without talent | `\u002Fproduct-commercial` |\n| Sound-off motion-graphics ad from real screenshots and product photos, no generated footage | `\u002Fmotion-ad` |\n| Rebuild an existing ad or clip you were given | `\u002Fvideo-clone` |\n| Voiceover drives the picture: explainer, faceless video, narrated piece | `\u002Fscript-video` |\n| Narrative with dialogue, score and a title: short film, trailer, scene | `\u002Fshort-film` |\n| A campaign, not one video: entity sheets, still set, several cuts | `\u002Flaunch-kit` |\n| A template to re-run on new inputs | `\u002Fvideo-workflow` |\n| Footage already exists and needs repair: cutout, upscale, outpaint, lip sync, generated sound | `\u002Fnodetool-video-post` |\n| A screen someone clicks, over the workflows behind a piece | `\u002Fnodetool-app-builder` |\n\nIf none fits, run the loop below directly.\n\nThose skills say what the picture looks like. A second set says where the beats\ngo, and the two compose: load the job skill for the look and the structure\nskill for the spine.\n\n| The structure question | Skill |\n|---|---|\n| Ad beats: hook, escalation, timecodes, VO discipline | `\u002Fcommercial-beat-sheet` |\n| A product page URL in, a finished cut and its cost out | `\u002Flaunch-commercial` |\n| A 30–120s explanation with a claim per beat | `\u002Fexplainer-storyboard` |\n| A treatment cut to a track's sections | `\u002Fmusic-video-treatment` |\n| Eight audio-first beats, the drop at ~65%, a title card | `\u002Ftrailer-template` |\n\nThese own their own briefs and beat budgets. The storyboard, entity and render\ncall shapes live once, in **Tool contract** below. Every job and structure skill\npoints here for them.\n\n## Two tool families, one board\n\n| | Headless | Browser |\n|---|---|---|\n| Names | `create_storyboard`, `get_storyboard`, `edit_storyboard`, `direct_storyboard`, `render_storyboard_stills`, `render_storyboard_clips`, `revise_storyboard_clip`, `assemble_storyboard_timeline`, and the rest of **Tool contract** | `ui_storyboard_*`: a browser twin for most headless ops, plus `set_screenplay` (table in **Tool contract**) |\n| Needs | nothing open | the board open as a tab, listed in the `ui_context` system block |\n| Shot target | id, 0-based index, or **slug** | id, 0-based index, or `\"selected\"` — **no slug** |\n| Permission gate | yes | no (client tools bypass it) |\n\nEvery board tool in both families names its board explicitly (`storyboard_id`, or\n`storyboardId` on the still-motion-graphics tools). There is no \"act on whatever is\nopen\" fallback.\n\nPrefer headless. Reach for `ui_storyboard_*` when the user is watching the board fill\nin, or when you need `set_screenplay` for `title`, `logline` or `style_bible`.\nHeadless `edit_storyboard` → `set_board` writes screenplay-level `narration`,\n`music_prompt` and `motion_design` while preserving the other screenplay fields.\nBridge the two with `ui_open_document {type: \"storyboard\", id}`.\n\n`ui_storyboard_generate_keyframe`, `ui_storyboard_generate_clip` and\n`ui_storyboard_revise_shot` spend exactly what the headless renders spend, and no\npermission prompt stands in front of them. Call them only inside a render the\nuser has already authorized.\n\n## The loop\n\n1. **Find the board.** `list_storyboards`, or read `ui_context`. No board yet →\n   `create_storyboard {name, brief, style, aspect_ratio}`.\n2. **Cast the entities.** `list_entities` first. A new one needs an image asset —\n   `generate_image` or the user's upload — then\n   `create_entity {asset_id, kind, name, descriptor}`. **There is no create-from-text.**\n3. **Attach the cast to the board:** `edit_storyboard` → `{op: \"set_board\", entity_ids: [...]}`,\n   or `ui_storyboard_set_entities {storyboard_id, entity_ids}` on an open board.\n   Name matching only searches the board cast, so an entity cast nowhere seasons\n   nothing, no matter what the shots say. An id in a shot's own `entity_ids` is\n   added to the board cast when the board is read.\n4. **Pin the models.** `find_model` with `capability` `text_to_image`, then\n   `image_to_video` or `text_to_video`; write both through\n   `{op: \"set_board\", image_model, video_model}`. There is no default — an unset\n   model fails the render rather than spending on a model nobody chose.\n5. **Direct.** One `{op: \"add_shot\", ...}` per shot. Report the shot count and\n   selected models. Continue to the stages authorized by the request. A board-only\n   request ends here. Honor any checkpoint the user requested.\n6. **Stills.** `render_storyboard_stills {storyboard_id}` — omit `targets` for every\n   shot that still needs one. Cap 24 shots per call.\n7. **Take selection, when requested.** Every render keeps the old still in\n   `keyframe_versions` and the old clip in `clip_versions`, and makes the new one\n   selected. `edit_storyboard` → `{op: \"select_version\", target, kind: \"keyframe\"|\"clip\",\n   version}` selects another (0-based, oldest first). Pause if the user reserved\n   the pick for themselves in the takes gallery.\n8. **Clips.** `render_storyboard_clips {storyboard_id}` within the requested\n   generation scope and budget. Reuse prior authorization instead of asking again.\n9. **Revise one shot:** `revise_storyboard_clip {target, instruction}`. Needs an\n   existing clip; it is video-to-video and touches no other shot.\n10. **Cut.** `assemble_storyboard_timeline`, then `validate_timeline`. Re-running\n    rebuilds the same sequence in place and keeps tracks the board does not own.\n11. **Finish** with `edit_timeline` ops (**Tool contract** § Timeline, below).\n    Load `timeline-edit-ops` with `load_skill` for the full op list, the presets\n    and the preview contract, and `motion-graphics` for the build loop. A repair\n    on a delivered clip belongs to `nodetool-video-post`.\n\n**Stills-only mode.** When the user wants a board and frames but no motion — a spec\nad, a pitch, a look test — run steps 1 to 7 and stop. Adding the motion later is\n`update_shot` on `motion` alone: action, wardrobe, set and cast stay put, so the\napproved stills still describe the finished piece.\n\n## What actually reaches the model\n\nThe prompt is assembled from named fields, comma-joined, not from the whole shot:\n\n| Field | Still | Clip, `keyframe` mode | Clip, `direct` or `reference` mode |\n|---|---|---|---|\n| `action` | yes | yes | yes |\n| `camera.framing` | `\"\u003Cframing> shot\"` | — | `\"\u003Cframing> shot\"` |\n| `camera.angle` | yes | — | yes |\n| `camera.lens` | `\"\u003Clens> lens\"` | — | `\"\u003Clens> lens\"` |\n| the shot's scene `lighting` | yes | — | yes |\n| `motion` | — | yes (first) | yes |\n| `camera.movement`, `camera.equipment` | — | yes | yes |\n| board `style` | yes | — | yes |\n\nA keyframe-mode clip animates a still that already carries framing, lens,\nlighting and style, so the clip prompt leaves them out. Write camera direction\ninto the `camera` object, not into `action` as well. `dialogue`, `notes`,\n`duration_seconds`, `end_state`, `sound` and `graphics` never enter a per-shot\nprompt (`end_state` and `sound` feed the one-take prompt only).\n\n**Entities season by plain name.** A shot with `entity_ids` uses exactly those.\nOtherwise: every style and location entity applies to every shot, and a character or\nprop applies when its **name appears** in the shot's `action`, `motion`, `dialogue`,\n`narration` or `slug`. Write `Nova reaches for the bottle`, not `@Nova reaches...`.\n`@` is a chat-composer affordance that emits an `entity:\u002F\u002F\u003Cid>` token into *your\nmessage*; it never becomes shot text.\n\n## Locks\n\n- Keep one `descriptor` per entity and let it do the work. Do not re-describe a face\n  in shot text.\n- A state change (wet hair, a stained shirt, a second outfit) is a **second entity**,\n  not an instruction inside one prompt.\n- Product geometry, label and colour come from the product entity's descriptor and\n  reference image. Never invent a logo.\n- Give every shot a stable `slug` (`1a`, `2a`, …) at `add_shot` time. Headless targets\n  accept it, and \"fix 3a\" then means one shot.\n- Render mode is per shot. `keyframe` (default) is cheaper to iterate and holds a look\n  steady. `direct` skips the still — worth it for heavy motion, where first-frame\n  conditioning stiffens the result, and for native-audio video models, which are\n  weakest on their image path.\n- A native-audio model writes the sound per clip, so a board of one clip per shot\n  cuts the audio at every join. Before rendering, load the `video-audio-continuity`\n  system skill through `load_skill`: either the whole piece is one shot\n  carrying the cuts, or the\n  continuity comes from a narration or music track and the shot audio is muted.\n  A silent cut is also valid when sound is not requested. Reuse existing audio\n  or keep the cut silent when extra generation would exceed the authorized scope.\n\n## Where the models will not do what the cut wants\n\nFour constraints that are not bugs and have no tool to fix them. Each has a working\nshape.\n\n**A video model returns the lengths it offers.** The render sends\n`duration_seconds`, and the model snaps it to its own steps — a shot directed at\n1.5s comes back at 5.184s on a model whose shortest clip is that long. For a run of\nbeats shorter than the model's shortest clip, render one generation with bracketed\ntimecodes in the prompt and record the split with `covered_by`. **Tool contract**\n§ Fusing shots, below, has the call and the rule for when to fuse and when to\nrender each beat long and trim.\n\n**Moderation reads the words, not the story.** A prompt naming institutional force —\npolice grabbing someone, a raid, restraint — trips a safety filter that a shot of the\nsame threat does not. Reframe with non-trigger vocabulary and keep the stakes:\n\"two uniformed city officials approaching with a clipboard and caution tape\" passes\nwhere \"two aggressive police officers grabbing her arms\" does not. Reframe once; do\nnot retry the rejected prompt.\n\n**A music model cannot leave a hole.** Ask for 1.5s of silence at 00:19.5 and the\ndecoder fills it with reverb tail and room tone — there is no envelope gate in the\nprompt. Cut the silence on the timeline instead: generate the score in two parts,\nlay them as two clips with the gap between them, and fade the first out (~300ms) and\nthe second in (~100ms) so the edges are not clicks.\n\n**Speech does not fit a 1.5s shot.** An expressive take of a line runs 4s, and\ncompressing it to the picture beat makes it sound processed. Let the words cross the\ncut: keep the voiceover clip on its own track and start it under the previous shot\n(J-cut) or run it past the cut into the next (L-cut). The picture cuts on the beat;\nthe line finishes where it finishes. On a script-linked board that is automatic —\neach shot runs as long as the lines it covers — so use this on an unlinked board or\nwhere the picture has to stay on the beat.\n\n## Gating and spend\n\nPermission mode decides what runs without asking. `read` tools always run.\n\n| Mode | write \u002F execute \u002F external |\n|---|---|\n| `auto` | runs |\n| `default` | asks the user |\n| `plan` | **blocked** |\n\n`plan` blocks `create_storyboard` and `edit_storyboard` too, so the board cannot be\nwritten in it. Respect the active permission mode and tool approval responses. For a board-only\nrequest, write the board and omit render calls. Do not switch modes or use browser\ntools to evade a denied headless action. A tool being callable does not authorize\nspend beyond the user's request.\n\n**You cannot price a render.** No tool estimates it, and `Shot.cost_estimate` is not\npopulated. Report the shot count, the clip count and the models without inventing a\ndollar estimate, and confirm that scope with the user before fanning out a clip\npass the request did not already size. If a user\nbudget cannot be checked before spending, resolve that constraint first. Report\nactual spend afterwards with `get_cost_summary`. If authorization is missing,\nprepare the board and explain the specific render action that needs approval.\n\n## Memory\n\n`memory_save` is durable across every conversation — use it for the style bible, the\ncast and the grade, with the entity and board ids in `resources`. `share_result` \u002F\n`read_shared` are **run-scoped and discarded**; they are for passing values inside one\nturn, not for locking a look across sessions.\n\n## Follow-ups this loop already handles\n\n```\nFix 3a only. Leave the rest.\nDrop the contre-jour across the whole board — soft even daylight. Update the\n  board style, do not rewrite the shots.\nNew still on 2a. Keep the old take.\nrevise_storyboard_clip 5a: darker, add rain, same blocking.\nAdd a reaction shot after 3a and re-slug from there. Do not re-render 1a-3a.\nCollapse 8, 9 and 10 into one 8s shot, keeping the lean-in as the last second.\nThe face drifted on 4a. Select still take 2, then regenerate the clip.\nThe label is unreadable on 2a. New macro still, then a clip from it.\nCut it. Assemble, validate, narration on its own track, mute Shot Audio on 1-6.\n```\n\n## What is below\n\n- **Tool contract** — every tool, its arguments, and the fields it refuses.\n- **Standing orders** — an optional brief for users who explicitly want\n  approval between stages. Its sample checkpoints do not add requirements to\n  a different request.\n\n## Tool contract\n\nThe one copy of the storyboard contract; the job and structure skills point\nhere. Exact arguments. Every field named here is checked in the implementation;\nan unrecognized field is **refused with an error**, not dropped.\n\n### Storyboard — headless\n\nWork with no editor open. Shot `target` = shot id, 0-based index as a string, or slug.\n\n| Tool | Arguments |\n|---|---|\n| `list_storyboards` | `limit?` → id, name, shots, with_keyframe, with_clip, timeline_id, updated_at |\n| `create_storyboard` | `name` (required), `brief?`, `style?`, `aspect_ratio?` (default `16:9`), `project_id?`, `id?` → `{ok, storyboard_id, id, name, project_id, shots, updated_at, revision}`; `storyboard_id` and `id` hold the same value |\n| `get_storyboard` | `storyboard_id` → brief, style, aspect ratio, narration, music_prompt, motion_design, image_model, video_model, script link, revision, and every shot with id\u002Findex\u002Fslug\u002Faction\u002Fcamera\u002Fmotion\u002Fduration\u002Fstatus\u002Fhas_keyframe\u002Fhas_clip\u002Fcovered_by |\n| `edit_storyboard` | `storyboard_id`, `ops[]` — see below, `expected_revision?` (refused if the board changed since that revision) |\n| `direct_storyboard` | `storyboard_id`, `redirect?`, `shot_count?` (default 6), `provider?`, `model?` — the Director writes scenes and shots from the board's brief, genre and style; set the brief with `set_setup` first. Renders nothing |\n| `render_storyboard_stills` | `storyboard_id`, `targets?`, `provider?`, `model?`, `style?`, `stale_only?`, `concurrency?` |\n| `render_storyboard_clips` | `storyboard_id`, `targets?`, `provider?`, `model?`, `resolution?`, `mode?` (`keyframe`\\|`direct`\\|`reference`), `stale_only?`, `concurrency?` |\n| `revise_storyboard_clip` | `storyboard_id`, `target`, `instruction`, `provider?`, `model?` |\n| `assemble_storyboard_timeline` | `storyboard_id`, `name?`, `fps?` (default 30) |\n| `derive_shot_from_clip` | `timeline_id`, `clip_id`, `frame_count?` (1-8, default 3), `action?` — a new reference-mode shot after the source shot, conditioned on frames of that clip. Renders nothing |\n| `extract_script_from_storyboard` | `storyboard_id`, `name?`, `relink?` |\n| `delete_storyboard` | `storyboard_id` |\n| `get_storyboard_one_take` | `storyboard_id` → `prompt` (the creator's), `compiled` (REFS, STEPS, AUDIO from the board), `full_prompt`, references with `[Image N]` (the shot stills, in shot order), shot windows, duration, `settings` (stored `duration_seconds`, `aspect_ratio`, `resolution`, `model`), `effective` (after board fallbacks), warnings |\n| `update_storyboard_one_take` | `storyboard_id`, `prompt?`, `duration_seconds?`, `aspect_ratio?`, `resolution?`, `model?` `{provider, id, name?}` (null clears one), `shots?` `[{shot_id, end_state?, sound?}]`, `expected_revision?` |\n\nRender limits: **24 shots per call**, `concurrency` default 3, max 8.\n\nOmitting `targets` selects every shot that still needs that step. For stills that is\nevery shot with no keyframe that is not set to render directly; for clips, every shot\nwith no picture — its own or one it is covered by (§ Fusing shots). A `keyframe`-mode\nshot that reaches `render_storyboard_clips` with no\nstill is reported in the results, not rendered — render its still first, or set its\n`render_mode` to `direct`. Each render appends to `keyframe_versions` \u002F\n`clip_versions` and makes the new one selected.\n\n#### `edit_storyboard` ops\n\nFifteen ops, applied in order, at most 60 per call:\n\n| Op | Arguments |\n|---|---|\n| `add_shot` | shot fields below; `action` required; `index?` or `after_shot_id?` (inserts after that shot, in its scene) |\n| `update_shot` | `target` + any shot fields |\n| `remove_shot` | `target` |\n| `reorder_shot` | `target`, `index` (board position) |\n| `move_shot` | `target`, `scene_id?`, `position` (0-based inside the target scene) — how a shot changes scene |\n| `duplicate_shot` | `target` — the copy lands right after it, without script links or coverage |\n| `set_board` | board fields below |\n| `set_setup` | `brief?`, `genre?`, `stage?` (the guided-setup answers `direct_storyboard` reads) |\n| `update_scene` | `scene_id`, `slugline?`, `lighting?` |\n| `create_scene` | `after_scene_id?`, `slugline?` — opens holding one blank shot |\n| `merge_scene` | `scene_id` — folds it into the scene before it |\n| `set_style` | `entity_id` (a style entity becomes the board preset and its descriptor the board style) or `style` (the descriptor alone) |\n| `select_version` | `target`, `kind` (`keyframe`\\|`clip`), `version` (0-based, oldest first) — nothing re-renders |\n| `delete_version` | `target`, `kind`, `version` — the asset stays in the library |\n| `add_keyframe_version` | `target`, `asset_id`, `flip_of?` — attaches a stored image as a new still and selects it |\n\n`set_entities` is accepted as an alias of `set_board`, and a few other near-miss\nnames resolve the same way; an unknown op is refused.\n\nShot fields (add and update both): `action`, `slug`, `camera`, `motion`, `end_state`,\n`sound`, `graphics`, `production`, `dialogue`, `narration`, `notes`, `duration_seconds`,\n`duration_source` (`audio`\\|`manual`), `render_mode` (`keyframe`\\|`direct`\\|`reference`),\n`entity_ids`, `location_id`, `covered_by`, `scene_id`.\n`graphics` is semantic design intent (`mode`, `direction`, exact text\u002Fassets in `elements`), not Timeline keyframes; pass `null` on `update_shot` to clear it.\n`production` holds the shot's production requirements (`media_strategy`,\n`protected_inputs`, …). A selection holding a shot with an asset in\n`protected_inputs` makes `render_storyboard_stills` return an error, and one holding\na `media_strategy: \"still_motion_graphics\"` shot does the same to\n`render_storyboard_clips`.\n`end_state` (the picture the shot ends on) and `sound` (what is heard) are one-take\ncues; `update_storyboard_one_take` sets them too.\n\nA one take sends the shot stills as `[Image N]` by default. A still fixes the\nframing and pose of one instant, so for an action shot the model holds that instant\ninstead of playing the action: a still of a splash at its peak renders as a shoe\nhovering over frozen water. For a board with action, set `reference_source:\n\"entities\"` on `update_storyboard_one_take`. The take then sends the reference\nimage of each board entity the shots use, and the shot text sets framing and\nmotion. Give the cast and the location entities clean reference images first.\n\n`camera` is `{framing?, lens?, angle?, movement?, equipment?}`.\n\n`covered_by` is `{shot_id, start_seconds?, end_seconds?}` — this shot's picture is a\nwindow into another shot's clip. See § Fusing shots below. `null` undoes it.\n\nBoard fields (`set_board` only): `brief`, `style`, `aspect_ratio`, `entity_ids`,\n`image_model`, `video_model`, `narration`, `music_prompt`, `motion_design`. Any other\nkey is refused with an error naming this set. The two model fields\ntake a model **object** from `find_model` (its `.ref`), or null, and become the\ndefaults for both render tools. `narration` and `music_prompt` take strings and\nupdate the screenplay; an empty string clears one. `motion_design` is\n`{direction?, transitions?: [{from_shot_id, to_shot_id, direction?}], continuities?:\n[{id, shot_ids, direction}]}`, or null to clear it.\n\n**An edit cannot set `keyframe`, `clip` or `status`.** Those belong to the render\ntools; passing them raises an error naming the right tool. `covered_by` is the one\nexception: coverage is a picture that arrived without a render, so setting it marks\nthe shot `rendered` and clearing it puts the shot back to `keyframe_ready`\u002F`planned`.\n\n**An edit cannot set `title`, `logline` or `style_bible` at the board level.**\nUse `ui_storyboard_set_screenplay` for those fields. Per-shot `narration` remains\na shot field. Board narration and music are separate screenplay fields:\n`assemble_storyboard_timeline` turns the music prompt into a draft music clip on\nevery board, and the board narration into a draft narration clip on a board with\nno linked script (a linked board voices its script lines instead).\n\n#### Fusing shots\n\nA video model snaps the requested length to the ones it offers — 5.184s, 6s, 8s —\nso a beat shorter than its shortest clip still buys the whole clip. A cut whose\nbeats run 1.5-2.5s is therefore cheaper to render as one generation covering a run\nof shots and split afterwards, than as one generation per shot: fifteen 1.5-2.5s\nbeats bought one at a time is ~77s of footage for a 30s cut.\n\nFuse a run of consecutive short beats that one prompt can carry: the same\nlocation and cast, cuts the model can make inside one take. Render a beat as its\nown clip and trim it on the timeline when it needs a picture no neighbour can\nshare, a different place, or its own still. Each of those clips is footage the cut\nthrows away, so report how many clips the board will buy before the clip pass and\nget the user's go-ahead when that is more than the request implied.\n\nDirect the run as one prompt with bracketed timecodes\n(`[00:00 to 00:02.5] Event … [00:02.5 to 00:05.2] Reception`), render it on the first\nshot of the run, then tell the board which slice each sibling uses:\n\n```json\n{\"op\": \"update_shot\", \"target\": \"06\",\n \"covered_by\": {\"shot_id\": \"05\", \"start_seconds\": 2.5, \"end_seconds\": 5.184}}\n```\n\nThe covered shot then reads `has_clip: true` with `status: \"rendered\"`, is skipped by\n`render_storyboard_clips` (so it is never generated twice), and\n`assemble_storyboard_timeline` lays it down as that window of the covering clip\ninstead of skipping it, and the covering shot ends where the first covered shot takes\nover. Without `end_seconds` the covered shot runs to the end of the covering clip.\n\nOne hop only: `shot_id` must name a shot that owns its clip, not another covered shot.\nRemoving the covering shot clears the coverage and reports which shots it uncovered.\n\n### Storyboard — browser (`ui_storyboard_*`)\n\nThe board must be open as a workspace tab; its id comes from the `ui_context` system\nblock. Not open → `edit_storyboard` edits the saved board. Use `ui_open_document {type: \"storyboard\", id}` to show it to the user. Target =\nshot id, index as a string, or `\"selected\"`. **Slugs are not resolved here.**\n\n| Tool | Arguments |\n|---|---|\n| `ui_storyboard_get_state` | `storyboard_id` |\n| `ui_storyboard_set_screenplay` | `storyboard_id`, `screenplay` |\n| `ui_storyboard_set_entities` | `storyboard_id`, `entity_ids` (replaces the cast; `[]` clears it) |\n| `ui_storyboard_add_shot` | `storyboard_id`, `action`, `slug?`, `camera?`, `motion?`, `graphics?`, `production?`, `durationSeconds?`, `index?`, `afterShotId?` |\n| `ui_storyboard_update_shot` | `storyboard_id`, `target`, `action?`, `slug?`, `camera?`, `motion?`, `graphics?`, `production?`, `dialogue?`, `notes?`, `durationSeconds?`, `durationSource?`, `status?` |\n| `ui_storyboard_remove_shot` \u002F `_duplicate_shot` | `storyboard_id`, `target` |\n| `ui_storyboard_move_shot` | `storyboard_id`, `target`, `sceneId?`, `position` |\n| `ui_storyboard_set_setup` | `storyboard_id`, `brief?`, `genre?`, `stage?`, `shotCount?`, `importSource?`, `directedFrom?` |\n| `ui_storyboard_direct` | `storyboard_id`, `redirect`, `shotCount?` |\n| `ui_storyboard_update_scene` | `storyboard_id`, `sceneId`, `slugline?`, `lighting?` |\n| `ui_storyboard_create_scene` \u002F `_merge_scene` | `storyboard_id`, `afterSceneId?` \u002F `sceneId` |\n| `ui_storyboard_set_style` | `storyboard_id`, `entityId?` or `descriptor?` |\n| `ui_storyboard_select_version` \u002F `_delete_version` | `storyboard_id`, `target`, `kind`, `version` |\n| `ui_storyboard_add_keyframe_version` | `storyboard_id`, `target`, `assetId`, `flipOf?` — adds the still without selecting it |\n| `ui_storyboard_generate_keyframe` | `storyboard_id`, `target`, `staleOnly?` |\n| `ui_storyboard_generate_clip` | `storyboard_id`, `target`, `staleOnly?` |\n| `ui_storyboard_revise_shot` | `storyboard_id`, `target`, `instruction` |\n| `ui_storyboard_assemble_timeline` | `storyboard_id` |\n| `ui_storyboard_select_shot` | `storyboard_id`, `target` (nullable) |\n| `ui_storyboard_extract_script` \u002F `_relink_script` \u002F `_reproject_shots` | `storyboard_id` (+ `targets?`) |\n| `ui_storyboard_set_duration_source` | `storyboard_id`, `targets`, `source` |\n\nThe browser shot tools take **no** `narration`, `entity_ids` or `render_mode`, and\n`add_shot` takes no `dialogue`. In the browser those arrive through\n`set_screenplay`; headless, through `edit_storyboard`.\n\nGeneration is asynchronous: `generate_keyframe` \u002F `generate_clip` start the job and\nreturn the shot. Poll `ui_storyboard_get_state` for `status`.\n\nStatuses: `planned` → `keyframe_generating` → `keyframe_ready` → `clip_generating` →\n`rendered`, or `failed`. (`approved` is legacy and reads as \"still ready\"; nothing\nsets it. Do not use it as a gate.)\n\n#### `screenplay` for `set_screenplay`\n\n```json\n{\n  \"type\": \"screenplay\",\n  \"title\": \"…\",\n  \"logline\": \"…\",\n  \"brief\": \"…\",\n  \"styleBible\": \"…\",\n  \"aspectRatio\": \"9:16\",\n  \"narration\": \"…\",\n  \"musicPrompt\": \"…\",\n  \"entityIds\": [\"\u003Casset id>\"],\n  \"shots\": [\n    {\n      \"slug\": \"1a\",\n      \"action\": \"Nova touches untreated hair, front-camera close\",\n      \"camera\": { \"framing\": \"close-up\", \"lens\": \"26mm\", \"angle\": \"eye\", \"movement\": \"handheld\" },\n      \"motion\": \"she lifts one section of hair and lets it fall, once\",\n      \"dialogue\": \"I wanted lighter hair…\",\n      \"durationSeconds\": 4,\n      \"entityIds\": [\"\u003Casset id>\"]\n    }\n  ]\n}\n```\n\nIds, indexes and statuses are filled in. `style` is accepted as an alias of\n`styleBible`. Only `action` is required per shot.\n\nThe top-level `entityIds` casts those entities on the **board** — that cast is what\nseasons every shot's still and clip prompt. Use `ui_storyboard_set_entities` to\nrecast without replacing the shots; `ui_storyboard_get_state` reports the current\ncast as `entityIds`. A shot's own `entityIds` overrides the board cast for that shot\n(`[]` means \"no entities on this shot\"); without one, styles and locations apply to\nevery shot and characters and props apply to the shots whose text names them.\n\n### Entities\n\n| Tool | Arguments |\n|---|---|\n| `list_entities` | `kind?` (`character`\\|`location`\\|`style`\\|`prop`), `query?`, `limit?` |\n| `get_entity` | `entity_id` |\n| `create_entity` | `asset_id`, `kind`, `name`, `descriptor` (all required), `description?`, `voice_id?`, `tags?`, `lora?`, `palette?` |\n| `update_entity` | `entity_id` + any field, including `asset_id` to move it to a new photo |\n| `delete_entity` | `entity_id` — clears the marker, keeps the image |\n| `apply_entities` | `text`, `entity_ids?` → seasoned prompt + reference asset ids |\n\nAn entity **is** an image asset carrying a marker. Its id is the asset id. To make one\nfrom nothing: `find_model` (`text_to_image`) → `generate_image` → `create_entity` with\nthe returned asset id. To make one from a photo the user attached: find it with\n`asset_search` \u002F `list_assets`, then `create_entity`.\n\n`apply_entities` is for seasoning a prompt you are about to send yourself\n(`generate_image`, `generate_video`). The storyboard render tools season internally —\ndo not pre-season shot text with it.\n\n### Timeline\n\n`assemble_storyboard_timeline` lays rendered clips end to end, stamps each with its\nboard and shot id, and gives every shot clip an **audio twin on a \"Shot Audio\" track**\n(each surface mutes video elements and mixes audio clips only). Board narration and\nmusic become draft clips on their own tracks.\n\n**Each shot is as long as its render**, not as long as its `duration_seconds` — a shot\ndirected at 1.5s that came back at 5.184s occupies 5.184s of the cut. Shots that came\nback off their directed length are returned in `retimed_shots` and warned about, so a\ncut that runs longer than planned is visible without playing it. `duration_seconds`\nonly decides a shot whose footage has no measurable length. A board linked to a script\nis the exception: there the words decide, and `trimmed_shots` names the shots whose\nfootage does not fill the slot its lines gave it.\n\n`edit_timeline {timeline_id, ops[]}` carries the edit; `timeline-edit-ops` holds its\nfull op list. Start with `get_state` for ids.\n\nTo duck the shots' own sound under a voiceover: `set_clip_params` on the Shot Audio\nclips with `muted: true`, or `volumeDb: -18`. `set_clip_params` also takes `name`,\n`opacity`, `speedMultiplier`, `fadeInMs`, `fadeOutMs`, `blendMode`, `borderRadius`,\n`hidden`, `locked`, `textStyle`, `shapeStyle`.\n\nEvery field goes on the op itself. A `params` \u002F `props` wrapper is unwrapped, but the\nflat form is the contract:\n\n```json\n{\"op\": \"set_clip_params\", \"target\": \"clip_1\",\n \"textStyle\": {\"fontFamily\": \"Space Grotesk\", \"fontWeight\": 800}}\n```\n\n`textStyle` is **merged** over the clip's own, so send only what you are changing —\nre-sending the whole object is how the fields you did not mean to touch get\noverwritten. `fontWeight` is a number, and the CSS keywords (`bold`, `semibold`,\n`extrabold`) are accepted and stored as one.\n\n**Set a bundled family or none at all.** `sans-serif`, `serif`, `system-ui` and the\nother CSS generics are refused where the clip is authored: they name no typeface, so\nthe editor preview, the render and `preview_timeline_frame` each pick a different one.\nNodeTool ships Inter (the default), Space Grotesk, Bebas Neue, Playfair Display, Lora\nand JetBrains Mono. A named system font is still allowed and `validate_timeline`\nreports it as `font_not_portable`.\n\n`validate_timeline {timeline_id | document, fps?}` after every edit pass. It catches\noverlaps, fades longer than their clip, unknown presets and incomplete bindings.\n\nOther timeline tools: `list_timelines`, `create_timeline`, `get_timeline`,\n`delete_timeline`, and the version family (`list_`\u002F`get_`\u002F`create_`\u002F`restore_`\u002F\n`delete_timeline_version`). Browser twins are `ui_timeline_*`.\n\n### Script\n\nUse a script when the words drive the cut. `extract_script_from_storyboard` projects a\nboard's dialogue and narration into a script and links the two: each shot keeps the\nline ids it covers, and from then on the script owns the words. `derive_storyboard_from_script`\ngoes the other way, one shot per line, optionally with a director pass over the scaffold.\n\n`voice_script_lines` synthesizes each line with its cast voice; `assemble_script_timeline`\nlays the takes end to end.\n\n**Give the cast their voices first, then voice with no override.** A line takes its\nvoice from its speaker: `add_line` without `speaker` leaves it with none, and\n`extract_script_from_storyboard` creates the Narrator with no voice and each\ncharacter with at most its entity's `voice_id` and no provider or model. Either way\nthe line reads `no_voice` until its speaker is bound. A voice is the\ntriple `{provider, model, voice}` where `voice` is the voice's own name (`Aoede`,\n`Charon`, `alloy`) — a provider and a model alone do not pick one, so\n`voice_script_lines {provider, model}` is refused. Set each speaker once:\n\n```json\n{\"op\": \"set_speaker_voice\", \"target\": \"MOM\",\n \"provider\": \"gemini\", \"model\": \"gemini-2.5-flash-preview-tts\", \"voice\": \"Aoede\"}\n```\n\nThe three keys sit on the op, though a `voice: {provider, model, voice_id}` object —\nthe shape `get_script` reports a voice in — is flattened onto it. Then call\n`voice_script_lines {script_id}` with no override and every speaker resolves its own. On a linked board, `assemble_storyboard_timeline` cuts words\nand picture together: each shot runs as long as the takes it covers and every voiced\nline gets its own voiceover clip.\n\nOthers: `list_scripts`, `get_script` (line status: `draft`, `stale`, `voiced`,\n`no_voice`), `create_script`, `edit_script`, `delete_script`. Browser twins are\n`ui_script_*`.\n\n#### Writing the lines\n\n`create_script` makes an empty one. `edit_script {script_id, ops[]}` ops:\n`set_setup` (brief, format, length, pace, language, stage), `add_speaker`,\n`set_speaker`, `set_speaker_voice`, `add_section`, `add_line`, `set_line_text`,\n`set_line_speaker`, `remove_line`, `remove_speaker`. Call `get_script` first for\nline and speaker ids.\n\n`write_script {script_id, rewrite?, imported_text?}` drafts the lines from the\nsetup and saves the cast and lines it produces, replacing what was there. Set\nthe brief with `set_setup` first. `rewrite: true` keeps the ids of the lines it\nkeeps, so their takes and storyboard links survive. Words passed as\n`imported_text` are only split into lines and attributed to speakers, never\nreworded. It records no take: voice the result with `voice_script_lines`.\n\nRewriting a line leaves its takes in place as **stale**, so a following\n`voice_script_lines` re-records exactly those and nothing else.\n\n### Models\n\n`find_model {capability, query?, task?, provider_hint?, model_hint?, prefer_local?,\nlimit?}` is the only way to name a model. **`capability` is required** and is one of\n`text_to_image`, `image_to_image`, `segment_image`, `text_to_video`, `image_to_video`,\n`reference_to_video`, `text_to_speech`, `text_to_music`, `audio_to_audio`,\n`automatic_speech_recognition`, `generate_embedding`, `generate_message`. `query` is the search box (`\"flux schnell\"`); `task` is a hint\nmatched against a model's supported tasks, not a search.\n\nNodeTool ships curated ids under the `nodetool` provider, which are the sane defaults\nwhen the user has no preference:\n\n| Id | Use |\n|---|---|\n| `nodetool\u002Fflux-schnell` | cheapest stills, text prompts only |\n| `nodetool\u002Fnano-banana` | sharper stills, takes reference images |\n| `nodetool\u002Fseedream` | most detail, slowest |\n| `nodetool\u002Fhailuo-fast` | cheapest clips, for blocking out a cut |\n| `nodetool\u002Fkling-turbo` | steadier motion, mid price |\n| `nodetool\u002Fkling-standard` | most faithful motion |\n| `nodetool\u002Fkokoro` | eight TTS voices |\n\n### Media, outside the board\n\n`generate_image {provider, model, prompt, negative_prompt?, width?, height?, quality?,\noutput_file?}`, plus `edit_image`, `generate_video`, `animate_image`, `generate_speech`,\n`generate_music` and `transcribe_audio` — each takes a `find_model` provider+model and\nsaves an `asset:\u002F\u002F` result. `model` also accepts a whole `find_model` hit or its `.ref`,\nin which case `provider` may be omitted.\n\n`understand_video {provider, model, video, prompt?, max_tokens?}` reads a whole video\nwith a multimodal model (Gemini reads video natively); use it to break down a reference\ncut. `video` takes an asset id, an `asset:\u002F\u002F` URI, a URL or a data URI. `view_image`\nputs pixels in your own context; `read_media_bytes` returns the bytes.\n\n### The Director node\n\n`nodetool.creative.Director` is a **workflow node**, not a chat surface. It turns a\nbrief into a `Screenplay` (props: `model`, `brief`, `style`, `shot_count`, `aspect_ratio`,\n`max_tokens`; outputs\n`screenplay`, `narration`, `music_prompt`, `title`). Reach for it only inside a\nreusable graph. In chat, `direct_storyboard` runs the same Director over a saved\nboard, or write the shots yourself with `edit_storyboard`.\n\n### Still-motion-graphics boards\n\nA board whose shots carry `production.media_strategy: \"still_motion_graphics\"` renders\nno clips: its stills and `graphics` elements become timeline layers.\n`preview_storyboard_design {storyboardId, expectedStoryboardRevision}` reads the design\nas a timeline preview with no save. `layout_storyboard` places every layer at each\nshot's hold frame with a vision model. `finish_storyboard` writes the editable\ntimeline: `strategy: \"deterministic\"` (default, no provider) returns an unreviewed\nscaffold, `\"agentic\"` composes the motion and reviews rendered frames. All three\nneed the board's current `revision` from `get_storyboard`.\n\n## Standing orders\n\nUse this optional template only when the user wants a staged review with approval\nbetween the board, stills, clips, and cut. Its checkpoints express that user's\nchosen workflow. They do not apply to other requests or override authorization\nalready given to finish a piece.\n\nRespect the thread's existing permission mode. Plan mode blocks writes. Do not\nswitch modes or use another tool family to evade a denial. The user can adapt the\nbrief to authorize the desired stages and set a budget.\n\n```\nYou are directing on the storyboard surface, then finishing in the timeline.\nDo not build a node graph unless I ask for a reusable template.\n\nSURFACES\nHeadless: create_storyboard, get_storyboard, edit_storyboard,\nrender_storyboard_stills, render_storyboard_clips, revise_storyboard_clip,\nassemble_storyboard_timeline, extract_script_from_storyboard.\nBrowser (only for a board open as a tab): ui_storyboard_get_state,\nui_storyboard_set_screenplay, ui_storyboard_generate_keyframe,\nui_storyboard_generate_clip, ui_storyboard_revise_shot,\nui_storyboard_assemble_timeline. Use ui_open_document to open a board.\nThe ui_ generate and revise calls spend like the headless renders: same\napproval rules.\n\nLOOP\n1. list_storyboards, or read ui_context. No board -> create_storyboard.\n2. Cast before anything renders. list_entities first. A new entity needs an\n   image asset: generate_image (or my attachment), then create_entity with\n   {asset_id, kind, name, descriptor}. There is no create-from-text.\n   Each entity: one name, one kind, one canonical descriptor sentence.\n3. edit_storyboard set_board {entity_ids, image_model, video_model,\n   brief, style, aspect_ratio, narration, music_prompt}. Models come from find_model — there is no\n   default and an unset model fails the render.\n4. Direct with edit_storyboard add_shot, one op per shot. Give every shot a\n   slug (1a, 2a, ...). Fields: action, slug, camera {framing, lens, angle,\n   movement}, motion, dialogue, narration, duration_seconds, render_mode.\n5. STOP after the board. Report shot count and the two model ids. Do not\n   estimate dollars — no tool prices a render. Wait for \"stills\".\n6. render_storyboard_stills. I pick takes in the board's takes gallery, or\n   tell you which one; you apply it with edit_storyboard select_version.\n   Wait for \"clips\".\n7. render_storyboard_clips. revise_storyboard_clip touches one shot only.\n8. On \"cut\": assemble_storyboard_timeline, then validate_timeline.\n\nWRITING THE SHOTS\nThe still prompt is action, camera framing, angle and lens, the scene\nlighting and the board style. A keyframe clip prompt is motion, action,\ncamera movement and equipment; a direct clip gets all of these. Write camera\ndirection into the camera object once, not into action as well.\nName entities in plain text — \"Nova reaches for the bottle\", never \"@Nova\".\nEntities season a shot when their name appears in its action, motion, dialogue,\nnarration or slug; styles and locations season every shot. A shot's entity_ids,\nif set, overrides that entirely.\n\nLOCKS\n- The descriptor is the face. Do not re-describe an entity in shot text.\n- Product geometry, label, cap and colour come from the product entity. No new\n  logos.\n- A state change (wet, stained, new outfit) is a second entity, not a morph\n  instruction inside one prompt.\n- Slugs stay stable. \"Fix 3a\" edits 3a and renders 3a.\n- UGC: handheld phone, grain, natural audio, no score, no beauty filter.\n  Hero: locked grade in the style, smooth camera, score allowed.\n- render_mode \"keyframe\" (default) for anything where the look must hold;\n  \"direct\" for heavy motion or a native-audio video model.\n\nMEMORY\nmemory_save the style, the cast and the grade, with the entity and board ids in\n`resources` — that survives into later threads. share_result\u002Fread_shared are\nrun-scoped and get discarded; do not use them to lock a look.\n\nIf the shot count looks expensive, propose a collapse before rendering clips.\n```\n","The shared half of every NodeTool video job. The use-case skills carry the style,\nthe shot pattern and the briefs; this carries the machinery they all assume.\n\nDirect video on the **storyboard** surface, then finish in the **timeline**. Use a node graph when the user requests one or needs a reusable template, as\ndescribed in `video-workflow`.\n\nRead the relevant part of **Tool contract** below before the first call in\nthat tool family. Use the live tool schema when it differs\nfrom an example. Load other sections only when the task reaches them.\n\n## Pick the use-case skill\n\n| Job | Skill |\n|---|---|\n| Phone-shot video with a person: UGC ad, testimonial, comedy, day-in-the-life, vlog | `\u002Fugc-video` |\n| Product film: pack shot, hero, brand spot, with or without talent | `\u002Fproduct-commercial` |\n| Sound-off motion-graphics ad from real screenshots and product photos, no generated footage | `\u002Fmotion-ad` |\n| Rebuild an existing ad or clip you were given | `\u002Fvideo-clone` |\n| Voiceover drives the picture: explainer, faceless video, narrated piece | `\u002Fscript-video` |\n| Narrative with dialogue, score and a title: short film, trailer, scene | `\u002Fshort-film` |\n| A campaign, not one video: entity sheets, still set, several cuts | `\u002Flaunch-kit` |\n| A template to re-run on new inputs | `\u002Fvideo-workflow` |\n| Footage already exists and needs repair: cutout, upscale, outpaint, lip sync, generated sound | `\u002Fnodetool-video-post` |\n| A screen someone clicks, over the workflows behind a piece | `\u002Fnodetool-app-builder` |\n\nIf none fits, run the loop below directly.\n\nThose skills say what the picture looks like. A second set says where the beats\ngo, and the two compose: load the job skill for the look and the structure\nskill for the spine.\n\n| The structure question | Skill |\n|---|---|\n| Ad beats: hook, escalation, timecodes, VO discipline | `\u002Fcommercial-beat-sheet` |\n| A product page URL in, a finished cut and its cost out | `\u002Flaunch-commercial` |\n| A 30–120s explanation with a claim per beat | `\u002Fexplainer-storyboard` |\n| A treatment cut to a track's sections | `\u002Fmusic-video-treatment` |\n| Eight audio-first beats, the drop at ~65%, a title card | `\u002Ftrailer-template` |\n\nThese own their own briefs and beat budgets. The storyboard, entity and render\ncall shapes live once, in **Tool contract** below. Every job and structure skill\npoints here for them.\n\n## Two tool families, one board\n\n| | Headless | Browser |\n|---|---|---|\n| Names | `create_storyboard`, `get_storyboard`, `edit_storyboard`, `direct_storyboard`, `render_storyboard_stills`, `render_storyboard_clips`, `revise_storyboard_clip`, `assemble_storyboard_timeline`, and the rest of **Tool contract** | `ui_storyboard_*`: a browser twin for most headless ops, plus `set_screenplay` (table in **Tool contract**) |\n| Needs | nothing open | the board open as a tab, listed in the `ui_context` system block |\n| Shot target | id, 0-based index, or **slug** | id, 0-based index, or `\"selected\"` — **no slug** |\n| Permission gate | yes | no (client tools bypass it) |\n\nEvery board tool in both families names its board explicitly (`storyboard_id`, or\n`storyboardId` on the still-motion-graphics tools). There is no \"act on whatever is\nopen\" fallback.\n\nPrefer headless. Reach for `ui_storyboard_*` when the user is watching the board fill\nin, or when you need `set_screenplay` for `title`, `logline` or `style_bible`.\nHeadless `edit_storyboard` → `set_board` writes screenplay-level `narration`,\n`music_prompt` and `motion_design` while preserving the other screenplay fields.\nBridge the two with `ui_open_document {type: \"storyboard\", id}`.\n\n`ui_storyboard_generate_keyframe`, `ui_storyboard_generate_clip` and\n`ui_storyboard_revise_shot` spend exactly what the headless renders spend, and no\npermission prompt stands in front of them. Call them only inside a render the\nuser has already authorized.\n\n## The loop\n\n1. **Find the board.** `list_storyboards`, or read `ui_context`. No board yet →\n   `create_storyboard {name, brief, style, aspect_ratio}`.\n2. **Cast the entities.** `list_entities` first. A new one needs an image asset —\n   `generate_image` or the user's upload — then\n   `create_entity {asset_id, kind, name, descriptor}`. **There is no create-from-text.**\n3. **Attach the cast to the board:** `edit_storyboard` → `{op: \"set_board\", entity_ids: [...]}`,\n   or `ui_storyboard_set_entities {storyboard_id, entity_ids}` on an open board.\n   Name matching only searches the board cast, so an entity cast nowhere seasons\n   nothing, no matter what the shots say. An id in a shot's own `entity_ids` is\n   added to the board cast when the board is read.\n4. **Pin the models.** `find_model` with `capability` `text_to_image`, then\n   `image_to_video` or `text_to_video`; write both through\n   `{op: \"set_board\", image_model, video_model}`. There is no default — an unset\n   model fails the render rather than spending on a model nobody chose.\n5. **Direct.** One `{op: \"add_shot\", ...}` per shot. Report the shot count and\n   selected models. Continue to the stages authorized by the request. A board-only\n   request ends here. Honor any checkpoint the user requested.\n6. **Stills.** `render_storyboard_stills {storyboard_id}` — omit `targets` for every\n   shot that still needs one. Cap 24 shots per call.\n7. **Take selection, when requested.** Every render keeps the old still in\n   `keyframe_versions` and the old clip in `clip_versions`, and makes the new one\n   selected. `edit_storyboard` → `{op: \"select_version\", target, kind: \"keyframe\"|\"clip\",\n   version}` selects another (0-based, oldest first). Pause if the user reserved\n   the pick for themselves in the takes gallery.\n8. **Clips.** `render_storyboard_clips {storyboard_id}` within the requested\n   generation scope and budget. Reuse prior authorization instead of asking again.\n9. **Revise one shot:** `revise_storyboard_clip {target, instruction}`. Needs an\n   existing clip; it is video-to-video and touches no other shot.\n10. **Cut.** `assemble_storyboard_timeline`, then `validate_timeline`. Re-running\n    rebuilds the same sequence in place and keeps tracks the board does not own.\n11. **Finish** with `edit_timeline` ops (**Tool contract** § Timeline, below).\n    Load `timeline-edit-ops` with `load_skill` for the full op list, the presets\n    and the preview contract, and `motion-graphics` for the build loop. A repair\n    on a delivered clip belongs to `nodetool-video-post`.\n\n**Stills-only mode.** When the user wants a board and frames but no motion — a spec\nad, a pitch, a look test — run steps 1 to 7 and stop. Adding the motion later is\n`update_shot` on `motion` alone: action, wardrobe, set and cast stay put, so the\napproved stills still describe the finished piece.\n\n## What actually reaches the model\n\nThe prompt is assembled from named fields, comma-joined, not from the whole shot:\n\n| Field | Still | Clip, `keyframe` mode | Clip, `direct` or `reference` mode |\n|---|---|---|---|\n| `action` | yes | yes | yes |\n| `camera.framing` | `\"\u003Cframing> shot\"` | — | `\"\u003Cframing> shot\"` |\n| `camera.angle` | yes | — | yes |\n| `camera.lens` | `\"\u003Clens> lens\"` | — | `\"\u003Clens> lens\"` |\n| the shot's scene `lighting` | yes | — | yes |\n| `motion` | — | yes (first) | yes |\n| `camera.movement`, `camera.equipment` | — | yes | yes |\n| board `style` | yes | — | yes |\n\nA keyframe-mode clip animates a still that already carries framing, lens,\nlighting and style, so the clip prompt leaves them out. Write camera direction\ninto the `camera` object, not into `action` as well. `dialogue`, `notes`,\n`duration_seconds`, `end_state`, `sound` and `graphics` never enter a per-shot\nprompt (`end_state` and `sound` feed the one-take prompt only).\n\n**Entities season by plain name.** A shot with `entity_ids` uses exactly those.\nOtherwise: every style and location entity applies to every shot, and a character or\nprop applies when its **name appears** in the shot's `action`, `motion`, `dialogue`,\n`narration` or `slug`. Write `Nova reaches for the bottle`, not `@Nova reaches...`.\n`@` is a chat-composer affordance that emits an `entity:\u002F\u002F\u003Cid>` token into *your\nmessage*; it never becomes shot text.\n\n## Locks\n\n- Keep one `descriptor` per entity and let it do the work. Do not re-describe a face\n  in shot text.\n- A state change (wet hair, a stained shirt, a second outfit) is a **second entity**,\n  not an instruction inside one prompt.\n- Product geometry, label and colour come from the product entity's descriptor and\n  reference image. Never invent a logo.\n- Give every shot a stable `slug` (`1a`, `2a`, …) at `add_shot` time. Headless targets\n  accept it, and \"fix 3a\" then means one shot.\n- Render mode is per shot. `keyframe` (default) is cheaper to iterate and holds a look\n  steady. `direct` skips the still — worth it for heavy motion, where first-frame\n  conditioning stiffens the result, and for native-audio video models, which are\n  weakest on their image path.\n- A native-audio model writes the sound per clip, so a board of one clip per shot\n  cuts the audio at every join. Before rendering, load the `video-audio-continuity`\n  system skill through `load_skill`: either the whole piece is one shot\n  carrying the cuts, or the\n  continuity comes from a narration or music track and the shot audio is muted.\n  A silent cut is also valid when sound is not requested. Reuse existing audio\n  or keep the cut silent when extra generation would exceed the authorized scope.\n\n## Where the models will not do what the cut wants\n\nFour constraints that are not bugs and have no tool to fix them. Each has a working\nshape.\n\n**A video model returns the lengths it offers.** The render sends\n`duration_seconds`, and the model snaps it to its own steps — a shot directed at\n1.5s comes back at 5.184s on a model whose shortest clip is that long. For a run of\nbeats shorter than the model's shortest clip, render one generation with bracketed\ntimecodes in the prompt and record the split with `covered_by`. **Tool contract**\n§ Fusing shots, below, has the call and the rule for when to fuse and when to\nrender each beat long and trim.\n\n**Moderation reads the words, not the story.** A prompt naming institutional force —\npolice grabbing someone, a raid, restraint — trips a safety filter that a shot of the\nsame threat does not. Reframe with non-trigger vocabulary and keep the stakes:\n\"two uniformed city officials approaching with a clipboard and caution tape\" passes\nwhere \"two aggressive police officers grabbing her arms\" does not. Reframe once; do\nnot retry the rejected prompt.\n\n**A music model cannot leave a hole.** Ask for 1.5s of silence at 00:19.5 and the\ndecoder fills it with reverb tail and room tone — there is no envelope gate in the\nprompt. Cut the silence on the timeline instead: generate the score in two parts,\nlay them as two clips with the gap between them, and fade the first out (~300ms) and\nthe second in (~100ms) so the edges are not clicks.\n\n**Speech does not fit a 1.5s shot.** An expressive take of a line runs 4s, and\ncompressing it to the picture beat makes it sound processed. Let the words cross the\ncut: keep the voiceover clip on its own track and start it under the previous shot\n(J-cut) or run it past the cut into the next (L-cut). The picture cuts on the beat;\nthe line finishes where it finishes. On a script-linked board that is automatic —\neach shot runs as long as the lines it covers — so use this on an unlinked board or\nwhere the picture has to stay on the beat.\n\n## Gating and spend\n\nPermission mode decides what runs without asking. `read` tools always run.\n\n| Mode | write \u002F execute \u002F external |\n|---|---|\n| `auto` | runs |\n| `default` | asks the user |\n| `plan` | **blocked** |\n\n`plan` blocks `create_storyboard` and `edit_storyboard` too, so the board cannot be\nwritten in it. Respect the active permission mode and tool approval responses. For a board-only\nrequest, write the board and omit render calls. Do not switch modes or use browser\ntools to evade a denied headless action. A tool being callable does not authorize\nspend beyond the user's request.\n\n**You cannot price a render.** No tool estimates it, and `Shot.cost_estimate` is not\npopulated. Report the shot count, the clip count and the models without inventing a\ndollar estimate, and confirm that scope with the user before fanning out a clip\npass the request did not already size. If a user\nbudget cannot be checked before spending, resolve that constraint first. Report\nactual spend afterwards with `get_cost_summary`. If authorization is missing,\nprepare the board and explain the specific render action that needs approval.\n\n## Memory\n\n`memory_save` is durable across every conversation — use it for the style bible, the\ncast and the grade, with the entity and board ids in `resources`. `share_result` \u002F\n`read_shared` are **run-scoped and discarded**; they are for passing values inside one\nturn, not for locking a look across sessions.\n\n## Follow-ups this loop already handles\n\n```\nFix 3a only. Leave the rest.\nDrop the contre-jour across the whole board — soft even daylight. Update the\n  board style, do not rewrite the shots.\nNew still on 2a. Keep the old take.\nrevise_storyboard_clip 5a: darker, add rain, same blocking.\nAdd a reaction shot after 3a and re-slug from there. Do not re-render 1a-3a.\nCollapse 8, 9 and 10 into one 8s shot, keeping the lean-in as the last second.\nThe face drifted on 4a. Select still take 2, then regenerate the clip.\nThe label is unreadable on 2a. New macro still, then a clip from it.\nCut it. Assemble, validate, narration on its own track, mute Shot Audio on 1-6.\n```\n\n## What is below\n\n- **Tool contract** — every tool, its arguments, and the fields it refuses.\n- **Standing orders** — an optional brief for users who explicitly want\n  approval between stages. Its sample checkpoints do not add requirements to\n  a different request.\n\n## Tool contract\n\nThe one copy of the storyboard contract; the job and structure skills point\nhere. Exact arguments. Every field named here is checked in the implementation;\nan unrecognized field is **refused with an error**, not dropped.\n\n### Storyboard — headless\n\nWork with no editor open. Shot `target` = shot id, 0-based index as a string, or slug.\n\n| Tool | Arguments |\n|---|---|\n| `list_storyboards` | `limit?` → id, name, shots, with_keyframe, with_clip, timeline_id, updated_at |\n| `create_storyboard` | `name` (required), `brief?`, `style?`, `aspect_ratio?` (default `16:9`), `project_id?`, `id?` → `{ok, storyboard_id, id, name, project_id, shots, updated_at, revision}`; `storyboard_id` and `id` hold the same value |\n| `get_storyboard` | `storyboard_id` → brief, style, aspect ratio, narration, music_prompt, motion_design, image_model, video_model, script link, revision, and every shot with id\u002Findex\u002Fslug\u002Faction\u002Fcamera\u002Fmotion\u002Fduration\u002Fstatus\u002Fhas_keyframe\u002Fhas_clip\u002Fcovered_by |\n| `edit_storyboard` | `storyboard_id`, `ops[]` — see below, `expected_revision?` (refused if the board changed since that revision) |\n| `direct_storyboard` | `storyboard_id`, `redirect?`, `shot_count?` (default 6), `provider?`, `model?` — the Director writes scenes and shots from the board's brief, genre and style; set the brief with `set_setup` first. Renders nothing |\n| `render_storyboard_stills` | `storyboard_id`, `targets?`, `provider?`, `model?`, `style?`, `stale_only?`, `concurrency?` |\n| `render_storyboard_clips` | `storyboard_id`, `targets?`, `provider?`, `model?`, `resolution?`, `mode?` (`keyframe`\\|`direct`\\|`reference`), `stale_only?`, `concurrency?` |\n| `revise_storyboard_clip` | `storyboard_id`, `target`, `instruction`, `provider?`, `model?` |\n| `assemble_storyboard_timeline` | `storyboard_id`, `name?`, `fps?` (default 30) |\n| `derive_shot_from_clip` | `timeline_id`, `clip_id`, `frame_count?` (1-8, default 3), `action?` — a new reference-mode shot after the source shot, conditioned on frames of that clip. Renders nothing |\n| `extract_script_from_storyboard` | `storyboard_id`, `name?`, `relink?` |\n| `delete_storyboard` | `storyboard_id` |\n| `get_storyboard_one_take` | `storyboard_id` → `prompt` (the creator's), `compiled` (REFS, STEPS, AUDIO from the board), `full_prompt`, references with `[Image N]` (the shot stills, in shot order), shot windows, duration, `settings` (stored `duration_seconds`, `aspect_ratio`, `resolution`, `model`), `effective` (after board fallbacks), warnings |\n| `update_storyboard_one_take` | `storyboard_id`, `prompt?`, `duration_seconds?`, `aspect_ratio?`, `resolution?`, `model?` `{provider, id, name?}` (null clears one), `shots?` `[{shot_id, end_state?, sound?}]`, `expected_revision?` |\n\nRender limits: **24 shots per call**, `concurrency` default 3, max 8.\n\nOmitting `targets` selects every shot that still needs that step. For stills that is\nevery shot with no keyframe that is not set to render directly; for clips, every shot\nwith no picture — its own or one it is covered by (§ Fusing shots). A `keyframe`-mode\nshot that reaches `render_storyboard_clips` with no\nstill is reported in the results, not rendered — render its still first, or set its\n`render_mode` to `direct`. Each render appends to `keyframe_versions` \u002F\n`clip_versions` and makes the new one selected.\n\n#### `edit_storyboard` ops\n\nFifteen ops, applied in order, at most 60 per call:\n\n| Op | Arguments |\n|---|---|\n| `add_shot` | shot fields below; `action` required; `index?` or `after_shot_id?` (inserts after that shot, in its scene) |\n| `update_shot` | `target` + any shot fields |\n| `remove_shot` | `target` |\n| `reorder_shot` | `target`, `index` (board position) |\n| `move_shot` | `target`, `scene_id?`, `position` (0-based inside the target scene) — how a shot changes scene |\n| `duplicate_shot` | `target` — the copy lands right after it, without script links or coverage |\n| `set_board` | board fields below |\n| `set_setup` | `brief?`, `genre?`, `stage?` (the guided-setup answers `direct_storyboard` reads) |\n| `update_scene` | `scene_id`, `slugline?`, `lighting?` |\n| `create_scene` | `after_scene_id?`, `slugline?` — opens holding one blank shot |\n| `merge_scene` | `scene_id` — folds it into the scene before it |\n| `set_style` | `entity_id` (a style entity becomes the board preset and its descriptor the board style) or `style` (the descriptor alone) |\n| `select_version` | `target`, `kind` (`keyframe`\\|`clip`), `version` (0-based, oldest first) — nothing re-renders |\n| `delete_version` | `target`, `kind`, `version` — the asset stays in the library |\n| `add_keyframe_version` | `target`, `asset_id`, `flip_of?` — attaches a stored image as a new still and selects it |\n\n`set_entities` is accepted as an alias of `set_board`, and a few other near-miss\nnames resolve the same way; an unknown op is refused.\n\nShot fields (add and update both): `action`, `slug`, `camera`, `motion`, `end_state`,\n`sound`, `graphics`, `production`, `dialogue`, `narration`, `notes`, `duration_seconds`,\n`duration_source` (`audio`\\|`manual`), `render_mode` (`keyframe`\\|`direct`\\|`reference`),\n`entity_ids`, `location_id`, `covered_by`, `scene_id`.\n`graphics` is semantic design intent (`mode`, `direction`, exact text\u002Fassets in `elements`), not Timeline keyframes; pass `null` on `update_shot` to clear it.\n`production` holds the shot's production requirements (`media_strategy`,\n`protected_inputs`, …). A selection holding a shot with an asset in\n`protected_inputs` makes `render_storyboard_stills` return an error, and one holding\na `media_strategy: \"still_motion_graphics\"` shot does the same to\n`render_storyboard_clips`.\n`end_state` (the picture the shot ends on) and `sound` (what is heard) are one-take\ncues; `update_storyboard_one_take` sets them too.\n\nA one take sends the shot stills as `[Image N]` by default. A still fixes the\nframing and pose of one instant, so for an action shot the model holds that instant\ninstead of playing the action: a still of a splash at its peak renders as a shoe\nhovering over frozen water. For a board with action, set `reference_source:\n\"entities\"` on `update_storyboard_one_take`. The take then sends the reference\nimage of each board entity the shots use, and the shot text sets framing and\nmotion. Give the cast and the location entities clean reference images first.\n\n`camera` is `{framing?, lens?, angle?, movement?, equipment?}`.\n\n`covered_by` is `{shot_id, start_seconds?, end_seconds?}` — this shot's picture is a\nwindow into another shot's clip. See § Fusing shots below. `null` undoes it.\n\nBoard fields (`set_board` only): `brief`, `style`, `aspect_ratio`, `entity_ids`,\n`image_model`, `video_model`, `narration`, `music_prompt`, `motion_design`. Any other\nkey is refused with an error naming this set. The two model fields\ntake a model **object** from `find_model` (its `.ref`), or null, and become the\ndefaults for both render tools. `narration` and `music_prompt` take strings and\nupdate the screenplay; an empty string clears one. `motion_design` is\n`{direction?, transitions?: [{from_shot_id, to_shot_id, direction?}], continuities?:\n[{id, shot_ids, direction}]}`, or null to clear it.\n\n**An edit cannot set `keyframe`, `clip` or `status`.** Those belong to the render\ntools; passing them raises an error naming the right tool. `covered_by` is the one\nexception: coverage is a picture that arrived without a render, so setting it marks\nthe shot `rendered` and clearing it puts the shot back to `keyframe_ready`\u002F`planned`.\n\n**An edit cannot set `title`, `logline` or `style_bible` at the board level.**\nUse `ui_storyboard_set_screenplay` for those fields. Per-shot `narration` remains\na shot field. Board narration and music are separate screenplay fields:\n`assemble_storyboard_timeline` turns the music prompt into a draft music clip on\nevery board, and the board narration into a draft narration clip on a board with\nno linked script (a linked board voices its script lines instead).\n\n#### Fusing shots\n\nA video model snaps the requested length to the ones it offers — 5.184s, 6s, 8s —\nso a beat shorter than its shortest clip still buys the whole clip. A cut whose\nbeats run 1.5-2.5s is therefore cheaper to render as one generation covering a run\nof shots and split afterwards, than as one generation per shot: fifteen 1.5-2.5s\nbeats bought one at a time is ~77s of footage for a 30s cut.\n\nFuse a run of consecutive short beats that one prompt can carry: the same\nlocation and cast, cuts the model can make inside one take. Render a beat as its\nown clip and trim it on the timeline when it needs a picture no neighbour can\nshare, a different place, or its own still. Each of those clips is footage the cut\nthrows away, so report how many clips the board will buy before the clip pass and\nget the user's go-ahead when that is more than the request implied.\n\nDirect the run as one prompt with bracketed timecodes\n(`[00:00 to 00:02.5] Event … [00:02.5 to 00:05.2] Reception`), render it on the first\nshot of the run, then tell the board which slice each sibling uses:\n\n```json\n{\"op\": \"update_shot\", \"target\": \"06\",\n \"covered_by\": {\"shot_id\": \"05\", \"start_seconds\": 2.5, \"end_seconds\": 5.184}}\n```\n\nThe covered shot then reads `has_clip: true` with `status: \"rendered\"`, is skipped by\n`render_storyboard_clips` (so it is never generated twice), and\n`assemble_storyboard_timeline` lays it down as that window of the covering clip\ninstead of skipping it, and the covering shot ends where the first covered shot takes\nover. Without `end_seconds` the covered shot runs to the end of the covering clip.\n\nOne hop only: `shot_id` must name a shot that owns its clip, not another covered shot.\nRemoving the covering shot clears the coverage and reports which shots it uncovered.\n\n### Storyboard — browser (`ui_storyboard_*`)\n\nThe board must be open as a workspace tab; its id comes from the `ui_context` system\nblock. Not open → `edit_storyboard` edits the saved board. Use `ui_open_document {type: \"storyboard\", id}` to show it to the user. Target =\nshot id, index as a string, or `\"selected\"`. **Slugs are not resolved here.**\n\n| Tool | Arguments |\n|---|---|\n| `ui_storyboard_get_state` | `storyboard_id` |\n| `ui_storyboard_set_screenplay` | `storyboard_id`, `screenplay` |\n| `ui_storyboard_set_entities` | `storyboard_id`, `entity_ids` (replaces the cast; `[]` clears it) |\n| `ui_storyboard_add_shot` | `storyboard_id`, `action`, `slug?`, `camera?`, `motion?`, `graphics?`, `production?`, `durationSeconds?`, `index?`, `afterShotId?` |\n| `ui_storyboard_update_shot` | `storyboard_id`, `target`, `action?`, `slug?`, `camera?`, `motion?`, `graphics?`, `production?`, `dialogue?`, `notes?`, `durationSeconds?`, `durationSource?`, `status?` |\n| `ui_storyboard_remove_shot` \u002F `_duplicate_shot` | `storyboard_id`, `target` |\n| `ui_storyboard_move_shot` | `storyboard_id`, `target`, `sceneId?`, `position` |\n| `ui_storyboard_set_setup` | `storyboard_id`, `brief?`, `genre?`, `stage?`, `shotCount?`, `importSource?`, `directedFrom?` |\n| `ui_storyboard_direct` | `storyboard_id`, `redirect`, `shotCount?` |\n| `ui_storyboard_update_scene` | `storyboard_id`, `sceneId`, `slugline?`, `lighting?` |\n| `ui_storyboard_create_scene` \u002F `_merge_scene` | `storyboard_id`, `afterSceneId?` \u002F `sceneId` |\n| `ui_storyboard_set_style` | `storyboard_id`, `entityId?` or `descriptor?` |\n| `ui_storyboard_select_version` \u002F `_delete_version` | `storyboard_id`, `target`, `kind`, `version` |\n| `ui_storyboard_add_keyframe_version` | `storyboard_id`, `target`, `assetId`, `flipOf?` — adds the still without selecting it |\n| `ui_storyboard_generate_keyframe` | `storyboard_id`, `target`, `staleOnly?` |\n| `ui_storyboard_generate_clip` | `storyboard_id`, `target`, `staleOnly?` |\n| `ui_storyboard_revise_shot` | `storyboard_id`, `target`, `instruction` |\n| `ui_storyboard_assemble_timeline` | `storyboard_id` |\n| `ui_storyboard_select_shot` | `storyboard_id`, `target` (nullable) |\n| `ui_storyboard_extract_script` \u002F `_relink_script` \u002F `_reproject_shots` | `storyboard_id` (+ `targets?`) |\n| `ui_storyboard_set_duration_source` | `storyboard_id`, `targets`, `source` |\n\nThe browser shot tools take **no** `narration`, `entity_ids` or `render_mode`, and\n`add_shot` takes no `dialogue`. In the browser those arrive through\n`set_screenplay`; headless, through `edit_storyboard`.\n\nGeneration is asynchronous: `generate_keyframe` \u002F `generate_clip` start the job and\nreturn the shot. Poll `ui_storyboard_get_state` for `status`.\n\nStatuses: `planned` → `keyframe_generating` → `keyframe_ready` → `clip_generating` →\n`rendered`, or `failed`. (`approved` is legacy and reads as \"still ready\"; nothing\nsets it. Do not use it as a gate.)\n\n#### `screenplay` for `set_screenplay`\n\n```json\n{\n  \"type\": \"screenplay\",\n  \"title\": \"…\",\n  \"logline\": \"…\",\n  \"brief\": \"…\",\n  \"styleBible\": \"…\",\n  \"aspectRatio\": \"9:16\",\n  \"narration\": \"…\",\n  \"musicPrompt\": \"…\",\n  \"entityIds\": [\"\u003Casset id>\"],\n  \"shots\": [\n    {\n      \"slug\": \"1a\",\n      \"action\": \"Nova touches untreated hair, front-camera close\",\n      \"camera\": { \"framing\": \"close-up\", \"lens\": \"26mm\", \"angle\": \"eye\", \"movement\": \"handheld\" },\n      \"motion\": \"she lifts one section of hair and lets it fall, once\",\n      \"dialogue\": \"I wanted lighter hair…\",\n      \"durationSeconds\": 4,\n      \"entityIds\": [\"\u003Casset id>\"]\n    }\n  ]\n}\n```\n\nIds, indexes and statuses are filled in. `style` is accepted as an alias of\n`styleBible`. Only `action` is required per shot.\n\nThe top-level `entityIds` casts those entities on the **board** — that cast is what\nseasons every shot's still and clip prompt. Use `ui_storyboard_set_entities` to\nrecast without replacing the shots; `ui_storyboard_get_state` reports the current\ncast as `entityIds`. A shot's own `entityIds` overrides the board cast for that shot\n(`[]` means \"no entities on this shot\"); without one, styles and locations apply to\nevery shot and characters and props apply to the shots whose text names them.\n\n### Entities\n\n| Tool | Arguments |\n|---|---|\n| `list_entities` | `kind?` (`character`\\|`location`\\|`style`\\|`prop`), `query?`, `limit?` |\n| `get_entity` | `entity_id` |\n| `create_entity` | `asset_id`, `kind`, `name`, `descriptor` (all required), `description?`, `voice_id?`, `tags?`, `lora?`, `palette?` |\n| `update_entity` | `entity_id` + any field, including `asset_id` to move it to a new photo |\n| `delete_entity` | `entity_id` — clears the marker, keeps the image |\n| `apply_entities` | `text`, `entity_ids?` → seasoned prompt + reference asset ids |\n\nAn entity **is** an image asset carrying a marker. Its id is the asset id. To make one\nfrom nothing: `find_model` (`text_to_image`) → `generate_image` → `create_entity` with\nthe returned asset id. To make one from a photo the user attached: find it with\n`asset_search` \u002F `list_assets`, then `create_entity`.\n\n`apply_entities` is for seasoning a prompt you are about to send yourself\n(`generate_image`, `generate_video`). The storyboard render tools season internally —\ndo not pre-season shot text with it.\n\n### Timeline\n\n`assemble_storyboard_timeline` lays rendered clips end to end, stamps each with its\nboard and shot id, and gives every shot clip an **audio twin on a \"Shot Audio\" track**\n(each surface mutes video elements and mixes audio clips only). Board narration and\nmusic become draft clips on their own tracks.\n\n**Each shot is as long as its render**, not as long as its `duration_seconds` — a shot\ndirected at 1.5s that came back at 5.184s occupies 5.184s of the cut. Shots that came\nback off their directed length are returned in `retimed_shots` and warned about, so a\ncut that runs longer than planned is visible without playing it. `duration_seconds`\nonly decides a shot whose footage has no measurable length. A board linked to a script\nis the exception: there the words decide, and `trimmed_shots` names the shots whose\nfootage does not fill the slot its lines gave it.\n\n`edit_timeline {timeline_id, ops[]}` carries the edit; `timeline-edit-ops` holds its\nfull op list. Start with `get_state` for ids.\n\nTo duck the shots' own sound under a voiceover: `set_clip_params` on the Shot Audio\nclips with `muted: true`, or `volumeDb: -18`. `set_clip_params` also takes `name`,\n`opacity`, `speedMultiplier`, `fadeInMs`, `fadeOutMs`, `blendMode`, `borderRadius`,\n`hidden`, `locked`, `textStyle`, `shapeStyle`.\n\nEvery field goes on the op itself. A `params` \u002F `props` wrapper is unwrapped, but the\nflat form is the contract:\n\n```json\n{\"op\": \"set_clip_params\", \"target\": \"clip_1\",\n \"textStyle\": {\"fontFamily\": \"Space Grotesk\", \"fontWeight\": 800}}\n```\n\n`textStyle` is **merged** over the clip's own, so send only what you are changing —\nre-sending the whole object is how the fields you did not mean to touch get\noverwritten. `fontWeight` is a number, and the CSS keywords (`bold`, `semibold`,\n`extrabold`) are accepted and stored as one.\n\n**Set a bundled family or none at all.** `sans-serif`, `serif`, `system-ui` and the\nother CSS generics are refused where the clip is authored: they name no typeface, so\nthe editor preview, the render and `preview_timeline_frame` each pick a different one.\nNodeTool ships Inter (the default), Space Grotesk, Bebas Neue, Playfair Display, Lora\nand JetBrains Mono. A named system font is still allowed and `validate_timeline`\nreports it as `font_not_portable`.\n\n`validate_timeline {timeline_id | document, fps?}` after every edit pass. It catches\noverlaps, fades longer than their clip, unknown presets and incomplete bindings.\n\nOther timeline tools: `list_timelines`, `create_timeline`, `get_timeline`,\n`delete_timeline`, and the version family (`list_`\u002F`get_`\u002F`create_`\u002F`restore_`\u002F\n`delete_timeline_version`). Browser twins are `ui_timeline_*`.\n\n### Script\n\nUse a script when the words drive the cut. `extract_script_from_storyboard` projects a\nboard's dialogue and narration into a script and links the two: each shot keeps the\nline ids it covers, and from then on the script owns the words. `derive_storyboard_from_script`\ngoes the other way, one shot per line, optionally with a director pass over the scaffold.\n\n`voice_script_lines` synthesizes each line with its cast voice; `assemble_script_timeline`\nlays the takes end to end.\n\n**Give the cast their voices first, then voice with no override.** A line takes its\nvoice from its speaker: `add_line` without `speaker` leaves it with none, and\n`extract_script_from_storyboard` creates the Narrator with no voice and each\ncharacter with at most its entity's `voice_id` and no provider or model. Either way\nthe line reads `no_voice` until its speaker is bound. A voice is the\ntriple `{provider, model, voice}` where `voice` is the voice's own name (`Aoede`,\n`Charon`, `alloy`) — a provider and a model alone do not pick one, so\n`voice_script_lines {provider, model}` is refused. Set each speaker once:\n\n```json\n{\"op\": \"set_speaker_voice\", \"target\": \"MOM\",\n \"provider\": \"gemini\", \"model\": \"gemini-2.5-flash-preview-tts\", \"voice\": \"Aoede\"}\n```\n\nThe three keys sit on the op, though a `voice: {provider, model, voice_id}` object —\nthe shape `get_script` reports a voice in — is flattened onto it. Then call\n`voice_script_lines {script_id}` with no override and every speaker resolves its own. On a linked board, `assemble_storyboard_timeline` cuts words\nand picture together: each shot runs as long as the takes it covers and every voiced\nline gets its own voiceover clip.\n\nOthers: `list_scripts`, `get_script` (line status: `draft`, `stale`, `voiced`,\n`no_voice`), `create_script`, `edit_script`, `delete_script`. Browser twins are\n`ui_script_*`.\n\n#### Writing the lines\n\n`create_script` makes an empty one. `edit_script {script_id, ops[]}` ops:\n`set_setup` (brief, format, length, pace, language, stage), `add_speaker`,\n`set_speaker`, `set_speaker_voice`, `add_section`, `add_line`, `set_line_text`,\n`set_line_speaker`, `remove_line`, `remove_speaker`. Call `get_script` first for\nline and speaker ids.\n\n`write_script {script_id, rewrite?, imported_text?}` drafts the lines from the\nsetup and saves the cast and lines it produces, replacing what was there. Set\nthe brief with `set_setup` first. `rewrite: true` keeps the ids of the lines it\nkeeps, so their takes and storyboard links survive. Words passed as\n`imported_text` are only split into lines and attributed to speakers, never\nreworded. It records no take: voice the result with `voice_script_lines`.\n\nRewriting a line leaves its takes in place as **stale**, so a following\n`voice_script_lines` re-records exactly those and nothing else.\n\n### Models\n\n`find_model {capability, query?, task?, provider_hint?, model_hint?, prefer_local?,\nlimit?}` is the only way to name a model. **`capability` is required** and is one of\n`text_to_image`, `image_to_image`, `segment_image`, `text_to_video`, `image_to_video`,\n`reference_to_video`, `text_to_speech`, `text_to_music`, `audio_to_audio`,\n`automatic_speech_recognition`, `generate_embedding`, `generate_message`. `query` is the search box (`\"flux schnell\"`); `task` is a hint\nmatched against a model's supported tasks, not a search.\n\nNodeTool ships curated ids under the `nodetool` provider, which are the sane defaults\nwhen the user has no preference:\n\n| Id | Use |\n|---|---|\n| `nodetool\u002Fflux-schnell` | cheapest stills, text prompts only |\n| `nodetool\u002Fnano-banana` | sharper stills, takes reference images |\n| `nodetool\u002Fseedream` | most detail, slowest |\n| `nodetool\u002Fhailuo-fast` | cheapest clips, for blocking out a cut |\n| `nodetool\u002Fkling-turbo` | steadier motion, mid price |\n| `nodetool\u002Fkling-standard` | most faithful motion |\n| `nodetool\u002Fkokoro` | eight TTS voices |\n\n### Media, outside the board\n\n`generate_image {provider, model, prompt, negative_prompt?, width?, height?, quality?,\noutput_file?}`, plus `edit_image`, `generate_video`, `animate_image`, `generate_speech`,\n`generate_music` and `transcribe_audio` — each takes a `find_model` provider+model and\nsaves an `asset:\u002F\u002F` result. `model` also accepts a whole `find_model` hit or its `.ref`,\nin which case `provider` may be omitted.\n\n`understand_video {provider, model, video, prompt?, max_tokens?}` reads a whole video\nwith a multimodal model (Gemini reads video natively); use it to break down a reference\ncut. `video` takes an asset id, an `asset:\u002F\u002F` URI, a URL or a data URI. `view_image`\nputs pixels in your own context; `read_media_bytes` returns the bytes.\n\n### The Director node\n\n`nodetool.creative.Director` is a **workflow node**, not a chat surface. It turns a\nbrief into a `Screenplay` (props: `model`, `brief`, `style`, `shot_count`, `aspect_ratio`,\n`max_tokens`; outputs\n`screenplay`, `narration`, `music_prompt`, `title`). Reach for it only inside a\nreusable graph. In chat, `direct_storyboard` runs the same Director over a saved\nboard, or write the shots yourself with `edit_storyboard`.\n\n### Still-motion-graphics boards\n\nA board whose shots carry `production.media_strategy: \"still_motion_graphics\"` renders\nno clips: its stills and `graphics` elements become timeline layers.\n`preview_storyboard_design {storyboardId, expectedStoryboardRevision}` reads the design\nas a timeline preview with no save. `layout_storyboard` places every layer at each\nshot's hold frame with a vision model. `finish_storyboard` writes the editable\ntimeline: `strategy: \"deterministic\"` (default, no provider) returns an unreviewed\nscaffold, `\"agentic\"` composes the motion and reviews rendered frames. All three\nneed the board's current `revision` from `get_storyboard`.\n\n## Standing orders\n\nUse this optional template only when the user wants a staged review with approval\nbetween the board, stills, clips, and cut. Its checkpoints express that user's\nchosen workflow. They do not apply to other requests or override authorization\nalready given to finish a piece.\n\nRespect the thread's existing permission mode. Plan mode blocks writes. Do not\nswitch modes or use another tool family to evade a denial. The user can adapt the\nbrief to authorize the desired stages and set a budget.\n\n```\nYou are directing on the storyboard surface, then finishing in the timeline.\nDo not build a node graph unless I ask for a reusable template.\n\nSURFACES\nHeadless: create_storyboard, get_storyboard, edit_storyboard,\nrender_storyboard_stills, render_storyboard_clips, revise_storyboard_clip,\nassemble_storyboard_timeline, extract_script_from_storyboard.\nBrowser (only for a board open as a tab): ui_storyboard_get_state,\nui_storyboard_set_screenplay, ui_storyboard_generate_keyframe,\nui_storyboard_generate_clip, ui_storyboard_revise_shot,\nui_storyboard_assemble_timeline. Use ui_open_document to open a board.\nThe ui_ generate and revise calls spend like the headless renders: same\napproval rules.\n\nLOOP\n1. list_storyboards, or read ui_context. No board -> create_storyboard.\n2. Cast before anything renders. list_entities first. A new entity needs an\n   image asset: generate_image (or my attachment), then create_entity with\n   {asset_id, kind, name, descriptor}. There is no create-from-text.\n   Each entity: one name, one kind, one canonical descriptor sentence.\n3. edit_storyboard set_board {entity_ids, image_model, video_model,\n   brief, style, aspect_ratio, narration, music_prompt}. Models come from find_model — there is no\n   default and an unset model fails the render.\n4. Direct with edit_storyboard add_shot, one op per shot. Give every shot a\n   slug (1a, 2a, ...). Fields: action, slug, camera {framing, lens, angle,\n   movement}, motion, dialogue, narration, duration_seconds, render_mode.\n5. STOP after the board. Report shot count and the two model ids. Do not\n   estimate dollars — no tool prices a render. Wait for \"stills\".\n6. render_storyboard_stills. I pick takes in the board's takes gallery, or\n   tell you which one; you apply it with edit_storyboard select_version.\n   Wait for \"clips\".\n7. render_storyboard_clips. revise_storyboard_clip touches one shot only.\n8. On \"cut\": assemble_storyboard_timeline, then validate_timeline.\n\nWRITING THE SHOTS\nThe still prompt is action, camera framing, angle and lens, the scene\nlighting and the board style. A keyframe clip prompt is motion, action,\ncamera movement and equipment; a direct clip gets all of these. Write camera\ndirection into the camera object once, not into action as well.\nName entities in plain text — \"Nova reaches for the bottle\", never \"@Nova\".\nEntities season a shot when their name appears in its action, motion, dialogue,\nnarration or slug; styles and locations season every shot. A shot's entity_ids,\nif set, overrides that entirely.\n\nLOCKS\n- The descriptor is the face. Do not re-describe an entity in shot text.\n- Product geometry, label, cap and colour come from the product entity. No new\n  logos.\n- A state change (wet, stained, new outfit) is a second entity, not a morph\n  instruction inside one prompt.\n- Slugs stay stable. \"Fix 3a\" edits 3a and renders 3a.\n- UGC: handheld phone, grain, natural audio, no score, no beauty filter.\n  Hero: locked grade in the style, smooth camera, score allowed.\n- render_mode \"keyframe\" (default) for anything where the look must hold;\n  \"direct\" for heavy motion or a native-audio video model.\n\nMEMORY\nmemory_save the style, the cast and the grade, with the entity and board ids in\n`resources` — that survives into later threads. share_result\u002Fread_shared are\nrun-scoped and get discarded; do not use them to lock a look.\n\nIf the shot count looks expensive, propose a collapse before rendering clips.\n```\n",{"name":5,"featured":47,"description":7},true,"main","c7226baa82daca42a19a5855c116544f97aa8bac","packages\u002Fsystem-skills\u002Fstoryboard-core",91,"https:\u002F\u002Fgithub.com\u002Fnodetool-ai\u002Fnodetool","https:\u002F\u002Fnodetool.ai\u002F","https:\u002F\u002Fgithub.com\u002Fnodetool-ai","No-code AI development","2026-11-15 03:27:49",{"source":8,"skillName":5,"commands":58,"prompt":68,"zipAvailable":47},[59,62,65],{"tool":60,"command":61},"npx","npx skills add nodetool-ai\u002Fnodetool --skill storyboard-core",{"tool":63,"command":64},"bunx","bunx skills add nodetool-ai\u002Fnodetool --skill storyboard-core",{"tool":66,"command":67},"pnpm","pnpm dlx skills add nodetool-ai\u002Fnodetool --skill storyboard-core","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fnodetool-ai\u002Fnodetool\u002Fblob\u002Fmain\u002Fpackages\u002Fsystem-skills\u002Fstoryboard-core\u002FSKILL.md",[70],{"path":71,"resourceType":72,"resourceTypeDesc":73,"sizeBytes":74,"sourceHtmlUrl":75},"prompt.md","REFERENCE","参考文档",13862,"https:\u002F\u002Fgithub.com\u002Fshenxingy\u002FClade\u002Fblob\u002Fmain\u002Fconfigs\u002Fskills\u002Fads-google\u002Fprompt.md",[77,86,119,146,160,176],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":81,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":85},"01M742MX3Y2ZYK884ZXTRFKB9P","humanizer","Rewrite AI-sounding text so it reads like the writer without changing what it says.\nUse when editing or reviewing prose for AI tells: not-X-but-Y contrasts, one-line\nclosers, staged openers, forced triads, dashes everywhere, inflated claims, sales\nlanguage, stock AI words, bold labels, or filler.","MIT","https:\u002F\u002Fgithub.com\u002Fnodetool-ai\u002Fnodetool\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fhumanizer\u002FSKILL.md",[],[],"2026-11-11 15:11:14",{"skillNo":87,"name":37,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":99,"publishedAt":42},"01M6BY4D93R0Q9400ZHJ04DXP1","Use the NodeTool MCP server to build, validate, run, and debug visual AI workflows, and to work with assets, collections, and jobs. Use when the user mentions NodeTool or asks for a workflow graph, a node, or a media generation run on their NodeTool server.","https:\u002F\u002Fgithub.com\u002Fnodetool-ai\u002Fnodetool\u002Fblob\u002Fmain\u002Fplugins\u002Fchatgpt\u002Fnodetool\u002Fskills\u002Fnodetool\u002FSKILL.md",[91,94],{"categoryNo":92,"categoryName":93,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":95,"categoryName":96,"taxonomyType":97,"taxonomyTypeDesc":98},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[37,100,101,102,103,104,105,106,107,36,108,27,109,110,111,112,113,114,115,116,117,118],"MCP","Media","workflows","when","generation","media generation","with","visual","collections","node","work","debug","graph","validate","assets","run","server","mcp server","workflow",{"skillNo":120,"name":121,"nameZh":6,"description":122,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":123,"categories":124,"keywords":126,"publishedAt":42},"01M6BY4AEB05ZPBRVD078ATR2H","wan-2-6-prompting","Prompt Alibaba's Wan 2.6 video — text-to-video with a global style line plus timing-bracketed shots, and image-to-video that describes only what changes over time. Covers the shot-mode switch per provider, the prompt budget, negative prompts, motion intensity wording, audio input and prompt expansion. Use whenever the model id names a Wan 2.6 video route (alibaba\u002Fwan-2.6\u002Ftext-to-video, alibaba\u002Fwan-2.6\u002Fimage-to-video, wan-video\u002Fwan-2.6-t2v, wan-video\u002Fwan-2.6-i2v, wan-video\u002Fwan2.6-i2v-flash) on generate_video, animate_image or a TextToVideo node. Not for Wan 2.5 or 2.7, or the Wan 2.6 image routes.","https:\u002F\u002Fgithub.com\u002Fnodetool-ai\u002Fnodetool\u002Fblob\u002Fmain\u002Fpackages\u002Fsystem-skills\u002Fwan-2-6-prompting\u002FSKILL.md",[125],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[127,128,129,130,131,132,133,109,134,135,136,137,138,139,140,141,142,143,144,145,38],"prompting","wan 2 6 prompting","line","expansion","input","image-to-video","text-to-video","route","only","mode","time","flash","Budget","generate","text","image","animate","model","Audio",{"skillNo":147,"name":148,"nameZh":6,"description":149,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":150,"categories":151,"keywords":154,"publishedAt":42},"01M6BY47T4748ZG5ZMTAR97ZWZ","video-workflow","Build a reusable NodeTool video workflow for batches or repeated inputs. For a single finished piece, use a storyboard skill.","https:\u002F\u002Fgithub.com\u002Fnodetool-ai\u002Fnodetool\u002Fblob\u002Fmain\u002Fpackages\u002Fsystem-skills\u002Fvideo-workflow\u002FSKILL.md",[152,153],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":92,"categoryName":93,"taxonomyType":21,"taxonomyTypeDesc":22},[118,155,38,156,26,157,158,36,159,37,27],"video workflow","reusable","build","batches","single",{"skillNo":161,"name":162,"nameZh":6,"description":163,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":164,"categories":165,"keywords":167,"publishedAt":42},"01M6BY4587N2SYN315SXGEMZC3","video-clone","Analyze a reference video and recreate its shot structure with a new product or cast in NodeTool.","https:\u002F\u002Fgithub.com\u002Fnodetool-ai\u002Fnodetool\u002Fblob\u002Fmain\u002Fpackages\u002Fsystem-skills\u002Fvideo-clone\u002FSKILL.md",[166],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[168,169,38,106,170,171,37,172,173,174,175],"clone","video clone","cast","new","analyze","product","structure","reference",{"skillNo":177,"name":178,"nameZh":6,"description":179,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":180,"categories":181,"keywords":183,"publishedAt":42},"01M6BY4257C2KQYYMD9EK6DK8E","video-audio-continuity","Keep sound continuous across a multi-scene piece cut from generated video — why one clip per scene hard-cuts the audio at every boundary, when to write all the scenes into a single generation instead, the sound-design vocabulary that survives a provider's copyright filter, and how to check the length, the aspect ratio and the mix of what came back. Use when a piece has more than one scene and the video model writes its own audio (Seedance 2, Veo 3, MiniMax H3, Kling 2.6 and later), or when a cut's sound drops out at the shot changes.","https:\u002F\u002Fgithub.com\u002Fnodetool-ai\u002Fnodetool\u002Fblob\u002Fmain\u002Fpackages\u002Fsystem-skills\u002Fvideo-audio-continuity\u002FSKILL.md",[182],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[184,38,145,185,186,187,188,189,190,191,192,193,194,103,195,196,144,197,198,199,200],"video audio continuity","continuity","write","why","back","veo 3","at","cut","later","across","filter","generated","how to","mix","design","boundary","how"]