diff --git a/README.md b/README.md
index 7d16499..5bf9909 100644
--- a/README.md
+++ b/README.md
@@ -59,6 +59,26 @@ The Python wrapper includes specific commands to manage the binary:
 - **Linux**: AMD64, ARM64
 - **Windows**: AMD64
 
+## Binary Integrity Verification
+
+On first run, the wrapper downloads the capiscio-core binary and verifies its SHA-256 checksum
+against the published `checksums.txt` from the GitHub release.
+
+Two failure modes exist:
+
+1. **Checksum mismatch** ("Binary integrity check failed"): The downloaded file does not match
+   the published checksum. This indicates tampering or corruption and **cannot be bypassed**.
+   Delete the cached binary and retry.
+
+2. **Checksums unavailable** ("checksums.txt could not be fetched" or "no entry for …"):
+   The checksums file could not be downloaded or does not contain an entry for the platform
+   binary. This can happen with pre-release versions or network issues. To bypass:
+
+```bash
+# Bypass only when checksums.txt is unavailable (not for mismatches)
+export CAPISCIO_SKIP_CHECKSUM=true
+```
+
 ## Troubleshooting
 
 **"Permission denied" errors:**
@@ -70,6 +90,16 @@ capiscio --wrapper-clean
 **"Binary not found" or download errors:**
 If you are behind a corporate firewall, ensure you can access `github.com`.
 
+**"Binary integrity check failed":**
+The downloaded binary does not match the published checksum — this may indicate a corrupted
+or tampered download. Delete the cached binary (`capiscio --wrapper-clean`) and retry.
+This error **cannot** be bypassed with `CAPISCIO_SKIP_CHECKSUM`.
+
+**"Checksum verification failed: checksums.txt could not be fetched":**
+The checksums file is unavailable (network issue or pre-release version). You can set
+`CAPISCIO_SKIP_CHECKSUM=true` to proceed without verification, but only do this in
+development environments.
+
 ## License
 
 Apache-2.0