elanous 0.2.6 → 0.2.8

package/scripts/test-diet/node.ts

@@ -0,0 +1,102 @@
+#!/usr/bin/env bun
+// TD2 graph nodes: pick → measure → record. Shadow only — measures alone on a remote host and drafts a card.
+//   bun scripts/test-diet/node.ts pick|measure|record   (inside `elanous graph run graphs/test-diet/test-diet.yaml`)
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { debug } from '../../src/debug/log.js';
+import { effectiveInstanceRoot } from '../../src/instance/resolve.js';
+import { appendLedger, costTable, judge, lastLedgerLine, pickRange, writeCardDraft, type Measurement } from './lib.js';
+
+type Context = { input: Record<string, unknown>; outputs: Record<string, Record<string, unknown>> };
+function context(): Context {
+  const at = process.env.ELANOUS_GRAPH_CONTEXT;
+  if (!at) throw new Error('ELANOUS_GRAPH_CONTEXT required');
+  const raw = JSON.parse(at.trimStart().startsWith('{') ? at : readFileSync(at, 'utf8')) as Partial<Context>;
+  return { input: raw.input ?? {}, outputs: raw.outputs ?? {} };
+}
+function emit(result: Record<string, unknown> & { outcome: 'ok' | 'fail' | 'error'; summary: string }): number {
+  console.log(JSON.stringify({ verdict: result.outcome === 'ok' ? 'pass' : 'fail', ...result }));
+  return result.outcome === 'ok' ? 0 : result.outcome === 'fail' ? 1 : 2;
+}
+const git = (args: string[]) => spawnSync('git', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }).stdout ?? '';
+
+function pick(ctx: Context): number {
+  const budgetSecs = typeof ctx.input.budgetSecs === 'number' && ctx.input.budgetSecs > 0 ? ctx.input.budgetSecs : 1800;
+  const files = git(['ls-files', '*.test.ts']).split('\n').filter(Boolean).sort();
+  const costs = costTable(readFileSync(join(process.cwd(), 'docs/measurements/td1-whole-gate-mechanical-2026-10-01.tsv'), 'utf8'));
+  const last = lastLedgerLine(effectiveInstanceRoot());
+  for (const r of last?.results ?? []) costs.set(r.file, r.secs);
+  // `start` re-looks a slice on purpose; otherwise continue from the ledger cursor.
+  const startAt = typeof ctx.input.start === 'number' && ctx.input.start >= 0 ? ctx.input.start : last?.next ?? 0;
+  const range = pickRange(files, startAt, costs, budgetSecs);
+  return emit({ outcome: 'ok', summary: `test-diet pick #${range.start}~#${range.end} of ${files.length} (≈${Math.round(range.estimatedSecs)}s)`, ...range, total: files.length, budgetSecs });
+}
+
+/** One remote run: shallow clone of the mirror, one install, each file alone with its peak memory. */
+function measure(ctx: Context): number {
+  const picked = ctx.outputs.pick?.files;
+  if (!Array.isArray(picked) || picked.length === 0) return emit({ outcome: 'fail', summary: 'nothing picked' });
+  const host = typeof ctx.input.remote === 'string' ? ctx.input.remote : 'node-b';
+  const mirror = typeof ctx.input.mirror === 'string' ? ctx.input.mirror : '~/mirror/elanous-agent.git';
+  const script = [
+    'set -u', 'export PATH="$HOME/.bun/bin:$PATH"',
+    'T=$(mktemp -d)', 'trap \'rm -rf "$T"\' EXIT',
+    `git clone -q --depth 1 "file://$(eval echo ${mirror})" "$T/repo" || exit 3`,
+    // Same installs as the gate: root and apps/pwa (PWA tests import its own dependencies).
+    'cd "$T/repo" && bun install --frozen-lockfile >/dev/null 2>&1 || exit 4',
+    '(cd apps/pwa && bun install --frozen-lockfile >/dev/null 2>&1) || echo "WARN pwa-install-failed"',
+    'echo "COMMIT $(git rev-parse HEAD)"',
+    'TO=$(command -v timeout || command -v gtimeout || true)',
+    'while IFS= read -r f; do',
+    '  [ -n "$f" ] || continue',
+    '  s=$(date +%s)',
+    '  if [ -n "$TO" ]; then /usr/bin/time -l "$TO" -k 10 300 bun run scripts/test-deterministic.ts "./$f" > "$T/out" 2> "$T/err"; else /usr/bin/time -l bun run scripts/test-deterministic.ts "./$f" > "$T/out" 2> "$T/err"; fi',
+    '  rc=$?; e=$(( $(date +%s) - s ))',
+    '  rss=$(awk \'/maximum resident set size/ {printf "%d", $1/1048576}\' "$T/err")',
+    // bun test prints its summary on stderr — read both streams.
+    '  pass=$(cat "$T/out" "$T/err" | grep -E -o "^ *[0-9]+ pass" | grep -E -o "[0-9]+" | tail -1); fail=$(cat "$T/out" "$T/err" | grep -E -o "^ *[0-9]+ fail" | grep -E -o "[0-9]+" | tail -1)',
+    // A failing file names its first error, so an environment gap (e.g. no Java on the host) is not read as a test defect.
+    '  why=""; [ "$rc" -ne 0 ] && why=$(grep -v -E "^\\s*$|^bun test|^ *[0-9]+ \\||^error: *$" "$T/err" | grep -m1 -E "Unable to|Cannot find|not found|ENOENT|EACCES|rror" | tr "\\t" " " | cut -c1-160)',
+    '  printf "M\\t%s\\t%s\\t%s\\t%s\\t%s\\t%s\\t%s\\n" "$f" "$e" "${rss:-}" "$rc" "${pass:-}" "${fail:-}" "$why"',
+    'done',
+  ].join('\n');
+  const run = spawnSync('ssh', ['-o', 'BatchMode=yes', host, 'bash', '-s'], { input: `${script}\n${picked.join('\n')}\n`, encoding: 'utf8', timeout: 4 * 3600_000, maxBuffer: 16 * 1024 * 1024 });
+  // The file list follows the script on stdin; `read` in the loop consumes it.
+  if (run.status !== 0 && !String(run.stdout).includes('\nM\t')) return emit({ outcome: 'error', summary: `remote measure failed (rc=${run.status}): ${String(run.stderr).trim().slice(0, 200)}` });
+  const commit = /^COMMIT (\w+)/m.exec(run.stdout)?.[1] ?? '?';
+  const measurements: Measurement[] = String(run.stdout).split('\n').filter((l) => l.startsWith('M\t')).map((l) => {
+    const [, file, secs, rss, rc, pass, fail, why] = l.split('\t');
+    const num = (v: string | undefined) => (v === undefined || v === '' ? null : Number(v));
+    return { file: file!, secs: Number(secs), rssMb: num(rss), rc: num(rc), pass: num(pass), fail: num(fail), ...(why ? { reason: why } : {}) };
+  });
+  return emit({ outcome: measurements.length ? 'ok' : 'error', summary: `measured ${measurements.length}/${picked.length} on ${host} at ${commit.slice(0, 9)}`, host, commit, measurements });
+}
+
+function record(ctx: Context): number {
+  const p = ctx.outputs.pick;
+  const m = ctx.outputs.measure;
+  const measurements = (m?.measurements ?? []) as Measurement[];
+  if (!p || measurements.length === 0) return emit({ outcome: 'fail', summary: 'nothing measured' });
+  const results = measurements.map((x) => judge(x, Number(git(['log', '--since=90.days', '--format=%s', '--', x.file]).split('\n').filter((s) => /^fix\b/i.test(s)).length)));
+  const line = {
+    at: new Date().toISOString(), range: `#${p.start}~#${p.end}`, start: Number(p.start), end: Number(p.end), next: Number(p.next), total: Number(p.total),
+    commit: String(m?.commit ?? '?'), budgetSecs: Number(p.budgetSecs), results,
+  };
+  const root = effectiveInstanceRoot();
+  appendLedger(root, line);
+  const card = writeCardDraft(root, line);
+  const counts = { keep: results.filter((r) => r.verdict === 'keep').length, review: results.filter((r) => r.verdict === 'review').length, failing: results.filter((r) => r.verdict === 'failing').length };
+  debug.log('test-diet', 'recorded', { range: line.range, ...counts, card: card !== null });
+  return emit({ outcome: 'ok', summary: `test-diet ${line.range} · keep ${counts.keep} · review ${counts.review} · failing ${counts.failing}${card ? ' · card draft' : ''}`, range: line.range, ...counts, ...(card ? { card } : {}) });
+}
+
+if (import.meta.main) {
+  const step = process.argv[2];
+  try {
+    const ctx = context();
+    process.exitCode = step === 'pick' ? pick(ctx) : step === 'measure' ? measure(ctx) : step === 'record' ? record(ctx) : emit({ outcome: 'error', summary: `unknown step: ${step}` });
+  } catch (error) {
+    process.exitCode = emit({ outcome: 'error', summary: error instanceof Error ? error.message : String(error) });
+  }
+}

package/scripts/ux/measure-first-text.ts

@@ -0,0 +1,102 @@
+// Usage: bun scripts/ux/measure-first-text.ts --questions questions.json [--url http://127.0.0.1:3456] [--token-stdin] [--json]
+// questions.json is a nonempty JSON array of nonempty question strings. Each question starts a fresh session.
+import { readFileSync } from 'node:fs';
+
+export interface FirstTextMeasurement {
+  question: string;
+  firstTextMs: number;
+  delta: string;
+}
+
+/** Stop the clock on the first complete, nonempty text-delta SSE event, not on response headers or turn-begin. */
+export async function measureFirstText(
+  question: string,
+  url: string,
+  options: { token?: string; fetch?: typeof fetch; now?: () => number } = {},
+): Promise<FirstTextMeasurement> {
+  const fetchFn = options.fetch ?? fetch;
+  const now = options.now ?? (() => performance.now());
+  const controller = new AbortController();
+  const started = now();
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  try {
+    const response = await fetchFn(new URL('/v1/prompt/stream', url), {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        accept: 'text/event-stream',
+        ...(options.token ? { authorization: `Bearer ${options.token}` } : {}),
+      },
+      body: JSON.stringify({ userText: question }),
+      signal: controller.signal,
+    });
+    if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+    if (!response.body) throw new Error('SSE response has no body');
+    reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      // SSE separators can straddle arbitrary UTF-8 chunks (including CRLF boundaries).
+      let boundary: RegExpExecArray | null;
+      while ((boundary = /\r?\n\r?\n/.exec(buffer)) !== null) {
+        const frame = buffer.slice(0, boundary.index);
+        buffer = buffer.slice(boundary.index + boundary[0].length);
+        const event = /^event:\s*(.*)$/m.exec(frame)?.[1]?.trim();
+        const data = frame.split(/\r?\n/).filter((line) => line.startsWith('data:')).map((line) => line.slice(5).trimStart()).join('\n');
+        if (event === 'text-delta') {
+          const payload: unknown = JSON.parse(data);
+          const delta = payload && typeof payload === 'object' && 'delta' in payload ? payload.delta : undefined;
+          if (typeof delta === 'string' && delta.length > 0) {
+            return { question, firstTextMs: now() - started, delta };
+          }
+        }
+        if (event === 'error') throw new Error(`SSE error: ${data}`);
+        if (event === 'turn-end') throw new Error('Turn ended without a text-delta');
+      }
+    }
+    throw new Error('SSE stream ended without a text-delta');
+  } finally {
+    // Do not leave the daemon generating the rest of a turn after the measurement.
+    if (reader) await reader.cancel().catch(() => {});
+    controller.abort();
+  }
+}
+
+export async function run(argv: string[], deps: { fetch?: typeof fetch; now?: () => number; stdin?: () => Promise<string> } = {}): Promise<FirstTextMeasurement[]> {
+  let url = 'http://127.0.0.1:3456';
+  let questionsPath: string | undefined;
+  let json = false;
+  let tokenStdin = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--json') json = true;
+    else if (arg === '--token-stdin') tokenStdin = true;
+    else if (arg === '--url' || arg === '--questions') {
+      const value = argv[++i];
+      if (!value || value.startsWith('--')) throw new Error(`${arg} requires a value`);
+      if (arg === '--url') url = value;
+      else questionsPath = value;
+    } else throw new Error(`Unknown argument: ${arg}`);
+  }
+  if (!questionsPath) throw new Error('Usage: --questions <JSON file> [--url <base URL>] [--token-stdin] [--json]');
+  const questions: unknown = JSON.parse(readFileSync(questionsPath, 'utf8'));
+  if (!Array.isArray(questions) || !questions.length || !questions.every((q) => typeof q === 'string' && q.trim().length > 0)) {
+    throw new Error('--questions must be a nonempty JSON array of nonempty strings');
+  }
+  const token = tokenStdin ? (await (deps.stdin ?? (() => Bun.stdin.text()))()).trim() : undefined;
+  const results: FirstTextMeasurement[] = [];
+  for (const question of questions as string[]) {
+    results.push(await measureFirstText(question, url, { token, fetch: deps.fetch, now: deps.now }));
+  }
+  if (json) console.log(JSON.stringify(results));
+  else for (const result of results) console.log(`${result.firstTextMs.toFixed(1)} ms\t${result.question}`);
+  return results;
+}
+
+if (import.meta.main) {
+  try { await run(process.argv.slice(2)); }
+  catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; }
+}

package/scripts/vflow-collect.ts

@@ -22,17 +22,30 @@ const UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36';
 const OUT_DIR = process.env.VFLOW_OUT ?? join(homedir(), 'docs', 'ref', 'vflow');
 const NDJSON = join(OUT_DIR, 'prompts.ndjson');
 const URLS = join(OUT_DIR, 'urls.txt');
-const CONCURRENCY = 4;
-const GAP_MS = 120;
+// ⚠️ 2026-10-01 실측: 4병렬·120ms 로 전수를 돌리면 수백 건 뒤 사이트가 429 를 낸다(재수집 404건 중 158건).
+// 기본을 낮추고, 429 는 «없다»가 아니라 «기다려라»로 읽는다(Retry-After 를 따른다).
+const CONCURRENCY = Number(process.env.VFLOW_CONCURRENCY ?? 2);
+const GAP_MS = Number(process.env.VFLOW_GAP_MS ?? 400);
+const MAX_429_RETRIES = 5;
 
 const argv = process.argv.slice(2);
 const limitAt = argv.indexOf('--limit');
 const LIMIT = limitAt >= 0 ? Number(argv[limitAt + 1]) : Infinity;
 
+let throttled = 0;
 async function get(url: string): Promise<string> {
-  const r = await fetch(url, { headers: { 'User-Agent': UA } });
-  if (!r.ok) throw new Error(`HTTP ${r.status}`);
-  return r.text();
+  for (let attempt = 0; ; attempt++) {
+    const r = await fetch(url, { headers: { 'User-Agent': UA } });
+    if (r.status === 429 && attempt < MAX_429_RETRIES) {
+      throttled++;
+      const after = Number(r.headers.get('retry-after'));
+      const waitMs = Number.isFinite(after) && after > 0 ? after * 1000 : 5000 * 2 ** attempt;
+      await new Promise((res) => setTimeout(res, waitMs));
+      continue;
+    }
+    if (!r.ok) throw new Error(`HTTP ${r.status}`);
+    return r.text();
+  }
 }
 
 /** 사이트맵 전수 → 영문 `/prompts/` URL. ⛔ 번역판(`/{lang}/prompts/`)은 «같은 내용»이라 뺀다. */
@@ -166,14 +179,14 @@ async function main(): Promise<void> {
       catch { failed++; return null; }                  // ⛔ 「없다」가 아니라 «못 받았다»
     }));
     for (const r of rows) { if (r) { appendFileSync(NDJSON, JSON.stringify(r) + '\n'); ok++; } else noLd++; }
-    if ((i / CONCURRENCY) % 25 === 0) console.log(`  … ${ok + noLd}/${todo.length}  ok=${ok} 건너뜀=${noLd}`);
+    if ((i / CONCURRENCY) % 25 === 0) console.log(`  … ${ok + noLd}/${todo.length}  ok=${ok} 못받음=${failed} jsonld없음=${noLd - failed} 429대기=${throttled}`);
   }
   // ⛔ 수를 «도구가» 낸다 — 사람이 세지 않는다.
   writeFileSync(join(OUT_DIR, 'MANIFEST.txt'),
     [`source: https://vflow.live (robots: Allow: / · 2026-09-23 확인)`,
      `fetched: ${new Date().toISOString()}`,
      `urls_total: ${urls.length}`, `rows_ok: ${ok + done.size}`,
-     `skipped_no_jsonld: ${noLd - failed}`, `failed_fetch: ${failed}`,
+     `skipped_no_jsonld: ${noLd - failed}`, `failed_fetch: ${failed}`, `throttled_429_retries: ${throttled}`,
      `schema: url model category slug name description prompt keywords[] datePublished author authorUrl sourcePost thumb spec{duration,camera[],lighting[],mood[],difficulty,promptLanguage,includes[]} video{url,isoDuration,resolution,aspect}`,
      `refetch: bun scripts/vflow-collect.ts`, ''].join('\n'));
   console.log(`\n  ✅ ok ${ok} · 건너뜀 ${noLd - failed} · 못 받음 ${failed}  →  ${NDJSON}`);

package/scripts/vflow-search.ts

@@ -0,0 +1,73 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { searchVflowReferences, type VflowQuery } from '../src/video-pipeline/vflow-reference.js';
+
+const args = process.argv.slice(2);
+let file = join(homedir(), 'docs', 'ref', 'vflow', 'prompts.ndjson');
+const query: { -readonly [K in keyof VflowQuery]: VflowQuery[K] } = { limit: 5 };
+let json = false;
+const techniques: string[] = [];
+const terms: string[] = [];
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i]!;
+  if (arg === '--json') { json = true; continue; }
+  if (['--file', '--model', '--technique', '--category', '--limit', '--camera', '--lighting', '--mood', '--max-seconds'].includes(arg)) {
+    const value = args[++i];
+    if (!value || value.startsWith('--')) {
+      console.error(`값이 필요한 옵션: ${arg}`);
+      process.exit(1);
+    }
+    switch (arg) {
+      case '--file': file = value; break;
+      case '--model': query.model = value; break;
+      case '--technique': techniques.push(value); break;
+      case '--category': query.category = value; break;
+      case '--camera': query.camera = value; break;
+      case '--lighting': query.lighting = value; break;
+      case '--mood': query.mood = value; break;
+      case '--limit': {
+        const parsed = Number(value);
+        if (!Number.isSafeInteger(parsed) || parsed < 0) {
+          console.error(`--limit 은 0 이상의 정수여야 합니다: ${value}`);
+          process.exit(1);
+        }
+        query.limit = parsed;
+        break;
+      }
+      case '--max-seconds': {
+        const parsed = Number(value);
+        if (!Number.isFinite(parsed) || parsed < 0 || !value.trim()) {
+          console.error(`--max-seconds 은 0 이상의 숫자여야 합니다: ${value}`);
+          process.exit(1);
+        }
+        query.maxSeconds = parsed;
+        break;
+      }
+    }
+  } else if (arg.startsWith('--')) {
+    console.error(`알 수 없는 옵션: ${arg}`);
+    process.exit(1);
+  } else {
+    terms.push(arg);
+  }
+}
+query.terms = terms;
+query.techniques = techniques;
+const result = searchVflowReferences(file, query);
+if (!result.available) {
+  console.error(`입력 파일을 읽을 수 없습니다: ${file} (${result.reason})`);
+  process.exit(1);
+}
+if (json) {
+  console.log(JSON.stringify(result.rows.map(({ url, model, category, name, prompt, keywords, author, authorUrl, video }) =>
+    ({ url, model, category, name, prompt, keywords, author, authorUrl, video: video ?? null }))));
+  if (result.matches === 0) console.error(`일치 0 · 읽은 줄 ${result.read}`);
+} else if (result.matches === 0) {
+  console.log(`일치 0 · 읽은 줄 ${result.read}`);
+} else {
+  for (const row of result.rows) {
+    console.log(`${row.name} · ${row.model}\n${row.url}\n${row.author ?? ''}\n${row.prompt.slice(0, 240)}${row.video?.url ? `\n${row.video.url}` : ''}`);
+  }
+}
+if (result.skipped) console.error(`건너뛴 줄 ${result.skipped}`);

package/scripts/video-free-line-test-walker.ts

@@ -0,0 +1,36 @@
+import { readFileSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+import type { GraphSpecLike, WalkerApi } from '../src/video-pipeline/walk-line.js';
+
+interface TestGraph extends GraphSpecLike {
+  entry_node: string;
+  terminal_nodes: string[];
+  nodes: ({ node_id: string; recipe?: string; max_visits?: number })[];
+}
+
+export const readGraphSpec: WalkerApi['readGraphSpec'] = (path) => {
+  try { return { spec: parseYaml(readFileSync(path, 'utf8')) as TestGraph }; }
+  catch (e) { return { error: (e as Error).message }; }
+};
+
+export const walkGraph: WalkerApi['walkGraph'] = async (graph, step, opts) => {
+  const spec = graph as TestGraph;
+  const visits = new Map<string, number>();
+  const steps: { node: string; visit: number }[] = [];
+  let next = spec.entry_node;
+  while (steps.length < opts.maxSteps) {
+    const node = spec.nodes.find((n) => n.node_id === next);
+    if (!node) return { terminal: null, stopReason: 'no-node', steps };
+    const visit = (visits.get(next) ?? 0) + 1;
+    if (visit > (node.max_visits ?? 1)) return { terminal: null, stopReason: 'budget-exceeded', steps };
+    visits.set(next, visit);
+    steps.push({ node: next, visit });
+    if (spec.terminal_nodes.includes(next)) return { terminal: next, stopReason: 'terminal', steps };
+    const outcome = await step(node);
+    if (outcome === null) { next = opts.unobservedNode; continue; }
+    const edge = spec.edges.find((e) => e.from === next && (e.to !== undefined || e.map?.[outcome] !== undefined));
+    if (!edge) return { terminal: null, stopReason: 'no-edge', steps };
+    next = edge.to ?? edge.map![outcome]!;
+  }
+  return { terminal: null, stopReason: 'budget-exceeded', steps };
+};

package/scripts/video-pipeline.ts

@@ -998,9 +998,8 @@ async function plan() {
     return where.length ? `${u} → 구간을 «${where.join('/')}» 까지` : `${u} → ⛔ 스핀 결손`;
   });
 
-  sayUnprobed();
-
   if (COMPACT) {
+    sayUnprobed();
     // ⛔ 노드별로 찍지 않는다 — encode 가 세 번 나온다. 능력 단위로 «접는다».
     const seen = new Map<string, { impl?: Impl; required: boolean }>();
     for (const o of out) for (const p of o.picks) {
@@ -1138,6 +1137,7 @@ async function plan() {
     return;
   }
 
+  sayUnprobed();
   console.log(`\n🧱 추천 스택 — 구간 ${nodes[0].id} → ${nodes[nodes.length - 1].id} · 선호 ${TIER_MARK[prefer]}`);
   console.log(`   설정: ${LOADED.source}${MACHINE ? ` · 기계 «${MACHINE_NAME}»` : ''}`);
   if (MISSING.size) console.log(`   ⚠️ 없다고 «가정»한 것: ${[...MISSING].join(', ')}`);

package/skills/explainer-video/SKILL.md

@@ -35,7 +35,7 @@ The grammar of a chapter (take it from the reference, don't improvise):
 
 The outro gives one line that sums everything up, then the CTA.
 
-⛔ Every claim must trace to a merged change or a measured run, listed in `sources`. Don't write «fully autonomous», dates you can't promise, or comparisons (`docs/marketing/GUIDE-launch-tone-and-banned-claims-*`).
+⛔ Every claim must trace to a merged change or a measured run, listed in `sources`. Don't write «fully autonomous», dates you can't promise, or comparisons with other products.
 
 ## 2. Voice — `bun $SKILL/engine/vo.ts <project>/script.json`
 
@@ -85,7 +85,7 @@ The reference supplies the **grammar** (components and staging), never its colou
 - **Text**: `#F2F1EE`.
 - **Motif**: the V6 «엘랑 소용돌이» mark (`engine/brand/`), used in three places — a slow, faint rotation behind the scene, the header, and the chapter cards.
 
-Why these choices, what the reference does, and what we can and cannot reproduce: `내부 문서 `RESEARCH-explainer-video-reference-decomposition-2026-09-30``.
+The reference is used only for its structure (header, chapter cards, a diagram that moves one step per line, keyword-timed captions). Its colours, artwork and voice are not reproduced.
 
 ## Field reel — photos from the venue → a vertical video in about a minute
 
@@ -95,13 +95,16 @@ zsh $SKILL/engine/reel.sh <folder> --title "마케터의 밤" --sub "2026.10.02
 
 - **Input**: a folder of phone photos (jpg · png · heic) and short clips (mp4 · mov). The default upload folder is `~/.elanous/field/<event>/`.
 - **Order**: by capture time (`mdls` creation date), then by file name.
-- **Captions**: optional `<folder>/captions.txt`, one line per item as `파일명 | 자막`. Items without a line get no caption.
+- **Captions**: optional `<folder>/captions.txt`, one line per item as `파일명 | 자막`. A photo without a line gets one line from a vision model (`codex exec -i`, all photos in parallel, 30 s cap each); if that fails it shows «현장 N». `FIELD_REEL_VISION=0` turns the vision step off.
+- **Title**: `--title`, or `title.txt` through the daemon. A slug-like title (`field-2026-10-01`) is replaced by a vision headline read from the first three photos (event or company names on screen first). The date line defaults to the first photo's capture date (KST).
+- **Music**: `FIELD_REEL_BGM=<file>` or `~/.cache/elanous-explainer/bgm/field.wav` — cut to length, faded in and out, leveled to about −16 LUFS. No file means no music. Use only licensed tracks (the default cache holds an Epidemic Sound download); the file is never committed.
 - **Output**:
-  - `<folder>/reel/reel-9x16.mp4` at 1080×1920, 30–60 s.
-  - A black title card, then each item: photos for 3.5 s with a slow zoom, clips for their first 5 s.
-  - One caption line per item, the V6 header, an Icarus Red progress bar, and an end card with elanous.ai.
-- **Fitting to length**: over 60 s drops items from the middle, keeping the first and last. Under 30 s stretches the photos.
-- **Measured**: 7 items → 31.2 s video in 56–83 s end to end (M-series Mac, `hyperframes render`).
+  - `<folder>/reel/reel-9x16.mp4` at 1080×1920, 24–60 s.
+  - An intro card (kicker, mark, title word by word, red rule, date), then each item: photos for about 4–6 s. A landscape photo is shown whole over a blurred fill of itself; a portrait photo fills the frame. Each move overlaps the next with a slide and a red wipe on the cut.
+  - Per item a counter (`01 / 03`), the caption rising word by word, and a red rule. The V6 header, an Icarus Red progress bar, and an end card with elanous.ai.
+  - `--part body` renders the photos only (no cards, no music) — for an instant version that stitches pre-rendered cards around it.
+- **Fitting to length**: over 60 s drops items from the middle, keeping the first and last. Under 24 s stretches the photos.
+- **Measured**: 3 photos → 24 s video in 28 s end to end, of which vision 8.7 s and render 15.9 s (M-series Mac, 10-01). Earlier: 7 items → 31.2 s video in 56–83 s.
 - **Before posting**: people's faces need their consent. Run the same 1 fps OCR check as any public video.
 
 ## Graph
@@ -114,4 +117,4 @@ zsh $SKILL/engine/reel.sh <folder> --title "마케터의 밤" --sub "2026.10.02
   - speech mismatch → vo;
   - bad script → script;
   - public release → needs-human.
-- **Not coded yet**: the `explainer-*` recipes. Until they are, you run these steps from this skill.
+- **Recipes**: the `explainer-*` recipes are in the elanous core, but `graph run` does not yet accept this graph's terminal nodes. The video-explainer plugin therefore ships the skill and nodes only; run these steps from this skill. The graph comes with plugin 0.2.0.

package/skills/explainer-video/engine/build.mjs

@@ -22,7 +22,7 @@ const W = 1920, H = 1080, FPS = 30;
 // ── palette (Elanvital CI · RCBC guide) ─────────────────────────────────────────
 const C = { deep: "#1D2751", deep2: "#141C3D", black: "#000000", ink: "#F2F1EE", red: "#E95047", muted: "rgba(242,241,238,0.62)", line: "rgba(242,241,238,0.86)", faint: "rgba(242,241,238,0.10)" };
 
-// ── mark (V6 «엘랑 소용돌이», docs/brand/icon) ───────────────────────────────────
+// ── mark (V6 «엘랑 소용돌이», engine/brand/) ─────────────────────────────────────
 const markSrc = readFileSync(process.env.ELANOUS_MARK ?? join(here, "brand", "elanous-mark-on-dark.svg"), "utf8");
 const markPaths = [...markSrc.matchAll(/<path d="([^"]*)"/g)].map((m) => m[1]);
 const mark = (size, blade = C.ink, dot = C.red, cls = "") =>