demobite 1.5.0 → 1.7.1

package/skill/scripts/briefs.mjs

@@ -2,6 +2,13 @@
 // of approved briefs into the agent; this script is the agent's hands:
 //
 //   node briefs.mjs list <batchId> [--paste <file>]     the authenticated truth for the batch (warns when a pasted bundle drifted)
+//   node briefs.mjs list --slug <slug>                  UPDATE RADAR (1.6.0): the batch behind a workflow's record code; writes
+//                                                       .recorder/radar/<slug>/bundle.json (+ briefs/<briefId>.json, one draft
+//                                                       per brief) and prints the briefs in order with their open questions
+//   node briefs.mjs refine <slug> <briefId> [--file <refined.json>] [--note "..."]
+//                                                       REFACTOR PASS (1.7.0): post the brief refined on this machine (default file
+//                                                       .recorder/radar/<slug>/refined/<briefId>.json) → a new revision; the Radar
+//                                                       page shows it as "Refined on your machine"; rewrites the bundle
 //   node briefs.mjs claim <batchId> <briefId> [--force] claim one brief → mints an attempt, creates take-<briefId>-r<revision>/brief.json
 //   node briefs.mjs event <takeDir|attemptRef> <event> [--note "..."]
 //                                                       planning | awaiting_storyboard_approval | recording | uploading | failed | cancelled
@@ -9,15 +16,23 @@
 //
 // Server contract (dbrec_ key, scope record):
 //   GET /api/recorder/briefs?batch=<batchId>
+//   GET /api/recorder/briefs?slug=<slug>      same payload + radar: { slug, name, workflowUrl }
+//                                             404 { error: "unknown_slug" } · 409 { error: "not_approved" }
 //   PUT /api/recorder/briefs/claim { briefId, revision, contentHash, idempotencyKey, force? }
 //   PUT /api/recorder/briefs/attempts/<attemptRef> { event, note? }
+//   PUT /api/recorder/briefs/<briefId>/refine { revision, contentHash, content, note? }
+//                                             -> { revision, contentHash }   (409 hash_mismatch · 410 superseded)
 // The stage call (upload.mjs) sends the attempt from <takeDir>/brief.json, and
 // after the uploads calls the delivery route from the claim's `api.uploaded`
 // (1.3.0): a take filmed from a brief becomes a bite by itself.
 //
-// Laws: one storyboard approval per brief, never one word for the batch.
-// Sequential takes, one Chrome on the profile. A failed brief never stops the
-// others. Never print the api_key.
+// Laws (founder ruling 2026-09-26, "the fewest edits before Export and Go
+// live"): every brief is refined against the repository and the running app
+// BEFORE anything films, and posted back through `refine`; every open
+// question is asked ONCE for the whole batch; the batch gets ONE approval;
+// then batch.mjs films the takes in the background, in parallel, each on its
+// own profile directory. A failed brief never stops the others. Never print
+// the api_key.
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
@@ -25,22 +40,26 @@ import crypto from "node:crypto";
 const [, , cmd, ...rest] = process.argv;
 const flag = (name) => rest.includes(name);
 const opt = (name) => { const i = rest.indexOf(name); return i >= 0 ? String(rest[i + 1] ?? "") : null; };
-const positional = rest.filter((a, i) => !a.startsWith("--") && !(i > 0 && ["--paste", "--note"].includes(rest[i - 1])));
+const positional = rest.filter((a, i) => !a.startsWith("--") && !(i > 0 && ["--paste", "--note", "--slug", "--file"].includes(rest[i - 1])));
+// `npx demobite record <slug>` runs this script (DEMOBITE_CLI=1); its login hint is the launcher's command.
+const loginHint = process.env.DEMOBITE_CLI ? "npx demobite login" : "node scripts/login.mjs";
 
 function usage(code = 2) {
   console.error(`Usage:
   node briefs.mjs list <batchId> [--paste <file>]
+  node briefs.mjs list --slug <slug>
+  node briefs.mjs refine <slug> <briefId> [--file <refined.json>] [--note "..."]
   node briefs.mjs claim <batchId> <briefId> [--force]
   node briefs.mjs event <takeDir|attemptRef> <event> [--note "..."]
   node briefs.mjs release <takeDir|attemptRef> [--note "..."]`);
   process.exit(code);
 }
-if (!cmd || !["list", "claim", "event", "release"].includes(cmd)) usage();
+if (!cmd || !["list", "claim", "event", "release", "refine"].includes(cmd)) usage();
 
 const cfgPath = path.resolve(".recorder", "config.json");
 let cfg = {};
 try { cfg = JSON.parse(fs.readFileSync(cfgPath, "utf8")); } catch {}
-if (!cfg.api_key || !cfg.base) { console.error("No recorder key. Run: node scripts/login.mjs"); process.exit(1); }
+if (!cfg.api_key || !cfg.base) { console.error(`Not connected to DemoBites. Run: ${loginHint}`); process.exit(1); }
 const base = cfg.base.replace(/\/+$/, "");
 const headers = { Authorization: `Bearer ${cfg.api_key}`, "Content-Type": "application/json" };
 
@@ -50,7 +69,7 @@ async function api(method, p, body) {
     res = await fetch(`${base}${p}`, { method, headers, body: body ? JSON.stringify(body) : undefined });
   } catch (e) { console.error(`DemoBites unreachable (${e.message}).`); process.exit(1); }
   const json = await res.json().catch(() => null);
-  if (res.status === 401) { console.error("The recorder key was refused. Run: node scripts/login.mjs"); process.exit(1); }
+  if (res.status === 401) { console.error(`The recorder key was refused. Run: ${loginHint}`); process.exit(1); }
   return { status: res.status, ok: res.ok, json };
 }
 
@@ -90,14 +109,116 @@ function printBatch(data) {
 async function fetchBatch(batchId) {
   const r = await api("GET", `/api/recorder/briefs?batch=${encodeURIComponent(batchId)}`);
   if (r.status === 403 && r.json?.error === "workspace_mismatch") {
-    console.error("This key's workspace is not the batch's workspace. Log in to the right workspace (node scripts/login.mjs) and try again.");
+    console.error(`This key's workspace is not the batch's workspace. Log in to the right workspace (${loginHint}) and try again.`);
     process.exit(1);
   }
   if (!r.ok || !r.json?.briefs) { console.error(`Could not read batch ${batchId}: ${r.status} ${r.json ? JSON.stringify(r.json).slice(0, 200) : ""}`); process.exit(1); }
   return r.json;
 }
 
-if (cmd === "list") {
+/** UPDATE RADAR (1.6.0): the batch behind a workflow's record code. */
+async function fetchBySlug(slug) {
+  const r = await api("GET", `/api/recorder/briefs?slug=${encodeURIComponent(slug)}`);
+  if (r.status === 404) { console.error("No batch with that code. Check the command on the Update Radar page."); process.exit(1); }
+  if (r.status === 409) { console.error("The briefs are not approved yet. Approve them on the Update Radar page, then run this again."); process.exit(1); }
+  if (r.status === 403 && r.json?.error === "workspace_mismatch") {
+    console.error(`This key's workspace is not the workflow's workspace. Log in to the right workspace (${loginHint}) and try again.`);
+    process.exit(1);
+  }
+  if (r.status === 403 && r.json?.error === "upgrade_required") { console.error("Update Radar is part of Product Awareness. Upgrade the workspace on the Update Radar page, then run this again."); process.exit(1); }
+  if (!r.ok || !r.json?.briefs) { console.error(`Could not read the batch for code ${slug}: ${r.status} ${r.json ? JSON.stringify(r.json).slice(0, 200) : ""}`); process.exit(1); }
+  return r.json;
+}
+
+/** The record-by-code view: the workflow, the batch id, then the briefs in order (position, title, seconds). */
+function printRadar(data, slug) {
+  const { batch, briefs, radar } = data;
+  const order = [...briefs].sort((a, b) => (a.position ?? 0) - (b.position ?? 0));
+  console.log(`Update Radar: ${radar?.name ?? slug}`);
+  // A radar batch has no target address: the agent films where the code
+  // already runs (the Record stage says so); print the target only when set.
+  console.log(`Batch ${batch?.id ?? "?"}${batch?.target?.url ? `  target ${batch.target.url}${batch.target.environment ? ` (${batch.target.environment})` : ""}` : ""}`);
+  console.log(`${briefs.length} brief${briefs.length === 1 ? "" : "s"}, each at most ${batch?.rules?.maxSeconds ?? 90} seconds, in this order:\n`);
+  const questions = [];
+  order.forEach((b, i) => {
+    const pos = String(i + 1).padStart(2, " ");
+    const secs = b.estimatedDurationSec ? `about ${b.estimatedDurationSec}s` : "length open";
+    const state = b.status && b.status !== "approved" ? `  [${b.status}${b.attempt ? `, attempt ${b.attempt.ref}` : ""}]` : "";
+    const refined = b.refinedLocally || b.refined ? "  (refined on this machine)" : "";
+    console.log(`  ${pos}. ${b.title}  (${secs})  brief ${b.briefId} r${b.revision}${state}${refined}`);
+    for (const q of b.questions ?? []) questions.push({ n: i + 1, title: b.title, q: typeof q === "string" ? q : q?.text ?? JSON.stringify(q) });
+  });
+  // QUESTIONS ONCE (2026-09-26): the drafts' open questions, gathered here so
+  // the agent asks them in one message for the whole batch, never mid-filming.
+  if (questions.length) {
+    console.log(`\nOpen questions in the drafts (ask them once, for the whole batch, before anything films):`);
+    for (const { n, title, q } of questions) console.log(`  brief ${n} (${title}): ${q}`);
+  }
+  if (radar?.workflowUrl) console.log(`\nWorkflow page: ${radar.workflowUrl}`);
+}
+
+/** The radar bundle on disk: bundle.json plus one draft file per brief (what
+ * the refactor pass starts from; the refined copy goes to refined/<briefId>.json). */
+function writeRadarBundle(slug, data) {
+  const dir = path.resolve(".recorder", "radar", slug);
+  fs.mkdirSync(path.join(dir, "briefs"), { recursive: true });
+  const bundlePath = path.join(dir, "bundle.json");
+  fs.writeFileSync(bundlePath, JSON.stringify({ slug, fetchedAt: new Date().toISOString(), ...data }, null, 2) + "\n");
+  for (const b of data.briefs) {
+    const safe = String(b.briefId).replace(/[^A-Za-z0-9._-]+/g, "-");
+    fs.writeFileSync(path.join(dir, "briefs", `${safe}.json`), JSON.stringify(b, null, 2) + "\n");
+  }
+  return bundlePath;
+}
+
+/** The brief's content for the refine door: ONLY the seven content fields
+ * the server's strict schema accepts, read from the draft file's top level or
+ * its `content` object; every other key a draft carries (identity, state,
+ * questions, author, attempts) is dropped, so a draft round-trips as is.
+ * The limits are the server's (a refine that breaks one answers 400
+ * invalid_refine): title ≤ 80, audience ≤ 60, outcome ≤ 200, flowIntent 2..8
+ * lines ≤ 120 each, prerequisites/exclusions ≤ 6 lines ≤ 160 each,
+ * estimatedDurationSec 15..90. They are checked here first, with the field
+ * named, so the agent trims before posting instead of reading a 400. */
+const CONTENT_LIMITS = { title: 80, audience: 60, outcome: 200 };
+const LIST_LIMITS = { flowIntent: { min: 2, max: 8, line: 120 }, prerequisites: { min: 0, max: 6, line: 160 }, exclusions: { min: 0, max: 6, line: 160 } };
+function refineContent(obj) {
+  const src = obj && typeof obj === "object" && obj.content && typeof obj.content === "object" ? obj.content : obj ?? {};
+  const pick = (camel, snake) => src[camel] !== undefined ? src[camel] : src[snake];
+  const out = {};
+  for (const k of ["title", "audience", "outcome"]) if (src[k] !== undefined) out[k] = src[k];
+  const fi = pick("flowIntent", "flow_intent"); if (fi !== undefined) out.flowIntent = fi;
+  for (const k of ["prerequisites", "exclusions"]) if (src[k] !== undefined) out[k] = src[k];
+  const d = pick("estimatedDurationSec", "estimated_duration_sec"); if (d !== undefined) out.estimatedDurationSec = d;
+  return out;
+}
+/** The server's limits, checked before the PUT; returns the problems as "field: why" lines. */
+function refineProblems(c) {
+  const out = [];
+  for (const [k, max] of Object.entries(CONTENT_LIMITS)) {
+    if (typeof c[k] !== "string" || !c[k].trim()) out.push(`${k}: required, a non-empty line`);
+    else if (c[k].trim().length > max) out.push(`${k}: ${c[k].trim().length} characters, the limit is ${max}`);
+  }
+  for (const [k, lim] of Object.entries(LIST_LIMITS)) {
+    const v = c[k] ?? [];
+    if (!Array.isArray(v)) { out.push(`${k}: must be a list of lines`); continue; }
+    if (v.length < lim.min || v.length > lim.max) out.push(`${k}: ${v.length} lines, allowed ${lim.min}..${lim.max}`);
+    v.forEach((line, i) => { if (typeof line !== "string" || !line.trim()) out.push(`${k}[${i}]: an empty line`); else if (line.trim().length > lim.line) out.push(`${k}[${i}]: ${line.trim().length} characters, the limit is ${lim.line}`); });
+  }
+  const d = c.estimatedDurationSec;
+  if (!Number.isInteger(d) || d < 15 || d > 90) out.push(`estimatedDurationSec: ${JSON.stringify(d)}, must be a whole number of seconds 15..90`);
+  return out;
+}
+
+if (cmd === "list" && opt("--slug") !== null) {
+  const slug = String(opt("--slug")).trim().toLowerCase();
+  if (!/^[a-z0-9-]{1,32}$/.test(slug)) { console.error("The record code is the short code on the Update Radar page, like k3fx9q."); process.exit(2); }
+  const data = await fetchBySlug(slug);
+  const bundlePath = writeRadarBundle(slug, data);
+  printRadar(data, slug);
+  const rel = path.relative(process.cwd(), bundlePath) || bundlePath;
+  console.log(`Bundle written: ${rel}  (one draft per brief in ${path.dirname(rel)}/briefs/, refined copies go to ${path.dirname(rel)}/refined/)`);
+} else if (cmd === "list") {
   const batchId = positional[0];
   if (!batchId) usage();
   const data = await fetchBatch(batchId);
@@ -120,6 +241,39 @@ if (cmd === "list") {
   }
 }
 
+// REFACTOR PASS (1.7.0): post a brief refined on this machine. The server
+// mints a new revision + contentHash for it and the Radar page shows the
+// refined text ("Refined on your machine"); the claim then takes the new
+// revision, so the bundle is rewritten from the server right after.
+if (cmd === "refine") {
+  const [slugArg, briefId] = positional;
+  const slug = String(slugArg ?? "").trim().toLowerCase();
+  if (!/^[a-z0-9-]{1,32}$/.test(slug) || !briefId) usage();
+  const safe = String(briefId).replace(/[^A-Za-z0-9._-]+/g, "-");
+  const file = opt("--file") ?? path.resolve(".recorder", "radar", slug, "refined", `${safe}.json`);
+  let refined;
+  try { refined = JSON.parse(fs.readFileSync(file, "utf8")); } catch (e) { console.error(`Refined brief not readable at ${file}: ${e.message}\nWrite the refined brief there (copy .recorder/radar/${slug}/briefs/${safe}.json and edit it), or pass --file.`); process.exit(2); }
+  const content = refineContent(refined);
+  const problems = refineProblems(content);
+  if (problems.length) { console.error(`${file}: the refined brief breaks the server's limits — fix these and post again:\n  ${problems.join("\n  ")}`); process.exit(2); }
+  const data = await fetchBySlug(slug);
+  const brief = data.briefs.find((b) => String(b.briefId) === String(briefId));
+  if (!brief) { console.error(`Brief ${briefId} is not in the batch behind code ${slug}.`); process.exit(1); }
+  const note = opt("--note");
+  const r = await api("PUT", `/api/recorder/briefs/${encodeURIComponent(brief.briefId)}/refine`, {
+    revision: brief.revision, contentHash: brief.contentHash, content, ...(note ? { note: note.slice(0, 600) } : {}),
+  });
+  if (r.status === 404 && !r.json?.error) { console.error("This DemoBites has no refine route yet (older server). Film from the refined file on this machine; the Radar page keeps the cloud draft."); process.exit(1); }
+  if (r.status === 409 && (r.json?.error === "hash_mismatch" || r.json?.error === "active_attempt")) { console.error(`Brief ${briefId}: ${r.json.error === "active_attempt" ? "a live attempt holds it; a refine lands before the claim, never after" : "the server's revision moved; run list --slug again and refine from the current draft"}.`); process.exit(1); }
+  if (r.status === 410 && r.json?.error === "take_delivered") { console.error(`Brief ${briefId} is locked: a take was delivered for it, so its text on the Radar page is frozen. Film the re-take from your refined file; the Radar page keeps the delivered wording.`); process.exit(1); }
+  if (r.status === 410) { console.error(`Brief ${briefId} r${brief.revision} was superseded by a newer revision. Run list --slug again.`); process.exit(1); }
+  if (!r.ok || r.json?.revision === undefined) { console.error(`Refine failed: ${r.status} ${r.json ? JSON.stringify(r.json).slice(0, 200) : ""}`); process.exit(1); }
+  console.log(`Refined ${brief.briefId}: r${brief.revision} → r${r.json.revision} (${r.json.contentHash ?? "hash from the server"}). The Radar page shows it as refined on this machine.`);
+  const fresh = await fetchBySlug(slug);
+  writeRadarBundle(slug, fresh);
+  console.log(`Bundle rewritten: .recorder/radar/${slug}/bundle.json`);
+}
+
 if (cmd === "claim") {
   const [batchId, briefId] = positional;
   if (!batchId || !briefId) usage();

package/skill/scripts/cleanup.mjs

@@ -32,7 +32,8 @@ if (steps.length === 0 && checks.length === 0) {
   process.exit(0);
 }
 
-const profileDir = path.resolve(".recorder", "profile");
+// RECORDER_PROFILE (1.7.0): a batch's parallel takes each prep and clean on their own seeded profile.
+const profileDir = path.resolve(process.env.RECORDER_PROFILE || path.join(".recorder", "profile"));
 const ctx = await chromium.launchPersistentContext(profileDir, { channel: "chrome", headless: true, viewport: { width: 1920, height: 1080 } }).catch(async () =>
   chromium.launchPersistentContext(profileDir, { headless: true, viewport: { width: 1920, height: 1080 } }),
 );

package/skill/scripts/manifest.mjs

@@ -194,6 +194,9 @@ const camera = (man.shots ?? [])
     label: s.label ?? undefined,
     ...(s.n != null ? { n: s.n } : {}),
     ...(s.revealed ? { revealed: true } : {}),
+    // WIDE (founder 2026-09-27): the camera at 1.0 for the span — the server
+    // ends the previous zoom at its start and writes no zoom row for it.
+    ...(s.wide ? { wide: true } : {}),
     ...(s.glide ? { glide: { t_start: norm(s.glide.t_start), t_end: norm(s.glide.t_end) } } : {}),
   }))
   .filter((s) => s.t_end > s.t_start && s.t_start < duration && s.w > 0 && s.h > 0)
@@ -238,8 +241,15 @@ if (fs.existsSync(cleanPath)) {
     const changedPx = yavg ? (parseFloat(yavg[1]) / 255) * FW * FH * SS * SS : 0;
     return { x: x / SS, y: y / SS, w: w / SS, h: h / SS, changedPx: changedPx / (SS * SS) };
   };
+  // FRAMING (founder 2026-09-27): a step the director framed `close` keeps its
+  // subject box — the page redrawing after an option pick is the landing, and
+  // the wide beat that follows frames it. The storyboard copy in the take dir
+  // is the recipe, so the frame is read from it by step number.
+  let framedClose = new Set();
+  try { const sb = JSON.parse(fs.readFileSync(path.join(dir, "storyboard.json"), "utf8")); (sb.steps ?? []).forEach((s, i) => { if (s?.frame === "close") framedClose.add(i + 1); }); } catch {}
   for (const st of steps) {
     if (!st.click) continue;
+    if (framedClose.has(st.n)) continue;
     const hasRevealedShot = camera.some((c) => c.n === st.n && c.revealed);
     if (hasRevealedShot) continue;
     const control = camera.find((c) => c.n === st.n && !c.revealed);
@@ -269,7 +279,9 @@ if (fs.existsSync(cleanPath)) {
       const wideStart = round2(st.click.t);
       const wideEnd = round2(Math.min(duration, st.t_end));
       if (wideEnd - wideStart >= 0.6) {
-        camera.push({ t_start: wideStart, t_end: wideEnd, x: 0, y: 0, w: FW, h: FH, n: st.n, label: `${st.label || "click"}, new page` });
+        // `wide: true` so the server frames it at 1.0 (an untagged full frame
+        // used to land on the 1.25 zoom floor — a phantom zoom on the new page).
+        camera.push({ t_start: wideStart, t_end: wideEnd, x: 0, y: 0, w: FW, h: FH, n: st.n, wide: true, label: `${st.label || "click"}, new page` });
         camera.sort((a, b) => a.t_start - b.t_start);
       }
       console.log(`consequence: step ${st.n} navigation — reset to wide at ${wideStart}s`);

package/skill/scripts/retake.mjs

@@ -5,16 +5,28 @@
 // is fetched from DemoBites; the server keeps the bite's CURRENT narration
 // text, voice, intro/outro and look, and refits camera, cuts and audio.
 //
-// Usage: node retake.mjs <biteId> [--note "what changed"] [--take <dir>]
+// Usage: node retake.mjs <biteId> [--note "what changed"] [--take <dir>] [--fresh]
 //
-// Flow: recipe -> storyboard.json -> record -> trim -> calibrate (gate) ->
+//   --take <dir>   film into an existing take dir. Its storyboard.json is the
+//                  SOURCE OF TRUTH and is never overwritten: fix a selector in
+//                  it and run again with --take, the fix stays. The recipe is
+//                  written only when the file is absent.
+//   --fresh        with --take: discard the dir's storyboard.json and write
+//                  the bite's recipe again.
+//
+// Flow (the same legs, the same scripts, as a normal take — see batch.mjs):
+// recipe -> storyboard.json -> cleanup.mjs --prep (when the storyboard
+// declares prep[] / checks.before[]) -> record -> cleanup.mjs (when it
+// declares cleanup[] / checks.after[]) -> trim -> calibrate (gate) ->
 // manifest -> upload --retake-of <biteId> (stages and delivers into the bite;
-// the person watches it on the Demos grid).
+// the person watches it on the Demos grid). upload.mjs refuses a take whose
+// storyboard declares cleanup[] until cleanup.json passes, so the cleanup leg
+// is not optional here.
 //
 // A step that no longer resolves makes record.mjs FAIL LOUDLY at that step.
 // That is the moment for the agent to look at the live page, fix the
 // storyboard (or drop the beat AND its line, and tell the human what is gone),
-// and run again. Nothing is staged until every step resolves.
+// and run again with --take. Nothing is staged until every step resolves.
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -22,19 +34,34 @@ import { spawnSync } from "node:child_process";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const args = process.argv.slice(2);
+const USAGE = 'Usage: node retake.mjs <biteId> [--note "what changed"] [--take <dir>] [--fresh]';
+if (args.includes("--help") || args.includes("-h")) { console.log(USAGE); process.exit(0); }
 const biteId = Number(args[0]);
 if (!Number.isInteger(biteId) || biteId <= 0) {
-  console.error('Usage: node retake.mjs <biteId> [--note "what changed"] [--take <dir>]');
+  console.error(USAGE);
   process.exit(2);
 }
 const opt = (name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
 const note = opt("--note") ?? "";
+const fresh = args.includes("--fresh");
 const cfgPath = path.resolve(".recorder", "config.json");
 let cfg = {};
 try { cfg = JSON.parse(fs.readFileSync(cfgPath, "utf8")); } catch {}
 if (!cfg.api_key || !cfg.base) { console.error("No recorder key. Run: node scripts/login.mjs"); process.exit(1); }
 const base = cfg.base.replace(/\/+$/, "");
 
+// Where the scripts are: installed, every script sits beside this file; in the
+// package repository record/trim/calibrate live in ../../scripts (batch.mjs
+// resolves the same two layouts).
+function scriptPath(name) {
+  for (const dir of [here, path.resolve(here, "..", "..", "scripts")]) {
+    const p = path.join(dir, name);
+    if (fs.existsSync(p)) return p;
+  }
+  console.error(`${name} not found beside ${here}. Run \`npx demobite\` to refresh the skill.`);
+  process.exit(1);
+}
+
 // 1. The recipe — the bite's DNA.
 const res = await fetch(`${base}/api/recorder/recipe?biteId=${biteId}`, { headers: { Authorization: `Bearer ${cfg.api_key}` } });
 if (res.status === 404) {
@@ -48,26 +75,57 @@ if (res.status === 402 || res.status === 403) {
 }
 if (!res.ok) { console.error(`Could not fetch the recipe (${res.status}).`); process.exit(1); }
 const recipe = await res.json();
-const storyboard = recipe.storyboard;
-if (!storyboard?.steps?.length) { console.error("The recipe has no storyboard steps."); process.exit(1); }
+if (!recipe.storyboard?.steps?.length) { console.error("The recipe has no storyboard steps."); process.exit(1); }
 
-// 2. Take dir + files.
+// 2. Take dir + files. With --take, an existing storyboard.json in the dir is
+// the source of truth (the "fix a selector, run again" loop); the recipe is
+// written only when the file is absent, or when --fresh asks for it.
 let takeDir = opt("--take");
 if (!takeDir) { let n = 1; while (fs.existsSync(`take-retake-${biteId}${n > 1 ? n : ""}`)) n++; takeDir = `take-retake-${biteId}${n > 1 ? n : ""}`; }
 fs.mkdirSync(takeDir, { recursive: true });
 const sbPath = path.join(takeDir, "storyboard.json");
-fs.writeFileSync(sbPath, JSON.stringify(storyboard, null, 2));
+let storyboard;
+if (fs.existsSync(sbPath) && !fresh) {
+  try { storyboard = JSON.parse(fs.readFileSync(sbPath, "utf8")); } catch (e) { console.error(`${sbPath} is not valid JSON (${e.message}). Fix it, or start over with --fresh.`); process.exit(1); }
+  if (!storyboard?.steps?.length) { console.error(`${sbPath} has no steps. Fix it, or start over with --fresh.`); process.exit(1); }
+  console.log(`Using the storyboard already in ${sbPath} (kept as is; --fresh replaces it from the recipe).`);
+} else {
+  storyboard = recipe.storyboard;
+  fs.writeFileSync(sbPath, JSON.stringify(storyboard, null, 2));
+  if (fresh) console.log(`${sbPath} replaced from the recipe (--fresh).`);
+}
 fs.writeFileSync(path.join(takeDir, "retake.json"), JSON.stringify({ biteId, note, engine: recipe.engine ?? null, fetchedAt: new Date().toISOString() }, null, 2));
-console.log(`Re-take of bite ${biteId} — ${storyboard.steps.length} steps from the recipe${recipe.engine ? ` (filmed by ${recipe.engine})` : ""}.`);
+console.log(`Re-take of bite ${biteId} — ${storyboard.steps.length} steps${recipe.engine ? ` (filmed by ${recipe.engine})` : ""}.`);
 if (note) console.log(`Note from the human: ${note}`);
+const hasPrep = (storyboard.prep?.length ?? 0) > 0 || (storyboard.checks?.before?.length ?? 0) > 0;
+const hasCleanup = (storyboard.cleanup?.length ?? 0) > 0 || (storyboard.checks?.after?.length ?? 0) > 0;
 
-// 3. Film -> trim -> calibrate (gate) -> manifest -> stage.
-const run = (script, extra) => spawnSync("node", [path.join(here, script), ...extra], { stdio: "inherit", cwd: process.cwd() });
-let r = run("record.mjs", [takeDir, sbPath]);
+// 3. Prep (off camera) -> film -> cleanup (off camera) -> trim -> calibrate
+// (gate) -> manifest -> stage. The same child scripts a normal take runs.
+const run = (script, extra) => spawnSync("node", [scriptPath(script), ...extra], { stdio: "inherit", cwd: process.cwd() });
+const again = `node scripts/retake.mjs ${biteId} --take ${takeDir}${note ? ` --note ${JSON.stringify(note)}` : ""}`;
+let r;
+if (hasPrep) {
+  console.log("Prep, off camera (storyboard.prep[] then checks.before[])...");
+  r = run("cleanup.mjs", [takeDir, "--prep"]);
+  if (r.status !== 0) {
+    console.error(`\nPrep did not pass (see ${path.join(takeDir, "prep.json")}). Nothing was filmed. Fix prep[] / checks.before[] in ${sbPath}, then run:\n  ${again}`);
+    process.exit(r.status ?? 1);
+  }
+}
+r = run("record.mjs", [takeDir, sbPath]);
 if (r.status !== 0) {
-  console.error(`\nThe take stopped at a step that no longer resolves. Look at the live page, fix the storyboard in ${sbPath}\n(or drop the beat and its line, and tell the human what is gone), then run:\n  node scripts/retake.mjs ${biteId} --take ${takeDir}${note ? ` --note ${JSON.stringify(note)}` : ""}`);
+  console.error(`\nThe take stopped at a step that no longer resolves. Look at the live page, fix the storyboard in ${sbPath}\n(or drop the beat and its line, and tell the human what is gone), then run:\n  ${again}`);
   process.exit(r.status ?? 1);
 }
+if (hasCleanup) {
+  console.log("Cleanup, off camera (storyboard.cleanup[] then checks.after[])...");
+  r = run("cleanup.mjs", [takeDir]);
+  if (r.status !== 0) {
+    console.error(`\nCleanup did not pass (see ${path.join(takeDir, "cleanup.json")}); the workspace may still carry what the take created, and upload.mjs will not stage it until cleanup.json says ok.\nFix cleanup[] / checks.after[] in ${sbPath} if a step no longer resolves, then, without filming again:\n  node scripts/cleanup.mjs ${takeDir}\n  node scripts/trim.mjs ${takeDir} && node scripts/calibrate.mjs ${takeDir} && node scripts/manifest.mjs ${takeDir}\n  node scripts/upload.mjs ${takeDir} --retake-of ${biteId}${note ? ` --note ${JSON.stringify(note)}` : ""}`);
+    process.exit(4);
+  }
+}
 r = run("trim.mjs", [takeDir]); if (r.status !== 0) process.exit(r.status ?? 1);
 r = run("calibrate.mjs", [takeDir]);
 if (r.status !== 0) { console.error("Calibration failed — do not stage this take. Investigate record_from / anchors and film again."); process.exit(3); }

package/skill/scripts/stage-wait.mjs

@@ -149,6 +149,125 @@ export async function waitForDecision({ base, apiKey, stagingId, pageUrl, delive
   return { exitCode: 0, status: "completed", biteId: approvedBiteId, studioUrl: finalStudioUrl };
 }
 
+// ── RE-TAKE: wait for the NEW version, not the bite ────────────────────────
+// A re-take (`upload.mjs --retake-of <biteId>`) lands INSIDE a bite that is
+// already `completed`: the server ingests the new recording as a new
+// uploaded_videos row + a 'processing' recipe row, and finalize's atomic swap
+// repoints the bite and flips that row to 'live'. The bite's status never
+// leaves `completed`, so waitForDecision returned on its first poll and
+// printed the PREVIOUS version's receipt (bite 1110 read 45.1s where the new
+// take was 44.6s, 2026-09-27). The marker that moves exactly at the swap and
+// that a recorder key can read is the LIVE recipe (GET /api/recorder/recipe):
+// after the swap its manifest is the one this take staged. The ingest
+// rewrites only steps[].narration.text (the bite's current lines), so the
+// manifest's duration and step windows survive verbatim and identify THIS
+// take. When the status route ever reports the bite's video id
+// (`videoId`), it is compared to the delivery's videoId first.
+
+/** What a staged manifest leaves on the live recipe: duration + step windows. */
+export function manifestFingerprint(manifest) {
+  if (!manifest || typeof manifest !== "object") return null;
+  const steps = Array.isArray(manifest.steps) ? manifest.steps : [];
+  if (!Number.isFinite(Number(manifest.duration)) && steps.length === 0) return null;
+  return JSON.stringify({
+    d: manifest.duration ?? null,
+    s: steps.map((s, i) => [s?.n ?? i + 1, s?.t_start ?? null, s?.t_end ?? null]),
+  });
+}
+
+/** The live recipe's fingerprint as the server sees it now, or null when it cannot be read. */
+export async function readLiveRecipeFingerprint({ base, apiKey, biteId }) {
+  try {
+    const res = await fetch(`${base}/api/recorder/recipe?biteId=${encodeURIComponent(biteId)}`, { headers: { Authorization: `Bearer ${apiKey}` } });
+    if (!res.ok) return null;
+    const recipe = await res.json().catch(() => null);
+    return manifestFingerprint(recipe?.manifest);
+  } catch { return null; }
+}
+
+/** GET /api/recorder/status for a bite, or null when it cannot be read. */
+export async function readBiteStatus({ base, apiKey, biteId }) {
+  try {
+    const res = await fetch(`${base}/api/recorder/status?biteId=${encodeURIComponent(biteId)}`, { headers: { Authorization: `Bearer ${apiKey}` } });
+    if (!res.ok) return null;
+    return await res.json().catch(() => null);
+  } catch { return null; }
+}
+
+/** The numbers the receipt prints; two equal reads in a row mean the post-swap manifest application has settled. */
+function receiptKey(st) {
+  return st ? JSON.stringify([st.status, st.durationSec ?? null, st.zooms ?? null, st.narrationTotal ?? null, st.narrationReady ?? null, st.title ?? null]) : null;
+}
+
+/** Wait until the re-take is the bite's live recording, then print ITS receipt.
+ *  `manifest` is the staged wire manifest, `before` the live fingerprint read
+ *  BEFORE staging (null when unknown), `videoId` the delivery's new video id.
+ *  Returns { exitCode, status, biteId, studioUrl } and never throws. */
+export async function waitForRetake({ base, apiKey, biteId, videoId = null, manifest = null, before = null, pageUrl, studioUrl = null, timeoutMs = 30 * 60 * 1000, pollMs = 4000, settleMs = 30 * 1000 }) {
+  const ours = manifestFingerprint(manifest);
+  if (ours && before && ours === before) {
+    console.error("Note: the bite's live recording already carries this take's manifest; the receipt below may describe it rather than a newer version.");
+  }
+  const deadline = Date.now() + timeoutMs;
+  let landed = false;
+  let how = null;
+  process.stdout.write(`Waiting for the new recording to land in bite ${biteId}`);
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, pollMs));
+    const st = await readBiteStatus({ base, apiKey, biteId });
+    if (st?.status === "failed") {
+      process.stdout.write("\n");
+      console.error(`The pipeline FAILED while re-taking bite ${biteId}. The bite keeps its previous recording. Do not hand over any link — investigate.`);
+      return { exitCode: 1, status: "failed", biteId, studioUrl: null };
+    }
+    // 1. The server names the bite's video: exact.
+    if (videoId && st && Number.isFinite(Number(st.videoId))) {
+      if (Number(st.videoId) === Number(videoId)) { landed = true; how = "video"; break; }
+      process.stdout.write("."); continue;
+    }
+    // 2. The live recipe carries this take's manifest: exact. Or it moved
+    //    away from what was live before staging: this take, or a newer one.
+    const fp = await readLiveRecipeFingerprint({ base, apiKey, biteId });
+    if (fp && ours && fp === ours) { landed = true; how = "recipe"; break; }
+    if (fp && before && fp !== before) { landed = true; how = "moved"; break; }
+    process.stdout.write(".");
+  }
+  process.stdout.write("\n");
+  if (!landed) {
+    console.error(`The new recording has not landed in bite ${biteId} within the wait window; the bite still plays its previous version. No receipt for the new one yet — watch it on your Demos grid: ${pageUrl}\n(wait again later with: node scripts/status.mjs <takeDir>)`);
+    return { exitCode: 1, status: "delivered", biteId, studioUrl: null };
+  }
+  console.log(`New recording landed in bite ${biteId}${how === "moved" ? " (the live recording changed after staging)" : ""}.`);
+
+  // The swap is followed by the manifest application (camera shots, narration
+  // rows) on the new version; read until the numbers hold still.
+  let last = await readBiteStatus({ base, apiKey, biteId });
+  const settleDeadline = Date.now() + settleMs;
+  let prevKey = receiptKey(last);
+  while (Date.now() < settleDeadline) {
+    await new Promise((r) => setTimeout(r, Math.min(pollMs, 3000)));
+    const st = await readBiteStatus({ base, apiKey, biteId });
+    const key = receiptKey(st);
+    if (st && key === prevKey && st.status === "completed" && (st.narrationTotal ?? 0) === (st.narrationReady ?? 0)) { last = st; break; }
+    if (st) { last = st; prevKey = key; }
+  }
+  if (last && last.status === "completed") {
+    console.log(
+      `Ready (new recording): "${last.title}" — ${last.durationSec ? last.durationSec.toFixed(1) + "s, " : ""}` +
+      `${last.narrationReady}/${last.narrationTotal} narration segments with audio, ${last.zooms} camera shots`,
+    );
+    if (last.narrationTotal === 0) console.error("WARNING: no narration segments landed. The voice will be silent.");
+    else if (last.narrationReady < last.narrationTotal) console.error(`WARNING: ${last.narrationTotal - last.narrationReady} segment(s) have no audio behind them.`);
+    if (last.zooms === 0) console.error("WARNING: no camera shots landed.");
+  } else {
+    console.error(`The new recording landed but the status door did not answer with a completed bite${last?.status ? ` (${last.status})` : ""}. Watch it here: ${pageUrl}`);
+    return { exitCode: 1, status: last?.status ?? "unknown", biteId, studioUrl: null };
+  }
+  const finalStudioUrl = studioUrl ? new URL(studioUrl, base).toString() : null;
+  if (finalStudioUrl) console.log(`Studio: ${finalStudioUrl}`);
+  return { exitCode: 0, status: "completed", biteId, studioUrl: finalStudioUrl };
+}
+
 /** One look, no waiting: the staged take's current status as the server sees it. */
 export async function peekStaged({ base, apiKey, stagingId }) {
   const res = await fetch(`${base}/api/recorder/stage?id=${encodeURIComponent(stagingId)}`, { headers: { Authorization: `Bearer ${apiKey}` } });

package/skill/scripts/status.mjs

@@ -12,7 +12,7 @@
 // same law as upload.mjs: no studio link before the bite is completed.
 import fs from "node:fs";
 import path from "node:path";
-import { waitForDecision, peekStaged, deliverStaged, gridUrl, formatResetDate, waitingLine } from "./stage-wait.mjs";
+import { waitForDecision, waitForRetake, peekStaged, deliverStaged, gridUrl, formatResetDate, waitingLine } from "./stage-wait.mjs";
 
 const args = process.argv.slice(2);
 const noWait = args.includes("--no-wait");
@@ -63,12 +63,20 @@ if (all) {
 let stagingId = target;
 let pageUrl = null;
 let delivered = false;
+// A re-take (staged with --retake-of) waits for its NEW version, not the bite,
+// which is completed already; upload.mjs left the baseline in staged.json.
+let retake = null;
 if (fs.existsSync(target) && fs.statSync(target).isDirectory()) {
   const staged = readStaged(target);
   if (!staged?.stagingId) { console.error(`${target} has no staged.json. Stage it first: node scripts/upload.mjs ${target} --stage-only`); process.exit(1); }
   stagingId = staged.stagingId;
   pageUrl = staged.dashboardUrl ?? null;
   delivered = staged.delivered === true;
+  if (Number.isInteger(staged.retakeOfBiteId) && staged.retakeOfBiteId > 0) {
+    let manifest = null;
+    try { manifest = JSON.parse(fs.readFileSync(path.join(target, "manifest.demobites.json"), "utf8")); } catch {}
+    retake = { biteId: staged.retakeOfBiteId, before: staged.retakeBefore ?? null, videoId: staged.videoId ?? null, studioUrl: staged.studioUrl ?? null, manifest };
+  }
   // A take whose delivery failed (network, 409) is delivered again here; the
   // server is idempotent. An older server (pending) and a kept take (waiting
   // for minutes, the server holds it) are left alone.
@@ -101,5 +109,7 @@ if (noWait) {
   process.exit(st.ok ? 0 : 1);
 }
 
-const outcome = await waitForDecision({ base, apiKey: cfg.api_key, stagingId, pageUrl, delivered });
+const outcome = retake && delivered
+  ? await waitForRetake({ base, apiKey: cfg.api_key, biteId: retake.biteId, videoId: retake.videoId, manifest: retake.manifest, before: retake.before, pageUrl, studioUrl: retake.studioUrl })
+  : await waitForDecision({ base, apiKey: cfg.api_key, stagingId, pageUrl, delivered });
 process.exit(outcome.exitCode);

package/skill/scripts/upload.mjs

@@ -214,6 +214,11 @@ if (attempt) {
   } catch (e) { console.error(`attempt event "uploading" failed: ${e.message} (continuing)`); }
 }
 const previewSizeBytes = fs.statSync(cleanPath).size;
+const { deliverStaged, waitForDecision, waitForRetake, readLiveRecipeFingerprint, gridUrl, waitingLine } = await import("./stage-wait.mjs");
+// RE-TAKE receipt (2026-09-27): the bite stays `completed` while the new
+// version is ingested, so the wait must watch the version, not the bite. The
+// live recipe's fingerprint BEFORE staging is the baseline it must move from.
+const retakeBefore = retakeOfBiteId ? await readLiveRecipeFingerprint({ base, apiKey: cfg.api_key, biteId: retakeOfBiteId }) : null;
 let stageRes;
 try {
   stageRes = await fetch(`${base}/api/recorder/stage`, {
@@ -270,7 +275,6 @@ await putS3(uploadUrl, "application/zip", zipPath, "ZIP");
 await putS3(previewUploadUrl, "video/mp4", cleanPath, "Preview");
 
 // ── delivery: EVERY take becomes a bite by itself ─────────────────────────
-const { deliverStaged, waitForDecision, gridUrl, waitingLine } = await import("./stage-wait.mjs");
 const delivery = await deliverStaged({ base, apiKey: cfg.api_key, stagingId, template: uploadedTemplate });
 const grid = gridUrl(base, delivery.dashboardUrl);
 // The staging id used to be printed only; a batch resumes from disk, so it is
@@ -286,6 +290,7 @@ try {
     biteId: delivery.biteId ?? null, videoId: delivery.videoId ?? null, studioUrl: delivery.studioUrl ? new URL(delivery.studioUrl, base).toString() : null,
     queued: delivery.queued ?? null, pending: delivery.pending ?? null, deliveryError: delivery.error ?? null,
     api: uploadedTemplate ? { uploaded: uploadedTemplate } : null, at: new Date().toISOString(),
+    retakeOfBiteId: retakeOfBiteId ?? null, retakeBefore,
   }, null, 2) + "\n");
 } catch (e) { console.error(`staged.json not written: ${e.message}`); }
 
@@ -304,9 +309,12 @@ function openGrid() {
 if (delivery.delivered) {
   console.log(`Delivered. Watch it come in: ${grid}`);
   openGrid();
-  if (stageOnly) { console.log(`Wait for the bite to finish later with: node scripts/status.mjs ${dir}`); process.exit(0); }
+  if (stageOnly) { console.log(`Wait for the ${retakeOfBiteId ? "new recording" : "bite"} to finish later with: node scripts/status.mjs ${dir}`); process.exit(0); }
   // LAW (founder 2026-08-08): no studio link before the bite is completed.
-  const outcome = await waitForDecision({ base, apiKey: cfg.api_key, stagingId, pageUrl: grid, delivered: true });
+  // A re-take's bite is completed already: wait for the NEW version instead.
+  const outcome = retakeOfBiteId
+    ? await waitForRetake({ base, apiKey: cfg.api_key, biteId: retakeOfBiteId, videoId: delivery.videoId ?? null, manifest, before: retakeBefore, pageUrl: grid, studioUrl: delivery.studioUrl ?? null })
+    : await waitForDecision({ base, apiKey: cfg.api_key, stagingId, pageUrl: grid, delivered: true });
   process.exit(outcome.exitCode);
 }
 if (delivery.waiting) {