@nodetool-ai/agents 0.8.4-a24.2 → 0.8.4

package/dist/_skills/storyboard-core/SKILL.md

@@ -0,0 +1,716 @@
+---
+name: storyboard-core
+description: "Use NodeTool storyboard, entity-casting, rendering, and timeline-assembly tools for video production or debugging their contracts."
+featured: true
+---
+
+The shared half of every NodeTool video job. The use-case skills carry the style,
+the shot pattern and the briefs; this carries the machinery they all assume.
+
+Direct 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
+described in `video-workflow`.
+
+Read the relevant part of **Tool contract** below before the first call in
+that tool family. Use the live tool schema when it differs
+from an example. Load other sections only when the task reaches them.
+
+## Pick the use-case skill
+
+| Job | Skill |
+|---|---|
+| Phone-shot video with a person: UGC ad, testimonial, comedy, day-in-the-life, vlog | `/ugc-video` |
+| Product film: pack shot, hero, brand spot, with or without talent | `/product-commercial` |
+| Sound-off motion-graphics ad from real screenshots and product photos, no generated footage | `/motion-ad` |
+| Rebuild an existing ad or clip you were given | `/video-clone` |
+| Voiceover drives the picture: explainer, faceless video, narrated piece | `/script-video` |
+| Narrative with dialogue, score and a title: short film, trailer, scene | `/short-film` |
+| A campaign, not one video: entity sheets, still set, several cuts | `/launch-kit` |
+| A template to re-run on new inputs | `/video-workflow` |
+| Footage already exists and needs repair: cutout, upscale, outpaint, lip sync, generated sound | `/nodetool-video-post` |
+| A screen someone clicks, over the workflows behind a piece | `/nodetool-app-builder` |
+
+If none fits, run the loop below directly.
+
+Those skills say what the picture looks like. A second set says where the beats
+go, and the two compose: load the job skill for the look and the structure
+skill for the spine.
+
+| The structure question | Skill |
+|---|---|
+| Ad beats: hook, escalation, timecodes, VO discipline | `/commercial-beat-sheet` |
+| A product page URL in, a finished cut and its cost out | `/launch-commercial` |
+| A 30–120s explanation with a claim per beat | `/explainer-storyboard` |
+| A treatment cut to a track's sections | `/music-video-treatment` |
+| Eight audio-first beats, the drop at ~65%, a title card | `/trailer-template` |
+
+These own their own briefs and beat budgets. The storyboard, entity and render
+call shapes live once, in **Tool contract** below. Every job and structure skill
+points here for them.
+
+## Two tool families, one board
+
+| | Headless | Browser |
+|---|---|---|
+| 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**) |
+| Needs | nothing open | the board open as a tab, listed in the `ui_context` system block |
+| Shot target | id, 0-based index, or **slug** | id, 0-based index, or `"selected"` — **no slug** |
+| Permission gate | yes | no (client tools bypass it) |
+
+Every board tool in both families names its board explicitly (`storyboard_id`, or
+`storyboardId` on the still-motion-graphics tools). There is no "act on whatever is
+open" fallback.
+
+Prefer headless. Reach for `ui_storyboard_*` when the user is watching the board fill
+in, or when you need `set_screenplay` for `title`, `logline` or `style_bible`.
+Headless `edit_storyboard` → `set_board` writes screenplay-level `narration`,
+`music_prompt` and `motion_design` while preserving the other screenplay fields.
+Bridge the two with `ui_open_document {type: "storyboard", id}`.
+
+`ui_storyboard_generate_keyframe`, `ui_storyboard_generate_clip` and
+`ui_storyboard_revise_shot` spend exactly what the headless renders spend, and no
+permission prompt stands in front of them. Call them only inside a render the
+user has already authorized.
+
+## The loop
+
+1. **Find the board.** `list_storyboards`, or read `ui_context`. No board yet →
+   `create_storyboard {name, brief, style, aspect_ratio}`.
+2. **Cast the entities.** `list_entities` first. A new one needs an image asset —
+   `generate_image` or the user's upload — then
+   `create_entity {asset_id, kind, name, descriptor}`. **There is no create-from-text.**
+3. **Attach the cast to the board:** `edit_storyboard` → `{op: "set_board", entity_ids: [...]}`,
+   or `ui_storyboard_set_entities {storyboard_id, entity_ids}` on an open board.
+   Name matching only searches the board cast, so an entity cast nowhere seasons
+   nothing, no matter what the shots say. An id in a shot's own `entity_ids` is
+   added to the board cast when the board is read.
+4. **Pin the models.** `find_model` with `capability` `text_to_image`, then
+   `image_to_video` or `text_to_video`; write both through
+   `{op: "set_board", image_model, video_model}`. There is no default — an unset
+   model fails the render rather than spending on a model nobody chose.
+5. **Direct.** One `{op: "add_shot", ...}` per shot. Report the shot count and
+   selected models. Continue to the stages authorized by the request. A board-only
+   request ends here. Honor any checkpoint the user requested.
+6. **Stills.** `render_storyboard_stills {storyboard_id}` — omit `targets` for every
+   shot that still needs one. Cap 24 shots per call.
+7. **Take selection, when requested.** Every render keeps the old still in
+   `keyframe_versions` and the old clip in `clip_versions`, and makes the new one
+   selected. `edit_storyboard` → `{op: "select_version", target, kind: "keyframe"|"clip",
+   version}` selects another (0-based, oldest first). Pause if the user reserved
+   the pick for themselves in the takes gallery.
+8. **Clips.** `render_storyboard_clips {storyboard_id}` within the requested
+   generation scope and budget. Reuse prior authorization instead of asking again.
+9. **Revise one shot:** `revise_storyboard_clip {target, instruction}`. Needs an
+   existing clip; it is video-to-video and touches no other shot.
+10. **Cut.** `assemble_storyboard_timeline`, then `validate_timeline`. Re-running
+    rebuilds the same sequence in place and keeps tracks the board does not own.
+11. **Finish** with `edit_timeline` ops (**Tool contract** § Timeline, below).
+    Load `timeline-edit-ops` with `load_skill` for the full op list, the presets
+    and the preview contract, and `motion-graphics` for the build loop. A repair
+    on a delivered clip belongs to `nodetool-video-post`.
+
+**Stills-only mode.** When the user wants a board and frames but no motion — a spec
+ad, a pitch, a look test — run steps 1 to 7 and stop. Adding the motion later is
+`update_shot` on `motion` alone: action, wardrobe, set and cast stay put, so the
+approved stills still describe the finished piece.
+
+## What actually reaches the model
+
+The prompt is assembled from named fields, comma-joined, not from the whole shot:
+
+| Field | Still | Clip, `keyframe` mode | Clip, `direct` or `reference` mode |
+|---|---|---|---|
+| `action` | yes | yes | yes |
+| `camera.framing` | `"<framing> shot"` | — | `"<framing> shot"` |
+| `camera.angle` | yes | — | yes |
+| `camera.lens` | `"<lens> lens"` | — | `"<lens> lens"` |
+| the shot's scene `lighting` | yes | — | yes |
+| `motion` | — | yes (first) | yes |
+| `camera.movement`, `camera.equipment` | — | yes | yes |
+| board `style` | yes | — | yes |
+
+A keyframe-mode clip animates a still that already carries framing, lens,
+lighting and style, so the clip prompt leaves them out. Write camera direction
+into the `camera` object, not into `action` as well. `dialogue`, `notes`,
+`duration_seconds`, `end_state`, `sound` and `graphics` never enter a per-shot
+prompt (`end_state` and `sound` feed the one-take prompt only).
+
+**Entities season by plain name.** A shot with `entity_ids` uses exactly those.
+Otherwise: every style and location entity applies to every shot, and a character or
+prop applies when its **name appears** in the shot's `action`, `motion`, `dialogue`,
+`narration` or `slug`. Write `Nova reaches for the bottle`, not `@Nova reaches...`.
+`@` is a chat-composer affordance that emits an `entity://<id>` token into *your
+message*; it never becomes shot text.
+
+## Locks
+
+- Keep one `descriptor` per entity and let it do the work. Do not re-describe a face
+  in shot text.
+- A state change (wet hair, a stained shirt, a second outfit) is a **second entity**,
+  not an instruction inside one prompt.
+- Product geometry, label and colour come from the product entity's descriptor and
+  reference image. Never invent a logo.
+- Give every shot a stable `slug` (`1a`, `2a`, …) at `add_shot` time. Headless targets
+  accept it, and "fix 3a" then means one shot.
+- Render mode is per shot. `keyframe` (default) is cheaper to iterate and holds a look
+  steady. `direct` skips the still — worth it for heavy motion, where first-frame
+  conditioning stiffens the result, and for native-audio video models, which are
+  weakest on their image path.
+- A native-audio model writes the sound per clip, so a board of one clip per shot
+  cuts the audio at every join. Before rendering, load the `video-audio-continuity`
+  system skill through `load_skill`: either the whole piece is one shot
+  carrying the cuts, or the
+  continuity comes from a narration or music track and the shot audio is muted.
+  A silent cut is also valid when sound is not requested. Reuse existing audio
+  or keep the cut silent when extra generation would exceed the authorized scope.
+
+## Where the models will not do what the cut wants
+
+Four constraints that are not bugs and have no tool to fix them. Each has a working
+shape.
+
+**A video model returns the lengths it offers.** The render sends
+`duration_seconds`, and the model snaps it to its own steps — a shot directed at
+1.5s comes back at 5.184s on a model whose shortest clip is that long. For a run of
+beats shorter than the model's shortest clip, render one generation with bracketed
+timecodes in the prompt and record the split with `covered_by`. **Tool contract**
+§ Fusing shots, below, has the call and the rule for when to fuse and when to
+render each beat long and trim.
+
+**Moderation reads the words, not the story.** A prompt naming institutional force —
+police grabbing someone, a raid, restraint — trips a safety filter that a shot of the
+same threat does not. Reframe with non-trigger vocabulary and keep the stakes:
+"two uniformed city officials approaching with a clipboard and caution tape" passes
+where "two aggressive police officers grabbing her arms" does not. Reframe once; do
+not retry the rejected prompt.
+
+**A music model cannot leave a hole.** Ask for 1.5s of silence at 00:19.5 and the
+decoder fills it with reverb tail and room tone — there is no envelope gate in the
+prompt. Cut the silence on the timeline instead: generate the score in two parts,
+lay them as two clips with the gap between them, and fade the first out (~300ms) and
+the second in (~100ms) so the edges are not clicks.
+
+**Speech does not fit a 1.5s shot.** An expressive take of a line runs 4s, and
+compressing it to the picture beat makes it sound processed. Let the words cross the
+cut: keep the voiceover clip on its own track and start it under the previous shot
+(J-cut) or run it past the cut into the next (L-cut). The picture cuts on the beat;
+the line finishes where it finishes. On a script-linked board that is automatic —
+each shot runs as long as the lines it covers — so use this on an unlinked board or
+where the picture has to stay on the beat.
+
+## Gating and spend
+
+Permission mode decides what runs without asking. `read` tools always run.
+
+| Mode | write / execute / external |
+|---|---|
+| `auto` | runs |
+| `default` | asks the user |
+| `plan` | **blocked** |
+
+`plan` blocks `create_storyboard` and `edit_storyboard` too, so the board cannot be
+written in it. Respect the active permission mode and tool approval responses. For a board-only
+request, write the board and omit render calls. Do not switch modes or use browser
+tools to evade a denied headless action. A tool being callable does not authorize
+spend beyond the user's request.
+
+**You cannot price a render.** No tool estimates it, and `Shot.cost_estimate` is not
+populated. Report the shot count, the clip count and the models without inventing a
+dollar estimate, and confirm that scope with the user before fanning out a clip
+pass the request did not already size. If a user
+budget cannot be checked before spending, resolve that constraint first. Report
+actual spend afterwards with `get_cost_summary`. If authorization is missing,
+prepare the board and explain the specific render action that needs approval.
+
+## Memory
+
+`memory_save` is durable across every conversation — use it for the style bible, the
+cast and the grade, with the entity and board ids in `resources`. `share_result` /
+`read_shared` are **run-scoped and discarded**; they are for passing values inside one
+turn, not for locking a look across sessions.
+
+## Follow-ups this loop already handles
+
+```
+Fix 3a only. Leave the rest.
+Drop the contre-jour across the whole board — soft even daylight. Update the
+  board style, do not rewrite the shots.
+New still on 2a. Keep the old take.
+revise_storyboard_clip 5a: darker, add rain, same blocking.
+Add a reaction shot after 3a and re-slug from there. Do not re-render 1a-3a.
+Collapse 8, 9 and 10 into one 8s shot, keeping the lean-in as the last second.
+The face drifted on 4a. Select still take 2, then regenerate the clip.
+The label is unreadable on 2a. New macro still, then a clip from it.
+Cut it. Assemble, validate, narration on its own track, mute Shot Audio on 1-6.
+```
+
+## What is below
+
+- **Tool contract** — every tool, its arguments, and the fields it refuses.
+- **Standing orders** — an optional brief for users who explicitly want
+  approval between stages. Its sample checkpoints do not add requirements to
+  a different request.
+
+## Tool contract
+
+The one copy of the storyboard contract; the job and structure skills point
+here. Exact arguments. Every field named here is checked in the implementation;
+an unrecognized field is **refused with an error**, not dropped.
+
+### Storyboard — headless
+
+Work with no editor open. Shot `target` = shot id, 0-based index as a string, or slug.
+
+| Tool | Arguments |
+|---|---|
+| `list_storyboards` | `limit?` → id, name, shots, with_keyframe, with_clip, timeline_id, updated_at |
+| `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 |
+| `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/index/slug/action/camera/motion/duration/status/has_keyframe/has_clip/covered_by |
+| `edit_storyboard` | `storyboard_id`, `ops[]` — see below, `expected_revision?` (refused if the board changed since that revision) |
+| `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 |
+| `render_storyboard_stills` | `storyboard_id`, `targets?`, `provider?`, `model?`, `style?`, `stale_only?`, `concurrency?` |
+| `render_storyboard_clips` | `storyboard_id`, `targets?`, `provider?`, `model?`, `resolution?`, `mode?` (`keyframe`\|`direct`\|`reference`), `stale_only?`, `concurrency?` |
+| `revise_storyboard_clip` | `storyboard_id`, `target`, `instruction`, `provider?`, `model?` |
+| `assemble_storyboard_timeline` | `storyboard_id`, `name?`, `fps?` (default 30) |
+| `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 |
+| `extract_script_from_storyboard` | `storyboard_id`, `name?`, `relink?` |
+| `delete_storyboard` | `storyboard_id` |
+| `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 |
+| `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?` |
+
+Render limits: **24 shots per call**, `concurrency` default 3, max 8.
+
+Omitting `targets` selects every shot that still needs that step. For stills that is
+every shot with no keyframe that is not set to render directly; for clips, every shot
+with no picture — its own or one it is covered by (§ Fusing shots). A `keyframe`-mode
+shot that reaches `render_storyboard_clips` with no
+still is reported in the results, not rendered — render its still first, or set its
+`render_mode` to `direct`. Each render appends to `keyframe_versions` /
+`clip_versions` and makes the new one selected.
+
+#### `edit_storyboard` ops
+
+Fifteen ops, applied in order, at most 60 per call:
+
+| Op | Arguments |
+|---|---|
+| `add_shot` | shot fields below; `action` required; `index?` or `after_shot_id?` (inserts after that shot, in its scene) |
+| `update_shot` | `target` + any shot fields |
+| `remove_shot` | `target` |
+| `reorder_shot` | `target`, `index` (board position) |
+| `move_shot` | `target`, `scene_id?`, `position` (0-based inside the target scene) — how a shot changes scene |
+| `duplicate_shot` | `target` — the copy lands right after it, without script links or coverage |
+| `set_board` | board fields below |
+| `set_setup` | `brief?`, `genre?`, `stage?` (the guided-setup answers `direct_storyboard` reads) |
+| `update_scene` | `scene_id`, `slugline?`, `lighting?` |
+| `create_scene` | `after_scene_id?`, `slugline?` — opens holding one blank shot |
+| `merge_scene` | `scene_id` — folds it into the scene before it |
+| `set_style` | `entity_id` (a style entity becomes the board preset and its descriptor the board style) or `style` (the descriptor alone) |
+| `select_version` | `target`, `kind` (`keyframe`\|`clip`), `version` (0-based, oldest first) — nothing re-renders |
+| `delete_version` | `target`, `kind`, `version` — the asset stays in the library |
+| `add_keyframe_version` | `target`, `asset_id`, `flip_of?` — attaches a stored image as a new still and selects it |
+
+`set_entities` is accepted as an alias of `set_board`, and a few other near-miss
+names resolve the same way; an unknown op is refused.
+
+Shot fields (add and update both): `action`, `slug`, `camera`, `motion`, `end_state`,
+`sound`, `graphics`, `production`, `dialogue`, `narration`, `notes`, `duration_seconds`,
+`duration_source` (`audio`\|`manual`), `render_mode` (`keyframe`\|`direct`\|`reference`),
+`entity_ids`, `location_id`, `covered_by`, `scene_id`.
+`graphics` is semantic design intent (`mode`, `direction`, exact text/assets in `elements`), not Timeline keyframes; pass `null` on `update_shot` to clear it.
+`production` holds the shot's production requirements (`media_strategy`,
+`protected_inputs`, …). A selection holding a shot with an asset in
+`protected_inputs` makes `render_storyboard_stills` return an error, and one holding
+a `media_strategy: "still_motion_graphics"` shot does the same to
+`render_storyboard_clips`.
+`end_state` (the picture the shot ends on) and `sound` (what is heard) are one-take
+cues; `update_storyboard_one_take` sets them too.
+
+`camera` is `{framing?, lens?, angle?, movement?, equipment?}`.
+
+`covered_by` is `{shot_id, start_seconds?, end_seconds?}` — this shot's picture is a
+window into another shot's clip. See § Fusing shots below. `null` undoes it.
+
+Board fields (`set_board` only): `brief`, `style`, `aspect_ratio`, `entity_ids`,
+`image_model`, `video_model`, `narration`, `music_prompt`, `motion_design`. Any other
+key is refused with an error naming this set. The two model fields
+take a model **object** from `find_model` (its `.ref`), or null, and become the
+defaults for both render tools. `narration` and `music_prompt` take strings and
+update the screenplay; an empty string clears one. `motion_design` is
+`{direction?, transitions?: [{from_shot_id, to_shot_id, direction?}], continuities?:
+[{id, shot_ids, direction}]}`, or null to clear it.
+
+**An edit cannot set `keyframe`, `clip` or `status`.** Those belong to the render
+tools; passing them raises an error naming the right tool. `covered_by` is the one
+exception: coverage is a picture that arrived without a render, so setting it marks
+the shot `rendered` and clearing it puts the shot back to `keyframe_ready`/`planned`.
+
+**An edit cannot set `title`, `logline` or `style_bible` at the board level.**
+Use `ui_storyboard_set_screenplay` for those fields. Per-shot `narration` remains
+a shot field. Board narration and music are separate screenplay fields:
+`assemble_storyboard_timeline` turns the music prompt into a draft music clip on
+every board, and the board narration into a draft narration clip on a board with
+no linked script (a linked board voices its script lines instead).
+
+#### Fusing shots
+
+A video model snaps the requested length to the ones it offers — 5.184s, 6s, 8s —
+so a beat shorter than its shortest clip still buys the whole clip. A cut whose
+beats run 1.5-2.5s is therefore cheaper to render as one generation covering a run
+of shots and split afterwards, than as one generation per shot: fifteen 1.5-2.5s
+beats bought one at a time is ~77s of footage for a 30s cut.
+
+Fuse a run of consecutive short beats that one prompt can carry: the same
+location and cast, cuts the model can make inside one take. Render a beat as its
+own clip and trim it on the timeline when it needs a picture no neighbour can
+share, a different place, or its own still. Each of those clips is footage the cut
+throws away, so report how many clips the board will buy before the clip pass and
+get the user's go-ahead when that is more than the request implied.
+
+Direct the run as one prompt with bracketed timecodes
+(`[00:00 to 00:02.5] Event … [00:02.5 to 00:05.2] Reception`), render it on the first
+shot of the run, then tell the board which slice each sibling uses:
+
+```json
+{"op": "update_shot", "target": "06",
+ "covered_by": {"shot_id": "05", "start_seconds": 2.5, "end_seconds": 5.184}}
+```
+
+The covered shot then reads `has_clip: true` with `status: "rendered"`, is skipped by
+`render_storyboard_clips` (so it is never generated twice), and
+`assemble_storyboard_timeline` lays it down as that window of the covering clip
+instead of skipping it, and the covering shot ends where the first covered shot takes
+over. Without `end_seconds` the covered shot runs to the end of the covering clip.
+
+One hop only: `shot_id` must name a shot that owns its clip, not another covered shot.
+Removing the covering shot clears the coverage and reports which shots it uncovered.
+
+### Storyboard — browser (`ui_storyboard_*`)
+
+The board must be open as a workspace tab; its id comes from the `ui_context` system
+block. Not open → `edit_storyboard` edits the saved board. Use `ui_open_document {type: "storyboard", id}` to show it to the user. Target =
+shot id, index as a string, or `"selected"`. **Slugs are not resolved here.**
+
+| Tool | Arguments |
+|---|---|
+| `ui_storyboard_get_state` | `storyboard_id` |
+| `ui_storyboard_set_screenplay` | `storyboard_id`, `screenplay` |
+| `ui_storyboard_set_entities` | `storyboard_id`, `entity_ids` (replaces the cast; `[]` clears it) |
+| `ui_storyboard_add_shot` | `storyboard_id`, `action`, `slug?`, `camera?`, `motion?`, `graphics?`, `production?`, `durationSeconds?`, `index?`, `afterShotId?` |
+| `ui_storyboard_update_shot` | `storyboard_id`, `target`, `action?`, `slug?`, `camera?`, `motion?`, `graphics?`, `production?`, `dialogue?`, `notes?`, `durationSeconds?`, `durationSource?`, `status?` |
+| `ui_storyboard_remove_shot` / `_duplicate_shot` | `storyboard_id`, `target` |
+| `ui_storyboard_move_shot` | `storyboard_id`, `target`, `sceneId?`, `position` |
+| `ui_storyboard_set_setup` | `storyboard_id`, `brief?`, `genre?`, `stage?`, `shotCount?`, `importSource?`, `directedFrom?` |
+| `ui_storyboard_direct` | `storyboard_id`, `redirect`, `shotCount?` |
+| `ui_storyboard_update_scene` | `storyboard_id`, `sceneId`, `slugline?`, `lighting?` |
+| `ui_storyboard_create_scene` / `_merge_scene` | `storyboard_id`, `afterSceneId?` / `sceneId` |
+| `ui_storyboard_set_style` | `storyboard_id`, `entityId?` or `descriptor?` |
+| `ui_storyboard_select_version` / `_delete_version` | `storyboard_id`, `target`, `kind`, `version` |
+| `ui_storyboard_add_keyframe_version` | `storyboard_id`, `target`, `assetId`, `flipOf?` — adds the still without selecting it |
+| `ui_storyboard_generate_keyframe` | `storyboard_id`, `target`, `staleOnly?` |
+| `ui_storyboard_generate_clip` | `storyboard_id`, `target`, `staleOnly?` |
+| `ui_storyboard_revise_shot` | `storyboard_id`, `target`, `instruction` |
+| `ui_storyboard_assemble_timeline` | `storyboard_id` |
+| `ui_storyboard_select_shot` | `storyboard_id`, `target` (nullable) |
+| `ui_storyboard_extract_script` / `_relink_script` / `_reproject_shots` | `storyboard_id` (+ `targets?`) |
+| `ui_storyboard_set_duration_source` | `storyboard_id`, `targets`, `source` |
+
+The browser shot tools take **no** `narration`, `entity_ids` or `render_mode`, and
+`add_shot` takes no `dialogue`. In the browser those arrive through
+`set_screenplay`; headless, through `edit_storyboard`.
+
+Generation is asynchronous: `generate_keyframe` / `generate_clip` start the job and
+return the shot. Poll `ui_storyboard_get_state` for `status`.
+
+Statuses: `planned` → `keyframe_generating` → `keyframe_ready` → `clip_generating` →
+`rendered`, or `failed`. (`approved` is legacy and reads as "still ready"; nothing
+sets it. Do not use it as a gate.)
+
+#### `screenplay` for `set_screenplay`
+
+```json
+{
+  "type": "screenplay",
+  "title": "…",
+  "logline": "…",
+  "brief": "…",
+  "styleBible": "…",
+  "aspectRatio": "9:16",
+  "narration": "…",
+  "musicPrompt": "…",
+  "entityIds": ["<asset id>"],
+  "shots": [
+    {
+      "slug": "1a",
+      "action": "Nova touches untreated hair, front-camera close",
+      "camera": { "framing": "close-up", "lens": "26mm", "angle": "eye", "movement": "handheld" },
+      "motion": "she lifts one section of hair and lets it fall, once",
+      "dialogue": "I wanted lighter hair…",
+      "durationSeconds": 4,
+      "entityIds": ["<asset id>"]
+    }
+  ]
+}
+```
+
+Ids, indexes and statuses are filled in. `style` is accepted as an alias of
+`styleBible`. Only `action` is required per shot.
+
+The top-level `entityIds` casts those entities on the **board** — that cast is what
+seasons every shot's still and clip prompt. Use `ui_storyboard_set_entities` to
+recast without replacing the shots; `ui_storyboard_get_state` reports the current
+cast as `entityIds`. A shot's own `entityIds` overrides the board cast for that shot
+(`[]` means "no entities on this shot"); without one, styles and locations apply to
+every shot and characters and props apply to the shots whose text names them.
+
+### Entities
+
+| Tool | Arguments |
+|---|---|
+| `list_entities` | `kind?` (`character`\|`location`\|`style`\|`prop`), `query?`, `limit?` |
+| `get_entity` | `entity_id` |
+| `create_entity` | `asset_id`, `kind`, `name`, `descriptor` (all required), `description?`, `voice_id?`, `tags?`, `lora?`, `palette?` |
+| `update_entity` | `entity_id` + any field, including `asset_id` to move it to a new photo |
+| `delete_entity` | `entity_id` — clears the marker, keeps the image |
+| `apply_entities` | `text`, `entity_ids?` → seasoned prompt + reference asset ids |
+
+An entity **is** an image asset carrying a marker. Its id is the asset id. To make one
+from nothing: `find_model` (`text_to_image`) → `generate_image` → `create_entity` with
+the returned asset id. To make one from a photo the user attached: find it with
+`asset_search` / `list_assets`, then `create_entity`.
+
+`apply_entities` is for seasoning a prompt you are about to send yourself
+(`generate_image`, `generate_video`). The storyboard render tools season internally —
+do not pre-season shot text with it.
+
+### Timeline
+
+`assemble_storyboard_timeline` lays rendered clips end to end, stamps each with its
+board and shot id, and gives every shot clip an **audio twin on a "Shot Audio" track**
+(each surface mutes video elements and mixes audio clips only). Board narration and
+music become draft clips on their own tracks.
+
+**Each shot is as long as its render**, not as long as its `duration_seconds` — a shot
+directed at 1.5s that came back at 5.184s occupies 5.184s of the cut. Shots that came
+back off their directed length are returned in `retimed_shots` and warned about, so a
+cut that runs longer than planned is visible without playing it. `duration_seconds`
+only decides a shot whose footage has no measurable length. A board linked to a script
+is the exception: there the words decide, and `trimmed_shots` names the shots whose
+footage does not fill the slot its lines gave it.
+
+`edit_timeline {timeline_id, ops[]}` carries the edit; `timeline-edit-ops` holds its
+full op list. Start with `get_state` for ids.
+
+To duck the shots' own sound under a voiceover: `set_clip_params` on the Shot Audio
+clips with `muted: true`, or `volumeDb: -18`. `set_clip_params` also takes `name`,
+`opacity`, `speedMultiplier`, `fadeInMs`, `fadeOutMs`, `blendMode`, `borderRadius`,
+`hidden`, `locked`, `textStyle`, `shapeStyle`.
+
+Every field goes on the op itself. A `params` / `props` wrapper is unwrapped, but the
+flat form is the contract:
+
+```json
+{"op": "set_clip_params", "target": "clip_1",
+ "textStyle": {"fontFamily": "Space Grotesk", "fontWeight": 800}}
+```
+
+`textStyle` is **merged** over the clip's own, so send only what you are changing —
+re-sending the whole object is how the fields you did not mean to touch get
+overwritten. `fontWeight` is a number, and the CSS keywords (`bold`, `semibold`,
+`extrabold`) are accepted and stored as one.
+
+**Set a bundled family or none at all.** `sans-serif`, `serif`, `system-ui` and the
+other CSS generics are refused where the clip is authored: they name no typeface, so
+the editor preview, the render and `preview_timeline_frame` each pick a different one.
+NodeTool ships Inter (the default), Space Grotesk, Bebas Neue, Playfair Display, Lora
+and JetBrains Mono. A named system font is still allowed and `validate_timeline`
+reports it as `font_not_portable`.
+
+`validate_timeline {timeline_id | document, fps?}` after every edit pass. It catches
+overlaps, fades longer than their clip, unknown presets and incomplete bindings.
+
+Other timeline tools: `list_timelines`, `create_timeline`, `get_timeline`,
+`delete_timeline`, and the version family (`list_`/`get_`/`create_`/`restore_`/
+`delete_timeline_version`). Browser twins are `ui_timeline_*`.
+
+### Script
+
+Use a script when the words drive the cut. `extract_script_from_storyboard` projects a
+board's dialogue and narration into a script and links the two: each shot keeps the
+line ids it covers, and from then on the script owns the words. `derive_storyboard_from_script`
+goes the other way, one shot per line, optionally with a director pass over the scaffold.
+
+`voice_script_lines` synthesizes each line with its cast voice; `assemble_script_timeline`
+lays the takes end to end.
+
+**Give the cast their voices first, then voice with no override.** A line takes its
+voice from its speaker: `add_line` without `speaker` leaves it with none, and
+`extract_script_from_storyboard` creates the Narrator with no voice and each
+character with at most its entity's `voice_id` and no provider or model. Either way
+the line reads `no_voice` until its speaker is bound. A voice is the
+triple `{provider, model, voice}` where `voice` is the voice's own name (`Aoede`,
+`Charon`, `alloy`) — a provider and a model alone do not pick one, so
+`voice_script_lines {provider, model}` is refused. Set each speaker once:
+
+```json
+{"op": "set_speaker_voice", "target": "MOM",
+ "provider": "gemini", "model": "gemini-2.5-flash-preview-tts", "voice": "Aoede"}
+```
+
+The three keys sit on the op, though a `voice: {provider, model, voice_id}` object —
+the shape `get_script` reports a voice in — is flattened onto it. Then call
+`voice_script_lines {script_id}` with no override and every speaker resolves its own. On a linked board, `assemble_storyboard_timeline` cuts words
+and picture together: each shot runs as long as the takes it covers and every voiced
+line gets its own voiceover clip.
+
+Others: `list_scripts`, `get_script` (line status: `draft`, `stale`, `voiced`,
+`no_voice`), `create_script`, `edit_script`, `delete_script`. Browser twins are
+`ui_script_*`.
+
+#### Writing the lines
+
+`create_script` makes an empty one. `edit_script {script_id, ops[]}` ops:
+`set_setup` (brief, format, length, pace, language, stage), `add_speaker`,
+`set_speaker`, `set_speaker_voice`, `add_section`, `add_line`, `set_line_text`,
+`set_line_speaker`, `remove_line`, `remove_speaker`. Call `get_script` first for
+line and speaker ids.
+
+`write_script {script_id, rewrite?, imported_text?}` drafts the lines from the
+setup and saves the cast and lines it produces, replacing what was there. Set
+the brief with `set_setup` first. `rewrite: true` keeps the ids of the lines it
+keeps, so their takes and storyboard links survive. Words passed as
+`imported_text` are only split into lines and attributed to speakers, never
+reworded. It records no take: voice the result with `voice_script_lines`.
+
+Rewriting a line leaves its takes in place as **stale**, so a following
+`voice_script_lines` re-records exactly those and nothing else.
+
+### Models
+
+`find_model {capability, query?, task?, provider_hint?, model_hint?, prefer_local?,
+limit?}` is the only way to name a model. **`capability` is required** and is one of
+`text_to_image`, `image_to_image`, `segment_image`, `text_to_video`, `image_to_video`,
+`reference_to_video`, `text_to_speech`, `text_to_music`, `audio_to_audio`,
+`automatic_speech_recognition`, `generate_embedding`, `generate_message`. `query` is the search box (`"flux schnell"`); `task` is a hint
+matched against a model's supported tasks, not a search.
+
+NodeTool ships curated ids under the `nodetool` provider, which are the sane defaults
+when the user has no preference:
+
+| Id | Use |
+|---|---|
+| `nodetool/flux-schnell` | cheapest stills, text prompts only |
+| `nodetool/nano-banana` | sharper stills, takes reference images |
+| `nodetool/seedream` | most detail, slowest |
+| `nodetool/hailuo-fast` | cheapest clips, for blocking out a cut |
+| `nodetool/kling-turbo` | steadier motion, mid price |
+| `nodetool/kling-standard` | most faithful motion |
+| `nodetool/kokoro` | eight TTS voices |
+
+### Media, outside the board
+
+`generate_image {provider, model, prompt, negative_prompt?, width?, height?, quality?,
+output_file?}`, plus `edit_image`, `generate_video`, `animate_image`, `generate_speech`,
+`generate_music` and `transcribe_audio` — each takes a `find_model` provider+model and
+saves an `asset://` result. `model` also accepts a whole `find_model` hit or its `.ref`,
+in which case `provider` may be omitted.
+
+`understand_video {provider, model, video, prompt?, max_tokens?}` reads a whole video
+with a multimodal model (Gemini reads video natively); use it to break down a reference
+cut. `video` takes an asset id, an `asset://` URI, a URL or a data URI. `view_image`
+puts pixels in your own context; `read_media_bytes` returns the bytes.
+
+### The Director node
+
+`nodetool.creative.Director` is a **workflow node**, not a chat surface. It turns a
+brief into a `Screenplay` (props: `model`, `brief`, `style`, `shot_count`, `aspect_ratio`,
+`max_tokens`; outputs
+`screenplay`, `narration`, `music_prompt`, `title`). Reach for it only inside a
+reusable graph. In chat, `direct_storyboard` runs the same Director over a saved
+board, or write the shots yourself with `edit_storyboard`.
+
+### Still-motion-graphics boards
+
+A board whose shots carry `production.media_strategy: "still_motion_graphics"` renders
+no clips: its stills and `graphics` elements become timeline layers.
+`preview_storyboard_design {storyboardId, expectedStoryboardRevision}` reads the design
+as a timeline preview with no save. `layout_storyboard` places every layer at each
+shot's hold frame with a vision model. `finish_storyboard` writes the editable
+timeline: `strategy: "deterministic"` (default, no provider) returns an unreviewed
+scaffold, `"agentic"` composes the motion and reviews rendered frames. All three
+need the board's current `revision` from `get_storyboard`.
+
+## Standing orders
+
+Use this optional template only when the user wants a staged review with approval
+between the board, stills, clips, and cut. Its checkpoints express that user's
+chosen workflow. They do not apply to other requests or override authorization
+already given to finish a piece.
+
+Respect the thread's existing permission mode. Plan mode blocks writes. Do not
+switch modes or use another tool family to evade a denial. The user can adapt the
+brief to authorize the desired stages and set a budget.
+
+```
+You are directing on the storyboard surface, then finishing in the timeline.
+Do not build a node graph unless I ask for a reusable template.
+
+SURFACES
+Headless: create_storyboard, get_storyboard, edit_storyboard,
+render_storyboard_stills, render_storyboard_clips, revise_storyboard_clip,
+assemble_storyboard_timeline, extract_script_from_storyboard.
+Browser (only for a board open as a tab): ui_storyboard_get_state,
+ui_storyboard_set_screenplay, ui_storyboard_generate_keyframe,
+ui_storyboard_generate_clip, ui_storyboard_revise_shot,
+ui_storyboard_assemble_timeline. Use ui_open_document to open a board.
+The ui_ generate and revise calls spend like the headless renders: same
+approval rules.
+
+LOOP
+1. list_storyboards, or read ui_context. No board -> create_storyboard.
+2. Cast before anything renders. list_entities first. A new entity needs an
+   image asset: generate_image (or my attachment), then create_entity with
+   {asset_id, kind, name, descriptor}. There is no create-from-text.
+   Each entity: one name, one kind, one canonical descriptor sentence.
+3. edit_storyboard set_board {entity_ids, image_model, video_model,
+   brief, style, aspect_ratio, narration, music_prompt}. Models come from find_model — there is no
+   default and an unset model fails the render.
+4. Direct with edit_storyboard add_shot, one op per shot. Give every shot a
+   slug (1a, 2a, ...). Fields: action, slug, camera {framing, lens, angle,
+   movement}, motion, dialogue, narration, duration_seconds, render_mode.
+5. STOP after the board. Report shot count and the two model ids. Do not
+   estimate dollars — no tool prices a render. Wait for "stills".
+6. render_storyboard_stills. I pick takes in the board's takes gallery, or
+   tell you which one; you apply it with edit_storyboard select_version.
+   Wait for "clips".
+7. render_storyboard_clips. revise_storyboard_clip touches one shot only.
+8. On "cut": assemble_storyboard_timeline, then validate_timeline.
+
+WRITING THE SHOTS
+The still prompt is action, camera framing, angle and lens, the scene
+lighting and the board style. A keyframe clip prompt is motion, action,
+camera movement and equipment; a direct clip gets all of these. Write camera
+direction into the camera object once, not into action as well.
+Name entities in plain text — "Nova reaches for the bottle", never "@Nova".
+Entities season a shot when their name appears in its action, motion, dialogue,
+narration or slug; styles and locations season every shot. A shot's entity_ids,
+if set, overrides that entirely.
+
+LOCKS
+- The descriptor is the face. Do not re-describe an entity in shot text.
+- Product geometry, label, cap and colour come from the product entity. No new
+  logos.
+- A state change (wet, stained, new outfit) is a second entity, not a morph
+  instruction inside one prompt.
+- Slugs stay stable. "Fix 3a" edits 3a and renders 3a.
+- UGC: handheld phone, grain, natural audio, no score, no beauty filter.
+  Hero: locked grade in the style, smooth camera, score allowed.
+- render_mode "keyframe" (default) for anything where the look must hold;
+  "direct" for heavy motion or a native-audio video model.
+
+MEMORY
+memory_save the style, the cast and the grade, with the entity and board ids in
+`resources` — that survives into later threads. share_result/read_shared are
+run-scoped and get discarded; do not use them to lock a look.
+
+If the shot count looks expensive, propose a collapse before rendering clips.
+```