@bobfrankston/rmfmail 1.2.143 → 1.2.145

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.143",
+  "version": "1.2.145",
   "description": "Local-first email client with IMAP sync and standalone native app",
   "type": "module",
   "main": "bin/mailx.js",
@@ -34,13 +34,13 @@
     "postinstall": "node bin/postinstall.js"
   },
   "dependencies": {
-    "@bobfrankston/iflow-direct": "^0.1.57",
+    "@bobfrankston/iflow-direct": "^0.1.58",
     "@bobfrankston/mailx-host": "^0.1.13",
     "@bobfrankston/mailx-imap": "^0.1.117",
     "@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.396",
     "@bobfrankston/node-tcp-transport": "^0.1.10",
     "@bobfrankston/oauthsupport": "^1.0.34",
     "@bobfrankston/rmf-tiny": "^0.1.38",
@@ -112,13 +112,13 @@
   },
   ".transformedSnapshot": {
     "dependencies": {
-      "@bobfrankston/iflow-direct": "^0.1.57",
+      "@bobfrankston/iflow-direct": "^0.1.58",
       "@bobfrankston/mailx-host": "^0.1.13",
       "@bobfrankston/mailx-imap": "^0.1.117",
       "@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.396",
       "@bobfrankston/node-tcp-transport": "^0.1.10",
       "@bobfrankston/oauthsupport": "^1.0.34",
       "@bobfrankston/rmf-tiny": "^0.1.38",