@wji.ai/cli 0.8.0 → 0.8.2

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

@@ -19,6 +19,7 @@
 //            [--market mainland|overseas]                            (mainland holds the supernatural to a rational explanation)
 //            [--format short|medium|movie]                            (短剧 1–3 min, 中剧 4–15 min, 电影 in ~5-minute parts — see FORMATS)
 //            [--register 台湾国语]                                      (语体 — decides how lines are written and the accent spoken)
+//            [--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,14 +27,18 @@
 //   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] [--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';
 
@@ -85,6 +90,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,
@@ -106,6 +114,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 },
 });
 
@@ -201,6 +211,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) ──
 
@@ -283,6 +294,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',
@@ -469,6 +481,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',
@@ -478,6 +494,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',
@@ -487,6 +507,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',
@@ -496,6 +520,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',
@@ -505,9 +533,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.
@@ -1164,7 +1250,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);
 }
@@ -1175,9 +1261,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;
@@ -1198,6 +1293,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);
 }
@@ -1535,13 +1642,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;
@@ -1574,6 +1682,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}`);
@@ -1700,15 +1815,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.
@@ -1717,7 +1837,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 }) => {
@@ -1799,26 +1919,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;
   }),
@@ -1826,7 +1946,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();
@@ -1839,6 +1965,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();
@@ -1855,6 +1985,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;
@@ -2524,9 +2656,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 || [];
@@ -2536,7 +2671,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) {
@@ -2546,28 +2681,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`);
@@ -2577,24 +2713,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;
   }),
@@ -2606,7 +2742,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; }
@@ -2622,9 +2758,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}`;
@@ -2643,6 +2781,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`);
@@ -3092,6 +3237,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) {
@@ -3320,7 +3534,21 @@ 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
@@ -3920,7 +4148,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),
@@ -3930,14 +4158,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),
@@ -3950,7 +4180,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: [] },
@@ -4031,6 +4261,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 || {};
@@ -4065,14 +4339,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') {
@@ -4108,7 +4397,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;
@@ -4169,7 +4470,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,
@@ -4245,7 +4550,14 @@ export function promptSkeleton(project, episode, segmentId) {
   } else if (params.references === 'sheets') {
     const legend = allRefs.map((r) => `${r.label} is ${r.use}.`);
     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();
     });
@@ -4256,7 +4568,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('; ');
@@ -4445,7 +4763,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]);
     });
@@ -4540,12 +4858,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 || ''}`);
@@ -4566,7 +4884,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}`, '');
@@ -4779,6 +5097,7 @@ 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,
       // 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.
@@ -4916,6 +5235,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');
@@ -4924,14 +5253,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'),
+      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;
   }
 
@@ -4972,6 +5304,17 @@ function main(argv) {
     return 0;
   }
 
+  if (cmd === 'dashboard') {
+    const loaded = loadProject(input);
+    const outputFlag = flag(rest, '--output');
+    const installed = installDashboard(loaded.paths.dir, {
+      output: typeof outputFlag === 'string' ? outputFlag : undefined,
+      force: Boolean(flag(rest, '--force')),
+    });
+    console.log(installed.copied ? `✓ ${installed.output}` : `✓ ${installed.output} (already beside project.json)`);
+    return 0;
+  }
+
   if (cmd === 'render') {
     const what = pos[1];
     const { project, episodes } = loadProject(input);
@@ -5036,6 +5379,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]);
@@ -5106,7 +5458,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));