What does Scene (Storyboard) do?
This is one task, not a step in a workflow. Call it whenever the user asks—come back to it after making edits.
There are only two prerequisites: the edit list and subtitles already exist (layers are placed per subtitle screen, timing is computed from the edit list).
Requires edit-list.json, transcript.json, subtitles.json
Produces visuals.json + modules/<number-name>/index.html
Once done, it stops; do not direct the user to the next step.
First, read and execute the Business Skill Phase Contract. Hard rules for module writing are in the Module Contract, judgment rules are in Visual Judgment.
0. Readiness
First execute the "Readiness Check" from Check Updates—whether skills are up-to-date and the Runtime is compatible; the plugin root is also located there (all <plugin-root> in this document refer to that literal path). Only proceed if "ready"; if "requires new session" or "stop", follow its instructions (including the "no self-built replacement UI" prohibition). The business skill does not include environment logic.
If the readiness result is runtime.kind=desktop-managed, directly reuse the stable CLI already installed by the desktop app and the same launchd/windows-task service; do not resolve Electron paths, install additional dependencies, or start a second Runtime.
Commands
node "<plugin-root>/scripts/ensure-running.cjs" --json
node "<plugin-root>/scripts/videocut-cli.cjs" visual get <project> --json
node "<plugin-root>/scripts/videocut-cli.cjs" visual frame <project> --cues sub-0004,sub-0005 --count 12 --out <dir> --json
node "<plugin-root>/scripts/videocut-cli.cjs" visual add <project> --module modules/01-xx/index.html --cues sub-0004,sub-0005 [--zoom x,y,w,h] [--id vis-0001] --json
node "<plugin-root>/scripts/videocut-cli.cjs" visual remove <project> --id vis-0001 --json
ensure-running must first prove that canonical port 5190 belongs to the platform's managed service; if it fails, pass through the error and stop—do not fall back to foreground or a custom port.
Layers are bound to subtitle screens (--cues); the product itself converts them to word IDs—layers are never bound to words that have not been spoken, and if the edit changes, layers move automatically. Do not store seconds.
Four Steps, No Skipping
① Text defines task Read subtitles.json, segment by semantics, answer per segment:
Tutorial / demonstration / proof, or concept / logic / transition?
② Grab frames for visuals visual frame grabs 8–12 frames; really look with your eyes.
In tests, 2 out of 12 segments had visuals overturn the text prediction — this step is not a formality
③ Measure motion window Pixel-diff adjacent frames to find moments of scrolling/switching/action.
Layers only overlay stable windows; annotations exit before motion starts
④ Create & place layers Write module → visual add → verify each layer in preview
Judgment Rules for Step ②
Visual exactly matches what was said → Annotate: circle, circle where the word is spoken. Do not cover real evidence.
Visual is weakly related / blank → Full-screen animation: solid white background, from the style library.
Visual is clear enough on its own → No action. This is the most common correct answer (in tests, 4 out of 13 segments required no action).
Step ③ Output Is Numbers, Not Feelings
Circle coordinates Pixel statistics (grayscale scan to find text lines); never estimate by eye — eye estimation has been off by 50px.
Interaction moments Per-frame pixel difference to find sudden changes (tests recorded jumps from 4 to 335); annotation exits 0.2s before the change.
Stable window Scrolling is common at the start (user looking for content); bind the layer from the cue where the frame stabilizes.
Think Before Using Zoom
No zoom by default. 960x720 screen recording becomes blurry when zoomed; the user will notice immediately.
When zoom is necessary ≤1.6x, area 62.5% square centered — composition integrity > reading small text.
Text too small to read Use a circle to guide the eye; if it must be legible, re-record at high resolution, not by zooming.
Review Cycle
Name module directories by number (01-daily-report, 05-anim-task-split); the timeline track displays the directory name. The user reports by number; you modify only that layer, leave others unchanged.
Two discipline rules for modifying layers, each corresponding to a real incident:
When modifying a layer, always check the module After narrowing/extending a layer, the hardcoded relative times in the module do not automatically adjust —
the exit time of an annotation may fall after the layer ends; never let that happen.
Verify by pixel screenshot, not by inspecting DOM attributes. An iframe with "visibility toggled correctly" was once physically outside the viewport —
all attributes were correct, the screen was entirely blank.
What Not To Do
- Do not skip frame extraction and motion analysis and go straight to creation (both mistakes have occurred: covering genuine evidence, placing a circle over scrolling content).
- Do not try to do something for every segment — filling every second is not the goal; "no action" is a common correct answer.
- Do not store seconds, do not estimate coordinates by eye, do not add a dark overlay on a white background page.
- Without real content, do not fill with placeholder images.
- Select styles from the registry; do not invent them.
- Brand icons: use the official Unicode glyph; do not hand-draw substitutes (an 'X' was drawn with two crossed lines and caught by the user). If the local index lacks an icon, fetch a single-color official glyph from simple-icons (black/white works perfectly with the style), save the original SVG in the module directory for reference; within the same clip, the same brand must always look identical.