docs: add binary integrity verification section (P0-4)

* docs: add binary integrity verification section (P0-4)

Document the checksum verification behavior, CAPISCIO_SKIP_CHECKSUM env var,
and add troubleshooting entry for checksum failures.

Ref: DOCS_REMEDIATION_PLAN P0-4 Part B

* docs: clarify checksum bypass vs mismatch failure modes

Address review comment: CAPISCIO_SKIP_CHECKSUM only bypasses when
checksums.txt is unavailable/missing entry. Actual checksum mismatches
are hard failures that cannot be bypassed.

Author: beonde

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