@bobfrankston/rmfmail 1.2.50 → 1.2.66

package/packages/mailx-settings/docs/local-first-plan.md

@@ -0,0 +1,303 @@
+# Local-first reconciliation plan
+
+> Status: **plan, not implementation**. Reviewed before any code is touched.
+> Owner: Claude. Approver: Bob.
+
+## The rule
+
+The local store is the source of truth for everything the user sees and does.
+The server is a separate, asynchronously-reconciled mirror.
+**No user-action code path waits on a network call.**
+
+Every user-visible read returns from local SQLite + local files in microseconds.
+Every user-visible write commits to the local store synchronously and returns
+the local id immediately. Server-side mirroring is the sync layer's job, not
+the UI's.
+
+This document defines the invariants, the new API split, the event protocol,
+the migration order, and the visible-state model.
+
+## Invariants the implementation must enforce
+
+1. **Reads never await server.** `getMessage`, `getMessages`, `getUnifiedInbox`,
+   `searchMessages` (local scope), `getCalendarEvents`, `getTasks`, autocomplete —
+   all read from local DB and return synchronously. If the IPC layer can't be
+   sync, it must return a Promise that resolves on the same tick.
+
+2. **Writes ACK from a local commit.**
+   - `saveDraft` writes the local Drafts row + `.eml` and returns the local UUID
+     in the same tick. The IMAP push is queued, never awaited.
+   - `send` writes the local Outbox row + `.ltr` and returns immediately. SMTP
+     and Sent-folder append are background work.
+   - `move`, `flag`, `delete` commit the local row mutation, return, and queue
+     the server-side mirror.
+
+3. **The sync queue is the only IMAP-touching code path.** A single background
+   reconciler drains queued local actions to the server, polls for server
+   changes, and emits events to the UI. Nothing else opens an IMAP client.
+
+4. **Local UUIDs are stable; server UIDs are metadata.** Every message gets a
+   local UUID at first sight (sync, draft save, server-search hit). Sync
+   maintains a UUID ↔ (account, folder, server-UID) map. Server-side moves
+   change the UID; the UUID stays. Local moves keep the UUID and queue a
+   server-side move. Tombstones (UUID + deleted flag) prevent re-fetch.
+
+5. **Slow / unreachable server is not a UI failure mode.** Connection caps,
+   IDLE drops, OAuth refresh hangs, 60-second IMAP timeouts — none reach the
+   click → render path. They surface in a non-blocking sync-status indicator.
+
+## Service-side API split
+
+Today's `MailxService` mixes local reads with server-touching code. Split into
+three layers:
+
+### Layer 1: `LocalStore` (sync, never touches network)
+
+Pure local reads + local commits. All synchronous (or trivially async over
+sql.js / fs). Throws if asked to do anything network-y.
+
+```typescript
+class LocalStore {
+    // Reads
+    getMessage(uuid: string): LocalMessage | null;
+    getMessageByUid(accountId: string, uid: number): LocalMessage | null;
+    getMessages(query: MessageQuery): LocalMessage[];
+    getUnifiedInbox(page, pageSize): { items: LocalMessage[]; total: number };
+    searchMessages(query: string, ...): LocalMessage[];   // FTS5 only
+    getCalendarEvents(fromMs, toMs): CalEvent[];
+    getTasks(includeCompleted): Task[];
+    searchContacts(query): Contact[];
+    getMessageBody(uuid: string): { html?: string; text?: string; attachments: ... } | null;
+
+    // Writes — return local UUID, queue server mirror
+    saveDraft(draft: ComposeDraft): { uuid: string };       // queues
+    sendMessage(msg: ComposeMessage): { uuid: string };     // queues
+    moveMessages(uuids: string[], toFolderId: number): { ok: true };
+    flagMessages(uuids: string[], flags: string[]): { ok: true };
+    deleteMessages(uuids: string[]): { ok: true };
+    createCalendarEvent(ev): { uuid: string };
+    updateCalendarEvent(uuid, patch): { ok: true };
+    deleteCalendarEvent(uuid): { ok: true };
+    createTask(t): { uuid: string };
+    updateTask(uuid, patch): { ok: true };
+    deleteTask(uuid): { ok: true };
+}
+```
+
+Every UI IPC call routes through this layer first. The webview never sees
+beyond this.
+
+### Layer 2: `SyncQueue` (async, mediates server)
+
+The only code path that opens IMAP clients, calls Gmail API, posts SMTP, etc.
+Single-threaded per account. Queue persisted across restarts.
+
+```typescript
+class SyncQueue {
+    enqueueMove(uuid, fromFolderId, toFolderId): void;
+    enqueueFlag(uuid, addFlags, removeFlags): void;
+    enqueueDelete(uuid): void;
+    enqueueDraftPush(uuid): void;
+    enqueueSend(uuid): void;
+    enqueueBodyRefresh(uuid): void;          // fire-and-forget; reconciler may dedupe
+
+    // Periodic
+    runPoll(): Promise<void>;                // checks server for new mail, etc.
+
+    // Event emit
+    on(event: "mirrored" | "conflict" | "error", handler): void;
+}
+```
+
+Items in the queue are persistent (SQLite `sync_queue` table with `kind`,
+`payload`, `attempts`, `created_at`, `last_attempt`, `next_attempt`, `status`).
+
+### Layer 3: `Reconciler` (background loop)
+
+Drains the queue, polls for server changes, emits events.
+
+```typescript
+class Reconciler {
+    start(): void;       // long-running tick
+    stop(): void;
+    syncNow(accountId?): void;       // user-initiated "sync now"
+}
+```
+
+Reconciler events:
+- `messageUpserted(uuid, source: "local"|"server")` — UI updates that row
+- `messageRemoved(uuid)` — UI removes the row
+- `bodyAvailable(uuid)` — UI re-fetches body (will hit local cache instantly)
+- `syncStateChanged(accountId, state)` — status indicator updates
+- `conflict(uuid, kind, detail)` — user gets a banner ("local move failed
+  on server because folder is gone")
+
+## Event protocol (local store → UI)
+
+Events flow one-way: store changes → UI redraws affected rows.
+
+| Event | When | UI behavior |
+|---|---|---|
+| `messageUpserted` | new mail synced; flag changed; body cached; envelope refreshed | re-render that row in place; if it's the focused row, re-render preview |
+| `messageRemoved` | server-side delete reconciled; local delete with no undo window | remove row; advance focus to next |
+| `bodyAvailable` | body fetch completed (from prefetch or on-demand reconcile) | re-render preview if this is the focused row |
+| `folderCountsChanged` | unread counts changed | update folder-tree pill |
+| `syncStateChanged` | reconciler started/stopped, account auth issue, sync error | update status bar indicator |
+| `conflict` | local action failed on server | show banner with retry/discard |
+
+Events carry a "sequence number" so the UI can drop stale events when the
+user has navigated away from the affected row.
+
+## Visible state model
+
+Each row carries three independent indicators:
+
+| Indicator | Source | Meaning |
+|---|---|---|
+| Body cached dot (existing teal/blue) | `body_path != null && file exists` | Tap is instant |
+| Local-only outline (new) | `dirty=true && providerId=null` | Not yet pushed to server |
+| Reconciliation pending (new) | `dirty=true && providerId!=null` | Push queued; will sync soon |
+
+Only "body cached" affects how a click renders. The other two are advisory —
+the user knows their action is committed locally and the server side will
+catch up.
+
+A status-bar pill shows `Sync OK` / `Syncing N items` / `Sync errors (click to view)`.
+That's the only UI surface that reflects server state.
+
+## Migration order
+
+Land in this order so each step is independently shippable:
+
+1. **Add `LocalStore` interface and route ALL UI IPC through it.** Service
+   methods become thin wrappers that pull from local DB only. No behavior
+   change yet — server fetches just stop happening on every UI call. Bodies
+   that aren't cached return null with a "not cached" hint.
+
+2. **UI handles the "not cached" case explicitly.** Show a placeholder-with-
+   spinner that says "downloading body…" with no time pressure (the click is
+   already responsive — body just takes time to arrive). Listen for
+   `bodyAvailable` event and re-render. Remove the 15s retry timer band-aid.
+   Remove `body-broken` red-dot band-aid.
+
+3. **Move all current `await imap*` calls in the service into `SyncQueue`
+   enqueue calls.** Drafts: write local + enqueue push. Send: write local +
+   enqueue SMTP. Move/flag/delete: commit local + enqueue mirror. Body fetch
+   on click: read local file or enqueue refresh (with `bodyAvailable` emit
+   when done).
+
+4. **Build the `Reconciler` loop** that drains the queue, runs periodic polls,
+   and emits events. Replace the current `syncAll` with a reconciler that
+   processes both queue items and "sync from server" pulls in priority order.
+
+5. **Add the visible-state indicators** (local-only outline, pending dot,
+   sync-status pill). Wire to the new event stream.
+
+6. **Migrate the conflict path.** When a queued item fails on the server
+   (folder deleted, message gone, auth lapsed), surface a single banner
+   listing the affected items with retry/discard.
+
+7. **Delete the band-aids**: 60s body-fetch timeout, 15s client retry timer,
+   `body-broken` class, "Fetching message body…" placeholder, all stale-gen
+   `if (gen !== showMessageGeneration) return` early-returns.
+
+Each step ships standalone. After step 3 the UI is already responsive
+even if the reconciler isn't built — it just stops doing sync until step 4.
+
+## Concrete call-site changes
+
+### Client side (TypeScript)
+
+Files to touch and what changes:
+
+- `client/components/message-viewer.ts` — `showMessage` becomes synchronous.
+  Reads from local cache, never awaits a server fetch. Body display routed
+  through new `bodyAvailable` event listener.
+- `client/components/message-list.ts` — same for `loadMessages`,
+  `loadUnifiedInbox`, `loadSearchResults` (local scope only).
+- `client/compose/compose.ts` — `saveDraft` and `send` get the local UUID
+  back immediately, no spinner.
+- `client/components/calendar-sidebar.ts` — `getCalendarEvents` /
+  `createCalendarEvent` etc. pure local; events update on `messageUpserted`.
+- `client/lib/api-client.ts` — every method documented as "local read" or
+  "queues server mirror". No method returns a server result directly anymore.
+- `client/app.ts` — wire the new event types into the existing service-
+  channel listener.
+
+### Service side (TypeScript)
+
+- `mailx-service/index.ts` — split. The `MailxService` class stays as the
+  IPC entry point but delegates: reads → `LocalStore`, writes → `LocalStore`
+  + `SyncQueue.enqueue*`, no more direct `imapManager.*` calls from UI
+  handlers.
+- New file `mailx-service/local-store.ts` — pure local reads/writes.
+- New file `mailx-service/sync-queue.ts` — persistent queue + enqueue API.
+- New file `mailx-service/reconciler.ts` — background loop, draining +
+  polling, emits events.
+- `mailx-imap/index.ts` — becomes a worker library called only by the
+  reconciler. UI never sees it.
+
+### Database
+
+- New table `sync_queue (id, kind, payload, attempts, created_at,
+  last_attempt, next_attempt, status, account_id)`.
+- New columns on `messages`: `dirty BOOLEAN` (local-only or pending),
+  `last_local_change_ms` (so reconciler picks oldest first).
+- Existing `body_path` semantics stay.
+
+## What the user sees afterward
+
+- Every click renders in <50ms regardless of server state.
+- Drafts save and Reply opens are instant.
+- New mail appears in the list as soon as the reconciler pulls it (no
+  user wait).
+- A persistent status pill in the bottom-right shows whether sync is
+  current, lagging, or failing.
+- Body fetches that haven't completed show a spinner inside the preview
+  pane that doesn't block interaction with the list.
+- Multi-account: bobma's slowness affects only bobma's status pill, never
+  the UI as a whole.
+
+## Effort
+
+Realistic for solo work, your pace:
+
+- Step 1 (route UI through LocalStore): 1-2 days
+- Step 2 (UI body-not-cached handling): 1 day
+- Step 3 (move IMAP calls into SyncQueue): 2-3 days
+- Step 4 (build Reconciler): 2-3 days
+- Step 5 (visible-state indicators): 1 day
+- Step 6 (conflict path): 1 day
+- Step 7 (delete band-aids): 1 day
+
+Total: ~9-12 working days, shipped incrementally. Each step is its own
+publish; no big-bang.
+
+## Decisions (2026-05-06)
+
+1. **sync_queue concurrency**: priority lanes (interactive > sync > prefetch
+   > backfill) **plus** multiple handlers per lane. The interactive lane is
+   reserved for on-demand body fetches the user just clicked; sync runs in
+   parallel on a different lane. Per-account serialization still applies
+   inside each lane to keep us under Dovecot/Gmail connection caps.
+
+2. **Multi-device conflict**: last-writer-wins. The case (drag-at-the-same-time
+   on two devices) is rare enough that no banner / merge UI is needed. The
+   later push wins; the earlier one is silently superseded.
+
+3. **Tombstones**: live forever, no retention policy. Cost is ~200 bytes per
+   row in the `messages` table — negligible even at 10k deletes/year × 10
+   years. They're shared across devices implicitly: every device syncs the
+   same server state, so a delete on phone propagates to desktop via the
+   server reconcile, no peer-to-peer sync needed. Local-only tombstones
+   (queued delete not yet pushed) stay per-device until the queue drains.
+
+4. **Calendar / tasks / contacts**: same model. No special cases. Today's
+   two-way cache code is already on this pattern; the refactor just makes
+   message paths match.
+
+5. **Outbox**: keep the existing flow as-is. The Drafts → Outbox → Sent
+   directory-based queue works and isn't blocking the UI today; subsuming
+   it would be churn for no user benefit.
+
+Step 1 starts immediately.

package/packages/mailx-settings/docs/npmglobalize-transitive-workspace-deps.md

@@ -0,0 +1,107 @@
+# npmglobalize: transitive workspace dep gap on standalone publish
+
+## Symptom
+
+A workspace member with `npmVisibility: "public"` (`@bobfrankston/mailx-imap`) gets
+published as a standalone registry package. Its tarball declares
+`@bobfrankston/mailx-settings: ^0.1.6` as a registry dep — but
+`mailx-settings` is *also* a workspace member, with no `.globalize.json5`,
+so it was never published. End user runs `npm install -g @bobfrankston/mailx`
+on a fresh machine and gets:
+
+```
+404 Not Found - GET https://registry.npmjs.org/@bobfrankston%2fmailx-settings
+```
+
+Reproducer (mailx workspace, 2026-05-02):
+- `app/packages/mailx-imap/.globalize.json5` → `npmVisibility: "public"`
+- `app/packages/mailx-imap/package.json` → `dependencies: { "@bobfrankston/mailx-settings": "file:../mailx-settings" }`
+- `app/packages/mailx-settings/` exists, no `.globalize.json5`
+- `npmglobalize` from workspace root: builds everything, publishes mailx-imap and the parent mailx, exits with success
+- `mailx-imap`'s published `package.json` rewrote `file:../mailx-settings` → `^0.1.6`
+- `mailx-settings` was never published
+
+## What npmglobalize does today
+
+When publishing a standalone-public workspace member, file: deps that point
+at *other workspace members* get rewritten to registry version constraints
+(`^X.Y.Z`) — same as it'd do for any external file: dep. No check that the
+referenced workspace member is itself public/published.
+
+Result: a tarball whose declared deps 404 on a clean install. The publish
+itself succeeds; the breakage shows up at install time on a remote machine.
+
+## What npmglobalize should do
+
+Pick one (preference order):
+
+### 1. Fail loud at publish time (cheapest, most defensible)
+
+Before publishing a workspace member as standalone-public, walk its file:
+deps. For each that resolves to another workspace member:
+- If that member is also public → fine, the registry constraint will resolve.
+- If that member is **not** public → **refuse to publish** with a clear error:
+
+  ```
+  Refusing to publish @bobfrankston/mailx-imap as a standalone registry
+  package: it depends on @bobfrankston/mailx-settings (workspace member,
+  not public). Published tarball would 404 on install.
+
+  Fixes:
+   - Add .globalize.json5 with npmVisibility: "public" to mailx-settings
+     (and any of its transitive workspace deps).
+   - Or remove .globalize.json5 from mailx-imap so it stays bundled
+     under the parent's tarball.
+  ```
+
+This is the behavior I'd ask for first. It's predictable, errors at the
+site of the mistake, and doesn't silently change packaging.
+
+### 2. Bundle transitive workspace deps in the standalone tarball
+
+When publishing a standalone-public workspace member, copy any non-public
+workspace deps **into the tarball** as bundled directories, and keep file:
+paths instead of rewriting to registry constraints. The published tarball
+becomes self-contained.
+
+Trade-off: tarball gets bigger and pulls in copies on every standalone
+publish. Multiple public members each carry their own copy of shared
+internal deps — duplication on disk, but install-time correctness.
+
+### 3. Auto-promote transitive workspace deps to public
+
+If a public member depends on a non-public workspace member, automatically
+promote the dep to public and publish it too. Cascading.
+
+Trade-off: silently expands the publish surface area — one new public
+package can flip the entire transitive closure to public. Surprising and
+hard to undo. Less defensible than (1) or (2).
+
+## Recommendation
+
+Implement (1). It's a one-pass dependency walk before the publish step,
+returning a clear error message. The other options can layer on later if
+the workflow demands them — but the loud failure prevents the silent-bad-
+publish from ever shipping in the first place.
+
+## Edge cases (1) needs to handle
+
+- **External file: deps** (not workspace members): `file:../../MailApps/iflow-direct`
+  resolves outside the workspace. Today these get rewritten to registry
+  versions and presumably *those* deps are published separately. Don't
+  block on those — only on workspace-internal file: deps.
+- **Public member depends on public member**: fine, registry resolves both.
+- **Public member depends on a registry version that exists**: fine.
+- **Public member depends on a workspace member with `noPublish: true`**:
+  same gap, same fail. Treat noPublish=true workspace members as "not public".
+- **Cyclic deps**: shouldn't apply here (workspace dep graphs are DAGs by
+  npm's own constraint), but if the walk hits one, abort with a different
+  message.
+
+## Why this matters
+
+Symptom is "Mac install fails" — but the root cause is npmglobalize
+publishing a tarball it can't possibly install correctly. The user has
+no signal at publish time; the breakage is invisible until someone tries
+to install the package on a fresh machine. Fail-at-publish makes the
+contract explicit: *if it publishes, it installs.*

package/packages/mailx-settings/docs/outlook.md

@@ -1,31 +1,93 @@
 # Outlook.com / Microsoft 365 Support
 
-Status (2026-06-05): **scaffolding present, not usable.** An account auto-detects
-the right hosts but cannot authenticate — there is no Microsoft OAuth wired, and
-Microsoft has disabled basic-auth (password) for outlook.com / office365, so the
-IMAP path can't fall back to a password either. Gmail is the only fully-wired
-OAuth provider today.
+Status (2026-06-21): **native Graph support implemented and wired as a
+PUBLIC client (PKCE, no secret).** The provider, the Microsoft tokenProvider,
+and the full three-way dispatcher routing (sync, body fetch, flags/move/trash,
+send via Graph `/sendMail`) are done. The **public client_id ships bundled in
+the build** (`packages/mailx-imap/microsoft-credentials.json`), so a fresh
+install needs no credential placement. The only human step is the one-time Azure
+app registration.
 
-This doc scopes what it takes to make Outlook a first-class account.
+> ## ⬇ WHAT ONLY YOU DO (one-time, ~10 min — already done for the `rmfmail` app)
+>
+> The app `rmfmail` is registered; its public client_id
+> `f0df4236-5d26-4aa3-a243-47f043b9db36` is committed in the build. These steps
+> are the recipe to reproduce it (e.g. a fresh app, or a fork):
+>
+> 1. **Register an Azure app** (full walkthrough in [§A](#a-register-the-azure-app--the-part-only-you-can-do) below):
+>    - Entra → App registrations → New registration → name `rmfmail`,
+>      account type **"any org directory + personal Microsoft accounts"**.
+>    - Redirect URI: platform **"Mobile and desktop applications"** = **`http://localhost`**.
+>    - **Authentication → Advanced settings → "Allow public client flows" → Yes.**
+>      (Required for the no-secret PKCE flow.)
+>    - **No client secret.** Skip "Certificates & secrets" entirely — a public
+>      client doesn't use one (this is what removes the 2-year renewal chore).
+>    - API permissions → Microsoft Graph → **Delegated**: `Mail.ReadWrite`,
+>      `Mail.Send`, `offline_access`, `openid`, `profile`.
+> 2. **Put the public client_id in the build** — edit
+>    `packages/mailx-imap/microsoft-credentials.json` (already present for
+>    `rmfmail`; client_id only, **never a secret**):
+>    ```json
+>    {
+>      "installed": {
+>        "client_id": "<Application (client) ID>",
+>        "auth_uri": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+>        "token_uri": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+>        "redirect_uris": ["http://localhost"]
+>      }
+>    }
+>    ```
+>    A per-machine override at `~/.rmfmail/microsoft-credentials.json` (note:
+>    **`.rmfmail`, not `.mailx`** — that's `getConfigDir()`) takes precedence if
+>    present, but isn't needed.
+> 3. **Add an Outlook account** to `accounts.jsonc` (cloud-canonical copy, e.g.
+>    `<Drive>/Home/.rmfmail/accounts.jsonc`) — just `{ "id": "...", "email":
+>    "you@outlook.com" }`; the `@outlook.com`/M365 domain auto-routes to Graph.
+>    Restart; first sync pops the Microsoft consent at `http://localhost`; approve.
+>
+> ## 🔁 Renewal / expiry — what you have to do over time
+>
+> **Nothing on a schedule.** Because this is a public client with **no secret**:
+> - **Client secret** — none exists, so there is **no 2-year (or any) secret
+>   renewal**. (A confidential setup would force rotating the secret before its
+>   expiry; we deliberately avoid that.)
+> - **Client ID** — permanent; never expires.
+> - **Refresh token** — cached per account under `~/.rmfmail/tokens/<email>/`;
+>   rmfmail refreshes it automatically. If it ever goes stale (you revoke access,
+>   change the password, or Microsoft invalidates it), rmfmail just re-shows the
+>   consent once. Not a scheduled task.
+> - **API permissions** — only re-touched if you add a feature needing a new
+>   scope (e.g. Calendar). Existing mail scopes don't expire.
+>
+> If consent fails with `invalid_request` / "client secret required", the app
+> isn't set as a public client — re-check "Allow public client flows = Yes" and
+> that no leftover per-machine `~/.rmfmail/microsoft-credentials.json` is passing
+> a stale secret. Tokens that mint but sync-401 usually mean a scope/audience
+> mismatch (Graph vs IMAP) — we mint **Graph**.
+
+The rest of this doc is the implementation reference and the detailed Azure
+walkthrough.
 
 ---
 
-## What already exists
+## What already exists (now wired — 2026-06-20)
 
 | Piece | Where | State |
 |---|---|---|
-| Graph API provider | `@bobfrankston/mailx-sync/outlook.ts` (re-exported `packages/mailx-imap/providers/outlook-api.ts`) | **Read-only**: `listFolders`, `fetchSince/ByDate/ByUids/One`, `getUids`. No send, no write-back, no drafts/attachments. |
-| Host auto-config | `packages/mailx-settings/index.ts:503` (`outlook.com`, `hotmail.com` → `outlook.office365.com:993` / `smtp.office365.com:587`, `auth: "oauth2"`) | Done |
+| Graph API provider | `@bobfrankston/mailx-sync/outlook.ts` (re-exported `packages/mailx-imap/providers/outlook-api.ts`) | **Full**: read (`listFolders`, `fetchSince/ByDate/ByUids/One`, `getUids`) + write-back (`setFlags`, `trashMessage`, `moveMessage`), `sendRaw` (POST /sendMail), `fetchBodiesBatch`, provider_id-first identity, rate-limit + Retry-After backoff. Mirrors `gmail.ts`. |
+| Microsoft tokenProvider | `packages/mailx-imap/index.ts` `addAccount` | **Done**: `isOutlookCfg(account)` reads `~/.rmfmail/microsoft-credentials.json` if present, else the **bundled** `packages/mailx-imap/microsoft-credentials.json`; mints Graph scopes (`Mail.ReadWrite Mail.Send offline_access openid profile`). |
+| Bundled public creds | `packages/mailx-imap/microsoft-credentials.json` | **Done**: public client_id only (no secret), committed + shipped with the package — fresh installs need no creds placement. |
+| Provider routing | `packages/mailx-imap/index.ts` | **Done**: `isOutlookAccount`/`isApiAccount`/`getApiProvider`/`getOutlookProvider`; ~15 dispatch sites route Outlook through the REST path like Gmail. Send via `sendRawForAccount` → Graph `/sendMail`. |
+| Host auto-config | `packages/mailx-settings/index.ts:503` (`outlook.com`, `hotmail.com` → `outlook.office365.com:993` / `smtp.office365.com:587`, `auth: "oauth2"`) | Done (the `auth:"oauth2"` flag is what lands Outlook in the tokenProvider branch) |
 | MX-based detection | `bin/mailx.ts:1307` (`*.outlook.com` / `*.protection.outlook.com` MX → Microsoft 365) | Done |
-| Generic OAuth flow | `@bobfrankston/oauthsupport` `OAuthTokenManager.ts:369` — validates `client_id/client_secret/auth_uri/token_uri` from the creds file; localhost loopback auth-code flow | **Provider-agnostic** — not Google-specific |
-| OAuth SMTP send | `packages/mailx-imap/index.ts:1533` builds `{type:"OAuth2", user, accessToken}` from `config.tokenProvider()` | Works for any provider with a tokenProvider |
-
-The single thing that makes Gmail work and Outlook not: the **tokenProvider** at
-`packages/mailx-imap/index.ts:798-848` is built only for Google. It hardcodes the
-Google credentials file (`~/.mailx/google-credentials.json`) and the all-Google
-scope string. Nothing constructs a Microsoft tokenProvider, so
-`OutlookApiProvider` is never instantiated and the office365 IMAP host has no
-token to present.
+| OAuth flow (PKCE) | `@bobfrankston/oauthsupport` `OAuthTokenManager.ts` | **PKCE added 2026-06-21**: `client_secret` now optional; auth-code flow sends `code_challenge`/`code_verifier` (S256). Public clients (Microsoft, no secret) and confidential clients (Google, secret) both work through one path. |
+
+**The one remaining gate is the Azure app registration** (your part, top of this
+doc) — and it's a public client, so once the app is registered with "Allow
+public client flows" enabled, Outlook authenticates and syncs/sends entirely via
+Graph — no IMAP, no SMTP, no secret to manage. (Historical note: send does NOT
+use the old OAuth-SMTP path at `index.ts:1533`, because a Graph-scoped token has
+the wrong audience for SMTP; Outlook sends via Graph `/sendMail`.)
 
 ---