@wji.ai/cli 0.4.0 → 0.5.1

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

@@ -0,0 +1,66 @@
+# Cinematography preset `scifi-soft` — 软科幻 · 赛博朋克 · 未来都市
+
+The look: **the future as feeling.** Holograms float over streets, neon and glowing interfaces
+colour every face, the air is thick with haze that catches beams of light, and rain turns the
+ground into a mirror. Technology is imaginative, sleek and unexplained; the story is about the
+people inside it. Two poles: **neon dystopia** (cyan and magenta, rain, crowds, 赛博朋克) and
+**luminous utopia** (white, glass, soft gradients, gardens in towers). The mechanics shared by
+every preset are in `cinematography.md`.
+
+## 1. Light — colour you can see — `light.source`, `light.direction`
+
+Every cut names its glowing source, carried verbatim in the frame with `luminous soft science
+fiction lighting`.
+
+| place | the source | what it gives |
+| --- | --- | --- |
+| night street | neon signs, holographic billboards, shop screens | dual-tone colour on the face (cyan one side, magenta the other), reflections in the wet ground |
+| apartment | a window of city light, a hologram companion, a glowing interface | colour through haze, the face lit by the interface from below and the side |
+| club, market | strobes, colour washes, light strips | saturated pools and beams through smoke |
+| utopia | glass ceilings, light panels, bioluminescent plants | soft gradients, white and pastel, glowing edges |
+| energy tech | an energy core, a weapon charging, a portal | a moving coloured key, bloom and flare |
+
+- **Dual-tone light is the signature**: two coloured sources, one on each side of the face. Key
+  from the side or behind (`side-*`, `back-*`, `backlight`: at least half the cuts with people,
+  gated); **never** `frontal` or `ambient` (the colour flattens).
+- **Haze in every frame** so the beams show; rain or wet ground for reflections.
+- **Scene lighting states** contain `luminous soft science fiction lighting` and the sources:
+  > `luminous soft science fiction lighting: magenta and cyan neon signs stacked up the walls of the narrow street, a holographic koi drifting above the crossing, haze catching the beams, the wet ground reflecting every colour. Empty street, no people.`
+
+## 2. Colour and design
+
+- **Neon dystopia**: cyan, magenta, violet, acid green against black; grime, crowds, cables,
+  vending machines, noodle stalls under holograms.
+- **Luminous utopia**: white, glass, pale blue and gold, soft gradients, plants and water in
+  architecture.
+- **Design is imaginative**: floating screens, transparent phones, drones, robots with faces,
+  light-lined clothing. Pick 3–5 signature devices per world and make them anchors so they recur.
+- **Wardrobe**: layered street wear with light strips, clear raincoats, sleek utopian uniforms.
+
+## 3. Composition and camera
+
+- **The city is a character**: extreme wides of the skyline and the street canyon; the person
+  small under the billboards. Vertical 9:16 suits towers and stacked signs.
+- **Reflections and layers**: shoot through wet glass, holograms and screens in the foreground
+  (soft, glowing).
+- **Camera**: gliding: slow `Tracking Shot` through the crowd, `Pedestal Up` up a tower, `Arc Shot`
+  around a hologram; drones as camera positions.
+- **Lens**: 35–85mm, T1.5–T2, so the neon turns into large coloured bokeh.
+
+## 4. With other axes
+
+- `action: bullet-time` or `superhero` for 未来动作; `grammar: faceslap` for a 逆袭 in a
+  corporate tower; `comedy: romcom` for a robot romance; `composition: art-first` for a
+  contemplative future.
+
+## 5. Sound
+
+Rain, crowds in many languages, synth hums, holographic chimes, drones passing. Music: synthwave,
+ambient pads.
+
+## 6. Review questions
+
+- Are there two colours on the face?
+- Is there haze for the beams and a wet surface for the reflections?
+- Are the world's signature devices in the frame?
+- Is the city felt — a wide that shows how big it is?

package/skill/short-drama/reference/cinematography-sweet-romance.md

@@ -0,0 +1,175 @@
+# Cinematography preset `sweet-romance` — 甜宠 · 韩风唯美 · 浪漫
+
+The look: **bright, soft, flattering light on the faces with a warm halo behind the hair; a
+pastel, low-contrast picture with creamy highlights and a dreamy glow; two people framed so that
+the space between them tells the story; shot wide open into creamy bokeh.** It is the modern
+idol-romance look: the screen should feel like a warm afternoon even when the scene is sad.
+
+The mechanics shared by every preset (the fields, the gates, where the phrases land, the
+character-sheet exception) are in `cinematography.md`.
+
+## 1. Light — soft sources, a lit face, a halo — `light.source`, `light.direction`
+
+Every cut names a **soft, motivated source** in `light.source`, carried verbatim in the frame
+along with `soft romantic lighting`. Big and soft beats small and hard:
+
+| time / place | the source | what it gives |
+| --- | --- | --- |
+| day interior | a big window, sheer curtains | soft wrap on the face, bright background that blooms |
+| golden hour (the signature) | the low sun behind the couple | warm rim and halo in the hair, lens flare, glowing air |
+| overcast / snow day | the whole sky, snow bounce | even, luminous, clean skin, cool-white with warm accents |
+| blue hour, rooftop or riverside | the sky + warm string lights / street lamps | cool background, warm faces, bokeh balls |
+| night interior (café, apartment) | warm lamps, fairy lights, candles on the table | a warm pool around the couple, the room a soft glow |
+| rainy night | shop windows and signs through wet glass | coloured bokeh, a warm key from the umbrella side |
+
+- **The face is lit and pretty.** Key the face soft from the front three-quarter (`front-left` /
+  `front-right`, 前侧柔光), or put the source behind and let the bounce fill the face (`back-*` /
+  `backlight`, 逆光). At least **half** the cuts with people use one of these (gated).
+- **Always look for the halo.** The source behind the person, lighting the edges of the hair and
+  shoulders, is the single strongest romance cue. Stage people with the window or the sun behind
+  them, and write it in `light.note` ("the low sun behind her turns the loose strands of her hair
+  gold; her face is lit softly by the bounce off the white table").
+- **Shadows are soft and open, never black.** Lift the shadow side ("the shadow side of his face
+  stays soft and open"). A half-lit, half-black face is the thriller look.
+- **Never on a face**: `underlight` (底光) and `top` (顶光). Both carve eye sockets and chins
+  (gated). `side-*` (侧光) is allowed but not in the preferred half: a hard split reads as moody.
+  Use it for a sad beat, not a sweet one.
+- **Scene lighting states** (stage 3) contain `soft romantic lighting`, name the sources, and
+  describe the glow:
+  > `soft romantic lighting: warm late-afternoon sun pouring through the tall café windows behind the counter, sheer curtains diffusing it into a soft glow, warm pendant bulbs lit above the tables, the room bright and airy with gentle open shadows, dust motes floating in the sunbeams. Empty scene, no people.`
+
+## 2. Colour — pastel, warm, low contrast
+
+Colour is written into the scene lighting states and the frames, because the video model grades
+from what it is told.
+
+- **Palette**: cream, peach, blush pink, butter yellow, sky blue, mint, soft lavender. Warm whites,
+  never clinical.
+- **Grade**: low contrast, lifted blacks, creamy (not clipped) highlights, warm-peach skin, a
+  slight glow around bright edges (halation). Say it in the frame: `pastel palette, creamy
+  highlights, lifted soft shadows, gentle glow`.
+- **The couple is colour-coordinated.** Give the two leads complementary wardrobe palettes in the
+  character bibles (her blush and cream, his camel and soft blue), so every two-shot is
+  harmonious. The pair's palettes converge in the episodes where they become a couple.
+- **One colour per scene** in the scene bible: the café is cream and wood, the rooftop is blue
+  hour with warm bulbs, the park is cherry-blossom pink, the snow scene is white-blue with warm
+  lamps. A scene should be recognisable from its colour alone.
+- Seasons and weather are romance tools: falling petals, first snow, light rain under one
+  umbrella, autumn leaves, sunbeams with dust. Put them in the scene anchors, so they appear
+  in every generation, and in `motion` when they move.
+
+## 3. Composition — the distance between two people
+
+**The space between the two leads is the story.** Use it deliberately across the drama:
+
+| stage of the relationship | how the two-shot is built |
+| --- | --- |
+| strangers / enemies | far apart in the frame, often separated by something: a door frame, a pillar, a glass wall, a table |
+| noticing (心动 starts) | still apart, but they share the frame, and their eyelines meet across the empty space |
+| closer (暧昧) | the gap narrows, over-the-shoulder singles with the other's shoulder soft in the foreground |
+| together | they share one side of the frame; the negative space is now the world around them, not between them |
+
+- **Negative space is air, not darkness.** In this look the empty part of the frame is bright:
+  sky, a sunlit window, a blossom-filled park. A small couple low in a 9:16 frame under a big sky
+  reads as 浪漫, not lonely.
+- **The 心动 close-up is centred and clean.** It is the one shot where symmetry and a centred
+  face are right: the audience falls for the face with the character.
+- **Over-the-shoulder is the dialogue workhorse.** The other person's shoulder or hair is the soft
+  foreground, which keeps both people in every line.
+- **Foregrounds are pretty things, thrown out of focus**: flowers on the café table, fairy
+  lights, falling petals or snow near the lens, rain on the glass, a curtain edge, the rim of a
+  cup. At least half the cuts have one (gated). Aim for most.
+- **Frame within a frame**: a window, a doorway, the space under an umbrella. It gives the couple
+  a small private world.
+- **Inserts are romance beats**: fingers almost touching, a hand on a sleeve, the shared
+  umbrella handle, two cups side by side. A 2-second `extreme-close` on hands does more than a
+  line of dialogue.
+
+## 4. Lens — long, fully open, the dreamiest bokeh
+
+`init` gives this preset a faster package: `Zeiss Master Prime` at **T1.3** (the body stays the
+default). Nothing is slower than **T2** (gated), so even the wides stay soft behind the couple.
+
+| shot | focal | stop | why |
+| --- | --- | --- | --- |
+| the 心动 close-up / eye-lock | 85mm (or 100mm) | T1.3 | the face alone, the background dissolved into huge soft discs |
+| over-the-shoulder singles | 75–85mm | T1.3 | the near shoulder melts, the face stays crisp |
+| two-shot, medium | 50mm | T1.3–T1.5 | both faces sharp, the room turns to glow |
+| couple in the place (wide) | 35mm | T2 | the season and the setting read, the lights behind still bloom |
+| hands / object insert | 100mm macro | T1.5–T2 | one sliver of focus |
+
+### The dreamiest bokeh (最梦幻的散景)
+
+A fast stop alone does not make dreamy bokeh; the frame has to give the lens **points of light to
+dissolve**. At least **half** the frames of a segment say what melts into bokeh (gated: the word
+`bokeh` in the frame). To get the biggest, creamiest discs:
+
+- **Put lights behind the subject, far away**: string lights, lanterns, candles, city lights,
+  car tail lights in the rain, sun glinting through leaves, sparkles on water, Christmas trees.
+  The farther they are behind the person, the bigger the discs.
+- **Go long and close**: 85mm or 100mm, the subject near the lens. Long focal + close subject +
+  far background is what turns each light into a large soft circle.
+- **Bokeh in front too**: fairy lights, flowers, petals or snow right in front of the lens,
+  becoming soft glowing shapes across the edge of the frame.
+- **Name it in the frame**, with its colour: `the warm string lights behind her melting into
+  oversized creamy golden bokeh`, `snowflakes near the lens drifting as soft white bokeh`.
+- Put a diffusion filter in `params.lookPhrase` for extra glow (`soft black pro-mist diffusion,
+  gentle halation`). Every segment prompt then carries it.
+
+## 5. Camera and motion — slow, floating, lingering
+
+The camera is gentle: slow `Push In` on a realisation, a slow `Arc Shot` circling the couple at a
+confession or a kiss, a floating `Tracking Shot` walking beside them, `Static Shot` for the
+lingering look. No `Shake`, no fast moves. `cameraNote.motivation` is usually `relationship` or
+`stillness`.
+
+- **Slow motion on the 心动 beat.** Write it in the cut's `motion` and `cameraNote`
+  ("in slow motion, her hair lifts in the breeze as she turns"). The video model understands
+  `slow motion`; one or two slow-motion cuts per episode, on the beats that matter.
+- **Ambient motion makes it breathe**: hair and scarves in a breeze, petals or snow drifting,
+  curtains moving, steam from the cups, bokeh lights twinkling. Put it in `cameraNote.hold` on a
+  lock-off, so the frame is never dead still.
+- **Hold the look.** Romance lives in the extra second: let the eye-lock cut run to the upper end
+  of `maxCutSeconds`.
+
+## 6. The 甜宠 set pieces — how to shoot them
+
+The genre's recurring moments (撒糖 beats) are where this look pays off. Each is a short sequence
+of cuts. Mark them as `turn` beats; when one is the episode's 爽点, its scene gets the seeded
+`visualPlan` — fill it with the sequence below.
+
+| moment | the cuts | light and camera | sound |
+| --- | --- | --- | --- |
+| 心动对视 (the eye-lock) | her CU → his CU → back to her, tighter | 85mm T1.5, halo behind each, slow `Push In`, slow motion on the last cut | music `enter` on the last cut |
+| 回眸 (the look back) | wide of her walking away → MS as she turns → CU of her smile | backlight from the sun ahead of her, hair in the wind, slow motion on the turn | music `swell` |
+| 意外靠近 (falls into arms / too close) | MS stumble → two-shot, faces inches apart → alternating ECUs of eyes | soft front key on both faces, `Static Shot`, hold longer than feels safe | music `silence`, a heartbeat sfx if wanted |
+| 共伞 (one umbrella in the rain) | wide of rain and warm shop lights → MS two-shot under the umbrella → insert of the hand on the handle | warm shop windows as key, rain lit from behind as bokeh | rain on the umbrella (sfx), music `enter` |
+| 披外套 / 围巾 (the coat or scarf) | MS as he drapes it → CU of her reaction → insert of hands on the collar | soft window or street lamp, 3/4 front key | music continues |
+| 摸头杀 (hand on her head) | OTS from behind her → CU of her face as the hand lands → his smile | halo behind him, soft front on her | music `silence` as the hand lands |
+| 壁咚 / 近距离对峙 | low two-shot against the wall → CU her → CU him | soft front three-quarter key, never top light, background soft | music `drop` |
+| 公主抱 (the carry) | wide as he lifts her → MS walking toward camera → CU her looking up at him | backlight from the corridor or the sun, slow `Tracking Shot` backwards | music `swell` |
+| 告白 / 初吻 (the confession) | two-shot apart → the gap closes → slow `Arc Shot` around them | golden hour or string lights, flare, slow motion | music `silence` on the line, `swell` as the gap closes |
+
+Sound is part of the look. The OST is the segment's `sound.music` with cues (`enter`, `swell`,
+`duck`, `drop`, `silence`, `out`) placed on the cut: it comes in or swells on the 心动 cut, and
+goes to `silence` just before a confession so the line lands in a hush.
+
+## 7. Cast, wardrobe and sets (for the bibles)
+
+- **Character bibles**: clean, styled, soft-textured wardrobe (knitwear, trench coats, shirts,
+  pastel dresses), neat hair with some movement, the pair's coordinated palettes. Styling is part
+  of the fantasy. With `style: photoreal` the negative-prompt rules in stage-characters still
+  apply; flattering comes from the light, not from banned skin words.
+- **Scenes that suit the genre**: a sunlit café, a rooftop at blue hour, a riverside walk at
+  night, a convenience store at night (warm, not grim), a library by the window, a park in
+  blossom or snow, a bus stop in the rain, the male lead's clean minimal apartment. Give each one
+  a colour (§2) and a soft source (§1) in its lighting states.
+
+## 8. Review questions
+
+- Is the face lit, soft and pretty in every cut with a person? Is there a halo in the hair?
+- Could you name the source (window, sun, string lights)? Is it big and soft?
+- What colour is this scene? Would you recognise it from a thumbnail?
+- Where are the two people in the frame, and is that distance the right one for this episode?
+- Is there something pretty and blurred in front of the lens?
+- On the 心动 beat: does the camera slow down, does the music come in, does the cut linger?

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

@@ -0,0 +1,83 @@
+# Cinematography — choosing and applying a look (`params.cinematography`)
+
+A cinematography preset is the drama's **lighting and composition**. It sits on top of the render
+style (`params.style`: photoreal, painterly, anime…) and the camera package (`params.camera`), and
+the gates hold every scene lighting state, every cut and every video prompt to it. One preset
+covers the whole drama, the same way one style does.
+
+| preset | for | the look in one line | guide |
+| --- | --- | --- | --- |
+| `low-key` | 悬疑 · 犯罪 · 惊悚 · 复仇 · 都市暗黑 | the scene's own practicals, people in shadow, side / back / rim light, negative space | `cinematography-low-key.md` |
+| `sweet-romance` | 甜宠 · 恋爱 · 韩风唯美 · 偶像剧 · 浪漫 | bright soft light on the face, a warm halo in the hair, pastel air, the distance between two people as the story | `cinematography-sweet-romance.md` |
+| `period-nostalgia` | 年代 · 怀旧 · 民国 · 七八九十年代 | a memory shot on film: warm faded grade, grain, window sun and bare bulbs, steady frames full of period detail | `cinematography-period-nostalgia.md` |
+| `costume-idol` | 古装偶像 · 古偶 · 仙侠 · 古装甜宠 | a luminous painted world: faces glowing through gauze, backlit silk, mist and petals, jade and moon-white | `cinematography-costume-idol.md` |
+| `costume-dark` | 古装写实 · 权谋 · 武侠 · 宫斗 · 复仇 | history lit by fire: candles, torches and lattice windows, faces carved from shadow, smoke, earthy texture | `cinematography-costume-dark.md` |
+| `scifi-hard` | 硬科幻 · 太空 · 工程写实 | the future as engineering: instrument panels, work lamps and one harsh sun, cold neutral palette, no magic or floating holograms | `cinematography-scifi-hard.md` |
+| `scifi-soft` | 软科幻 · 赛博朋克 · 未来都市 · 科幻 | the future as feeling: holograms and neon, dual-tone colour light, haze and reflections | `cinematography-scifi-soft.md` |
+| `none` | projects created before the presets, or a look the user describes that fits neither | only the base `photography` rules | — |
+
+**Choosing.** `init` picks from `--genre` (`cinematographyForGenre`), costume and period first:
+
+1. 古装 / 古偶 / 仙侠 / 宫廷 / 武侠 / 权谋… → `costume-idol` when the genre also says 古偶, 仙侠,
+   玄幻 or romance; `costume-dark` when it says 暗黑, 写实, 权谋, 武侠, 江湖, 宫斗, 悬疑, 复仇 or
+   历史; a bare `古装` gets `costume-idol` — **confirm that one with the user**, the two looks are
+   opposites.
+2. 硬科幻 → `scifi-hard`; 软科幻 / 科幻 / 未来 / 赛博朋克 / 星际 → `scifi-soft` (a bare 科幻 gets
+   `scifi-soft` — confirm it with the user).
+3. 年代 / 怀旧 / 复古 / 民国 / 八十年代… → `period-nostalgia`.
+4. 甜宠 / 恋爱 / 爱情 / 浪漫 / 韩风 / 偶像 / romance → `sweet-romance`.
+5. Anything else → `low-key`.
+
+Composition is a separate axis: `params.composition: art-first` (艺术优先) frames any of these
+looks for negative space, symmetry and monumental scale — see `composition-art-first.md`.
+
+`--cinematography` overrides it. When the genre mixes two (a 甜宠 with a revenge plot, a 年代 drama
+that is really a thriller), ask the user which way the *picture* should lean; the story can still
+be dark in a bright look. Write the choice into
+`outline.guideline.visualStyle` too, so the 创作指引 and the pictures agree.
+
+Read the preset's guide before writing the scene lighting states (stage 3) and before the first
+storyboard (stage 5).
+
+## What every preset gates
+
+| where | what must be there | gate |
+| --- | --- | --- |
+| `scenes[].lighting[].prompt` | the preset's `framePhrase`, plus the sources that light the space | `scene-design` |
+| every `cut.frame` | the `framePhrase`, the direction phrase, `light.source` verbatim, the camera phrase, the foreground | `photography` |
+| every `cut.light` | `direction` (never one of the preset's `bannedLight` on a person), `source`, `note` | `photography` |
+| each segment | at least `preferredShare` of the cuts with people keyed from `preferredLight`; at least half with a foreground | `photography` |
+| every `cut.aperture` / `params.camera.aperture` | `maxStop` or faster | `photography` |
+| video prompt, `sheets` mode | the Look line carries the preset's `videoPhrase` (for `wan`: a `画面：` line with `videoPhraseZh`). `prompt segment` writes it for you | `video-prompt` |
+
+| preset | `framePhrase` | `bannedLight` on a person | `preferredLight` (≥ 50 % of cuts with people) | `init` package | `maxStop` | also gated | refused sources |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `low-key` | `low-key practical lighting` | `frontal`, `ambient` | `side-*`, `back-*`, `backlight` | default (T1.5) | T2.8 | — | — |
+| `sweet-romance` | `soft romantic lighting` | `underlight`, `top` | `front-left`, `front-right`, `back-*`, `backlight` | Master Prime **T1.3** | **T2** | ≥ 50 % of frames name their `bokeh` | — |
+| `period-nostalgia` | `nostalgic period film look` | `frontal`, `underlight` | `front-left`, `front-right`, `side-*`, `back-left`, `back-right` | default (T1.5) | **T4** | — | LEDs, smartphones, laptops, tablets, flat screens, ring lights |
+| `costume-idol` | `ethereal costume drama lighting` | `underlight`, `top` | `front-left`, `front-right`, `back-*`, `backlight` | Master Prime **T1.3** | **T2** | ≥ 50 % `bokeh`; every segment has a `wide` / `extreme-wide` whose frame says `negative space` | anything electric |
+| `costume-dark` | `low-key firelit period lighting` | `frontal`, `ambient` | `side-*`, `back-*`, `backlight` | default (T1.5) | T2.8 | every segment has a `wide` / `extreme-wide` whose frame says `negative space` | anything electric |
+| `scifi-hard` | `grounded hard science fiction lighting` | `frontal`, `ambient` | `side-*`, `back-left`, `back-right`, `top` | default (T1.5) | T2.8 | — | magic, holograms, force fields, energy glows |
+| `scifi-soft` | `luminous soft science fiction lighting` | `frontal`, `ambient` | `side-*`, `back-*`, `backlight` | default (T1.5) | T2.8 | — | — |
+
+"Refused sources" is checked against `light.source` only: a frame may still say what is *not*
+there.
+
+In `keyframes` mode each keyframe is generated from its frame, so the frames carry the look and
+the video prompt does not repeat it.
+
+**The phrases never name a nationality.** "Korean drama" or 韩剧 in a look phrase pulls every
+face toward that ethnicity, whatever the character sheets say. The look is described by its
+light, colour and lens; the faces come from the sheets.
+
+**Character sheets are the exception.** A sheet is an identity reference, not a shot. It keeps its
+own lighting (a soft directional key in the portrait zone, flat and even in the turnaround zones;
+see stage-characters), because a face the model cannot read on the sheet is a face it cannot
+match. The preset is applied in the shot, not on the sheet.
+
+## Adding a preset
+
+A new look is an entry in `CINEMATOGRAPHY_PRESETS` (`scripts/short-drama.mjs`) with the fields
+above (plus, where the look needs them, `anachronisms`, `kit`, `bokehShare`, `widePerSegment`), a `cinematography-<key>.md` guide in the same shape as the two here (light, colour,
+composition, lens, camera and motion, review questions), a row in the tables above, and selftest
+cases. Add a genre pattern to `cinematographyForGenre` if `init` should pick it on its own.

package/skill/short-drama/reference/composition-art-first.md

@@ -0,0 +1,74 @@
+# Composition `art-first` — 艺术优先
+
+**Composition comes before coverage.** Every frame is built like a painting or a photograph:
+vast negative space, rigorous symmetry, monumental scale with small figures in immense spaces,
+strong geometry, a patient camera. It works in **any genre and any look**: an art-first 古装, an
+art-first 硬科幻, an art-first 悬疑, an art-first 甜宠. Set it for the drama
+(`params.composition: art-first`) or for one segment (`"composition": "art-first"`); a segment in
+an art-first drama can step out with `"composition": "standard"` (a chaotic fight, a crowded
+market).
+
+## 1. The devices — `cut.composition`
+
+Every cut of an art-first segment names its devices (one or more). Each device's phrase is gated
+verbatim in the frame:
+
+| device | phrase in the frame | 中文 | use |
+| --- | --- | --- | --- |
+| `negative-space` | vast negative space | 大面积留白 | a small figure and a big empty field (sky, wall, snow, sea, darkness): loneliness, awe, waiting |
+| `symmetry` | perfectly symmetrical composition | 严格对称构图 | the centred axis: power, ritual, order, something too perfect |
+| `grand-scale` | monumental scale with small figures in an immense space | 宏大壮观的空间中人物渺小 | the world bigger than the people: a palace, a ship, a canyon, a city |
+| `frame-in-frame` | framed within a frame | 框中框构图 | doors, windows, arches, mirrors: a character trapped or watched |
+| `leading-lines` | strong leading lines | 强烈的引导线 | corridors, rails, roads, beams converging on the subject |
+| `silhouette` | a stark silhouette against the light | 逆光中的鲜明剪影 | the shape of a person or an act, not the face |
+| `layered-depth` | layered foreground, midground and background | 前中后景层次分明 | a world with depth |
+| `color-block` | bold blocks of flat colour | 大块平涂色块 | graphic, painted frames |
+| `top-down` | a graphic top-down view | 图形化的俯视构图 | patterns, bodies on a floor, a table from above |
+| `thirds` | the subject placed on a third | 主体位于三分线 | the quiet default |
+
+**Gated** (waivable per segment when the user asks):
+- `composition-device` — every cut names at least one device, and its phrase is in the frame.
+- `signature-share` — at least **half** the cuts of a segment use a signature device:
+  `negative-space`, `symmetry` or `grand-scale`.
+- `art-wide` — every segment has at least one `wide` or `extreme-wide`.
+- The prompt carries the `Composition:` line (`构图：` for `wan`); `prompt segment` writes it.
+
+**Advisory** (`grammar-advice`): cuts average 3 s or more, so a composed frame can be seen (not in
+fight or comedy segments); no handheld in an art-first segment unless it is a fight or a gag.
+
+## 2. How to build an art-first frame
+
+- **Decide what the empty space means** before placing the person: the sky they will never
+  reach, the corridor they must walk, the wall between two people.
+- **Place the figure small and exact**: on the axis for symmetry, on a third or at an edge for
+  negative space, low in a 9:16 frame under the sky or high above an empty floor.
+- **Hold it.** The camera is `Static Shot`, or moves slowly and ends on a composed frame
+  (`cameraNote.endFraming` says the composition it lands on).
+- **Let one element break the geometry**: the red umbrella in the grey square, the one figure
+  facing the other way. That is where the eye goes.
+- **Colour with intent**: few colours, large areas. Pair with the look's palette.
+- **Close-ups are composed too**: a face on a third with the empty side where it looks; a
+  symmetrical face straight to camera for a moment of truth.
+
+Write it: `extreme wide shot, perfectly symmetrical composition down the snow-covered palace
+axis, a lone figure in red kneeling at the centre, vast negative space of white on both sides`.
+
+## 3. With the other axes
+
+| combination | how it plays |
+| --- | --- |
+| `costume-idol` / `costume-dark` | the palace axis, the court in rows, the lone figure in a snow field; the costume presets' wide-with-negative-space rule is already met |
+| `scifi-hard` | engineered symmetry of corridors and airlocks, the ship dwarfed by a planet |
+| `scifi-soft` | the tiny figure under a wall of holograms, the symmetrical neon street |
+| `low-key` | silhouettes and one pool of light in darkness as negative space |
+| `sweet-romance` | the couple small in a vast bright landscape, symmetry for the confession |
+| `grammar: action` | the fight inside the geometry: wide locked-off frames, the moves readable, fewer cuts |
+| `grammar: faceslap` | the hero centred on the axis, the room arranged symmetrically around the reversal |
+| `grammar: comedy` | the `deadpan` style is already art-first; slapstick in symmetry is its own joke |
+
+## 4. Review questions
+
+- What does the empty space mean in this frame?
+- Is the figure placed exactly — on the axis, on a third, at the edge?
+- Is there one element that breaks the geometry, and is it the one that matters?
+- Would this frame hold up as a still photograph?

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

@@ -141,7 +141,9 @@ names: the frame is delivery text.
 Lighting: `light.direction` is relative to the camera; `light.note` describes what the light
 *does* on the face or the object ("the cabinet glow holds the right of his face; nothing moves
 but the light on his jaw") — the result reads more stably than the position alone, and it must
-say whether left / right is the screen's or the subject's.
+say whether left / right is the screen's or the subject's. Under a `params.cinematography`
+preset the key is a named source (`light.source`), and the preset decides which directions a
+person may and should be keyed from. See `cinematography.md`.
 
 ## 7. Generability (gates `filmable`, `motion`; advice in `storyboard-advice`)
 

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

@@ -15,7 +15,7 @@ the focusing questions first, do not pad a synopsis around a blank.
 
 | 判断项 | 必须回答的问题 | 合格标准 | field |
 | --- | --- | --- | --- |
-| 题材定位 | 复仇、逆袭、甜宠、豪门、悬疑、古装、家庭伦理，还是混合？ | 类型清晰，不能只写“爱情”或“都市” | `params.genre` |
+| 题材定位 | 复仇、逆袭、甜宠、豪门、悬疑、古装、家庭伦理，还是混合？ | 类型清晰，不能只写“爱情”或“都市” | `params.genre`, `params.story` (the genre rules: `story.md`) |
 | 受众定位 | 主要观众追求什么情绪补偿？ | 能说出观众想看的爽感、痛点或幻想 | `audience` |
 | 一句话卖点 | 主角、困境、反击与最大看点，一句话 | 句子内同时有角色、冲突、反转或利益点 | `logline` |
 | 核心爽点 | 打脸、复仇、强宠、身份揭露、智商碾压还是情感释放？ | 爽点可以反复变奏，不是一场戏就用完 | `satisfactionEngine` |
@@ -99,6 +99,9 @@ episodes.
 
 ## 6. Inside an episode — the formula (gate `rhythm`, stage 4)
 
+The seconds below are the `short` format's. A `medium` episode hooks by 30 s and turns every
+60 s; a `movie` part turns every 90 s and only the first part needs the cold open — `format.md`.
+
 | 段落 | 目标 | 必须出现 | 检查问题 |
 | --- | --- | --- | --- |
 | 0–15 秒 | 立即留住观众 | 冲突、羞辱、危机、奇观、秘密、反转 | 观众不看上一集，是否仍会想继续看？ |

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

@@ -0,0 +1,94 @@
+# Format — short drama, medium drama, movie (`params.format`)
+
+The skill makes three kinds of work with **the same pipeline and the same story structure**: an
+outline of units, a script per unit, a storyboard per unit, the sheets, the clips. What changes is
+how long a unit is and the pulse it is held to.
+
+| | `short` 短剧 | `medium` 中剧 | `movie` 电影 |
+| --- | --- | --- | --- |
+| unit | 集 (episode) | 集 (episode) | 段 (part) of one film |
+| length | 1–3 min | 4–15 min | 3–8 min (≈ 5) |
+| count | 30–100 | 10–40 | ≈ 18 for a 90-minute film |
+| default ratio | 9:16 | 16:9 | 16:9 (21:9 for scope) |
+| hook | a cold open every episode, on screen by 15 s | every episode, by 30 s | **the first part only**, by 60 s |
+| turns | every 30 s | every 60 s | every 90 s |
+| lines in a row | ≤ 3 | ≤ 4 | ≤ 5 |
+| action beside dialogue | ≥ 35 % | ≥ 30 % | ≥ 25 % |
+| cliff | every episode | every episode | at the act breaks (the end of golden and escalation); a part ends on a turn or a question |
+| paywall logic | 卡点 at E8–12, ~E30 | the first cliffs of the season | none — the audience has paid for the whole film |
+
+`init` reads the format from the genre (电影 / 微电影 / movie → `movie`, 中剧 / 横屏剧 → `medium`) or from
+the length (over 3 minutes → `medium`); `--format` overrides it. The rhythm values above are
+defaults: a project may still set `hookSeconds`, `turnSeconds`, `maxConsecutiveLines` or
+`minActionRatio` itself. `validate` flags a unit length outside the format's range.
+
+## What stays the same
+
+- **The outline**: the brief (the six judgements), the three phases, the 创作指引, beats, and one
+  outline unit per episode or part, each with its function, task, change, 爽点 and hook. In a movie,
+  **golden / escalation / climax are acts one, two and three**, and each part's "hook" is the question
+  or turn it hands to the next part.
+- **The bibles, the script beats, 谈话+行动, filmability**, the storyboard, the canvases (one per unit),
+  the references and the gates.
+- **The looks, the action styles, the grammars, the composition and the story genres** — all of them.
+
+## How the genre rules scale
+
+The story-genre rules are mostly **shares of the run** (the turn at 25–45 %, the arch-nemesis at
+80 %, the black moment at 70–90 %), which mean the same thing in every format. The few written as
+counts ("a payback by E3", "no more than 3 episodes without sugar", "a breakthrough every 12") were
+researched on 1–2-minute episodes, so they convert:
+
+- **medium — by runtime.** Three 1.5-minute episodes are one 5-minute episode: "by E3" becomes "by
+  E1", "every 12 episodes" becomes "every 4".
+- **movie — by share of the film**, because a film is not paced like a paywalled series: "the first
+  payback by E3" becomes "by 20 % of the film" (part 4 of 18), "at most 3 without sugar" becomes
+  "at most ~20 %".
+- **"long enough"** conditions (a rule that only applies to runs of 20+ episodes) compare runtime,
+  so a 90-minute film or a 24 × 5-minute season qualifies.
+
+Messages then speak of *units* rather than episodes. The comedy density converts by the minute
+outside `short`: at least `0.8 × minutes` punchlines a unit for `slapstick` / `deadpan`,
+`0.5 × minutes` otherwise (4 and 3 in a 5-minute unit).
+
+## Medium drama (中剧)
+
+The 4–15-minute episode (横屏微短剧 and the short series of the long-video platforms) keeps the 短剧
+engine — a hook, turns, a 爽点, a cliff in every episode — with room to breathe:
+
+- **Each episode has an A story and, from 8 minutes up, a B story**; two or three turns; the 爽点 in
+  the back half; the cliff at the end.
+- **Scenes can run longer** (a 90-second confrontation plays), but keep the turn every minute.
+- **The season still front-loads**: the first three episodes build retention (the `episode-design`
+  gate still checks E1 grabs, E2 proves the 爽点, E3 widens the line).
+- **16:9** opens the frame: two-shots and wides carry more; the `composition` and `cinematography`
+  guides apply as written.
+
+## Movie in parts (电影)
+
+A feature written as ~5-minute parts is still one story. Think of the parts as **sequences** — each
+with a local goal, an obstacle and a turn — grouped into three acts:
+
+| act | phase | share | what happens |
+| --- | --- | --- | --- |
+| 1 | golden | ~25–30 % | the opening image and the hook in part 1; the world and the want; the catalyst at ~10 %; the break into act two |
+| 2 | escalation | ~45–50 % | fun and games — the genre's promise delivered; **the midpoint** at 50 % (a false win or a false loss, the stakes raised); the bad guys close in |
+| 3 | climax | ~20–25 % | all is lost at ~75 %; the dark night; the finale that pays every plant; the closing image |
+
+- **A part ends on a button, not a cliffhanger** — a turn, a decision, a question — except at the two
+  act breaks, where the film does cliff. The part's `hookType` names what it hands on.
+- **Plant and pay off across the whole film**: the mystery clue ledger, the revenge ladder, the
+  romance milestones and the running gags all work on the film's parts exactly as on episodes.
+- **The 爽点 per part** becomes the part's payoff — a small win, a reveal, a laugh, a scare — so a film
+  written this way keeps the 短剧's density of payoffs without its cliff at every cut.
+- **Production**: each part is still a unit of work — its own script file, its own storyboard (about
+  twenty 15-second generations for 5 minutes), its own canvas. Continuity across parts is the same
+  continuity across segments (`craft-shots.md`), carried by the sheets.
+- **The frame**: 16:9 by default, 21:9 for a scope film; the `art-first` composition suits cinema.
+
+## Choosing
+
+Ask at the parameters question. A vertical, paywalled, many-episode series is `short`; a
+horizontal series of longer episodes is `medium`; a single story meant to be watched in one go is a
+`movie`, whatever its length. When in doubt, ask where it will be released and how it will be
+watched.

package/skill/short-drama/reference/grammar-comedy.md

@@ -0,0 +1,105 @@
+# Grammar `comedy` — 喜剧
+
+Comedy is **timing and faces**. A joke is a setup, a punchline and the room to laugh; the camera's
+job is to let the audience see the face and give the laugh its beat. Three styles
+(`params.comedy`) share that grammar and differ in rhythm and camera. Combinations and exceptions:
+`grammar.md`.
+
+Use it on a segment with `"grammar": "comedy"`, or make it the default (`params.grammar:
+comedy`) in a comedy, where a straight scene sets `grammar: drama` on itself.
+
+## 1. The shared grammar
+
+| field | on | meaning |
+| --- | --- | --- |
+| `gag: "setup"` | the cut that plants the joke | the expectation, the rule, the lie, the thing that will go wrong |
+| `gag: "build"` | optional, cuts that raise it | the rule of three: the same thing twice, then the twist |
+| `gag: "punchline"` | the cut the joke lands on | the reversal, the reveal, the pratfall, the line |
+| `purpose.kind: "reaction"` | the cut after the punchline | the laugh room: the face that takes the joke |
+
+**Gated:**
+- **Setup first** (`setup-first`): a punchline needs a `setup` earlier in the same scene.
+- **Laugh room** (`punchline-reaction`): a punchline is followed by a `reaction` cut of at least
+  the style's `hold` seconds, **or** the punchline itself is a `Static Shot` held `hold + 1`
+  seconds (the awkward hold).
+
+**Advisory** (`grammar-advice`): a comedy segment with no punchline; the average cut length of the
+style; its signature shot; a punchline keyed from the side or behind in a `low-key` /
+`costume-dark` drama (a laugh needs the face).
+
+**Craft that holds for all three:**
+- **Faces must read.** Comedy is the one grammar that asks the light to reach the face on the
+  punchline, even in a dark look.
+- **The reaction is funnier than the action.** Cut to the person who sees it, not the thing
+  itself, and hold.
+- **The rule of three**: set it up, repeat it, break it. Mark the first two `setup` / `build`.
+- **Callbacks**: a setup in episode 1 can pay off in episode 5; put the setup on the cut
+  (`gag: setup`) so the payoff can point at it.
+- **Silence is a sound**: a `silence` music cue or a pause in the ambience before the punchline.
+- **Model limits**: a pratfall, a spit take, a double-take, a jaw drop, a freeze are common
+  actions and render well; a precise timed collision (a pie hitting a moving face) does not —
+  show the before and the after.
+
+## 2. `slapstick` — 无厘头喜剧
+
+Big, fast, physical, exaggerated. Faces stretched, bodies flung, logic abandoned.
+
+- **Rhythm**: short cuts (2–3 s); laugh room `hold` = 2 s.
+- **Camera**: the **crash zoom** (`Zoom In`) onto a stunned face is the signature; whip pans
+  (`Pan Left` / `Pan Right`) between two people; a freeze-frame on the peak of the gag;
+  `Shake Slightly` on a crash.
+- **Sound**: cartoon sfx on every beat (boing, whoosh, record scratch), a comic sting after the
+  punchline, sudden silence.
+- **Set pieces**: the double-take; the pratfall on the prop planted in the setup; the
+  over-the-top 反应 (fainting, spitting tea); the absurd escalation of a small lie.
+- **Example `motion.action`**: `he spits the tea across the table`; `she freezes with the
+  chopsticks halfway to her mouth`.
+
+## 3. `deadpan` — 冷面处境喜剧
+
+Dry, still, awkward. The frame does the joke: symmetrical static shots held a beat too long,
+characters with straight faces in an absurd situation.
+
+- **Rhythm**: long cuts (3–5 s); laugh room `hold` = 3 s — the silence after is the joke.
+- **Camera**: locked-off (`Static Shot`) wides and mediums, centred and symmetrical; people
+  arranged in a row facing the camera; no zooms, no shake.
+- **Sound**: no comic sfx, often no music; the ambience (a clock, a fly, a fridge hum) fills the
+  awkward pause.
+- **Set pieces**: the awkward silence after the wrong thing is said; the straight-faced
+  explanation of something absurd; the slow turn of every head in the row; the cut to the one
+  person who has not moved.
+- **Example `motion.action`**: `all four turn their heads toward him at the same time`; `he sets
+  the cup down very slowly`.
+
+## 4. `romcom` — 甜宠喜剧
+
+Cute, flustered, embarrassed. The joke is on the lovers: the misunderstanding, the accidental
+closeness, the blush.
+
+- **Rhythm**: 2–4 s; laugh room `hold` = 2 s.
+- **Camera**: close-up reactions (the blush, the double-take, the eyes going wide) are the
+  signature; a `Push In` on the embarrassed face; the two-shot of the misunderstanding with both
+  faces readable. Pairs with the `sweet-romance` look.
+- **Sound**: playful pops and plinks, a heartbeat, a cute sting; the OST can enter on the blush.
+- **Set pieces**: the overheard sentence taken the wrong way; the accidental fall into each
+  other's arms (then the scramble apart); the text sent to the wrong person; the jealous
+  friend's exaggerated reaction; the third wheel.
+- **Example `motion.action`**: `her face goes red and she hides behind the menu`; `he does a
+  double-take between the phone and her` (one action).
+
+## 5. With the other axes
+
+| combination | how it plays |
+| --- | --- |
+| `costume-idol` / `costume-dark` (古装喜剧) | court etiquette as the straight line the joke breaks; `deadpan` suits a court, `slapstick` a tavern |
+| `period-nostalgia` (年代喜剧) | `deadpan` with the era's objects as props; the static tableau is already an old photograph |
+| `sweet-romance` | `romcom` |
+| with `action` (`hk-kungfu`) | the comic fight: the setup is the prop, the punchline the hit that goes wrong, the reaction the shaken hand |
+| with `faceslap` | the villain's comeuppance played to farce |
+
+## 6. Review questions
+
+- Where is the setup, and does the audience see it?
+- Whose face takes the joke, and for how long?
+- Is the face lit on the punchline?
+- Is the camera doing the style — crash zoom, locked-off symmetry, or the close-up blush?