demobite 1.0.9 → 1.2.0

package/scripts/trim.mjs

@@ -15,15 +15,8 @@ if (!dir) {
   console.error("Usage: node trim.mjs <takeDir>");
   process.exit(2);
 }
-const requireTool = (tool) => {
-  try { execFileSync(tool, ["-version"], { stdio: "ignore" }); }
-  catch {
-    console.error(`${tool} is required on PATH. Install it (macOS: brew install ffmpeg) and rerun.`);
-    process.exit(1);
-  }
-};
-requireTool("ffmpeg");
-requireTool("ffprobe");
+import { ffmpeg as FFMPEG, ffprobe as FFPROBE, requireMediaTools } from "./media-tools.mjs";
+requireMediaTools();
 
 const raw = path.join(dir, "raw.webm");
 const manPath = path.join(dir, "manifest.json");
@@ -61,7 +54,7 @@ if ((man.beacon?.flips?.length ?? 0) >= 3) {
   // 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) + 10, 45);
-  const res = spawnSync("ffmpeg", [
+  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 });
@@ -111,6 +104,28 @@ if ((man.beacon?.flips?.length ?? 0) >= 3) {
 }
 
 const cutAt = Math.max(0, r0 - beaconDelta);
+
+// TAIL law (vanilla-Linux smoke 2026-09-09): raw.webm keeps receiving frames
+// while the browser context tears down — on a headless shell that was a
+// ~10 s FROZEN tail after the last beat, and the agent had to cut it by hand.
+// The story ends where the recorder's last step ended; keep one breath after
+// it and cut the rest. Clean time = wall - record_from (identity law above),
+// so the story's end in raw time is cutAt + (lastStepEnd - r0). Only applied
+// when the raw file actually runs on past that point.
+const TAIL_BEAT_S = 0.8;
+const lastStepEnd = Math.max(0, ...(man.steps ?? []).map((st) => Number(st.t_end) || 0));
+let tailCut = 0;
+if (lastStepEnd > r0) {
+  const storyEndRaw = cutAt + (lastStepEnd - r0) + TAIL_BEAT_S;
+  let rawDur = 0;
+  try {
+    rawDur = parseFloat(execFileSync(FFPROBE(), ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", raw]).toString().trim()) || 0;
+  } catch { /* webm without a duration header — fall through, no tail cut */ }
+  if (rawDur && rawDur - storyEndRaw > 1.0) {
+    tailCut = Math.round(storyEndRaw * 100) / 100;
+    console.log(`tail: raw runs ${(rawDur - storyEndRaw).toFixed(1)}s past the last beat — cutting at ${tailCut.toFixed(2)}s (last step ended at ${(lastStepEnd - r0).toFixed(2)}s of clean time)`);
+  }
+}
 if (cutAt !== r0 - beaconDelta) console.log("beacon: corrected cut clamped at 0 — head shorter than the anchor error");
 man.timebase = {
   a: 1,
@@ -123,17 +138,17 @@ man.timebase = {
 fs.writeFileSync(manPath, JSON.stringify(man, null, 2));
 console.log(`timebase: identity, video = wall - ${r0.toFixed(3)}${beaconMethod ? ` (cut at raw ${cutAt.toFixed(3)}s)` : ""}`);
 
-execFileSync("ffmpeg", [
+execFileSync(FFMPEG(), [
   "-y", "-loglevel", "error",
   "-i", raw,
-  "-filter_complex", `[0:v]trim=start=${cutAt},setpts=PTS-STARTPTS,fps=30,format=yuv420p[out]`,
+  "-filter_complex", `[0:v]trim=${tailCut ? `start=${cutAt}:end=${tailCut}` : `start=${cutAt}`},setpts=PTS-STARTPTS,fps=30,format=yuv420p[out]`,
   "-map", "[out]",
   "-c:v", "libx264", "-preset", "medium", "-crf", "19",
   "-movflags", "+faststart",
   clean,
 ], { stdio: "inherit" });
 
-const dur = execFileSync("ffprobe", [
+const dur = execFileSync(FFPROBE(), [
   "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", clean,
 ]).toString().trim();
 const duration = parseFloat(dur);

package/skill/SKILL.md

@@ -7,7 +7,7 @@ description: Film a product demo by driving a real browser from a storyboard and
 
 You are the camera operator, the director, and the editor. You film a real browser doing a real flow, narrate it, and deliver a clean take into DemoBites, where everything — voice, camera, cursor, look — becomes editable. There is ONE delivery: a DemoBites bite. Never ask how the demo should be delivered.
 
-All scripts live in `scripts/` beside this file. They are plain Node ESM. Requirements: Node 18+, `playwright` installed with Chromium (`npm i playwright && npx playwright install chromium`), and `ffmpeg` on PATH. Run every script from the project directory so `.recorder/` lands next to the project.
+All scripts live in `scripts/` beside this file. They are plain Node ESM. Requirements: Node 18+. `npx demobite` installs Playwright, ffmpeg and ffprobe beside the skill; every script resolves the media tools through `scripts/media-tools.mjs` (a compatible system build first, then the packaged one). Never call `ffmpeg` or `ffprobe` by bare name in a new script. Run every script from the project directory so `.recorder/` lands next to the project.
 
 Follow the phases in order. Never skip the storyboard approval. Never ingest before the human's word — for DemoBites, Approve on the in-app preview page IS the word.
 
@@ -82,6 +82,29 @@ When a page you need shows a login wall (login form, auth redirect, checkpoint p
 
 Write the storyboard as JSON before touching the camera.
 
+### Phase 3a: Harvest the product's vocabulary FIRST
+
+The demo speaks the product's CURRENT words, never the brief's, never the pull request's, never your memory's. Products get renamed between the moment a brief is written and the moment you film (founder, 2026-09-14: a take said "Release Readiness" while the app's rail said "Assignments").
+
+```bash
+node scripts/vocab.mjs <takeDir> <url of every screen the take visits>
+```
+
+It opens each screen on the recorder profile, without video, hovers the rail so tooltips render, and writes `<takeDir>/vocab.json`: nav labels with their tooltips and aria labels, page headings, button and link labels, dialog titles. **Every noun in `narration` and `on_screen` must appear in vocab.json.** The brief's and the PR's words are hints about WHAT changed and where to look; when a brief's noun is missing from the app, say so in the storyboard presentation ("the brief says allowlist, the app says Who can enter") and use the app's word.
+
+### LAW: the camera shows an action to its end
+
+The agent sits on the running product with a signed-in account. It knows the flow. It performs it. A take that walks into an empty page and narrates "if there were something here" is forbidden; so is "here you would see" (founder, 2026-09-14).
+
+- **a. Reversible actions are performed for real.** Create the briefing, add the bites, create the assignment with safe people, move the zoom, press Save. Reversible means you can return the workspace to its prior state after the cut.
+- **b. Every take returns the workspace to its initial state, after the camera stops.** The storyboard declares the plan in `cleanup[]` (steps, same schema, run headless by `cleanup.mjs` after `record.mjs`, before `upload.mjs`) and in `cleanup_plan[]` (plain sentences the human reads: "After the cut: delete briefing X, remove assignment Y"). `checks.after[]` proves it (expect / absent selectors). A step you cannot revert is not performed.
+- **c. Irreversible actions are not performed.** An export that spends minutes, an email to real people, a payment, a publish to a real customer's live page, deleting existing content. The cursor goes to the control, the narration names what it does, the button is not pressed. That is the 99 percent rule: bring the viewer to the last click and name it. Mark these beats in the storyboard with `"pointed": true` and in the presentation with "pointed at, not pressed".
+- **d. Cancel is never a beat.** Never say "we cancel because this is a demo", never zoom on a Cancel button, never make the escape a scene. A dialog that must close without committing closes through the X, the backdrop or Escape, off narration, without a zoom, in the gap between beats. When the dialog's confirm IS reversible, press it (rule a).
+- **e. Empty states are a failure of preparation, not a scene.** If the flow needs data, `prep[]` creates it before the camera (`node scripts/cleanup.mjs <takeDir> --prep`, checked by `checks.before[]`), the take shows the flow, `cleanup[]` removes it.
+- **f. Never present a screen you did not reach.**
+
+`upload.mjs` refuses to stage a take whose storyboard declares `cleanup[]` until `cleanup.json` says the cleanup ran and its checks passed (`--allow-uncleaned` overrides, and prints that it did).
+
 ### LAW: the video is the metronome, not the script
 
 **The narration is INTENT, never final copy.** In the DemoBites ending it is handed to the ingestion, which rescripts it and refits it to the video exactly as it does for a customer's own uploaded voice. So never stretch a shot to cover a sentence. A shot is as long as the ACTION needs, and the words get fitted to it afterwards.
@@ -132,6 +155,34 @@ Storyboard schema:
 
 Step fields: `action` is one of `goto | settle | scroll | click | hover | type | expect`. **Durations (`dwell`, `after`, settle `ms`, scroll `ms`) are milliseconds; a value under 60 is read as seconds** (write `"dwell": 3400` or `"dwell": 3.4`, never `"dwell": 3` meaning 3 ms). `goto` needs `url`. `settle` takes `ms` and an optional `focus` selector. `scroll` needs `dy` and takes `ms`. `click`/`hover` need `selector` and take `minY` (minimum Y for the visible instance pick), `dwell`, `after`, `waitLoad`. Every step takes `label` and `narration`.
 
+Beyond `steps`, a storyboard may carry the off-camera blocks (Phase 3a/law above); `cleanup.mjs` runs them on the same profile without video:
+
+```json
+{
+  "prep": [ { "action": "goto", "url": "https://app.acme.com/briefings" }, { "action": "click", "selector": "button:has-text('Create')", "after": 2000 } ],
+  "checks": { "before": [ { "action": "expect", "selector": "text=Demo briefing" } ], "after": [ { "action": "absent", "selector": "text=Demo briefing" } ] },
+  "cleanup": [ { "action": "goto", "url": "https://app.acme.com/briefings" }, { "action": "click", "selector": "button:has-text('Delete')", "after": 1500 } ],
+  "cleanup_plan": [ "After the cut: delete the briefing 'Demo briefing' created for this take.", "After the cut: remove the assignment for demo@acme.com." ]
+}
+```
+
+Off-camera steps add `press` (`"key": "Escape"`), `wait` (`"ms"`), `expect` and `absent` (checks).
+
+A real cleanup, taken from a filmed take (DemoBites, the Enablement Center list): the row menu is a button with `title="Briefing options"`, Delete opens a dialog that asks the name to be typed, then "Permanently Delete".
+
+```json
+"cleanup": [
+  { "action": "goto", "url": "https://app.demobites.com/enablement-center", "after": 4000 },
+  { "action": "click", "selector": "div.group:has-text('Onboarding briefing (demo)') button[title='Briefing options']", "after": 800 },
+  { "action": "click", "selector": "[role='menu'] [role='menuitem']:has-text('Delete')", "after": 1200 },
+  { "action": "type", "selector": "[role='dialog'] input", "text": "Onboarding briefing (demo)" },
+  { "action": "click", "selector": "[role='dialog'] button:has-text('Permanently Delete')", "after": 4000 }
+],
+"checks": { "after": [ { "action": "absent", "selector": "text=Onboarding briefing (demo)" } ] }
+```
+
+ A step with `"required": false` may fail without stopping the rest. A camera step with `"pointed": true` is an irreversible action the cursor reaches and names but never presses (law c).
+
 Two fields carry the whole advantage of this lane, so fill them in:
 
 - **`on_screen`** describes what the viewer is looking at during the beat. It rides into the ingestion's rescripting stage, so the model writes narration while KNOWING the cursor is on the degree badge and the menu just opened. A microphone can never supply this. Write it for every narrated beat.
@@ -141,6 +192,8 @@ Use `hideCss` for chat widgets and cookie banners that would pollute the picture
 
 **Show the storyboard inline and get approval before filming.** Present it as a numbered shot list, not raw JSON. Say the target length out loud so the human can push back on pacing before you burn a take. Iterate until they say go.
 
+The presentation has three blocks, always: the shot list (irreversible beats marked "pointed at, not pressed"), **"Before the camera"** (what `prep[]` creates) and **"After the cut"** (the `cleanup_plan[]` sentences). A storyboard whose flow needs data and has no prep, or creates anything and has no cleanup plan, is not ready to show.
+
 ## LAW: bot walls — one human checkpoint, never a disguise
 
 Some sites challenge automated browsers. The protocol, in order, no
@@ -192,7 +245,9 @@ Only come back to the human when a PRODUCT question remains that you cannot deci
 ## Phase 5: The take
 
 ```bash
+node scripts/cleanup.mjs <takeDir> --prep       # only when the storyboard has prep[]: creates the data, runs checks.before
 node scripts/record.mjs <takeDir> <storyboard.json>
+node scripts/cleanup.mjs <takeDir>              # only when the storyboard has cleanup[]: reverts, runs checks.after, writes cleanup.json
 ```
 
 Outputs `raw.webm` and `manifest.json` (internal schema, absolute times) into `<takeDir>`. The recorder stamps `record_from`: the moment the first page was FULLY loaded (networkidle plus a beat). Everything before it gets trimmed in both endings, so the published cut always opens on a loaded page.
@@ -218,7 +273,7 @@ Send the TRIMMED CLEAN take into DemoBites. The studio owns the look: NO backdro
 node scripts/trim.mjs <takeDir>             # raw.webm -> clean.mp4, trim from record_from ONLY
 node scripts/calibrate.mjs <takeDir>        # anchor-measure the clock against the footage
 node scripts/manifest.mjs <takeDir>         # internal manifest -> manifest.demobites.json (wire schema)
-node scripts/upload.mjs <takeDir>           # STAGE the take + open the in-app preview
+node scripts/upload.mjs <takeDir>           # STAGE the take + open the in-app preview (refuses an uncleaned take)
 ```
 
 **The human word lives in the product now.** `upload.mjs` stages the take (the
@@ -260,6 +315,32 @@ Laws for a re-take:
 - **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.
 
+## Batch of briefs (GitHub PR → demos)
+
+The human pastes a bundle of approved briefs into the chat: a header (batchId, workspaceId, the target URL, the 90 second rule) and one block per brief (briefId, revision, contentHash, title, audience, outcome, flowIntent). Up to five briefs. The pasted text is a copy; the server holds the truth.
+
+```bash
+node scripts/briefs.mjs list <batchId> [--paste bundle.txt]        # the approved briefs; warns when the paste drifted
+node scripts/briefs.mjs claim <batchId> <briefId>                   # mints an attempt, creates take-<briefId>-r<revision>/brief.json
+node scripts/briefs.mjs event <takeDir> planning|awaiting_storyboard_approval|recording|uploading|failed|cancelled [--note "..."]
+node scripts/briefs.mjs release <takeDir>                           # give the brief back (cancelled)
+node scripts/upload.mjs <takeDir> --stage-only --no-open            # stage with the attempt riding along, do not wait
+node scripts/status.mjs <takeDir>                                   # later: wait for the word, then for the bite
+node scripts/status.mjs --all                                       # one look at every staged take here
+```
+
+The procedure, in order:
+
+1. `list` first, always, with `--paste` when the human pasted text. Work from the server's briefs, never from the paste, and say so when they differ.
+2. Claim the briefs you are about to film, one `claim` each. A claim answers "active attempt" when another agent or an earlier run holds the brief: show the human the attempt reference and its start time, and only with their word claim again with `--force`.
+3. Run `vocab.mjs` over the screens each brief visits, then write every storyboard (Phase 3) with the brief as the spec and vocab.json as the only dictionary: the flowIntent lines are the beats, the outcome is the last beat, the exclusions are things the camera never shows, and the take stays under the brief's `maxSeconds` (90). Send `event <takeDir> planning` when you start a storyboard and `event <takeDir> awaiting_storyboard_approval` when it is ready.
+4. **Show the storyboards together, get a word on each one.** One message can carry all of them, but every brief gets its own yes or no. Never take one yes as a yes for the batch. A brief the human declines gets `release`.
+5. Film sequentially, never in parallel: one Chrome on the profile. Per take: `event recording` → Phase 4 dry run → `cleanup.mjs --prep` when declared → Phase 5 take → `cleanup.mjs` (revert, checks.after) → trim, calibrate, manifest → `upload.mjs <takeDir> --stage-only --no-open`. Report, per take, what was created and what was reverted, with the before/after checks. `upload.mjs` reads `brief.json`, moves the attempt to uploading and stages with the attempt on the payload; it writes `staged.json` with the staging id.
+6. **A failed brief never stops the others.** On a failure send `event <takeDir> failed --note "<what happened>"`, keep the take directory for diagnosis, and continue with the next brief. Report every failure plainly at the end.
+7. When all takes are staged, tell the human: N takes are waiting in the review queue (the `queueUrl` printed by the last stage), one Approve or Discard each. Then `status.mjs --all` shows where each stands; `status.mjs <takeDir>` waits for one.
+
+Resume after an interruption from what is on disk and on the server: a `take-*` directory with `brief.json` is claimed; with `raw.webm` it was filmed; with `clean.mp4` and `manifest.demobites.json` it is ready to stage; with `staged.json` it is staged (check it with `status.mjs --no-wait`). `list` shows the server's view of every attempt. Never re-claim a brief that already has your own live attempt; never re-stage one that `staged.json` says is staged unless the human asked for a new take (`upload.mjs --supersede`).
+
 ## 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.
@@ -329,4 +410,4 @@ The upload zip contains exactly one file: `clean.mp4` stored as `recording.mp4`.
 - Anything the human sees (storyboard presentation, review page, questions) uses commas and periods only, no dashes, and real action words. Never orphan a single word on its own line in a heading.
 - Never touch credentials. Never print the api_key. Config and key files are chmod 600.
 - Never INGEST without the human's explicit word. For the DemoBites ending, staging for the in-app preview is HOW the word is asked — the take becomes a bite only when the human clicks Approve on that page.
-- One take directory per take, keep failed takes for diagnosis, name them `take-<slug>`, `take-<slug>2`, and so on.
+- One take directory per take, keep failed takes for diagnosis, name them `take-<slug>`, `take-<slug>2`, and so on. A take claimed from a brief is `take-<briefId>-r<revision>`.

package/skill/scripts/briefs.mjs

@@ -0,0 +1,164 @@
+// Batch of briefs (GitHub PR → demos, 2026-09-13). The human pastes a bundle
+// 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 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
+//   node briefs.mjs release <takeDir|attemptRef> [--note "..."]   = event cancelled (give the brief back)
+//
+// Server contract (dbrec_ key, scope record):
+//   GET /api/recorder/briefs?batch=<batchId>
+//   PUT /api/recorder/briefs/claim { briefId, revision, contentHash, idempotencyKey, force? }
+//   PUT /api/recorder/briefs/attempts/<attemptRef> { event, note? }
+// The stage call (upload.mjs) sends the attempt from <takeDir>/brief.json.
+//
+// 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.
+import fs from "node:fs";
+import path from "node:path";
+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])));
+
+function usage(code = 2) {
+  console.error(`Usage:
+  node briefs.mjs list <batchId> [--paste <file>]
+  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();
+
+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(/\/+$/, "");
+const headers = { Authorization: `Bearer ${cfg.api_key}`, "Content-Type": "application/json" };
+
+async function api(method, p, body) {
+  let res;
+  try {
+    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); }
+  return { status: res.status, ok: res.ok, json };
+}
+
+export function takeDirFor(briefId, revision) {
+  const safe = String(briefId).replace(/[^A-Za-z0-9._-]+/g, "-");
+  return `take-${safe}-r${revision}`;
+}
+
+/** The pasted bundle: one block per brief with briefId / revision / contentHash lines. */
+function parsePaste(text) {
+  const out = new Map();
+  const blocks = text.split(/\n(?=\s*briefId\s*[:=])/i);
+  for (const b of blocks) {
+    const id = b.match(/briefId\s*[:=]\s*([A-Za-z0-9._-]+)/i)?.[1];
+    if (!id) continue;
+    const revision = b.match(/revision\s*[:=]\s*(\d+)/i)?.[1];
+    const hash = b.match(/contentHash\s*[:=]\s*([A-Za-z0-9:_-]+)/i)?.[1];
+    out.set(id, { revision: revision !== undefined ? Number(revision) : null, contentHash: hash ?? null });
+  }
+  return out;
+}
+
+function printBatch(data) {
+  const { batch, briefs } = data;
+  const src = batch?.source ? `${batch.source.repo}#${batch.source.prNumber}` : "";
+  console.log(`Batch ${batch?.id ?? "?"}  ${src}  target ${batch?.target?.url ?? "?"}${batch?.target?.environment ? ` (${batch.target.environment})` : ""}`);
+  console.log(`${briefs.length} brief${briefs.length === 1 ? "" : "s"}, each at most 90 seconds. One storyboard approval per brief.`);
+  for (const b of briefs) {
+    const att = b.attempt ? ` · attempt ${b.attempt.ref} (${b.attempt.state})` : "";
+    console.log(`\n  ${b.briefId}  r${b.revision}  ${b.status}${att}\n  ${b.title}\n  audience: ${b.audience}\n  outcome: ${b.outcome}${b.estimatedDurationSec ? `\n  about ${b.estimatedDurationSec}s` : ""}`);
+    for (const f of b.flowIntent ?? []) console.log(`    · ${f}`);
+    if (b.prerequisites?.length) console.log(`  needs: ${b.prerequisites.join("; ")}`);
+    if (b.exclusions?.length) console.log(`  never: ${b.exclusions.join("; ")}`);
+  }
+}
+
+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.");
+    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") {
+  const batchId = positional[0];
+  if (!batchId) usage();
+  const data = await fetchBatch(batchId);
+  printBatch(data);
+  const pasteFile = opt("--paste");
+  if (pasteFile) {
+    let text = "";
+    try { text = fs.readFileSync(pasteFile, "utf8"); } catch (e) { console.error(`--paste ${pasteFile}: ${e.message}`); process.exit(2); }
+    const pasted = parsePaste(text);
+    let drift = 0;
+    for (const b of data.briefs) {
+      const p = pasted.get(String(b.briefId));
+      if (!p) { console.error(`\nWARNING: brief ${b.briefId} is in the batch but not in the pasted text.`); drift++; continue; }
+      if (p.contentHash && p.contentHash !== b.contentHash) { console.error(`\nWARNING: brief ${b.briefId}: the pasted contentHash differs from the approved revision r${b.revision}. Work from the approved text above, not the paste.`); drift++; }
+      if (p.revision !== null && p.revision !== b.revision) { console.error(`\nWARNING: brief ${b.briefId}: pasted revision r${p.revision}, approved revision r${b.revision}.`); drift++; }
+    }
+    for (const id of pasted.keys()) if (!data.briefs.some((b) => String(b.briefId) === id)) { console.error(`\nWARNING: pasted brief ${id} is not in batch ${batchId}.`); drift++; }
+    if (drift === 0) console.log("\nThe pasted bundle matches the approved briefs.");
+    else process.exitCode = 3;
+  }
+}
+
+if (cmd === "claim") {
+  const [batchId, briefId] = positional;
+  if (!batchId || !briefId) usage();
+  const data = await fetchBatch(batchId);
+  const brief = data.briefs.find((b) => String(b.briefId) === String(briefId));
+  if (!brief) { console.error(`Brief ${briefId} is not in batch ${batchId}.`); process.exit(1); }
+  const idempotencyKey = crypto.createHash("sha256").update(`${batchId}:${brief.briefId}:${brief.revision}:${brief.contentHash}`).digest("hex").slice(0, 32);
+  const body = { briefId: brief.briefId, revision: brief.revision, contentHash: brief.contentHash, idempotencyKey, ...(flag("--force") ? { force: true } : {}) };
+  const r = await api("PUT", "/api/recorder/briefs/claim", body);
+  if (r.status === 409 && r.json?.error === "active_attempt") {
+    const a = r.json.active_attempt ?? r.json;
+    console.error(`Brief ${briefId} already has a live attempt (${a.attemptRef ?? "?"}${a.since ? `, since ${a.since}` : ""}). Show this to the human; with their word, claim again with --force to supersede it.`);
+    process.exit(1);
+  }
+  if (r.status === 409 && r.json?.error === "hash_mismatch") { console.error(`Brief ${briefId}: the content hash does not match the approved revision. Run list again and work from the approved text.`); process.exit(1); }
+  if (r.status === 410) { console.error(`Brief ${briefId} r${brief.revision} was superseded by a newer revision. Run list again.`); process.exit(1); }
+  if (!r.ok || !r.json?.attemptRef) { console.error(`Claim failed: ${r.status} ${r.json ? JSON.stringify(r.json).slice(0, 200) : ""}`); process.exit(1); }
+  const dir = takeDirFor(brief.briefId, brief.revision);
+  fs.mkdirSync(dir, { recursive: true });
+  const record = {
+    batchId, briefId: brief.briefId, revision: brief.revision, contentHash: brief.contentHash, attemptRef: r.json.attemptRef,
+    brief: r.json.brief ?? brief, target: r.json.target ?? data.batch?.target ?? null, rules: r.json.rules ?? { maxSeconds: 90 },
+    source: data.batch?.source ?? null, claimedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(path.join(dir, "brief.json"), JSON.stringify(record, null, 2) + "\n");
+  console.log(`Claimed ${brief.briefId} r${brief.revision} → ${dir}/brief.json (attempt ${r.json.attemptRef}, at most ${record.rules.maxSeconds}s)`);
+  console.log(`Title: ${record.brief.title}\nTarget: ${record.target?.url ?? "?"}`);
+}
+
+if (cmd === "event" || cmd === "release") {
+  const ref = positional[0];
+  const event = cmd === "release" ? "cancelled" : positional[1];
+  const EVENTS = ["planning", "awaiting_storyboard_approval", "recording", "uploading", "failed", "cancelled"];
+  if (!ref || !EVENTS.includes(event)) usage();
+  let attemptRef = ref;
+  if (fs.existsSync(ref) && fs.statSync(ref).isDirectory()) {
+    try { attemptRef = JSON.parse(fs.readFileSync(path.join(ref, "brief.json"), "utf8")).attemptRef; } catch { console.error(`${ref}/brief.json not found or unreadable.`); process.exit(1); }
+  }
+  const note = opt("--note");
+  const r = await api("PUT", `/api/recorder/briefs/attempts/${encodeURIComponent(attemptRef)}`, { event, ...(note ? { note: note.slice(0, 600) } : {}) });
+  if (r.status === 409) { console.error(`Event "${event}" refused for ${attemptRef}: ${r.json?.message ?? r.json?.error ?? "state does not allow it"} (current: ${r.json?.state ?? "?"}).`); process.exit(1); }
+  if (!r.ok) { console.error(`Event failed: ${r.status} ${r.json ? JSON.stringify(r.json).slice(0, 200) : ""}`); process.exit(1); }
+  console.log(`${attemptRef}: ${r.json?.state ?? event}`);
+}

package/skill/scripts/cleanup.mjs

@@ -0,0 +1,104 @@
+// Prep and cleanup around a take, off camera (law: the camera shows an action
+// to its end, and every take returns the workspace to its initial state).
+//
+//   node cleanup.mjs <takeDir> --prep       run storyboard.prep[] then storyboard.checks.before[]
+//   node cleanup.mjs <takeDir>              run storyboard.cleanup[] then storyboard.checks.after[]
+//
+// Steps use the storyboard's own step schema, no video, headless on the
+// recorder profile: goto | click | type | press | hover | wait | expect | absent.
+//   { "action": "press", "key": "Escape" }                 close a dialog through the keyboard
+//   { "action": "wait", "ms": 1500 }
+//   { "action": "expect", "selector": "text=Foo" }          must be visible (a check)
+//   { "action": "absent", "selector": "text=Foo" }          must NOT be visible (a check)
+// `checks.before` runs after prep, `checks.after` runs after cleanup; both are
+// lists of expect/absent steps. Writes <takeDir>/prep.json or cleanup.json
+// { ran, checks, ok, at }. upload.mjs refuses to stage a take whose storyboard
+// declares cleanup[] until cleanup.json says ok:true (--allow-uncleaned to
+// override, loudly).
+import fs from "node:fs";
+import path from "node:path";
+import { chromium } from "playwright";
+
+const dir = process.argv[2];
+const prep = process.argv.includes("--prep");
+if (!dir) { console.error("Usage: node cleanup.mjs <takeDir> [--prep]"); process.exit(2); }
+const sb = JSON.parse(fs.readFileSync(path.join(dir, "storyboard.json"), "utf8"));
+const steps = prep ? (sb.prep ?? []) : (sb.cleanup ?? []);
+const checks = prep ? (sb.checks?.before ?? []) : (sb.checks?.after ?? []);
+const outName = prep ? "prep.json" : "cleanup.json";
+if (steps.length === 0 && checks.length === 0) {
+  console.log(`${prep ? "prep" : "cleanup"}: nothing declared in storyboard.json`);
+  fs.writeFileSync(path.join(dir, outName), JSON.stringify({ ran: [], checks: [], ok: true, nothingDeclared: true, at: new Date().toISOString() }, null, 2) + "\n");
+  process.exit(0);
+}
+
+const profileDir = path.resolve(".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 } }),
+);
+const page = await ctx.newPage();
+if (sb.hideCss) page.on("load", () => page.addStyleTag({ content: sb.hideCss }).catch(() => {}));
+
+async function visibleTarget(selector, minY = 0) {
+  const els = page.locator(selector);
+  const deadline = Date.now() + 15000;
+  while (Date.now() < deadline) {
+    const n = await els.count();
+    for (let i = 0; i < n; i++) {
+      const el = els.nth(i);
+      if (await el.isVisible().catch(() => false)) {
+        const box = await el.boundingBox();
+        if (box && box.y >= minY) return el;
+      }
+    }
+    await page.waitForTimeout(250);
+  }
+  return null;
+}
+
+const report = { ran: [], checks: [], ok: true, at: new Date().toISOString() };
+async function run(step, isCheck) {
+  const label = step.label || `${step.action} ${step.selector || step.url || step.key || ""}`.trim();
+  const rec = { label, action: step.action, ok: true };
+  try {
+    if (step.action === "goto") { await page.goto(step.url, { waitUntil: "load", timeout: 60000 }); await page.waitForTimeout(step.after ?? 1500); }
+    else if (step.action === "wait") { await page.waitForTimeout(step.ms ?? 1000); }
+    else if (step.action === "press") { await page.keyboard.press(step.key || "Escape"); await page.waitForTimeout(step.after ?? 600); }
+    else if (step.action === "expect" || step.action === "absent") {
+      const el = await visibleTarget(step.selector, step.minY ?? 0);
+      const present = !!el;
+      rec.ok = step.action === "expect" ? present : !present;
+      rec.detail = present ? "visible" : "not visible";
+    }
+    else if (step.action === "click" || step.action === "hover" || step.action === "type") {
+      const el = await visibleTarget(step.selector, step.minY ?? 0);
+      if (!el) throw new Error(`no visible target for ${step.selector}`);
+      if (step.action === "hover") await el.hover();
+      if (step.action === "click") { await el.click(); await page.waitForTimeout(step.after ?? 1200); }
+      if (step.action === "type") { await el.click(); if (step.clear) { await el.fill("").catch(async () => { await page.keyboard.press("ControlOrMeta+A"); await page.keyboard.press("Backspace"); }); } await page.keyboard.type(String(step.text ?? ""), { delay: 20 }); if (step.enter) await page.keyboard.press("Enter"); await page.waitForTimeout(step.after ?? 500); }
+    }
+    else throw new Error(`unknown action ${step.action}`);
+  } catch (e) { rec.ok = false; rec.error = e.message; }
+  rec.url = page.url(); // where the step left the page (a failed prep leaves its draft's url here)
+  (isCheck ? report.checks : report.ran).push(rec);
+  // An optional step (required:false) may fail without failing the report:
+  // the checks decide. Required steps and checks decide the verdict.
+  if (!rec.ok && (isCheck || step.required !== false)) report.ok = false;
+  console.log(`${rec.ok ? "✓" : "✗"} ${isCheck ? "check " : ""}${label}${rec.detail ? ` (${rec.detail})` : ""}${rec.error ? ` — ${rec.error}` : ""}`);
+  return rec.ok;
+}
+
+for (const step of steps) { if (!(await run(step, false)) && step.required !== false) { console.error(`stopping: "${step.label || step.action}" failed and is required`); break; } }
+// Checks need a page under them: when nothing navigated yet, open the
+// storyboard's own url first (a prep with only checks, or a cleanup whose
+// steps never left the blank tab).
+if (checks.length > 0 && page.url() === "about:blank" && sb.url) { await page.goto(sb.url, { waitUntil: "load", timeout: 60000 }).catch(() => {}); await page.waitForTimeout(3500); }
+for (const step of checks) await run(step, true);
+await ctx.close();
+// The verdict: when checks are declared they ARE the proof (a rerun after a
+// partial revert legitimately finds nothing left to do); without checks, every
+// required step must have passed.
+if (checks.length > 0) report.ok = report.checks.every((c) => c.ok);
+fs.writeFileSync(path.join(dir, outName), JSON.stringify(report, null, 2) + "\n");
+console.log(`${outName} written: ${report.ok ? "ok" : "NOT ok"} (${report.ran.length} steps, ${report.checks.length} checks)`);
+process.exit(report.ok ? 0 : 1);

package/skill/scripts/manifest.mjs

@@ -29,6 +29,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { execFileSync, spawnSync } from "node:child_process";
+import { ffmpeg as FFMPEG, ffprobe as FFPROBE } from "./media-tools.mjs";
 
 const args = process.argv.slice(2);
 const dir = args[0];
@@ -73,7 +74,7 @@ let duration = round2(Math.max(0, A * (man.duration ?? 0) + B));
 const cleanPath = path.join(dir, "clean.mp4");
 if (fs.existsSync(cleanPath)) {
   try {
-    duration = round2(parseFloat(execFileSync("ffprobe", [
+    duration = round2(parseFloat(execFileSync(FFPROBE(), [
       "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", cleanPath,
     ]).toString().trim()));
   } catch {
@@ -215,7 +216,7 @@ if (fs.existsSync(cleanPath)) {
     // count exists because the bbox alone lies: two tiny unrelated changes
     // far apart (caret + spinner) span a huge, nearly-empty bbox (review
     // finding, 2026-08-09).
-    const res = spawnSync("ffmpeg", [
+    const res = spawnSync(FFMPEG(), [
       "-loglevel", "info",
       "-ss", String(Math.max(0, tPre)), "-i", cleanPath,
       "-ss", String(Math.min(duration - 0.05, tPost)), "-i", cleanPath,

package/skill/scripts/stage-wait.mjs

@@ -0,0 +1,87 @@
+// Shared wait for a staged take: poll while the human decides in the app,
+// then until the bite is READY, then print the receipt. Used by upload.mjs
+// (single take) and status.mjs (a batch resumes here per take).
+//
+// LAW (founder 2026-08-08): never hand a human a studio link before the bite
+// is finished. Approve only STARTS the pipeline; transcode, rescript, fit,
+// synthesize and finalize happen after. The link exists ONLY behind a
+// confirmed "completed".
+//
+// Returns { exitCode, status, biteId, studioUrl } and never throws.
+
+export async function waitForDecision({ base, apiKey, stagingId, pageUrl, decisionTimeoutMs = 30 * 60 * 1000, pollMs = 4000 }) {
+  const headers = { Authorization: `Bearer ${apiKey}` };
+  const deadline = Date.now() + decisionTimeoutMs;
+  let announced = false;
+  let completed = false;
+  let approvedBiteId = null;
+  let finalStudioUrl = null;
+  process.stdout.write("Waiting for your word in the browser");
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, pollMs));
+    let res;
+    try {
+      res = await fetch(`${base}/api/recorder/stage?id=${encodeURIComponent(stagingId)}`, { headers });
+    } catch { process.stdout.write("."); continue; }
+    if (!res.ok) { process.stdout.write("."); continue; }
+    const st = await res.json().catch(() => null);
+    if (!st) { process.stdout.write("."); continue; }
+    if (st.status === "rejected") {
+      process.stdout.write("\n");
+      console.error("Discarded in the app. Adjust the storyboard and film again.");
+      return { exitCode: 1, status: "rejected", biteId: null, studioUrl: null };
+    }
+    if (st.status === "approved") {
+      if (!announced) {
+        process.stdout.write("\n");
+        console.log(`Approved — bite ${st.biteId} is being created`);
+        announced = true;
+        approvedBiteId = st.biteId;
+        finalStudioUrl = st.studioUrl ? new URL(st.studioUrl, base).toString() : null;
+        process.stdout.write("Waiting for the bite to finish");
+      }
+      if (st.biteStatus === "completed") { completed = true; process.stdout.write("\n"); break; }
+      if (st.biteStatus === "failed") {
+        process.stdout.write("\n");
+        console.error("The pipeline FAILED for this bite. Do not hand over any link — investigate.");
+        return { exitCode: 1, status: "failed", biteId: approvedBiteId, studioUrl: null };
+      }
+    }
+    process.stdout.write(".");
+  }
+  if (!announced) {
+    process.stdout.write("\n");
+    console.error(`No decision yet. The preview stays available at:\n  ${pageUrl}`);
+    return { exitCode: 1, status: "pending", biteId: null, studioUrl: null };
+  }
+  if (!completed) {
+    console.error("Approved, but the bite did not finish within the wait window. Do not share the link yet — poll /api/recorder/status or reload the preview page.");
+    return { exitCode: 1, status: "approved", biteId: approvedBiteId, studioUrl: null };
+  }
+
+  // Final receipt via the status endpoint (same gate as before).
+  let last = null;
+  try {
+    const res = await fetch(`${base}/api/recorder/status?biteId=${approvedBiteId}`, { headers });
+    if (res.ok) last = await res.json().catch(() => null);
+  } catch { /* summary is best-effort; readiness was confirmed above */ }
+  if (last && last.status === "completed") {
+    console.log(
+      `Ready: "${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.");
+  }
+  if (finalStudioUrl) console.log(`Studio: ${finalStudioUrl}`);
+  return { exitCode: 0, status: "completed", biteId: approvedBiteId, 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}` } });
+  if (!res.ok) return { ok: false, httpStatus: res.status };
+  const st = await res.json().catch(() => null);
+  return st ? { ok: true, ...st } : { ok: false, httpStatus: res.status };
+}