@bobfrankston/rmfmail 1.2.142 → 1.2.144

package/TODO.md

@@ -99,13 +99,14 @@ Everything AI-shaped collected here so Bob can think about it on its own terms,
 |---|---|
 | **Q103-AI** ❓ | **Rules / extensions engine shape (C39).** Parked 2026-04-23 while Bob experiments with imail. Revisit once imail findings settle. Candidate shapes when it's time: declarative JSONC rules (`if from: foo then move to bar`), TypeScript plugins under `~/.mailx/extensions/`, AI-classified categories (newsletter / priority / action-required), or a hybrid. |
 | **Q111-AI** ❓ | **Writing assistance.** LanguageTool (API or self-hosted), custom AI via the existing ghost-text path (Ollama / Claude / OpenAI), in-WebView2 native spellcheck only (current), or something else? |
-| **Q113-AI** ❓ | **AI-flavored per-message metadata.** The schema shape in Q113 above directly affects where AI-assigned priority / categories / summaries live. If Q113 lands on a separate `message_meta` table the AI tags have a natural home; if it's a JSON column on `messages`, the AI writer mutates the same row. |
+| **Q113-AI** ❓ | **AI-flavored per-message metadata.** The schema shape in Q113 above directly affects where AI-assigned priority / categories / summaries live. If Q113 lands on a separate `message_meta` table the AI tags have a natural home; if it's a JSON column on `messages`, the AI writer mutates the same row. *Update 2026-07-16: C155 answers the cross-app half — categories/signals live ON the message as IMAP keywords with a shared registry; Q113's table-vs-column question now only covers rmfmail-internal rich residue.* |
 
 ### AI — Backlog
 
 | # | Status | Item |
 |---|---|---|
-| [**C39**](#ext39) ❓ | PARKED | Rules / extensions engine + AI classification. See Q103-AI. |
+| **C155** ❓ | DRAFT | **Annotation registry + imail companion annotator** [M]. Companion app annotates each letter *before* sorting. Two-layer design (2026-07-16 discussion): data plane = IMAP keywords on the message itself (core RFC 3501, portable — Gmail labels / Graph categories are the same concept per provider); vocabulary plane = one shared `annotations.jsonc` registry with MCP-tool-style entries (`description`/`whenToApply` prompt the AI annotator, `sortAction` drives the sorter, `label` feeds UIs). No shared DB needed — IMAP STORE is the concurrency layer; rich residue (dates, summaries) stays out or comes back later as a service-owned sidecar. Design note: `docs/annotation-registry.md`; starter vocabulary: `docs/annotations.jsonc`. Awaiting Bob's think-through — open questions at the end of the design note. Subsumes the cross-app half of Q113/Q113-AI; feeds Q103-AI/C39/P19 (rules engine shape). |
+| [**C39**](#ext39) ❓ | PARKED | Rules / extensions engine + AI classification. See Q103-AI, C155. |
 | [**P19**](#priority-daily) ❓ | OPEN | Screener — imail rules + AI classifier. Elevated under daily-driver; same classifier question as C39. |
 | **AI-writing** ❓ | OPEN | Proofread / rewrite / tone-adjust in compose. Currently a Settings toggle that's off; needs the shape from Q111-AI before wiring. |
 | **AI-extract-contact** | OPEN | Right-click an email → Add contact auto-fills Name / Organization / Phone from the letter body. "In the future" per user 2026-04-23. Depends on a working AI back-end choice from Q111-AI. |

package/client/compose/compose.html

@@ -588,12 +588,12 @@
         </div>
     </div>
     <div class="compose-toolbar">
-        <button class="tb-btn" id="btn-send">Send</button>
-        <button class="tb-btn" id="btn-attach">Attach</button>
+        <button class="tb-btn" id="btn-send" title="Send (Ctrl+Enter)">Send</button>
+        <button class="tb-btn" id="btn-attach" title="Attach files">Attach</button>
         <input type="file" id="compose-file" multiple hidden>
         <button class="tb-btn" id="btn-edit-in-word" title="Open the body in Microsoft Word — saves in Word reload back into the editor">Edit in Word</button>
         <button class="tb-btn" id="btn-compose-help" title="Editor shortcuts and formatting reference (Quill vs tiptap differences)">?</button>
-        <button class="tb-btn" id="btn-discard">Discard</button>
+        <button class="tb-btn" id="btn-discard" title="Discard this message without saving a draft">Discard</button>
         <span id="compose-editor-badge" class="compose-editor-badge" title="Active editor — change in Settings → Compose"></span>
         <span id="compose-status" class="compose-status"></span>
     </div>

package/client/index.html

@@ -714,7 +714,7 @@
         </div>
         <div class="toolbar-center">
             <div class="tb-menu" id="view-menu">
-                <button class="tb-btn" id="btn-view">View</button>
+                <button class="tb-btn" id="btn-view" title="View menu — sort order, date basis, thread grouping, layout">View</button>
                 <div class="tb-menu-dropdown" id="view-dropdown" hidden>
                     <button class="tb-menu-item" id="opt-new-window" title="Open another full mailx window (own OS window — e.g. Drafts here, Sent there, side by side). Secondary windows don't live-update on new mail; switch folders or sync to refresh.">🗗 New window</button>
                     <hr class="tb-menu-sep">
@@ -738,7 +738,7 @@
                 </div>
             </div>
             <div class="tb-menu" id="settings-menu">
-                <button class="tb-btn" id="btn-settings">Settings</button>
+                <button class="tb-btn" id="btn-settings" title="Settings menu — accounts, compose, AI, config files">Settings</button>
                 <div class="tb-menu-dropdown" id="settings-dropdown" hidden>
                     <div class="tb-menu-submenu" id="theme-submenu-wrap">
                         <button type="button" class="tb-menu-item tb-menu-item-submenu" id="theme-submenu-toggle" aria-haspopup="true" aria-expanded="false" title="Theme: System / Light / Dark">Theme <span class="tb-menu-submenu-current" id="theme-submenu-current">System</span> ▸</button>
@@ -883,7 +883,7 @@
                     <button class="tb-btn" id="btn-print" title="Print (Ctrl+P)">🖨</button>
                     <button class="tb-btn" id="mv-view-thread" title="View thread (conversation)" hidden>💬</button>
                     <span style="flex:1"></span>
-                    <button class="mv-action mv-action-primary" id="mv-edit-draft" hidden>Edit & Send</button>
+                    <button class="mv-action mv-action-primary" id="mv-edit-draft" title="Open this draft in the compose editor" hidden>Edit & Send</button>
                     <a class="mv-unsubscribe" id="mv-unsubscribe" hidden>Unsubscribe</a>
                     <button class="mv-action" id="mv-view-source" title="View source (.eml)" hidden>Source</button>
                     <button class="mv-action" id="mv-popout" title="Pop out (desktop) / Full-screen (mobile)">⤢</button>

package/docs/annotation-registry.md

@@ -0,0 +1,74 @@
+# Annotation registry — companion annotator for imail (design sketch)
+
+*Status: DRAFT 2026-07-16 — captured from discussion; Bob thinking it over. TODO item C155.*
+
+## Goal
+
+A companion app annotates each letter **before** sorting. imail's sorter (and any
+other consumer — rmfmail UI, agents, future tools) reads the annotations and acts.
+The mechanism should be general — not private to imail the way its `ai/` cache is.
+
+## Decision so far: keywords on the message + a shared JSON registry
+
+Two-layer design, no shared database required:
+
+1. **Data plane — tags on the message itself.** IMAP keywords (core RFC 3501,
+   not Dovecot-specific: any server advertising `\*` in PERMANENTFLAGS). The
+   message carries its own annotations; they survive folder moves; IMAP STORE is
+   atomic per message so concurrency is the server's problem, already solved.
+   Provider mapping for the same concept:
+   | Provider | Mechanism |
+   |---|---|
+   | Dovecot / Cyrus / Fastmail / iCloud / Yahoo IMAP | user keywords (atoms) |
+   | Gmail | API labels (Gmail IMAP ignores custom keywords) |
+   | Outlook / Graph | categories |
+   | JMAP | keywords (unified with IMAP's by design) |
+
+2. **Vocabulary plane — one shared JSON registry** (`annotations.jsonc`, draft
+   next to this doc) with MCP-tool-style entries per keyword: `label`,
+   `description`, `whenToApply`, `exclusiveGroup`, `setBy`, `sortAction`.
+   The registry does triple duty:
+   - the AI annotator's prompt is generated from `description` / `whenToApply`
+     (same way MCP tool descriptions steer an agent);
+   - the sorter maps keyword → action from `sortAction`;
+   - UIs (rmfmail chips, Thunderbird tags) get display names from `label`.
+   Adding a category = editing one file. No schema migration, no API change.
+
+## Constraints / cautions
+
+- **Keyword budget**: Dovecot on maildir caps keywords ~26/mailbox (filename
+  letters). Registry stays small and curated; `exclusiveGroup` keeps categories
+  mutually exclusive instead of accreting.
+- **Atoms only**: no spaces, ASCII, prefix everything `im_` so the vocabulary
+  can't collide with `$Junk`, `$Forwarded`, etc.
+- **Tags, not key-value**: scores get bucketed (`im_spam_high`); anything
+  non-enumerable (extracted dates, reasoning text, summaries) does NOT fit.
+  If rich values are needed later, a sidecar store comes back *only for that
+  residue* — the keyword layer stays as the interoperable spine. (imail's
+  `.ics` writer is precedent: rich results can also just be files.)
+- **Registry distribution**: share it the way accounts.jsonc is shared — GDrive
+  via API with a local cache, never a file on a network path. Slots into
+  rmfmail's existing config-editor/watch machinery; imail (self-contained by
+  policy) keeps its own cached copy.
+- **Shared SQLite over SMB is ruled out** (WAL needs shared memory; SMB locking
+  corrupts). If a shared rich store is ever needed: a small annotation service
+  owning WAL SQLite behind HTTP/MCP (the rmfmail-daemon pattern), or libSQL
+  embedded replicas for multi-machine.
+
+## Fit with existing TODO items
+
+- **Q113 / Q113-AI** (per-message metadata shape): this design answers the
+  cross-app half — message-attached keywords + registry. A local
+  `message_meta` table remains a possible rmfmail-internal cache/residue store.
+- **Q103-AI / C39 / P19** (rules engine + screener): `sortAction` in the
+  registry is a candidate rule shape; imail experiments feed this directly.
+
+## Open questions for Bob
+
+1. Starter vocabulary — which categories actually earn one of the ~26 slots?
+2. Does the annotator mirror keywords → Gmail labels / Graph categories from
+   day one, or Dovecot-only first (bobma is the hot path)?
+3. Where does the annotator run — IDLE-driven daemon on new mail (before
+   imail's scheduled pass), or a stage inside imail's own loop?
+4. Should rmfmail render `im_*` keywords as chips in the message list (it
+   already syncs them in `flags_json` — display-only change)?

package/docs/annotations.jsonc

@@ -0,0 +1,78 @@
+// Annotation registry — DRAFT starter vocabulary (see annotation-registry.md).
+// One entry per IMAP keyword the companion annotator may set. MCP-tool-style
+// descriptions: `description` + `whenToApply` are written for an AI annotator
+// the same way a tool description is written for an agent; `sortAction` is
+// read by the sorter; `label` by UIs. Keywords are IMAP atoms: ASCII, no
+// spaces, always prefixed `im_`. Budget: Dovecot/maildir allows ~26 keywords
+// per mailbox — keep this list SMALL and curated.
+{
+    "version": 1,
+    "keywords": {
+        // ── Categories (mutually exclusive — at most one per message) ──
+        "im_bills": {
+            "label": "Bills & orders",
+            "description": "Invoices, receipts, order/shipping confirmations from a vendor the user has transacted with.",
+            "whenToApply": "Sender is a merchant/utility/bank AND the body references a specific transaction, amount, order number, or account.",
+            "exclusiveGroup": "category",
+            "setBy": ["annotator"],
+            "sortAction": { "moveTo": "Added/bills and orders" }
+        },
+        "im_newsletter": {
+            "label": "Newsletter",
+            "description": "Bulk editorial content the user subscribed to — digests, columns, mailing-list posts that are broadcast rather than personal.",
+            "whenToApply": "List-Unsubscribe header present AND content is editorial/broadcast, not transactional and not addressed to the user personally.",
+            "exclusiveGroup": "category",
+            "setBy": ["annotator"],
+            "sortAction": { "moveTo": "Added/newsletters" }
+        },
+        "im_political": {
+            "label": "Political",
+            "description": "Campaign fundraising, advocacy, and political-action mail.",
+            "whenToApply": "Sender is a campaign/PAC/advocacy org, or body is dominated by donation asks or political calls to action.",
+            "exclusiveGroup": "category",
+            "setBy": ["annotator"],
+            "sortAction": { "moveTo": "Added/political" }
+        },
+        "im_event": {
+            "label": "Event / invite",
+            "description": "Invitations and event announcements with a concrete date/time the user could attend.",
+            "whenToApply": "Body or attachment carries a specific event with date/time/place (calendar invite, webinar, meetup, talk).",
+            "exclusiveGroup": "category",
+            "setBy": ["annotator"],
+            // Rich residue (the extracted datetime) doesn't fit a keyword —
+            // the annotator writes the .ics file, as imail already does.
+            "sortAction": { "keep": true }
+        },
+        "im_personal": {
+            "label": "Personal",
+            "description": "A human wrote this specifically to the user — correspondence, not broadcast.",
+            "whenToApply": "Individual sender, no unsubscribe machinery, content addresses the user or an ongoing thread.",
+            "exclusiveGroup": "category",
+            "setBy": ["annotator"],
+            "sortAction": { "keep": true }
+        },
+
+        // ── Independent signals (combinable) ──
+        "im_spam_high": {
+            "label": "Likely spam",
+            "description": "High-confidence spam beyond what SpamAssassin already headers — bucketed score, since keywords cannot carry values.",
+            "whenToApply": "Model confidence ≥ 0.9 that the message is unsolicited bulk/scam. Never apply on mere newsletter-ness.",
+            "setBy": ["annotator"],
+            "sortAction": { "moveTo": "Spam" }
+        },
+        "im_action": {
+            "label": "Action required",
+            "description": "The user is being asked to do something with a real deadline or dependency (reply, pay, RSVP, sign, review).",
+            "whenToApply": "Explicit request directed at the user with a deadline or a blocked party waiting.",
+            "setBy": ["annotator"],
+            "sortAction": { "keep": true }
+        },
+        "im_screened": {
+            "label": "Screened",
+            "description": "Bookkeeping: the annotator has processed this message. Lets the sorter and re-runs skip already-annotated mail cheaply.",
+            "whenToApply": "Set on every message the annotator completes, regardless of verdict.",
+            "setBy": ["annotator"],
+            "sortAction": { "keep": true }
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/rmfmail",
-  "version": "1.2.142",
+  "version": "1.2.144",
   "description": "Local-first email client with IMAP sync and standalone native app",
   "type": "module",
   "main": "bin/mailx.js",
@@ -40,7 +40,7 @@
     "@bobfrankston/mailx-store-web": "^0.1.38",
     "@bobfrankston/mailx-sync": "^0.1.27",
     "@bobfrankston/miscinfo": "^1.0.13",
-    "@bobfrankston/msger": "^0.1.394",
+    "@bobfrankston/msger": "^0.1.395",
     "@bobfrankston/node-tcp-transport": "^0.1.10",
     "@bobfrankston/oauthsupport": "^1.0.34",
     "@bobfrankston/rmf-tiny": "^0.1.38",
@@ -118,7 +118,7 @@
       "@bobfrankston/mailx-store-web": "^0.1.38",
       "@bobfrankston/mailx-sync": "^0.1.27",
       "@bobfrankston/miscinfo": "^1.0.13",
-      "@bobfrankston/msger": "^0.1.394",
+      "@bobfrankston/msger": "^0.1.395",
       "@bobfrankston/node-tcp-transport": "^0.1.10",
       "@bobfrankston/oauthsupport": "^1.0.34",
       "@bobfrankston/rmf-tiny": "^0.1.38",