@bobfrankston/mailx-settings 0.1.6 → 0.1.9

package/cloud.d.ts

@@ -16,10 +16,35 @@
  * Dropbox (removed 2026-04-06): Never implemented — placeholder only.
  *   Would need Dropbox OAuth app, token management, and Dropbox API v2 calls.
  */
-/** Find the settings folder on GDrive, or create a flat "mailx" folder.
- *  Supports nested paths from config (e.g. "home/.mailx") by walking each
- *  segment. Falls back to the folderId in config if set, so a stale ID that
- *  points to the wrong folder gets corrected on next lookup. */
+/** Verify a cached folder ID still points to an `.rmfmail`-named folder
+ *  the user owns and isn't trashed. Returns true if the ID is good to use,
+ *  false if mailx should drop it and re-discover via gDriveFindOrCreateFolder.
+ *
+ *  Catches the cross-version-corruption case: 1.0.504 had a buggy folder
+ *  lookup that created an empty `rmfmail` folder at My Drive root and cached
+ *  its ID. Once 1.0.505 fixed the lookup, the cached ID still pointed at the
+ *  buggy folder forever — mailx kept reading the 1-account stub instead of
+ *  the user's real `home/.rmfmail/accounts.jsonc`. This validator forces a
+ *  re-discovery whenever the cached ID is wrong. */
+export declare function gDriveValidateCachedFolder(folderId: string): Promise<boolean>;
+/** Find or create the rmfmail settings folder on Google Drive.
+ *
+ *  Lookup order — match the Android side (`mailx-store-web/android-bootstrap.ts`):
+ *    1. `home/.rmfmail/` — the established convention. Bob's family-of-two
+ *       layout has been here since the rebrand. Path scope (`'root' in
+ *       parents` for `home`, then `<homeId> in parents` for `.rmfmail`) is
+ *       what the Android side does, so desktop matches.
+ *    2. `.rmfmail/` at My Drive root — fallback for users who don't have a
+ *       `home/` folder. Mostly hypothetical; included so a brand-new Drive
+ *       still works.
+ *    3. Create `.rmfmail` at My Drive root if neither exists. Don't auto-
+ *       create `home/` — that's a user-organization choice we shouldn't
+ *       make for them.
+ *
+ *  Previously this looked for a literal `rmfmail` (no dot) at root, which
+ *  on clean install created a NEW empty folder alongside the real data,
+ *  orphaning the user's accounts/contacts/etc. Switched to the dotted name
+ *  matching the actual folder convention. */
 export declare function gDriveFindOrCreateFolder(): Promise<string | null>;
 export type CloudProvider = "gdrive" | "google" | "local";
 export interface CloudFile {

package/cloud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud.d.ts","sourceRoot":"","sources":["cloud.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA0JH;;;;;;;;;oDASoD;AACpD,wBAAsB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CA8BnF;AAcD;;;;;;;;;;;;;;;;;6CAiB6C;AAC7C,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAwBvE;AA4ED,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE1D,MAAM,WAAW,SAAS;IACtB,kFAAkF;IAClF,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/C,uGAAuG;IACvG,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,8BAA8B;IAC9B,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAuBtF;AAED;;;;2DAI2D;AAC3D,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAoBvG"}

package/cloud.js

@@ -19,7 +19,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { authenticateOAuth } from "@bobfrankston/oauthsupport";
-const SETTINGS_DIR = path.join(process.env.USERPROFILE || process.env.HOME || ".", ".mailx");
+const SETTINGS_DIR = path.join(process.env.USERPROFILE || process.env.HOME || ".", ".rmfmail");
 // ── Credentials ──
 // Google Drive: reuse iflow's OAuth credentials (same Google Cloud project)
 function findGoogleCredentials() {
@@ -54,10 +54,6 @@ const GDRIVE_TOKEN_DIR = path.join(SETTINGS_DIR, "tokens", "gdrive");
 // The Gmail scope is already mail.google.com (full email), so this isn't a
 // bigger privacy ask. Token cache at tokens/gdrive/ will re-auth on scope change.
 const GDRIVE_SCOPES = "https://www.googleapis.com/auth/drive";
-/** Paths to try when no config.path is set (fresh install). Order matters:
- *  "home/.mailx" is the user convention for shared family settings; "mailx"
- *  is the auto-created default. First one that exists on GDrive wins. */
-const GDRIVE_PATH_SEARCH_ORDER = ["home/.mailx", "mailx"];
 // ── Token helpers ──
 /** Get a GDrive-capable token. Prefers the Gmail token (which now includes
  *  drive scope) — avoids a second OAuth consent prompt. Falls back to the
@@ -103,7 +99,7 @@ async function getGoogleDriveToken() {
     // Strategy 2: dedicated GDrive token (legacy path or non-Gmail setups)
     const creds = findGoogleCredentials();
     if (!creds) {
-        console.error("  [cloud] No Google credentials found (checked ~/.mailx/google-credentials.json and iflow package)");
+        console.error("  [cloud] No Google credentials found (checked ~/.rmfmail/google-credentials.json and iflow package)");
         return null;
     }
     const tokenPath = path.join(GDRIVE_TOKEN_DIR, "token.json");
@@ -179,19 +175,46 @@ async function walkGDrivePath(token, segments, create) {
     }
     return parentId || null;
 }
-/** Resolve a folder ID back to its name (for diagnostic logging). */
-async function gDriveGetFolderName(token, folderId) {
+/** Verify a cached folder ID still points to an `.rmfmail`-named folder
+ *  the user owns and isn't trashed. Returns true if the ID is good to use,
+ *  false if mailx should drop it and re-discover via gDriveFindOrCreateFolder.
+ *
+ *  Catches the cross-version-corruption case: 1.0.504 had a buggy folder
+ *  lookup that created an empty `rmfmail` folder at My Drive root and cached
+ *  its ID. Once 1.0.505 fixed the lookup, the cached ID still pointed at the
+ *  buggy folder forever — mailx kept reading the 1-account stub instead of
+ *  the user's real `home/.rmfmail/accounts.jsonc`. This validator forces a
+ *  re-discovery whenever the cached ID is wrong. */
+export async function gDriveValidateCachedFolder(folderId) {
+    const token = await getGoogleDriveToken();
+    if (!token)
+        return true; // can't verify → trust the cache (no token = nothing else to do)
     try {
-        const res = await fetch(`https://www.googleapis.com/drive/v3/files/${folderId}?fields=name,parents`, {
-            headers: { Authorization: `Bearer ${token}` },
-        });
+        const res = await fetch(`https://www.googleapis.com/drive/v3/files/${folderId}?fields=id,name,trashed,mimeType`, { headers: { Authorization: `Bearer ${token}` } });
+        if (res.status === 404) {
+            console.log(`  [cloud] cached folderId ${folderId} → 404 (folder deleted), re-discovering`);
+            return false;
+        }
         if (!res.ok)
-            return null;
+            return true;
         const data = await res.json();
-        return data.name || null;
+        if (data.trashed) {
+            console.log(`  [cloud] cached folderId ${folderId} is trashed, re-discovering`);
+            return false;
+        }
+        if (data.mimeType !== "application/vnd.google-apps.folder") {
+            console.log(`  [cloud] cached folderId ${folderId} is not a folder (${data.mimeType}), re-discovering`);
+            return false;
+        }
+        if (data.name !== ".rmfmail") {
+            console.log(`  [cloud] cached folderId ${folderId} is named '${data.name}', not '.rmfmail' — re-discovering`);
+            return false;
+        }
+        return true;
     }
-    catch {
-        return null;
+    catch (e) {
+        console.error(`  [cloud] gDriveValidateCachedFolder: ${e.message}`);
+        return true; // network failure → trust the cache
     }
 }
 /** Find a single folder by name, optionally inside a parent. */
@@ -209,48 +232,45 @@ async function gDriveFindFolder(token, name, parentId) {
     const data = await res.json();
     return data.files?.[0]?.id || null;
 }
-/** Find the settings folder on GDrive, or create a flat "mailx" folder.
- *  Supports nested paths from config (e.g. "home/.mailx") by walking each
- *  segment. Falls back to the folderId in config if set, so a stale ID that
- *  points to the wrong folder gets corrected on next lookup. */
+/** Find or create the rmfmail settings folder on Google Drive.
+ *
+ *  Lookup order — match the Android side (`mailx-store-web/android-bootstrap.ts`):
+ *    1. `home/.rmfmail/` — the established convention. Bob's family-of-two
+ *       layout has been here since the rebrand. Path scope (`'root' in
+ *       parents` for `home`, then `<homeId> in parents` for `.rmfmail`) is
+ *       what the Android side does, so desktop matches.
+ *    2. `.rmfmail/` at My Drive root — fallback for users who don't have a
+ *       `home/` folder. Mostly hypothetical; included so a brand-new Drive
+ *       still works.
+ *    3. Create `.rmfmail` at My Drive root if neither exists. Don't auto-
+ *       create `home/` — that's a user-organization choice we shouldn't
+ *       make for them.
+ *
+ *  Previously this looked for a literal `rmfmail` (no dot) at root, which
+ *  on clean install created a NEW empty folder alongside the real data,
+ *  orphaning the user's accounts/contacts/etc. Switched to the dotted name
+ *  matching the actual folder convention. */
 export async function gDriveFindOrCreateFolder() {
     const token = await getGoogleDriveToken();
     if (!token)
         return null;
-    // Read path from config — supports nested like "home/.mailx"
-    let cfgEntry = null;
     try {
-        const cfgPath = path.join(SETTINGS_DIR, "config.jsonc");
-        if (fs.existsSync(cfgPath)) {
-            const raw = fs.readFileSync(cfgPath, "utf-8").replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
-            cfgEntry = JSON.parse(raw).sharedDir;
+        // 1. Try home/.rmfmail (the canonical location)
+        const inHome = await walkGDrivePath(token, ["home", ".rmfmail"], false);
+        if (inHome) {
+            console.log(`  [cloud] Found 'home/.rmfmail' folder (${inHome})`);
+            return inHome;
         }
-    }
-    catch { /* ignore */ }
-    // Build search list: configured path first, then common conventions
-    const configuredPath = (typeof cfgEntry === "object" && cfgEntry?.path) ? cfgEntry.path : null;
-    const pathsToTry = configuredPath
-        ? [configuredPath]
-        : GDRIVE_PATH_SEARCH_ORDER;
-    try {
-        for (const tryPath of pathsToTry) {
-            console.log(`  [cloud] Trying GDrive path: '${tryPath}'`);
-            const segments = tryPath.split(/[/\\]/).filter(Boolean);
-            const folderId = await walkGDrivePath(token, segments, false);
-            if (folderId) {
-                // Resolve folder ID back to name for verification
-                const name = await gDriveGetFolderName(token, folderId);
-                console.log(`  [cloud] Found existing '${tryPath}' → folder '${name || "?"}' (${folderId})`);
-                return folderId;
-            }
-            console.log(`  [cloud] Path '${tryPath}' not found on GDrive`);
+        // 2. Try .rmfmail at root
+        const atRoot = await walkGDrivePath(token, [".rmfmail"], false);
+        if (atRoot) {
+            console.log(`  [cloud] Found '.rmfmail' folder at My Drive root (${atRoot})`);
+            return atRoot;
         }
-        // None found — create the last (simplest) path
-        const createPath = configuredPath || GDRIVE_PATH_SEARCH_ORDER[GDRIVE_PATH_SEARCH_ORDER.length - 1];
-        const segments = createPath.split(/[/\\]/).filter(Boolean);
-        const created = await walkGDrivePath(token, segments, true);
+        // 3. Create .rmfmail at root (don't try to create `home/`)
+        const created = await walkGDrivePath(token, [".rmfmail"], true);
         if (created)
-            console.log(`  [cloud] Created '${createPath}' folder: ${created}`);
+            console.log(`  [cloud] Created '.rmfmail' folder at My Drive root (${created})`);
         return created;
     }
     catch (e) {

package/copy-docs.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * copy-docs.js — pre-pack hook for mailx-settings.
+ *
+ * The reference docs live at `<workspace>/app/docs/*.md` so they're easy
+ * to edit and discover in the source tree. The published npm package
+ * needs them as a sibling of index.js so `deployDocs()` can find them at
+ * runtime via `__dirname/docs/`. This script copies the workspace docs
+ * into a local `./docs/` directory just before npm publish, then npm's
+ * `files` field includes them in the tarball.
+ *
+ * Idempotent — safe to run multiple times. Source path is the workspace
+ * root resolved upward from this package.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const __dirname = import.meta.dirname;
+const src = path.join(__dirname, "..", "..", "docs");
+const dst = path.join(__dirname, "docs");
+
+if (!fs.existsSync(src)) {
+    console.log(`[mailx-settings] no source docs at ${src} — skipping copy`);
+    process.exit(0);
+}
+fs.mkdirSync(dst, { recursive: true });
+const files = fs.readdirSync(src).filter(f => f.endsWith(".md"));
+for (const f of files) {
+    fs.copyFileSync(path.join(src, f), path.join(dst, f));
+}
+console.log(`[mailx-settings] copied ${files.length} .md file(s) from app/docs/ → docs/`);

package/docs/accounts.md

@@ -0,0 +1,46 @@
+# accounts.jsonc
+
+> **Owned by rmfmail. Do not edit this file — your changes will be overwritten the next time the app starts.** The canonical copy ships with each release; this file is a deployed copy for reference. To change account *settings*, edit `accounts.jsonc` (which IS user-editable). To change *documentation*, file an issue.
+
+## What this file documents
+
+`accounts.jsonc` lists every email account rmfmail manages. It lives in your shared GDrive folder (`My Drive/home/.rmfmail/`) so all your devices read the same list.
+
+## Shape
+
+```jsonc
+{
+  "name": "Bob Frankston",         // optional; default name applied to every account that doesn't override
+  "accounts": [
+    {
+      "id": "gmail",                // short tag used in folder paths and the UI
+      "email": "you@example.com",   // primary login address
+      "name": "Bob Frankston",      // display name (optional if file-level name is set)
+      "imap": { "host": "imap.example.com", "port": 993, "tls": true, "auth": "password" },
+      "smtp": { "host": "smtp.example.com", "port": 465, "tls": true, "auth": "password" },
+      "enabled": true,              // false skips this account at startup
+      "identityDomains": ["alias.com"]  // extra domains for Reply-From auto-detect
+    }
+  ],
+  "keys": {                         // AI provider API keys (optional)
+    "anthropic": "",                // sk-ant-api03-...
+    "openai": ""                    // sk-...
+  }
+}
+```
+
+## Field rules
+
+- **id** — short identifier. Used in folder paths (e.g. `bob.ma/INBOX`) and as a stable key when accounts.jsonc is edited.
+- **email** — primary login. Determines provider auto-config when `imap`/`smtp` are omitted.
+- **imap / smtp** — explicit server config. Omit for known providers (Gmail / Outlook / Yahoo / iCloud / Google Workspace are detected from the email domain via MX records).
+- **auth** — `"password"` for traditional IMAP/SMTP, `"oauth2"` for Gmail/Google Workspace/Outlook.
+- **enabled** — set `false` to keep the account record but skip sync at startup.
+- **identityDomains** — addresses you receive at on alternative domains. When you Reply, rmfmail picks the matching identity address as From instead of the account's primary.
+- **keys.anthropic / keys.openai** — API keys for the AI features (translate / proofread / summarize / autocomplete). Lives at the file's top level alongside `accounts:` so you set it once across all your devices. Generated at console.anthropic.com or platform.openai.com. Provider selection is in `preferences.jsonc`; the key here is read based on which provider is active. Empty string means "not configured" — the AI feature silently no-ops. Local Ollama provider needs no key.
+
+## Notes
+
+- JSONC: `// line comments` and trailing commas are allowed. The parser is lenient.
+- Adding/removing accounts requires a daemon restart (`rmfmail -kill && rmfmail`). A status banner reminds you when the file changes.
+- For OAuth accounts (Gmail, Google Workspace), the token cache lives in `~/.rmfmail/tokens/` and is per-machine.

package/docs/allowlist.md

@@ -0,0 +1,27 @@
+# allowlist.jsonc
+
+> **Owned by rmfmail. Do not edit this file — your changes will be overwritten the next time the app starts.** This is reference documentation. To change allow-list data, edit `allowlist.jsonc` itself.
+
+## What this file documents
+
+`allowlist.jsonc` controls which senders' remote content (images, etc.) loads automatically and which senders/domains are flagged with a ⚠ banner. Lives in `My Drive/home/.rmfmail/`.
+
+## Shape
+
+```jsonc
+{
+  "senders": ["alice@example.com"],         // load remote content for these senders
+  "domains": ["example.com"],                // load remote content for any sender at these domains
+  "recipients": ["you@example.com"],         // addresses you receive at — treated as "your inbox identity"
+  "flaggedSenders": ["spam@bad.com"],        // viewer shows ⚠ FLAGGED banner for these senders
+  "flaggedDomains": ["phishing.example"]     // viewer shows ⚠ FLAGGED banner for any sender at these domains
+}
+```
+
+## Notes
+
+- All entries are case-insensitive plain email or domain strings.
+- Multi-client safe: each device's save merges with the cloud copy (set-union), so adds from any device propagate.
+- Use the message viewer's "allow remote content" button to add a sender/domain to `senders`/`domains` interactively.
+- Use the right-click menu in the viewer to flag a sender/domain — adds to `flaggedSenders`/`flaggedDomains`.
+- JSONC: `// line comments` and trailing commas are allowed.

package/docs/clients.md

@@ -0,0 +1,24 @@
+# clients.jsonc
+
+> **Owned by rmfmail. Do not edit this file — your changes will be overwritten the next time the app starts.** This is reference documentation.
+
+## What this file documents
+
+`clients.jsonc` is the registry of devices running rmfmail under your account. It's auto-managed: each device adds itself on first launch and refreshes its `lastSeen` timestamp on every startup. You don't normally need to look at it.
+
+## Shape
+
+```jsonc
+{
+  "devices": [
+    { "id": "abc-uuid", "name": "Pixel 9 Pro Fold", "lastSeen": 1746381600000, "accounts": ["gmail", "bobma"] },
+    { "id": "def-uuid", "name": "rmf39 desktop",     "lastSeen": 1746399999000, "accounts": ["gmail", "bobma"] }
+  ]
+}
+```
+
+## Notes
+
+- `id` is a stable UUID generated on first launch and stored locally (`localStorage` on Android, config dir on desktop).
+- `accounts` is the list of account ids this device is currently configured for.
+- Removing a device from this file forces it to re-register on next launch — harmless but pointless.

package/docs/config.md

@@ -0,0 +1,32 @@
+# config.jsonc
+
+> **Owned by rmfmail. Do not edit this DOCUMENTATION file — changes will be overwritten.** Note: the **actual** `config.jsonc` IS user-editable; this `.md` file is just the reference for it.
+
+## What this file documents
+
+`config.jsonc` is your *local, per-machine* config. It is **NOT** synced to GDrive — every machine has its own. It points at the shared GDrive folder and overrides machine-specific paths.
+
+Lives at `~/.rmfmail/config.jsonc` on the local filesystem.
+
+## Shape
+
+```jsonc
+{
+  "sharedDir": {
+    "provider": "gdrive",
+    "path": ".rmfmail",                            // folder name in My Drive (currently My Drive/home/.rmfmail)
+    "folderId": "1AbCdEf...XYZ"                    // resolved Drive folderId, cached after first lookup
+  },
+  "storePath": "~/.rmfmail/mailxstore",            // local directory for .eml message bodies
+  "historyDays": 30                                // how far back to sync; overrides the shared default
+}
+```
+
+## Notes
+
+- `sharedDir.provider`: `"gdrive"` is the only currently-supported value (OneDrive/Dropbox were removed).
+- `sharedDir.folderId` is resolved at startup if missing; caching it avoids a Drive query on every launch.
+- `storePath` is where `.eml` bodies are stored locally. Defaults to `~/.rmfmail/mailxstore` on desktop. Android uses app-private sandbox storage and ignores this field.
+- `historyDays` is a per-machine override for the cloud-synced default in `preferences.jsonc`.
+- Because this file is local, edits don't propagate to other devices. Use `accounts.jsonc` / `preferences.jsonc` for shared settings.
+- JSONC: `// line comments` and trailing commas are allowed.

package/docs/contact-rules.md

@@ -0,0 +1,40 @@
+# contact-rules.jsonc
+
+> **Owned by rmfmail. Do not edit this file — your changes will be overwritten the next time the app starts.** This is reference documentation. The actual rules ship with the app and update on every release.
+
+## What this file documents
+
+`contact-rules.jsonc` defines the **global** junk-contact filter patterns (noreply, mailer-daemon, gateway domains, one-off-shape locals, etc.). It is *NOT* user-editable — it's part of the app, deployed alongside your data so you can see what's being filtered.
+
+User-specific filters live in `contacts.jsonc` (`denylist` exact match; `denylistPatterns` regex array — TODO).
+
+## Shape
+
+```jsonc
+{
+  "rulesVersion": "v3-domain-oneoff",   // bump when patterns tighten — triggers one-shot purge
+  "junk": {
+    "localExact":  "^(no-?reply|do-?not-?reply|noreply|mailer-daemon|...)$",
+    "localSuffix": "(-bounces|\\+bounces|-noreply|-no-reply|...)$",
+    "localPrefix": "^(no-?reply|noreply|notifications?|alerts?|bounces?|mailer)[-_+]",
+    "localOneoff": "^[0-9a-f]{4,}\\.[0-9a-f]{4,}(\\.[0-9a-z]{6,})?$",
+    "domain":      "^(txt\\.voice\\.google\\.com|reply\\.facebook\\.com|reply\\.linkedin\\.com)$"
+  }
+}
+```
+
+## How rules apply
+
+Each newly-harvested address is checked against ALL rule patterns; any match drops it. Each rule is a single regex, case-insensitive:
+
+- **localExact** — whole-string match against the local part (before `@`).
+- **localSuffix** — local part ends with the pattern.
+- **localPrefix** — local part begins with the pattern + a `-` / `_` / `+` separator. Catches `noreply-<random>` style.
+- **localOneoff** — full-shape match for per-message gateway addresses (Google Voice SMS uses three dot-separated alphanumeric segments).
+- **domain** — whole-string match against the domain (after `@`).
+
+## When rules update
+
+Each rmfmail release ships an updated `contact-rules.jsonc`. On startup, the app compares the bundled `rulesVersion` to the value stored locally. If they differ, the app sweeps the contacts table once and removes rows the new rules now reject — then records the new version so the sweep doesn't repeat.
+
+To add a rule: file an issue, or fork+PR. (Eventually `rules.jsonc` per-user will allow personal additions without forking.)

package/docs/contacts.md

@@ -0,0 +1,48 @@
+# contacts.jsonc
+
+> **Owned by rmfmail. Do not edit this file — your changes will be overwritten the next time the app starts.** This is reference documentation. To change contact data, edit `contacts.jsonc` itself.
+
+## What this file documents
+
+`contacts.jsonc` is your address book. It's split into three tiers and lives in `My Drive/home/.rmfmail/`.
+
+## Shape
+
+```jsonc
+{
+  "preferred": [
+    { "name": "David Reed", "email": "dpreed@example.com", "organization": "Deep Plum" }
+  ],
+  "denylist": [
+    "spammer@example.com"
+  ],
+  "discovered": [
+    { "name": "Bob", "email": "bob@example.com", "useCount": 715, "lastUsed": 1777921829000 }
+  ]
+}
+```
+
+## Tiers
+
+- **preferred** — manually-curated, top-ranked in autocomplete. Add people you actually want to reach quickly.
+- **denylist** — addresses (lowercased) excluded from autocomplete entirely.
+- **discovered** — auto-collected from sent/received mail. `useCount` × recency drives autocomplete ranking. Junk patterns (see below) are dropped at insertion.
+
+## Global junk filter
+
+Addresses matching any of these are dropped at insertion AND swept on startup:
+
+- Whole local part: `noreply`, `no-reply`, `do-not-reply`, `mailer-daemon`, `postmaster`, `bounces`, etc.
+- Local-part prefix: `noreply-<random>`, `notifications-<id>`, `alerts-<x>`, `bounces-<x>`, `mailer-<x>`
+- Local-part suffix: `*-bounces`, `*+bounces`, `*-noreply`, `*-notifications`
+- Multi-segment one-off shape: `16179691997.15082868100.nfblcbll1x` (per-message gateway addresses)
+- Domains: `txt.voice.google.com` (Google Voice SMS gateway), `reply.facebook.com`, `reply.linkedin.com`
+
+The full pattern set lives in `contact-rules.jsonc` (shipped with the app). Bumping `rulesVersion` in that file triggers a one-shot purge of historical rows the new rules now reject.
+
+## Notes
+
+- JSONC: `// line comments` and trailing commas are allowed.
+- `useCount` and `lastUsed` are auto-managed; manually editing them only changes ranking briefly until the next sync.
+- Removing a `preferred` entry doesn't add it to `denylist` — it just demotes back to `discovered` (or drops if not seen in mail).
+- Each device contributes its observed addresses to `discovered`. The file accumulates the union across devices.

package/docs/editor.md

@@ -0,0 +1,92 @@
+# Compose editor — formatting and shortcuts
+
+mailx ships with two rich-text editors: **Quill** (default) and **tiptap**.
+Most things work the same in both. Differences are called out below.
+
+Switch editors via **Settings → Editor → Quill | tiptap**.
+
+## Universal — works in both editors
+
+| Action | Shortcut | Where |
+|---|---|---|
+| **Send** | Ctrl+Enter | toolbar Send button |
+| Bold / Italic / Underline | Ctrl+B / Ctrl+I / Ctrl+U | toolbar B / I / U |
+| Strikethrough | Ctrl+Shift+X | toolbar S |
+| Bulleted list | Ctrl+Shift+8 | toolbar • |
+| Ordered list | Ctrl+Shift+7 | toolbar 1. |
+| Insert / edit link | Ctrl+K | toolbar 🔗 |
+| Remove link | Ctrl+Shift+K | (no toolbar button — use Ctrl+Shift+K) |
+| Blockquote | (Quill: Ctrl+Shift+Q; tiptap: toolbar) | toolbar `“` |
+| Clear formatting | Ctrl+\\ | toolbar ✖ |
+| Heading (H1 / H2 / H3) | (Quill: format dropdown; tiptap: select dropdown) | "Normal / Heading 1 / 2 / 3" |
+| Undo / Redo | Ctrl+Z / Ctrl+Y | (no toolbar button) |
+| Spell-check | (browser native — red underlines) | right-click word |
+| Paste plain text | Ctrl+Shift+V | (browser native) |
+
+## Quill-only
+
+| Action | Shortcut |
+|---|---|
+| Indent / outdent | Ctrl+] / Ctrl+[ |
+| Color text | Ctrl+Shift+C |
+| Format dropdown | toolbar (left side) |
+| Inline code | toolbar `<>` |
+| Code block | toolbar |
+| Image inserter | (no built-in; use drag-and-drop or paste) |
+
+Quill has a more elaborate toolbar with format-specific dropdowns (font,
+size, color). Internally Quill uses its own *Delta* document model — copy/
+paste from Word/Outlook sometimes leaves extra `<p><br></p>` empty
+paragraphs that you'll see in the sent message body.
+
+## tiptap-only
+
+| Action | Where |
+|---|---|
+| Heading select | left of toolbar |
+| Toggle bold / italic / underline / strike | toolbar B / I / U / S |
+| Blockquote | toolbar `“` |
+| Image (drag-and-drop) | drop a file into the body |
+
+tiptap is built on ProseMirror. Output HTML is cleaner than Quill on
+Word/Outlook paste roundtrips. Bundle is smaller. Some Quill toolbar
+features (inline code, indent shortcuts, color picker) aren't wired —
+use the heading select / format menu instead.
+
+## Common features (across both)
+
+- **Drag-and-drop attachments** — drop files anywhere on the compose
+  window to attach. Overlay highlights the drop target while dragging.
+- **Edit in Word / LibreOffice** — toolbar **Edit in Word** button opens
+  the body in your default external editor (configurable in
+  Settings → External editor). Save in the external editor and the body
+  reloads here. Behind the scenes mailx writes a temporary `.docx` file
+  (see `~/.rmfmail/external-edit/`) and watches it for changes.
+- **Auto-save drafts** — every 5 seconds (and on input debounce + on
+  blur). Drafts land in the Drafts folder via IMAP append.
+- **Address auto-completion** — type a partial name in To/Cc/Bcc; matches
+  rank by recency × use-count. Group names from `contacts.jsonc → groups`
+  also surface here.
+- **Address-field expansion** — recipient fields are auto-growing
+  textareas; long lists wrap to multiple lines.
+- **Group expansion on send** — type a group name (e.g. `family`) in
+  To/Cc/Bcc and it expands to the address list at send time.
+- **Ghost-text autocomplete** (off by default) — Settings →
+  AI autocomplete → on. Predicts the next words while you type.
+
+## When the toolbar doesn't appear
+
+The editor loads from a CDN (jsdelivr). If your network can't reach it,
+the toolbar disappears and a plain `contenteditable` fallback takes over.
+Status bar shows the failure. mailx now tries the *other* editor before
+falling all the way back; if both fail you get a plain textarea with no
+shortcuts and no toolbar — sending still works.
+
+## See also
+
+- `accounts.md`, `contacts.md`, `allowlist.md`, `clients.md`, `config.md`,
+  `preferences.md` — config-file references (these live in your GDrive
+  `.rmfmail/` folder).
+- This `editor.md` is **app-internal** — it ships with each release and
+  documents the editor as it currently exists in the version you're
+  running. It is not deployed to your user folder.

package/docs/preferences.md

@@ -0,0 +1,43 @@
+# preferences.jsonc
+
+> **Owned by rmfmail. Do not edit this file — your changes will be overwritten the next time the app starts.** This is reference documentation.
+
+## What this file documents
+
+`preferences.jsonc` holds your shared UI / sync / autocomplete preferences, synced via `My Drive/home/.rmfmail/`.
+
+## Shape
+
+```jsonc
+{
+  "ui": {
+    "theme": "system",            // "system" | "light" | "dark"
+    "twoLine": false,             // two-line message-list rows
+    "previewPane": true,
+    "previewSnippets": true,
+    "threaded": false,
+    "flaggedOnly": false,
+    "folderCounts": false,
+    "calendarSidebar": false,
+    "editor": "quill"             // "quill" | "tiptap"
+  },
+  "sync": {
+    "intervalMinutes": 5,         // full-sync interval (per-folder); IDLE handles INBOX inline
+    "historyDays": 30,            // how far back to sync (overridable per-machine in config.jsonc)
+    "prefetch": true              // background-fetch message bodies after metadata sync
+  },
+  "autocomplete": {
+    "enabled": false,             // ghost-text completions in compose
+    "provider": "ollama",         // "ollama" | "claude" | "openai"
+    "translateEnabled": false,    // AI-powered Translate menu item in viewer
+    "proofreadEnabled": false
+  }
+}
+```
+
+## Notes
+
+- The View menu and Settings menu in the toolbar both write here.
+- `sync.intervalMinutes` controls the full-folder sync cadence. INBOX uses RFC 2177 IDLE (instant push) on Dovecot accounts; Gmail accounts poll every 30s.
+- `sync.historyDays` is a default; override per-machine via `config.jsonc`.
+- AI features are off by default. Enabling `autocomplete.enabled` requires a configured provider (Ollama local, Claude API key, or OpenAI API key).