diff --git a/README.md b/README.md
index b190f54..2aec262 100644
--- a/README.md
+++ b/README.md
@@ -74,9 +74,22 @@ For prerelease channels, tarball installs, authenticated GitHub Release installs
 
 This dogfood bundle uses VHS as the outer camera for real Codex and Claude interactive TUIs while each agent explores the `agent-tty` skill/CLI, drives `nvim --clean`, writes a file, and exports inner proof artifacts.
 
-| Codex                                                                                                                                              | Claude                                                                                                                                                |
-| -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [![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) |
+<table>
+  <tr>
+    <th width="50%">Codex</th>
+    <th width="50%">Claude</th>
+  </tr>
+  <tr>
+    <td>
+      <video src="https://github.com/user-attachments/assets/27cc3b9b-9b91-4cd9-a3a5-1bbb61c33e19" controls width="100%"></video>
+    </td>
+    <td>
+      <video src="https://github.com/user-attachments/assets/36221ef7-97c4-4b06-b673-21ac623a5f0a" controls width="100%"></video>
+    </td>
+  </tr>
+</table>
+
+GitHub renders these as inline H.264 MP4 video players. See [`VIDEO_PLAYBACK.md`](./dogfood/agent-uses-agent-tty/VIDEO_PLAYBACK.md) for the upload flow that produces the `user-attachments` URLs; the checked-in WebM proof files remain the canonical source of truth.
 
 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.
 
diff --git a/dogfood/agent-uses-agent-tty/README.md b/dogfood/agent-uses-agent-tty/README.md
index 243d4df..f56f690 100644
--- a/dogfood/agent-uses-agent-tty/README.md
+++ b/dogfood/agent-uses-agent-tty/README.md
@@ -3,9 +3,27 @@
 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.
 
-| 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)  |
-| Claude | [![Claude Hero Demo](./artifacts/claude-thumbnail.png)](./artifacts/claude-outer.webm) | [cast](./artifacts/claude-inner-nvim.cast), [WebM](./artifacts/claude-inner-nvim.webm) | [proof](./artifacts/claude-final-file-proof.txt) |
+The Outer Hero Demo column embeds the uploaded H.264 MP4 recordings as inline GitHub video players; see [VIDEO_PLAYBACK.md](./VIDEO_PLAYBACK.md) for the upload flow. The checked-in WebM files remain the canonical proof artifacts.
+
+<table>
+  <tr>
+    <th>Agent</th>
+    <th>Outer Hero Demo</th>
+    <th>Inner proof artifacts</th>
+    <th>File proof</th>
+  </tr>
+  <tr>
+    <td>Codex</td>
+    <td><video src="https://github.com/user-attachments/assets/27cc3b9b-9b91-4cd9-a3a5-1bbb61c33e19" controls width="320"></video></td>
+    <td><a href="./artifacts/codex-inner-nvim.cast">cast</a>, <a href="./artifacts/codex-inner-nvim.webm">WebM</a></td>
+    <td><a href="./artifacts/codex-final-file-proof.txt">proof</a></td>
+  </tr>
+  <tr>
+    <td>Claude</td>
+    <td><video src="https://github.com/user-attachments/assets/36221ef7-97c4-4b06-b673-21ac623a5f0a" controls width="320"></video></td>
+    <td><a href="./artifacts/claude-inner-nvim.cast">cast</a>, <a href="./artifacts/claude-inner-nvim.webm">WebM</a></td>
+    <td><a href="./artifacts/claude-final-file-proof.txt">proof</a></td>
+  </tr>
+</table>
 
 See [promoted-run-summary.md](./promoted-run-summary.md) for the regeneration summary.
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..af84857
--- /dev/null
+++ b/dogfood/agent-uses-agent-tty/VIDEO_PLAYBACK.md
@@ -0,0 +1,104 @@
+# Hero Demo GitHub video playback
+
+The canonical Hero Demo recordings stay checked in as WebM proof artifacts, but
+README-facing playback uses GitHub-uploaded H.264 MP4 attachments embedded as
+inline `<video>` players.
+
+## Why this shape
+
+GitHub serves `user-attachments` assets only when they are embedded inline in
+rendered Markdown (it rewrites them to signed `private-user-images` URLs that
+anonymous visitors can stream). Two things follow, both verified against logged-out
+GitHub:
+
+1. **A thumbnail _linked_ to a `user-attachments` URL is broken for the public.**
+   `https://github.com/user-attachments/assets/<uuid>` returns `404` on direct
+   navigation, so `[![thumb](png)](asset-url)` lands anonymous visitors on a 404.
+   Use an inline `<video>` element instead.
+2. **GitHub strips the `<video poster>` attribute**, so a curated poster image
+   cannot be supplied as an attribute. Instead the upload MP4 holds the curated
+   thumbnail as its opening frames, so the player's natural first-frame still
+   shows the end-state proof rather than a blank startup terminal.
+
+The MP4 copies are derived playback assets, not canonical proof. They live under
+`.debug/video-upload/` (git-ignored); the checked-in `*-outer.webm` files remain
+the source of truth.
+
+## 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`. For each agent it
+prepends ~0.3s of `artifacts/<agent>-thumbnail.png` as the opening frames, encodes
+H.264 MP4, 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.5 MB       |
+| Claude | `.debug/video-upload/claude-outer-h264.mp4` | H.264 / `yuv420p` | 1600x900            | ~3.4 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 `user-attachments` uploads:
+the endpoint authenticates with a browser `user_session` cookie, not a `gh` OAuth
+token. Two working routes:
+
+- **CLI (`gh-image`).** The [`drogers0/gh-image`](https://github.com/drogers0/gh-image)
+  extension uploads via the same internal endpoints, reading your logged-in browser
+  `user_session` cookie (treat that cookie like a password):
+
+  ```bash
+  gh extension install drogers0/gh-image
+  gh image --repo coder/agent-tty .debug/video-upload/codex-outer-h264.mp4
+  gh image --repo coder/agent-tty .debug/video-upload/claude-outer-h264.mp4
+  ```
+
+  Copy only the bare `https://github.com/user-attachments/assets/...` URL from each
+  line (drop the `![](...)` Markdown wrapper).
+
+- **Manual.** Drag each MP4 into any GitHub Markdown text area (a draft issue or PR
+  comment) with write access to `coder/agent-tty`, wait for the `user-attachments`
+  URL, and copy it. The draft does not need to be submitted.
+
+## Apply the URLs
+
+```bash
+mise run demo:agent-uses-agent-tty:apply-video-urls -- \
+  --codex-url https://github.com/user-attachments/assets/REPLACE-CODEX \
+  --claude-url https://github.com/user-attachments/assets/REPLACE-CLAUDE
+```
+
+The task rewrites the `src` of the inline `<video>` elements (one per agent, in
+Codex/Claude order) in the root README and this bundle README, and refreshes the
+bundle manifest entry for `README.md`. Then verify:
+
+```bash
+npm run validate-bundle:canonical
+```
+
+## Verify in a logged-out browser
+
+This is the step that catches the failure modes above. Open the rendered README on
+the branch **while logged out of GitHub** and confirm each `<video>` plays:
+
+- `https://github.com/coder/agent-tty/blob/<branch>/README.md`
+
+Do not test by navigating directly to the `user-attachments/assets/<uuid>` URL — that
+returns 404 anonymously by design even when the inline player works. Confirm the
+embedded `<video>` element actually streams (it should show the curated thumbnail as
+its still, then play).
+
+## Fallback
+
+If GitHub attachment URLs are ever rejected for maintainability, use a GitHub Pages
+gallery with `<video controls>` and committed H.264 MP4 playback copies. Do not point
+README playback at committed repository videos as the primary 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..d2db7e4 100644
--- a/dogfood/agent-uses-agent-tty/manifest.json
+++ b/dogfood/agent-uses-agent-tty/manifest.json
@@ -3,7 +3,6 @@
   "title": "Agents use agent-tty: Codex and Claude Hero Demo",
   "description": "README-facing Hero Demo where VHS records real Codex and Claude TUIs while agent-tty produces inner proof artifacts.",
   "createdAt": "2026-05-21T15:55:52.138Z",
-  "scenario": "agent-uses-agent-tty-hero-demo",
   "result": "pass",
   "commands": [
     "mise run demo:agent-uses-agent-tty -- --agent both --runs 3 --record-seconds 180 --promote"
@@ -114,8 +113,14 @@
     {
       "path": "README.md",
       "description": "Hero Demo bundle README",
-      "sha256": "dac35e0a5702cd749f726428ececc4905183c89cb4b3580e666c39bcb444fc8b",
-      "bytes": 1406
+      "sha256": "5e884d11936bfc38343344b1dd95e4ebafb2b70f2a8e834fdb1fd97a900f6927",
+      "bytes": 1544
+    },
+    {
+      "path": "VIDEO_PLAYBACK.md",
+      "description": "GitHub video playback guidance for the Hero Demo",
+      "sha256": "e62744bd9dac50d97e99fb2d6377b5f09b8a8e1d4e64ada70ae537bb8c4d2f39",
+      "bytes": 4584
     },
     {
       "path": "reproduce.sh",
@@ -123,5 +128,6 @@
       "sha256": "92b69748b18cbb64b5d02c25cd98225e8cbc3f793b3d6fc7362d85d3aa8412a9",
       "bytes": 276
     }
-  ]
+  ],
+  "scenario": "agent-uses-agent-tty-hero-demo"
 }
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..162b784
--- /dev/null
+++ b/src/tools/hero-video-playback.ts
@@ -0,0 +1,290 @@
+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>;
+
+// GitHub strips the <video poster> attribute on render, so the curated
+// thumbnail cannot be supplied as a poster. Instead we hold the thumbnail as
+// the opening frames of the upload MP4: the video element's natural first-frame
+// still then shows the curated end-state proof rather than a blank terminal.
+const FRAME_WIDTH = 1600;
+const FRAME_HEIGHT = 900;
+const POSTER_HOLD_SECONDS = '0.3';
+const POSTER_FPS = 30;
+const POSTER_FILTER =
+  `[0:v]scale=${String(FRAME_WIDTH)}:${String(FRAME_HEIGHT)},setsar=1,fps=${String(POSTER_FPS)},format=yuv420p[intro];` +
+  `[1:v]scale=${String(FRAME_WIDTH)}:${String(FRAME_HEIGHT)},setsar=1,fps=${String(POSTER_FPS)},format=yuv420p[main];` +
+  `[intro][main]concat=n=2:v=1[v]`;
+
+// README-facing playback uses inline HTML <video> elements (one per agent, in
+// AGENTS order). Bare user-attachments URLs do not become players inside table
+// cells, and a thumbnail linked to a user-attachments URL 404s for anonymous
+// visitors, so the tables embed <video> tags whose src we rewrite here.
+const VIDEO_SRC_PATTERN = /(<video\b[^>]*\bsrc=")[^"]*(")/g;
+
+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}`,
+  );
+}
+
+/** Rewrites the src of each inline <video> tag, in AGENTS order. */
+export function replaceVideoSrcs(text: string, urls: AgentUrls): string {
+  const matches = text.match(VIDEO_SRC_PATTERN) ?? [];
+  invariant(
+    matches.length === AGENTS.length,
+    `expected ${String(AGENTS.length)} <video> src attributes, found ${String(matches.length)}`,
+  );
+  let index = 0;
+  return text.replace(
+    VIDEO_SRC_PATTERN,
+    (_match, prefix: string, suffix: string) => {
+      const agent = AGENTS[index];
+      index += 1;
+      invariant(agent !== undefined, 'video index out of range');
+      return `${prefix}${urls[agent]}${suffix}`;
+    },
+  );
+}
+
+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;
+}
+
+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 posterPath = join(bundleDir, 'artifacts', `${agent}-thumbnail.png`);
+    const outputPath = join(uploadDir, `${agent}-outer-h264.mp4`);
+    const probePath = join(uploadDir, `${agent}-outer-h264.ffprobe.json`);
+    await assertNonEmptyFile(inputPath);
+    await assertNonEmptyFile(posterPath);
+    run(toolCommand('HERO_VIDEO_FFMPEG', 'ffmpeg'), [
+      '-y',
+      '-loop',
+      '1',
+      '-t',
+      POSTER_HOLD_SECONDS,
+      '-i',
+      posterPath,
+      '-i',
+      inputPath,
+      '-an',
+      '-filter_complex',
+      POSTER_FILTER,
+      '-map',
+      '[v]',
+      '-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);
+  }
+
+  for (const path of [rootReadmePath, join(bundleDir, 'README.md')]) {
+    const text = await readFile(path, 'utf8');
+    await writeFile(path, replaceVideoSrcs(text, options.urls));
+  }
+  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;
+  }
+}