@wji.ai/cli 0.4.0 → 0.5.1

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

@@ -0,0 +1,94 @@
+# Action — how fights are cut (`params.action`)
+
+An action style says **how a fight is broken into shots**: rhythm, coverage, camera, speed,
+signature shots, sound. It is separate from the cinematography preset (the light, see
+`cinematography.md`) and the render style (`params.style`), so the three combine: a
+`costume-dark` 古装 with `historical-realist` fights, a `low-key` city thriller with `gun-fu`.
+
+It applies only to **fight segments**: set `"grammar": "action"` on a storyboard segment that is
+a fight, chase or power battle (or `["action", "comedy"]` for a comic fight — see `grammar.md`).
+Talk segments keep the ordinary storyboard rules. The old `action: true` still works.
+
+| style | 中文 | for | the fight in one line | natural look | guide |
+| --- | --- | --- | --- | --- | --- |
+| `gun-fu` | 近身枪斗 | 杀手、特工、黑帮枪战 | close-quarters gunplay fused with grappling, long takes, full bodies, no wasted motion | `low-key` | `action-gun-fu.md` |
+| `hk-kungfu` | 港式功夫 | 功夫、动作喜剧、警匪 | crisp full-body exchanges, anything to hand is a weapon, speed-ramped hits, comedy between blows | `none` / `low-key` | `action-hk-kungfu.md` |
+| `wuxia-fantasy` | 仙侠武侠 | 仙侠、玄幻、武侠 | wire-work flight, flowing silk, sword light and qi, slow motion and freeze poses | `costume-idol` | `action-wuxia-fantasy.md` |
+| `historical-realist` | 写实冷兵器 | 古装权谋、战争、写实武侠 | heavy blades, mud and exhaustion, few blows, each one final | `costume-dark` | `action-historical-realist.md` |
+| `bullet-time` | 子弹时间 | 科幻、超现实动作 | time freezes mid-move, the camera orbits, bullets trace trails, then snap to speed | `low-key` | `action-bullet-time.md` |
+| `superhero` | 超级英雄 | 超能力、英雄 | power reveals, low-angle hero framing, landings, spectacle | `none` | `action-superhero.md` |
+| `street-brawl` | 写实街头格斗 | 黑帮、复仇、犯罪 | raw handheld close-quarters fighting in cramped spaces | `low-key` | `action-street-brawl.md` |
+| `car-chase` | 飞车追逐 | 犯罪、特工、复仇 | low tracking alongside, the driver inside vs the cars outside, near misses, a crash | `none` / `low-key` | `action-car-chase.md` |
+
+**Choosing.** `init` sets `params.action` only when the genre names a style outright (功夫, 枪战,
+杀手, 冷兵器, 超级英雄, 飞车, 街头格斗, 仙侠 + 动作…); otherwise it stays `none`. When the story has
+fights and the style is `none`, **ask the user** which one, with the table above. One style per
+drama; a drama with both a sword fight and a car chase picks the dominant one, and the other
+segments may deviate through the exceptions below.
+
+## 1. The shared craft — breaking a fight into moves (拆招)
+
+A video model cannot perform continuous choreography. It performs **one clear, big, common move**
+well: a punch, a kick, a shot, a throw, a leap, a swerve. Everything in the action styles is built
+on that:
+
+1. **One cut, one move.** Wind-up → contact → result, one blow per cut (`motion.action` with one
+   fight verb, gated). A three-move combo is three cuts. The drama of a fight lives in the rhythm
+   of the cuts, not in a single shot's choreography.
+2. **The fight sequence** — the unit every style varies:
+   | beat | cut | purpose |
+   | --- | --- | --- |
+   | geography | wide / extreme-wide: who is where, the exits, the weapons to hand | `establish` |
+   | the exchange | medium / close: one move per cut, alternating attacker | `performance` / `pressure` |
+   | the impact | insert or close: the blow lands (`move.impact: true`) | `performance` / `consequence` |
+   | the answer | the receiver's reaction or the consequence (flies back, falls, drops the gun) | `reaction` / `consequence` |
+   | the reset | back to the wide: the new geography after the blow | `establish` / `transition` |
+3. **Show the result, not the contact.** Models draw results (a body flying back, a table
+   breaking, glass shattering, a gun skidding away) better than the exact moment of contact. Put
+   the landing in `motion.result`.
+4. **Sound sells the hit.** Every impact gets an sfx on its cut (`sound.sfx`), and the music cue
+   plan (`sound.music`) drops out before the decisive blow.
+
+## 2. Fields
+
+| field | where | what |
+| --- | --- | --- |
+| `grammar: "action"` | segment | this segment is a fight / chase / power battle; the action gates apply |
+| `move: { kind, impact }` | cut | `kind` ∈ `strike kick shot slash stab block dodge throw grapple fall leap draw reload power stance chase swerve crash none`; `impact: true` when the move lands on a body or an object |
+| `exceptions: [{ rule, reason }]` | segment | waive a hard rule for this segment **only when the user asks**; `reason` records the request |
+| `params.action` | project | the style (table above) |
+| `params.violence` | project | `blood` (default: blood and wounds may show) or `implied` (impact through reaction and sound only) |
+
+## 3. The gates
+
+| rule | what | hard? |
+| --- | --- | --- |
+| `open-wide` | the first fight segment of a scene opens on a `wide` / `extreme-wide`; later fight segments in the scene contain at least one | hard, waivable |
+| `one-move` | `motion.action` has at most one fight verb (punches, kicks, shoots, slashes, blocks, throws, swerves… / 出拳, 踢, 开枪, 劈, 格挡…) and no chaining ("then", "接着", "连环") | hard, waivable |
+| `impact-reaction` | a cut with `move.impact` is followed by a `reaction` or `consequence` cut, unless it is itself a `consequence` (the result shown in the same shot) | hard, waivable |
+| `no-graphic` | no dismemberment, decapitation, severed limbs or organs — providers refuse them even with blood allowed | hard, waivable (the provider may still refuse) |
+| blood | with `params.violence: implied`, no blood or wounds in frames or prompts | hard |
+| style phrase | a fight segment's prompt carries the style's phrase (an `Action:` line, `动作：` for `wan`); `prompt segment` writes it | hard |
+| no IP names | no film, franchise, character or performer names (John Wick, Matrix, Marvel, 李小龙, 成龙…) in any prompt or frame — every segment, not only fights | hard |
+| rhythm | a fight segment's cuts average the style's length (`action-advice`) | advisory |
+| signature shots | the episode's fight segments contain the style's signature shots (an Arc Shot for `bullet-time`, handheld for `street-brawl`…) | advisory |
+
+**Exceptions.** When the user asks for something a hard rule forbids ("open on the fist, no
+wide", "one continuous combo in one shot"), add
+`"exceptions": [{ "rule": "open-wide", "reason": "user: open on the fist" }]` to that
+segment. Never add one on your own to turn a gate green. A waived `one-move` is a known risk:
+tell the user the model may garble the combo, and check the clip.
+
+## 4. Blood
+
+`params.violence: blood` (the default) lets frames and prompts show blood: a split lip, a spray
+on a wall, a stained blade, a wound on a sleeve. Keep it **specific and small** ("a thin line of
+blood at the corner of his mouth") rather than vague and lurid; providers judge by wording. Never
+dismemberment, decapitation or organs (gated). `implied` is for platforms or audiences that allow
+none: the reaction, the sound, the dropped weapon and the aftermath carry it.
+
+## 5. What each guide contains
+
+Rhythm and cut lengths · shot sizes and camera · speed (slow motion, ramps) · the signature
+sequences written as shot lists · staging and props · sound · the look it pairs with · example
+`motion` lines (one move each) · review questions.

package/skill/short-drama/reference/cinematography-costume-dark.md

@@ -0,0 +1,117 @@
+# Cinematography preset `costume-dark` — 古装写实 · 权谋 · 武侠 · 暗黑
+
+The look: **history as it was lit — by fire.** Candles, oil lamps, braziers and torches at night;
+daylight and moonlight cut into bars by lattice windows in the day. Faces are carved out of deep
+shadow from the side and from behind. Smoke and dust hang in every shaft of light. Colour is
+earthy and desaturated: ochre, umber, soot, cold steel blue. Texture is real: worn fabric, rusted
+armour, weathered wood, wet stone. It is the `low-key` look moved into the past, so read
+`cinematography-low-key.md` too (staging against the source, the reverse-angle flip, negative
+space).
+
+The mechanics shared by every preset (the fields, the gates, where the phrases land, the
+character-sheet exception) are in `cinematography.md`. Pair it with `register: 古装` for the lines.
+
+## 1. Light — only fire and the sky — `light.source`, `light.direction`
+
+Every cut names its source in `light.source`, carried verbatim in the frame with `low-key firelit
+period lighting`. **No electric light exists** (gated).
+
+| time / place | the source | what it gives |
+| --- | --- | --- |
+| night, study or bedchamber | one or two candles, an oil lamp | a small warm pool, the face half in it, the room lost in black |
+| night, hall or prison | braziers, wall torches | flickering orange from below the eyeline of standing people, moving shadows |
+| night, outside | moonlight, a lantern carried by hand | cold blue rim, a warm moving key |
+| day, interior | daylight through lattice windows or paper screens | bars and patterns of light across faces and floors |
+| day, exterior | overcast sky, low winter sun, haze | flat grey world, faces modelled by the low sun from the side |
+| battle, market, road | fire, smoke, dust, rain | backlit silhouettes, light shafts through smoke |
+
+- **Stage the person beside the flame or the window**, then choose the camera side that makes it
+  a side light or a back light. At least **half** the cuts with people are `side-*` / `back-*` /
+  `backlight` (gated). The reverse angle flips the same candle from key to rim.
+- **Never on a face**: `frontal` and `ambient` (gated). `underlight` is allowed, because a candle
+  on a low table really does light from below: use it for menace, sparingly.
+- **Flicker is part of the light.** Say it in `light.note` ("the candle flame sways and the light
+  on his cheek breathes with it").
+- **Lattice light** (窗棂光影) is the day signature: the window's pattern thrown across a face,
+  a floor, a hand.
+- **Scene lighting states** contain `low-key firelit period lighting` and the sources:
+  > `low-key firelit period lighting: a single oil lamp on the low desk and two candles by the scroll rack are the only light, a warm pool over the desk and the floor mat, the lattice windows dark blue with moonlight, smoke from the incense burner drifting through the lamplight, the corners of the study falling into black. Empty room, no people.`
+
+## 2. Colour and texture — earth, soot, steel
+
+- **Palette**: ochre, umber, dark wood, soot black, bone, dried-blood red, cold steel blue for
+  night and armour. Saturated colour is rare, and so it means something: one red robe, one gold
+  seal.
+- **Grade**: desaturated, contrasty but not crushed, warm firelight against cold night.
+- **Texture is realism**: frayed hems, stains, repaired armour, mud on boots, cracked lacquer,
+  wet stone, rough hemp. Put it in the character and scene bibles; with `style: photoreal` the
+  sheet negative-prompt rules still apply (realism comes from materials and wear, not banned skin
+  words).
+- **The air carries the light**: smoke, incense, dust, breath in the cold, rain. It turns every
+  source into a visible shaft. Make it an anchor of the scene.
+
+## 3. Composition — vast wides with 留白, power and threat
+
+### 全景 / 大全景 with 大量留白 (gated)
+
+As in `costume-idol`, **every segment has at least one `wide` or `extreme-wide` cut, and its
+frame says where the `negative space` is** (gated). Here the empty space is heavy, not airy: the
+world is vast and indifferent, and the people in it are small against power, war and history.
+
+- **What fills the negative space**: darkness (a black throne hall with one pool of candlelight,
+  a night sky over the city wall), smoke and dust (a burning city, a battlefield after the fight,
+  a desert road in haze), grey sky and snow (a frozen river, an execution ground, the palace
+  square under a winter overcast), rain (the courtyard lit by one lantern).
+- **The figure is small and alone**: a lone rider on the ridge, a minister kneeling in the middle
+  of the empty square, the prisoner in a pool of torchlight in a huge dark hall, two swordsmen
+  facing each other across a bamboo forest in mist. In 9:16, the figure low in the frame under
+  the dark or the sky, or at the far end of a long axis (a corridor, a stair, a city gate).
+- **Place the wide deliberately**: to open a scene (the scale of the palace, the army, the
+  wilderness), to show who holds power (the throne at the far end of the hall), and after a
+  blow (the character left alone in the vast space).
+- Write it: `extreme wide shot, a lone kneeling figure small in the lower third of the empty
+  palace square, the vast negative space of grey winter sky and falling snow above, two braziers
+  burning at the foot of the steps`.
+- A wide still needs depth: a banner, a spear, a lattice or a flame soft in the foreground, the
+  palace roofs or the ridge line fading into haze behind.
+
+### Power and threat
+
+- **Negative space is darkness and threat** in the closer shots too: the empty throne, the dark
+  doorway behind the listener.
+- **Power by height and position**: the emperor high and centred, the minister low and off-axis;
+  `height: low` for the one who holds power, `high` for the one who has lost it.
+- **Foregrounds**: lattice screens, candle flames, bead curtains, the edge of a folding screen,
+  spears and banners, a shoulder in armour. At least half the cuts (gated). Shooting *through*
+  screens is the intrigue genre: someone is always watching.
+- **Silhouettes** against a lit doorway or a burning city are allowed and strong.
+
+## 4. Lens
+
+| shot | focal | stop |
+| --- | --- | --- |
+| candlelit close-up | 75–85mm | T1.5 |
+| two people at a desk, OTS | 50–75mm | T1.5–T2 |
+| hall, court, courtyard | 25–35mm | T2–T2.8 |
+| battle / road wide | 18–25mm | T2.8 |
+
+Nothing slower than T2.8 (gated). Candlelight needs the wide aperture, and so does the look.
+
+## 5. Camera and motion
+
+- Controlled: `Static Shot` for audiences and interrogations, slow `Push In` as a threat lands,
+  slow `Truck Left` / `Truck Right` along a line of kneeling officials. `Shake Slightly` only in battle and chases.
+- **Motion lives in the light and the air**: flames sway, smoke drifts, rain falls through
+  torchlight, a curtain moves in a draught. A lock-off is never dead.
+- Violence is shown by consequence and sound more than by choreography the model cannot perform
+  (see craft-shots §7).
+- Sound: fire crackle, wind, rain on tiles, armour creaking, distant drums, and silence in the
+  court before a verdict.
+
+## 6. Review questions
+
+- Is there any light in this frame that needs electricity?
+- Can you point at the flame or the window lighting the face? Is the face half in darkness?
+- Is there smoke, dust or rain to make the light visible?
+- Does the texture look used — frayed, stained, weathered — or costume-new?
+- Who holds power in this frame, and does the composition say so?

package/skill/short-drama/reference/cinematography-costume-idol.md

@@ -0,0 +1,126 @@
+# Cinematography preset `costume-idol` — 古装偶像 · 古偶 · 仙侠
+
+The look: **a luminous, painted world.** Faces are bright, soft and flawless. Light is diffused
+through silk gauze and paper windows and glows through flowing hair and sleeves from behind.
+Mist, petals and shafts of light drift through the air. The palette is soft: jade, moon-white,
+pale pink, pale gold. The frames swing between two scales: vast wides and extreme wides full of
+empty sky and mist (大量留白) with a small figure in them, and close shots of the couple fully open
+into the dreamiest bokeh. It is `sweet-romance` moved into a palace or an immortal realm, so read
+`cinematography-sweet-romance.md` too (the couple's distance, the 心动 set pieces and the music
+cues all apply).
+
+The mechanics shared by every preset (the fields, the gates, where the phrases land, the
+character-sheet exception) are in `cinematography.md`. Pair it with `register: 古装` for the lines.
+
+## 1. Light — diffused, glowing, never electric — `light.source`, `light.direction`
+
+Every cut names a soft period source in `light.source`, carried verbatim in the frame with
+`ethereal costume drama lighting`. **No electric light exists** (gated: bulbs, neon, fluorescent
+tubes, LEDs, street lights, screens are refused).
+
+| time / place | the source | what it gives |
+| --- | --- | --- |
+| day, palace hall | sun through paper windows and layers of silk gauze | an even, luminous wrap on the faces, glowing backgrounds |
+| garden, peach blossom | the open sky, the sun behind the trees | a halo in the hair, petals lit from behind |
+| immortal realm, mountain | sun through mist and clouds, god rays | shafts of light, a soft white world |
+| night, courtyard | moonlight + rows of red lanterns | cool moon rim, warm lantern key, bokeh lanterns |
+| night, bedchamber | many candles through gauze curtains | a warm glow wrapping the couple |
+| magic | the glow of a spell, a jade pendant, fireflies | a coloured key from the hand or the object |
+
+- **The face is luminous.** Soft three-quarter front (`front-left` / `front-right`) or a glow from
+  behind (`back-*` / `backlight`): at least **half** the cuts with people (gated).
+- **Backlight through fabric** is the signature: the sun or the lanterns behind flowing sleeves,
+  veils and loose hair, turning them into light.
+- **Never on a face**: `underlight` and `top` (gated). Those belong to `costume-dark`.
+- Shadows are soft and open; nothing falls to black except the night sky.
+- **Scene lighting states** contain `ethereal costume drama lighting` and the sources:
+  > `ethereal costume drama lighting: soft morning sun diffused through the tall paper lattice windows and layers of pale silk gauze, the hall luminous and airy, a faint mist catching the shafts of light, jade and moon-white surfaces glowing softly. Empty hall, no people.`
+
+## 2. Colour, fabric and air
+
+- **Palette**: jade green, celadon, moon-white, pale pink, lotus, pale gold, soft lavender. Give
+  each lead a colour in the character bible (he in moon-white and silver, she in pale pink and
+  jade) and keep it through the drama. The villain gets the deep, saturated colour.
+- **Grade**: soft, bright, slightly desaturated pastels, creamy highlights, a gentle glow
+  (halation) around bright edges.
+- **Fabric is the effects budget**: silk that catches light, layered gauze, long sleeves and
+  ribbons that move. Say it in the frames (`sheer silk sleeves glowing in the backlight`).
+- **Air is never empty**: mist, falling petals (peach, plum, pear blossom), drifting snow, floating
+  lanterns, fireflies, incense smoke. Make one of them an anchor of each scene, and move it in
+  `motion` / `cameraNote.hold`.
+
+## 3. Composition — vast wides with 留白, intimate close-ups
+
+This look lives on two scales at once: **the world is huge and empty, the couple is close and
+glowing.** Cut between them.
+
+### 全景 / 大全景 with 大量留白 (gated)
+
+**Every segment has at least one `wide` or `extreme-wide` cut, and its frame says where the
+`negative space` is** (gated). The empty part of the frame is the fantasy: the world is bigger
+than the people in it.
+
+- **What fills the negative space**: sky and clouds, a sea of mist, a still lake, a snow field, an
+  endless palace courtyard, a sea of blossom, mountain ridges fading into haze. Bright and soft,
+  never black.
+- **The figure is small.** One or two people take up a small part of the frame: on a bridge, at
+  the top of a stairway, on a cliff edge, in the middle of an empty courtyard. The 9:16 frame is
+  tall: put them in the lower third with the sky or mist above, or at the top with the empty
+  stairway below.
+- **Place the wide deliberately**: to open a scene (where are we), to end it (the couple left
+  alone in the world), and at the emotional turn (she walks away across the empty courtyard).
+- Write it: `extreme wide shot, a lone figure in moon-white robes on the arched bridge in the
+  lower third, the vast negative space above filled with drifting mist and peach blossom`.
+- A wide still needs depth (the `storyboard-advice` note on 9:16 wides): a blossom branch or a
+  lantern soft in the foreground, the mountains or the palace roofs faded in the background.
+
+### Close to the couple
+
+- **The couple uses the romance rules** (the distance between them, over-the-shoulder with a
+  soft sleeve or hair in the foreground, the centred 心动 close-up), see
+  `cinematography-sweet-romance.md` §3.
+- **Palaces and ceremonies are symmetrical**: centred axis, the throne or the gate in the middle,
+  people in rows. Low `height` for power.
+- **Foregrounds**: gauze curtains, blossom branches, bead curtains, lantern tassels, lattice
+  windows, drifting petals near the lens. At least half the cuts (gated).
+- **Frame within a frame**: moon gates, lattice windows, the gap in a folding screen, the space
+  under an oil-paper umbrella.
+
+## 4. Lens — fully open, the dreamiest bokeh
+
+`init` gives this preset a faster package: `Zeiss Master Prime` at **T1.3**. Nothing is slower
+than **T2** (gated).
+
+| shot | focal | stop |
+| --- | --- | --- |
+| realm / palace extreme wide | 18mm | T2 |
+| courtyard, bridge, garden wide | 25mm | T2 |
+| two-shot in the garden | 50mm | T1.3–T1.5 |
+| couple, OTS | 75–85mm | T1.3 |
+| the 心动 close-up | 85mm | T1.3 |
+
+**The dreamiest bokeh** follows `cinematography-sweet-romance.md` §4: at least half the frames of
+a segment name what melts into `bokeh` (gated). The period gives you the best sources: rows of
+red lanterns, a lantern festival, candles through gauze, fireflies, sun glinting through blossom
+branches, sparkles on the lake, floating river lanterns. Diffusion in `params.lookPhrase` suits
+this look (`soft pro-mist diffusion, gentle halation`).
+
+## 5. Camera and motion
+
+- Floating and slow: slow `Arc Shot` around the couple, rising `Pedestal Up` / `Tilt Up` to a
+  palace or a flying figure, slow `Push In` on a look, gentle `Tracking Shot` through a garden.
+- **Slow motion** on the 心动 beats, the turn of a sleeve, a flying leap, falling petals around a
+  still figure. Write `in slow motion` in `motion`.
+- **Wind is always on**: hair, sleeves, ribbons and petals move in every lock-off.
+- The 甜宠 set pieces translate directly (see `cinematography-sweet-romance.md` §6), plus the
+  genre's own: 执手 (holding hands on a bridge), 簪花 (putting a flower or hairpin in her hair),
+  共乘一马 (riding one horse), 月下对饮 (drinking under the moon), 灯会 (the lantern festival),
+  英雄救美 (a rescue ending in a spin and a caught glance).
+
+## 6. Review questions
+
+- Is there any light in this frame that needs electricity?
+- Is the face luminous? Is something (hair, sleeve, veil) glowing from behind?
+- What is floating in the air in this scene?
+- Does each lead wear their own colour?
+- Palace: is it symmetrical? Couple: is the distance right for this episode?

package/skill/short-drama/reference/cinematography-low-key.md

@@ -0,0 +1,115 @@
+# Cinematography preset `low-key` — 悬疑 / 犯罪 / 惊悚 / 都市暗黑
+
+The look: **low-key light that comes from the scene itself, people standing in shadow and shaped
+from the side or from behind, frames with room to breathe and a foreground in front of them, shot
+wide open.** The mechanics shared by every preset (the fields, the gates, where the phrases land,
+the character-sheet exception) are in `cinematography.md`.
+
+The brief it comes from:
+
+> **光影**：low key，尽量使用现场光源，需要注意角色的站位及镜头的方向调整光源的方向。人物要站在阴影位置。
+> 优先使用侧光、逆光、边缘光、轮廓光等等。人物避免使用包围光或世界光。
+> **构图**：构图留白设计，保留空间感。场景需要加入前景画面增加层次。因应不同场景使用大光圈镜头。
+
+
+## 1. Light comes from the scene — `light.source`
+
+There are no film lights. Every key light is a **practical**: something that exists in the space
+and can be painted, like a lamp, a window, a screen, a neon sign, a fridge door, a candle, a
+streetlight through glass, or the light box of a vending machine. A good anchor (stage 3) often
+*is* the practical ("the flickering oden light box").
+
+- **Scene lighting states** (`scenes[].lighting[].prompt`, stage 3) are written in the look. Each
+  one contains `low-key practical lighting`, names each practical, says where it sits in the space
+  and what colour it is, and describes the **pools of light with darkness between them**. Nothing
+  is evenly lit.
+  > `low-key practical lighting: the cold fluorescent tube over the counter and the warm oden light box by the door are the only sources; pools of light on the counter and the floor by the door, the back aisles falling to near black, the street outside unlit. Empty scene, no people.`
+- **Every cut** names its source in `light.source`, and the frame carries the same words
+  verbatim, along with `low-key practical lighting`:
+  ```json
+  "light": { "direction": "side-left",
+             "source": "the oden light box",
+             "note": "the light box catches the left edge of her face and the rim of her ear; the rest of her face stays in shadow, the fluorescent spill behind her lifts only her hair" }
+  ```
+
+## 2. Stage the person against the source — `light.direction`
+
+The direction is **relative to the camera** (craft-shots §6), so it follows from two choices: where
+the person stands relative to the practical, and where the camera looks from. Block the person
+first, then choose the camera side that turns the practical into a side light or a back light.
+
+| the practical is… | from the camera it reads as | use |
+| --- | --- | --- |
+| beside the person, 90° to the lens | `side-left` / `side-right` — 侧光, half the face lit, half in shadow | **preferred** |
+| behind the person, off to one side | `back-left` / `back-right` — 逆侧光 / 边缘光, an edge on the cheek, shoulder and hair | **preferred** |
+| directly behind the person | `backlight` — 逆光 / 轮廓光, a silhouette with a lit outline | **preferred** |
+| in front of the person, 45° to the lens | `front-left` / `front-right` — 前侧光 | sparingly: a reveal close-up where the face must read |
+| overhead (a hanging bulb, a ceiling tube) | `top` — 顶光, eye sockets fall dark | when that is the practical |
+| below the eyeline (a phone, a screen, a candle) | `underlight` — 底光 | when that is the practical |
+| on the lens axis | `frontal` — 顺光 | **never on a person** (包围光: flat, no shadow side) |
+| everywhere / nowhere | `ambient` — 世界光 | **never on a person** (no key, no shape) |
+
+- **The person stands in the shadow**, next to the pool of light, not in the middle of it. The
+  light catches an edge: the cheekbone, the jawline, an ear, a shoulder. Write that result in
+  `light.note` ("only her cheekbone and the rim of her ear catch the light; the far side of her
+  face falls to black").
+- **No fill.** The shadow side is lifted only by what the practical bounces off a nearby surface,
+  if at all. Deep blacks are part of the look, not an exposure mistake.
+- **The reverse angle flips the role of the same lamp.** A practical that side-keys her from
+  camera left in the single becomes a rim from behind camera right in the reverse over her
+  partner's shoulder. Work out both sides of the axis (`segment.axis`) before cutting a dialogue,
+  so the scene's light stays in one place while the camera moves around it.
+- **Gated**: a cut with a person on screen may not be `frontal` or `ambient`, and **at least half**
+  the cuts with people in each segment must be `side-*`, `back-*` or `backlight`. When the gate
+  fails, re-stage the person or move the camera; don't just relabel the direction.
+
+## 3. Composition — negative space and a foreground
+
+**留白 — negative space.** Don't centre the person and fill the frame. Put them on a third, and
+give the empty part of the frame a job: the dark aisle they are walking into, the door behind
+them that is about to open, the distance to the person they won't look at. In the low-key look
+the negative space is usually the dark part of the frame.
+
+- Leave looking room on the side the person faces (`start.facing`), and leading room on the side
+  they move toward.
+- A vertical 9:16 frame has room above and below. A small figure low in the frame under dark
+  space reads as isolation or pressure, and this is often the strongest wide shot.
+- A close-up still leaves room: the face off-centre, with the space on the side the eyes look.
+- Write the placement into `frame`: `she sits in the lower-left third, the unlit shelves filling
+  the right two-thirds of the frame`.
+
+**前景 — a foreground layer.** Most cuts shoot *past* something: the edge of a shelf, rain on the
+glass, a door frame, a hanging lamp, the shoulder of the other person (an over-the-shoulder). Take
+it from the scene's anchors where you can, so it also carries continuity. The existing `photography`
+gate already requires a named `foreground` on at least half the cuts of a segment, said to be out
+of focus. Aim higher than that minimum in this look.
+
+**Three layers.** A defocused foreground, the person in the shadow in the mid-ground, and a
+practical in the background that falls into bokeh. That depth is what the wide aperture exists for.
+
+## 4. Lens — wide open, chosen per scene
+
+The default package (`ARRI ALEXA Mini LF` / `Zeiss Supreme Prime` / `T1.5`) already shoots wide
+open. A cut may override `focal` and `aperture` to suit the scene, but **never slower than T2.8**
+(gated).
+
+| scene | focal | stop | why |
+| --- | --- | --- | --- |
+| intimate dialogue close-up, interior night | 75–85mm | T1.5 | eyes sharp, ears already soft, the background a wash of practicals |
+| two-shot / medium, interior | 40–50mm | T1.5–T2 | both faces hold, the room behind melts |
+| over-the-shoulder | 50–75mm | T1.5–T2 | the near shoulder is the foreground blur |
+| wide establishing, interior or street at night | 25–35mm | T2–T2.8 | the space stays readable, the far practicals bloom |
+| day exterior | 35–50mm | T2–T2.8 | still shallow; the brightness is carried by an implied ND, not by stopping down |
+| insert / prop | 100mm macro | T2–T2.8 | a sliver of focus on the one detail |
+
+The frame carries the whole camera phrase verbatim, including the stop
+(`shot on an ARRI ALEXA Mini LF with a Zeiss Supreme Prime 75mm at T1.5`).
+
+## 5. Review questions
+
+- Can you point at the lamp in each cut? If the light has no source in the scene, it is a film
+  light, and this look has none.
+- Is the person standing *beside* the light rather than *in* it?
+- On the reverse angle, is the same lamp still on the same side of the room?
+- Cover the person with your thumb. Does the empty part of the frame still say something?
+- What is the blurred thing in front of the lens, and is it something from this scene?

package/skill/short-drama/reference/cinematography-period-nostalgia.md

@@ -0,0 +1,106 @@
+# Cinematography preset `period-nostalgia` — 年代 · 怀旧
+
+The look: **a memory shot on film.** Warm, faded colour on vintage lenses and film stock, with
+grain and a soft glow. The light is the era's own: sun through a window, a bare tungsten bulb, a
+green-white fluorescent tube, the flicker of an old television. Frames are steady and unhurried,
+so the period details (the enamel mug, the bicycle, the calendar on the wall) have time to be
+seen. The feeling is warmth with an ache: the picture should feel like something already lost.
+
+The mechanics shared by every preset (the fields, the gates, where the phrases land, the
+character-sheet exception) are in `cinematography.md`. Pair it with `register: 年代` for the lines.
+
+## 0. Name the decade
+
+The preset is the *look*. The *era* is yours to state, and the details depend on it. Put the
+decade in `params.lookPhrase` (e.g. `1980s`), so every segment prompt carries it, and in every
+scene lighting state and frame. A 1920s 民国 drama, a 1970s 大院 drama and a 1990s 下岗 drama
+share the film look and nothing else:
+
+| era | light sources that exist | palette |
+| --- | --- | --- |
+| 民国 (1920s–40s) | sun, oil lamps, early bare bulbs, candles, neon on the treaty-port streets | sepia, ivory, tea brown, jade, black lacquer |
+| 1960s–70s | sun, bare bulbs, kerosene lamps in the countryside, the one fluorescent tube in the office | faded army green, navy, grey, a slogan red |
+| 1980s | sun, bare bulbs, fluorescent tubes, desk lamps, the first colour TVs, neon on new shopfronts | warm amber, mustard, brick red, teal, cream |
+| 1990s | fluorescent tubes, shop neon, karaoke lights, CRT TVs, street lamps | cooler greens, bright signage colours over faded walls |
+
+The validator refuses sources no older era had (LEDs, smartphones, laptops, flat screens, ring
+lights). The finer calls — a fluorescent tube in a 民国 room, a colour TV in 1972 — are yours; the
+review questions (§6) ask them.
+
+## 1. Light — the era's own sources — `light.source`, `light.direction`
+
+Every cut names its source in `light.source`, carried verbatim in the frame with `nostalgic
+period film look`.
+
+- **Window sun is the signature.** Hard, warm shafts through a window, dust hanging in them, a
+  pool of light on the floor or the table. Afternoon is the nostalgic hour.
+- **Bare bulbs at night**: one warm tungsten bulb hanging over the table, the room falling off
+  into brown shadow. A fluorescent tube is the colder, harsher office or factory version: let it
+  go slightly green.
+- **The face is lit by an angle, not a flash.** Key from the window or the bulb at three-quarter
+  or from the side; at least **half** the cuts with people are `front-left` / `front-right` /
+  `side-*` / `back-left` / `back-right` (gated). `top` is allowed when the bare bulb really hangs
+  above them; it is not in the preferred half.
+- **Never on a face**: `frontal` (reads as a modern flash snapshot) and `underlight` (horror).
+- Shadows are warm brown, not black; contrast is gentle, like old print film.
+- **Scene lighting states** contain `nostalgic period film look`, the decade and the sources:
+  > `nostalgic period film look, 1980s: warm late-afternoon sun slanting through the single window of the dormitory room, dust hanging in the shaft of light, a bare tungsten bulb unlit above the table, faded mint-green walls glowing where the sun lands, the corners falling into warm brown shadow. Empty room, no people.`
+
+## 2. Colour and texture — film, not filter
+
+- **Grade**: warm amber highlights, faded lifted blacks, muted greens and brick reds, colours that
+  look sun-bleached. Say it in the frame: `faded warm film colour, soft grain, gentle halation`.
+- **Film texture**: soft grain, halation around the window and the bulbs, slight softness at the
+  frame edges from the vintage lens. Put a lens and stock in `params.camera` if you want it named
+  (e.g. lens `Cooke Speed Panchro`), or in `params.lookPhrase` (`shot on 35mm film`).
+- **Production design carries the era**, and this look is built to show it. Make the period
+  objects the scenes' **anchors** (so they appear in every generation) and the **foregrounds**:
+  the enamel mug with a red slogan, the thermos, the transistor radio, the wall calendar, the
+  bicycle, the lace doily on the TV, the coal stove, the cassette player, the lottery posters.
+- Wardrobe in the character bibles is of the era: knitted vests, army-green jackets, floral
+  shirts, wide trousers, perms and parted hair. Faded and worn, not costume-new.
+
+## 3. Composition — steady, framed, lived-in
+
+- **Let the frame sit.** More `Static Shot` and slow `Push In` than any other preset. The shot
+  holds, and life moves inside it.
+- **Frame within a frame**: doorways of the 筒子楼 corridor, the courtyard gate of the 胡同, the
+  window of the bus, the hatch of the ticket office. It looks through time.
+- **Medium-wide more than close-up.** The room is part of the character. Keep people in their
+  space with room around them; save the close-up for the emotional peak.
+- **Foregrounds are period objects**, thrown out of focus: the mug, a bead curtain, laundry on the
+  line, a bicycle wheel, the net curtain. At least half the cuts have one (gated).
+- **Tableau shots** for families and groups: people arranged around the table or the courtyard
+  like an old photograph, the camera at eye height, level and still.
+
+## 4. Lens — vintage, not necessarily wide open
+
+This preset allows **T4** (the others stop at T2.8): the period detail is the point, and the
+room should often read in focus.
+
+| shot | focal | stop |
+| --- | --- | --- |
+| the room / courtyard / street tableau | 25–35mm | T2.8–T4 |
+| people in their space, medium | 40–50mm | T2–T2.8 |
+| the emotional close-up | 75mm | T2 |
+| period-object insert | 100mm macro | T2.8 |
+
+## 5. Camera, motion and sound
+
+- Gentle camera: `Static Shot`, slow `Push In`, a slow `Truck Left` / `Truck Right` along a corridor or a street, a
+  `Tracking Shot` alongside a bicycle. No shake.
+- **Motion that breathes the era**: dust in the sunbeam, a ceiling fan turning, the curtain
+  lifting, steam from a teacup, the bicycle bell, the TV picture rolling.
+- **Sound is half the nostalgia**: the radio, cicadas in the courtyard, the bicycle bell, the
+  street hawker, the train in the distance, a period song on the cassette player. Put the diegetic
+  music in `sound.sfx` or as the segment's `music` intent.
+- **Transitions by memory**: a match cut from an object in the present to the same object then,
+  or a slow push into a photograph that becomes the scene.
+
+## 6. Review questions
+
+- Which year is it? Would every object and light source in this frame exist that year?
+- Can you point at the window or the bulb that lights the face?
+- Is there a period object in the foreground or the anchors that tells you the era at a glance?
+- Does the picture feel like film (grain, warm faded colour), not like a filter?
+- Does the frame hold long enough for the room to be seen?

package/skill/short-drama/reference/cinematography-scifi-hard.md

@@ -0,0 +1,63 @@
+# Cinematography preset `scifi-hard` — 硬科幻
+
+The look: **the future as engineering.** Technology is functional, heavy and worn; every light has
+a physical source (an instrument panel, a work lamp, a screen, an LED strip, the sun through a
+viewport); in space, one harsh sun and black shadows. The palette is cold and neutral (white,
+grey, gunmetal) with amber and red warning lights. The camera is sober, almost documentary, and
+scale is real: a person is small next to a machine because the machine is big, not because it
+glows. The mechanics shared by every preset are in `cinematography.md`.
+
+## 1. Light — only what is built or natural — `light.source`, `light.direction`
+
+Every cut names its source, carried verbatim in the frame with `grounded hard science fiction
+lighting`. **No magic, floating holograms, force fields or energy glows** (gated: those sources are
+refused). A display is a physical screen; a HUD is a reflection in a visor.
+
+| place | the source | what it gives |
+| --- | --- | --- |
+| ship corridor, lab | overhead panel strips, work lamps | hard top and side light, pools on the deck, dark between the panels |
+| cockpit, control room | instrument panels, screens | cool light from below and the side on the faces, reflections in glass |
+| spacewalk, surface | one harsh sun, the planet's glow | razor-edged shadows, black sky, a rim of earthlight |
+| emergency | red and amber warning beacons | rotating hard colour, the face in and out of light |
+| habitat | practical lamps, a window to the planet | warmer pools in a cold structure |
+
+- The face is keyed **hard, from one side or from above** (`side-*`, `back-*`, `top`: at least half
+  the cuts with people, gated). **Never** `frontal` or `ambient` on a person: space has no soft
+  world light.
+- Shadows are deep and hard-edged; contrast is high; fill comes only from bounce off a hull or a
+  panel.
+- **Scene lighting states** contain `grounded hard science fiction lighting` and the sources:
+  > `grounded hard science fiction lighting: white overhead panel strips every two metres along the ship corridor, the deck between them in shadow, amber status lights glowing at each hatch, frost on the viewport at the far end. Empty corridor, no people.`
+
+## 2. Design, colour and texture
+
+- **Palette**: white, grey, gunmetal, bone, with amber and red for warnings and a single accent per
+  faction or ship. Low saturation; the colour comes from the warning lights.
+- **Design is functional**: cables, labels, stencilled numbers, scuffed paint, tape repairs,
+  checklists. Make these the scene anchors and the foregrounds.
+- **Wardrobe**: flight suits, pressure suits, work overalls with patches; helmets with visor
+  reflections.
+- **Physics as drama**: silence in vacuum (only the suit's breathing and radio), floating objects in
+  zero-g, condensation of breath in a cold hull, the slow drift of debris.
+
+## 3. Composition and camera
+
+- **Scale by comparison**: a figure beside a machine, a ship against a planet, a suit on a
+  hull. Wides and extreme wides establish it.
+- **Symmetry of engineered spaces**: corridors, airlocks and control rooms are built symmetric;
+  use them (`composition: art-first` pairs well).
+- **Camera**: steady, observational: `Static Shot`, slow `Push In`, `Truck Left` / `Truck Right`
+  along a corridor. Weightless float for zero-g (a slow drifting `Arc Shot`).
+- **Lens**: 25–35mm for spaces, 50–85mm for faces behind visors, T2–T2.8.
+
+## 4. Sound
+
+Hums, fans, relays, alarms, radio chatter with squelch, breathing in a helmet, silence outside.
+Music sparse: a low drone, a single piano line.
+
+## 5. Review questions
+
+- Could this be built? Is every light a panel, a lamp, a screen or the sun?
+- Is there any floating hologram, glow or magic in the frame?
+- Is the scale shown by comparison with something human?
+- Is the palette cold and neutral, with colour only from warnings?