demobite 1.0.5 → 1.0.7

package/launcher/index.mjs

@@ -113,6 +113,21 @@ Other MCP clients: any Streamable HTTP client works with the same URL + header.
   return false;
 };
 
+if (arg === "retake") {
+  const biteId = process.argv[3];
+  if (!biteId || !/^\d+$/.test(biteId)) { warn('Usage: npx demobite retake <biteId> [--note "what changed"]'); process.exit(2); }
+  let cfg = readCfg();
+  if (!cfg?.api_key) {
+    console.log("\n  Not connected yet — linking this machine to DemoBites first…\n");
+    const r = spawnSync("node", [path.join(dest, "scripts", "login.mjs")], { stdio: "inherit", cwd: process.cwd() });
+    if (r.status !== 0) process.exit(r.status ?? 1);
+    cfg = readCfg();
+  }
+  if (!cfg?.api_key) { warn("Login did not complete — run: npx demobite login"); process.exit(1); }
+  const r = spawnSync("node", [path.join(dest, "scripts", "retake.mjs"), ...process.argv.slice(3)], { stdio: "inherit", cwd: process.cwd() });
+  process.exit(r.status ?? 1);
+}
+
 if (arg === "mcp") {
   let cfg = readCfg();
   if (!cfg?.api_key) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "demobite",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "The DemoBites agentic recorder — you prompt, it films a real browser, and DemoBites turns the take into an editable demo bite.",
   "bin": {
     "demobite": "launcher/index.mjs"

package/scripts/record.mjs

@@ -36,6 +36,24 @@ for (const [i, s] of STORYBOARD.steps.entries()) {
 }
 
 const DIR = path.resolve(outArg);
+
+// RE-TAKE (founder 2026-09-02): the storyboard IS the bite's DNA. Keep a verbatim
+// copy in the take dir so upload.mjs can stage it as the recording recipe —
+// selectors, urls, typed text, hideCss — the wire manifest alone cannot re-film.
+const ENGINE_VERSION = "1.0.7";
+fs.mkdirSync(DIR, { recursive: true });
+// The copy is the RECIPE, not the transport: cdpWsUrl / storageStatePath are
+// per-take plumbing stamped by the cloud runner (a CDP url carries a session
+// token) — never persisted, never staged.
+const { cdpWsUrl: _cdpStamp, storageStatePath: _ssStamp, ...recipeStoryboard } = STORYBOARD;
+fs.writeFileSync(path.join(DIR, "storyboard.json"), JSON.stringify(recipeStoryboard, null, 2));
+try {
+  const cfgPath = path.resolve(".recorder/config.json");
+  const cfg = fs.existsSync(cfgPath) ? JSON.parse(fs.readFileSync(cfgPath, "utf8")) : {};
+  // Only the public shape — NEVER the api_key or workspace.
+  const config = { app: STORYBOARD.app ?? cfg.app ?? null, url: STORYBOARD.url ?? cfg.url ?? null, frame: cfg.frame ?? { width: 1920, height: 1080 }, base: cfg.base ?? "https://app.demobites.com" };
+  fs.writeFileSync(path.join(DIR, "recipe.json"), JSON.stringify({ version: 1, lane: (process.env.CDP_WS_URL || STORYBOARD.cdpWsUrl) ? "cloud" : "skill", engine: ENGINE_VERSION, config }, null, 2));
+} catch (e) { console.error("recipe.json not written:", e.message); }
 fs.mkdirSync(DIR, { recursive: true });
 
 // LAW (supersampled capture, measured 2026-08-09): deviceScaleFactor is a
@@ -144,17 +162,54 @@ const launchOpts = {
   deviceScaleFactor: 1,
   args: ["--force-color-profile=srgb", "--disable-blink-features=AutomationControlled"],
 };
+
+// THREE ways to get a browser. ONE script serves both lanes — the cloud
+// sandbox runs THIS file. (2026-09-02: a sync that carried only mode C into
+// the sandbox copy crashed every cloud film leg ~85 s after bootstrap.)
+//  A. CDP mode (CDP_WS_URL env or storyboard.cdpWsUrl): connect to a browser
+//     someone else PROVISIONED (Surfsky / Browserbase / sandbox endpoint) and
+//     film in a fresh recording context on it. Never creates or tears down
+//     the remote browser — the provisioner owns it. A connected browser has
+//     no persistent-context video, so newContext({recordVideo}) is the way.
+//  B. Storage-state mode (STORAGE_STATE env or storyboard.storageStatePath,
+//     no CDP): a signed-in take. The caller decrypts a vaulted Playwright
+//     storageState ({cookies, origins:[{origin, localStorage}]}) to a file
+//     and hands us the path; we launch our OWN browser and load that session
+//     into a fresh recording context. The file is opaque here — loaded,
+//     never logged or copied. storageState is per context, so it also rides
+//     into mode A's context when both are set.
+//  C. Launch mode (default): the local persistent Chrome for public urls.
 let ctx;
+let connectedBrowser = null;
+let ownedBrowser = null;
+const cdpWsUrl = process.env.CDP_WS_URL || STORYBOARD.cdpWsUrl || null;
+const storageStatePath = process.env.STORAGE_STATE || STORYBOARD.storageStatePath || null;
+const contextOpts = {
+  viewport: VIEW,
+  recordVideo: { dir: DIR, size: VIEW },
+  deviceScaleFactor: 1,
+  ...(storageStatePath ? { storageState: storageStatePath } : {}),
+};
 const wantChannel = STORYBOARD.channel ?? "chrome";
-try {
-  ctx = await chromium.launchPersistentContext(
-    profileDir,
-    wantChannel === "chromium" ? launchOpts : { ...launchOpts, channel: wantChannel },
-  );
-} catch (launchErr) {
-  if (wantChannel === "chromium") throw launchErr;
-  console.error(`Real Chrome (channel '${wantChannel}') failed to launch (${launchErr.message.split("\n")[0]}); falling back to bundled Chromium.`);
-  ctx = await chromium.launchPersistentContext(profileDir, launchOpts);
+const launchWithFallback = async (launch) => {
+  try {
+    return await launch(wantChannel === "chromium" ? {} : { channel: wantChannel });
+  } catch (launchErr) {
+    if (wantChannel === "chromium") throw launchErr;
+    console.error(`Real Chrome (channel '${wantChannel}') failed to launch (${launchErr.message.split("\n")[0]}); falling back to bundled Chromium.`);
+    return await launch({});
+  }
+};
+if (cdpWsUrl) {
+  connectedBrowser = await chromium.connectOverCDP(cdpWsUrl);
+  ctx = await connectedBrowser.newContext(contextOpts);
+  console.error(`CDP mode: filming in a provided context (${connectedBrowser.contexts().length - 1} pre-existing)${storageStatePath ? ", signed-in session loaded" : ""}.`);
+} else if (storageStatePath) {
+  ownedBrowser = await launchWithFallback((ch) => chromium.launch({ headless: launchOpts.headless, args: launchOpts.args, ...ch }));
+  ctx = await ownedBrowser.newContext(contextOpts);
+  console.error("Storage-state mode: own browser, signed-in session loaded into a fresh recording context.");
+} else {
+  ctx = await launchWithFallback((ch) => chromium.launchPersistentContext(profileDir, { ...launchOpts, ...ch }));
 }
 const page = ctx.pages()[0] || (await ctx.newPage());
 
@@ -315,6 +370,21 @@ const pushShot = (box, tStart, tEnd, label, extra) => {
   });
 };
 
+// User-approved zoom (storyboard flow 2026-08-20, cloud planner + storyboard
+// page): a step may carry zoom {x,y,w,h} in PERCENT of the frame, adjusted by
+// the customer before filming. It overrides the auto shot box. zoom:null means
+// the customer removed the zoom — NO shot for that step. Absent = classic auto.
+const userShotBox = (step, fallback) => {
+  if (step.zoom === null) return null;
+  if (!step.zoom) return fallback ?? null;
+  return {
+    x: (step.zoom.x / 100) * VIEW.width,
+    y: (step.zoom.y / 100) * VIEW.height,
+    width: (step.zoom.w / 100) * VIEW.width,
+    height: (step.zoom.h / 100) * VIEW.height,
+  };
+};
+
 /** LAW (visible-instance pick, dry-run lesson): sticky-header twins and
  *  offscreen duplicates shadow the real control — take the first VISIBLE match
  *  whose top clears minY, retrying while the page settles. */
@@ -323,8 +393,10 @@ async function visibleTarget(selector, minY = 0, timeout = 15000) {
   const waitT0 = Date.now();
   const all = page.locator(selector);
   await all.first().waitFor({ state: "attached", timeout }).catch(() => {});
+  let scrollCorrections = 0;
   for (let tries = 0; tries < 20; tries++) {
     const n = await all.count().catch(() => 0);
+    let offVerticalEl = null; // a visible instance that's only off-frame vertically
     for (let i = 0; i < n; i++) {
       const el = all.nth(i);
       if (!(await el.isVisible().catch(() => false))) continue;
@@ -336,10 +408,26 @@ async function visibleTarget(selector, minY = 0, timeout = 15000) {
       // cursor 360px off the 1920 frame and the click landed off-camera.
       // A target's CENTER must be inside the recorded frame, with margin.
       const cx = b.x + b.width / 2, cy = b.y + b.height / 2;
-      if (cx < 8 || cx > VIEW.width - 8 || cy < 8 || cy > VIEW.height - 8) continue;
+      const offHoriz = cx < 8 || cx > VIEW.width - 8;
+      const offVert = cy < 8 || cy > VIEW.height - 8;
+      if (offHoriz) continue; // a horizontal strip — vertical scroll won't fix it
+      if (offVert) { if (!offVerticalEl) offVerticalEl = el; continue; }
       // Return the ELEMENT alongside its box so callers never re-scan.
       if (b.y >= minY * SUPERSAMPLE) { visibleTarget.lastWaitMs = Date.now() - waitT0; return { box: b, el }; }
     }
+    // ROBUSTNESS (authored-tour scroll drift): a hover/click target the author
+    // named but the authored scroll amounts did not land in the frame is a
+    // below/above-fold instance. Travel to it — scroll it toward the upper
+    // third and re-scan — instead of failing the whole take. Bounded so a
+    // genuinely-unreachable target still ends the loop. This is the camera
+    // following the subject, not a camera-path change.
+    if (offVerticalEl && scrollCorrections < 3) {
+      scrollCorrections++;
+      await offVerticalEl.scrollIntoViewIfNeeded({ timeout: 2000 }).catch(() => {});
+      await page.evaluate(() => window.scrollBy(0, -Math.round(window.innerHeight * 0.28))).catch(() => {});
+      await page.waitForTimeout(450);
+      continue;
+    }
     await page.waitForTimeout(500);
   }
   return { box: null, el: null };
@@ -527,6 +615,49 @@ async function smoothScroll(dy, ms = 1400, within = null) {
   }), [dy, ms, within]);
 }
 
+// ── Head beacon ────────────────────────────────────────────────────────────
+// The identity law (video = wall - record_from) assumes raw.webm's t=0 lines
+// up with T0. That anchoring is otherwise UNMEASURED: on a cold remote-CDP
+// browser it drifts by seconds (the 2026-08-21 Product Hunt class) and even
+// locally the startup lead swings 0–2.5 s between takes (2026-09-02). So
+// MEASURE it: flash the still-blank page full-frame at stamped wall times
+// before any content loads. trim.mjs finds the flashes in raw.webm by scene
+// detection and corrects the cut point; both flashes sit before record_from,
+// so the published cut never contains them. Hover-anchor calibration then
+// measures only the residual.
+try {
+  const flip = async (color) => {
+    const before = t();
+    await page.evaluate((c) => { document.documentElement.style.background = c; }, color);
+    const after = t();
+    // The paint happened between call and return; the midpoint bounds the
+    // stamp error at half a CDP round trip — inside one frame co-located.
+    return { color, wall: (before + after) / 2 };
+  };
+  // Wait for the screencast to actually be ROLLING (first frames on disk):
+  // over a remote CDP link the recorder starts late, and a flash before the
+  // first frame is invisible (mode A smoke, 2026-09-02).
+  const rollDeadline = Date.now() + 5000;
+  while (Date.now() < rollDeadline) {
+    const rolling = fs.readdirSync(DIR).some((f) => f.endsWith(".webm") && fs.statSync(path.join(DIR, f)).size > 4096);
+    if (rolling) break;
+    await page.waitForTimeout(100);
+  }
+  await page.evaluate(() => { document.documentElement.style.background = "#ffffff"; });
+  await page.waitForTimeout(600); // let the white state reach the recording
+  const flips = [];
+  flips.push(await flip("#ff00ff")); // onset 1: white -> magenta
+  await page.waitForTimeout(400);
+  flips.push(await flip("#ffffff")); // onset 2: magenta -> white
+  await page.waitForTimeout(400);
+  manifest.beacon = { flips };
+  process.stdout.write(`beacon: flips at ${flips.map((f) => f.wall.toFixed(3)).join("s, ")}s (wall)\n`);
+} catch (e) {
+  // A failed beacon must never kill a take — trim just falls back to the
+  // stamped anchor, exactly the pre-beacon behavior.
+  console.error("beacon: skipped (" + e.message.split("\n")[0] + ")");
+}
+
 let failure = null;
 try {
   for (const step of STORYBOARD.steps) {
@@ -543,7 +674,10 @@ try {
     process.stdout.write(`step ${rec.n} ${step.action} ${step.label ?? ""}\n`);
     if (step.action === "goto") {
       const navIssuedAt = t();
-      await page.goto(step.url, { waitUntil: "load" });
+      // domcontentloaded, not load: a heavy site behind a proxy (the cloud
+      // browser) can stall `load` 45 s+ on third-party subresources.
+      // record_from / nav.to are still stamped after the paint gates below.
+      await page.goto(step.url, { waitUntil: "domcontentloaded", timeout: 60000 });
       await ensureCursor();
       await applyHideCss();
       if (manifest.record_from !== undefined) {
@@ -623,15 +757,32 @@ try {
       await page.waitForTimeout(settleMs);
       if (step.focus) {
         const box = await visibleBox(step.focus, step.minY ?? 0, 4000);
-        pushShot(box, shotStart, t(), step.label, { n: rec.n });
+        pushShot(userShotBox(step, box), shotStart, t(), step.label, { n: rec.n });
+      } else if (step.zoom) {
+        pushShot(userShotBox(step, null), shotStart, t(), step.label, { n: rec.n });
       }
     } else if (step.action === "scroll") {
       // scrollTo distances are ALSO zoomed-space under CSS zoom (measured:
       // scrollTo(0,600) moves 300 design px) — storyboards speak design px.
+      const shotStart = t();
       await smoothScroll(step.dy * SUPERSAMPLE, ms(step.ms, 1400), step.within ?? null);
+      if (step.zoom) pushShot(userShotBox(step, null), shotStart, t(), step.label, { n: rec.n });
     } else if (step.action === "click" || step.action === "hover") {
-      const { box, el } = await visibleTarget(step.selector, step.minY ?? 0);
-      if (!box) throw new Error("no visible target for " + step.selector);
+      const { box, el } = await visibleTarget(step.selector, step.minY ?? 0, step.action === "hover" ? 8000 : 15000);
+      if (!box) {
+        if (step.action === "hover") {
+          // Storyboard resilience (2026-08-20): a showcase hover whose target
+          // vanished between plan time and film time must not kill the take —
+          // the customer approved a tour, not a selector. Skip the beat and
+          // keep filming; the shot simply never happens.
+          console.log(`MISSING TARGET (hover, skipped): step ${rec.n} ${step.selector}`);
+          rec.skipped = "missing_target";
+          rec.t_end = t();
+          manifest.steps.push(rec);
+          continue;
+        }
+        throw new Error("no visible target for " + step.selector);
+      }
       // SLOW-CONTENT STAMP (Reddit lesson 2026-08-09): a long target wait
       // means the app was loading ON CAMERA — the viewer watched skeletons.
       // The take still completes; the stamp makes the dead air visible at
@@ -684,7 +835,7 @@ try {
         // that, and the same ballistic motion read stiffer for it. The shot
         // begins just before ARRIVAL, so the previous frame holds still
         // while the cursor sweeps across it, then the camera reframes.
-        pushShot(step.focus ? await visibleBox(step.focus, 0, 3000) : box, Math.max(shotStart, arrivalT - 0.3), t(), step.label, { n: rec.n, glide: { t_start: Math.round(shotStart * 100) / 100, t_end: Math.round(arrivalT * 100) / 100 } });
+        pushShot(userShotBox(step, step.focus ? await visibleBox(step.focus, 0, 3000) : box), Math.max(shotStart, arrivalT - 0.3), t(), step.label, { n: rec.n, glide: { t_start: Math.round(shotStart * 100) / 100, t_end: Math.round(arrivalT * 100) / 100 } });
       } else {
         await page.waitForTimeout(ms(step.dwell, DEFAULT_CLICK_DWELL));
         await page.evaluate(([a, b]) => window.__recPulse?.(a, b), [x, y]);
@@ -701,7 +852,7 @@ try {
         }
         // Shot one: the control — beginning near ARRIVAL (see the camera
         // choreography law above), never spanning the approach glide.
-        pushShot(box, Math.max(shotStart, arrivalT - 0.3), t() + 0.3, step.label, { n: rec.n, glide: { t_start: Math.round(shotStart * 100) / 100, t_end: Math.round(arrivalT * 100) / 100 } });
+        pushShot(userShotBox(step, box), Math.max(shotStart, arrivalT - 0.3), t() + 0.3, step.label, { n: rec.n, glide: { t_start: Math.round(shotStart * 100) / 100, t_end: Math.round(arrivalT * 100) / 100 } });
         // LAW (press physics, founder 2026-08-09): a press has a down and an
         // up — but the up only exists if the clicked surface is still there.
         // A menu item or modal button that DESTROYS itself on click gets a
@@ -826,12 +977,24 @@ try {
         await page.keyboard.type(ch);
         await page.waitForTimeout(34 + Math.random() * 70);
       }
-      if (step.enter) {
+      if (step.enter || step.submit) {
+        // `enter` is the skill's spelling, `submit` the cloud planner's.
         await page.waitForTimeout(300);
+        const urlBefore = page.url();
         await page.keyboard.press("Enter");
+        // A submit usually navigates: re-arm the presenter layer on the new
+        // document, exactly like a goto — otherwise the cursor vanishes for
+        // the rest of the take.
+        await page.waitForLoadState("domcontentloaded", { timeout: 30000 }).catch(() => {});
+        if (page.url() !== urlBefore) {
+          await page.waitForLoadState("networkidle", { timeout: 6000 }).catch(() => {});
+          await ensureCursor();
+          await applyHideCss();
+          await page.evaluate(([a, b]) => window.__recSetCursor?.(a, b), [x, y]);
+        }
       }
       // One shot: the field, from arrival through the typing.
-      pushShot(box, Math.max(shotStart, arrivalT - 0.3), t() + 0.3, step.label ?? "type", { n: rec.n, glide: { t_start: Math.round(shotStart * 100) / 100, t_end: Math.round(arrivalT * 100) / 100 } });
+      pushShot(userShotBox(step, box), Math.max(shotStart, arrivalT - 0.3), t() + 0.3, step.label ?? "type", { n: rec.n, glide: { t_start: Math.round(shotStart * 100) / 100, t_end: Math.round(arrivalT * 100) / 100 } });
       currentCursor = await cursorUnderPoint();
       pushMouse("move", cx, cy);
       await page.waitForTimeout(ms(step.after, DEFAULT_CLICK_AFTER));
@@ -865,6 +1028,11 @@ if (video) {
   const vpath = await video.path();
   fs.renameSync(vpath, path.join(DIR, "raw.webm"));
 }
+// CDP mode: disconnect from the provided browser WITHOUT killing it — the
+// provisioner owns the remote browser's lifecycle, not us. Mode B's browser
+// is ours to close.
+if (connectedBrowser) { try { await connectedBrowser.close(); } catch {} }
+if (ownedBrowser) { try { await ownedBrowser.close(); } catch {} }
 fs.writeFileSync(path.join(DIR, "manifest.json"), JSON.stringify(manifest, null, 2));
 if (failure) {
   console.error(`TAKE FAILED at step ${manifest.steps.length + 1}: ${failure.message}`);

package/scripts/trim.mjs

@@ -8,7 +8,7 @@
 // Usage: node trim.mjs <takeDir>
 import fs from "node:fs";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 
 const dir = process.argv[2];
 if (!dir) {
@@ -46,20 +46,62 @@ const clean = path.join(dir, "clean.mp4");
 // took 0.49s to load tilted 0.897x. Both produced ramps of error that read as
 // a broken cursor.
 const r0 = man.record_from ?? 0;
+
+// Head-beacon phase 0: the identity law above fixes the RATE; the beacon
+// fixes the ANCHOR. record.mjs flashed the blank page full-frame at stamped
+// wall times before any content loaded; find those flashes in raw.webm and
+// the difference (stamped wall - observed video time) is the exact anchoring
+// error between t()-space and the video timeline — near zero on a warm local
+// browser, whole seconds on a cold remote-CDP one (2026-08-21 PH class).
+// Shift the cut by it so clean.mp4 truly begins at the record_from moment.
+let beaconDelta = 0;
+let beaconMethod = "";
+if ((man.beacon?.flips?.length ?? 0) >= 2) {
+  const flips = man.beacon.flips;
+  // The flashes are the first big whole-frame changes in the head. Search a
+  // window generous enough for seconds of anchor error in either direction.
+  const searchEnd = Math.min(Math.max(r0, flips[flips.length - 1].wall) + 8, 40);
+  const res = spawnSync("ffmpeg", [
+    "-loglevel", "info", "-t", String(searchEnd), "-i", raw,
+    "-vf", "select='gt(scene,0.3)',showinfo", "-f", "null", "-",
+  ], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+  const onsets = [...`${res.stderr ?? ""}`.matchAll(/pts_time:([0-9.]+)/g)]
+    .map((m) => parseFloat(m[1]));
+  if (onsets.length >= 2) {
+    // Pair the first two onsets to the two flips, in order. Anything the page
+    // paints later (the goto) lands after onset 2 and never enters the pair.
+    const d1 = flips[0].wall - onsets[0];
+    const d2 = flips[1].wall - onsets[1];
+    const spread = Math.abs(d1 - d2);
+    if (spread <= 0.15) {
+      beaconDelta = (d1 + d2) / 2;
+      beaconMethod = ` + head-beacon anchor ${beaconDelta >= 0 ? "+" : ""}${beaconDelta.toFixed(3)}s (2 flips, spread ${(spread * 1000).toFixed(0)}ms)`;
+      console.log(`beacon: anchor error ${beaconDelta >= 0 ? "+" : ""}${beaconDelta.toFixed(3)}s measured (flip spread ${(spread * 1000).toFixed(0)}ms) — cut corrected`);
+    } else {
+      console.log(`beacon: flip deltas disagree (${(spread * 1000).toFixed(0)}ms spread) — ignoring beacon, cut stays as stamped`);
+    }
+  } else {
+    console.log("beacon: flashes not found in the raw head — cut stays as stamped");
+  }
+}
+
+const cutAt = Math.max(0, r0 - beaconDelta);
+if (cutAt !== r0 - beaconDelta) console.log("beacon: corrected cut clamped at 0 — head shorter than the anchor error");
 man.timebase = {
   a: 1,
   b: -r0,
-  method: "identity (raw is wall-rate; see 2026-08-09 four-lane verification)",
+  method: "identity (raw is wall-rate; see 2026-08-09 four-lane verification)" + beaconMethod,
   k: 1,
   videoRecordFrom: r0,
+  ...(beaconMethod ? { beaconDelta } : {}),
 };
 fs.writeFileSync(manPath, JSON.stringify(man, null, 2));
-console.log(`timebase: identity, video = wall - ${r0.toFixed(3)}`);
+console.log(`timebase: identity, video = wall - ${r0.toFixed(3)}${beaconMethod ? ` (cut at raw ${cutAt.toFixed(3)}s)` : ""}`);
 
 execFileSync("ffmpeg", [
   "-y", "-loglevel", "error",
   "-i", raw,
-  "-filter_complex", `[0:v]trim=start=${r0},setpts=PTS-STARTPTS,fps=30,format=yuv420p[out]`,
+  "-filter_complex", `[0:v]trim=start=${cutAt},setpts=PTS-STARTPTS,fps=30,format=yuv420p[out]`,
   "-map", "[out]",
   "-c:v", "libx264", "-preset", "medium", "-crf", "19",
   "-movflags", "+faststart",

package/skill/SKILL.md

@@ -236,6 +236,30 @@ What the human approves on that page is the **picture and the coverage**, never
 
 `upload.mjs` now polls `/api/recorder/status` until the bite reaches `completed` and prints what actually landed. **Read that line before you say anything to the human.** It reports `narrationReady/narrationTotal` segments with real audio behind them, and the camera shot count. If narration is 0, or ready is below total, or shots are 0, say so plainly and investigate. Do not pass on a link with a warning above it as though it were a success.
 
+## Phase 7: Re-take (Launch plan and up)
+
+A bite filmed by this recorder carries its recipe (storyboard, config, manifest) inside DemoBites. When the
+human's app changes, they do not re-record: they ask for a **re-take**, and the same story is filmed again
+against today's app and landed **inside the same bite**. Links, analytics, the bite's current narration text
+(their edits win over the original intent), voice, intro/outro and look are preserved; camera, cuts and audio
+are refitted by the ingestion.
+
+```bash
+node scripts/retake.mjs <biteId> [--note "what changed"]   # or: npx demobite retake <biteId> --note "..."
+```
+
+Laws for a re-take:
+- **Read the note first.** "We moved Export to the header" tells you which step will break before you film.
+- **A step that no longer resolves stops the take at that step.** Look at the live page. If the control moved,
+  fix the selector in the take's `storyboard.json` and run again with `--take <dir>`. If the feature is truly
+  gone, DROP that beat AND its narration line, and tell the human plainly: "This capability no longer exists,
+  we removed it from the video." Nothing stages until every step resolves.
+- **The narration in the recipe is the ORIGINAL intent.** Do not rewrite it to taste: the server replaces it
+  with the bite's current text per step. Only remove lines whose beats you dropped.
+- **Same pacing laws apply** (intro, narrate the path, linger, cut and fade on page transitions).
+- **The human approves in-app.** The preview page says "Re-take of <bite>". Approve replaces the recording in
+  that bite; the previous recording is kept for rollback, never overwritten.
+
 ## The wire manifest (fixed contract, version 2)
 
 `manifest.mjs` produces exactly this shape. All times are relative to the UPLOADED file (record_from already subtracted, clamped at 0). `duration` is the duration of the uploaded clean.mp4.
@@ -280,8 +304,12 @@ PUT <base>/api/recorder/device  { device_code }          (poll every `interval`
 DELETE <base>/api/recorder/key  (Authorization: Bearer <api_key>)
   -> { revoked: true }                                    (logout)
 
+GET <base>/api/recorder/recipe?biteId=<id>  (Authorization: Bearer <api_key>)   // RE-TAKE: the bite's recipe
+  -> { storyboard, config:{app,url,frame}, manifest, engine }   (404 no recipe; 402/403 plan gate)
+
 PUT <base>/api/recorder/stage  (Authorization: Bearer <api_key>)
-  { filename, sizeBytes, previewSizeBytes, manifest }
+  { filename, sizeBytes, previewSizeBytes, manifest, recipe? }, retakeOfBiteId? }
+  // recipe = { version:1, lane:'skill', engine, storyboard, config:{app,url,frame,base} } — the RE-TAKE DNA (never the api_key)
   -> { stagingId, uploadUrl, previewUploadUrl, videoKey, previewUrl }
 
 GET <base>/api/recorder/stage?id=<stagingId>  (Authorization: Bearer <api_key>)

package/skill/scripts/retake.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// RE-TAKE (local lane, Phase 1 — founder 2026-09-02): re-film a bite that was
+// recorded by the agentic recorder, against the app as it is TODAY, and land
+// the new footage INSIDE THE SAME BITE. The bite's recipe (storyboard + config)
+// 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>]
+//
+// Flow: recipe -> storyboard.json -> record -> trim -> calibrate (gate) ->
+// manifest -> upload --retake-of <biteId> (stages; the human approves in-app,
+// where the preview says "Re-take of <bite>").
+//
+// 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.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const biteId = Number(args[0]);
+if (!Number.isInteger(biteId) || biteId <= 0) {
+  console.error('Usage: node retake.mjs <biteId> [--note "what changed"] [--take <dir>]');
+  process.exit(2);
+}
+const opt = (name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
+const note = opt("--note") ?? "";
+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(/\/+$/, "");
+
+// 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) {
+  console.error(`Bite ${biteId} has no recording recipe. Only bites filmed by the agentic recorder (engine 1.0.6 or later) can be re-taken.`);
+  process.exit(1);
+}
+if (res.status === 402 || res.status === 403) {
+  const body = await res.json().catch(() => ({}));
+  console.error(body?.message || "Re-take is available from the Launch plan. Upgrade in DemoBites to use it.");
+  process.exit(1);
+}
+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); }
+
+// 2. Take dir + files.
+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));
+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})` : ""}.`);
+if (note) console.log(`Note from the human: ${note}`);
+
+// 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]);
+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)}` : ""}`);
+  process.exit(r.status ?? 1);
+}
+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); }
+r = run("manifest.mjs", [takeDir]); if (r.status !== 0) process.exit(r.status ?? 1);
+r = run("upload.mjs", [takeDir, "--retake-of", String(biteId)]);
+process.exit(r.status ?? 0);

package/skill/scripts/upload.mjs

@@ -29,6 +29,12 @@ if (!dir) {
   console.error("Usage: node upload.mjs <takeDir>");
   process.exit(2);
 }
+// RE-TAKE (2026-09-02): `--retake-of <biteId>` stages this take as a NEW RECORDING
+// of an existing bite instead of a new bite. The server keeps the bite's current
+// narration text, voice, intro/outro and look; the human approves in-app.
+const retakeIdx = process.argv.indexOf("--retake-of");
+const retakeOfBiteId = retakeIdx >= 0 ? Number(process.argv[retakeIdx + 1]) : null;
+if (retakeIdx >= 0 && !(Number.isInteger(retakeOfBiteId) && retakeOfBiteId > 0)) { console.error("--retake-of needs a bite id"); process.exit(2); }
 const cfgPath = path.resolve(".recorder", "config.json");
 let cfg = {};
 try { cfg = JSON.parse(fs.readFileSync(cfgPath, "utf8")); } catch {}
@@ -40,6 +46,19 @@ const base = cfg.base.replace(/\/+$/, "");
 
 const cleanPath = path.join(dir, "clean.mp4");
 const wirePath = path.join(dir, "manifest.demobites.json");
+// Recording recipe (RE-TAKE, 2026-09-02): storyboard + public config, written by
+// record.mjs. Staged next to the manifest so the bite can be re-filmed later.
+// Absent on takes filmed by older engines — staging still works without it.
+let recipe = null;
+try {
+  const sbPath = path.join(dir, "storyboard.json");
+  const rcPath = path.join(dir, "recipe.json");
+  if (fs.existsSync(sbPath)) {
+    const rc = fs.existsSync(rcPath) ? JSON.parse(fs.readFileSync(rcPath, "utf8")) : {};
+    recipe = { version: 1, lane: rc.lane ?? "skill", engine: rc.engine ?? null, storyboard: JSON.parse(fs.readFileSync(sbPath, "utf8")), config: rc.config ?? {} };
+    if (recipe.config && "api_key" in recipe.config) delete recipe.config.api_key;
+  }
+} catch (e) { console.error("recipe skipped:", e.message); }
 if (!fs.existsSync(cleanPath)) { console.error(`${cleanPath} not found. Run: node scripts/trim.mjs ${dir}`); process.exit(1); }
 if (!fs.existsSync(wirePath)) { console.error(`${wirePath} not found. Run: node scripts/manifest.mjs ${dir}`); process.exit(1); }
 const manifest = JSON.parse(fs.readFileSync(wirePath, "utf8"));
@@ -115,6 +134,7 @@ if (!zipped) {
 fs.rmSync(staging, { recursive: true, force: true });
 const sizeBytes = fs.statSync(zipPath).size;
 console.log(`take.zip ready (${(sizeBytes / 1024 / 1024).toFixed(1)} MB, ${zipped ? "system zip" : "store method"})`);
+if (retakeOfBiteId) console.log(`Staging as a RE-TAKE of bite ${retakeOfBiteId} — the new recording replaces the current one inside that bite once approved.`);
 
 // ── stage ──────────────────────────────────────────────────────────────────
 const authHeaders = { Authorization: `Bearer ${cfg.api_key}`, "Content-Type": "application/json" };
@@ -124,7 +144,7 @@ try {
   stageRes = await fetch(`${base}/api/recorder/stage`, {
     method: "PUT",
     headers: authHeaders,
-    body: JSON.stringify({ filename: "take.zip", sizeBytes, previewSizeBytes, manifest }),
+    body: JSON.stringify({ filename: "take.zip", sizeBytes, previewSizeBytes, manifest, ...(recipe ? { recipe } : {}), ...(retakeOfBiteId ? { retakeOfBiteId } : {}) }),
   });
 } catch (e) {
   console.error(`Could not reach ${base}: ${e.message}`);