@bobfrankston/mailx-settings 0.1.6 → 0.1.9

package/index.d.ts

@@ -15,7 +15,7 @@
  *
  * The old settings.jsonc is still supported for backward compatibility.
  */
-import type { MailxSettings, AccountConfig, AutocompleteSettings } from "@bobfrankston/mailx-types";
+import type { MailxSettings, AccountConfig, AutocompleteSettings, AiKeys } from "@bobfrankston/mailx-types";
 declare const LOCAL_DIR: string;
 /** Subscribers notified whenever lastCloudError changes (push to UI immediately). */
 type CloudErrorListener = (error: string | null, context?: {
@@ -38,6 +38,9 @@ export declare function getStorageInfo(): {
     provider: string;
     mode: "mount" | "api" | "local";
     cloudPath?: string;
+    folderName?: string;
+    folderId?: string;
+    configDir?: string;
     cloudError?: string;
 };
 /** Fill in provider defaults for an account based on email domain.
@@ -78,7 +81,11 @@ declare const DEFAULT_ALLOWLIST: {
 };
 /** Load account configs */
 export declare function loadAccounts(): AccountConfig[];
-/** Load accounts with cloud API fallback (async — use when cloud settings may not be mounted) */
+/** Load accounts, preferring the cloud copy when cloud is configured.
+ *  The local file in `~/.rmfmail/` is an offline cache, NOT the source of
+ *  truth — earlier versions returned the local copy whenever it was non-empty,
+ *  which left the desktop reading a stale single-account file forever after
+ *  the GDrive folder lookup got fixed. */
 export declare function loadAccountsAsync(): Promise<AccountConfig[]>;
 /** Strip default-valued fields from a normalized AccountConfig so the
  *  serialized JSONC stays compact and human-editable. The previous version
@@ -100,8 +107,32 @@ export declare function denormalizeAccount(acct: AccountConfig, globalName?: str
 /** Save account configs */
 /** Save accounts — merges with cloud copy by email (multi-client safe).
  *  Writes the lean form via denormalizeAccount so accounts.jsonc stays
- *  compact and human-editable. */
+ *  compact and human-editable. Preserves the top-level `keys` field
+ *  (AI API keys) if present in the existing cloud or local file. */
 export declare function saveAccounts(accounts: AccountConfig[]): Promise<void>;
+/** Load top-level AI keys from accounts.jsonc. Returns empty placeholders
+ *  ({ anthropic: "", openai: "" }) when the file lacks a `keys` section,
+ *  so callers can call this unconditionally without missing-section guards.
+ *  Reads from the same shared/local path resolution as loadAccounts. */
+export declare function loadKeys(): AiKeys;
+/** Save AI keys back to accounts.jsonc, preserving the rest of the file
+ *  (accounts list, file-level name). Used by Settings → AI to persist a
+ *  key the user just entered. Cloud-synced via saveFile. */
+export declare function saveKeys(keys: AiKeys): Promise<void>;
+/** First-run helper: ensure `keys: { anthropic: "", openai: "" }` is
+ *  materialized in accounts.jsonc so the user sees placeholders for every
+ *  supported provider when they open the config editor. Adds missing
+ *  fields without disturbing existing values, so `keys: {}` becomes
+ *  `keys: { anthropic: "", openai: "" }` and `keys: { anthropic: "sk-..." }`
+ *  becomes `keys: { anthropic: "sk-...", openai: "" }`. Idempotent. */
+export declare function ensureKeysSectionExists(): Promise<void>;
+/** First-run helper: materialize the `autocomplete` block in
+ *  preferences.jsonc with explicit defaults. loadPreferences() merges
+ *  defaults at read time, but the file on disk often has no
+ *  `autocomplete` key, so a user opening Settings → Edit config files
+ *  doesn't see the AI provider knobs. This writes the defaults out so
+ *  the user can edit them. Idempotent. */
+export declare function ensureAutocompletePrefsExist(): Promise<void>;
 /** Load preferences (shared + local overrides, with legacy fallback) */
 export declare function loadPreferences(): typeof DEFAULT_PREFERENCES;
 /** Save preferences */
@@ -127,8 +158,8 @@ export { getSharedDir };
 /** Initialize local config if it doesn't exist */
 export declare function initLocalConfig(sharedDir?: string, storePath?: string): void;
 /** Initialize config with Google Drive cloud storage.
- *  Finds or creates the app-owned "mailx" folder via Drive API and stores its ID.
- *  No mount scanning — API only. Existing settings at other paths (e.g., home/.mailx
+ *  Finds or creates the app-owned ".rmfmail" folder via Drive API and stores its ID.
+ *  No mount scanning — API only. Existing settings at other paths (e.g., home/.rmfmail
  *  from Desktop sync) must be migrated manually or via config.jsonc importPath. */
 export declare function initCloudConfig(provider?: "gdrive"): Promise<void>;
 declare const DEFAULT_SETTINGS: MailxSettings;
@@ -137,4 +168,20 @@ export declare function getHistoryDays(accountId?: string): number;
 /** Get prefetch setting: download bodies during sync (default true) */
 export declare function getPrefetch(): boolean;
 export { DEFAULT_SETTINGS, DEFAULT_ALLOWLIST, DEFAULT_PREFERENCES, DEFAULT_AUTOCOMPLETE, LOCAL_DIR };
+/** Deploy the app-owned `.md` reference docs to the shared cloud folder so
+ *  users can read them next to the `.jsonc` files they document. The .md
+ *  files live in the app bundle (`<workspace>/app/docs/` in dev, or
+ *  `<package>/docs/` in published builds) and are overwritten on every
+ *  release — the file header documents that fact, so users know not to
+ *  edit them.
+ *
+ *  Skip-path: a manifest file `.docs-version` on the cloud records the
+ *  app version that last deployed. We re-deploy only when the running
+ *  app's version differs, so startup doesn't pound Drive on every launch.
+ *
+ *  This function is fire-and-forget at the call site; failures are logged
+ *  but never throw. The `.md` files are reference material, not load-
+ *  bearing — the app works without them.
+ */
+export declare function deployDocs(appVersion: string): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"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"}

package/index.js

@@ -18,9 +18,131 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { parse as parseJsonc } from "jsonc-parser";
-import { getCloudProvider, gDriveFindOrCreateFolder } from "./cloud.js";
+import { getCloudProvider, gDriveFindOrCreateFolder, gDriveValidateCachedFolder } from "./cloud.js";
+const __dirname = import.meta.dirname;
 // ── Paths ──
-const LOCAL_DIR = path.join(process.env.USERPROFILE || process.env.HOME || ".", ".mailx");
+// REMOVE 2026-06-15 — one-shot migration of legacy ~/.mailx → ~/.rmfmail.
+// Five cases handled (idempotent — running twice is safe):
+//   1. only ~/.mailx: rename to ~/.rmfmail (atomic single move).
+//   2. ~/.mailx contains ONLY a `mailxstore/` subdir while ~/.rmfmail is
+//      already the active config — move the body store across, rewrite
+//      body_path rows in the DB, then remove the empty ~/.mailx. This is
+//      the hybrid-state user (their config jumped to .rmfmail but the
+//      stored body files lived under .mailx because storePath was an
+//      absolute path).
+//   3. both exist with other content in ~/.mailx: rename to ~/.mailx-old
+//      so it's visibly cruft.
+//   4. only ~/.rmfmail (or neither): do nothing.
+// 5 covers config.jsonc with absolute storePath pointing at ~/.mailx —
+// rewritten to a relative "mailxstore" so the path follows the config dir.
+{
+    const home = process.env.USERPROFILE || process.env.HOME || ".";
+    const oldDir = path.join(home, ".mailx");
+    const newDir = path.join(home, ".rmfmail");
+    const asideDir = path.join(home, ".mailx-old");
+    if (!fs.existsSync(newDir) && fs.existsSync(oldDir)) {
+        fs.renameSync(oldDir, newDir);
+        console.log("[migrate] ~/.mailx → ~/.rmfmail");
+    }
+    else if (fs.existsSync(newDir) && fs.existsSync(oldDir)) {
+        // Hybrid: figure out whether `.mailx/` is just a leftover store or
+        // has meaningful content.
+        let entries = [];
+        try {
+            entries = fs.readdirSync(oldDir);
+        }
+        catch { /* */ }
+        const onlyStore = entries.length === 1 && entries[0] === "mailxstore";
+        if (onlyStore) {
+            const oldStore = path.join(oldDir, "mailxstore");
+            const newStore = path.join(newDir, "mailxstore");
+            try {
+                fs.mkdirSync(newStore, { recursive: true });
+                // Recursive move (rename per top-level entry; rename across
+                // dirs on the same volume is atomic, fall back to copy+unlink
+                // if it fails — e.g. when the volumes differ).
+                const moveRecursive = (src, dst) => {
+                    const stat = fs.statSync(src);
+                    if (stat.isDirectory()) {
+                        fs.mkdirSync(dst, { recursive: true });
+                        for (const child of fs.readdirSync(src))
+                            moveRecursive(path.join(src, child), path.join(dst, child));
+                        try {
+                            fs.rmdirSync(src);
+                        }
+                        catch { /* */ }
+                    }
+                    else {
+                        try {
+                            fs.renameSync(src, dst);
+                        }
+                        catch {
+                            fs.copyFileSync(src, dst);
+                            fs.unlinkSync(src);
+                        }
+                    }
+                };
+                for (const child of fs.readdirSync(oldStore)) {
+                    moveRecursive(path.join(oldStore, child), path.join(newStore, child));
+                }
+                try {
+                    fs.rmdirSync(oldStore);
+                }
+                catch { /* */ }
+                try {
+                    fs.rmdirSync(oldDir);
+                }
+                catch { /* may still have files; let next case handle */ }
+                console.log("[migrate] moved ~/.mailx/mailxstore/* → ~/.rmfmail/mailxstore/");
+            }
+            catch (e) {
+                console.warn(`[migrate] mailxstore move failed: ${e.message}`);
+            }
+        }
+        else if (!fs.existsSync(asideDir)) {
+            fs.renameSync(oldDir, asideDir);
+            console.log("[migrate] ~/.mailx → ~/.mailx-old (safe to delete)");
+        }
+    }
+    // Body-path rewrite: any DB rows still pointing at the old absolute
+    // store path get translated to the new one. Fire-and-forget — the DB
+    // module exposes a method called from the daemon's startup; this
+    // module-level migration just touches config.jsonc.
+    const localCfg = path.join(newDir, "config.jsonc");
+    if (fs.existsSync(localCfg)) {
+        try {
+            const raw = fs.readFileSync(localCfg, "utf-8");
+            const stripped = raw.replace(/^\s*\/\/.*$/gm, "").replace(/,(\s*[}\]])/g, "$1");
+            const cfg = JSON.parse(stripped);
+            // Drop storePath entirely when it points at the legacy dir or
+            // is the default — config.jsonc shouldn't pin paths that follow
+            // from where LOCAL_DIR is. Users who actually need a custom
+            // store location keep that override; everyone else gets the
+            // default (~/.rmfmail/mailxstore) without ceremony.
+            if (typeof cfg.storePath === "string") {
+                const p = cfg.storePath;
+                const isLegacyAbs = /[\\/]\.mailx[\\/]mailxstore$/i.test(p);
+                const isDefaultRel = p === "mailxstore";
+                const isDefaultAbs = /[\\/]\.rmfmail[\\/]mailxstore$/i.test(p);
+                if (isLegacyAbs || isDefaultRel || isDefaultAbs) {
+                    delete cfg.storePath;
+                    fs.writeFileSync(localCfg, JSON.stringify(cfg, null, 2));
+                    console.log("[migrate] config.jsonc storePath dropped (using default ~/.rmfmail/mailxstore)");
+                }
+            }
+            // Same for sharedDir.path label (cosmetic — folderId is what matters).
+            if (cfg.sharedDir && typeof cfg.sharedDir === "object" && cfg.sharedDir.path === "home/.mailx") {
+                cfg.sharedDir.path = "home/.rmfmail";
+                fs.writeFileSync(localCfg, JSON.stringify(cfg, null, 2));
+                console.log("[migrate] config.jsonc sharedDir.path → home/.rmfmail");
+            }
+        }
+        catch (e) {
+            console.warn(`[migrate] config.jsonc rewrite failed: ${e.message}`);
+        }
+    }
+}
+const LOCAL_DIR = path.join(process.env.USERPROFILE || process.env.HOME || ".", ".rmfmail");
 const LOCAL_CONFIG_PATH = path.join(LOCAL_DIR, "config.jsonc");
 const LEGACY_CONFIG_PATH = path.join(LOCAL_DIR, "config.json");
 const DEFAULT_STORE_PATH = path.join(LOCAL_DIR, "mailxstore");
@@ -107,10 +229,25 @@ function getSharedDir() {
     // Legacy settingsPath no longer used for shared dir — use loadLegacySettings() for reading only.
     return LOCAL_DIR;
 }
+/** Once-per-process validation flag — verify the cached folderId points at
+ *  an `.rmfmail` folder before trusting it. Catches the cross-version-cache
+ *  corruption case where 1.0.504 cached a wrong ID and never re-discovered. */
+let folderIdValidated = false;
 /** Read a file via cloud API (when filesystem mount not available) */
 export async function cloudRead(filename) {
     if (!pendingCloudConfig)
         return null;
+    // Validate cached folderId once per process. If it points somewhere
+    // other than an `.rmfmail` folder (e.g. an orphan from a buggy version),
+    // drop it and re-discover via gDriveFindOrCreateFolder.
+    if (pendingCloudConfig.folderId && !folderIdValidated) {
+        folderIdValidated = true;
+        const ok = await gDriveValidateCachedFolder(pendingCloudConfig.folderId);
+        if (!ok) {
+            pendingCloudConfig.folderId = undefined;
+            clearFolderIdInConfig();
+        }
+    }
     // Ensure we have a folder ID
     if (!pendingCloudConfig.folderId) {
         pendingCloudConfig.folderId = await gDriveFindOrCreateFolder() || undefined;
@@ -187,12 +324,25 @@ function saveFolderIdToConfig(folderId) {
     }
     catch { /* non-critical */ }
 }
+/** Drop a stale folder ID from config.jsonc so the next cloudRead/cloudWrite
+ *  re-discovers via gDriveFindOrCreateFolder. */
+function clearFolderIdInConfig() {
+    try {
+        const config = readLocalConfig();
+        if (config.sharedDir && typeof config.sharedDir === "object" && !Array.isArray(config.sharedDir)) {
+            delete config.sharedDir.folderId;
+            atomicWrite(LOCAL_CONFIG_PATH, config);
+        }
+    }
+    catch { /* non-critical */ }
+}
 /** Whether cloud API fallback is active */
 export function isCloudMode() {
     return pendingCloudConfig !== null;
 }
 /** Get storage provider info for display */
 export function getStorageInfo() {
+    const configDir = LOCAL_DIR;
     const config = readLocalConfig();
     if (config.sharedDir) {
         const entries = Array.isArray(config.sharedDir) ? config.sharedDir : [config.sharedDir];
@@ -200,7 +350,7 @@ export function getStorageInfo() {
             if (typeof entry === "string") {
                 const resolved = resolveSharedEntry(entry);
                 if (resolved && resolved !== LOCAL_DIR) {
-                    return { provider: "local", mode: "local", cloudPath: resolved };
+                    return { provider: "local", mode: "local", cloudPath: resolved, configDir };
                 }
                 continue;
             }
@@ -208,20 +358,20 @@ export function getStorageInfo() {
             const name = (entry.provider === "gdrive" || entry.provider === "google") ? "gdrive" : entry.provider;
             if (entry.folderId) {
                 // Has folder ID → API mode (don't scan filesystem for mounts)
-                return { provider: name, mode: "api", cloudPath: entry.path, cloudError: lastCloudError || undefined };
+                return { provider: name, mode: "api", cloudPath: entry.path, folderName: entry.path, folderId: entry.folderId, configDir, cloudError: lastCloudError || undefined };
             }
             const resolved = resolveSharedEntry(entry);
             if (resolved && resolved !== LOCAL_DIR) {
-                return { provider: name, mode: "mount", cloudPath: entry.path };
+                return { provider: name, mode: "mount", cloudPath: entry.path, folderName: entry.path, configDir };
             }
         }
         // Not mounted and no folderId — check pendingCloudConfig from initCloudConfig()
         if (pendingCloudConfig) {
             const name = (pendingCloudConfig.provider === "gdrive" || pendingCloudConfig.provider === "google") ? "gdrive" : pendingCloudConfig.provider;
-            return { provider: name, mode: "api", cloudPath: pendingCloudConfig.path, cloudError: lastCloudError || undefined };
+            return { provider: name, mode: "api", cloudPath: pendingCloudConfig.path, folderName: pendingCloudConfig.path, configDir, cloudError: lastCloudError || undefined };
         }
     }
-    return { provider: "local", mode: "local" };
+    return { provider: "local", mode: "local", configDir };
 }
 // ── File helpers ──
 /** Read JSON or JSONC file. If exact path not found, tries .json/.jsonc variant. */
@@ -422,7 +572,7 @@ const DEFAULT_PREFERENCES = {
         ollamaUrl: "http://localhost:11434",
         ollamaModel: "qwen2.5-coder:1.5b",
         cloudApiKey: "",
-        cloudModel: "claude-sonnet-4-20250514",
+        cloudModel: "claude-sonnet-4-5",
         debounceMs: 600,
         maxTokens: 60,
     },
@@ -433,7 +583,7 @@ const DEFAULT_AUTOCOMPLETE = {
     ollamaUrl: "http://localhost:11434",
     ollamaModel: "qwen2.5-coder:1.5b",
     cloudApiKey: "",
-    cloudModel: "claude-sonnet-4-20250514",
+    cloudModel: "claude-sonnet-4-5",
     debounceMs: 600,
     maxTokens: 60,
 };
@@ -532,27 +682,30 @@ function applyAccountOverrides(accounts) {
     }
     return accounts;
 }
-/** Load accounts with cloud API fallback (async — use when cloud settings may not be mounted) */
+/** Load accounts, preferring the cloud copy when cloud is configured.
+ *  The local file in `~/.rmfmail/` is an offline cache, NOT the source of
+ *  truth — earlier versions returned the local copy whenever it was non-empty,
+ *  which left the desktop reading a stale single-account file forever after
+ *  the GDrive folder lookup got fixed. */
 export async function loadAccountsAsync() {
-    // Try sync first (filesystem)
-    const accounts = loadAccounts();
-    if (accounts.length > 0)
-        return accounts;
-    // Try cloud API fallback
+    // Make sure pendingCloudConfig is initialized (calling getSharedDir as a
+    // side effect — it sets pendingCloudConfig from the local config.jsonc).
+    getSharedDir();
+    // Cloud configured → cloud is canonical.
     if (pendingCloudConfig) {
-        console.log("  [cloud] Trying cloud API for accounts...");
         const content = await cloudRead("accounts.jsonc");
         if (content) {
             const data = parseJsonc(content);
             if (data?.accounts || Array.isArray(data)) {
                 const raw = data.accounts || data;
                 const globalName = data.name || "";
+                // cloudRead has already cached content to LOCAL_DIR.
                 return applyAccountOverrides(raw.map((a) => normalizeAccount(a, globalName)));
             }
         }
-        // Legacy settings.jsonc is no longer read — use accounts.jsonc only
+        // Cloud unreachable / unparseable — fall through to local cache.
     }
-    return [];
+    return loadAccounts();
 }
 /** Strip default-valued fields from a normalized AccountConfig so the
  *  serialized JSONC stays compact and human-editable. The previous version
@@ -647,28 +800,44 @@ export function denormalizeAccount(acct, globalName) {
 /** Save account configs */
 /** Save accounts — merges with cloud copy by email (multi-client safe).
  *  Writes the lean form via denormalizeAccount so accounts.jsonc stays
- *  compact and human-editable. */
+ *  compact and human-editable. Preserves the top-level `keys` field
+ *  (AI API keys) if present in the existing cloud or local file. */
 export async function saveAccounts(accounts) {
-    // Merge with cloud: keep all accounts, deduplicate by normalized email
+    // Read existing top-level fields we need to preserve (keys, etc.) before
+    // we rewrite. Prefer cloud over local.
+    let preservedKeys;
+    let cloudCopy;
     try {
         const cloudContent = await cloudRead("accounts.jsonc");
-        if (cloudContent) {
-            const cloud = parseJsonc(cloudContent);
-            const cloudAccts = cloud?.accounts || (Array.isArray(cloud) ? cloud : []);
-            if (cloudAccts.length > 0) {
-                const seen = new Set(accounts.map(a => normalizeEmail(a.email)));
-                for (const ca of cloudAccts) {
-                    if (ca.email && !seen.has(normalizeEmail(ca.email))) {
-                        // Cloud entries are already lean — feed through
-                        // normalizeAccount to coerce to AccountConfig shape.
-                        accounts.push(normalizeAccount(ca));
-                        seen.add(normalizeEmail(ca.email));
-                    }
+        if (cloudContent)
+            cloudCopy = parseJsonc(cloudContent);
+    }
+    catch { /* ignore */ }
+    if (!cloudCopy) {
+        try {
+            const localPath = path.join(LOCAL_DIR, "accounts.jsonc");
+            if (fs.existsSync(localPath))
+                cloudCopy = readJsonc(localPath);
+        }
+        catch { /* ignore */ }
+    }
+    if (cloudCopy?.keys && typeof cloudCopy.keys === "object")
+        preservedKeys = cloudCopy.keys;
+    // Merge with cloud: keep all accounts, deduplicate by normalized email
+    if (cloudCopy) {
+        const cloudAccts = cloudCopy.accounts || (Array.isArray(cloudCopy) ? cloudCopy : []);
+        if (cloudAccts.length > 0) {
+            const seen = new Set(accounts.map(a => normalizeEmail(a.email)));
+            for (const ca of cloudAccts) {
+                if (ca.email && !seen.has(normalizeEmail(ca.email))) {
+                    // Cloud entries are already lean — feed through
+                    // normalizeAccount to coerce to AccountConfig shape.
+                    accounts.push(normalizeAccount(ca));
+                    seen.add(normalizeEmail(ca.email));
                 }
             }
         }
     }
-    catch { /* cloud read failed — save local version */ }
     // Promote a shared "name" to file level when every account has the same
     // name — keeps the JSONC tidy ({ "name": "Bob Frankston", "accounts": [...] }
     // instead of repeating "name" on each entry).
@@ -676,8 +845,106 @@ export async function saveAccounts(accounts) {
     const globalName = names.size === 1 ? [...names][0] : undefined;
     const lean = accounts.map(a => denormalizeAccount(a, globalName));
     const payload = globalName ? { name: globalName, accounts: lean } : { accounts: lean };
+    if (preservedKeys)
+        payload.keys = preservedKeys;
     saveFile("accounts.jsonc", payload);
 }
+/** Load top-level AI keys from accounts.jsonc. Returns empty placeholders
+ *  ({ anthropic: "", openai: "" }) when the file lacks a `keys` section,
+ *  so callers can call this unconditionally without missing-section guards.
+ *  Reads from the same shared/local path resolution as loadAccounts. */
+export function loadKeys() {
+    const sharedDir = getSharedDir();
+    const sharedPath = path.join(sharedDir, "accounts.jsonc");
+    const localPath = path.join(LOCAL_DIR, "accounts.jsonc");
+    let raw = readJsonc(sharedPath);
+    if (!raw)
+        raw = readJsonc(localPath);
+    const keys = raw?.keys;
+    return {
+        anthropic: typeof keys?.anthropic === "string" ? keys.anthropic : "",
+        openai: typeof keys?.openai === "string" ? keys.openai : "",
+    };
+}
+/** Save AI keys back to accounts.jsonc, preserving the rest of the file
+ *  (accounts list, file-level name). Used by Settings → AI to persist a
+ *  key the user just entered. Cloud-synced via saveFile. */
+export async function saveKeys(keys) {
+    let existing = {};
+    try {
+        const cloudContent = await cloudRead("accounts.jsonc");
+        if (cloudContent)
+            existing = parseJsonc(cloudContent) || {};
+    }
+    catch { /* ignore */ }
+    if (!existing.accounts) {
+        try {
+            const localPath = path.join(LOCAL_DIR, "accounts.jsonc");
+            if (fs.existsSync(localPath))
+                existing = readJsonc(localPath) || existing;
+        }
+        catch { /* ignore */ }
+    }
+    const merged = { ...existing.keys, ...keys };
+    // Drop empty-string fields so the on-disk file stays tidy when the user
+    // clears a key (writes `""` from the UI) — keep only meaningful values.
+    const cleaned = {};
+    if (merged.anthropic)
+        cleaned.anthropic = merged.anthropic;
+    if (merged.openai)
+        cleaned.openai = merged.openai;
+    existing.keys = cleaned;
+    saveFile("accounts.jsonc", existing);
+}
+/** First-run helper: ensure `keys: { anthropic: "", openai: "" }` is
+ *  materialized in accounts.jsonc so the user sees placeholders for every
+ *  supported provider when they open the config editor. Adds missing
+ *  fields without disturbing existing values, so `keys: {}` becomes
+ *  `keys: { anthropic: "", openai: "" }` and `keys: { anthropic: "sk-..." }`
+ *  becomes `keys: { anthropic: "sk-...", openai: "" }`. Idempotent. */
+export async function ensureKeysSectionExists() {
+    const sharedDir = getSharedDir();
+    const sharedPath = path.join(sharedDir, "accounts.jsonc");
+    const raw = readJsonc(sharedPath);
+    if (!raw)
+        return; // no accounts file yet — first-time setup will handle it
+    const existing = (raw.keys && typeof raw.keys === "object") ? raw.keys : {};
+    const merged = {
+        anthropic: typeof existing.anthropic === "string" ? existing.anthropic : "",
+        openai: typeof existing.openai === "string" ? existing.openai : "",
+    };
+    // Skip the write if the on-disk shape already matches — avoids touching
+    // accounts.jsonc on every startup and the spurious "config changed" banner.
+    if (raw.keys
+        && typeof raw.keys === "object"
+        && raw.keys.anthropic === merged.anthropic
+        && raw.keys.openai === merged.openai
+        && Object.keys(raw.keys).length === 2)
+        return;
+    raw.keys = merged;
+    saveFile("accounts.jsonc", raw);
+}
+/** First-run helper: materialize the `autocomplete` block in
+ *  preferences.jsonc with explicit defaults. loadPreferences() merges
+ *  defaults at read time, but the file on disk often has no
+ *  `autocomplete` key, so a user opening Settings → Edit config files
+ *  doesn't see the AI provider knobs. This writes the defaults out so
+ *  the user can edit them. Idempotent. */
+export async function ensureAutocompletePrefsExist() {
+    const sharedDir = getSharedDir();
+    const sharedPath = path.join(sharedDir, "preferences.jsonc");
+    let raw = readJsonc(sharedPath);
+    if (!raw)
+        raw = {};
+    if (raw.autocomplete && typeof raw.autocomplete === "object")
+        return; // already present
+    raw.autocomplete = { ...DEFAULT_AUTOCOMPLETE };
+    // Strip the cloudApiKey field — the API key now lives in
+    // accounts.jsonc.keys, not here. Writing "" would mislead users into
+    // editing the wrong file.
+    delete raw.autocomplete.cloudApiKey;
+    saveFile("preferences.jsonc", raw);
+}
 /** Load preferences (shared + local overrides, with legacy fallback) */
 export function loadPreferences() {
     let shared = loadFile("preferences.jsonc", DEFAULT_PREFERENCES);
@@ -797,27 +1064,27 @@ export function initLocalConfig(sharedDir, storePath) {
     const config = {
         ...existing,
         sharedDir: resolvedSharedDir,
-        storePath: storePath || existing.storePath || DEFAULT_STORE_PATH,
+        // storePath is now optional — omit when default. Resolves to
+        // ~/.rmfmail/mailxstore via getStorePath() if not specified.
+        ...(storePath || existing.storePath ? { storePath: storePath || existing.storePath } : {}),
     };
     fs.mkdirSync(LOCAL_DIR, { recursive: true });
     atomicWrite(LOCAL_CONFIG_PATH, config);
 }
 /** Initialize config with Google Drive cloud storage.
- *  Finds or creates the app-owned "mailx" folder via Drive API and stores its ID.
- *  No mount scanning — API only. Existing settings at other paths (e.g., home/.mailx
+ *  Finds or creates the app-owned ".rmfmail" folder via Drive API and stores its ID.
+ *  No mount scanning — API only. Existing settings at other paths (e.g., home/.rmfmail
  *  from Desktop sync) must be migrated manually or via config.jsonc importPath. */
 export async function initCloudConfig(provider = "gdrive") {
     const existing = readLocalConfig();
     if (existing.sharedDir)
         return; // Already configured
-    // Find or create the settings folder via Drive API — tries "home/.mailx"
-    // first (family convention), then "mailx" (default). The found path gets
-    // saved so future lookups don't re-scan.
+    // Find or create the settings folder via Drive API. Stored path is the
+    // canonical post-rebrand location; the folderId is what actually drives
+    // subsequent reads/writes, so even legacy users with the old folder name
+    // work fine since gDriveFindOrCreateFolder resolves whichever exists.
     const folderId = await gDriveFindOrCreateFolder();
-    // Detect which path was actually found by reading back from the API
-    // (gDriveFindOrCreateFolder logs it). For now use "mailx" as default
-    // label — the folderId is what matters for subsequent reads/writes.
-    const sharedDir = { provider, path: "home/.mailx", folderId: folderId || undefined };
+    const sharedDir = { provider, path: "home/.rmfmail", folderId: folderId || undefined };
     const config = { ...existing, sharedDir, storePath: existing.storePath || DEFAULT_STORE_PATH };
     fs.mkdirSync(LOCAL_DIR, { recursive: true });
     atomicWrite(LOCAL_CONFIG_PATH, config);
@@ -848,4 +1115,59 @@ export function getPrefetch() {
     return prefs.sync.prefetch !== false;
 }
 export { DEFAULT_SETTINGS, DEFAULT_ALLOWLIST, DEFAULT_PREFERENCES, DEFAULT_AUTOCOMPLETE, LOCAL_DIR };
+/** Deploy the app-owned `.md` reference docs to the shared cloud folder so
+ *  users can read them next to the `.jsonc` files they document. The .md
+ *  files live in the app bundle (`<workspace>/app/docs/` in dev, or
+ *  `<package>/docs/` in published builds) and are overwritten on every
+ *  release — the file header documents that fact, so users know not to
+ *  edit them.
+ *
+ *  Skip-path: a manifest file `.docs-version` on the cloud records the
+ *  app version that last deployed. We re-deploy only when the running
+ *  app's version differs, so startup doesn't pound Drive on every launch.
+ *
+ *  This function is fire-and-forget at the call site; failures are logged
+ *  but never throw. The `.md` files are reference material, not load-
+ *  bearing — the app works without them.
+ */
+export async function deployDocs(appVersion) {
+    if (!pendingCloudConfig?.folderId)
+        return;
+    const provider = getCloudProvider(pendingCloudConfig.provider, pendingCloudConfig.folderId);
+    if (!provider)
+        return;
+    // Resolve the source docs dir. In dev the workspace has `app/docs/`;
+    // in published packages we look for `docs/` next to this file.
+    const candidates = [
+        path.join(__dirname, "..", "..", "docs"), // workspace dev
+        path.join(__dirname, "docs"), // sibling in published package
+        path.join(__dirname, "..", "docs"), // one level up in some layouts
+    ];
+    let docsDir = "";
+    for (const c of candidates) {
+        if (fs.existsSync(c) && fs.readdirSync(c).some(f => f.endsWith(".md"))) {
+            docsDir = c;
+            break;
+        }
+    }
+    if (!docsDir) {
+        console.log("  [docs] no docs/ dir found in package — skipping deploy");
+        return;
+    }
+    try {
+        const deployedVersion = (await provider.read(".docs-version") || "").trim();
+        if (deployedVersion === appVersion)
+            return; // already up to date
+        const mdFiles = fs.readdirSync(docsDir).filter(f => f.endsWith(".md"));
+        for (const f of mdFiles) {
+            const content = fs.readFileSync(path.join(docsDir, f), "utf-8");
+            await provider.write(f, content);
+        }
+        await provider.write(".docs-version", appVersion);
+        console.log(`  [docs] deployed ${mdFiles.length} .md file(s) for app v${appVersion}`);
+    }
+    catch (e) {
+        console.warn(`  [docs] deploy failed: ${e.message}`);
+    }
+}
 //# sourceMappingURL=index.js.map