docs: document unsigned-installer bypass + prebuilt download path (#22)

First v0.1.3 desktop download on Apple Silicon hit the "SQLRite
is damaged and can't be opened" Gatekeeper dialog — a misleading
variant of the unsigned-app warning that shows up specifically
for (quarantined) + (ad-hoc signed) binaries on recent macOS.
The old release-body text only warned about the gentler
"unidentified developer" message and offered a right-click-Open
workaround that doesn't work for the "damaged" variant.

Replace that with the actual fix (`xattr -cr /Applications/SQLRite.app`)
across three surfaces so nobody else hits it cold:

  - `.github/workflows/release.yml` — the template for future
    desktop releases: Linux / macOS / Windows-specific bypass
    steps, plus an explanation of why "damaged" happens (Apple
    Silicon requires a signature, Tauri ad-hoc signs, quarantine
    + ad-hoc trips a stricter Gatekeeper path).

  - `README.md` — the Desktop app section now lists the seven
    installer artifacts per platform, links to the latest GitHub
    Release, and calls out the unsigned-installer friction
    inline.

  - `docs/desktop.md` — new "Installing a prebuilt binary"
    section covering the full download table, per-platform
    bypass commands, and a paragraph on why macOS uses
    "damaged" instead of "unidentified developer". Updated the
    "Running from source" section to reflect `bundle.active`
    now defaulting to `true` (Phase 6e) and that icons are
    pre-generated + committed.

  - `docs/getting-started.md` — adds a "Don't want to build from
    source?" pointer to the latest desktop release.

  - `docs/_index.md` — surfaces `desktop.md` in the "Start here"
    list so people arriving at the developer guide find the
    downloads + bypass info without drilling.

Also backfilled the already-published `sqlrite-desktop-v0.1.3`
release body with the new text via `gh release edit` so the URL
anyone hits today has the workaround (done separately, not part
of this commit).

Phase 6.1 (code signing) removes the need for any of this — this
commit just makes the gap before 6.1 lands less miserable.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: joaoh82

.github/workflows/release.yml

@@ -385,9 +385,34 @@ jobs:
           tagName: sqlrite-desktop-v${{ needs.detect.outputs.version }}
           releaseName: Desktop v${{ needs.detect.outputs.version }}
           releaseBody: |
-            SQLRite desktop app — unsigned installers for Linux (AppImage + deb), macOS (dmg, aarch64), Windows (msi).
+            SQLRite desktop app — unsigned installers. This release wave ships:
 
-            **⚠️ Unsigned installers**: macOS shows "SQLRite can't be opened because it is from an unidentified developer" — right-click → Open → Open to bypass. Windows SmartScreen blocks on first run — click "More info" → "Run anyway". Code signing lands in Phase 6.1.
+            - **Linux**: `.AppImage` + `.deb` (Debian/Ubuntu) + `.rpm` (Fedora/RHEL), x86_64
+            - **macOS**: `.dmg` + raw `.app.tar.gz`, Apple Silicon (aarch64). Intel Macs not supported yet — tracked as a Phase 6e follow-up (universal dmg).
+            - **Windows**: `.msi` + `.exe` (NSIS installer), x86_64
+
+            ### ⚠️ Unsigned installer warnings
+
+            Installers aren't code-signed yet (Phase 6.1 wires up Apple Developer ID + Windows code-signing). First-launch warnings to expect:
+
+            **macOS — "SQLRite is damaged and can't be opened" or "unidentified developer":**
+
+            ```bash
+            xattr -cr /Applications/SQLRite.app
+            ```
+
+            This strips the `com.apple.quarantine` attribute your browser attached on download. macOS Gatekeeper shows "damaged" (not the gentler "unidentified developer") because Tauri ad-hoc signs the binary — Apple Silicon *requires* a signature, even an ad-hoc one, but quarantined ad-hoc signatures trip a stricter Gatekeeper path. The app is fine; the signature just isn't from a registered Apple Developer ID.
+
+            **Windows — SmartScreen "Windows protected your PC":**
+
+            Click "More info" → "Run anyway".
+
+            **Linux — AppImage:**
+
+            ```bash
+            chmod +x SQLRite_*_amd64.AppImage
+            ./SQLRite_*_amd64.AppImage
+            ```
 
             See the umbrella release [v${{ needs.detect.outputs.version }}](../../releases/tag/v${{ needs.detect.outputs.version }}) for the full changelog.
           releaseDraft: false

README.md

@@ -65,7 +65,20 @@ A cross-platform Tauri 2.0 + Svelte 5 desktop GUI ships alongside the REPL (see
 
 ![SQLRite Desktop](<images/SQLRite - Desktop.png> "The SQLRite desktop app")
 
-Launch it with `cd desktop && npm install && npm run tauri dev`. The header's New… / Open… / Save As… buttons cover the file lifecycle; the query editor has a live line-number gutter, `⌘/` (Ctrl+/) SQL comment toggle, and selection-aware Run (highlight a statement to run just that one).
+**Prebuilt installers** — download from the [latest desktop release](https://github.com/joaoh82/rust_sqlite/releases/latest):
+
+| Platform | Files |
+|---|---|
+| Linux x86_64 | `.AppImage`, `.deb` (Debian/Ubuntu), `.rpm` (Fedora/RHEL) |
+| macOS Apple Silicon | `.dmg`, raw `.app.tar.gz` *(Intel Macs not supported yet — universal dmg is a follow-up)* |
+| Windows x86_64 | `.msi`, `.exe` (NSIS) |
+
+> ⚠️ **Installers are unsigned** until Phase 6.1 wires up Apple Developer ID + Windows code-signing certs. First-launch friction to expect:
+> - **macOS**: "SQLRite is damaged" or "unidentified developer" → run `xattr -cr /Applications/SQLRite.app` once to strip the quarantine attribute, then it opens normally. The app is fine; Tauri ad-hoc signs every macOS binary (Apple Silicon requires a signature), but quarantined ad-hoc signatures trip a stricter Gatekeeper path with the scary "damaged" wording.
+> - **Windows**: SmartScreen → click "More info" → "Run anyway".
+> - **Linux AppImage**: `chmod +x SQLRite_*.AppImage` before launching.
+
+**From source** — `cd desktop && npm install && npm run tauri dev`. The header's New… / Open… / Save As… buttons cover the file lifecycle; the query editor has a live line-number gutter, `⌘/` (Ctrl+/) SQL comment toggle, and selection-aware Run (highlight a statement to run just that one).
 
 ### Developer guide
 

docs/_index.md

@@ -6,6 +6,7 @@ A small, hand-written guide to the SQLRite codebase — how it's structured, how
 
 - [Getting started](getting-started.md) — install toolchain, build, run the REPL, your first `CREATE TABLE`
 - [Using SQLRite](usage.md) — complete REPL / SQL / meta-command reference
+- [Desktop app](desktop.md) — downloads, unsigned-installer bypass steps, and the Tauri architecture
 - [Smoke test](smoke-test.md) — step-by-step walkthrough to sanity-check REPL + desktop app after any non-trivial change
 - [Architecture](architecture.md) — high-level layer diagram and module map
 - [Design decisions](design-decisions.md) — the "why" behind the major choices

docs/desktop.md

@@ -8,7 +8,54 @@ Lives under [`desktop/`](../desktop/).
 
 *Screenshot: the default three-pane layout — sidebar with tables and schema on the left, query editor with line numbers up top, result grid below. Header carries New… / Open… / Save As… and shows the active database path.*
 
-## Running it
+## Installing a prebuilt binary
+
+Since Phase 6e, every release pushes installers to a per-version GitHub Release. Grab the right artifact for your platform from the [latest desktop release](https://github.com/joaoh82/rust_sqlite/releases/latest):
+
+| Platform | Artifact | Notes |
+|---|---|---|
+| Linux x86_64 | `SQLRite_<ver>_amd64.AppImage` | `chmod +x` then run directly; bundles its own libs |
+| Linux x86_64 | `SQLRite_<ver>_amd64.deb` | Debian / Ubuntu — `sudo dpkg -i` |
+| Linux x86_64 | `SQLRite-<ver>-1.x86_64.rpm` | Fedora / RHEL / openSUSE — `sudo rpm -i` |
+| macOS aarch64 | `SQLRite_<ver>_aarch64.dmg` | Apple Silicon only (M1/M2/M3/M4) |
+| macOS aarch64 | `SQLRite_aarch64.app.tar.gz` | Raw `.app` bundle — for users who don't want the dmg |
+| Windows x86_64 | `SQLRite_<ver>_x64_en-US.msi` | Windows Installer package |
+| Windows x86_64 | `SQLRite_<ver>_x64-setup.exe` | NSIS installer, smaller footprint |
+
+Intel Macs and Linux aarch64 are [tracked as follow-ups](roadmap.md#phase-6e-desktop-publish) — for now those platforms build from source.
+
+### Unsigned-installer warnings
+
+Installers ship **unsigned** until Phase 6.1 wires up Apple Developer ID + Windows code-signing certs. Expect one of these on first launch:
+
+#### macOS — "SQLRite is damaged and can't be opened"
+
+Or the gentler "unidentified developer" dialog on older macOS versions. One-time fix:
+
+```bash
+xattr -cr /Applications/SQLRite.app
+```
+
+Then double-click normally. Point `xattr` at wherever the `.app` lives if you haven't moved it to `/Applications` yet.
+
+**Why "damaged" instead of "unidentified developer"?** Apple Silicon *requires* every Mach-O binary to carry a signature — even an ad-hoc one (`codesign --sign -`), which is what Tauri applies by default. When you download the dmg, your browser attaches `com.apple.quarantine` as an extended attribute. On recent macOS, the combination of (quarantined) + (ad-hoc signed) trips a stricter Gatekeeper code path that reports "damaged" instead of the milder unsigned-app flow. Stripping the quarantine attribute with `xattr -cr` takes Gatekeeper out of the loop. The app isn't actually corrupt — the error message just isn't honest about what it's complaining about.
+
+Once Phase 6.1 lands notarization, this bypass won't be needed; macOS will trust the binary on first launch.
+
+#### Windows — SmartScreen "Windows protected your PC"
+
+Click **More info** → **Run anyway**. SmartScreen remembers your choice, so subsequent launches are clean.
+
+#### Linux — AppImage won't run
+
+```bash
+chmod +x SQLRite_<ver>_amd64.AppImage
+./SQLRite_<ver>_amd64.AppImage
+```
+
+`.deb` and `.rpm` packages don't have this step — they install through the system package manager and get the executable bit from the package metadata.
+
+## Running from source
 
 Two prerequisites beyond the engine's toolchain:
 
@@ -25,13 +72,15 @@ npm run tauri dev
 
 That builds the Rust side (incremental after the first time), boots the Vite dev server on port 1420, and opens a native window pointing at it. Hot reload works for the Svelte side; Rust changes trigger a rebuild.
 
-For a one-off release build:
+For a one-off release build that produces installers for your local platform:
 
 ```bash
 npm run tauri build
 ```
 
-Bundling is disabled in [`tauri.conf.json`](../desktop/src-tauri/tauri.conf.json) by default — flip `bundle.active` to `true` and plug in real app icons when you want to produce an installer.
+[`tauri.conf.json`](../desktop/src-tauri/tauri.conf.json) ships with `bundle.active: true` since Phase 6e, so this builds a full set of platform-native installers (`.dmg` on macOS, `.AppImage` / `.deb` / `.rpm` on Linux, `.msi` / `.exe` on Windows) under `desktop/src-tauri/target/release/bundle/`.
+
+Icons are pre-generated and committed at `desktop/src-tauri/icons/`. If you swap the source `icon.png`, re-run `npx tauri icon src-tauri/icons/icon.png` from `desktop/` and commit the regenerated `.icns` / `.ico` / size-specific PNGs. CI doesn't re-run this — the commit is the source of truth.
 
 ## Architecture
 

docs/getting-started.md

@@ -110,7 +110,11 @@ rust_sqlite/
 
 ## Running the desktop app
 
-A Tauri 2.0 desktop GUI lives under [`desktop/`](../desktop/). It needs Node.js in addition to the Rust toolchain:
+A Tauri 2.0 desktop GUI lives under [`desktop/`](../desktop/).
+
+**Don't want to build from source?** Prebuilt installers (`.dmg`, `.msi`, `.AppImage`, `.deb`, `.rpm`) land on every release at [the latest desktop release page](https://github.com/joaoh82/rust_sqlite/releases/latest). They're unsigned — see [the desktop docs](desktop.md#unsigned-installer-warnings) for the one-line Gatekeeper / SmartScreen bypasses.
+
+**From source** — needs Node.js in addition to the Rust toolchain:
 
 ```bash
 cd desktop