docs(macos): installing the unsigned build on macOS 14 / 15+, and the minimum macOS version (#1594, #1591)

README.md

@@ -151,12 +151,20 @@ flatpak install --user ./Querya-Desktop-*-linux.flatpak
 Download the Windows installer (`.exe`) or portable archive (`.zip`) from [Releases](https://github.com/QueryaHub/Querya-Desktop/releases). Run the setup to automatically register `.sql` and `.sqlite` file associations.
 
 ### macOS
-Download the universal `.dmg` from [Releases](https://github.com/QueryaHub/Querya-Desktop/releases), mount the disk image, and drag **Querya Desktop** into your `Applications` folder.
-
-> **Unsigned builds:** If Gatekeeper blocks the app after installation, run:
-> ```bash
-> xattr -cr "/Applications/Querya Desktop.app"
-> ```
+Requires **macOS 10.15 (Catalina) or later**; the app is a universal build (Apple silicon and Intel).
+
+1. Download `Querya-Desktop-<version>-macos.dmg` from [Releases](https://github.com/QueryaHub/Querya-Desktop/releases), open it and drag **Querya Desktop** into `Applications`.
+2. Start it from `Applications`, not from the disk image or `Downloads`: there macOS runs a temporary read-only copy, and the in-app update cannot replace it.
+
+> **Unsigned builds.** A release built without the Developer ID secrets is ad-hoc signed, and Gatekeeper blocks its first launch:
+> - **macOS 14 and earlier:** Control-click (right-click) the app → **Open** → **Open**.
+> - **macOS 15 and later:** that no longer works. Try to open the app once, then go to **System Settings → Privacy & Security**, find "Querya Desktop was blocked…" and click **Open Anyway**.
+> - Or clear the quarantine flag in Terminal:
+>   ```bash
+>   xattr -dr com.apple.quarantine "/Applications/Querya Desktop.app"
+>   ```
+>
+> The unsigned build is not sandboxed and behaves like the signed one (connections, SSH keys, extensions, MCP, in-app updates); only this first-launch step differs. See [macOS signing](docs/macos-signing.md).
 
 ---
 

docs/macos-signing.md

@@ -141,6 +141,28 @@ If you later add plugins that require microphone, camera, or other protected res
 
 ---
 
+## Running an unsigned build
+
+Without the signing secrets the release ships an ad-hoc signed app. It has no App Sandbox (see Entitlements above), so it can reach `~/.querya`, `~/.ssh`, saved SQLite paths, run extensions under `sandbox-exec`, serve MCP and update itself, like the signed build. What differs is Gatekeeper:
+
+| macOS | First launch |
+|---|---|
+| 14 and earlier | Control-click the app → **Open** → **Open**. |
+| 15 and later | Control-click → Open no longer bypasses Gatekeeper. Open the app once, then **System Settings → Privacy & Security → Open Anyway**. |
+| any | `xattr -dr com.apple.quarantine "/Applications/Querya Desktop.app"` |
+
+Move the app to `/Applications` before the first launch. Started from `~/Downloads` or the disk image, macOS runs it through App Translocation (a read-only copy at a random path): the in-app update refuses to run there and points to the release page instead (#1587).
+
+Related: secrets are stored in the login keychain, so they work without `keychain-access-groups` and without a provisioning profile (#1586); an update must carry the same Team ID as the installed app when the installed app is signed (#1588).
+
+## Minimum macOS version
+
+`MACOSX_DEPLOYMENT_TARGET` is **10.15** in every Xcode configuration, and `LSMinimumSystemVersion` follows it. That is also the highest minimum among the macOS plugins in use (`file_selector_macos` and `url_launcher_macos` need 10.15; `package_info_plus`, `device_info_plus` and the vendored `refresh_rate` need 10.14). Raising it needs no plugin change, lowering it is not possible.
+
+Rendering above 60 Hz on a ProMotion display needs **macOS 14** or later (`refresh_rate`, see [motion and high refresh](motion-and-high-refresh.md)); on older versions the app runs at 60 Hz.
+
+---
+
 ## References
 
 - Flutter: [Build and release a macOS app](https://docs.flutter.dev/deployment/macos)