kasaframe 0.0.0-stage → 0.1.3

package/packages/cli/src/commands/make.ts

@@ -0,0 +1,1121 @@
+import { spawn, spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { askTerminal, blenderLibDir, capabilities, genImage, genVideo, hasKey, NeedsApproval, parseAllow, type Question, questionsText, seam, seamFrames, settle, still, whereToPut } from "@kasaframe/gen";
+import { applyAnswers, attachStudio, loadSeries, type Series, seriesFromRequest, chat, codeBlock, detect, formatLook, jsonBlock, listTemplates, loadTemplate, look, lookSheet, makePlan, type Message, type Plan, planQuestions, premiumBlock, projectBrief, PURPOSES, type Purpose, readProject, spend, spentLine, WAIT, writeCaptions, writeStats } from "@kasaframe/plan";
+import { checkContent, contentPrompt, directBrief } from "@kasaframe/director";
+import { transform } from "esbuild";
+import { bundleFor, dressSeed, pickDress } from "@kasaframe/motion/menu";
+import { themeStyle } from "@kasaframe/themes";
+import { captionMode } from "@kasaframe/motion/captions";
+import { jizuraCheck } from "@kasaframe/jizura/install";
+import { openPage } from "../browser.ts";
+import { librosa } from "../deps.ts";
+import { lyricsCheck } from "./lyrics.ts";
+import { type Command, num, parseFlags } from "../command.ts";
+import { acquireRenderLock } from "../lock.ts";
+import { gate, jobLimit, pool } from "../pool.ts";
+
+const kfBin = fileURLToPath(new URL("../kf.ts", import.meta.url));
+const repo = fileURLToPath(new URL("../../../../", import.meta.url));
+
+// 박자(librosa)·뮤비 가사(JIZURA·정렬) — 없으면 넣는 법·지금 되는 다른 길·빼기를 묻는다
+function toolQuestions(purpose: Purpose, willSong: boolean): Question[] {
+  const out: Question[] = [];
+  const b = librosa();
+  if (willSong && !b.ok)
+    out.push({
+      id: "beats", cap: "beats", header: "박자 분석", flag: "--beats", missing: true, default: WAIT, skip: "none",
+      ask: `곡에 장면 경계·움직임을 맞출 박자 분석(librosa)이 없다 — ${b.detail}`,
+      choices: [{ value: WAIT, label: "깔고 다시", note: b.fix ?? "kf setup beats" }, { value: "none", label: "곡 없이", note: "곡을 빼고 화면 안 움직임으로만 — 박 없이 곡만 까는 길은 없다" }],
+    });
+  if (purpose === "mv") {
+    const j = jizuraCheck();
+    const l = lyricsCheck();
+    if (!j.ok || !l.ok)
+      out.push({
+        id: "lyrics", cap: "lyrics", header: "가사", flag: "--lyrics", missing: true, default: WAIT, skip: "none",
+        ask: `뮤비 가사에 쓸 ${[!j.ok ? "가사 층 엔진(JIZURA)" : "", !l.ok ? "가사 정렬(demucs·stable-ts)" : ""].filter(Boolean).join("·")} 이 없다`,
+        choices: [
+          { value: WAIT, label: "깔고 다시", note: `kf setup ${[!j.ok ? "jizura" : "", !l.ok ? "lyrics" : ""].filter(Boolean).join(" ")}` },
+          ...(l.ok && !j.ok ? [{ value: "words", label: "가사 층 없이 낱말로", note: "정렬한 낱말을 DOM 글로 띄운다 — JIZURA 레이아웃·효과는 없다" }] : []),
+          { value: "none", label: "가사 없이", note: "곡과 화면만" },
+        ],
+      });
+  }
+  return out;
+}
+
+// 시리즈가 박은 답(목소리·곡 파일·생성 답) — 질문 플래그 값으로 넣어 묻지 않는다
+function seriesAnswers(s: Series | null): Record<string, string> {
+  if (!s) return {};
+  return Object.fromEntries(Object.entries({ ...s.answers, voice: s.voice, music: s.music?.file && resolve(repo, s.music.file) }).filter((e): e is [string, string] => typeof e[1] === "string"));
+}
+
+// Claude Code 를 OG 로 다른 모델(딥시크 등)에 붙이면 OG /v1/messages 가 그림을 버린다 — 세션이 kf sheet 를 Read 해도 못 본다.
+// 그런 「눈 없는 세션」이면 --finish 끝에 --vision-model 을 알려 준다(그림 보는 모델은 기본으로 부르지 않는다)
+export const eyelessSession = (): boolean =>
+  /opengateway/i.test(process.env.ANTHROPIC_BASE_URL ?? "") && !/^anthropic\//.test(process.env.ANTHROPIC_MODEL ?? "anthropic/");
+const AUDIO = /\.(mp3|wav|m4a|aac|flac|ogg)$/i;
+const DEFAULT_VISION = "google/gemini-3.5-flash";
+// 화면에 찍히면 안 되는 글 — 지난 실험에서 실제로 나온 것들
+const BAD_TEXT = /\bundefined\b|\bNaN\b|\[object Object\]|\bnull\b|�/;
+
+const cmd: Command = {
+  summary: "요청 한 줄로 끝까지 — 용도 판별·계획·생성 자산·장면 작성·렌더·검사·고치기",
+  usage: `kf make "<요청>" [--out 폴더] [--assets 폴더] [--music 곡] [--model claude-code|<OG 모델>] [--purpose 용도] [--theme id|auto] [--title 이름] [--yes]
+kf make --finish <폴더> [--model ...]     장면을 다 채운 뒤 렌더·검사·표지(Claude Code 모드의 둘째 단계)
+kf make --rewrite <폴더> --scenes a,b [--model <OG 모델>]   고른 장면만 다시 쓰고 그 조각만 다시 굽고 그 구간만 검사(작업실 장면 카드)
+                  감독 프로젝트는 모델 없이 kf direct --scenes 로 다시 짓는다(--pattern a=<패턴>·--scene-seed a=<글> 로 다른 후보)
+                  모델을 안 주면 그 일을 만든 모델(plan.json 의 model) — 장면 코드를 쓰는 길인데 그것도 없으면 멈춘다
+kf make --finish <폴더> --scenes a,b   장면 파일을 손으로 고친 뒤 — 바뀐 조각만 다시 굽고 그 구간만 검사
+kf make --answer <폴더> --image <값> --video <값> …   Claude Code 모드에서 MAKE.md 맨 위 질문의 답을 넣는다(계획·지시서를 고쳐 쓴다)
+
+  생성 능력(kf doctor 「생성 능력」): 계획은 그림 컷·주인공 3D 샷(Blender)·이음매 3D 전환(three)·캐릭터가 움직이는 컷(영상 모델)을
+  기본으로 넣는다. 돈이 들거나 없는 능력은 만들기 전에 한 번에 묻는다 — Claude Code 모드는 MAKE.md 맨 위, OG 모드는 터미널에서
+  (터미널이 아니면 보기와 다시 부를 플래그를 찍고 종료 코드 3)
+  --image og-…|codex-imagegen|none · --video <공급자>|none · --blender three|none   그 질문에 미리 답한다
+  --voice <엔진>:<목소리>|none   내레이션 목소리(쇼츠·설명 — 보기는 로컬 Qwen3(KF_QWEN3_TTS_URL 있을 때)·ElevenLabs·자막만·그 밖 순, 키 없는 보기는 넣는 법. kf narrate --voices)
+  --music <곡 파일>|gen:<공급자>|none   곡(쇼츠·설명은 분위기 맞는 곡 모음 곡을 묻지 않고 고르고, 없을 때만 생성·곡 넣기·없음을 묻는다)
+  --allow image,video,…   그 능력은 권장 답으로, 목록에 없는 능력은 돈 안 드는 길로 — 묻지 않는다
+
+  감독 모드(기본, 뮤비 빼고): 모델은 content.json(장면마다 type·칸·들릴 말·출처)만 쓰고, kf direct 가 검증된 장면 문법을
+  골라 장면 파일을 조립한다(LLM 이 장면 코드를 안 쓴다 — 어떤 모델이든 content.json 만 맞으면 화면 품질이 같다)
+  --no-direct     감독 없이 모델이 장면 코드를 직접 쓰는 길(뮤비는 늘 이 길)
+  --model         claude-code(기본, 어디서 부르든): 지시서(MAKE.md)까지 만들고 멈춘다 — 감독 모드면 세션이 content.json 을 쓰고
+                  kf direct → --finish, --no-direct 면 세션이 장면을 채우고 --finish. OG 를 한 번도 부르지 않는다
+                  <OG 모델>: 짚을 때만 — OG chat/completions 로 content.json(--no-direct 면 장면)을 쓰고 렌더·검사까지
+  --vision-model  그림 보는 검사 모델(기본 none — 세션이 kf look 의 장면 모음·확인표를 직접 본다). 그림을 못 보는 세션만 ${DEFAULT_VISION} 같은 모델을 준다
+  --allow-premium Opus·GPT 계열 OG 모델(--model·--vision-model·--rewrite)을 푼다(KF_ALLOW_PREMIUM=1 과 같다). 없으면 부르기 전에 막는다
+  끝날 때(성공·실패·중단) <작업 폴더>/make-stats.json 에 단계별 모델·ms·토큰·usd 와 합계를 남기고 「OG 호출 N번 · 토큰 · $」 한 줄을 찍는다
+  --series        시리즈 묶음(series/<id>.json) · none. 안 주면 요청이 짚은 시리즈(「OG 쇼츠」처럼) — 용도·테마·목소리·곡·자막·길이·끝 카드·생성 답을 묻지 않고 그 묶음대로
+  --purpose       용도를 못 박는다: ${PURPOSES.join(" · ")}
+  --theme         테마 id · auto(요청이 「리소 느낌」처럼 짚은 테마, 아니면 내용에 맞는 approved 후보 셋 중 첫째. 첫 장면을 셋 다 찍어 out/theme-<id>.png) · none(프리셋만)
+                  안 주면(시리즈가 정하지도 않았으면) 묻는다 — 보기는 approved 테마 전부(생김새 한 줄·2D/3D·견본)와 「알아서」(= auto). kf theme sheet
+  --yes           묻지 않고 권장 답으로 — 돈이 드는 그림·영상도 승인한다(지역 제한이 걸린 H3 는 --video h3-pod 로 짚어야만)
+  --max-usd       영상 하나 상한(기본 1)
+  --video-provider  영상 공급자를 못 박는다(예: h3-pod — KF_H3_URL·KF_H3_STEPS 필요). 기본은 KF_VIDEO_PROVIDER, 없으면 생성 담당 기본
+  --fix           검사가 떨어졌을 때 고치기 횟수(기본 2)
+  --captions on|off|fit  화면 자막(fit 은 장면을 자막 띠 위로 줄여 올린다) — 새로 만들 땐 kf.json 에 적고, --finish 에선 그 판만 덮는다(다시 만들지 않고 켜고 끄기). srt·vtt 는 둘 다 낸다
+  --suffix [글]   --finish 결과 이름 뒤에 붙인다(값 없이면 -자막 · -자막없음) — 원본 video.mp4 를 덮지 않고 둘 다 남긴다
+  --no-gen        생성 모델을 부르지 않는다 — 묻지 않고 그림·영상 모델은 빼고, Blender 가 없으면 three 로 대신한다
+
+용도를 못 정하면 터미널에서 묻고, 터미널이 아니면 보기를 찍고 종료 코드 3.`,
+  async run(argv) {
+    // 장부는 어느 길로 끝나든(성공·실패·throw·Ctrl-C) 한 번 — 작업 폴더가 서기 전에 끝났으면 줄만 찍는다
+    const at: Track = {};
+    let code: number | string = "오류";
+    let closed = false;
+    const close = () => {
+      if (closed || at.quiet) return;
+      closed = true;
+      if (at.dir && existsSync(at.dir)) writeStats(at.dir, { command: at.command ?? "make", model: at.model ?? "", code });
+      console.log(`\n${spentLine()}`);
+    };
+    const stop = (sig: NodeJS.Signals) => {
+      code = sig;
+      close();
+      process.exit(sig === "SIGINT" ? 130 : 143);
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    try {
+      code = await make(argv, at);
+      return code;
+    } finally {
+      process.off("SIGINT", stop);
+      process.off("SIGTERM", stop);
+      close();
+    }
+  },
+};
+export default cmd;
+
+interface Track {
+  dir?: string;
+  model?: string;
+  command?: string;
+  quiet?: boolean;
+}
+
+async function make(argv: string[], at: Track): Promise<number> {
+  const { args, opts } = parseFlags(argv);
+  const str = (k: string) => (typeof opts[k] === "string" ? (opts[k] as string) : undefined);
+  // OG 모델은 짚을 때만 — 어디서 부르든(Claude Code 안팎·작업실) 기본은 지시서까지 만들고 세션이 잇는 claude-code
+  const model = str("model") ?? "claude-code";
+  const vision = str("vision-model") ?? "none";
+  at.model = model;
+  if (opts["allow-premium"]) process.env.KF_ALLOW_PREMIUM = "1";
+  for (const m of [model, vision]) {
+    const why = m !== "claude-code" && m !== "none" ? premiumBlock(m) : null;
+    if (why) {
+      console.error(`kf make: ${why}`);
+      return 2;
+    }
+  }
+  // OG 모드는 장면 쓰기·그림 보기까지 OG 를 부른다 — 뼈대만 만들고 죽지 않게 처음에 막는다
+  if (model !== "claude-code" && !hasKey("opengateway")) {
+    console.error(`kf make: OG 키가 없다 — ${whereToPut("opengateway")}. 키 없이는 --model 을 빼고(claude-code) — 장면은 세션이 쓰고 그림 생성은 건너뛴다`);
+    return 2;
+  }
+  const fixes = num(opts.fix, 2);
+  const captions = str("captions");
+  if (captions !== undefined && captions !== "on" && captions !== "off" && captions !== "fit") {
+    console.error(`kf make: --captions 는 on·off·fit — ${captions}`);
+    return 2;
+  }
+  const suffix = str("suffix") ?? (opts.suffix ? (captions === "off" ? "-자막없음" : "-자막") : "");
+
+  if (opts.answer) {
+    at.quiet = true;
+    const dir = resolve(typeof opts.answer === "string" ? opts.answer : (args[0] ?? "."));
+    return answerProject(dir, opts);
+  }
+  if (opts.rewrite) {
+    const dir = resolve(typeof opts.rewrite === "string" ? opts.rewrite : (args[0] ?? "."));
+    Object.assign(at, { dir, command: "rewrite" });
+    const ids = (str("scenes") ?? "").split(",").filter(Boolean);
+    if (!ids.length) {
+      console.error("kf make --rewrite: --scenes a,b 가 필요하다");
+      return 2;
+    }
+    // 감독 프로젝트 — 모델 없이 그 장면만 다시 짓는다(다른 장면 파일은 바이트 그대로라 그 조각은 다시 안 굽는다)
+    if (isDirect(dir)) {
+      const pick = ["pattern", "scene-seed"].flatMap((k) => (str(k) ? [`--${k}`, str(k)!] : []));
+      // 들릴 말을 고쳤을 때만 다시 읽힌다 — 목소리가 장면 길이를 정해서 뒤 장면 시각이 움직인다(그 조각들도 다시 굽힌다)
+      const narrate = sayChanged(dir, ids) ? [] : ["--no-narrate"];
+      const d = await relay(["direct", dir, "--scenes", ids.join(","), ...narrate, "--no-check", ...pick]);
+      if (d !== 0) return d;
+      return finish(dir, { model: "direct", vision, fixes: 0, scenes: ids });
+    }
+    // 다시 쓰기는 그 일을 만든 모델로 — 기본 모델로 몰래 바꾸지 않는다
+    const own = str("model") ?? readPlan(dir).model;
+    if (!own || own === "claude-code") {
+      console.error(`kf make --rewrite: 장면 코드를 다시 쓸 OG 모델이 없다 — --model <OG 모델>로 주거나, 세션이 ${ids.join(",")} 장면 파일을 고치고 kf make --finish ${dir} --scenes ${ids.join(",")}`);
+      return 2;
+    }
+    at.model = own;
+    // 그 일을 만든 모델이 비싼 계열이면 다시 쓰기도 같은 문에서 막는다
+    if (premiumBlock(own)) {
+      console.error(`kf make --rewrite: ${premiumBlock(own)}`);
+      return 2;
+    }
+    writeFileSync(join(dir, "MAKE.md"), projectBrief(dir));
+    await writeScenes(dir, own, ids);
+    return finish(dir, { model: own, vision, fixes, scenes: ids });
+  }
+  if (opts.finish) {
+    const dir = resolve(typeof opts.finish === "string" ? opts.finish : (args[0] ?? "."));
+    Object.assign(at, { dir, command: "finish" });
+    const plan = existsSync(join(dir, "plan.json")) ? JSON.parse(readFileSync(join(dir, "plan.json"), "utf8")) : {};
+    const gen = { approve: !!opts.yes || videoApproved(plan), maxUsd: num(opts["max-usd"], 1), videoProvider: str("video-provider") ?? process.env.KF_VIDEO_PROVIDER };
+    const studio = await attachStudio({ dir, request: plan.request ?? dir, model, purpose: plan.purpose });
+    const unmirror = studio?.mirror();
+    if (studio) console.log(`작업실: ${studio.url}`);
+    await studio?.send({ phase: "render" });
+    const scenes = str("scenes")?.split(",").filter(Boolean);
+    const code = await finish(dir, { model, vision, fixes, gen: opts["no-gen"] ? undefined : gen, captions, suffix, ...(scenes?.length ? { scenes } : {}) });
+    await unmirror?.();
+    await studio?.send({ done: true, ok: code === 0 });
+    return code;
+  }
+
+  const request = args.join(" ").trim();
+  if (!request) {
+    console.error('kf make: 요청 글이 필요하다 — kf make "카사텀 홍보 영상 1분"');
+    return 2;
+  }
+  const assetFiles = str("assets") ? listFiles(resolve(str("assets")!)) : [];
+  // 시리즈가 먼저 — 같은 시리즈면 매번 같은 묶음. 사람이 따로 준 플래그는 그대로 이긴다
+  const series: Series | null = str("series") === "none" ? null : str("series") ? loadSeries(str("series")!) : seriesFromRequest(request);
+  if (series) console.error(`시리즈 ${series.id}(${series.label}) — 용도·테마·목소리·곡·자막·길이·끝 카드를 묶음대로`);
+  // --music 은 곡 파일, 아니면 음악 질문의 답(gen:<공급자>·none) — 답은 파일로 읽지 않는다
+  const musicFlag = str("music");
+  const musicAnswer = musicFlag !== undefined && /^(gen:|none$)/.test(musicFlag);
+  const given = musicFlag && !musicAnswer ? resolve(musicFlag) : (assetFiles.find((f) => AUDIO.test(f)) ?? (series?.music?.file ? resolve(repo, series.music.file) : undefined));
+
+  let purpose = (str("purpose") ?? series?.purpose) as Purpose | undefined;
+  const det = detect({ request, assets: assetFiles, music: given }, listTemplates());
+  if (!purpose) {
+    if (det.ambiguous) {
+      purpose = await ask(det.ranked.slice(0, 4).map((r) => r.purpose));
+      if (!purpose) {
+        console.error(`kf make: 용도를 못 정했다(확신 ${det.confidence}). --purpose 로 골라 다시: ${det.ranked.slice(0, 4).map((r) => `${r.purpose}(${r.p})`).join(" · ")}`);
+        return 3;
+      }
+    } else purpose = det.purpose;
+  }
+  const chosen = det.ranked.find((r) => r.purpose === purpose);
+  // 곡을 안 줬으면 곡이 끌고 가는 용도(홍보·공개)일 때만 곡 모음에서 고른다 — 쇼츠·설명에 아무 곡이나 깔리지 않게
+  // 분위기를 정한 틀(쇼츠·설명)은 곡을 묻기 틀이 고른다(분위기 맞는 곡 모음 곡 → 생성 → 없음)
+  const tplOf = loadTemplate(purpose);
+  const music = given ?? (!musicAnswer && tplOf.music === "required" && !tplOf.mood ? findLibraryMusic(request) : undefined);
+  console.error(`용도 ${purpose} (${series && !str("purpose") ? `시리즈 ${series.id}` : `확신 ${chosen?.p ?? 1}${chosen?.reasons.length ? ` — ${chosen.reasons.join(", ")}` : ""}`})`);
+
+  // 만들기 전에 묻는다 — 뼈대를 만들고 나서 멈추면 반쯤 만든 폴더가 남는다
+  const caps = await capabilities({ probe: true });
+  const draft = makePlan({ request, purpose, assets: assetFiles, music: given ?? null, series: series?.id ?? "none" });
+  const { questions, auto } = planQuestions(draft, caps);
+  const flags = { ...seriesAnswers(series), ...opts };
+  const settled = settle(questions, { given: flags, yes: !!opts.yes, noGen: !!opts["no-gen"], allow: parseAllow(opts.allow) });
+  // 묻지 않고 정한 답(있는 공짜 능력)도 사람이 준 플래그·시리즈 답이 이긴다. --no-gen 이면 공짜라도 생성 모델(그림·영상)은 뺀다
+  const forced = Object.fromEntries(
+    Object.keys(auto).flatMap((id) => (typeof flags[id] === "string" ? [[id, flags[id] as string]] : opts["no-gen"] && (id === "image" || id === "video") ? [[id, "none"]] : [])),
+  );
+  let answers: Record<string, string> = { ...auto, ...forced, ...settled.answers };
+  let open = settled.open;
+  // 박자·가사 도구는 뼈대를 세울 때 쓴다 — 없으면 조용히 박 없이·낱말로 가지 않고, 모드와 상관없이 뼈대 전에 답을 받는다
+  const willSong = !!(music ?? (answers.music && !/^(gen:|none$|wait$)/.test(answers.music) ? answers.music : undefined));
+  const tools = toolQuestions(purpose, willSong);
+  const toolSettled = settle(tools, { given: flags, yes: !!opts.yes, noGen: !!opts["no-gen"], allow: parseAllow(opts.allow) });
+  questions.push(...tools);
+  answers = { ...answers, ...toolSettled.answers };
+  Object.assign(settled.how, toolSettled.how);
+  if (toolSettled.open.length) {
+    const asked = await askTerminal(toolSettled.open);
+    if (!asked) {
+      console.error(`kf make: 뼈대 전에 정할 것이 ${toolSettled.open.length}가지 — 사람에게 묻고 플래그로 답해 다시 부른다\n\n${questionsText(toolSettled.open)}`);
+      return 3;
+    }
+    answers = { ...answers, ...asked };
+  }
+  if (answers.beats === "none" && answers.music && !/^(gen:|none$)/.test(answers.music)) answers.music = "none";
+  if (open.length && model !== "claude-code") {
+    const asked = await askTerminal(open);
+    if (!asked) {
+      console.error(`kf make: 만들기 전에 정할 것이 ${open.length}가지 — 플래그로 답해 다시 부른다(--yes 면 권장, --no-gen 이면 돈 안 드는 길)\n\n${questionsText(open)}`);
+      return 3;
+    }
+    answers = { ...answers, ...asked };
+    open = [];
+  }
+  for (const [id, v] of Object.entries(answers)) console.error(`능력 ${id}: ${v}(${settled.how[id] === "flag" || forced[id] ? "플래그" : settled.how[id] ? `--${settled.how[id]}` : auto[id] ? "있어서 바로" : "물어서"})`);
+  const stops = questions.filter((q) => answers[q.id] === WAIT);
+  if (stops.length) {
+    console.error(`kf make: 켜고 다시 부른다 —\n${stops.map((q) => `  ${q.ask}: ${q.choices.find((c) => c.value === WAIT)?.note}`).join("\n")}`);
+    return 3;
+  }
+
+  const dir = resolve(str("out") ?? `${purpose}-${stamp()}`);
+  Object.assign(at, { dir, command: "make" });
+  const newArgs = [kfBin, "new", dir, "--template", purpose, "--request", request, "--series", series?.id ?? "none"];
+  if (series?.end?.line) newArgs.push("--line", series.end.line);
+  // 박자 분석을 빼기로 했으면 곡도 깔지 않는다 — 박 없이 곡만 까는 길은 없다
+  const song = answers.beats === "none" ? undefined : (music ?? (answers.music && !/^(gen:|none$|wait$)/.test(answers.music) ? answers.music : undefined));
+  if (song) newArgs.push("--music", song);
+  if (str("title")) newArgs.push("--title", str("title")!);
+  // 테마 질문의 답(플래그·터미널) → 아직 묻는 중이거나 묻지 않은 테마(시리즈·요청이 짚은 것)는 auto. 테마 없이 프리셋만 쓰려면 --theme none
+  newArgs.push("--theme", answers.theme && answers.theme !== WAIT ? answers.theme : (str("theme") ?? "auto"));
+  if (opts.force) newArgs.push("--force");
+  const made = spawnSync(process.execPath, newArgs, { stdio: ["ignore", "inherit", "inherit"] });
+  if (made.status !== 0) return made.status ?? 1;
+
+  const studio = await attachStudio({ dir, request, model, purpose });
+  const unmirror = studio?.mirror();
+  if (studio) console.log(`작업실: ${studio.url}`);
+  const plan: Plan = { ...applyAnswers(JSON.parse(readFileSync(join(dir, "plan.json"), "utf8")), answers).plan, asks: open };
+  // 새 프로젝트는 이 영상의 기본으로 적는다 — 계획 다듬기가 내레이션을 쓸지도 이걸 본다
+  if (captions) {
+    const kfPath = join(dir, "kf.json");
+    writeJson(kfPath, { ...JSON.parse(readFileSync(kfPath, "utf8")), captions });
+    plan.captions = captionMode(captions);
+  }
+  if (!str("purpose") && !series) {
+    plan.confidence = chosen?.p ?? det.confidence;
+    plan.alternatives = det.ranked.filter((r) => r.purpose !== purpose).slice(0, 2).map((r) => ({ purpose: r.purpose, p: r.p }));
+    plan.reasons = [...(chosen?.reasons ?? []), ...plan.reasons.filter((r) => r !== "사람이 정함")];
+  }
+  // 장면 다시 쓰기(--rewrite)가 같은 모델을 부른다
+  (plan as Plan & { model?: string }).model = model;
+  if (assetFiles.length) {
+    mkdirSync(join(dir, "assets", "in"), { recursive: true });
+    for (const f of assetFiles) if (!AUDIO.test(f)) copyFileSync(f, join(dir, "assets", "in", basename(f)));
+  }
+  writeJson(join(dir, "plan.json"), plan);
+  if (plan.theme) {
+    const pick = plan.themeCandidates?.find((c) => c.id === plan.theme);
+    console.error(`테마 ${plan.theme}${pick ? ` — ${pick.why}` : ""}${plan.themeCandidates && plan.themeCandidates.length > 1 ? ` (다른 후보: ${plan.themeCandidates.filter((c) => c.id !== plan.theme).map((c) => c.id).join(" · ")})` : ""}`);
+  }
+  if (plan.themeCandidates && plan.themeCandidates.length > 1) themeStills(dir, plan.themeCandidates.map((c) => c.id));
+
+  // 감독 모드 — 뮤비는 가사 층이 화면을 맡아 장면 문법을 안 쓴다
+  const direct = !opts["no-direct"] && purpose !== "mv";
+  if (direct) {
+    writeJson(join(dir, "plan.json"), { ...plan, direct: true });
+    writeFileSync(join(dir, "MAKE.md"), directBrief(dir));
+    if (model === "claude-code") {
+      if (open.length) console.log(`\n먼저 사람에게 물을 것 ${open.length}가지 — ${dir}/MAKE.md 맨 위 「사용자에게 먼저 물을 것」(AskUserQuestion), 답은 kf make --answer ${dir} ${open.map((q) => `${q.flag} <값>`).join(" ")}`);
+      console.log(`\n감독 모드 — ${dir}/MAKE.md 를 읽고 ${dir}/content.json 을 쓴다(장면 코드는 안 쓴다). 그다음:\n  kf direct ${dir}\n  kf look ${dir}\n  kf make --finish ${dir}`);
+      await unmirror?.();
+      await studio?.send({ phase: "scenes" });
+      return 0;
+    }
+    if (!(await writeContent(dir, model))) {
+      console.error(`kf make: ${model} 이 맞는 content.json 을 못 냈다 — ${dir}/content.json 을 손보고 kf direct ${dir}`);
+      return 1;
+    }
+    const d = spawnSync(process.execPath, [kfBin, "direct", dir], { stdio: ["ignore", "inherit", "inherit"] });
+    if (d.status !== 0 && d.status !== 1) return d.status ?? 1;
+    const gen = { approve: !!opts.yes || videoApproved(plan), maxUsd: num(opts["max-usd"], 1), videoProvider: str("video-provider") ?? process.env.KF_VIDEO_PROVIDER };
+    const code = await finish(dir, { model, vision, fixes, gen: opts["no-gen"] ? undefined : gen });
+    await unmirror?.();
+    await studio?.send({ done: true, ok: code === 0 });
+    return code;
+  }
+
+  if (model !== "claude-code") {
+    await refinePlan(dir, model, request);
+    // 내레이션 먼저 — 계획 다듬기가 쓴 장면별 문장을 읽혀 장면 길이를 목소리에 맞춘 뒤 장면을 쓴다
+    const code = narrateStep(dir);
+    if (code !== 0) return code;
+  }
+
+  const gen = { approve: !!opts.yes || videoApproved(plan), maxUsd: num(opts["max-usd"], 1), videoProvider: str("video-provider") ?? process.env.KF_VIDEO_PROVIDER };
+  // claude-code 모드는 그림·3D 샷을 세션이 만든다 — 막연한 자동 프롬프트로 엉뚱한 그림이 나왔다. 지시서에 목록과 고른 공급자로 낸다
+  if (model !== "claude-code") {
+    await genImages(dir);
+    await writeShots(dir, model);
+  }
+
+  writeFileSync(join(dir, "MAKE.md"), projectBrief(dir));
+  if (model === "claude-code") {
+    const flags = [opts.yes ? "--yes" : "", gen.videoProvider ? `--video-provider ${gen.videoProvider}` : ""].filter(Boolean).join(" ");
+    if (open.length) console.log(`\n먼저 사람에게 물을 것 ${open.length}가지 — ${dir}/MAKE.md 맨 위 「사용자에게 먼저 물을 것」(AskUserQuestion), 답은 kf make --answer ${dir} ${open.map((q) => `${q.flag} <값>`).join(" ")}`);
+    console.log(`\n${dir}/MAKE.md 를 읽고 scenes/*.ts 를 채운다. 다 채우면(이음매 영상은 그때 앞뒤 장면 프레임으로 만든다):\n  kf make --finish ${dir}${flags ? ` ${flags}` : ""}`);
+    // 장면은 세션이 쓴다 — 작업실 미리보기가 저장할 때마다 따라온다
+    console.error("장면 쓰는 중(세션) — 저장할 때마다 작업실 미리보기에 바로 보인다");
+    await unmirror?.();
+    await studio?.send({ phase: "scenes" });
+    return 0;
+  }
+  // 이음매는 틀의 3D 전환이 맡는다 — 모델이 다시 쓰지 않는다
+  await writeScenes(dir, model, readProject(dir).scenes.filter((s) => s.role !== "seam").map((s) => s.id));
+  const code = await finish(dir, { model, vision, fixes, gen: opts["no-gen"] ? undefined : gen });
+  await unmirror?.();
+  await studio?.send({ done: true, ok: code === 0 });
+  return code;
+}
+
+// --- 감독 모드: 모델은 content.json 하나만 — 칸이 틀리면 어느 칸인지 돌려줘 두 번까지 다시
+
+function isDirect(dir: string): boolean {
+  const p = join(dir, "plan.json");
+  return existsSync(p) && JSON.parse(readFileSync(p, "utf8")).direct === true;
+}
+
+async function writeContent(dir: string, model: string): Promise<boolean> {
+  const plan = JSON.parse(readFileSync(join(dir, "plan.json"), "utf8"));
+  let fix: string | undefined;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    // 생각하는 모델은 생각에 토큰을 먼저 쓴다 — 상한이 낮으면 답 JSON 이 잘린다
+    const r = await chat(model, contentPrompt(dir, fix), { json: true, temperature: 0.5, maxTokens: 16000, stage: "content" });
+    const j = jsonBlock<Record<string, unknown>>(r.text);
+    if (!j) {
+      fix = "JSON 을 못 읽었다 — JSON 하나로만 답한다";
+      continue;
+    }
+    const c = checkContent({ ...j, request: plan.request });
+    console.error(`content.json ${attempt + 1}번째(${model}, ${(r.ms / 1000).toFixed(1)}초) — ${c.errors.length ? `칸 오류 ${c.errors.length}` : `장면 ${c.content.scenes.length}`}`);
+    if (c.errors.length) {
+      fix = c.errors.map((e) => `${e.at}: ${e.msg}`).join("\n");
+      continue;
+    }
+    writeJson(join(dir, "content.json"), { ...j, request: plan.request });
+    return true;
+  }
+  return false;
+}
+
+// --- 계획 다듬기: 틀이 정한 뼈대(시각·역할)는 그대로, 이름·끝 한 줄·장면 할 일·생성 프롬프트만 요청에 맞춘다
+
+async function refinePlan(dir: string, model: string, request: string): Promise<void> {
+  const plan: Plan = JSON.parse(readFileSync(join(dir, "plan.json"), "utf8"));
+  const kf = JSON.parse(readFileSync(join(dir, "kf.json"), "utf8"));
+  const ask: Message[] = [
+    {
+      role: "system",
+      content:
+        "너는 짧은 영상의 연출 계획을 다듬는다. 장면 id·순서·시각은 바꾸지 않는다. 화면에 쓸 글 정책을 지킨다. JSON 하나로만 답한다.",
+    },
+    {
+      role: "user",
+      content: `요청: ${request}
+용도: ${plan.purpose} · ${plan.duration}초 · ${plan.aspect} · 스타일 ${plan.style} · 화면 글 정책 ${kf.text?.policy}
+장면: ${JSON.stringify(plan.scenes.map((s) => ({ id: s.id, role: s.role, dur: s.dur, idea: s.idea })))}
+생성 자산: ${JSON.stringify(plan.gen.map((g) => ({ id: g.id, kind: g.kind, scene: g.scene, prompt: g.prompt })))}
+
+다음 꼴로: {"title": "제품·주제 이름(짧게)", "line": "끝 카드 한 줄(없으면 빈 글)", "scenes": [{"id": "...", "idea": "이 요청에 맞춘 구체적인 화면·움직임 한두 문장"}], "gen": [{"id": "...", "prompt": "영어 생성 프롬프트, 글자·로고 없이"}]${captionMode(kf.captions) !== "none" ? ', "captions": [{"scene": "장면 id", "text": "그 장면에서 들릴 한국어 내레이션 — 차분한 설명체, 짧은 마디를 쉼표로, 문장은 마침표로. 목소리가 장면 길이를 정하니 1초에 4–5글자(차분한 낭독)로 장면 길이에 가깝게, 훅은 한 마디(끝 장면·이음매는 비워도 된다)"}]' : ""}}`,
+    },
+  ];
+  try {
+    // 생각하는 모델은 생각에 토큰을 먼저 쓴다 — 상한이 낮으면 답 JSON 이 잘린다
+    const r = await chat(model, ask, { json: true, temperature: 0.5, maxTokens: 16000, stage: "plan" });
+    const j = jsonBlock<{ title?: string; line?: string; scenes?: { id: string; idea: string }[]; gen?: { id: string; prompt: string }[]; captions?: { scene: string; text: string }[] }>(r.text);
+    if (!j) throw new Error(`JSON 을 못 읽었다(${r.text.length}자: ${r.text.slice(0, 160).replace(/\s+/g, " ")})`);
+    if (j.title) plan.title = kf.title = j.title;
+    for (const s of j.scenes ?? []) {
+      const p = plan.scenes.find((x) => x.id === s.id);
+      const k = kf.scenes.find((x: { id: string }) => x.id === s.id);
+      if (p && s.idea) p.idea = k.idea = s.idea;
+    }
+    for (const g of j.gen ?? []) {
+      const p = plan.gen.find((x) => x.id === g.id);
+      if (p && g.prompt) p.prompt = g.prompt;
+    }
+    (plan as Plan & { line?: string }).line = j.line ?? "";
+    if (captionMode(kf.captions) !== "none" && j.captions?.length) writeJson(join(dir, "captions.json"), j.captions);
+    writeJson(join(dir, "plan.json"), plan);
+    writeJson(join(dir, "kf.json"), kf);
+    console.error(`계획 다듬음(${model}, ${(r.ms / 1000).toFixed(1)}초): ${plan.title}`);
+  } catch (e) {
+    console.error(`계획 다듬기 건너뜀 — ${e instanceof Error ? e.message : e}`);
+  }
+}
+
+// --- 장면 쓰기: 장면마다 파일 하나를 받아 놓고, 실제로 열어 오류·이상한 글이 없을 때까지 돌려준다.
+// 장면끼리는 동시에 쓴다(모델 호출이 대부분 기다림). 열어 보기는 한 번에 하나 — 페이지는 모든 장면을 같이 싣는다.
+// 그래서 떨어진 판은 열어 본 뒤 바로 앞 파일로 되돌린다: 옆 장면의 열어 보기가 남의 깨진 판에 걸리지 않게
+
+const probing = gate(1);
+
+async function writeScenes(dir: string, model: string, ids: string[], feedback: Record<string, string> = {}): Promise<void> {
+  const brief = readFileSync(join(dir, "MAKE.md"), "utf8");
+  const kf = readProject(dir);
+  const scenes = ids.map((id) => kf.scenes.find((x) => x.id === id)).filter((s): s is NonNullable<typeof s> => !!s);
+  await pool(scenes, jobLimit(3), async (s) => {
+    const file = join(dir, s.file);
+    const before = existsSync(file) ? readFileSync(file, "utf8") : "";
+    let note = feedback[s.id] ?? "";
+    let tried = "";
+    console.error(`장면 ${s.id}: 쓰는 중 (${model})`);
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const current = tried || before;
+      const messages: Message[] = [
+        { role: "system", content: `너는 kasaframe 장면 파일을 쓴다. 아래 지시서를 지킨다. 답은 TypeScript 코드 블록 하나뿐.\n\n${brief}` },
+        {
+          role: "user",
+          content: `장면 ${s.id}(${s.file}, ${s.dur.toFixed(2)}초, 역할 ${s.role})의 파일 전체를 써라.\n할 일: ${s.idea}\n\n지금 파일:\n\`\`\`ts\n${current}\`\`\`${note ? `\n\n고칠 것:\n${note}` : ""}`,
+        },
+      ];
+      const r = await chat(model, messages, { temperature: 0.6, maxTokens: 32000, stage: `scene:${s.id}` });
+      const code = r.finish === "length" ? null : codeBlock(r.text);
+      if (r.finish === "length") {
+        note = "답이 길이 상한에서 잘렸다. 군더더기 없이 더 짧게, ```ts 블록 하나로 파일 전체를 답하라.";
+        console.error(`  ${s.id} ${attempt + 1}번째 — 답이 잘림`);
+        continue;
+      }
+      if (!code) {
+        note = "코드 블록을 못 찾았다. ```ts 블록 하나로 파일 전체를 답하라.";
+        continue;
+      }
+      tried = code;
+      const problems = await probing(async () => {
+        writeFileSync(file, code);
+        const p = await probeScene(dir, s.id);
+        if (p.length) writeFileSync(file, before);
+        return p;
+      });
+      console.error(`  ${s.id} ${attempt + 1}번째 ${(r.ms / 1000).toFixed(1)}초 — ${problems.length ? problems.join(" / ") : "통과"}`);
+      if (!problems.length) {
+        console.error(`장면 ${s.id}: 씀`);
+        return;
+      }
+      note = problems.join("\n");
+    }
+    // 세 번 다 떨어지면 앞 파일 그대로 — 깨진 판이 통째 렌더를 멈추지 않게. 마지막 판은 out/failed 에 남긴다
+    mkdirSync(join(dir, "out", "failed"), { recursive: true });
+    if (tried) writeFileSync(join(dir, "out", "failed", `${s.id}.ts`), tried);
+    console.error(`장면 ${s.id}: 실패 세 번 다 검사에 걸림 — 앞 파일 그대로(마지막 판 out/failed/${s.id}.ts)`);
+  });
+}
+
+// 렌더 전에 장면 하나를 세 시각에서 열어 본다 — 통짜 렌더 1분을 쓰기 전에 잡을 것을 잡는다
+async function probeScene(dir: string, id: string): Promise<string[]> {
+  const kf = readProject(dir);
+  const s = kf.scenes.find((x) => x.id === id)!;
+  const problems: string[] = [];
+  // 문법이 깨지면 페이지는 「__kf 를 안 걸었다」밖에 말해 주지 않는다 — 줄·칸이 붙은 오류를 먼저 돌려준다
+  try {
+    await transform(readFileSync(join(dir, s.file), "utf8"), { loader: "ts", sourcefile: s.file });
+  } catch (e) {
+    const errs = (e as { errors?: { text: string; location?: { line: number; column: number; lineText: string } }[] }).errors ?? [];
+    return errs.length ? errs.slice(0, 3).map((x) => `문법 오류 ${s.file}:${x.location?.line}:${x.location?.column} ${x.text} — ${x.location?.lineText.trim().slice(0, 120)}`) : [`문법 오류: ${e instanceof Error ? e.message : e}`];
+  }
+  let p: Awaited<ReturnType<typeof openPage>>;
+  try {
+    p = await openPage(dir);
+  } catch (e) {
+    return [`페이지가 안 열린다: ${(e instanceof Error ? e.message : String(e)).slice(0, 600)}`];
+  }
+  const errors: string[] = [];
+  p.page.on("pageerror", (e) => errors.push(e.message));
+  try {
+    for (const t of [s.from + 0.05, s.from + s.dur / 2, s.from + s.dur - 0.05]) {
+      await p.seek(t);
+      const text: string = await p.page.evaluate(() => (document.getElementById("stage") ?? document.body).innerText);
+      const bad = text.match(BAD_TEXT);
+      if (bad) problems.push(`${(t - s.from).toFixed(2)}초 화면에 "${bad[0]}" 글자가 찍힌다`);
+      const box = await p.page.evaluate(() => {
+        const out: string[] = [];
+        const W = innerWidth;
+        const H = innerHeight;
+        for (const el of Array.from(document.querySelectorAll("#stage *"))) {
+          if (!(el as HTMLElement).innerText?.trim() || el.children.length) continue;
+          const r = el.getBoundingClientRect();
+          const cs = getComputedStyle(el);
+          if (cs.opacity === "0" || cs.visibility === "hidden" || r.width === 0) continue;
+          if (r.right < 0 || r.bottom < 0 || r.left > W || r.top > H) continue;
+          if (r.left < -2 || r.top < -2 || r.right > W + 2 || r.bottom > H + 2) out.push((el as HTMLElement).innerText.trim().slice(0, 20));
+        }
+        return out;
+      });
+      if (box.length) problems.push(`${(t - s.from).toFixed(2)}초에 글이 화면 밖으로 나간다: ${box.slice(0, 3).join(", ")}`);
+    }
+  } catch (e) {
+    problems.push(`seek 중 오류: ${e instanceof Error ? e.message : e}`);
+  } finally {
+    await p.close();
+  }
+  for (const e of new Set(errors)) problems.push(`페이지 오류: ${e}`);
+  return [...new Set(problems)];
+}
+
+// 테마 후보마다 첫 장면을 그 테마로 한 장 — 사람이 셋을 나란히 보고 고른다. style.json 만 잠깐 바꿔 찍고 되돌린다
+function themeStills(dir: string, ids: string[]): void {
+  const stylePath = join(dir, "style.json");
+  const keep = readFileSync(stylePath, "utf8");
+  const motion = JSON.parse(keep).motion;
+  const kf = readProject(dir);
+  const first = kf.scenes[0];
+  const t = +(first.from + Math.min(first.dur * 0.6, 1.2)).toFixed(3);
+  try {
+    for (const id of ids) {
+      writeJson(stylePath, { ...themeStyle(id), motion });
+      const r = spawnSync(process.execPath, [kfBin, "still", dir, "--t", String(t), "--out", join(dir, "out", `theme-${id}.png`)], { stdio: "ignore" });
+      console.error(`테마 후보 ${id}: ${r.status === 0 ? `out/theme-${id}.png` : "못 찍음"}`);
+    }
+  } finally {
+    writeFileSync(stylePath, keep);
+  }
+}
+
+// --- 생성 자산: 그림은 장면을 쓰기 전에(장면이 가져다 쓴다), 영상은 장면을 다 쓴 뒤에(이음매는 앞뒤 장면의 진짜 프레임에서 뽑는다)
+
+interface GenOpts {
+  approve: boolean;
+  maxUsd: number;
+  videoProvider?: string;
+}
+
+const genLog = (l: string) => console.error(`  ${l}`);
+
+// 생성 자산도 make-stats.json 장부에 — 캐시에서 꺼낸 것은 이번에 돈을 안 썼다
+function genSpent(a: Awaited<ReturnType<typeof genImage>>, stage: string): void {
+  if (a.cached) return;
+  spend({ model: `${a.meta.provider}/${a.meta.model}`, stage, ms: a.meta.elapsedMs, prompt: 0, completion: 0, cached: 0, usd: a.meta.costUsd, og: a.meta.provider.startsWith("og-") });
+}
+
+async function genImages(dir: string): Promise<void> {
+  const plan: Plan = JSON.parse(readFileSync(join(dir, "plan.json"), "utf8"));
+  const imgs = plan.gen.filter((g) => g.kind === "img");
+  if (!imgs.length) return;
+  console.error(`생성 자산 그림 ${imgs.length}개…`);
+  // 장당 상한·고른 공급자는 그대로, 부르기만 겹친다
+  await pool(imgs, jobLimit(3), async (g) => {
+    if (g.scene) console.error(`장면 ${g.scene}: 재료 — 그림 ${g.id}`);
+    try {
+      const size = g.size ?? (plan.aspect === "9:16" ? "1080x1920" : plan.aspect === "1:1" ? "1080x1080" : "1920x1080");
+      const a = await genImage(g.id, { prompt: g.prompt, size, transparent: g.transparent, quality: g.quality, refs: g.refs?.map((r) => join(dir, r)) }, { outDir: join(dir, "assets", "gen"), log: genLog }, g.provider);
+      genSpent(a, `gen:img:${g.id}`);
+      console.error(`  gen:img:${g.id} ${a.cached ? "cached" : "made"} ${a.path} $${(a.cached ? 0 : a.meta.costUsd).toFixed(3)}`);
+    } catch (e) {
+      console.error(`  gen:img:${g.id} ${e instanceof NeedsApproval ? "needs-approval" : "error"} ${e instanceof Error ? e.message : e}`);
+    }
+  });
+}
+
+async function genVideos(dir: string, o: GenOpts): Promise<void> {
+  const plan: Plan = JSON.parse(readFileSync(join(dir, "plan.json"), "utf8"));
+  const vids = plan.gen.filter((g) => g.kind === "vid");
+  if (!vids.length) return;
+  console.error(`생성 자산 영상 ${vids.length}개…`);
+  const ctx = { outDir: join(dir, "assets", "gen"), approve: o.approve, maxUsd: o.maxUsd, log: genLog };
+  // 영상 하나마다 승인·상한(maxUsd)을 따로 본다 — 겹쳐 불러도 묻기 틀은 그대로
+  await pool(vids, jobLimit(2), async (g) => {
+    const provider = o.videoProvider ?? g.provider;
+    console.error(`장면 ${g.scene ?? g.id}: 재료 — 영상 ${g.id}`);
+    try {
+      const a = g.seam
+        ? await seam({ project: dir, scene: g.id, prompt: g.prompt, provider }, ctx)
+        : await genVideo(g.id, { prompt: g.prompt, duration: g.dur ?? 5, aspect: plan.aspect, firstFrame: g.first && join(dir, g.first), lastFrame: g.last && join(dir, g.last) }, ctx, provider);
+      genSpent(a, `gen:vid:${g.id}`);
+      console.error(`  gen:vid:${g.id} ${a.cached ? "cached" : "made"} ${a.path} $${(a.cached ? 0 : a.meta.costUsd).toFixed(3)}`);
+    } catch (e) {
+      const tail = e instanceof NeedsApproval ? `needs-approval 견적 $${e.estimateUsd.toFixed(3)}(${e.provider}) — --yes 로 승인하면 만든다, 지금은 대체 화면` : `error ${e instanceof Error ? e.message : e}`;
+      console.error(`  gen:vid:${g.id} ${tail}`);
+    }
+  });
+}
+
+// 영상 모델은 사람이 공급자를 골랐을 때(또는 --yes)만 돈을 쓴다 — 아직 묻는 중이면 견적만
+function videoApproved(plan: Partial<Plan>): boolean {
+  const v = plan.answers?.video;
+  return !!v && v !== "none" && v !== WAIT && !(plan.asks ?? []).some((q) => q.id === "video");
+}
+
+// --- 주인공 3D 샷(OG 모드): 모델이 kfb 헬퍼로 샷 스크립트를 쓰고, 몇 장 찍어 보아 돌면 굽는다. 세 번 안에 못 서면 three 로 물러난다
+
+function shotGuide(): string {
+  const lib = blenderLibDir();
+  const readme = readFileSync(join(lib, "README.md"), "utf8");
+  const how = readme.slice(readme.indexOf("## 샷 스크립트 짜기"), readme.indexOf("## 판마다 다른 곳"));
+  const api = readFileSync(join(lib, "kfb.py"), "utf8").split("\n").filter((l) => /^(def [a-z]\w*\(|class [A-Z])/.test(l)).join("\n");
+  return `${how}\n\nkfb 함수(이것만 쓴다):\n${api}\n\n예(등대 섬):\n\`\`\`python\n${readFileSync(join(lib, "shots", "lighthouse.py"), "utf8")}\n\`\`\``;
+}
+
+function blenderRun(dir: string, file: string, scene: string, id: string, extra: string[]): { ok: boolean; tail: string } {
+  const r = spawnSync(process.execPath, [kfBin, "blender", join(dir, file), "--project", dir, "--scene", scene, "--id", id, ...extra], { encoding: "utf8" });
+  const tail = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim().split("\n").slice(-25).join("\n");
+  return { ok: r.status === 0, tail };
+}
+
+async function writeShots(dir: string, model: string): Promise<void> {
+  const plan: Plan = JSON.parse(readFileSync(join(dir, "plan.json"), "utf8"));
+  const shots = (plan.shots ?? []).filter((s) => s.tool === "blender");
+  if (!shots.length) return;
+  const kf = readProject(dir);
+  const style = JSON.parse(readFileSync(join(dir, "style.json"), "utf8"));
+  const guide = shotGuide();
+  for (const shot of shots) {
+    const sc = kf.scenes.find((x) => x.id === shot.scene);
+    if (!sc) continue;
+    mkdirSync(join(dir, "shots"), { recursive: true });
+    const peek = [0.15, 0.5, 0.9].map((k) => +(sc.from + sc.dur * k).toFixed(2)).join(",");
+    let note = "";
+    let ok = false;
+    console.error(`3D 샷 ${shot.id} 쓰는 중(${model}) — 장면 ${sc.id} ${sc.dur.toFixed(2)}초`);
+    for (let attempt = 0; attempt < 3 && !ok; attempt++) {
+      const r = await chat(model, [
+        { role: "system", content: `너는 Blender 툰 3D 샷 스크립트(파이썬, tools/blender/kfb.py 헬퍼)를 쓴다. 답은 python 코드 블록 하나뿐.\n\n${guide}` },
+        {
+          role: "user",
+          content: `샷: ${shot.idea}\n장면 ${sc.id}: 프로젝트 ${sc.from.toFixed(2)}–${(sc.from + sc.dur).toFixed(2)}초(update(t) 의 t 는 프로젝트 초), 화면 ${kf.width}x${kf.height}\n색(style.json): ${JSON.stringify(style.colors ?? {})}\n글자는 넣지 않는다(장면이 위에 얹는다). 주인공 하나를 화면 가운데 크게, 쉬지 않게 박에 뛰거나 도는 물체, 카메라 열쇠는 S.downbeats·S.drops 에 두고 도착하면 선다.${note ? `\n\n고칠 것:\n${note}` : ""}`,
+        },
+      ], { temperature: 0.5, maxTokens: 16000, stage: `shot:${shot.id}` });
+      const code = codeBlock(r.text, "python|py");
+      if (!code) {
+        note = "코드 블록을 못 찾았다. ```python 블록 하나로 파일 전체를 답하라.";
+        continue;
+      }
+      writeFileSync(join(dir, shot.file), code);
+      // 스틸 몇 장은 kf still 처럼 잠금 없이 — 남의 긴 렌더 뒤에서 기다리지 않는다(굽기는 잠금을 쓴다)
+      const t = blenderRun(dir, shot.file, sc.id, shot.id, ["--still", peek, "--res", "50", "--no-lock"]);
+      ok = t.ok;
+      note = ok ? "" : `kf blender --still 이 실패했다:\n${t.tail}`;
+      console.error(`  ${shot.id} ${attempt + 1}번째 ${(r.ms / 1000).toFixed(1)}초 — ${ok ? "스틸 통과" : "실패"}`);
+    }
+    // 절반 크기·두 장에 한 장 — 무거운 렌더를 짧게(페이지가 늘려 보인다)
+    const baked = ok && blenderRun(dir, shot.file, sc.id, shot.id, ["--res", "50", "--step", "2"]).ok;
+    if (!baked) {
+      console.error(`  ${shot.id} 를 못 구웠다 — 장면 ${sc.id} 는 three.js(stage3d)로 3D 를 짓는다`);
+      plan.shots = (plan.shots ?? []).map((s) => (s.id === shot.id ? { ...s, tool: "three" } : s));
+      writeJson(join(dir, "plan.json"), plan);
+    } else console.error(`  ${shot.id} → assets/blender/${shot.id}.mp4`);
+  }
+}
+
+// --- 묻기: Claude Code 모드에서 세션이 사람에게 물은 답을 넣는다 — 질문은 plan.json 의 asks 를 지금 능력으로 다시 만들어(함수 칸까지) 고른다
+async function answerProject(dir: string, opts: Record<string, string | boolean | undefined>): Promise<number> {
+  const file = join(dir, "plan.json");
+  if (!existsSync(file)) {
+    console.error(`kf make --answer: ${dir} 에 plan.json 이 없다`);
+    return 2;
+  }
+  const plan: Plan = JSON.parse(readFileSync(file, "utf8"));
+  const waiting = new Set((plan.asks ?? []).map((q) => q.id));
+  const fresh = planQuestions(plan, await capabilities({ probe: true })).questions.filter((q) => waiting.has(q.id));
+  const settled = settle(fresh, { given: opts, yes: !!opts.yes, noGen: !!opts["no-gen"], allow: parseAllow(opts.allow) });
+  const { plan: next, stop } = applyAnswers(plan, settled.answers, fresh);
+  next.asks = (plan.asks ?? []).filter((q) => !(q.id in settled.answers));
+  writeJson(file, next);
+  if (settled.answers.theme) {
+    const was = readProject(dir).theme ?? null;
+    const now = retheme(dir, settled.answers.theme);
+    console.log(now === was ? `테마 ${now ?? "없음(프리셋)"} 그대로` : `테마 ${was ?? "없음"} → ${now ?? "없음(프리셋)"} — style.json·kf.json·장면 뼈대 DRESS 를 바꿨다`);
+  }
+  writeFileSync(join(dir, "MAKE.md"), isDirect(dir) ? directBrief(dir) : projectBrief(dir));
+  for (const [id, v] of Object.entries(settled.answers)) console.log(`${id}: ${v}`);
+  if (stop.length) {
+    console.error(`켜고 다시 부른다 —\n${stop.map((x) => `  ${x}`).join("\n")}`);
+    return 3;
+  }
+  if (next.asks.length) {
+    console.error(`아직 답이 없다: ${next.asks.map((q) => `${q.flag} <${q.choices.map((c) => c.value).join("|")}>`).join(" ")}`);
+    return 3;
+  }
+  console.log(`${dir}/MAKE.md 를 고쳐 썼다 — 답대로 그림·3D 샷·영상 컷을 만들고 장면을 채운다`);
+  return 0;
+}
+
+// 맨 위 질문의 테마 답 — kf new 가 auto 로 깐 테마를 바꾼다(plan.json·kf.json·style.json, 장면 뼈대의 DRESS 한 줄).
+// 감독 모드는 kf direct 가 kf.json 의 테마로 장면을 지으니 여기까지면 된다. 바뀐 테마 id(프리셋이면 null)를 돌려준다
+function retheme(dir: string, answer: string): string | null {
+  const plan = readPlan(dir) as Plan;
+  const kfPath = join(dir, "kf.json");
+  const kf = JSON.parse(readFileSync(kfPath, "utf8"));
+  const id: string | null = answer === "auto" ? (plan.themeCandidates?.[0]?.id ?? kf.theme ?? null) : answer === "none" ? null : answer;
+  if ((kf.theme ?? null) === id) return id;
+  const tpl = loadTemplate(plan.purpose);
+  // 프리셋으로 돌아가면 kf new 가 테마 없이 골랐을 프리셋 — 시리즈·요청 낱말·틀 차례
+  const preset = id ? null : makePlan({ request: plan.request, purpose: plan.purpose, theme: "none", series: plan.series ?? "none" }).style;
+  const style = id ? themeStyle(id) : JSON.parse(readFileSync(join(repo, "presets", `${existsSync(join(repo, "presets", `${preset}.json`)) ? preset : "neutral-dark"}.json`), "utf8"));
+  style.motion = { ...style.motion, ...tpl.motion };
+  writeJson(join(dir, "style.json"), style);
+  if (tpl.moves) {
+    const dress = pickDress(dressSeed(plan.request || plan.title, plan.purpose, id ?? preset!), plan.scenes, bundleFor(tpl.moves, id ?? undefined));
+    const byId = new Map(plan.scenes.map((s, i) => [s.id, dress[i]]));
+    for (const s of kf.scenes as { id: string; file: string; dress?: Record<string, string> }[]) {
+      const next = byId.get(s.id);
+      if (!s.dress || !next) continue;
+      const file = join(dir, s.file);
+      // 뼈대가 채운 값만 갈아 끼운다 — 세션이 손댄 줄·뼈대에 박힌 글자 값은 그대로
+      if (existsSync(file))
+        writeFileSync(file, readFileSync(file, "utf8").replace(/^const DRESS: Dress = \{.*\};$/m, (line) => Object.entries(next).reduce((l, [k, v]) => l.replace(`${k}: "${s.dress![k]}"`, `${k}: "${v}"`), line)));
+      s.dress = { ...next };
+    }
+  }
+  if (id) kf.theme = id;
+  else delete kf.theme;
+  writeJson(kfPath, kf);
+  writeJson(join(dir, "plan.json"), { ...readPlan(dir), theme: id, style: id ?? preset });
+  return id;
+}
+
+// 결과 메타 — 이 영상에 들어간 생성 자산과 회사·바깥 결과물에 걸리는 제한(H3 공개 가중치 등)을 한 파일에
+function writeCredits(dir: string, video: string): void {
+  const read = (sub: string) =>
+    existsSync(join(dir, "assets", sub))
+      ? readdirSync(join(dir, "assets", sub)).filter((f) => f.endsWith(".json")).map((f) => ({ file: join("assets", sub, f), ...JSON.parse(readFileSync(join(dir, "assets", sub, f), "utf8")) }))
+      : [];
+  const gen = read("gen").map((m) => ({ id: m.id, kind: m.kind, provider: m.provider, model: m.model, costUsd: m.costUsd, license: m.license, region: m.region, ...(m.restrict ? { restrict: m.restrict } : {}) }));
+  const blender = read("blender").map((m) => ({ id: m.file.replace(/^.*\/|\.json$/g, ""), kind: "3d", provider: "blender", model: `Blender ${m.blender}`, costUsd: 0, license: "출력물은 만든 사람 것(Blender GPL 은 출력물에 걸리지 않는다)" }));
+  const plan = existsSync(join(dir, "plan.json")) ? JSON.parse(readFileSync(join(dir, "plan.json"), "utf8")) : {};
+  const restricted = gen.filter((g) => g.restrict);
+  const credits = { video: basename(video), answers: plan.answers ?? {}, assets: [...gen, ...blender], costUsd: Number(gen.reduce((n, g) => n + (g.costUsd ?? 0), 0).toFixed(4)), restricted: restricted.map((g) => ({ id: g.id, provider: g.provider, restrict: g.restrict })) };
+  const path = join(dir, "out", `${basename(video, ".mp4")}.credits.json`);
+  writeJson(path, credits);
+  if (restricted.length) console.log(`\n제한 있는 자산 ${restricted.length}개 — 회사·바깥 결과물에 내기 전에 바꾼다:\n${restricted.map((g) => `  ${g.id}(${g.provider}): ${g.restrict}`).join("\n")}`);
+  console.log(`결과 메타: ${path}`);
+}
+
+// 이음매 장면의 모션그래픽 전환(transition3d)은 앞 장면 마지막 화면·뒤 장면 첫 화면 두 장을 받아 그 사이를 잇는다.
+// 장면을 다 쓴 뒤에 찍어야 진짜 화면이 된다 — 그림이 없으면 전환이 style 색으로 대체 화면을 그린다
+async function seamStills(dir: string, only?: string[]): Promise<void> {
+  const kf = JSON.parse(readFileSync(join(dir, "kf.json"), "utf8"));
+  const seams = (kf.scenes as { id: string; role: string }[]).filter((s) => s.role === "seam" && (!only || only.includes(s.id)));
+  if (!seams.length) return;
+  mkdirSync(join(dir, "assets", "seam"), { recursive: true });
+  for (const s of seams) {
+    const { firstFrame, lastFrame } = seamFrames(kf, s.id);
+    try {
+      if (firstFrame !== undefined) await still(dir, firstFrame, join(dir, "assets", "seam", `${s.id}-from.png`));
+      if (lastFrame !== undefined) await still(dir, lastFrame, join(dir, "assets", "seam", `${s.id}-to.png`));
+      console.error(`이음매 ${s.id}: 앞뒤 화면 두 장 찍음`);
+    } catch (e) {
+      console.error(`이음매 ${s.id}: 앞뒤 화면을 못 찍었다 — 대체 화면으로 간다(${e instanceof Error ? e.message : e})`);
+    }
+  }
+}
+
+// --- 마무리: 렌더 → 검사 → (OG 모드면) 고치기 → 표지
+
+// captions 를 주면 그 판만 화면 자막을 켜고 끈다(kf.json 은 그대로) — 굽기·검사·자막 트랙이 같은 값을 본다
+// scenes 를 주면 그 장면 둘레(그 장면 + 붙은 이음매)만 — 이음 화면·검사를 그 구간에서. 굽기는 kf render 가 바뀐 조각만 다시 찍는다
+async function finish(dir: string, o: { model: string; vision: string; fixes: number; gen?: GenOpts; captions?: "on" | "off" | "fit"; suffix?: string; scenes?: string[] }): Promise<number> {
+  if (!existsSync(join(dir, "kf.json"))) {
+    console.error(`kf make: ${dir} 에 kf.json 이 없다`);
+    return 2;
+  }
+  // 세션이 kf narrate 를 건너뛰었으면 여기서 — 목소리·곡을 깔고 장면 길이를 맞춘 뒤 굽는다
+  if (readProject(dir).voice === undefined) {
+    const code = narrateStep(dir);
+    if (code !== 0) return code;
+  }
+  if (o.gen) await genVideos(dir, o.gen);
+  const touched = o.scenes ? around(dir, o.scenes) : undefined;
+  await seamStills(dir, touched);
+  const out = join(dir, "out", `video${o.suffix ?? ""}.mp4`);
+  const capFlag = o.captions ? ["--captions", o.captions] : [];
+  let verdict = { code: 0, report: "" };
+  for (let round = 0; ; round++) {
+    if (round > 0) await seamStills(dir, touched);
+    // 굽기와 검사 사이에 잠금을 놓으면 기다리던 남의 긴 렌더가 끼어든다 — 둘을 한 번에 쥐고 자식은 잠금 없이
+    const release = await acquireRenderLock(dir, 3600);
+    const r = await relay(["render", dir, "--out", out, "--tabs", "2", "--no-lock", ...capFlag]);
+    if (r !== 0) {
+      release();
+      console.error("kf make: 렌더가 실패했다");
+      return r;
+    }
+    // 고친 둘레 + 실제로 다시 구운 조각(라이브러리·테마가 바뀌면 안 고친 장면도 다시 굽힌다) — 다 다시 구웠으면 통째 검사
+    const scope = touched && redone(out, touched);
+    for (const id of scope ?? readProject(dir).scenes.map((x) => x.id)) console.error(`장면 ${id}: 검사`);
+    verdict = scope ? checkPart(dir, scope, [...capFlag, "--no-lock"]) : check(dir, [...capFlag, "--no-lock"]);
+    release();
+    sceneVerdicts(dir, scope);
+    const review = o.vision !== "none" ? await visionReview(dir, o.vision) : {};
+    const toFix: Record<string, string> = { ...review };
+    for (const [id, note] of Object.entries(findingsByScene(dir))) toFix[id] = [toFix[id], note].filter(Boolean).join("\n");
+    // 고친 장면만 다시 굽는 길이면 고치기도 그 둘레 안에서 — 안 건드린 장면의 옛 지적으로 남의 장면을 다시 쓰지 않는다
+    if (touched) for (const id of Object.keys(toFix)) if (!touched.includes(id)) delete toFix[id];
+    // 감독 프로젝트는 kf direct 가 떨어진 장면을 다음 후보로 이미 다시 지었다 — 모델이 장면 코드를 덮어쓰지 않는다
+    if ((verdict.code === 0 && !Object.keys(review).length) || o.model === "claude-code" || isDirect(dir) || round >= o.fixes) break;
+    if (!Object.keys(toFix).length) break;
+    console.error(`고치기 ${round + 1}/${o.fixes}: ${Object.keys(toFix).join(" ")}`);
+    writeFileSync(join(dir, "MAKE.md"), projectBrief(dir));
+    await writeScenes(dir, o.model, Object.keys(toFix), toFix);
+  }
+  const subs = writeCaptions(dir, o.captions && captionMode(o.captions));
+  const cover = coverTime(dir);
+  if (!touched || touched.includes(cover.scene) || !existsSync(join(dir, "out", "cover.png")))
+    spawnSync(process.execPath, [kfBin, "still", dir, "--t", String(cover.t), "--out", join(dir, "out", "cover.png")], { stdio: "ignore" });
+  console.log(`\n${[out, join(dir, "out", "cover.png"), ...subs].join("\n")}`);
+  writeCredits(dir, out);
+  if (o.vision === "none" && !touched) lookHint(dir);
+  else if (o.vision === "none") console.log(`\n장면 모음: kf look ${dir}`);
+  if (verdict.report) console.log(`\n검사:\n${verdict.report}`);
+  return verdict.code;
+}
+
+// 틀이 내레이션·분위기 곡을 정한 용도(쇼츠·설명)만. 장면별 문장(captions.json)이 없으면 곡만 깐다
+function narrateStep(dir: string): number {
+  const tpl = loadTemplate(readProject(dir).template);
+  if (!tpl.narration?.on && !tpl.mood) return 0;
+  const lines = existsSync(join(dir, "captions.json")) ? JSON.parse(readFileSync(join(dir, "captions.json"), "utf8")) : [];
+  const plan = existsSync(join(dir, "plan.json")) ? JSON.parse(readFileSync(join(dir, "plan.json"), "utf8")) : {};
+  const voice = plan.voice ?? plan.answers?.voice;
+  // 문장이 없다고 목소리를 조용히 빼지 않는다 — 사람이 목소리를 none 으로 고른 때만 곡만 깐다
+  if (!lines.length && tpl.narration?.on && voice !== "none") {
+    console.error(`kf make: 내레이션 문장(captions.json)이 없다 — 장면별 문장을 쓰고 kf narrate ${dir}, 목소리를 빼려면 kf make --answer ${dir} --voice none`);
+    return 3;
+  }
+  const r = spawnSync(process.execPath, [kfBin, "narrate", dir], { stdio: ["ignore", "inherit", "inherit"] });
+  if (r.status !== 0) console.error("kf make: kf narrate 가 실패했다 — 위 메시지를 보고 고친 뒤 kf narrate <폴더>");
+  return r.status ?? 1;
+}
+
+// 자식 kf 의 줄을 이 프로세스 console 로 다시 찍는다 — 작업실 거울(attachStudio.mirror)은 console.error 만 봐서, 물려준 출력(inherit)은 작업실에 안 닿는다
+function relay(args: string[]): Promise<number> {
+  return new Promise((done) => {
+    const p = spawn(process.execPath, [kfBin, ...args], { stdio: ["ignore", "pipe", "pipe"] });
+    for (const [stream, out] of [[p.stdout, console.log], [p.stderr, console.error]] as const) {
+      let buf = "";
+      stream.setEncoding("utf8");
+      stream.on("data", (chunk: string) => {
+        buf += chunk;
+        const parts = buf.split(/\r?\n/);
+        buf = parts.pop() ?? "";
+        for (const l of parts) out(l);
+      });
+      stream.on("end", () => buf && out(buf));
+    }
+    p.on("close", (code) => done(code ?? 1));
+  });
+}
+
+// 폴더를 주면 kf check 가 페이지를 열어 프레임마다 훑는다 — mp4 를 OCR 하는 것보다 정확하다
+function check(dir: string, extra: string[] = []): { code: number; report: string } {
+  const r = spawnSync(process.execPath, [kfBin, "check", dir, ...extra], { encoding: "utf8" });
+  return { code: r.status ?? 1, report: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim() };
+}
+
+// 굽기 보고서(kf render 가 영상 옆에 남긴 .json)의 다시 구운 조각을 더한다. 전부면 undefined — 통째로
+function redone(video: string, touched: string[]): string[] | undefined {
+  const all = readProject(dirname(dirname(video))).scenes.map((s) => s.id);
+  let rendered: string[] = [];
+  try {
+    rendered = JSON.parse(readFileSync(video.replace(/\.[^.]+$/, ".json"), "utf8")).segments?.rendered ?? [];
+  } catch {}
+  const scope = all.filter((id) => touched.includes(id) || rendered.includes(id));
+  return scope.length === all.length ? undefined : scope;
+}
+
+// 고친 장면과 거기 붙은 이음매 — 이음매는 앞뒤 장면의 화면을 잇는다
+function around(dir: string, ids: string[]): string[] {
+  const scenes = readProject(dir).scenes;
+  const out = new Set(ids);
+  for (const [i, s] of scenes.entries()) {
+    if (!ids.includes(s.id)) continue;
+    for (const n of [scenes[i - 1], scenes[i + 1]]) if (n?.role === "seam") out.add(n.id);
+  }
+  return scenes.filter((s) => out.has(s.id)).map((s) => s.id);
+}
+
+interface CheckJson {
+  ok: boolean;
+  counts: { error: number; warn: number };
+  findings: { rule: string; severity: string; from: number; to?: number; message: string }[];
+  [k: string]: unknown;
+}
+
+// 고친 구간만 훑고 out/check.json 의 그 구간 지적만 갈아 끼운다 — 나머지 장면의 앞 검사 결과는 그대로 둔다
+function checkPart(dir: string, ids: string[], extra: string[] = []): { code: number; report: string } {
+  const scenes = readProject(dir).scenes;
+  const file = join(dir, "out", "check.json");
+  const before: CheckJson | null = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : null;
+  // 붙어 있는 장면끼리 한 구간으로 — 페이지를 여는 값이 커서 장면마다 따로 열지 않는다
+  const ranges: [number, number][] = [];
+  for (const s of scenes) {
+    if (!ids.includes(s.id)) continue;
+    const last = ranges.at(-1);
+    if (last && Math.abs(last[1] - s.from) < 1e-6) last[1] = s.from + s.dur;
+    else ranges.push([s.from, s.from + s.dur]);
+  }
+  const found: CheckJson["findings"] = [];
+  const reports: string[] = [];
+  let failed = 0;
+  let last: CheckJson | null = null;
+  for (const [a, b] of ranges) {
+    const part = join(dir, "out", "check-part.json");
+    const r = spawnSync(process.execPath, [kfBin, "check", dir, "--from", a.toFixed(4), "--to", b.toFixed(4), "--json", part, ...extra], { encoding: "utf8" });
+    reports.push(`${r.stdout ?? ""}${r.stderr ?? ""}`.trim());
+    if (r.status === 2 || !existsSync(part)) failed = 2;
+    else {
+      last = JSON.parse(readFileSync(part, "utf8"));
+      found.push(...last!.findings);
+      rmSync(part, { force: true });
+    }
+  }
+  if (failed) return { code: 2, report: reports.join("\n\n") };
+  const inside = (t: number) => ranges.some(([a, b]) => t >= a - 1e-6 && t < b - 1e-6);
+  const findings = [...(before?.findings ?? []).filter((f) => !inside(f.from)), ...found].sort((x, y) => x.from - y.from);
+  const counts = { error: findings.filter((f) => f.severity === "error").length, warn: findings.filter((f) => f.severity === "warn").length };
+  writeJson(file, { ...(before ?? last), findings, counts, ok: counts.error === 0, part: ranges });
+  return { code: counts.error ? 1 : 0, report: reports.join("\n\n") };
+}
+
+// 장면마다 검사 결과 한 줄 — 작업실 타임라인이 「끝」·「실패」로 읽는다
+function sceneVerdicts(dir: string, only?: string[]): void {
+  const file = join(dir, "out", "check.json");
+  const findings: CheckJson["findings"] = existsSync(file) ? (JSON.parse(readFileSync(file, "utf8")).findings ?? []) : [];
+  for (const s of readProject(dir).scenes) {
+    if (only && !only.includes(s.id)) continue;
+    const errs = findings.filter((f) => f.severity === "error" && f.from >= s.from - 1e-6 && f.from < s.from + s.dur);
+    console.error(errs.length ? `장면 ${s.id}: 실패 검사 오류 ${errs.length} — ${[...new Set(errs.map((f) => f.rule))].join(", ")}` : `장면 ${s.id}: 끝`);
+  }
+}
+
+// out/check.json 의 오류를 시각으로 장면에 묶는다 — 장면마다 자기 몫의 지적만 받아 다시 쓴다
+function findingsByScene(dir: string): Record<string, string> {
+  const file = join(dir, "out", "check.json");
+  if (!existsSync(file)) return {};
+  const kf = readProject(dir);
+  const report = JSON.parse(readFileSync(file, "utf8")) as { findings?: { rule: string; severity: string; from: number; to?: number; message: string }[] };
+  const out: Record<string, string[]> = {};
+  for (const f of report.findings ?? []) {
+    if (f.severity !== "error") continue;
+    const s = kf.scenes.find((x) => f.from >= x.from && f.from < x.from + x.dur) ?? kf.scenes.at(-1)!;
+    (out[s.id] ??= []).push(`[${f.rule}] 장면 안 ${(f.from - s.from).toFixed(2)}초${f.to !== undefined ? `–${(f.to - s.from).toFixed(2)}초` : ""}: ${f.message}`);
+  }
+  return Object.fromEntries(Object.entries(out).map(([k, v]) => [k, `검사(kf check):\n${v.join("\n")}`]));
+}
+
+// 그림 보는 모델을 안 부를 때 — 세션이 직접 볼 장면 모음·확인표를 만들어 경로를 찍는다
+function lookHint(dir: string): void {
+  try {
+    const s = lookSheet(dir);
+    console.log(`\n직접 볼 것: ${s.sheet}\n확인표:     ${s.checklist}`);
+  } catch (e) {
+    console.error(`장면 모음을 못 만들었다 — ${e instanceof Error ? e.message : e}`);
+  }
+  if (eyelessSession()) console.log(`그림이 안 보이는 세션이면: kf look ${dir} --vision-model ${DEFAULT_VISION}`);
+}
+
+// 장면 모음을 그림 보는 모델에 보여 주고(kf look --vision-model), 고칠 장면만 받아 온다
+async function visionReview(dir: string, model: string): Promise<Record<string, string>> {
+  try {
+    const r = await look(dir, { model });
+    console.error(formatLook(r));
+    return Object.fromEntries(r.scenes.filter((s) => !s.ok).map((s) => [s.id, `그림 검사(${model}): ${s.problems.join(" / ")}`]));
+  } catch (e) {
+    console.error(`그림 검사 건너뜀 — ${e instanceof Error ? e.message : e}`);
+    return {};
+  }
+}
+
+function coverTime(dir: string): { scene: string; t: number } {
+  const kf = readProject(dir);
+  const pick = kf.scenes.find((s) => s.role === "drop") ?? kf.scenes.find((s) => s.role === "hook" || s.role === "reveal") ?? kf.scenes[0];
+  return { scene: pick.id, t: +(pick.from + Math.min(0.8, pick.dur / 2)).toFixed(3) };
+}
+
+// --- 그 밖
+
+async function ask(choices: Purpose[]): Promise<Purpose | undefined> {
+  if (!process.stdin.isTTY) return undefined;
+  const labels = listTemplates();
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  const lines = choices.map((c, i) => `  ${i + 1}) ${c} — ${labels.find((t) => t.id === c)?.label}`).join("\n");
+  const a = await rl.question(`어떤 용도의 영상인가?\n${lines}\n번호: `);
+  rl.close();
+  return choices[Number(a) - 1];
+}
+
+// 곡을 안 줬을 때 KF_MUSIC_DIR(저작권 걱정 없는 곡 모음)에서 요청 낱말과 이름이 맞는 곡을 고른다.
+// 곡 파일 이름은 대개 영어라 한국어 장르 낱말을 영어로도 찾는다
+const GENRE: Record<string, string[]> = {
+  카와이: ["kawaii", "cute"],
+  귀여운: ["kawaii", "cute"],
+  퓨처베이스: ["future", "bass"],
+  칠: ["chill", "lofi"],
+  로파이: ["lofi", "lo-fi"],
+  몽환: ["dream", "ambient"],
+  신나는: ["upbeat", "energetic", "edm"],
+  잔잔한: ["calm", "ambient", "piano"],
+  애니: ["anime"],
+  시네마틱: ["cinematic", "epic"],
+};
+
+// 기본 곡 모음은 레포의 music/(README 에 곡마다 원본·라이선스). KF_MUSIC_DIR 이 있으면 그쪽
+const musicDir = (): string => process.env.KF_MUSIC_DIR || fileURLToPath(new URL("../../../../music/", import.meta.url));
+
+function findLibraryMusic(request: string): string | undefined {
+  const lib = musicDir();
+  if (!existsSync(lib)) return undefined;
+  const songs = listFiles(lib).filter((f) => AUDIO.test(f));
+  const words = request.toLowerCase().split(/[\s,]+/).filter((w) => w.length > 1);
+  const wanted = [...words, ...Object.entries(GENRE).filter(([k]) => request.includes(k)).flatMap(([, v]) => v)];
+  const score = (f: string) => wanted.filter((w) => basename(f, extname(f)).toLowerCase().includes(w)).length;
+  return songs.sort((a, b) => score(b) - score(a))[0];
+}
+
+function listFiles(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  if (statSync(dir).isFile()) return [dir];
+  return readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? readdirSync(join(dir, e.name)).map((f) => join(dir, e.name, f)) : [join(dir, e.name)]));
+}
+
+function stamp(): string {
+  const d = new Date();
+  const p = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}`;
+}
+
+// content.json 의 say 와 지금 깔린 목소리 문장(captions.json)이 다른 장면이 있나
+function sayChanged(dir: string, ids: string[]): boolean {
+  const read = (f: string) => (existsSync(join(dir, f)) ? JSON.parse(readFileSync(join(dir, f), "utf8")) : null);
+  const content = read("content.json") as { scenes?: { id: string; say?: string }[] } | null;
+  const lines = (read("captions.json") ?? []) as { scene?: string; text?: string }[];
+  return ids.some((id) => (content?.scenes?.find((s) => s.id === id)?.say ?? "").trim() !== lines.filter((l) => l.scene === id).map((l) => l.text?.trim() ?? "").join(" ").trim());
+}
+
+function readPlan(dir: string): Partial<Plan> & { model?: string } {
+  const p = join(dir, "plan.json");
+  return existsSync(p) ? JSON.parse(readFileSync(p, "utf8")) : {};
+}
+
+function writeJson(path: string, v: unknown): void {
+  writeFileSync(path, `${JSON.stringify(v, null, 2)}\n`);
+}