# CLAUDE.md

## Stack

Cloudflare Worker (TypeScript + Hono) + React 18 + Vite + Tailwind + shadcn/ui + Cloudflare D1 + remote MCP server (`@hono/mcp`) + OAuth for claude.ai connectors (`@cloudflare/workers-oauth-provider`, KV-backed).

Package manager: **pnpm**. Never use npm commands.

## Key Commands

```bash
pnpm run dev               # Worker backend :8787
pnpm run dev:web           # React frontend :5173 (proxy /api → :8787)
pnpm run db:migrate:local  # apply D1 migrations locally
pnpm run deploy            # build:web + db:migrate:remote + wrangler deploy
pnpm run test              # unit tests (workers pool)
pnpm run fixtures:pull     # pull real mails from remote D1 → test/fixtures/*.eml (gitignored)
pnpm run test:mail         # deterministic regression on real-mail fixtures (free, no LLM)
pnpm run test:eval         # live LLM classification eval on fixtures (costs API calls)
```

## Architecture Boundaries — Never Violate

1. `isPromotionalEmail()` must run **before** any LLM call in the email handler (`src/email/handler.ts`).
2. Every incoming email → `raw_mails`. Only AI-extracted results → `code_mails`. Never skip `raw_mails`.
3. `ASSETS` is required for the frontend. There is no legacy HTML fallback.
4. DOMPurify + sandboxed iframe on all email HTML rendering. Do not relax.
5. Auth boundaries: middleware in `src/app.ts` (`sessionAuth` on `/api/*`, `requireAdmin` on `/api/admin/*`, `apiKeyAuth` on `/mcp` for `aik_` keys) plus the `OAuthProvider` wrapper in `src/index.ts` (validates OAuth tokens on `/mcp`, then `oauthPropsAuth` re-fetches the user from D1 — never trust props beyond `userId`). Do not move or bypass either layer; the only allowed provider bypasses in `index.ts` are `Bearer aik_` pre-routing and the whole-provider skip when `OAUTH_KV` is unbound (OAuth is an optional feature).
6. `visibleMails()` (`src/services/mail.ts`) is the **only** mail permission layer — REST and MCP both query through it. Never add a parallel filter path.
7. Sensitive categories (`password_reset`, `account_security`) are default-deny for users; `legacy` and raw email bodies are admin-only on every interface.
8. All AI calls go through `callProvider()` (`src/services/classify.ts`). Do not add per-provider methods alongside it.
9. Schema changes = new numbered file in `migrations/`. Never edit applied migrations.

## Env Vars

Required: `AI_BASE_URL`, `AI_API_KEY`, `AI_API_FORMAT` (`openai`|`responses`|`anthropic`), `AI_MODEL`, `JWT_SECRET` (Cloudflare secret, signs session JWTs; local dev reads it from gitignored `.dev.vars`).
Optional binding: `OAUTH_KV` KV namespace (name mandated by `workers-oauth-provider`; stores OAuth tokens/grants/clients). Present → OAuth enabled on `/mcp`; absent → OAuth fully bypassed, `/mcp` accepts `aik_` keys only and `/oauth/*` returns 404.
Optional fallback: `AI_FALLBACK_BASE_URL`, `AI_FALLBACK_API_KEY`, `AI_FALLBACK_API_FORMAT`, `AI_FALLBACK_MODEL` (all four or none).
Optional Bark push: `UseBark`, `barkUrl`, `barkTokens`.

## Frontend Component Rules

- UI components: shadcn/ui only. No new UI libraries without discussion.
- Colors: CSS variables in `web/src/index.css`. No hardcoded hex except table hover states.
- Use `text-muted-foreground` for secondary text. `text-muted` is a background color — never use as text.
- All grid children need `min-w-0` to prevent overflow.

## Compact Instructions

When compressing, preserve in priority order:

1. Architecture decisions (NEVER summarize)
2. Modified files and their key changes
3. Current verification status (pass/fail)
4. Open TODOs and rollback notes
5. Tool outputs (can delete, keep pass/fail only)