demobite 1.1.0 → 1.2.0

package/launcher/index.mjs

@@ -156,6 +156,21 @@ if (arg === "retake") {
   process.exit(r.status ?? 1);
 }
 
+// Batch of briefs (2026-09-13): `npx demobite briefs list <batchId>` etc. and
+// `npx demobite status <takeDir|stagingId>` hand straight to the skill scripts.
+if (arg === "briefs" || arg === "status") {
+  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", `${arg}.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.1.0",
+  "version": "1.2.0",
   "description": "The DemoBites agentic recorder \u2014 you prompt, it films a real browser, and DemoBites turns the take into an editable demo bite.",
   "bin": {
     "demobite": "launcher/index.mjs"

package/skill/SKILL.md

@@ -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/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 };
+}

package/skill/scripts/status.mjs

@@ -0,0 +1,72 @@
+// Where a staged take stands, and the wait for its word.
+//
+//   node status.mjs <takeDir>            wait for the decision, then for the bite to finish (reads <takeDir>/staged.json)
+//   node status.mjs <stagingId>          same, by id
+//   node status.mjs <takeDir> --no-wait  one look, no waiting: pending | approved (+bite status) | rejected
+//   node status.mjs --all                one look at every take-*/staged.json under the current directory
+//
+// A batch stages every take with `upload.mjs --stage-only --no-open`, then the
+// agent (or the human, later) comes back here per take. The 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 } from "./stage-wait.mjs";
+
+const args = process.argv.slice(2);
+const noWait = args.includes("--no-wait");
+const all = args.includes("--all");
+const target = args.find((a) => !a.startsWith("--"));
+if (!target && !all) {
+  console.error("Usage: node status.mjs <takeDir|stagingId> [--no-wait]   |   node status.mjs --all");
+  process.exit(2);
+}
+
+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(/\/+$/, "");
+
+function readStaged(dir) {
+  const p = path.join(dir, "staged.json");
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; }
+}
+
+function describe(st) {
+  if (!st.ok) return `unreachable (${st.httpStatus})`;
+  if (st.status === "rejected") return "discarded in the app";
+  if (st.status === "approved") return `approved, bite ${st.biteId ?? "?"} ${st.biteStatus ?? "processing"}`;
+  return "waiting for the word in the app";
+}
+
+if (all) {
+  const dirs = fs.readdirSync(".").filter((d) => d.startsWith("take-") && fs.existsSync(path.join(d, "staged.json")));
+  if (dirs.length === 0) { console.log("No staged takes here."); process.exit(0); }
+  for (const d of dirs) {
+    const staged = readStaged(d);
+    const st = staged?.stagingId ? await peekStaged({ base, apiKey: cfg.api_key, stagingId: staged.stagingId }) : { ok: false, httpStatus: 0 };
+    console.log(`${d.padEnd(40)} ${describe(st)}${staged?.previewUrl ? `\n${"".padEnd(40)} ${staged.previewUrl}` : ""}`);
+  }
+  process.exit(0);
+}
+
+let stagingId = target;
+let pageUrl = 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.previewUrl ?? null;
+}
+if (!pageUrl) pageUrl = `${base}/recording-preview/agentic/${encodeURIComponent(stagingId)}`;
+
+if (noWait) {
+  const st = await peekStaged({ base, apiKey: cfg.api_key, stagingId });
+  console.log(`${stagingId}: ${describe(st)}`);
+  if (st.ok && st.status === "approved" && st.biteStatus === "completed" && st.studioUrl) console.log(`Studio: ${new URL(st.studioUrl, base).toString()}`);
+  process.exit(st.ok ? 0 : 1);
+}
+
+const outcome = await waitForDecision({ base, apiKey: cfg.api_key, stagingId, pageUrl });
+process.exit(outcome.exitCode);

package/skill/scripts/upload.mjs

@@ -40,6 +40,28 @@ if (retakeIdx >= 0 && !(Number.isInteger(retakeOfBiteId) && retakeOfBiteId > 0))
 // history show why this version was filmed. Never a secret, never required.
 const noteIdx = process.argv.indexOf("--note");
 const retakeNote = noteIdx >= 0 ? String(process.argv[noteIdx + 1] ?? "").trim().slice(0, 600) : "";
+// BATCH OF BRIEFS (2026-09-13): a take claimed from a brief carries its attempt
+// (briefId, revision, contentHash, attemptRef) so provenance rides into the
+// staged take and the bite. Read from <takeDir>/brief.json (written by
+// briefs.mjs claim) unless --attempt <file> points elsewhere or --no-attempt
+// opts out. `--stage-only` returns right after the two uploads (the batch
+// waits with status.mjs); `--supersede` replaces a stage already pinned to
+// this attempt (the server refuses a second one otherwise).
+const stageOnly = process.argv.includes("--stage-only");
+const supersede = process.argv.includes("--supersede");
+const attemptIdx = process.argv.indexOf("--attempt");
+const attemptPath = process.argv.includes("--no-attempt")
+  ? null
+  : attemptIdx >= 0 ? String(process.argv[attemptIdx + 1] ?? "") : path.join(dir, "brief.json");
+let attempt = null;
+if (attemptPath && fs.existsSync(attemptPath)) {
+  try {
+    const b = JSON.parse(fs.readFileSync(attemptPath, "utf8"));
+    if (b.briefId && b.revision !== undefined && b.contentHash && b.attemptRef) {
+      attempt = { briefId: String(b.briefId), revision: b.revision, contentHash: String(b.contentHash), attemptRef: String(b.attemptRef) };
+    } else console.error(`${attemptPath} is missing briefId/revision/contentHash/attemptRef; staging without an attempt`);
+  } catch (e) { console.error(`${attemptPath} unreadable (${e.message}); staging without an attempt`); }
+} else if (attemptIdx >= 0) { console.error(`--attempt ${attemptPath} not found`); process.exit(2); }
 const cfgPath = path.resolve(".recorder", "config.json");
 let cfg = {};
 try { cfg = JSON.parse(fs.readFileSync(cfgPath, "utf8")); } catch {}
@@ -65,6 +87,22 @@ try {
     if (retakeNote) recipe.config = { ...(recipe.config ?? {}), retake_note: retakeNote };
   }
 } catch (e) { console.error("recipe skipped:", e.message); }
+// LAW (founder 2026-09-14): a take that created anything returns the workspace
+// to its initial state before it is staged. The storyboard declares cleanup[];
+// cleanup.mjs writes cleanup.json with the checks. No passing cleanup.json,
+// no stage. --allow-uncleaned overrides, and says so out loud.
+try {
+  const sbp = path.join(dir, "storyboard.json");
+  const sb = fs.existsSync(sbp) ? JSON.parse(fs.readFileSync(sbp, "utf8")) : {};
+  if (Array.isArray(sb.cleanup) && sb.cleanup.length > 0) {
+    const cp = path.join(dir, "cleanup.json");
+    const rep = fs.existsSync(cp) ? JSON.parse(fs.readFileSync(cp, "utf8")) : null;
+    if (!rep || rep.ok !== true) {
+      if (process.argv.includes("--allow-uncleaned")) console.error("WARNING: staging a take whose cleanup did not run or did not pass (--allow-uncleaned). The workspace may still carry what the take created.");
+      else { console.error(`This take declares cleanup[] but ${rep ? "cleanup.json says NOT ok" : "cleanup.json is missing"}. Run: node scripts/cleanup.mjs ${dir}  (then stage again)`); process.exit(1); }
+    }
+  }
+} catch (e) { console.error(`cleanup check 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"));
@@ -144,13 +182,23 @@ if (retakeOfBiteId) console.log(`Staging as a RE-TAKE of bite ${retakeOfBiteId}
 
 // ── stage ──────────────────────────────────────────────────────────────────
 const authHeaders = { Authorization: `Bearer ${cfg.api_key}`, "Content-Type": "application/json" };
+if (attempt) {
+  // The attempt moves to "uploading" before the stage call; a 409 here means
+  // the server already sees it at or past that state, which is fine.
+  try {
+    const ev = await fetch(`${base}/api/recorder/briefs/attempts/${encodeURIComponent(attempt.attemptRef)}`, {
+      method: "PUT", headers: authHeaders, body: JSON.stringify({ event: "uploading" }),
+    });
+    if (!ev.ok && ev.status !== 409) console.error(`attempt event "uploading" → ${ev.status} (continuing)`);
+  } catch (e) { console.error(`attempt event "uploading" failed: ${e.message} (continuing)`); }
+}
 const previewSizeBytes = fs.statSync(cleanPath).size;
 let stageRes;
 try {
   stageRes = await fetch(`${base}/api/recorder/stage`, {
     method: "PUT",
     headers: authHeaders,
-    body: JSON.stringify({ filename: "take.zip", sizeBytes, previewSizeBytes, manifest, ...(recipe ? { recipe } : {}), ...(retakeOfBiteId ? { retakeOfBiteId } : {}) }),
+    body: JSON.stringify({ filename: "take.zip", sizeBytes, previewSizeBytes, manifest, ...(recipe ? { recipe } : {}), ...(retakeOfBiteId ? { retakeOfBiteId } : {}), ...(attempt ? { attempt } : {}), ...(attempt && supersede ? { supersede: true } : {}) }),
   });
 } catch (e) {
   console.error(`Could not reach ${base}: ${e.message}`);
@@ -168,6 +216,14 @@ if (!stageRes.ok) {
     console.error(`DemoBites declined the stage. Check ${base}/bites and try again.`);
     process.exit(1);
   }
+  if (errBody?.error === "invalid_attempt") {
+    console.error(`DemoBites refused the attempt on this take: ${errBody.message ?? "invalid_attempt"}. Re-claim the brief (node scripts/briefs.mjs claim …) and stage again.`);
+    process.exit(1);
+  }
+  if (errBody?.error === "attempt_already_staged") {
+    console.error(`This attempt already has a staged take${errBody.stagingId ? ` (${errBody.stagingId})` : ""}. Review that one, or stage again with --supersede to replace it.`);
+    process.exit(1);
+  }
   console.error(`Stage failed: ${stageRes.status} ${errBody ? JSON.stringify(errBody) : ""}`);
   process.exit(1);
 }
@@ -191,6 +247,14 @@ async function putS3(url, contentType, filePath, label) {
 }
 await putS3(uploadUrl, "application/zip", zipPath, "ZIP");
 await putS3(previewUploadUrl, "video/mp4", cleanPath, "Preview");
+// The staging id used to be printed only; a batch resumes from disk, so it is
+// persisted next to the take (status.mjs reads it).
+try {
+  fs.writeFileSync(path.join(dir, "staged.json"), JSON.stringify({
+    stagingId, previewUrl: new URL(previewUrl, base).toString(), queueUrl: queueUrl ? new URL(queueUrl, base).toString() : null,
+    pendingCount: pendingCount ?? null, attemptRef: attempt?.attemptRef ?? null, briefId: attempt?.briefId ?? null, at: new Date().toISOString(),
+  }, null, 2) + "\n");
+} catch (e) { console.error(`staged.json not written: ${e.message}`); }
 
 // ── open the in-app preview — the review happens THERE ─────────────────────
 // Batch etiquette (founder, 2026-08-11): when takes are stacked for a later
@@ -211,83 +275,15 @@ if (!noOpen) {
   } catch { /* printing the URL above is the fallback */ }
 }
 
-// ── poll while the human decides, then until the bite is READY ─────────────
-// LAW (founder 2026-08-08): never hand a human a studio link before the bite
-// is finished. Approve only STARTS the pipeline.
-const POLL_MS = 4000;
-const DECISION_TIMEOUT_MS = 30 * 60 * 1000;
-const deadline = Date.now() + DECISION_TIMEOUT_MS;
-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, POLL_MS));
-  let res;
-  try {
-    res = await fetch(`${base}/api/recorder/stage?id=${stagingId}`, {
-      headers: { Authorization: `Bearer ${cfg.api_key}` },
-    });
-  } 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.");
-    process.exit(1);
-  }
-  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.");
-      process.exit(1);
-    }
-  }
-  process.stdout.write(".");
-}
-if (!announced) {
-  process.stdout.write("\n");
-  console.error(`No decision yet. The preview stays available at:\n  ${pageUrl}`);
-  process.exit(1);
-}
-// LAW: the studio link exists ONLY behind a confirmed 'completed'. A deadline
-// expiry after approval is NOT completion (review finding: the fallthrough
-// here once printed the link for an unfinished bite).
-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.");
-  process.exit(1);
+if (stageOnly) {
+  console.log(`Staged only. Wait for the decision later with: node scripts/status.mjs ${dir}`);
+  process.exit(0);
 }
 
-// ── 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: { Authorization: `Bearer ${cfg.api_key}` },
-  });
-  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}`);
+// ── poll while the human decides, then until the bite is READY ─────────────
+// Shared with status.mjs (a batch waits there). The law it enforces: never
+// hand a human a studio link before the bite is finished; Approve only
+// STARTS the pipeline.
+const { waitForDecision } = await import("./stage-wait.mjs");
+const outcome = await waitForDecision({ base, apiKey: cfg.api_key, stagingId, pageUrl });
+process.exit(outcome.exitCode);

package/skill/scripts/vocab.mjs

@@ -0,0 +1,88 @@
+// Harvest the product's CURRENT vocabulary from the running app (Phase 3a).
+//
+//   node vocab.mjs <takeDir> <url> [<url> ...] [--headless=false]
+//
+// Opens each URL headless on the recorder profile (signed in, no video) and
+// writes <takeDir>/vocab.json: for every screen, the nav labels (visible text,
+// aria-label, title, tooltips), the page headings, the button and link labels,
+// and the titles of any open dialogs. The storyboard's narration and
+// on_screen lines may only use nouns that appear here. The brief's and the
+// PR's words are hints about WHAT changed, never the words the demo speaks
+// (founder, 2026-09-14: a take said "Release Readiness" while the app said
+// "Assignments").
+//
+// Prints a short inventory so the agent can read it in chat before writing.
+import fs from "node:fs";
+import path from "node:path";
+import { chromium } from "playwright";
+
+const args = process.argv.slice(2);
+const dir = args[0];
+const urls = args.slice(1).filter((a) => /^https?:\/\//.test(a));
+if (!dir || urls.length === 0) {
+  console.error("Usage: node vocab.mjs <takeDir> <url> [<url> ...]");
+  process.exit(2);
+}
+fs.mkdirSync(dir, { recursive: true });
+const profileDir = path.resolve(".recorder", "profile");
+const headless = !args.includes("--headless=false");
+
+const ctx = await chromium.launchPersistentContext(profileDir, { channel: "chrome", headless, viewport: { width: 1920, height: 1080 } }).catch(async () =>
+  chromium.launchPersistentContext(profileDir, { headless, viewport: { width: 1920, height: 1080 } }),
+);
+const page = await ctx.newPage();
+
+const harvest = () => {
+  const clean = (s) => (s || "").replace(/\s+/g, " ").trim();
+  const vis = (el) => { const r = el.getBoundingClientRect(); return r.width > 0 && r.height > 0 && getComputedStyle(el).visibility !== "hidden"; };
+  const labelOf = (el) => clean(el.getAttribute("aria-label") || el.getAttribute("title") || el.getAttribute("data-tooltip") || el.innerText);
+  const uniq = (xs) => [...new Set(xs.filter(Boolean))];
+  const inRail = (el) => el.getBoundingClientRect().x < 90;
+  const nav = uniq([...document.querySelectorAll("nav a, nav button, aside a, aside button, [role='navigation'] a, header a, header button")].filter(vis).map((el) => {
+    const label = labelOf(el);
+    const href = el.getAttribute("href") || "";
+    // Tooltips often live on a sibling/parent: look at the closest element that carries one.
+    const tip = clean(el.closest("[title],[aria-label],[data-tooltip]")?.getAttribute("title") || el.closest("[data-tooltip]")?.getAttribute("data-tooltip") || "");
+    return (label || tip) ? `${label || tip}${href ? ` (${href})` : ""}${inRail(el) ? " [rail]" : ""}` : "";
+  }));
+  const headings = uniq([...document.querySelectorAll("h1, h2, h3")].filter(vis).map((el) => clean(el.innerText)).filter((t) => t.length < 90));
+  // Editors keep their controls in header bars and side panels, so nothing is
+  // excluded by landmark; only the left rail (x < 90) is reported separately.
+  const buttons = uniq([...document.querySelectorAll("button, [role='button'], a[href], [role='tab'], [role='menuitem']")].filter(vis).filter((el) => !inRail(el)).map(labelOf).filter((t) => t && t.length < 60));
+  const fields = uniq([...document.querySelectorAll("input, textarea, [contenteditable='true']")].filter(vis).map((el) => clean(el.getAttribute("aria-label") || el.getAttribute("placeholder") || el.closest("label")?.innerText || "")).filter((t) => t && t.length < 60));
+  const dialogs = uniq([...document.querySelectorAll("[role='dialog'], [role='alertdialog']")].map((d) => clean(d.querySelector("h1,h2,h3,[id*='title']")?.innerText || d.getAttribute("aria-label") || "")));
+  const tooltips = uniq([...document.querySelectorAll("[role='tooltip']")].map((el) => clean(el.innerText)));
+  return { title: document.title, nav, headings, buttons, fields, dialogs, tooltips };
+};
+
+const screens = [];
+for (const url of urls) {
+  await page.goto(url, { waitUntil: "networkidle", timeout: 60000 }).catch(() => page.goto(url, { waitUntil: "load", timeout: 60000 }).catch((e) => console.error(`${url}: ${e.message}`)));
+  // Entitlement-gated nav items paint late; give the app a moment, then hover
+  // every rail link (the icons carry their names as tooltips, not as text) so
+  // the tooltip portals render into the DOM.
+  await page.waitForTimeout(5000);
+  const rail = page.locator("a[href^='/']");
+  const n = Math.min(await rail.count(), 40);
+  const tips = new Set();
+  for (let i = 0; i < n; i++) {
+    const el = rail.nth(i);
+    const box = await el.boundingBox().catch(() => null);
+    if (!box || box.x > 90 || box.width > 80) continue;
+    await el.hover().catch(() => {});
+    await page.waitForTimeout(700);
+    const texts = await page.locator("[role='tooltip'], [data-slot='tooltip-content'], [data-slot='tooltip-popup']").allInnerTexts().catch(() => []);
+    for (const t of texts) if (t.trim()) tips.add(`${t.trim()} (${(await el.getAttribute("href")) || "?"})`);
+  }
+  await page.mouse.move(600, 600);
+  const h = await page.evaluate(harvest);
+  h.railTooltips = [...tips];
+  h.url = page.url();
+  screens.push(h);
+  console.log(`\n${h.url}\n  title: ${h.title}\n  headings: ${h.headings.join(" · ")}\n  rail tooltips: ${h.railTooltips.join(" · ") || "(none rendered)"}\n  nav: ${h.nav.slice(0, 20).join(" · ")}\n  buttons/links: ${h.buttons.slice(0, 60).join(" · ")}${h.fields.length ? `\n  fields: ${h.fields.join(" · ")}` : ""}${h.dialogs.filter(Boolean).length ? `\n  dialogs: ${h.dialogs.filter(Boolean).join(" · ")}` : ""}`);
+}
+await ctx.close();
+
+const out = { harvestedAt: new Date().toISOString(), screens };
+fs.writeFileSync(path.join(dir, "vocab.json"), JSON.stringify(out, null, 2) + "\n");
+console.log(`\nvocab.json written (${screens.length} screen${screens.length === 1 ? "" : "s"}). Narration may use only these nouns.`);