@wji.ai/cli 0.4.0 → 0.5.0

package/dist/core/npc.js

@@ -0,0 +1,108 @@
+import { isObjectId } from './client.js';
+/**
+ * NPC City residents (NPCs). Search endpoints return raw entities (`owner` is
+ * an id); get / create / patch return the presented shape (`owner` is
+ * `{id,name,avatarUrl}`). Everything the CLI prints reads fields both share.
+ */
+export const RESIDENTS = '/npc-city/residents';
+export const NPC_STATUSES = ['active', 'debut', 'hiatus'];
+export const NPC_VISIBILITIES = ['public', 'private'];
+/** Work-history entry types; the server turns anything else into `event`. */
+export const NPC_JOB_TYPES = ['concert', 'release', 'collaboration', 'brand', 'event', 'ad', 'appearance'];
+/** How people refer to a resident: `NAME (@handle)`. */
+export const npcLabel = (r) => (r?.handle ? `${r.name} (${r.handle})` : String(r?.name ?? r?.id ?? ''));
+/** Every resident the caller manages in the current org context (`--org`). */
+export async function listMyNpcs(client) {
+    const out = [];
+    for (let page = 1; page <= 50; page++) {
+        const res = await client.getFresh(`${RESIDENTS}/mine`, { page, limit: 100 });
+        out.push(...(res?.data || []));
+        if (!res?.pagination?.hasNext)
+            break;
+    }
+    return out;
+}
+/**
+ * A resident from what a person would type: id, `@handle` (or the handle
+ * without `@`), exact name, else a unique name/handle prefix among yours; an
+ * `@handle` that isn't yours falls back to the public directory. Ambiguity is
+ * an error, never a guess. Returns the presented resident.
+ */
+export async function resolveNpc(client, token) {
+    const t = token.trim();
+    if (isObjectId(t))
+        return client.getFresh(`${RESIDENTS}/${t}`);
+    const mine = await listMyNpcs(client);
+    const lower = t.toLowerCase();
+    const handle = lower.startsWith('@') ? lower : `@${lower}`;
+    const pick = (r) => client.getFresh(`${RESIDENTS}/${r.id}`);
+    const byHandle = mine.filter((r) => String(r.handle || '').toLowerCase() === handle);
+    if (byHandle.length === 1)
+        return pick(byHandle[0]);
+    const byName = mine.filter((r) => String(r.name || '').toLowerCase() === lower);
+    if (byName.length === 1)
+        return pick(byName[0]);
+    if (byName.length > 1) {
+        throw new Error(`Several NPCs are called "${t}": ${byName.map(npcLabel).join(', ')} — use the @handle or id`);
+    }
+    const bare = lower.replace(/^@/, '');
+    const prefix = mine.filter((r) => String(r.name || '').toLowerCase().startsWith(bare) ||
+        String(r.handle || '').toLowerCase().replace(/^@/, '').startsWith(bare));
+    if (prefix.length === 1)
+        return pick(prefix[0]);
+    if (prefix.length > 1)
+        throw new Error(`"${t}" matches several NPCs: ${prefix.map(npcLabel).join(', ')}`);
+    // Someone else's public NPC (e.g. to credit it on a Backreel post).
+    if (t.startsWith('@')) {
+        const pub = await client.getFresh(`${RESIDENTS}/by-handle/${encodeURIComponent(t)}`).catch(() => undefined);
+        if (pub?.id)
+            return pub;
+    }
+    throw new Error(`No NPC "${t}" among yours. See \`wji npc list\`; org-owned NPCs need \`--org <orgId>\`.`);
+}
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * A job from CLI flags, validated here because the server silently drops
+ * entries without a title or date and rewrites unknown types to `event`.
+ * With `base` the flags are merged onto an existing job (`job set`).
+ */
+export function parseJob(opts, base) {
+    const job = {
+        type: opts.type ?? base?.type ?? '',
+        title: opts.title ?? base?.title ?? '',
+        detail: opts.detail ?? base?.detail ?? '',
+        date: opts.date ?? base?.date ?? '',
+    };
+    const location = opts.location ?? base?.location;
+    const url = opts.url ?? base?.url;
+    if (location)
+        job.location = location;
+    if (url)
+        job.url = url;
+    if (!NPC_JOB_TYPES.includes(job.type)) {
+        throw new Error(`Job type must be one of ${NPC_JOB_TYPES.join(', ')} (got "${job.type}")`);
+    }
+    if (!job.title.trim())
+        throw new Error('A job needs --title');
+    if (!DATE_RE.test(job.date))
+        throw new Error(`A job needs --date as YYYY-MM-DD (got "${job.date}")`);
+    return job;
+}
+/** Jobs have no ids: read the array fresh, change it, write it back whole. */
+export async function updateJobs(client, id, fn) {
+    const current = await client.getFresh(`${RESIDENTS}/${id}`);
+    const jobs = fn([...(current.jobs || [])]);
+    return client.patch(`${RESIDENTS}/${id}`, { jobs });
+}
+/** 1-based positions from the command line, checked against the list length. */
+export function parsePositions(values, length) {
+    const out = values.map((v) => {
+        const n = Number(v);
+        if (!Number.isInteger(n) || n < 1 || n > length) {
+            throw new Error(`No #${v} — there ${length === 1 ? 'is 1 entry' : `are ${length} entries`}`);
+        }
+        return n - 1;
+    });
+    return [...new Set(out)].sort((a, b) => a - b);
+}
+export const today = () => new Date().toISOString().slice(0, 10);

package/dist/core/output.js

@@ -136,8 +136,10 @@ export function relativeTime(value) {
         [60000, 'm'],
     ];
     for (const [ms, label] of units) {
-        if (Math.abs(diff) >= ms)
-            return `${Math.round(diff / ms)}${label} ago`;
+        if (Math.abs(diff) >= ms) {
+            const n = Math.round(Math.abs(diff) / ms);
+            return diff >= 0 ? `${n}${label} ago` : `in ${n}${label}`;
+        }
     }
     return 'just now';
 }

package/dist/index.js

@@ -17,6 +17,9 @@ import { presetCommand } from './commands/preset.js';
 import { skillCommand } from './commands/skill.js';
 import { canvasCommand } from './commands/canvas.js';
 import { crewCommand } from './commands/crew.js';
+import { classCommand } from './commands/class.js';
+import { npcCommand } from './commands/npc.js';
+import { backreelCommand } from './commands/backreel.js';
 // Read from package.json so `wji --version` cannot drift from the published
 // version — the skill compares the two to detect a stale install.
 const VERSION = createRequire(import.meta.url)('../package.json').version;
@@ -69,6 +72,9 @@ program.addCommand(presetCommand(globals));
 program.addCommand(skillCommand(globals));
 program.addCommand(canvasCommand(globals));
 program.addCommand(crewCommand(globals));
+program.addCommand(classCommand(globals));
+program.addCommand(npcCommand(globals));
+program.addCommand(backreelCommand(globals));
 program.addHelpText('after', `
 Examples:
   wji auth login --email you@example.com
@@ -79,6 +85,8 @@ Examples:
   wji fs tree $(wji ws get --json | jq -r .id) --depth 2
   wji asset upload ./reference.png --workspace <id>
   wji canvas status                 # after pressing the link button on a canvas
+  wji npc job add @mika -t concert --title "Neon Night" --date 2026-10-01
+  wji backreel credit add <postId> --npc @mika --role "飾 阿明" --job appearance
 
 Auth precedence: --token > $WJI_TOKEN / $WJI_API_KEY > profile apiKey > profile accessToken.
 Config lives in ~/.wji/config.json (chmod 600).`);

package/package.json

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

package/skill/short-drama/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Produce an AI short drama (短劇), a medium drama (中劇, 4–15-minute episodes) or a movie written in ~5-minute parts 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, 短劇 / 短剧, 中剧, a series or a movie / 电影 / 微电影 made with AI video, 分集 / 分镜 / 剧本 for AI video, or producing a serialised or feature-length video story on WJI. Works together with the `wji` skill.
 ---
 
 # Short drama on WJI
@@ -51,10 +51,13 @@ ending), change the guideline first, then the episodes.
    `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
+3. **Ask the parameters once**, in one message: the **format** (`short` 短剧 1–3-minute episodes,
+   `medium` 中剧 4–15-minute episodes, `movie` 电影 written as ~5-minute parts — read
+   `{baseDir}/reference/format.md`; the pipeline and the story structure are the same, the rhythm
+   and the genre counts scale), episodes (or parts) × minutes each, 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
+   model speaks), ratio (default 9:16 for short, 16:9 for medium and movie). 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.
 
@@ -89,9 +92,47 @@ ending), change the guideline first, then the episodes.
    `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`.
+
+   **The cinematography** is `params.cinematography`, the drama's lighting and composition preset.
+   `init` picks it from the genre: `costume-idol` (古偶 / 仙侠: luminous, gauze and backlit silk) or
+   `costume-dark` (权谋 / 武侠 / 写实: candles, torches, lattice light, faces in shadow) for 古装 —
+   a bare 古装 gets `costume-idol`, so confirm it with the user; `period-nostalgia` for 年代 / 怀旧
+   (film grain, warm faded colour, window sun and bare bulbs); `scifi-hard` for 硬科幻 (instrument
+   panels, work lamps, one harsh sun, no magic or floating holograms) and `scifi-soft` for 软科幻 /
+   科幻 / 赛博朋克 / 未来 (holograms, neon, dual-tone colour, haze) — a bare 科幻 gets `scifi-soft`,
+   confirm it; `sweet-romance` for 甜宠 / 恋爱 /
+   韩风唯美 (bright soft light, a warm halo in the hair, pastel); `low-key` for everything else
+   (the scene's own practicals, people in shadow, side / back / rim light). The costume and period
+   presets refuse light sources their era did not have, and `scifi-hard` refuses magic and floating
+   holograms. The preset is gated from the scene lighting
+   states through every cut to the video prompt's Look line. Read
+   `{baseDir}/reference/cinematography.md`, then the chosen preset's guide. Pass
+   `--cinematography` when the genre mixes both (ask the user which way the picture leans), and
+   `none` only when the user wants a look that fits neither.
+
+   **Genre is composed, not picked.** Besides the look, a drama has an action style
+   (`params.action`: `gun-fu` · `hk-kungfu` · `wuxia-fantasy` · `historical-realist` ·
+   `bullet-time` · `superhero` · `street-brawl` · `car-chase`), a comedy style (`params.comedy`:
+   `slapstick` · `deadpan` · `romcom`), and a default **grammar** (`params.grammar`: `drama` ·
+   `action` · `faceslap` · `comedy`) for segments that do not name their own. `init` reads all of
+   them from the genre (古装喜剧 → `costume-idol` + `comedy` + `slapstick`; 未来动作 → `low-key` +
+   `bullet-time`). Confirm the composition with the user; when the story has fights or gags and
+   the style is `none`, ask. The recipes table is in `{baseDir}/reference/grammar.md`.
+   **The story genres** are `params.story`, a list that combines: `revenge` 复仇/逆袭 · `sweet` 甜宠 ·
+   `mystery` 悬疑 · `comedy` 喜剧 · `angst` 虐恋 · `family` 家庭伦理 · `palace` 宫斗/权谋 · `cultivation`
+   玄幻/修仙/系统 · `scifi` 科幻 · `horror` 恐怖/灵异. `params.market` (`mainland` / `overseas`) decides
+   whether the supernatural may be real. They decide how the story is *written*: what the outline must
+   track (a payback ladder, romance milestones, a question and clue ledger, running gags) and the
+   genre rules it is held to. `init` reads them from the genre; confirm them with the user — read
+   `{baseDir}/reference/story.md`.
+   **Composition** is its own axis: `params.composition: art-first` (艺术优先) frames any genre for
+   negative space, symmetry and monumental scale — every cut names its devices
+   (`composition: [...]`), gated; read `{baseDir}/reference/composition-art-first.md`. A segment
+   may override it (`"composition": "standard"` for a chaotic fight).
+   `params.violence` is `blood` (default) or `implied`.
 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]
+   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>"] [--cinematography low-key|sweet-romance|period-nostalgia|costume-idol|costume-dark|scifi-hard|scifi-soft|none] [--action gun-fu|hk-kungfu|wuxia-fantasy|historical-realist|bullet-time|superhero|street-brawl|car-chase|none] [--violence blood|implied] [--grammar drama|action|faceslap|comedy] [--comedy slapstick|deadpan|romcom|none] [--composition standard|art-first] [--story revenge,sweet,…] [--market mainland|overseas] [--format short|medium|movie] [--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.
@@ -129,10 +170,18 @@ Read `{baseDir}/reference/stage-outline.md`.
    `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).
+   **Per story genre** (`params.story`), read its guide (`{baseDir}/reference/story-<genre>.md`)
+   and write its ledger with the skeleton: the antagonist tiers and the payback ladder
+   (`revenge`), the romance milestones (`sweet`), the central question, the culprit and the clue
+   ledger (`mystery`), the comic premise, comic flaws and running gags (`comedy`), the 虐/悔/追 beats
+   and the engineered misbelief (`angst`), the family web, secrets and reconciliations (`family`),
+   the rank ladder, schemes and factions (`palace`), the power system, 金手指 and upgrade log
+   (`cultivation`), the novum, world rules and countdown (`scifi`), the threat, its rules and the
+   scare log (`horror`).
    `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
+   land (`cutNote` / `mergeNote`), the guideline's priorities and the genre ledgers. 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,
@@ -173,10 +222,11 @@ Read `{baseDir}/reference/stage-characters.md`.
 
 ## Stage 3 — Art (scenes + props)
 
-Read `{baseDir}/reference/stage-art.md`.
+Read `{baseDir}/reference/stage-art.md`, and the cinematography preset's guide
+(`{baseDir}/reference/cinematography-<preset>.md`, §1 and §2) before writing a lighting state.
 
 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):
+   in (in the preset's look, lit by named sources), 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`):
@@ -194,7 +244,10 @@ Read `{baseDir}/reference/stage-script.md`.
    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.
+   in the register, from each speaker's `speech` (`dialogue-craft.md`). Genre markers on the beats:
+   `clue: "K1"` on the beat that plants a mystery clue in its plant episode; `gag: setup / build /
+   punchline` and `runningGag` in a comedy (a setup before every punchline, punchlines ≤ 20 字).
+   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
@@ -212,6 +265,31 @@ plus `light.note` saying what it picks out, what fills the shadow side and how i
 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.
 
+**Every cut is lit and composed in the preset's look.** Read the preset's guide
+(`{baseDir}/reference/cinematography-<preset>.md`) before the first storyboard. Name the source
+in `light.source`, stage the person against it, and choose the camera side that gives the
+preset's preferred direction (the table in `cinematography.md`). Compose as the guide says,
+shoot past a foreground, and stay within the preset's stop (T2.8; T2 for `sweet-romance` and `costume-idol`, which
+start on a T1.3 package and name their bokeh; T4 for `period-nostalgia`). Both costume presets (`costume-idol`, `costume-dark`) also need a 全景 / 大全景 with negative
+space in every segment.
+For `sweet-romance` and `costume-idol`, shoot the 甜宠 set pieces (心动对视, 回眸, 共伞…) as
+`cinematography-sweet-romance.md` §6 lays out.
+
+**Each segment is cut in its grammar.** Set `grammar` on a segment whose kind differs from the
+drama's default (`"action"`, `"faceslap"`, `"comedy"`, `"drama"`, or several:
+`["action", "comedy"]`) and read `{baseDir}/reference/grammar.md` plus the guide of each grammar
+used before cutting it:
+- `action` (`action.md`, `action-<style>.md`) — break the fight into moves (拆招): one move per
+  cut (`move: { kind, impact }`), open on a wide, a reaction or consequence after every impact.
+- `faceslap` (`grammar-faceslap.md`) — pressure, the calm, the entrance, **the proof on screen**,
+  **a cascade of at least two reactions**. The 爽点 of a 打脸 / 身份揭露 / 智商碾压 / 复仇 episode
+  is cut this way.
+- `comedy` (`grammar-comedy.md`) — **a setup before every punchline** (`gag`), **laugh room
+  after it**, in the comedy style's rhythm.
+The bold rules are gated. Waive one for a segment (`exceptions: [{ rule, reason }]`) only when the
+user asks for it, never to turn a gate green. `prompt segment` writes each grammar's line
+(`Action:` / `Payoff:` / `Comedy:`). No film, franchise or performer names in any prompt (gated).
+
 **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`

package/skill/short-drama/reference/action-bullet-time.md

@@ -0,0 +1,47 @@
+# Action style `bullet-time` — 子弹时间
+
+**The fight:** time itself is the effect. At the peak of a move, time slows to a near freeze; the
+camera **orbits the frozen moment**; bullets crawl through the air leaving rippling trails;
+debris, casings and raindrops hang suspended; then everything snaps back to full speed. Between
+those moments, the fighting is sleek, acrobatic and precise. Shared rules and fields: `action.md`.
+
+**Look:** `low-key`, graded cold (green-cyan or steel blue) with hard highlights; sleek black
+clothing, sunglasses, long coats. Lobbies with pillars, rooftops, subway platforms, rain.
+
+## Rhythm and coverage
+
+- **Cuts are medium to long** (3–5 s), because the frozen moment needs time to be circled.
+- **Sizes**: medium and wide around the frozen moment (the whole body mid-air, the bullets in
+  frame); extreme-close for a bullet or a drop of water.
+- **Camera**: the **`Arc Shot`** is the style — at least one per fight, circling a subject frozen
+  mid-move. `Push In` to a bullet; `Static Shot` for the snap back to speed.
+- **Speed**: the freeze and the snap back are **two cuts** (one move per cut, gated): the frozen
+  cut says `time slows to a near freeze as …, in slow motion`, the next cut says `time snaps back
+  to full speed as …`. One freeze per sequence: too many and none of them lands.
+
+## Signature sequences
+
+| sequence | cuts |
+| --- | --- |
+| **the dodge** | wide: the gunman fires across the rooftop (shot) → medium, Arc Shot: time freezes as she bends backwards, bullets crawling past above her with rippling trails (dodge, slow motion) → wide: time snaps back and she springs upright (consequence) |
+| **the frozen kick** | medium: he leaps into a spinning kick (leap) → medium, Arc Shot: time freezes mid-air, the camera circling him, rain suspended (kick, slow motion) → close: the kick lands at full speed (kick, impact) → wide: the opponent crashes through a pillar (consequence) |
+| **the lobby** | wide: the pillared lobby, guards turning (establish) → medium: she fires, casings hanging in the air in slow motion (shot, impact) → wide: pillar fragments exploding and hanging, then falling (consequence) |
+| **the bullet** | extreme-close: a bullet crawling through the air, the air rippling around it (shot, slow motion) → close: his raised hand, the bullet stopping in front of his palm (power) |
+
+## Sound
+
+The world slowing: sounds stretching and dropping in pitch, a deep boom, a single heartbeat, then
+everything snapping back loud. Music: electronic, pulsing; `drop` into the freeze, `enter` hard on
+the snap back.
+
+## Example `motion.action`
+
+- `she bends backwards as the bullets pass above her, in slow motion`
+- `time freezes as he spins into the kick mid-air, in slow motion` (the next cut: `time snaps back to full speed as the kick lands`)
+- `a bullet crawls toward his palm and stops in the air`
+
+## Review questions
+
+- Is there an Arc Shot around a frozen moment?
+- Can you see the bullets, the casings, the rain hanging in the air?
+- Does time snap back hard after the freeze?

package/skill/short-drama/reference/action-car-chase.md

@@ -0,0 +1,51 @@
+# Action style `car-chase` — 飞车追逐
+
+**The chase:** speed you can feel, cut between **inside** (the driver's hands, eyes, the mirror)
+and **outside** (the cars racing low past the camera, drifting through turns, near misses with
+traffic), building to a crash or an escape. A manoeuvre is a move: one swerve, drift, ram or
+crash per cut. Shared rules and fields: `action.md`.
+
+**Look:** `none` for daylight, `low-key` for night streets (tail lights and neon streaking in the
+windows, wet asphalt).
+
+## Rhythm and coverage
+
+- **Cuts are short**: 2–3 s, getting shorter toward the crash.
+- **Sizes**: wide and extreme wide outside (the cars in the street, the traffic, the turn);
+  medium and close inside (the driver, the gear stick, the mirror with the pursuer in it).
+- **Camera**: `Tracking Shot` low alongside the car (the style's shot), a static camera at road
+  level as a car roars past, `Pan Left` / `Pan Right` following a drift, `Shake Slightly` inside
+  the car.
+- **Alternate inside and outside**: never three outside cuts in a row without the driver's face.
+
+## Signature sequences
+
+| sequence | cuts |
+| --- | --- |
+| **the start** | close: the driver's hand on the gear stick (establish) → wide, road level: the car tears away, tyres smoking (chase) → close: the mirror, headlights appearing behind (pressure) |
+| **the drift** | wide, high: the car slides sideways through the intersection (swerve) → medium inside: the driver fighting the wheel (performance) → wide: the pursuer misses the turn (consequence) |
+| **the near miss** | low tracking: the car weaves between two trucks (swerve) → close inside: her eyes (reaction) → wide: the truck's mirror clipped off (consequence) |
+| **the ram** | medium: the pursuer rams the rear bumper (crash, impact) → medium inside: the driver thrown forward (reaction) |
+| **the crash** | wide: the pursuer's car hits the barrier and rolls (crash, impact) → wide: it comes to rest upside down, wheels spinning (consequence) → close inside: the driver breathing, watching it in the mirror (reaction) |
+
+## Staging
+
+City streets at night, highways, tunnels, markets the car smashes through, mountain roads,
+docks. Traffic is part of the choreography: trucks, buses, scooters, a crossing pedestrian.
+
+## Sound
+
+Engines rising and falling through the gears, tyres screeching, horns doppler-shifting past,
+metal crunching, glass, then the silence after the crash. Music: driving; `drop` at the crash.
+
+## Example `motion.action`
+
+- `the car slides sideways through the intersection`
+- `the black sedan rams the rear bumper`
+- `she shifts down and floors the pedal`
+
+## Review questions
+
+- Is there a low tracking shot alongside the car?
+- Do inside and outside alternate, with the driver's face every few cuts?
+- Does the chase build to a crash, an escape or a stop?

package/skill/short-drama/reference/action-gun-fu.md

@@ -0,0 +1,52 @@
+# Action style `gun-fu` — 近身枪斗
+
+**The fight:** a professional working. Guns at arm's length, fused with throws, joint locks and
+takedowns; every move efficient, nothing wasted. The camera stays back and **lets the whole body
+be seen** in long takes, so the audience believes the skill. Violence is fast, clean and
+procedural: reload, clear the room, move on. Shared rules and fields: `action.md`.
+
+**Look:** `low-key` (neon, wet streets, a club, a hotel corridor, a concrete stairwell). Colour
+from practicals: magenta and cyan neon, sodium orange, muzzle flash.
+
+## Rhythm and coverage
+
+- **Cuts are long**: 4–5 s is normal (average 3.5–5 s). Fewer, longer cuts than any other style.
+- **Sizes are wide and medium**: the body in the frame, head to shoes. Close-ups are for the
+  gun (a reload insert) and the eyes (the decision), not for the blows.
+- **Camera**: `Tracking Shot` following the fighter down a corridor, `Truck Left` / `Truck Right`
+  alongside a room clear, `Static Shot` wides for an exchange. Almost no shake: the camera is as
+  controlled as the fighter.
+- **Speed**: real time. No slow motion except, rarely, the last shot of a sequence.
+
+## Signature sequences
+
+| sequence | cuts |
+| --- | --- |
+| **the room clear** | wide: he enters, three men turn (establish) → medium tracking: he fires at the first (shot, impact) → wide: the man drops (consequence) → medium: he throws the second over his hip (throw, impact) → close: the second hits the floor (reaction) → medium: he fires down at him (shot) |
+| **the reload** | medium: slide locks back, empty → extreme-close insert: the magazine drops and the new one slams in (reload) → medium: he raises the gun as the next man rounds the corner |
+| **gun and grapple** | medium: the enemy grabs his gun arm (grapple) → medium: he twists the arm into a lock (grapple) → close: the enemy's face hits the wall (reaction) |
+| **the stairwell** | high wide down the stairwell: the fighters on two landings (establish) → medium: he fires up through the gap (shot) → wide: a body falls past the rail (consequence) |
+
+## Staging and props
+
+Corridors, stairwells, clubs, glass rooms, car parks: spaces with lines and cover. Tactical
+suits, holsters, suppressors. Spent casings on the floor are the style's detail, and each fight
+ends in a room of stillness and smoke.
+
+## Sound
+
+Suppressed and unsuppressed shots with real weight, casings tinkling, the slide racking, bodies
+hitting floors, heavy breath. Music: a driving low synth or bass under the whole fight
+(`enter` on the first shot, `drop` for the final one).
+
+## Example `motion.action` (one move each)
+
+- `he fires twice into the chest of the man at the bar` (one move: the shot)
+- `he hooks the man's arm and throws him over his hip onto the tiles`
+- `the empty magazine drops and he slams in a new one`
+
+## Review questions
+
+- Can you see the whole body in the blows? Is the cut long enough to believe it?
+- Does each cut hold one move, and does the next cut show what it did?
+- Is there a reload, a grapple and a moment of stillness after?

package/skill/short-drama/reference/action-historical-realist.md

@@ -0,0 +1,50 @@
+# Action style `historical-realist` — 写实冷兵器
+
+**The fight:** heavy, clumsy, desperate and final. Swords and spears have real weight; fighters
+tire, slip in the mud, gasp inside armour; exchanges are short because a blade ends them. No
+flying, no flourishes: the drama is the standoff before and the exhaustion after. Shared rules
+and fields: `action.md`.
+
+**Look:** `costume-dark` (firelight, smoke, earthy texture). Rain, mud and grey sky suit it.
+
+## Rhythm and coverage
+
+- **Cuts are medium**: 2.5–4 s. The standoff can hold longer; the clash itself is quick.
+- **Sizes**: medium and close, inside the fight, with a wide to open (the geography, the scale of
+  the battle) and to reset.
+- **Camera**: handheld — `Shake Slightly` inside the fight, `Shake Strongly` in the chaos of a
+  battle — close to the fighters, low. `Static Shot` for the standoff.
+- **Speed**: real time. At most one slow cut: the aftermath, the fighter on his knees.
+
+## Signature sequences
+
+| sequence | cuts |
+| --- | --- |
+| **the standoff** | wide: two fighters facing across the mud, rain falling (establish) → close: his hand tightening on the hilt (stance) → close: her eyes (pressure) |
+| **the clash** | medium handheld: he charges and swings (slash) → close: the blades bind, grinding (block, impact) → medium: she shoves him back into the mud (reaction) |
+| **the killing blow** | medium: the spear thrusts in (stab, impact) → close: his face as it lands (reaction) → wide: he sinks to his knees in the rain (consequence) |
+| **the battlefield** | extreme wide: two lines of soldiers in the smoke (establish) → medium handheld: the hero in the press, shields crashing (grapple) → close: a man falls at his feet (consequence) → wide: the hero alone in the smoke, breathing (performance) |
+| **after** | medium: the victor leaning on the sword, breath steaming, blood on the blade (performance) |
+
+## Staging and props
+
+Muddy courtyards, rain, city walls, burning villages, forests, battlefields in smoke. Armour that
+creaks, dented helmets, notched blades, torn cloth. Blood, if `params.violence: blood`, is real
+and restrained: on the blade, on the hands, spattered on a face.
+
+## Sound
+
+Metal on metal, armour creaking, feet in mud, grunts and ragged breath, rain, the silence after.
+Music: low drums or nothing; the style often plays better with no score.
+
+## Example `motion.action`
+
+- `he swings the heavy blade down at her shoulder`
+- `she catches it on her own blade and the two edges grind together`
+- `he sinks to his knees in the mud, the sword slipping from his hand`
+
+## Review questions
+
+- Does the weapon feel heavy? Does anyone tire?
+- Is there a standoff before and a silence after?
+- Is the camera close and handheld inside the fight?

package/skill/short-drama/reference/action-hk-kungfu.md

@@ -0,0 +1,54 @@
+# Action style `hk-kungfu` — 港式功夫
+
+**The fight:** crisp, fast, readable kung fu. Every strike and block is framed full-body so the
+audience can follow the exchange; the hero uses **whatever is to hand** (a chair, a ladder, a
+bench, a mop, a steamer basket); the key hit lands with a speed ramp and is **shown twice from
+two angles**; and between blows there is physical comedy: the shaken hand after hitting a
+pot, the look to camera. Shared rules and fields: `action.md`.
+
+**Look:** `none` or `low-key`. The moves must read, so the light is clearer than a thriller's: a
+market, a restaurant kitchen, a warehouse, a construction site, a tea house.
+
+## Rhythm and coverage
+
+- **Cuts are short**: 2–3 s (average 2–3 s; the 2 s minimum is the floor). Speed comes from the
+  rhythm of short cuts and ramps, not from 1-second cuts the model cannot render cleanly.
+- **Sizes**: a locked-off **wide or medium** for the exchange, full body, both fighters in frame;
+  inserts on the prop and the hit.
+- **Camera**: mostly `Static Shot` so the choreography reads; a quick `Pan Left` / `Pan Right`
+  (whip-like) to follow a throw; `Push In` on the comic reaction.
+- **Speed**: write the ramp into the cut (`in a speed ramp, the kick slows at the moment of
+  contact and snaps back`). **The repeat**: the decisive hit is cut twice, the second from a
+  new angle (the 3-hit repeat for the big one).
+
+## Signature sequences
+
+| sequence | cuts |
+| --- | --- |
+| **the prop fight** | wide: he backs into a kitchen, cleavers and pans everywhere (establish) → medium: he snatches a pan from the stove (draw) → medium: he blocks a pole with the pan (block, impact) → close: the pan rings and he shakes his stinging hand (reaction, comedy) |
+| **the repeat hit** | wide: the villain charges (establish) → medium: the hero's flying kick lands, speed ramp (kick, impact) → wide from the side: the same kick again, the villain flying back (consequence) → close: the villain's stunned face on the floor (reaction) |
+| **the ladder** | wide: three thugs close in (establish) → medium: he swings the ladder round (strike, impact) → wide: the three go down in a row (consequence) → medium: he steps through the rungs, grinning (performance) |
+| **the pose** | after the last blow, a medium on the hero settling into a stance, a beat of stillness (stance) — the 定格 |
+
+## Staging and props
+
+Markets, dim sum kitchens, bamboo scaffolding, fishing docks, warehouses, rooftops. Everyday
+props as weapons are the style: chairs, benches, ladders, brooms, umbrellas, woks, bicycles.
+
+## Sound
+
+Exaggerated punch and kick sfx (whooshes and snaps), the clang of props, the crowd gasping, a
+comic sting after a joke. Music: percussive, driving; `duck` for the comic beat.
+
+## Example `motion.action`
+
+- `he swings the wooden bench round into the thug's ribs`
+- `she ducks under the pole` (a dodge is one move)
+- `he shakes his stinging hand and blows on his knuckles` (the comic beat)
+
+## Review questions
+
+- Can you follow every exchange — both fighters in frame, full body?
+- Is there a prop in the hero's hands at least once?
+- Is the decisive hit shown twice, with a ramp?
+- Is there one laugh inside the fight?

package/skill/short-drama/reference/action-street-brawl.md

@@ -0,0 +1,49 @@
+# Action style `street-brawl` — 写实街头格斗
+
+**The fight:** ugly and desperate. Two or a few bodies in a space too small for them — a
+corridor, a stairwell, a bathroom, an alley — slamming into walls and doors, grappling, falling,
+getting up exhausted. No technique on display; survival. The camera is in there with them,
+jostled. Shared rules and fields: `action.md`.
+
+**Look:** `low-key` (a single bulb in a corridor, fluorescent tubes in a toilet, a sodium lamp in
+an alley). Sweat, rain, grime.
+
+## Rhythm and coverage
+
+- **Cuts are short to medium**: 2–3.5 s.
+- **Sizes**: medium and close, cramped; a wide down the corridor to open and to reset (the long
+  corridor fight is the signature: one side of the frame to the other).
+- **Camera**: handheld (`Shake Slightly`; `Shake Strongly` in the worst of it), close, at chest
+  height. A `Truck Left` / `Truck Right` along a corridor for the one-take feeling.
+- **Speed**: real time. Nothing stylised.
+
+## Signature sequences
+
+| sequence | cuts |
+| --- | --- |
+| **the corridor** | wide down the corridor: one man against six (establish) → wide, truck: he swings a hammer at the first (strike, impact) → medium: the man slams into the wall (reaction) → wide, truck: the crowd pushes him back along the corridor (grapple) |
+| **the wall** | medium handheld: he drives the other man backwards into the door (grapple, impact) → close: the door frame splinters (consequence) |
+| **the ground** | medium: both fall to the floor, grappling (grapple) → close: a hand reaching for a knife on the tiles (pressure) → close: the knife skids away under a kick (kick, impact) → medium: both lie gasping (consequence) |
+| **after** | medium: he gets up slowly, one hand on the wall, bleeding from the brow (performance) |
+
+## Staging and props
+
+Corridors, stairwells, toilets, kitchens, alleys, cramped apartments, a car's back seat. Whatever
+is there: a hammer, a bottle, a chair, a fire extinguisher, a door.
+
+## Sound
+
+Bodies on walls and doors, breaking glass, grunts, ragged breath, shoes on tiles, a phone
+buzzing in the middle of it. Music: none or a low drone.
+
+## Example `motion.action`
+
+- `he slams the man backwards into the door`
+- `both men fall to the tiles, grappling`
+- `he gets up slowly with one hand on the wall`
+
+## Review questions
+
+- Is the space too small? Does the fight use its walls, doors and floor?
+- Is the camera handheld and close?
+- Does anyone look tired or hurt after?