@wji.ai/cli 0.4.0 → 0.5.0

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?

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

@@ -0,0 +1,67 @@
+# Grammar `faceslap` — 爽剧打脸
+
+The payoff 短剧 audiences come for: the hero who was mocked, doubted or trampled **turns the
+tables in public**. The whole beat is built for one feeling (扬眉吐气): the arrogance before, the
+calm of the hero, the proof, then face after face changing its tune. Cut it as a sequence, not as
+one shot. Combinations and exceptions: `grammar.md`.
+
+Use it on a segment with `"grammar": "faceslap"` — always on the 爽点 of an episode whose
+`satisfaction.type` is 打脸, 身份揭露, 智商碾压 or 复仇, and anywhere else the tables turn.
+
+## 1. The sequence
+
+| # | beat | cut | purpose | notes |
+| --- | --- | --- | --- | --- |
+| 1 | **the pressure** (压) | the villain's arrogance: the sneer, the insult, the crowd laughing along | `pressure` | the harder the setup, the harder the payoff; can sit in the segment before |
+| 2 | **the calm** (静) | the hero unmoved: a small smile, a slow look up, the untouched tea | `performance` | stillness against their noise |
+| 3 | **the entrance / the move** (起) | the hero stands, walks in, or someone important enters on their side; **low angle**, often slow motion | `reveal` / `decision` | the music enters here |
+| 4 | **the proof** (证) | an insert on what turns the tables: the contract, the black card, the badge, the ring, the phone screen, the transfer receipt, the photograph | `evidence` / `reveal` | gated: every 打脸 shows its proof |
+| 5 | **the cascade** (反应链) | face after face: the villain pales, the crowd whispers, the one who doubted drops their cup, the villain's ally steps away | `reaction` × 2 or more | gated: ≥ 2 reaction cuts (this segment and the next in the scene), on different people |
+| 6 | **the landing** (落) | the villain's consequence (kneels, is escorted out, loses the deal) or the hero's quiet last line | `consequence` | the hook for the next beat can hide here |
+
+Beats 1–2 may belong to the segment before. The gate checks 4 and 5; the advisory
+`grammar-advice` notes a missing pressure cut, a missing low angle and a missing music hit.
+
+## 2. Camera and framing
+
+- **The hero from below** (`height: low`), centred, unhurried; the villain at eye level or from
+  above as they shrink. Swap the power geometry of the earlier scenes.
+- **The proof in close-up or extreme close-up**, held long enough to read (2–3 s). Readable text
+  follows the prop's `textPolicy` (stage-art). A slap on the table is the classic entrance for it.
+- **The cascade in close-ups**, each a different face, 2 s each, cut on the beat of the music.
+  A `Push In` on the villain's face as it drains is the signature shot.
+- **Slow motion** on the entrance or the proof (`in slow motion` in `motion`), once.
+- **The crowd** is the chorus: one wide of the room changing its tune (heads turning, phones
+  lowering) sells the scale. Staging per `maxOnScreen`.
+
+## 3. Sound
+
+`sound.music`: `silence` or `drop` under the insult (the room holds its breath), `enter` or
+`swell` on the entrance or the proof, full through the cascade. `sound.sfx`: the slap of the
+document on the table, the gasp, the cup falling, the murmur rising. A single line from the hero,
+quiet, often lands harder than a speech.
+
+## 4. With the other axes
+
+| combination | how it plays |
+| --- | --- |
+| `low-key` look | the hero steps out of the shadow into the practical light for the reveal |
+| `sweet-romance` look (霸总) | the male lead arrives to back her; the halo behind him on the entrance |
+| `costume-dark` (宫斗) | the edict, the jade token, the imperial seal as the proof; kneeling as the landing |
+| with `action` | the underdog's single decisive blow, then the cascade of the watching crowd |
+| with `comedy` | the villain's reaction pushed to farce (the jaw drop, the spit take), still ≥ 2 reactions |
+
+## 5. Example cut lines
+
+- pressure: `the young heir laughs and tosses the contract onto the floor at her feet`
+- entrance: `she rises from the chair in slow motion and looks up at him`
+- proof: `she lays the black card on the table`
+- reaction: `his smile drains away and he takes half a step back`
+- reaction: `the manager's pen stops above the page`
+
+## 6. Review questions
+
+- Was the hero pushed down hard enough before?
+- Can the audience read the proof?
+- How many different faces change — at least two?
+- Is the hero shot from below, and does the music come in?

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

@@ -0,0 +1,103 @@
+# Genre = axes + grammars — how a drama's look and cutting are composed
+
+A genre like 古装喜剧 or 未来动作 is not one setting. It is a **combination**: what the world looks
+like, how people talk, and how each scene is cut. The skill keeps those apart so any combination
+works, and never needs a preset per genre.
+
+## 1. The drama's axes (one value each, in `params`)
+
+| axis | param | what it decides | values | guide |
+| --- | --- | --- | --- | --- |
+| render | `style` | how the picture is drawn | `photoreal` · `realistic` · `ghibli` · `soft3d` · `disney3d` | stage-characters |
+| look | `cinematography` | light, colour, the world | `low-key` · `sweet-romance` · `period-nostalgia` · `costume-idol` · `costume-dark` · `scifi-hard` · `scifi-soft` · `none` | `cinematography.md` |
+| framing | `composition` | what the frame is built for, in any genre (a segment may override it) | `standard` · `art-first` (艺术优先: negative space, symmetry, monumental scale) | `composition-art-first.md` |
+| lines | `register` | how dialogue is written and spoken | `粤语` · `大陆普通话` · `台湾国语` · `港式普通话` · `古装` · `年代` · `英文美式` · `英文英式` | dialogue-craft |
+| fights | `action` | how a fight is cut | `gun-fu` · `hk-kungfu` · `wuxia-fantasy` · `historical-realist` · `bullet-time` · `superhero` · `street-brawl` · `car-chase` · `none` | `action.md` |
+| laughs | `comedy` | how a gag is cut | `slapstick` · `deadpan` · `romcom` · `none` | `grammar-comedy.md` |
+| default cutting | `grammar` | the grammar of a segment that does not name its own | `drama` · `action` · `faceslap` · `comedy` | this file |
+
+## 2. The segment's grammar (per storyboard segment)
+
+Each segment is cut in one or more grammars: `segment.grammar` (a string or an array), else
+`params.grammar`.
+
+| grammar | for | adds | guide |
+| --- | --- | --- | --- |
+| `drama` | ordinary scenes | nothing beyond the base storyboard rules | — |
+| `action` | fights, chases, power battles | open wide, one move per cut, a reaction after every impact, in `params.action`'s style | `action.md` |
+| `faceslap` | the 打脸 payoff: 身份揭露, 智商碾压, 复仇 reversals | the proof on screen, a cascade of ≥ 2 reactions | `grammar-faceslap.md` |
+| `comedy` | gags | a setup before every punchline, laugh room after it, in `params.comedy`'s style | `grammar-comedy.md` |
+
+**Grammars combine.** `"grammar": ["action", "comedy"]` is a comic fight (a 港式功夫喜剧 brawl):
+every hard rule of both applies, and the prompt carries both lines. `["faceslap", "comedy"]` is a
+comic 打脸 (the villain's jaw literally drops). `["action", "faceslap"]` is the fight in which the
+underdog wins and the room turns.
+
+**The prompt says how it is cut.** `prompt segment` writes one labelled line per grammar,
+gated verbatim: `Action: …`, `Payoff: …`, `Comedy: …` (for `wan`: `动作：`, `爽点：`, `喜剧：`).
+
+## 3. Recipes — common 短剧 genres as combinations
+
+`init` reads every axis from `--genre` on its own (the look, the action style, the default
+grammar and the comedy style), so `--genre 古装喜剧` already composes the first row. Confirm the
+result with the user and override any axis with its flag; a value in *italics* below is one
+`init` does not pick from the genre alone, so pass it.
+
+| genre | look | register | default grammar | action | comedy | 打脸 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 古装喜剧 | `costume-idol` (or `costume-dark` for a dry court comedy) | 古装 | `comedy` | — | `slapstick` / `deadpan` | on the 爽点 |
+| 未来动作 / 科幻动作 | `scifi-soft` (or *`scifi-hard`*) | any | `drama` | `bullet-time` (or *`superhero`*) | — | — |
+| 硬科幻 | `scifi-hard` | any | `drama` | — | — | — |
+| 赛博朋克 | `scifi-soft` | any | `drama` | *`gun-fu` / `street-brawl`* | — | — |
+| 艺术古装 / 文艺科幻 / any 艺术 genre | the genre's look | any | the genre's | — | — | — · plus `composition: art-first` |
+| 霸总甜宠 | `sweet-romance` | 大陆普通话 | `drama` | — | `romcom` for the gags | on the 爽点 |
+| 战神 / 赘婿 / 逆袭 | `low-key` or `none` | any | `drama` | *`street-brawl` / `gun-fu`* | — | **every 爽点** |
+| 港式功夫喜剧 | *`none`* | 粤语 | `comedy` | `hk-kungfu` | `slapstick` | — |
+| 仙侠 | `costume-idol` | 古装 | `drama` | `wuxia-fantasy` | — | — |
+| 宫斗 / 权谋 | `costume-dark` | 古装 | `drama` | `historical-realist` if it fights | — | **every 爽点** |
+| 年代喜剧 | `period-nostalgia` | 年代 | `comedy` | — | *`deadpan`* | — |
+| 甜宠喜剧 | `sweet-romance` | any | `comedy` | — | `romcom` | — |
+| 都市悬疑 | `low-key` | any | `drama` | — | — | — |
+
+`init` also reads `composition: art-first` when the genre says 艺术 / 文艺 / arthouse; for any other
+genre, pass `--composition art-first` when the user asks for art-first framing.
+
+How to read a mixed genre:
+- **The look is the world**, and there is one. A comedy set in a palace is `costume-*`, not a
+  "comedy look".
+- **The default grammar is what most scenes are.** In a comedy, most segments are comedy, and the
+  straight scene sets `grammar: drama` on itself. In a drama with a few jokes, the default is
+  `drama` and the gag segments set `comedy`.
+- **Fights, 打脸 and gags are segments.** Mark them where they happen, not on the whole drama.
+- **The 爽点 of a 打脸-type episode is a `faceslap` segment.** When the outline's
+  `satisfaction.type` is 打脸 / 身份揭露 / 智商碾压 / 复仇, the advisory `grammar-advice` names the
+  segment carrying the `satisfactionBeat` if it is not cut as one.
+
+## 4. Exceptions
+
+Every hard grammar rule can be waived for one segment when **the user asks for it**:
+`"exceptions": [{ "rule": "<rule>", "reason": "user: <what they asked>" }]`. The rules:
+`open-wide` · `one-move` · `impact-reaction` · `no-graphic` (action), `reveal-insert` ·
+`reaction-chain` (faceslap), `punchline-reaction` · `setup-first` (comedy), `composition-device` ·
+`signature-share` · `art-wide` (art-first). Never add an exception
+yourself to turn a gate green. The old `actionExceptions` key and `action: true` still work.
+
+## 5. Gates
+
+| gate | checks |
+| --- | --- |
+| `grammar` | grammars are known; `params.action` / `params.comedy` are chosen when a segment uses them; exceptions name a rule and carry a reason; `gag` values; each grammar's line in the prompt |
+| `action` | the fight rules (`action.md`) |
+| `faceslap` | the proof on screen; ≥ 2 reactions after it (this segment and the next one in the scene) |
+| `comedy` | a setup before every punchline (in the scene); laugh room after it |
+| `action-advice` · `grammar-advice` | rhythm, signature shots, 打脸 craft, comedy craft, the 爽点 link (advisory) |
+| `composition` | art-first: every cut's devices named and in the frame, ≥ 50 % negative space / symmetry / monumental scale, a wide per segment |
+| `no-ip-names` | no film, franchise or performer names anywhere |
+
+## 6. Adding a grammar or a style
+
+A new **style of an existing grammar** (a fourth comedy style, a ninth action style) is an entry
+in `COMEDY_STYLES` / `ACTION_STYLES` with its phrases, rhythm and signature shots, plus a section
+in its guide. A new **grammar** (suspense, horror, melodrama…) is a name in `GRAMMARS`, its hard
+rules in a gate, its advisory craft in `grammar-advice`, a line in `grammarLines`, and a guide
+`grammar-<name>.md` in the same shape as the two here.

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

@@ -15,7 +15,7 @@ node {baseDir}/scripts/short-drama.mjs <cmd> {project} …
 
 | Operation | Command |
 | --- | --- |
-| `init` | `short-drama.mjs init {project} --title "<t>" --episodes N --minutes M --genre "<g>" --register 台湾国语 [--adapt 抽核] [--ratio 9:16] [--video h3\|seedance\|seedance2\|seedance2fast\|wan] [--resolution 480P…] [--accent "<accent>"] [--style photoreal\|realistic\|ghibli] [--references sheets\|keyframes] [--duration auto\|fixed] [--look "<lens>"] [--lang zh]` |
+| `init` | `short-drama.mjs init {project} --title "<t>" --episodes N --minutes M --genre "<g>" --register 台湾国语 [--adapt 抽核] [--ratio 9:16] [--video h3\|seedance\|seedance2\|seedance2fast\|wan] [--resolution 480P…] [--accent "<accent>"] [--style photoreal\|realistic\|ghibli] [--references sheets\|keyframes] [--duration auto\|fixed] [--look "<lens>"] [--cinematography low-key\|sweet-romance\|period-nostalgia\|costume-idol\|costume-dark\|scifi-hard\|scifi-soft\|none] [--action <style>\|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]` |
 | `validate` | `short-drama.mjs validate {project} [--stage <stage>] [--ep N]` — exits 1 on a hard failure, 0 on advisories alone |
 | `checkup` | `short-drama.mjs checkup {project}` — same, but prints the passing and skipped rows too |
 | `seed` | `short-drama.mjs seed {project} script --ep N [--force]` · `… seed {project} storyboard --ep N [--force]` |

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

@@ -67,6 +67,15 @@ All commands accept either the directory or the `project.json` path.
 | `audioTrack` | `bed` | the Seed Audio node per segment: `bed` (ambience + sfx + timed music, no voices), `full` (the bed plus every line in the connected `@Audio1..3` voices — at most three speakers), `none` |
 | `subtitles` | false | `true` drops the subtitles-off sentence requirement from the prompts |
 | `maxFrameChars` | 900 | frames longer than this are flagged as padding (advisory) |
+| `composition` | picked by `init` from the genre (`standard` unless it says 艺术 / 文艺) | what the frame is built for, `COMPOSITION_STYLES`: `standard` or `art-first` (艺术优先: every cut names its devices, ≥ 50 % negative space / symmetry / monumental scale, a wide per segment, a `Composition:` line); a segment may override it with its own `composition`; see `composition-art-first.md` |
+| `grammar` | picked by `init` from the genre (`comedy` for a comedy, else `drama`) | the grammar a segment without its own `grammar` is cut in: `drama` · `action` · `faceslap` · `comedy`; see `grammar.md` |
+| `comedy` | picked by `init` from the genre (`none` unless a comedy) | the comedy style, `COMEDY_STYLES`: `slapstick` · `deadpan` · `romcom` · `none`; see `grammar-comedy.md` |
+| `format` | `short` (`init` reads it from the genre or the length) | `short` 短剧 (1–3 min), `medium` 中剧 (4–15 min), `movie` 电影 in ~5-minute parts; sets the default `hookSeconds` / `turnSeconds` / `maxConsecutiveLines` / `minActionRatio` and how the genre counts scale (`span`); see `format.md` |
+| `market` | `mainland` | `mainland` or `overseas` — on the mainland a horror threat is explained rationally and the superstition notes apply |
+| `story` | read by `init` from the genre (empty unless it names one) | the story genres, a list: `revenge` · `sweet` · `mystery` · `comedy` · `angst` · `family` · `palace` · `cultivation` · `scifi` · `horror`; each adds an outline ledger and rules (gates `story-*`); see `story.md` |
+| `action` | `none` (`init` reads it from the genre only when named) | how fight segments are cut, `ACTION_STYLES`: `gun-fu`, `hk-kungfu`, `wuxia-fantasy`, `historical-realist`, `bullet-time`, `superhero`, `street-brawl`, `car-chase` or `none`; see `action.md` |
+| `violence` | `blood` | `blood` lets frames and prompts show blood and wounds (never dismemberment, decapitation or organs); `implied` shows impact only through reaction and sound |
+| `cinematography` | picked by `init` from the genre (`none` when the key is missing) | the lighting and composition preset, `CINEMATOGRAPHY_PRESETS`: `low-key` (practical sources, people in shadow, side / back / rim light, negative space), `sweet-romance` (soft bright faces, backlit halo, pastel, the couple's distance as the story), `period-nostalgia` (film look, window sun and bare bulbs, ≤ T4), `scifi-hard` (engineered light, one harsh sun, no magic or holograms), `scifi-soft` (holograms, neon, dual-tone colour), `costume-idol` (luminous, gauze, backlit silk), `costume-dark` (firelight and lattice windows, faces in shadow); both costume presets need a wide with negative space in every segment or `none`. Every preset: a named `light.source`, a foreground, ≤ T2.8 unless it says otherwise (`sweet-romance` / `costume-idol`: ≤ T2, a T1.3 package from `init`, half the frames naming their bokeh); the period and costume ones refuse sources from the wrong era. Gated in `scene-design`, `photography` and `video-prompt`; see `cinematography.md` |
 | `lookPhrase` | empty | a lens / look phrase (e.g. `wide-aperture lens, shallow depth of field, creamy background bokeh and soft out-of-focus foreground elements`) that every segment prompt must carry verbatim |
 | `style` | `realistic` | `photoreal` (live action), `realistic` (semi-realistic painterly) or `ghibli`; one style for the whole drama (see stage-characters) |
 | `register` | required | the 语体 the lines are written in: `粤语` / `大陆普通话` / `台湾国语` / `港式普通话` / `古装` / `年代` / `英文美式` / `英文英式` (traditional spellings accepted). When `speechAccent` is empty it is derived from this in the prompt's language (`standard Mandarin` / `标准普通话`). A character may override it in `bible.speech.register`. The `dialogue-register` gate is **advisory** — it notes lines that break the register and never fails `validate` |
@@ -114,6 +123,17 @@ written exactly like 2.5 — they differ only in the ceiling (15 s, not 30) and
 | `guideline` | yes | the 创作指引 — `{tone, emotionalIntensity, dialogueStyle, visualStyle, productionLimits, forbidden[] (≥3), priorities[] (3–5)}`; `render guideline` publishes it as its own dataset and it is re-read before every stage |
 | `beats[]` | ≥1 | `{id:"B01", type, weight:"major"|"minor", episode, setup, payoff}`; `episode` is the only place a beat's position lives |
 | `episodes[]` | exactly `params.episodes` | `{ep, function[], task: {goal, obstacle, stake}, change, satisfaction: {type, action}, hookType, synopsis, hook, suspense, sceneIds[], characterIds[], propIds[], crowdPlan?, warnings[]}` — narrative prose, **no dialogue quotes** (`「」『』“”`). `function` ⊆ `开局钩子 / 冲突升级 / 身份揭露 / 情感推进 / 大反转 / 清算收束`; `satisfaction.type` ∈ the six 爽点 types and `action` is the visible action that does it; `hookType` ∈ `身份 / 危机 / 结果 / 情感 / 反转 / 道具`. Episode 1 includes 开局钩子; with ≥ 3 episodes, episode 2's 爽点 type is the brief's engine and episode 3 includes 冲突升级 / 身份揭露 / 大反转; the finale includes 清算收束 or 大反转 |
+| `paybacks[]` | `revenge` | `{ ep, target (an antagonist), scale: small / big / final, by (who lands it), how }` — every antagonist finished once, in tier order (gate `story-revenge`) |
+| `romance[]` | `sweet` | `{ ep, milestone, until?, note }` — `milestone` ∈ `meet bind spark touch jealousy protect kiss confession misunderstanding reconcile public black-moment commit`; a misunderstanding has `until` (gate `story-sweet`) |
+| `mysteryMode` · `questions[]` · `clues[]` | `mystery` | `whodunit` / `inverted` / `thriller`; `{ id, layer 1–3, question, openEp, answerEp, clues[] }`; `{ id, kind: true / red-herring, what, plantEp, prop?, echoEps[], dismissedEp? }` (gate `story-mystery`) |
+| `brief.comicPremise` · `runningGags[]` | `comedy` | the gap between the normal and the comic world; `{ id, premise, eps[] }` (gate `story-comedy`) |
+| `angst` · `brief.redLines` | `angst` | `{ ending: HE / HE-second / BE / OE, turnEp, exitEp, reconcileEp, misbelief: { belief, engineeredBy, evidence, audienceRevealEp, heroRevealEp }, beats: [{ ep, kind: 虐 / 悔 / 追 / 糖, inflictor?, what?, cost?, severity?, releaseEp?, public? }] }`; what the male lead never does (gate `story-angst`) |
+| `secrets[]` · `vindications[]` · `reconciliations[]` | `family` | `{ id, content, audienceKnowsEp, plantEp, hintEps[], revealEp }`; `{ char, ep, venue, witnesses[] }`; `{ pair, woundEp, triggerEp, turnEp, endState }` (gate `story-family`) |
+| `rankLadder` · `rankEvents[]` · `schemes[]` · `factions[]` · `allegiance[]` | `palace` | `{ track, levels[] }`; `{ char, ep, to }`; `{ id, schemer, target, stakes, setupEp, revealEp, outcome, counteredBy: { type, ref, plantEp }, flaw, justice? }`; `{ id, leader, members[] }`; `{ char, ep, from, to, motive, foreshadowEp }` (gate `story-palace`) |
+| `powerSystem` · `goldenFinger` · `startPower` · `upgrades[]` · `fights[]` | `cultivation` | `{ realms: [{ id, name, visual }] }`; `{ type, name, activationEp, rules[], costs[] }` (or two); `废柴 / 隐藏大佬 / 满级`; `{ ep, char, to, cause, cost }`; `{ ep, foe, heroRealm, foeRealm, foeRevealedEp, edge? }` (gate `story-cultivation`) |
+| `brief.novum` · `worldRules[]` · `countdown` · `loops[]` · `foreknowledge[]` · `secondaryNovums[]` | `scifi` | `{ statement, category, mode, firstEp }`; `{ id, rule, kind: power / limit / cost / trigger / exception, shownEp, decidesEps[], brokenEp?, revealSetupEp? }`; `{ label, zeroEp, log: [{ ep, value }] }`; `{ n, ep, newInfo, changed }`; `{ event, plantedEp, payoffEp, deviated }`; `{ id, derivesFrom }` (gate `story-scifi`) |
+| `horror` · `horrorRules[]` · `episodes[].scares` | `horror` | `{ subgenre, threat: { nature, firstSignEp, glimpseEps[], revealEp, explanation: { type, revealEp, clueEps[] } } }`; `{ id, text, isTrue, shownEp, brokenEp?, consequence }`; `[氛围 / 假警报 / 惊吓 / 揭示 / 规则惩罚]` (gate `story-horror`) |
+| `storyExceptions[]` | no | `{ rule, reason }` — waives a story rule for the whole drama when the user asks (`story.md`) |
 
 `warnings` values: `雨戏`, `肢体接触`, `人群`, `手部特写` (generation hazards).
 
@@ -151,6 +171,13 @@ Outline stage fills the first block; the characters stage fills the rest.
 }
 ```
 
+Story-genre character fields (outline stage, only for the genres in `params.story`):
+`antagonist: { tier: 1–3, firstPressEp, motive }` (`revenge`), `mysteryRole` (`investigator`
+`culprit` `accomplice` `suspect` `unreliable-ally` `victim` `witness`) and `firstEp` (`mystery`),
+`comic: { flaw, humanity, role: 逗 / 捧 / both }` (`comedy`), `family: { generation, role, minor?,
+endState }` (`family`). Script beats may carry `clue` (a clue
+id or list) and `gag` (`setup` / `build` / `punchline`) with `runningGag`.
+
 | Field | Language | Rules |
 | --- | --- | --- |
 | `tier` | — | `lead` (1–5, `arc` required) / `support` (≤10, `arc` required) / `functional` (≤10, `name` is a role label such as 急诊医生, `arc` optional) |
@@ -237,7 +264,7 @@ prompt bans hands**). At most `thresholds.maxProps` (8).
         "cuts": [
           { "beats": [1, 1], "seconds": 3, "size": "medium", "camera": "Tracking Shot",
             "focal": "40mm",
-            "light": { "direction": "back-left", "note": "the store light rims her shoulder; the street stays unlit" },
+            "light": { "direction": "back-left", "source": "the store's fluorescent window", "note": "the store light rims her shoulder; the street stays unlit" },
             "foreground": "the dripping edge of the striped awning",
             "characters": ["C01"], "props": ["P01"], "frame": "medium shot of …, cinematic film still", "note": "" }
         ],
@@ -278,17 +305,21 @@ Duration: `Σ lines (chars ÷ charsPerSecond) + Σ actions × actionSeconds`.
 | `camera` | one of the H3 vocabulary: `Static Shot` `Push In` `Pull Out` `Zoom In` `Zoom Out` `Pan Left` `Pan Right` `Truck Left` `Truck Right` `Tilt Up` `Tilt Down` `Pedestal Up` `Pedestal Down` `Arc Shot` `Tracking Shot` `Shake Slightly` `Shake Strongly` `POV` `Roll Clockwise` `Roll Counterclockwise` |
 | `characters` / `props` | ⊆ the scene's; `characters.length > maxOnScreen` needs `note` |
 | `focal` / `aperture` | optional per-cut overrides of the lens; left out, `FOCAL_BY_SIZE` picks the focal from the shot size (extreme-wide 18mm, wide 25mm, medium 40mm, close 75mm, extreme-close 100mm macro) and `params.camera.aperture` the stop |
-| `light` | `{ direction, note }`. `direction` ∈ `frontal` `front-left` `front-right` `side-left` `side-right` `back-left` `back-right` `backlight` `top` `underlight` `ambient` — **relative to the camera, not the room**; `note` says what the key picks out, what fills the shadow side and how it changes over the cut. Both required |
+| `light` | `{ direction, source, note }`. `direction` ∈ `frontal` `front-left` `front-right` `side-left` `side-right` `back-left` `back-right` `backlight` `top` `underlight` `ambient` — **relative to the camera, not the room**; `note` says what the key picks out, what fills the shadow side and how it changes over the cut. Both required. `source` (required under a `cinematography` preset) is the lamp, window, sun or string lights the key comes from, named verbatim in `frame`; the preset bans some directions on a person and wants ≥ ½ the cuts with people per segment from its preferred ones (`cinematography.md`) |
 | `foreground` | what sits between the lens and the subject, to be thrown out of focus. `""` is a deliberately clean frame; at least half the cuts of a segment must have one |
 | `background` | optional — the third depth layer behind the subject; expected (or a `note`) on a 9:16 wide |
+| `composition` | art-first segments only: the devices of the frame, one or more of `negative-space` `symmetry` `grand-scale` `frame-in-frame` `leading-lines` `silhouette` `layered-depth` `color-block` `top-down` `thirds`; each device's phrase is in `frame` (gate `composition`) |
+| `gag` | comedy segments only: `setup` · `build` · `punchline` — a punchline needs a setup earlier in the scene and a reaction after it (gate `comedy`) |
+| `move` | fight segments only: `{ kind, impact }` — `kind` ∈ `strike kick shot slash stab block dodge throw grapple fall leap draw reload power stance chase swerve crash none`; `impact: true` when it lands, and then the next cut is a `reaction` / `consequence` (or this cut is a `consequence`) — gate `action` |
 | `purpose` | `{ kind, change }` — `kind` ∈ `establish / reveal / evidence / reaction / pressure / decision / consequence / performance / transition`; `change` says what the audience knows or who holds power when the cut ends (gate `shot-purpose`) |
 | `angle` / `height` / `axisSide` | `front / three-quarter / profile / rear-three-quarter / back` · `ground / low / eye / high / top` · `working / cross / neutral` (`cross` needs `note`) — gate `framing-axis` |
 | `start` / `end` | boundaries `{ positions: {C01: …}, facing: {C01: screen-left\|screen-right\|camera\|away}, gaze, hands, heldProps: {C01: [P01]}, state: [] }` for every person on screen; `start` only on a segment's first cut (later cuts inherit the previous `end`); a prop changes hands only on an action beat; `state` items that exist only in `end` may not appear in `frame` — gate `continuity` |
 | `motion` | `{ trigger, action, result }` — cue, one visible state chain, landing (or `hold`); English unless the prompt language is Chinese; no names, no inferred states, ≤ 3 hand verbs — gate `motion` |
 | `cameraNote` | `{ motivation, trigger, path, endFraming }` on any move (`motivation` ∈ `reveal / pressure / alignment / relationship / transition / stillness`), `{ hold }` on a `Static Shot` — gate `motion` |
-| `frame` | English prompt for the moment: composition, this moment's positions and poses, the size phrase, the style's `framePhrase` (`photorealistic cinematic film still` / `cinematic film still` / `hand-painted anime film still`), **and verbatim** the camera phrase (`shot on an ARRI ALEXA Mini LF with a Zeiss Supreme Prime 75mm at T1.5`), the light-direction phrase and the foreground; **no names** — identity comes from the sheet references |
+| `frame` | English prompt for the moment: composition, this moment's positions and poses, the size phrase, the style's `framePhrase` (`photorealistic cinematic film still` / `cinematic film still` / `hand-painted anime film still`), **and verbatim** the camera phrase (`shot on an ARRI ALEXA Mini LF with a Zeiss Supreme Prime 75mm at T1.5`), the light-direction phrase and the foreground, and under a `cinematography` preset also its `framePhrase` and the `light.source`; **no names** — identity comes from the sheet references |
 | `prompt` | the video prompt, shape by `params.video` (below); gate `prompt-hygiene` (no `…`, no ids / paths / notes, subtitles off unless `params.subtitles`, H3 lips-closed clause, sheets-mode `@imageK` per shot) |
 | `segments[].axis` | `{ between: [C01, C02], workingSide, screenLeft, screenRight }`, required when two or more people appear in the segment |
+| `segments[].grammar` / `exceptions` | `grammar` (a string or an array) says how the segment is cut — `drama` · `action` · `faceslap` · `comedy`; missing, it is `params.grammar`; the old `action: true` means `action`. Each grammar's rules apply (gates `grammar`, `action`, `faceslap`, `comedy`; advisory `action-advice`, `grammar-advice`) and the prompt carries each grammar's line. `exceptions: [{ rule, reason }]` waives one rule for this segment when the user asks — rules `open-wide` `one-move` `impact-reaction` `no-graphic` `reveal-insert` `reaction-chain` `punchline-reaction` `setup-first` (the old `actionExceptions` still works) |
 | `segments[].sound` | `{ ambience, sfx: [{ cut, event }], music }` — ambience identical across a scene's segments; `music` is `N/A`, an intent string, or `{ intent, cues: [{ at: <cut number \| "10.5s">, do: enter \| swell \| duck \| drop \| silence \| out, note }] }` — gate `sound`. `prompt audio E01-01` derives the segment's Seed Audio soundtrack prompt from it (timecoded `[start s:end s]` ambience / sfx / music, plus the lines with `--full`) — gate `audio-track` |
 | `storyboard.visualPlans[]` | `{ sceneIndex, turn, alignment, pressure, progression, rhythm, landing, sound }` for the 爽点 scene and the cliff scene (seeded) — gate `visual-plan` |
 | `props[].textPolicy` | optional `{ mode: readable \| symbolic \| blank, text }` — gate `text-policy` |

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

@@ -9,7 +9,7 @@ stage's output is a **consistency plan** per asset, not a mood board.
 | --- | --- |
 | `summary` | design intent — what story this space tells, not a floor plan |
 | `anchors` (3–5) | features that must appear in every generation: paintable, recognisable, checkable ("flickering oden light box", "red drawer with worn corners"; not "old atmosphere") |
-| `lighting` (≥1) | one English prompt per lighting state the episodes actually use — derive them from the episodes the scene appears in, don't write a day/dusk/night set nobody uses |
+| `lighting` (≥1) | one English prompt per lighting state the episodes actually use — derive them from the episodes the scene appears in, don't write a day/dusk/night set nobody uses. With a `params.cinematography` preset each prompt contains the preset's `framePhrase` (`low-key practical lighting` / `soft romantic lighting`) and names the sources that light the space (what, where, what colour) — see the preset's guide, `cinematography-<preset>.md` §1 |
 | `image.prompt` | the master view, **empty scene, no people** (say so); `negativePrompt` must ban people |
 | `image.sheet` | environment sheet: main panel (≈72 % × 70 %, master view + first lighting state) + an L of detail panels showing the anchors; `THE SPACE MUST BE IDENTICAL ACROSS ALL PANELS`, `nothing invented that is not present in the master view`; the style render phrase |
 | `variantOf` + `changes` | a scene that is the parent with a different time / weather / foreground — cheaper and more consistent than a new environment; outline scenes with a `reusePlan` become variants |

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

@@ -51,6 +51,27 @@ gate should pass before you show the skeleton.
 Show the user, in plain language: the lines cut, the people merged, the episode of each major beat.
 Wait for a yes. Change the skeleton on their feedback and validate again.
 
+## Genre ledgers (`params.story`)
+
+Each story genre adds what the outline must track, written with the skeleton and shown at
+sign-off (`story.md`, and the genre's own guide for the rules and the craft):
+
+| genre | ledger | gate |
+| --- | --- | --- |
+| `revenge` | `characters[].antagonist { tier, firstPressEp, motive }`, `outline.paybacks[] { ep, target, scale, by, how }` | `story-revenge` |
+| `sweet` | `outline.romance[] { ep, milestone, until?, note }` | `story-sweet` |
+| `mystery` | `outline.mysteryMode`, `outline.questions[]`, `outline.clues[]`, `characters[].mysteryRole` / `firstEp` | `story-mystery` |
+| `comedy` | `outline.brief.comicPremise`, `characters[].comic { flaw, humanity, role }`, `outline.runningGags[]` | `story-comedy` |
+| `angst` | `outline.angst { ending, turnEp, exitEp, reconcileEp, misbelief, beats[] }`, `outline.brief.redLines` | `story-angst` |
+| `family` | `characters[].family`, `outline.secrets[]`, `outline.vindications[]`, `outline.reconciliations[]` | `story-family` |
+| `palace` | `outline.rankLadder`, `outline.rankEvents[]`, `outline.schemes[]`, `outline.factions[]`, `outline.allegiance[]` | `story-palace` |
+| `cultivation` | `outline.powerSystem`, `outline.goldenFinger`, `outline.startPower`, `outline.upgrades[]`, `outline.fights[]` | `story-cultivation` |
+| `scifi` | `outline.brief.novum`, `outline.worldRules[]`, `outline.countdown`, `outline.loops[]`, `outline.foreknowledge[]` | `story-scifi` |
+| `horror` | `outline.horror { subgenre, threat }`, `outline.horrorRules[]`, `outline.episodes[].scares` | `story-horror` |
+
+The episodes are then designed against the ledger: a payback episode's `satisfaction.type` is a
+payback type, a sugar episode's is 强宠 / 情感释放, and so on — the gates count both.
+
 ## Episodes (batches of ≤10)
 
 Design first, prose second. Per episode the 分集目录 fields: `function` (开局钩子 / 冲突升级 /

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

@@ -67,6 +67,16 @@ this episode.
   only way to get it back.
 - **A picture change is a sound change** downstream — remember it when the storyboard exists.
 
+## Genre markers (gate `story-script`)
+
+- **Mystery**: the beat that plants a clue carries `clue: "K1"` (or a list) in the clue's plant
+  episode — a clue is something the camera shows, never narration. Plant it inside a beat doing
+  something else (`story-mystery.md` §5).
+- **Comedy**: `gag: setup` where a joke is planted, `gag: build` for the repeats of a rule of three,
+  `gag: punchline` where it lands (at least 2–3 an episode), `runningGag: "G1"` on a callback. Every
+  punchline has a setup before it (or calls back a running gag); a punchline line is ≤ 20 字 and
+  ends on the funny word (`story-comedy.md`).
+
 ## Feel (not gated, decides whether it plays)
 
 Short lines, dense action: an action or reaction every two or three lines, never four lines in a

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

@@ -146,6 +146,21 @@ picks out, what fills the shadow side, and **how it changes over the cut** — a
 the fill away, a pan that carries the face out of one source into another, a turn that trades a
 front key for a rim. A cut where the light does nothing is a cut where the light was not directed.
 
+Under a `params.cinematography` preset the light also has a `source`: the lamp, window, sun or
+string lights, candle or lattice window it comes from, named verbatim in the frame. A person is never keyed from the
+preset's banned directions (e.g. `low-key` / `costume-dark`: `frontal` / `ambient`;
+`sweet-romance` / `costume-idol`: `underlight` / `top`), at least half the cuts with people in a
+segment use its preferred ones, the stop stays within the preset's limit, and a period or costume
+preset refuses a source its era did not have. Stage the person against the source first, then pick the camera side; the
+tables are in `cinematography.md` and the preset's guide.
+
+**Each segment is cut in its grammar** (`segment.grammar`, else `params.grammar`; see
+`grammar.md`): `action` segments open on a wide, take one move per cut and answer every impact
+(`action.md`); `faceslap` segments show the proof and a cascade of reactions
+(`grammar-faceslap.md`); `comedy` segments set up every punchline and give it laugh room
+(`grammar-comedy.md`). Each grammar adds its line to the prompt (`Action:` / `Payoff:` /
+`Comedy:`).
+
 ### Foreground
 
 Depth needs something to be shallow *against*. `foreground` names what sits between the lens and