Add README with install and Gatekeeper bypass instructions

README.md

@@ -0,0 +1,74 @@
+# FocusFixer
+
+Native macOS menu-bar utility that fixes a long-standing multi-display bug: after clicking a
+window on one screen, keyboard focus can stay on a window on another screen, so typing goes to
+the wrong place. Download, unzip, run — grant Accessibility when prompted (see `CLAUDE.md` for
+how the app is built).
+
+## Installing from a downloaded release
+
+Grab `FocusFixer-vX.Y.Z.zip` from the
+[releases page](https://gitea.sttlab.eu/stt/focus-fixer/releases), unzip it, and drag
+`FocusFixer.app` to `/Applications`.
+
+The app is signed with a self-signed identity (`sttlab-apps`), not an Apple Developer ID —
+there's no paid Apple account behind this project. macOS's Gatekeeper doesn't trust that
+signature by default, so on first launch of a version downloaded from a browser (which
+macOS marks with a quarantine flag) you'll likely see it refuse to open, or ask to move it to
+the bin. Pick **one** of the two options below to get past that — you don't need both.
+
+### Option 1 — Trust the `sttlab-apps` certificate
+
+This tells your Mac to trust anything signed by this specific certificate going forward, so
+you won't need to repeat this for future versions of the app (as long as it keeps being signed
+with the same identity).
+
+1. Get the certificate: `sttlab-apps.cer` (ask for it, or export it yourself if you have
+   access to the machine it was created on: `security find-certificate -c "sttlab-apps" -p
+   > sttlab-apps.cer`).
+2. Import it into your login keychain:
+   ```bash
+   security import sttlab-apps.cer -k ~/Library/Keychains/login.keychain-db
+   ```
+3. Trust it, but **only** for code signing (not as a general root CA):
+   ```bash
+   security add-trusted-cert -r trustRoot -p codeSign \
+     -k ~/Library/Keychains/login.keychain-db sttlab-apps.cer
+   ```
+   macOS will prompt for your login password — that's it asking permission to change
+   keychain trust settings, not this command asking for a password directly.
+4. Open `FocusFixer.app` normally (double-click, or `open /Applications/FocusFixer.app`).
+
+### Option 2 — Bypass Gatekeeper for this app only
+
+No trust changes, no certificate needed — just tells macOS to stop flagging this specific
+app. You'll need to repeat this for each new version you download (the quarantine flag is
+set per downloaded file).
+
+Either:
+
+- Right-click `FocusFixer.app` in Finder → **Open** → **Open** again in the confirmation
+  dialog. (Regular double-click won't offer this the first time; right-click → Open does.)
+
+Or, from a terminal:
+
+```bash
+xattr -dr com.apple.quarantine /Applications/FocusFixer.app
+```
+
+(`-r` because it's a bundle — the quarantine flag can be set on files inside it too, not just
+the top-level `.app`.)
+
+Both achieve the same result: the app opens. Option 1 is the better choice if you expect to
+download future versions and don't want to repeat the bypass each time; Option 2 is faster
+for a one-off.
+
+## Granting Accessibility permission
+
+FocusFixer needs Accessibility access to watch clicks and reassert focus — it can't do
+anything useful without it. On first launch it prompts for the grant automatically; if you
+miss the prompt or need to re-grant it later, go to **System Settings → Privacy & Security →
+Accessibility** and enable FocusFixer there.
+
+FocusFixer has no Dock icon and no regular window — look for its icon in the menu bar. That
+menu is also where you toggle it on/off and enable/disable launching at login.