@wji.ai/cli 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wji.ai/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Command line interface for the WJI AI platform",
   "license": "UNLICENSED",
   "author": "WJI AI",

package/skill/short-drama/SKILL.md

@@ -15,13 +15,24 @@ outline ──▶ characters ──▶ art ──▶ script (per episode) ──
  story/      character/   location/    story/                   shot/E01/  datasets
  dataset     datasets +   prop/        screenplay               + E01 canvas: keyframes → video
              `characters` datasets +   dataset
-             canvas       `scenes` canvas
+             canvas       `scenes` + `props` canvases
 ```
 
-`{baseDir}` = this directory. Script: `node {baseDir}/scripts/short-drama.mjs <cmd> …` (zero
-dependencies). Read `{baseDir}/reference/schema.md` before writing any JSON and
-`{baseDir}/reference/workspace-layout.md` before touching WJI. The `wji` skill governs every CLI
-call (auth, confirmations, spending policy, model choice) — this skill only says what to build.
+`{baseDir}` = this directory. Read `{baseDir}/reference/schema.md` before writing any JSON and
+`{baseDir}/reference/workspace-layout.md` before touching WJI.
+
+**First, decide which surface you are on — it decides how every operation below is spelled.**
+
+- `short_drama_validate` is among your tools → you are in **WJI chat**. Read
+  `{baseDir}/reference/operations-wji.md`. Every `node {baseDir}/scripts/short-drama.mjs <cmd>` and
+  `wji <cmd>` line in this skill is the CLI spelling of an operation — translate it with the tables
+  there. There is no shell and no project directory.
+- Otherwise you are in **Claude Code with the `wji` CLI**. Read
+  `{baseDir}/reference/operations-cli.md`; the commands in this skill are literal. The script is
+  `node {baseDir}/scripts/short-drama.mjs <cmd> …` (zero dependencies), and the `wji` skill governs
+  every CLI call (auth, confirmations, spending policy, model choice).
+
+Either way, this skill only says **what to build**; the operations doc says how to say it.
 
 **How the drama is written** comes from `{baseDir}/reference/craft-story.md` (the 短剧 method:
 brief, three phases, 分集目录, 爽点 / 钩子 libraries, the episode formula, the character bible) and
@@ -68,9 +79,10 @@ ending), change the guideline first, then the episodes.
    **Style**: `photoreal` for a live-action drama, `realistic` for semi-realistic painterly,
    `ghibli` for hand-painted anime. **References** (default `sheets`): the video node references
    the character/scene sheets directly and no storyboard images are generated — fewer images to
-   pay for and approve, and continuity comes from the sheets. Choose `keyframes` (one generated
-   image per cut) only when a shot has to be composed exactly; h3 needs it for its keyframe-pinned
-   prompt. **Duration** (default `auto`): the model matches the clip to the prompt; `fixed` sends
+   pay for and approve, and continuity comes from the sheets. Every mode works this way, h3
+   included (its sheets-mode prompt opens with an `@imageK is …` legend instead of the alignment
+   line). Choose `keyframes` (one generated image per cut) only when the user asks for it or a shot
+   has to be composed exactly — never switch a project to it on your own. **Duration** (default `auto`): the model matches the clip to the prompt; `fixed` sends
    `-d` = Σ cuts and is forced on models without an auto duration.
 
    **The camera package** is `params.camera` — body, lens family and working stop, default
@@ -166,8 +178,9 @@ Read `{baseDir}/reference/stage-art.md`.
 1. Scenes: `summary`, 3–5 `anchors`, `lighting` states derived from the episodes the scene appears
    in, empty-scene `image.*`; variants via `variantOf` + `changes`. Props (only narrative ones):
    `scale`, `anchors`, `states`, white-background `image.*`. `validate --stage art`.
-2. Sync to `location/` and `prop/` datasets; `scenes` canvas: one sheet node per scene / prop
-   (16:9), variant and state nodes `--from` the parent sheet. Generate, inspect (no people in a
+2. Sync to `location/` and `prop/` datasets; `scenes` canvas: one sheet node per scene (16:9),
+   lighting / variant nodes `--from` the parent sheet; `props` canvas (`wji canvas create props`):
+   one white-background sheet node per prop, state nodes `--from` it. Generate, inspect (no people in a
    scene, no hands on a prop, one space across all panels), attach as `icon`, bind.
 
 ## Stage 4 — Script (per episode, batches of ≤3)
@@ -236,20 +249,24 @@ must be connected: pictures, then clips, then voices.
 2. Sync: shot folder `shot/E0N`, one `shot` dataset per segment (`video_prompt` = the prompt,
    content = `render segment E0N-01` — the 分镜 with one `### SHOT k` block per cut).
 3. `E0N` canvas (`wji canvas create E0N`): display nodes for every sheet the episode uses
-   (`canvas add image --asset …`, keyed in `wji.displayNodes`). Then, in the default `sheets` mode,
-   the video node per segment straight from those display nodes (`--from` them in the order
-   `prompt segment` prints the legend — the order is the legend, so a reconnect must redo the whole
-   set). With `references: keyframes`, first a keyframe node per cut (`--from` the display nodes,
-   ratio = `params.ratio`), then the video node `--from` the keyframes in cut order.
-   Either way the video node takes the mode's model, `--resolution params.videoResolution`,
-   `--prompt-file`, and `-d` = Σ cut seconds **only in `fixed` duration mode** — in `auto` leave
-   `-d` off and let the model match the clip to the prompt.
-4. In `sheets` mode go straight to generating the clips. With `keyframes`, **generate the first
-   segment's keyframes only**, download, check: same world as the scene sheet, same faces as the
-   character sheets, the right shot size, nobody extra in frame. Regenerate what is off, then
-   continue segment by segment. Keyframes for one segment are a batch (quote the total); each video
-   is a video (ask, or `-auto`). Stay under the queue cap (`wji` skill *Limits*): submit up to the
+   (`canvas add image --asset …`, keyed in `wji.displayNodes`), plus the voice display nodes of
+   whoever speaks. **No storyboard images are generated**: the video node per segment references
+   the sheets directly — `--from` the scene / character / prop display nodes then the voices, in
+   the order `prompt segment` prints the legend (the order *is* the numbering, so a reconnect must
+   redo the whole set). The video node takes the mode's model, `--resolution
+   params.videoResolution`, `--prompt-file`, and `-d` = Σ cut seconds **only in `fixed` duration
+   mode** — in `auto` leave `-d` off and let the model match the clip to the prompt.
+4. Generate the clips segment by segment — each video is a video (ask, or `-auto`); download and
+   check the first one against the sheets (same world, same faces, right size, nobody extra)
+   before submitting the rest. Stay under the queue cap (`wji` skill *Limits*): submit up to the
    cap, `wji history get <id> --wait`, continue.
+
+   *Only if the user set `references: keyframes`* (a shot that must be composed exactly): a keyframe
+   image node per cut first (`--from` the display nodes, ratio = `params.ratio`, prompt from
+   `prompt segment`), the video node `--from` the keyframes in cut order; generate the first
+   segment's keyframes only, inspect, then continue. Keyframes for one segment are a batch (quote
+   the total). Do not switch a project to keyframes on your own — it doubles the images to pay for
+   and approve.
 5. **Soundtrack node** per segment (`params.audioTrack`, default `bed`): `prompt audio E0N-01`
    derives a Seed Audio prompt from `segment.sound` — timecoded `[start s:end s]` ambience, sfx on
    their cuts, music that enters / swells / ducks / falls silent at the cues you wrote on
@@ -257,7 +274,7 @@ must be connected: pictures, then clips, then voices.
    credits a minute, no `--from`; `--full` adds the lines in the connected `@Audio1..3` voices).
    Seed Audio is the voice-sample model, but it is an audio-scene generator: one prompt is a whole
    track. Attach the asset to the shot dataset; bind `wji.nodes.track` / `wji.assets.track`.
-6. After each clip: `fs set <shot dataset> --add-images <keyframes…> <track> --set primaryVideo=<clip>`;
+6. After each clip: `fs set <shot dataset> --add-images <track> [<keyframes…>] --set primaryVideo=<clip>`;
    bind asset ids. `manifest --ep N` must come back clean before you call the episode done.
 
 - **A failed generation is not always a bad prompt.** `wan-3.0-ref` rejections from DashScope's

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

@@ -1,5 +1,10 @@
 # Canvas recipes for short drama
 
+**On WJI** (`canvas_*` tools, no shell): the layouts below are the contract — which node sits in
+which row, and in what order the references are connected. Read them as written and substitute the
+tool calls from `operations-wji.md`; `--from A B C` is `fromNodeIds: ['A','B','C']` and the array
+order is the reference order. Everything about rows, `@imageN` order and prompts is identical.
+
 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`.
@@ -46,7 +51,7 @@ wji fs set <C01 dataset> --add-images <headshot> <sheet> <voice> --icon <headsho
 Reference for the sheet prompt file: `@image1 is the face to match exactly — same features, same
 hairstyle. ` + `image.sheet`.
 
-## 2. `scenes` canvas
+## 2. `scenes` canvas — one row per scene
 
 ```bash
 wji canvas create scenes --json | jq -r .id                                      # → SC; bind wji.canvases.scenes
@@ -54,18 +59,33 @@ 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
+After generation: inspect (no people, 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>`.
 
+## 2b. `props` canvas — one row per prop
+
+Props live on their own canvas: white background, `handheld scale` / `tabletop scale` /
+`furniture scale` in the prompt, one **state** node per `states[]` entry referencing the sheet.
+
+```bash
+wji canvas create props --json | jq -r .id                                       # → PC; bind wji.canvases.props
+wji canvas add title -c PC -t "P01 旧监控硬盘" --at 0,0
+wji canvas add image -c PC -n "P01 sheet" -m "<image model>" -r 16:9 --at 400,0 --prompt-file /tmp/P01-sheet.txt   # → PS1
+wji canvas add image -c PC -n "P01 state 接在主机上" --from PS1 -m "<image model>" -r 16:9 \
+  -p "@image1 is the prop to reproduce exactly. <state prompt>, pure white background, no people, no hands"
+```
+
+Inspect (no hands, no people, the same object in every panel), attach
+(`--add-images <sheet> <states…> --icon <sheet>`), bind `props.P01.wji.nodes.sheet`,
+`props.P01.wji.assets.sheet`, `props.P01.wji.assets.states.<state>`. On the episode canvas the
+prop's sheet becomes a display node like any other (`wji.displayNodes["P01:sheet"]`).
+
 ## 3. `E01` canvas
 
 ```bash
@@ -77,23 +97,33 @@ wji canvas add image -c E1 -n "S02 sheet" --asset <S02 sheet asset> --at 500,0
 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
+# row 1 — segment E01-01 (default: reference images → video, no storyboard images)
+SD prompt <project> segment E01-01 > /tmp/E01-01-prompt.txt   # the header line lists refs: in the order to connect them
 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 video -c E1 -n "E01-01" --from D_S02 D_C01 D_C03 D_P01 D_C03v D_C01v -m seedance-2.5-ref -r 9:16 \
+  --resolution 480p --prompt-file /tmp/E01-01-prompt.txt --json | jq -r .id                          # → VID1
+# D_S02 D_C01 D_C03 D_P01 → @image1 … @image4   ·   D_C03v D_C01v → @audio1 @audio2   (pictures, then clips, then voices)
+SD bind <project> --ep 1 storyboard.segments.E01-01.wji.nodes.video 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.
+`wji canvas get VID1` must print `@image1 ← D_S02`, `@image2 ← D_C01` … exactly as the prompt's
+legend says; fix with disconnect/connect if it does not. With `videoDuration: auto` (the default)
+there is no `-d`; `minimax-h3-ref` has no auto duration, so h3 projects pass `-d` = Σ cut seconds.
+
+**Only with `params.references: keyframes`** — one generated image per cut, referenced by the video
+node instead of the sheets (an opt-in for shots that must be composed exactly; twice the images to
+pay for and approve):
+
+```bash
+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  (prompt = plan prefix + cut.frame)
+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
+wji canvas add video -c E1 -n "E01-01" --from K1 K2 K3 K4 K5 D_C03v D_C01v -m minimax-h3-ref -r 9:16 -d 15 \
+  --resolution 768P --prompt-file /tmp/E01-01-prompt.txt --json | jq -r .id                          # → VID1
+```
 
 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`.
@@ -114,16 +144,6 @@ that character's lines to the label. Caps: 3 audio references on `minimax-h3-ref
 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`:
 

package/skill/short-drama/reference/operations-cli.md

@@ -0,0 +1,43 @@
+# Operations — Claude Code / `wji` CLI
+
+This is the **CLI binding** of the operations the stage docs name. You are on this surface when you
+have a shell and a project directory. If `short_drama_validate` is among your tools instead, you are
+on WJI — read `operations-wji.md` and ignore this file.
+
+`{baseDir}` = the skill directory. `{project}` = the project directory (the one holding
+`project.json` and `episodes/E0N.json`). The engine is zero-dependency:
+
+```
+node {baseDir}/scripts/short-drama.mjs <cmd> {project} …
+```
+
+## The engine
+
+| Operation | Command |
+| --- | --- |
+| `init` | `short-drama.mjs init {project} --title "<t>" --episodes N --minutes M --genre "<g>" --register 台湾国语 [--adapt 抽核] [--ratio 9:16] [--video h3\|seedance\|seedance2\|seedance2fast\|wan] [--resolution 480P…] [--accent "<accent>"] [--style photoreal\|realistic\|ghibli] [--references sheets\|keyframes] [--duration auto\|fixed] [--look "<lens>"] [--lang zh]` |
+| `validate` | `short-drama.mjs validate {project} [--stage <stage>] [--ep N]` — exits 1 on a hard failure, 0 on advisories alone |
+| `checkup` | `short-drama.mjs checkup {project}` — same, but prints the passing and skipped rows too |
+| `seed` | `short-drama.mjs seed {project} script --ep N [--force]` · `… seed {project} storyboard --ep N [--force]` |
+| `render` | `short-drama.mjs render {project} outline \| guideline \| character C01 \| scene S01 \| prop P01 \| script --ep N \| dialogue --ep N \| segment E01-01` |
+| `prompt` | `short-drama.mjs prompt {project} segment E01-01 [--json]` · `… prompt {project} audio E01-01 [--full\|--bed]` · `… prompt {project} voice C01` |
+| `manifest` | `short-drama.mjs manifest {project} [--stage <stage>] [--ep N] [--json]` — exit 2 while anything is unbound |
+| `bind` | `short-drama.mjs bind {project} [--ep N] <path> <value>` — record a WJI id in the JSON |
+
+Read and write `project.json` / `episodes/E0N.json` with your ordinary file tools; `bind` exists only
+so the WJI ids land on the right path without hand-editing.
+
+## WJI, through the `wji` CLI
+
+The `wji` skill governs auth, confirmations and spending. The calls this skill makes:
+
+| Purpose | Command |
+| --- | --- |
+| preflight | `wji auth whoami --json`, `wji profile wallet` |
+| workspace | `wji ws create "<title>" -r <ratio>` → `wji ws use <id>` |
+| datasets | `wji dataset new … --app <appId>`, `wji fs set <id> --merge` (never `--content`), `--add-images` (never `--images` on an existing node) |
+| canvases | `wji canvas create <name>` · `wji canvas add <kind> -c <cv> …` · `wji canvas connect <a> <b>` · `wji canvas get <node>` · `wji canvas gen <node> [--yes --wait]` · `wji canvas rm` |
+| assets | `wji asset download <id> -o <dir>` — **look at what you generated** before building on it |
+| history | `wji history get <id> --wait` |
+
+Full canvas layouts, with the node rows and the reference order, are in `canvas-recipes.md`.

package/skill/short-drama/reference/operations-wji.md

@@ -0,0 +1,82 @@
+# Operations — WJI chat (`short_drama_*` / `canvas_*` tools)
+
+This is the **WJI binding** of the operations the stage docs name. You are on this surface when
+`short_drama_validate` is among your tools: there is no shell, no project directory and no `wji`
+command — everything below is a tool call. If you have a shell instead, read `operations-cli.md`.
+
+Whenever a stage doc shows a `node …/short-drama.mjs <cmd>` or `wji <cmd>` line, translate it with
+the tables here. The rules, the gates and the JSON schema are identical on both surfaces.
+
+## Where the project lives
+
+There is no `project.json` on disk. The project is a small set of datasets in the workspace's
+**story** folder:
+
+```
+story/<title> · 短劇工程/
+  project     ← the whole project.json, in content.shortDrama.data
+  E01, E02 …  ← one per episode, the episodes/E0N.json
+```
+
+`short_drama_create` makes them and returns a **`project` id**. Every other tool takes that id;
+episodes are addressed with `ep: N`, never by node id.
+
+## The engine
+
+| Operation | Tool |
+| --- | --- |
+| `init` | `short_drama_create { workspace, title, episodes, minutes, genre, register, … }` → `{ projectId, project }` |
+| read the JSON | `short_drama_get { project, ep?, section? }` — `section` trims a big branch (`characters`, `storyboard` …) |
+| write the JSON | `short_drama_put { project, ep?, data }` for a whole document, or `{ project, ep?, path, value }` for one field (this is `bind`) |
+| `validate` | `short_drama_validate { project, stage?, ep? }` |
+| `checkup` | `short_drama_validate { project, all: true }` |
+| `seed` | `short_drama_seed { project, what: 'script' \| 'storyboard', ep, force? }` |
+| `render` | `short_drama_render { project, what, ep?, id? }` → markdown |
+| `prompt` | `short_drama_prompt { project, what: 'segment' \| 'audio' \| 'voice', id, mode? }` |
+| `manifest` | `short_drama_manifest { project, stage?, ep? }` |
+
+**`short_drama_put` validates as it writes** and returns the gates for the stage you touched — read
+that result instead of calling `short_drama_validate` again. A turn is capped at 20 tool calls, so
+write a whole document at a time rather than field by field.
+
+## WJI
+
+| Purpose | Tool |
+| --- | --- |
+| workspace | `workspace_search`, `workspace_get`, `workspace_create`, `workspace_add_app` |
+| semantic folders | `resolve_dataset_folder { id, key: 'story' \| 'character' \| 'location' \| 'prop' \| 'shot' }` |
+| datasets | `fsnode_create_file { parent, name, dataset: true, datasetType, description, content, tags }`, `fsnode_update`, `fsnode_upsert_segment` |
+| assets | `asset_get`, `asset_check_status`, `asset_create_from_url` |
+| canvases | the `canvas_*` tools below |
+
+## Canvases
+
+Every canvas tool takes an explicit `canvas` id, so you can build the `characters`, `scenes`, `props`
+and per-episode canvases in one conversation. The layouts — which node in which row, and in what
+order to connect the references — are in `canvas-recipes.md`; read the CLI recipe there and
+substitute:
+
+| `canvas-recipes.md` shows | call |
+| --- | --- |
+| `wji canvas create <name>` | `canvas_create { workspace, name }` → canvas id |
+| `wji canvas add <kind> -c CV -n "<name>" --at x,y …` | `canvas_create_node { canvas, kind, name, position: {x, y}, … }` |
+| `--prompt-file /tmp/x.txt` / `-p "<prompt>"` | `generate: { prompt, model, ratio, resolution, duration }` on `canvas_create_node` |
+| `--asset <id>` (a display node) | `assetId` on `canvas_create_node` |
+| `--from A B C` | `fromNodeIds: ['A','B','C']` — **the array order is the reference order** |
+| `wji canvas connect <a> <b>` | `canvas_connect_nodes { canvas, fromId, toId }` |
+| `wji canvas get <node>` | `canvas_get_node { canvas, id }` — references, label, status, asset |
+| `wji canvas gen <node>` (cost preview) | `canvas_generate { canvas, nodeIds, estimateOnly: true }` |
+| `wji canvas gen <node> --yes --wait` | `canvas_generate { canvas, nodeIds, wait: true }` |
+| `wji canvas rm` | `canvas_delete_nodes { canvas, ids }` |
+
+Reference labels (`@image1`, `@audio1` …) are numbered per type in connection order, exactly as the
+canvas UI numbers them. After connecting, call `canvas_get_node` and check the labels match what the
+prompt names **before** generating — a mislabelled reference is a wasted generation.
+
+**Spending.** Generation costs the user credits. Call `canvas_generate` with `estimateOnly: true`
+first, tell the user the cost, and only generate for real once they say yes. The `wji` skill's
+spending policy applies here in full.
+
+**In a canvas chat** (the chat panel beside an open canvas) the browser supplies its own `canvas_*`
+tools, which always act on the canvas the user is looking at and take no `canvas` argument. A short
+drama needs several canvases, so do that work in a workspace chat; in a canvas chat, say so.

package/skill/short-drama/reference/schema.md

@@ -212,7 +212,7 @@ prompt bans hands**). At most `thresholds.maxProps` (8).
 {
   "endpoint": "https://api.wji.ai", "workspaceId": "…",
   "datasetFolders": { "story": "…", "character": "…", "location": "…", "prop": "…", "shot": "…" },
-  "canvases": { "characters": "…", "scenes": "…", "episodes": { "1": "…" } },
+  "canvases": { "characters": "…", "scenes": "…", "props": "…", "episodes": { "1": "…" } },
   "outlineDatasetId": "…", "guidelineDatasetId": "…"
 }
 ```

package/skill/short-drama/reference/stage-art.md

@@ -40,7 +40,8 @@ node {baseDir}/scripts/short-drama.mjs render <project> scene S01 > /tmp/S01.md
 wji fs set <id> --merge content=@/tmp/S01.md --merge image_prompt=@/tmp/S01-sheet.txt --merge metadata.shortDrama=@/tmp/S01.json
 ```
 
-`scenes` canvas (`canvas-recipes.md` §2): one 16:9 **sheet** node per scene and per prop; per
+`scenes` canvas (`canvas-recipes.md` §2) for the scenes and a separate `props` canvas (§2b) for
+the props: one 16:9 **sheet** node per scene and per prop; per
 extra lighting state / prop state one node `--from` the sheet (`@image1 is this exact space —
 keep structure, materials and wear identical; change only: <state prompt>`); variants `--from` the
 parent scene's sheet with the `changes` text. Sheets are single images (run), a whole batch of

package/skill/short-drama/reference/stage-storyboard.md

@@ -46,8 +46,8 @@ Three worksheets, all deleted once the segments are written:
    needs — a 15 s model wants 9–15 s runs, a 30 s model can hold a whole exchange in one.
 2. **Cut = 2–5 s**, aim at 3. A segment holds 3–5 cuts. The dialogue of the beats a cut claims
    must fit in its seconds (`chars ÷ 4.5`) — a 4.4 s line gets a 5 s cut, or two cuts.
-3. **`frame` per cut** (the prompt for that moment; in `keyframes` mode it is also the keyframe
-   image's prompt, and in the default `sheets` mode it is the shot's description inside the segment
+3. **`frame` per cut** — the shot's description inside the segment prompt (by default no image
+   is generated from it; only with `references: keyframes` does it also become the keyframe image's
    prompt): an English prompt for that moment — composition, this
    moment's positions and poses (already on the boat / still on the pier — the model trusts the
    picture over the text), the size phrase (`wide shot`, `close-up`…), the style's
@@ -363,7 +363,9 @@ sheets, put the people in a `Cast:` line of the prompt; the face will drift betw
 A look that must hold across every clip — lens, depth of field, foreground blur — goes in
 `params.lookPhrase`, which every segment prompt must carry verbatim.
 
-## Keyframes on WJI
+## Keyframes — only with `params.references: keyframes`
+
+Not the default. Read this section only when the user has chosen keyframes for a project.
 
 Each keyframe is an image node whose references are the **sheet display nodes** on the episode
 canvas, in the order the reference plan prints (environment first, then each person, then props),
@@ -378,7 +380,8 @@ every frame.
 
 **First segment first.** Generate its keyframes, download them, check against the sheets (same
 world, same faces, right size, nobody extra), fix, then continue. An episode is 30–40 keyframes;
-a wrong direction costs the whole batch.
+a wrong direction costs the whole batch — which is why this is opt-in and the default references
+the sheets directly.
 
 ## Soundtrack node — Seed Audio is not a TTS
 

package/skill/short-drama/reference/workspace-layout.md

@@ -18,6 +18,7 @@ workspace "<title>"                      wji ws create "<title>" -r <params.rati
     └── canvases/
         ├── characters   wji canvas create characters
         ├── scenes       wji canvas create scenes
+        ├── props        wji canvas create props
         ├── E01, E02 …   wji canvas create E01
         └── canvas-001   (the default one — leave it)
 ```
@@ -79,29 +80,40 @@ the headshot + sheet as image references and the voice as audio.
 Bind the node ids (`wji.nodes.*`) and, after generation, the asset ids
 (`wji.assets.*`); then attach the assets to the dataset.
 
-### `scenes` canvas — one row per scene, then one per prop
+### `scenes` canvas — one row per scene
 
 ```
 [title S01] → [image* sheet 16:9] → [image* lighting:<state> @image1=sheet] …
-[title P01] → [image* sheet 16:9 white bg] → [image* state:<state> @image1=sheet] …
 ```
 
 Variants (`variantOf`) reference the parent scene's sheet node as `@image1`.
 
+### `props` canvas — one row per prop
+
+```
+[title P01] → [image* sheet 16:9 white bg] → [image* state:<state> @image1=sheet] …
+```
+
+Bound as `wji.canvases.props`; `manifest` asks for it as soon as the project has a prop.
+
 ### `E<nn>` canvas — references on top, one block per segment
 
 ```
 row 0   [image display C01 sheet] [image display C02 sheet] [image display S01 sheet] [image display P01 sheet] [audio display C01 voice]
-row 1   [title E01-01] [image* f1 (@image = sheets in frame)] [image* f2] … → [video* E01-01 (@image1..N = keyframes or sheets, @audio1..M = the voices of whoever speaks)] [text prompt]
+row 1   [title E01-01] → [video* E01-01 (@image1..N = the sheet display nodes, @audio1..M = the voices of whoever speaks)] [audio* E01-01 track] [text prompt]
 row 2   [title E01-02] …
 ```
 
+By default the video node references the sheets directly — **no storyboard images**. Only with
+`params.references: keyframes` does row 1 gain `[image* f1] [image* f2] …` between the title and the
+video node, and the video node then references those instead of the sheets.
+
 - Display nodes: `canvas add image --asset <assetId> -n "C01 sheet"` and `canvas add audio --asset <voiceAsset> -n "C01 voice"` — record both in the episode's `wji.displayNodes` (`"C01:sheet"`, `"C01:voice"`) so every generate node can `--from` them. Pictures become `@imageN`, voices `@audioN`, numbered per type in connection order.
 - Per segment, beside the video node, a **soundtrack audio node** (`canvas add audio -n "E01-01 track" -m seed-audio-1.0 --prompt-file …`, prompt from `prompt audio E01-01`) → `storyboard.segments.E01-01.wji.nodes.track`; its asset joins the shot dataset's `images[]`.
-- Keyframe k: `canvas add image -n "E01-01 f<k>" --from <scene sheet display> <character sheet displays…> <prop sheet displays…> -m <image model> -r <params.ratio> -p "<frame prompt prefixed with what each @imageN is>"`.
-- Video: `canvas add video -n "E01-01" --from <sheet display nodes, or f1…fN in keyframes mode> <voice display nodes of everyone who speaks> -m <the mode's model> -r <params.ratio> [-d <Σ cut seconds>] --prompt-file prompt.txt`. The model and its resolution spelling come from `prompt segment` (`video.model`, `video.resolution`). `-d` **only in `videoDuration: fixed`** — it switches auto-duration off, which pins the clip to the storyboard's timestamps but also fixes the price; in `auto` (the default) leave it out and the model matches the clip to the prompt.
+- Video: `canvas add video -n "E01-01" --from <sheet display nodes in legend order> <voice display nodes of everyone who speaks> -m <the mode's model> -r <params.ratio> [-d <Σ cut seconds>] --prompt-file prompt.txt`. The model and its resolution spelling come from `prompt segment` (`video.model`, `video.resolution`). `-d` **only in `videoDuration: fixed`** — it switches auto-duration off, which pins the clip to the storyboard's timestamps but also fixes the price; in `auto` (the default) leave it out and the model matches the clip to the prompt.
 - Prompt text node: `canvas add text -n "E01-01 prompt" --text-file prompt.txt` beside the video node, for people reading the canvas.
-- Shot dataset: `dataset new <shot/E01 folder> "E01-01" -t shot -d "<one line>"`, `--set video_prompt=@prompt.txt`, images = keyframes, `primaryVideo` = the clip.
+- Keyframes (opt-in only): `canvas add image -n "E01-01 f<k>" --from <sheet display nodes> -m <image model> -r <params.ratio> -p "<plan prefix + frame>"`, and the video node then `--from f1…fN` instead of the sheets.
+- Shot dataset: `dataset new <shot/E01 folder> "E01-01" -t shot -d "<one line>"`, `--set video_prompt=@prompt.txt`, images = the soundtrack (and keyframes, if any), `primaryVideo` = the clip.
 
 Placement: `canvas add` puts a node right of its `--from` nodes; pass `--at x,y`
 for the row starts (title nodes) so blocks do not overlap. Take ids from the

package/skill/short-drama/scripts/selftest.mjs

@@ -1359,6 +1359,10 @@ const breaks = (gateId, project, episode, needle) => {
   const items = manifest(PROJECT, { 1: E01 });
   ok(items.some((i) => i.item === 'wji.workspaceId'), 'manifest asks for the workspace first');
   ok(items.some((i) => i.item === 'characters.C01.wji.datasetId'), 'manifest lists character datasets');
+  ok(items.some((i) => i.item === 'wji.canvases.scenes') && items.some((i) => i.item === 'wji.canvases.props'), 'manifest asks for a scenes canvas and a separate props canvas');
+  ok(items.find((i) => i.item === 'props.P01.wji.nodes.sheet').hint.includes('-c <props>'), 'prop sheets go on the props canvas');
+  const noProps = clone(PROJECT); noProps.props = []; noProps.outline.episodes.forEach((e) => (e.propIds = []));
+  ok(!manifest(noProps, {}).some((i) => i.item === 'wji.canvases.props'), 'no props, no props canvas');
   ok(items.some((i) => i.item === 'wji.displayNodes.S02:sheet'), 'manifest lists display nodes the episode needs');
   ok(items.some((i) => i.item === 'storyboard.segments.E01-01.wji.nodes.keyframes.4'), 'manifest lists every keyframe node');
   ok(items.some((i) => i.item === 'storyboard.segments.E01-05.wji.nodes.video'), 'manifest lists video nodes');

package/skill/short-drama/scripts/short-drama.mjs

@@ -2975,7 +2975,9 @@ export function manifest(project, episodes, opts = {}) {
     }
   }
   if (stages.includes('art')) {
-    if ((project.scenes || []).length + (project.props || []).length && !w.canvases?.scenes) add('art', 'canvas', 'wji.canvases.scenes', 'wji canvas create scenes');
+    if ((project.scenes || []).length && !w.canvases?.scenes) add('art', 'canvas', 'wji.canvases.scenes', 'wji canvas create scenes');
+    // Props get their own canvas: white-background sheets and state variants, one row per prop.
+    if ((project.props || []).length && !w.canvases?.props) add('art', 'canvas', 'wji.canvases.props', 'wji canvas create props');
     for (const s of project.scenes || []) {
       const sw = s.wji || {};
       if (!sw.datasetId) add('art', s.id, `scenes.${s.id}.wji.datasetId`, `wji dataset new <location> "${s.name}" -t location`);
@@ -2985,7 +2987,7 @@ export function manifest(project, episodes, opts = {}) {
     for (const p of project.props || []) {
       const pw = p.wji || {};
       if (!pw.datasetId) add('art', p.id, `props.${p.id}.wji.datasetId`, `wji dataset new <prop> "${p.name}" -t prop`);
-      if (!pw.nodes?.sheet) add('art', p.id, `props.${p.id}.wji.nodes.sheet`, `wji canvas add image -c <scenes> -n "${p.id} sheet" -r 16:9`);
+      if (!pw.nodes?.sheet) add('art', p.id, `props.${p.id}.wji.nodes.sheet`, `wji canvas add image -c <props> -n "${p.id} sheet" -r 16:9`);
       else if (!pw.assets?.sheet) add('art', p.id, `props.${p.id}.wji.assets.sheet`, `wji canvas gen ${pw.nodes.sheet} → asset`);
     }
   }
@@ -3156,24 +3158,41 @@ function positional(args) {
   return out;
 }
 
-function printGates(results, { all }) {
+/**
+ * The gate report as text. One writer for every surface: the CLI prints it, the
+ * WJI tool returns it. `all` keeps the passing and skipped rows (checkup).
+ */
+export function formatGates(results, { all, stage } = {}) {
+  const lines = [];
   let failed = 0;
   let notes = 0;
   for (const r of results) {
-    if (r.skipped) { if (all) console.log(`  – ${r.stage}/${r.id} · ${r.label} (skipped: ${r.skipped})`); continue; }
+    if (r.skipped) { if (all) lines.push(`  – ${r.stage}/${r.id} · ${r.label} (skipped: ${r.skipped})`); continue; }
     if (r.advisory) {
       const warnings = r.warnings || [];
       notes += warnings.length;
-      if (all || warnings.length) console.log(`  ${warnings.length ? '⚠' : '✓'} ${r.stage}/${r.id} · ${r.label} (advisory)`);
-      for (const w of warnings) console.log(`      ⚠ ${w}`);
+      if (all || warnings.length) lines.push(`  ${warnings.length ? '⚠' : '✓'} ${r.stage}/${r.id} · ${r.label} (advisory)`);
+      for (const w of warnings) lines.push(`      ⚠ ${w}`);
       continue;
     }
     const ok = !r.failures.length;
     if (!ok) failed += 1;
-    if (all || !ok) console.log(`  ${ok ? '✓' : '✗'} ${r.stage}/${r.id} · ${r.label}`);
-    for (const f of r.failures) console.log(`      - ${f}`);
+    if (all || !ok) lines.push(`  ${ok ? '✓' : '✗'} ${r.stage}/${r.id} · ${r.label}`);
+    for (const f of r.failures) lines.push(`      - ${f}`);
   }
-  return { failed, notes };
+  const hard = results.filter((r) => !r.skipped && !r.advisory).length;
+  const advisory = results.filter((r) => !r.skipped && r.advisory).length;
+  const tail = advisory ? `, ${advisory} advisory (${notes} note${notes === 1 ? '' : 's'})` : '';
+  const summary = failed
+    ? `✗ ${failed}/${hard} gate(s) failed${tail}`
+    : `✓ ${hard} gate(s) passed${stage ? ` (through ${stage})` : ''}${tail}`;
+  return { lines, text: [...lines, summary].join('\n'), summary, failed, notes, hard, advisory };
+}
+
+function printGates(results, opts) {
+  const out = formatGates(results, opts);
+  for (const line of out.lines) console.log(line);
+  return out;
 }
 
 function main(argv) {
@@ -3218,11 +3237,8 @@ function main(argv) {
     const { project, episodes } = loadProject(input, { eps });
     const ctx = makeContext(project, episodes, { eps });
     const results = runGates(ctx, { stage });
-    const { failed, notes } = printGates(results, { all: cmd === 'checkup' });
-    const hard = results.filter((r) => !r.skipped && !r.advisory).length;
-    const advisory = results.filter((r) => !r.skipped && r.advisory).length;
-    const tail = advisory ? `, ${advisory} advisory (${notes} note${notes === 1 ? '' : 's'})` : '';
-    console.log(failed ? `✗ ${failed}/${hard} gate(s) failed${tail}` : `✓ ${hard} gate(s) passed${stage ? ` (through ${stage})` : ''}${tail}`);
+    const { failed, summary } = printGates(results, { all: cmd === 'checkup', stage });
+    console.log(summary);
     return cmd === 'validate' && failed ? 1 : 0;
   }