I’ll add the provided image as a repo-top asset, check the project’s structure so it lands in the right place, then branch and commit the change.

The repo is a Go project on main with a clean worktree. I found the image at the supplied path; next I’m going to put it under a small assets folder and reference it at the very top of the README so it shows up at the top of the repo page.

I’m making a new codex/ branch now, then I’ll add the binary asset and a single README line above the title.

The header image is now in assets/git-sync-header.png, and the README starts with it before the # git-sync title. I’m checking the diff and then I’ll stage and commit it.

Done. I created branch codex/add-repo-header-image and committed c2fe52e Add repo header image.

Changed:

• Added assets/git-sync-header.png
• Added it to the top of README.md

::git-create-branch{cwd="/Users/rizel/Documents/work/gitsync" branch="codex/add-repo-header-image"} ::git-stage{cwd="/Users/rizel/Documents/work/gitsync"} ::git-commit{cwd="/Users/rizel/Documents/work/gitsync"}

Put them in the same repo asset area:

/Users/rizel/Documents/work/gitsync/assets/

Suggested names:

• /Users/rizel/Documents/work/gitsync/assets/git-sync-run.png
• /Users/rizel/Documents/work/gitsync/assets/git-sync-plan.png

Then reference them from the README near the relevant sections:

• git-sync-run.png under the “Commands” section after the git-sync sync description
• git-sync-plan.png near the paragraph that mentions git-sync plan

If they’re docs-focused screenshots rather than branding, docs/assets/ would also be reasonable, but since the repo already now has assets/git-sync-header.png, keeping all README images in top-level assets/ is the cleanest choice.

I’ll take a closer look through the README for the exact command mentions and point to the best insertion spots.

Yes. Best spots in README.md:

• git-sync plan image: right after line 28, where the README says “To preview what would happen without pushing, run git-sync plan...”. That is the only explicit plan mention in the README, so it’s the natural home.

• git-sync sync image: either after the Quick Start command block ending around README.md, or after the sync bullet in the Commands section around README.md. I’d put it after Quick Start because that’s where readers see an actual runnable git-sync sync invocation.

So the clean layout would be:

• top banner stays at line 1
• git-sync plan screenshot under ## Commands
• git-sync sync screenshot under ## Quick Start after the command block

Got it: gitsync.mp4 is the sync demo, and gitsyncplan.mp4 is the plan demo. I’ll add both under the existing assets/ folder and wire them into the README at the spots we just identified.

The branch is clean and the two recordings are reasonable-size MP4s. I’m naming them git-sync-run.mp4 and git-sync-plan.mp4, then adding compact video embeds in the README rather than treating them as static images.

The README now has the plan demo under the git-sync plan mention and the sync demo immediately after the Quick Start command. I’m checking the diff and then I’ll commit this as a second change on the same branch.

Added and committed them on codex/add-repo-header-image.

The sync recording is now assets/git-sync-run.mp4, shown after the Quick Start git-sync sync command. The plan recording is assets/git-sync-plan.mp4, shown right after the README’s git-sync plan mention.

New commit: 52e7832 Add command demo videos

::git-stage{cwd="/Users/rizel/Documents/work/gitsync"} ::git-commit{cwd="/Users/rizel/Documents/work/gitsync"}

Yep, good catch. I’ll refresh from main, inspect what landed there, then rewrite this branch so its diff against main is only the two demo videos plus their README embeds.

origin/main has moved, so I’ve fetched it. Now I’m checking whether the top image is already present there and then I’ll rebase this branch to drop our duplicate header-image commit.

Nice, the rebase applied cleanly. The branch is now based on the updated origin/main; I’m doing one final diff check to confirm the old top-image asset is no longer part of this branch.

Done. I rebased the branch onto the updated origin/main, which already has the top cover image from PR #30.

The branch now contains only:

• README video embeds
• assets/git-sync-plan.mp4
• assets/git-sync-run.mp4

The duplicate assets/git-sync-header.png commit is gone from this branch. Current branch commit is 636b5a3 Add command demo videos.

I’ll push the rebased branch and open a PR against main, then I’ll give you the PR link.

The push is running through the repo’s Git sync hooks and still working; I’m letting it finish before creating the PR so GitHub sees the branch cleanly.

Opened the PR: entireio/git-sync#31

It’s based on updated main and only includes the two demo videos plus README embeds.

::git-push{cwd="/Users/rizel/Documents/work/gitsync" branch="codex/add-repo-header-image"} ::git-create-pr{cwd="/Users/rizel/Documents/work/gitsync" branch="codex/add-repo-header-image" url="https://github.com/entireio/git-sync/pull/31" isDraft=false}

I’ll check what GitHub rendered versus what’s in the repo, then I’ll adjust the README to a format GitHub actually supports for media previews. My hunch is the raw <video> tags are being sanitized or not rendered in README context.

Interesting: fetched origin/main currently does not contain the video files or README embeds at all, so this may be either a merge that didn’t include our branch, or GitHub is showing a different branch than this local remote state. I’m checking the PR state next.

I found the core issue: GitHub README rendering won’t play MP4 files committed in the repo as inline videos. The reliable README-native fix is to convert the demos to animated image assets, usually GIFs, and embed those with normal Markdown image syntax.

This machine doesn’t have ffmpeg on PATH, so I’m checking the bundled workspace runtimes before I decide whether to use a local Python video library or another installed media tool.

I’m going to use a temporary Python video stack to make GIFs, then update the existing PR branch by replacing the non-rendering MP4 embeds with standard image embeds. That keeps the repo README portable and avoids depending on GitHub’s video attachment system.

The recordings are short but 4K, so I’m creating optimized 1280px-wide GIFs with a generated palette. That should render in the README while keeping the diff less dramatic than full-resolution animation.

The GIFs came out small enough to be reasonable: about 2 MB for sync and 4 MB for plan. I’m removing the MP4s from the PR and swapping the README to normal ![...]() image embeds.

This is the shape we want: the README references .gif files, and the .mp4 files are removed from the branch. I’ll amend the PR commit and force-push with lease so the open PR updates in place.

Yep, the MP4 embeds were the problem. GitHub README pages don’t reliably render repo-committed MP4s inline from <video> tags.

I updated PR #31 to use animated GIFs instead:

• Removed the MP4 files from the PR
• Added assets/git-sync-plan.gif
• Added assets/git-sync-run.gif
• Changed the README to normal Markdown image embeds

Force-pushed the PR branch to commit 5d3185a Add command demo animations.

::git-push{cwd="/Users/rizel/Documents/work/gitsync" branch="codex/add-repo-header-image"}

Yes, a drag-and-drop GitHub upload URL is usually better for README videos: GitHub hosts it as an uploaded asset, and the generated URL can render/play where committed MP4s often do not. I’ll remove the GIFs and the README GIF embeds from the PR now, leaving the branch ready for those URLs.

I found exactly the two GIF embeds and the two GIF files. Removing those now, then I’ll amend and push the PR so it no longer carries the GIF assets.

After removing them, this branch intentionally has no remaining content change until we add the drag-and-drop URLs. I’m going to amend the PR branch to an empty tree relative to main and force-push, so GitHub no longer shows the GIF files in the PR.

Yes, drag-and-drop GitHub asset URLs should be better for actual videos.

I removed the GIF files and GIF README embeds from PR #31, then force-pushed. The PR is now open with 0 changed files, ready for the two GitHub-hosted video URLs when you have them.

When you get the URLs, send me:

• sync video URL
• plan video URL

and I’ll put them back in the same two README spots.

Perfect. I’ll add those two GitHub-hosted attachment URLs in the README at the same plan/sync spots, then amend and push the PR branch.

The branch is clean and currently has no changes. I’m inserting the plan URL under the plan paragraph and the sync URL after the Quick Start command block, as plain attachment URLs so GitHub can render them.

The README diff is just the two hosted video URLs. I’ll amend the PR commit and force-push the branch now.

Done. PR #31 now uses the GitHub-hosted video URLs directly in the README:

• plan URL under the git-sync plan mention
• sync URL after the Quick Start git-sync sync command

No GIFs or MP4s are in the branch now. New PR commit is b294a4c Add command demo videos.

::git-push{cwd="/Users/rizel/Documents/work/gitsync" branch="codex/add-repo-header-image"}

Yep, that makes sense: committed repo assets are better for future reuse on entire.io, and ![]() gives GitHub’s renderer a better shot than raw <video>. I’ll move the original MP4s into docs/images and point the README at them with Markdown image syntax.

The branch is clean. I found the original MP4s and the existing docs/images directory, so I’m copying them there and replacing the hosted URLs with ![]() references to the repo files.

The diff now uses committed MP4s in docs/images with Markdown image syntax. I’ll amend the PR commit and force-push it back to the open PR.

Push is still finishing through the repository’s sync wrapper. I’m waiting it out so the PR branch updates cleanly.

Done. PR #31 now uses committed MP4 assets in docs/images with Markdown image syntax:

• docs/images/git-sync-plan.mp4
• docs/images/git-sync-run.mp4

README now has:

Force-pushed commit 0a69b3c Add command demo videos.

::git-push{cwd="/Users/rizel/Documents/work/gitsync" branch="codex/add-repo-header-image"}

Got it. I’ll switch the README back to the GitHub-hosted attachment URLs and remove the committed MP4 files from docs/images, then update the PR branch.

The README is back to the user-attachments URLs, and the repo MP4s are removed locally. I’ll amend the PR commit and force-push it.

Done. PR #31 is back to the GitHub user-attachments version.

The committed MP4s in docs/images are removed from the branch, and the PR now only changes README.md with the two hosted video URLs. New commit is 8b4d61d Add command demo videos.

::git-push{cwd="/Users/rizel/Documents/work/gitsync" branch="codex/add-repo-header-image"}

Yep, I’ll remove the plan video URL and leave only the sync demo after the Quick Start command.

The plan URL is gone; only the sync video remains. I’ll amend and force-push the PR update.