docs: discovery blueprint + multi-provider design (#8)

docs/discovery/07-ai-feature-catalogue.md

@@ -0,0 +1,70 @@
+# 07 — AI Feature Catalogue (Phase 6)
+
+Every realistic AI feature, judged honestly against the guiding rule: **AI only where it
+clearly beats traditional approaches.** Each entry: *problem · AI role & why · could
+traditional solve it? · complexity · performance · privacy.* All AI is local (Ollama),
+optional, advisory, and explainable (see [06](06-ai-strategy.md)). Complexity = S/M/L/XL.
+
+Legend for the verdict column:
+🟢 **AI clearly wins** · 🟡 **traditional-first, AI for the hard tail** · ⚪ **not AI at all**
+
+---
+
+## Group 1 — 🟢 AI clearly wins
+LLM/embeddings are genuinely the right tool; traditional approaches are weak here.
+
+| Feature | Problem | Why AI (and why traditional falls short) | Cx | Perf | Privacy |
+|---------|---------|------------------------------------------|----|------|---------|
+| **Thread / conversation summary** | Long threads are walls of text | LLMs summarise free text; regex/extractive summaries miss nuance & context | L | Warm 7B; cache per-thread, invalidate on new msg | Body → local LLM only |
+| **Conversational "ask your inbox"** (RAG) | "What did Sarah say about the invoice?" | Retrieval + generation over many emails; impossible with filters alone | XL | Semantic retrieve → 7B answer w/ **citations**; ~1–3s | Retrieval + gen fully local |
+| **Reply suggestions / writing assistant** | Blank-page drafting, tone | LLM drafts context-aware replies; templates can't adapt to content | L | Warm 7B, streamed | Thread context → local |
+| **Task / meeting / calendar / reminder extraction** | Commitments hide in prose | LLM structured-JSON extraction of {task, date, attendee}; regex catches only rigid formats | L | 7B `format:json`, async on read/sync | Body → local |
+| **Entity extraction** (amounts, orgs, dates, order #s) | Can't search/facet by meaning | LLM/NER generalises across phrasings; regex is brittle per-vendor | L | 7B or small NER, batched at sync | Local |
+| **Document / attachment understanding** | Can't search *inside* files | OCR/vision + summarise; no traditional equivalent for images/PDF meaning | XL | Vision model **on-demand** (heavy); OCR async | File content → local |
+| **Cross-thread linking / related conversations** | Related context is scattered | Embedding nearest-neighbours find semantic links; keyword join misses paraphrase | M | pgvector HNSW; precomputed | Vectors local |
+| **Relationship mapping / knowledge graph** | No view of who/what connects | Extraction + embeddings build a people/topic graph; not expressible in SQL alone | XL | Batch build; incremental | Local graph store |
+| **Conversation insights** (decisions, sentiment shift) | "What was decided / how's this going?" | LLM reads intent/sentiment over a thread; rules can't | L | 7B; cache | Local |
+| **Sentiment analysis** | Gauge tone (angry client?) | Small model/LLM classifies tone; lexicon methods are crude/misleading | M | small model or embeddings | Local |
+| **Email comparison** ("what changed vs last quote?") | Manual diffing of prose | LLM semantic diff; text-diff shows characters, not meaning | M | 7B on two bodies | Local |
+| **Explain search results / decisions** | Trust & learnability | For semantic/NL, only the model can say *why*; lexical uses `ts_headline` (non-AI) | M | cheap (reuse retrieval) | Local |
+
+## Group 2 — 🟡 Traditional-first, AI for the hard tail
+Heuristics/rules do 70–90% cheaply and instantly; AI handles ambiguity and adds explanations.
+The existing `HeuristicClassifier` and unsubscribe signals are the traditional backbone.
+
+| Feature | Problem | Traditional core | Where AI adds value | Cx | Perf / Privacy |
+|---------|---------|------------------|---------------------|----|----------------|
+| **Automatic categorisation** | Sort inbox into buckets | Rules on sender/domain/headers (exists) | Embedding zero-shot / small-LLM for the ambiguous long tail + confidence | M | Rules instant; LLM only on "unknown"; local |
+| **Smart filing / smart labels** | Where should this go? | Rules + user's past filing patterns | LLM/embedding *suggestions* with confidence, user-correctable | M | Suggest async; local |
+| **Priority prediction** | What needs me now? | Behavioural signals: your reply-rate to sender, frequency, VIPs, keywords, direct-to-me | ML/LLM refines ranking for edge cases | M | Mostly SQL/heuristic; local |
+| **Follow-up / awaiting-reply detection** | Dropped balls | Heuristic: *you* sent, contains a question, no reply in N days | LLM confirms "expects a reply" & drafts nudge | M | Heuristic instant; LLM optional; local |
+| **Smart notifications** | Notification fatigue | Rules over priority + quiet hours | LLM tunes "is this actually urgent" for borderline | S | Rules-first; local |
+| **Spam detection** | Junk | Rules/Bayesian + provider signals | Small model for novel spam; LLM explains | M | Fast; local |
+| **Phishing detection** | Safety | URL/domain analysis, SPF/DKIM hints, lookalike detection (+ existing SSRF guard) | **LLM reasons about social-engineering cues**; runs async on flagged mail, explains risk | L | Rules sync; LLM async on suspicious; local |
+| **Duplicate email detection** | Clutter / repeats | **Exact hash** for identical | **Embedding cosine** for near-duplicates | M | hash instant; vector cheap; local |
+| **Inbox assistant** (daily brief) | "Catch me up" | Compose from priority/follow-up/counts (rules) | LLM writes the natural-language brief over that structured data | L | 7B once/session; local |
+
+## Group 3 — ⚪ Not AI (don't waste VRAM)
+| Feature | Do it with | Why not AI |
+|---------|-----------|------------|
+| **Language detection** | fastText-lid / CLD3 library | Instant, accurate, ~0 VRAM; an LLM is pure overhead |
+| **Exact duplicate detection** | content hash | Deterministic and free |
+| **Unsubscribe detection** | List-Unsubscribe header parsing (exists) | Structured signal already present |
+
+---
+
+## Selection guidance (feeds the roadmap)
+- **First AI wins (highest value / lowest risk):** thread summary · follow-up detection
+  (heuristic + AI confirm) · reply suggestions · NL search parse. All reuse the one warm 7B.
+- **Semantic tier (needs pgvector + embeddings):** related/find-similar · near-dup ·
+  conversation insights · categorisation long-tail.
+- **Ambitious tier:** ask-your-inbox (RAG) · knowledge graph · attachment/vision understanding.
+- **Never gate the core on any of these** — each has a non-AI fallback or simply hides when
+  AI is off.
+
+## Privacy posture (applies to all)
+Email bodies and attachments are processed **on-device via Ollama**; embeddings, summaries,
+extractions, and graphs are **stored locally in Postgres**. No content leaves the machine
+unless the user deliberately configures a cloud provider — and even then, per-feature
+consent should gate it. This is the product's defining trust advantage (see
+[02](02-competitor-analysis.md)).