@wji.ai/cli 0.8.2 → 0.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wji.ai/cli",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Command line interface for the WJI AI platform",
   "license": "UNLICENSED",
   "author": "WJI AI",
@@ -28,18 +28,19 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22.23.4"
+  },
+  "scripts": {
+    "build": "tsup && chmod +x dist/index.js",
+    "dev": "tsup --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "start": "node dist/index.js",
+    "prepublishOnly": "pnpm run build"
   },
   "dependencies": {
     "commander": "^12.1.0"
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "tsup && chmod +x dist/index.js",
-    "dev": "tsup --watch",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "start": "node dist/index.js"
   }
-}
+}

package/skill/short-drama/SKILL.md

@@ -138,6 +138,7 @@ ending), change the guideline first, then the episodes.
    ```bash
    node {baseDir}/scripts/short-drama.mjs init <dir> --title "<title>" --episodes N --minutes M --genre "<genre>" --register 台湾国语 [--adapt 抽核] [--ratio 9:16] [--video h3|seedance|seedance2|seedance2fast|wan] [--resolution 480P|…] [--accent "台湾口音国语"] [--style photoreal|realistic|ghibli] [--references sheets|keyframes] [--duration auto|fixed] [--look "<lens phrase>"] [--cinematography low-key|sweet-romance|period-nostalgia|costume-idol|costume-dark|scifi-hard|scifi-soft|none] [--action gun-fu|hk-kungfu|wuxia-fantasy|historical-realist|bullet-time|superhero|street-brawl|car-chase|none] [--violence blood|implied] [--grammar drama|action|faceslap|comedy] [--comedy slapstick|deadpan|romcom|none] [--composition standard|art-first] [--story revenge,sweet,…] [--market mainland|overseas] [--format short|medium|movie] [--lang zh] [--image-lang en|zh]
    # --image-lang zh: character / scene / prop image prompts in Chinese (the default is English)
+   # --foreground low|medium|high: how often cuts shoot past a foreground (default medium; high for 唯美 / 美感优先)
    # params.camera (body / lens / aperture) is edited in project.json
    ```
    An existing `project.json` means a resumed run: `validate` and `manifest` tell you where it stands.
@@ -297,14 +298,20 @@ Read `{baseDir}/reference/stage-storyboard.md`.
 Every cut is a set-up, so besides its beats and framing it carries the **lens** (`focal`, or let the
 shot size pick it), the **key light relative to the camera** (`light.direction` from the vocabulary
 plus `light.note` saying what it picks out, what fills the shadow side and how it changes over the
-cut) and the **foreground** to throw out of focus. All three are gated and all three go into the
+cut) and the **foreground** if the story gives one a reason (`params.foregroundLevel`: `low` / `medium` / `high`). All three are gated and all three go into the
 prompt, alongside the camera package and each speaker's delivery.
 
+**Everyone on screen is alive** (gate `idle-motion`, sheets mode): a model freezes whoever the prompt gives no
+  motion. In a cut with two or more visible people, all but the one carrying the action get a small
+  motion in `idle` (`"still"` when keeping still is the performance). See `craft-motion.md`.
+
+**Two people talking** (gate `two-person-framing`, sheets mode): a two-shot once, then over-the-shoulder (`ots`) for the exchange, a clean single for the punchline. A single names only its person; every look states a screen direction (`eyeline`); the sides stay locked. See `reference/craft-shots.md`.
+
 **Every cut is lit and composed in the preset's look.** Read the preset's guide
 (`{baseDir}/reference/cinematography-<preset>.md`) before the first storyboard. Name the source
 in `light.source`, stage the person against it, and choose the camera side that gives the
 preset's preferred direction (the table in `cinematography.md`). Compose as the guide says,
-shoot past a foreground, and stay within the preset's stop (T2.8; T2 for `sweet-romance` and `costume-idol`, which
+and stay within the preset's stop (T2.8; T2 for `sweet-romance` and `costume-idol`, which
 start on a T1.3 package and name their bokeh; T4 for `period-nostalgia`). Both costume presets (`costume-idol`, `costume-dark`) also need a 全景 / 大全景 with negative
 space in every segment.
 For `sweet-romance` and `costume-idol`, shoot the 甜宠 set pieces (心动对视, 回眸, 共伞…) as

package/skill/short-drama/examples/night-shift/project.json

@@ -12,7 +12,8 @@
     "videoResolution": "768P",
     "references": "keyframes",
     "style": "realistic",
-    "register": "大陆普通话"
+    "register": "大陆普通话",
+    "foregroundLevel": "high"
   },
   "source": {
     "kind": "original",
@@ -278,7 +279,7 @@
       "image": {
         "prompt": "Portrait of a young East Asian woman in her mid-twenties, contemporary 2020s Chinese city, night-shift convenience store clerk, slim and upright, hair pulled into a loose low ponytail, faded navy jacket over a striped store uniform, faint shadows under alert eyes, thin lips pressed together, three-quarter view bust, plain neutral background, soft directional key light from the upper left with a cool fill, shallow depth of field",
         "negativePrompt": "plastic skin, over-smoothed face, perfectly symmetrical face, doll-like features, dead eyes without highlights, helmet hair, flat textureless fabric, stiff mannequin pose, logo, brand name, text, watermark",
-        "sheet": "Single character model sheet on ONE 16:9 landscape canvas, pure white background. semi-realistic character illustration, painterly rendering with soft blended edges and visible brush texture, anatomically grounded. LEFT ZONE (about 34% of the canvas width): one bust portrait, front view, head and shoulders, both shoulders complete, flat straight bottom edge. RIGHT-TOP ZONE: three FULL-BODY views side by side (front, side, back) on one shared ground line, same height, same head-to-body ratio, PROPORTIONS ARE CRITICAL, no stretching or squashing. RIGHT-BOTTOM ZONE: four small isolated close-up studies (low ponytail tie, jacket cuff wear, store name tag, worn canvas sneakers); the detail studies give way, not the figures. Thin hairline rules separate the zones. Subject: a young East Asian woman in her mid-twenties, contemporary Chinese night-shift convenience store clerk, faded navy jacket over a striped uniform, alert tired eyes; all views share the SAME face as the bust portrait. LIGHTING IN THE LEFT ZONE ONLY: soft directional key from the upper left with ambient occlusion under the chin. LIGHTING IN THE RIGHT ZONES: flat even orthographic lighting, no cast shadows. No text, no watermark.",
+        "sheet": "Single character sheet on ONE 16:9 landscape canvas, three panels left to right, grey-white seamless studio background, studio lighting. semi-realistic character illustration, painterly rendering with soft blended edges and visible brush texture, anatomically grounded. LEFT: one headshot, the face filling the full height of the panel, facial features large and clear. CENTER: full-body front view, the face completely covered by a flat grey box so no facial features are visible. RIGHT: full-body back view, same height and body proportions as the front view, feet on the same ground line. Subject: a young East Asian woman in her mid-twenties, contemporary Chinese night-shift convenience store clerk, faded navy jacket over a striped uniform, alert tired eyes. Same costume on both full-body views. No side view, no extra characters, no scenery, no text, no watermark.",
         "tags": [
           "semi-realistic",
           "painterly",
@@ -442,7 +443,7 @@
       "image": {
         "prompt": "Portrait of an East Asian man in his early sixties, contemporary 2020s China, retired security guard, stocky build with a slight stoop, grey close-cropped crew cut, washed-out grey zip jacket, thick fingers, deep crow's feet, weathered skin with uneven tone and visible pores, three-quarter view bust, plain neutral background, soft directional key light from the upper left with a cool fill, shallow depth of field",
         "negativePrompt": "plastic skin, over-smoothed face, perfectly symmetrical face, young face, dead eyes without highlights, helmet hair, flat textureless fabric, stiff mannequin pose, logo, brand name, text, watermark",
-        "sheet": "Single character model sheet on ONE 16:9 landscape canvas, pure white background. semi-realistic character illustration, painterly rendering with soft blended edges and visible brush texture, anatomically grounded. LEFT ZONE (about 34% of the canvas width): one bust portrait, front view, head and shoulders, both shoulders complete, flat straight bottom edge. RIGHT-TOP ZONE: three FULL-BODY views side by side (front, side, back) on one shared ground line, same height, same head-to-body ratio, PROPORTIONS ARE CRITICAL, no stretching or squashing. RIGHT-BOTTOM ZONE: four small isolated close-up studies (crew-cut hairline, jacket zipper pull, thick scarred knuckles, worn leather shoes); the detail studies give way, not the figures. Thin hairline rules separate the zones. Subject: a stocky East Asian man in his early sixties, contemporary retired security guard, grey crew cut, washed-out grey zip jacket, slight stoop; all views share the SAME face as the bust portrait. LIGHTING IN THE LEFT ZONE ONLY: soft directional key from the upper left with ambient occlusion under the chin. LIGHTING IN THE RIGHT ZONES: flat even orthographic lighting, no cast shadows. No text, no watermark.",
+        "sheet": "Single character sheet on ONE 16:9 landscape canvas, three panels left to right, grey-white seamless studio background, studio lighting. semi-realistic character illustration, painterly rendering with soft blended edges and visible brush texture, anatomically grounded. LEFT: one headshot, the face filling the full height of the panel, facial features large and clear. CENTER: full-body front view, the face completely covered by a flat grey box so no facial features are visible. RIGHT: full-body back view, same height and body proportions as the front view, feet on the same ground line. Subject: a stocky East Asian man in his early sixties, contemporary retired security guard, grey crew cut, washed-out grey zip jacket, slight stoop. Same costume on both full-body views. No side view, no extra characters, no scenery, no text, no watermark.",
         "tags": [
           "semi-realistic",
           "painterly",
@@ -538,7 +539,7 @@
       "image": {
         "prompt": "Portrait of a tall thin East Asian man around forty, contemporary 2020s Chinese city at night, black hooded raincoat zipped to the chin, hood pulled low so only the jaw and unshaven stubble show, rain beading on the wet plastic, three-quarter view bust, plain neutral background, hard cool rim light from behind and a dim key from the left, shallow depth of field",
         "negativePrompt": "plastic skin, over-smoothed face, perfectly symmetrical face, full face clearly visible, dead eyes, dry raincoat, flat textureless fabric, stiff mannequin pose, logo, brand name, text, watermark",
-        "sheet": "Single character model sheet on ONE 16:9 landscape canvas, pure white background. semi-realistic character illustration, painterly rendering with soft blended edges and visible brush texture, anatomically grounded. LEFT ZONE (about 34% of the canvas width): one bust portrait, front view, head and shoulders, both shoulders complete, flat straight bottom edge. RIGHT-TOP ZONE: three FULL-BODY views side by side (front, side, back) on one shared ground line, same height, same head-to-body ratio, PROPORTIONS ARE CRITICAL, no stretching or squashing. RIGHT-BOTTOM ZONE: four small isolated close-up studies (raincoat hood seam, zipper pulled to the chin, wet rubber boots, stubbled jaw); the detail studies give way, not the figures. Thin hairline rules separate the zones. Subject: a tall thin East Asian man around forty, contemporary, black hooded raincoat with the hood low over the face, stubble; all views share the SAME face as the bust portrait. LIGHTING IN THE LEFT ZONE ONLY: dim key from the left with a cool rim light. LIGHTING IN THE RIGHT ZONES: flat even orthographic lighting, no cast shadows. No text, no watermark.",
+        "sheet": "Single character sheet on ONE 16:9 landscape canvas, three panels left to right, grey-white seamless studio background, studio lighting. semi-realistic character illustration, painterly rendering with soft blended edges and visible brush texture, anatomically grounded. LEFT: one headshot, the face filling the full height of the panel, facial features large and clear. CENTER: full-body front view, the face completely covered by a flat grey box so no facial features are visible. RIGHT: full-body back view, same height and body proportions as the front view, feet on the same ground line. Subject: a tall thin East Asian man around forty, contemporary, black hooded raincoat with the hood low over the face, stubble. Same costume on both full-body views. No side view, no extra characters, no scenery, no text, no watermark.",
         "tags": [
           "semi-realistic",
           "painterly",

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

@@ -78,13 +78,12 @@ the negative space is usually the dark part of the frame.
 - Write the placement into `frame`: `she sits in the lower-left third, the unlit shelves filling
   the right two-thirds of the frame`.
 
-**前景 — a foreground layer.** Most cuts shoot *past* something: the edge of a shelf, rain on the
-glass, a door frame, a hanging lamp, the shoulder of the other person (an over-the-shoulder). Take
-it from the scene's anchors where you can, so it also carries continuity. The existing `photography`
-gate already requires a named `foreground` on at least half the cuts of a segment, said to be out
-of focus. Aim higher than that minimum in this look.
+**前景 — a foreground layer.** Where the story gives a reason, shoot *past* something: the edge of a
+shelf, rain on the glass, a door frame, a hanging lamp, the shoulder of the other person (an
+over-the-shoulder). Take it from the scene's anchors where you can, so it also carries continuity.
+`params.foregroundLevel` sets how often; this look suits `medium` or `high`.
 
-**Three layers.** A defocused foreground, the person in the shadow in the mid-ground, and a
+**Three layers, when a cut has a foreground.** A defocused foreground, the person in the shadow in the mid-ground, and a
 practical in the background that falls into bokeh. That depth is what the wide aperture exists for.
 
 ## 4. Lens — wide open, chosen per scene

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

@@ -46,7 +46,7 @@ storyboard (stage 5).
 | `scenes[].lighting[].prompt` | the preset's `framePhrase`, plus the sources that light the space | `scene-design` |
 | every `cut.frame` | the `framePhrase`, the direction phrase, `light.source` verbatim, the camera phrase, the foreground | `photography` |
 | every `cut.light` | `direction` (never one of the preset's `bannedLight` on a person), `source`, `note` | `photography` |
-| each segment | at least `preferredShare` of the cuts with people keyed from `preferredLight`; at least half with a foreground | `photography` |
+| each segment | at least `preferredShare` of the cuts with people keyed from `preferredLight`; the episode's foreground share within `params.foregroundLevel` | `photography` |
 | every `cut.aperture` / `params.camera.aperture` | `maxStop` or faster | `photography` |
 | video prompt, `sheets` mode | the Look line carries the preset's `videoPhrase` (for `wan`: a `画面：` line with `videoPhraseZh`). `prompt segment` writes it for you | `video-prompt` |
 

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

@@ -19,7 +19,27 @@ text for a machine, not prose for a reader.
    what is received → one or two visible signals in a channel the size can read (gaze, breath,
    body set, object handling) → the decision (an action taken or withheld) → the landing at the
    end boundary. A wide cannot carry an eyelid; a close-up cannot carry a full-body retreat.
-   Keeping still is a valid performance when it is the character's strategy.
+   Keeping still is a valid performance when it is the character's strategy — and even then they
+   breathe and blink (`idle: "still"`).
+
+### Everyone on screen is alive (gate `idle-motion`, sheets mode)
+
+A model freezes whoever the prompt gives no motion, so a sub-character stands in the background like
+a photo. `motion` is the one action that carries the cut; everyone else who is visible gets a small
+motion of their own in `cut.idle: { C02: "shifts her weight, picking at her sleeve" }`. The skeleton
+writes it into the shot. The rule, per cut with two or more visible people: all but the one carrying
+the action have one (an over-the-shoulder's shoulder does not count). Give the speaker one too when
+they would otherwise only talk.
+
+- **Take it from why they are there.** Waiting: shifts weight, fiddles with a strap, checks the door.
+  Working: the work carries on. Listening: a small nod, the eyes moving over the other's face. Tense:
+  a tightening jaw, a thumb rubbing a finger. Do not reuse one motion across people or cuts: two people
+  breathing in time reads as a loop.
+- **Small enough not to steal the cut:** one motion, in place. A line, a moving mouth or a change of
+  place is a cut's action, not an idle (gated, as is a length over 90 characters).
+- **It must not break the boundaries:** hands, held props and positions end where `end` says.
+- **Crowds and extras** with no sheet go in `background` as a motion, not a list of people: "shoppers
+  drifting past far behind her".
 4. **Camera** — `cameraNote`. A lock-off is written like a move: the framing, **what still moves
    inside it**, how long it holds (`hold`). An empty camera line is read as "free to drift", and
    the model grows a push-in nobody asked for. A move names its `motivation` (reveal / pressure

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

@@ -88,6 +88,30 @@ adjective:
   tighter) is a statement of power — make it on purpose.
 - **Over-the-shoulder** names whose shoulder is in the foreground (`foreground`); that decides
   whose shot it is.
+
+### Two people talking
+
+A model puts into the shot everyone the shot names, and "looking at him" gives it no direction. In
+sheets mode the gate `two-person-framing` holds every two-person segment to these, and `prompt
+segment` writes the phrases for you:
+
+- **Default pattern:** a two-shot once to set who stands where → **over-the-shoulder**, alternating,
+  for the exchange → a **clean single** for the punchline or the biggest reaction. A reaction lands
+  harder alone, so do not put every shot over a shoulder.
+- **A single is single.** `characters` holds one person, the shot opens `Only @imageK in frame.`, and
+  the rest of the shot never describes the other person. Their reaction gets its own cut.
+- **Every look has a direction.** `eyeline: { C01: "screen-left down" }` — `screen-left` or
+  `screen-right`, then `level`, `up` or `down`. The direction is toward the other person, so it follows
+  from the side they stand on. `"away screen-left"` is a deliberate look elsewhere; `"task"` keeps the
+  eyes on what the hands are doing. Height comes from the blocking: a person kneeling looks up, the
+  one standing looks down.
+- **The sides are locked.** `axis.screenLeft` / `screenRight` become a `Sides:` line in the prompt, and
+  every shot holds them. Moving a person across needs `axisSide: cross` with a `note`.
+- **Over-the-shoulder is its own setting.** `ots: "C01"` is the person whose shoulder is near the lens;
+  `characters` holds both people. The prompt says their face is not visible, so only one face is left
+  for the lip-sync and the eyes. It counts as a foreground for `params.foregroundLevel`, and that person
+  needs no `eyeline`. When one person is much lower, shoot up past the low shoulder or down past the
+  high one, and keep the sides.
 - **Crossing the axis** is legal with a neutral shot, an in-shot crossing, a deliberate
   disorientation or a re-established geography — `axisSide: cross` with a `note` that says which;
   the new working side is then inherited by the cuts after it.

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

@@ -66,6 +66,7 @@ All commands accept either the directory or the `project.json` path.
 | `lookPhraseZh` | empty | the same look phrase in the drama's language, gated in a **Chinese** prompt (`wan`) where the English `lookPhrase` would be both out of place and extra length for the content filter to judge |
 | `speechLeadSeconds` | 0.5 | added to a cut's dialogue seconds before the fit check — the mouth opens after the cut starts; also where a line starts in the `full` soundtrack prompt |
 | `audioTrack` | `post` | where the soundtrack is made. **`post`** (the default): the clips carry dialogue, ambience and in-picture sfx but **no music** (`No music.` / `non_diegetic_music: N/A` / `无配乐`) and no `post: true` sfx — music and sound design cannot carry across separately generated segments, so they are made once over the **edited episode**, on its timecode (`prompt score E01`, then `mix-over-video.md`); no per-segment audio node. `bed` (ambience + sfx + timed music, no voices) / `full` (the bed plus every line in the connected `@Audio1..3` voices — at most three speakers): a Seed Audio node per segment, music in the clip prompt. `none`: no soundtrack work |
+| `foregroundLevel` | `medium`; `high` for 唯美 / 美感优先 (`composition: art-first`, `cinematography: sweet-romance` or `costume-idol`, a genre naming 唯美 or 美感) | how often a cut shoots past a foreground, measured across the episode: `low` up to 25 % of the cuts, `medium` 25–50 %, `high` 50 % or more (gate `photography`; `--foreground` at init). Which cuts: `stage-storyboard.md` |
 | `scoreFps` | 24 | frame rate `prompt score` writes SMPTE `HH:MM:SS:FF` at (`--fps` overrides); set it to the edit's real fps |
 | `subtitles` | false | `true` drops the subtitles-off sentence requirement from the prompts |
 | `maxFrameChars` | 900 | frames longer than this are flagged as padding (advisory) |
@@ -190,7 +191,7 @@ id or list) and `gag` (`setup` / `build` / `punchline`) with `runningGag`.
 | `profile.evidence[]` | source | verbatim quotes, never translated |
 | `image.prompt` | **`params.imagePromptLang`** (English by default) | portrait prompt; **no names or aliases**; must state ethnicity and era |
 | `image.negativePrompt` | `imagePromptLang` | style-dependent, see stage-characters |
-| `image.sheet` | `imagePromptLang` | 16:9 three-zone sheet prompt; no names; contains the style's render phrase (`STYLE_PRESETS[style].render`, or `.renderZh` in Chinese) |
+| `image.sheet` | `imagePromptLang` | 16:9 three-panel sheet (headshot filling the height, front full body with the face covered by a grey box, back full body), grey-white studio background, studio lighting; no names; contains the style's render phrase (`STYLE_PRESETS[style].render`, or `.renderZh` in Chinese) |
 | `voice.prompt` | English | ≤400 characters, a static voice identity, **no quoted lines** |
 | `voice.videoDirection` | **English** | ≤160 characters, one clause: how they speak (pace, where the voice sits, what it does at the end of a phrase, accent). It is pasted beside **every line this character says** in a video prompt, and gated there — compress `voice.prompt`, do not repeat it |
 | `identityEn` | **English** | ≤80 characters, the name-free way a prompt refers to this person (`the woman in her mid thirties in headphones`). Distinct per character; no names. Used to attribute dialogue in `keyframes` mode and anywhere a `@imageK` label is not available |
@@ -324,6 +325,9 @@ Duration: `Σ lines (chars ÷ charsPerSecond) + Σ actions × actionSeconds`.
 | `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) |
+| `cuts[].idle` | sheets mode: `{ <id>: "shifts her weight" }`, a small motion in place for a person other than the one carrying the action, or `"still"` (breathing and blinking only). In a cut with two or more visible people, all but one need one (gate `idle-motion`) |
+| `cuts[].eyeline` | sheets mode, two-person segments, **required**: `{ <id>: "screen-left\|screen-right level\|up\|down" }` for everyone on screen, or `"away screen-left"`, or `"task"` (gate `two-person-framing`) |
+| `cuts[].ots` | the person whose shoulder is near the lens in an over-the-shoulder; `characters` holds both people; counts as a foreground; that person needs no `eyeline` |
 | `segments[].sound` | `{ ambience, sfx: [{ cut, event, post? }], 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`. An sfx with `post: true` is **sound design outside the story world** (stinger, riser, whoosh, impact hit, reverse cymbal) — never in the clip prompt, made over the edit. In `audioTrack: post` the `music` is the **spotting intent** for the episode score: it never enters the clip, and `prompt score E01` lays it, the post sfx, the lines and the scene beds on the episode timeline. In `bed` / `full`, `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` |
 | `wji.assets.edit` / `wji.assets.mix` (episode) | `audioTrack: post` only — the locked edit of the episode (clips cut together, no music) and the final mixed episode (edit + score + sound design). `manifest` asks for the edit once every clip is bound, then for the mix |
 | `segments[].refOverride[]` | optional — the Director pins this segment's **picture** references instead of the derived set (environment, people, props): `[{ entity, asset?: "sheet" \| "headshot" \| "lighting:<state>", faceOf?, why?, use?, zh? }]` in the order they will be connected (`@image1…`). `faceOf: "C01"` says this picture supplies that character's face, so their lines bind to it even when a body sheet of theirs comes later. Voices and the previous clip are still appended after the pictures. An empty array means "derived" |

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

@@ -61,23 +61,32 @@ the `seedNote` and `render dialogue` puts them beside each line for the polish p
   **must** ban `photorealistic`. Both gated. Always add `logo, brand name, text` — a "store
   uniform" comes back wearing a real chain's badge otherwise (seen in testing), and a real brand
   on a character is a problem in every shot after it.
-- `image.sheet`: the model-sheet layout, written out in full every time:
+- `image.sheet`: the three-panel sheet, written out in full every time. Left to right on
+  one 16:9 canvas, grey-white seamless studio background, studio lighting:
 
   ```
-  ┌──────────┬────────────────────────────┐
-  │  bust    │   front    side    back     │   ONE 16:9 canvas, pure white background
-  │ portrait ├────────────────────────────┤   LEFT ZONE ≈ 34 % width: head-and-shoulders bust,
-  │ (face    │  detail · detail · detail   │     both shoulders complete, flat bottom edge
-  │  ref)    │                            │   RIGHT-TOP: three full-body views, same height,
-  └──────────┴────────────────────────────┘     same head-to-body ratio, PROPORTIONS ARE CRITICAL
-                                               RIGHT-BOTTOM: 4–5 small detail studies;
-                                               the detail studies give way, not the figures
+  ┌────────────┬────────────┬────────────┐
+  │  headshot  │   front    │    back    │   ONE 16:9 canvas
+  │  face fills│  full body │  full body │   grey-white studio background
+  │  the height│  grey box  │            │   studio lighting
+  │            │  over face │            │
+  └────────────┴────────────┴────────────┘
   ```
 
-  Plus: `all views share the SAME face as the bust portrait`, `LIGHTING IN THE LEFT ZONE ONLY:
-  soft directional key…`, `LIGHTING IN THE RIGHT ZONES: flat even orthographic lighting`, the
-  style's render phrase (`STYLE_PRESETS[style].render` — `node scripts/short-drama.mjs` exports
-  it; copy it verbatim), `No text, no watermark`. Gated: `16:9`, render phrase, no names.
+  ```
+  Single character sheet on ONE 16:9 landscape canvas, three panels left to right,
+  grey-white seamless studio background, studio lighting. <style render phrase>.
+  LEFT: one headshot, the face filling the full height of the panel, facial features
+  large and clear. CENTER: full-body front view, the face completely covered by a flat
+  grey box so no facial features are visible. RIGHT: full-body back view, same height
+  and body proportions as the front view, feet on the same ground line. Subject:
+  <ethnicity, age, era, identity, hair, outfit>. Same costume on both full-body views.
+  No side view, no extra characters, no scenery, no text, no watermark.
+  ```
+
+  The face lives only in the left headshot. The center panel is the costume and the body.
+  Copy the style render phrase verbatim (`STYLE_PRESETS[style].render` — `node scripts/short-drama.mjs`
+  exports it). Gated: `16:9`, render phrase, no names.
 
 ## Voice
 
@@ -167,9 +176,10 @@ invents a voice that fits it, which is why the headshot must be approved first.
 one reference, so pass only the headshot node. About 3.6 credits a sample.
 
 Generate headshots first (a set of headshots is a batch — quote the total), **look at them**
-(download and open), then sheets and voices from the approved headshots. Check a sheet for: one
-face across all views, three full bodies of equal height, no squashed figures, white background.
-Regenerate rather than accept a sheet with two faces — every shot inherits it. Listen to the voice
+(download and open), then sheets and voices from the approved headshots. Check a sheet for: the
+headshot face fills the panel height, the front full body has its face covered by a flat grey
+box, the back full body matches that height, grey-white studio background. Regenerate rather
+than accept a sheet with a visible face on the front body — every shot inherits it. Listen to the voice
 before you attach it: the age and the weight of the voice should match the face.
 
 Attach and bind:

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

@@ -163,11 +163,37 @@ tables are in `cinematography.md` and the preset's guide.
 
 ### Foreground
 
-Depth needs something to be shallow *against*. `foreground` names what sits between the lens and
-the subject — a console edge, a curtain of rain off an awning, a blurred shoulder, a doorframe —
-and the frame prompt says it is thrown out of focus. `""` is a deliberately clean frame, and the
-gate allows it for up to half the cuts of a segment: a segment of clean frames reads flat, and a
-drama where every shot is clean reads like a corporate video.
+`foreground` names what sits between the lens and the subject — a console edge, a curtain of rain
+off an awning, a blurred shoulder, a doorframe — and the frame prompt says it is thrown out of focus.
+`""` is a deliberately clean frame.
+
+**How often** is `params.foregroundLevel`, gated across the episode so scenes can differ:
+
+| Level | Cuts with a foreground | Use |
+|---|---|---|
+| `low` | up to 25 % | clean, direct, face-led; only where the story asks for one |
+| `medium` (default) | 25–50 % | where the story or the shot type gives a reason |
+| `high` (default for 唯美 / 美感优先) | 50 % or more | a layered, voyeuristic or crowded look; soft, composed beauty |
+
+唯美 / 美感优先 means `composition: art-first`, `cinematography: sweet-romance` or `costume-idol`, or a genre
+that says 唯美 or 美感. Naming `foregroundLevel` overrides this.
+
+**Which cuts** — story first, then shot type, then shot size. Remove it in your head: if the audience
+loses no meaning, shoot the cut clean.
+
+1. **Story decides whether.** Threat (the barrel in front of him), watching or hiding (a doorframe, a
+   curtain), trapped or outnumbered (bodies closing in), distance between two people, power (the
+   powerful one's shoulder or weapon), closeness (her hair, soft), a clue that matters later.
+2. **Shot type decides what.** Over-the-shoulder always has one (the listener's shoulder); POV has what
+   they look past; an establishing shot has a layer of the place. Usually clean: a reaction close-up, an
+   insert, the 打脸 proof or reveal, an action impact, a moment of isolation.
+3. **Shot size decides how much.** A wide can take a large shape on one edge; a medium one edge; a close
+   a soft sliver, never near the eyes or mouth; an extreme close-up almost never.
+
+Take it from the scene: it must already be there and on the camera's side of the action. Keep it off
+the face, the mouth, the key prop and the action. Prefer simple still shapes (edges, frames, shoulders)
+over foreground faces and hands, which can read as an extra person. Do not repeat one object across
+cuts unless it is a story motif. At `high`, keep the same reasons and simply use them more.
 
 Directing feel (not gated): reverse angles for dialogue (asker's close-up, answerer's close-up);
 the first cut of an episode moves; a key action gets its own 2 s insert; a reaction shot after a

package/skill/short-drama/reference/workspace-layout.md

@@ -73,7 +73,7 @@ the headshot + sheet as image references and the voice as audio.
 ```
 
 - headshot: `canvas add image -n "C01 headshot" -m <image model> -r 1:1 -p "<image.prompt>"`
-- sheet:    `canvas add image -n "C01 sheet" --from <headshotNode> -m <image model> -r 16:9 -p "@image1 is the face to match. <image.sheet>"`
+- sheet:    `canvas add image -n "C01 sheet" --from <headshotNode> -m <image model> -r 16:9 -p "@image1 is the face to match exactly. <image.sheet>"`
 - voice:    `canvas add audio -n "C01 voice" -m <audio/tts model> -p "<voice.prompt>"` (optional; skip when no voice model is enabled)
 - title:    `canvas add title -t "C01 林小夏" --at <x>,<y>` — one per row, rows 700 px apart
 

package/skill/short-drama/scripts/selftest.mjs

@@ -14,7 +14,7 @@ import {
   paramsOf, parseEpRange, promptSkeleton, renderCharacter, renderOutline, renderProp, renderScene, renderScript,
   renderSegment, runGates, seedScript, seedStoryboard, seedanceAnchors, slug, timestamp, writeJsonFile,
   wanLegendLine, wanSheetLegendLine, wanShotHeader, segmentReferences, imageReferences, audioReferences, voiceSamplePrompt, voiceSampleSeconds, nonWhitespace,
-  speechDirection, cameraPhrase, lightPhrase, foregroundPhrase, focalOf, LIGHT_DIRECTIONS, identityOf, isEnglish,
+  speechDirection, cameraPhrase, lightPhrase, idlePhrase, idleSentence, IDLE_MAX_CHARS, eyelinePhrase, eyelineValid, onlyInFramePhrase, overShoulderPhrase, sidesLine, foregroundPhrase, foregroundBand, foregroundForLook, focalOf, LIGHT_DIRECTIONS, identityOf, isEnglish,
   renderGuideline, renderDialogue, scriptSelfCheck, beatOffsets, turnPoints, parseAge, talkAndAction, normalizeRegister, REGISTERS, REGISTER_ACCENT,
   cutStart, segmentCharacters, keyScenes, shotTexts, motionSentence, cameraClause, PURPOSE_KINDS, ANGLES, HEIGHTS, NO_SUBTITLES, LIPS_CLOSED,
   audioPrompt, musicOf, cueSeconds, AUDIO_MODEL, AUDIO_MAX_CHARS, AUDIO_MAX_SECONDS, scoreSheet, smpte,
@@ -850,18 +850,127 @@ const breaks = (gateId, project, episode, needle) => {
   breaks('photography', PROJECT, noNote, 'light.note is required');
   const wrongDir = clone(E01); wrongDir.storyboard.segments[0].cuts[0].light.direction = 'top';
   breaks('photography', PROJECT, wrongDir, 'keyed from directly above');
-  // Foreground: named in the frame, said to be out of focus, and present on at least half the cuts.
+  // Foreground: named in the frame, said to be out of focus, and within params.foregroundLevel across the episode.
   ok(foregroundPhrase(cut).includes('out of focus'), 'the foreground phrase says it is defocused');
   eq(foregroundPhrase({ foreground: '' }), '', 'a clean frame adds nothing');
   ok(foregroundPhrase({ foreground: '\u6536\u94f6\u53f0' }, 'zh').includes('\u524d\u666f'), 'the Chinese foreground phrase says 前景');
-  const noFg = clone(E01); noFg.storyboard.segments[0].cuts.forEach((c) => { c.foreground = ''; });
-  breaks('photography', PROJECT, noFg, 'no depth');
+  const noFg = clone(E01); noFg.storyboard.segments.forEach((seg) => seg.cuts.forEach((c) => { c.foreground = ''; }));
+  // The fixture sits at `high`: no foreground at all is too few there, and fine at `low`.
+  breaks('photography', PROJECT, noFg, 'params.foregroundLevel high allows');
+  const asLevel = (level) => ({ ...PROJECT, params: { ...PROJECT.params, foregroundLevel: level } });
+  ok(!failures('photography', asLevel('low'), noFg).some((f) => f.includes('foregroundLevel')), 'low accepts an episode of clean frames');
+  breaks('photography', asLevel('low'), E01, 'params.foregroundLevel low allows');
+  breaks('photography', asLevel('medium'), E01, 'params.foregroundLevel medium allows');
+  breaks('params', asLevel('sometimes'), E01, 'params.foregroundLevel must be one of');
+  const levelFor = (params) => paramsOf({ params }).foregroundLevel;
+  eq(levelFor({}), 'medium', 'the default level is medium');
+  eq(levelFor({ composition: 'standard', cinematography: 'low-key', genre: '复仇' }), 'medium', 'a standard look stays medium');
+  eq(levelFor({ composition: 'art-first' }), 'high', '艺术优先 defaults to high');
+  eq(levelFor({ cinematography: 'sweet-romance' }), 'high', 'the 唯美 romance preset defaults to high');
+  eq(levelFor({ cinematography: 'costume-idol' }), 'high', 'the 唯美 costume preset defaults to high');
+  eq(levelFor({ genre: '唯美古风' }), 'high', 'a 唯美 genre defaults to high');
+  eq(levelFor({ genre: '美感優先' }), 'high', 'a 美感優先 genre defaults to high');
+  eq(levelFor({ composition: 'art-first', foregroundLevel: 'low' }), 'low', 'a named level beats the look');
+  eq(foregroundForLook({ cinematography: 'costume-dark' }), 'medium', 'the dark costume preset is not 唯美');
+  eq(foregroundBand('low', 40).max, 10, 'low allows a quarter of the cuts');
+  eq(foregroundBand('medium', 40).min, 10, 'medium starts at a quarter');
+  eq(foregroundBand('medium', 40).max, 20, 'medium stops at half');
+  eq(foregroundBand('high', 40).min, 20, 'high starts at half');
+  ok(foregroundBand('nope', 40) === null, 'an unknown level has no band');
+  for (const [k, pr] of Object.entries(CINEMATOGRAPHY_PRESETS)) if (pr) ok(!/foreground/i.test(pr.videoPhrase) && !/前景/.test(pr.videoPhraseZh), `${k} leaves the foreground to the level`);
   const missingFg = clone(E01); delete missingFg.storyboard.segments[0].cuts[0].foreground;
   breaks('photography', PROJECT, missingFg, 'foreground is required');
   const unsaidFg = clone(E01); unsaidFg.storyboard.segments[0].cuts[0].frame = unsaidFg.storyboard.segments[0].cuts[0].frame.replace('the dripping edge of the striped awning', 'a wall');
   breaks('photography', PROJECT, unsaidFg, 'must name the foreground');
 }
 
+{
+  // Everyone on screen is alive: a model freezes whoever the prompt gives no motion.
+  eq(idlePhrase('shifts her weight', '@image3'), '@image3 shifts her weight.', 'an idle reads as a sentence');
+  eq(idlePhrase('still', '@image3'), '@image3 holds still, only breathing and blinking.', 'still keeps the breath');
+  ok(idlePhrase('轻轻换了一下重心', '@image3', 'zh').endsWith('轻轻换了一下重心。'), 'the Chinese idle');
+  eq(idleSentence({ characters: ['A', 'B'], idle: { B: 'taps a finger' } }, (id) => id), 'B taps a finger. ', 'only the people with an idle are written');
+  const p = clone(PROJECT); p.params.references = 'sheets';
+  const only = (f) => f.filter((m) => m.startsWith('E01-02'));
+  const build = (idle) => {
+    const ep = clone(E01); const seg = ep.storyboard.segments.find((s) => s.id === 'E01-02');
+    const two = seg.cuts[2];   // C01 + C02
+    if (idle) two.idle = idle;
+    seg.prompt = promptSkeleton(p, ep, seg.id).video.prompt;
+    return { ep, seg, two };
+  };
+  const bare = build();
+  ok(only(failures('idle-motion', p, bare.ep)).some((m) => m.includes('have an idle')), 'a second visible person with no idle fails');
+  const good = build({ C02: 'shifts her weight and picks at her sleeve' });
+  eq(only(failures('idle-motion', p, good.ep)).filter((m) => !m.includes('cameraNote.hold')).length, 0, 'one idle for the second person passes');
+  ok(good.seg.prompt.includes('shifts her weight and picks at her sleeve.'), 'the skeleton writes the idle');
+  const stillOne = build({ C02: 'still' });
+  ok(stillOne.seg.prompt.includes('holds still, only breathing and blinking.'), 'still is written with the breath');
+  eq(only(failures('idle-motion', p, stillOne.ep)).filter((m) => !m.includes('cameraNote.hold')).length, 0, 'keeping still is allowed when it is the performance');
+  ok(only(failures('idle-motion', p, build({ C02: 'walks to the door' }).ep)).some((m) => m.includes('too big')), 'a change of place is not an idle');
+  ok(only(failures('idle-motion', p, build({ C02: 'says something quietly' }).ep)).some((m) => m.includes('too big')), 'a line is not an idle');
+  ok(only(failures('idle-motion', p, build({ C02: 'x'.repeat(IDLE_MAX_CHARS + 1) }).ep)).some((m) => m.includes('one small motion')), 'an idle stays small');
+  const unwritten = build({ C02: 'taps a finger' }); unwritten.seg.prompt = unwritten.seg.prompt.replace(/taps a finger\.\s*/, '');
+  ok(only(failures('idle-motion', p, unwritten.ep)).some((m) => m.includes('must carry the idle')), 'an idle left out of the prompt fails');
+  const onlyHold = build({ C02: 'taps a finger' }); onlyHold.two.cameraNote = { ...onlyHold.two.cameraNote, hold: 'only the sign flickers' };
+  ok(only(failures('idle-motion', p, onlyHold.ep)).some((m) => m.includes('drop "only"')), '"only the sign" contradicts the people moving');
+  const offScreen = build({ C03: 'taps a finger' });
+  ok(only(failures('idle-motion', p, offScreen.ep)).some((m) => m.includes('not on screen')), 'an idle for someone off screen fails');
+  eq(failures('idle-motion', PROJECT, E01).length, 0, 'keyframes mode is exempt');
+}
+
+{
+  // Two people on screen, sheets mode: who is in frame, where they look, which side they stand on.
+  eq(eyelinePhrase('screen-right down', '@image3'), '@image3 looks toward screen-right and down.', 'an eyeline has a direction and a height');
+  eq(eyelinePhrase('task', '@image3'), '@image3 keeps their eyes on what their hands are doing.', 'task keeps the eyes on the work');
+  ok(eyelinePhrase('away screen-left', '@image3').includes('looks away'), 'away says so');
+  ok(eyelinePhrase('screen-left up', '@image3', 'zh').includes('左侧上方'), 'the Chinese eyeline');
+  ok(eyelineValid('screen-left level') && eyelineValid('task') && eyelineValid('away screen-right down'), 'valid eyelines');
+  ok(!eyelineValid('at him') && !eyelineValid('screen-right sideways'), 'an eyeline without a direction is refused');
+  const p = clone(PROJECT); p.params.references = 'sheets';
+  const framed = () => {
+    const ep = clone(E01);
+    const seg = ep.storyboard.segments.find((s) => s.id === 'E01-02');   // C01 | C02 | C01+C02 | C02 | C02, C02 screen left
+    const look = { C01: 'screen-left level', C02: 'screen-right level' };
+    seg.cuts.forEach((c) => { c.eyeline = Object.fromEntries((c.characters || []).map((id) => [id, look[id]])); });
+    seg.prompt = promptSkeleton(p, ep, seg.id).video.prompt;
+    return { ep, seg };
+  };
+  const only = (f) => f.filter((m) => m.startsWith('E01-02'));
+  const { ep: okEp, seg: okSeg } = framed();
+  eq(only(failures('two-person-framing', p, okEp)).length, 0, 'the skeleton writes everything the gate asks for');
+  ok(okSeg.prompt.includes('Sides: '), 'the skeleton locks the sides');
+  ok(okSeg.prompt.includes('Only @image'), 'the skeleton opens a single with who is in frame');
+  ok(okSeg.prompt.includes('looks toward screen-left'), 'the skeleton states the eyeline');
+  const noLook = framed(); delete noLook.seg.cuts[0].eyeline;
+  ok(only(failures('two-person-framing', p, noLook.ep)).some((m) => m.includes('is required')), 'an eyeline is required');
+  const vague = framed(); vague.seg.cuts[0].eyeline = { C01: 'at him' };
+  ok(only(failures('two-person-framing', p, vague.ep)).some((m) => m.includes('not valid')), '"at him" is refused');
+  const wrong = framed(); wrong.seg.cuts[0].eyeline = { C01: 'screen-right level' };
+  ok(only(failures('two-person-framing', p, wrong.ep)).some((m) => m.includes('so looking at the other person is screen-left')), 'looking away from the other person is caught');
+  const away = framed(); away.seg.cuts[0].eyeline = { C01: 'away screen-right' }; away.seg.prompt = promptSkeleton(p, away.ep, away.seg.id).video.prompt;
+  ok(!only(failures('two-person-framing', p, away.ep)).some((m) => m.includes('so looking')), 'a deliberate look away passes');
+  const noSides = framed(); noSides.seg.prompt = noSides.seg.prompt.replace(/Sides: [^\n]*\n/, '');
+  ok(only(failures('two-person-framing', p, noSides.ep)).some((m) => m.includes('must lock the sides')), 'a prompt without the sides line fails');
+  const leaked = framed();
+  const labelOf = /(@image\d+) looks toward screen-right/.exec(leaked.seg.prompt)[1];
+  leaked.seg.prompt = leaked.seg.prompt.replace(/(Shot 1 \([^)]*\): )/, `$1Behind him stands ${labelOf}. `).replace(/(\[Shot 1\] )/, `$1Behind him stands ${labelOf}. `);
+  ok(only(failures('two-person-framing', p, leaked.ep)).some((m) => m.includes('must not describe')), 'a single that names the other person fails');
+  const ots = framed(); const twoShot = ots.seg.cuts[2];
+  twoShot.ots = 'C01'; delete twoShot.eyeline.C01;
+  ots.seg.prompt = promptSkeleton(p, ots.ep, ots.seg.id).video.prompt;
+  ok(ots.seg.prompt.includes('their face not visible'), 'the skeleton writes the over-the-shoulder');
+  ok(ots.seg.prompt.includes('lower-right foreground'), 'the near shoulder sits on its own side of the axis');
+  eq(only(failures('two-person-framing', p, ots.ep)).length, 0, 'over-the-shoulder needs no eyeline from the shoulder');
+  const badOts = framed(); badOts.seg.cuts[0].ots = 'C02';
+  ok(only(failures('two-person-framing', p, badOts.ep)).some((m) => m.includes('ots must be one of')), 'ots must be on screen with one other');
+  eq(onlyInFramePhrase('@image3', 'zh'), '画面中只有@image3。', 'the Chinese single');
+  ok(overShoulderPhrase('@image3', 'left', 'zh').includes('左下方前景'), 'the Chinese over-the-shoulder');
+  ok(sidesLine({ screenLeft: 'A', screenRight: 'B' }, (id) => id, 'zh').includes('A始终在画面左侧'), 'the Chinese sides line');
+  // Keyframes carry the blocking in their pictures: the gate stays out of the way.
+  eq(failures('two-person-framing', PROJECT, E01).length, 0, 'keyframes mode is exempt');
+}
+
 {
   // The house cinematography (params.cinematography low-key): practical sources, no flat light on a
   // person, most cuts keyed from the side or behind, shot wide open; the look rides every prompt.
@@ -2307,8 +2416,8 @@ const breaks = (gateId, project, episode, needle) => {
 
 // ── gate inventory (crew engine) ────────────────────────────────────────────
 {
-  eq(GATES.length, 67, 'gate count');
-  eq(GATES.filter((g) => !g.advisory).length, 61, 'hard gate count');
+  eq(GATES.length, 69, 'gate count');
+  eq(GATES.filter((g) => !g.advisory).length, 63, 'hard gate count');
   eq(GATES.filter((g) => g.advisory).length, 6, 'advisory gate count');
   ok(!GATES.find((g) => g.id === 'boundary-contrast').advisory, 'boundary-contrast is hard');
   ok(GATES.find((g) => g.id === 'boundary-contrast-episode').advisory, 'boundary-contrast-episode is advisory');
@@ -2430,8 +2539,8 @@ const breaks = (gateId, project, episode, needle) => {
   const results = runGates(makeContext(PROJECT, { 1: E01 }));
   const rep = formatGates(results);
   eq(Object.keys(rep).sort().join(','), 'advisory,failed,hard,lines,notes,summary,text', 'formatGates shape');
-  eq(rep.summary, '✓ 61 gate(s) passed, 6 advisory (1 note)', 'fixture summary');
-  eq(rep.failed, 0, 'nothing failed'); eq(rep.hard, 61, 'hard count'); eq(rep.advisory, 6, 'advisory count');
+  eq(rep.summary, '✓ 63 gate(s) passed, 6 advisory (1 note)', 'fixture summary');
+  eq(rep.failed, 0, 'nothing failed'); eq(rep.hard, 63, 'hard count'); eq(rep.advisory, 6, 'advisory count');
   // The fixture now raises one advisory (E01-03 carries the 爽点 and is not cut as faceslap),
   // exactly as it does in the wji-cli copy — advisory lines print, failures still must not.
   eq(rep.lines.filter((l) => l.includes('✗')).length, 0, 'a green run prints no failed gates');

package/skill/short-drama/scripts/short-drama.mjs

@@ -19,6 +19,7 @@
 //            [--market mainland|overseas]                            (mainland holds the supernatural to a rational explanation)
 //            [--format short|medium|movie]                            (短剧 1–3 min, 中剧 4–15 min, 电影 in ~5-minute parts — see FORMATS)
 //            [--register 台湾国语]                                      (语体 — decides how lines are written and the accent spoken)
+//            [--foreground low|medium|high]                             (how often cuts shoot past a foreground — see FOREGROUND_LEVELS)
 //            [--image-lang en|zh]                                       (language of the character / scene / prop image prompts)
 //   validate <project> [--stage outline|characters|art|script|storyboard] [--ep 1-3]
 //   checkup  <project> [--stage …] [--ep …]            every gate with ✓/✗, exit 0
@@ -199,6 +200,28 @@ export const AUDIO_MAX_REFS = 3;
  * `bed` (ambience + sfx + music) / `full` (the bed plus the lines): a Seed Audio node per segment.
  */
 export const AUDIO_TRACK_MODES = ['post', 'none', 'bed', 'full'];
+// Share of an episode's cuts that may carry a foreground. Measured per episode, not per segment, so a
+// siege can be full of them and a quiet confession can have none.
+export const FOREGROUND_LEVELS = Object.freeze({
+  low: { min: 0, max: 0.25 },
+  medium: { min: 0.25, max: 0.5 },
+  high: { min: 0.5, max: 1 },
+});
+/**
+ * The level a project gets when it does not name one: `high` for 唯美 or 美感优先 — the art-first
+ * composition, the two 唯美 cinematography presets, or a genre that says so — `medium` otherwise.
+ */
+export function foregroundForLook(params) {
+  const aesthetic = params?.composition === 'art-first'
+    || ['sweet-romance', 'costume-idol'].includes(params?.cinematography)
+    || /唯美|美感/.test(String(params?.genre || ''));
+  return aesthetic ? 'high' : 'medium';
+}
+/** The foreground cut count a level allows in an episode of `cuts` cuts. */
+export function foregroundBand(level, cuts) {
+  const band = FOREGROUND_LEVELS[level];
+  return band ? { min: Math.floor(band.min * cuts), max: Math.ceil(band.max * cuts) } : null;
+}
 /** No per-segment audio node in these modes. */
 export const NO_SEGMENT_TRACK = ['post', 'none'];
 /** What the music does at a cue point. */
@@ -413,10 +436,58 @@ export function speechDirection(character, delivery, lang = 'en') {
   return bits.join(lang === 'zh' ? '\uff0c' : ', ');
 }
 
+// Two people on screen. A model puts into the shot everyone the shot names, and "looking at him" gives
+// it no direction, so sheets-mode prompts say who is in frame, which way each person looks and which
+// side each stands on (gate two-person-framing).
+export const EYELINE_DIRECTIONS = ['screen-left', 'screen-right'];
+export const EYELINE_HEIGHTS = ['level', 'up', 'down'];
+/** "screen-right down" · "away screen-left" · "task" (eyes on what the hands are doing). */
+export function parseEyeline(value) {
+  const words = String(value || '').trim().split(/\s+/).filter(Boolean);
+  if (words[0] === 'task') return { task: true };
+  const away = words[0] === 'away';
+  const [to, height = 'level'] = away ? words.slice(1) : words;
+  return { to, height, away };
+}
+export function eyelineValid(value) {
+  const e = parseEyeline(value);
+  return Boolean(e.task) || (EYELINE_DIRECTIONS.includes(e.to) && EYELINE_HEIGHTS.includes(e.height));
+}
+export function eyelinePhrase(value, who, lang = 'en') {
+  const e = parseEyeline(value);
+  const zh = lang === 'zh';
+  if (e.task) return zh ? `${who}的视线落在手上的活上。` : `${who} keeps their eyes on what their hands are doing.`;
+  const side = zh ? (e.to === 'screen-left' ? '左' : '右') : e.to;
+  if (zh) return `${who}的视线${e.away ? '移开，' : ''}朝画面${side}侧${e.height === 'up' ? '上方' : e.height === 'down' ? '下方' : '平视'}。`;
+  return `${who} ${e.away ? 'looks away toward' : 'looks toward'} ${side}${e.height === 'up' ? ' and up' : e.height === 'down' ? ' and down' : ' at eye level'}.`;
+}
+export function sidesLine(axis, whoOf, lang = 'en') {
+  const left = whoOf(axis.screenLeft), right = whoOf(axis.screenRight);
+  return lang === 'zh' ? `站位：${left}始终在画面左侧，${right}始终在画面右侧。` : `Sides: ${left} stays on screen left and ${right} on screen right in every shot.`;
+}
+export function onlyInFramePhrase(who, lang = 'en') {
+  return lang === 'zh' ? `画面中只有${who}。` : `Only ${who} in frame.`;
+}
+export function overShoulderPhrase(who, side, lang = 'en') {
+  return lang === 'zh'
+    ? `越过${who}的肩拍摄：其肩与后脑虚化在画面${side === 'left' ? '左' : '右'}下方前景，看不到其脸。`
+    : `Over-the-shoulder from behind ${who}: their shoulder and the back of their head soft in the lower-${side} foreground, their face not visible.`;
+}
+/** What a shot opens with in a two-person segment: who is in frame, then where each person looks. */
+export function shotFraming(cut, seg, whoOf, lang = 'en') {
+  if (segmentCharacters(seg).length < 2) return '';
+  const chars = cut.characters || [];
+  const parts = [];
+  if (cut.ots) parts.push(overShoulderPhrase(whoOf(cut.ots), seg.axis?.screenLeft === cut.ots ? 'left' : 'right', lang));
+  else if (chars.length === 1) parts.push(onlyInFramePhrase(whoOf(chars[0]), lang));
+  for (const id of chars) if (id !== cut.ots && cut.eyeline?.[id]) parts.push(eyelinePhrase(cut.eyeline[id], whoOf(id), lang));
+  return parts.length ? `${parts.join(' ')} ` : '';
+}
+
 /**
  * The blurred thing between the lens and the subject. Depth needs something to be shallow against,
- * so a cut names one and the prompt says it is out of focus; an empty `foreground` is a deliberate
- * clean frame and the gate limits how many of those a segment may have.
+ * so a cut that needs one names it and the prompt says it is out of focus; an empty `foreground` is a
+ * deliberate clean frame. params.foregroundLevel sets how many of each an episode has.
  */
 export function foregroundPhrase(cut, lang = 'en') {
   const fg = String(cut?.foreground || '').trim();
@@ -435,6 +506,23 @@ export function motionSentence(cut, lang = 'en') {
   return `Cue: ${t}. Action: ${a}. End: ${r}.`;
 }
 
+// Everyone on screen is alive. A model freezes whoever the prompt gives no motion, so each person other
+// than the one carrying the cut's action gets a small motion of their own (gate idle-motion).
+export const IDLE_STILL = 'still';
+// A line, a mouth that moves or a change of place is a cut's action, not an idle.
+export const IDLE_TOO_BIG = /\b(says?|speaks?|talks?|whispers?|shouts?|mouths?|chews?|walks?|crosses|leaves|enters|runs?|sits? down|stands? up)\b|[说說讲講喊嚼]|走向|离开|離開|坐下|站起/i;
+export const IDLE_MAX_CHARS = 90;
+export function idlePhrase(idle, who, lang = 'en') {
+  const text = String(idle || '').trim().replace(/[.。]+$/, '');
+  if (text === IDLE_STILL) return lang === 'zh' ? `${who}保持不动，只有呼吸与眨眼。` : `${who} holds still, only breathing and blinking.`;
+  return lang === 'zh' ? `${who}${text}。` : `${who} ${text}.`;
+}
+/** The idle motions of a cut, in on-screen order. */
+export function idleSentence(cut, whoOf, lang = 'en') {
+  const parts = (cut.characters || []).filter((id) => cut.idle?.[id]).map((id) => idlePhrase(cut.idle[id], whoOf(id), lang));
+  return parts.length ? `${parts.join(' ')} ` : '';
+}
+
 /**
  * A lock-off is written (what still moves, held), a move is written (why, when, along what, ending
  * where) — an empty camera line is read by the model as permission to drift.
@@ -614,8 +702,8 @@ export const CINEMATOGRAPHY_PRESETS = {
   'low-key': {
     label: 'low-key, practical-lit, negative space, wide open',
     framePhrase: 'low-key practical lighting',
-    videoPhrase: 'low-key cinematography lit only by practical sources in the scene, faces held in shadow and shaped by side, back and rim light with no flat fill, compositions with generous negative space and layered out-of-focus foregrounds, shallow depth of field',
-    videoPhraseZh: '低调光影，光线只来自场景内的现场光源，人物处于阴影中，以侧光、逆光、轮廓光勾勒，不打平光补光，构图留白，前景虚化增加层次，大光圈浅景深',
+    videoPhrase: 'low-key cinematography lit only by practical sources in the scene, faces held in shadow and shaped by side, back and rim light with no flat fill, compositions with generous negative space, shallow depth of field',
+    videoPhraseZh: '低调光影，光线只来自场景内的现场光源，人物处于阴影中，以侧光、逆光、轮廓光勾勒，不打平光补光，构图留白，大光圈浅景深',
     sourceHint: 'the practical in or just outside the frame that the key comes from (a lamp, a window, a screen, a sign), not a film light',
     // 包围光 / 世界光: light from the lens axis or from nowhere flattens the face and kills the shadow side.
     bannedLight: ['frontal', 'ambient'],
@@ -630,8 +718,8 @@ export const CINEMATOGRAPHY_PRESETS = {
   'sweet-romance': {
     label: 'sweet romance: soft high-key glow, backlit halo, pastel, dreamy bokeh',
     framePhrase: 'soft romantic lighting',
-    videoPhrase: 'soft romantic cinematography of a modern idol romance drama, bright airy high-key light from soft motivated sources, faces softly and flatteringly lit with a warm backlight haloing the hair, gentle low-contrast pastel grade with creamy highlights and lifted shadows, dreamy diffusion and soft halation, shot wide open with an extremely shallow depth of field, dreamy oversized creamy bokeh balls and soft out-of-focus foregrounds',
-    videoPhraseZh: '唯美浪漫偶像剧质感，明亮通透的柔光，光线来自窗光、夕阳、串灯等柔和光源，人物面部柔和明亮，暖色逆光在发丝上形成光晕，低反差粉嫩柔和色调，高光奶油般柔和，暗部通透不死黑，柔焦朦胧，全开大光圈极浅景深，梦幻的大颗奶油光斑散景与柔焦前景',
+    videoPhrase: 'soft romantic cinematography of a modern idol romance drama, bright airy high-key light from soft motivated sources, faces softly and flatteringly lit with a warm backlight haloing the hair, gentle low-contrast pastel grade with creamy highlights and lifted shadows, dreamy diffusion and soft halation, shot wide open with an extremely shallow depth of field, dreamy oversized creamy bokeh balls',
+    videoPhraseZh: '唯美浪漫偶像剧质感，明亮通透的柔光，光线来自窗光、夕阳、串灯等柔和光源，人物面部柔和明亮，暖色逆光在发丝上形成光晕，低反差粉嫩柔和色调，高光奶油般柔和，暗部通透不死黑，柔焦朦胧，全开大光圈极浅景深，梦幻的大颗奶油光斑散景',
     sourceHint: 'the soft source in or just outside the frame that the light comes from (a big window, the low sun, overcast sky, string lights, a café lamp), not a film light',
     // 底光 / 顶光: the horror and interrogation lights — they carve eye sockets and chins.
     bannedLight: ['underlight', 'top'],
@@ -685,8 +773,8 @@ export const CINEMATOGRAPHY_PRESETS = {
   'costume-dark': {
     label: 'dark historical realism: firelight and lattice windows, faces in shadow, smoke, earthy texture',
     framePhrase: 'low-key firelit period lighting',
-    videoPhrase: 'gritty low-key historical cinematography with realistic texture, lit only by candles, oil lamps, braziers, torches and daylight or moonlight through lattice windows, faces carved by side and back light and falling into deep shadow, smoke and dust hanging in shafts of light, desaturated earthy palette of ochre, umber and cold steel blue, worn fabric, weathered wood and stone, sweeping wide and extreme-wide shots with vast negative space of darkness, smoke and sky, compositions with negative space and layered out-of-focus foregrounds, shallow depth of field',
-    videoPhraseZh: '写实质感的暗黑古装影调，光线只来自蜡烛、油灯、火盆、火把，以及透过窗棂的日光或月光，人物面部被侧光与逆光雕刻，隐入浓重阴影，烟尘在光束中悬浮，低饱和的赭石、深棕与冷铁蓝色调，布料磨旧，木石斑驳，大量全景与大全景，大面积留白于黑暗、烟尘与天空之中，构图留白，前景虚化增加层次，大光圈浅景深',
+    videoPhrase: 'gritty low-key historical cinematography with realistic texture, lit only by candles, oil lamps, braziers, torches and daylight or moonlight through lattice windows, faces carved by side and back light and falling into deep shadow, smoke and dust hanging in shafts of light, desaturated earthy palette of ochre, umber and cold steel blue, worn fabric, weathered wood and stone, sweeping wide and extreme-wide shots with vast negative space of darkness, smoke and sky, compositions with negative space, shallow depth of field',
+    videoPhraseZh: '写实质感的暗黑古装影调，光线只来自蜡烛、油灯、火盆、火把，以及透过窗棂的日光或月光，人物面部被侧光与逆光雕刻，隐入浓重阴影，烟尘在光束中悬浮，低饱和的赭石、深棕与冷铁蓝色调，布料磨旧，木石斑驳，大量全景与大全景，大面积留白于黑暗、烟尘与天空之中，构图留白，大光圈浅景深',
     sourceHint: 'the period source the key comes from (a candle, an oil lamp, a brazier, a torch, daylight or moonlight through a lattice window), never an electric light',
     bannedLight: ['frontal', 'ambient'],
     bannedWhy: 'floods the face (包围光 / 世界光) — stage the person so the flame or the lattice window sits beside or behind them',
@@ -1221,6 +1309,8 @@ export function slug(name) {
 export function paramsOf(project) {
   const p = { ...DEFAULT_PARAMS, ...(project.params || {}) };
   p.thresholds = { ...DEFAULT_PARAMS.thresholds, ...(project.params?.thresholds || {}) };
+  // Named, or read from the look, so a later change of look carries the level with it.
+  if (project.params?.foregroundLevel == null) p.foregroundLevel = foregroundForLook(p);
   // The model decides how long a segment may be; an explicit param still wins, but it is then gated.
   const mode = videoModel(p);
   if (project.params?.maxSegmentSeconds == null) p.maxSegmentSeconds = mode.maxSegmentSeconds;
@@ -1619,6 +1709,7 @@ export const GATES = [
     if (!ADAPT_MODES.includes(params.adaptMode)) out.push(`params.adaptMode must be one of ${ADAPT_MODES.join(' / ')}`);
     if (!VIDEO_MODES.includes(params.video)) out.push(`params.video must be one of ${VIDEO_MODES.join(' / ')}`);
     if (!AUDIO_TRACK_MODES.includes(params.audioTrack)) out.push(`params.audioTrack must be one of ${AUDIO_TRACK_MODES.join(' / ')}`);
+    if (!FOREGROUND_LEVELS[params.foregroundLevel]) out.push(`params.foregroundLevel must be one of ${Object.keys(FOREGROUND_LEVELS).join(' / ')}`);
     if (!REGISTERS.includes(params.register)) out.push(`params.register (语体) must be one of ${REGISTERS.join(' / ')} — it decides how the lines are written and the accent the model speaks`);
     if (!REFERENCE_MODES.includes(params.references)) out.push(`params.references must be one of ${REFERENCE_MODES.join(' / ')}`);
     if (!DURATION_MODES.includes(params.videoDuration)) out.push(`params.videoDuration must be one of ${DURATION_MODES.join(' / ')}`);
@@ -3100,15 +3191,16 @@ export const GATES = [
     }
     return out;
   }),
-  gate('photography', 'storyboard', 'every cut names its lens and stop, its key-light direction, and enough foreground; the cinematography preset (named source, preferred light, wide open)', (ctx) => {
+  gate('photography', 'storyboard', 'every cut names its lens and stop, its key-light direction, and a foreground share within params.foregroundLevel; the cinematography preset (named source, preferred light, wide open)', (ctx) => {
     const { project, params } = ctx;
     const out = [];
     const kit = params.camera || DEFAULT_PARAMS.camera;
     const look = cinematographyOf(params);
-    for (const [, e] of ctx.episodes) {
+    for (const [epId, e] of ctx.episodes) {
+      let epCuts = 0, epForeground = 0;
       for (const seg of e.storyboard?.segments || []) {
         const cuts = seg.cuts || [];
-        let withForeground = 0;
+        epCuts += cuts.length;
         let withPeople = 0, shaped = 0, withBokeh = 0, wides = 0;
         cuts.forEach((c, k) => {
           const where = `${seg.id} cut ${k + 1}`;
@@ -3132,10 +3224,11 @@ export const GATES = [
           // Foreground.
           const fg = String(c.foreground || '').trim();
           if (fg) {
-            withForeground += 1;
+            epForeground += 1;
             if (frame.trim() && !frame.includes(fg)) out.push(`${where}: frame prompt must name the foreground "${fg}"`);
             if (frame.trim() && !/out of focus|foreground blur|defocus|bokeh|soft foreground/i.test(frame)) out.push(`${where}: the foreground is named but never said to be out of focus`);
           }
+          else if (c.ots) epForeground += 1;   // the near shoulder is the foreground
           if (c.foreground === undefined) out.push(`${where}: foreground is required — name what sits between the lens and the subject, or "" for a deliberately clean frame`);
           if (!look) return;
           // The cinematography preset: a named source, no banned light on a person, shot wide open.
@@ -3161,8 +3254,10 @@ export const GATES = [
         if (look && look.bokehShare && cuts.length && withBokeh < look.bokehShare * cuts.length) out.push(`${seg.id}: only ${withBokeh} of ${cuts.length} frames name their bokeh — at least ${Math.round(look.bokehShare * 100)} % must say what melts into bokeh behind or in front of the subject (params.cinematography ${params.cinematography})`);
         if (look && look.widePerSegment && cuts.length && wides < look.widePerSegment) out.push(`${seg.id}: no wide or extreme-wide cut — ${params.cinematography} needs at least ${look.widePerSegment} per segment, a 全景 / 大全景 with vast negative space`);
         if (look && withPeople && shaped < look.preferredShare * withPeople) out.push(`${seg.id}: only ${shaped} of ${withPeople} cuts with people are ${look.preferredWhat} (${look.preferredLight.join(' / ')}) — at least ${Math.round(look.preferredShare * 100)} % must (params.cinematography ${params.cinematography}); re-stage the person against the source or move the camera`);
-        // "Reasonably" means most of them: a segment of clean frames is flat.
-        if (cuts.length && withForeground * 2 < cuts.length) out.push(`${seg.id}: only ${withForeground} of ${cuts.length} cuts have a foreground element — at least half must, or the segment has no depth`);
+      }
+      const band = foregroundBand(params.foregroundLevel, epCuts);
+      if (band && (epForeground < band.min || epForeground > band.max)) {
+        out.push(`E${pad2(epId)}: ${epForeground} of ${epCuts} cuts have a foreground — params.foregroundLevel ${params.foregroundLevel} allows ${band.min}–${band.max}. Change which cuts carry one (story first), or change the level`);
       }
     }
     return out;
@@ -3553,7 +3648,7 @@ export const GATES = [
           const text = texts.get(k + 1);
           if (!text) return;   // the dialect gate reports the missing shot
           const lines = claimedLines(scene, [c]);
-          if (mode.family === 'h3' && lines.length && (c.characters || []).length >= 2 && !/does not speak|lips remain completely closed/.test(text)) out.push(`${seg.id} [Shot ${k + 1}]: two people on screen while one speaks — say the other "does not speak; ${LIPS_CLOSED}" or the lip-sync lands on the more visible face (measured 3/3 vs 2/3)`);
+          if (mode.family === 'h3' && lines.length && (c.characters || []).length >= 2 && !c.ots && !/does not speak|lips remain completely closed/.test(text)) out.push(`${seg.id} [Shot ${k + 1}]: two people on screen while one speaks — say the other "does not speak; ${LIPS_CLOSED}" or the lip-sync lands on the more visible face (measured 3/3 vs 2/3)`);
           if (sheetOf) for (const id of c.characters || []) {
             const label = sheetOf.get(id);
             if (label && !text.includes(label)) out.push(`${seg.id} shot ${k + 1}: ${characterById(project, id)?.identityEn || id} is on screen but the shot never binds ${label} — a person bound in one shot and unbound in the next becomes two people`);
@@ -3564,6 +3659,93 @@ export const GATES = [
     }
     return out;
   }),
+  gate('two-person-framing', 'storyboard', 'sheets mode, two-person segments: a single names only its person, every look has a screen direction toward the other, the sides are locked, over-the-shoulder is said', (ctx) => {
+    const { project, params } = ctx;
+    const out = [];
+    if (params.references !== 'sheets') return out;
+    const lang = videoModel(params).promptLang === 'zh' ? 'zh' : 'en';
+    for (const [, e] of ctx.episodes) {
+      for (const seg of e.storyboard?.segments || []) {
+        const people = segmentCharacters(seg);
+        if (people.length < 2) continue;
+        const cuts = seg.cuts || [];
+        const axis = isObject(seg.axis) ? seg.axis : null;
+        const labels = characterLabels(segmentReferences(project, e, seg));
+        const whoOf = (id) => labels.get(id) || identityOf(characterById(project, id));
+        const prompt = String(seg.prompt || '');
+        const texts = prompt.trim() ? shotTexts(prompt, videoModel(params).family, params.references) : new Map();
+        if (prompt.trim() && axis?.screenLeft && axis?.screenRight && !cuts.some((c) => c.axisSide === 'cross')) {
+          const line = sidesLine(axis, whoOf, lang);
+          if (!prompt.includes(line)) out.push(`${seg.id}: the prompt must lock the sides — add "${line}"`);
+        }
+        cuts.forEach((c, k) => {
+          const where = `${seg.id} cut ${k + 1}`;
+          const chars = c.characters || [];
+          const text = texts.get(k + 1);
+          if (c.ots) {
+            if (!chars.includes(c.ots) || chars.length !== 2) out.push(`${where}: ots must be one of exactly two people on screen — the one whose shoulder is near the lens`);
+            else if (text && !text.includes(overShoulderPhrase(whoOf(c.ots), axis?.screenLeft === c.ots ? 'left' : 'right', lang))) out.push(`${where}: the shot must say the over-the-shoulder — paste "${overShoulderPhrase(whoOf(c.ots), axis?.screenLeft === c.ots ? 'left' : 'right', lang)}"`);
+          } else if (chars.length === 1 && text) {
+            const phrase = onlyInFramePhrase(whoOf(chars[0]), lang);
+            if (!text.includes(phrase)) out.push(`${where}: a single must open with "${phrase}"`);
+            for (const other of people.filter((id) => id !== chars[0])) {
+              const label = labels.get(other);
+              const identity = String(characterById(project, other)?.identityEn || '').trim();
+              if ((label && new RegExp(`${label}(?!\\d)`).test(text)) || (identity && text.includes(identity))) out.push(`${where}: a single on ${chars[0]} must not describe ${other} — whoever a shot names ends up on screen`);
+            }
+          }
+          for (const id of chars) {
+            if (id === c.ots) continue;
+            const value = c.eyeline?.[id];
+            if (!value) { out.push(`${where}: eyeline.${id} is required — "screen-left|screen-right level|up|down", "away screen-left" or "task"`); continue; }
+            if (!eyelineValid(value)) { out.push(`${where}: eyeline.${id} "${value}" is not valid — "screen-left|screen-right level|up|down", "away screen-left" or "task"`); continue; }
+            const look = parseEyeline(value);
+            if (axis && !look.task && !look.away && c.axisSide !== 'cross' && (id === axis.screenLeft || id === axis.screenRight)) {
+              const toward = id === axis.screenLeft ? 'screen-right' : 'screen-left';
+              if (look.to !== toward) out.push(`${where}: ${id} stands on ${id === axis.screenLeft ? 'screen left' : 'screen right'}, so looking at the other person is ${toward}, not ${look.to} — or say "away ${look.to}"`);
+            }
+            if (text && !text.includes(eyelinePhrase(value, whoOf(id), lang))) out.push(`${where}: the shot must state the eyeline — paste "${eyelinePhrase(value, whoOf(id), lang)}"`);
+          }
+        });
+      }
+    }
+    return out;
+  }),
+  gate('idle-motion', 'storyboard', 'sheets mode: in a cut with two or more visible faces, everyone but the one carrying the action has a small motion of their own, written into the shot', (ctx) => {
+    const { project, params } = ctx;
+    const out = [];
+    if (params.references !== 'sheets') return out;
+    const lang = videoModel(params).promptLang === 'zh' ? 'zh' : 'en';
+    for (const [, e] of ctx.episodes) {
+      for (const seg of e.storyboard?.segments || []) {
+        const labels = characterLabels(segmentReferences(project, e, seg));
+        const whoOf = (id) => labels.get(id) || identityOf(characterById(project, id));
+        const prompt = String(seg.prompt || '');
+        const texts = prompt.trim() ? shotTexts(prompt, videoModel(params).family, params.references) : new Map();
+        (seg.cuts || []).forEach((c, k) => {
+          const where = `${seg.id} cut ${k + 1}`;
+          const visible = (c.characters || []).filter((id) => id !== c.ots);
+          for (const [id, idle] of Object.entries(isObject(c.idle) ? c.idle : {})) {
+            if (!(c.characters || []).includes(id)) out.push(`${where}: idle.${id} — that person is not on screen`);
+            const text = String(idle || '').trim();
+            if (text.length > IDLE_MAX_CHARS) out.push(`${where}: idle.${id} is ${text.length} chars, max ${IDLE_MAX_CHARS} — one small motion`);
+            if (IDLE_TOO_BIG.test(text)) out.push(`${where}: idle.${id} "${text}" is too big for an idle — a line, a moving mouth or a change of place is a cut's action`);
+            const phrase = idlePhrase(idle, whoOf(id), lang);
+            const shot = texts.get(k + 1);
+            if (shot && !shot.includes(phrase)) out.push(`${where}: the shot must carry the idle — paste "${phrase}"`);
+          }
+          if (visible.length < 2) return;
+          const idled = visible.filter((id) => String(c.idle?.[id] || '').trim());
+          if (idled.length < visible.length - 1) {
+            const missing = visible.filter((id) => !idled.includes(id));
+            out.push(`${where}: ${visible.length} people are visible but only ${idled.length} have an idle — give all but the one carrying the action a small motion in cut.idle (${missing.join(', ')}), or "${IDLE_STILL}" when keeping still is the performance`);
+          }
+          if (/^\s*(only|nothing but)\b|只有|只剩/i.test(String(c.cameraNote?.hold || ''))) out.push(`${where}: cameraNote.hold says only "${c.cameraNote.hold}" moves, but the people in frame move too — drop "only"`);
+        });
+      }
+    }
+    return out;
+  }),
   gate('audio-track', 'storyboard', 'Seed Audio node per segment: the derived prompt fits the model (≤ 120 s, ≤ 2048 chars, ≤ 3 voices in full mode)', (ctx) => {
     const { project, params } = ctx;
     const out = [];
@@ -3599,6 +3781,9 @@ export const GATES = [
           const action = String(c.motion?.action || '');
           if (/\b(does not|doesn't|never)\b/i.test(action) || /没有|不去|不[看说动]/.test(action)) out.push(`${where}: motion.action is phrased as what does not happen — a model cannot film an absence; write the action that happens instead (a hold, a hand that stays)`);
         });
+        const scene = (e.scenes || [])[Number(seg.sceneIndex) - 1];
+        const twoFaceLines = scene ? cuts.filter((c) => (c.characters || []).length >= 2 && !c.ots && claimedLines(scene, [c]).length).length : 0;
+        if (twoFaceLines >= 2) out.push(`${seg.id}: ${twoFaceLines} lines are played with both faces in frame — try the pattern in craft-shots.md: a two-shot once, over-the-shoulder for the exchange, a clean single for the punchline`);
         if (cuts.length >= 4 && ups >= 2 && downs === 0) out.push(`${seg.id}: every cut tightens — by mid-segment there is nowhere left to go; step back out once or hold the working size`);
       }
     }
@@ -3999,11 +4184,24 @@ function checkSpeechDirections(seg, prompt, lines, project, lang, refs = []) {
   return out;
 }
 
+/** Which image reference carries each person's face in a segment. */
+export function characterLabels(refs) {
+  const images = refs.filter((r) => r.kind === 'image');
+  const labels = new Map();
+  for (const r of images) {
+    const who = r.faceOf || (r.asset === 'sheet' || r.asset === 'headshot' ? r.entity : null);
+    if (who && !labels.has(who)) labels.set(who, r.label);
+  }
+  for (const r of images.filter((x) => x.asset === 'headshot' || x.faceOf)) labels.set(r.faceOf || r.entity, r.label);
+  return labels;
+}
+
 function shotParagraphs(prompt) {
   const map = new Map();
   const re = /\[Shot (\d+)\]\s*([\s\S]*?)(?=\n\[Shot \d+\]|\n\s*\n|$)/g;
   let m;
-  while ((m = re.exec(prompt))) map.set(Number(m[1]), m[2].trim());
+  // The soundscape line also says "at [Shot 1]": the shot's own paragraph comes first and is the one kept.
+  while ((m = re.exec(prompt))) if (!map.has(Number(m[1]))) map.set(Number(m[1]), m[2].trim());
   return map;
 }
 
@@ -4215,7 +4413,7 @@ export function seedStoryboard(project, episode) {
   });
   return {
     ...episode,
-    storyboard: { plan: segmentPlan(project, episode), seedScenes, visualPlans, segments: [] },
+    storyboard: { plan: { ...segmentPlan(project, episode), foregroundLevel: paramsOf(project).foregroundLevel }, seedScenes, visualPlans, segments: [] },
   };
 }
 
@@ -4503,7 +4701,17 @@ export function promptSkeleton(project, episode, segmentId) {
   const clipMusic = params.audioTrack === 'post' ? '' : musicOf(sound).intent;
   // Who else is on screen while `speaker` has a line: the H3 idiom keeps the lip-sync off them.
   // In keyframes mode the @imageN labels are frames, so a person is named by identity instead.
-  const othersOnScreen = (c, speaker) => (c.characters || []).filter((id) => id !== speaker).map((id) => (params.references === 'sheets' && sheetLabels.get(id) ? `the person in ${sheetLabels.get(id)}` : identityOf(characterById(project, id))));
+  const framingLabels = characterLabels(allRefs);
+  const whoOf = (id) => framingLabels.get(id) || identityOf(characterById(project, id));
+  const framingLang = videoModel(params).promptLang === 'zh' ? 'zh' : 'en';
+  const idleOf = (c) => (params.references === 'sheets' ? idleSentence(c, whoOf, framingLang) : '');
+  const framingOf = (c) => (params.references === 'sheets' ? shotFraming(c, seg, whoOf, framingLang) : '');
+  const sidesOf = () => {
+    const axis = isObject(seg.axis) ? seg.axis : null;
+    if (params.references !== 'sheets' || !axis?.screenLeft || !axis?.screenRight || cuts.some((c) => c.axisSide === 'cross')) return [];
+    return [sidesLine(axis, whoOf, framingLang)];
+  };
+  const othersOnScreen = (c, speaker) => (c.characters || []).filter((id) => id !== speaker && id !== c.ots).map((id) => (params.references === 'sheets' && sheetLabels.get(id) ? `the person in ${sheetLabels.get(id)}` : identityOf(characterById(project, id))));
   let video;
   if (mode.family === 'h3') {
     const sheets = params.references === 'sheets';
@@ -4519,14 +4727,14 @@ export function promptSkeleton(project, episode, segmentId) {
       // In sheets mode the cut's own `frame` goes into the prompt and already carries the lens, the
       // light and the foreground (gated there), so only the shot size and camera move are added.
       const body = sheets
-        ? `${c.frame || '…'} ${SIZES[c.size] || c.size}, ${c.camera}.`
+        ? `${framingOf(c)}${c.frame || '…'} ${SIZES[c.size] || c.size}, ${c.camera}.`
         : `… anchor on @image${k + 1} · ${SIZES[c.size] || c.size}, ${c.camera}, ${cameraPhrase(c, params)}. ${lightPhrase(c)}.${foregroundPhrase(c)}`;
-      return `${head}${body} ${motionSentence(c)} ${cameraClause(c)} ${d}${lips}`.replace(/\s+/g, ' ').trim();
+      return `${head}${body} ${motionSentence(c)} ${idleOf(c)}${cameraClause(c)} ${d}${lips}`.replace(/\s+/g, ' ').trim();
     });
     // Keyframes are aligned by the alignment line; the voices are named either way.
     const voiceLegend = allRefs.filter((r) => r.kind !== 'image').map((r) => `${r.label} is ${r.use}.`);
     const lead = sheets
-      ? allRefs.map((r) => `${r.label} is ${r.use}.`)
+      ? [...allRefs.map((r) => `${r.label} is ${r.use}.`), ...sidesOf()]
       : [h3AlignmentLine(cuts), ...voiceLegend];
     const look = sheets ? [`Look: ${lookOf()}.`, ''] : [];
     const soundscape = [sound.ambience || '…', ...cuts.map((c, k) => (sfxOf(k) ? `at [Shot ${k + 1}] ${sfxOf(k)}` : '')).filter(Boolean)].join('; ');
@@ -4537,18 +4745,18 @@ export function promptSkeleton(project, episode, segmentId) {
       // Wan's prompt is Chinese: the lens and the light direction translate, the note and the
       // foreground are the author's English prose, so they are left as blanks to write in Chinese.
       const shot = `${cameraPhrase(c, params, 'zh')}。${LIGHT_DIRECTIONS_ZH[c.light?.direction] || '…'}，…。前景：${c.foreground ? '…（虚化）' : '无'}。`;
-      return [`${wanShotHeader(cuts, k)}…${shot}${motionSentence(c, 'zh')}${cameraClause(c, 'zh')}`, ...talk].join('\n');
+      return [`${wanShotHeader(cuts, k)}${framingOf(c)}…${shot}${motionSentence(c, 'zh')}${idleOf(c)}${cameraClause(c, 'zh')}`, ...talk].join('\n');
     });
     const sfxAll = cuts.map((c, k) => (sfxOf(k) ? `镜头${k + 1}：${sfxOf(k)}` : '')).filter(Boolean).join('；');
     video = [
-      params.references === 'sheets' ? wanSheetLegendLine(allRefs) : wanLegendLine(cuts, allRefs), '',
+      params.references === 'sheets' ? wanSheetLegendLine(allRefs) : wanLegendLine(cuts, allRefs), ...sidesOf(), '',
       ...blocks.flatMap((b) => [b, '']),
       ...(cine && params.references === 'sheets' ? [`画面：${cine.videoPhraseZh}${params.lookPhraseZh ? `，${params.lookPhraseZh}` : ''}。`, ''] : []),
       ...(grammarLines(seg, params, 'zh').length ? [...grammarLines(seg, params, 'zh'), ''] : []),
       `音频：对白为${accent || '…'}，环境音${sound.ambience || '…'}${sfxAll ? `；${sfxAll}` : ''}${clipMusic ? `；配乐：${clipMusic}` : params.audioTrack === 'post' ? '；无配乐' : ''}。${params.subtitles ? '' : `${NO_SUBTITLES.zh}。`}`,
     ].join('\n');
   } else if (params.references === 'sheets') {
-    const legend = allRefs.map((r) => `${r.label} is ${r.use}.`);
+    const legend = [...allRefs.map((r) => `${r.label} is ${r.use}.`), ...sidesOf()];
     const shots = cuts.map((c, k) => {
       const talk = dialogue[k].map((l) => {
         const base = `${l.speakerRef}${l.direction ? `, ${l.direction},` : ''} says: ${l.line}`;
@@ -4559,7 +4767,7 @@ export function promptSkeleton(project, episode, segmentId) {
         return `${base} while ${others.join(' and ')} ${others.length > 1 ? 'do' : 'does'} not speak, ${LIPS_CLOSED}`;
       }).join(' ');
       // The frame already carries the lens, the light and the foreground — do not repeat them.
-      return `Shot ${k + 1} (${starts[k].toFixed(1)}–${(starts[k] + Number(c.seconds)).toFixed(1)} s, ${SIZES[c.size] || c.size}, ${c.camera}): ${c.frame || '…'} ${motionSentence(c)} ${cameraClause(c)} ${talk}`.replace(/\s+/g, ' ').trim();
+      return `Shot ${k + 1} (${starts[k].toFixed(1)}–${(starts[k] + Number(c.seconds)).toFixed(1)} s, ${SIZES[c.size] || c.size}, ${c.camera}): ${framingOf(c)}${c.frame || '…'} ${motionSentence(c)} ${idleOf(c)}${cameraClause(c)} ${talk}`.replace(/\s+/g, ' ').trim();
     });
     const sfxAll = cuts.map((c, k) => (sfxOf(k) ? `shot ${k + 1}: ${sfxOf(k)}` : '')).filter(Boolean).join('; ');
     video = [...legend, '', ...shots, '', ...actionLine, `Look: ${lookOf()}. Maintain continuity in character identities, clothing, prop ownership, scene layout and the camera axis across every shot.`, `Sound: ${sound.ambience || '…'}${sfxAll ? `; ${sfxAll}` : ''}.${accent && dialogue.flat().length ? ` All dialogue in ${accent}.` : ''}${clipMusic ? ` Music: ${clipMusic}.` : ' No music.'}${params.subtitles ? '' : ` ${NO_SUBTITLES.en[0].toUpperCase()}${NO_SUBTITLES.en.slice(1)}.`}`].join('\n');
@@ -5098,6 +5306,7 @@ export function initProject(opts) {
       lookPhrase: opts.look || DEFAULT_PARAMS.lookPhrase,
       style: opts.style || DEFAULT_PARAMS.style,
       imagePromptLang: opts.imageLang || DEFAULT_PARAMS.imagePromptLang,
+      ...(opts.foreground ? { foregroundLevel: opts.foreground } : {}),
       // Picked from the genre unless named; `--cinematography none` opts out.
       cinematography: cine,
       // Named, or read from the genre only when it names an action style outright.
@@ -5253,7 +5462,7 @@ function main(argv) {
       adapt: flag(rest, '--adapt'), ratio: flag(rest, '--ratio'), video: flag(rest, '--video'), style: flag(rest, '--style'), lang: flag(rest, '--lang'),
       resolution: flag(rest, '--resolution'), accent: flag(rest, '--accent'),
       references: flag(rest, '--references'), duration: flag(rest, '--duration'), look: flag(rest, '--look'),
-      register: flag(rest, '--register'), imageLang: flag(rest, '--image-lang'),
+      register: flag(rest, '--register'), imageLang: flag(rest, '--image-lang'), foreground: flag(rest, '--foreground'),
       cinematography: flag(rest, '--cinematography'), action: flag(rest, '--action'), violence: flag(rest, '--violence'), grammar: flag(rest, '--grammar'), comedy: flag(rest, '--comedy'), composition: flag(rest, '--composition'), story: flag(rest, '--story'), market: flag(rest, '--market'), format: flag(rest, '--format'),
       source: flag(rest, '--source'), sourcePath: flag(rest, '--source-path'),
     });