diff --git a/README.md b/README.md
index 5139052..b051ba8 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,11 @@
+---
+title: hermes-proton
+description: Hermes Agent runtime + Proton product suite integration — skills, plugins, and MCP tools for Proton Mail, Drive, Pass, VPN, Calendar
+state: prototype
+created: 2026-06-08
+updated: 2026-06-08
+---
+
 # hermes-proton
 
 > Hermes Agent runtime + Proton product suite integration — skills, plugins, and MCP tools for Proton Mail, Drive, Pass, VPN, Calendar.
diff --git a/docs/landscape.md b/docs/landscape.md
new file mode 100644
index 0000000..d56c47f
--- /dev/null
+++ b/docs/landscape.md
@@ -0,0 +1,561 @@
+# Proton Third-Party Client Landscape
+
+> Landscape scan of 7 open-source Proton client implementations — patterns, pitfalls, and reusable code for hermes-proton.
+> Compiled: 2026-06-08
+> Analyst: Face (kanban t_3c87cd08)
+
+---
+
+## Overview
+
+| # | Project | Lang | Stars | Auth | Scope | Key Value for Hermes-Proton |
+|---|---------|------|-------|------|-------|----------------------------|
+| 1 | **hydroxide** (emersion) | Go | 2.1k | SRP direct | Mail, Contacts, Calendar | Complete SRP+2FA+refresh implementation; bbolt caching; NaCl secretbox session persistence |
+| 2 | **rclone protondrive** | Go | 57k | SRP direct | Drive only | Battle-tested Drive encryption (4MB blocks, X25519, gopenpgp v2); most-used third-party client |
+| 3 | **proton-cli** (roman-16) | Go | 17 | SRP direct | All 5 products | Most architecturally mature; clean 3-tier layering; session cache; REF ID system; error classification |
+| 4 | **pm-cli** (bscott) | Go | 14 | Bridge pass | Mail only | Agent-friendly gold standard: `--json` everywhere, `--help-json`, idempotency keys, semantic summaries |
+| 5 | **proton-webdav-bridge** (StollD) | Go | 28 | SRP direct | Drive as WebDAV | In-memory tree cache + 5s event poll; Drive encryption via go-proton-api fork (archived) |
+| 6 | **proton-tui** (cdump) | Rust | 12 | SRP direct | VPN only | Standalone SRP-6a auth module (reusable Rust crate); WireGuard key conversion; VPN lifecycle |
+| 7 | **openclaw-protonmail-skill** (rvacyber) | TS | 16 | Bridge pass | Mail only | Closest analogue to Hermes skill pattern; IMAP/SMTP via Bridge; env-var config; search sanitization |
+
+---
+
+## 1. Project-by-Project Analysis
+
+### 1.1 hydroxide (emersion/hydroxide)
+
+**Location:** `github.com/emersion/hydroxide`
+**Stars:** 2.1k | **License:** MIT | **Language:** Go 1.24
+
+#### Auth Approach — Full SRP Direct (No Bridge Dependency)
+
+```
+AuthInfo(username) → POST /auth/info → {srpSession, Modulus (PGP-signed), ServerEphemeral, Salt}
+srp(password, info) → bcrypt (cost 10) + expandHash (4×SHA-512) + generateProofs (2048-bit, LE)
+Auth(username, password, info) → POST /auth → verify server proof (constant-time compare)
+AuthTOTP(code) → POST /auth/2fa (bitmap check: Enabled != 0)
+Unlock(auth, keySalts, passphrase) → decrypt keyring with password/token
+```
+
+- **SRP implementation location:** `protonmail/srp.go` — 2048-bit group, little-endian byte order matching Proton web client
+- **Password hashing:** `protonmail/password.go` — `hashPassword()`: version 3/4 appends "proton" to salt, bcrypts (cost 10), runs `expandHash()` — 4 rounds SHA-512 with suffix bytes 0-3
+- **Modulus trust:** Hardcoded `modulusPubkey` PGP key in source; modulus response is clearsigned and verified
+- **2FA:** TOTP only; bitmap check (`Enabled != 0` not `Enabled == 1`); U2F/WebAuthn not implemented
+- **Re-auth chain:** `AuthRefresh()` → POST `/auth/refresh`; on code 10013 (invalid refresh token) → fallback to full SRP Auth (fails if 2FA enabled)
+
+#### Token Persistence — NaCl Secretbox
+
+- **Storage:** `~/.config/hydroxide/auth.json`
+- **Format:** JSON map `map[string]string` (username → base64-encrypted blob)
+- **Encryption:** NaCl secretbox (XSalsa20-Poly1305) with random 24-byte nonce
+- **Key:** Random 32-byte bridge password (base64), shown once at login, NOT stored by hydroxide
+- **CachedAuth struct:** `{Auth (UID, AccessToken, RefreshToken, ExpiresIn), LoginPassword, MailboxPassword, KeySalts}`
+
+#### Error Handling
+
+| Pattern | Details |
+|---------|---------|
+| **401 auto-retry** | `Client.do()` — single retry with `ReAuth` callback |
+| **APIError struct** | `{Code int, Message string}` — wrapped from `RawAPIError` |
+| **Refresh failure** | Code 10013 → full re-auth via SRP (2FA blocks this) |
+| **429 rate limit** | **Not handled** — no retry-wait logic (gap for production) |
+
+#### Crypto
+
+- `github.com/ProtonMail/go-crypto v1.4.1` (Proton's OpenPGP fork with SHA-512 support)
+- Message encryption: `Message.Encrypt(to, signed)` → armored PGP via `openpgp.SymmetricallyEncrypt`
+- Attachment crypto: `Attachment.GenerateKey()` → AES-256 key → symmetrically encrypted
+- Contact crypto: `NewEncryptedContactCard`, `NewSignedContactCard` — dual-card scheme
+- Key derivation: `computeKeyPassword()` → bcrypt, strip prefix (last 29 bytes)
+
+#### Project Structure
+```
+protonmail/         # Core API client (18 files)
+  ├── auth.go       # Auth flows (AuthInfo, Auth, AuthTOTP, AuthRefresh, Unlock, Logout)
+  ├── srp.go        # SRP-6a protocol
+  ├── password.go   # Key derivation (bcrypt + SHA-512)
+  ├── crypto.go     # OpenPGP operations
+  ├── messages.go   # Message CRUD + Encrypt/Read
+  ├── events.go     # Event polling (GetEvent)
+  └── ...
+auth/auth.go       # Session persistence, Manager, re-auth, 2FA detection
+imap/              # IMAP server backend + bbolt database
+smtp/              # SMTP backend (MIME → PGP → send)
+carddav/           # CardDAV handler
+cmd/hydroxide/     # CLI entry (11 subcommands)
+```
+
+**Key takeaway:** Most complete SRP+session management reference. The NaCl secretbox pattern for encrypted token storage is directly adoptable.
+
+---
+
+### 1.2 rclone protondrive backend
+
+**Location:** `github.com/rclone/rclone/tree/master/backend/protondrive`
+**Stars:** 57k (rclone project) | **License:** MIT | **Language:** Go
+
+#### Auth Approach — SRP Direct (via archived bridge library)
+
+Uses `henrybear327/Proton-API-Bridge` (archived Feb 2026) and `henrybear327/go-proton-api` (archived Feb 2026). Both are single-contributor projects with **no upstream development**.
+
+- SRP auth via `ProtonMail/go-srp v0.0.7`
+- **Auth flow:** Login → API client creation → keyring unlock → Drive backend init
+- **SaltedKeyPass caching:** After first login, the salted key pass is cached so subsequent operations don't need password
+- **authHandler callback pattern:** Transparent token refresh middleware
+
+#### Encryption — gopenpgp v2 (X25519)
+
+- **Key type:** X25519 (Curve25519-based OpenPGP keys)
+- **Block size:** 4MB blocks
+- **Encryption:** OpenPGP CFB mode per block
+- **Hashing:** SHA-256 block hashes + armored detached signatures per block; SHA-1 content digests (Proton legacy)
+- **Bootstrap key:** HKDF from user key → address key → share key → node key → session key
+- **Key library:** `github.com/ProtonMail/gopenpgp/v2 v2.10.0`
+
+#### Token Management
+
+- Config stores: UID + AccessToken + RefreshToken + SaltedKeyPass
+- `configKey` constants hidden in config file
+- Auto-refresh handled by bridge library (opaque to rclone backend)
+
+#### Error Handling
+
+| Pattern | Details |
+|---------|---------|
+| **shouldRetry** | Catches API Code=200501 (rate limit?) and 5xx server errors |
+| **HTTP retry** | Deferred to `resty` (rclone's HTTP client) |
+| **Sentinel errors** | 17 typed error constants in Proton-API-Bridge |
+
+#### ⚠️ Critical Risk
+
+Both `henrybear327/Proton-API-Bridge` and `henrybear327/go-proton-api` are **archived** (Feb 2026). rclone vendors them as-is. Any new project relying on this code path inherits the risk of unpatched bugs and API breakage.
+
+---
+
+### 1.3 proton-cli (roman-16/proton-cli)
+
+**Location:** `github.com/roman-16/proton-cli`
+**Stars:** 17 | **License:** MIT | **Language:** Go 1.26.1 | **Version:** v1.4.0 (May 2026)
+
+#### Architecture — 3-Tier Layered (Best in Class)
+
+```
+cmd/          # Cobra CLI commands (per-product packages)
+internal/
+  api/        # HTTP client, SRP auth, error types, HV resolver
+  services/   # Domain services (mail, drive, calendar, contacts, pass) — per-product packages
+  app/        # Wiring container (App struct holding 5 services + API + Renderer)
+  session/    # Session persistence (~/.config/proton-cli/sessions/<profile>.json)
+  config/     # TOML multi-profile config
+  keys/       # PGP key hierarchy unlock
+  pgp/        # Card encryption (clear/signed/encrypted/encrypted+signed)
+  aead/       # AES-256-GCM for Pass items/vaults
+  render/     # Output formatting (text/JSON/YAML/tables/progress)
+  idcache/    # Short-ID → full ID cache
+  hv/         # Embedded webview CAPTCHA helper
+```
+
+**The `App` wiring pattern is worth adopting directly:**
+```go
+type App struct {
+    Profile  string
+    Creds    Credentials
+    API      *api.Client      // Single session, shared across all 5 services
+    Mail     *mail.Service
+    Drive    *drive.Service
+    Calendar *calendar.Service
+    Contacts *contacts.Service
+    Pass     *pass.Service
+    R        *render.Renderer
+    IDCache  *idcache.Cache
+}
+```
+
+#### Auth Approach — Full SRP (Not Bridge)
+
+- `POST /auth/v4/sessions` (creates unauth session)
+- `POST /core/v4/auth/info` → `go-srp` proofs
+- `POST /core/v4/auth` → verify server proof (MITM prevention)
+- `POST /core/v4/auth/2fa` if bit 0 set in `TwoFA.Enabled`
+- HV (CAPTCHA) via embedded webview helper binary
+- **Dependencies:** `go-srp v0.0.7`, `gopenpgp/v2 v2.10.0`
+
+#### Session Management
+
+- **Storage:** `~/.config/proton-cli/sessions/<profile>.json` (0600)
+- **SaltedKeyPass caching:** Stored in session file → subsequent invocations don't need password
+- **Auto-refresh:** `api.Client.Do()` calls `POST /auth/v4/refresh` on 401, persists via `session.Save()`
+- **Thread safety:** `sync.RWMutex` on client for token reads/writes
+- **Multi-profile:** Each profile has independent session + config
+
+#### Error Handling — Typed Hierarchy with Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | User error |
+| 2 | Auth failure |
+| 3 | Not found |
+| 4 | Ambiguous/conflict |
+| 5 | Network/server error |
+| 130 | Cancelled (Ctrl+C) |
+
+Hierarchy: `APIError` → `HumanVerificationError` (code 9001) → `ExitError` → `WrongTableError` (cross-table probing for message↔conversation confusion) → `ErrNotFound` / `AmbiguousError`
+
+**Notable:** Cross-table probing on 422 errors — if a GET fails, it probes the opposite table (message↔conversation) and returns a precise diagnostic.
+
+#### Key Design Decisions
+
+1. **Single HTTP client** shared across all 5 products — no per-service auth
+2. **App-in-context** pattern — `*app.App` stored in `context.Context` via `app.WithApp()`, avoids global state
+3. **REF ID resolution** — prefix matching (8+ chars) from idcache; ambiguous → exit 4 with candidates
+4. **Dashed ID protection** — auto-inserts `--` before Proton base64 IDs starting with `-`
+5. **Render abstraction** — `render.Renderer` handles text/JSON/YAML; commands never call `fmt.Println`
+6. **Dry-run on mutations** — global `--dry-run` flag checked by all mutation commands
+
+#### Notable Gaps
+- No OAuth — env-var or config-file passwords only
+- No structured logging — `slog` to stderr only; no log file/rotation
+- CAPTCHA webview only — no stdin-based email/SMS verification
+
+---
+
+### 1.4 pm-cli (bscott/pm-cli)
+
+**Location:** `github.com/bscott/pm-cli`
+**Stars:** 14 | **License:** MIT | **Language:** Go | **Version:** v0.2.5 (April 2026)
+
+#### Architecture — Bridge Protocol Only
+
+- **Does NOT call Proton API directly** — connects to local Proton Bridge daemon
+- **IMAP:** `127.0.0.1:1143` (STARTTLS) — read/search mail
+- **SMTP:** `127.0.0.1:1025` (STARTTLS) — send mail
+- **Auth:** Bridge-generated app password (not Proton password)
+- **TLS:** `InsecureSkipVerify: true` (Bridge self-signed cert), v0.2.5 enforces **loopback-only**
+
+#### Agent-Friendly Features (Gold Standard for Hermes)
+
+| Feature | Implementation | Value for Agents |
+|---------|---------------|------------------|
+| **Universal `--json`** | `Formatter` struct threaded through all commands; `{"success": true, "data": {...}}` envelope | Always parseable, always on stdout |
+| **`--help-json`** | Full typed command tree as JSON (flags, args, types, examples) | Zero-parsing schema introspection in 1 call |
+| **Idempotency keys** | `--idempotency-key` on mail send/reply/forward; 24h TTL in `~/.config/pm-cli/idempotency.json` | Safe retry without double-send |
+| **Semantic AI commands** | `mail summarize` (sentiment, priority, action_required, summary); `mail extract` (emails, URLs, dates, phone_numbers, action_items) | Pre-digested LLM input |
+| **Consistent error envelope** | `{"success": false, "error": "..."}` on stdout | Always parseable even on failure |
+| **Stable IDs** | Both seq numbers (`123`) and UIDs (`uid:456`) in output | Stable across invocations |
+| **Watch + env vars** | `mail watch --exec` exposes metadata as `PM_MSG_*` env vars | Safe agent automation |
+
+#### Error Handling
+
+- Two-mode: human (stderr, color) vs JSON (stdout, structured)
+- Descriptive messages with actionable guidance
+- Exit code 1 on any error
+- Wrapped errors via `%w`
+
+#### Security Hardening (v0.2.5)
+1. SMTP Header Injection — `SanitizeHeaderValue()` strips CR/LF
+2. TLS Loopback Enforcement — `isLoopbackHost()` refuses non-localhost
+3. Shell Injection — env vars replace string interpolation in watch mode
+4. ANSI Escape Injection — `SanitizeForTerminal()` strips escapes
+
+#### Gaps
+- **Bridge required** — doesn't work without Bridge daemon
+- **Mail only** — no Calendar, Drive, Pass, VPN
+- **Polling only** — 30s poll interval, no IMAP IDLE
+- **Single account** — one config at a time
+- **Local-only** — can't be remote/multi-user
+
+---
+
+### 1.5 proton-webdav-bridge (StollD)
+
+**Location:** `github.com/StollD/proton-webdav-bridge`
+**Stars:** 28 | **License:** MIT | **Language:** Go
+
+#### Architecture
+
+- **Purpose:** Exposes Proton Drive as a local WebDAV filesystem
+- **Daemon pattern:** Registers WebDAV handler on localhost:7984, proxies Drive operations
+- **Auth:** SRP direct via `henrybear327/go-proton-api` (same archived fork as rclone)
+
+#### Caching — Pure In-Memory
+
+- Two `map[string]*Link` — one for ID lookups, one for path lookups
+- **No disk persistence** — full re-fetch on restart
+- **Event poll:** Background goroutine polls Proton share events every 5 seconds via `TriggerUpdate()`
+- **Synchronous cache refresh** before every download/upload
+
+#### Encryption
+
+- Same gopenpgp/v2 stack as rclone (X25519)
+- Full key hierarchy: User Key → Address Key → Share Key → Node Key → Session Key
+- Reader decrypts blocks on-demand with SHA-256 hash verification
+- Writer encrypts in 4MB blocks with SHA-1 content hashing (Proton API validation)
+
+#### Critical Issues
+
+1. **Archived dependencies** — both `henrybear327/go-proton-api` and `StollD/proton-drive` are single-contributor, archived
+2. **`panic(err)` on init failures** — no graceful degradation
+3. **Headless auth unsupported** — interactive `--login` only
+4. **Token expiry = `os.Exit(1)`** — hard abort
+
+---
+
+### 1.6 proton-tui (cdump)
+
+**Location:** `github.com/cdump/proton-tui`
+**Stars:** ~12 | **License:** MIT | **Language:** Rust | **Version:** v0.3.0
+
+#### Auth — Standalone Rust SRP-6a Implementation
+
+The `auth.rs` module (~500 lines) is the single most reusable piece for Hermes-proton.
+
+**Flow:**
+1. `POST /auth/info` → extract modulus from PGP signed response body
+2. `SrpClient::new(modulus)` → generate random 256-bit `a`
+3. Password hashing: bcrypt (cost 10, `$2y$`) + `pm_hash()` (4×SHA-512 extend to 2048 bits)
+4. SRP-6a math: `u = H(A,B)`, `S = (B - k*g^x)^(a+u*x) mod N`, client proof `M = H(A,B,K)`
+5. `POST /auth` → verify, handle 2FA
+
+**Reusable functions:**
+- `pm_hash` — Proton's custom 2048-bit hash (4 SHA-512 rounds with suffixes 0x00-0x03)
+- `hash_password` — bcrypt + PMHash combined
+- `verify_server_proof` — constant-time comparison
+- PGP modulus extraction — parse clearsigned response
+
+**Dependencies:** `num-bigint`, `sha2`, `bcrypt`, `base64`, `reqwest` — all standard crates
+
+#### VPN Connection — WireGuard Only
+
+- **Key generation:** Ed25519 `SigningKey` → X25519 via SHA-512 + bit clamping
+- **Certificate registration:** `POST /vpn/v1/certificate` with ED25519 public PEM
+- **Connection:** `sudo wg-quick up <config>` with runtime/saved config targets
+- **Disconnection:** `sudo wg-quick down <config>`
+
+#### Token Management
+
+- **Storage:** `~/.config/proton-tui/tokens.json` (0o600 on Unix)
+- **Struct:** `StoredTokens { uid, access_token, refresh_token }`
+- **Clear:** Menu option (deletes file)
+- **Conversion:** `impl From<AuthResult> for StoredTokens`
+
+---
+
+### 1.7 openclaw-protonmail-skill (rvacyber)
+
+**Location:** `github.com/rvacyber/openclaw-protonmail-skill`
+**Stars:** 16 | **License:** MIT | **Language:** TypeScript | **Version:** v1.0.1 (2026-04)
+
+#### Skill Structure — Direct Hermes Reference
+
+```
+SKILL.md              # OpenClaw manifest (YAML frontmatter)
+src/
+  index.ts            # ProtonMailSkill class — orchestrator
+  imap.ts             # IMAPClient — read/search operations
+  smtp.ts             # SMTPClient — send/reply operations
+  tools.ts            # OpenClaw tool registrations + TOOL_DEFINITIONS
+bin/protonmail        # CLI entry (Node.js shebang)
+```
+
+#### Bridge Connection Pattern (Directly Transferable)
+
+```typescript
+// IMAP (read path) — 127.0.0.1:1143, TLS, rejectUnauthorized: false
+// SMTP (write path) — 127.0.0.1:1025, STARTTLS (secure: false), rejectUnauthorized: false
+// Always enforce localhost-only host validation
+```
+
+#### Operations
+
+| Method | What It Does | Key Implementation Detail |
+|--------|-------------|---------------------------|
+| `listInbox(limit, unreadOnly)` | List recent messages | Search ALL or UNSEEN, sort by UID desc, fetch headers |
+| `search(query, limit)` | Search with syntax | Parse `from:`, `subject:`, `body:`, `newer_than:` filters |
+| `readMessage(messageId)` | Full email content | UID fetch + mailparser; `messageFound` + `fetch.end` hang prevention |
+| `send(to, subject, body, options)` | Send new email | Plain text + optional HTML/CC/BCC/attachments via nodemailer |
+| `reply(originalMessage, body)` | Reply with threading | RFC 5322 `In-Reply-To`/`References` headers |
+
+#### Search Sanitization (Security Pattern)
+- Length limit: 200 chars
+- Character allowlist: `[a-zA-Z0-9@._+\-\s:]`
+- No CR/LF/control chars
+- Unrecognized queries → safe subject keyword search fallback
+
+#### Config & Env
+
+```yaml
+# SKILL.md metadata
+requires:
+  env: [PROTONMAIL_ACCOUNT, PROTONMAIL_BRIDGE_PASSWORD]
+```
+
+```
+PROTONMAIL_ACCOUNT=user@pm.me
+PROTONMAIL_BRIDGE_PASSWORD=<bridge-app-password>
+```
+
+**Transferable config pattern:** env vars with config-override fallback; same naming scheme for Hermes (`HERMES_PROTON_ACCOUNT`, `HERMES_PROTON_BRIDGE_PASSWORD`).
+
+#### Security Evolution (v0.1.0 → v0.1.1)
+- v0.1.0: TLS bypass without localhost enforcement
+- v0.1.1: Hosts validated against `['127.0.0.1', 'localhost', '::1']`
+- **Hermes-proton must follow the hardened pattern**
+
+---
+
+## 2. Cross-Cutting Patterns
+
+### 2.1 Auth Strategy Comparison
+
+| Approach | Projects | Pros | Cons |
+|----------|----------|------|------|
+| **SRP Direct** | hydroxide, rclone, proton-cli, proton-webdav, proton-tui | No dependency; full API access; all products | Complex implementation; 2FA handling; CAPTCHA required; token refresh logic |
+| **Bridge Protocol** | pm-cli, openclaw-skill | No crypto needed; no 2FA; no CAPTCHA; stable IMAP/SMTP | Mail only; Bridge dependency; self-signed TLS; local process only |
+
+**Recommendation for Hermes-proton:** Support both paths — Bridge for mail (fastest path, proven), SRP for Calendar/Drive/Pass/VPN (via go-proton-api or proton-cli patterns).
+
+### 2.2 SRP Implementation Details (Consensus Across Projects)
+
+1. **Go standard:** `ProtonMail/go-srp` — official library, used by 4/4 Go projects
+2. **Rust alternative:** `num-bigint` + `sha2` + `bcrypt` — standalone impl in proton-tui/auth.rs
+3. **Key derivation:** bcrypt (cost 10, `$2y$`) → 4×SHA-512 (expand to 2048 bits) → modulus operations
+4. **Modulus verification:** PGP clearsigned modulus response verified against Proton's hardcoded public key
+5. **2FA:** Bitmap check (`Enabled & 1`); TOTP only in all projects
+6. **CAPTCHA:** Only roman-16/proton-cli has a solution (embedded webview helper)
+
+### 2.3 Token/Session Persistence Patterns
+
+| Project | Location | Encryption | Format |
+|---------|----------|------------|--------|
+| hydroxide | `~/.config/hydroxide/auth.json` | NaCl secretbox (XSalsa20-Poly1305) | JSON map |
+| proton-cli | `~/.config/proton-cli/sessions/<profile>.json` | Filesystem perms (0600) | JSON |
+| proton-webdav | `$XDG_DATA_HOME/proton-webdav-bridge/tokens.json` | Filesystem perms (0600) | JSON |
+| proton-tui | `~/.config/proton-tui/tokens.json` | Filesystem perms (0600) | JSON |
+| pm-cli | OS keyring (libsecret/Keychain) | Platform keyring | N/A |
+
+**Recommendation:** Use OS keyring for Bridge password (pm-cli pattern); encrypt cached tokens with NaCl secretbox if stored on disk (hydroxide pattern).
+
+### 2.4 Error Handling Patterns
+
+| Pattern | Found In | Details |
+|---------|----------|---------|
+| 401 auto-retry with refresh | hydroxide, proton-cli, rclone | Single retry with ReAuth callback |
+| Typed error hierarchy | proton-cli, pm-cli, hydroxide | APIError, ExitError, WrongTableError |
+| Cross-table probing | proton-cli | 422 → probe opposite table |
+| Exit code mapping | proton-cli | 0-130 typed codes |
+| Structured JSON errors | pm-cli | `{"success": false, "error": "..."}` |
+| 429 not handled | All projects | **Gap for production** — no project implements 429 backoff |
+
+### 2.5 Crypto Stack
+
+| Component | Standard Library | Used By |
+|-----------|-----------------|---------|
+| OpenPGP (X25519) | `go-crypto` / `gopenpgp v2` | hydroxide, rclone, proton-cli, proton-webdav |
+| Symmetric encryption | NaCl secretbox (XSalsa20-Poly1305) | hydroxide (session storage) |
+| AES-256-GCM | Standard library | proton-cli (Pass items) |
+| Card encryption | OpenPGP + signing | proton-cli, hydroxide |
+| Key derivation | bcrypt + SHA-512 | All SRP-based projects |
+
+---
+
+## 3. Critical Risks
+
+### 3.1 Archived Dependencies
+
+Two projects that use SRP direct for Drive (`rclone protondrive`, `proton-webdav-bridge`) depend on archived libraries:
+- `henrybear327/Proton-API-Bridge` — archived Feb 2026
+- `henrybear327/go-proton-api` — archived Feb 2026
+- `StollD/proton-drive` — single-contributor
+
+**Mitigation:** Use `roman-16/proton-cli`'s approach instead (direct `go-proton-api` from ProtonMail, or use the official Proton Go SDK).
+
+### 3.2 No 429 Handling
+
+None of the 7 projects implement explicit rate-limit backoff. For a production agent making many API calls, this is a gap that must be filled.
+
+### 3.3 Headless CAPTCHA
+
+Only roman-16/proton-cli handles CAPTCHA (via embedded webview helper). For headless agent environments, CAPTCHA is a blocker unless using the Bridge path (which bypasses CAPTCHA entirely).
+
+### 3.4 2FA Limitations
+
+- Token refresh failure + 2FA enabled = cannot auto-re-auth (hydroxide)
+- Only TOTP supported; U2F/WebAuthn unimplemented in all projects
+- Bridge path avoids 2FA entirely
+
+---
+
+## 4. Recommendations for Hermes-Proton
+
+### 4.1 Architecture
+
+Adopt roman-16/proton-cli's **3-tier layered architecture**:
+1. **Plugin layer** (Komodo plugin) — auth lifecycle, session management, shared state
+2. **Service layer** (Hermes skills) — per-product tool collections
+3. **Transport layer** — Bridge (mail) + SRP direct (Calendar/Drive/Pass/VPN)
+
+### 4.2 Auth Paths
+
+**Path A: Bridge (mail only)**
+- OpenClaw-skill pattern: IMAP `127.0.0.1:1143` + SMTP `127.0.0.1:1025`
+- Env vars: `HERMES_PROTON_ACCOUNT`, `HERMES_PROTON_BRIDGE_PASSWORD`
+- Localhost-enforced TLS with self-signed cert acceptance
+- OS keyring for credential storage (pm-cli pattern)
+
+**Path B: SRP Direct (all products)**
+- roman-16/proton-cli's auth flow as reference
+- `go-srp` for Go-based components
+- proton-tui's `auth.rs` for Rust-based components
+- NaCl secretbox encrypted token cache (hydroxide pattern)
+- Cross-table error probing for ID resolution
+
+### 4.3 Agent-Friendly Output (pm-cli patterns)
+
+- Universal `--json` flag with `{"success": true, "data": {...}}` envelope
+- `--help-json` for tool introspection
+- Idempotency keys for mutation operations
+- Semantic subcommands (`summarize`, `extract`)
+- Consistent exit codes
+
+### 4.4 Must-Avoid
+
+- Do NOT vendor archived `henrybear327` libraries (use official `ProtonMail/go-srp` + `go-proton-api`)
+- Do NOT skip 429 handling
+- Do NOT allow non-localhost TLS bypass (follow openclaw-skill's hardening)
+- Do NOT hard-code single-protocol assumptions (support both Bridge and SRP)
+
+### 4.5 Key File Locations to Reference
+
+| Pattern | Source Project | File |
+|---------|---------------|------|
+| SRP auth (Go) | hydroxide | `protonmail/auth.go`, `protonmail/srp.go` |
+| SRP auth (Go, idomatic) | proton-cli | `internal/api/auth.go` |
+| SRP auth (Rust) | proton-tui | `src/auth.rs` |
+| NaCl session storage | hydroxide | `auth/auth.go` |
+| Bridge IMAP client | openclaw-skill | `src/imap.ts` |
+| Bridge SMTP client | openclaw-skill | `src/smtp.ts` |
+| Agent-friendly output | pm-cli | `internal/output/formatter.go` |
+| Error classification | proton-cli | `internal/app/app.go` |
+| Card encryption | proton-cli | `internal/pgp/cards.go` |
+| Drive encryption | proton-webdav | entire `proton-drive` library |
+| Session persistence | proton-tui | `src/tokens.rs` |
+| Multi-profile config | proton-cli | `internal/config/` |
+
+---
+
+## 5. Dependency Matrix for Hermes-Proton
+
+| Component | Recommended Library | Version | Source |
+|-----------|-------------------|---------|--------|
+| Go SRP | `github.com/ProtonMail/go-srp` | v0.0.7 | Official |
+| Go API Client | `github.com/ProtonMail/go-proton-api` | latest | Official |
+| OpenPGP/Crypto | `github.com/ProtonMail/go-crypto` | v1.4.1 | Official |
+| Go OpenPGP (high-level) | `github.com/ProtonMail/gopenpgp/v2` | v2.10.0 | Official |
+| Rust SRP | `num-bigint` + `sha2` + `bcrypt` | latest | proton-tui auth.rs pattern |
+| Node IMAP | `imap` | latest | openclaw-skill pattern |
+| Node SMTP | `nodemailer` | latest | openclaw-skill pattern |
+| Node Mail Parse | `mailparser` | latest | openclaw-skill pattern |
+| OS Keyring (Go) | `zalando/go-keyring` | latest | pm-cli pattern |
+| Embedded DB | `go.etcd.io/bbolt` | v1.4.3 | hydroxide pattern |
+| Webview (Go) | webview/webview | — | proton-cli HV pattern |