From e2eff3956c79b5f95664212e7fa67d43682c7dff Mon Sep 17 00:00:00 2001
From: Hunter Bown <hmbown@gmail.com>
Date: Tue, 26 May 2026 10:32:07 -0500
Subject: [PATCH] docs(install): add macOS Gatekeeper quarantine workaround
 (#2139)

Harvested from PR #2139 (copilot-swe-agent). README changes skipped
to preserve the narrative harness section.

Co-authored-by: copilot-swe-agent[bot]
---
 docs/INSTALL.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 2a9fd17b..ab4ef018 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -266,6 +266,13 @@ chmod +x ~/.local/bin/codewhale ~/.local/bin/codewhale-tui
 codewhale --version
 ```
 
+> **macOS Gatekeeper note.** If you downloaded the binaries with a browser,
+> macOS may block them with "Apple cannot verify" warnings. Clear the quarantine
+> attribute on both binaries and retry:
+> ```bash
+> xattr -d com.apple.quarantine ~/.local/bin/codewhale ~/.local/bin/codewhale-tui 2>/dev/null || true
+> ```
+
 Verify integrity against the per-release SHA-256 manifest:
 
 ```bash