@wji.ai/cli 0.4.0 → 0.5.1

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

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

@@ -0,0 +1,117 @@
+# Story genre `angst` — 虐恋 / 追妻火葬场
+
+虐恋情深 · 追妻火葬场 · 替身文学 · 白月光 / 朱砂痣 · 带球跑 · 先虐后甜. The opposite pole of `sweet`
+(`story-sweet.md`); in a mixed drama the two share the romance, and `angst` decides the shape.
+Shared machinery: `story.md`.
+
+## 1. The promise — delayed justice in love
+
+The audience does not pay to suffer. **The pain is a deposit; his regret and pursuit are the
+withdrawal, with interest.** 追妻火葬场 is a power reversal: early on he controls the relationship,
+later she sets the price of forgiveness — "emotional fairness", his arrogance collapsing into
+regret. A 虐点 that is never repaid is a broken promise, not a stronger drama.
+
+- **Make them love her before anything breaks.** Tragedy is destroying something beautiful in
+  front of people who care. Her devotion is concrete (the hangover soup at 3 a.m., the three-year
+  diary, the career she gave up).
+- **Catharsis** swings between "too late" (tears) and "in the nick of time" (action). 火葬场 is
+  built on "almost too late": a BE lands on too late, a HE on the nick of time.
+- **The market is moving**: 女频 dominates the billion-play titles and 虐恋 with 追妻 reversals was a
+  2025 mainstay, but toward the **清醒女主** and the **克制霸总**; the 壁咚 / 强吻 era is over. 虐 survives
+  as 甜虐 with a dignified heroine, not as prolonged victimhood.
+
+## 2. The series — 虐 ≤ 30 %, 悔 ≈ 40 %, 追 ≈ 30 %
+
+| phase | where (80 episodes) | what |
+| --- | --- | --- |
+| 虐 | to ~30 % | cause and effect, not wallowing: her devotion, his false belief, the wound; **the heroine's dark night** (she loses the child, the marriage, her illusions) and **she leaves by her own choice** — the 卡一 cliff (E8–12) ends on that decision |
+| 悔 | ~25–45 % → | **the turn**: he learns or suspects the truth, or she "dies" / disappears — the 卡二 cliff (E26–30); **the hero's dark night** (too late, she is gone) |
+| 追 | → ~85 % | the 火葬场: she holds power; every pursuit beat costs him something he values (status, pride in public, money, his family, his body in the rain); a public apology before witnesses; the antagonist who engineered it all is paid off |
+| ending | last ~15 % | HE (先虐后甜 — sugar after), HE with the second lead (男二上位, when he crossed a line), BE (declared, prestige), OE (rare). Whatever the ending, she ends with more agency than she began |
+
+**Tracked in the outline** (gate `story-angst`): `outline.angst: { ending, turnEp, exitEp,
+reconcileEp, misbelief: { belief, engineeredBy, evidence, audienceRevealEp, heroRevealEp },
+beats: [{ ep, kind: 虐 / 悔 / 追 / 糖, target?, inflictor?, what?, cost?, severity?, releaseEp?,
+public? }] }` and `outline.brief.redLines` (what the male lead never does).
+
+| rule | default | why |
+| --- | --- | --- |
+| `abuse-cap` | the last 虐 beat before the turn at ≤ 35 % | 虐妻 ≤ 30 %, with room for the 卡二 gate |
+| `turn-timing` | the turn at 25–45 % | regret begins at 卡二 |
+| `regret-outweighs` | 悔 + 追 beats ≥ 1.5 × 虐 beats | "his regret must outweigh her suffering" (30/40/30 is 2.3×) |
+| `pursuit-length` | ≥ 3 追 beats, lasting ≥ 15 % before she forgives (HE) | 火葬场不够烧 is the standard complaint |
+| `release-cadence` | every 虐 beat released within 2 episodes | swipe behaviour; the 虐/甜/爽 rotation |
+| `engineered-misbelief` | the misunderstanding is engineered by a non-lead, rests on evidence, the audience knows by E3, he learns by 55 % | a misunderstanding one sentence would clear reads as 降智; the tears come from irony |
+| `exit-by-choice` | she leaves at 10–40 %, no later than the turn | her leaving is her choice, not an expulsion |
+| `costly-regret` | every 悔 / 追 beat has a cost; one public 追 beat | the grovel is before witnesses |
+| `ending-contract` | HE reconciles at ≥ 85 % with sugar after; a BE brief does not promise sweetness | 先虐后甜 is the commercial default |
+| `male-lead-red-lines` | `brief.redLines` declared; no beat where the male lead strikes, drugs, confines, coerces or forces a kneel | 虐 is emotional and situational; regulators and audiences refuse the rest |
+
+## 3. The episode
+
+- A minor climax every 2–3 minutes, a cliff at every end, the core conflict inside 30 s.
+- **Every 虐 episode still has a 爽 beat — her dignity**: a cold line, a refusal, the divorce papers
+  signed, a walk-out, a competence the audience sees. Not him being kind.
+- **Dramatic irony is the engine**: the audience sees her hidden sacrifice, he does not. The
+  flashback that re-reads his cruelty is the tearjerker loop.
+- **Hooks by phase**: 虐 — 情感 (her silent breakdown), 结果 (the test, the diagnosis), 道具 (the diary,
+  the ultrasound); 悔 — 反转 (he finds the evidence), 身份 (she was the real 白月光 / the benefactor);
+  追 — 危机 (a rival suitor, the villainess strikes again), 情感 (will she take his hand).
+
+## 4. Characters
+
+- **The male lead** wounds her severely but for a reason: 爱而不自知, a misbelief planted by a third
+  party, or treating her as a 替身. His cruelty is consistent with a false belief. Never
+  irredeemable; never physical abuse (`redLines`).
+- **The heroine** may suffer but is never 圣母 or 降智; her silence has a reason (a promise, pride,
+  shielding someone, no proof); "redeemed only after her death" is criticised — she lives to set
+  the price.
+- **The 白月光 / 替身 structure**: A loves C (the unreachable first love); B loves A and resembles C.
+  Modern variants: the 替身 was the real childhood saviour; the 白月光 manufactured the claim; the 替身
+  walks away and C's return disappoints him. The 朱砂痣 — the one who stayed — is her position.
+- **The engine** needs a named inflictor (the 白月光, a mother-in-law, a rival), an artifact of
+  evidence, and a reveal the audience sees early; the inflictor is paid off (打脸 / 复仇) before the
+  reconciliation.
+
+## 5. Beats and freshness
+
+| beat | status |
+| --- | --- |
+| 带球跑 (she leaves pregnant, returns years later with a 萌宝) | alive; needs a time skip and a transformed heroine; child rules apply (`story-family.md`) |
+| 死遁 / 假死 (he goes mad) | alive; give her a point of view in the gap years |
+| 挖肾 / 献血 / 换心 | dated and restricted — blood and surgery close-ups are banned on platforms; imply |
+| 失忆 | usable as a clock or reversal; mocked as a deus ex machina |
+| terminal illness / a clock | strong, if planted early |
+| 离婚协议 / 流产 | a powerful 卡点 — the aftermath, never gore |
+| 雨中下跪, the public grovel | popular when *he* chooses it; forcing anyone to kneel, slaps, thrown money are banned |
+| 强吻 / 壁咚 / 强制爱 | dated and targeted — avoid |
+
+Give each lead a signature line early and reprise it with the roles swapped: the echo is the
+payoff.
+
+## 6. Dialogue
+
+Lines under 10 characters. The 虐 phase runs on understatement — her pain in subtext ("好。" "我签。"
+"你开心就好。"), his cruelty in cold certainty ("别让我再说第二遍。"). The 悔 phase reverses the register:
+he halts and repeats ("我错了"; "你回来好不好"), she is crisp and final. No monologues — tears and a
+prop close-up do the work.
+
+## 7. What fails, and the red lines
+
+A 虐 phase too long; a purely evil male lead; cheap forgiveness; pain for its own sake; a 圣母
+heroine; misunderstandings that need stupidity; a new misunderstanding after the truth is out; the
+白月光 never punished; a reconciliation nobody witnesses. **Regulation**: NRTA "爽而有度" (2025), the
+correct 婚恋观 in the 2024–25 notices, the 霸总 correction (2024, 2025), the June 2026 campaign on
+畸形婚恋观 and 暴力复仇; platform rules (红果 2026) ban forced kneeling, slaps, thrown money, blood
+close-ups, knives to the throat and drugging. `story-advice` flags organ harvesting, blood and
+forced kisses in the outline.
+
+## 8. Sources (read as search summaries)
+
+知乎 追妻火葬场万能公式 (30/40/30) and templates; 中华网 and 知乎 on why women watch 追妻火葬场; 流媒体网 on
+红果 2025 (女频 share) and 卡点 (卡一 E8–12, 卡二 E26–30); 澎湃 on 2025 虐恋 and "虐恋阵亡，纯爱永续"; 澎湃 /
+DataEye 14 黄金设定; 36氪 on 反套路霸总 and 霸总 regulation; DataEye 2025; 知乎 on 替身文学, 万赞虐文, 带球跑;
+人人都是产品经理 on 6,000 titles; NRTA notices (2025-02, 2026-06) and 管理提示; tvoao; 每经 on 霸总 correction;
+澎湃 on 1,200 removals; 新京报 and 天星AI on 红果 2026 rules; ScreenWeaver; The Experiment on *Today I
+Divorce My Superstar Husband*; Dramabeans and Tatler on K-drama devices; September C. Fawkes on All
+Is Lost; Linda Williams, "Melodrama Revised"; 搜狐 on BE vs HE.

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

@@ -0,0 +1,136 @@
+# Story genre `comedy` — 喜剧
+
+沙雕 · 无厘头 · 情景喜剧 · 甜宠喜剧 · 古装喜剧. This is the **writing** of comedy; how a gag is cut
+is `grammar-comedy.md`. Shared machinery: `story.md`.
+
+## 1. The promise — the laugh as the texture of a story
+
+- **Comedy is incongruity**: an expectation set up, then broken (错位, 误会与巧合, 情境置换, 语误,
+  元素嫁接). Vorhaus calls the engine the **comic premise** — the gap between comic reality and
+  real reality.
+- **In 短剧 the laugh is packaged with 情绪价值.** The biggest comedy-adjacent hit of 2025, 《十八岁
+  太奶奶驾到》, combines 反差萌 (an old soul in a young body) with 打脸 (爽) and a tear-jerking family
+  reunion (温情). 《成何体统》 split "笑点、虐点、爽点" and put one of each in an episode.
+- **Comedy rides the story; it does not replace it.** The 太奶奶 team tried a sitcom form for a
+  later season and the audience rejected it — they wanted the story and its emotion, with the
+  comedy inside. Keep the revenge, romance or family through-line and its 爽点 cadence; comedy is
+  the texture and the delivery, not the spine. (That is why `comedy` usually sits beside another
+  story genre in `params.story`.)
+- **"Distance makes us laugh; humanity makes us stay."** Audiences now reject piled-up
+  physiological gags (堆砌式的笑点); they want structure and real-life resonance (接地气).
+
+## 2. The series
+
+- **The comic premise** (`outline.brief.comicPremise`, gated): the normal world, the comic world,
+  the gap. *An 18-year-old body with a great-grandmother inside. Office workers transmigrated into
+  a palace-intrigue novel, running the court with KPIs and spreadsheets.* Vorhaus' clash of
+  context: force incompatible things together.
+- **Running gags and callbacks** (`outline.runningGags[]`, gated): a gag repeated at least three
+  times, **varied and escalated** each time and tied to the plot — without escalation, repetition
+  is dead weight. The Chinese form is 三翻四抖: a 包袱 threaded through the piece, laid out over
+  several 翻 and shaken open at the end. Pay the running gag off late (in the climax).
+- **Escalation** (UCB): each move "in keeping with, yet more absurd than" the last — "if this is
+  true, what else is true?" and "why is it true?".
+- **The 爽点 cadence still applies** (每集一个小爽点，三集一个大爽点). The best 爽点 double as
+  punchlines: the 打脸 played as a reversal gag.
+- **Sitcom tools**: A/B stories, a cold open, a tag; the trouble resolved and harmony restored at
+  the end (大事化小，小事化了, the 温馨收 close).
+
+## 3. The episode
+
+- **Density.** There is no 短剧-specific benchmark. Sitcoms run from one laugh every 8–11 s (the
+  fastest) to 16–22 s; stand-up aims for 4–6 a minute. A 短剧 also carries plot and 爽, so for a
+  1–2-minute episode: **3–6 gags for 沙雕 / 无厘头, 2–3 for a romcom or a 古装 comedy carrying plot**
+  (gated at the script: `gag-density`, 3 for `slapstick` / `deadpan`, 2 otherwise, 2 for one-minute
+  episodes). Count the laughs after every draft.
+- **The hook can be a gag** within the first 10–15 s. **The biggest laugh lands in the last
+  third**, on the 爽点 or just before the cliff.
+- **The comic cliff** is an impending exposure: the dramatic irony about to break, the
+  misunderstanding about to be discovered (揭秘→发现 — once the audience knows a secret, the writer
+  owes them the moment a character finds it out). Do not let three comic-only cliffs in a row
+  replace the plot hook.
+- **In the script**, mark the beats: `gag: setup` where the joke is planted, `gag: build` for the
+  repeats of a rule of three, `gag: punchline` where it lands, and `runningGag: "G1"` on a beat that
+  calls back a running gag. The storyboard's `grammar-comedy` cuts pick these up.
+
+**Script rules** (gate `story-script`; waivable on the user's request):
+
+| rule | default | why |
+| --- | --- | --- |
+| `gag-density` | ≥ 3 punchlines an episode (`slapstick`, `deadpan`), ≥ 2 otherwise and in one-minute episodes | sitcom benchmarks, set lower for a plot-carrying 短剧 |
+| `gag-setup` | every punchline has a setup earlier in the episode, or calls back a running gag first seen in an earlier episode | 铺平垫稳 — no payoff without a plant |
+| `punchline-brevity` | a punchline line is ≤ 20 characters (≤ 12 English words) | 笑点直接干脆; the funny word last, nothing explaining it after |
+
+## 4. Comic characters
+
+- **Every lead and support has a comic flaw** (`characters[].comic.flaw`, gated), and the leads' flaws
+  differ. Vorhaus' four elements: a **comic perspective** (a worldview at odds with normal
+  reality), **flaws**, **humanity** ("for every flaw an equal and opposite humanity" —
+  `comic.humanity`), and **exaggeration**.
+- **逗 and 捧** (`comic.role`): the 逗哏 makes the laughs; the 捧哏 frames them, gives the next line
+  its footing and controls the rhythm. **Somebody plays it straight** (gated) — the voice of
+  reason, the audience surrogate. "If everyone is unusual, no one is." 一头沉 (one partner
+  dominates) or 子母哏 (both trade gags).
+- **Base reality first**: the scene establishes the normal world before the first unusual thing.
+- **Pairs built on contrast** (开心麻花: 从人物关系入手去锤炼包袱) — the butler who acts like the young
+  master and the young master who acts like the butler; the 欢喜冤家 sparring lovers; 读心 (he
+  hears her thoughts); exaggerated family love.
+- **Ensembles** as opera role types (老生 / 小生 / 花旦 / 青衣), each distinct.
+
+## 5. Building a joke
+
+1. **Setup and punchline — 铺平垫稳**: the setup natural (平) and logically tight (稳); no little
+   zingers inside the setup, they drain the punchline.
+2. **The rule of three (三拍子)**: two normal items, the third breaks the pattern.
+3. **Reversal** (反转, 人设反转).
+4. **Exaggeration** of perspective, flaw and humanity — the heart of 无厘头.
+5. **Misunderstanding and dramatic irony**: the audience knows, the character does not, so plain
+   lines carry a double meaning. Pay it off: the discovery must come.
+6. **错位**: the wrong person does the wrong thing, or walks into the wrong place.
+7. **Clash of context and anachronism**: high and low, old and modern flipped together; office
+   jargon in a palace.
+8. **The game** (UCB): find the first unusual thing, then heighten and justify it.
+9. **Callbacks**: an earlier 笑点 returns in a new context, escalated.
+10. **The wildly inappropriate response** (Vorhaus).
+11. **Wordplay (谐音梗)** — only when it starts from what you want to say; a pun worked backwards is
+    a 烂梗.
+
+**What survives AI video.** Robust: situational irony and misunderstanding (the situation carries
+it, not the performance); contrast in costume, prop or setting; exaggerated static reaction faces;
+an insert (the object, the text message) as the punchline; a voice-over inner monologue (读心 gags
+need no lip-sync); sound effects and freezes; a rule of three cut as three shots. Fragile: precise
+pratfall timing, collisions, rapid overlapping 抢话, a gag that depends on a micro-expression or a
+lip-synced funny word. **Let the punchline land on a cut or a reaction, not mid-shot acting.**
+
+## 6. Dialogue
+
+- **Brevity** — 笑点直接干脆，不能拖泥带水, and never explain after the laugh.
+- **The funny word last** — end the line on the point of highest tension; in Chinese, put the
+  包袱 word or the reversal at the end of the clause.
+- **Memes** add 代入感 but date quickly ("老套的梗跟不上潮流，太高级的梗不接地气"): at most one an
+  episode, never the only gag.
+- **Avoid 尬**: gags that make the leads irrational just to get a laugh; predictable reused 梗;
+  straining too hard (用力过猛).
+- **Dialect** for flavour, tested on outsiders.
+
+## 7. What fails
+
+Gags that break character logic; repetition without escalation; switching form mid-series and
+losing the emotional line; everyone zany with no straight man; explaining the joke or cluttering
+the setup; stacked gags with no structure; dated or niche memes; a misunderstanding planted and
+never paid off; comedy that depends on physical or lip-sync precision the video model cannot give;
+punching down at the sympathetic lead instead of at the antagonist's pretension.
+
+## 8. Sources (read as search summaries)
+
+知乎 on 结构喜剧 (三拍子, call back, 温馨收); 界面 on 开心麻花 and 短剧, on 语误, on 情景喜剧; 豆瓣 on comedy
+technique and 三翻四抖; Cracked / No Film School / Ken Levine on jokes per minute; 知乎 on
+seconds-per-laugh benchmarks; the UCB Comedy Improvisation Manual (game, base reality,
+heightening); John Vorhaus, The Comic Toolbox (comic premise, perspective, flaw, humanity, clash of
+context, rule of three); MasterClass and No Film School on sitcom structure; comedy callbacks and
+escalation (Medium, New York Improv Theater); 流媒体网 三点论 and CSDN on 短剧 爽点 cadence; 短剧编剧
+九九; 澎湃 / ETtoday on 《十八岁太奶奶驾到》; 腾讯 (范博洋 on the failed sitcom season); 网易 / 知乎 on
+《成何体统》; 界面 / 腾讯 on 《家里家外》; 澎湃 on 无厘头 and 《一年一度喜剧大赛》; zh.wikipedia on 捧哏;
+Backstage on the straight man; 知乎 on 戏剧性反讽; Luma and arXiv on comedy in AI video; Descript and
+PremiumBeat on comedy editing; Greg Dean on punchlines; 腾讯 / 澎湃 on 谐音梗; 搜狐 on why 短剧 comedy
+fails. No 短剧-specific laughs-per-minute figure was found; the density thresholds are extrapolated.