# Task B5 Report: Document the feature in the README

## Status
COMPLETED

## Section Added
Added `## Patching packages` section to `README.md` after the "Build Process" section (before "Build Environment").

### Content
The new section explains:

1. **Problem statement:** Compiler/OS-specific build failures in packages like RcppParallel that cascade to all dependents.
2. **Registry location:** Points to `local/patches/registry.json` and references `local/patches/README.md` for the schema.
3. **Two-tier approach:**
   - Lightweight overrides (env vars, configure args, Makevars)
   - Source diffs (version-pinned, deeper fixes)
4. **Implementation:** Explains that bincraft pre-builds patched binaries and serves them to pak, ensuring transitive dependents receive the fixed package.
5. **Design spec link:** References `specs/2026-06-30-package-patching-design.md`.

## Verification

### Git Diff
```
+## Patching packages
+
+Some CRAN packages fail to compile on specific platforms due to compiler- or OS-specific issues unrelated to the package itself.
+The canonical example is `RcppParallel`, whose bundled TBB sources fail on musl (Alpine) and newer compiler/OS combinations.
+Because such packages are often transitive dependencies of many others, a single failure cascades: all dependents fail even though nothing is wrong with the dependent itself.
+
+To address this, frequently-failing packages can be "patched" before they are installed — whether as a direct build target or a transitive dependency pulled in by `pak`.
+
+The patch registry lives in `local/patches/registry.json`.
+Each entry specifies a package and the platforms/versions it applies to, along with either lightweight build-time overrides (environment variables, configure arguments, Makevars) or a source diff (for deeper fixes).
+See `local/patches/README.md` for the complete schema.
+
+Patching uses a two-tier approach:
+
+1. **Lightweight overrides:** environment variables, configure arguments, or Makevars settings applied during build — typically version-independent and fast.
+2. **Source diffs:** unified diff patches applied to the unpacked source before building — more powerful but version-pinned.
+
+The system is implemented in `bincraft`: when a package needs patching, `bincraft` pre-builds it with the patch and serves the patched binary to `pak`, ensuring transitive dependents receive the fixed package.
+This way, the fix cascades to all packages that depend on it.
+
+For the design rationale and architecture, see `specs/2026-06-30-package-patching-design.md`.
```

### Linting
- **markdownlint-cli2:** No errors (0 error(s))
- **Style:** Follows existing README conventions (one sentence per line for prose, bullet lists for structure)
- **Commit:** `a826a27 docs(patches): document the package patching workflow`

## Files Modified
- `/Users/pjs/.t3/worktrees/build-cran-binaries/t3code-6d007901/README.md`

## Concerns
None. The section is complete, properly placed, lints cleanly, and follows all repository conventions.