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	Spec around Have I Been Pwned; ship behind a config flag, off until a key is added. No cost now.
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.