Move binary media files (mp4/gif) out of Git — broken LFS state and 326MB repo bloat

[rickstaa]

Problem

Cloning the repo produces this warning:

Encountered 16 files that should have been pointers, but weren't:
    snippets/assets/domain/00_HOME/Eric Shreck Gif.gif
    snippets/assets/domain/04_GATEWAYS/test-video.mp4
    snippets/assets/domain/10_PRODUCTS/Embody/Videos/arealiensreal.mp4
    snippets/assets/media/gifs/daydream.gif
    snippets/assets/media/icons/home-house.gif
    snippets/assets/media/icons/smart-house.gif
    snippets/assets/media/videos/Embody.mp4
    snippets/assets/media/videos/HeroBackground.mp4
    snippets/assets/media/videos/LivepeerStudio.mp4
    snippets/assets/media/videos/daydream.mp4
    snippets/assets/media/videos/frameworks.mp4
    snippets/assets/media/videos/livepeer-founders-post.mp4
    snippets/assets/media/videos/nytv.live.mp4
    snippets/assets/media/videos/nytvlivepromo.mp4
    snippets/assets/media/videos/streamplace.mp4
    v1/images/ai/cool-cat-hat-moving.gif

These binary files are committed directly as Git blobs rather than LFS pointers, bloating the repo to ~497MB on clone.

Current state

• .gitattributes declares *.gif and *.mp4 as LFS-tracked, but no files are actually managed by LFS
• History shows LFS was enabled, then reverted (c71a41e9), then .gitattributes was restored (e3ab83a9) — but the actual files were never migrated
• Total binary media in the repo: ~326MB across snippets/assets/media/ (200MB) and snippets/assets/domain/ (126MB)
• 136 MDX files reference local media paths; 14 use raw GitHub URLs pointing at a docs-v2-assets branch

Proposal

Git is not the right place to store large video and GIF files. Options to consider:

1. Cloud storage + CDN (Cloudflare R2, S3+CloudFront, or Livepeer's own infra) — best long-term solution for video assets in a docs site
2. Mintlify-native asset hosting — if supported by the framework
3. Dedicated assets branch — a docs-v2-assets branch already exists with some precedent
4. Fix Git LFS properly — run git lfs migrate import and force-push; simplest but Git LFS has bandwidth/storage costs and adds clone complexity

Whichever path is chosen, the migration should:

• Update all 136+ local media references in MDX files
• Remove the binaries from Git history (via git filter-repo or BFG) to actually reduce repo size
• Add contribution guidelines for future media assets
• Add lazy-loading defaults for media components (already flagged in tasks/optimise-performance.mdx)

Related

• tasks/optimise-performance.mdx — P0 actions include replacing GIF heroes and hosting media through CDN-only paths
• Branch codex/99999-asset-migrate-3b — appears to be related migration work

[DeveloperAlly]

Resolved. 19 large assets migrated to docs-v2-assets branch, binaries removed from working tree, and sync-large-assets workflow repaired. See commits: 66609ed, f1ef480, 6db4bf9, 4d44488, 6b377ab.