docs: give Linux and Windows equal footing; hyphenate every shortcut label

Documentation:

- The GUI is stated as the primary interface on every platform; the
  earlier claim that Linux is CLI-first is gone.
- §2.1 becomes "Installing Rectify" with macOS, Linux, and Windows
  subsections, each opening with the public clone of this repository and
  the per-session launch commands.
- §3.1's Linux section reaches the depth the Windows one already had:
  python3-venv (stock Debian/Ubuntu fails `python3 -m venv` without it),
  libxcb packages, QT_QPA_PLATFORM=xcb as the Wayland fallback, a
  PYTHONPATH wrapper for launching from any directory, and a .desktop
  entry. States plainly that Linux has no packaged deliverable.
- §2.15 lists all three settings paths; §2.3 covers the platform-specific
  Open dialog and HEIC thumbnails; Finder/Mac-only phrasing generalized.
- README gains a matching Linux section, and its "pre-built executables"
  section no longer promises Linux and Windows binaries that were never
  published.

Keyboard notation:

- Both documents print the macOS symbols throughout, with one
  substitution rule (Ctrl for ⌘, Alt for ⌥) stated in the guide's §2
  preamble and under each shortcut table.
- Every combination is joined with a hyphen on all platforms — ⌘-O,
  Ctrl-O, ⇧-⌘-Z, ⌥-⇧ — rather than Apple's tight ⌘O, whose glyphs have
  side bearings too small to separate them from the next character.
- shortcuts.py carries this in SECTIONS and _mac_translate; gui.py's
  tooltip modifier follows. Display labels only: the QKeySequence
  bindings keep Qt's "Ctrl+X" syntax and are untouched.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

README.md

@@ -5,17 +5,22 @@ Perspective correction for paintings and rectangular objects. Takes a photo of a
 ## Quick start
 
 ```bash
-# From source
+# From source (Linux/macOS)
 python3 -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
 python -m rectify --gui photo.jpg
 ```
 
-Or download a pre-built executable from the releases page — no Python required.
+On macOS there is also a ready-to-run signed app — see
+[Installation methods](#installation-methods).
 
 ## Setup from source
 
+The repository is public — no account, login, or permission is needed to clone
+it. It can also be browsed, and downloaded as a ZIP, at
+<https://git.andykopra.com/ack/rectify/>.
+
 ```bash
 git clone https://git.andykopra.com/ack/rectify.git
 cd rectify
@@ -24,11 +29,66 @@ source .venv/bin/activate
 pip install -r requirements.txt
 ```
 
+The GUI is the primary interface on every platform; the CLI drives the same
+engine without a window, for scripting and batch work.
+
 **Platform notes:**
-- **Linux:** May need `sudo apt install libxcb-xinerama0 libxcb-cursor0` for Qt
-- **macOS:** Works with Homebrew or python.org Python
+- **Linux:** See [Run from source on Linux](#run-from-source-on-linux) below
+- **macOS:** Works with Homebrew or python.org Python (Apple silicon and Intel).
+  For day-to-day use, install `Rectify.dmg` instead of running from source
 - **Windows:** See [Run from source on Windows](#run-from-source-on-windows) below
 
+### Run from source on Linux
+
+Linux is the platform Rectify is developed on, so it is the best-tested of the
+three. There is no packaged download the way macOS has its `.dmg` — you run it
+from source. Development happens on Ubuntu with GNOME; any current distribution
+with Python 3.10+, `git`, and a graphical desktop works, and only the `apt`
+command lines below are Ubuntu-specific.
+
+Start with the public clone in [Setup from source](#setup-from-source) above —
+`git clone https://git.andykopra.com/ack/rectify.git`, no account needed.
+
+**Debian/Ubuntu need one package before the venv step** — without it,
+`python3 -m venv` fails with `ensurepip is not available`:
+
+```bash
+sudo apt install python3-venv python3-pip
+```
+
+Then follow [Setup from source](#setup-from-source) above and launch:
+
+```bash
+source .venv/bin/activate
+python -m rectify --gui photo.jpg
+```
+
+**If something goes wrong:**
+
+- *PySide6 fails to start* — install the X11/XCB libraries Qt needs:
+  `sudo apt install libxcb-xinerama0 libxcb-cursor0`
+- *Window sizing, cursors, or tooltips look wrong (or the app won't start) in a
+  Wayland session* — force the X11 path with
+  `QT_QPA_PLATFORM=xcb python -m rectify --gui`. Worth trying first for any
+  display oddity, especially on NVIDIA drivers
+- *HEIC files show a generic icon in the Open dialog* — thumbnails come from your
+  desktop, not from Rectify (which reads them fine either way). Run
+  `scripts/install_heic_thumbnailer.sh` once; it self-skips if your system
+  already handles HEIC
+
+**Launching from anywhere.** The venv's own interpreter can run Rectify directly,
+so a one-line wrapper (saved as `~/bin/rectify`, `chmod +x`) avoids activating
+the venv each time and keeps relative filenames working:
+
+```sh
+#!/bin/sh
+exec env PYTHONPATH="$HOME/rectify" "$HOME/rectify/.venv/bin/python" -m rectify "$@"
+```
+
+For a clickable icon, point a `~/.local/share/applications/rectify.desktop`
+entry at that wrapper with `Exec=/home/YOUR_USER/bin/rectify --gui %f`. Per-user
+settings are written to `~/.local/share/<username>/Rectify/settings.json`.
+
 ### Run from source on Windows
 
 Every dependency ships a Windows wheel — PySide6 bundles Qt and `pillow-heif`
@@ -38,8 +98,9 @@ dialog, with image thumbnails.
 
 **Prerequisites:** Python 3.10–3.13 from
 [python.org](https://www.python.org/downloads/windows/) — tick **"Add python.exe
-to PATH"** in the installer. `git` is optional; you can download the repository
-as a ZIP instead.
+to PATH"** in the installer. `git` is optional; the public repository can be
+downloaded as a ZIP from <https://git.andykopra.com/ack/rectify/> instead. Either
+way, no account or permission is needed.
 
 **PowerShell:**
 
@@ -86,8 +147,9 @@ each behaves:
 
 1. Opening a **HEIC/HEIF** photo from an iPhone.
 2. Display scaling at 125% and 150% — menu, panel, and control sizing.
-3. The keyboard shortcuts (press **Shift+Alt** for the overlay) — all use Ctrl
-   on Windows.
+3. The keyboard shortcuts — press **Shift-Alt** for the overlay. On Windows,
+   Ctrl and Alt stand in for the ⌘ and ⌥ used in the
+   [shortcut table](#keyboard-shortcuts) below.
 4. Saving to a folder whose path contains spaces.
 5. Building an executable with `pyinstaller rectify.spec` (see
    [Building a standalone executable](#building-a-standalone-executable)) and
@@ -113,8 +175,8 @@ The GUI provides:
 - **Color correct** — recover accurate color when a neutral reference is in the frame. Tick **Color correct**, then choose a reference mode — **Gray** or **White** (neither is preselected; pick the one that matches your reference). Click the swatch, then click the reference area in the left image; Rectify averages a small square around that point — its side length in pixels is the **Sample size** (1 = just the clicked pixel; default 10 = a 10×10 block) — and white-balances the output so the patch becomes neutral. **Gray** mode (a gray card, or any surface you trust as neutral gray) couples color and exposure: the **Reflectance** value is the target tone the patch is mapped to, in the photographer's unit — default **18%** (standard middle-gray card); set it to your card's rating (e.g. 12%) or adjust to taste (adjustable 3–80%). **White** mode (a white sheet or other white reference) *decouples* them: it neutralizes the color cast while keeping the patch's own brightness — so white is **not** forced to maximum and anything brighter (a highlight, a lamp) keeps its headroom — and a centered **Brightness** slider (0 = unchanged) then raises or lowers the whole result independently. The swatch shows the sampled color and turns red if the spot is too bright or too dark to use; a 2-pixel-wide red border marks the sampled region, with the averaged pixels just inside it. Sample the card outside the artwork — it's read from the source image but the correction is applied to the result, in every mode. **The measured gray is sticky:** shoot one reference frame with a gray card, pick it once, then for other images taken under the same light just tick Color correct and they reuse that gray automatically (no need for a card in every shot). Reusing a gray takes a frozen *snapshot* — re-picking the reference later won't silently change images that already borrowed it. **Left-click** the swatch to pick a gray on the current image; **right-click** it to re-apply the last-used gray (handy when an image already has its own value you want to replace). An image you picked on keeps its own measurement and shows the red marker; one using a borrowed gray shows the color in the swatch but no marker
 - **Corner dragging** — click and drag corners; arrow keys for 1-pixel nudge
 - **Edge dragging** — click near an edge and drag to move it perpendicular to itself; arrow keys for fine nudging
-- **Ctrl+Left-Click** — moves the nearest movable point (a quad corner in Extract mode, a keystone-line arrow handle in Lines mode) to the click position. Designed for precision adjustment while zoomed in; the cursor becomes a crosshair whenever Ctrl is held so you know the gesture is armed
-- **Alt+Left-Click ×2** — draws a red antialiased "alternate-line" annotation between two clicked points. Useful for sketching what auto-detection *should* produce in screenshots and bug reports. A dashed rubber-band tracks the cursor between the first and second click; multiple annotations accumulate; Esc clears them all (and any temporary marks in general); a new image load also clears.
+- **⌘-Left-Click** — moves the nearest movable point (a quad corner in Extract mode, a keystone-line arrow handle in Lines mode) to the click position. Designed for precision adjustment while zoomed in; the cursor becomes a crosshair whenever ⌘ is held so you know the gesture is armed
+- **⌥-Left-Click ×2** — draws a red antialiased "alternate-line" annotation between two clicked points. Useful for sketching what auto-detection *should* produce in screenshots and bug reports. A dashed rubber-band tracks the cursor between the first and second click; multiple annotations accumulate; Esc clears them all (and any temporary marks in general); a new image load also clears.
 - **Alignment indicator** — edges turn blue when their endpoints are vertically or horizontally aligned (same x or y value); the same blue/green indicator applies to keystone-line pairs in Lines mode
 - **Subregion selection** — click in the center of the quad and drag to reposition; scroll wheel while dragging to resize. Use with Peel in to extract individual subjects from multi-subject photos
 - **Peel stack** — Peel in/out to strip successive frame layers; left panel always shows the original with mapped-back overlay
@@ -122,35 +184,45 @@ The GUI provides:
 - **Keystone correction** — remove vertical and/or horizontal keystone distortion using line pairs. Draw one or two pairs of lines on features known to be parallel (e.g., building edges, door frames); the correction makes them parallel in the output. Arrow-shaped handles distinguish lines from the quad overlay
 - **Stretch** (Transform → Lines) — keystone correction straightens converging lines but can't recover how wide the result should be relative to its height (the lines carry no scale, and there's no reference rectangle as in Quad mode). The **Stretch** slider is a by-eye correction for that residual width-to-height relationship: 1.00 leaves the width unchanged, above 1.00 widens, below narrows. Shown only in Lines mode; remembered per image
 - **Saving** — one **Save** button with an **Increment** checkbox. The default output name is the source image's name with **`_rectified`** appended (e.g. `hotel.png` → `hotel_rectified.png`), so a save never overwrites the input. With Increment **off**, Save opens a dialog (pre-filled with that default) where the extension you type picks the format (png/jpg/jpeg/tiff/tif/webp/bmp; an unsupported type is rejected with the supported list). With Increment **on**, Save writes the next auto-numbered file (`hotel_rectified_1`, `hotel_rectified_2`, …) with one click — no dialog. Both modes share the last-used folder and type; folder, type, and the Increment setting persist across sessions
-- **Undo/redo** — Ctrl+Z / Ctrl+Shift+Z for corner adjustments (keyboard only)
+- **Undo/redo** — ⌘-Z / ⌘-Shift-Z for corner adjustments (keyboard only)
 - **Drag and drop** — drop an image file onto the window
 - **Before/after** — hold Space to compare
 - **Tooltips** — hover any control for a short explanation in a readable boxed popup; toolbar buttons also show their keyboard shortcut. Fully translated in all three interface languages
-- **Settings persistence** — all preferences (including your last save folder, file type, and Increment mode), window layout, and per-image state (corners, keystone lines, bow value, Stretch value, color-correction sample, plus any manual override of the aspect ratio) cached for every image you've touched. Switch between images with Ctrl+↑/↓ while preparing a batch; come back to any image and your tuning is intact. Saved on close and restored on next launch
+- **Settings persistence** — all preferences (including your last save folder, file type, and Increment mode), window layout, and per-image state (corners, keystone lines, bow value, Stretch value, color-correction sample, plus any manual override of the aspect ratio) cached for every image you've touched. Switch between images with ⌘-↑/↓ while preparing a batch; come back to any image and your tuning is intact. Saved on close and restored on next launch
 
 ### Keyboard shortcuts
 
 | Shortcut | Action |
 |----------|--------|
-| Ctrl+O | Open image |
-| Ctrl+S | Save (opens the dialog, or writes the next auto-numbered file when Increment is on) |
-| Ctrl+D | Reset (re-detect from scratch) |
-| Ctrl+R | Re-open the current file (re-read pixels from disk; per-image cache preserves corners, keystone pairs, bow) |
-| Ctrl+↓ / Ctrl+↑ | Load next / previous image in the current directory (wraps around) |
-| Ctrl+Z | Undo |
-| Ctrl+Shift+Z | Redo |
+| ⌘-O | Open image |
+| ⌘-S | Save (opens the dialog, or writes the next auto-numbered file when Increment is on) |
+| ⌘-D | Reset (re-detect from scratch) |
+| ⌘-R | Re-open the current file (re-read pixels from disk; per-image cache preserves corners, keystone pairs, bow) |
+| ⌘-↓ / ⌘-↑ | Load next / previous image in the current directory (wraps around) |
+| ⌘-Z | Undo |
+| ⌘-Shift-Z | Redo |
 | + or = | Peel in |
 | - | Peel out |
 | Space (hold) | Before/after comparison |
 | Arrow keys | Nudge selected corner, edge, or whole quad |
 | Mouse wheel | Zoom (or adjust element with Shift or left-button held) |
-| Shift + wheel | Adjust quad element under cursor (corner, edge, or whole quad) |
-| Ctrl + Left-click | Snap the nearest point (corner or line endpoint) to the click position |
-| Alt + Left-click ×2 | Draw a red alternate-line annotation between two clicks |
+| Shift-wheel | Adjust quad element under cursor (corner, edge, or whole quad) |
+| ⌘-Left-click | Snap the nearest point (corner or line endpoint) to the click position |
+| ⌥-Left-click ×2 | Draw a red alternate-line annotation between two clicks |
 | Esc | Clear temporary marks (annotations, etc.) |
 | Right-click | Reset zoom on clicked panel |
 | 0 | Reset zoom on both panels |
-| Shift+Alt (hold) | Show keyboard-shortcut overlay (centered popup) |
+| Shift-⌥ (hold) | Show keyboard-shortcut overlay (centered popup) |
+
+Keys are written with the macOS symbols **⌘** (Command) and **⌥** (Option).
+**On Linux and Windows, read Ctrl for ⌘ and Alt for ⌥** — ⌘-O is Ctrl-O, ⌘-click
+is Ctrl-click, Shift-⌥ is Shift-Alt. That substitution is the whole difference;
+no shortcut exists on one system and not another. Two macOS-only details: ⌃-click
+— the physical Control key — is just how a one-button mouse delivers a
+right-click, while ⌘-click is the snap gesture; and combinations containing Shift
+are shown in Apple's order on screen (⇧-⌘-Z, ⌥-⇧), the same keys as the
+⌘-Shift-Z and Shift-⌥ above. Rectify labels its own tooltips and overlay for the
+system you are on.
 
 The same shortcut table is printed by `rectify -k` (also `--keyboard`), so you can read it without opening the GUI.
 
@@ -184,33 +256,19 @@ The GUI always runs the automatic two-pass sweep — both detection strategies,
 
 ## Installation methods
 
-### Pre-built executables
+### Pre-built application
 
-Download the executable for your platform from the releases page. No Python installation is required.
+**macOS** is the only platform with a published build: a signed, notarized
+`Rectify.dmg` that needs no Python installation.
 
-**Linux:**
-```bash
-chmod +x rectify
-./rectify --gui photo.jpg
-```
-
-**macOS:**
-- Download `Rectify.dmg`, open it, and drag `Rectify.app` to your Applications folder
+- Open the `.dmg` and drag `Rectify.app` to your Applications folder
 - Double-click `Rectify.app` to launch — it opens the GUI with a file dialog
 - You can also drag an image file onto the `Rectify.app` icon in Finder or the Dock to open it directly
-- Or download the command-line executable and run from Terminal:
-```bash
-chmod +x rectify
-./rectify --gui photo.jpg
-```
 
-**Windows:**
-- Download `rectify.exe`
-- Double-click to launch (opens the GUI with a file dialog)
-- Or run from Command Prompt / PowerShell:
-```powershell
-.\rectify.exe --gui photo.jpg
-```
+**Linux and Windows** run from source ([above](#setup-from-source)). You can
+build a standalone executable yourself if you want one — see
+[Building a standalone executable](#building-a-standalone-executable) — but it is
+not required, and running from source is the normal path on both.
 
 ### Building a standalone executable