posit-dev · sharon-wang · Jun 2, 2026 · May 29, 2026 · Jun 2, 2026 · juliasilge
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -65,6 +65,10 @@ Key formatting rules:
   - `lint.yml`: URL checking on PRs
   - `publish-release-notes.yml`: Manual workflow for S3/CloudFront deployment
 
+## Videos and Git LFS
+
+Video files (`.mp4`, `.mov`) are stored with Git LFS (see `.gitattributes`). When adding or replacing a video, make sure Git LFS is installed (`git lfs install`) so the file goes through the LFS filter. If a video shows up as changed in `git diff` but you didn't touch it, it was probably committed outside of LFS. Fix it by running `git add <file>` to re-add it through the filter.
+
-## Videos and Git LFS
-
-Video files (`.mp4`, `.mov`) are stored with Git LFS (see `.gitattributes`). When adding or replacing a video, make sure Git LFS is installed (`git lfs install`) so the file goes through the LFS filter. If a video shows up as changed in `git diff` but you didn't touch it, it was probably committed outside of LFS. Fix it by running `git add <file>` to re-add it through the filter.
+## Videos and Git LFS
+
+Video files (`.mp4`, `.mov`) are stored with Git LFS (see `.gitattributes`). When adding or replacing a video, make sure Git LFS is installed and initialized (`git lfs install`) so the file goes through the LFS filter.
+
+If a video shows up as changed in `git diff` or `git status` but you didn't touch it, that's a phantom diff: the file was committed as raw binary instead of an LFS pointer, so the clean filter now produces a pointer that differs from the stored blob. Do not stage or commit this as part of unrelated work. Running `git add` would rewrite the stored blob into a pointer, which is a real change to history. Instead, discard it with `git restore <file>`, and handle converting the file to LFS as its own deliberate change.
+
-## Videos and Git LFS
-
-Video files (`.mp4`, `.mov`) are stored with Git LFS (see `.gitattributes`). When adding or replacing a video, make sure Git LFS is installed (`git lfs install`) so the file goes through the LFS filter. If a video shows up as changed in `git diff` but you didn't touch it, it was probably committed outside of LFS. Fix it by running `git add <file>` to re-add it through the filter.
+## Videos and Git LFS
+
+Video files (`.mp4`, `.mov`) are stored with Git LFS (see `.gitattributes`). When adding or replacing a video, make sure Git LFS is installed and initialized (`git lfs install`) so the file goes through the LFS filter.
+
+If a video shows up as changed in `git diff` or `git status` but you didn't touch it, that's a phantom diff: the file was committed as raw binary instead of an LFS pointer, so the clean filter now produces a pointer that differs from the stored blob. Do not stage or commit this as part of unrelated work. Running `git add` would rewrite the stored blob into a pointer, which is a real change to history. Instead, discard it with `git restore <file>`, and handle converting the file to LFS as its own deliberate change.
+
 ## Issue Tracking
 
 Report issues at https://github.com/posit-dev/positron/issues (main Positron repo, not this website repo).
diff --git a/README.md b/README.md
@@ -15,6 +15,8 @@ We currently use the issue tracker for [Positron](https://github.com/posit-dev/p
 
 This repository uses [Git LFS](https://git-lfs.com/) to store large files such as videos. Make sure you have Git LFS installed before cloning.
 
+If you see phantom diffs on video files you didn't change, it usually means those files were committed outside of LFS. Run `git add <file>` to re-add them through the LFS filter, then commit the result.
-If you see phantom diffs on video files you didn't change, it usually means those files were committed outside of LFS. Run `git add <file>` to re-add them through the LFS filter, then commit the result.
+Because videos are stored in Git LFS, install and initialize Git LFS (`git lfs install`) before adding or replacing a video so it goes through the LFS filter. If you ever see a "phantom diff" on a video file you didn't touch, it means that file was committed as raw binary instead of an LFS pointer. Don't commit the change into an unrelated PR: run `git restore <file>` to clear it locally, and flag the file so it can be re-added through LFS on its own.
-If you see phantom diffs on video files you didn't change, it usually means those files were committed outside of LFS. Run `git add <file>` to re-add them through the LFS filter, then commit the result.
+Because videos are stored in Git LFS, install and initialize Git LFS (`git lfs install`) before adding or replacing a video so it goes through the LFS filter. If you ever see a "phantom diff" on a video file you didn't touch, it means that file was committed as raw binary instead of an LFS pointer. Don't commit the change into an unrelated PR: run `git restore <file>` to clear it locally, and flag the file so it can be re-added through LFS on its own.
+
 If you have [Quarto installed locally](https://quarto.org/docs/get-started/) and Chrome or Edge, you can preview the site by running one of the Debug Configurations in VS Code or Positron.
 
 The configurations run `quarto preview` and then open the site in a new browser window.

diff --git a/videos/connections.mp4 b/videos/connections.mp4
diff --git a/videos/data-explorer.mp4 b/videos/data-explorer.mp4
diff --git a/videos/positron-assistant-copytoeditor.mp4 b/videos/positron-assistant-copytoeditor.mp4
diff --git a/videos/positron-hero-fast-tour.mp4 b/videos/positron-hero-fast-tour.mp4