demobites 1.5.0 → 1.7.0

package/skill/SKILL.md

@@ -164,6 +164,19 @@ Holding shots to cover estimated lines is what produced a 60 second take with th
 
 **LAW: page transitions are cut and faded, never watched.** When the story moves to another page, the viewer sees page one, a short fade, page two — never the loading blank. record.mjs stamps every mid-take `goto` and manifest.mjs cuts that window out with a fade (`cuts` in the wire manifest); the ingestion lays it on the bite as a timeline cut. No zoom and no narration live inside a cut (the studio forbids both), so put the line about the new page on the beat AFTER it has landed, and say goodbye to the old page BEFORE the goto.
 
+### FRAMING: the camera obeys the script
+
+Framing is our job, never the customer's (founder, 2026-09-27). Decide it from the narration you wrote. The customer never hears about zooms, framing or the cursor.
+
+- Every step gets `frame`: `"close"` or `"wide"`.
+- A field, a button, a menu item, a toggle, a badge, a row = `"close"`.
+- Landing on a page, a report, a chart, a table, a dashboard, a list of results = `"wide"`. So is every line that says "here is", "you see", "you land on", "the whole".
+- A `type` step with `enter` is close for the typing. What Enter reveals is wide by itself; the recorder sees the new page. Do not add a beat for it.
+- A bare `settle` right after a navigation is wide by itself.
+- Two consecutive wides on the same page are one shot. Write both; the server joins them.
+- Never more than 4 seconds of close on a static screen. When the line runs longer, the beat is wide.
+- No `frame` = the recorder's own choice, close on the subject. `reveals: false` keeps the camera where it is after a click or an Enter.
+
 Storyboard schema (`rulesVersion` and per-step `rules` come from Phase 1b):
 
 ```json
@@ -183,7 +196,7 @@ Storyboard schema (`rulesVersion` and per-step `rules` come from Phase 1b):
 }
 ```
 
-Step fields: `action` is one of `goto | settle | scroll | click | hover | type | expect`. `rules` (optional, any step) lists the numbers of the workspace rules that shaped the beat; the storyboard's top-level `rulesVersion` names the rule set (Phase 1b). **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`.
+Step fields: `action` is one of `goto | settle | scroll | click | hover | type | expect`. `rules` (optional, any step) lists the numbers of the workspace rules that shaped the beat; the storyboard's top-level `rulesVersion` names the rule set (Phase 1b). **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`. `type` needs `selector` and `text` and takes `enter` (press Enter after the text), `clear`, `after`, `reveals`. Every step takes `label`, `narration` and `frame` (`"close"` or `"wide"`, the FRAMING law above; any other value stops the take).
 
 Beyond `steps`, a storyboard may carry the off-camera blocks (Phase 3a/law above); `cleanup.mjs` runs them on the same profile without video:
 
@@ -220,7 +233,7 @@ Two fields carry the whole advantage of this lane, so fill them in:
 
 Use `hideCss` for chat widgets and cookie banners that would pollute the picture. The first `goto` opens the video, so the first narration goes on the settle right after it.
 
-**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.
+**Show the storyboard inline and get approval before filming.** Present it as a numbered shot list, not raw JSON. The list is the story: what the viewer sees and hears, beat by beat. Never zooms, framing, selectors or the cursor. 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.
 
@@ -291,6 +304,7 @@ Filming laws baked into `record.mjs`, do not reimplement or weaken them:
 - Mouse coordinate clicks: the real mouse tracks the drawn cursor, hover states fire naturally.
 - **The camera follows the subject, measured off the live page.** Every hover records the hovered element's rectangle. Every click records TWO shots: the control on approach, and then whatever the click opened. A click that opens a menu or a dialog moves the subject somewhere else on screen, so a camera left on the button shows a dimmed backdrop while the thing you just opened sits off frame.
 - **Shots overlap on purpose.** The manifest's camera path is chained by the backend so the runtime travels from one subject to the next at zoom. Never "fix" this into a non overlapping sequence, that is the pull out to 1.0 between every shot.
+- **A landing is wide.** A `type` with `enter` ends its close shot the moment before Enter; what Enter revealed (a new URL, a page that changed) is a full-frame `wide: true` shot, and so is a bare settle after a navigation and any step framed `wide`. The server ends the previous zoom at the wide's start and never holds a close shot over it (founder, 2026-09-27).
 
 If the take fails mid flow, the partial video and manifest are still saved. Diagnose, fix the storyboard, film again.
 
@@ -336,7 +350,7 @@ node scripts/retake.mjs <biteId> [--note "what changed"]   # or: npx demobite re
 Laws for a re-take:
 - **Read the note first.** "We moved Export to the header" tells you which step will break before you film.
 - **A step that no longer resolves stops the take at that step.** Look at the live page. If the control moved,
-  fix the selector in the take's `storyboard.json` and run again with `--take <dir>`. If the feature is truly
+  fix the selector in the take's `storyboard.json` and run again with `--take <dir>` (your edited storyboard is kept; `--fresh` replaces it with the server's recipe). If the feature is truly
   gone, DROP that beat AND its narration line, and tell the human plainly: "This capability no longer exists,
   we removed it from the video." Nothing stages until every step resolves.
 - **The narration in the recipe is the ORIGINAL intent.** Do not rewrite it to taste: the server replaces it
@@ -352,6 +366,7 @@ The human pastes a bundle of approved briefs into the chat: a header (batchId, w
 
 ```bash
 node scripts/briefs.mjs list <batchId> [--paste bundle.txt]        # the approved briefs; warns when the paste drifted
+node scripts/briefs.mjs list --slug <slug>                          # Update Radar: the batch behind a record code, filmed in four phases (see the section below)
 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)
@@ -372,6 +387,70 @@ The procedure, in order:
 
 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 delivered, waiting for minutes, or 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 delivered, waiting or staged unless the human asked for a new take (`upload.mjs --supersede`).
 
+## Record a batch by slug (Update Radar)
+
+An Update Radar workflow (a scan of merged pull requests → topics → briefs) ends its Briefs stage with a short record code and the command `npx demobite record <slug>` on its page ("Go to your terminal or your coding agent where you installed it and run this command"). The human either ran the command themselves and pasted its output to you, or asked you to run it. Either way the batch is a batch of briefs as above, reached by its code instead of its id. Phase 0 (the auth gate, with the human's word) and Phase 1b (the workspace rules) come first, as for every run. Plan limits are not your concern. Delivery is one door.
+
+**We will be judged by the outcome: the fewest edits before Export and Go live** (founder ruling, 2026-09-26). The cloud draft is a starting point, never final. The run has four steps (List → Refactor + questions → One approval → Film in the background), in this order, and no other question is asked once filming starts. The Phase numbers named inside them are the skill's phases above.
+
+```bash
+npx demobite record <slug>                                        # what the human runs: lists the batch, writes .recorder/radar/<slug>/
+node scripts/briefs.mjs list --slug <slug>                        # the same call from the skill: GET <base>/api/recorder/briefs?slug=<slug>
+node scripts/briefs.mjs refine <slug> <briefId> [--note "..."]    # phase 2: post the brief you refined (.recorder/radar/<slug>/refined/<briefId>.json)
+node scripts/batch.mjs plan <slug>                                # phase 3: the pool for this machine and which briefs have a storyboard
+node scripts/batch.mjs run <slug> [--concurrency N]               # phase 4: film every approved storyboard in the background, deliver each as it lands
+```
+
+The answer to `list --slug` is the batch payload plus `radar: { slug, name, workflowUrl }`. The command prints the workflow's name, the batch id, the briefs in their order (position, title, estimated seconds), every open question the drafts carry, then writes `.recorder/radar/<slug>/bundle.json` and one draft per brief in `.recorder/radar/<slug>/briefs/<briefId>.json`. Its answers when something is off, and what you do:
+
+- "Not connected to DemoBites" → Phase 0, with the human's word; never open the browser by yourself.
+- "No batch with that code" → the code is wrong; ask the human to check the command on the Update Radar page.
+- "The briefs are not approved yet" → the human approves them on the Update Radar page; wait for their word, then list again.
+- "The recorder key was refused" → the key is stale or belongs to another workspace; Phase 0 again, with their word.
+
+### 1. List
+
+`list --slug <slug>` (or read the bundle the human's run wrote). Work from the server's briefs. The batch id on the first lines is the `<batchId>` every other command takes. Run `rules.mjs` now (Phase 1b). Nothing is claimed yet, nothing films.
+
+### 2. Refactor every brief, then ask every question once
+
+**The refactor pass, before any filming.** Walk EVERY brief in the batch against the repository (Phase 3b: routes, navigation, controls, the handlers behind each action, the gates) and the running app (Phase 3a: `vocab.mjs` over every screen the brief names). For each brief:
+
+- Confirm the flow exists at the target address. A flow that is not there is said so, not filmed.
+- Replace guessed screens and labels with the real ones, the app's current words (vocab.json is the dictionary).
+- Drop the steps that are not there. Add nothing the brief did not ask for.
+- Tighten `flowIntent` and the narration intent to what is on screen; the outcome stays the last beat; the exclusions stay things the camera never shows; the take stays under `maxSeconds` (90).
+
+Write the refined brief to `.recorder/radar/<slug>/refined/<briefId>.json` (copy the draft from `briefs/<briefId>.json` and edit it; same fields — the command keeps only the seven content fields, so the draft's other keys may stay) and post it back: `node scripts/briefs.mjs refine <slug> <briefId> --note "<what you changed and why>"`. The server mints a new revision and the Radar page shows that brief as "Refined on your machine", so the human sees what will be filmed before it is filmed. The command rewrites the bundle with the new revisions; the claim in step 4 takes them. The server's limits, checked before the post and named on failure: title ≤ 80 characters, audience ≤ 60, outcome ≤ 200, flowIntent 2–8 lines of ≤ 120, prerequisites and exclusions up to 6 lines of ≤ 160, estimatedDurationSec a whole number 15–90. Write within them; a refine over a limit is refused, never truncated. A brief that needs no change is not posted. An older DemoBites without the refine route answers so; then film from your refined file and say that the page still shows the cloud draft.
+
+**The brief stays a story** (founder ruling, 2026-09-27). What the human approves is narrative only: "this is the story I'd like to tell", the beats in plain words, the outcome. Never a word about zooms, framing, the cursor, verification, selectors or how you direct. Not in the refined brief, not in the refine note, not in the approval text. Directing is your job and it stays behind the scenes.
+
+**Double-checked behind the scenes.** Before anything is shown, check every brief against the running app and the repository: go there, open the screens, click the path, see the report land. Correct the storyboard silently. Only a change at the level of the story reaches the refine note, in one line ("the app has no Export here; the story ends on Schedule").
+
+**Questions once, for the whole batch.** Only what the app and the code cannot answer. While you walk the briefs, collect every open question: the drafts' `questions[]` (printed by `list`), the account or login the flows need, test data that must exist, feature flags, the URL and environment to film on, and anything else you cannot decide from the code and the app. Ask them in ONE message, numbered, brief by brief, and wait for the answers. Never a question mid-filming: a take that would need one is not ready to film, and it is said so in this message. When there is nothing to ask, say that in one line and go on.
+
+Then write every storyboard (Phase 3, the refined brief as the spec, the workspace rules below the laws, vocab.json as the only dictionary) into `.recorder/radar/<slug>/storyboards/<briefId>.json`, and run the headless dry run (Phase 4) for each of them on your own, before the human sees anything. A brief you could not refine into a filmable storyboard is reported with the reason and left without a storyboard; `batch.mjs` skips it and says so.
+
+### 3. One approval for the batch
+
+Show the refined storyboards for ALL briefs together, each as a numbered shot list with its three blocks (the shot list with "pointed at, not pressed" beats, "Before the camera", "After the cut"), its estimated length, the rules applied, and what changed against the cloud draft in one line per brief (the story, never the directing). Then ask for one yes for the batch: "Film these 3?". **One word for the batch replaces one approval per brief** (founder ruling, 2026-09-26). The human may strike a brief from the batch in their answer ("film 1 and 3"); that brief gets no storyboard in `storyboards/` (or `--only <briefId,...>` on the run). A no on the batch means back to step 2, not filming a subset. `node scripts/batch.mjs plan <slug>` shows what the run will do: the pool size for this machine and which briefs have a storyboard.
+
+### 4. Film in the background, in parallel
+
+On the yes: `node scripts/batch.mjs run <slug>` (run it in the background so you keep answering). It launches the takes together in a small pool sized to the machine and delivers each one as it finishes:
+
+- **The pool rule:** 2 takes at a time on a machine with 8 CPU cores or fewer, or 16 GB of memory or less; 3 above that; `--concurrency N` overrides; never more than 4. The rest queue.
+- **One browser profile per take.** Each take films on its own profile directory seeded from `.recorder/profile` (the signed-in session rides along, the profile lock does not), passed to `record.mjs` and `cleanup.mjs` as `RECORDER_PROFILE`, and removed after the take. Never share one Chrome profile between two takes.
+- **Per take, in order, as child processes of the same scripts a single take uses:** `briefs.mjs claim` → `event recording` → `cleanup.mjs --prep` (when declared) → `record.mjs` → `cleanup.mjs` (revert, checks.after, when declared) → `trim.mjs` → `calibrate.mjs` → `manifest.mjs` → `upload.mjs --stage-only --no-open`, the one delivery door: the take becomes a bite by itself, or is kept waiting for recording minutes.
+- **A failed take never stops the others.** The attempt gets `event failed --note "<step>: <why>"`, the take directory stays for diagnosis, the pool goes on. Logs live in `.recorder/radar/<slug>/takes/<briefId>/<step>.log` (and `take.log`, every step in order); `takes/summary.json` is the batch's outcome.
+- **Progress lines.** The script prints one line per event (claimed, filming, filmed, cleaned, delivered with the bite id, kept, failed with the step and the log). Relay them to the human as they land, in the same words. At the end it prints the summary per brief, the Demos grid, and the Radar `workflowUrl`.
+
+When the run ends, report per brief what happened, name any take kept waiting for recording minutes (it waits on the Demos grid), name any failed take with its step and what you will change before filming it again (a failed take is filmed again alone with `--only <briefId>`, after the fix, with the human's word), and end with the Update Radar link, `radar.workflowUrl` from the bundle: the workflow page shows each take arriving and the demos it becomes. The human publishes from there; you never publish. `status.mjs --all` shows where each delivered take stands; `status.mjs <takeDir>` waits for one to finish and prints what landed (the Phase 6 receipt law holds: no studio link before the bite is completed).
+
+**One demo, not a batch.** Someone who asks for a single demo from a Radar brief, or a single re-film, gets the single-take path: `claim`, storyboard, the yes on it, `record.mjs` on the profile, cleanup, trim, calibrate, manifest, `upload.mjs`. `batch.mjs` is for the batch.
+
+Resume like a batch: what is on disk (`take-*` directories, `takes/<briefId>/result.json`) and what `list --slug` reports is the truth, never a second claim on your own live attempt. `batch.mjs run` again films only the briefs whose storyboards are present; pass `--only` for the ones to film again.
+
 ## 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.
@@ -390,11 +469,13 @@ Resume after an interruption from what is on disk and on the server: a `take-*`
     click?: { x, y, t },                     // frame px + seconds
     narration?: { text, t, estimated_duration }
   }],
-  camera: [{ t_start, t_end, x, y, w, h, label }],  // focus rectangles, frame px
+  camera: [{ t_start, t_end, x, y, w, h, label, n?, revealed?, wide?, glide? }],  // focus rectangles, frame px
   cuts?: [{ t_start, t_end, transition: 'fade'|'abrupt', n }]  // navigation loads, cut out of the bite
 }
 ```
 
+`wide: true` on a camera shot is the camera at 1.0 for the span: the server ends the previous zoom at its start, joins consecutive wides, and writes no zoom for it.
+
 `estimated_duration` is only ever an estimate and nothing downstream treats it as final.
 
 ### What the two v2 fields buy
@@ -419,6 +500,14 @@ DELETE <base>/api/recorder/key  (Authorization: Bearer <api_key>)
 GET <base>/api/recorder/rules  (Authorization: Bearer <api_key>)   // WORKSPACE RULES (1.4): never cached
   -> { workspaceId, rules: string | null, version, updatedAt }   (the claim's api.rules is the same url; workspaceRules on the claim is the snapshot)
 
+GET <base>/api/recorder/briefs?batch=<batchId>  (Authorization: Bearer <api_key>)   // BATCH OF BRIEFS: the approved briefs, their attempts, the delivery door
+GET <base>/api/recorder/briefs?slug=<slug>      (Authorization: Bearer <api_key>)   // UPDATE RADAR (1.6): same payload + radar { slug, name, workflowUrl }
+  -> { batch, api, workspaceRules, briefs, radar? }   (404 unknown_slug; 409 not_approved; 403 workspace_mismatch)
+
+PUT <base>/api/recorder/briefs/<briefId>/refine  (Authorization: Bearer <api_key>)   // REFACTOR PASS (1.7): the brief refined on this machine
+  { revision, contentHash, content, note? }        // content = the brief's fields (title, audience, outcome, flowIntent, exclusions, ...)
+  -> { revision, contentHash }                     // the new revision; the Radar page shows "Refined on your machine" (409 hash_mismatch; 410 superseded)
+
 GET <base>/api/recorder/recipe?biteId=<id>  (Authorization: Bearer <api_key>)   // RE-TAKE: the bite's recipe
   -> { storyboard, config:{app,url,frame}, manifest, engine }   (404 no recipe; 402/403 plan gate)
 
@@ -450,5 +539,5 @@ The upload zip contains exactly one file: `clean.mp4` stored as `recording.mp4`.
 
 - Anything the human sees (storyboard presentation, questions, reports) 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 film without the human's explicit word on the storyboard. That yes, in the chat, is the word for the take: delivery ingests by itself, and the human watches the take on the Demos grid, never on a preview page. For a batch of briefs the word is given on the batch and on each storyboard. Never publish, never share, never send invitations.
+- Never film without the human's explicit word on the storyboard. That yes, in the chat, is the word for the take: delivery ingests by itself, and the human watches the take on the Demos grid, never on a preview page. For a pasted batch of briefs the word is given on each storyboard; for an Update Radar batch reached by its record code the word is ONE yes on the refined storyboards shown together (founder ruling 2026-09-26), after every question was asked once. Never publish, never share, never send invitations.
 - 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/batch.mjs

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+// FILM IN THE BACKGROUND, IN PARALLEL (1.7.0, founder ruling 2026-09-26):
+// after the ONE approval for the batch, the takes of an Update Radar batch
+// are filmed together in a small pool, each in its OWN browser profile
+// directory, and each is delivered as it finishes. A failed take never stops
+// the others. "We will be judged by the outcome: the fewest edits before
+// Export and Go live."
+//
+//   node batch.mjs plan <slug>                         the pool size for this machine and which briefs have a storyboard (films nothing)
+//   node batch.mjs run  <slug> [--concurrency N]       film every brief with a storyboard, N at a time (1..4), deliver each as it lands
+//                      [--only <briefId,...>] [--keep-profiles]
+//
+// Inputs, all under .recorder/radar/<slug>/ (written by `briefs.mjs list --slug`
+// and by the agent's refactor pass):
+//   bundle.json                    the batch (refreshed from the server first; the disk copy is the fallback)
+//   storyboards/<briefId>.json     one approved storyboard per brief (Phase 3 schema); a brief without one is skipped, and said
+// Outputs:
+//   takes/<briefId>/<step>.log     one log per step (claim, prep, record, cleanup, trim, calibrate, manifest, upload)
+//   takes/<briefId>/take.log       every step in order
+//   takes/<briefId>/result.json    what happened to the take
+//   takes/summary.json             the batch's outcome
+//   take-<briefId>-r<revision>/    the take itself, in the project directory as for every claimed brief
+//
+// Per take, in order, as child processes of the existing scripts (nothing is
+// reimplemented here): briefs claim → event recording → cleanup --prep (when
+// declared) → record → cleanup (when declared) → trim → calibrate → manifest →
+// upload --stage-only --no-open (the delivery door). On a failure: event
+// failed --note, keep the take directory, go on with the next brief.
+//
+// THE POOL RULE: 2 concurrent takes on a machine with 8 CPU cores or fewer,
+// or 16 GB of memory or less; 3 above that; --concurrency overrides; never
+// more than 4. Each take films on its own profile directory seeded from
+// .recorder/profile (the signed-in session rides along, the profile lock
+// does not), passed to the children as RECORDER_PROFILE.
+//
+// Never prints the api_key (the children never do either).
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const [, , cmd, slugArg, ...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; };
+
+function usage(code = 2) {
+  console.error(`Usage:
+  node batch.mjs plan <slug>
+  node batch.mjs run  <slug> [--concurrency N] [--only <briefId,...>] [--keep-profiles]`);
+  process.exit(code);
+}
+if (!cmd || !["plan", "run"].includes(cmd)) usage();
+const slug = String(slugArg ?? "").trim().toLowerCase();
+if (!/^[a-z0-9-]{1,32}$/.test(slug)) { console.error("The record code is the short code on the Update Radar page, like k3fx9q."); process.exit(2); }
+
+// ── where the scripts are ──────────────────────────────────────────────────
+// Installed, every script sits beside this file. In the package repository
+// record/trim/calibrate live in ../../scripts; both layouts resolve.
+function scriptPath(name) {
+  for (const dir of [here, path.resolve(here, "..", "..", "scripts")]) {
+    const p = path.join(dir, name);
+    if (fs.existsSync(p)) return p;
+  }
+  console.error(`${name} not found beside ${here}. Run \`npx demobite\` to refresh the skill.`);
+  process.exit(1);
+}
+const SCRIPTS = {
+  briefs: scriptPath("briefs.mjs"), cleanup: scriptPath("cleanup.mjs"), record: scriptPath("record.mjs"),
+  trim: scriptPath("trim.mjs"), calibrate: scriptPath("calibrate.mjs"), manifest: scriptPath("manifest.mjs"), upload: scriptPath("upload.mjs"),
+};
+
+// ── the pool rule ──────────────────────────────────────────────────────────
+const MAX_CONCURRENCY = 4;
+function poolSize({ cpus = os.cpus().length, memGiB = os.totalmem() / 2 ** 30, override = null } = {}) {
+  if (override !== null && override !== undefined && override !== "") {
+    const n = Number(override);
+    if (!Number.isInteger(n) || n < 1) { console.error(`--concurrency must be a whole number from 1 to ${MAX_CONCURRENCY}.`); process.exit(2); }
+    return { size: Math.min(n, MAX_CONCURRENCY), why: n > MAX_CONCURRENCY ? `--concurrency ${n}, capped at ${MAX_CONCURRENCY}` : `--concurrency ${n}` };
+  }
+  const small = cpus <= 8 || memGiB <= 16;
+  return { size: small ? 2 : 3, why: `${cpus} CPU cores, ${Math.round(memGiB)} GB memory` };
+}
+
+// ── the batch on disk and on the server ────────────────────────────────────
+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(`Not connected to DemoBites. Run: ${process.env.DEMOBITE_CLI ? "npx demobite login" : "node scripts/login.mjs"}`); process.exit(1); }
+const base = cfg.base.replace(/\/+$/, "");
+
+const radarDir = path.resolve(".recorder", "radar", slug);
+const bundlePath = path.join(radarDir, "bundle.json");
+const storyboardsDir = path.join(radarDir, "storyboards");
+const takesDir = path.join(radarDir, "takes");
+const sharedProfile = path.resolve(".recorder", "profile");
+
+const stamp = () => new Date().toTimeString().slice(0, 8);
+const say = (line) => console.log(`${stamp()}  ${line}`);
+
+function loadBundle() {
+  // The server's view first (revisions move after a refine); the disk copy when it cannot be reached.
+  fs.mkdirSync(takesDir, { recursive: true });
+  const r = spawnSync("node", [SCRIPTS.briefs, "list", "--slug", slug], { cwd: process.cwd(), env: process.env, encoding: "utf8" });
+  fs.writeFileSync(path.join(takesDir, "list.log"), `${r.stdout ?? ""}${r.stderr ?? ""}`);
+  if (r.status !== 0) {
+    const first = (r.stderr || r.stdout || "").trim().split("\n")[0];
+    if (!fs.existsSync(bundlePath)) { console.error(first || "Could not read the batch."); process.exit(1); }
+    console.error(`Could not refresh the batch from DemoBites (${first}); using the bundle on disk.`);
+  }
+  let bundle;
+  try { bundle = JSON.parse(fs.readFileSync(bundlePath, "utf8")); } catch (e) { console.error(`${bundlePath} unreadable: ${e.message}. Run: node scripts/briefs.mjs list --slug ${slug}`); process.exit(1); }
+  if (!bundle.batch?.id || !Array.isArray(bundle.briefs)) { console.error(`${bundlePath} has no batch. Run: node scripts/briefs.mjs list --slug ${slug}`); process.exit(1); }
+  return bundle;
+}
+
+const safeId = (id) => String(id).replace(/[^A-Za-z0-9._-]+/g, "-");
+const storyboardFor = (b) => path.join(storyboardsDir, `${safeId(b.briefId)}.json`);
+
+function planBatch(bundle) {
+  const order = [...bundle.briefs].sort((a, b) => (a.position ?? 0) - (b.position ?? 0));
+  const only = opt("--only") ? new Set(opt("--only").split(",").map((s) => s.trim()).filter(Boolean)) : null;
+  return order.map((b, i) => {
+    const sb = storyboardFor(b);
+    let storyboard = null; let problem = null;
+    if (only && !only.has(String(b.briefId))) problem = "not in --only";
+    else if (!fs.existsSync(sb)) problem = "no storyboard";
+    else {
+      try { storyboard = JSON.parse(fs.readFileSync(sb, "utf8")); } catch (e) { problem = `storyboard unreadable: ${e.message}`; }
+      if (storyboard && (!Array.isArray(storyboard.steps) || storyboard.steps.length === 0)) problem = "storyboard has no steps";
+    }
+    const live = b.attempt && ["planning", "awaiting_storyboard_approval", "recording", "uploading"].includes(b.attempt.state);
+    if (!problem && b.status && !["approved", "refined"].includes(b.status) && !live) problem = `brief is ${b.status}`;
+    return { n: i + 1, brief: b, storyboardPath: sb, storyboard, problem, liveAttempt: live ? b.attempt : null };
+  });
+}
+
+// ── one step = one child process, logged ───────────────────────────────────
+function runStep(take, step, script, args, extraEnv = {}) {
+  return new Promise((resolve) => {
+    const logPath = path.join(take.logDir, `${step}.log`);
+    const out = fs.createWriteStream(logPath);
+    const all = fs.createWriteStream(path.join(take.logDir, "take.log"), { flags: "a" });
+    all.write(`\n── ${step}  ${new Date().toISOString()}\n   node ${path.basename(script)} ${args.join(" ")}\n`);
+    let stdout = ""; let stderr = "";
+    const child = spawn("node", [script, ...args], { cwd: process.cwd(), env: { ...process.env, ...extraEnv }, stdio: ["ignore", "pipe", "pipe"] });
+    take.child = child;
+    child.stdout.on("data", (d) => { stdout += d; out.write(d); all.write(d); });
+    child.stderr.on("data", (d) => { stderr += d; out.write(d); all.write(d); });
+    child.on("close", (code, signal) => {
+      take.child = null;
+      out.end(); all.end();
+      resolve({ code: signal ? 1 : code, stdout, stderr, logPath, signal });
+    });
+    child.on("error", (e) => { take.child = null; stderr += e.message; out.end(); all.end(); resolve({ code: 1, stdout, stderr, logPath }); });
+  });
+}
+const firstLine = (r) => (r.stderr.trim() || r.stdout.trim()).split("\n").filter(Boolean).pop() ?? `exit ${r.code}`;
+const rel = (p) => path.relative(process.cwd(), p) || p;
+
+// ── one profile per take, seeded from the shared one ───────────────────────
+// Chrome refuses a second instance on the same profile (SingletonLock); a
+// COPY carries the signed-in session and nothing that locks. Caches stay
+// behind: they are large and Chrome rebuilds them.
+const SKIP_IN_PROFILE = /^(Singleton|lockfile$|.*Cache$|Crashpad$|BrowserMetrics|Safe Browsing|component_crx_cache|extensions_crx_cache)/i;
+function seedProfile(take) {
+  const dir = path.join(take.logDir, "profile");
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(dir, { recursive: true });
+  if (fs.existsSync(sharedProfile)) {
+    fs.cpSync(sharedProfile, dir, { recursive: true, force: true, filter: (src) => !SKIP_IN_PROFILE.test(path.basename(src)) });
+  }
+  return dir;
+}
+
+// ── one take, start to delivery ────────────────────────────────────────────
+const takesInFlight = new Set();
+async function runTake(item, bundle, results) {
+  const b = item.brief;
+  const label = `brief ${item.n}/${bundle.briefs.length} "${b.title}"`;
+  const take = { briefId: b.briefId, title: b.title, n: item.n, logDir: path.join(takesDir, safeId(b.briefId)), child: null };
+  takesInFlight.add(take);
+  try { await filmTake(item, bundle, results, take, label); } finally { takesInFlight.delete(take); }
+}
+
+async function filmTake(item, bundle, results, take, label) {
+  const b = item.brief;
+  fs.mkdirSync(take.logDir, { recursive: true });
+  fs.rmSync(path.join(take.logDir, "take.log"), { force: true });
+  const result = { briefId: b.briefId, title: b.title, n: item.n, startedAt: new Date().toISOString(), takeDir: null, attemptRef: null, outcome: null, step: null, error: null, biteId: null, logDir: rel(take.logDir) };
+  results.push(result);
+  const finish = (outcome, extra = {}) => { Object.assign(result, { outcome, endedAt: new Date().toISOString(), ...extra }); fs.writeFileSync(path.join(take.logDir, "result.json"), JSON.stringify(result, null, 2) + "\n"); };
+  const fail = async (step, r) => {
+    const why = firstLine(r);
+    result.step = step; result.error = why;
+    say(`${label}: failed at ${step} (${why}). Log: ${rel(r.logPath)}`);
+    if (result.attemptRef && result.takeDir) await runStep(take, "event-failed", SCRIPTS.briefs, ["event", result.takeDir, "failed", "--note", `${step}: ${why}`.slice(0, 600)]);
+    finish("failed");
+  };
+
+  // 1. claim → take-<briefId>-r<revision>/brief.json
+  const claim = await runStep(take, "claim", SCRIPTS.briefs, ["claim", String(bundle.batch.id), String(b.briefId)]);
+  if (claim.code !== 0) { result.step = "claim"; result.error = firstLine(claim); say(`${label}: claim refused (${result.error}). Log: ${rel(claim.logPath)}`); finish("claim_refused"); return; }
+  const m = /→ (\S+)\/brief\.json \(attempt ([^,)]+)/.exec(claim.stdout);
+  result.takeDir = m?.[1] ?? `take-${safeId(b.briefId)}-r${b.revision}`;
+  result.attemptRef = m?.[2] ?? null;
+  if (!fs.existsSync(path.join(result.takeDir, "brief.json"))) { result.step = "claim"; result.error = `no brief.json in ${result.takeDir}`; say(`${label}: claim did not write ${result.takeDir}/brief.json`); finish("failed"); return; }
+  say(`${label}: claimed → ${result.takeDir} (attempt ${result.attemptRef ?? "?"})`);
+
+  // 2. the approved storyboard travels with the take (cleanup --prep reads it before record does)
+  fs.copyFileSync(item.storyboardPath, path.join(result.takeDir, "storyboard.json"));
+  const sb = item.storyboard;
+  const hasPrep = (sb.prep?.length ?? 0) > 0 || (sb.checks?.before?.length ?? 0) > 0;
+  const hasCleanup = (sb.cleanup?.length ?? 0) > 0 || (sb.checks?.after?.length ?? 0) > 0;
+
+  // 3. the attempt moves to recording; the take gets its own profile
+  const ev = await runStep(take, "event-recording", SCRIPTS.briefs, ["event", result.takeDir, "recording"]);
+  if (ev.code !== 0) { await fail("event recording", ev); return; }
+  let profile;
+  try { profile = seedProfile(take); } catch (e) { await fail("profile", { stdout: "", stderr: e.message, logPath: path.join(take.logDir, "take.log"), code: 1 }); return; }
+  const env = { RECORDER_PROFILE: profile };
+  say(`${label}: filming on its own profile (${rel(profile)})`);
+
+  try {
+    if (hasPrep) { const r = await runStep(take, "prep", SCRIPTS.cleanup, [result.takeDir, "--prep"], env); if (r.code !== 0) { await fail("prep", r); return; } say(`${label}: prep done (checks before passed)`); }
+    const rec = await runStep(take, "record", SCRIPTS.record, [result.takeDir, item.storyboardPath], env);
+    if (rec.code !== 0) { await fail("record", rec); return; }
+    say(`${label}: filmed`);
+    if (hasCleanup) { const r = await runStep(take, "cleanup", SCRIPTS.cleanup, [result.takeDir], env); if (r.code !== 0) { await fail("cleanup", r); return; } say(`${label}: workspace returned to its initial state (checks after passed)`); }
+  } finally {
+    if (!flag("--keep-profiles")) fs.rmSync(profile, { recursive: true, force: true });
+  }
+
+  // 4. finish the file, then the ONE delivery door
+  for (const [step, script] of [["trim", SCRIPTS.trim], ["calibrate", SCRIPTS.calibrate], ["manifest", SCRIPTS.manifest]]) {
+    const r = await runStep(take, step, script, [result.takeDir]);
+    if (r.code !== 0) { await fail(step, r); return; }
+  }
+  const up = await runStep(take, "upload", SCRIPTS.upload, [result.takeDir, "--stage-only", "--no-open"]);
+  let staged = null;
+  try { staged = JSON.parse(fs.readFileSync(path.join(result.takeDir, "staged.json"), "utf8")); } catch {}
+  if (staged?.delivered && staged.biteId) {
+    result.biteId = staged.biteId;
+    say(`${label}: delivered → bite ${staged.biteId}, becoming a demo by itself`);
+    finish("delivered", { stagingId: staged.stagingId, dashboardUrl: staged.dashboardUrl });
+    return;
+  }
+  if (staged?.waiting) {
+    const kept = up.stdout.split("\n").find((l) => l.startsWith("Kept.")) ?? "Kept. The take is waiting for recording minutes.";
+    say(`${label}: ${kept}`);
+    finish("waiting", { stagingId: staged.stagingId, resetsAt: staged.resetsAt, dashboardUrl: staged.dashboardUrl });
+    return;
+  }
+  if (up.code !== 0 || !staged) { await fail("upload", up); return; }
+  result.step = "upload"; result.error = staged.deliveryError ?? "staged, not delivered";
+  say(`${label}: staged but not delivered (${result.error}). Try again later: node scripts/status.mjs ${result.takeDir}`);
+  finish("staged", { stagingId: staged.stagingId });
+}
+
+// ── the pool ───────────────────────────────────────────────────────────────
+async function runPool(items, size, worker) {
+  const queue = [...items];
+  const active = new Set();
+  const next = async () => {
+    const item = queue.shift();
+    if (!item) return;
+    const p = worker(item).catch((e) => { say(`brief ${item.n} "${item.brief.title}": ${e.message}`); }).finally(() => active.delete(p));
+    active.add(p);
+    await p;
+    await next();
+  };
+  await Promise.all(Array.from({ length: Math.min(size, queue.length) }, () => next()));
+}
+
+// ── main ───────────────────────────────────────────────────────────────────
+const bundle = loadBundle();
+const plan = planBatch(bundle);
+const pool = poolSize({ override: opt("--concurrency") });
+const ready = plan.filter((p) => !p.problem);
+const radarName = bundle.radar?.name ?? slug;
+
+console.log(`Update Radar: ${radarName}  batch ${bundle.batch.id}`);
+console.log(`Pool: ${pool.size} take${pool.size === 1 ? "" : "s"} at a time (${pool.why}), each on its own profile directory; the rest queue.`);
+for (const p of plan) {
+  const tag = p.problem ? `skip, ${p.problem}` : `ready${p.liveAttempt ? `, live attempt ${p.liveAttempt.ref} will be superseded by the claim` : ""}`;
+  console.log(`  ${String(p.n).padStart(2, " ")}. ${p.brief.title}  brief ${p.brief.briefId} r${p.brief.revision}  [${tag}]`);
+}
+if (cmd === "plan") {
+  console.log(`\nStoryboards live in ${rel(storyboardsDir)}/<briefId>.json. Films nothing; run: node scripts/batch.mjs run ${slug}`);
+  process.exit(ready.length ? 0 : 1);
+}
+if (!ready.length) { console.error(`\nNothing to film: no brief has a storyboard in ${rel(storyboardsDir)}/.`); process.exit(1); }
+console.log(`\nFilming ${ready.length} of ${plan.length} in the background. Logs: ${rel(takesDir)}/<briefId>/\n`);
+
+const results = [];
+let interrupted = false;
+process.on("SIGINT", () => {
+  if (interrupted) process.exit(130);
+  interrupted = true;
+  say("interrupted: stopping the takes in flight; claimed briefs are marked failed so they can be filmed again");
+  for (const t of takesInFlight) t.child?.kill("SIGTERM");
+});
+
+await runPool(ready, pool.size, async (item) => {
+  if (interrupted) return;
+  await runTake(item, bundle, results);
+});
+
+// ── the summary ────────────────────────────────────────────────────────────
+const count = (o) => results.filter((r) => r.outcome === o).length;
+const skipped = plan.filter((p) => p.problem);
+console.log(`\nBatch ${bundle.batch.id}: ${count("delivered")} delivered, ${count("waiting")} kept waiting for recording minutes, ${count("failed") + count("claim_refused") + count("staged")} not delivered, ${skipped.length} skipped.`);
+for (const r of results.sort((a, b) => a.n - b.n)) {
+  const line = r.outcome === "delivered" ? `delivered, bite ${r.biteId}`
+    : r.outcome === "waiting" ? "kept, waiting for recording minutes (it waits on the Demos grid)"
+    : r.outcome === "staged" ? `staged, not delivered (${r.error}); node scripts/status.mjs ${r.takeDir}`
+    : r.outcome === "claim_refused" ? `claim refused: ${r.error}`
+    : `failed at ${r.step}: ${r.error} (${r.logDir}/${r.step === "event recording" ? "event-recording" : r.step}.log)`;
+  console.log(`  ${String(r.n).padStart(2, " ")}. ${r.title}: ${line}`);
+}
+for (const p of skipped) console.log(`  ${String(p.n).padStart(2, " ")}. ${p.brief.title}: skipped, ${p.problem}`);
+const summary = { slug, batchId: bundle.batch.id, radar: bundle.radar ?? null, pool, startedAt: results[0]?.startedAt ?? null, endedAt: new Date().toISOString(), results, skipped: skipped.map((p) => ({ briefId: p.brief.briefId, title: p.brief.title, why: p.problem })) };
+fs.writeFileSync(path.join(takesDir, "summary.json"), JSON.stringify(summary, null, 2) + "\n");
+const grid = `${base}/demos`;
+console.log(`\nDemos grid: ${grid}`);
+if (bundle.radar?.workflowUrl) console.log(`Workflow page: ${bundle.radar.workflowUrl}`);
+process.exit(results.every((r) => r.outcome === "delivered" || r.outcome === "waiting") && !interrupted ? 0 : 1);