@wji.ai/cli 0.1.1 → 0.3.0

package/README.md

@@ -165,7 +165,9 @@ wji canvas gen <node> --yes --wait                  # spends credits
 ```
 
 Changes appear live in the open canvas. Pass `--canvas <id>` to work on a
-canvas that is not linked (`wji canvas list`).
+canvas that is not linked (`wji canvas list`); `wji canvas create <name>` adds
+an empty canvas, `wji canvas add image --asset <id>` shows an existing asset
+and `wji canvas add dataset --dataset <id>` places a dataset card.
 
 ## Skills
 
@@ -240,3 +242,10 @@ cp -r "$(npm root -g)/@wji.ai/cli/skill/wji" ~/.claude/skills/wji
 
 From a source checkout: `cp -r skill/wji ~/.claude/skills/wji`. Re-copy after
 upgrading the CLI so the skill matches the commands.
+
+`skill/short-drama/` is a second skill built on top of it: an AI short-drama
+pipeline (outline → characters → scenes/props → script → storyboard) whose
+stages are checked by `skill/short-drama/scripts/short-drama.mjs validate`,
+with the data stored as workspace datasets and the work laid out on canvases.
+Install it the same way (`cp -r skill/short-drama ~/.claude/skills/short-drama`)
+next to `wji`; `node skill/short-drama/scripts/selftest.mjs` runs its self-test.

package/dist/commands/canvas.js

@@ -23,7 +23,8 @@ const NODE_PREFIX = 'canvas/node/';
 const EDGE_MIMETYPE = 'canvas/edge';
 const CANVAS_MIMETYPE = 'workspace-v2/canvas';
 const CANVASES_MIMETYPE = 'workspace-v2/canvases';
-const CREATABLE_KINDS = ['text', 'title', 'comment', 'image', 'video', 'audio'];
+const DATASET_MIMETYPE = 'workspace/dataset';
+const CREATABLE_KINDS = ['text', 'title', 'comment', 'image', 'video', 'audio', 'dataset'];
 const MEDIA_KINDS = new Set(['image', 'video', 'audio']);
 const TEXT_KINDS = new Set(['text', 'title', 'comment']);
 /** Default names the canvas UI shows localized. */
@@ -34,6 +35,12 @@ const DEFAULT_NAMES = {
     image: '图片',
     video: '视频',
     audio: '音频',
+    dataset: '数据集',
+};
+/** What the web writes into a brand-new canvas folder (CanvasAppFileSystem.createCanvas). */
+const INITIAL_CANVAS_CONTENT = {
+    data: { viewport: { x: 0, y: 0, zoom: 1 }, backgroundMode: 'dots' },
+    metadata: {},
 };
 /** The canvas lays media out on a 250px short side; text nodes are wider. */
 const MEDIA_BASE = 250;
@@ -105,6 +112,19 @@ async function loadCanvas(client, canvasId) {
         assets,
     };
 }
+/** The `canvases` folder of every InfiniteCanvas app in a workspace. */
+async function canvasesFolders(client, wsId) {
+    const ws = await client.get(`/workspace/list/${wsId}`);
+    const apps = (ws.apps || []).filter((a) => a.app === 'InfiniteCanvas' || a.type === 'INFINITE_CANVAS');
+    const out = [];
+    for (const app of apps) {
+        const tree = await client.get(`/workspace/list/${wsId}/fs/${app.id}`);
+        const folder = (tree?.children || []).find((n) => n.mimetype === CANVASES_MIMETYPE);
+        if (folder)
+            out.push({ appId: String(app.id), folderId: String(folder.id) });
+    }
+    return out;
+}
 function requireNode(canvas, id) {
     const node = canvas.byId.get(id);
     if (!node)
@@ -144,6 +164,9 @@ function describe(canvas, node) {
         assetId: node.file,
         url: asset?.url || undefined,
         assetType: asset?.type,
+        dataset: node.kind === 'dataset' && node.content.datasetId
+            ? { id: String(node.content.datasetId), name: node.content.datasetName, type: node.content.datasetType, folder: node.content.datasetParentName }
+            : undefined,
         status: generate?.historyId ? (pending ? 'generating' : asset?.error ? 'failed' : asset?.url ? 'done' : 'pending') : undefined,
         error: asset?.error?.message || asset?.error || undefined,
         generate,
@@ -152,12 +175,16 @@ function describe(canvas, node) {
     };
 }
 // ── models ──────────────────────────────────────────────────────────────────
+/** An audio node is fed by either an `audio` or a `tts` model — the backend tags voice models `tts`. */
+const KIND_FEATURES = { audio: ['audio', 'tts'] };
 async function findModel(client, kind, name, workspaceId) {
-    const rows = await fetchModels(client, { features: [kind], workspace: workspaceId });
+    const features = KIND_FEATURES[kind] ?? [kind];
+    const rows = (await Promise.all(features.map((f) => fetchModels(client, { features: [f], workspace: workspaceId })))).flat();
     const usable = rows.filter((m) => m.enabled !== false);
     const model = usable.find((m) => m.nickname === name) ?? usable.find((m) => m.name === name);
     if (!model) {
-        throw new Error(`No ${kind} model "${name}". See \`wji models list --feature ${kind}\`.`);
+        const hint = features.map((f) => `--feature ${f}`).join(' / ');
+        throw new Error(`No ${kind} model "${name}". See \`wji models list ${hint}\`.`);
     }
     return model;
 }
@@ -243,6 +270,8 @@ function applyModelDefaults(model, kind, generate, opts) {
 // ── writes ──────────────────────────────────────────────────────────────────
 /** Short side 250, like the canvas; text-ish nodes use a typical card size. */
 function estimateSize(canvas, node) {
+    if (node.kind === 'dataset')
+        return { width: 480, height: 220 };
     if (!MEDIA_KINDS.has(node.kind))
         return { width: 320, height: 200 };
     const ratioText = node.content.mode === 'generate' ? node.content.generate?.ratio : undefined;
@@ -335,6 +364,8 @@ async function patchNode(client, node, body) {
 function summary(n) {
     if (n.text !== undefined)
         return String(n.text).replace(/\s+/g, ' ');
+    if (n.dataset)
+        return [n.dataset.type, n.dataset.name, color.dim(n.dataset.id)].filter(Boolean).join(' ');
     if (n.mode === 'generate') {
         const g = n.generate || {};
         const state = n.status === 'done' ? color.green('done') : n.status === 'failed' ? color.red('failed') : n.status ? color.yellow(n.status) : '';
@@ -361,6 +392,7 @@ function printNode(n) {
         ['name', n.name],
         ['position', n.position && `${Math.round(n.position.x)},${Math.round(n.position.y)}`],
         ['text', n.text],
+        ['dataset', n.dataset && `${n.dataset.type || 'dataset'} "${n.dataset.name || ''}" ${color.dim(n.dataset.id)}${n.dataset.folder ? ` in ${n.dataset.folder}` : ''}`],
         ['asset', n.assetId],
         ['url', n.url],
         ['status', n.status],
@@ -603,17 +635,11 @@ export function canvasCommand(globals) {
         const c = client();
         const linked = opts.workspace ? null : await linkedState(c);
         const wsId = opts.workspace || linked?.workspaceId || c.requireWorkspace();
-        const ws = await c.get(`/workspace/list/${wsId}`);
-        const apps = (ws.apps || []).filter((a) => a.app === 'InfiniteCanvas' || a.type === 'INFINITE_CANVAS');
         const rows = [];
-        for (const app of apps) {
-            const tree = await c.get(`/workspace/list/${wsId}/fs/${app.id}`);
-            const folder = (tree?.children || []).find((n) => n.mimetype === CANVASES_MIMETYPE);
-            if (!folder)
-                continue;
-            const canvases = toList(await c.getFresh(`/fsnode/list/${folder.id}/children`, { limit: -1 }));
+        for (const { appId, folderId } of await canvasesFolders(c, wsId)) {
+            const canvases = toList(await c.getFresh(`/fsnode/list/${folderId}/children`, { limit: -1 }));
             for (const it of canvases.filter((n) => n.mimetype === CANVAS_MIMETYPE)) {
-                rows.push({ id: it.id, name: it.name, app: app.id, linked: it.id === linked?.canvasId, updatedAt: it.updatedAt });
+                rows.push({ id: it.id, name: it.name, app: appId, linked: it.id === linked?.canvasId, updatedAt: it.updatedAt });
             }
         }
         render(rows, () => table(rows, [
@@ -623,6 +649,36 @@ export function canvasCommand(globals) {
             { header: 'app', value: (r) => r.app },
         ]));
     });
+    canvas
+        .command('create <name>')
+        .description('Create an empty canvas in a workspace (its InfiniteCanvas app)')
+        .option('-w, --workspace <id>', 'workspace (defaults to the linked one, then the profile default)')
+        .option('--app <appId>', 'InfiniteCanvas app when the workspace has several')
+        .action(async (name, opts) => {
+        const c = client();
+        const linked = opts.workspace ? null : await linkedState(c);
+        const wsId = opts.workspace || linked?.workspaceId || c.requireWorkspace();
+        const folders = await canvasesFolders(c, wsId);
+        if (!folders.length)
+            throw new Error(`Workspace ${wsId} has no InfiniteCanvas app. Add one with \`wji ws app add canvas\`.`);
+        const target = opts.app ? folders.find((f) => f.appId === opts.app) : folders[0];
+        if (!target)
+            throw new Error(`No InfiniteCanvas app ${opts.app} in workspace ${wsId}`);
+        if (!opts.app && folders.length > 1)
+            warn(`Several InfiniteCanvas apps — using ${target.appId}; pass --app to choose`);
+        const raw = await c.post('/fsnode/create', {
+            name,
+            type: 'folder',
+            mimetype: CANVAS_MIMETYPE,
+            parent: target.folderId,
+            content: INITIAL_CANVAS_CONTENT,
+        });
+        const out = { id: raw.id, name: raw.name, app: target.appId, workspaceId: wsId };
+        render(out, () => {
+            success(`Created canvas "${out.name}" ${color.dim(out.id)}`);
+            info(color.dim(`Target it with --canvas ${out.id}, or open it in the browser and press link.`));
+        });
+    });
     canvas
         .command('nodes')
         .description('Nodes with references and a content summary (* = generate node)')
@@ -671,6 +727,7 @@ export function canvasCommand(globals) {
         .option('-t, --text <text>', 'text for text/title/comment (- reads stdin)')
         .option('--text-file <path>', 'read the text from a file')
         .option('--asset <assetId>', 'show an existing asset (display node)')
+        .option('--dataset <fsnodeId>', 'for `add dataset`: the workspace dataset node to show on the canvas')
         .option('--from <nodeIds...>', 'connect these nodes in as references, in order (@image1, @image2…)')
         .option('--at <x,y>', 'position; default is right of the --from nodes')).action(async (kind, opts) => {
         if (!CREATABLE_KINDS.includes(kind)) {
@@ -694,6 +751,28 @@ export function canvasCommand(globals) {
                 throw new Error(`${kind} nodes need --text`);
             content.text = text;
         }
+        else if (kind === 'dataset') {
+            // A dataset node is a card bound to a workspace dataset (CanvasAppFileSystem.createDatasetNodeFromDataset).
+            if (!opts.dataset)
+                throw new Error('dataset nodes need --dataset <fsnodeId>');
+            if (from.length)
+                throw new Error('dataset nodes take no references; connect them out to a generate node instead');
+            const ds = await c.getFresh(`/fsnode/list/${opts.dataset}`);
+            if (ds?.mimetype !== DATASET_MIMETYPE) {
+                throw new Error(`${opts.dataset} is not a dataset (mimetype ${ds?.mimetype || 'none'})`);
+            }
+            const parent = ds.parent ? await c.get(`/fsnode/list/${idOf(ds.parent)}`).catch(() => null) : null;
+            const dsName = ds.nickname || ds.name || DEFAULT_NAMES.dataset;
+            if (!opts.name)
+                body.name = dsName;
+            Object.assign(content, {
+                datasetId: String(ds.id),
+                datasetName: dsName,
+                datasetType: String(ds.content?.type || ''),
+                datasetParentName: parent ? parent.nickname || parent.name || '' : '',
+                description: String(ds.content?.description || ''),
+            });
+        }
         else {
             const { patch, explicit } = await generateOptions(opts);
             const wantsGenerate = Object.keys(patch).length > 0;

package/dist/commands/fsnode.js

@@ -3,6 +3,15 @@ import { WjiClient } from '../core/client.js';
 import { confirm, parseKeyValues, readJson, readValue } from '../core/prompt.js';
 import { color, detail, info, relativeTime, render, success, table, truncate } from '../core/output.js';
 import { printTree } from './workspace.js';
+/** Nested plain objects merge; arrays and scalars are replaced. */
+function deepMerge(base, patch) {
+    const out = { ...base };
+    for (const [key, value] of Object.entries(patch)) {
+        const isObject = (v) => v && typeof v === 'object' && !Array.isArray(v);
+        out[key] = isObject(value) && isObject(out[key]) ? deepMerge(out[key], value) : value;
+    }
+    return out;
+}
 export function fsCommand(globals) {
     const fs = new Command('fs')
         .aliases(['fsnode'])
@@ -106,7 +115,9 @@ export function fsCommand(globals) {
         .option('--icon <assetId>', 'set the icon asset')
         .option('--asset <assetId>', 'set the attached file asset (use "null" to clear)')
         .option('--sort <n>', 'sort order')
-        .option('--set <key=value...>', 'arbitrary field, dotted keys allowed')
+        .option('--set <key=value...>', 'arbitrary top-level field, dotted keys allowed (content.* would REPLACE content — use --merge)')
+        .option('--merge <key=value...>', 'set fields inside content, merged with the current content; values accept @file')
+        .option('--add-images <assetId...>', 'append to the image asset list instead of replacing it')
         .action(async (id, opts) => {
         const client = new WjiClient(globals());
         const body = {
@@ -120,6 +131,24 @@ export function fsCommand(globals) {
             sort: opts.sort != null ? Number(opts.sort) : undefined,
             ...parseKeyValues(opts.set),
         };
+        if (opts.merge?.length || opts.addImages?.length) {
+            // PATCH replaces `content` and `images` whole, so read first and merge.
+            const node = await client.getFresh(`/fsnode/list/${id}`);
+            if (opts.merge?.length) {
+                const pairs = [];
+                for (const pair of opts.merge) {
+                    const index = pair.indexOf('=');
+                    if (index === -1)
+                        throw new Error(`Expected key=value, got "${pair}"`);
+                    pairs.push(`${pair.slice(0, index)}=${await readValue(pair.slice(index + 1))}`);
+                }
+                body.content = deepMerge(body.content ?? node.content ?? {}, parseKeyValues(pairs));
+            }
+            if (opts.addImages?.length) {
+                const current = (opts.images ?? node.images ?? []).map((it) => (typeof it === 'string' ? it : it.id));
+                body.images = [...current, ...opts.addImages.filter((it) => !current.includes(it))];
+            }
+        }
         const updated = await client.patch(`/fsnode/list/${id}`, body);
         render(updated, (n) => success(`Updated ${n?.id || id}`));
     });

package/dist/commands/workspace.js

@@ -16,6 +16,8 @@ const APPS = {
     batch: 'Batch',
     digitalhost: 'DigitalHost',
 };
+/** Apps every new workspace gets unless `-a` or `--no-apps` says otherwise — what the drama and canvas workflows need. */
+const DEFAULT_APPS = ['dataset', 'datasetimagegeneration', 'canvas'];
 const APP_TYPES = {
     Dataset: 'DATASET',
     DatasetImageGeneration: 'DATASET_IMAGE_GENERATION',
@@ -103,10 +105,12 @@ export function workspaceCommand(globals) {
         .option('-r, --aspect-ratio <ratio>', '16:9 | 9:16 | 21:9', '16:9')
         .option('-l, --language <lang>', 'dialogue language', 'auto')
         .option('-t, --type <type>', 'workspaceType')
-        .option('-a, --app <app...>', 'apps to create, e.g. dataset files canvas')
+        .option('-a, --app <app...>', `apps to create (default: ${DEFAULT_APPS.join(' ')})`)
+        .option('--no-apps', 'create an empty workspace with no apps')
         .action(async (name, opts) => {
         const client = new WjiClient(globals());
-        const apps = (opts.app || []).map((token) => {
+        const tokens = opts.app?.length ? opts.app : opts.apps ? DEFAULT_APPS : [];
+        const apps = tokens.map((token) => {
             const { app, type } = resolveApp(token);
             return { app, type, name: app };
         });

package/package.json

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

package/skill/short-drama/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: short-drama
+description: Produce an AI short drama (短劇) on the WJI platform end to end — write it the way a commercial 短剧 is written (创作简报, 创作指引, 人物圣经, 分集目录 with 爽点 and 钩子, the 15-second hook and 30-second turns, 谈话+行动, the right 语体), adapt a story or novel into an outline, character / scene / prop bibles, per-episode scripts and storyboards, then generate the sheets, keyframes and video clips through the `wji` CLI, with data stored as workspace datasets and the work laid out on canvases (characters, scenes, one per episode). Every stage is gated by `scripts/short-drama.mjs validate`. Use whenever a task mentions short drama, 短劇 / 短剧, 分集 / 分镜 / 剧本 for AI video, or producing a serialised video story on WJI. Works together with the `wji` skill.
+---
+
+# Short drama on WJI
+
+Five stages, one project directory, one workspace. The **model writes the design fields**; the
+**script checks them** (`validate`), derives what can be derived (`seed`, `prompt`) and keeps the
+local ↔ WJI bindings (`manifest`, `bind`). Nothing is generated until its stage is green.
+
+```
+outline ──▶ characters ──▶ art ──▶ script (per episode) ──▶ storyboard (per episode)
+   │            │            │           │                        │
+ story/      character/   location/    story/                   shot/E01/  datasets
+ dataset     datasets +   prop/        screenplay               + E01 canvas: keyframes → video
+             `characters` datasets +   dataset
+             canvas       `scenes` + `props` canvases
+```
+
+`{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
+`{baseDir}/reference/dialogue-craft.md` (lines as action, 语体 rules, the polish pass). Read the
+first before stage 1 and the second before stage 4. The gates encode what those two can check.
+
+**Re-read the guideline.** The 创作指引 (`render guideline`) is the drama's top rule document.
+Print it before writing any character, any episode and any storyboard, and print the speakers'
+`render character` before writing their lines — a script that drifts from the guideline is wrong
+even when every gate is green. When the user changes a core requirement (genre, register, length,
+ending), change the guideline first, then the episodes.
+
+## Before anything else
+
+1. **Preflight WJI**: `wji auth whoami --json`, the version check from the `wji` skill,
+   `wji profile wallet` (a drama is many generations — know the balance).
+2. **Scan the message for `-auto`** (spending waiver, see the `wji` skill). Without it: one image
+   runs, video and batches ask first.
+3. **Ask the parameters once**, in one message: episodes × minutes per episode, genre, adapt
+   mode (原创 / 忠实 / 抽核 / 借壳), the 语体 (`register`: 粤语 / 大陆普通话 / 台湾国语 / 港式普通话 /
+   古装 / 年代 / 英文美式 / 英文英式 — it decides how the lines are written and the accent the video
+   model speaks), ratio (default 9:16). Offer the defaults you will use unless
+   told otherwise: `video: h3` (MiniMax H3 ref), `style: realistic`, **`references: sheets`** (no
+   storyboard images) and **`videoDuration: auto`**. Do not start Stage 1 without the first two.
+
+   **The video mode decides how the plot is cut up.** A segment is one video generation, so its
+   length is whatever the provider accepts — and that differs by a factor of two:
+
+   | `--video` | model | segment | images | voices | auto duration | prompt |
+   | --- | --- | --- | --- | --- | --- | --- |
+   | `h3` | `minimax-h3-ref` | **5–15 s** | 9 | 3 | ✗ — always `fixed` | English, keyframe-pinned |
+   | `seedance` | `seedance-2.5-ref` | **4–30 s** | 30 | 10 | ✓ | English, `@imageN` |
+   | `seedance2` | `seedance-2.0-ref` | **4–15 s** | 9 | 3 | ✓ | English, `@imageN` |
+   | `seedance2fast` | `seedance-2.0-fast-ref` | **4–15 s** | 9 | 3 | ✓ | English, `@imageN` |
+   | `wan` | `wan-3.0-ref` | **2–30 s** | 10 | 5 | ✓ | Chinese prose, **speaks the dialogue itself** |
+
+   All five take **whole seconds only**, and each has its own resolution tiers (h3: 480P / 768P /
+   2K / 4K — note there is no 720P; the Seedance pair is lowercase; wan: 480P / 720P / 1080P).
+   `validate` checks the spelling against the model. Pick the mode **before** the storyboard: the
+   same 90-second episode is 7 generations on a 15 s model and 3 on a 30 s one, and
+   `seed storyboard` computes that split for you. With `wan`, set `speechAccent` (e.g.
+   台湾口音国语) because the model speaks the lines.
+
+   **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. 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
+   `ARRI ALEXA Mini LF` / `Zeiss Supreme Prime` / `T1.5`. Every shot prompt names it verbatim, so
+   the drama looks shot on one rig; a cut can override the focal and the stop. A look the user asks
+   for on top of that (大光圈, 背景虛化, 前景模糊…) goes in `lookPhrase`.
+4. **Locate or create the project directory** (the user's choice, else next to the source):
+   ```bash
+   node {baseDir}/scripts/short-drama.mjs init <dir> --title "<title>" --episodes N --minutes M --genre "<genre>" --register 台湾国语 [--adapt 抽核] [--ratio 9:16] [--video h3|seedance|seedance2|seedance2fast|wan] [--resolution 480P|…] [--accent "台湾口音国语"] [--style photoreal|realistic|ghibli] [--references sheets|keyframes] [--duration auto|fixed] [--look "<lens phrase>"] [--lang zh]
+   # params.camera (body / lens / aperture) is edited in project.json
+   ```
+   An existing `project.json` means a resumed run: `validate` and `manifest` tell you where it stands.
+5. **Workspace**: reuse the one bound in `project.json`; otherwise create it and bind the ids
+   (`wji ws create "<title>" -r <ratio>` → `wji ws use` → find the semantic
+   folders → `bind`). Details in `reference/workspace-layout.md`.
+
+## The loop every stage follows
+
+```
+write JSON → validate --stage <stage> → fix until green → render → sync datasets → build canvas → generate → bind ids
+```
+
+- **Validate before spending.** `validate` exits 1 with the failing gates; fix each one, re-run.
+  Never generate from a red stage.
+- **Sync = publish.** `render` produces the markdown for the dataset's `content.content`; the
+  entity JSON goes to `metadata.shortDrama`; prompts to `image_prompt` / `video_prompt` /
+  `audio_prompt` (a character's voice brief). Use
+  `wji fs set --merge …` (never `--content`), `--add-images` (never `--images` on an existing node).
+- **Bind immediately.** Every id `wji` returns goes into `project.json` / `episodes/E<nn>.json`
+  with `bind` before the next command. `manifest` lists what is still unbound; run it before creating
+  anything so a resumed run never duplicates.
+- **Look at what you generated.** `wji asset download <id> -o <dir>` and open the image before
+  approving a sheet or moving to the next segment. The reference-repo lesson: one wrong sheet
+  corrupts every shot after it.
+
+## Stage 1 — Outline
+
+Read `{baseDir}/reference/stage-outline.md`.
+
+1. **Brief first**: `outline.brief` — the six judgements (logline, audience, 爽点 engine, main
+   hook, the pressures on both sides, emotional line, promise). If the user gave one line, ask
+   the focusing questions; do not invent a genre.
+2. **Skeleton**: `outline.core/keep/cut/merge/risks`, `characters[]` (id/name/tier/role/arc/from),
+   `scenes[]` (id/name/primary/reusePlan), `props[]` (id/name/function/beatIds), `beats[]`,
+   `outline.structure` (golden / escalation / climax with episode ranges) and `outline.guideline`
+   (tone, intensity, dialogue style, visual style, limits, ≥ 3 forbidden, 3–5 priorities).
+   `validate --stage outline` will still fail on `episodes` — that is expected at this point; read
+   the other gates.
+3. **Sign-off ⛔**: show the user the brief, what was cut, who was merged, where the major beats
+   land (`cutNote` / `mergeNote`) and the guideline's priorities. Do not write episode synopses
+   before they agree — a wrong skeleton wastes every downstream stage.
+4. **Episodes** in batches of ≤10 — design before prose: `function` / `task` / `change` /
+   `satisfaction` / `hookType` (the 分集目录; episode 1 grabs, 2 proves the 爽点, 3 widens the line,
+   the finale settles), then `synopsis` / `hook` / `suspense` / ids / `crowdPlan` / `warnings`;
+   `validate --stage outline` until green.
+5. Sync: `render outline` → `story/` dataset (type `outline`, `viewMode=content`), bind
+   `wji.outlineDatasetId`; `render guideline` → its own `story/` dataset `<title> 创作指引`
+   (type `outline`), bind `wji.guidelineDatasetId`.
+
+## Stage 2 — Characters
+
+Read `{baseDir}/reference/stage-characters.md`.
+
+1. Fill `oneLiner`, `profile` (with the 关系网 in `relationships`: surface / real / power / secret),
+   **`bible`** (剧情功能, 一句话人物钩子, Want vs Need, 核心误信, 核心矛盾, 受压反应, `speech` — and for leads
+   the wound, past choices, forbidden / mustFace and the arc; `craft-story.md` §7), `identityEn`,
+   `image` (portrait prompt, negative, 16:9 sheet prompt, tags) and `voice` for every character;
+   `validate --stage characters`. Two of those exist purely so a video prompt can talk about the
+   person: **`identityEn`** is the name-free way to refer to them (`the woman in her mid thirties
+   in headphones`) and **`voice.videoDirection`** is one English clause on how they speak, pasted
+   beside every line they say in every clip — written from `bible.speech`.
+2. Sync each character to a `character/` dataset (description = oneLiner, content = `render
+   character C01`, `image_prompt` = the sheet prompt, `audio_prompt` = `prompt voice C01`,
+   metadata = the JSON).
+3. `characters` canvas (`wji canvas create characters` once): per character a title node, a
+   **headshot** image node (1:1, portrait prompt), a **sheet** image node (16:9, `--from` the headshot,
+   sheet prompt prefixed with `@image1 is the face to match`), and a **voice** audio node
+   (`seed-audio-1.0`, `--from` the headshot — the model reads the face and invents a voice for it;
+   the composed prompt asks for a dry voice, because the same model also makes rooms, scores and
+   sound effects — that is what its stage-5 soundtrack nodes are for;
+   `prompt voice C01` composes the text: a parenthetical carrying age, identity, personality,
+   timbre, pitch, pace, accent and emotion, then the acted line).
+   Recipes in `reference/canvas-recipes.md`.
+4. Generate headshots first (single images run without asking; a batch of them is a batch — quote
+   the total), inspect, then sheets and voices from the approved headshots. Listen to each voice.
+   Attach all three assets — the asset list takes audio too:
+   `fs set <dataset> --add-images <headshot> <sheet> <voice> --icon <headshot> --set primaryAudio=<voice>`; bind node and asset ids.
+
+## Stage 3 — Art (scenes + props)
+
+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 (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)
+
+Read `{baseDir}/reference/stage-script.md`.
+
+1. `render guideline` and the speakers' `render character` first. Then `seed script --ep N`
+   writes `episodes/E0N.json` with target seconds, hook/cliff, claimed beats, the episode design
+   (`function` / `task` / `change` / `hookType`, `satisfactionBeat` to set) and a `seedNote`
+   (synopsis, the 爽点 to realise, register, guideline priorities, every speaker's `bible.speech`,
+   ids, previous cliff, budget). Fill `scenes[].flow` — action beats and line beats alternating,
+   **common actions only**, hook image inside the first 3 beats and by 15 s, a `turn: true` beat
+   at least every 30 s, the 爽点 on an action (`satisfactionBeat`), cliff as the last beat; lines
+   in the register, from each speaker's `speech` (`dialogue-craft.md`). Delete `seedNote` when done.
+2. `validate --stage script --ep N` — duration math, line length, speakers, hook window, the
+   rhythm, the design, filmability, upstream ids; the register gate only advises. Over budget: cut
+   actions first; under: add conflict, not small talk. When dialogue is the weakness, run the
+   polish pass: `render dialogue --ep N` → fill the 逐句校对表 → apply → re-validate.
+3. Sync: `render script --ep N` (the 短剧 episode format with the 创作自检 table) → `story/` dataset
+   `E0N 剧本` (type `screenplay`, `viewMode=content`); bind `wji.screenplayDatasetId` with `--ep N`.
+
+## Stage 5 — Storyboard (per episode)
+
+Read `{baseDir}/reference/stage-storyboard.md`.
+
+Every cut is a set-up, so besides its beats and framing it carries the **lens** (`focal`, or let the
+shot size pick it), the **key light relative to the camera** (`light.direction` from the vocabulary
+plus `light.note` saying what it picks out, what fills the shadow side and how it changes over the
+cut) and the **foreground** to throw out of focus. All three are gated and all three go into the
+prompt, alongside the camera package and each speaker's delivery.
+
+**And every cut is a shot with a job** — read `{baseDir}/reference/craft-shots.md` and
+`{baseDir}/reference/craft-motion.md` before the first storyboard. In both reference modes a cut
+carries its `purpose` (kind + what changes), its three framing axes (`angle`, `height`, `axisSide`
+against the segment's declared `axis`), its `start` / `end` boundaries (positions, facing, gaze,
+hands, held props per person — the next cut and the next segment begin where these end), its
+`motion` (cue → one visible action → landing) and `cameraNote` (a lock-off says what still moves, a
+move says why and where it ends); the segment carries its `sound` (ambience chained across the
+scene, sfx per cut, music intent) and the 爽点 / cliff scenes a `visualPlan`. `frame` stays the
+frozen start instant. `prompt segment` composes all of it into the prompt, and the prompt is
+delivery text: no ids, files or notes, subtitles off, the other person's lips closed while one
+speaks (H3), everyone bound by `@imageK` in their own shot (sheets).
+
+**Everything the node references is addressed by its label, everywhere it applies.** WJI numbers
+connected references per type, each series from 1: `@image1…` the sheets or keyframes, `@video1…`
+the previous clip when `params.videoReferences: previous` is on (continuity of grade and camera
+language — opt-in), `@audio1…` the voice samples of whoever speaks. The legend says what each one
+is, and then each label is used where it belongs — `@imageK` in the shot that anchors on it,
+`@videoK` in the sentence saying what to carry over, and **every line a character speaks names
+their `@audioN`**, at each line rather than once in the legend, because the model picks a voice per
+line. All of it is gated. `prompt segment` prints the references in the exact order the video node
+must be connected: pictures, then clips, then voices.
+
+1. `seed storyboard --ep N` adds `storyboard.plan`, `storyboard.seedScenes` (every beat with its
+   computed seconds, an axis hint per scene) and `storyboard.visualPlans` (the worksheet for the
+   爽点 scene and the cliff scene — fill it before cutting them). **Follow the plan**: it reads the chosen model's duration range and says how
+   many segments each scene needs and how long each should be — the split follows the model, not
+   the story's own rhythm, because a segment is one generation and cannot outlast what the provider
+   accepts. Then cut the episode into those **segments** (one scene each,
+   `minSegmentSeconds`–`maxSegmentSeconds`, whole seconds) of **cuts** (2–5 s, claiming consecutive
+   beats). Per cut: `purpose`, `angle` / `height` / `axisSide`, `start` (first cut) and `end`,
+   `motion`, `cameraNote`, light / foreground / `background`, then the `frame` (the start instant);
+   per segment `axis` and `sound`. Then the segment `prompt` — take the skeleton from
+   `prompt <project> segment E0N-01` and fill in the descriptions. Delete `seedScenes` and `plan`
+   when done. `validate --stage storyboard --ep N` (the advisory `storyboard-advice` only notes).
+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`), 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
+   `sound.music.cues` — and `canvas add audio -m seed-audio-1.0 --prompt-file …` makes it (~0.15
+   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 <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
+  content filter (`DataInspectionFailed`) charge nothing and are partly random — retry the same node
+  8–12 times, then **shorten** the prompt (that, not rewording, is what clears a stuck one).
+
+## Reporting
+
+One line per stage when you stop: what exists (counts), what was generated and the credits
+actually charged (the `credits` line of each result, not the estimate), what `manifest` still
+lists, and any gate you had to fix. If a generation failed, say which and why — never resubmit a
+node whose status is `generating`.
+
+## Rules specific to this skill
+
+- **The user signs off the brief + outline skeleton and the first segment's keyframes.**
+  Everything else runs on the `wji` spending table.
+- **The guideline outranks a good idea.** A single episode's idea that conflicts with
+  `outline.guideline` is either dropped or the guideline is changed with the user first.
+- **Ids are stable.** Never renumber `C01` / `S01` / `P01` / `B01` / `E01-01` after a dataset or node
+  is bound; add new ids at the end.
+- **Prompts never carry names.** Faces come from the sheet references; `validate` rejects a name
+  or alias in any English prompt.
+- **The voice sample is a reference, not a deliverable.** 3–5 s, acted, generated from the
+  headshot; it connects to later video nodes as `@audio1` to hold the timbre the way the sheet
+  holds the face.
+- **In `wan` mode the dialogue audio also comes from the video model** — the video model speaks the lines from the segment
+  prompt's 音频 line. Fill the `voice` fields anyway; they are the register, and the gate wants them.
+- **One style for the whole drama** (`params.style`). Changing it later means regenerating every
+  sheet — say so before doing it.
+- **Keyframes at `params.ratio`, sheets at 16:9.** A 9:16 drama still gets landscape sheets.
+- **Don't fight a gate by loosening `params`** unless the user asks; the thresholds encode
+  production limits (H3 15 s, 2–5 s attention span, one breath per line).
+
+## Self-test
+
+```bash
+node {baseDir}/scripts/selftest.mjs      # no model calls, every gate has a breaking case
+node {baseDir}/scripts/short-drama.mjs validate {baseDir}/examples/night-shift
+```
+
+`examples/night-shift` — 《夜班便利店》, 3 × 1 min, three characters, two scenes, one prop, episode 1
+scripted and storyboarded in H3 mode — passes every gate (the register gate is advisory and clean)
+and is the reference for the shape of every field, the brief, the guideline and the bibles
+included.