Inboxintel/docs/specs/README.md

InboxIntel — Feature Build-Out & UI Overhaul Specs

This folder is the design contract for the Clean.Email-parity feature build-out plus a full UI overhaul. Specs are written to be executable: each names real types, files, and the patterns already in the codebase.

Locked decisions (2026-06-30)

Area	Decision
Automation safety	Hybrid. Safe, reversible actions (label, archive/skip-inbox, mark-read, star, move-to-label) apply automatically. Destructive actions (trash, delete, keep-newest culling, trash-by-age) are proposed and require one-click user approval before touching Gmail.
Scope	Tier 1 + 2 only. Gmail-only. No sending (no Compose/Reply/Forward). No multi-provider.
Gmail vs in-app	Touch real Gmail. Screener/Block/Pause/Read-Later/Deliver-To use managed InboxIntel/… labels + skip-inbox so the inbox is clean everywhere (phone, web). All reversible.
Privacy Monitor	Use XposedOrNot (free, no API key for email endpoints) as the default provider, on by default. HIBP kept as a swappable key-based alternative. Only ever checks the signed-in user's own address.
UI aesthetic	Stripe / Notion — light, airy, generous whitespace, soft shadows.
Color modes	Light + dark toggle, light-first, driven by CSS-variable design tokens.
UI stack	Tailwind CSS + shadcn-style headless primitives (Radix + cva + tailwind-merge), hand-built component set.
UI rollout	Incremental — stand up the design system, then convert page-by-page. App stays working throughout.
Brand	Keep existing logo. Propose a new accent + neutral palette (see ui-overhaul.md) for approval.
Mobile	Desktop-first, responsive-ok — usable on phones, but desktop is the primary target.

The unifying idea

Clean.Email's whole "keeps your inbox clean automatically" story reduces to one engine plus a few specializations:

                    ┌─────────────────────────────┐
                    │   Automation Engine          │
                    │   (conditions → action)      │
                    └──────────────┬──────────────┘
        ┌──────────────────────────┼──────────────────────────┐
        ▼                          ▼                          ▼
  AutomationRule            SenderPolicy                 per-email / per-thread
  (custom rules,            (Block, Whitelist,           Pinned (Email.IsPinned)
   Trash-by-Age)             Screener, Pause,            Mute  (MailThread.IsMuted)
                             Read-Later, Keep-Newest,
                             Deliver-To)

Everything writes through the existing CleanupService / IGmailService, logs to a single AutomationAction table that doubles as the approval queue (Proposed) and the Activity Log (Applied / Rejected / Undone).

Spec index

File	Covers
feature-rules-engine.md	Auto Clean Rules, the execution engine, hybrid approval queue, Pinned, Mute, Trash-by-Age, Keep-Newest, the AutomationWorker
feature-sender-policy.md	Block, Whitelist, Screener, Pause, Read-Later, Deliver-To (per-sender)
feature-activity-log.md	Unified AutomationAction log, undo, Activity Summaries
feature-privacy-monitor.md	HIBP breach checking behind a flag
ui-overhaul.md	Design tokens, palette proposal, Tailwind+shadcn setup, page-by-page migration
build-plan.md	Increment sequencing, commit plan, what depends on what

Cross-cutting invariants (apply to every feature)

1. User-scoping. Every query, mutation, and background pass filters by UserId. No cross-user data path may exist. (Standing security instruction.)
2. AI never destroys. The existing AiService doc invariant holds: AI only reads and suggests. Automation destructive actions come from deterministic rules + user approval, never directly from an LLM.
3. Reversibility & managed labels. Anything that hides mail uses Gmail labels under the InboxIntel/ namespace and skip-inbox (remove INBOX), never hard-delete. Hard delete is never an automatic or proposed action — it stays manual-only.
4. Graceful degradation. A failing Gmail/AI/HIBP call logs and continues; it never crashes the worker or a sync.
5. Pinned & Whitelisted are sacrosanct. No rule, policy, or sweep may act on a pinned email or a whitelisted sender.