Add Capt app icon and clarify download trust warnings

CONTRIBUTING.md

@@ -18,6 +18,13 @@ Apple Development certificate from the keychain, falling back to ad-hoc with a w
 privacy permissions may be re-requested after each rebuild. `CAPT_SIGN_IDENTITY` overrides the
 choice; see [README.md](README.md#known-limitations).
 
+## App icon
+
+`Resources/AppIcon.png` is the supplied logo, preserved without cropping or redrawing.
+Run `Scripts/build-icon.sh` after replacing it and commit the generated `Resources/AppIcon.icns`.
+The bundle uses this icon in Finder and other macOS app surfaces; the menu bar retains its
+caption status symbol so enabled/disabled states remain visible.
+
 ## Layout rules
 
 - `Sources/CaptionCore` holds protocols, caption state, and session orchestration. It never imports

RELEASE.md

@@ -49,6 +49,23 @@ checksums. Filenames include `-local`: these downloads are not notarized for pub
 The app itself is at `build/Capt.app`. This uses the installed Swift toolchain and available
 macOS SDK; public notarization also needs full Xcode.
 
+## When macOS blocks a download or launch
+
+Current downloads are ad-hoc signed, not Developer ID signed or notarized by Apple.
+If Capt downloads but opening it reports an unidentified developer or that Apple cannot
+check it, try opening Capt once, then use **System Settings → Privacy & Security → Open Anyway**
+if you trust the release. Follow [Apple’s guidance](https://support.apple.com/en-us/102445).
+
+If the browser blocks the download itself, or macOS reports the app is damaged or will harm
+your computer, record the exact warning first. Download a fresh copy from this repository's
+GitHub release and verify its SHA-256 checksum; do not disable Gatekeeper system-wide.
+A checksum verifies that the file matches the published download, not its safety.
+
+The publisher-side solution is Developer ID signing and Apple notarization for both the app
+and the DMG. `Scripts/package.sh release` supports that locally after the account setup below.
+The current GitHub Actions workflow still creates ad-hoc builds and needs signing credentials
+and a notarization step before it can produce trusted public downloads.
+
 ## One-time public release setup
 
 1. Install Xcode 26 or newer and select its developer directory (for example, set

Resources/Info.plist

@@ -10,6 +10,8 @@
 	<string>app.capt</string>
 	<key>CFBundleInfoDictionaryVersion</key>
 	<string>6.0</string>
+	<key>CFBundleIconFile</key>
+	<string>AppIcon</string>
 	<key>CFBundleName</key>
 	<string>Capt</string>
 	<key>CFBundleDisplayName</key>

Scripts/build-icon.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Convert the supplied logo into the standard macOS app-icon sizes.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+mkdir -p build/AppIcon.iconset
+for size in 16 32 128 256 512; do
+  sips -z "$size" "$size" Resources/AppIcon.png \
+    --out "build/AppIcon.iconset/icon_${size}x${size}.png" >/dev/null
+  double=$((size * 2))
+  sips -z "$double" "$double" Resources/AppIcon.png \
+    --out "build/AppIcon.iconset/icon_${size}x${size}@2x.png" >/dev/null
+done
+iconutil -c icns build/AppIcon.iconset -o Resources/AppIcon.icns

Scripts/build.sh

@@ -68,6 +68,7 @@ rm -rf "$APP"
 mkdir -p "$APP/Contents/MacOS" "$APP/Contents/Resources"
 cp "$BIN" "$APP/Contents/MacOS/Capt"
 cp Resources/Info.plist "$APP/Contents/Info.plist"
+cp Resources/AppIcon.icns "$APP/Contents/Resources/AppIcon.icns"
 cp NOTICE LICENSE "$APP/Contents/Resources/"   # third-party and source license notices ship with the binary
 echo -n "APPL????" > "$APP/Contents/PkgInfo"