# 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`](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`](feature-sender-policy.md) | Block, Whitelist, Screener, Pause, Read-Later, Deliver-To (per-sender) |
| [`feature-activity-log.md`](feature-activity-log.md) | Unified `AutomationAction` log, undo, Activity Summaries |
| [`feature-privacy-monitor.md`](feature-privacy-monitor.md) | HIBP breach checking behind a flag |
| [`ui-overhaul.md`](ui-overhaul.md) | Design tokens, palette proposal, Tailwind+shadcn setup, page-by-page migration |
| [`build-plan.md`](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.