protonmail-bridge-agent-skill 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luke Ramsden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,4 @@
+This project is an independent, unofficial tool and is not affiliated with,
+endorsed by, or sponsored by Proton AG. "Proton" and "Proton Mail" are
+trademarks of Proton AG. Proton Mail Bridge is required and is available
+from Proton at https://proton.me/mail/bridge.

package/README.md

@@ -0,0 +1,89 @@
+# Proton Mail Bridge Agent Skill
+
+Give coding agents read-only access to a Proton Mail inbox — with instant full-text search across the entire archive — through the local [Proton Mail Bridge](https://proton.me/mail/bridge) IMAP server.
+
+The skill ships `pmail`, a zero-dependency Python CLI (stdlib only) that talks IMAP to Bridge on `127.0.0.1:1143`, maintains a local SQLite+FTS5 cache of the whole mailbox, and serves bm25-ranked keyword search with snippets in well under a second (measured against an ~80k-message archive where Bridge's own server-side search takes ~15s and returns unranked UIDs).
+
+## Requirements
+
+- macOS (credentials are stored in the system Keychain)
+- [Proton Mail Bridge](https://proton.me/mail/bridge) installed, signed in, and running
+- Python 3.9+ (no packages to install — stdlib only)
+
+## Install
+
+Install with the Skills CLI:
+
+```bash
+npx skills add lukeramsden/protonmail-bridge-agent-skill@protonmail-bridge
+```
+
+Install globally for all supported agents:
+
+```bash
+npx skills add lukeramsden/protonmail-bridge-agent-skill@protonmail-bridge -g -a '*' -y
+```
+
+List the skills available in this repository without installing:
+
+```bash
+npx skills add lukeramsden/protonmail-bridge-agent-skill --list
+```
+
+## Quick start
+
+```bash
+./doctor                              # verify all runtime dependencies
+./pmail setup                         # account email + Bridge password -> Keychain
+./pmail sync --all --full             # backfill the whole archive (resumable)
+./pmail search "invoice"              # ranked full-text search, sub-second
+./pmail list INBOX --unseen
+./pmail read 34655
+./pmail save-attach 34655 1
+```
+
+All commands print JSON on stdout; progress and errors go to stderr.
+
+## What the skill provides
+
+- **Full-archive FTS search** — SQLite FTS5 with bm25 ranking and match snippets; phrases, `OR`/`NOT`, and filters (`--from`, `--since`, `--unseen`, `--mailbox`)
+- **Resumable backfill** — cursor-persisted batches; interrupt and resume freely; automatic wipe/resync if Bridge's UIDVALIDITY changes
+- **Cache-first reads** — `list`, `read`, and `search` serve from the local cache with an implicit incremental sync at most once per minute; `--live` and `--no-sync` escape hatches
+- **Attachment download** — `save-attach` extracts parts to the cache's attachments directory
+- **Self-diagnostics** — `doctor` checks python/sqlite, credentials, Bridge reachability + login, cache health, and disk space, printing an actionable fix per failure
+- **Read-only by construction** — only `BODY.PEEK` and `EXAMINE` on the wire; no STORE/COPY/EXPUNGE/APPEND anywhere, so reading mail never sets `\Seen`
+
+## Privacy and security
+
+- Everything is local: pmail only ever connects to the Bridge listener on your own machine
+- The Bridge password lives in macOS Keychain (service `pmail-bridge`); the only on-disk config is your account email in `~/.local/share/pmail/config.json` (mode 600)
+- The cache (`~/.local/share/pmail/`) is fully rebuildable — delete it anytime and re-run `pmail sync --all --full`
+
+## Repository layout
+
+```text
+skills/
+└── protonmail-bridge/
+    ├── SKILL.md    # agent-facing instructions and command reference
+    ├── pmail       # the CLI (Python stdlib only, executable)
+    └── doctor      # runtime dependency checker
+```
+
+## License
+
+This repository is available under the MIT License. See [NOTICE](NOTICE) for trademark attribution.
+
+## Install as a pi package
+
+```bash
+pi install npm:protonmail-bridge-agent-skill
+```
+
+## Releasing
+
+```bash
+npm version patch|minor|major && git push --follow-tags
+```
+
+The `v*` tag triggers `.github/workflows/publish.yml`, which publishes to npm
+with OIDC trusted publishing and provenance.

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "protonmail-bridge-agent-skill",
+  "version": "1.0.0",
+  "description": "Agent skill: read-only Proton Mail access via Proton Mail Bridge IMAP with a local SQLite FTS cache (pmail CLI, Python stdlib only).",
+  "license": "MIT",
+  "author": "lukeramsden",
+  "repository": { "type": "git", "url": "git+https://github.com/lukeramsden/protonmail-bridge-agent-skill.git" },
+  "homepage": "https://github.com/lukeramsden/protonmail-bridge-agent-skill#readme",
+  "bugs": "https://github.com/lukeramsden/protonmail-bridge-agent-skill/issues",
+  "keywords": [ "pi-package", "pi-skill", "pi-coding-agent", "agent-skill", "protonmail-bridge" ],
+  "pi": { "skills": [ "./skills" ] },
+  "bin": { "pmail": "skills/protonmail-bridge/pmail" },
+  "files": [ "skills", "README.md", "LICENSE", "NOTICE" ],
+  "scripts": { "verify": "python3 -m py_compile skills/*/pmail skills/*/doctor" }
+}

package/skills/protonmail-bridge/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: protonmail-bridge
+description: Read, list, and full-text search email from a Proton Mail account via the local Proton Mail Bridge IMAP server and a fast local SQLite cache. Use for checking the inbox, reading messages, searching the entire mailbox by keyword/sender, or downloading attachments. Read-only; cannot send or modify mail. Requires the Proton Mail Bridge app running locally.
+---
+
+# Proton Mail Bridge (`pmail`)
+
+Read-only email access through Proton Mail Bridge (IMAP on 127.0.0.1:1143) with a
+local SQLite+FTS5 cache for instant full-text search across the whole mailbox.
+
+The CLI is `pmail` in this skill's directory. Run commands from the skill
+directory as `./pmail <command> ...` (or invoke it by its absolute path).
+
+All data commands print **JSON on stdout**; progress and errors go to stderr.
+Pipe through `jq` when you need to reshape output.
+
+**If pmail fails or behaves unexpectedly, run the doctor script first:**
+
+```bash
+./doctor
+```
+
+It checks every runtime dependency (python/sqlite, account configuration,
+Keychain credentials, Bridge reachability + login, cache database, disk space)
+and prints an actionable fix for each failure. If it reports Bridge
+unreachable, stop and ask the user to start the Proton Mail Bridge app —
+do not retry in a loop.
+
+## First-time setup
+
+Run `./doctor` — it reports anything missing. On a fresh machine it will ask
+you to run `./pmail setup`, which prompts for the Proton account email and the
+Bridge-generated password (Bridge app > Mailbox details), verifies them against
+Bridge, stores the password in macOS Keychain, and writes the account email to
+`~/.local/share/pmail/config.json`.
+
+## Commands
+
+```bash
+pmail mailboxes                        # folders + labels, message counts, cached counts
+pmail list [mailbox] [--limit N] [--unseen] [--live]
+pmail read <uid> [--mailbox M] [--max-chars N] [--raw]
+pmail search <words...> [--mailbox M] [--from X] [--since YYYY-MM-DD] [--unseen] [--limit N] [--live]
+pmail sync [--mailbox M | --all] [--full] [--skip-all-mail]
+pmail status                           # cache state per mailbox, db size
+pmail save-attach <uid> <index> [--mailbox M]   # index comes from `read` output
+```
+
+## Behavior notes
+
+- **Mailboxes**: `INBOX`, `Archive`, `Sent`, `Drafts`, `Trash`, `Spam`, `Starred`,
+  `All Mail` (everything), plus user labels under `Labels/<name>` and folders
+  under `Folders/<name>`. `search` defaults to `All Mail`; `list`/`read` default
+  to `INBOX`.
+- **Cache-first**: `list`, `read`, and `search` run an implicit incremental sync
+  (at most once per minute) and then serve from the local cache. Use `--live` to
+  force a server query or `--no-sync` to skip the implicit sync.
+- **Backfill**: `pmail sync --mailbox "All Mail" --full` caches the entire mailbox
+  (resumable if interrupted; roughly 300 msg/s through Bridge). Until it has run,
+  `search` only covers what has been synced so far; use `--live` for an
+  uncached server-side search.
+- **Search syntax**: cached search is SQLite FTS5 — plain words are AND-ed,
+  `"quoted phrases"` and `OR`/`NOT` work. Results are bm25-ranked with snippets
+  (sub-second over an ~80k-message archive). FTS matches whole tokens;
+  `--live` IMAP search matches substrings and also scans headers, so hit counts
+  differ slightly between the two.
+- **Bodies**: most real-world mail is HTML-only; pmail indexes the stripped text
+  of the HTML part so search covers those messages too.
+- **Read-only guarantee**: bodies are fetched with BODY.PEEK and mailboxes are
+  opened read-only, so reading mail here never marks it `\Seen`.
+- **UIDs are per-mailbox**: a UID from a `search` on `All Mail` must be read
+  back with `--mailbox "All Mail"`.
+
+## Credentials
+
+The Bridge password is read from macOS Keychain (service `pmail-bridge`) or
+`$PMAIL_PASSWORD`; the account email comes from `$PMAIL_ACCOUNT` or the config
+written by `pmail setup`. To store or rotate credentials:
+
+```bash
+pmail setup        # prompts for account email + Bridge password, verifies login
+```
+
+Bridge rotates its local password when it re-authenticates — if logins start
+failing, get the new password from Bridge > Mailbox details and re-run setup.
+
+## Data and configuration
+
+- Cache: `~/.local/share/pmail/mail.db` (SQLite, WAL mode) +
+  `~/.local/share/pmail/attachments/`. Fully rebuildable from Bridge — safe to
+  delete; the next `pmail sync --all --full` repopulates it. A UIDVALIDITY
+  change on the server triggers an automatic per-mailbox wipe and resync.
+- The full-archive cache can grow to several GB (raw bodies incl. HTML are
+  stored).
+- Env overrides: `PMAIL_HOST` (127.0.0.1), `PMAIL_PORT` (1143),
+  `PMAIL_ACCOUNT`, `PMAIL_PASSWORD`, `PMAIL_DATA` (cache directory).
+- The first command after a minute of quiet runs a fast incremental sync
+  (~1-2s); subsequent commands within the minute are instant. `--no-sync`
+  skips this; `--live` bypasses the cache entirely.

package/skills/protonmail-bridge/doctor

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""doctor - diagnose pmail's runtime dependencies.
+
+Checks every layer the pmail CLI needs, in order, and prints PASS/FAIL with
+an actionable fix for each failure. Exit code 0 if all hard checks pass,
+1 otherwise. Safe to run anytime: it changes nothing (except creating the
+data directory if missing).
+
+Run: ./doctor from the skill directory.
+"""
+
+import os
+import shutil
+import socket
+import sqlite3
+import ssl
+import subprocess
+import sys
+import tempfile
+
+IMAP_HOST = os.environ.get("PMAIL_HOST", "127.0.0.1")
+IMAP_PORT = int(os.environ.get("PMAIL_PORT", "1143"))
+KEYCHAIN_SERVICE = "pmail-bridge"
+DATA_DIR = os.path.expanduser(os.environ.get("PMAIL_DATA", "~/.local/share/pmail"))
+DB_PATH = os.path.join(DATA_DIR, "mail.db")
+CONFIG_PATH = os.path.join(DATA_DIR, "config.json")
+
+def configured_account():
+    """$PMAIL_ACCOUNT, else the account written by `pmail setup`. May be None."""
+    a = os.environ.get("PMAIL_ACCOUNT")
+    if a:
+        return a
+    try:
+        import json
+        with open(CONFIG_PATH) as f:
+            return json.load(f).get("account")
+    except (OSError, ValueError):
+        return None
+
+ACCOUNT = configured_account()
+
+failures = 0
+
+def check(ok, label, fix=None, info=None):
+    global failures
+    mark = "PASS" if ok else "FAIL"
+    line = f"[{mark}] {label}"
+    if ok and info:
+        line += f"  ({info})"
+    print(line)
+    if not ok:
+        failures += 1
+        if fix:
+            print(f"       fix: {fix}")
+    return ok
+
+def note(text):
+    print(f"       {text}")
+
+# 1. python version (pmail needs 3.9+ for imaplib's timeout parameter)
+v = sys.version_info
+check(v >= (3, 9), f"python3 version", info=".".join(map(str, v[:3])),
+      fix="install Python 3.9+ (e.g. `brew install python3`)")
+
+# 2. sqlite3 with FTS5 (the search index needs it)
+try:
+    db = sqlite3.connect(":memory:")
+    db.execute("CREATE VIRTUAL TABLE t USING fts5(x)")
+    check(True, "sqlite3 FTS5 extension", info=sqlite3.sqlite_version)
+except Exception as e:
+    check(False, "sqlite3 FTS5 extension", fix=f"python3 sqlite3 lacks FTS5: {e}")
+
+# 3. macOS `security` CLI (Keychain access)
+check(shutil.which("security") is not None, "`security` CLI on PATH",
+      fix="expected on macOS; if missing, set PMAIL_PASSWORD instead")
+
+# 4. account configured, then credentials available; never print the secret
+acct_ok = check(ACCOUNT is not None, "account configured",
+                info="$PMAIL_ACCOUNT" if os.environ.get("PMAIL_ACCOUNT") else "pmail setup config",
+                fix="run `pmail setup` (stores only the email address in "
+                    f"{CONFIG_PATH}), or set PMAIL_ACCOUNT")
+pw = os.environ.get("PMAIL_PASSWORD")
+cred_source = "PMAIL_PASSWORD env var" if pw else None
+if not pw and acct_ok:
+    r = subprocess.run(
+        ["security", "find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", ACCOUNT, "-w"],
+        capture_output=True, text=True)
+    if r.returncode == 0 and r.stdout.strip():
+        pw = r.stdout.strip()
+        cred_source = f"Keychain (service '{KEYCHAIN_SERVICE}')"
+check(pw is not None, "Bridge password available", info=cred_source,
+      fix="run `pmail setup` to store the Bridge password in Keychain "
+          "(Bridge app > Mailbox details), or set PMAIL_PASSWORD")
+
+# 5. Bridge TCP port reachable
+try:
+    with socket.create_connection((IMAP_HOST, IMAP_PORT), timeout=5):
+        check(True, f"Bridge listening on {IMAP_HOST}:{IMAP_PORT}")
+        bridge_up = True
+except OSError as e:
+    check(False, f"Bridge listening on {IMAP_HOST}:{IMAP_PORT}",
+          fix=f"start the Proton Mail Bridge app ({e})")
+    bridge_up = False
+
+# 6. full IMAP handshake: STARTTLS + LOGIN + LIST
+if bridge_up and pw:
+    try:
+        import imaplib
+        ctx = ssl.create_default_context()
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+        m = imaplib.IMAP4(IMAP_HOST, IMAP_PORT, timeout=15)
+        banner = m.welcome.decode(errors="replace")
+        m.starttls(ctx)
+        m.login(ACCOUNT or "", pw)
+        typ, boxes = m.list()
+        n = len(boxes or [])
+        m.logout()
+        check(True, "IMAP STARTTLS + login + LIST",
+              info=f"{n} mailboxes; {banner.split(' - ')[0].lstrip('* OK ')}")
+    except imaplib.IMAP4.error as e:
+        check(False, "IMAP STARTTLS + login + LIST",
+              fix=f"Bridge rejected login: {e}. Passwords rotate when Bridge "
+                  f"re-auths — get the current one from Bridge > Mailbox details "
+                  f"and run `pmail setup`")
+    except (OSError, ssl.SSLError) as e:
+        check(False, "IMAP STARTTLS + login + LIST", fix=f"handshake failed: {e}")
+elif not bridge_up:
+    note("skipping IMAP handshake (Bridge unreachable)")
+else:
+    note("skipping IMAP handshake (no credentials)")
+
+# 7. data directory present and writable
+try:
+    os.makedirs(DATA_DIR, exist_ok=True)
+    with tempfile.TemporaryFile(dir=DATA_DIR):
+        pass
+    check(True, "data directory writable", info=DATA_DIR)
+except OSError as e:
+    check(False, "data directory writable",
+          fix=f"check permissions on {DATA_DIR} ({e})")
+
+# 8. cache database opens, has schema, and is consistent (informational)
+if os.path.exists(DB_PATH):
+    try:
+        db = sqlite3.connect(f"file:{DB_PATH}?mode=ro", uri=True, timeout=10)
+        counts = dict(db.execute("SELECT mailbox, COUNT(*) FROM messages GROUP BY mailbox"))
+        total = sum(counts.values())
+        sync = db.execute("SELECT MAX(synced_at) FROM sync_state").fetchone()[0]
+        db.close()
+        size_mb = os.path.getsize(DB_PATH) / 1e6
+        check(True, "cache database readable",
+              info=f"{total:,} messages in {len(counts)} mailboxes, {size_mb:,.0f} MB")
+        if sync:
+            from datetime import datetime, timezone
+            age_h = (__import__("time").time() - sync) / 3600
+            note(f"last sync: {datetime.fromtimestamp(sync, timezone.utc):%Y-%m-%d %H:%M} UTC "
+                 f"({age_h:.1f}h ago)")
+        if total == 0:
+            note("cache is empty - run `pmail sync --all --full` to backfill")
+    except sqlite3.Error as e:
+        check(False, "cache database readable",
+              fix=f"database looks corrupt ({e}); it is fully rebuildable: "
+                  f"delete {DB_PATH} and run `pmail sync --all --full`")
+else:
+    note(f"no cache database yet at {DB_PATH}")
+    note("run `pmail sync --all --full` to build it (search/list work live until then)")
+
+# 9. free disk space for cache growth (informational)
+free_gb = shutil.disk_usage(DATA_DIR).free / 1e9
+check(free_gb > 1, "free disk space", info=f"{free_gb:.0f} GB available",
+      fix="free up disk space; the full-archive cache needs several GB")
+
+print()
+if failures:
+    print(f"doctor: {failures} check(s) FAILED - see fixes above")
+    sys.exit(1)
+print("doctor: all checks passed")

package/skills/protonmail-bridge/pmail

@@ -0,0 +1,844 @@
+#!/usr/bin/env python3
+"""pmail - read ProtonMail via the local Proton Mail Bridge IMAP server.
+
+Zero dependencies (Python 3 stdlib only). Strictly read-only: bodies are
+fetched with BODY.PEEK, mailboxes are opened with EXAMINE, and no command
+ever stores flags, moves, or deletes mail.
+
+Cache: ~/.local/share/pmail/mail.db (SQLite + FTS5, rebuildable).
+Credentials: macOS Keychain (service "pmail-bridge") or the PMAIL_PASSWORD
+env var; account email from PMAIL_ACCOUNT or `pmail setup`. Override the
+server with PMAIL_HOST / PMAIL_PORT.
+
+All data commands print JSON on stdout; progress and errors go to stderr.
+"""
+
+import argparse
+import getpass
+import imaplib
+import json
+import os
+import re
+import sqlite3
+import ssl
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+from email import policy
+from email.parser import BytesParser
+from email.utils import parsedate_to_datetime
+
+IMAP_HOST = os.environ.get("PMAIL_HOST", "127.0.0.1")
+IMAP_PORT = int(os.environ.get("PMAIL_PORT", "1143"))
+KEYCHAIN_SERVICE = "pmail-bridge"
+DATA_DIR = os.path.expanduser(os.environ.get("PMAIL_DATA", "~/.local/share/pmail"))
+DB_PATH = os.path.join(DATA_DIR, "mail.db")
+ATTACH_DIR = os.path.join(DATA_DIR, "attachments")
+CONFIG_PATH = os.path.join(DATA_DIR, "config.json")
+
+def account():
+    """Proton account email: $PMAIL_ACCOUNT, else the config written by setup."""
+    a = os.environ.get("PMAIL_ACCOUNT")
+    if a:
+        return a
+    try:
+        with open(CONFIG_PATH) as f:
+            a = json.load(f).get("account")
+            if a:
+                return a
+    except (OSError, json.JSONDecodeError):
+        pass
+    die("no account configured - run `pmail setup` first (or set PMAIL_ACCOUNT)")
+
+DEFAULT_LIMIT = 20
+SYNC_STALENESS = 60      # seconds; implicit sync runs at most this often
+QUICK_SEED = 500         # newest N UIDs synced on every incremental sync
+BACKFILL_BATCH = 200     # UID window per backfill step (cursor persisted per step)
+FETCH_CHUNK = 100        # messages per IMAP FETCH command
+
+# ---------------------------------------------------------------- utilities
+
+def die(msg, code=1):
+    print(f"pmail: error: {msg}", file=sys.stderr)
+    sys.exit(code)
+
+def log(msg):
+    print(msg, file=sys.stderr)
+
+def emit(obj):
+    print(json.dumps(obj, indent=2, ensure_ascii=False))
+
+def quote_mailbox(name):
+    return '"' + name.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+def iso(ts):
+    if ts is None:
+        return None
+    return datetime.fromtimestamp(ts, timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+# ------------------------------------------------------------- credentials
+
+def get_password():
+    pw = os.environ.get("PMAIL_PASSWORD")
+    if pw:
+        return pw
+    r = subprocess.run(
+        ["security", "find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", account(), "-w"],
+        capture_output=True, text=True)
+    if r.returncode != 0:
+        die(f"no credentials: store the Bridge password with `pmail setup`, "
+            f"or set PMAIL_PASSWORD (Keychain service '{KEYCHAIN_SERVICE}', account '{account()}')")
+    return r.stdout.rstrip("\n")
+
+# ------------------------------------------------------------------- IMAP
+
+def connect():
+    """Connect + login. Dies with an actionable message if Bridge is down."""
+    ctx = ssl.create_default_context()
+    ctx.check_hostname = False
+    ctx.verify_mode = ssl.CERT_NONE
+    try:
+        m = imaplib.IMAP4(IMAP_HOST, IMAP_PORT, timeout=30)
+        m.starttls(ctx)
+    except (OSError, ssl.SSLError) as e:
+        die(f"cannot reach Proton Mail Bridge at {IMAP_HOST}:{IMAP_PORT} - "
+            f"is the Proton Mail Bridge app running? ({e})")
+    try:
+        m.login(account(), get_password())
+    except imaplib.IMAP4.error as e:
+        die(f"Bridge login failed for {account()}: {e}. "
+            f"Get the current password from Bridge > Mailbox details and run `pmail setup`.")
+    return m
+
+def try_connect():
+    """Like connect(), but returns None instead of dying (for implicit sync)."""
+    try:
+        return connect()
+    except SystemExit:
+        return None
+
+UID_RE = re.compile(rb"UID (\d+)")
+FLAGS_RE = re.compile(rb"FLAGS \(([^)]*)\)")
+
+def parse_fetch_meta(header):
+    uid_m = UID_RE.search(header)
+    flags_m = FLAGS_RE.search(header)
+    return (int(uid_m.group(1)) if uid_m else None,
+            flags_m.group(1).decode(errors="replace") if flags_m else "")
+
+def iter_fetch(data):
+    """Yield (uid, flags, literal_bytes) from an imaplib FETCH response.
+    Gluon appends 'UID n' AFTER the literal, so combine each tuple's header
+    with the trailing bytes item that follows it."""
+    for i, item in enumerate(data):
+        if isinstance(item, tuple):
+            blob = item[0]
+            if i + 1 < len(data) and isinstance(data[i + 1], bytes):
+                blob += data[i + 1]
+            uid, flags = parse_fetch_meta(blob)
+            if uid is not None and isinstance(item[1], bytes):
+                yield uid, flags, item[1]
+
+def fetch_full(m, uids):
+    """UID FETCH (FLAGS BODY.PEEK[]) for the given UIDs, in chunks.
+    Yields (uid, flags, raw_bytes)."""
+    for i in range(0, len(uids), FETCH_CHUNK):
+        chunk = uids[i:i + FETCH_CHUNK]
+        typ, data = m.uid("FETCH", ",".join(map(str, chunk)), "(FLAGS BODY.PEEK[])")
+        if typ != "OK":
+            log(f"warning: FETCH failed for chunk starting at UID {chunk[0]}, skipping")
+            continue
+        yield from iter_fetch(data)
+
+def fetch_headers(m, uids):
+    """UID FETCH (FLAGS BODY.PEEK[HEADER.FIELDS ...]) -> list of summary dicts."""
+    out = []
+    fields = "(FLAGS BODY.PEEK[HEADER.FIELDS (FROM TO CC SUBJECT DATE)])"
+    for i in range(0, len(uids), FETCH_CHUNK):
+        chunk = uids[i:i + FETCH_CHUNK]
+        typ, data = m.uid("FETCH", ",".join(map(str, chunk)), fields)
+        if typ != "OK":
+            continue
+        for uid, flags, hdr_bytes in iter_fetch(data):
+            msg = BytesParser(policy=policy.default).parsebytes(hdr_bytes)
+            out.append({
+                "uid": uid,
+                "date": iso(parse_date(msg.get("Date"))),
+                "from": safe_str(msg.get("From")),
+                "to": safe_str(msg.get("To")),
+                "subject": safe_str(msg.get("Subject")),
+                "flags": flags,
+            })
+    return out
+
+# ----------------------------------------------------------------- parsing
+
+def safe_str(header):
+    if header is None:
+        return ""
+    try:
+        return str(header)
+    except Exception:
+        return str(header.raw) if hasattr(header, "raw") else ""
+
+def parse_date(header):
+    if header is None:
+        return None
+    try:
+        dt = parsedate_to_datetime(str(header))
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return int(dt.timestamp())
+    except Exception:
+        return None
+
+def part_text(part):
+    try:
+        content = part.get_content()
+        if isinstance(content, bytes):
+            return content.decode("utf-8", errors="replace")
+        return content or ""
+    except Exception:
+        try:
+            payload = part.get_payload(decode=True)
+            return payload.decode("utf-8", errors="replace") if payload else ""
+        except Exception:
+            return ""
+
+def parse_message(raw):
+    """Parse a raw RFC822 message into a cache record."""
+    msg = BytesParser(policy=policy.default).parsebytes(raw)
+    text_parts, html_parts, attachments = [], [], []
+    for part in msg.walk():
+        if part.get_content_maintype() == "multipart":
+            continue
+        ctype = part.get_content_type()
+        filename = part.get_filename()
+        if part.get_content_disposition() == "attachment" or filename:
+            try:
+                payload = part.get_payload(decode=True)
+            except Exception:
+                payload = None
+            attachments.append({
+                "index": len(attachments) + 1,
+                "name": filename or "unnamed",
+                "mime": ctype,
+                "size": len(payload) if payload else 0,
+            })
+        elif ctype == "text/plain":
+            text_parts.append(part_text(part))
+        elif ctype == "text/html":
+            html_parts.append(part_text(part))
+    body_text = "\n".join(p for p in text_parts if p).strip()
+    body_html = "\n".join(p for p in html_parts if p).strip()
+    if not body_text and body_html:
+        # ~97% of real mail is HTML-only; index the stripped text so FTS works
+        body_text = html_to_text(body_html)
+    else:
+        body_text = INVISIBLES_RE.sub("", body_text)
+    return {
+        "message_id": safe_str(msg.get("Message-ID")),
+        "date": parse_date(msg.get("Date")),
+        "from_addr": safe_str(msg.get("From")),
+        "to_addr": safe_str(msg.get("To")),
+        "cc": safe_str(msg.get("Cc")),
+        "subject": safe_str(msg.get("Subject")),
+        "size": len(raw),
+        "body_text": body_text,
+        "body_html": body_html,
+        "attachments": json.dumps(attachments, ensure_ascii=False),
+    }
+
+HTML_TAG_RE = re.compile(r"<[^>]+>")
+HTML_STRIP_RE = re.compile(r"(?is)<(script|style|head)[^>]*>.*?</\1>|<!--.*?-->")
+INVISIBLES_RE = re.compile(
+    "[\u00ad\u034f\u200b-\u200f\u202a-\u202e\u2060\ufeff]")  # zero-width/format junk
+
+def html_to_text(html):
+    txt = HTML_STRIP_RE.sub(" ", html)   # drop style/script/head bodies + comments
+    txt = HTML_TAG_RE.sub(" ", txt)
+    txt = INVISIBLES_RE.sub("", txt)
+    txt = re.sub(r"[ \t]+", " ", txt)
+    txt = re.sub(r"\n\s*\n\s*\n+", "\n\n", txt)
+    for ent, ch in (("&amp;", "&"), ("&lt;", "<"), ("&gt;", ">"),
+                    ("&quot;", '"'), ("&#39;", "'"), ("&nbsp;", " ")):
+        txt = txt.replace(ent, ch)
+    return txt.strip()
+
+# ------------------------------------------------------------------- cache
+
+SCHEMA = """
+PRAGMA journal_mode=WAL;
+CREATE TABLE IF NOT EXISTS messages (
+  mailbox TEXT NOT NULL,
+  uid INTEGER NOT NULL,
+  message_id TEXT,
+  date INTEGER,
+  from_addr TEXT,
+  to_addr TEXT,
+  cc TEXT,
+  subject TEXT,
+  flags TEXT DEFAULT '',
+  size INTEGER,
+  body_text TEXT,
+  body_html TEXT,
+  attachments TEXT DEFAULT '[]',
+  synced_at INTEGER,
+  PRIMARY KEY (mailbox, uid)
+);
+CREATE VIRTUAL TABLE IF NOT EXISTS mail_fts USING fts5(
+  subject, from_addr, to_addr, body_text,
+  content='messages', content_rowid='rowid'
+);
+CREATE TRIGGER IF NOT EXISTS messages_ai AFTER INSERT ON messages BEGIN
+  INSERT INTO mail_fts(rowid, subject, from_addr, to_addr, body_text)
+  VALUES (new.rowid, new.subject, new.from_addr, new.to_addr, new.body_text);
+END;
+CREATE TRIGGER IF NOT EXISTS messages_ad AFTER DELETE ON messages BEGIN
+  INSERT INTO mail_fts(mail_fts, rowid, subject, from_addr, to_addr, body_text)
+  VALUES ('delete', old.rowid, old.subject, old.from_addr, old.to_addr, old.body_text);
+END;
+CREATE TRIGGER IF NOT EXISTS messages_au AFTER UPDATE ON messages BEGIN
+  INSERT INTO mail_fts(mail_fts, rowid, subject, from_addr, to_addr, body_text)
+  VALUES ('delete', old.rowid, old.subject, old.from_addr, old.to_addr, old.body_text);
+  INSERT INTO mail_fts(rowid, subject, from_addr, to_addr, body_text)
+  VALUES (new.rowid, new.subject, new.from_addr, new.to_addr, new.body_text);
+END;
+CREATE TABLE IF NOT EXISTS sync_state (
+  mailbox TEXT PRIMARY KEY,
+  uidvalidity INTEGER,
+  backfill_cursor INTEGER DEFAULT 0,
+  uidnext INTEGER,
+  synced_at INTEGER
+);
+"""
+
+UPSERT = """
+INSERT INTO messages
+  (mailbox, uid, message_id, date, from_addr, to_addr, cc, subject,
+   flags, size, body_text, body_html, attachments, synced_at)
+VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+ON CONFLICT(mailbox, uid) DO UPDATE SET
+  message_id=excluded.message_id, date=excluded.date,
+  from_addr=excluded.from_addr, to_addr=excluded.to_addr, cc=excluded.cc,
+  subject=excluded.subject, flags=excluded.flags, size=excluded.size,
+  body_text=excluded.body_text, body_html=excluded.body_html,
+  attachments=excluded.attachments, synced_at=excluded.synced_at
+"""
+
+def open_db():
+    os.makedirs(DATA_DIR, exist_ok=True)
+    db = sqlite3.connect(DB_PATH)
+    db.executescript(SCHEMA)
+    return db
+
+def insert_record(db, box, rec, uid, flags):
+    db.execute(UPSERT, (
+        box, uid, rec["message_id"], rec["date"], rec["from_addr"], rec["to_addr"],
+        rec["cc"], rec["subject"], flags, rec["size"], rec["body_text"],
+        rec["body_html"], rec["attachments"], int(time.time())))
+
+def cached_count(db, box):
+    return db.execute("SELECT COUNT(*) FROM messages WHERE mailbox=?", (box,)).fetchone()[0]
+
+def get_sync_row(db, box):
+    return db.execute(
+        "SELECT uidvalidity, backfill_cursor, uidnext, synced_at FROM sync_state WHERE mailbox=?",
+        (box,)).fetchone()
+
+# -------------------------------------------------------------------- sync
+
+def mailbox_status(m, box):
+    typ, st = m.status(quote_mailbox(box), "(UIDVALIDITY UIDNEXT MESSAGES)")
+    if typ != "OK" or not st or not st[0]:
+        die(f"STATUS failed for mailbox '{box}'")
+    vals = dict(re.findall(r"(\w+) (\d+)", st[0].decode(errors="replace")))
+    return {"uidvalidity": int(vals.get("UIDVALIDITY", 0)),
+            "uidnext": int(vals.get("UIDNEXT", 1)),
+            "messages": int(vals.get("MESSAGES", 0))}
+
+def fetch_missing(db, m, box, uids):
+    """Fetch and cache any of `uids` not already in the db. Returns counts."""
+    if not uids:
+        return 0, 0
+    placeholders = ",".join("?" * len(uids))
+    have = {r[0] for r in db.execute(
+        f"SELECT uid FROM messages WHERE mailbox=? AND uid IN ({placeholders})",
+        (box, *uids))}
+    missing = [u for u in uids if u not in have]
+    fetched = 0
+    for uid, flags, raw in fetch_full(m, missing):
+        insert_record(db, box, parse_message(raw), uid, flags)
+        fetched += 1
+    db.commit()
+    return fetched, len(uids) - len(missing)
+
+def reconcile_flags(db, m, box):
+    """Pull FLAGS for every UID in the mailbox; update only rows that changed."""
+    typ, data = m.uid("FETCH", "1:*", "(FLAGS)")
+    if typ != "OK":
+        return 0
+    changed = 0
+    for item in data:
+        blob = item[0] if isinstance(item, tuple) else item
+        if not isinstance(blob, bytes):
+            continue
+        uid_m, flags_m = UID_RE.search(blob), FLAGS_RE.search(blob)
+        if uid_m and flags_m:
+            flags = flags_m.group(1).decode(errors="replace")
+            cur = db.execute(
+                "UPDATE messages SET flags=? WHERE mailbox=? AND uid=? AND flags != ?",
+                (flags, box, int(uid_m.group(1)), flags))
+            changed += cur.rowcount
+    db.commit()
+    return changed
+
+def sync_mailbox(db, m, box, full=False, batch=BACKFILL_BATCH, quick=QUICK_SEED,
+                 progress=True):
+    m.select(quote_mailbox(box), readonly=True)
+    st = mailbox_status(m, box)
+    row = get_sync_row(db, box)
+    if row is None:
+        cursor = 0
+        db.execute("INSERT INTO sync_state (mailbox, uidvalidity, backfill_cursor) VALUES (?,?,0)",
+                   (box, st["uidvalidity"]))
+        db.commit()
+    elif row[0] != st["uidvalidity"]:
+        if progress:
+            log(f"{box}: UIDVALIDITY changed ({row[0]} -> {st['uidvalidity']}); "
+                f"wiping {cached_count(db, box)} cached rows")
+        db.execute("DELETE FROM messages WHERE mailbox=?", (box,))
+        cursor = 0
+    else:
+        cursor = row[1]
+
+    typ, d = m.uid("SEARCH", "ALL")
+    server_uids = sorted(int(u) for u in d[0].split()) if d and d[0] else []
+    fetched = skipped = 0
+
+    # 1. recent-first seed: newest `quick` UIDs
+    f, s = fetch_missing(db, m, box, server_uids[-quick:])
+    fetched += f; skipped += s
+    if progress and f:
+        log(f"{box}: quick-seeded {f} recent message(s)")
+
+    # 2. resumable backfill over the contiguous UID range
+    if full and server_uids:
+        top = server_uids[-1]
+        while cursor < top:
+            lo, hi = cursor + 1, cursor + batch
+            chunk = [u for u in server_uids if lo <= u <= hi]
+            f, s = fetch_missing(db, m, box, chunk)
+            fetched += f; skipped += s
+            cursor = hi
+            db.execute(
+                "UPDATE sync_state SET backfill_cursor=?, uidvalidity=?, uidnext=?, synced_at=? "
+                "WHERE mailbox=?",
+                (cursor, st["uidvalidity"], st["uidnext"], int(time.time()), box))
+            db.commit()
+            if progress:
+                log(f"{box}: backfilled UID range ..{hi} "
+                    f"(+{f} new, {cached_count(db, box)} cached total)")
+
+    # 3. flags reconcile (explicit sync only)
+    changed = reconcile_flags(db, m, box)
+    db.execute(
+        "UPDATE sync_state SET uidnext=?, synced_at=? WHERE mailbox=?",
+        (st["uidnext"], int(time.time()), box))
+    db.commit()
+    return {"mailbox": box, "server_messages": st["messages"],
+            "cached": cached_count(db, box), "fetched": fetched,
+            "already_cached": skipped, "flags_updated": changed,
+            "backfill_cursor": cursor, "uidnext": st["uidnext"]}
+
+def implicit_sync(db, box, no_sync):
+    """Best-effort incremental sync; never fatal, keeps cache fresh on reads."""
+    if no_sync:
+        return
+    row = get_sync_row(db, box)
+    if row and row[3] and time.time() - row[3] < SYNC_STALENESS:
+        return
+    m = try_connect()
+    if m is None:
+        return  # Bridge down: serve whatever the cache has
+    try:
+        st = mailbox_status(m, box)
+        if get_sync_row(db, box) is None or get_sync_row(db, box)[0] != st["uidvalidity"]:
+            sync_mailbox(db, m, box, full=False, progress=False)
+        else:
+            m.select(quote_mailbox(box), readonly=True)
+            typ, d = m.uid("SEARCH", "ALL")
+            server_uids = sorted(int(u) for u in d[0].split()) if d and d[0] else []
+            fetch_missing(db, m, box, server_uids[-QUICK_SEED:])
+            db.execute("UPDATE sync_state SET uidnext=?, synced_at=? WHERE mailbox=?",
+                       (st["uidnext"], int(time.time()), box))
+            db.commit()
+    finally:
+        try:
+            m.logout()
+        except Exception:
+            pass
+
+# ----------------------------------------------------------- command impls
+
+def cmd_setup(args):
+    acct = input("Proton account email: ").strip()
+    if not acct:
+        die("empty account")
+    pw = getpass.getpass(f"Bridge password for {acct} (Bridge app > Mailbox details): ")
+    if not pw:
+        die("empty password")
+    r = subprocess.run(
+        ["security", "add-generic-password", "-s", KEYCHAIN_SERVICE, "-a", acct,
+         "-w", pw, "-U"], capture_output=True, text=True)
+    if r.returncode != 0:
+        die(f"Keychain store failed: {r.stderr.strip()}")
+    os.makedirs(DATA_DIR, exist_ok=True)
+    with open(CONFIG_PATH, "w") as f:
+        json.dump({"account": acct}, f)
+    os.chmod(CONFIG_PATH, 0o600)
+    m = connect()
+    m.logout()
+    log(f"Account '{acct}' configured; password stored in macOS Keychain and "
+        f"verified against Bridge.")
+
+def cmd_mailboxes(args):
+    db = open_db()
+    m = connect()
+    typ, boxes = m.list()
+    if typ != "OK":
+        die("LIST failed")
+    out = []
+    for b in boxes:
+        if not isinstance(b, bytes):
+            continue
+        mm = re.match(rb"\(([^)]*)\)\s+\"[^\"]*\"\s+(.*)$", b)
+        if not mm:
+            continue
+        attrs = mm.group(1).decode(errors="replace")
+        name = mm.group(2).decode(errors="replace").strip('"')
+        entry = {"mailbox": name, "attributes": attrs}
+        if "\\Noselect" not in attrs:
+            try:
+                st = mailbox_status(m, name)
+                entry["messages"] = st["messages"]
+            except SystemExit:
+                entry["messages"] = None
+            entry["cached"] = cached_count(db, name)
+        out.append(entry)
+    m.logout()
+    emit(out)
+
+def cmd_list(args):
+    db = open_db()
+    implicit_sync(db, args.mailbox, args.no_sync)
+    use_cache = (not args.live) and cached_count(db, args.mailbox) > 0
+    if use_cache:
+        sql = ("SELECT uid, date, from_addr, to_addr, subject, flags FROM messages "
+               "WHERE mailbox=?")
+        params = [args.mailbox]
+        if args.unseen:
+            sql += " AND flags NOT LIKE '%\\Seen%'"
+        sql += " ORDER BY uid DESC LIMIT ?"
+        params.append(args.limit)
+        rows = [{"uid": r[0], "date": iso(r[1]), "from": r[2], "to": r[3],
+                 "subject": r[4], "flags": r[5], "source": "cache"}
+                for r in db.execute(sql, params)]
+        emit({"mailbox": args.mailbox, "source": "cache", "count": len(rows),
+              "messages": rows})
+        return
+    m = connect()
+    m.select(quote_mailbox(args.mailbox), readonly=True)
+    typ, d = m.uid("SEARCH", "UNSEEN" if args.unseen else "ALL")
+    uids = sorted(int(u) for u in d[0].split()) if d and d[0] else []
+    latest = uids[-args.limit:][::-1]
+    rows = fetch_headers(m, latest)
+    m.logout()
+    for r in rows:
+        r["source"] = "live"
+    emit({"mailbox": args.mailbox, "source": "live", "count": len(rows),
+          "messages": rows})
+
+def render_message(box, uid, rec, flags, max_chars):
+    body, source = rec["body_text"], "text"
+    if not body and rec["body_html"]:
+        body, source = html_to_text(rec["body_html"]), "html-stripped"
+    truncated = False
+    if max_chars and len(body) > max_chars:
+        body = body[:max_chars]
+        truncated = True
+    return {
+        "mailbox": box, "uid": uid,
+        "date": iso(rec["date"]), "from": rec["from_addr"], "to": rec["to_addr"],
+        "cc": rec["cc"], "subject": rec["subject"], "flags": flags,
+        "body_source": source, "truncated": truncated,
+        "attachments": json.loads(rec["attachments"] or "[]"),
+        "body": body,
+    }
+
+def cmd_read(args):
+    if args.raw:
+        m = connect()
+        m.select(quote_mailbox(args.mailbox), readonly=True)
+        for uid, flags, raw in fetch_full(m, [args.uid]):
+            sys.stdout.buffer.write(raw)
+            m.logout()
+            return
+        m.logout()
+        die(f"UID {args.uid} not found in {args.mailbox}")
+    db = open_db()
+    implicit_sync(db, args.mailbox, args.no_sync)
+    row = db.execute(
+        "SELECT message_id, date, from_addr, to_addr, cc, subject, flags, size,"
+        " body_text, body_html, attachments FROM messages WHERE mailbox=? AND uid=?",
+        (args.mailbox, args.uid)).fetchone()
+    if row is not None:
+        rec = {"date": row[1], "from_addr": row[2], "to_addr": row[3], "cc": row[4],
+               "subject": row[5], "body_text": row[8], "body_html": row[9],
+               "attachments": row[10]}
+        out = render_message(args.mailbox, args.uid, rec, row[6], args.max_chars)
+        out["source"] = "cache"
+        emit(out)
+        return
+    # cache miss -> live fetch, cache it, render
+    m = connect()
+    m.select(quote_mailbox(args.mailbox), readonly=True)
+    for uid, flags, raw in fetch_full(m, [args.uid]):
+        rec = parse_message(raw)
+        insert_record(db, args.mailbox, rec, uid, flags)
+        db.commit()
+        m.logout()
+        out = render_message(args.mailbox, uid, rec, flags, args.max_chars)
+        out["source"] = "live"
+        emit(out)
+        return
+    m.logout()
+    die(f"UID {args.uid} not found in {args.mailbox}")
+
+def cmd_search(args):
+    db = open_db()
+    if not args.live:
+        implicit_sync(db, args.mailbox, args.no_sync)
+        if cached_count(db, args.mailbox) > 0:
+            return search_fts(db, args)
+        log("pmail: cache empty for this mailbox; falling back to --live search")
+    m = connect()
+    m.select(quote_mailbox(args.mailbox), readonly=True)
+    crit = []
+    if args.unseen:
+        crit.append("UNSEEN")
+    if args.sender:
+        crit += ["FROM", f'"{args.sender}"']
+    if args.subject:
+        crit += ["SUBJECT", f'"{args.subject}"']
+    if args.since:
+        crit += ["SINCE", args.since]
+    for w in args.words:
+        crit += ["TEXT", f'"{w}"']
+    if not crit:
+        die("search needs at least one word or filter")
+    typ, d = m.uid("SEARCH", *crit)
+    if typ != "OK":
+        die(f"SEARCH failed: {d}")
+    uids = sorted(int(u) for u in d[0].split()) if d and d[0] else []
+    latest = uids[-args.limit:][::-1]
+    rows = fetch_headers(m, latest)
+    m.logout()
+    emit({"mailbox": args.mailbox, "source": "live", "total_hits": len(uids),
+          "count": len(rows), "messages": rows})
+
+def search_fts(db, args):
+    where, params = ["mail_fts MATCH ?"], [args.query]
+    where.append("m.mailbox=?"); params.append(args.mailbox)
+    if args.sender:
+        where.append("m.from_addr LIKE ?"); params.append(f"%{args.sender}%")
+    if args.since:
+        try:
+            ts = int(datetime.fromisoformat(args.since).replace(tzinfo=timezone.utc).timestamp())
+            where.append("m.date >= ?"); params.append(ts)
+        except ValueError:
+            die(f"--since must be ISO date (e.g. 2026-01-01), got '{args.since}'")
+    if args.unseen:
+        where.append("m.flags NOT LIKE '%\\Seen%'")
+    # rank in a CTE first (CROSS JOIN pins scan order: FTS first, rowid probes),
+    # then compute the expensive snippet() only for the rows that survive LIMIT
+    sql = f"""
+      WITH top AS (
+        SELECT m.rowid AS rid, bm25(mail_fts, 10.0, 5.0, 1.0, 1.0) AS r
+        FROM mail_fts CROSS JOIN messages m ON m.rowid = mail_fts.rowid
+        WHERE {' AND '.join(where)}
+        ORDER BY r LIMIT ?)
+      SELECT m.uid, m.date, m.from_addr, m.subject, m.flags,
+             snippet(mail_fts, 3, '>>>', '<<<', '...', 24), top.r
+      FROM top JOIN messages m ON m.rowid = top.rid
+      JOIN mail_fts ON mail_fts.rowid = top.rid
+      ORDER BY top.r"""
+    params.append(args.limit)
+    try:
+        rows = db.execute(sql, params).fetchall()
+    except sqlite3.OperationalError:
+        # not a valid FTS5 query: treat words as an AND of quoted terms
+        terms = args.query.split()
+        if not terms:
+            die("empty search query")
+        params[0] = " AND ".join('"' + t.replace('"', '') + '"' for t in terms)
+        try:
+            rows = db.execute(sql, params).fetchall()
+        except sqlite3.OperationalError as e:
+            die(f"search failed: {e}")
+    out = [{"uid": r[0], "date": iso(r[1]), "from": r[2], "subject": r[3],
+            "flags": r[4],
+            "snippet": INVISIBLES_RE.sub("", re.sub(r"\s+", " ", r[5] or "")).strip(),
+            "rank": round(r[6], 3)} for r in rows]
+    emit({"mailbox": args.mailbox, "source": "cache-fts", "query": args.query,
+          "count": len(out), "messages": out})
+
+def cmd_sync(args):
+    db = open_db()
+    m = connect()
+    if args.all:
+        typ, boxes = m.list()
+        targets = []
+        for b in boxes or []:
+            if isinstance(b, bytes):
+                mm = re.match(rb"\(([^)]*)\)\s+\"[^\"]*\"\s+(.*)$", b)
+                if mm and b"\\Noselect" not in mm.group(1):
+                    targets.append(mm.group(2).decode(errors="replace").strip('"'))
+        if len(targets) > 1 and "All Mail" in targets and args.skip_all_mail:
+            targets.remove("All Mail")
+        # backfill the biggest (All Mail) last so smaller boxes finish first
+        targets.sort(key=lambda t: (t == "All Mail", t))
+    else:
+        targets = [args.mailbox]
+    results = []
+    for box in targets:
+        m.select(quote_mailbox(box), readonly=True)
+        results.append(sync_mailbox(db, m, box, full=args.full, batch=args.batch))
+    m.logout()
+    emit({"synced": results})
+
+def cmd_status(args):
+    db = open_db()
+    rows = []
+    for box, uidvalidity, cursor, uidnext, synced_at in db.execute(
+            "SELECT mailbox, uidvalidity, backfill_cursor, uidnext, synced_at "
+            "FROM sync_state ORDER BY mailbox"):
+        rows.append({
+            "mailbox": box, "cached": cached_count(db, box),
+            "server_messages": (uidnext - 1) if uidnext else None,
+            "backfill_complete": bool(uidnext and cursor >= uidnext - 1),
+            "backfill_cursor": cursor, "uidnext": uidnext,
+            "last_sync": iso(synced_at),
+        })
+    db_size = os.path.getsize(DB_PATH) if os.path.exists(DB_PATH) else 0
+    attach = []
+    if os.path.isdir(ATTACH_DIR):
+        attach = os.listdir(ATTACH_DIR)
+    emit({"db_path": DB_PATH, "db_size_mb": round(db_size / 1e6, 1),
+          "mailboxes": rows, "attachments_saved": len(attach)})
+
+def cmd_save_attach(args):
+    db = open_db()
+    os.makedirs(ATTACH_DIR, exist_ok=True)
+    m = connect()
+    m.select(quote_mailbox(args.mailbox), readonly=True)
+    for uid, flags, raw in fetch_full(m, [args.uid]):
+        msg = BytesParser(policy=policy.default).parsebytes(raw)
+        idx = 0
+        for part in msg.walk():
+            if part.get_content_maintype() == "multipart":
+                continue
+            filename = part.get_filename()
+            if part.get_content_disposition() == "attachment" or filename:
+                idx += 1
+                if idx == args.index:
+                    payload = part.get_payload(decode=True)
+                    if payload is None:
+                        m.logout()
+                        die(f"attachment {args.index} has no decodable payload")
+                    safe = re.sub(r"[^\w.\-]+", "_", filename or f"attachment-{idx}")
+                    path = os.path.join(ATTACH_DIR,
+                                        f"{args.mailbox.replace('/', '_')}-{uid}-{idx}-{safe}")
+                    with open(path, "wb") as f:
+                        f.write(payload)
+                    m.logout()
+                    emit({"saved": path, "name": filename, "mime": part.get_content_type(),
+                          "size": len(payload)})
+                    return
+        m.logout()
+        die(f"message UID {args.uid} has only {idx} attachment(s)")
+    m.logout()
+    die(f"UID {args.uid} not found in {args.mailbox}")
+
+# --------------------------------------------------------------------- CLI
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="pmail",
+        description="Read ProtonMail via local Bridge IMAP. Read-only. JSON on stdout.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sp = sub.add_parser("setup", help="store Bridge password in macOS Keychain")
+    sp.set_defaults(fn=cmd_setup)
+
+    sp = sub.add_parser("mailboxes", help="list folders/labels with counts")
+    sp.set_defaults(fn=cmd_mailboxes)
+
+    sp = sub.add_parser("list", help="list messages (default: INBOX, cache-first)")
+    sp.add_argument("mailbox", nargs="?", default="INBOX")
+    sp.add_argument("--limit", type=int, default=DEFAULT_LIMIT)
+    sp.add_argument("--unseen", action="store_true")
+    sp.add_argument("--live", action="store_true", help="bypass cache, query Bridge")
+    sp.add_argument("--no-sync", action="store_true", help="skip implicit incremental sync")
+    sp.set_defaults(fn=cmd_list)
+
+    sp = sub.add_parser("read", help="read one message by UID (cache-first)")
+    sp.add_argument("uid", type=int)
+    sp.add_argument("--mailbox", default="INBOX")
+    sp.add_argument("--raw", action="store_true", help="dump untouched RFC822 to stdout")
+    sp.add_argument("--max-chars", type=int, default=20000, help="0 = no limit")
+    sp.add_argument("--no-sync", action="store_true")
+    sp.set_defaults(fn=cmd_read)
+
+    sp = sub.add_parser("search", help="full-text search (FTS5 cache) or --live IMAP search")
+    sp.add_argument("words", nargs="*", help="keywords (AND-ed); quotes/phrases passed to FTS5")
+    sp.add_argument("--mailbox", default="All Mail")
+    sp.add_argument("--from", dest="sender")
+    sp.add_argument("--subject")
+    sp.add_argument("--since", help="ISO date, e.g. 2026-01-01")
+    sp.add_argument("--unseen", action="store_true")
+    sp.add_argument("--limit", type=int, default=DEFAULT_LIMIT)
+    sp.add_argument("--live", action="store_true")
+    sp.add_argument("--no-sync", action="store_true")
+    sp.set_defaults(fn=cmd_search)
+
+    sp = sub.add_parser("sync", help="sync mailbox(es) into the local cache")
+    sp.add_argument("--mailbox", default="INBOX")
+    sp.add_argument("--all", action="store_true", help="sync every folder/label")
+    sp.add_argument("--skip-all-mail", action="store_true",
+                    help="with --all: skip the 'All Mail' virtual mailbox (it duplicates the others)")
+    sp.add_argument("--full", action="store_true", help="run/resume full backfill")
+    sp.add_argument("--batch", type=int, default=BACKFILL_BATCH)
+    sp.set_defaults(fn=cmd_sync)
+
+    sp = sub.add_parser("status", help="cache state per mailbox")
+    sp.set_defaults(fn=cmd_status)
+
+    sp = sub.add_parser("save-attach", help="download attachment N of message UID")
+    sp.add_argument("uid", type=int)
+    sp.add_argument("index", type=int, help="attachment index from `read` output (1-based)")
+    sp.add_argument("--mailbox", default="INBOX")
+    sp.set_defaults(fn=cmd_save_attach)
+    return p
+
+def main():
+    args = build_parser().parse_args()
+    if args.cmd == "search":
+        args.query = " ".join(args.words)
+        if not args.live and not args.query and not (args.sender or args.subject):
+            die("search needs at least one word (cached search is text-based)")
+    args.fn(args)
+
+if __name__ == "__main__":
+    main()