demobite 1.0.8 → 1.1.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 ─────────────────────────────────────────────────────────

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "demobite",
-  "version": "1.0.8",
-  "description": "The DemoBites agentic recorder — you prompt, it films a real browser, and DemoBites turns the take into an editable demo bite.",
+  "version": "1.1.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 });
@@ -131,10 +133,20 @@ console.log(`calibrate: map video = ${tb.a} * wall + ${tb.b.toFixed(3)} (${tb.me
 console.log(`calibrate: ${anchors.length} hover anchor${anchors.length === 1 ? "" : "s"} usable`);
 
 let anchored = false;
+// BEACON OUTRANKS ANCHORS (2026-09-02, second prod bite-96 take): the head
+// beacon had measured the cut to +-14 ms, yet ONE hover anchor locked onto a
+// stray pixel change 2.66 s away and dragged the clock with it. When the
+// beacon has spoken (trim stamped beaconDelta from >=3 matched flashes),
+// anchors may only REFINE the clock inside a third of a second; they never
+// re-decide it. Without a beacon the wide sweep stays (the pre-beacon world).
+const beaconAnchored = typeof tb?.beaconDelta === "number";
+const SWEEP_LO = beaconAnchored ? -0.35 : -3.0;
+const SWEEP_HI = beaconAnchored ? 0.35 : 1.0;
+if (beaconAnchored) console.log(`calibrate: beacon-anchored clock — hover anchors may refine by at most ${SWEEP_HI.toFixed(2)}s`);
 if (anchors.length >= 2) {
   const TOL = 0.067; // two frames
   let best = { delta: 0, score: -1, resid: Infinity };
-  for (let d = -3.0; d <= 1.0001; d += 1 / 60) {
+  for (let d = SWEEP_LO; d <= SWEEP_HI + 0.0001; d += 1 / 60) {
     let score = 0, resid = 0, hits = 0;
     for (const a of anchors) {
       const target = a.pred + d;
@@ -171,21 +183,27 @@ if (anchors.length >= 2) {
         console.log(`  anchor ${a.label}: no flip within tolerance at this offset (skipped)`);
       }
     }
-    const rms = Math.sqrt(residuals.reduce((s, r) => s + r * r, 0) / residuals.length);
-    if (rms > 0.08) {
+    if (residuals.length < 2) {
+      // One surviving anchor is an opinion, not a measurement.
+      console.log(`calibrate: only ${residuals.length} anchor survived the lock — clock left ${beaconAnchored ? "on the beacon" : "as stamped"}.`);
+      anchored = beaconAnchored;
+      best.delta = 0;
+    }
+    const rms = residuals.length >= 2 ? Math.sqrt(residuals.reduce((s, r) => s + r * r, 0) / residuals.length) : 0;
+    if (residuals.length >= 2 && rms > 0.08) {
       console.error(`CALIBRATE FAILED: hover-anchor rms ${(rms * 1000).toFixed(0)}ms exceeds 80ms — footage disagrees with itself. Do not upload.`);
       process.exit(1);
     }
-    if (Math.abs(best.delta) > 0.005) {
+    if (residuals.length >= 2 && Math.abs(best.delta) > 0.005) {
       tb.b += best.delta;
       tb.videoRecordFrom = -tb.b;
       tb.method += ` + hover-anchor ${best.delta.toFixed(3)}s (${best.hits} anchors, rms ${(rms * 1000).toFixed(0)}ms)`;
       fs.writeFileSync(manPath, JSON.stringify(man, null, 2));
       console.log(`calibrate: hover anchors moved the clock ${best.delta.toFixed(3)}s — b is now ${tb.b.toFixed(3)} (rms ${(rms * 1000).toFixed(0)}ms)`);
-    } else {
+    } else if (residuals.length >= 2) {
       console.log(`calibrate: hover anchors confirm the stamp as-is (rms ${(rms * 1000).toFixed(0)}ms)`);
     }
-    anchored = true;
+    if (residuals.length >= 2) anchored = true;
   }
 }
 
@@ -202,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 });
@@ -221,6 +239,8 @@ if (scenes.length === 0) {
   process.exit(0);
 }
 
+const SWEEP_LO_FB = beaconAnchored ? -0.35 : -4;
+const SWEEP_HI_FB = beaconAnchored ? 0.35 : 1.0;
 if (!anchored) {
   // Old plausible-latency search. Kept ONLY as the no-anchor fallback; its
   // known failure mode (plausible != true, 0.237s off on a real take) is why
@@ -237,7 +257,7 @@ if (!anchored) {
     return total;
   };
   let bestDelta = 0, bestScore = score(0);
-  for (let d = -4; d <= 1.0001; d += 1 / 30) {
+  for (let d = SWEEP_LO_FB; d <= SWEEP_HI_FB + 0.0001; d += 1 / 30) {
     const sc = score(d);
     if (sc < bestScore - 1e-9) { bestScore = sc; bestDelta = d; }
   }
@@ -272,6 +292,15 @@ if (!anchored && (median < -0.15 || median > 0.9)) {
   );
   process.exit(1);
 }
+if (!beaconAnchored && anchored && (median < -0.6 || median > 2.5)) {
+  // INCIDENT 2026-09-02: +4.6 s "latency" on an anchored clock was the head
+  // miscut showing through (the anchors had locked onto the wrong beat).
+  console.error(`VERIFY FAILED: median click latency ${median.toFixed(3)}s on an anchor-measured clock is not an app delay, it is a broken timebase (the cut point or the anchor lock is wrong). Do not upload — film again.`);
+  process.exit(1);
+}
+if (beaconAnchored && (median < -0.6 || median > 2.5)) {
+  console.log(`WARNING: median click latency ${median.toFixed(3)}s on a beacon-measured clock — the clock is trusted, so the app genuinely answered late. The footage shows the wait; judge whether the beat reads as slow.`);
+}
 if (anchored && (median < -0.15 || median > 0.9)) {
   console.log(`note: median click latency ${median.toFixed(3)}s is unusual, but the clock is anchor-measured — likely a genuinely slow app response. Judge the take on duration and feel.`);
 }

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);
+}

package/scripts/record.mjs

@@ -40,7 +40,7 @@ const DIR = path.resolve(outArg);
 // RE-TAKE (founder 2026-09-02): the storyboard IS the bite's DNA. Keep a verbatim
 // copy in the take dir so upload.mjs can stage it as the recording recipe —
 // selectors, urls, typed text, hideCss — the wire manifest alone cannot re-film.
-const ENGINE_VERSION = "1.0.8";
+const ENGINE_VERSION = "1.0.9";
 fs.mkdirSync(DIR, { recursive: true });
 // The copy is the RECIPE, not the transport: cdpWsUrl / storageStatePath are
 // per-take plumbing stamped by the cloud runner (a CDP url carries a session
@@ -615,6 +615,7 @@ async function smoothScroll(dy, ms = 1400, within = null) {
   }), [dy, ms, within]);
 }
 
+const BEACON_GAPS_MS = [300, 450, 600, 750, 900, 1050];
 // ── Head beacon ────────────────────────────────────────────────────────────
 // The identity law (video = wall - record_from) assumes raw.webm's t=0 lines
 // up with T0. That anchoring is otherwise UNMEASURED: on a cold remote-CDP
@@ -634,22 +635,26 @@ try {
     // stamp error at half a CDP round trip — inside one frame co-located.
     return { color, wall: (before + after) / 2 };
   };
-  // Wait for the screencast to actually be ROLLING (first frames on disk):
-  // over a remote CDP link the recorder starts late, and a flash before the
-  // first frame is invisible (mode A smoke, 2026-09-02).
-  const rollDeadline = Date.now() + 5000;
-  while (Date.now() < rollDeadline) {
-    const rolling = fs.readdirSync(DIR).some((f) => f.endsWith(".webm") && fs.statSync(path.join(DIR, f)).size > 4096);
-    if (rolling) break;
-    await page.waitForTimeout(100);
-  }
+  // GAP-CODED PATTERN (2026-09-02, after the prod bite-96 miscut): nothing
+  // inside this process can see whether the screencast is rolling yet (the
+  // video file does not grow while recording), and under load the first
+  // frame can land seconds after the page exists. So the beacon no longer
+  // relies on being seen from its first flash: seven flashes with strictly
+  // increasing gaps form a signature trim.mjs recognises from ANY three
+  // consecutive flashes it finds. A screencast that started late still
+  // yields the anchor; one that missed every flash stops the take in trim.
   await page.evaluate(() => { document.documentElement.style.background = "#ffffff"; });
-  await page.waitForTimeout(600); // let the white state reach the recording
+  await page.waitForTimeout(1500); // let the page exist and the white state settle
   const flips = [];
-  flips.push(await flip("#ff00ff")); // onset 1: white -> magenta
-  await page.waitForTimeout(400);
-  flips.push(await flip("#ffffff")); // onset 2: magenta -> white
-  await page.waitForTimeout(400);
+  let color = "#ff00ff";
+  for (const gapMs of BEACON_GAPS_MS) {
+    flips.push(await flip(color));
+    color = color === "#ff00ff" ? "#ffffff" : "#ff00ff";
+    await page.waitForTimeout(gapMs);
+  }
+  flips.push(await flip(color)); // final onset closes the last gap
+  if (color === "#ff00ff") { await page.waitForTimeout(250); flips.push(await flip("#ffffff")); }
+  await page.waitForTimeout(300);
   manifest.beacon = { flips };
   process.stdout.write(`beacon: flips at ${flips.map((f) => f.wall.toFixed(3)).join("s, ")}s (wall)\n`);
 } catch (e) {

package/scripts/trim.mjs

@@ -15,15 +15,8 @@ if (!dir) {
   console.error("Usage: node trim.mjs <takeDir>");
   process.exit(2);
 }
-const requireTool = (tool) => {
-  try { execFileSync(tool, ["-version"], { stdio: "ignore" }); }
-  catch {
-    console.error(`${tool} is required on PATH. Install it (macOS: brew install ffmpeg) and rerun.`);
-    process.exit(1);
-  }
-};
-requireTool("ffmpeg");
-requireTool("ffprobe");
+import { ffmpeg as FFMPEG, ffprobe as FFPROBE, requireMediaTools } from "./media-tools.mjs";
+requireMediaTools();
 
 const raw = path.join(dir, "raw.webm");
 const manPath = path.join(dir, "manifest.json");
@@ -56,36 +49,83 @@ const r0 = man.record_from ?? 0;
 // Shift the cut by it so clean.mp4 truly begins at the record_from moment.
 let beaconDelta = 0;
 let beaconMethod = "";
-if ((man.beacon?.flips?.length ?? 0) >= 2) {
+if ((man.beacon?.flips?.length ?? 0) >= 3) {
   const flips = man.beacon.flips;
   // The flashes are the first big whole-frame changes in the head. Search a
   // window generous enough for seconds of anchor error in either direction.
-  const searchEnd = Math.min(Math.max(r0, flips[flips.length - 1].wall) + 8, 40);
-  const res = spawnSync("ffmpeg", [
+  const searchEnd = Math.min(Math.max(r0, flips[flips.length - 1].wall) + 10, 45);
+  const res = spawnSync(FFMPEG(), [
     "-loglevel", "info", "-t", String(searchEnd), "-i", raw,
     "-vf", "select='gt(scene,0.3)',showinfo", "-f", "null", "-",
   ], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
   const onsets = [...`${res.stderr ?? ""}`.matchAll(/pts_time:([0-9.]+)/g)]
     .map((m) => parseFloat(m[1]));
-  if (onsets.length >= 2) {
-    // Pair the first two onsets to the two flips, in order. Anything the page
-    // paints later (the goto) lands after onset 2 and never enters the pair.
-    const d1 = flips[0].wall - onsets[0];
-    const d2 = flips[1].wall - onsets[1];
-    const spread = Math.abs(d1 - d2);
-    if (spread <= 0.15) {
-      beaconDelta = (d1 + d2) / 2;
-      beaconMethod = ` + head-beacon anchor ${beaconDelta >= 0 ? "+" : ""}${beaconDelta.toFixed(3)}s (2 flips, spread ${(spread * 1000).toFixed(0)}ms)`;
-      console.log(`beacon: anchor error ${beaconDelta >= 0 ? "+" : ""}${beaconDelta.toFixed(3)}s measured (flip spread ${(spread * 1000).toFixed(0)}ms) — cut corrected`);
-    } else {
-      console.log(`beacon: flip deltas disagree (${(spread * 1000).toFixed(0)}ms spread) — ignoring beacon, cut stays as stamped`);
+  // Align the KNOWN flash gaps against the DETECTED onset gaps: slide every
+  // flip index against every onset index and count consecutive gap matches
+  // (tolerance 70 ms). Three flashes in a row (two matching gaps) identify
+  // the pattern unambiguously because the gaps strictly increase; the
+  // alignment with the most matches wins. Missing leading flashes (a
+  // screencast that started late) cost nothing but the pairs they would
+  // have added.
+  const TOL = 0.07;
+  let best = null;
+  for (let i = 0; i < flips.length - 2; i++) {
+    for (let j = 0; j < onsets.length - 2; j++) {
+      let k = 0;
+      while (i + k + 1 < flips.length && j + k + 1 < onsets.length) {
+        const gf = flips[i + k + 1].wall - flips[i + k].wall;
+        const go = onsets[j + k + 1] - onsets[j + k];
+        if (Math.abs(gf - go) > TOL) break;
+        k++;
+      }
+      if (k >= 2 && (!best || k > best.k)) best = { i, j, k };
+    }
+  }
+  if (best) {
+    const deltas = [];
+    for (let m = 0; m <= best.k; m++) deltas.push(flips[best.i + m].wall - onsets[best.j + m]);
+    const spread = Math.max(...deltas) - Math.min(...deltas);
+    beaconDelta = deltas.reduce((a, b) => a + b, 0) / deltas.length;
+    const missed = best.i;
+    beaconMethod = ` + head-beacon anchor ${beaconDelta >= 0 ? "+" : ""}${beaconDelta.toFixed(3)}s (${deltas.length} flashes matched, ${missed} missed, spread ${(spread * 1000).toFixed(0)}ms)`;
+    console.log(`beacon: anchor error ${beaconDelta >= 0 ? "+" : ""}${beaconDelta.toFixed(3)}s measured from ${deltas.length} flashes (${missed} before the first frame, spread ${(spread * 1000).toFixed(0)}ms) — cut corrected`);
+    if (spread > 0.15) {
+      console.error(`BEACON FAILED: matched flashes disagree by ${(spread * 1000).toFixed(0)}ms. The cut point cannot be trusted — do not upload, film again.`);
+      process.exit(3);
     }
   } else {
-    console.log("beacon: flashes not found in the raw head — cut stays as stamped");
+    // INCIDENT 2026-09-02: a missed beacon staged a take whose head was cut
+    // seconds late (screencast started after the flashes). The stamped cut
+    // is only right when the screencast began at wall 0, which nothing
+    // guarantees — so a recorded-but-unfound beacon is a hard stop.
+    console.error(`BEACON FAILED: no run of the flash pattern found in the raw head (${onsets.length} onsets seen). The startup lead is unmeasured and the cut point cannot be trusted. Do not upload — film again (a busy machine delays the screencast; let builds finish first).`);
+    process.exit(3);
   }
 }
 
 const cutAt = Math.max(0, r0 - beaconDelta);
+
+// TAIL law (vanilla-Linux smoke 2026-09-09): raw.webm keeps receiving frames
+// while the browser context tears down — on a headless shell that was a
+// ~10 s FROZEN tail after the last beat, and the agent had to cut it by hand.
+// The story ends where the recorder's last step ended; keep one breath after
+// it and cut the rest. Clean time = wall - record_from (identity law above),
+// so the story's end in raw time is cutAt + (lastStepEnd - r0). Only applied
+// when the raw file actually runs on past that point.
+const TAIL_BEAT_S = 0.8;
+const lastStepEnd = Math.max(0, ...(man.steps ?? []).map((st) => Number(st.t_end) || 0));
+let tailCut = 0;
+if (lastStepEnd > r0) {
+  const storyEndRaw = cutAt + (lastStepEnd - r0) + TAIL_BEAT_S;
+  let rawDur = 0;
+  try {
+    rawDur = parseFloat(execFileSync(FFPROBE(), ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", raw]).toString().trim()) || 0;
+  } catch { /* webm without a duration header — fall through, no tail cut */ }
+  if (rawDur && rawDur - storyEndRaw > 1.0) {
+    tailCut = Math.round(storyEndRaw * 100) / 100;
+    console.log(`tail: raw runs ${(rawDur - storyEndRaw).toFixed(1)}s past the last beat — cutting at ${tailCut.toFixed(2)}s (last step ended at ${(lastStepEnd - r0).toFixed(2)}s of clean time)`);
+  }
+}
 if (cutAt !== r0 - beaconDelta) console.log("beacon: corrected cut clamped at 0 — head shorter than the anchor error");
 man.timebase = {
   a: 1,
@@ -98,17 +138,17 @@ man.timebase = {
 fs.writeFileSync(manPath, JSON.stringify(man, null, 2));
 console.log(`timebase: identity, video = wall - ${r0.toFixed(3)}${beaconMethod ? ` (cut at raw ${cutAt.toFixed(3)}s)` : ""}`);
 
-execFileSync("ffmpeg", [
+execFileSync(FFMPEG(), [
   "-y", "-loglevel", "error",
   "-i", raw,
-  "-filter_complex", `[0:v]trim=start=${cutAt},setpts=PTS-STARTPTS,fps=30,format=yuv420p[out]`,
+  "-filter_complex", `[0:v]trim=${tailCut ? `start=${cutAt}:end=${tailCut}` : `start=${cutAt}`},setpts=PTS-STARTPTS,fps=30,format=yuv420p[out]`,
   "-map", "[out]",
   "-c:v", "libx264", "-preset", "medium", "-crf", "19",
   "-movflags", "+faststart",
   clean,
 ], { stdio: "inherit" });
 
-const dur = execFileSync("ffprobe", [
+const dur = execFileSync(FFPROBE(), [
   "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", clean,
 ]).toString().trim();
 const duration = parseFloat(dur);

package/skill/SKILL.md

@@ -7,7 +7,7 @@ description: Film a product demo by driving a real browser from a storyboard and
 
 You are the camera operator, the director, and the editor. You film a real browser doing a real flow, narrate it, and deliver a clean take into DemoBites, where everything — voice, camera, cursor, look — becomes editable. There is ONE delivery: a DemoBites bite. Never ask how the demo should be delivered.
 
-All scripts live in `scripts/` beside this file. They are plain Node ESM. Requirements: Node 18+, `playwright` installed with Chromium (`npm i playwright && npx playwright install chromium`), and `ffmpeg` on PATH. Run every script from the project directory so `.recorder/` lands next to the project.
+All scripts live in `scripts/` beside this file. They are plain Node ESM. Requirements: Node 18+. `npx demobite` installs Playwright, ffmpeg and ffprobe beside the skill; every script resolves the media tools through `scripts/media-tools.mjs` (a compatible system build first, then the packaged one). Never call `ffmpeg` or `ffprobe` by bare name in a new script. Run every script from the project directory so `.recorder/` lands next to the project.
 
 Follow the phases in order. Never skip the storyboard approval. Never ingest before the human's word — for DemoBites, Approve on the in-app preview page IS the word.
 

package/skill/scripts/manifest.mjs

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