README: end-user install + getting-started

Add a download-and-run path for non-developers: per-OS install from the
Releases page (desktop app vs CLI binary, with the Gatekeeper / SmartScreen
one-time override each needs), a step-by-step getting-started with the
IMAP/SMTP connection table and Thunderbird / Apple Mail notes, and an
unofficial-&-unsigned disclaimer up top. Reframe the old cargo-centric
sections as 'Build from source', and document that body search covers
downloaded messages while metadata search covers the whole mailbox.

README.md

@@ -7,6 +7,12 @@ encryption transparently.
 
 Available as a **CLI** and a **desktop GUI** (Tauri).
 
+> ⚠️ **Unofficial & unsigned.** TutaBridge is an independent project — not
+> affiliated with, endorsed by, or supported by Tuta. It logs into your account
+> and decrypts your mail locally, outside Tuta's official apps; use it at your
+> own risk. The released binaries are **not code-signed**, so macOS and Windows
+> warn on first launch — see [Install](#install) for how to get past that.
+
 ## Features
 
 - **IMAP + SMTP** servers on localhost (TLS), so any standard mail client works.
@@ -22,6 +28,96 @@ Available as a **CLI** and a **desktop GUI** (Tauri).
   encrypted `.eml.enc` files. Subsequent launches load from cache and only fetch
   the delta, so the client is usable immediately.
 - **Complete mailbox backup** to portable `.eml` files (see below).
+- **Full mailbox + search** — the whole account is listed over IMAP and
+  searchable by subject, sender, date and (full-text) body from your mail client.
+
+## Install
+
+Download the latest build from the [**Releases**](../../releases) page. Every
+platform ships two flavours:
+
+- a **desktop app** — a normal double-click GUI, recommended for most people;
+- a **CLI binary** — a single executable you run from a terminal, for
+  headless / server use.
+
+| Platform | Desktop app | CLI binary |
+|----------|-------------|------------|
+| **macOS** (Apple Silicon) | `TutaBridge_*_universal.dmg` | `tutabridge-macos-arm64` |
+| **Windows** (x64) | `TutaBridge_*_x64-setup.exe` (or `.msi`) | `tutabridge-windows-x86_64.exe` |
+| **Linux** (x64) | `*.AppImage` / `*.deb` / `*.rpm` | `tutabridge-linux-x86_64` |
+
+Because the binaries aren't signed, each OS needs a one-time nudge to run them:
+
+### macOS
+
+Open the `.dmg` and drag TutaBridge to Applications. On first launch macOS says
+the app "cannot be opened because the developer cannot be verified" — **right-click
+the app → Open → Open**, which whitelists it permanently. (Plain double-click
+won't offer the override.)
+
+### Windows
+
+Run the `.exe` / `.msi`. SmartScreen shows "Windows protected your PC" — click
+**More info → Run anyway**.
+
+### Linux
+
+```bash
+chmod +x TutaBridge_*_amd64.AppImage && ./TutaBridge_*_amd64.AppImage
+# or:  sudo dpkg -i TutaBridge_*_amd64.deb     (Debian/Ubuntu)
+# or:  sudo rpm -i  TutaBridge-*.x86_64.rpm     (Fedora/RHEL)
+```
+
+### CLI binary (any OS)
+
+The CLI files have **no extension**, so double-clicking does nothing useful (your
+OS may even open them in a text editor). Run them from a terminal:
+
+```bash
+chmod +x tutabridge-macos-arm64                          # make it executable
+xattr -d com.apple.quarantine tutabridge-macos-arm64     # macOS only: clear Gatekeeper
+./tutabridge-macos-arm64                                  # run
+```
+
+## Getting started
+
+1. **Launch** the app (or run the CLI). On first run it asks for your Tuta email,
+   then your password and TOTP code if there's no saved session. The session is
+   stored in your OS keychain, so later launches resume automatically.
+2. TutaBridge shows the **local connection details**. Note the **bridge password** —
+   this is generated by TutaBridge for local IMAP/SMTP auth and is **not** your
+   Tuta password. (CLI: it's printed in the logs; GUI: it's on the main screen.)
+3. **Add the account** in your mail client with these settings:
+
+   | | Server | Port | Security | Auth |
+   |---|---|---|---|---|
+   | **IMAP** (incoming) | `127.0.0.1` | `1143` | SSL/TLS | normal password |
+   | **SMTP** (outgoing) | `127.0.0.1` | `1025` | SSL/TLS | normal password |
+
+   - **Username**: your Tuta email
+   - **Password**: the **bridge password** from step 2
+   - Accept the **self-signed certificate** when the client prompts.
+
+Keep TutaBridge running while you use your mail client — it's the local server
+the client talks to.
+
+### Client-specific notes
+
+- **Thunderbird**: add the account manually (don't let auto-config probe public
+  servers). Set both servers to `127.0.0.1` with SSL/TLS + "Normal password",
+  and accept the certificate exception on first connect.
+- **Apple Mail**: add an "Other Mail Account", then in *Server Settings* turn
+  **off** "Automatically manage connection settings" so you can pin host
+  `127.0.0.1`, the ports above, and TLS.
+
+### Notes & limitations
+
+- **Search** runs in your mail client and is honest: subject / sender / date
+  search covers the whole mailbox; **body** (full-text) search covers messages
+  whose body has been **downloaded**. Keep "every message body offline" enabled
+  (or raise the offline-bodies limit) for full-mailbox body search.
+- **Self-signed cert** is expected — the bridge only listens on `127.0.0.1`, so
+  traffic never leaves your machine.
 
 ## Architecture
 
@@ -43,50 +139,33 @@ Tuta API  ←──  Syncer (background)  ──→  MailStore (in-memory)  ←
 The storage encryption key is derived from your Tuta session, so there's no extra
 password to manage; the cache is encrypted at rest.
 
-## Build
+## Build from source
+
+Requires the Rust toolchain and the `tuta-repo` submodule
+(`git clone --recursive`, or `git submodule update --init --recursive`).
 
 ```bash
 cargo build                      # CLI + core
 cargo build -p tutabridge-core   # core library only
+cargo run                        # run the CLI from source
+./dev.sh                         # GUI in dev mode (cargo tauri dev)
 ```
 
-GUI (Tauri + React) in dev mode:
+## Files & locations
 
-```bash
+Config and cache live under your platform's app-data directory — on macOS
-./dev.sh                         # cargo tauri dev — opens the desktop app
+`~/Library/Application Support/tutabridge/`:
-```
-
-## Running the bridge
-
-CLI:
-
-```bash
-cargo run            # or: ./target/debug/tutabridge
-```
-
-On first run it prompts for your Tuta email; the session is then stored in the OS
-keychain so later launches resume without a password (TOTP is prompted when
-required). The bridge prints the local connection details:
-
-```
-IMAP server: 127.0.0.1:1143 (SSL/TLS)
-SMTP server: 127.0.0.1:1025 (SSL/TLS)
-Username:    <your tuta email>
-Password:    <bridge password — shown in the logs / GUI>
-```
-
-Point your mail client at those, accept the self-signed certificate, and use the
-**bridge password** (not your Tuta password) for IMAP/SMTP auth.
-
-Config and cache live under
-`~/Library/Application Support/tutabridge/` (macOS):
 
 ```
 config.toml          account + ports + bridge_password + sync_limit
-store.db             SQLCipher metadata index
+store.db             SQLCipher metadata + full-text body index
 mails/<id>.eml.enc   per-mail encrypted bodies
 ```
 
+`sync_limit` controls how many recent message **bodies** are kept offline; the
+full mailbox is always listed and metadata-searchable regardless. Set it to `0`
+(or tick "keep every message body offline" in the GUI) to download everything.
+
 ## Backup
 
 Export **every** email to a folder of plain `.eml` files — one file per message,