demobite 1.0.9 → 1.2.0

package/README.md

@@ -1,115 +1,161 @@
-# demobite
+# DemoBites Agentic Recorder
 
-**You prompt, it records.** The agentic recorder films a real browser from a
-storyboard — real cursor physics, a measured clock, cinematic camera moves —
-and delivers the take into [DemoBites](https://demobites.com), where it becomes
-a fully editable demo: AI narration, zooms, cursor rendering, intro and outro,
-localization, all tweakable in the studio.
+**Ask your coding agent to record your product. Edit the result. Download the MP4.**
+
+Your agent drives a real browser on your machine and records the flow you describe. Connect a free DemoBites account to turn the take into an editable video, with text-to-speech, zooms, captions, and MP4 export included.
+
+**Sign in to your app locally. You do not hand DemoBites your app password or upload your recording browser profile.**
 
 ```bash
-npx demobite
+npx demobite@latest
 ```
 
-That one command checks your setup, installs the recorder skill for
-your coding agent — [Claude Code](https://claude.com/claude-code), Cursor,
-or Codex — and wires the DemoBites
-management MCP so your agent can also run your Update Center and Demo Center.
-Sign-in happens through your own browser — no passwords in the terminal, ever.
-Then you just ask your agent:
+**Free Studio · Text-to-speech included · Unlimited exports · No watermark · No credit card**
+
+[Website](https://agentic-recorder.com/) · [npm](https://www.npmjs.com/package/demobite) · [Report an issue](https://github.com/demobites/agentic-recorder/issues)
+
+## See the workflow
+
+https://github.com/user-attachments/assets/18293b85-82e2-475f-8d94-543f1f9bbc1d
 
-> "Record a demo of how search works on our app, and upload it to DemoBites."
+An illustrated walkthrough of the flow, with waiting time compressed.
 
-> "Create a release with my latest bites and add Spanish."
+## Start with your own agent
 
-Commands: `npx demobite` (full setup) · `npx demobite login` · `npx demobite mcp`
-(register the management MCP with your agent) · `npx demobite logout`.
-Anything public — publishing a release, taking a language offline — always
-shows you a preview to approve first. Managing by agent requires the Grow plan;
-recording works on every plan.
+You need a coding agent that can read skill instructions, run terminal commands, and control a local browser. A browser-only chat session cannot run this local workflow.
 
-The agent storyboards the flow, films it in a real Chrome, and stages the take
-for your approval inside DemoBites. You approve in the product; the platform
-does the rest.
+Before installing:
 
-## Manage DemoBites from your agent (MCP)
+- **Node.js 18 or newer** and npm.
+- **Google Chrome**, recommended. The recorder also supports Playwright's Chromium.
+- A **free DemoBites account** for the Studio workflow below.
 
-Recording is half the story. The same package wires the **DemoBites management
-MCP** — a control plane your agent uses to run your Update Center and Demo
-Center. Your customers' agents read your centers; your agent runs them.
+Run these commands from your project directory:
 
 ```bash
-npx demobite mcp
+# Install the skill and check your setup.
+npx demobite@latest
+
+# Connect this project to your DemoBites workspace.
+npx demobite login
 ```
 
-Claude Code is registered automatically. Any other MCP client works over
-Streamable HTTP: point it at `https://app.demobites.com/api/mcp` with the
-`Authorization: Bearer <key>` header the command prints (in Cursor, add both
-under Settings → MCP). Then talk to your agent like a teammate:
+The installer installs Playwright, ffmpeg and ffprobe beside the skill if they are not already there. It uses your own ffmpeg when a compatible build is on your PATH. It checks for Chrome and downloads Chromium on the first take if Chrome is missing.
+
+To connect, open the link printed in your terminal and approve the connection in your browser. If you are signed out of DemoBites, sign in there first. You do not paste a password into the terminal.
+
+Then ask your agent:
+
+> Record a demo of inviting a teammate in my app at http://localhost:3000. Open Team settings, invite alex@example.com as an Admin, and show the confirmation. Show me the storyboard before recording.
+
+Use your own app URL and a demo account. The agent performs real actions in your app, including sending an invitation if that is part of the approved flow.
+
+### Which agent?
+
+The installer currently places the skill at `~/.claude/skills/agentic-recorder/`, the Claude Code skill directory.
+
+For Cursor or Codex, make the [recorder instructions](skill/SKILL.md) available to your agent and ensure it can run the installed scripts. The launcher currently does not install into separate Cursor or Codex skill directories. Connecting an MCP client alone does not install the recorder skill.
+
+## From prompt to finished video
+
+1. **Describe the flow.** Give your agent the app URL and what you want to demonstrate.
+2. **Approve the storyboard.** Review the steps and estimated length before filming. If your app needs a login, sign in yourself in the recorder's local browser window.
+3. **Let it record.** The agent checks the flow and films it. Recording normally runs in the background.
+4. **Review the raw take.** Open the review link printed in the terminal. Check the footage, then approve it to create a Bite, an editable video project.
+5. **Tweak and download.** In the Studio, change a sentence, generate its voice, adjust the zooms or timing, and export your MP4.
+
+The storyboard's narration is a starting point. DemoBites rewrites and fits it to the footage; you can edit the final wording in the Studio.
+
+## What connecting to DemoBites adds
+
+The recorder supplies footage, action timings, cursor movements, and camera targets. The Studio uses that information to create a video you can keep editing.
+
+| Included in the free Studio | What you can do |
+| --- | --- |
+| Script and text-to-speech | Edit the words and generate narration without recording your own voice. |
+| Camera and cursor editing | Adjust automatic zooms, cursor appearance, and timing. |
+| Video finishing | Trim the take, edit captions, and add your background, branding, intro, and outro. |
+| MP4 export | Download Full HD video with narration and no DemoBites watermark. |
 
-> "Create a release with my latest bites, add Spanish, and publish it."
+**The free Studio holds up to 8 Bites at a time, with unlimited exports. Invite three people who sign up and the Studio becomes unlimited, still free.** It has no trial clock and requires no credit card. You bring your own coding agent; its subscription or model usage is separate. An ElevenLabs key is optional, not required for the Studio's included text-to-speech.
 
-> "What's on our Demo Center? Swap the checkout bite for the onboarding one."
+You can use the exported video in your docs, website, release notes, or wherever you need it. Paid publishing and management features are optional. See [current plan details](https://www.demobites.com/pricing).
 
-### What it can do — 19 tools
+## One prompt, one result
 
-| Group | Tools |
-|---|---|
-| Connect | `get_started` · `connect_demobites` · `check_connection` · `get_recording_options` |
-| Read | `get_status` · `list_bites` · `list_releases` · `get_release` · `list_languages` |
-| Draft & edit | `create_release` · `update_release` · `assign_bites_to_release` · `update_center_settings` · `add_language` · `update_demo_center` |
-| Publish — with your approval | `publish_release` · `unpublish_release` · `remove_language` · `publish_demo_center` |
+> Record a demo of Funnels: where customers drop off, which channels work. Show the sidebar and graphs.
 
-The server describes itself: any client's `tools/list` returns every tool with
-its full input schema, straight from the running code.
 
-### You stay in charge
 
-Draft work executes directly, exactly like clicking around the product. But
-anything that touches a **public** page is two-phase: the tool returns a
-human-readable preview plus a single-use confirmation token, your agent shows
-you the preview, and only your go-ahead executes it. Tokens expire in ten
-minutes, are bound to the exact action and arguments, and every management
-call lands in an audit log.
+https://github.com/user-attachments/assets/02eb7d3e-fe74-4c0d-b532-e16bfc3fa614
 
-### Plans
 
-Connecting and reading are open. Managing requires the **Grow** plan.
-Recording works on every plan.
+ 
+ Recorded by the agent, then edited and narrated in the free Studio. This prompt assumes the agent already knows the app URL and can access the Funnels page.
 
-Full guide: [Manage from your agent](https://www.demobites.com/docs/bites/manage-from-your-agent)
+## Your app login stays local
 
-## What's in this repository
+**You do not need to hand DemoBites your app password to record a signed-in flow.** Sign in yourself in the recorder's browser on your machine.
 
-| Directory | What it is |
-|---|---|
-| `launcher/` | The `npx demobite` entry — environment checks, skill install, login |
-| `skill/` | The DemoBites recorder skill for coding agents (staging, preview, approval flow) |
-| `recorder/` | The open recorder — same filming engine, no account, ends at a polished `demo.mp4` |
-| `scripts/` | The shared engine: filming, clock calibration, cutting |
+The recorder uses a separate, persistent Chrome profile at `.recorder/profile/`. Your app session is saved there for later takes. It does not automatically inherit the sessions in your everyday Chrome profile.
 
-## Just want the recorder, no DemoBites?
+| Data | Where it goes |
+| --- | --- |
+| Your app's browser session | Stays in the local recording profile; the standard local workflow does not upload that profile to DemoBites. |
+| DemoBites recorder key | Saved in `.recorder/config.json` and used to authenticate recorder requests to DemoBites. This is separate from your app login. |
+| Footage and recording metadata | Uploaded to DemoBites for review and processing, including the storyboard, narration intent, cursor events, and camera targets. |
 
-The `recorder/` directory is a standalone skill: the same real-browser filming,
-hover-anchor clock calibration and camera work, delivering a finished, styled
-`demo.mp4` on your disk — no account, no upload. Point your coding agent at it and
-film. When you want narration, zooms, an editable timeline and hosting, the
-sibling skill in `skill/` is one login away.
+Recording happens locally. Studio processing and editing use DemoBites online. Anything visible or typed into the recorded flow can appear in the footage or recording metadata, so use suitable demo data. Your coding agent's own data handling still follows its provider and your settings.
 
-## How updates reach you
+Keep `.recorder/` and take directories out of version control. To disconnect the recorder, run `npx demobite logout`.
 
-Run with `@latest` and every invocation resolves the newest published version —
-the skill you install always matches the DemoBites platform it talks to.
-Releases are published from GitHub Actions with npm provenance: every version
-is cryptographically tied to a public commit in this repository.
+## Local output without a DemoBites account
 
-## Requirements
+The repository also contains a [standalone recorder skill](recorder/SKILL.md) and local finishing scripts. These produce a local MP4; optional voiceover uses your own ElevenLabs key.
 
-- Node 18+
-- A coding agent — [Claude Code](https://claude.com/claude-code), Cursor, or Codex; the recorder is agent-driven
-- Google Chrome (recommended; films with the real browser) — otherwise
-  Chromium is downloaded on first take
-- ffmpeg (`brew install ffmpeg` on macOS)
+This is an advanced, manual workflow. The default `npx demobite@latest` command installs the Studio-connected skill, not the standalone skill. The standalone finishing reference contains legacy instructions; use the standalone skill as the entry point rather than treating it as a second ending of the installed Studio skill.
+
+## A few boundaries
+
+- The agentic recorder films **browser workflows**. It does not record native desktop apps or phone screens.
+- The Studio-connected skill is designed for short demos, usually **30–45 seconds**, with a **90-second maximum per Bite**. Split longer stories into separate videos.
+- Some sites block automated browsers. The workflow may need a human sign-in or verification step, and some sites may refuse recording.
+- Filming does not publish anything. You review the take before creating the Bite; public publishing is a separate action.
+
+## Optional: Retake and management
+
+When your UI changes, **Retake** can refilm an existing Bite from its saved recipe. It is a paid capability; see [plan details](https://www.demobites.com/pricing).
+
+```bash
+npx demobite retake <biteId> --note "Export moved to the header"
+```
+
+The package also includes a DemoBites management MCP for releases and centers:
+
+```bash
+npx demobite mcp
+```
+
+The default installer also attempts to register that MCP with Claude Code when the current project is already connected. Management access depends on your account and key permissions. You do not need paid management to record, edit, or export a free Bite.
+
+[Management documentation](https://www.demobites.com/docs/bites/manage-from-your-agent)
+
+## Repository
+
+| Directory | Purpose |
+| --- | --- |
+| `launcher/` | CLI setup, connection commands, and MCP registration. |
+| `skill/` | Studio-connected recorder instructions, login, upload, and Retake. |
+| `scripts/` | Shared browser recording, trimming, and timing calibration. |
+| `recorder/` | Standalone skill and local video finishing tools. |
+| `aliases/` | `agentic-recorder` and `demobites` aliases for the same launcher. |
+
+Run `npx demobite@latest` again to update the installed skill. For publishing instructions, see [RELEASING.md](RELEASING.md).
+
+Found something confusing or have an example to share? [Open an issue](https://github.com/demobites/agentic-recorder/issues). Include your operating system, agent, and recorder version. Remove keys, cookies, and private app data from logs or recordings before attaching them.
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+The code in this repository is [MIT licensed](LICENSE). The hosted DemoBites Studio is a separate service; its source is not included here.
+
+Built and maintained by [DemoBites](https://www.demobites.com/).

package/launcher/index.mjs

@@ -45,10 +45,9 @@ const chromePaths = [
   "C:/Program Files/Google/Chrome/Application/chrome.exe",
   "/usr/bin/google-chrome",
 ];
-if (chromePaths.some((p) => fs.existsSync(p)) || hasBin("google-chrome")) ok("Google Chrome (films with the real browser)");
-else warn("Google Chrome not found — the recorder will download Chromium on first take");
-if (hasBin("ffmpeg")) ok("ffmpeg");
-else warn("ffmpeg not found — install it (macOS: brew install ffmpeg) before recording");
+const haveChrome = chromePaths.some((p) => fs.existsSync(p)) || hasBin("google-chrome") || hasBin("google-chrome-stable");
+if (haveChrome) ok("Google Chrome (films with the real browser)");
+else console.log("  · Google Chrome not found — installing Playwright's Chromium for the recorder");
 if (hasBin("claude")) ok("Claude Code (drives the recorder; MCP registers automatically)");
 else warn("Claude Code not found — using Cursor or Codex? They drive the recorder too; MCP setup prints below");
 
@@ -63,12 +62,41 @@ for (const f of fs.readdirSync(path.join(pkgRoot, "skill/scripts"))) copy(`skill
 for (const f of fs.readdirSync(path.join(pkgRoot, "scripts"))) copy(`scripts/${f}`, `scripts/${f}`);
 ok(`Skill installed → ${dest}`);
 
-// Playwright lives with the skill so takes can film.
-if (!fs.existsSync(path.join(dest, "node_modules", "playwright"))) {
-  console.log("\n  Installing Playwright (one-time)…");
-  const r = spawnSync("npm", ["install", "--prefix", dest, "--silent", "playwright"], { stdio: "inherit" });
+// Playwright and the media tools live with the skill so takes can film and
+// finish on any machine. ffmpeg and ffprobe are packaged per platform
+// (@ffmpeg-installer, @ffprobe-installer); a compatible system build is preferred when present
+// (scripts/media-tools.mjs decides). One line installs everything.
+const needed = ["playwright", "@ffmpeg-installer/ffmpeg", "@ffprobe-installer/ffprobe"].filter(
+  (m) => !fs.existsSync(path.join(dest, "node_modules", m)),
+);
+if (needed.length) {
+  console.log(`\n  Installing ${needed.join(", ")} (one-time)…`);
+  const r = spawnSync("npm", ["install", "--prefix", dest, "--silent", "--no-audit", "--no-fund", ...needed], { stdio: "inherit" });
   if (r.status === 0) ok("Playwright ready");
-  else warn("Playwright install failed — run: npm install --prefix ~/.claude/skills/agentic-recorder playwright");
+  else warn(`Install failed — run: npm install --prefix ~/.claude/skills/agentic-recorder ${needed.join(" ")}`);
+}
+// No Chrome on this machine: fetch Playwright's Chromium once so the first
+// take has a browser. Linux needs the shared libraries too (--with-deps).
+if (!haveChrome) {
+  const pw = path.join(dest, "node_modules", "playwright", "cli.js");
+  const marker = path.join(dest, ".chromium-ready");
+  if (!fs.existsSync(marker) && fs.existsSync(pw)) {
+    console.log("  Installing Chromium (one-time)…");
+    const args = [pw, "install", "chromium", ...(process.platform === "linux" ? ["--with-deps"] : [])];
+    const r = spawnSync("node", args, { stdio: "inherit", cwd: dest });
+    if (r.status === 0) { fs.writeFileSync(marker, new Date().toISOString()); ok("Chromium ready"); }
+    else warn(`Chromium install failed — run: node ${pw} install chromium${process.platform === "linux" ? " --with-deps" : ""}`);
+  } else if (fs.existsSync(marker)) ok("Chromium ready");
+}
+{
+  // Verify both tools actually run (compatibility, not presence).
+  const r = spawnSync("node", [path.join(dest, "scripts", "media-tools.mjs")], { encoding: "utf8" });
+  const rows = (r.stdout || "").trim().split("\n").filter(Boolean).map((l) => l.split("\t"));
+  for (const [tool, source, info] of rows) {
+    if (source === "missing") warn(`${tool}: no working build (${info})`);
+    else ok(`${tool} ready (${source === "packaged" ? "packaged with the recorder" : source === "system" ? "your system build" : "from .recorder/config.json"})`);
+  }
+  if (r.status !== 0) warn("Recording will fail until ffmpeg and ffprobe both work. Re-run this command, or install them on your system.");
 }
 
 // ── 3. Subcommands ─────────────────────────────────────────────────────────
@@ -128,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,7 +1,7 @@
 {
   "name": "demobite",
-  "version": "1.0.9",
-  "description": "The DemoBites agentic recorder — you prompt, it films a real browser, and DemoBites turns the take into an editable demo bite.",
+  "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"
   },
@@ -34,5 +34,9 @@
     "url": "https://github.com/demobites/agentic-recorder/issues"
   },
   "license": "MIT",
-  "type": "module"
+  "type": "module",
+  "scripts": {
+    "check-aliases": "node scripts/check-aliases.mjs",
+    "prepublishOnly": "node scripts/check-aliases.mjs"
+  }
 }

package/recorder/scripts/mux.mjs

@@ -22,15 +22,8 @@ if (!dir) {
   console.error("Usage: node mux.mjs <takeDir>");
   process.exit(2);
 }
-const requireTool = (tool) => {
-  try { execFileSync(tool, ["-version"], { stdio: "ignore" }); }
-  catch {
-    console.error(`${tool} is required on PATH. Install it (macOS: brew install ffmpeg) and rerun.`);
-    process.exit(1);
-  }
-};
-requireTool("ffmpeg");
-requireTool("ffprobe");
+import { ffmpeg as FFMPEG, ffprobe as FFPROBE, requireMediaTools } from "../../scripts/media-tools.mjs";
+requireMediaTools(["ffmpeg","ffprobe"]);
 
 const demoPath = path.join(dir, "demo.mp4");
 const manPath = path.join(dir, "manifest.json");
@@ -66,7 +59,7 @@ const delays = tts
 const mix = tts.map((_, i) => `[a${i}]`).join("") + `amix=inputs=${tts.length}:normalize=0[aout]`;
 
 const outPath = path.join(dir, "demo-voiced.mp4");
-execFileSync("ffmpeg", [
+execFileSync(FFMPEG(), [
   "-y", "-loglevel", "error",
   "-i", demoPath,
   ...inputArgs,
@@ -75,7 +68,7 @@ execFileSync("ffmpeg", [
   "-c:v", "copy", "-c:a", "aac", "-b:a", "160k",
   outPath,
 ], { stdio: "inherit" });
-const dur = execFileSync("ffprobe", [
+const dur = execFileSync(FFPROBE(), [
   "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", outPath,
 ]).toString().trim();
 console.log(`demo-voiced.mp4 ready, ${parseFloat(dur).toFixed(2)}s`);

package/recorder/scripts/post.sh

@@ -10,7 +10,10 @@
 #
 # Usage: post.sh <takeDir> [backdrop-hex-no-#]   (default backdrop 0f1420)
 set -euo pipefail
-command -v ffmpeg >/dev/null 2>&1 || { echo "ffmpeg is required on PATH. Install it (macOS: brew install ffmpeg) and rerun." >&2; exit 1; }
+HERE="$(cd "$(dirname "$0")" && pwd)"
+FFMPEG="$(node "$HERE/../../scripts/media-tools.mjs" 2>/dev/null | awk -F"\t" '$1=="ffmpeg"{print $3}')"
+FFPROBE="$(node "$HERE/../../scripts/media-tools.mjs" 2>/dev/null | awk -F"\t" '$1=="ffprobe"{print $3}')"
+[ -n "$FFMPEG" ] && [ -n "$FFPROBE" ] || { echo "ffmpeg/ffprobe: no working build found. Run npx demobite@latest again, or install them on your system." >&2; exit 1; }
 command -v node >/dev/null 2>&1 || { echo "node is required on PATH." >&2; exit 1; }
 D=${1:?Usage: post.sh <takeDir> [backdrop-hex-no-#]}
 # Backdrop resolution mirrors frame.mjs exactly: CLI arg, then the remembered
@@ -20,7 +23,7 @@ BG=${2:-$(node -p "try{(JSON.parse(require('fs').readFileSync('.recorder/config.
 [ -f "$D/raw.webm" ] || { echo "$D/raw.webm not found. Run record.mjs first." >&2; exit 1; }
 [ -f "$D/shadow.png" ] && [ -f "$D/mask.png" ] || { echo "Overlays missing. Run: node frame.mjs $D" >&2; exit 1; }
 TRIM=$(node -p "JSON.parse(require('fs').readFileSync('$D/manifest.json','utf8')).record_from||0")
-ffmpeg -y -loglevel error -i "$D/raw.webm" -i "$D/shadow.png" -i "$D/mask.png" -filter_complex \
+"$FFMPEG" -y -loglevel error -i "$D/raw.webm" -i "$D/shadow.png" -i "$D/mask.png" -filter_complex \
 "color=c=0x${BG}:s=1920x1080:r=30[bg];[0:v]trim=start=${TRIM},setpts=PTS-STARTPTS,scale=1728:972:flags=lanczos[v];[2:v]format=gray[m];[v][m]alphamerge[va];[bg][1:v]overlay=0:0[b1];[b1][va]overlay=96:54:shortest=1,fps=30,format=yuv420p[out]" \
 -map "[out]" -c:v libx264 -preset medium -crf 19 -movflags +faststart "$D/demo.mp4"
-echo "demo.mp4 duration: $(ffprobe -v error -show_entries format=duration -of csv=p=0 "$D/demo.mp4")s"
+echo "demo.mp4 duration: $("$FFPROBE" -v error -show_entries format=duration -of csv=p=0 "$D/demo.mp4")s"

package/recorder/scripts/tts.mjs

@@ -20,14 +20,8 @@ if (!dir) {
   console.error("Usage: node tts.mjs <takeDir>");
   process.exit(2);
 }
-const requireTool = (tool) => {
-  try { execFileSync(tool, ["-version"], { stdio: "ignore" }); }
-  catch {
-    console.error(`${tool} is required on PATH. Install it (macOS: brew install ffmpeg) and rerun.`);
-    process.exit(1);
-  }
-};
-requireTool("ffprobe");
+import { ffmpeg as FFMPEG, ffprobe as FFPROBE, requireMediaTools } from "../../scripts/media-tools.mjs";
+requireMediaTools(["ffprobe"]);
 
 let KEY = process.env.ELEVENLABS_API_KEY || "";
 if (!KEY) {
@@ -68,7 +62,7 @@ for (const step of narrated) {
   const buf = Buffer.from(await res.arrayBuffer());
   const file = `seg${step.n}.mp3`;
   fs.writeFileSync(path.join(outDir, file), buf);
-  const dur = parseFloat(execFileSync("ffprobe", [
+  const dur = parseFloat(execFileSync(FFPROBE(), [
     "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", path.join(outDir, file),
   ]).toString());
   out.push({ n: step.n, text: step.narration.text, file, duration: Math.round(dur * 100) / 100 });

package/scripts/calibrate.mjs

@@ -28,6 +28,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { ffmpeg as FFMPEG, requireMediaTools } from "./media-tools.mjs";
+requireMediaTools(["ffmpeg"]);
 
 const dir = process.argv[2];
 if (!dir) { console.error("Usage: node calibrate.mjs <takeDir>"); process.exit(2); }
@@ -97,7 +99,7 @@ function roiChanges(bb) {
   const pad = 6;
   const x0 = Math.max(0, bb.x - pad), y0 = Math.max(0, bb.y - pad);
   const w = Math.min(FRAME.w - x0, bb.w + 2 * pad), h = Math.min(FRAME.h - y0, bb.h + 2 * pad);
-  const res = spawnSync("ffmpeg", [
+  const res = spawnSync(FFMPEG(), [
     "-loglevel", "info", "-i", clean,
     "-vf", `crop=${w}:${h}:${x0}:${y0},select='gte(scene,0)',metadata=print`, "-f", "null", "-",
   ], { encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
@@ -218,7 +220,7 @@ if (clicks.length === 0) {
 }
 
 function sceneChanges(threshold) {
-  const res = spawnSync("ffmpeg", [
+  const res = spawnSync(FFMPEG(), [
     "-loglevel", "info", "-i", clean,
     "-vf", `select='gt(scene,${threshold})',showinfo`, "-f", "null", "-",
   ], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });

package/scripts/check-aliases.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// ALIAS GUARD (founder law, 2026-09-09): `agentic-recorder` and `demobites` on
+// npm are aliases of this package. They depend on `demobite` with a caret
+// range, so minor and patch releases flow through automatically, but a MAJOR
+// bump silently strands them on the old major. This guard runs before every
+// publish of demobite (prepublishOnly) and in CI, and refuses to continue if
+// any alias's dependency range no longer covers the version about to ship.
+//
+// When it fails: bump the range in aliases/<name>/package.json (and the alias
+// version), publish each alias from the founder's own terminal, then publish
+// demobite. See RELEASING.md.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const main = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+const aliasesDir = path.join(root, "aliases");
+const [major] = main.version.split(".").map(Number);
+
+let failed = false;
+for (const name of fs.readdirSync(aliasesDir)) {
+  const pkgPath = path.join(aliasesDir, name, "package.json");
+  if (!fs.existsSync(pkgPath)) continue;
+  const alias = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  const range = alias.dependencies?.demobite ?? "";
+  const m = /^\^(\d+)\./.exec(range);
+  const covered = m && Number(m[1]) === major;
+  const line = `${alias.name.padEnd(18)} depends on demobite ${range.padEnd(8)} → ${covered ? "covers" : "DOES NOT COVER"} ${main.version}`;
+  console.log((covered ? "  ✓ " : "  ✗ ") + line);
+  if (!covered) failed = true;
+  const bin = fs.readFileSync(path.join(aliasesDir, name, "index.mjs"), "utf8");
+  if (!bin.includes('import "demobite/launcher/index.mjs"')) {
+    console.log(`  ✗ ${alias.name} does not import the demobite launcher`);
+    failed = true;
+  }
+}
+if (failed) {
+  console.error("\nAlias guard failed: an npm alias would strand on the old major. Update aliases/*/package.json (range + version), publish the aliases, then publish demobite. See RELEASING.md.");
+  process.exit(1);
+}
+console.log("alias guard: ok");

package/scripts/media-tools.mjs

@@ -0,0 +1,93 @@
+// media-tools — the ONE place the recorder resolves ffmpeg and ffprobe.
+//
+// Order (founder design 2026-09-09):
+//   1. an explicit override in <project>/.recorder/config.json  { "ffmpeg": "...", "ffprobe": "..." }
+//   2. a SYSTEM binary on PATH that passes the compatibility probe (below)
+//   3. the packaged binaries from @ffmpeg-installer/ffmpeg + @ffprobe-installer/ffprobe
+//      (one platform each), installed by the launcher beside Playwright in the skill folder
+//
+// Compatibility, not presence: trim/mux need libx264 and the aac encoder. An old
+// or stripped system build fails the probe and the packaged binary wins.
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+// scripts/ lives directly under the skill folder; node_modules sits beside it.
+const skillRoot = path.resolve(here, "..");
+
+function probe(bin, tool) {
+  try {
+    const out = execFileSync(bin, ["-version"], { stdio: ["ignore", "pipe", "ignore"], timeout: 8000 }).toString();
+    if (!/^ff(mpeg|probe) version/m.test(out)) return { ok: false, why: "not an ffmpeg build" };
+    if (tool === "ffmpeg") {
+      const enc = execFileSync(bin, ["-hide_banner", "-encoders"], { stdio: ["ignore", "pipe", "ignore"], timeout: 8000 }).toString();
+      if (!/\blibx264\b/.test(enc)) return { ok: false, why: "no libx264 encoder" };
+      if (!/\baac\b/.test(enc)) return { ok: false, why: "no aac encoder" };
+    }
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, why: e?.code === "ENOENT" ? "not found" : "did not run" };
+  }
+}
+
+function fromOverride(tool) {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(process.cwd(), ".recorder", "config.json"), "utf8"));
+    const v = cfg?.[tool];
+    return typeof v === "string" && v ? v : null;
+  } catch { return null; }
+}
+
+function fromPackage(tool) {
+  // Per-platform packages: only the current platform's binary is downloaded.
+  const pkg = tool === "ffmpeg" ? "@ffmpeg-installer/ffmpeg" : "@ffprobe-installer/ffprobe";
+  for (const base of [skillRoot, process.cwd()]) {
+    try {
+      const req = createRequire(pathToFileURL(path.join(base, "package.json")));
+      const p = req(pkg)?.path;
+      if (typeof p === "string" && fs.existsSync(p)) return p;
+    } catch { /* not installed here */ }
+  }
+  return null;
+}
+
+const cache = {};
+/** Resolve a tool. Returns { path, source, why } — path null when nothing works. */
+export function resolveTool(tool) {
+  if (cache[tool]) return cache[tool];
+  const tried = [];
+  const o = fromOverride(tool);
+  if (o) { const r = probe(o, tool); if (r.ok) return (cache[tool] = { path: o, source: "config" }); tried.push(`config ${o}: ${r.why}`); }
+  const sys = probe(tool, tool);
+  if (sys.ok) return (cache[tool] = { path: tool, source: "system" });
+  tried.push(`system: ${sys.why}`);
+  const pk = fromPackage(tool);
+  if (pk) { const r = probe(pk, tool); if (r.ok) return (cache[tool] = { path: pk, source: "packaged" }); tried.push(`packaged ${pk}: ${r.why}`); }
+  else tried.push("packaged: not installed");
+  return (cache[tool] = { path: null, source: null, why: tried.join("; ") });
+}
+
+export const ffmpeg = () => resolveTool("ffmpeg").path;
+export const ffprobe = () => resolveTool("ffprobe").path;
+
+/** Exit with a clear message unless both tools resolve. Used by every script that films or finishes. */
+export function requireMediaTools(tools = ["ffmpeg", "ffprobe"]) {
+  const missing = tools.map((t) => [t, resolveTool(t)]).filter(([, r]) => !r.path);
+  if (missing.length) {
+    for (const [t, r] of missing) console.error(`${t}: no working build found (${r.why}).`);
+    console.error("Run `npx demobite@latest` again to install the packaged ffmpeg and ffprobe, or install them on your system.");
+    process.exit(1);
+  }
+}
+
+// `node media-tools.mjs` prints what would be used — the launcher calls this.
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  for (const t of ["ffmpeg", "ffprobe"]) {
+    const r = resolveTool(t);
+    console.log(r.path ? `${t}\t${r.source}\t${r.path}` : `${t}\tmissing\t${r.why}`);
+  }
+  process.exit(["ffmpeg", "ffprobe"].every((t) => resolveTool(t).path) ? 0 : 1);
+}