## TL;DR
Parse renames from `git diff --name-status` instead of the patch text: binary renames appear as an R line with old and new paths, while the patch body is just a "Binary files ... differ" stub with no headers to parse. Parsers that only understand text hunks drop these silently. Read the name-status lines and you get every rename for free.

```text
agent's diff parser failed on binary file renames in docs sync
```

## Steps
1. Reproduce with the right plumbing: run `git diff --name-status HEAD~1 HEAD` on a commit that renames a binary. Expected: a line like `R100 old/path/image.png new/path/image.png`. The patch text for the same commit shows only `Binary files ... differ` with no file headers, which is what breaks naive parsers.
2. Change the parser to consume name-status lines: for every line starting with R, strip the similarity score and record the old-to-new path pair. Handle A, D, and M lines the same way for adds, deletes, and modifies.
3. Treat the binary stub as opaque: when the patch body says the files differ and are binary, skip hunk parsing for that file and use the path pair from step 2. Expected: no more parse exceptions on binary commits.
4. Update the sync mapping: renamed binaries keep their docs references working by rewriting links from the old path to the new path. Expected: the built docs have no broken image or asset links after the rename.
5. Test on a fixture commit containing a renamed image and a renamed PDF: the sync should complete and report both renames. Expected: exit 0 and both new paths in the sync log.

## Use this when
- docs sync breaks on commits that rename images, PDFs, or other binaries
- renamed assets vanish from generated docs
- your diff parser assumes every file has text hunks

## Not for this skill when
- renames of text files fail too (general rename handling bug, not binary-specific)
- the sync fails on all binary files, renamed or not (binary handling bug)
- git itself reports the rename wrong (check rename detection config first)

## Variant phrasings
- diff parser choked on renamed png in docs sync
- binary file rename broke docs sync
- agent dropped renamed images during sync

## Why it happens
Text diffs carry file headers that parsers key on, but binary diffs carry only a one-line "differ" notice. A parser written against text hunks finds no headers, throws or skips the file, and the sync never learns the new path, so references to the renamed asset break.

## Edge cases
- Similarity below the rename threshold shows as separate D plus A lines: the sync should handle that pair too, or lower the threshold.
- Executable-bit-only changes on binaries produce a mode-change line with no content diff: do not treat it as a rename.
- Very large binaries may be excluded from diffs entirely by config: fall back to comparing file listings.
- Case-only renames on case-insensitive filesystems can confuse path mapping: normalize case when matching.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_L4aLzBGIMsDXrrgBotVfQg