@wji.ai/cli 0.8.1 → 0.8.3

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

@@ -19,6 +19,8 @@
 //            [--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
 //   seed     <project> script --ep N [--force]        episodes/E0N.json skeleton from the outline
@@ -26,19 +28,20 @@
 //   render   <project> outline | guideline | character C01 | scene S01 | prop P01 | script --ep N | dialogue --ep N | segment E01-01
 //   prompt   <project> segment E01-01                 derived video-prompt skeleton + keyframe reference plan
 //   prompt   <project> voice C01                       the acted sample text for the voice node
+//   prompt   <project> image C01|S01|P01 [--asset headshot|sheet|lighting:<state>|state:<state>] [--json]
+//                                                      the image node's prompt, in params.imagePromptLang (+ negative, ratio, reference)
 //   prompt   <project> audio E01-01 [--full]          the segment's Seed Audio soundtrack prompt (timecoded ambience / sfx / music, + lines with --full)
 //   prompt   <project> score E01 [--fps 24]           the episode's spotting sheet for the post soundtrack (audioTrack post): planned
 //                                                      timecodes of scenes, lines, music cues and post sfx, and the ≤120 s Seed Audio sections
-//   dashboard <project> [--output dashboard.html] [--assets <dir>]
-//                                                      static production dashboard for the whole project
+//   dashboard <project> [--output dashboard.html] [--force]
+//                                                      copy the static dashboard next to the project; it loads project.json
 //   manifest <project> [--stage …] [--ep N]           unbound WJI objects, in execution order
 //   bind     <project> [--ep N] <path> <value>        write a WJI id back (path segments may be entity ids)
 //   slug     <name>
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { renderDashboard } from './short-drama-dashboard.mjs';
 
 // ── constants ───────────────────────────────────────────────────────────────
 
@@ -88,6 +91,9 @@ export const DEFAULT_PARAMS = Object.freeze({
   format: 'short',
   // Where it is released (MARKETS): mainland holds the supernatural to a rational explanation.
   market: 'mainland',
+  // The language of the character / scene / prop image prompts (sheets, headshots, lighting and
+  // prop states): `en`, or `zh` when the image model takes Chinese and the crew wants to read them.
+  imagePromptLang: 'en',
   minCutSeconds: 2,
   maxCutSeconds: 5,
   maxOnScreen: 3,
@@ -109,6 +115,8 @@ export const DEFAULT_PARAMS = Object.freeze({
   audioTrack: 'post',
   // Frame rate the post spotting sheet writes SMPTE timecode at (conform it to the edit's real fps).
   scoreFps: 24,
+  // Scene-boundary contrast: last K cuts of scene N vs first K of scene N+1 (gate boundary-contrast).
+  boundaryContrastCuts: 2,
   thresholds: { maxLeads: 5, maxSupport: 10, maxFunctional: 10, maxBeatGap: 3, maxProps: 8 },
 });
 
@@ -192,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. */
@@ -204,6 +234,7 @@ export const DURATION_MODES = ['fixed', 'auto'];
  * move carry over instead of being re-invented per clip. `none` leaves the sheets to do that alone.
  */
 export const VIDEO_REFERENCE_MODES = ['none', 'previous'];
+export const IMAGE_PROMPT_LANGS = ['en', 'zh'];
 
 // ── screenplay craft (from the w-short-drama-editor / character-creator / dialogue-editor method) ──
 
@@ -286,6 +317,7 @@ export const NO_SUBTITLES = { en: 'no subtitles, no captions, no on-screen dialo
 export const LIPS_CLOSED = 'lips remain completely closed';
 export const WARNINGS = ['雨戏', '肢体接触', '人群', '手部特写'];
 export const PROP_SCALES = { handheld: 'handheld scale', tabletop: 'tabletop scale', furniture: 'furniture scale' };
+export const PROP_SCALES_ZH = { handheld: '手持尺寸', tabletop: '桌面尺寸', furniture: '大件尺寸' };
 export const SIZES = {
   'extreme-wide': 'extreme wide shot',
   wide: 'wide shot',
@@ -404,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();
@@ -426,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.
@@ -472,6 +569,10 @@ export const STYLE_PRESETS = {
     negativeMustNot: ['photorealistic', '3d render'],
     negativeMust: [],
     tags: ['semi-realistic', 'painterly', 'cinematic'],
+    renderZh: '半写实角色插画，绘画质感，笔触柔和融合并带可见的笔刷肌理，解剖结构扎实',
+    framePhraseZh: '电影剧照',
+    negativeMustNotZh: ['照片级', '真人', '3d渲染'],
+    negativeMustZh: [],
   },
   photoreal: {
     label: 'photographic live-action',
@@ -481,6 +582,10 @@ export const STYLE_PRESETS = {
     negativeMustNot: ['photorealistic', 'film grain', 'skin texture'],
     negativeMust: ['illustration', 'anime', 'cartoon'],
     tags: ['photoreal', 'live action', 'cinematic'],
+    renderZh: '真人实拍参考摄影，皮肤可见毛孔与细绒毛，布料有真实织纹与磨损，中性电影调色',
+    framePhraseZh: '照片级写实电影剧照',
+    negativeMustNotZh: ['照片级', '胶片颗粒', '皮肤纹理'],
+    negativeMustZh: ['插画', '动漫', '卡通'],
   },
   soft3d: {
     label: 'soft clay-toy 3D animation',
@@ -490,6 +595,10 @@ export const STYLE_PRESETS = {
     negativeMustNot: ['3d render', 'cgi', 'stylized', 'clay', 'matte', 'toy', 'simplified'],
     negativeMust: ['photorealistic'],
     tags: ['3d animation', 'clay render', 'soft toy style', 'kids tv'],
+    renderZh: '柔和哑光的黏土玩具风格三维渲染，表面光滑无毛孔，发型是一整块圆润的造型，五官极简，四肢圆胖，大头身比，柔和全局光',
+    framePhraseZh: '黏土动画电影剧照',
+    negativeMustNotZh: ['3d渲染', 'cg', '风格化', '黏土', '哑光', '玩具', '简化'],
+    negativeMustZh: ['照片级'],
   },
   disney3d: {
     label: 'Disney/Pixar-style 3D animation',
@@ -499,6 +608,10 @@ export const STYLE_PRESETS = {
     negativeMustNot: ['3d render', 'cgi', 'stylized', 'cartoon'],
     negativeMust: ['photorealistic'],
     tags: ['3d animation', 'disney pixar style', 'family', 'cinematic'],
+    renderZh: '迪士尼与皮克斯长片风格的三维动画，圆润讨喜的造型语言，大而传神的眼睛，次表面散射皮肤，温暖的电影主光与轮廓光',
+    framePhraseZh: '三维动画电影剧照',
+    negativeMustNotZh: ['3d渲染', 'cg', '风格化', '卡通'],
+    negativeMustZh: ['照片级'],
   },
   ghibli: {
     label: 'hand-painted anime',
@@ -508,9 +621,67 @@ export const STYLE_PRESETS = {
     negativeMustNot: [],
     negativeMust: ['photorealistic'],
     tags: ['anime', 'cel shading', 'hand-painted'],
+    renderZh: '日本经典动画电影风格的手绘赛璐璐动画，干净线稿，平涂色彩配柔和水彩背景',
+    framePhraseZh: '手绘动画电影剧照',
+    negativeMustNotZh: [],
+    negativeMustZh: ['照片级'],
   },
 };
 
+// Traditional → simplified for the characters the Chinese image-prompt rules look for, so a crew
+// writing 繁體 (真人實拍參考攝影, 純白背景, 東亞) passes the same checks as one writing 简体.
+const ZH_T = '實參攝寫繪畫質膚絨織紋損調級動風簡賽顆東亞漢華國韓歐維紀時當現戰無場沒純圖臉須髮還間構變燈樣與體條機啞寬細電影剛劇個們來這為後從歲種頭於將兩裡進遠擊衛萬處滿點眾邊師張長門開關問員陽陰雲書幾話鐵號專業輕壓環題顏鏡區鬥創標誌劃會戲網際聲氣態網雜淺濃暗餘濕黃綠藍紅寫臨團鄉樓廳櫃燈廢廠館護殘獨帶膠鮮爾歷羅陸屬樂傳麗貴壯結線淨';
+const ZH_S = '实参摄写绘画质肤绒织纹损调级动风简赛颗东亚汉华国韩欧维纪时当现战无场没纯图脸须发还间构变灯样与体条机哑宽细电影刚剧个们来这为后从岁种头于将两里进远击卫万处满点众边师张长门开关问员阳阴云书几话铁号专业轻压环题颜镜区斗创标志划会戏网际声气态网杂浅浓暗余湿黄绿蓝红写临团乡楼厅柜灯废厂馆护残独带胶鲜尔历罗陆属乐传丽贵壮结线净';
+const ZH_FOLD = new Map([...ZH_T].map((ch, i) => [ch, ZH_S[i]]));
+const ZH_HANT = new Map([...ZH_S].map((ch, i) => [ch, [...ZH_T][i]]));
+/** True when the text is written in 繁體 (it changes under folding). */
+export function isHant(text) {
+  const t = String(text ?? '');
+  return [...t].some((ch) => ZH_FOLD.has(ch));
+}
+/** Simplified → traditional for the engine's own fixed phrases (not a general converter). */
+export function hantPhrase(text) {
+  return [...String(text ?? '').replace(/干净/g, '乾淨')].map((ch) => ZH_HANT.get(ch) || ch).join('');
+}
+export function foldZh(text) {
+  return [...String(text ?? '')].map((ch) => ZH_FOLD.get(ch) || ch).join('').toLowerCase();
+}
+
+const ZH_ETHNICITY_RE = /(东亚|亚洲|亚裔|汉族|华人|中国|日本|韩国|朝鲜|欧洲|白人|黑人|非洲|拉丁|中东|阿拉伯|南亚|东南亚|混血|蒙古|藏族|维吾尔|鲜卑|匈奴|胡人|西域|印度)/;
+// whole era words only — a bare 明 / 清 / 元 would match 明亮 / 清晰 / 元素
+const ZH_ERA_RE = /(年代|世纪|时期|当代|现代|古代|近代|公元|未来|中世纪|维多利亚|民国|春秋|战国|先秦|秦朝|秦代|秦末|西汉|东汉|汉朝|汉代|汉初|汉末|三国|西晋|东晋|晋朝|南北朝|北魏|北齐|北周|南朝|隋朝|隋代|隋末|唐朝|唐代|初唐|盛唐|晚唐|五代|宋朝|宋代|北宋|南宋|元朝|元代|明朝|明代|明末|清朝|清代|晚清)/;
+
+// the checked part of a Chinese render phrase: up to its first comma, at most 8 characters
+const renderKeyZh = (preset) => preset.renderZh.split('，')[0].slice(0, 8);
+
+/** The rules the image-prompt gates apply, in the project's image-prompt language. */
+export function imagePromptKit(params) {
+  const zh = params.imagePromptLang === 'zh';
+  const preset = STYLE_PRESETS[params.style] || STYLE_PRESETS.realistic;
+  const has = (text, word) => (zh ? foldZh(text).includes(foldZh(word)) : String(text ?? '').toLowerCase().includes(String(word).toLowerCase()));
+  return {
+    zh,
+    label: zh ? 'Chinese' : 'English',
+    inLang: (text) => (zh ? CJK_RE.test(String(text ?? '')) : isEnglish(text)),
+    ethnicity: (text) => (zh ? ZH_ETHNICITY_RE.test(foldZh(text)) : ETHNICITY_RE.test(String(text ?? ''))),
+    era: (text) => (zh ? ZH_ERA_RE.test(foldZh(text)) : ERA_RE.test(String(text ?? ''))),
+    sheetRatio: (text) => /16\s*[:：]\s*9/.test(String(text ?? '')),
+    // the style's render phrase — its first 30 characters in English, up to 8 before the first comma in Chinese
+    render: zh ? preset.renderZh : preset.render,
+    renderKey: zh ? renderKeyZh(preset) : preset.render.slice(0, 30),
+    hasRender: (text) => has(text, zh ? renderKeyZh(preset) : preset.render.slice(0, 30)),
+    framePhrase: zh ? preset.framePhraseZh : preset.framePhrase,
+    negativeMust: zh ? preset.negativeMustZh : preset.negativeMust,
+    negativeMustNot: zh ? preset.negativeMustNotZh : preset.negativeMustNot,
+    has,
+    bansPeople: (neg) => (zh ? /人/.test(foldZh(neg)) : /(people|person|figure|human|man|woman|crowd)/.test(String(neg).toLowerCase())),
+    bansHands: (neg) => (zh ? /手/.test(foldZh(neg)) : /(hand|finger)/.test(String(neg).toLowerCase())),
+    saysEmpty: (text) => (zh ? /(空场景|空无一人|没有人|没有任何人|无人|空景)/.test(foldZh(text)) : /(no people|empty|unpopulated|nobody|no one|no human)/i.test(String(text))),
+    whiteBackground: (text) => (zh ? /(纯白背景|白色背景|白底)/.test(foldZh(text)) : /white background/i.test(String(text))),
+    scalePhrase: (scale) => (zh ? PROP_SCALES_ZH[scale] : PROP_SCALES[scale]),
+  };
+}
+
 /**
  * The drama's lighting and composition, orthogonal to the render style (`params.style`). Each
  * preset has a guide in reference/cinematography-<key>.md; the gates read only the fields below.
@@ -531,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'],
@@ -547,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'],
@@ -602,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',
@@ -1138,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;
@@ -1167,7 +1340,7 @@ export function langTag(lang) {
 export function forbiddenNames(project) {
   const out = [];
   for (const c of project.characters || []) {
-    for (const n of [c.name, ...(c.aliases || [])]) if (n && String(n).trim().length >= 2) out.push(String(n).trim());
+    for (const n of [c.name, ...(c.aliases || []), c.disguise?.name]) if (n && String(n).trim().length >= 2) out.push(String(n).trim());
   }
   return uniq(out);
 }
@@ -1178,9 +1351,18 @@ export function containsName(text, name) {
   return new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'i').test(text);
 }
 
+function promptTokens(text) {
+  const t = foldZh(text);
+  const words = t.match(/[a-z0-9']+/g) || [];
+  // Chinese has no spaces: compare character bigrams inside each run of CJK characters.
+  const bigrams = [];
+  for (const run of t.match(/[\u3400-\u9fff]+/g) || []) for (let i = 0; i + 1 < run.length; i++) bigrams.push(run.slice(i, i + 2));
+  return new Set([...words, ...bigrams]);
+}
+
 export function jaccard(a, b) {
-  const wa = new Set(String(a).toLowerCase().match(/[a-z0-9']+/g) || []);
-  const wb = new Set(String(b).toLowerCase().match(/[a-z0-9']+/g) || []);
+  const wa = promptTokens(a);
+  const wb = promptTokens(b);
   if (wa.size < 8 || wb.size < 8) return 0;
   let inter = 0;
   for (const w of wa) if (wb.has(w)) inter += 1;
@@ -1201,6 +1383,18 @@ function sceneById(project, id) {
 function characterById(project, id) {
   return (project.characters || []).find((c) => c.id === id);
 }
+/**
+ * The name the drama's own documents use for a character in episode `ep`. A character with
+ * `disguise: {name, revealEpisode}` goes by the disguise name before the reveal, so an episode's
+ * script, polish sheet and segment sheet never spoil who they are. Without `ep` it is the real name.
+ */
+export function displayName(project, id, ep) {
+  const c = characterById(project, id);
+  if (!c) return id;
+  const d = c.disguise;
+  if (isObject(d) && String(d.name || '').trim() && ep != null && Number(ep) < Number(d.revealEpisode)) return String(d.name).trim();
+  return c.name || id;
+}
 function propById(project, id) {
   return (project.props || []).find((p) => p.id === id);
 }
@@ -1515,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(' / ')}`);
@@ -1538,13 +1733,14 @@ export const GATES = [
     else {
       const [lo, hi] = FORMATS[params.format].minutes;
       const m = Number(params.minutesPerEpisode);
-      if (m && (m < lo || m > hi)) out.push(`params.minutesPerEpisode ${m} is outside the ${params.format} range ${lo}–${hi} minutes — pick the format that fits (short 1–3, medium 4–15, movie parts 3–8)`);
+      if (m && (m < lo || m > hi)) out.push(`params.minutesPerEpisode ${m} is outside the ${params.format} range ${lo}\u2013${hi} minutes \u2014 pick the format that fits (short 1\u20133, medium 4\u201315, movie parts 3\u20138)`);
     }
     if (!MARKETS.includes(params.market)) out.push(`params.market must be one of ${MARKETS.join(' / ')}`);
     for (const k of asList(params.story)) if (!Object.hasOwn(STORY_GENRES, k)) out.push(`params.story "${k}" is not one of ${Object.keys(STORY_GENRES).join(' / ')}`);
     if (!Object.hasOwn(COMPOSITION_STYLES, params.composition)) out.push(`params.composition must be one of ${Object.keys(COMPOSITION_STYLES).join(' / ')}`);
     if (!Object.hasOwn(COMEDY_STYLES, params.comedy)) out.push(`params.comedy must be one of ${Object.keys(COMEDY_STYLES).join(' / ')}`);
     if (!Object.hasOwn(CINEMATOGRAPHY_PRESETS, params.cinematography)) out.push(`params.cinematography must be one of ${Object.keys(CINEMATOGRAPHY_PRESETS).join(' / ')}`);
+    if (!IMAGE_PROMPT_LANGS.includes(params.imagePromptLang)) out.push(`params.imagePromptLang must be one of ${IMAGE_PROMPT_LANGS.join(' / ')} (the language of the character / scene / prop image prompts)`);
     if (!/^\d+:\d+$/.test(String(params.ratio))) out.push('params.ratio must look like 9:16');
     if (!project.title) out.push('title is required');
     return out;
@@ -1577,6 +1773,13 @@ export const GATES = [
       if (!c.role) out.push(`${c.id}: role is required`);
       if (['lead', 'support'].includes(c.tier) && !c.arc) out.push(`${c.id}: ${c.tier} characters need an arc`);
       if (!Array.isArray(c.from) || !c.from.length) out.push(`${c.id}: from[] must record where the character comes from (or ["原创"])`);
+      if (c.disguise !== undefined) {
+        const d = isObject(c.disguise) ? c.disguise : {};
+        const rev = Number(d.revealEpisode);
+        if (!String(d.name || '').trim()) out.push(`${c.id}: disguise.name is empty — the name this character goes by before the reveal`);
+        else if (String(d.name).trim() === c.name) out.push(`${c.id}: disguise.name equals the real name`);
+        if (!(Number.isInteger(rev) && rev >= 2 && rev <= Number(params.episodes))) out.push(`${c.id}: disguise.revealEpisode must be an episode in 2–${params.episodes} (the first episode that uses the real name)`);
+      }
     }
     if (count.lead < 1 || count.lead > t.maxLeads) out.push(`lead characters: ${count.lead}, must be 1–${t.maxLeads}`);
     if (count.support > t.maxSupport) out.push(`support characters: ${count.support}, max ${t.maxSupport}`);
@@ -1703,15 +1906,20 @@ export const GATES = [
     const phases = project.outline?.structure;
     const n = Number(params.episodes) || 0;
     if (!Array.isArray(phases) || !phases.length) return ['outline.structure is missing — three phases (golden / escalation / climax) with episode ranges'];
-    const expect = n >= 3 ? PHASES : PHASES.filter((p) => p !== 'escalation');
+    // Single-episode dramas: golden + climax both cover ep 1 (retention and payoff in the same 集).
+    const expect = n === 1 ? ['golden', 'climax'] : n >= 3 ? PHASES : PHASES.filter((p) => p !== 'escalation');
     const got = phases.map((p) => p.phase);
     if (got.join(',') !== expect.join(',')) out.push(`outline.structure phases must be ${expect.join(' → ')} in that order (got ${got.join(', ') || 'none'})`);
     let cursor = 1;
     phases.forEach((p, i) => {
       const [a, b] = Array.isArray(p.episodes) ? p.episodes.map(Number) : [NaN, NaN];
       if (!(a >= 1 && b >= a && b <= n)) { out.push(`outline.structure[${i}] (${p.phase}): episodes must be [from, to] inside 1–${n}`); return; }
-      if (a !== cursor) out.push(`outline.structure[${i}] (${p.phase}) starts at ${a}, expected ${cursor} — the phases must tile the episodes without gaps`);
-      cursor = b + 1;
+      if (n === 1) {
+        if (!(a === 1 && b === 1)) out.push(`outline.structure[${i}] (${p.phase}): for a 1-episode drama both phases must be [1, 1]`);
+      } else {
+        if (a !== cursor) out.push(`outline.structure[${i}] (${p.phase}) starts at ${a}, expected ${cursor} — the phases must tile the episodes without gaps`);
+        cursor = b + 1;
+      }
       for (const key of ['task', 'satisfactionPlan', 'hookPlan']) if (!String(p[key] || '').trim()) out.push(`outline.structure[${i}] (${p.phase}): ${key} is empty`);
       if (p.phase === 'golden') {
         // 黄金窗口 is the first ~20 % — and never less than the first three episodes of a long run.
@@ -1720,7 +1928,7 @@ export const GATES = [
         if (n >= 6 && b < 3) out.push(`golden window ends at episode ${b}; with ${n} episodes the first three episodes are the retention window`);
       }
     });
-    if (phases.length && cursor - 1 !== n && !out.some((m) => m.includes('inside 1'))) out.push(`outline.structure ends at episode ${cursor - 1}, the drama has ${n}`);
+    if (n !== 1 && phases.length && cursor - 1 !== n && !out.some((m) => m.includes('inside 1'))) out.push(`outline.structure ends at episode ${cursor - 1}, the drama has ${n}`);
     return out;
   }),
   gate('guideline', 'outline', '创作指引: tone, dialogue, visuals, limits, ≥3 forbidden, 3–5 priorities', ({ project }) => {
@@ -1802,26 +2010,26 @@ export const GATES = [
     }
     return out;
   }),
-  gate('char-prompts', 'characters', 'image prompts English, no names, ethnicity + era stated', ({ project, params }) => {
+  gate('char-prompts', 'characters', 'image prompts in params.imagePromptLang (English by default), no names, ethnicity + era stated', ({ project, params }) => {
     const out = [];
     const names = forbiddenNames(project);
-    const preset = STYLE_PRESETS[params.style] || STYLE_PRESETS.realistic;
+    const kit = imagePromptKit(params);
     for (const c of project.characters || []) {
       const img = c.image || {};
       for (const key of ['prompt', 'negativePrompt', 'sheet']) {
         const text = String(img[key] || '');
         if (!text.trim()) { out.push(`${c.id}: image.${key} is empty`); continue; }
-        if (!isEnglish(text)) out.push(`${c.id}: image.${key} must be English`);
+        if (!kit.inLang(text)) out.push(`${c.id}: image.${key} must be ${kit.label} (params.imagePromptLang = ${params.imagePromptLang})`);
         for (const n of names) if (containsName(text, n)) out.push(`${c.id}: image.${key} contains the name "${n}" — describe, don't name`);
       }
       if (!Array.isArray(img.tags) || !img.tags.length) out.push(`${c.id}: image.tags is empty`);
-      if (img.prompt && !ETHNICITY_RE.test(img.prompt)) out.push(`${c.id}: image.prompt must state ethnicity / facial heritage`);
-      if (img.prompt && !ERA_RE.test(img.prompt)) out.push(`${c.id}: image.prompt must state the era`);
-      if (img.sheet && !/16:9/.test(img.sheet)) out.push(`${c.id}: image.sheet must specify the 16:9 canvas`);
-      if (img.sheet && !img.sheet.toLowerCase().includes(preset.render.slice(0, 30).toLowerCase())) out.push(`${c.id}: image.sheet must contain the ${params.style} render phrase (see STYLE_PRESETS)`);
-      const neg = String(img.negativePrompt || '').toLowerCase();
-      for (const word of preset.negativeMustNot) if (neg.includes(word)) out.push(`${c.id}: style ${params.style} must not ban "${word}" in the negative prompt`);
-      for (const word of preset.negativeMust) if (!neg.includes(word)) out.push(`${c.id}: style ${params.style} must ban "${word}" in the negative prompt`);
+      if (img.prompt && !kit.ethnicity(img.prompt)) out.push(`${c.id}: image.prompt must state ethnicity / facial heritage${kit.zh ? '（如 东亚、汉族）' : ''}`);
+      if (img.prompt && !kit.era(img.prompt)) out.push(`${c.id}: image.prompt must state the era${kit.zh ? '（如 当代、秦末汉初、唐代）' : ''}`);
+      if (img.sheet && !kit.sheetRatio(img.sheet)) out.push(`${c.id}: image.sheet must specify the 16:9 canvas`);
+      if (img.sheet && !kit.hasRender(img.sheet)) out.push(`${c.id}: image.sheet must contain the ${params.style} render phrase "${kit.renderKey}…" (see STYLE_PRESETS${kit.zh ? '.renderZh' : ''})`);
+      const neg = String(img.negativePrompt || '');
+      for (const word of kit.negativeMustNot) if (kit.has(neg, word)) out.push(`${c.id}: style ${params.style} must not ban "${word}" in the negative prompt`);
+      for (const word of kit.negativeMust) if (!kit.has(neg, word)) out.push(`${c.id}: style ${params.style} must ban "${word}" in the negative prompt`);
     }
     return out;
   }),
@@ -1829,7 +2037,13 @@ export const GATES = [
     const out = [];
     for (const c of project.characters || []) {
       const v = c.voice || {};
-      for (const key of ['timbre', 'pitch', 'pace', 'accent', 'emotion']) if (!String(v[key] || '').trim()) out.push(`${c.id}: voice.${key} is empty`);
+      for (const key of ['timbre', 'pitch', 'pace', 'accent', 'emotion']) {
+        const text = String(v[key] || '');
+        if (!text.trim()) { out.push(`${c.id}: voice.${key} is empty`); continue; }
+        // pasted verbatim beside the character's first line in every Chinese segment prompt, and into the voice-sample prompt
+        const nm = forbiddenNames(project).find((n) => containsName(text, n));
+        if (nm) out.push(`${c.id}: voice.${key} contains the name "${nm}" — it is pasted into prompts; say 对她 / 对他 or describe the person`);
+      }
       if (params.voiceSamples !== false) {
         const sample = v.sample || {};
         const line = String(sample.line || '').trim();
@@ -1842,6 +2056,10 @@ export const GATES = [
           if (QUOTE_RE.test(line)) out.push(`${c.id}: voice.sample.line must not carry quote marks — the engine reads them`);
         }
         if (!direction) out.push(`${c.id}: voice.sample.direction is empty — say how it is acted; it becomes the parenthetical the model obeys`);
+        else {
+          const nm = forbiddenNames(project).find((n) => containsName(direction, n));
+          if (nm) out.push(`${c.id}: voice.sample.direction contains the name "${nm}" — it goes into the voice-sample prompt`);
+        }
       }
       // The compact form the video prompt puts beside every line this character speaks.
       const vd = String(v.videoDirection || '').trim();
@@ -1858,6 +2076,8 @@ export const GATES = [
         if (!isEnglish(prompt)) out.push(`${c.id}: voice.prompt must be English`);
         if (prompt.length > 400) out.push(`${c.id}: voice.prompt is ${prompt.length} chars, max 400 — write a parameter string, not prose`);
         if (QUOTED_LINE_RE.test(prompt)) out.push(`${c.id}: voice.prompt contains a quoted line — engines read it aloud`);
+        const nm = forbiddenNames(project).find((n) => containsName(prompt, n));
+        if (nm) out.push(`${c.id}: voice.prompt contains the name "${nm}"`);
       }
     }
     return out;
@@ -2527,9 +2747,12 @@ export const GATES = [
     return out;
   }, { advisory: true }),
   // ── art ───────────────────────────────────────────────────────────────
-  gate('scene-design', 'art', 'scenes: intent, 3–5 anchors, ≥1 English lighting state (in the cinematography preset)', ({ project, params }) => {
+  gate('scene-design', 'art', 'scenes: intent, 3–5 anchors, ≥1 lighting state in params.imagePromptLang (in the cinematography preset)', ({ project, params }) => {
     const out = [];
-    const look = cinematographyOf(params);
+    const kit = imagePromptKit(params);
+    // The cinematography presets carry an English framePhrase only, so a Chinese
+    // image prompt (imagePromptLang zh) has nothing to match — skip the check there.
+    const look = kit.zh ? null : cinematographyOf(params);
     for (const s of project.scenes || []) {
       if (!String(s.summary || '').trim()) out.push(`${s.id}: summary (design intent) is empty`);
       const anchors = s.anchors || [];
@@ -2539,7 +2762,7 @@ export const GATES = [
       if (!lighting.length) out.push(`${s.id}: at least one lighting state is required`);
       for (const l of lighting) {
         if (!l.state || !l.prompt) out.push(`${s.id}: every lighting state needs state + prompt`);
-        else if (!isEnglish(l.prompt)) out.push(`${s.id}: lighting "${l.state}" prompt must be English`);
+        else if (!kit.inLang(l.prompt)) out.push(`${s.id}: lighting "${l.state}" prompt must be ${kit.label}`);
         else if (look && !l.prompt.toLowerCase().includes(look.framePhrase)) out.push(`${s.id}: lighting "${l.state}" prompt must contain "${look.framePhrase}" and name the practical sources that light the space (params.cinematography ${params.cinematography})`);
       }
       if (s.variantOf) {
@@ -2549,28 +2772,29 @@ export const GATES = [
     }
     return out;
   }),
-  gate('scene-prompts', 'art', 'scene prompts English, empty of people, no names, style-consistent', ({ project, params }) => {
+  gate('scene-prompts', 'art', 'scene prompts in params.imagePromptLang, empty of people, no names, style-consistent', ({ project, params }) => {
     const out = [];
     const names = forbiddenNames(project);
-    const preset = STYLE_PRESETS[params.style] || STYLE_PRESETS.realistic;
+    const kit = imagePromptKit(params);
     for (const s of project.scenes || []) {
       const img = s.image || {};
       for (const key of ['prompt', 'negativePrompt', 'sheet']) {
         const text = String(img[key] || '');
         if (!text.trim()) { out.push(`${s.id}: image.${key} is empty`); continue; }
-        if (!isEnglish(text)) out.push(`${s.id}: image.${key} must be English`);
+        if (!kit.inLang(text)) out.push(`${s.id}: image.${key} must be ${kit.label}`);
         for (const n of names) if (containsName(text, n)) out.push(`${s.id}: image.${key} contains the character name "${n}"`);
       }
-      const neg = String(img.negativePrompt || '').toLowerCase();
-      if (neg && !/(people|person|figure|human|man|woman|crowd)/.test(neg)) out.push(`${s.id}: negativePrompt must ban people — environments are a separate asset layer`);
-      if (img.prompt && !/(no people|empty|unpopulated|nobody|no one|no human)/i.test(img.prompt)) out.push(`${s.id}: image.prompt must say the scene is empty (no people)`);
-      if (img.sheet && !img.sheet.toLowerCase().includes(preset.render.slice(0, 30).toLowerCase())) out.push(`${s.id}: image.sheet must contain the ${params.style} render phrase`);
+      const neg = String(img.negativePrompt || '');
+      if (neg && !kit.bansPeople(neg)) out.push(`${s.id}: negativePrompt must ban people — environments are a separate asset layer`);
+      if (img.prompt && !kit.saysEmpty(img.prompt)) out.push(`${s.id}: image.prompt must say the scene is empty (${kit.zh ? '空场景，没有人' : 'no people'})`);
+      if (img.sheet && !kit.hasRender(img.sheet)) out.push(`${s.id}: image.sheet must contain the ${params.style} render phrase "${kit.renderKey}…"`);
     }
     return out;
   }),
-  gate('prop-design', 'art', 'props: scale phrase, 3–5 anchors, ≥1 state, white background, no hands', ({ project }) => {
+  gate('prop-design', 'art', 'props: scale phrase, 3–5 anchors, ≥1 state, white background, no hands', ({ project, params }) => {
     const out = [];
     const names = forbiddenNames(project);
+    const kit = imagePromptKit(params);
     for (const p of project.props || []) {
       if (!PROP_SCALES[p.scale]) out.push(`${p.id}: scale must be one of ${Object.keys(PROP_SCALES).join(' / ')}`);
       if (!String(p.summary || '').trim()) out.push(`${p.id}: summary (dramatic function) is empty`);
@@ -2580,24 +2804,24 @@ export const GATES = [
       if (!states.length) out.push(`${p.id}: at least one state is required`);
       for (const st of states) {
         if (!st.state || !st.prompt) out.push(`${p.id}: every state needs state + prompt`);
-        else if (!isEnglish(st.prompt)) out.push(`${p.id}: state "${st.state}" prompt must be English`);
+        else if (!kit.inLang(st.prompt)) out.push(`${p.id}: state "${st.state}" prompt must be ${kit.label}`);
       }
       for (const id of p.relatedScenes || []) if (!sceneById(project, id)) out.push(`${p.id}: relatedScenes references unknown scene ${id}`);
       const img = p.image || {};
       for (const key of ['prompt', 'negativePrompt', 'sheet']) {
         const text = String(img[key] || '');
         if (!text.trim()) { out.push(`${p.id}: image.${key} is empty`); continue; }
-        if (!isEnglish(text)) out.push(`${p.id}: image.${key} must be English`);
+        if (!kit.inLang(text)) out.push(`${p.id}: image.${key} must be ${kit.label}`);
         for (const n of names) if (containsName(text, n)) out.push(`${p.id}: image.${key} contains the character name "${n}"`);
       }
-      const phrase = PROP_SCALES[p.scale];
+      const phrase = kit.scalePhrase(p.scale);
       if (phrase) {
-        for (const key of ['prompt', 'sheet']) if (img[key] && !img[key].toLowerCase().includes(phrase)) out.push(`${p.id}: image.${key} must contain "${phrase}"`);
+        for (const key of ['prompt', 'sheet']) if (img[key] && !kit.has(img[key], phrase)) out.push(`${p.id}: image.${key} must contain "${phrase}"`);
       }
-      const neg = String(img.negativePrompt || '').toLowerCase();
-      if (neg && !/(hand|finger)/.test(neg)) out.push(`${p.id}: negativePrompt must ban hands — a hand holding the prop is the usual contamination`);
-      if (neg && !/(people|person|figure|human)/.test(neg)) out.push(`${p.id}: negativePrompt must ban people`);
-      for (const key of ['prompt', 'sheet']) if (img[key] && !/white background/i.test(img[key])) out.push(`${p.id}: image.${key} must specify a pure white background`);
+      const neg = String(img.negativePrompt || '');
+      if (neg && !kit.bansHands(neg)) out.push(`${p.id}: negativePrompt must ban hands — a hand holding the prop is the usual contamination`);
+      if (neg && !(kit.zh ? kit.bansPeople(neg) : /(people|person|figure|human)/.test(neg.toLowerCase()))) out.push(`${p.id}: negativePrompt must ban people`);
+      for (const key of ['prompt', 'sheet']) if (img[key] && !kit.whiteBackground(img[key])) out.push(`${p.id}: image.${key} must specify a pure white background${kit.zh ? '（纯白背景）' : ''}`);
     }
     return out;
   }),
@@ -2609,7 +2833,7 @@ export const GATES = [
     for (const [ep, e] of ctx.episodes) {
       if (Number(e.ep) !== Number(ep)) out.push(`E${pad2(ep)}: ep field is ${e.ep}`);
       if (!(Number(e.targetSeconds) > 0)) out.push(`E${pad2(ep)}: targetSeconds missing (run seed script)`);
-      if (!String(e.hook || '').trim()) out.push(`E${pad2(ep)}: hook is empty`);
+      if (!String(e.hook || '').trim()) out.push(`E${pad2(ep)}: hook is empty — describe the opening image (seed leaves it for you; the outline's hook is the cliff)`);
       if (!String(e.cliff || '').trim()) out.push(`E${pad2(ep)}: cliff is empty`);
       if (!Array.isArray(e.beatsClaimed)) out.push(`E${pad2(ep)}: beatsClaimed must be an array`);
       if (!Array.isArray(e.scenes) || !e.scenes.length) { out.push(`E${pad2(ep)}: scenes is empty`); continue; }
@@ -2625,9 +2849,11 @@ export const GATES = [
     }
     return out;
   }),
-  gate('beat-flow', 'script', 'beats: action ⇄ line, one kind each, no quotes in actions, speakers legal, line ≤ N chars', (ctx) => {
-    const { params } = ctx;
+  gate('beat-flow', 'script', 'beats: action ⇄ line, one kind each, no quotes in actions, speakers legal, line ≤ N chars, no names in a delivery the video prompt carries', (ctx) => {
+    const { project, params } = ctx;
     const out = [];
+    const names = forbiddenNames(project);
+    const promptLang = videoModel(params).promptLang;
     for (const [ep, e] of ctx.episodes) {
       (e.scenes || []).forEach((sc, i) => {
         const where = `E${pad2(ep)} scene ${i + 1}`;
@@ -2646,6 +2872,13 @@ export const GATES = [
             if (!String(b.line || '').trim()) out.push(`${where} beat ${k + 1}: line is empty`);
             if (nonWhitespace(b.line) > params.maxLineChars) out.push(`${where} beat ${k + 1}: line has ${nonWhitespace(b.line)} chars, max ${params.maxLineChars}`);
             if (b.speaker !== 'VO' && !(sc.characters || []).includes(b.speaker)) out.push(`${where} beat ${k + 1}: speaker ${b.speaker} is not in this scene (or VO)`);
+            // speechDirection pastes the delivery beside the line in a Chinese (wan) prompt, and an English
+            // delivery into any prompt — where a name fails the storyboard's no-names check much later.
+            const delivery = String(b.delivery || '');
+            if (delivery && beatDelivery(delivery, promptLang)) {
+              const nm = names.find((n) => containsName(delivery, n));
+              if (nm) out.push(`${where} beat ${k + 1}: delivery names "${nm}" — it goes into the video prompt beside the line; say 她 / 他 / 对方 or describe them`);
+            }
           }
         });
         if ((sc.flow || []).length && actions === 0) out.push(`${where}: no action beat — a scene of pure dialogue is a radio play`);
@@ -2958,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}`;
@@ -2990,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.
@@ -3019,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;
@@ -3095,6 +3332,75 @@ export const GATES = [
     }
     return out;
   }),
+  gate('boundary-contrast', 'storyboard', '跨场边界: last K cuts of scene N must not match first K of scene N+1 in size+angle+people (params.boundaryContrastCuts, default 2); note "match-cut" to exempt', (ctx) => {
+    const out = [];
+    const Kraw = Number(ctx.params.boundaryContrastCuts);
+    const K = Number.isFinite(Kraw) && Kraw >= 1 ? Math.min(3, Math.floor(Kraw)) : 2;
+    const isMatchCut = (c) => /match[\s-]?cut/i.test(String(c?.note || ''));
+    const signature = (c) => `${c?.size || ''}|${c?.angle || ''}|${[...(c?.characters || [])].map(String).sort().join(',')}`;
+    for (const [, e] of ctx.episodes) {
+      const segs = e.storyboard?.segments || [];
+      const byScene = new Map();
+      for (const seg of segs) {
+        const si = Number(seg.sceneIndex);
+        if (!Number.isFinite(si)) continue;
+        if (!byScene.has(si)) byScene.set(si, []);
+        byScene.get(si).push(seg);
+      }
+      const sceneIds = [...byScene.keys()].sort((a, b) => a - b);
+      for (let i = 0; i < sceneIds.length - 1; i++) {
+        const aSegs = byScene.get(sceneIds[i]);
+        const bSegs = byScene.get(sceneIds[i + 1]);
+        const lastSeg = aSegs[aSegs.length - 1];
+        const firstSeg = bSegs[0];
+        const aCuts = lastSeg.cuts || [];
+        const bCuts = firstSeg.cuts || [];
+        if (!aCuts.length || !bCuts.length) continue;
+        const tail = aCuts.slice(-K);
+        const head = bCuts.slice(0, K);
+        tail.forEach((tc, ti) => {
+          head.forEach((hc, hi) => {
+            if (isMatchCut(tc) || isMatchCut(hc)) return;
+            if (signature(tc) !== signature(hc)) return;
+            const aIdx = aCuts.length - tail.length + ti + 1;
+            out.push(`${firstSeg.id} cut ${hi + 1}: same size, angle and people as ${lastSeg.id} cut ${aIdx} across the scene ${sceneIds[i]}→${sceneIds[i + 1]} boundary — change at least one, or mark note "match-cut" if intentional`);
+          });
+        });
+      }
+    }
+    return out;
+  }),
+  gate('boundary-contrast-episode', 'storyboard', '跨集边界 (advisory): last K cuts of episode E should not match first K of E+1 in size+angle+people', (ctx) => {
+    const out = [];
+    const Kraw = Number(ctx.params.boundaryContrastCuts);
+    const K = Number.isFinite(Kraw) && Kraw >= 1 ? Math.min(3, Math.floor(Kraw)) : 2;
+    const isMatchCut = (c) => /match[\s-]?cut/i.test(String(c?.note || ''));
+    const signature = (c) => `${c?.size || ''}|${c?.angle || ''}|${[...(c?.characters || [])].map(String).sort().join(',')}`;
+    const eps = [...ctx.episodes.entries()].sort((a, b) => Number(a[0]) - Number(b[0]));
+    for (let i = 0; i < eps.length - 1; i++) {
+      const [epA, eA] = eps[i];
+      const [epB, eB] = eps[i + 1];
+      const segsA = eA.storyboard?.segments || [];
+      const segsB = eB.storyboard?.segments || [];
+      if (!segsA.length || !segsB.length) continue;
+      const lastSeg = segsA[segsA.length - 1];
+      const firstSeg = segsB[0];
+      const aCuts = lastSeg.cuts || [];
+      const bCuts = firstSeg.cuts || [];
+      if (!aCuts.length || !bCuts.length) continue;
+      const tail = aCuts.slice(-K);
+      const head = bCuts.slice(0, K);
+      tail.forEach((tc, ti) => {
+        head.forEach((hc, hi) => {
+          if (isMatchCut(tc) || isMatchCut(hc)) return;
+          if (signature(tc) !== signature(hc)) return;
+          const aIdx = aCuts.length - tail.length + ti + 1;
+          out.push(`${firstSeg.id} cut ${hi + 1}: same size, angle and people as ${lastSeg.id} cut ${aIdx} across episode E${String(epA).padStart(2, '0')}→E${String(epB).padStart(2, '0')} — change at least one for a fresher open, or mark note "match-cut" if the echo is intentional`);
+        });
+      });
+    }
+    return out;
+  }, { advisory: true }),
   gate('framing-axis', 'storyboard', '角度 / 机位高度 / 轴线: three separate fields; a two-person segment declares its axis; reverse shots face opposite ways', (ctx) => {
     const out = [];
     for (const [, e] of ctx.episodes) {
@@ -3323,12 +3629,26 @@ export const GATES = [
         }
         const texts = shotTexts(prompt, mode.family, params.references);
         const refs = segmentReferences(project, e, seg);
-        const sheetOf = params.references === 'sheets' ? new Map(refs.filter((r) => r.kind === 'image' && r.asset === 'sheet').map((r) => [r.entity, r.label])) : null;
+        const sheetOf = params.references === 'sheets'
+          ? (() => {
+              const m = new Map();
+              for (const r of refs.filter((x) => x.kind === 'image')) {
+                const who = r.faceOf || (r.asset === 'sheet' || r.asset === 'headshot' ? r.entity : null);
+                if (who && !m.has(who)) m.set(who, r.label);
+              }
+              // Prefer explicit headshot / faceOf over later body sheets
+              for (const r of refs.filter((x) => x.kind === 'image' && (x.asset === 'headshot' || x.faceOf))) {
+                const who = r.faceOf || r.entity;
+                m.set(who, r.label);
+              }
+              return m;
+            })()
+          : null;
         (seg.cuts || []).forEach((c, k) => {
           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`);
@@ -3339,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 = [];
@@ -3374,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`);
       }
     }
@@ -3774,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;
 }
 
@@ -3923,7 +4346,7 @@ export function seedScript(project, ep) {
   for (const id of outlineEp.characterIds || []) {
     const c = characterById(project, id);
     const sp = c?.bible?.speech || {};
-    if (c) speech[id] = { name: c.name, rhythm: sp.rhythm || '', silence: sp.silence || '', catchphrase: sp.catchphrase || '', forbiddenWords: sp.forbiddenWords || [], register: sp.register || '', voice: c.voice?.pace || '' };
+    if (c) speech[id] = { name: displayName(project, id, ep), rhythm: sp.rhythm || '', silence: sp.silence || '', catchphrase: sp.catchphrase || '', forbiddenWords: sp.forbiddenWords || [], register: sp.register || '', voice: c.voice?.pace || '' };
   }
   return {
     ep: Number(ep),
@@ -3933,14 +4356,16 @@ export function seedScript(project, ep) {
     task: isObject(outlineEp.task) ? { ...outlineEp.task } : { goal: '', obstacle: '', stake: '' },
     change: outlineEp.change || '',
     hookType: outlineEp.hookType || '',
-    hook: outlineEp.hook || '',
-    cliff: outlineEp.suspense || '',
+    hook: '',
+    cliff: outlineEp.hook || '',
     beatsClaimed: beats.map((b) => b.id),
     hookBeat: [1, 1],
     satisfactionBeat: null,
     scenes: [],
     seedNote: {
       synopsis: outlineEp.synopsis || '',
+      openingHook: `write \`hook\` yourself: the concrete image, in motion, that opens the episode (on screen within the first ${params.hookWindow} beats and by ${params.hookSeconds} s). \`cliff\` is seeded from the outline's hook — the question that makes them tap the next episode`,
+      suspense: outlineEp.suspense || '',
       satisfaction: isObject(outlineEp.satisfaction) ? { ...outlineEp.satisfaction } : { type: '', action: '' },
       register: params.register,
       guidelinePriorities: asList(project.outline?.guideline?.priorities),
@@ -3953,7 +4378,7 @@ export function seedScript(project, ep) {
       crowdPlan: outlineEp.crowdPlan || '',
       warnings: outlineEp.warnings || [],
       beats: beats.map((b) => ({ id: b.id, type: b.type, weight: b.weight || 'minor', setup: b.setup, payoff: b.payoff })),
-      previousCliff: prev?.suspense || '',
+      previousCliff: prev?.hook || '',
       budget: `${Math.round(Number(params.minutesPerEpisode) * 60)} s ≈ ${Math.round((Number(params.minutesPerEpisode) * 60) / 3.3)} beats; lines at ${params.charsPerSecond} chars/s, actions ${params.actionSeconds} s each`,
     },
     storyboard: { segments: [] },
@@ -3988,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: [] },
   };
 }
 
@@ -4034,6 +4459,50 @@ export function segmentPlan(project, episode) {
  * Measured on Seed Audio 1.0: the parenthetical is obeyed, not spoken (a 12-character line ran
  * 5.17 s plain and 4.88 s with the direction), so it costs nothing in the sample's length.
  */
+/**
+ * The full prompt of one image node on the characters / scenes / props canvas, in the project's
+ * image-prompt language: the headshot (1:1), the sheet (16:9; a character's references its headshot
+ * as @image1), a scene's lighting variant and a prop's state (both reference the sheet as @image1).
+ * The Operator pastes `prompt` and `negative` as they are — no hand-assembled prefixes.
+ */
+export function imagePrompt(project, id, asset) {
+  const params = paramsOf(project);
+  const kit = imagePromptKit(params);
+  const zh = kit.zh;
+  const c = characterById(project, id), sc = sceneById(project, id), pr = propById(project, id);
+  const entity = c || sc || pr;
+  if (!entity) throw new Error(`no character / scene / prop ${id}`);
+  const img = entity.image || {};
+  // the fixed phrases follow the script the prompts are written in (繁體 or 简体)
+  const hant = zh && isHant(`${img.prompt || ''}${img.sheet || ''}`);
+  const t = (phrase) => (hant ? hantPhrase(phrase) : phrase);
+  const out = (prompt, ratio, from) => ({ entity: id, asset, lang: params.imagePromptLang, prompt, negative: String(img.negativePrompt || ''), ratio, from });
+  const kind = asset || 'sheet';
+  if (c) {
+    if (kind === 'headshot') return out(zh ? `${img.prompt}${t('，正面干净人像，纯色中性背景')}` : `${img.prompt}, clean front-facing portrait, plain neutral background`, '1:1', null);
+    if (kind === 'sheet') return out(`${zh ? t('@image1 是必须完全一致的脸——五官与发型相同。') : '@image1 is the face to match exactly — same features, same hairstyle. '}${img.sheet}`, '16:9', 'headshot');
+    throw new Error(`a character has --asset headshot | sheet, not ${kind}`);
+  }
+  if (kind === 'sheet') return out(String(img.sheet || ''), '16:9', null);
+  if (sc && kind.startsWith('lighting:')) {
+    const state = kind.slice('lighting:'.length);
+    const l = (sc.lighting || []).find((x) => x.state === state);
+    if (!l) throw new Error(`${id} has no lighting state "${state}" (${(sc.lighting || []).map((x) => x.state).join(' / ')})`);
+    return out(zh
+      ? `${t('@image1 是同一个空间；结构、材质与磨损完全一致，只改变光线：')}${l.prompt}${t(`。空场景，没有任何人，${kit.framePhrase}`)}`
+      : `@image1 is this exact space; keep structure, materials and wear identical; change only the lighting: ${l.prompt}. Empty scene, no people, ${kit.framePhrase}`, '16:9', 'sheet');
+  }
+  if (pr && kind.startsWith('state:')) {
+    const state = kind.slice('state:'.length);
+    const st = (pr.states || []).find((x) => x.state === state);
+    if (!st) throw new Error(`${id} has no state "${state}" (${(pr.states || []).map((x) => x.state).join(' / ')})`);
+    return out(zh
+      ? `${t('@image1 是要完全还原的同一件道具。')}${st.prompt}${t('。纯白背景，没有人，没有手')}`
+      : `@image1 is the prop to reproduce exactly. ${st.prompt}, pure white background, no people, no hands`, '16:9', 'sheet');
+  }
+  throw new Error(sc ? `a scene has --asset sheet | lighting:<state>` : `a prop has --asset sheet | state:<state>`);
+}
+
 export function voiceSamplePrompt(character, params = {}) {
   const v = character?.voice || {};
   const pf = character?.profile || {};
@@ -4068,14 +4537,29 @@ export function voiceSampleSeconds(character, params) {
 export function segmentReferences(project, episode, seg) {
   const scene = (episode.scenes || [])[Number(seg.sceneIndex) - 1] || {};
   const sceneEntity = sceneById(project, scene.sceneId) || {};
-  const refs = [];
-  refs.push({ entity: scene.sceneId, asset: 'sheet', why: `environment: ${sceneEntity.name || scene.sceneId}${scene.lighting ? ` (${scene.lighting})` : ''}`, use: 'the environment \u2014 match its layout, materials and wear exactly', zh: '环境，严格还原布局、材质与旧痕' });
-  if (scene.lighting && sceneEntity.wji?.assets?.lighting?.[scene.lighting]) refs.push({ entity: scene.sceneId, asset: `lighting:${scene.lighting}`, why: `lighting state ${scene.lighting}`, use: 'the same environment in the lighting state to use', zh: '同一场景的光线状态' });
-  const seen = new Set();
   const params = paramsOf(project);
-  if (params.humanReferences !== false) for (const c of seg.cuts || []) for (const id of c.characters || []) if (!seen.has(id)) { seen.add(id); refs.push({ entity: id, asset: 'sheet', why: `face and clothes of ${characterById(project, id)?.name || id}`, use: 'the character sheet of one person in this segment \u2014 match face, hair and clothes exactly', zh: '人物三视图，严格还原面容、发型与服装' }); }
-  for (const c of seg.cuts || []) for (const id of c.props || []) if (!seen.has(id)) { seen.add(id); refs.push({ entity: id, asset: 'sheet', why: `prop ${propById(project, id)?.name || id}`, use: 'the prop to reproduce exactly', zh: '需要严格还原的道具' }); }
-  refs.forEach((r) => (r.kind = 'image'));
+  const refs = [];
+  // Optional per-segment image ref plan (Director Strategy B etc.) — pictures only; voices/video still appended below.
+  if (Array.isArray(seg.refOverride) && seg.refOverride.length) {
+    for (const r of seg.refOverride) {
+      refs.push({
+        entity: r.entity,
+        asset: r.asset || 'sheet',
+        why: r.why || `${r.entity}:${r.asset || 'sheet'}`,
+        use: r.use || 'a reference image for this segment',
+        zh: r.zh || '',
+        kind: 'image',
+        faceOf: r.faceOf || null,
+      });
+    }
+  } else {
+    refs.push({ entity: scene.sceneId, asset: 'sheet', why: `environment: ${sceneEntity.name || scene.sceneId}${scene.lighting ? ` (${scene.lighting})` : ''}`, use: 'the environment \u2014 match its layout, materials and wear exactly', zh: '环境，严格还原布局、材质与旧痕' });
+    if (scene.lighting && sceneEntity.wji?.assets?.lighting?.[scene.lighting]) refs.push({ entity: scene.sceneId, asset: `lighting:${scene.lighting}`, why: `lighting state ${scene.lighting}`, use: 'the same environment in the lighting state to use', zh: '同一场景的光线状态' });
+    const seen = new Set();
+    if (params.humanReferences !== false) for (const c of seg.cuts || []) for (const id of c.characters || []) if (!seen.has(id)) { seen.add(id); refs.push({ entity: id, asset: 'sheet', why: `face and clothes of ${characterById(project, id)?.name || id}`, use: 'the character sheet of one person in this segment \u2014 match face, hair and clothes exactly', zh: '人物三视图，严格还原面容、发型与服装' }); }
+    for (const c of seg.cuts || []) for (const id of c.props || []) if (!seen.has(id)) { seen.add(id); refs.push({ entity: id, asset: 'sheet', why: `prop ${propById(project, id)?.name || id}`, use: 'the prop to reproduce exactly', zh: '需要严格还原的道具' }); }
+    refs.forEach((r) => (r.kind = 'image'));
+  }
   // The clip before this one, when the project asks for it: the cheapest continuity there is — the
   // model sees what the last generation actually produced, not a description of it.
   if (params.videoReferences === 'previous') {
@@ -4111,7 +4595,19 @@ export function segmentReferences(project, episode, seg) {
     r.zh = `\u4e0a\u4e00\u6bb5\u7684\u6210\u7247\uff0c\u5ef6\u7eed\u5b83\u7684\u8d28\u611f\u3001\u670d\u88c5\u3001\u5149\u7ebf\u4e0e\u955c\u5934\u8bed\u8a00\uff0c\u63a5\u7740\u5b83\u5f80\u4e0b\u6f14\uff0c\u4e0d\u8981\u91cd\u590d\u5b83\u7684\u52a8\u4f5c`;
   }
   const sheetOf = params.references === 'sheets'
-    ? new Map(refs.filter((r) => r.kind === 'image' && r.asset === 'sheet').map((r) => [r.entity, r.label]))
+    ? (() => {
+        const m = new Map();
+        for (const r of refs.filter((x) => x.kind === 'image')) {
+          const who = r.faceOf || (r.asset === 'sheet' || r.asset === 'headshot' ? r.entity : null);
+          if (who && !m.has(who)) m.set(who, r.label);
+        }
+        // Prefer explicit headshot / faceOf over later body sheets
+        for (const r of refs.filter((x) => x.kind === 'image' && (x.asset === 'headshot' || x.faceOf))) {
+          const who = r.faceOf || r.entity;
+          m.set(who, r.label);
+        }
+        return m;
+      })()
     : new Map();
   for (const r of refs) {
     if (r.kind !== 'audio') continue;
@@ -4172,7 +4668,11 @@ export function promptSkeleton(project, episode, segmentId) {
     described.add(l.speaker);
     // A line is attributed by the reference that carries the voice — that is what the model has to
     // read it in. The sheet label rides along so the picture and the voice are tied to one person.
-    const who = [voice, sheet].filter(Boolean).join(' / ') || identityOf(ch);
+    // VO has no character / no @audio: never fall through identityOf(null) → "the person in this shot"
+    // (that wrongly lip-syncs the line onto whoever is on camera).
+    const who = l.speaker === 'VO'
+      ? 'an off-screen booth-edge friend voiceover'
+      : ([voice, sheet].filter(Boolean).join(' / ') || identityOf(ch));
     return {
       ...l,
       cut: k + 1,
@@ -4201,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';
@@ -4217,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('; ');
@@ -4235,22 +4745,29 @@ 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) => `${l.speakerRef}${l.direction ? `, ${l.direction},` : ''} says: ${l.line}`).join(' ');
+      const talk = dialogue[k].map((l) => {
+        const base = `${l.speakerRef}${l.direction ? `, ${l.direction},` : ''} says: ${l.line}`;
+        // VO is off-screen: keep every on-screen mouth closed so the cheer never lands on the visible face.
+        if (l.speaker !== 'VO') return base;
+        const others = othersOnScreen(c, l.speaker);
+        if (!others.length) return base;
+        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');
@@ -4259,7 +4776,13 @@ export function promptSkeleton(project, episode, segmentId) {
     const shotOf = (c) => `${SIZES[c.size] || c.size}, ${c.camera}, ${cameraPhrase(c, params)}; ${lightPhrase(c)}${foregroundPhrase(c)}`;
     const states = cuts.map((c, k) => (k === 0 ? `This first frame defines … (${shotOf(c)}).` : k === cuts.length - 1 && cuts.length >= 2 ? `This last frame defines … (${shotOf(c)}).` : `@image${k + 1} defines keyframe ${k + 1}: … (${shotOf(c)}).`));
     const script = cuts.map((c, k) => {
-      const talk = dialogue[k].map((l) => `${l.speakerRef}${l.direction ? `, ${l.direction},` : ''} says: ${l.line}`).join(' ');
+      const talk = dialogue[k].map((l) => {
+        const base = `${l.speakerRef}${l.direction ? `, ${l.direction},` : ''} says: ${l.line}`;
+        if (l.speaker !== 'VO') return base;
+        const others = othersOnScreen(c, l.speaker);
+        if (!others.length) return base;
+        return `${base} while ${others.join(' and ')} ${others.length > 1 ? 'do' : 'does'} not speak, ${LIPS_CLOSED}`;
+      }).join(' ');
       return `From @image${k + 1} (${starts[k].toFixed(1)}–${(starts[k] + Number(c.seconds)).toFixed(1)} s): ${motionSentence(c)} ${cameraClause(c)} ${talk}`.replace(/\s+/g, ' ').trim();
     });
     const sfxAll = cuts.map((c, k) => (sfxOf(k) ? `from @image${k + 1}: ${sfxOf(k)}` : '')).filter(Boolean).join('; ');
@@ -4448,7 +4971,7 @@ export function renderDialogue(project, episode) {
       if (b.line === undefined) return;
       const ch = characterById(project, b.speaker);
       const sp = ch?.bible?.speech || {};
-      const who = b.speaker === 'VO' ? 'VO' : ch?.name || b.speaker;
+      const who = b.speaker === 'VO' ? 'VO' : displayName(project, b.speaker, episode.ep);
       const hint = [sp.rhythm, sp.silence ? `沉默：${sp.silence}` : '', (sp.forbiddenWords || []).length ? `禁用：${sp.forbiddenWords.join('、')}` : ''].filter(Boolean).join('；');
       rows.push([`${who}${b.delivery ? `（${b.delivery}）` : ''}：${b.line}`, '', '', '', hint]);
     });
@@ -4543,12 +5066,12 @@ export function renderScript(project, episode) {
   const satRef = Array.isArray(episode.satisfactionBeat) ? episode.satisfactionBeat.map(Number) : null;
   (episode.scenes || []).forEach((sc, i) => {
     const scene = sceneById(project, sc.sceneId);
-    lines.push(`## ${i + 1}. ${scene?.name || sc.sceneId}${sc.lighting ? ` · ${sc.lighting}` : ''}`, '', `人物：${(sc.characters || []).map((id) => characterById(project, id)?.name || id).join('、')}${(sc.props || []).length ? ` · 道具：${sc.props.map((id) => propById(project, id)?.name || id).join('、')}` : ''}`, '');
+    lines.push(`## ${i + 1}. ${scene?.name || sc.sceneId}${sc.lighting ? ` · ${sc.lighting}` : ''}`, '', `人物：${(sc.characters || []).map((id) => displayName(project, id, episode.ep)).join('、')}${(sc.props || []).length ? ` · 道具：${sc.props.map((id) => propById(project, id)?.name || id).join('、')}` : ''}`, '');
     (sc.flow || []).forEach((b, k) => {
       const o = at(i + 1, k + 1);
       const span = o ? `（${Math.round(o.start)}-${Math.round(o.end)}秒）` : '';
       if (b.line !== undefined) {
-        const who = b.speaker === 'VO' ? 'VO' : characterById(project, b.speaker)?.name || b.speaker;
+        const who = b.speaker === 'VO' ? 'VO' : displayName(project, b.speaker, episode.ep);
         lines.push(`${who}${b.delivery ? `（${b.delivery}）` : ''}：${b.line}`);
       } else lines.push(`△${span}${b.action}${b.turn ? '　⟲' : ''}`);
       if (satRef && satRef[0] === i + 1 && satRef[1] === k + 1) lines.push('', `【爽点标记】${sat.action || sat.type || ''}`);
@@ -4569,7 +5092,7 @@ export function renderSegment(project, episode, segmentId) {
   const cuts = seg.cuts || [];
   const starts = cutStarts(cuts);
   const total = cuts.reduce((s, c) => s + (Number(c.seconds) || 0), 0);
-  const nameOf = (id) => characterById(project, id)?.name || id;
+  const nameOf = (id) => displayName(project, id, episode.ep);
   const lines = [`# ${seg.id}`, '', `${sceneById(project, scene.sceneId)?.name || scene.sceneId || ''}${scene.lighting ? ` · ${scene.lighting}` : ''} · ${round2(total)} s · ${params.video} · ${grammarsOf(seg, params).join(' + ')}`, ''];
   const kit = params.camera || DEFAULT_PARAMS.camera;
   lines.push(`镜头：${kit.body} + ${kit.lens}`, '');
@@ -4782,6 +5305,8 @@ export function initProject(opts) {
       videoDuration: opts.duration || (mode.autoDuration ? DEFAULT_PARAMS.videoDuration : 'fixed'),
       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.
@@ -4919,6 +5444,16 @@ function main(argv) {
     return 0;
   }
 
+  function installDashboard(projectDir, opts = {}) {
+    const output = resolve(opts.output || join(projectDir, 'dashboard.html'));
+    const source = join(dirname(fileURLToPath(import.meta.url)), '..', 'dashboard.html');
+    if (!existsSync(source)) throw new Error(`static dashboard missing: ${source}`);
+    if (existsSync(output) && !opts.force) return { output, copied: false };
+    mkdirSync(dirname(output), { recursive: true });
+    copyFileSync(source, output);
+    return { output, copied: true };
+  }
+
   if (cmd === 'init') {
     const dir = pos[0];
     if (!dir) throw new Error('usage: init <dir> --title … --episodes N --minutes M --genre G');
@@ -4927,14 +5462,17 @@ 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'), 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'),
+      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'),
     });
     const paths = projectPaths(dir);
     if (existsSync(paths.project) && !flag(rest, '--force')) throw new Error(`${paths.project} exists (pass --force to overwrite)`);
     writeJsonFile(paths.project, project);
     mkdirSync(paths.episodes, { recursive: true });
+    const dashboard = installDashboard(paths.dir);
     console.log(`✓ ${paths.project}`);
+    console.log(`✓ ${dashboard.output}`);
     return 0;
   }
 
@@ -4977,22 +5515,12 @@ function main(argv) {
 
   if (cmd === 'dashboard') {
     const loaded = loadProject(input);
-    const output = resolve(flag(rest, '--output', join(loaded.paths.dir, 'dashboard.html')));
-    if (existsSync(output) && !flag(rest, '--force')) {
-      throw new Error(`${output} exists (pass --force to overwrite)`);
-    }
-    const gateResults = runGates(makeContext(loaded.project, loaded.episodes));
-    const html = renderDashboard({
-      project: loaded.project,
-      episodes: loaded.episodes,
-      gateResults,
-      projectDir: loaded.paths.dir,
-      assetsDir: flag(rest, '--assets'),
-      outputPath: output,
+    const outputFlag = flag(rest, '--output');
+    const installed = installDashboard(loaded.paths.dir, {
+      output: typeof outputFlag === 'string' ? outputFlag : undefined,
+      force: Boolean(flag(rest, '--force')),
     });
-    mkdirSync(dirname(output), { recursive: true });
-    writeFileSync(output, html, 'utf8');
-    console.log(`✓ ${output}`);
+    console.log(installed.copied ? `✓ ${installed.output}` : `✓ ${installed.output} (already beside project.json)`);
     return 0;
   }
 
@@ -5060,6 +5588,15 @@ function main(argv) {
     return 0;
   }
 
+  if (cmd === 'prompt' && pos[1] === 'image') {
+    const { project } = loadProject(input);
+    if (!pos[2]) throw new Error('usage: prompt <project> image C01|S01|P01 [--asset headshot|sheet|lighting:<state>|state:<state>] [--json]');
+    const out = imagePrompt(project, pos[2], flag(rest, '--asset') || 'sheet');
+    if (flag(rest, '--json')) console.log(JSON.stringify(out, null, 2));
+    else console.log(out.prompt);
+    return 0;
+  }
+
   if (cmd === 'prompt' && pos[1] === 'voice') {
     const { project } = loadProject(input);
     const c = characterById(project, pos[2]);
@@ -5130,7 +5667,7 @@ function main(argv) {
   throw new Error(`unknown command "${cmd}" — run with --help`);
 }
 
-const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+const isMain = process.argv[1] && realpathSync(resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url));
 if (isMain) {
   try {
     process.exitCode = main(process.argv.slice(2));