demobite 0.0.1 → 1.0.1

package/README.md

@@ -7,16 +7,26 @@ a fully editable demo: AI narration, zooms, cursor rendering, intro and outro,
 localization, all tweakable in the studio.
 
 ```bash
-npx demobite@latest
+npx demobite
 ```
 
 That one command checks your setup, installs the recorder skill for
-[Claude Code](https://claude.com/claude-code), and connects your machine to
-DemoBites through your own browser — no passwords in the terminal, ever.
+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:
 
 > "Record a demo of how search works on our app, and upload it to DemoBites."
 
+> "Create a release with my latest bites and add Spanish."
+
+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.
+
 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.
@@ -26,7 +36,7 @@ does the rest.
 | Directory | What it is |
 |---|---|
 | `launcher/` | The `npx demobite` entry — environment checks, skill install, login |
-| `skill/` | The DemoBites recorder skill for Claude Code (staging, preview, approval flow) |
+| `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 |
 
@@ -34,7 +44,7 @@ does the rest.
 
 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 Claude Code at it and
+`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.
 
@@ -48,7 +58,7 @@ is cryptographically tied to a public commit in this repository.
 ## Requirements
 
 - Node 18+
-- [Claude Code](https://claude.com/claude-code) — the recorder is agent-driven
+- 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)

package/launcher/index.mjs

@@ -1,14 +1,21 @@
 #!/usr/bin/env node
-// demobite — the DemoBites agentic recorder, one command away.
+// demobite — connect DemoBites to your agent, one command away.
 //
-//   npx demobite@latest            install/update the skill + check your setup
+//   npx demobite@latest            full setup: checks, recorder skill, MCP
 //   npx demobite@latest login      connect this machine to DemoBites
+//   npx demobite@latest mcp        register the DemoBites management MCP
 //   npx demobite@latest logout     disconnect (revokes the key server-side)
 //
+// One front door (founder 2026-08-31): the user never chooses between the
+// recorder skill and the management MCP — bare `npx demobite` sets up both.
+// The MCP is universal (every agent gets it); the skill is the bonus layer
+// for code agents, and stays the advocated recording lane because the agent
+// knows the customer's code. `agentic-recorder` remains a docs alias of bare.
+//
 // This launcher is deliberately boring: it verifies the environment, installs
-// the recorder skill into your agent's skills directory, and hands off. The
-// recorder itself is driven by your coding agent (Claude Code): once set up,
-// you just ask it — "record a demo of how search works on our app".
+// the recorder skill into your agent's skills directory, wires the MCP, and
+// hands off. The recorder itself is driven by your coding agent (Claude
+// Code): once set up, you just ask it — "record a demo of our search flow".
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -42,8 +49,8 @@ if (chromePaths.some((p) => fs.existsSync(p)) || hasBin("google-chrome")) ok("Go
 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");
-if (hasBin("claude")) ok("Claude Code (the agent that drives the recorder)");
-else warn("Claude Code not found — install it from https://claude.com/claude-code, the recorder is agent-driven");
+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");
 
 // ── 2. Install / update the skill ──────────────────────────────────────────
 const skillsDir = path.join(os.homedir(), ".claude", "skills");
@@ -73,12 +80,72 @@ if (arg === "login" || arg === "logout") {
   process.exit(r.status ?? 0);
 }
 
+// ── 3b. Management MCP ─────────────────────────────────────────────────────
+// The key lives in <cwd>/.recorder/config.json (login.mjs writes it there),
+// so MCP registration is per-project too — `claude mcp add` default (local)
+// scope matches that exactly and keeps the key out of committable files.
+const readCfg = () => {
+  try { return JSON.parse(fs.readFileSync(path.join(process.cwd(), ".recorder", "config.json"), "utf8")); }
+  catch { return null; }
+};
+const registerMcp = (cfg, { quiet = false } = {}) => {
+  const url = `${cfg.base ?? "https://app.demobites.com"}/api/mcp`;
+  const header = `Authorization: Bearer ${cfg.api_key}`;
+  if (hasBin("claude")) {
+    const r = spawnSync("claude", ["mcp", "add", "--transport", "http", "demobites", url, "--header", header], {
+      stdio: quiet ? "ignore" : "inherit",
+      cwd: process.cwd(),
+    });
+    if (r.status === 0) { ok(`DemoBites MCP registered with Claude Code (${url})`); return true; }
+  }
+  if (!quiet) {
+    console.log(`
+Add the DemoBites MCP to your agent manually — Streamable HTTP:
+
+    URL:     ${url}
+    Header:  ${header}
+
+Claude Code:  claude mcp add --transport http demobites ${url} --header "${header}"
+Cursor:       add the URL + header under Settings → MCP
+Other MCP clients: any Streamable HTTP client works with the same URL + header.
+`);
+  }
+  return false;
+};
+
+if (arg === "mcp") {
+  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); }
+  registerMcp(cfg);
+  console.log(`
+Your agent can now manage DemoBites — try asking it:
+
+    "Create a release with my latest bites and add Spanish"
+
+Publishing always shows you a preview to approve first.
+`);
+  process.exit(0);
+}
+
 // ── 4. Handoff ─────────────────────────────────────────────────────────────
+// Bare invocation (and the `agentic-recorder` docs alias): if this project is
+// already linked, quietly wire the MCP too — one command, both magics.
+const cfg = readCfg();
+if (cfg?.api_key) registerMcp(cfg, { quiet: true });
 console.log(`
-Ready. The recorder is agent-driven — open Claude Code in your project and ask:
+Ready. Everything is agent-driven — open your coding agent (Claude Code,
+Cursor, Codex) in your project and ask:
 
     "Record a demo of <your flow> and upload it to DemoBites"
+    "Create a release with my latest bites and add Spanish"
 
 It signs in via your browser on first use (or run: npx demobite login).
+Manage-by-agent needs the MCP: npx demobite mcp (once, after login).
 Only the recorder, no DemoBites? See the open recorder in this package's repo.
 `);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "demobite",
-  "version": "0.0.1",
-  "description": "The DemoBites agentic recorder — you prompt, it films a real browser, and DemoBites turns the take into an editable demo bite.",
+  "version": "1.0.1",
+  "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"
   },
@@ -27,12 +27,12 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/demobites/demobite.git"
+    "url": "git+https://github.com/demobites/agentic-recorder.git"
   },
-  "homepage": "https://github.com/demobites/demobite#readme",
+  "homepage": "https://github.com/demobites/agentic-recorder#readme",
   "bugs": {
-    "url": "https://github.com/demobites/demobite/issues"
+    "url": "https://github.com/demobites/agentic-recorder/issues"
   },
   "license": "MIT",
   "type": "module"
-}
+}

package/scripts/record.mjs

@@ -20,7 +20,7 @@ if (!outArg || !storyArg) {
 }
 
 const STORYBOARD = JSON.parse(fs.readFileSync(storyArg, "utf8"));
-const ACTIONS = new Set(["goto", "settle", "scroll", "click", "hover"]);
+const ACTIONS = new Set(["goto", "settle", "scroll", "click", "hover", "type", "expect"]);
 if (!Array.isArray(STORYBOARD.steps) || STORYBOARD.steps.length === 0) {
   console.error("Storyboard has no steps.");
   process.exit(2);
@@ -31,6 +31,8 @@ for (const [i, s] of STORYBOARD.steps.entries()) {
   if (s.action === "goto" && !s.url) { console.error(`${at}: goto needs url`); process.exit(2); }
   if (s.action === "scroll" && typeof s.dy !== "number") { console.error(`${at}: scroll needs numeric dy`); process.exit(2); }
   if ((s.action === "click" || s.action === "hover") && !s.selector) { console.error(`${at}: ${s.action} needs selector`); process.exit(2); }
+  if (s.action === "type" && (!s.selector || typeof s.text !== "string")) { console.error(`${at}: type needs selector and text`); process.exit(2); }
+  if (s.action === "expect" && !s.selector) { console.error(`${at}: expect needs selector`); process.exit(2); }
 }
 
 const DIR = path.resolve(outArg);
@@ -486,17 +488,30 @@ async function glide(x, y) {
   pushMouse("move", x, y);
 }
 
-async function smoothScroll(dy, ms = 1400) {
-  await page.evaluate(([d, m]) => new Promise((res) => {
-    const y0 = window.scrollY, t0 = performance.now();
+async function smoothScroll(dy, ms = 1400, within = null) {
+  // `within` (2026-08-28, UC-studio lesson): full-viewport apps scroll INNER
+  // panels, not the window — window.scrollTo is a no-op there. When set, it
+  // is a CSS selector; the first matching element that actually scrolls
+  // (scrollHeight meaningfully over clientHeight) is eased instead of the
+  // window. Same easing, same on-camera motion.
+  await page.evaluate(([d, m, sel]) => new Promise((res) => {
+    let target = null;
+    if (sel) {
+      target = [...document.querySelectorAll(sel)].find(
+        (el) => el.scrollHeight > el.clientHeight + 40,
+      ) ?? null;
+    }
+    const y0 = target ? target.scrollTop : window.scrollY;
+    const t0 = performance.now();
     const step = (now) => {
       const e = Math.min(1, (now - t0) / m);
       const ease = e < 0.5 ? 2 * e * e : 1 - Math.pow(-2 * e + 2, 2) / 2;
-      window.scrollTo(0, y0 + d * ease);
+      if (target) target.scrollTo(0, y0 + d * ease);
+      else window.scrollTo(0, y0 + d * ease);
       e < 1 ? requestAnimationFrame(step) : res();
     };
     requestAnimationFrame(step);
-  }), [dy, ms]);
+  }), [dy, ms, within]);
 }
 
 let failure = null;
@@ -518,11 +533,46 @@ try {
       await ensureCursor();
       await applyHideCss();
       if (manifest.record_from === undefined) {
-        // LAW (first-frame, founder 2026-08-08): the published cut opens on a
-        // FULLY loaded page — wait for network quiet (best effort, LinkedIn
-        // style long-pollers never go fully idle) plus a short beat, THEN
-        // stamp record_from: where the final video begins.
+        // LAW (first-frame, founder 2026-08-08, HARDENED 2026-08-13 after a
+        // take opened on a white page): the published cut opens on a FULLY
+        // loaded page. Network quiet is NOT paint — client-rendered apps go
+        // networkidle while the screen is still blank. Three gates in order:
+        //   1. network quiet (best effort — long-pollers never go idle)
+        //   2. PAINT GATE: poll until the page shows real content (visible
+        //      text mass or media elements), up to 15s
+        //   3. if the NEXT storyboard step is an `expect`, resolve it HERE,
+        //      before the stamp — the cut then provably opens on the state
+        //      the story assumes (the expect step later re-checks instantly)
+        // Only then stamp record_from: where the final video begins.
         await page.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => {});
+        const paintDeadline = Date.now() + 15000;
+        let painted = false;
+        while (Date.now() < paintDeadline) {
+          painted = await page.evaluate(() => {
+            const textMass = (document.body?.innerText ?? "").trim().length;
+            const media = document.querySelectorAll("img, video, canvas, svg").length;
+            let visible = 0;
+            for (const el of document.querySelectorAll("div, section, main, button")) {
+              const r = el.getBoundingClientRect();
+              if (r.width > 40 && r.height > 20) { visible++; if (visible > 8) break; }
+            }
+            return (textMass > 80 || media >= 3) && visible > 8;
+          }).catch(() => false);
+          if (painted) break;
+          await page.waitForTimeout(250);
+        }
+        if (!painted) {
+          console.log("PAINT GATE: page never showed real content within 15s — the take would open on a blank frame. Judge the footage carefully.");
+        }
+        const nextStep = STORYBOARD.steps[STORYBOARD.steps.indexOf(step) + 1];
+        if (nextStep?.action === "expect" && nextStep.selector) {
+          const sel = nextStep.text
+            ? `${nextStep.selector}:has-text(${JSON.stringify(nextStep.text)})`
+            : nextStep.selector;
+          await page.locator(sel).first().waitFor({ state: "visible", timeout: nextStep.timeout ?? 15000 }).catch(() => {
+            console.log(`PAINT GATE: pre-stamp expect "${sel}" not visible — stamping anyway; the expect step will abort the take.`);
+          });
+        }
         await page.waitForTimeout(600);
         manifest.record_from = t();
       }
@@ -539,7 +589,7 @@ try {
     } else if (step.action === "scroll") {
       // scrollTo distances are ALSO zoomed-space under CSS zoom (measured:
       // scrollTo(0,600) moves 300 design px) — storyboards speak design px.
-      await smoothScroll(step.dy * SUPERSAMPLE, step.ms ?? 1400);
+      await smoothScroll(step.dy * SUPERSAMPLE, step.ms ?? 1400, step.within ?? null);
     } else if (step.action === "click" || step.action === "hover") {
       const { box, el } = await visibleTarget(step.selector, step.minY ?? 0);
       if (!box) throw new Error("no visible target for " + step.selector);
@@ -551,7 +601,12 @@ try {
         rec.slow_content_ms = visibleTarget.lastWaitMs;
         console.log(`SLOW CONTENT: step ${rec.n} waited ${(visibleTarget.lastWaitMs / 1000).toFixed(1)}s for its target — content was loading on camera. Judge the take; prefer a retake.`);
       }
-      const x = box.x + box.width / 2, y = box.y + box.height / 2;
+      // Optional fractional click point within the target box (step.at =
+      // [fx, fy], each 0..1, default center). Lets a click SET a value on
+      // track-style controls (sliders) without needing drag support.
+      const atFx = Array.isArray(step.at) ? Math.min(1, Math.max(0, step.at[0] ?? 0.5)) : 0.5;
+      const atFy = Array.isArray(step.at) ? Math.min(1, Math.max(0, step.at[1] ?? 0.5)) : 0.5;
+      const x = box.x + box.width * atFx, y = box.y + box.height * atFy;
       // Resolved BEFORE the glide so the answer costs no video time.
       const targetCursor = await cursorForElement(el);
       const shotStart = t();
@@ -673,6 +728,72 @@ try {
           }
         }
       }
+    } else if (step.action === "expect") {
+      // PRECONDITION GATE (brand-kit incident, 2026-08-11): assert the page
+      // is what the story assumes BEFORE any mutating click. Costs no camera
+      // time — no cursor movement, no shot. The take FAILS LOUDLY here if
+      // the state is wrong (wrong workspace, wrong account, wrong screen),
+      // instead of filming a confident mistake.
+      const sel = step.text
+        ? `${step.selector}:has-text(${JSON.stringify(step.text)})`
+        : step.selector;
+      try {
+        await page.locator(sel).first().waitFor({ state: "visible", timeout: step.timeout ?? 8000 });
+      } catch {
+        throw new Error(
+          `EXPECT FAILED at step ${rec.n}: "${sel}" not visible — the page is not what the storyboard assumes. Take aborted before any further action.`
+        );
+      }
+    } else if (step.action === "type") {
+      // Click the field, then type with a human cadence. Optional step.clear
+      // selects-all + deletes first; optional step.enter presses Enter after.
+      const { box, el } = await visibleTarget(step.selector, step.minY ?? 0);
+      if (!box) throw new Error("no visible target for " + step.selector);
+      const x = box.x + box.width / 2, y = box.y + box.height / 2;
+      const targetCursor = await cursorForElement(el);
+      const shotStart = t();
+      currentCursor = "arrow";
+      await glide(x, y);
+      const arrivalT = t();
+      currentCursor = targetCursor;
+      rec.cursor = currentCursor;
+      pushMouse("move", x, y);
+      rec.target = {
+        selector: step.selector,
+        x: Math.round(x / SUPERSAMPLE), y: Math.round(y / SUPERSAMPLE),
+        bbox: {
+          x: Math.round(box.x / SUPERSAMPLE), y: Math.round(box.y / SUPERSAMPLE),
+          w: Math.round(box.width / SUPERSAMPLE), h: Math.round(box.height / SUPERSAMPLE),
+        },
+      };
+      await page.waitForTimeout(step.dwell ?? DEFAULT_CLICK_DWELL);
+      await page.evaluate(([a, b]) => window.__recPulse?.(a, b), [x, y]);
+      await page.waitForTimeout(220);
+      rec.click_at = t();
+      pushMouse("click", x, y, "left");
+      await page.mouse.click(x, y);
+      await page.waitForTimeout(380);
+      if (step.clear) {
+        await page.keyboard.press(process.platform === "darwin" ? "Meta+a" : "Control+a");
+        await page.waitForTimeout(180);
+        await page.keyboard.press("Backspace");
+        await page.waitForTimeout(280);
+      }
+      const text = String(step.text);
+      rec.typed = text;
+      for (const ch of text) {
+        await page.keyboard.type(ch);
+        await page.waitForTimeout(34 + Math.random() * 70);
+      }
+      if (step.enter) {
+        await page.waitForTimeout(300);
+        await page.keyboard.press("Enter");
+      }
+      // One shot: the field, from arrival through the typing.
+      pushShot(box, Math.max(shotStart, arrivalT - 0.3), t() + 0.3, step.label ?? "type", { n: rec.n, glide: { t_start: Math.round(shotStart * 100) / 100, t_end: Math.round(arrivalT * 100) / 100 } });
+      currentCursor = await cursorUnderPoint();
+      pushMouse("move", cx, cy);
+      await page.waitForTimeout(step.after ?? DEFAULT_CLICK_AFTER);
     }
     rec.t_end = t();
     manifest.steps.push(rec);

package/scripts/trim.mjs

@@ -69,4 +69,20 @@ execFileSync("ffmpeg", [
 const dur = execFileSync("ffprobe", [
   "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", clean,
 ]).toString().trim();
+const duration = parseFloat(dur);
+// LAW (founder): a Bite is capped at 90 seconds by product concept. A take
+// that cuts longer than that must not proceed to staging — the story needs a
+// SPLIT, not a trim. Fail loudly here, before any upload machinery runs.
+if (duration > 90) {
+  console.error(
+    `HARD CAP: this take cuts to ${duration.toFixed(1)}s — a Bite is limited to 90 seconds. ` +
+    "Do not upload. Split the scenario into multiple Bites and refilm."
+  );
+  process.exit(1);
+}
+if (duration > 60) {
+  console.error(
+    `Note: ${duration.toFixed(1)}s is long for a Bite — the sweet spot is 30 to 45 seconds. Consider tightening.`
+  );
+}
 console.log(`clean.mp4 ready in ${dir} (trimmed ${r0.toFixed ? r0.toFixed(2) : r0}s from the head), duration ${parseFloat(dur).toFixed(2)}s`);

package/skill/SKILL.md

@@ -53,7 +53,7 @@ Look for `.recorder/config.json` next to the project. If it exists, use it and a
 - **app**: the product's name as it should appear in titles.
 - **url**: the starting URL of the flow.
 - **frame**: fixed at 1920x1080 for now, do not ask, just record it.
-- **base**: defaults to `https://dev.demobites.com`, only ask if the human mentions a different environment.
+- **base**: defaults to `https://app.demobites.com`, only ask if the human mentions a different environment.
 
 Write the answers to `.recorder/config.json` and never ask again:
 
@@ -62,7 +62,7 @@ Write the answers to `.recorder/config.json` and never ask again:
   "app": "Acme",
   "url": "https://app.acme.com",
   "frame": { "width": 1920, "height": 1080 },
-  "base": "https://dev.demobites.com"
+  "base": "https://app.demobites.com"
 }
 ```
 
@@ -91,6 +91,12 @@ Holding shots to cover estimated lines is what produced a 60 second take with th
 **Budgets, hold yourself to them:**
 
 - **30 to 45 seconds total.** Over 45 is a rewrite, not a trim.
+- **90 seconds is a HARD CAP, by product concept, and it is a limit, not a
+  target.** A Bite over 90 seconds does not exist. Budget the beats BEFORE
+  filming: if the human's scenario cannot honestly fit inside 90 seconds, do
+  not film-and-trim and do not compress it into uselessness — tell them up
+  front and ask them to SPLIT it into multiple Bites, one story per Bite.
+  State the estimated duration in every storyboard presentation.
 - **6 to 10 beats.** More than that and nothing gets seen.
 - **8 to 14 words per narration line.** Short beats one long one, every time.
 - Trust the defaults in `record.mjs` (`DEFAULT_HOVER_DWELL` 3.2s, `DEFAULT_CLICK_AFTER` 2.0s). Only override when the app itself is slow.
@@ -279,7 +285,7 @@ GET <base>/api/recorder/status?biteId=<id>  (Authorization: Bearer <api_key>)
   -> { status, title, durationSec, zooms, narrationTotal, narrationReady, transcription }
 ```
 
-The upload zip contains exactly one file: `clean.mp4` stored as `recording.mp4`. Nothing else goes in the zip. Default base is `https://dev.demobites.com`, overridable via `config.base`.
+The upload zip contains exactly one file: `clean.mp4` stored as `recording.mp4`. Nothing else goes in the zip. Default base is `https://app.demobites.com`, overridable via `config.base`.
 
 ## Standing rules
 

package/skill/scripts/login.mjs

@@ -15,7 +15,7 @@
 //        node login.mjs --logout     revoke the key server-side AND strip it
 //                                    from local config — a leaked config file
 //                                    dies with the logout.
-// Base resolution: CLI arg, config.base, https://dev.demobites.com.
+// Base resolution: CLI arg, config.base, https://app.demobites.com.
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
@@ -33,8 +33,8 @@ const wantLogout = process.argv.includes("--logout");
 // CLI base argument must not point the revoke at a different host (review
 // finding — the real key would stay live while we claim success).
 const base = (wantLogout
-  ? (cfg.base || argv[0] || "https://dev.demobites.com")
-  : (argv[0] || cfg.base || "https://dev.demobites.com")
+  ? (cfg.base || argv[0] || "https://app.demobites.com")
+  : (argv[0] || cfg.base || "https://app.demobites.com")
 ).replace(/\/+$/, "");
 
 if (wantLogout) {
@@ -126,6 +126,9 @@ while (Date.now() < deadline) {
     cfg.base = base;
     cfg.api_key = data.api_key;
     cfg.workspace = data.workspace;
+    // Capability scopes (MCP engine 2026-08-31): "manage" rides only on
+    // Grow-approved keys and unlocks `npx demobite mcp`.
+    cfg.scopes = Array.isArray(data.scopes) && data.scopes.length ? data.scopes : ["record"];
     fs.mkdirSync(cfgDir, { recursive: true });
     fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + "\n");
     fs.chmodSync(cfgPath, 0o600);
@@ -133,7 +136,11 @@ while (Date.now() < deadline) {
       data.workspace && typeof data.workspace === "object"
         ? data.workspace.name ?? data.workspace.slug ?? JSON.stringify(data.workspace)
         : data.workspace;
+    const canManage = cfg.scopes.includes("manage");
     console.log(`Approved. Recorder key saved to .recorder/config.json (workspace: ${wsName}).`);
+    console.log(canManage
+      ? "This key can also MANAGE your centers — wire your agent with: npx demobite mcp"
+      : "This key records only. Managing by agent (MCP) comes with the Grow plan.");
     process.exit(0);
   }
   // denied / expired / consumed — terminal states. The wording matters:

package/skill/scripts/upload.mjs

@@ -167,15 +167,23 @@ await putS3(uploadUrl, "application/zip", zipPath, "ZIP");
 await putS3(previewUploadUrl, "video/mp4", cleanPath, "Preview");
 
 // ── open the in-app preview — the review happens THERE ─────────────────────
+// Batch etiquette (founder, 2026-08-11): when takes are stacked for a later
+// review sprint, auto-opening a tab per take is spam. `--no-open` (or
+// config.open_preview === false) stages silently — the queue pill and the
+// printed URL carry the message. Default stays open: for a single take the
+// opened page IS the consent moment.
 const pageUrl = new URL(previewUrl, base).toString();
 console.log(`Staged. Review and approve in the browser:\n  ${pageUrl}`);
 if (typeof pendingCount === "number" && pendingCount > 1 && queueUrl) {
   console.log(`${pendingCount} takes are now waiting for review: ${new URL(queueUrl, base).toString()}`);
 }
-try {
-  const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-  spawnSync(opener, [pageUrl], { stdio: "ignore" });
-} catch { /* printing the URL above is the fallback */ }
+const noOpen = process.argv.includes("--no-open") || cfg.open_preview === false;
+if (!noOpen) {
+  try {
+    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    spawnSync(opener, [pageUrl], { stdio: "ignore" });
+  } catch { /* printing the URL above is the fallback */ }
+}
 
 // ── poll while the human decides, then until the bite is READY ─────────────
 // LAW (founder 2026-08-08): never hand a human a studio link before the bite