Document quarantine handling for downloaded release packages

Author: Mesteriis

README.md

@@ -74,6 +74,12 @@ For signed artifacts:
 ./Scripts/release-smoke-install.sh --signed dist/DevStackMenu-*.pkg
 ```
 
+If you download a release `.pkg` from GitHub instead of building locally, note the current distribution status:
+
+- local `dist/` exists only in your working copy or CI workspace after `make package`
+- GitHub Release assets are separate downloaded files and do not appear in your local `dist/`
+- unsigned / non-notarized downloaded packages can be blocked by Gatekeeper on macOS
+
 The smoke script verifies:
 
 - package path resolution and signature policy
@@ -110,6 +116,28 @@ rehash
 
 This `.pkg` is the primary release artifact built by CI.
 
+## Downloaded Release Packages
+
+If macOS blocks an already-downloaded release package with "Apple could not verify it", the package is not notarized yet.
+
+If you trust the release and want to install it manually, remove the quarantine attribute and open it again:
+
+```sh
+PKG="$(ls -1t ~/Downloads/DevStackMenu-*.pkg | head -n 1)"
+xattr -dr com.apple.quarantine "$PKG"
+open "$PKG"
+```
+
+Or install directly without Finder:
+
+```sh
+PKG="$(ls -1t ~/Downloads/DevStackMenu-*.pkg | head -n 1)"
+xattr -dr com.apple.quarantine "$PKG"
+sudo installer -pkg "$PKG" -target /
+```
+
+If you want Gatekeeper-friendly installs without removing quarantine manually, the release must be signed with Developer ID Installer and notarized. The repository already contains the pipeline hooks for that in `Scripts/sign-notarize-package.sh` and `.github/workflows/release.yml`; it only needs the Apple signing/notarization secrets configured.
+
 ## What It Does
 
 - shows the current active profile, managed runtime, tunnel state, Docker context and compact metrics in the macOS menu bar

RELEASING.md

@@ -29,11 +29,13 @@ It performs installer + pkgutil + post-install checks.
 8. Verify the main app and compose-import helper use distinct bundle identifiers in the built artifacts.
 9. Verify single-instance behavior by launching the installed app twice and confirming the second launch exits while the original instance stays alive.
 10. If signing credentials are configured, run `workflow_dispatch` on Release Artifacts for signed/notarized output.
+11. If signing credentials are not configured, expect downloaded GitHub Release `.pkg` files to be blocked by Gatekeeper until the user removes `com.apple.quarantine` manually.
 
 ## GitHub Release Flow
 
 The repository includes a workflow that builds a `.pkg` artifact, uploads it as a workflow artifact, and attaches it to the GitHub release for the tag on push/tag events.
 Signed/notarized output is optional and driven by workflow secrets.
+Without these secrets, GitHub Release assets remain unsigned and non-notarized, which is acceptable for maintainer testing but not a polished public install flow.
 
 To enable signing/notarization on `workflow_dispatch`, configure:
 
@@ -54,3 +56,10 @@ v0.1.1
 
 - Artifacts are unsigned by default.
 - `make install-local` is a convenience for maintainers and local users; it is not a substitute for a signed distribution flow.
+- For a downloaded unsigned package, the current manual bypass is:
+
+```sh
+PKG="$(ls -1t ~/Downloads/DevStackMenu-*.pkg | head -n 1)"
+xattr -dr com.apple.quarantine "$PKG"
+sudo installer -pkg "$PKG" -target /
+```