diff --git a/bun.lock b/bun.lock
index e86c75c0379..064381c2c2f 100644
--- a/bun.lock
+++ b/bun.lock
@@ -12,6 +12,7 @@
         "@clack/prompts": "1.7.0",
         "@octokit/rest": "^21.0.0",
         "@types/opentype.js": "1.3.10",
+        "@vercel/blob": "2.6.1",
         "@vercel/og": "0.6.8",
         "chalk": "5.6.2",
         "glob": "13.0.0",
@@ -2095,9 +2096,15 @@
 
     "@upsetjs/venn.js": ["@upsetjs/venn.js@2.0.0", "", { "optionalDependencies": { "d3-selection": "^3.0.0", "d3-transition": "^3.0.1" } }, "sha512-WbBhLrooyePuQ1VZxrJjtLvTc4NVfpOyKx0sKqioq9bX1C1m7Jgykkn8gLrtwumBioXIqam8DLxp88Adbue6Hw=="],
 
+    "@vercel/blob": ["@vercel/blob@2.6.1", "", { "dependencies": { "@vercel/oidc": "^3.6.1", "async-retry": "^1.3.3", "is-buffer": "^2.0.5", "is-node-process": "^1.2.0", "throttleit": "^2.1.0", "undici": "^6.23.0" } }, "sha512-KTJytw85j1XQBxjN5d6UXI7fIWNQe1jotn4nWN+0hePqLs+Qi1B3jHdQcSKFGF0m2rsy9uhPT6GOXMtHe3qNzg=="],
+
+    "@vercel/cli-config": ["@vercel/cli-config@0.2.0", "", { "dependencies": { "xdg-app-paths": "5", "zod": "4.1.11" } }, "sha512-fJRRRB7734BDuXZ89yBEaA2ncYhH7bWX30mk04W80J6VAfQc+4iB8lyzAdaGpFV3/vNlkt9VZt+/uoQoWX6UsQ=="],
+
+    "@vercel/cli-exec": ["@vercel/cli-exec@1.0.0", "", { "dependencies": { "execa": "5.1.1" } }, "sha512-kQF8LGie/Hbdq9/psJxLE7owRTcqMQMhgybU04gCeR7cbQAr5t8OrjefDNColJv1QSSucFt4pLwRiARVmlOnug=="],
+
     "@vercel/og": ["@vercel/og@0.6.8", "", { "dependencies": { "@resvg/resvg-wasm": "2.4.0", "satori": "0.12.2", "yoga-wasm-web": "0.3.3" } }, "sha512-e4kQK9mP8ntpo3dACWirGod/hHv4qO5JMj9a/0a2AZto7b4persj5YP7t1Er372gTtYFTYxNhMx34jRvHooglw=="],
 
-    "@vercel/oidc": ["@vercel/oidc@3.1.0", "", {}, "sha512-Fw28YZpRnA3cAHHDlkt7xQHiJ0fcL+NRcIqsocZQUSmbzeIKRpwttJjik5ZGanXP+vlA4SbTg+AbA3bP363l+w=="],
+    "@vercel/oidc": ["@vercel/oidc@3.8.0", "", { "dependencies": { "@vercel/cli-config": "0.2.0", "@vercel/cli-exec": "1.0.0", "jose": "^5.9.6" } }, "sha512-r00laGW6Pv778RoR6M2NxX91ycSj+PBwVo+fOb9Bif+F0IyUKt25zrvBzfEzQpeAzbqOgPZyQibEWDdDFApd+A=="],
 
     "@vitejs/plugin-react": ["@vitejs/plugin-react@4.7.0", "", { "dependencies": { "@babel/core": "^7.28.0", "@babel/plugin-transform-react-jsx-self": "^7.27.1", "@babel/plugin-transform-react-jsx-source": "^7.27.1", "@rolldown/pluginutils": "1.0.0-beta.27", "@types/babel__core": "^7.20.5", "react-refresh": "^0.17.0" }, "peerDependencies": { "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0" } }, "sha512-gUu9hwfWvvEDBBmgtAowQCojwZmJ5mcLn3aufeCsitijs3+f2NsrPtlAWIR6OPiqljl96GVCUbLe0HyqIpVaoA=="],
 
@@ -2939,6 +2946,8 @@
 
     "is-binary-path": ["is-binary-path@2.1.0", "", { "dependencies": { "binary-extensions": "^2.0.0" } }, "sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw=="],
 
+    "is-buffer": ["is-buffer@2.0.5", "", {}, "sha512-i2R6zNFDwgEHJyQUtJEk0XFi1i0dPFn/oqjK3/vPCcDeJvW5NQ83V8QbicfF1SupOaB0h8ntgBC2YiE7dfyctQ=="],
+
     "is-core-module": ["is-core-module@2.16.2", "", { "dependencies": { "hasown": "^2.0.3" } }, "sha512-evOr8xfXKxE6qSR0hSXL2r3sd7ALj8+7jQEUvPYcm5sgZFdJ+AYzT6yNmJenvIYQBgIGwfwz08sL8zoL7yq2BA=="],
 
     "is-decimal": ["is-decimal@2.0.1", "", {}, "sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A=="],
@@ -2957,6 +2966,8 @@
 
     "is-interactive": ["is-interactive@2.0.0", "", {}, "sha512-qP1vozQRI+BMOPcjFzrjXuQvdak2pHNUMZoeG2eRbiSqyvbEf/wQtEOTOX1guk6E3t36RkaqiSt8A/6YElNxLQ=="],
 
+    "is-node-process": ["is-node-process@1.2.0", "", {}, "sha512-Vg4o6/fqPxIjtxgUH5QLJhwZ7gW5diGCVlXpuUfELC62CuxM1iHcRe51f2W1FDy04Ai4KJkagKjx3XaqyfRKXw=="],
+
     "is-number": ["is-number@7.0.0", "", {}, "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng=="],
 
     "is-plain-obj": ["is-plain-obj@4.1.0", "", {}, "sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg=="],
@@ -3433,6 +3444,8 @@
 
     "orderedmap": ["orderedmap@2.1.1", "", {}, "sha512-TvAWxi0nDe1j/rtMcWcIj94+Ffe6n7zhow33h40SKxmsmozs6dz/e+EajymfoFcHd7sxNn8yHM8839uixMOV6g=="],
 
+    "os-paths": ["os-paths@4.4.0", "", {}, "sha512-wrAwOeXp1RRMFfQY8Sy7VaGVmPocaLwSFOYCGKSyo8qmJ+/yaafCl5BCA1IQZWqFSRBrKDYFeR9d/VyQzfH/jg=="],
+
     "p-limit": ["p-limit@3.1.0", "", { "dependencies": { "yocto-queue": "^0.1.0" } }, "sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ=="],
 
     "p-retry": ["p-retry@4.6.2", "", { "dependencies": { "@types/retry": "0.12.0", "retry": "^0.13.1" } }, "sha512-312Id396EbJdvRONlngUx0NydfrIQ5lsYu0znKVUzVvArzEIt08V1qhtyESbGVd1FGX7UKtiFp5uwKZdM8wIuQ=="],
@@ -3723,7 +3736,7 @@
 
     "ret": ["ret@0.5.0", "", {}, "sha512-I1XxrZSQ+oErkRR4jYbAyEEu2I0avBvvMM5JN+6EBprOGRCs63ENqZ3vjavq8fBw2+62G5LF5XelKwuJpcvcxw=="],
 
-    "retry": ["retry@0.12.0", "", {}, "sha512-9LkiTwjUh6rT555DtE9rTX+BKByPfrMzEAtnlEtdEwr3Nkffwiihqe2bWADg+OQRjt9gl6ICdmB/ZFDCGAtSow=="],
+    "retry": ["retry@0.13.1", "", {}, "sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg=="],
 
     "retry-request": ["retry-request@7.0.2", "", { "dependencies": { "@types/request": "^2.48.8", "extend": "^3.0.2", "teeny-request": "^9.0.0" } }, "sha512-dUOvLMJ0/JJYEn8NrpOaGNE7X3vpI5XlZS/u0ANjqtcZVKnIxP7IgCFwrKTxENw29emmwug53awKtaMm4i9g5w=="],
 
@@ -4155,6 +4168,10 @@
 
     "ws": ["ws@8.21.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g=="],
 
+    "xdg-app-paths": ["xdg-app-paths@5.5.1", "", { "dependencies": { "os-paths": "^4.0.1", "xdg-portable": "^7.2.0" } }, "sha512-hI3flOB4PLZIy5prbtTpirobtPE2ZtZ52szO+2mM9Efp6ErM398La+C1lIpNWDfNoQk+6Lsi6nMcCwVB7pxeMQ=="],
+
+    "xdg-portable": ["xdg-portable@7.3.0", "", { "dependencies": { "os-paths": "^4.0.1" } }, "sha512-sqMMuL1rc0FmMBOzCpd0yuy9trqF2yTTVe+E9ogwCSWQCdDEtQUwrZPT6AxqtsFGRNxycgncbP/xmOOSPw5ZUw=="],
+
     "xlsx": ["xlsx@https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz", { "bin": { "xlsx": "./bin/xlsx.njs" } }],
 
     "xml": ["xml@1.0.1", "", {}, "sha512-huCv9IH9Tcf95zuYCsQraZtWnJvBtLVE0QHMOs8bWyZAFZNDcYjsPq1nEx8jKA9y+Beo9v+7OBPRisQTjinQMw=="],
@@ -4213,6 +4230,8 @@
 
     "@a2a-js/sdk/jose": ["jose@6.2.3", "", {}, "sha512-YYVDInQKFJfR/xa3ojUTl8c2KoTwiL1R5Wg9YCydwH0x0B9grbzlg5HC7mMjCtUJjbQ/YnGEZIhI5tCgfTb4Hw=="],
 
+    "@ai-sdk/gateway/@vercel/oidc": ["@vercel/oidc@3.1.0", "", {}, "sha512-Fw28YZpRnA3cAHHDlkt7xQHiJ0fcL+NRcIqsocZQUSmbzeIKRpwttJjik5ZGanXP+vlA4SbTg+AbA3bP363l+w=="],
+
     "@apidevtools/json-schema-ref-parser/js-yaml": ["js-yaml@4.2.0", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-ePWsvanv0DWuDRsW8dnt+R4jQ31SCRCQ7hhNcPXZPsoBZiemuZNYGf7adZdqX2D86j6rvKp3RpCxVTSb8WQlOw=="],
 
     "@asamuzakjp/css-color/lru-cache": ["lru-cache@10.4.3", "", {}, "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ=="],
@@ -4643,6 +4662,12 @@
 
     "@types/ws/@types/node": ["@types/node@25.9.3", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-603BddQMv3pUcr4U2dhujk83N2tTDVr/34wII2B6bJy6g+8WD6yUb11jszNs0gdi4PesVWl7ABt8nYMVpnLUcg=="],
 
+    "@vercel/blob/undici": ["undici@6.27.0", "", {}, "sha512-YmfV3YnEDzXRC5lZ2jWtWWHKGUm1zIt8AhesR1tens+HTNv+YZlN/dp6G727LOvMJ8xjP9Be7Y2Sdr96LDm+pg=="],
+
+    "@vercel/cli-exec/execa": ["execa@5.1.1", "", { "dependencies": { "cross-spawn": "^7.0.3", "get-stream": "^6.0.0", "human-signals": "^2.1.0", "is-stream": "^2.0.0", "merge-stream": "^2.0.0", "npm-run-path": "^4.0.1", "onetime": "^5.1.2", "signal-exit": "^3.0.3", "strip-final-newline": "^2.0.0" } }, "sha512-8uSpZZocAZRBAPIEINJj3Lo9HyGitllczc27Eh5YYojjMFMn8yHMDMaUHE2Jqfq05D/wucwI4JGURyXt1vchyg=="],
+
+    "@vercel/oidc/jose": ["jose@5.10.0", "", {}, "sha512-s+3Al/p9g32Iq+oqXxkW//7jk2Vig6FF1CFqzVXoTUXt2qz89YWbL+OwS17NFYEvxC35n0FKeGO2LGYSxeM2Gg=="],
+
     "accepts/mime-types": ["mime-types@2.1.35", "", { "dependencies": { "mime-db": "1.52.0" } }, "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw=="],
 
     "ai/@opentelemetry/api": ["@opentelemetry/api@1.9.0", "", {}, "sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg=="],
@@ -4651,8 +4676,6 @@
 
     "anymatch/picomatch": ["picomatch@2.3.2", "", {}, "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA=="],
 
-    "async-retry/retry": ["retry@0.13.1", "", {}, "sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg=="],
-
     "axios/https-proxy-agent": ["https-proxy-agent@5.0.1", "", { "dependencies": { "agent-base": "6", "debug": "4" } }, "sha512-dFcAjpTQFgoLMzC2VwU+C/CbS7uRL0lWmxDITmqm7C+7F0Odmj6s9l6alZc6AELXhrnggM2CeWSXHGOdX2YtwA=="],
 
     "better-auth/jose": ["jose@6.2.3", "", {}, "sha512-YYVDInQKFJfR/xa3ojUTl8c2KoTwiL1R5Wg9YCydwH0x0B9grbzlg5HC7mMjCtUJjbQ/YnGEZIhI5tCgfTb4Hw=="],
@@ -4875,8 +4898,6 @@
 
     "ora/strip-ansi": ["strip-ansi@7.2.0", "", { "dependencies": { "ansi-regex": "^6.2.2" } }, "sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w=="],
 
-    "p-retry/retry": ["retry@0.13.1", "", {}, "sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg=="],
-
     "parse-entities/@types/unist": ["@types/unist@2.0.11", "", {}, "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA=="],
 
     "parse5/entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="],
@@ -4897,6 +4918,8 @@
 
     "pptxgenjs/@types/node": ["@types/node@22.19.21", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-VMeFBSCKQKmm2swI2kW51SFusDqekC6q9trBCvJ/JliDchFSuoYYKN7yVNjPthP1HKZcx3U1gI/wTcEBjEFKTA=="],
 
+    "proper-lockfile/retry": ["retry@0.12.0", "", {}, "sha512-9LkiTwjUh6rT555DtE9rTX+BKByPfrMzEAtnlEtdEwr3Nkffwiihqe2bWADg+OQRjt9gl6ICdmB/ZFDCGAtSow=="],
+
     "protobufjs/@types/node": ["@types/node@25.9.3", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-603BddQMv3pUcr4U2dhujk83N2tTDVr/34wII2B6bJy6g+8WD6yUb11jszNs0gdi4PesVWl7ABt8nYMVpnLUcg=="],
 
     "proxy-addr/ipaddr.js": ["ipaddr.js@1.9.1", "", {}, "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g=="],
@@ -5203,6 +5226,16 @@
 
     "@types/ws/@types/node/undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="],
 
+    "@vercel/cli-exec/execa/get-stream": ["get-stream@6.0.1", "", {}, "sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg=="],
+
+    "@vercel/cli-exec/execa/human-signals": ["human-signals@2.1.0", "", {}, "sha512-B4FFZ6q/T2jhhksgkbEW3HBvWIfDW85snkQgawt07S7J5QXTk6BkNV+0yAeZrM5QpMAdYlocGoljn0sJ/WQkFw=="],
+
+    "@vercel/cli-exec/execa/npm-run-path": ["npm-run-path@4.0.1", "", { "dependencies": { "path-key": "^3.0.0" } }, "sha512-S48WzZW777zhNIrn7gxOlISNAqi9ZC/uQFnRdbeIHhZhCA6UqpkOT8T1G7BvfdgP4Er8gF4sUbaS0i7QvIfCWw=="],
+
+    "@vercel/cli-exec/execa/onetime": ["onetime@5.1.2", "", { "dependencies": { "mimic-fn": "^2.1.0" } }, "sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg=="],
+
+    "@vercel/cli-exec/execa/strip-final-newline": ["strip-final-newline@2.0.0", "", {}, "sha512-BrpvfNAE3dcvq7ll3xVumzjKjZQ5tI1sEUIKr3Uoks0XUl45St3FlatVqef9prk4jRDzhW6WZg+3bk93y6pLjA=="],
+
     "accepts/mime-types/mime-db": ["mime-db@1.52.0", "", {}, "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg=="],
 
     "axios/https-proxy-agent/agent-base": ["agent-base@6.0.2", "", { "dependencies": { "debug": "4" } }, "sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ=="],
@@ -5547,6 +5580,8 @@
 
     "@types/request/form-data/mime-types/mime-db": ["mime-db@1.52.0", "", {}, "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg=="],
 
+    "@vercel/cli-exec/execa/onetime/mimic-fn": ["mimic-fn@2.1.0", "", {}, "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg=="],
+
     "cli-truncate/string-width/strip-ansi/ansi-regex": ["ansi-regex@6.2.2", "", {}, "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg=="],
 
     "gaxios/node-fetch/whatwg-url/tr46": ["tr46@0.0.3", "", {}, "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw=="],
diff --git a/package.json b/package.json
index f4ec2af72e5..71857be7f76 100644
--- a/package.json
+++ b/package.json
@@ -37,6 +37,9 @@
     "check:bare-icons": "bun run scripts/check-bare-icons.ts",
     "check:icon-paths": "bun run scripts/check-icon-paths.ts",
     "check:migrations": "bun run scripts/check-migrations-safety.ts",
+    "academy:videos:check": "bun run scripts/academy-videos.ts --check",
+    "academy:videos:faststart": "bun run scripts/academy-videos.ts --apply",
+    "academy:videos:compress": "bun run scripts/academy-videos.ts --compress",
     "mship-contracts:generate": "bun run scripts/sync-mothership-stream-contract.ts",
     "mship-contracts:check": "bun run scripts/sync-mothership-stream-contract.ts --check",
     "billing-protocol-contract:generate": "bun run scripts/sync-billing-protocol-contract.ts",
@@ -92,6 +95,7 @@
     "@clack/prompts": "1.7.0",
     "@octokit/rest": "^21.0.0",
     "@types/opentype.js": "1.3.10",
+    "@vercel/blob": "2.6.1",
     "@vercel/og": "0.6.8",
     "chalk": "5.6.2",
     "glob": "13.0.0",
diff --git a/scripts/academy-videos.ts b/scripts/academy-videos.ts
new file mode 100644
index 00000000000..e2d44a43188
--- /dev/null
+++ b/scripts/academy-videos.ts
@@ -0,0 +1,611 @@
+#!/usr/bin/env bun
+/**
+ * Audits — and optionally repairs — the "faststart" layout of the Academy
+ * lesson videos referenced from `apps/docs/content/docs/en/academy/**\/*.mdx`.
+ *
+ * An MP4 stores its index (the `moov` atom) either before or after the media
+ * payload (`mdat`). A browser cannot decode a single frame until it has read
+ * `moov`, so when `moov` trails the payload the `<video>` element must download
+ * the *entire* file before it paints anything. Every Academy lesson is 45–90 MB,
+ * which is why a first visit shows a black player for a very long time while a
+ * second visit — served from the HTTP disk cache — starts instantly.
+ *
+ * `ffmpeg -movflags +faststart` relocates `moov` to the front. It is a stream
+ * copy: no re-encode, no quality loss, byte-identical media payload.
+ *
+ * Modes:
+ *   --check           (default) Range-read the first few KB of each remote video
+ *                     and report which ones lack faststart. Needs no credentials
+ *                     and downloads only a few KB per file. Exits 1 if any fail.
+ *   --apply           Download, remux, verify, and overwrite each bad video in
+ *                     place on Vercel Blob. Lossless. Requires BLOB_READ_WRITE_TOKEN.
+ *   --compress        Re-encode every video with x264 at --crf, then overwrite.
+ *                     LOSSY AND IRREVERSIBLE — always pair with --backup-prefix.
+ *                     The source recordings are ~4.6 Mbps for screen capture,
+ *                     which CRF 23 at native resolution cuts ~3x while measuring
+ *                     VMAF 95+ against the source.
+ *
+ * Flags:
+ *   --crf <n>            Quality target for --compress. Lower is better and
+ *                        larger; 23 is the measured sweet spot. Defaults to 23.
+ *   --backup-prefix <p>  Server-side copy of each object to `<p>/<name>.mp4`
+ *                        before it is overwritten. Skips names already backed up,
+ *                        so a re-run never clobbers a good backup with a
+ *                        re-encoded one. Defaults to `academy/originals`.
+ *   --only <substr>      Restrict to videos whose pathname contains <substr>.
+ *                        Use this to rehearse on a single file before a full run.
+ *   --work-dir <dir>     Where downloads and outputs land. Defaults to a temp dir.
+ *                        An existing download is reused rather than re-fetched.
+ *
+ * Run: `bun run scripts/academy-videos.ts --check`
+ *      `BLOB_READ_WRITE_TOKEN=… bun run scripts/academy-videos.ts --apply`
+ *      `BLOB_READ_WRITE_TOKEN=… bun run scripts/academy-videos.ts --compress --crf 23`
+ */
+import { spawn } from 'node:child_process'
+import { createReadStream, createWriteStream } from 'node:fs'
+import { mkdir, mkdtemp, open, readFile, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { Readable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import type { ReadableStream as NodeReadableStream } from 'node:stream/web'
+import { sleep } from '@sim/utils/helpers'
+import { backoffWithJitter } from '@sim/utils/retry'
+import { copy, head as headBlob, put } from '@vercel/blob'
+import { glob } from 'glob'
+
+const ROOT = path.resolve(import.meta.dir, '..')
+const ACADEMY_GLOB = 'apps/docs/content/docs/en/academy/**/*.mdx'
+
+/** Bytes range-read from the head of a remote MP4 when probing atom order. */
+const PROBE_BYTES = 8192
+
+/** Cache lifetime to restore on re-upload, matching the existing blob objects. */
+const CACHE_MAX_AGE_SECONDS = 2_592_000
+
+/** Remuxed duration may drift from the source by at most this much. */
+const DURATION_TOLERANCE_SECONDS = 0.5
+
+/** Post-upload atom-order probes, retried while the CDN edge catches up. */
+const REMOTE_CONFIRM_ATTEMPTS = 4
+
+/**
+ * Default x264 quality for `--compress`. Measured on a 1440p lesson: CRF 23 at
+ * native resolution scored VMAF 95.34 mean / 90.66 worst frame for a 3.0x size
+ * cut, while CRF 20 bought only +0.77 VMAF for 64% more bytes.
+ */
+const DEFAULT_CRF = 23
+
+/** Where `--compress` parks a copy of each object before overwriting it. */
+const DEFAULT_BACKUP_PREFIX = 'academy/originals'
+
+/** A re-encode that saves less than this isn't worth the quality loss. */
+const MIN_COMPRESSION_RATIO = 1.2
+
+interface Args {
+  apply: boolean
+  compress: boolean
+  crf: number
+  backupPrefix: string
+  only?: string
+  workDir?: string
+}
+
+function parseArgs(argv: string[]): Args {
+  const args: Args = {
+    apply: false,
+    compress: false,
+    crf: DEFAULT_CRF,
+    backupPrefix: DEFAULT_BACKUP_PREFIX,
+  }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--apply') args.apply = true
+    else if (arg === '--check') args.apply = false
+    else if (arg === '--compress') args.compress = true
+    else if (arg === '--crf') args.crf = Number(argv[++i])
+    else if (arg === '--backup-prefix') args.backupPrefix = argv[++i]
+    else if (arg === '--only') args.only = argv[++i]
+    else if (arg === '--work-dir') args.workDir = argv[++i]
+    else throw new Error(`Unknown argument: ${arg}`)
+  }
+  if (!Number.isInteger(args.crf) || args.crf < 0 || args.crf > 51) {
+    throw new Error(`--crf must be an integer in 0…51, got ${args.crf}`)
+  }
+  return args
+}
+
+interface AcademyVideo {
+  /** Absolute source URL as written in the MDX. */
+  url: string
+  /** Blob pathname, e.g. `academy/tables-operations.mp4`. */
+  pathname: string
+  /** MDX files that reference this URL. */
+  sources: string[]
+}
+
+/**
+ * Collect every distinct blob-hosted MP4 referenced by an Academy lesson. The
+ * MDX is the source of truth — enumerating the blob store instead would also
+ * sweep up assets no page links to.
+ */
+async function discoverVideos(): Promise<AcademyVideo[]> {
+  const files = await glob(ACADEMY_GLOB, { cwd: ROOT, absolute: true })
+  const byUrl = new Map<string, AcademyVideo>()
+
+  for (const file of files.sort()) {
+    const contents = await readFile(file, 'utf8')
+    const matches = contents.matchAll(/src=["'](https?:\/\/[^"']+\.mp4)["']/g)
+    for (const [, url] of matches) {
+      const existing = byUrl.get(url)
+      const relative = path.relative(ROOT, file)
+      if (existing) {
+        existing.sources.push(relative)
+        continue
+      }
+      byUrl.set(url, {
+        url,
+        pathname: new URL(url).pathname.replace(/^\//, ''),
+        sources: [relative],
+      })
+    }
+  }
+
+  return [...byUrl.values()].sort((a, b) => a.pathname.localeCompare(b.pathname))
+}
+
+/**
+ * Walk the top-level ISO-BMFF box list and report whether `moov` precedes the
+ * media payload. Boxes are `[uint32 size][char[4] type]`; size 1 means the real
+ * size follows as a uint64, and size 0 means "extends to end of file".
+ */
+function hasFaststartLayout(head: Buffer): boolean | null {
+  let offset = 0
+  while (offset + 8 <= head.length) {
+    const type = head.toString('latin1', offset + 4, offset + 8)
+    if (type === 'moov') return true
+    if (type === 'mdat') return false
+
+    let size = head.readUInt32BE(offset)
+    if (size === 1) {
+      if (offset + 16 > head.length) return null
+      const large = head.readBigUInt64BE(offset + 8)
+      if (large > BigInt(Number.MAX_SAFE_INTEGER)) return null
+      size = Number(large)
+    } else if (size === 0) {
+      return false
+    }
+    if (size < 8) return null
+    offset += size
+  }
+  return null
+}
+
+interface ProbeResult {
+  faststart: boolean | null
+  size: number
+}
+
+/**
+ * Range-read the head of a remote MP4 and classify its atom order.
+ *
+ * Pass `revalidate` after a write. The blob CDN keys purely on pathname —
+ * a query-string buster is ignored — and it will happily serve the *previous*
+ * object's byte range for a while after an overwrite, which reads as a bogus
+ * "still not faststart". Only a `no-cache` request forces the edge to
+ * revalidate against the origin.
+ */
+async function probeRemote(url: string, revalidate = false): Promise<ProbeResult> {
+  const headers: Record<string, string> = { range: `bytes=0-${PROBE_BYTES - 1}` }
+  if (revalidate) {
+    headers['cache-control'] = 'no-cache'
+    headers.pragma = 'no-cache'
+  }
+
+  const response = await fetch(url, { headers })
+  if (!response.ok) throw new Error(`GET ${url} → ${response.status} ${response.statusText}`)
+
+  const head = Buffer.from(await response.arrayBuffer())
+  const contentRange = response.headers.get('content-range')
+  const total = contentRange?.match(/\/(\d+)$/)?.[1]
+  const size = total ? Number(total) : Number(response.headers.get('content-length') ?? 0)
+
+  return { faststart: hasFaststartLayout(head), size }
+}
+
+/** Read the head of a local MP4 and classify its atom order. */
+async function probeLocal(file: string): Promise<boolean | null> {
+  const handle = await open(file, 'r')
+  try {
+    const head = Buffer.alloc(PROBE_BYTES)
+    const { bytesRead } = await handle.read(head, 0, PROBE_BYTES, 0)
+    return hasFaststartLayout(head.subarray(0, bytesRead))
+  } finally {
+    await handle.close()
+  }
+}
+
+interface CommandResult {
+  code: number
+  stdout: string
+  stderr: string
+}
+
+function run(command: string, args: string[]): Promise<CommandResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args)
+    let stdout = ''
+    let stderr = ''
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk
+    })
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk
+    })
+    child.on('error', reject)
+    child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }))
+  })
+}
+
+async function assertToolAvailable(command: string): Promise<void> {
+  const { code } = await run(command, ['-version'])
+  if (code !== 0) throw new Error(`\`${command}\` is required but not runnable. Install ffmpeg.`)
+}
+
+/** Container duration in seconds, used to prove the remux preserved the media. */
+async function probeDuration(file: string): Promise<number> {
+  const { code, stdout, stderr } = await run('ffprobe', [
+    '-v',
+    'error',
+    '-show_entries',
+    'format=duration',
+    '-of',
+    'default=noprint_wrappers=1:nokey=1',
+    file,
+  ])
+  if (code !== 0) throw new Error(`ffprobe failed for ${file}: ${stderr.trim()}`)
+  const duration = Number(stdout.trim())
+  if (!Number.isFinite(duration)) throw new Error(`ffprobe returned no duration for ${file}`)
+  return duration
+}
+
+function formatMb(bytes: number): string {
+  return `${(bytes / 1_048_576).toFixed(1)} MB`
+}
+
+async function download(url: string, destination: string): Promise<void> {
+  const response = await fetch(url)
+  if (!response.ok || !response.body) {
+    throw new Error(`GET ${url} → ${response.status} ${response.statusText}`)
+  }
+  const body = response.body as NodeReadableStream<Uint8Array>
+  await pipeline(Readable.fromWeb(body), createWriteStream(destination))
+}
+
+/**
+ * Confirm the freshly-written object really is the faststart remux.
+ *
+ * `content-length` is the authoritative signal — it comes from object metadata
+ * rather than a cached byte range, and the remux is reliably a different size
+ * from the original. The atom-order probe is retried behind it because an edge
+ * node can keep serving the old body for a few seconds after the write.
+ */
+async function confirmRemoteFaststart(video: AcademyVideo, expectedSize: number): Promise<void> {
+  for (let attempt = 0; attempt < REMOTE_CONFIRM_ATTEMPTS; attempt++) {
+    if (attempt > 0) await sleep(backoffWithJitter(attempt, null))
+
+    const { faststart, size } = await probeRemote(video.url, true)
+    if (faststart === true) return
+
+    if (size === expectedSize) {
+      console.log('  (edge still serving the previous body; object metadata already matches)')
+      return
+    }
+  }
+  throw new Error(
+    `remote object still does not lead with a moov atom after ${REMOTE_CONFIRM_ATTEMPTS} attempts`
+  )
+}
+
+/** Reuse an existing download; only fetch what the work dir doesn't already hold. */
+async function ensureDownloaded(
+  video: AcademyVideo,
+  destination: string,
+  remoteSize: number
+): Promise<number> {
+  const existing = await stat(destination).catch(() => null)
+  if (existing && (remoteSize === 0 || existing.size === remoteSize)) {
+    console.log(`  reusing local copy (${formatMb(existing.size)})`)
+    return existing.size
+  }
+
+  console.log(`  downloading ${formatMb(remoteSize)} → ${destination}`)
+  await download(video.url, destination)
+
+  const size = (await stat(destination)).size
+  if (remoteSize > 0 && size !== remoteSize) {
+    throw new Error(`truncated download: got ${size} bytes, expected ${remoteSize}`)
+  }
+  return size
+}
+
+/**
+ * Copy the live object aside before it is overwritten.
+ *
+ * Server-side, so it costs no bandwidth. Existing backups are left alone — on a
+ * second `--compress` run the live object is already re-encoded, and copying it
+ * over the backup would destroy the only pristine source.
+ */
+async function backupRemote(video: AcademyVideo, prefix: string): Promise<void> {
+  const name = path.basename(video.pathname)
+  const target = `${prefix}/${name}`
+  const targetUrl = new URL(`/${target}`, video.url).toString()
+
+  if (await headBlob(targetUrl).catch(() => null)) {
+    console.log(`  backup already present at ${target}`)
+    return
+  }
+
+  const source = await headBlob(video.url)
+  const { url } = await copy(video.url, target, { access: 'public', addRandomSuffix: false })
+  const stored = await headBlob(url)
+  if (stored.size !== source.size) {
+    throw new Error(`backup size mismatch: ${source.size} → ${stored.size}`)
+  }
+  console.log(`  backed up → ${target} (${formatMb(stored.size)})`)
+}
+
+/**
+ * Back up → re-encode → verify → overwrite one video.
+ *
+ * Lossy, so the guards are stricter than the remux path: the backup must exist
+ * before anything is overwritten, the output must actually be smaller by a
+ * worthwhile margin, and duration and frame count must both survive intact.
+ */
+async function compressOne(
+  video: AcademyVideo,
+  workDir: string,
+  remoteSize: number,
+  args: Args
+): Promise<void> {
+  const name = path.basename(video.pathname)
+  const original = path.join(workDir, 'original', name)
+  const encoded = path.join(workDir, 'compressed', name)
+
+  await backupRemote(video, args.backupPrefix)
+  const sourceSize = await ensureDownloaded(video, original, remoteSize)
+
+  console.log(`  encoding x264 crf ${args.crf} at native resolution`)
+  const { code, stderr } = await run('ffmpeg', [
+    '-y',
+    '-i',
+    original,
+    '-c:v',
+    'libx264',
+    '-crf',
+    String(args.crf),
+    '-preset',
+    'medium',
+    '-c:a',
+    'copy',
+    '-movflags',
+    '+faststart',
+    encoded,
+  ])
+  if (code !== 0) throw new Error(`ffmpeg failed:\n${stderr.trim()}`)
+
+  if ((await probeLocal(encoded)) !== true) {
+    throw new Error('encoded file does not lead with a moov atom')
+  }
+
+  const [sourceDuration, encodedDuration] = await Promise.all([
+    probeDuration(original),
+    probeDuration(encoded),
+  ])
+  if (Math.abs(sourceDuration - encodedDuration) > DURATION_TOLERANCE_SECONDS) {
+    throw new Error(
+      `duration drift: source ${sourceDuration.toFixed(2)}s vs encode ${encodedDuration.toFixed(2)}s`
+    )
+  }
+
+  const encodedSize = (await stat(encoded)).size
+  const ratio = sourceSize / encodedSize
+  if (ratio < MIN_COMPRESSION_RATIO) {
+    throw new Error(
+      `only ${ratio.toFixed(2)}x smaller — not worth a lossy overwrite (source already efficient?)`
+    )
+  }
+
+  console.log(
+    `  verified: ${formatMb(encodedSize)} vs ${formatMb(sourceSize)} (${ratio.toFixed(2)}x), ${encodedDuration.toFixed(1)}s`
+  )
+
+  console.log(`  uploading → ${video.pathname}`)
+  const { url } = await put(video.pathname, createReadStream(encoded), {
+    access: 'public',
+    contentType: 'video/mp4',
+    addRandomSuffix: false,
+    allowOverwrite: true,
+    multipart: true,
+    cacheControlMaxAge: CACHE_MAX_AGE_SECONDS,
+  })
+  if (url !== video.url) {
+    throw new Error(`upload landed at an unexpected URL: ${url} (expected ${video.url})`)
+  }
+
+  await confirmRemoteFaststart(video, encodedSize)
+  console.log('  ✓ live object re-encoded and leading with moov')
+}
+
+/**
+ * Download → remux → verify → overwrite one video. Every check runs against the
+ * local remux before anything is uploaded, and the remote object is re-probed
+ * afterwards, so a silently-bad upload cannot pass unnoticed.
+ */
+async function repair(video: AcademyVideo, workDir: string, remoteSize: number): Promise<void> {
+  const name = path.basename(video.pathname)
+  const original = path.join(workDir, 'original', name)
+  const remuxed = path.join(workDir, 'faststart', name)
+
+  console.log(`  downloading ${formatMb(remoteSize)} → ${original}`)
+  await download(video.url, original)
+
+  const downloadedSize = (await stat(original)).size
+  if (remoteSize > 0 && downloadedSize !== remoteSize) {
+    throw new Error(`truncated download: got ${downloadedSize} bytes, expected ${remoteSize}`)
+  }
+
+  console.log('  remuxing with -movflags +faststart (stream copy)')
+  const { code, stderr } = await run('ffmpeg', [
+    '-y',
+    '-i',
+    original,
+    '-c',
+    'copy',
+    '-map',
+    '0',
+    '-movflags',
+    '+faststart',
+    remuxed,
+  ])
+  if (code !== 0) throw new Error(`ffmpeg failed:\n${stderr.trim()}`)
+
+  if ((await probeLocal(remuxed)) !== true) {
+    throw new Error('remuxed file still does not lead with a moov atom')
+  }
+
+  const [sourceDuration, remuxedDuration] = await Promise.all([
+    probeDuration(original),
+    probeDuration(remuxed),
+  ])
+  if (Math.abs(sourceDuration - remuxedDuration) > DURATION_TOLERANCE_SECONDS) {
+    throw new Error(
+      `duration drift: source ${sourceDuration.toFixed(2)}s vs remux ${remuxedDuration.toFixed(2)}s`
+    )
+  }
+
+  const remuxedSize = (await stat(remuxed)).size
+  console.log(
+    `  verified: moov first, ${remuxedDuration.toFixed(1)}s, ${formatMb(remuxedSize)} (was ${formatMb(downloadedSize)})`
+  )
+
+  console.log(`  uploading → ${video.pathname}`)
+  const { url } = await put(video.pathname, createReadStream(remuxed), {
+    access: 'public',
+    contentType: 'video/mp4',
+    addRandomSuffix: false,
+    allowOverwrite: true,
+    multipart: true,
+    cacheControlMaxAge: CACHE_MAX_AGE_SECONDS,
+  })
+  if (url !== video.url) {
+    throw new Error(`upload landed at an unexpected URL: ${url} (expected ${video.url})`)
+  }
+
+  await confirmRemoteFaststart(video, remuxedSize)
+  console.log('  ✓ live object now leads with moov')
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2))
+
+  let videos = await discoverVideos()
+  if (args.only) videos = videos.filter((v) => v.pathname.includes(args.only as string))
+
+  if (videos.length === 0) {
+    console.error(`No Academy videos matched${args.only ? ` --only ${args.only}` : ''}.`)
+    process.exit(1)
+  }
+
+  console.log(`Probing ${videos.length} Academy video${videos.length === 1 ? '' : 's'}…\n`)
+
+  const probed: { video: AcademyVideo; size: number }[] = []
+  const bad: { video: AcademyVideo; size: number }[] = []
+  for (const video of videos) {
+    const { faststart, size } = await probeRemote(video.url, true)
+    const status =
+      faststart === true ? 'faststart' : faststart === false ? 'MOOV AT END' : 'unknown'
+    console.log(`  ${video.pathname.padEnd(44)} ${formatMb(size).padStart(9)}  ${status}`)
+    probed.push({ video, size })
+    if (faststart !== true) bad.push({ video, size })
+  }
+
+  // --compress touches every video; the faststart repair only touches broken ones.
+  const targets = args.compress ? probed : bad
+
+  if (targets.length === 0) {
+    console.log('\nAll Academy videos already lead with a moov atom.')
+    return
+  }
+
+  if (!args.compress) {
+    console.log(
+      `\n${bad.length} of ${videos.length} video(s) must download in full before playback.`
+    )
+    if (!args.apply) {
+      console.log(
+        'Re-run with --apply (and BLOB_READ_WRITE_TOKEN set) to remux and overwrite them.'
+      )
+      process.exit(1)
+    }
+  }
+
+  if (!process.env.BLOB_READ_WRITE_TOKEN) {
+    throw new Error('Overwriting requires BLOB_READ_WRITE_TOKEN to be set.')
+  }
+  await assertToolAvailable('ffmpeg')
+  await assertToolAvailable('ffprobe')
+
+  const workDir = args.workDir
+    ? path.resolve(args.workDir)
+    : await mkdtemp(path.join(tmpdir(), 'academy-videos-'))
+  await mkdir(path.join(workDir, 'original'), { recursive: true })
+  await mkdir(path.join(workDir, args.compress ? 'compressed' : 'faststart'), { recursive: true })
+  console.log(`\nWork directory: ${workDir}`)
+  if (args.compress) {
+    console.log(
+      `Re-encoding ${targets.length} video(s) at crf ${args.crf}; each is copied to ${args.backupPrefix}/ first.\n`
+    )
+  } else {
+    console.log('Originals are kept here as a backup.\n')
+  }
+
+  const failures: { pathname: string; reason: string }[] = []
+  let savedBytes = 0
+  for (const [index, { video, size }] of targets.entries()) {
+    console.log(`[${index + 1}/${targets.length}] ${video.pathname}`)
+    try {
+      if (args.compress) {
+        await compressOne(video, workDir, size, args)
+        const after = (await stat(path.join(workDir, 'compressed', path.basename(video.pathname))))
+          .size
+        savedBytes += size - after
+      } else {
+        await repair(video, workDir, size)
+      }
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+      console.error(`  ✗ ${reason}`)
+      failures.push({ pathname: video.pathname, reason })
+    }
+    console.log('')
+  }
+
+  if (failures.length > 0) {
+    console.error(`${failures.length} video(s) failed:`)
+    for (const failure of failures) console.error(`  ${failure.pathname}: ${failure.reason}`)
+    process.exit(1)
+  }
+
+  if (args.compress) {
+    console.log(`Re-encoded ${targets.length} video(s), saving ${formatMb(savedBytes)} overall.`)
+    console.log(`Pre-encode copies remain at ${args.backupPrefix}/.`)
+  } else {
+    console.log(`Repaired ${targets.length} video(s). Originals remain in ${workDir}/original.`)
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error)
+  process.exit(1)
+})