Distillation

<observations> Date: Jul 30, 2026

🔴 (16:34) User received feedback from friends on binpatch landing page positioning and wants 4 changes: (1) add a big graph comparing download size and time for a 100MB binary using gzipped size (referencing actual binary sizes from Sentry CLI repo and patch sizes), (2) drop the focus on CLI — binpatch applies to any binary such as electron apps, (3) use existing card boxes on landing page for "where/when can I use binpatch" content, (4) ensure .md versions of pages exist (replicate what getsentry/cli repo uses for docs, or at minimum add copy-as-markdown buttons).
🟡 (16:34) Agent explored binpatch project structure. Root files: CHANGELOG.md, .craft.yml, LICENSE, logo-brief.md, package.json, package-lock.json, README.md (8374 bytes), tsconfig.json, tsup.config.ts, vitest.config.ts, .github/, action/, dist/, node_modules/, src/, test/, website/.
🟡 (16:34) website/ directory uses Astro + Starlight (@astrojs/starlight ^0.41.4, astro ^7.1.4, sharp ^0.35.0). Custom domain: binpatch.p.byk.im. PR previews build under /_preview/pr-<n>/ driven by DOCS_BASE_PATH env var. Site described as "Stop re-downloading the entire binary on every CLI update. binpatch generates and applies small binary delta patches — the same engine sentry-cli uses."
🟡 (16:34) website/public/ assets: apple-touch-icon.png (18470 bytes), architecture-flow.svg (2812 bytes), favicon-32.png (2195 bytes), favicon.svg (663 bytes), flow.svg (3204 bytes). website/src/assets/: logo.svg (809 bytes). website/src/ also contains content.config.ts (270 bytes) and custom.css (2464 bytes).
🟡 (16:34) website/src/content/docs/ contains 15 markdown docs: apply.md (4513), architecture.md (7023), ci-integration.md (6625), contributing.md (3955), custom-fetch.md (4848), discover.md (6427), faq.md (5013), getting-started.md (3553), github-action.md (8399), index.mdx (5419), installation.md (2119), progress.md (4951), security.md (5482), telemetry.md (4484), wire-contract.md (4953).
🟡 (16:34) Current landing page (index.mdx) hero tagline: "Every CLI update re-downloads the whole binary. Most of it never changed. Patch only what moved." Claims delta is "typically 0.05–0.1% of the full size. That 100 MB update becomes a ~190 KB patch." Includes 4 cards: "Generate from CI", "Apply in your binary", "Battle-tested at scale", "Pure TS, no runtime dependencies".
🟡 (16:34) Astro config sidebar groups: Getting Started (Introduction, Installation, Quickstart), Concepts (Wire Contract, Architecture, Security), Guides (Applying patches, Discovering chains, Progress & events, Custom fetch / CA, Instrumentation hook), CI Integration (GitHub Action, Library integration), Resources (FAQ, Contributing).
🔴 (16:34) User's binpatch project positioning covers self-updating binaries, not just CLIs. Current applicable targets listed: Bun (bun build --compile), Deno (deno compile), Node SEA (node --experimental-sea-config + node --build), yao-pkg/@yao-pkg/pkg, esbuild --bundle, Fossilize + Demo. Threshold for delta value: >50 MB. Uses bsdiff, SHA-256 verification, parallel chain download, OOM guard, MIT-licensed TypeScript library + drop-in GitHub Action. Powers self-updates in production for shipped CLI binaries.
🔴 (16:34) User's binpatch library contract guarantees: resolveAndApply accepts offline flag (cache-only, never touch the network), emits ProgressEvents to ProgressHandler (safeProgress) — library never draws progress (caller renders it), missing progress handler is silent, a throwing handler can never abort the operation. onUnavailable reasons: "no_patches" | "malformed_chain" | "too_long" | "over_budget" | "network". Exports listed: resolveAndApply, compareVersions, ProgressEvent, ProgressHandler, `

Distillation

Observations