@wji.ai/cli 0.1.0 → 0.2.0

package/skill/short-drama/reference/canvas-recipes.md

@@ -0,0 +1,199 @@
+# Canvas recipes for short drama
+
+Command sequences for the three canvas types. All ids are placeholders — take real ones from the
+command output (`wji --json canvas add … | jq -r .id`) and `bind` them at once. `SD` below is
+`node {baseDir}/scripts/short-drama.mjs`.
+
+Common setup (once per project):
+
+```bash
+wji ws create "<title>" -r 9:16 --json | jq -r .id     # default template: dataset, image generation, canvas → WS
+wji ws use WS
+SD bind <project> wji.workspaceId WS
+DS_APP=$(wji --json ws get | jq -r '.apps[] | select(.app=="Dataset") | .id')
+wji --json ws fs --app $DS_APP | jq -r '.. | objects | select(.content.semanticKey?) | "\(.content.semanticKey) \(.id)"'
+SD bind <project> wji.datasetFolders.character <id>        # story / character / location / prop / shot
+# zsh: a variable holding several ids is not word-split — pass ids literally or pipe through `while read`
+wji models list --feature image        # pick the image model once (GPT Image 2.5 Sunburst if listed)
+wji models get "<image model>"         # confirm 1:1 and 16:9 ratios and the max reference count
+```
+
+## 1. `characters` canvas
+
+```bash
+wji canvas create characters --json | jq -r .id                                  # → CV; bind wji.canvases.characters
+# row for C01 (rows 700 px apart: --at 0,0 / 0,700 / …)
+wji canvas add title -c CV -t "C01 林小夏" --at 0,0 --json | jq -r .id           # → T1; bind characters.C01.wji.nodes.title
+wji canvas add image -c CV -n "C01 headshot" -m "<image model>" -r 1:1 \
+  --at 400,0 -p "<image.prompt>, clean front-facing portrait, plain neutral background" --json | jq -r .id   # → H1
+wji canvas add image -c CV -n "C01 sheet" --from H1 -m "<image model>" -r 16:9 \
+  --prompt-file /tmp/C01-sheet.txt --json | jq -r .id                          # → S1 (file = "@image1 is the face to match exactly. " + image.sheet)
+wji canvas add audio -c CV -n "C01 voice" --from H1 -m seed-audio-1.0 \
+  -p "$(SD prompt <project> voice C01)" --json | jq -r .id                     # → V1; references the HEADSHOT
+#   the prompt is （age;identity;personality;timbre;pitch;pace;accent;emotion;此刻<direction>）<line>
+SD bind <project> characters.C01.wji.nodes.headshot H1      # sheet S1, voice V1
+```
+
+Generate: headshots for all characters are one batch (quote the total, or `-auto`), then look at
+each (`wji canvas get H1 --json | jq -r .assetId` → `wji asset download <asset> -o /tmp/sd`), then
+sheets. `wji canvas gen S1 --yes --wait` per node; the result's asset id →
+`bind characters.C01.wji.assets.sheet`. Attach to the dataset:
+
+```bash
+wji fs set <C01 dataset> --add-images <headshot> <sheet> <voice> --icon <headshot> --set primaryAudio=<voice>
+```
+
+Reference for the sheet prompt file: `@image1 is the face to match exactly — same features, same
+hairstyle. ` + `image.sheet`.
+
+## 2. `scenes` canvas
+
+```bash
+wji canvas create scenes --json | jq -r .id                                      # → SC; bind wji.canvases.scenes
+wji canvas add title -c SC -t "S01 便利店店内" --at 0,0
+wji canvas add image -c SC -n "S01 sheet" -m "<image model>" -r 16:9 --at 400,0 --prompt-file /tmp/S01-sheet.txt   # → SS1
+wji canvas add image -c SC -n "S01 lighting 监控回放绿" --from SS1 -m "<image model>" -r 16:9 \
+  -p "@image1 is this exact space; keep structure, materials and wear identical; change only the lighting: <lighting prompt>. Empty scene, no people, cinematic film still"
+# props: same, white background, `handheld scale` etc. in the prompt
+wji canvas add image -c SC -n "P01 sheet" -m "<image model>" -r 16:9 --at 400,700 --prompt-file /tmp/P01-sheet.txt
+wji canvas add image -c SC -n "P01 state 接在主机上" --from <P01 sheet> -m "<image model>" -r 16:9 -p "@image1 is the prop to reproduce exactly. <state prompt>, pure white background, no people, no hands"
+```
+
+Variants: `--from` the parent scene's sheet node, prompt = parent master view + `changes` +
+`keep the structure, materials and wear identical to @image1`.
+
+After generation: inspect (no people / hands, one space across panels), attach
+(`--add-images <sheet> <variants…> --icon <sheet>`), bind `scenes.S01.wji.nodes.sheet`,
+`scenes.S01.wji.assets.sheet`, `scenes.S01.wji.assets.lighting.<state>`.
+
+## 3. `E01` canvas
+
+```bash
+wji canvas create E01 --json | jq -r .id                                          # → E1; bind --ep 1 wji.canvasId
+# row 0 — the sheets this episode uses, as display nodes (assets already generated in stages 2–3)
+wji canvas add image -c E1 -n "C01 sheet" --asset <C01 sheet asset> --at 0,0 --json | jq -r .id     # → D_C01
+SD bind <project> --ep 1 wji.displayNodes.C01:sheet D_C01
+wji canvas add image -c E1 -n "S02 sheet" --asset <S02 sheet asset> --at 500,0 …                    # D_S02, D_C03, D_P01 …
+wji canvas add audio -c E1 -n "C01 voice" --asset <C01 voice asset> --at 2000,0                      # D_C01v (only if a voice exists)
+wji canvas add dataset -c E1 --dataset <C01 dataset id> --at 0,300                                    # optional: the character card, for people reading the canvas
+
+# row 1 — segment E01-01
+SD prompt <project> segment E01-01            # reference plan per keyframe + video prompt skeleton
+wji canvas add title -c E1 -t "E01-01 · 雨棚 · 15 s" --at 0,700
+wji canvas add image -c E1 -n "E01-01 f1" --from D_S02 D_C01 D_C03 D_P01 -m "<image model>" -r 9:16 --at 400,700 \
+  --prompt-file /tmp/E01-01-f1.txt                                                                    # → K1 … K5
+SD bind <project> --ep 1 storyboard.segments.E01-01.wji.nodes.keyframes.0 K1
+wji canvas gen K1 --yes --wait      # first segment: generate, download, inspect, fix, then the rest of the segment
+wji canvas add video -c E1 -n "E01-01" --from K1 K2 K3 K4 K5 D_C01v -m minimax-h3-ref -r 9:16 -d 15 \
+  --prompt-file /tmp/E01-01-prompt.txt --json | jq -r .id                                            # → VID1
+wji canvas add text -c E1 -n "E01-01 prompt" --text-file /tmp/E01-01-prompt.txt
+wji canvas gen VID1                 # prints the cost and refuses → tell the user → then --yes --wait (or -auto)
+```
+
+The keyframe prompt file is the plan's prefix (`@image1 is the environment …; @image2 is the
+character sheet of one person …`) followed by the cut's `frame`. Reference order in `--from` must
+match the plan's labels — `wji canvas get K1` shows `@image1 ← D_S02` etc.; fix with
+disconnect/connect if it does not.
+
+Video models, one per `params.video`: `h3` → `minimax-h3-ref`, `seedance` → `seedance-2.5-ref`,
+`seedance2` → `seedance-2.0-ref`, `seedance2fast` → `seedance-2.0-fast-ref`, `wan` → `wan-3.0-ref`.
+`prompt segment` prints the right one under `video.model` with the resolution already in that
+model's spelling — copy both rather than typing them, and `wji models get <name>` confirms the caps.
+Pass `-d` **only in `videoDuration: fixed`** (it switches `autoDuration` off, which is what pins the
+clip to the storyboard); in `auto`, leave it out. `minimax-h3-ref` has no `autoDuration`, so it is
+always `-d`.
+
+**Connect the voices too.** Everyone who speaks in the segment brings their voice asset as an audio
+reference — `canvas add audio --asset <voiceAsset>` once per character on the episode canvas, then
+`--from` them **after** the pictures (and after the clip reference, if there is one: `canvas connect`
+labels each edge as it is made, and `wji canvas connect <prev video node> <this video node>` prints
+`as @video1`, which is how to check the numbering landed where the prompt expects). They become `@audio1…M` (their own series, so a voice
+connected after three sheets is `@audio1`, not `@image4`), and the prompt attributes every one of
+that character's lines to the label. Caps: 3 audio references on `minimax-h3-ref` and the Seedance
+2.0 pair, 5 on `wan-3.0-ref`, 10 on `seedance-2.5-ref`. `prompt segment` prints the whole list,
+pictures then voices, in the order to connect them; drop them only if the model shows no audio
+reference support (`params.voiceSamples: false`).
+
+Sheets mode (`params.references: sheets`, no keyframes — **the default**) — the video node's
+`--from` are the sheet display nodes then the voice display nodes, in the order `prompt segment`
+prints, and with `videoDuration: auto` there is no `-d`:
+
+```bash
+wji canvas add video -c E1 -n "E01-01" --from D_S01 D_C01 D_P01 D_C01_VOICE -m seedance-2.5-ref -r 9:16 \
+  --resolution 480p --prompt-file /tmp/E01-01-prompt.txt      # resolution values are case-sensitive per model
+# D_S01 D_C01 D_P01 → @image1 @image2 @image3   ·   D_C01_VOICE → @audio1
+```
+
+The segment's **soundtrack node** (Seed Audio; `params.audioTrack`, default `bed`) sits beside the
+video node — no `--from` for a bed, the voice display nodes in speaking order for `--full`:
+
+```bash
+SD prompt <project> audio E01-01 > /tmp/E01-01-audio.txt                    # timecoded ambience / sfx / music
+wji canvas add audio -c E1 -n "E01-01 track" -m seed-audio-1.0 --prompt-file /tmp/E01-01-audio.txt --json | jq -r .id   # → A1
+SD bind <project> --ep 1 storyboard.segments.E01-01.wji.nodes.track A1
+wji canvas gen A1 --yes --wait                                                # ~0.15 credits a minute; attach: fs set <shot dataset> --add-images <asset>
+# --full: wji canvas add audio … --from D_C02_VOICE D_C01_VOICE  (→ @Audio1 @Audio2, the order the prompt names them)
+```
+
+`wan` mode, one clip per segment (the model speaks the dialogue itself, so no voice nodes):
+
+```bash
+wji canvas add video -c E1 -n "E01-01" --from K1 K2 K3 -m wan-3.0-ref -r 9:16 -d 15 \
+  --resolution 480P --prompt-file /tmp/E01-01-prompt.txt
+```
+
+`wan-3.0-ref` takes at most **10** reference images and whole-second durations (2–30 s); the
+`timing` gate already refuses a segment that breaks either rule. `--set audio=false` turns the
+generated sound off if you are laying your own track.
+
+`wan-3.0-ref` rejections from DashScope's green-net (`DataInspectionFailed`) are random and free —
+retry the same node 8–12 times, then shorten the prompt (see `stage-storyboard.md`).
+
+Queue: FREE accounts run 3 jobs at once — submit 3 keyframes, `wji history get <id> --wait` (or
+`wji canvas get <node>` until `done`), submit the next 3. A 429 was rejected before charging;
+wait, don't loop.
+
+After the clip: `wji fs set <E01-01 shot dataset> --add-images K1a K2a … --icon K1a --set primaryVideo=<clip asset>`,
+bind `storyboard.segments.E01-01.wji.assets.video`, then `SD manifest <project> --ep 1`.
+
+## Reference order after `connect`
+
+WJI numbers connected references **per type and in edge order** — `@image1 @image2 …` for pictures,
+`@video1 …` for clips, `@audio1 …` for the character voices — and that numbering is what the prompt
+addresses. So a voice node connected alongside three sheets is `@audio1`, not `@image4`.
+
+References are numbered by edge creation order. `canvas connect` appends, so adding a sheet later
+puts it *last* even if the legend says `@image2`. To restore the legend order, `disconnect` the
+edges that should come after it and `connect` them again in order — then `canvas get <video>`
+must print `@image1 ← <scene>`, `@image2 ← <person>` … exactly as `prompt segment` lists them.
+
+## Waiting for long clips
+
+`canvas gen --wait` gives up after 600 s by default and a 25–30 s Seedance clip can take longer;
+the task keeps running. Pass `--timeout 900`, or pick it up with `wji history get <id> --wait` —
+never resubmit a node whose status is still `generating`.
+
+## Measured prices (2026-09, one FREE account — re-check with `canvas gen` without `--yes`)
+
+With `params.videoReferences: previous`, the previous segment's **video node** is `--from`'d
+directly — it already carries the clip, so no display node is needed, and segment k cannot be built
+until k−1 has generated.
+
+| Generation | Credits |
+| --- | --- |
+| gpt-image-2.5-sunburst 1:1 1k (headshot, keyframe) | 18.3 |
+| gpt-image-2.5-sunburst 16:9 1080p (sheet) | 14.34 |
+| wan-3.0-ref 480P | 15 / s (15 s = 225) |
+| minimax-h3-ref 480P | 15 / s (15 s = 225) |
+| seedance-2.5-ref 480p, auto duration | ≈ 31 / s, billed on the real length (≈30 s = 900–930) |
+
+The Seedance 2.0 pair was not price-measured here; `canvas gen` without `--yes` quotes before
+charging, and `seedance-2.0-fast-ref` is the cheap one — use it for a draft pass of a shot you
+expect to re-cut, then re-run the approved segments on 2.5.
+
+A rejected submission (content filter, real-person check, 429) is not charged.
+
+## Cleaning up
+
+`wji canvas rm` and `wji fs rm` are destructive — name the targets in the chat and wait for a yes
+(the `wji` skill rules). Never delete a node whose asset is attached to a dataset without saying so.

package/skill/short-drama/reference/craft-motion.md

@@ -0,0 +1,116 @@
+# Motion craft — what happens over the seconds, and how the prompt says it
+
+The method behind `motion`, `cameraNote`, `sound` and the prompt-hygiene rules, distilled from
+the user's `short-drama-video-prompts` skill. The frame says how a cut starts; **the motion
+sentence says what changes between the start and the end boundary**, and the prompt is delivery
+text for a machine, not prose for a reader.
+
+## 1. The seven parts of a motion (gates `motion`, `sound`)
+
+1. **Start anchor** — the start boundary, in the present tense, static: "her hands are crossed on
+   her knees, her eyes on the puddle". Never "she is about to stand" (that is already motion).
+2. **Ordered subject motion** — `motion.trigger` (the cue: a sound, a line, a look), `motion.action`
+   (one visible state chain: who, what, direction, contact, landing — a hand-over names the giver,
+   the receiver, the hand and where the object lands) and `motion.result` (the end state, or
+   `hold`). Causal order, not a list: "hearing the latch, her eyes go to the door first; her left
+   hand stops on the page; only then does her back leave the chair". "Slowly, naturally,
+   cinematic" are not paths.
+3. **Performance arc** — never emotion labels in sequence (calm → tense → shocked). Trigger →
+   what is received → one or two visible signals in a channel the size can read (gaze, breath,
+   body set, object handling) → the decision (an action taken or withheld) → the landing at the
+   end boundary. A wide cannot carry an eyelid; a close-up cannot carry a full-body retreat.
+   Keeping still is a valid performance when it is the character's strategy.
+4. **Camera** — `cameraNote`. A lock-off is written like a move: the framing, **what still moves
+   inside it**, how long it holds (`hold`). An empty camera line is read as "free to drift", and
+   the model grows a push-in nobody asked for. A move names its `motivation` (reveal / pressure
+   / alignment / relationship / transition / stillness), its `trigger`, its `path` and tempo, and
+   its `endFraming` inside the cut's boundaries. Lock and move never rule the same interval
+   without a stated transition. One camera idea per cut; camera words are dialect-specific
+   (`CAMERAS` is H3's list, `CAMERAS_ZH` wan's) — do not carry a term validated on one model to
+   another.
+5. **Environment** — only motion that touches the subject or carries a cue: wind on a curtain,
+   steam, a reflection. Nothing invented for liveliness; weather or damage that is not in the
+   accepted state does not appear.
+6. **Sound** — `segment.sound`: `ambience` (the room tone, **identical across every segment of a
+   scene** — separately generated clips each invent their own, and every cut point then "whooshes"
+   into a new room), `sfx` pinned to a cut, `music` as `N/A` or an intent (where it enters, what it
+   sits under — music is implemented on the timeline, not burned into a clip). For a same-pass
+   model the sound section is a **complete timeline**: every voice event in order with speaker and
+   spoken language, ambience or silence between them, closed with the exclusions the script
+   declared. Left undefined, the seconds fill with sound the model chose.
+7. **End report** — the `end` boundary, field by field. A "more natural ending" in the prompt does
+   not override it; if the motion cannot reach it, the storyboard changes, not the boundary.
+
+## 2. Timing is arithmetic (gate `timing`)
+
+The cut seconds are the explicit timing plan and they sum to the segment. Both directions are
+defects: **overflow** is truncated — the closing action, the line's tail and the end pose go with
+it; **shortfall** is not a held frame — the model fills the unallocated seconds with motion that
+has no source. A line needs a lead-in before the mouth opens (`speechLeadSeconds`, 0.5) and a
+landing after it; a 4.0 s line does not fit a 4 s cut. Measured on H3 Chinese: ~4.1 speakable
+characters a second, with rushing first and silent truncation after — lengthen the cut, split
+it, or ask the script to cut the line; never quicken the delivery to make the sum work.
+
+## 3. Delivery text carries only what is to be filmed (gate `prompt-hygiene`)
+
+Inside the prompt there is no room for how the work was done:
+
+| never in the prompt | why |
+| --- | --- |
+| file names, versions, paths (`sheet_v3.png`) | rendered as text on screen |
+| entity ids, segment ids, rule ids, status words | the same, or read as an instruction to draw them |
+| sketch references ("as in panel 2"), retake notes ("fix the hands this time") | meaningless to the model, and "hands" becomes a subject |
+| walls of negatives ("no extra people, no deformed hands, no text…") | the nouns become the picture; write the positive fact instead ("only the two of them in frame, both hands complete and visible") |
+| `…` left from the skeleton | an unfilled slot |
+
+Bind on **every** mention or on none. In sheets mode a person is `@imageK` in every shot they
+are in; bound once and then "she" is read as two different people. The skeleton does this for the
+lines; the gate checks it per shot.
+
+**Subtitles are off unless asked.** Same-pass models add captions on their own; every prompt
+says so in its own language (`no subtitles, no captions, no on-screen dialogue text` / `全程无字幕`)
+— `params.subtitles: true` to allow them. Readable on-screen text (a prop with `textPolicy:
+readable`) is exact, everywhere it is shown, and never cancelled by a global "no text".
+
+## 4. Per model, measured
+
+**MiniMax H3** (`minimax-h3-ref`). Structured fields in English, dialogue kept in the original
+language inside `<d>[Chinese] …</d>` — only the line, no parenthetical, no seconds. On first
+mention a speaker is placed on- or off-screen with a timbre; **when another face is on screen
+during a line, write that they `do not speak; lips remain completely closed`** — 3/3 correct
+lip-sync against 2/3 without it, because the model puts the mouth on the most visible face; better
+still, have the non-speaker turned away or out of frame. `non_diegetic_music: N/A` when there is
+no score (omitting it produced music). Cut timestamps land near but not exactly; `<scenetrans>`
+carries a line across an in-generation cut, `<cutoff>` ends a clip mid-line only when the script
+wants it. Duration is any integer 4–15 (WJI's form: 5–15); first/last-frame inputs and reference
+inputs are mutually exclusive, so a start frame plus sheets all go in as references.
+
+**Seedance 2.5 / 2.0** (`seedance-*-ref`). `镜头 k [0:00–0:03]` timelines with no gaps and the
+last endpoint equal to the total; bind on every mention; 2.5 takes `extend` (continue from an
+actual clip plus its actual tail frame as `@image1`) and `edit`; tail frames improve the last
+frame's landing but hand the path between two frames to interpolation — an action the cut exists
+for must not rest on that gap. Two-frame chaining is not available on WJI today; `videoReferences:
+previous` passes the previous clip only.
+
+**Seed Audio 1.0** (`seed-audio-1.0`) — the soundtrack node. One prompt is a mini script:
+name the environment, each element and how the scene unfolds; `[start s:end s]` in front of an
+element pins it to that interval (100 ms precision), which is how the bed lines up with the cuts
+and how music is made to duck, swell or fall silent at a moment ("Let the music drop before the
+key line" is the documented idiom). Up to 120 s per generation, 2048 characters, three reference
+voices as `@Audio1..3` **or** one reference image, never both; a reference clip is under 30 s.
+Ask for `instrumental` when there are to be no vocals, and say "no dialogue" on a bed — left
+open, it invents a narrator. `prompt audio` derives all of this from `segment.sound`.
+
+**Wan 3.0** (`wan-3.0-ref`). Chinese prompt, same-pass audio, the 音频 line is the whole sound
+design; the content filter judges the assembled prompt's *length* (`stage-storyboard.md`), so the
+motion and camera clauses stay terse.
+
+## 5. Self-check before generating
+
+Does the prompt start from the exact start boundary and restate only what this execution needs?
+Is every person and prop that acts, reacts or is handed over resolvable — bound or described? Do
+two people on screen resolve to two different bindings on every mention? Has every performance
+change a trigger and a visible channel? Do the seconds add up in both directions, with the
+lead-in? Does the sound section cover the whole cut — lines, ambience between, music declared?
+Is there any file name, id, note or negative dump left? Would the end the prompt describes match
+the `end` boundary field by field?

package/skill/short-drama/reference/craft-shots.md

@@ -0,0 +1,177 @@
+# Shot craft — how a cut earns its place
+
+The method behind the storyboard fields added to stage 5, distilled from the user's
+`short-drama-storyboard` skill. It applies in **both** reference modes: in `keyframes` the frame
+becomes an image, in `sheets` it is the shot's description inside the segment prompt — either
+way the cut carries the same shot grammar, and `prompt segment` composes it. What can be checked
+is a gate, named per section; the rest is judgement.
+
+## 1. A cut has one job — `purpose` (gate `shot-purpose`)
+
+A cut exists to change what the audience knows, who holds power, the pressure in the room, the
+space, or the rhythm. "Medium shot of her talking" is not a purpose. Design in this order:
+
+1. find the key action in the beats the cut claims — an act, a line, a discovery, a refusal, a
+   hand-over, a reveal;
+2. say what changes for the audience or a character because of it (`purpose.change`);
+3. decide whose experience the picture is organised from;
+4. fix what must be visible at the start and the end;
+5. only then choose the size, the camera move and the cut point.
+
+`purpose.kind`: `establish` (space, who is where), `reveal` (new information enters), `evidence`
+(the object the audience must read), `reaction` (the receiver's face or hands), `pressure`
+(distance closes, an exit is taken), `decision` (a visible choice), `consequence` (the result
+lands), `performance` (the line and the body that says it), `transition`.
+
+**Cut on a change.** Adjacent cuts differ in at least one of size, angle or who is on screen —
+the same framing twice is a jump cut with a number. **A turn needs a reader.** A cut claiming a
+script `turn` beat or the 爽点 is a reveal-class cut (`reveal / evidence / decision /
+consequence`), or the next cut is a `reaction` on someone who did not speak the line — a blow
+nobody is seen to receive did not land. **The cliff cut** (the episode's last beat) is `reveal /
+consequence / reaction / pressure`; it never resolves.
+
+## 2. The size ladder
+
+| 景别 | what it carries |
+| --- | --- |
+| 远景 `extreme-wide` | geography, the person swallowed by the space; no expression |
+| 全景 `wide` | the room, who controls the door, group power |
+| 中景 `medium` | interaction, hands, two-person strategy, blocking |
+| 近景 `close` | a decision, evidence, a hidden reaction |
+| 特写 `extreme-close` | one face, one hand, one wound — the only fact in frame; the space is gone |
+
+A scene opens one step wider than it will play, lands on its **working size** on the second
+cut, then steps a size up or down around it; a wide or an extreme close-up is an excursion,
+used once and returned from. Do not use the size as an emotion dial — the question is always
+*where does the information the audience must read live*: on the knuckles, give the extreme
+close-up; in the distance between two people, do not cut in. A segment that only tightens has
+nowhere to go by its middle (`storyboard-advice`).
+
+**9:16 narrows the ladder.** Wides carry information sideways, and a phone has a third of the
+width. Vertical drama plays in medium / close / extreme-close, and space is built in **depth**:
+foreground, mid-ground, background — a doorframe, a counter edge, a shoulder in front, the room
+behind (`foreground`, `background`). A wide on 9:16 must say why (`note`) or carry a `background`
+that does the geography.
+
+## 3. Three axes, three fields (gate `framing-axis`)
+
+"A motivated angle" hides three separate decisions, and the common accident is writing 俯拍 when
+what was meant was "from behind her shoulder".
+
+| field | vocabulary | what it answers |
+| --- | --- | --- |
+| `angle` | `front` 正面 · `three-quarter` 斜侧 · `profile` 正侧 · `rear-three-quarter` 后斜侧 · `back` 背面 | how much face the audience may read, and whose side they stand on |
+| `height` | `ground` · `low` 仰 · `eye` 平视 · `high` 俯 · `top` | who is bigger than whom this instant — `eye` is a *choice* for equals |
+| `focal` | the lens (`FOCAL_BY_SIZE` or your own) | how far apart two people look |
+
+They do not derive from each other: a low angle from behind is "we follow him as he grows", a
+low angle from the front is "he is coming down on us"; a long lens on a wide flattens two people
+across a room into one. Height is expensive on 9:16 — a tilt eats the vertical room the person
+has — so carry power with angle and distance first.
+
+## 4. The axis — `segment.axis`, `axisSide`, `facing`
+
+The 轴线 is the line between two named people. Write it as three checkable assertions, not an
+adjective:
+
+```json
+"axis": { "between": ["C01", "C02"], "workingSide": "the customer side of the counter, camera looking at the clerk over the oden warmer",
+          "screenLeft": "C02", "screenRight": "C01" }
+```
+
+- **Bare left / right always means screen left / right.** A person's own side carries the
+  subject: "her right hand", "his left shoulder". Mixing the two readings is the usual cause of a
+  reversed reverse-shot, and every sentence looks fine on its own.
+- **Reverse shots are complementary**: if A faces `screen-right` in her single, B faces
+  `screen-left` in his. Two singles facing the same way read as both looking at a third person.
+  Match the eyeline height to the real height difference; an asymmetric pair (one higher, one
+  tighter) is a statement of power — make it on purpose.
+- **Over-the-shoulder** names whose shoulder is in the foreground (`foreground`); that decides
+  whose shot it is.
+- **Crossing the axis** is legal with a neutral shot, an in-shot crossing, a deliberate
+  disorientation or a re-established geography — `axisSide: cross` with a `note` that says which;
+  the new working side is then inherited by the cuts after it.
+- Three or more people: draw the **directed relationship** first (who protects / presses /
+  watches whom, from which beat), then place bodies, facing, distance and lines of action; one
+  representative reaction beats a row of identical gasps; background people do not change sides
+  between cuts without a reason.
+
+## 5. Start → one action → end (gate `continuity`)
+
+Every cut has two boundaries, and the boundaries are the continuity system:
+
+```json
+"start": { "positions": { "C01": "behind the counter" }, "facing": { "C01": "screen-left" }, "gaze": { "C01": "at the bag" },
+           "hands": { "C01": "both hands on the counter edge" }, "heldProps": { "C01": [] }, "state": ["the bag lying on the counter"] },
+"end":   { … the same fields … }
+```
+
+- `start` is written on a segment's **first** cut only; every later cut begins where the previous
+  one ended (the script derives it), and a segment in the same scene begins where the previous
+  segment ended — positions and held props are compared.
+- Each boundary is an absolute fact readable without the last cut ("on the stool" — never "same
+  as before"). A person who enters on a cut has no start; `render segment` marks them 入画.
+- **A prop changes hands only on an action beat.** A hand-over between two lines is teleporting.
+- `state[]` are short visible facts ("the drawer slightly ajar", "steam rising off the bowl").
+  A state that only exists in `end` may not be named in `frame` — that is **keyframe drift**,
+  the picture already showing the result.
+
+## 6. The frozen frame — `frame`
+
+The frame is the **start instant**, in both modes: the still a photographer could take at
+second 0.00 of the cut. Twelve things make it renderable without the artist inventing any of
+them; ~400–500 characters is full, 800 is padding:
+
+| write | or the model decides it for you |
+| --- | --- |
+| where each person is and how far apart | spacing drifts cut to cut, the room seems to change |
+| foreground / mid-ground / background | depth collapses into one layer |
+| where the eye should land (the shot's one fact) | the frame is evenly weighted, nobody knows what to look at |
+| composition and size phrase | each cut composed at random; they do not cut together |
+| which side of the axis, height, lens | the reverse angle does not match |
+| where the light comes from and its quality — its *result* on the face | the key jumps between cuts of one scene |
+| every present person's pose, facing, hands, held props | the next cut cannot pick them up |
+| what is the same as the previous cut, in one clause | "unwritten" is read as "free to change" |
+
+**Static test**: no ordered verbs (then / before / after that / begins to / 先 / 再 / 然后),
+no expression *changing*, no camera move, no weather *transforming* — those belong to `motion`.
+A held pose can imply tension; it cannot require two moments. **No names**, no ids, no file
+names: the frame is delivery text.
+
+Lighting: `light.direction` is relative to the camera; `light.note` describes what the light
+*does* on the face or the object ("the cabinet glow holds the right of his face; nothing moves
+but the light on his jaw") — the result reads more stably than the position alone, and it must
+say whether left / right is the screen's or the subject's.
+
+## 7. Generability (gates `filmable`, `motion`; advice in `storyboard-advice`)
+
+A video model performs what it has seen a million times: walk in, sit, stand, turn, nod, hand
+over, take, hold, push a door, set something down, reach. Four risk classes it does not perform:
+
+| risk | example | rewrite |
+| --- | --- | --- |
+| precise interception | blocking a closing lid with a palm | close it, then keep the hand on it (two common actions + a hold) |
+| invisible inner state | 像是听见了什么 · seems to realise | the visible action that shows it |
+| the negative action | 没有接话 · does not press it | the action that happens instead — a hold, a hand that stays |
+| a hand chain | four steps of two-hand work in four seconds | hand the change to an object, split the cut, or end on the result |
+
+Drama lives in the **combination and timing** of ordinary actions, not in their precision. The
+test: read the action to someone who has not seen the script — can they mime it at once?
+
+## 8. Key scenes — `storyboard.visualPlans[]` (gate `visual-plan`)
+
+Only for scenes where the directing choice changes the experience: a first appearance, a reveal
+of identity or evidence, a reversal, the climax or the cliff. `seed storyboard` writes the
+worksheet for the 爽点 scene and the cliff scene; before cutting them answer 戏剧转向 (`turn`),
+观众立场 (`alignment`: where we stand at the start, where we are moved to), 空间压力
+(`pressure`: entrances, distance, blocking, exits), 视觉推进 (`progression`: what lands first —
+information, reaction or space), 摄影节奏 (`rhythm`: what triggers a lock, a move, a cut-in, a
+hold), 反应落点 (`landing`: whose choice ends the scene) and 声音策略 (`sound`). Ordinary scenes
+go straight to cuts.
+
+## 9. Review questions
+
+Which beats does this cut realise, omit or repeat? What has changed when it ends? Why this size
+and this camera behaviour? Can every person stand, see and move where the space puts them? Is the
+end a start the next cut can pick up? If this cut were deleted or merged, what story meaning would
+be lost — and if the answer is nothing, merge it.