chore(docs): migrate docs/images/ media to static.heygen.ai CDN

[jrusso1020]

What

Move all preview mp4/png/gif assets under docs/images/ out of the repo and serve them from the HeyGen public CDN:

docs/images/**                → https://static.heygen.ai/hyperframes-oss/docs/images/**

Backed by s3://heygen-public/hyperframes-oss/docs/images/ (CloudFront-fronted, long-lived cache headers).

Why

Addresses part of #300 (npx skills add heygen-com/hyperframes times out at 60s against this 554MB repo).

• Drops ~49MB from the working tree and every future Mintlify checkout.
• docs/images/ is pure generated output — previews are rebuilt from registry/ sources by scripts/generate-{catalog,template}-previews.ts. Committing them was always hygiene debt.
• Git-LFS would be the wrong tool here: Mintlify rebuilds pull LFS on every deploy, burning LFS bandwidth on an OSS public repo. A CDN backed by our own S3 bucket has bounded cost and already-provisioned infra.

The remaining size contribution to the reported 554MB is the producer regression snapshots in packages/producer/tests/*/output/output.mp4 — those are already LFS-tracked (see .gitattributes). The real reason skills add blows the 60s timeout is LFS smudge during git clone, which is a skills CLI fix (pass GIT_LFS_SKIP_SMUDGE=1), not a repo fix. Follow-up PR to be opened against vercel-labs/skills.

How

1. Synced docs/images/ → s3://heygen-public/hyperframes-oss/docs/images/ with Cache-Control: public, max-age=31536000, immutable.
2. Rewrote 90+ references across 44 MDX files, TemplateCard.jsx, and catalog-index.json from /images/... to absolute CDN URLs.
3. Updated README.md img src to the CDN URL (renders correctly on the GitHub repo page).
4. Added docs/images/ to .gitignore with a comment pointing at the regenerate/upload workflow.
5. Added scripts/upload-docs-images.sh (syncs docs/images/ → S3 with the engineering-767398024897 profile) and wired it up as bun run upload:docs-images.
6. Updated generator script docstrings to point at the upload step.
7. Deleted the 103 tracked files under docs/images/.

Maintainer workflow after this lands

When adding/updating a catalog block, component, or template preview:

bun run generate:catalog-previews --only <name>    # or generate:previews for templates
bun run upload:docs-images
# commit the registry/ + docs/ MDX changes

External contributors can open PRs with registry + MDX changes; a maintainer runs the generator + upload before merging.

Test plan

• curl -sI https://static.heygen.ai/hyperframes-oss/docs/images/readme-demo.mp4 → 200, video/mp4
• Same for a catalog mp4, a template png, and the gif — all 200 with correct content-types
• grep -rn '/images/' on docs/ and README.md — no bare /images/ references remain; every hit is the full CDN URL
• bunx oxfmt --check + bunx oxlint pass on modified files
• Mintlify PR preview renders videos/images correctly (will verify on this PR)
• README.md preview on GitHub shows the hero demo gif (will verify after push)

Notes for reviewers

• The CDN files are already live — this PR only updates references and deletes the tree, so rolling back is a simple revert.
• History rewrite (git filter-repo) intentionally not done here. .git stays at ~328MB, but git clone --depth 1 (what the skills CLI uses) skips history and downloads a much smaller pack. If we later want to rewrite, it's a one-time operation we can coordinate.
• Once the upstream skills CLI GIT_LFS_SKIP_SMUDGE=1 fix lands, npx skills add heygen-com/hyperframes should complete well under the 60s timeout.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
hyperframes	🟢 Ready	View Preview	Apr 17, 2026, 6:08 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.