diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.yml
index 70114e4..d1df465 100644
--- a/.github/workflows/desktop-release.yml
+++ b/.github/workflows/desktop-release.yml
@@ -182,7 +182,14 @@ jobs:
           GH_TOKEN: ${{ github.token }}
         run: |
           if gh release view "$VERSION" >/dev/null 2>&1; then
-            echo "::error title=Release already exists::GitHub immutable releases do not allow replacing assets. Create a new patch tag, for example v1.0.1, and run Desktop Release for that tag."
+            asset_count="$(gh release view "$VERSION" --json assets --jq '.assets | length')"
+
+            if [ "$asset_count" -gt 0 ]; then
+              echo "::notice title=Release already published::Release $VERSION already has $asset_count assets. Immutable release assets cannot be replaced, so this rerun is treated as already complete."
+              exit 0
+            fi
+
+            echo "::error title=Release already exists::Release $VERSION exists without assets. GitHub immutable releases do not allow replacing published assets. Create a new patch tag and run Desktop Release for that tag."
             exit 1
           fi
 
diff --git a/docs/DESKTOP.md b/docs/DESKTOP.md
index 030c64c..5abbf47 100644
--- a/docs/DESKTOP.md
+++ b/docs/DESKTOP.md
@@ -43,6 +43,16 @@ Electron Builder signing environment variables to produce signed artifacts:
   `APPLE_API_ISSUER`
 - Windows: `WIN_CSC_LINK`, `WIN_CSC_KEY_PASSWORD`
 
+Unsigned macOS downloads can show a Gatekeeper dialog saying `"SpecDock" is
+damaged and can't be opened`. If you trust the downloaded release and have
+verified `SHA256SUMS.txt`, cancel the dialog, copy the app to `/Applications`,
+then remove the quarantine flag:
+
+```bash
+sudo xattr -dr com.apple.quarantine /Applications/SpecDock.app
+open /Applications/SpecDock.app
+```
+
 The GitHub `Desktop Release` workflow maps repository secrets to those
 environment variables and verifies signatures when credentials are present. In
 GitHub, store the Apple `.p8` notarization key as `APPLE_API_KEY_BASE64`; the
diff --git a/docs/release-notes/v1.0.1.md b/docs/release-notes/v1.0.1.md
index 5b5b936..37034e6 100644
--- a/docs/release-notes/v1.0.1.md
+++ b/docs/release-notes/v1.0.1.md
@@ -27,3 +27,9 @@ SpecDock v1.0.1 is a patch release for the stable desktop line.
   targets disabled unless the user enables them locally.
 - Runtime timeout and response-size settings are validated and capped by the
   application limits.
+
+## Known macOS Install Note
+
+- macOS can show `"SpecDock" is damaged and can't be opened` for unsigned
+  downloads. Verify the checksum, copy `SpecDock.app` to `/Applications`, then
+  run `sudo xattr -dr com.apple.quarantine /Applications/SpecDock.app`.