diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index fabbf9f..4e190f4 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -11,7 +11,7 @@ name: Release
 # (bundle.macOS.signingIdentity: "-", hardenedRuntime: false). That replaces
 # the linker-only signature that made macOS report the app as "damaged" and
 # refuse Finder launches — users now get the standard "Open Anyway" prompt
-# (or run `xattr -dr com.apple.quarantine` for the damaged-error case, see
+# (or run `sudo xattr -dr com.apple.quarantine` for the damaged-error case, see
 # README). Still NOT Developer-ID signed / notarized (no certs yet).
 # tauri-action automatically signs + notarizes when the signing secrets are
 # present, so the moment we add APPLE_CERTIFICATE / APPLE_API_KEY /
diff --git a/AGENTS.md b/AGENTS.md
index 8e7c9fd..e041826 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -168,6 +168,7 @@ Cut a release by tagging the **`prod`** branch once the PR is merged — `git ta
 - `src/lib/version.test.ts` and `src/lib/docs-coverage.test.ts` if they assert the version
 - **README download links are static (versioned)** — both download tables (top **Download** section + **Which file should I download?**) link directly to the release-tag assets (`releases/download/v0.7.9/<file>`). tauri-action uses default versioned asset names (`Gridline_<ver>_aarch64.dmg`, `Gridline-<ver>-1.x86_64.rpm`, etc.) — update BOTH tables to the new names on every release (see the MAINTENANCE comment in README.md).
 - **Bundled pg tools:** `tauri.conf.json` `bundle.resources` lists `resources/pg_tools/*`; the `release.yml` matrix builds/downloads + checksum-verifies the static binaries before the Tauri build step.
+- **Release notes must include the macOS first-launch instructions** — until a Developer ID signing certificate is secured, releases are ad-hoc signed only (not notarized), so every macOS user hits a Gatekeeper prompt. The draft release body must include: right-click → **Open** → **Open** (or System Settings → Privacy & Security → **Open Anyway**) for "developer cannot be verified", and `sudo xattr -dr com.apple.quarantine /Applications/Gridline.app` (with the re-run-after-every-upgrade note) for "damaged and can't be opened".
 
 ### Adding a Tauri Command
 
diff --git a/README.md b/README.md
index de9921d..8a27f69 100644
--- a/README.md
+++ b/README.md
@@ -301,10 +301,10 @@ Gridline is currently distributed **unsigned** — it doesn't pay for code-signi
 - **macOS — "Gridline is damaged and can't be opened":** remove the quarantine flag macOS attaches to downloaded apps, then launch normally:
 
   ```bash
-  xattr -dr com.apple.quarantine /Applications/Gridline.app
+  sudo xattr -dr com.apple.quarantine /Applications/Gridline.app
   ```
 
-  You need to re-run this after **every upgrade** (each freshly-downloaded copy gets re-quarantined).
+  (`sudo` is required — some files inside the bundle are read-only, so removing the flag needs admin rights.) Re-run after **every upgrade** — each freshly-downloaded copy gets re-quarantined.
 - **Windows:** on the SmartScreen prompt, click **More info** → **Run anyway**.
 - **Linux:** no warning — install and run normally.
 
diff --git a/ROADMAP.md b/ROADMAP.md
index b0dfc73..8002253 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -9,7 +9,7 @@ This file is the **source of truth** for what Gridline is building. [AGENTS.md](
 ## ✅ Shipped (0.7.9)
 
 - **macOS Finder launch fix** — the local store opens under the OS app-data directory instead of a cwd-relative `gridline.db` (Finder/LaunchServices launches run with cwd `/`, so the old path made the app silently exit with a Rust panic before the UI started).
-- **macOS ad-hoc code signing** — bundles are signed at build time (`bundle.macOS.signingIdentity "-"`, hardened runtime off), replacing the Xcode linker-only signature that macOS treated as unsigned ("damaged and can't be opened", silent Finder refusal). Users still get a one-time Gatekeeper prompt; README documents the `xattr -dr com.apple.quarantine` workaround.
+- **macOS ad-hoc code signing** — bundles are signed at build time (`bundle.macOS.signingIdentity "-"`, hardened runtime off), replacing the Xcode linker-only signature that macOS treated as unsigned ("damaged and can't be opened", silent Finder refusal). Users still get a one-time Gatekeeper prompt; README documents the `sudo xattr -dr com.apple.quarantine` workaround.
 - **Vendored OpenSSL for `ssh2`** — the release binary no longer links an absolute Homebrew `/opt/homebrew/.../libssl.3.dylib` path (dyld aborted on machines without it).
 - **Version bump** 0.7.8 → **0.7.9**.