@foldspace_npm/harness 0.1.31 → 0.1.32

package/bin/record.mjs

@@ -0,0 +1,412 @@
+#!/usr/bin/env node
+// foldspace record - a short video of the agent working in the product, for
+// the human to share: an opening card ("Meet the <product> Product Agent"),
+// then one scene for each of the agent's key use cases, recorded live in the
+// test window (the question typed key by key in a fresh conversation, the
+// agent thinking, the answer arriving), a caption once each answer settles -
+// the capabilities it shows, the question, what the user gets - an optional
+// closing card, a small Foldspace logo over the scenes - in Foldspace's
+// colours, not the app's.
+//
+//   npx foldspace record [--scenes video/scenes.json] [--preset landscape|square]
+//                        [--no-end-card] [--from <recordDir>]
+//
+// The video shows real data from the signed-in account: nothing is masked
+// and nothing is uploaded. Whether to share it is the human's call.
+// No test mode: a recording never arms it, and refuses to run while attach
+// has it on (the panel would show its banner) - read from the daemon's log,
+// or from the page, which attach marks either way.
+//
+// --from makes the video again from an earlier recording, with the
+// capabilities and lines in the scenes file now - nothing is recorded,
+// the window is not touched.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { ATTACH_DAEMON_LOG_FILE, attachTestModeOn, liveDaemon, pageTestModeOn } from "../src/attach-daemon.mjs";
+import { withBadgeOff } from "../src/badge-auto.mjs";
+import { CdpPage, parseArgs, printJson } from "../src/cdp-client.mjs";
+import { findChrome } from "../src/chrome-binary.mjs";
+import { recordEvent } from "../src/session-events.mjs";
+import { resolveProjectDir } from "../src/upgrade.mjs";
+import {
+  PRESETS,
+  VideoError,
+  buildPlan,
+  checkRecordingMatches,
+  closeAllHeadless,
+  loadRecording,
+  needsChrome,
+  probeEncoder,
+  renderInChrome,
+} from "../src/video/compose.mjs";
+import { pruneRecordings, recordScene } from "../src/video/recorder.mjs";
+import { ensureVideoIgnored, validateScenes, videoBaseName } from "../src/video/scenes.mjs";
+import { TIMING } from "../src/video/timeline.mjs";
+
+const { flags } = parseArgs(process.argv.slice(2), ["scenes", "preset", "from"]);
+const projectDir = path.resolve(resolveProjectDir());
+const scenesFile = path.resolve(projectDir, String(flags.scenes || path.join("video", "scenes.json")));
+const preset = String(flags.preset || "landscape");
+const recordRoot = path.join(projectDir, ".foldspace-dev", "record");
+const startedAt = Date.now();
+
+let page = null;
+let finished = false;
+// Where the run is, for a stop half-way: what to put back, what is kept.
+const run = { phase: "checking", recordDir: null, recordingComplete: false };
+// What a stopped run must undo, newest last: the badge, the screencast.
+const undo = new Set();
+
+function finish(result, code) {
+  if (finished) return;
+  finished = true;
+  recordEvent(projectDir, "record", {
+    ok: Boolean(result.ok),
+    scenes: result.scenes?.length ?? null,
+    ...(result.ok ? {} : { code: result.code || "failed" }),
+  });
+  printJson(result);
+  page?.close();
+  process.exit(code);
+}
+
+// The main flow's way out, awaited so nothing after it runs. While a stop is
+// being handled, the stop's own report is the one that counts: whatever fails
+// here then (the hidden Chrome closing, say) fails because of the stop.
+function end(result, code) {
+  if (!run.stopping) finish(result, code);
+  return new Promise(() => {});
+}
+
+const progress = (line) => process.stderr.write(`record: ${line}\n`);
+const rel = (file) => path.relative(projectDir, file) || file;
+const fromAgain = (dir) =>
+  `The recording is kept: \`npx foldspace record --from ${rel(dir)}\` makes the video again without asking anything.`;
+
+// Stopped half-way - Ctrl-C, or the shell's timeout. A `finally` never runs
+// when the process is killed, so without this the pill and corner tag would
+// stay hidden for the rest of the session, and a hidden Chrome would keep
+// running. Put things back (briefly: each step gives up after 2 s), then say
+// what happened in the same JSON as always.
+function stop(signal) {
+  if (finished || run.stopping) return;
+  run.stopping = true;
+  const exitCode = signal === "SIGINT" ? 130 : signal === "SIGHUP" ? 129 : 143;
+  progress(`stopped (${signal}): putting the window back`);
+  const hardStop = setTimeout(() => process.exit(exitCode), 6000);
+  Promise.allSettled([...undo].reverse().map((step) => step()))
+    .then(() => closeAllHeadless())
+    .finally(() => {
+      clearTimeout(hardStop);
+      const kept = run.recordingComplete && run.recordDir;
+      finish(
+        {
+          ok: false,
+          code: "interrupted",
+          reason:
+            run.phase === "recording"
+              ? `Stopped (${signal}) while recording; the pill and corner tag are back. A recording takes a few minutes: run it with a 10-minute timeout.`
+              : run.phase === "composing" && kept
+                ? `Stopped (${signal}) while making the video. ${fromAgain(run.recordDir)}`
+                : `Stopped (${signal}) before anything was recorded.`,
+          ...(run.recordDir ? { recordDir: run.recordDir } : {}),
+        },
+        exitCode,
+      );
+    });
+}
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(signal, () => stop(signal));
+
+function readScenes() {
+  let raw;
+  try {
+    raw = fs.readFileSync(scenesFile, "utf8");
+  } catch {
+    finish(
+      {
+        ok: false,
+        code: "no_scenes",
+        reason: `No scenes file at ${path.relative(projectDir, scenesFile) || scenesFile}. Agree 4-5 scenes with the human and write it first (the share-a-video skill shows the shape).`,
+      },
+      1,
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    finish({ ok: false, code: "bad_scenes", reason: `${path.basename(scenesFile)} is not valid JSON: ${error.message}` }, 1);
+  }
+  const checked = validateScenes(parsed);
+  if (!checked.ok) {
+    finish({ ok: false, code: "bad_scenes", reason: `Fix ${path.basename(scenesFile)} first.`, errors: checked.errors }, 1);
+  }
+  return checked;
+}
+
+const askAgain = (scene) => `Prove the question with \`npx foldspace ask "${scene.question}"\`, then record again.`;
+
+const SCENE_REASONS = {
+  // As `ask` says it: while attach runs, its log knows why the panel is missing.
+  no_panel: () =>
+    liveDaemon(projectDir)
+      ? "No agent panel on this page while attach runs. Read the lines under the last [lifecycle] line in .foldspace-dev/attach-daemon.log, then record again."
+      : "No agent panel on this page. Run `npx foldspace attach --daemon`, follow what it says about the page, then record again.",
+  no_composer: () =>
+    "The agent panel is on the page but never showed a composer. Run `npx foldspace observe screenshot` and look at the page.",
+  not_sent: (scene) => `The question could not be typed into the panel's composer. ${askAgain(scene)}`,
+  no_reply: (scene) => `No reply within the 90 s a scene may take. ${askAgain(scene)}`,
+  not_settled: (scene) => `The answer did not finish within the 90 s a scene may take. ${askAgain(scene)}`,
+  no_frames: () =>
+    "Chrome sent almost no pictures of the page: the test window must stay open and in view - not minimized, not covered. Ask the human to leave it that way, then record again.",
+  hidden: () =>
+    "The test window was minimized or covered while recording, so part of the scene is missing. Ask the human to keep it where they can see it, then record again.",
+};
+
+const TEST_MODE_REASON =
+  "attach runs with --test-mode, so the panel shows its test-mode banner, and a video is recorded without test mode. " +
+  "The recording's conversations then appear in their Foldspace dashboard, next to their users' conversations: say so, and on their yes run `npx foldspace attach --stop`, " +
+  "then `npx foldspace attach --daemon` with the flags it ran with minus --test-mode, then record again. After the recording, attach again with --test-mode.";
+
+/** attach's daemon log says "Test:  on"; a foreground attach marks the page itself. */
+async function testModeOn(page) {
+  const daemon = liveDaemon(projectDir);
+  if (daemon) {
+    try {
+      const log = fs.readFileSync(daemon.logPath || path.join(projectDir, ".foldspace-dev", ATTACH_DAEMON_LOG_FILE), "utf8");
+      if (attachTestModeOn(log)) return true;
+    } catch {
+      // no log to read: the page still says
+    }
+  }
+  return pageTestModeOn(page);
+}
+
+function writeManifest(recordDir, manifest) {
+  fs.writeFileSync(path.join(recordDir, "record.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+async function record(config) {
+  page = await CdpPage.open({ projectDir, command: "record" });
+  if (await testModeOn(page)) await end({ ok: false, code: "test_mode", reason: TEST_MODE_REASON }, 1);
+  const agentApiName = page.info.target?.agentApiName;
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const recordDir = path.join(recordRoot, stamp);
+  fs.mkdirSync(recordDir, { recursive: true });
+  run.recordDir = recordDir;
+  run.phase = "recording";
+  // `complete` only once every scene's answer settled: --from refuses the rest.
+  const manifest = {
+    version: 2,
+    createdAt: new Date().toISOString(),
+    complete: false,
+    scenes: config.scenes.map((scene, index) => ({ n: index + 1, dir: `scene-${index + 1}`, question: scene.question })),
+  };
+  writeManifest(recordDir, manifest);
+
+  const reports = [];
+  let failed = null;
+  // Nothing of the harness in the video: no pill, no corner tag. Focus
+  // emulation keeps the page painting and taking keys as if it were in front,
+  // without ever bringing the window forward.
+  const unfocus = () => page?.send("Emulation.setFocusEmulationEnabled", { enabled: false }, { timeoutMs: 2000 }).catch(() => {});
+  const stopCapture = () => page?.send("Page.stopScreencast", {}, { timeoutMs: 2000 }).catch(() => {});
+  await withBadgeOff(
+    page,
+    async () => {
+      await page.send("Emulation.setFocusEmulationEnabled", { enabled: true }).catch(() => {});
+      undo.add(unfocus);
+      undo.add(stopCapture);
+      try {
+        for (const [index, scene] of config.scenes.entries()) {
+          progress(`scene ${index + 1} of ${config.scenes.length}: "${scene.question}"`);
+          const report = await recordScene(page, {
+            question: scene.question,
+            dir: path.join(recordDir, `scene-${index + 1}`),
+            agentApiName,
+          });
+          reports.push({ n: index + 1, ...report });
+          Object.assign(manifest.scenes[index], { ok: Boolean(report.ok), ...(report.ok ? {} : { reason: report.reason }) });
+          writeManifest(recordDir, manifest);
+          if (!report.ok) {
+            failed = { n: index + 1, scene, report };
+            break;
+          }
+        }
+      } finally {
+        await unfocus();
+        undo.delete(unfocus);
+        undo.delete(stopCapture);
+      }
+    },
+    // The badge's own restore, for a run stopped half-way.
+    { register: (restore) => undo.add(() => restore({ timeoutMs: 2000 })) },
+  );
+  undo.clear();
+  page.close();
+  page = null;
+  if (!failed) {
+    manifest.complete = true;
+    writeManifest(recordDir, manifest);
+    run.recordingComplete = true;
+  }
+  pruneRecordings(recordRoot, 3);
+
+  if (failed) {
+    const explain = SCENE_REASONS[failed.report.reason] || (() => failed.report.reason);
+    await end(
+      {
+        ok: false,
+        code: failed.report.reason,
+        reason: `Scene ${failed.n}: ${explain(failed.scene)}`,
+        question: failed.scene.question,
+        recordDir,
+        scenes: reports.map(sceneSummary),
+      },
+      1,
+    );
+  }
+  return { recordDir, reports };
+}
+
+function sceneSummary(report) {
+  return {
+    n: report.n,
+    question: report.question,
+    ok: Boolean(report.ok),
+    ...(report.reason ? { reason: report.reason } : {}),
+    newChat: report.newChat,
+    typedBy: report.typedBy,
+    recordedS: report.end != null ? Math.round(report.end / 100) / 10 : null,
+    frames: report.frames,
+  };
+}
+
+/** The last recorded picture of each scene: the answer as it ended. */
+function lastFrames(recording) {
+  return recording.scenes.map((scene) => {
+    const last = scene.frames[scene.frames.length - 1];
+    return last ? rel(path.join(recording.dir, scene.dir, last.file)) : null;
+  });
+}
+
+async function compose(config, recordDir, chromePath) {
+  const recording = loadRecording(recordDir);
+  const mismatch = checkRecordingMatches(recording, config);
+  if (mismatch) throw new VideoError("scenes_changed", `${mismatch} Run \`npx foldspace record\` without --from.`);
+  run.recordingComplete = true;
+  const endCard = config.endCard && !flags["no-end-card"];
+  const plan = buildPlan({ recording, config, preset, endCard });
+  let shown = -1;
+  const rendered = await renderInChrome({
+    plan,
+    recordDir,
+    chromePath,
+    onProgress: ({ frame, of }) => {
+      const percent = Math.floor((frame / of) * 10) * 10;
+      if (percent > shown) {
+        shown = percent;
+        progress(`making the video: ${percent}%`);
+      }
+    },
+  });
+  const outDir = path.join(projectDir, "video");
+  fs.mkdirSync(outDir, { recursive: true });
+  // The video holds real data: never saved with the code, in any project.
+  ensureVideoIgnored(outDir);
+  const base = `${videoBaseName(config.product)}${preset === "square" ? "-square" : ""}`;
+  const video = path.join(outDir, `${base}.mp4`);
+  const poster = path.join(outDir, `${base}.jpg`);
+  fs.writeFileSync(video, rendered.mp4);
+  if (rendered.poster) fs.writeFileSync(poster, rendered.poster);
+  return {
+    video,
+    poster: rendered.poster ? poster : null,
+    durationS: Math.round(plan.layout.totalS * 10) / 10,
+    sizeMB: Math.round((rendered.mp4.length / 1024 / 1024) * 10) / 10,
+    width: plan.width,
+    height: plan.height,
+    preset,
+    codec: rendered.done?.codec || null,
+    endCard,
+    logoSpot: rendered.done?.logo || null,
+    ...(plan.fit.overS > 0
+      ? {
+          note: `${Math.round(plan.fit.totalS)} s, longer than the ${TIMING.maxTotalS} s it should be at most, with the waits already shortened: drop a scene, or pick questions with shorter answers.`,
+        }
+      : {}),
+    sceneSeconds: plan.clips.filter((clip) => clip.kind === "scene").map((clip) => Math.round(clip.durationS * 10) / 10),
+    lastFrames: lastFrames(recording),
+  };
+}
+
+async function main() {
+  if (!PRESETS[preset]) {
+    await end({ ok: false, code: "bad_preset", reason: `Unknown --preset '${preset}': landscape or square.` }, 1);
+  }
+  const checked = readScenes();
+  const config = checked.value;
+  for (const warning of checked.warnings) progress(warning);
+
+  // Before minutes of recording: can this machine's Chrome make the video?
+  const chromePath = findChrome();
+  const probe = await probeEncoder({ chromePath });
+  if (!probe.ok) {
+    await end({ ok: false, code: probe.code, reason: probe.message || needsChrome(chromePath) }, 1);
+  }
+
+  let recordDir;
+  let reports = null;
+  if (flags.from) {
+    // As printed in the summary (from the project), or from where this runs.
+    const fromProject = path.resolve(projectDir, String(flags.from));
+    const fromHere = path.resolve(String(flags.from));
+    recordDir = fs.existsSync(fromProject) || !fs.existsSync(fromHere) ? fromProject : fromHere;
+    run.recordDir = recordDir;
+  } else {
+    ({ recordDir, reports } = await record(config));
+  }
+
+  run.phase = "composing";
+  progress("making the video in a hidden Chrome");
+  let made;
+  try {
+    made = await compose(config, recordDir, chromePath);
+  } catch (error) {
+    const code = error instanceof VideoError ? error.code : "compose_failed";
+    // A finished recording is never lost to a failure here: say how to remake it.
+    const said = code === "no_h264" ? needsChrome(chromePath) : String(error?.message || error);
+    await end(
+      {
+        ok: false,
+        code,
+        reason: run.recordingComplete ? `${said} ${fromAgain(recordDir)}` : said,
+        recordDir,
+      },
+      1,
+    );
+  }
+  const scenes = (reports ? reports.map(sceneSummary) : config.scenes.map((scene, index) => ({ n: index + 1, question: scene.question }))).map(
+    (scene, index) => ({ ...scene, inVideoS: made.sceneSeconds[index], lastFrame: made.lastFrames[index] }),
+  );
+  const { sceneSeconds: _sceneSeconds, lastFrames: _lastFrames, ...summary } = made;
+  await end(
+    {
+      ok: true,
+      ...summary,
+      scenes,
+      recordDir,
+      ms: Date.now() - startedAt,
+      next: [
+        "Read the poster and each scene's lastFrame: every answer complete, none an error or \"that action isn't available\". The human watches the video",
+        "Hand over the MP4 and the poster. Say plainly: it shows real data from their account, and whether to share it is their call",
+        `To change a scene's capabilities or line, or the end card: edit ${rel(scenesFile)}, then \`npx foldspace record --from ${rel(recordDir)}\``,
+      ],
+    },
+    0,
+  );
+}
+
+main().catch((error) => end({ ok: false, code: "failed", reason: String(error?.message || error) }, 1));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.31",
+  "version": "0.1.32",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {

package/src/attach-daemon.mjs

@@ -151,6 +151,24 @@ export async function waitForRegistration({
   );
 }
 
+/** attach prints "Test:  on" when it starts with --test-mode (and "Test:  off - ..." without). */
+export function attachTestModeOn(logText) {
+  return /^Test:\s+on\b/m.test(String(logText ?? ""));
+}
+
+// attach marks the page with the test mode it set, so a command can see it
+// even when attach runs in the foreground and keeps no daemon log.
+export const PAGE_TEST_MODE_KEY = "__FOLDSPACE_TEST_MODE__";
+
+/** Whether attach set test mode on this page; false when it cannot tell. */
+export async function pageTestModeOn(page) {
+  try {
+    return (await page.evaluate(`return window.${PAGE_TEST_MODE_KEY} === true;`, { timeoutMs: 5000 })) === true;
+  } catch {
+    return false;
+  }
+}
+
 export function liveDaemon(root, isAlive = isProcessAlive) {
   const state = readDaemonState(root);
   if (!state?.pid || !isAlive(state.pid)) return null;

package/src/badge-auto.mjs

@@ -17,9 +17,10 @@ export async function readBadge(page) {
   }
 }
 
-export async function writeBadge(page, payload) {
+export async function writeBadge(page, payload, { timeoutMs } = {}) {
   await page.evaluate(
     `sessionStorage.setItem(${JSON.stringify(BADGE_KEY)}, ${JSON.stringify(JSON.stringify(payload))}); return true;`,
+    timeoutMs ? { timeoutMs } : undefined,
   );
 }
 
@@ -40,3 +41,39 @@ export async function withWorkingBadge(page, action) {
     if (raised) await writeBadge(page, before ?? { state: "label" }).catch(() => {});
   }
 }
+
+/**
+ * Run `action` with nothing drawn - no pill, no corner tag - then restore what
+ * was there. For a recording: the video shows the product, not the harness.
+ * attach's badge script redraws within a second, so the wait lets it go.
+ * `register` receives the restore function as soon as the badge is down, so a
+ * run that is stopped half-way (Ctrl-C, a timeout) can put it back too: a
+ * `finally` never runs when the process is killed.
+ */
+export async function withBadgeOff(
+  page,
+  action,
+  { settleMs = 1200, wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), register } = {},
+) {
+  const before = await readBadge(page);
+  let restored = false;
+  const restore = async ({ timeoutMs } = {}) => {
+    if (restored) return;
+    restored = true;
+    await writeBadge(page, before ?? { state: "label" }, { timeoutMs }).catch(() => {});
+  };
+  let lowered = false;
+  try {
+    await writeBadge(page, { state: "off" });
+    lowered = true;
+    register?.(restore);
+    await wait(settleMs);
+  } catch {
+    // no page to write to: nothing is drawn either
+  }
+  try {
+    return await action();
+  } finally {
+    if (lowered) await restore();
+  }
+}

package/src/cdp-client.mjs

@@ -1,4 +1,5 @@
-// A small CDP page client for `observe`, `ask`, `badge` and `published`.
+// A small CDP page client for `observe`, `ask`, `badge`, `published` and
+// `record`.
 //
 // It is a second client on the test window and is safe to use while
 // `foldspace attach` is running: attach's claim on the debug port is about
@@ -178,6 +179,11 @@ export class CdpPage {
     this.#listeners.get(method).push(listener);
   }
 
+  off(method, listener) {
+    const listeners = this.#listeners.get(method) || [];
+    this.#listeners.set(method, listeners.filter((item) => item !== listener));
+  }
+
   /** Evaluate the body of an async function in the page; returns its JSON value. */
   async evaluate(body, { timeoutMs = 30000 } = {}) {
     const result = await this.send(

package/src/chrome-binary.mjs

@@ -0,0 +1,28 @@
+// Which Chrome to launch: CHROME_PATH, else the usual install places. Shared
+// by `inject` (the test window) and `record` (the hidden Chrome that makes the
+// video), so both use the same browser.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export function chromeCandidates(platform = os.platform(), env = process.env) {
+  if (platform === "darwin") {
+    return [
+      "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+      "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+      "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    ];
+  }
+  if (platform === "win32") {
+    // Installed for everyone (Program Files), or for this user only (LocalAppData).
+    return [env.PROGRAMFILES, env["PROGRAMFILES(X86)"], env.LOCALAPPDATA]
+      .filter(Boolean)
+      .map((root) => path.win32.join(root, "Google", "Chrome", "Application", "chrome.exe"));
+  }
+  return ["/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/chromium"];
+}
+
+export function findChrome({ env = process.env, platform = os.platform(), exists = fs.existsSync } = {}) {
+  return env.CHROME_PATH || chromeCandidates(platform, env).find((candidate) => exists(candidate)) || null;
+}

package/src/cli-help.mjs

@@ -2,6 +2,7 @@ const GROUPS = [
   ["start", "Start an actions project"],
   ["develop", "Build the portable artifact"],
   ["verify", "Verify against a live application"],
+  ["share", "Share what the agent does"],
   ["publish", "Publish explicitly"],
 ];
 

package/src/cli-registry.mjs

@@ -32,7 +32,7 @@ export const CLI_COMMANDS = Object.freeze([
       {
         name: "directory",
         required: "non-interactive",
-        description: "New project directory",
+        description: "Project directory: a new one, or one that holds nothing but files the system or an editor put there",
       },
     ],
     options: [
@@ -59,10 +59,10 @@ export const CLI_COMMANDS = Object.freeze([
     ],
     prerequisites: [
       "Node 20 or newer",
-      "A target directory that does not already exist",
+      "A target directory that does not exist yet, or holds nothing but .DS_Store, .localized, Icon\\r, ._*, Thumbs.db, desktop.ini, .mcp.json, .git/, .vscode/, .cursor/, .idea/ or .claude/ without settings.json, and is not the home directory, its Desktop, Documents or Downloads, the disk's root, a Claude Code Desktop no-folder session, or a Codex chat's folder (~/Documents/Codex and the folders directly in it)",
       "Non-interactive use requires directory, product ID, Agent Key, and app domain",
     ],
-    effects: ["Creates a new local project; never initializes Git"],
+    effects: ["Creates a local project in a new folder, or in place in one that holds nothing but files the system or an editor put there; never overwrites a file and never initializes Git"],
     next: [
       "npm install --ignore-scripts",
       "Before the first build, CLAUDE.md step 5 (\"Every session starts the same way\"): with a code project, its agent/ replaces the scaffold's",
@@ -107,6 +107,8 @@ export const CLI_COMMANDS = Object.freeze([
       "With --yes, writes the latest version into package.json (exact) and runs npm install --ignore-scripts",
       "Does not rebuild dist/index.js or publish anything",
       "--refresh-instructions copies CLAUDE.md to CLAUDE.md.bak then writes the stub",
+      "With --yes or --refresh-instructions, writes the harness's skills (share-a-video) into .claude/skills/ from the installed version, keeping a copy that differs as <file>.bak; other skills there are left alone",
+      "Any foldspace command writes a harness skill the project is missing, so the first upgrade from a harness older than the skill still gets it",
     ],
     next: [
       "If outdated, ask the human, then run npx foldspace upgrade --yes",
@@ -440,6 +442,54 @@ export const CLI_COMMANDS = Object.freeze([
       "To go back to the local build: npx foldspace attach --daemon",
     ],
   }),
+  Object.freeze({
+    name: "record",
+    entry: "record.mjs",
+    group: "share",
+    summary: "Record a short video of the agent's key use cases, answered in the test window, for the human to share",
+    usage:
+      "foldspace record [--scenes <file>] [--preset landscape|square] [--no-end-card] [--from <record-dir>]",
+    risk: "browser-session",
+    environment: "local-chrome",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR", "CDP_PORT", "CHROME_PATH"],
+    capabilities: ["browser.cdp", "page.evaluate", "browser.launch"],
+    positionals: [],
+    options: [
+      value("--scenes", "file", "The scenes and their captions: { product, scenes: [{ question, capabilities, line }] }", {
+        default: "video/scenes.json",
+      }),
+      value("--preset", "landscape|square", "1920x1080 or 1080x1080; either way the whole product stays in the frame", {
+        default: "landscape",
+        choices: ["landscape", "square"],
+      }),
+      flag("--no-end-card", "Leave out the closing card"),
+      value(
+        "--from",
+        "record-dir",
+        "Make the video again from an earlier recording, with the capabilities and lines in the scenes file now; records nothing",
+      ),
+    ],
+    prerequisites: [
+      "The test window from `npm run inject`, signed in, with the agent on the page: `npx foldspace attach --daemon` running, or after `npx foldspace published`",
+      "attach without --test-mode",
+      "Each question already proven with `npx foldspace ask`",
+      "Google Chrome, which makes the video (some Chromium builds cannot encode H.264)",
+    ],
+    effects: [
+      "Asks each question in a new conversation, typed key by key: real conversations, in their Foldspace dashboard",
+      "The video shows real data from the signed-in account; nothing is masked. Whether to share it is the human's call",
+      "Hides the pill and the corner tag while it records, and puts them back after - also when it is stopped (Ctrl-C, a timeout)",
+      "Runs for a few minutes: give it a 10-minute timeout",
+      "Records with Chrome's own screen capture (no screen-recording permission) into .foldspace-dev/record/, keeping the 3 latest finished recordings",
+      "Makes the video in a separate hidden Chrome; writes video/<product>-<date>.mp4 and a .jpg poster, and video/.gitignore so neither is saved with the code",
+      "Uploads nothing and posts nothing",
+    ],
+    next: [
+      "Read the poster and each scene's lastFrame: every answer complete, none an error. The human watches the video",
+      "Hand over the MP4 and the poster: say plainly it shows real data from their account, and that sharing it is their call",
+      "To change a scene's capabilities or line: edit the scenes file, then `npx foldspace record --from <recordDir>`",
+    ],
+  }),
   Object.freeze({
     name: "deploy",
     // Foldspace-internal: it uploads to Foldspace's own storage, which no