From d1e20c42737761a758affc508818751bc0e93ddd Mon Sep 17 00:00:00 2001
From: Thomas Kosiewski <tk@coder.com>
Date: Fri, 22 May 2026 10:10:30 +0000
Subject: [PATCH] docs: add hero demo video playback workflow

---
 README.md                                     |   2 +
 dogfood/agent-uses-agent-tty/README.md        |   2 +
 .../agent-uses-agent-tty/VIDEO_PLAYBACK.md    |  66 ++++
 dogfood/agent-uses-agent-tty/manifest.json    |  10 +-
 mise.lock                                     |   2 +-
 mise.toml                                     |  34 +-
 src/tools/canonicalBundleArtifacts.ts         |  72 ++++
 src/tools/hero-demo.ts                        |  67 +---
 src/tools/hero-video-playback.ts              | 312 ++++++++++++++++++
 9 files changed, 508 insertions(+), 59 deletions(-)
 create mode 100644 dogfood/agent-uses-agent-tty/VIDEO_PLAYBACK.md
 create mode 100644 src/tools/canonicalBundleArtifacts.ts
 create mode 100644 src/tools/hero-video-playback.ts

diff --git a/README.md b/README.md
index b190f54..e29dd96 100644
--- a/README.md
+++ b/README.md
@@ -78,6 +78,8 @@ This dogfood bundle uses VHS as the outer camera for real Codex and Claude inter
 | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [![Codex agent-tty demo](./dogfood/agent-uses-agent-tty/artifacts/codex-thumbnail.png)](./dogfood/agent-uses-agent-tty/artifacts/codex-outer.webm) | [![Claude agent-tty demo](./dogfood/agent-uses-agent-tty/artifacts/claude-thumbnail.png)](./dogfood/agent-uses-agent-tty/artifacts/claude-outer.webm) |
 
+GitHub may show these checked-in WebM proof files as raw downloads. See [`VIDEO_PLAYBACK.md`](./dogfood/agent-uses-agent-tty/VIDEO_PLAYBACK.md) for the upload-ready H.264 MP4 flow that turns the thumbnails into GitHub video-player links.
+
 See [`dogfood/agent-uses-agent-tty/`](./dogfood/agent-uses-agent-tty/) for the Hero Demo reproducer, outer transcripts, inner Neovim recordings, and final file proofs.
 
 ## Common Usage
diff --git a/dogfood/agent-uses-agent-tty/README.md b/dogfood/agent-uses-agent-tty/README.md
index 243d4df..dd0799f 100644
--- a/dogfood/agent-uses-agent-tty/README.md
+++ b/dogfood/agent-uses-agent-tty/README.md
@@ -3,6 +3,8 @@
 This bundle is the README-facing **Hero Demo** for real coding-agent TUIs using `agent-tty`.
 VHS records the outer Codex and Claude Code TUIs as the presentation layer. The product proof is the inner `agent-tty` artifact set produced while each real agent explores the skill and CLI, drives Neovim, and exports recordings.
 
+GitHub may show checked-in WebM files as raw downloads; see [VIDEO_PLAYBACK.md](./VIDEO_PLAYBACK.md) for the H.264 attachment flow used to turn these thumbnails into GitHub video-player links.
+
 | Agent  | Outer Hero Demo                                                                        | Inner proof artifacts                                                                  | File proof                                       |
 | ------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------ |
 | Codex  | [![Codex Hero Demo](./artifacts/codex-thumbnail.png)](./artifacts/codex-outer.webm)    | [cast](./artifacts/codex-inner-nvim.cast), [WebM](./artifacts/codex-inner-nvim.webm)   | [proof](./artifacts/codex-final-file-proof.txt)  |
diff --git a/dogfood/agent-uses-agent-tty/VIDEO_PLAYBACK.md b/dogfood/agent-uses-agent-tty/VIDEO_PLAYBACK.md
new file mode 100644
index 0000000..86ad234
--- /dev/null
+++ b/dogfood/agent-uses-agent-tty/VIDEO_PLAYBACK.md
@@ -0,0 +1,66 @@
+# Hero Demo GitHub video playback
+
+GitHub repository file pages may show checked-in video files as raw downloads instead of a player. The canonical Hero Demo recordings stay checked in as WebM proof artifacts, but README-facing playback should use GitHub-uploaded H.264 MP4 attachment URLs.
+
+## Current recommendation
+
+1. Keep these checked-in proof artifacts as the source of truth:
+   - `artifacts/codex-outer.webm`
+   - `artifacts/claude-outer.webm`
+2. Generate upload-only H.264 MP4 copies from those WebMs.
+3. Upload the MP4 copies through GitHub's Markdown attachment flow.
+4. Replace the README thumbnail link targets with the resulting `https://github.com/user-attachments/assets/...` URLs.
+
+The MP4 copies are derived playback assets, not canonical proof artifacts. They should live under `.debug/video-upload/` locally unless the project later chooses a Pages gallery or another committed-media route.
+
+## Prepare upload assets
+
+From the repository root:
+
+```bash
+mise run demo:agent-uses-agent-tty:upload-assets
+```
+
+The task uses the pinned `ffmpeg`/`ffprobe` from `mise.toml`, converts both outer WebMs to H.264 MP4 files, writes ffprobe metadata, and writes checksums under `.debug/video-upload/`.
+
+Expected constraints for the promoted 2026-05-21 recordings:
+
+| Agent  | Upload file                                 | Expected codec    | Expected dimensions | Expected size |
+| ------ | ------------------------------------------- | ----------------- | ------------------- | ------------- |
+| Codex  | `.debug/video-upload/codex-outer-h264.mp4`  | H.264 / `yuv420p` | 1600x900            | ~3.3 MB       |
+| Claude | `.debug/video-upload/claude-outer-h264.mp4` | H.264 / `yuv420p` | 1600x900            | ~3.0 MB       |
+
+Both expected sizes are below GitHub's 10 MB video attachment limit for free plans.
+
+## Upload through GitHub
+
+GitHub does not expose a supported PAT-backed API for creating `user-attachments` video URLs. Use the web Markdown editor flow:
+
+1. Open any GitHub Markdown text area with write access to `coder/agent-tty`:
+   - a draft issue body,
+   - a PR comment,
+   - or the web editor for a Markdown file.
+2. Drag `codex-outer-h264.mp4` into the text area and wait for GitHub to replace it with a `https://github.com/user-attachments/assets/...` URL.
+3. Drag `claude-outer-h264.mp4` into the text area and copy its URL too.
+4. The comment or draft does not need to be submitted if the URLs have been copied.
+5. Verify each copied URL opens a GitHub video player before editing the README.
+
+## README patch after upload
+
+Apply the copied attachment URLs with the helper task:
+
+```bash
+mise run demo:agent-uses-agent-tty:apply-video-urls -- \
+  --codex-url https://github.com/user-attachments/assets/REPLACE-CODEX-H264-MP4 \
+  --claude-url https://github.com/user-attachments/assets/REPLACE-CLAUDE-H264-MP4
+```
+
+The task updates the root README, the bundle README, and the bundle manifest entry for `README.md`. Verify the result with:
+
+```bash
+npm run validate-bundle:canonical
+```
+
+## Fallback
+
+If GitHub attachment URLs are rejected for maintainability, use a GitHub Pages gallery with `<video controls>` and committed H.264 MP4 playback copies. Do not point README thumbnails at committed repository videos as the primary playback path; GitHub may show those as raw downloads.
diff --git a/dogfood/agent-uses-agent-tty/manifest.json b/dogfood/agent-uses-agent-tty/manifest.json
index 91b1dcb..d25bafd 100644
--- a/dogfood/agent-uses-agent-tty/manifest.json
+++ b/dogfood/agent-uses-agent-tty/manifest.json
@@ -114,8 +114,14 @@
     {
       "path": "README.md",
       "description": "Hero Demo bundle README",
-      "sha256": "dac35e0a5702cd749f726428ececc4905183c89cb4b3580e666c39bcb444fc8b",
-      "bytes": 1406
+      "sha256": "d6e0d3741409d1dd677f5b6e8236548c8e82ba832e79161d14bcd40c12fb4cf5",
+      "bytes": 1600
+    },
+    {
+      "path": "VIDEO_PLAYBACK.md",
+      "description": "GitHub video playback guidance for the Hero Demo",
+      "sha256": "0c7447a0d8f77694048eb686e5313719925ceda37c083439200fc15ffd81865c",
+      "bytes": 3315
     },
     {
       "path": "reproduce.sh",
diff --git a/mise.lock b/mise.lock
index ba9db8b..a0452fc 100644
--- a/mise.lock
+++ b/mise.lock
@@ -1,4 +1,4 @@
-# @generated - this file is auto-generated by `mise lock` https://mise.jdx.dev/dev-tools/mise-lock.html
+# @generated - this file is auto-generated by `mise lock` https://mise.en.dev/dev-tools/mise-lock.html
 
 [[tools.actionlint]]
 version = "1.7.12"
diff --git a/mise.toml b/mise.toml
index 86b6380..d956576 100644
--- a/mise.toml
+++ b/mise.toml
@@ -2,7 +2,6 @@
 actionlint = "1.7.12"
 communique = "1.1.3"
 zizmor = "1.24.1"
-# Live-demo-only recorder tools are pinned inside src/tools/hero-demo.ts so ordinary CI stays credential- and recorder-tool-free.
 # CI installs [tools] with `mise install --locked`; update mise.lock whenever tool versions or supported CI platforms change.
 node = "26"
 python = "3"
@@ -37,7 +36,38 @@ run = "npm run smoke:install -- --skip-build"
 
 [tasks."demo:agent-uses-agent-tty"]
 description = "Regenerate the real-agent Hero Demo proof bundle"
-run = "npx tsx src/tools/hero-demo.ts"
+run = '''
+PATH="$(mise bin-paths vhs@0.11.0 ttyd@1.7.7 ffmpeg@8.1.1 | paste -sd: -):$PATH" \
+  npx tsx src/tools/hero-demo.ts
+'''
+tools.ffmpeg = "8.1.1"
+tools.vhs = "0.11.0"
+tools.ttyd = "1.7.7"
+
+[tasks."demo:agent-uses-agent-tty:upload-assets"]
+description = "Prepare H.264 MP4 upload assets for the Hero Demo"
+run = '''
+HERO_VIDEO_FFMPEG="$(mise which ffmpeg --tool ffmpeg@8.1.1)" \
+HERO_VIDEO_FFPROBE="$(mise which ffprobe --tool ffmpeg@8.1.1)" \
+  npx tsx src/tools/hero-video-playback.ts prepare-upload-assets
+'''
+tools.ffmpeg = "8.1.1"
+sources = [
+  "dogfood/agent-uses-agent-tty/artifacts/codex-outer.webm",
+  "dogfood/agent-uses-agent-tty/artifacts/claude-outer.webm",
+  "src/tools/hero-video-playback.ts",
+]
+outputs = ["dogfood/agent-uses-agent-tty/.debug/video-upload/*"]
+
+[tasks."demo:agent-uses-agent-tty:apply-video-urls"]
+description = "Apply GitHub user-attachment video URLs to the Hero Demo READMEs"
+run = "npx tsx src/tools/hero-video-playback.ts apply-video-urls"
+sources = [
+  "README.md",
+  "dogfood/agent-uses-agent-tty/README.md",
+  "dogfood/agent-uses-agent-tty/manifest.json",
+  "src/tools/hero-video-playback.ts",
+]
 
 [tasks.validate-bundles]
 description = "Validate canonical proof bundles against the canonical schema"
diff --git a/src/tools/canonicalBundleArtifacts.ts b/src/tools/canonicalBundleArtifacts.ts
new file mode 100644
index 0000000..1f518fd
--- /dev/null
+++ b/src/tools/canonicalBundleArtifacts.ts
@@ -0,0 +1,72 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+
+import type {
+  CanonicalBundleArtifact,
+  CanonicalBundleManifest,
+} from './bundleManifestSchema.js';
+import { CanonicalBundleManifestSchema } from './bundleManifestSchema.js';
+import {
+  readValidatedJsonFile,
+  writeValidatedJsonFile,
+} from '../storage/manifests.js';
+import { invariant } from '../util/assert.js';
+
+export async function sha256File(path: string): Promise<string> {
+  const hash = createHash('sha256');
+  await pipeline(createReadStream(path), hash);
+  return hash.digest('hex');
+}
+
+export async function canonicalBundleArtifactEntry(
+  bundleDir: string,
+  relativePath: string,
+  description: string,
+): Promise<CanonicalBundleArtifact> {
+  const fullPath = join(bundleDir, relativePath);
+  const stats = await stat(fullPath);
+  return {
+    path: relativePath,
+    description,
+    sha256: await sha256File(fullPath),
+    bytes: stats.size,
+  };
+}
+
+function validateCanonicalBundleManifest(
+  _path: string,
+  data: unknown,
+): CanonicalBundleManifest {
+  return CanonicalBundleManifestSchema.parse(data);
+}
+
+export async function readCanonicalBundleManifest(
+  path: string,
+): Promise<CanonicalBundleManifest> {
+  const manifest = await readValidatedJsonFile({
+    path,
+    pathLabel: 'canonical bundle manifest path',
+    allowMissing: false,
+    readErrorMessage: `Failed to read canonical bundle manifest at ${path}.`,
+    invalidJsonMessage: `Canonical bundle manifest contains invalid JSON at ${path}.`,
+    validate: validateCanonicalBundleManifest,
+  });
+  invariant(manifest !== null, 'canonical bundle manifest must exist');
+  return manifest;
+}
+
+export async function writeCanonicalBundleManifest(
+  path: string,
+  manifest: CanonicalBundleManifest,
+): Promise<void> {
+  await writeValidatedJsonFile({
+    path,
+    pathLabel: 'canonical bundle manifest path',
+    data: manifest,
+    writeErrorMessage: `Failed to write canonical bundle manifest at ${path}.`,
+    validate: validateCanonicalBundleManifest,
+  });
+}
diff --git a/src/tools/hero-demo.ts b/src/tools/hero-demo.ts
index d7fd324..7849ea9 100644
--- a/src/tools/hero-demo.ts
+++ b/src/tools/hero-demo.ts
@@ -21,13 +21,14 @@ import { basename, dirname, join, resolve } from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
-import type { CanonicalBundleArtifact } from './bundleManifestSchema.js';
 import { CanonicalBundleManifestSchema } from './bundleManifestSchema.js';
+import { canonicalBundleArtifactEntry } from './canonicalBundleArtifacts.js';
 import { invariant } from '../util/assert.js';
 import { isDirectExecution } from '../util/isDirectExecution.js';
 
 const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
 const DEFAULT_BUNDLE_DIR = join(REPO_ROOT, 'dogfood/agent-uses-agent-tty');
+const VIDEO_PLAYBACK_DOC = 'VIDEO_PLAYBACK.md';
 const DEFAULT_EXPECTED_TEXT =
   'agent-tty nested Neovim proof from a real coding agent.';
 const DEFAULT_RECORD_SECONDS = 3 * 60;
@@ -40,8 +41,6 @@ const OUTER_FONT_SIZE = 14;
 const CLAUDE_VISUAL_REDACTION_HEIGHT = Math.floor(OUTER_HEIGHT / 5);
 const CLAUDE_VISUAL_REDACTION_FILTER = `drawbox=x=0:y=0:w=iw:h=${String(CLAUDE_VISUAL_REDACTION_HEIGHT)}:color=black:t=fill`;
 
-const DEMO_TOOL_SPECS = ['vhs@0.11.0', 'ttyd@1.7.7', 'ffmpeg@8.1.1'];
-
 type AgentName = (typeof AGENTS)[number];
 
 export interface HeroDemoOptions {
@@ -447,33 +446,10 @@ async function assertNonEmpty(path: string): Promise<void> {
   );
 }
 
-let cachedDemoToolPathPrefix: string | undefined;
-
-function demoToolPathPrefix(): string {
-  if (cachedDemoToolPathPrefix === undefined) {
-    run('mise', ['install', ...DEMO_TOOL_SPECS]);
-  }
-  cachedDemoToolPathPrefix ??= run('mise', ['bin-paths', ...DEMO_TOOL_SPECS])
-    .trim()
-    .split('\n')
-    .filter(Boolean)
-    .join(':');
-  invariant(cachedDemoToolPathPrefix !== '', 'demo tool PATH is empty');
-  return cachedDemoToolPathPrefix;
-}
-
-function demoToolEnv(): NodeJS.ProcessEnv {
-  return {
-    ...process.env,
-    PATH: `${demoToolPathPrefix()}:${process.env.PATH ?? ''}`,
-  };
-}
-
 function runDemoTool(command: string, args: string[], cwd = REPO_ROOT): string {
   return execFileSync(command, args, {
     cwd,
     encoding: 'utf8',
-    env: demoToolEnv(),
     stdio: ['ignore', 'pipe', 'pipe'],
   });
 }
@@ -677,7 +653,6 @@ async function runOne(
     runDir,
     vhsLog,
     (options.recordSeconds + RECORD_TIMEOUT_BUFFER_SECONDS) * 1000,
-    demoToolEnv(),
   );
   ensureThumbnail(runDir);
 
@@ -765,29 +740,8 @@ function sha256Text(text: string): string {
   return createHash('sha256').update(text).digest('hex');
 }
 
-async function sha256File(path: string): Promise<string> {
-  return createHash('sha256')
-    .update(await readFile(path))
-    .digest('hex');
-}
-
-async function artifactEntry(
-  bundleDir: string,
-  relativePath: string,
-  description: string,
-): Promise<CanonicalBundleArtifact> {
-  const fullPath = join(bundleDir, relativePath);
-  const stats = await stat(fullPath);
-  return {
-    path: relativePath,
-    description,
-    sha256: await sha256File(fullPath),
-    bytes: stats.size,
-  };
-}
-
 async function cleanBundle(bundleDir: string): Promise<void> {
-  const keep = new Set(['.gitignore']);
+  const keep = new Set(['.gitignore', VIDEO_PLAYBACK_DOC]);
   for (const entry of await readdir(bundleDir, { withFileTypes: true })) {
     if (keep.has(entry.name)) {
       continue;
@@ -901,6 +855,10 @@ async function promote(
     path: 'README.md',
     description: 'Hero Demo bundle README',
   });
+  promotedPaths.push({
+    path: VIDEO_PLAYBACK_DOC,
+    description: 'GitHub video playback guidance for the Hero Demo',
+  });
 
   const reproducePath = join(options.bundleDir, 'reproduce.sh');
   await writeExecutable(reproducePath, renderReproduce(options));
@@ -914,7 +872,7 @@ async function promote(
   const manifestArtifacts = [];
   for (const promoted of promotedPaths) {
     manifestArtifacts.push(
-      await artifactEntry(
+      await canonicalBundleArtifactEntry(
         options.bundleDir,
         promoted.path,
         promoted.description,
@@ -973,11 +931,10 @@ function safeToolVersion(
 }
 
 function collectToolVersions(): Array<[string, string]> {
-  const demoEnv = demoToolEnv();
   return [
-    ['vhs', safeToolVersion('vhs', ['--version'], demoEnv)],
-    ['ttyd', safeToolVersion('ttyd', ['--version'], demoEnv)],
-    ['ffmpeg', safeToolVersion('ffmpeg', ['-version'], demoEnv)],
+    ['vhs', safeToolVersion('vhs', ['--version'])],
+    ['ttyd', safeToolVersion('ttyd', ['--version'])],
+    ['ffmpeg', safeToolVersion('ffmpeg', ['-version'])],
     ['codex', safeToolVersion('codex', ['--version'])],
     ['claude', safeToolVersion('claude', ['--version'])],
   ];
@@ -1026,6 +983,8 @@ function renderReadme(): string {
 This bundle is the README-facing **Hero Demo** for real coding-agent TUIs using \`agent-tty\`.
 VHS records the outer Codex and Claude Code TUIs as the presentation layer. The product proof is the inner \`agent-tty\` artifact set produced while each real agent explores the skill and CLI, drives Neovim, and exports recordings.
 
+GitHub may show checked-in WebM files as raw downloads; see [${VIDEO_PLAYBACK_DOC}](./${VIDEO_PLAYBACK_DOC}) for the H.264 attachment flow used to turn these thumbnails into GitHub video-player links.
+
 | Agent | Outer Hero Demo | Inner proof artifacts | File proof |
 | --- | --- | --- | --- |
 | Codex | [![Codex Hero Demo](./artifacts/codex-thumbnail.png)](./artifacts/codex-outer.webm) | [cast](./artifacts/codex-inner-nvim.cast), [WebM](./artifacts/codex-inner-nvim.webm) | [proof](./artifacts/codex-final-file-proof.txt) |
diff --git a/src/tools/hero-video-playback.ts b/src/tools/hero-video-playback.ts
new file mode 100644
index 0000000..cec773f
--- /dev/null
+++ b/src/tools/hero-video-playback.ts
@@ -0,0 +1,312 @@
+import { execFileSync } from 'node:child_process';
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import {
+  canonicalBundleArtifactEntry,
+  readCanonicalBundleManifest,
+  sha256File,
+  writeCanonicalBundleManifest,
+} from './canonicalBundleArtifacts.js';
+import { invariant } from '../util/assert.js';
+import { isDirectExecution } from '../util/isDirectExecution.js';
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const DEFAULT_BUNDLE_DIR = join(REPO_ROOT, 'dogfood/agent-uses-agent-tty');
+const DEFAULT_ROOT_README = join(REPO_ROOT, 'README.md');
+const USER_ATTACHMENT_PREFIX = 'https://github.com/user-attachments/assets/';
+const AGENTS = ['codex', 'claude'] as const;
+
+type AgentName = (typeof AGENTS)[number];
+type AgentUrls = Record<AgentName, string>;
+
+const README_LINKS: Record<
+  AgentName,
+  {
+    rootAlt: string;
+    rootThumbnail: string;
+    bundleAlt: string;
+    bundleThumbnail: string;
+  }
+> = {
+  codex: {
+    rootAlt: 'Codex agent-tty demo',
+    rootThumbnail:
+      './dogfood/agent-uses-agent-tty/artifacts/codex-thumbnail.png',
+    bundleAlt: 'Codex Hero Demo',
+    bundleThumbnail: './artifacts/codex-thumbnail.png',
+  },
+  claude: {
+    rootAlt: 'Claude agent-tty demo',
+    rootThumbnail:
+      './dogfood/agent-uses-agent-tty/artifacts/claude-thumbnail.png',
+    bundleAlt: 'Claude Hero Demo',
+    bundleThumbnail: './artifacts/claude-thumbnail.png',
+  },
+};
+
+export interface PrepareHeroVideoUploadAssetsOptions {
+  bundleDir?: string;
+  uploadDir?: string;
+}
+
+export interface ApplyHeroVideoUrlsOptions {
+  rootReadmePath?: string;
+  bundleDir?: string;
+  urls: AgentUrls;
+}
+
+function toolCommand(envName: string, fallback: string): string {
+  return process.env[envName] ?? fallback;
+}
+
+function run(command: string, args: string[], cwd = REPO_ROOT): string {
+  return execFileSync(command, args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+async function assertNonEmptyFile(path: string): Promise<void> {
+  const stats = await stat(path);
+  invariant(
+    stats.isFile() && stats.size > 0,
+    `expected non-empty file: ${path}`,
+  );
+}
+
+function assertAttachmentUrl(url: string, agent: AgentName): void {
+  invariant(
+    url.startsWith(USER_ATTACHMENT_PREFIX),
+    `${agent} URL must start with ${USER_ATTACHMENT_PREFIX}`,
+  );
+}
+
+function replaceOne(
+  text: string,
+  pattern: RegExp,
+  replacement: string,
+): string {
+  const globalPattern = new RegExp(pattern.source, `${pattern.flags}g`);
+  const matches = text.match(globalPattern) ?? [];
+  invariant(matches.length === 1, `expected one match for ${pattern}`);
+  return text.replace(pattern, replacement);
+}
+
+function readFlag(args: string[], name: string): string | undefined {
+  const index = args.indexOf(name);
+  if (index < 0) {
+    return undefined;
+  }
+  const value = args[index + 1];
+  invariant(
+    value !== undefined && !value.startsWith('--'),
+    `missing value for ${name}`,
+  );
+  args.splice(index, 2);
+  return value;
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function updateReadmeLink(
+  text: string,
+  alt: string,
+  thumbnailPath: string,
+  url: string,
+): string {
+  const pattern = new RegExp(
+    `(\\[!\\[${escapeRegExp(alt)}\\]\\(${escapeRegExp(thumbnailPath)}\\)\\])\\([^)]*\\)`,
+  );
+  return replaceOne(text, pattern, `$1(${url})`);
+}
+
+async function updateManifest(
+  bundleDir: string,
+  paths: string[],
+): Promise<void> {
+  const manifestPath = resolve(bundleDir, 'manifest.json');
+  const manifest = await readCanonicalBundleManifest(manifestPath);
+  for (const path of paths) {
+    const index = manifest.artifacts.findIndex(
+      (artifact) => artifact.path === path,
+    );
+    invariant(index >= 0, `manifest entry not found: ${path}`);
+    const current = manifest.artifacts[index];
+    invariant(current !== undefined, `manifest entry not found: ${path}`);
+    manifest.artifacts[index] = await canonicalBundleArtifactEntry(
+      bundleDir,
+      path,
+      current.description,
+    );
+  }
+  await writeCanonicalBundleManifest(manifestPath, manifest);
+}
+
+export async function prepareHeroVideoUploadAssets(
+  options: PrepareHeroVideoUploadAssetsOptions = {},
+): Promise<void> {
+  const bundleDir = options.bundleDir ?? DEFAULT_BUNDLE_DIR;
+  const uploadDir = options.uploadDir ?? join(bundleDir, '.debug/video-upload');
+  await rm(uploadDir, { recursive: true, force: true });
+  await mkdir(uploadDir, { recursive: true });
+
+  const checksumLines: string[] = [];
+  for (const agent of AGENTS) {
+    const inputPath = join(bundleDir, 'artifacts', `${agent}-outer.webm`);
+    const outputPath = join(uploadDir, `${agent}-outer-h264.mp4`);
+    const probePath = join(uploadDir, `${agent}-outer-h264.ffprobe.json`);
+    await assertNonEmptyFile(inputPath);
+    run(toolCommand('HERO_VIDEO_FFMPEG', 'ffmpeg'), [
+      '-y',
+      '-i',
+      inputPath,
+      '-an',
+      '-c:v',
+      'libx264',
+      '-pix_fmt',
+      'yuv420p',
+      '-preset',
+      'medium',
+      '-crf',
+      '28',
+      '-movflags',
+      '+faststart',
+      outputPath,
+    ]);
+    await assertNonEmptyFile(outputPath);
+    const probeJson = run(toolCommand('HERO_VIDEO_FFPROBE', 'ffprobe'), [
+      '-v',
+      'error',
+      '-select_streams',
+      'v:0',
+      '-show_entries',
+      'stream=codec_name,pix_fmt,width,height,duration',
+      '-show_entries',
+      'format=size,duration,format_name',
+      '-of',
+      'json',
+      outputPath,
+    ]);
+    await writeFile(probePath, probeJson);
+    const repoRelativeOutput = relative(REPO_ROOT, outputPath);
+    checksumLines.push(
+      `${await sha256File(outputPath)}  ${repoRelativeOutput}`,
+    );
+  }
+  await writeFile(
+    join(uploadDir, 'SHA256SUMS'),
+    `${checksumLines.join('\n')}\n`,
+  );
+
+  process.stdout.write(
+    `Prepared upload assets in ${relative(REPO_ROOT, uploadDir)}\n`,
+  );
+}
+
+export async function applyHeroVideoUrls(
+  options: ApplyHeroVideoUrlsOptions,
+): Promise<void> {
+  const rootReadmePath = options.rootReadmePath ?? DEFAULT_ROOT_README;
+  const bundleDir = options.bundleDir ?? DEFAULT_BUNDLE_DIR;
+  for (const agent of AGENTS) {
+    assertAttachmentUrl(options.urls[agent], agent);
+  }
+
+  let rootReadme = await readFile(rootReadmePath, 'utf8');
+  for (const agent of AGENTS) {
+    const link = README_LINKS[agent];
+    rootReadme = updateReadmeLink(
+      rootReadme,
+      link.rootAlt,
+      link.rootThumbnail,
+      options.urls[agent],
+    );
+  }
+  await writeFile(rootReadmePath, rootReadme);
+
+  const bundleReadmePath = join(bundleDir, 'README.md');
+  let bundleReadme = await readFile(bundleReadmePath, 'utf8');
+  for (const agent of AGENTS) {
+    const link = README_LINKS[agent];
+    bundleReadme = updateReadmeLink(
+      bundleReadme,
+      link.bundleAlt,
+      link.bundleThumbnail,
+      options.urls[agent],
+    );
+  }
+  await writeFile(bundleReadmePath, bundleReadme);
+  await updateManifest(bundleDir, ['README.md']);
+
+  process.stdout.write('Applied Hero Demo video URLs.\n');
+}
+
+function usage(): string {
+  return [
+    'Usage:',
+    '  hero-video-playback prepare-upload-assets [--bundle-dir DIR] [--upload-dir DIR]',
+    '  hero-video-playback apply-video-urls --codex-url URL --claude-url URL [--bundle-dir DIR] [--root-readme PATH]',
+    '',
+  ].join('\n');
+}
+
+async function main(args: string[]): Promise<void> {
+  const command = args.shift();
+  if (command === '--help' || command === 'help') {
+    process.stdout.write(usage());
+    return;
+  }
+  if (command === 'prepare-upload-assets') {
+    const bundleDir = readFlag(args, '--bundle-dir');
+    const uploadDir = readFlag(args, '--upload-dir');
+    invariant(args.length === 0, `unexpected arguments: ${args.join(' ')}`);
+    const options: PrepareHeroVideoUploadAssetsOptions = {};
+    if (bundleDir !== undefined) {
+      options.bundleDir = bundleDir;
+    }
+    if (uploadDir !== undefined) {
+      options.uploadDir = uploadDir;
+    }
+    await prepareHeroVideoUploadAssets(options);
+    return;
+  }
+  if (command === 'apply-video-urls') {
+    const codexUrl = readFlag(args, '--codex-url');
+    const claudeUrl = readFlag(args, '--claude-url');
+    const bundleDir = readFlag(args, '--bundle-dir');
+    const rootReadmePath = readFlag(args, '--root-readme');
+    invariant(codexUrl !== undefined, 'missing --codex-url');
+    invariant(claudeUrl !== undefined, 'missing --claude-url');
+    invariant(args.length === 0, `unexpected arguments: ${args.join(' ')}`);
+    const options: ApplyHeroVideoUrlsOptions = {
+      urls: { codex: codexUrl, claude: claudeUrl },
+    };
+    if (rootReadmePath !== undefined) {
+      options.rootReadmePath = rootReadmePath;
+    }
+    if (bundleDir !== undefined) {
+      options.bundleDir = bundleDir;
+    }
+    await applyHeroVideoUrls(options);
+    return;
+  }
+  throw new Error(
+    `${command === undefined ? 'missing command' : `unknown command: ${command}`}\n${usage()}`,
+  );
+}
+
+if (isDirectExecution(import.meta.url)) {
+  try {
+    await main(process.argv.slice(2));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+  }
+}