explainer-video 0.0.0-stage → 0.4.0

package/skills/explainer-video-from-codebase/tools/flow-diagram.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/* =============================================================================
+   flow-diagram.mjs — the skeleton of a flow's diagram, generated from the
+   validated flows, so its boxes and arrows are the code's and not a guess.
+
+   Usage:
+     node tools/flow-diagram.mjs --flows out/<name>/flows.validated.json --as map [--flow <id>]
+     node tools/flow-diagram.mjs --flows out/<name>/flows.validated.json --flow <id> --as sequence
+     node tools/flow-diagram.mjs --flows out/<name>/flows.validated.json --flow <id> --as exercises
+
+   Prints JSON (design §4.6); the agent adds the layout polish and the beats:
+     map        a `diagram` host config: one box per module the hops run through
+                (every series item, or one with --flow), its hops as members, an
+                arrow per call between modules; `crossings` lists the queue, HTTP
+                and spawn hand-offs with their evidence (for banners).
+     sequence   `svg` lane params for SceneCore.primitives.sequence: the caller
+                (the entry's route, queue key or command) and each module as a
+                participant, one message per hop, kind call / queue / http / spawn.
+     exercises  a `diagram` host config for an eval or dev flow: its hops as the
+                harness lane on the left, each production flow it drives as one
+                named box with its video number ("see video 8"), and the crossing
+                between them; the production flow is never re-drawn.
+
+   The video number comes from plan.json beside the validated flows when it was
+   planned from this exact file, else from the same planner at the default cap.
+
+   Exit: 0 ok · 1 bad flags, unreadable inputs, an unknown flow, or exercises on a
+         flow with no `exercises` hop
+   ========================================================================== */
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+import { planVideos } from './lib/decompose.mjs';
+
+const fail = (code, msg) => { console.error(`[flow-diagram] ${msg}`); process.exit(code); };
+
+/* ---------------- args ---------------- */
+const argv = process.argv.slice(2);
+const VALUED = new Set(['--flows', '--flow', '--as']);
+const flags = new Map();
+for (let i = 0; i < argv.length; i++) {
+  if (VALUED.has(argv[i])) { if (argv[i + 1] == null) fail(1, `${argv[i]} needs a value`); flags.set(argv[i], argv[++i]); }
+  else fail(1, `unknown argument ${argv[i]}`);
+}
+const AS = flags.get('--as');
+if (!flags.has('--flows') || !['map', 'sequence', 'exercises'].includes(AS)) fail(1, 'usage: flow-diagram.mjs --flows out/<name>/flows.validated.json --as map|sequence|exercises [--flow <id>]');
+if (AS !== 'map' && !flags.has('--flow')) fail(1, `--as ${AS} draws one flow: pass --flow <id>`);
+const VALIDATED = resolve(flags.get('--flows')), OUT = dirname(VALIDATED);
+const sha = t => createHash('sha256').update(t).digest('hex');
+const readText = (f, what) => { try { return readFileSync(f, 'utf8'); } catch (e) { fail(1, `cannot read ${what} ${f}: ${e.message}`); } };
+const text = readText(VALIDATED, 'the validated flows');
+let v;
+try { v = JSON.parse(text); } catch (e) { fail(1, `${VALIDATED} is not valid JSON: ${e.message}`); }
+if (v?.schema !== 1 || v.tool?.name !== 'apply-flows.mjs' || v.ok !== true) fail(1, `${VALIDATED} is not a passing apply-flows.mjs output (schema 1)`);
+const items = new Map([...v.flows, ...v.cores].map(x => [x.id, x]));
+const one = flags.get('--flow');
+if (one != null && !items.has(one)) fail(1, `no flow or core "${one}" in ${VALIDATED} (have: ${[...items.keys()].join(', ')})`);
+
+const moduleOf = sym => sym.split(':')[0];
+// `pkg.mod.leaf` -> `mod.leaf`; a TS/JS module (a path) -> its last two path parts
+const shortName = mod => mod.includes('/') ? mod.split('/').slice(-2).join('/') : mod.split('.').slice(-2).join('.');
+const COLOR = { queue: 'hub', http: 'ok', spawn: 'bad' };
+const CROSS = new Set(Object.keys(COLOR));
+// the call that brings a hop in: the first downward step of its connection (the walk returns up, then calls down)
+const callIn = h => (h.connection?.steps || []).find(s => s.down) || null;
+const crossKind = h => (h.connection?.steps || []).find(s => s.down && CROSS.has(s.kind))?.kind || null;
+
+// the video a flow is narrated in: plan.json when planned from this file, else the planner at its default cap
+function videoOf(id) {
+  const planPath = join(OUT, 'plan.json');
+  if (existsSync(planPath)) {
+    const plan = JSON.parse(readText(planPath, 'the plan'));
+    if (plan.inputs?.validated?.sha256 === sha(text)) return { video: plan.videos.find(x => x.group === id)?.index ?? null, videoFrom: 'plan.json' };
+  }
+  return { video: planVideos(v, {}).videos.find(x => x.group === id)?.index ?? null, videoFrom: 'estimate (no plan.json from this file)' };
+}
+
+// n row positions from top to bottom, one centred row when n is 1
+const spread = (n, top, bottom) => Array.from({ length: n }, (_, r) => Math.round(n === 1 ? (top + bottom) / 2 : top + r * (bottom - top) / (n - 1)));
+// a grid the agent will re-lay: three columns, rows as needed
+const grid = n => {
+  const cols = Math.min(3, Math.max(1, n)), rows = Math.ceil(n / cols);
+  const xs = cols === 1 ? [960] : cols === 2 ? [600, 1320] : [340, 960, 1580];
+  return { columns: Object.fromEntries(xs.map((x, i) => [`c${i}`, { x }])), rows: spread(rows, 260, 940), at: i => ({ column: `c${i % cols}`, row: Math.floor(i / cols) }) };
+};
+
+/* ---------------- map ---------------- */
+function map() {
+  const chosen = one ? [items.get(one)] : v.series.map(s => items.get(s.id));
+  const mods = new Map();   // module -> { hops, group }
+  const add = h => { const m = moduleOf(h.symbol); if (!mods.has(m)) mods.set(m, { hops: [], group: h.group }); if (!mods.get(m).hops.includes(h.name)) mods.get(m).hops.push(h.name); };
+  for (const it of chosen) for (const h of it.hops) add(h);
+  const ids = new Map([...mods.keys()].map((m, i) => [m, `m${i}`]));
+  const g = grid(mods.size);
+  const nodes = [...mods].map(([m, x], i) => ({ id: ids.get(m), kind: 'box', ...g.at(i), label: shortName(m), stereotype: `${m} · ${x.group}`,
+    members: x.hops.length > 6 ? [...x.hops.slice(0, 5), `+${x.hops.length - 5} more`] : x.hops }));
+  const edges = new Map(), crossings = [];
+  for (const it of chosen) for (const h of it.hops) {
+    for (const s of (h.connection?.steps || []).filter(s => s.down)) {
+      const a = moduleOf(s.from), b = moduleOf(s.to);
+      if (!ids.has(a) || !ids.has(b) || a === b) continue;
+      const k = `${a}>${b}`;
+      if (!edges.has(k) || CROSS.has(s.kind)) edges.set(k, { id: `e${edges.size}`, from: ids.get(a), to: ids.get(b), arrow: true, color: COLOR[s.kind] || 'client' });
+      if (CROSS.has(s.kind)) crossings.push({ item: it.id, hop: h.index, from: s.from, to: s.to, kind: s.kind, evidence: s.evidence || null });
+    }
+    const x = h.exercises ? h.drive : null;
+    if (x && ids.has(moduleOf(x.to))) {
+      const a = moduleOf(h.symbol), b = moduleOf(x.to);
+      edges.set(`${a}>${b}`, { id: '', from: ids.get(a), to: ids.get(b), arrow: true, color: COLOR[x.kind] || 'client' });
+      crossings.push({ item: it.id, hop: h.index, from: h.symbol, to: x.to, kind: x.kind, evidence: x.evidence, exercises: h.exercises });
+    }
+  }
+  [...edges.values()].forEach((e, i) => { e.id = `e${i}`; });
+  return { host: 'diagram', as: 'map', flow: one || null, items: chosen.map(x => x.id),
+    config: { layout: { columns: g.columns, rows: g.rows }, nodes, edges: [...edges.values()] }, crossings };
+}
+
+/* ---------------- sequence ---------------- */
+function callerLabel(it) {
+  const e = it.entry;
+  if (!e) return { label: 'caller', sub: it.kind === 'core' ? 'shared code: called from several flows' : null };
+  if (e.kind === 'http') return { label: `${e.method} ${e.path}`, sub: 'HTTP request' };
+  if (e.kind === 'ui-route') return { label: e.path, sub: 'page in the browser' };
+  if (e.kind === 'queue-consumer' || e.kind === 'scheduled') return { label: e.key, sub: e.kind === 'scheduled' ? 'schedule' : 'queue message' };
+  if (e.kind === 'main' || e.kind === 'cli') return { label: e.file, sub: 'command line' };
+  return { label: e.kind, sub: e.file };
+}
+function sequence() {
+  const it = items.get(one);
+  const parts = [{ id: 'caller', ...callerLabel(it) }];
+  const pid = new Map();
+  const part = mod => { if (!pid.has(mod)) { pid.set(mod, `p${pid.size}`); parts.push({ id: pid.get(mod), label: shortName(mod), sub: shortName(mod) === mod ? null : mod }); } return pid.get(mod); };
+  const messages = [];
+  const entryKind = it.entry?.kind === 'http' ? 'http' : it.entry?.kind === 'queue-consumer' ? 'queue' : 'call';
+  for (const h of it.hops) {
+    const to = part(moduleOf(h.symbol)), c = callIn(h);
+    const from = c ? part(moduleOf(c.from)) : 'caller';
+    messages.push({ from, to, label: h.name, kind: crossKind(h) || (c ? 'call' : entryKind), hop: h.index, via: Math.max(0, (h.connection?.steps || []).filter(s => s.down).length - 1) });
+  }
+  for (const h of it.hops.filter(x => x.exercises)) {
+    const tgt = items.get(h.exercises), vid = videoOf(h.exercises);
+    const id = `flow:${h.exercises}`;
+    if (!parts.some(p => p.id === id)) parts.push({ id, label: tgt.title, sub: vid.video ? `see video ${vid.video}` : 'a production flow' });
+    messages.push({ from: part(moduleOf(h.symbol)), to: id, label: `drives ${h.exercises}`, kind: h.drive.kind, hop: h.index, via: 0 });
+  }
+  return { host: 'svg', as: 'sequence', flow: it.id, primitive: 'sequence',
+    params: { x: 160, y: 170, w: 1600, h: 800, at: 0, participants: parts, messages } };
+}
+
+/* ---------------- exercises ---------------- */
+// how an eval or dev hop drives the production flow it names is apply-flows' `drive`: {kind, to, evidence}
+function exercises() {
+  const it = items.get(one);
+  const drives = it.hops.filter(h => h.exercises);
+  if (!drives.length) fail(1, `${one} has no hop that exercises a production flow: --as exercises draws an eval or dev flow's hand-off`);
+  const targets = [...new Set(drives.map(h => h.exercises))];
+  const ys = spread(Math.max(it.hops.length, targets.length), 220, 900);
+  const links = drives.map(h => ({ hop: h.index, symbol: h.symbol, target: h.exercises, targetTitle: items.get(h.exercises).title, ...videoOf(h.exercises), ...h.drive }));
+  const nodes = [
+    ...it.hops.map((h, i) => ({ id: `h${h.index}`, kind: 'box', column: 'harness', row: i, label: h.name, stereotype: `${it.group} · hop ${h.index}`, size: { w: 420, h: 96 } })),
+    ...targets.map((t, i) => { const l = links.find(x => x.target === t); return { id: `flow:${t}`, kind: 'box', column: 'production', row: i, label: t, stereotype: 'production flow', members: [l.video ? `see video ${l.video}` : 'not in this series'], sub: items.get(t).title }; }),
+  ];
+  const edges = links.map((l, i) => ({ id: `x${i}`, from: `h${l.hop}`, to: `flow:${l.target}`, arrow: true, color: COLOR[l.kind] || 'client' }));
+  return { host: 'diagram', as: 'exercises', flow: it.id, exercises: links,
+    config: { layout: { columns: { harness: { x: 440 }, production: { x: 1420 } }, rows: ys }, nodes, edges } };
+}
+
+console.log(JSON.stringify(AS === 'map' ? map() : AS === 'sequence' ? sequence() : exercises(), null, 2));

package/skills/explainer-video-from-codebase/tools/flow-plan.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/* =============================================================================
+   flow-plan.mjs — turn an approved, validated flow list into a video plan in
+   the coursework plan's shape, so the per-video stages 3–8 run unchanged.
+
+   Usage:
+     node tools/flow-plan.mjs --flows out/<name>/flows.validated.json [--max-min 25] [--estimate] [--force]
+
+   Refuses (exit 5) unless flows.approved.json beside it carries the sha256 of
+   this flows.validated.json, and flows.json has not changed since it was
+   validated: no plan, and so no script, exists before the user approves the
+   list, and any later edit needs a new approval. --estimate prints the plan
+   without writing it and without an approval (the approval table's estimate).
+
+   The plan: one overview video, then each series flow and core in series order,
+   split under the cap (lib/decompose.mjs). Each video carries `group` (its flow
+   or core id), `sections` ("<file> :: <symbol> @L<start>", what a script's
+   `covers` must name) and `sectionSpans` with each hop's cited tests. The plan
+   lists `forms` (overview, flow, core) for apply-enrichment, and the approval.
+   Coverage (C4): every kept hop is assigned to exactly one video.
+
+   Exit: 0 ok · 1 bad flags or unreadable input · 2 an orphaned hop or a video over
+         the cap · 4 would overwrite the plan an enriched plan was built from ·
+         5 no matching approval
+   ========================================================================== */
+import { readFileSync, writeFileSync, existsSync, realpathSync } from 'node:fs';
+import { join, resolve, dirname, sep, relative } from 'node:path';
+import { createHash } from 'node:crypto';
+import { MODEL, planVideos } from './lib/decompose.mjs';
+
+const fail = (code, msg) => { console.error(`[flow-plan] ${msg}`); process.exit(code); };
+
+/* ---------------- args ---------------- */
+const argv = process.argv.slice(2);
+const VALUED = new Set(['--flows', '--max-min']), BOOL = new Set(['--estimate', '--force']);
+const flags = new Map();
+for (let i = 0; i < argv.length; i++) {
+  if (VALUED.has(argv[i])) { if (argv[i + 1] == null) fail(1, `${argv[i]} needs a value`); flags.set(argv[i], argv[++i]); }
+  else if (BOOL.has(argv[i])) flags.set(argv[i], true);
+  else fail(1, `unknown argument ${argv[i]}`);
+}
+if (!flags.has('--flows')) fail(1, 'usage: flow-plan.mjs --flows out/<name>/flows.validated.json [--max-min 25] [--estimate] [--force]');
+const maxMin = flags.has('--max-min') ? Number(flags.get('--max-min')) : 25, minMin = 2.5;
+if (!(maxMin > 0)) fail(1, '--max-min must be a positive number of minutes');
+const VALIDATED = resolve(flags.get('--flows')), OUT = dirname(VALIDATED);
+const sha = t => createHash('sha256').update(t).digest('hex');
+let text, v;
+try { text = readFileSync(VALIDATED, 'utf8'); v = JSON.parse(text); } catch (e) { fail(1, `cannot read the validated flows ${VALIDATED}: ${e.message}`); }
+if (v?.schema !== 1 || v.tool?.name !== 'apply-flows.mjs' || v.ok !== true) fail(1, `${VALIDATED} is not a passing apply-flows.mjs output (schema 1)`);
+if (v.root && existsSync(v.root)) { const root = realpathSync(v.root), o = realpathSync(OUT); if (o === root || o.startsWith(root + sep)) fail(1, `refusing to write inside the repo: ${OUT}`); }
+const estimate = flags.has('--estimate');
+
+/* ---------------- the approval (design §4.4b) ---------------- */
+const APPROVED = join(OUT, 'flows.approved.json');
+let approval = null;
+const refuse = msg => estimate ? console.log(`[flow-plan] estimate only: ${msg}`) : fail(5, `${msg}\n  Show the user the approval table in flows.md and, on their explicit yes, run approve-flows. No plan was written.`);
+const flowsFile = join(OUT, v.inputs.flows.file);
+if (existsSync(flowsFile) && sha(readFileSync(flowsFile, 'utf8')) !== v.inputs.flows.sha256)
+  refuse(`${v.inputs.flows.file} changed since apply-flows validated it: rerun apply-flows; the edited list needs a new approval.`);
+else if (!existsSync(APPROVED)) refuse('no flows.approved.json: the user has not approved this flow list.');
+else {
+  try { approval = JSON.parse(readFileSync(APPROVED, 'utf8')); } catch (e) { refuse(`flows.approved.json is not valid JSON: ${e.message}`); }
+  if (approval && approval.flowsHash !== sha(text)) {
+    refuse(`flows.approved.json approves a different flow list (sha256 ${String(approval.flowsHash).slice(0, 12)}…, this one is ${sha(text).slice(0, 12)}…): the list changed after the approval.`);
+    approval = null;
+  }
+}
+
+/* ---------------- plan ---------------- */
+const p = planVideos(v, { maxMin, minMin });
+const plan = {
+  generatedFrom: flags.get('--flows'), kind: 'codebase', root: v.root, commit: v.commit, treeHash: v.treeHash,
+  model: { ...MODEL, maxVideoMin: maxMin, minVideoMin: minMin },
+  forms: ['overview', 'flow', 'core'],
+  approval: approval && { by: approval.approvedBy, at: approval.at, note: approval.note, flowsHash: approval.flowsHash },
+  inputs: { ...v.inputs, validated: { file: relative(OUT, VALIDATED), sha256: sha(text) } },
+  totals: p.totals, coverage: p.coverage, orphans: p.orphans, capViolations: p.capViolations,
+  outOfRepo: v.outOfRepo, tests: v.tests, videos: p.videos,
+};
+
+const cite = t => `${t.strength === 'reachable' ? 'reachable from' : 'pinned by'} \`${t.test.split(':').pop()}\` (${t.file}:${t.assertLines.join(',')}): ${t.say}${t.strength === 'reachable' ? ' (reachable only: never "pinned" or "tested")' : ''}`;
+const L = [];
+L.push(`# ${(v.root || '').split('/').pop()} — code-flow video plan`, '');
+L.push(plan.approval ? `Approved by **${plan.approval.by}** at ${plan.approval.at}: "${plan.approval.note}" (flows.validated.json sha256 ${plan.approval.flowsHash.slice(0, 12)}…)`
+  : '**Estimate only: this flow list is not approved.** No plan is written until the user approves it.', '');
+const B = MODEL.basis;
+L.push(`> Calibrated on ${B.videos} narrated pilot video (${B.hops} hops, ${B.narratedLines} narrated lines, ${B.branches} taught branches, ` +
+  `${B.citedTests} cited tests, ${B.words} words): frame ${MODEL.frame}, hop ${MODEL.hopBase} + ${MODEL.wpl} words per narrated line (≤ ${MODEL.lineCap}), ` +
+  `taught branch ${MODEL.branch}, cited test ${MODEL.test} (≤ ${MODEL.maxTests} per video). Still **uncalibrated**: crossing ${MODEL.boundary} ` +
+  `(the pilot crossed no boundary) and the overview's ${MODEL.overview} words.`, '');
+L.push(`## ${p.totals.videos} videos, ${p.totals.seriesMinutes} min (longest ${p.totals.longestVideoMin} min, cap ${maxMin} min)`, '');
+L.push('| # | Title | Form | Group | Hops | Crossings | Branches | Cited tests | Words | Min |', '|---|---|---|---|---|---|---|---|---|---|');
+for (const x of p.videos) L.push(`| ${x.index} | ${x.title} | \`${x.form}\` | ${x.group} | ${x.evidence.hops ?? '—'} | ${x.evidence.crossings ?? '—'} | ${x.evidence.branches ?? '—'} | ${x.evidence.citedTests ?? '—'} | ${x.words} | ${x.minutes} |`);
+L.push('', '## Sections per video', '', 'A script covers each of its video\'s sections by name in `covers`.', '');
+for (const x of p.videos) {
+  L.push(`### ${x.index}. ${x.title}`, '', `${x.form} · ${x.formWhy}`, '');
+  for (const s of x.sectionSpans) L.push(`- \`${s.id}\`${s.pinnedBy?.length ? ` — ${s.pinnedBy.map(cite).join('; ')}` : ''}`);
+  for (const t of x.teach || []) L.push(`- teach \`${t.dispatch || t.guard}\`: ${t.say}`);
+  L.push('');
+}
+L.push('## Coverage (C4)', '', `${p.coverage.length} hops · ${p.coverage.length - p.orphans.length} assigned to exactly one video · **${p.orphans.length} orphaned**`);
+for (const o of p.orphans) L.push(`- ⚠️ ${o.item} hop ${o.hop}: ${o.symbol}`);
+for (const c of p.capViolations) L.push(`- ⚠️ video ${c.index} is ${c.minutes} min, over the ${maxMin} min cap: a hop is never split; raise --max-min or narrate fewer lines`);
+if (v.outOfRepo.length) L.push('', '## Out-of-repo claims (unverified)', '', ...v.outOfRepo.map(o => `- ${o.claim} — ${o.evidence}`));
+L.push('');
+const md = L.join('\n');
+
+if (estimate) { console.log(md); process.exit(p.orphans.length || p.capViolations.length ? 2 : 0); }
+
+/* ---------------- model guard: an enriched plan is keyed by video index ---------------- */
+const ENRICHED = join(OUT, 'plan.enriched.json');
+if (existsSync(ENRICHED)) {
+  let prev = null;
+  try { prev = JSON.parse(readFileSync(ENRICHED, 'utf8')); } catch { prev = null; }
+  const why = [];
+  if (prev?.treeHash !== v.treeHash) why.push('the code map tree');
+  if (prev?.inputs?.candidates?.sha256 !== v.inputs.candidates.sha256) why.push('candidates.json');
+  if (prev?.inputs?.flows?.sha256 !== v.inputs.flows.sha256) why.push('flows.json');
+  if (prev?.approval?.flowsHash !== approval.flowsHash || prev?.approval?.at !== approval.at) why.push('the approval');
+  if (prev?.model?.maxVideoMin !== maxMin) why.push(`the cap (${prev?.model?.maxVideoMin} → ${maxMin} min)`);
+  if (why.length && !flags.has('--force')) fail(4, `plan.enriched.json was built from a different plan (${why.join(', ')} changed): enrichment is keyed by video index, so re-planning would repoint every curated title. Rerun with --force, then rerun apply-enrichment.`);
+  if (why.length) console.error(`[flow-plan] --force: overwriting the plan behind plan.enriched.json (${why.join(', ')} changed); rerun apply-enrichment`);
+}
+writeFileSync(join(OUT, 'plan.json'), JSON.stringify(plan, null, 2));
+writeFileSync(join(OUT, 'plan.md'), md);
+console.log(md);
+console.log(`[out] ${join(OUT, 'plan.json')}`);
+console.log(`[out] ${join(OUT, 'plan.md')}`);
+if (p.orphans.length || p.capViolations.length) { console.log(`\n⚠️  ${p.orphans.length} orphaned hop(s), ${p.capViolations.length} video(s) over the cap`); process.exitCode = 2; }

package/skills/explainer-video-from-codebase/tools/flows-md.mjs

@@ -0,0 +1,87 @@
+/* flows.md: the approval table first (every series flow and core with its reason, every skipped high-ranked row,
+   the variants, the dev rows, the estimate), then the C1′ and C1 accounting, then every flow and core in full: every
+   hop with how it is reached, the rule and evidence of each edge, and the cited tests with their assertion lines.
+   No truncation: this is what the user approves. */
+const short = id => id == null ? '' : id.endsWith(':<main>') ? id.split(':')[0].split('.').pop() + ':<main>' : id.split(':').pop();
+const cell = c => String(c ?? '').replace(/\|/g, '\\|').replace(/\n/g, ' ');
+const table = (head, rows) => rows.length ? [`| ${head.join(' | ')} |`, `|${head.map(() => '---').join('|')}|`, ...rows.map(r => `| ${r.map(cell).join(' | ')} |`)].join('\n') : '_none_';
+const code = id => id ? `\`${id}\`` : '';
+const span = h => `${h.file}:${h.start}-${h.end}${h.lines ? ` (lines ${h.lines.map(([a, b]) => a === b ? a : `${a}-${b}`).join(',')})` : ''}`;
+
+const reached = h => {
+  const c = h.connection;
+  if (!c) return '';
+  if (c.how === 'entry' || c.how === 'start') return c.how;
+  if (c.how === 'variant') return 'starts a variant';
+  const from = c.path[0];
+  return `${c.how === 'candidate' ? 'walk' : c.how === 'edges' ? 'edges' : 'declared link'} from \`${short(from)}\`: ${c.steps.map(s => s.kind).join(' → ')}`;
+};
+const evidence = h => (h.connection?.steps || []).filter(s => s.rule || s.declared || (s.evidence && s.kind !== 'static')).map(s => `${s.rule || s.kind}: ${s.evidence || ''}`.trim()).join('; ');
+const tests = h => h.pinnedBy.map(t => `\`${short(t.test)}\` (${t.file}:${t.line}-${t.end}, asserts at ${t.assertLines.join(', ') || '—'}${t.strength === 'reachable' ? ', reachable only: never "tested"' : ''}) — ${t.say}`).join('<br>');
+
+export function renderFlows(v, problems, estimate, r) {
+  const out = [];
+  const all = [...v.flows, ...v.cores];
+  const byId = new Map(all.map(x => [x.id, x]));
+  out.push(`# Flows: ${(v.root || '').split('/').pop()}`, '',
+    `- ${v.commit ? `commit \`${v.commit.slice(0, 7)}\` · ` : ''}tree ${(v.treeHash || '').slice(0, 19)}…`,
+    `- inputs: \`${v.inputs.flows.file}\` (sha256 ${v.inputs.flows.sha256.slice(0, 12)}…), \`${v.inputs.candidates.file}\`, \`${v.inputs.ranking.file}\``,
+    `- high-ranked: the top ${v.params.explainTop} production and top ${v.params.explainTopEval} eval rows, plus every row at or above the lowest-ranked row the series includes`, '');
+  if (problems.length) out.push(`## ${problems.length} problem(s): not validated`, '', ...problems.map(p => `- ${p}`), '');
+
+  out.push('## Approval table', '',
+    problems.length ? 'Fix the problems above first: nothing here may be approved yet.'
+      : 'Show this table to the user and ask them to approve it or edit it (add, drop, reorder, promote). Run `approve-flows` only on an explicit yes; after any edit, rerun `apply-flows` and ask again.', '');
+  out.push('### The proposed series, in video order', '',
+    table(['#', 'kind', 'id', 'title', 'group', 'rank', 'size', 'why'], v.series.map((s, i) => { const x = byId.get(s.id), c = x.from && r.candidates[x.from];
+      return [i + 1, s.kind, code(s.id), x.title, x.group, s.rank || '—', `${x.hops.length} hops${c ? ` · ${c.own} own symbols` : ''}`, s.why]; })), '');
+  const highSet = new Set(Object.values(v.triage.highRanked).flatMap(h => h.rows.map(x => x.entry)));
+  out.push('### Skipped rows', '', table(['entry', 'group', 'rank', 'high-ranked', 'why'], v.skipped.map(s => [code(short(s.entry)), s.group, s.rank || '—', highSet.has(s.entry) ? 'yes' : 'no', s.why])), '');
+  out.push('### Variants', '', table(['of', 'entry', 'rank', 'why'], all.flatMap(x => x.variants.map(y => [code(x.id), code(short(y.entry)), y.rank || '—', y.why]))), '');
+  if (v.promote.length) out.push('### Promoted dev rows', '', table(['entry', 'rank', 'why'], v.promote.map(p => [code(short(p.entry)), p.rank || '—', p.why])), '');
+  out.push('### Dev rows (filtered by default; promote one in flows.json with a reason)', '',
+    table(['entry', 'kind', 'route / key', 'rank', 'status'], v.triage.entries.filter(t => t.group === 'dev').map(t => [code(short(t.id)), t.kind, t.route, t.rank ? `#${t.rank}` : '—', t.status || 'untriaged'])), '');
+  if (estimate) {
+    out.push(`### Estimate: ${estimate.videos.length} videos, ${estimate.totals.seriesMinutes} min (cap ${estimate.totals.capMinutes} min per video)`, '',
+      'From the cost model in `flow-plan --estimate`; calibrated on one pilot code video, except the crossing and overview constants.', '',
+      table(['#', 'video', 'form', 'hops', 'cited tests', 'words', 'min'], estimate.videos.map(x => [x.index, x.title, x.form, x.evidence.hops ?? '—', x.evidence.citedTests ?? '—', x.words, x.minutes])), '');
+  }
+
+  out.push('## High-ranked rows (C1′)', '');
+  for (const [grp, h] of Object.entries(v.triage.highRanked)) {
+    if (!h.rows.length) continue;
+    const s = h.summary;
+    out.push(`${grp}: ${s.highRanked} high-ranked · ${s.series} in series · ${s.variant} variant · ${s.skipped} skipped · ${s.unexplained} unexplained`, '',
+      table(['rank', 'entry', 'decision', 'why'], h.rows.map(x => [`#${x.rank}`, code(short(x.entry)), x.status || '**unexplained**', x.why || ''])), '');
+  }
+  const t = v.triage.entries, g = grp => t.filter(x => x.group === grp), n = (xs, s) => xs.filter(x => x.status === s).length;
+  out.push('## Entry triage (C1)', '',
+    `${t.length + v.triage.testGroupEntries.length} entries · prod ${g('prod').length} · eval ${g('eval').length} · dev ${g('dev').length} (${n(g('dev'), 'dev-filtered')} filtered, ${n(g('dev'), 'continuation')} continuations) · ${t.filter(x => !x.status).length} untriaged · test-group entries: ${v.triage.testGroupEntries.length} (listed)`, '',
+    table(['entry', 'group', 'kind', 'route / key', 'rank', 'decision', 'by', 'reason'], t.map(x => [code(x.id), x.group, x.kind, x.route, x.rank ? `#${x.rank}` : '—', x.status || '**untriaged**', x.by, x.reason])), '');
+  if (v.triage.testGroupEntries.length) out.push('Entries in the test group (not flows): ' + v.triage.testGroupEntries.map(code).join(', '), '');
+  if (v.excluded.length) out.push('### Exclusion rules', '', table(['match', 'why', 'matched'], v.excluded.map(x => [code(x.match), x.why, x.matched.map(short).join(', ')])), '');
+
+  out.push('## Flows and cores', '');
+  for (const s of v.series) {
+    const x = byId.get(s.id);
+    out.push(`### ${x.kind} \`${x.id}\`: ${x.title}`, '',
+      `${x.from ? `from \`${x.from}\`${x.entry?.path ? ` (${[x.entry.method, x.entry.path].filter(Boolean).join(' ')})` : x.entry?.key ? ` (${x.entry.key})` : ''} · ` : ''}group ${x.group} · ${x.rank || 'no rank'} · why: ${s.why}`, '',
+      table(['#', 'hop', 'span', 'reached by', 'rule / evidence', 'cited tests', 'notes'], x.hops.map(h => [h.index, code(h.symbol), span(h), reached(h), evidence(h), tests(h),
+        [h.crossing ? 'crossing' : '', h.break ? 'break' : '', h.uses ? `uses ${h.uses}` : '', h.exercises ? `exercises ${h.exercises}` : '', h.selectedBy ? `selected only by an unverified out-of-repo claim: ${h.selectedBy.outOfRepo}` : ''].filter(Boolean).join(', ')])), '');
+    if (x.segments.length) out.push('Segments:', '', table(['root', 'reached from', 'via', 'own', 'decision', 'say / why'], x.segments.map(y => [code(short(y.root)), y.from ? code(short(y.from)) : '(entry)', y.kind || '', y.own, y.decision + (y.rule ? ` (${y.rule})` : ''), y.say || y.why || ''])), '');
+    if (x.teach.length) out.push('Taught branches:', '', table(['point', 'at hop', 'alternatives', 'say'], x.teach.map(y => [code(y.dispatch || y.guard), y.hop,
+      (y.alternatives || []).map(a => typeof a === 'string' ? code(short(a)) : a.cls ? `\`${short(a.cls)}\` when ${a.guards.join(' & ') || '(fallthrough)'}${a.sel ? ` (${Object.entries(a.sel).map(([p, s2]) => `${p}: ${s2}`).join(', ')})` : ''}` : `\`${short(a.to)}\` when ${a.guards.join(' & ')}`).join('; '), y.say])), '');
+    if (x.links.length) out.push('Declared links:', '', table(['from', 'to', 'kind', 'evidence'], x.links.map(l => [code(short(l.from)), code(short(l.to)), l.kind, l.evidence])), '');
+  }
+  const shared = new Map();
+  // a hop that `uses` the core holding the same symbol is that core's reference, not a second narration
+  const refersToCore = h => h.uses && byId.get(h.uses)?.hops.some(y => y.symbol === h.symbol);
+  for (const x of all) for (const h of x.hops) if (!refersToCore(h)) (shared.get(h.symbol) || shared.set(h.symbol, []).get(h.symbol)).push(x.id);
+  const twice = [...shared].filter(([, ids]) => ids.length > 1);
+  out.push('## Hops kept by two or more flows', '', 'A sequence kept by two or more flows is a core candidate; a hop listed here is narrated in each.', '',
+    table(['hop', 'kept by'], twice.map(([s, ids]) => [code(s), ids.join(', ')])), '');
+  out.push('## Out-of-repo claims (unverified)', '', table(['claim', 'evidence', 'selects'], v.outOfRepo.map(o => [o.claim, o.evidence, o.selects.map(code).join(', ')])), '');
+  out.push('## Test configuration', '', 'Mocks every test under a conftest runs with: a claim that a test exercises one of these targets is false.', '',
+    table(['target', 'scope', 'where'], [...v.tests.sessionMocks.map(x => [code(x.target), 'session', x.conftest]), ...v.tests.autouseMocks.map(x => [code(x.target), 'autouse fixture', code(x.fixture)])]), '');
+  return out.join('\n');
+}