diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..91eb2f7
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,592 @@
+# @rafters/mail Architecture
+
+Technical reference for the internal design of @rafters/mail, an edge-native email inbox framework.
+
+This document covers the type system, data model, adapter boundaries, data flows, and package structure. Read this before contributing or building adapters.
+
+---
+
+## The gap
+
+There is no open-source email inbox framework for edge/serverless runtimes. ActionMailbox (Rails) covers inbound ingestion only, roughly 15% of the surface needed for a production inbox. It does not handle outbound sending, threading, classification, folder/label management, team collaboration, or blob storage.
+
+Chatwoot has an open GitHub issue for Cloudflare Email Workers support. They cannot add it. Their architecture assumes a traditional server runtime with persistent processes, background jobs, and a PostgreSQL database.
+
+@rafters/mail fills this gap. Inbound, outbound, threading, classification, folders, labels, team collaboration, and blob storage. All designed for SQLite-based edge databases (D1, Turso, libSQL) with object storage (R2, S3).
+
+---
+
+## Architecture principles
+
+### 1. Zod is the source of truth for all types
+
+Every data structure starts as a Zod schema. TypeScript types are derived via `z.infer<>`. No handwritten interfaces for data shapes. This gives three things at once: static types, runtime validation at system boundaries, and mock generation with Zocker for tests.
+
+```typescript
+// This is how types are defined. Always.
+const threadStatusSchema = z.enum(['open', 'pending', 'resolved', 'closed']);
+type ThreadStatus = z.infer<typeof threadStatusSchema>;
+
+// Never this.
+interface ThreadStatus { ... }
+```
+
+### 2. Zero vendor lock-in in core
+
+`@rafters/mail` has zero dependencies on Resend, Cloudflare, React Email, or Workers AI. Every external concern is an adapter in a separate package. The core defines interfaces. Adapters implement them.
+
+### 3. Drizzle for schema, wrangler owns migrations
+
+The core exports Drizzle table definitions for type-safe queries and raw SQL for migration files. The package never runs `drizzle-kit push` or `drizzle-kit migrate`. Apps copy migration SQL into wrangler-managed migration files and apply them with `wrangler d1 migrations apply`.
+
+### 4. User references are plain text
+
+All user ID columns (`ownerId`, `assigneeId`, `assignedBy`, `authorId`, `appliedBy`) are plain `text` with no foreign key constraints. The `AuthAdapter` interface resolves user identity at runtime. This means the mail schema works with any auth system: better-auth, Lucia, Clerk, a custom JWT, anything.
+
+### 5. Ship what we use
+
+Initial adapters cover Cloudflare Workers + Resend + React Email + Workers AI because that stack runs in production. No speculative adapters. Community contributors can add Postmark, Mailgun, SES, Deno KV, S3, and whatever else they run.
+
+### 6. Platform vocabulary over vendor vocabulary
+
+Internal code uses platform terms. Vendor terms only appear inside adapter implementations.
+
+| Platform term | Vendor term (Resend) |
+| ------------- | -------------------- |
+| MailingList   | Audience             |
+| Subscriber    | Contact              |
+| Campaign      | Broadcast            |
+
+### 7. No barrel files
+
+Edge runtimes have bundle size constraints. Workers enforces a 1MB compressed limit. Barrel exports (`index.ts` re-exporting everything) pull the entire module graph into every consumer. All packages use subpath exports in `package.json` so consumers import exactly what they need.
+
+```typescript
+// Correct: subpath import
+import { createResendProvider } from "@rafters/mail-resend";
+import { createR2BlobStorage } from "@rafters/mail-cloudflare/storage";
+
+// Wrong: barrel import that pulls in everything
+import { createResendProvider, createR2BlobStorage } from "@rafters/mail";
+```
+
+---
+
+## Package structure
+
+Six packages. Core has zero vendor dependencies.
+
+```
+@rafters/mail                  Core: schema, types, interfaces, threading
+@rafters/mail-resend           Outbound adapter (Resend API via raw fetch)
+@rafters/mail-cloudflare       Inbound adapter (CF Email Routing) + R2 blob storage
+@rafters/mail-react-email      Template renderer (React Email)
+@rafters/mail-workers-ai       Classifier (Workers AI, DeBERTa-v3)
+@rafters/better-auth-resend    Glue: wires Resend + React Email into better-auth OTP
+```
+
+Dependency graph:
+
+```
+@rafters/mail  <--  @rafters/mail-resend
+               <--  @rafters/mail-cloudflare
+               <--  @rafters/mail-react-email
+               <--  @rafters/mail-workers-ai
+
+@rafters/mail-resend + @rafters/mail-react-email  <--  @rafters/better-auth-resend
+```
+
+Every adapter depends only on `@rafters/mail`. The `better-auth-resend` glue is the only package with two adapter dependencies.
+
+---
+
+## Data model
+
+### Schema: 10 inbox tables + 3 newsletter tables
+
+All IDs are UUIDv7 via `$defaultFn`. All timestamps use `integer` with `mode: 'timestamp_ms'` and `unixepoch('subsecond') * 1000` defaults (the D1/SQLite pattern). All tables have soft delete via `deletedAt`. JSON columns use SQLite text with `mode: 'json'`.
+
+#### Inbox tables
+
+| Table                 | Purpose                                                                                    |
+| --------------------- | ------------------------------------------------------------------------------------------ |
+| `mailbox`             | Email addresses that send/receive. Personal (one owner) or shared (team).                  |
+| `inbox_folder`        | System folders + custom folders. Per-mailbox.                                              |
+| `inbox_label`         | System, AI-generated, and user-created labels. Per-mailbox.                                |
+| `inbox_thread`        | Conversation grouping. Subject, snippet, participants, folder, status, priority.           |
+| `inbox_message`       | Individual messages. RFC 5322 headers, envelope data, AI classification fields, blob keys. |
+| `inbox_message_label` | Many-to-many: message to label. Tracks who/what applied the label.                         |
+| `inbox_thread_label`  | Many-to-many: thread to label. Thread-level filtering.                                     |
+| `inbox_attachment`    | Attachment metadata. Content in blob storage. Supports inline (Content-ID) and regular.    |
+| `thread_assignment`   | Thread assignment for shared mailbox collaboration. Status: active/completed/reassigned.   |
+| `thread_note`         | Internal notes on threads. Markdown. Not visible to external parties.                      |
+
+#### Newsletter tables
+
+| Table                 | Purpose                                                                    |
+| --------------------- | -------------------------------------------------------------------------- |
+| `platform_audience`   | Platform-wide mailing lists.                                               |
+| `platform_subscriber` | User subscriptions to audiences.                                           |
+| `broadcast_audit`     | Compliance trail: who sent what, when, to which audience, recipient count. |
+
+The email provider (Resend) is the source of truth for subscriber data. The local tables store the registry, mappings, and provider sync identifiers. Subscriber email addresses, unsubscribe status, and campaign content live in the provider.
+
+### System folders
+
+Every mailbox gets six immutable system folders on creation:
+
+| Slug      | Purpose                                  |
+| --------- | ---------------------------------------- |
+| `inbox`   | Default landing folder for inbound email |
+| `sent`    | Outbound emails                          |
+| `drafts`  | Unsent drafts                            |
+| `spam`    | AI-classified or manually flagged spam   |
+| `trash`   | Soft-deleted, auto-purge after 30 days   |
+| `archive` | Archived conversations                   |
+
+Custom folders can be created per-mailbox.
+
+### Label types
+
+Three kinds:
+
+- **System labels**: `important`, `starred`, `unread`. Immutable.
+- **AI-generated labels**: created by the classifier. `isAiGenerated = true`. Based on regex patterns (e.g., `bug-report`, `feature-request`).
+- **User-created labels**: custom tags created by staff.
+
+Labels are many-to-many on both messages and threads. Junction tables track who applied the label and when. Null `appliedBy` means system or AI.
+
+### Zod schema layer
+
+Every table has corresponding Zod schemas:
+
+- **Insert schemas** for creating records
+- **Select schemas** for reading records
+- **Update schemas** for partial updates
+- **Enum schemas**: `mailboxTypeSchema`, `threadStatusSchema`, `threadPrioritySchema`, `aiCategorySchema`, `systemFolderSchema`
+
+Types are always inferred:
+
+```typescript
+type ThreadStatus = z.infer<typeof threadStatusSchema>;
+type InboxMessage = z.infer<typeof inboxMessageSelectSchema>;
+```
+
+---
+
+## Adapter interfaces
+
+All adapter interfaces are defined as Zod schemas in `@rafters/mail`. Types are inferred. Adapter packages implement the interfaces.
+
+### EmailProvider (outbound)
+
+Sends email. Manages mailing lists, subscribers, and campaigns.
+
+```typescript
+interface EmailProvider {
+  sendEmail(params: EmailParams): Promise<{ id: string }>;
+  createMailingList(name: string): Promise<MailingList>;
+  addSubscriber(listId: string, email: string, data?: SubscriberData): Promise<Subscriber>;
+  sendCampaign(params: CampaignParams): Promise<{ id: string }>;
+  // + getMailingList, removeSubscriber, listSubscribers, campaign draft flow, etc.
+}
+```
+
+Implementation: `@rafters/mail-resend` (Resend API via raw `fetch`, no SDK dependency).
+
+### InboundAdapter
+
+Receives email from an external source, stores it.
+
+```typescript
+interface InboundAdapter {
+  handleIncoming(email: InboundEmail): Promise<{ messageId: string; threadId: string }>;
+}
+```
+
+Implementation: `@rafters/mail-cloudflare` (Cloudflare Email Routing).
+
+### BlobStorage
+
+Stores and retrieves raw email content and parsed bodies.
+
+```typescript
+interface BlobStorage {
+  put(key: string, content: string | ArrayBuffer, options?: BlobPutOptions): Promise<void>;
+  get(key: string, options?: BlobGetOptions): Promise<BlobObject | null>;
+  delete(key: string): Promise<void>;
+  generateKey(contentHash: string, extension: string): string;
+}
+```
+
+Key format: `emails/{year}/{month}/{sha256-first-16-chars}.{eml|html|txt}` (month is zero-padded)
+
+Implementation: `@rafters/mail-cloudflare` (R2).
+
+### TemplateRenderer
+
+Renders email templates to HTML and plain text.
+
+```typescript
+interface TemplateRenderer {
+  render(
+    template: string,
+    props: Record<string, unknown>,
+  ): Promise<{ html: string; text?: string }>;
+}
+```
+
+Implementation: `@rafters/mail-react-email`.
+
+### EmailClassifier
+
+Classifies email content into categories with confidence scores.
+
+```typescript
+interface EmailClassifier {
+  classify(from: string, subject: string, body: string): Promise<EmailClassification>;
+}
+```
+
+Where `EmailClassification` is:
+
+```typescript
+const emailClassificationSchema = z.object({
+  category: z.enum([
+    "support",
+    "feedback",
+    "abuse",
+    "partnership",
+    "spam",
+    "billing",
+    "legal",
+    "other",
+  ]),
+  confidence: z.number().min(0).max(100),
+  tags: z.array(z.string()),
+  priority: z.enum(["low", "normal", "high", "urgent"]),
+});
+```
+
+Implementation: `@rafters/mail-workers-ai` (DeBERTa-v3 zero-shot on Workers AI).
+
+### AuthAdapter
+
+Resolves user identity and mailbox access. App-provided, no default implementation.
+
+```typescript
+interface AuthAdapter {
+  getCurrentUser(): Promise<InboxUser>;
+  getUserById(id: string): Promise<InboxUser | null>;
+  hasMailboxAccess(userId: string, mailboxId: string): Promise<boolean>;
+  getUserRole(userId: string, mailboxId: string): Promise<InboxRole | null>;
+}
+```
+
+Roles: `owner`, `admin`, `agent`, `viewer`.
+
+---
+
+## Data flows
+
+### Inbound flow
+
+An email arrives from the outside world and lands in the inbox.
+
+```
+External sender
+  |
+  v
+Cloudflare Email Routing
+  |
+  v
+CF Email Worker (InboundAdapter)
+  |
+  +---> [1] Parse RFC 5322 headers
+  |         From, To, CC, Subject, Message-ID, In-Reply-To, References, Date
+  |
+  +---> [2] Store raw .eml in blob storage (R2)
+  |         Key: emails/{year}/{month-zero-padded}/{sha256-16}.eml
+  |
+  +---> [3] Store parsed HTML and plain text as separate blobs
+  |         Keys: .../{sha256-16}.html, .../{sha256-16}.txt
+  |
+  +---> [4] Insert metadata row into D1 (inbox_message)
+  |         Columns: message ID, subject, from/to/cc, blob keys,
+  |         isRead=false, isOutbound=false
+  |
+  +---> [5] Thread matching
+  |         Look up In-Reply-To against existing inbox_message.messageId
+  |         If no match, check References header entries
+  |         If no match, create new thread
+  |         Update thread snippet and participant list
+  |
+  +---> [6] Dispatch to classification queue/workflow
+```
+
+The raw `.eml` is the source of truth. D1 stores parsed metadata for fast queries. If metadata is ever wrong, it can be re-derived from the raw email in blob storage.
+
+### Outbound flow
+
+A user replies to a thread or composes a new email.
+
+```
+App calls InboxEmailService.replyToThread() or composeEmail()
+  |
+  +---> [1] Look up thread and latest message
+  |
+  +---> [2] Generate Message-ID: <uuidv7@domain>
+  |
+  +---> [3] Set In-Reply-To to latest message's Message-ID
+  |         Append to References chain (RFC 5322)
+  |
+  +---> [4] Render template via TemplateRenderer
+  |         Pass props (brandName, logoUrl, content, etc.)
+  |         Returns { html, text }
+  |
+  +---> [5] Send via EmailProvider (Resend adapter)
+  |         Provider returns { id }
+  |
+  +---> [6] Store outbound message in D1
+  |         isOutbound=true, blob keys for raw RFC 822 content
+  |         Store rendered content in blob storage
+  |
+  +---> [7] Update thread
+            Set snippet to first 200 chars of plain text
+            Update participant list with any new addresses
+            Move to sent folder if new compose, keep in current folder if reply
+```
+
+### Classification flow
+
+Runs asynchronously after inbound storage. Triggered by a Cloudflare Queue message or Workflow step.
+
+```
+Queue/Workflow picks up message
+  |
+  +---> [1] Fetch first 4KB of message body from blob storage
+  |         Truncation is intentional. Classification does not need
+  |         the full body. 4KB covers subject + opening content.
+  |
+  +---> [2] Zero-shot classify with Workers AI
+  |         Model: @cf/microsoft/deberta-v3-base-zeroshot-v1.1-all-33
+  |         Labels: support, feedback, abuse, partnership, spam, billing, legal, other
+  |         Returns: category + confidence score (0-100)
+  |
+  +---> [3] Determine priority
+  |         abuse, legal -> always high
+  |         Urgent keywords (urgent, emergency, asap, immediately,
+  |           critical, broken, down, outage) -> urgent
+  |         High keywords (important, priority, help, issue,
+  |           problem, error, bug, crash) -> high
+  |         support, billing -> normal
+  |         feedback, partnership -> normal
+  |         Everything else -> low
+  |
+  +---> [4] Auto-tag via regex patterns
+  |         install|setup|download       -> installation
+  |         crash|error|bug|broken       -> bug-report
+  |         feature|request|suggest      -> feature-request
+  |         account|login|password|auth  -> account
+  |         payment|billing|subscribe|refund -> billing
+  |         (Apps add domain-specific patterns via config)
+  |
+  +---> [5] Update D1 record
+  |         Set aiCategory, aiConfidence, aiPriority on inbox_message
+  |
+  +---> [6] Update R2 metadata
+  |         Attach classification data to the blob object
+  |
+  +---> [7] Spam handling
+  |         If category=spam, move thread to spam folder
+  |
+  +---> [8] Apply AI-generated labels
+            Find-or-create labels from tags
+            Insert into inbox_message_label with appliedBy=null (AI)
+```
+
+The classifier ships a default set of tag patterns. Apps extend or override via `ClassifierConfig`:
+
+```typescript
+interface ClassifierConfig {
+  tagPatterns?: Array<{ pattern: RegExp; tag: string }>;
+  urgentKeywords?: string[];
+  highPriorityKeywords?: string[];
+  classificationLabels?: string[];
+  maxInputLength?: number; // default: 4000
+}
+```
+
+### Threading logic
+
+RFC 5322 References/In-Reply-To, Gmail-style:
+
+- **Inbound**: match `In-Reply-To` against existing `inbox_message.messageId`. If no match, walk the `References` header. If still no match, create a new thread.
+- **Outbound**: generate `<uuidv7@domain>` as Message-ID. Set `In-Reply-To` to the latest message in the thread. Append all prior Message-IDs to the References chain.
+- **Thread subject**: from the first message.
+- **Thread snippet**: first 200 characters of the latest message's plain text body.
+- **Thread participants**: JSON array of all email addresses that have appeared in From, To, or CC across all messages in the thread.
+
+---
+
+## Service interfaces
+
+Core exports six service interfaces. Apps compose them from adapters.
+
+```typescript
+interface InboxEmailService {
+  replyToThread(params: ReplyToThreadParams): Promise<{ messageId: string }>;
+  composeEmail(params: ComposeEmailParams): Promise<{ threadId: string; messageId: string }>;
+}
+
+interface ThreadService {
+  getThread(threadId: string): Promise<Thread | undefined>;
+  listThreads(mailboxId: string, folderId?: string): Promise<Thread[]>;
+  moveToFolder(threadId: string, folderId: string): Promise<void>;
+  updateStatus(threadId: string, status: ThreadStatus): Promise<void>;
+  updatePriority(threadId: string, priority: ThreadPriority): Promise<void>;
+  archive(threadId: string): Promise<void>;
+  trash(threadId: string): Promise<void>;
+}
+
+interface FolderService {
+  createFolder(mailboxId: string, name: string): Promise<Folder>;
+  listFolders(mailboxId: string): Promise<Folder[]>;
+  deleteFolder(folderId: string): Promise<void>;
+  initSystemFolders(mailboxId: string): Promise<void>;
+}
+
+interface LabelService {
+  createLabel(mailboxId: string, name: string): Promise<Label>;
+  listLabels(mailboxId: string): Promise<Label[]>;
+  applyToMessage(messageId: string, labelId: string, appliedBy?: string): Promise<void>;
+  applyToThread(threadId: string, labelId: string, appliedBy?: string): Promise<void>;
+  removeFromMessage(messageId: string, labelId: string): Promise<void>;
+  removeFromThread(threadId: string, labelId: string): Promise<void>;
+}
+
+interface AssignmentService {
+  assign(threadId: string, assigneeId: string, assignedBy?: string): Promise<void>;
+  reassign(threadId: string, newAssigneeId: string, assignedBy?: string): Promise<void>;
+  complete(threadId: string): Promise<void>;
+  getActiveAssignment(threadId: string): Promise<Assignment | null>;
+}
+
+interface NoteService {
+  addNote(threadId: string, authorId: string, content: string): Promise<Note>;
+  listNotes(threadId: string): Promise<Note[]>;
+  deleteNote(noteId: string): Promise<void>;
+}
+```
+
+---
+
+## Extraction boundary
+
+What ships in `@rafters/mail` packages vs. what stays app-specific.
+
+### Extracted
+
+- All 10 inbox tables and 3 newsletter tables (Drizzle definitions + raw SQL)
+- All Zod schemas and inferred types
+- `EmailProvider` interface and `ResendProvider` implementation
+- `ResendService` (fetch-based API wrapper, no SDK)
+- `MockEmailProvider` (in-memory mock for testing)
+- All Resend API type schemas
+- `InboxEmailService` (reply-to-thread, compose-email)
+- Threading logic (Message-ID generation, References chain building)
+- Email classifier (classify function, priority rules, tag extraction)
+- `ClassifyEmailWorkflow` (Cloudflare Workflow, step-based)
+- Queue consumer (`handleEmailClassifyQueue`)
+- `BaseEmail` template (configurable branding via props)
+- OTP template
+- R2 storage key generation
+- Raw email RFC 822 generation for outbound storage
+
+### Not extracted (app-specific)
+
+- Domain-specific tag patterns (apps add their own regex patterns via `ClassifierConfig`)
+- App-specific environment bindings (bucket names, domain constants)
+- App-specific templates beyond base/OTP
+- Hardcoded branding (logos, URLs, copyright text)
+- Domain-specific database tables that reference app models
+
+---
+
+## IMAP on the edge (planned)
+
+Status: designed, not built. Planned for post-0.1.0. A full design document exists.
+
+### Concept
+
+An IMAP server running on Cloudflare Durable Objects. Every standard email client (Thunderbird, Apple Mail, Outlook) becomes a frontend for an @rafters/mail inbox. No one is running IMAP servers on edge runtimes today.
+
+### Why Durable Objects
+
+IMAP is a stateful, long-lived protocol. Each client session maintains state: selected mailbox, message flags, sequence numbers.
+
+- **Per-mailbox DO isolation.** Each mailbox is a Durable Object. Connection state is colocated with the mailbox data.
+- **WebSocket hibernation for IDLE.** IMAP IDLE ("notify me when new mail arrives") maps directly to DO hibernation. The DO sleeps at near-zero cost and wakes only when new mail arrives or the client sends a command.
+- **Alarms for session timeouts.** RFC 2177 recommends 29-minute IDLE refresh. DO alarms handle this natively.
+- **Cost model.** Hibernated DOs are essentially free. You pay for command processing and new mail delivery.
+
+### Command set (MVP)
+
+CAPABILITY, LOGIN, LOGOUT, SELECT, EXAMINE, LIST, LSUB, STATUS, FETCH, SEARCH, STORE, EXPUNGE, CLOSE, NOOP, IDLE.
+
+### Flag mapping
+
+| IMAP flag   | @rafters/mail field       |
+| ----------- | ------------------------- |
+| `\Seen`     | `inboxMessage.isRead`     |
+| `\Flagged`  | `inboxMessage.isStarred`  |
+| `\Deleted`  | soft delete (`deletedAt`) |
+| `\Draft`    | folder slug = `drafts`    |
+| `\Answered` | thread has outbound reply |
+
+Custom IMAP flags (keywords) map to labels via `inbox_message_label`.
+
+### UID mapping
+
+IMAP UIDs are derived from UUIDv7 natural ordering. The DO maintains a UID-to-UUIDv7 mapping and a session-scoped sequence number index. UIDVALIDITY is incremented if the mapping is rebuilt.
+
+### Transport
+
+Two options, both using the same protocol handler:
+
+- **IMAP-over-WebSocket**: works on any Cloudflare plan. Requires a thin local proxy for standard clients.
+- **Cloudflare Spectrum**: native TCP on port 993. Standard clients connect directly. Requires Enterprise or paid add-on.
+
+Recommendation: ship WebSocket first, add Spectrum when demand justifies it.
+
+---
+
+## Future: multi-channel messaging
+
+The adapter pattern is designed to support channels beyond email. Social posting, push notifications, and in-app messages could become adapter packages sharing the same core thread/message/label model.
+
+The data model already supports this. Threads group messages. Messages have a direction flag (`isOutbound`) and metadata fields. Labels and folders organize them. The `EmailProvider` interface is channel-specific, but `ThreadService`, `LabelService`, `FolderService`, `AssignmentService`, and `NoteService` are channel-agnostic.
+
+This expansion is roadmapped but not in current scope. Ship email complete first.
+
+---
+
+## Design decisions log
+
+**Why raw fetch instead of the Resend SDK?**
+The Resend SDK pulls in dependencies and assumes Node.js APIs. Edge runtimes provide `fetch` natively. A raw fetch wrapper with Zod validation on both request and response is smaller, has zero transitive dependencies, and runs on any runtime.
+
+**Why SQLite (D1) instead of Postgres?**
+Edge runtimes colocate compute and data. D1 is Cloudflare's edge SQLite. Turso and libSQL provide the same model on other platforms. Postgres requires a connection to a centralized database, which adds latency and defeats the purpose of edge compute.
+
+**Why R2 for blob storage instead of D1 BLOBs?**
+Emails with attachments can be large. D1 rows have size limits. R2 stores arbitrarily large objects, supports range reads (for fetching the first 4KB during classification), and costs less per GB than database storage. D1 holds the metadata, R2 holds the content.
+
+**Why UUIDv7?**
+Sortable by creation time. No coordination required. Works as both a database primary key and an IMAP UID source (natural ordering).
+
+**Why 4KB truncation for classification?**
+DeBERTa-v3 has a 512-token context window. 4KB of text comfortably fits within that after tokenization. Fetching the full email body for classification wastes bandwidth and R2 read operations. The subject line and opening paragraph contain the signal needed for categorization.
+
+**Why no barrel files?**
+Measured impact: a barrel export that re-exports all of `@rafters/mail` pulls ~45KB into any consumer that imports a single type. With subpath exports, consumers import only what they reference. On Workers with a 1MB compressed limit, this matters.
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000..e5d8da8
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,395 @@
+# Getting Started with @rafters/mail
+
+An edge-native email inbox framework. Inbound, outbound, threading, classification, folders, labels, team collaboration. Runs on Cloudflare Workers, D1, and R2.
+
+---
+
+## Prerequisites
+
+You need:
+
+- A Cloudflare account with Workers, D1, and R2 enabled
+- A Resend account with an API key and a verified sending domain
+- Node.js 20+ and pnpm
+- Wrangler CLI (`pnpm add -g wrangler`)
+
+Your domain's MX records must point to Cloudflare Email Routing for inbound email. Outbound goes through Resend.
+
+---
+
+## 1. Install packages
+
+```bash
+pnpm add @rafters/mail @rafters/mail-resend @rafters/mail-cloudflare
+```
+
+`@rafters/mail` is the core: schema, types, service interfaces, threading logic. Zero vendor dependencies. The other two are adapters for Resend (outbound) and Cloudflare (inbound + blob storage).
+
+---
+
+## 2. Create your D1 database and R2 bucket
+
+```bash
+wrangler d1 create mail-db
+wrangler r2 bucket create mail-blobs
+```
+
+Add them to your `wrangler.jsonc`:
+
+```jsonc
+{
+  "name": "mail-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-04-01",
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "mail-db",
+      "database_id": "<your-database-id>",
+    },
+  ],
+  "r2_buckets": [
+    {
+      "binding": "EMAIL_STORAGE",
+      "bucket_name": "mail-blobs",
+    },
+  ],
+  "vars": {
+    "RESEND_FROM_EMAIL": "support@yourdomain.com",
+    "EMAIL_DOMAIN": "yourdomain.com",
+  },
+  // Secrets set via `wrangler secret put`:
+  // RESEND_API_KEY
+}
+```
+
+---
+
+## 3. Run the schema migration
+
+Generate a migration file and copy the SQL from `@rafters/mail`:
+
+```bash
+wrangler d1 migrations create mail-db init-mail-tables
+```
+
+This creates a file at `migrations/0001_init-mail-tables.sql`. Populate it:
+
+```typescript
+// scripts/print-migration.ts
+import { migrationSQL } from "@rafters/mail/migrations";
+console.log(migrationSQL);
+```
+
+```bash
+pnpm tsx scripts/print-migration.ts > migrations/0001_init-mail-tables.sql
+```
+
+Apply the migration:
+
+```bash
+wrangler d1 migrations apply mail-db --local   # local dev
+wrangler d1 migrations apply mail-db --remote  # production
+```
+
+This creates all 10 inbox tables (mailbox, inbox_folder, inbox_label, inbox_thread, inbox_message, inbox_message_label, inbox_thread_label, inbox_attachment, thread_assignment, thread_note) plus the 3 newsletter tables.
+
+---
+
+## 4. Implement the auth adapter
+
+`@rafters/mail` does not ship an auth implementation. You provide one. The adapter resolves user identity and mailbox access at runtime.
+
+```typescript
+// src/auth-adapter.ts
+import type { AuthAdapter, InboxUser, InboxRole } from "@rafters/mail";
+
+export function createAuthAdapter(db: D1Database): AuthAdapter {
+  return {
+    async getCurrentUser(): Promise<InboxUser> {
+      // Replace with your auth system.
+      // Pull from session, JWT, better-auth, whatever you use.
+      throw new Error("Implement getCurrentUser from your auth system");
+    },
+
+    async getUserById(id: string): Promise<InboxUser | null> {
+      const row = await db
+        .prepare("SELECT id, email, name FROM user WHERE id = ?")
+        .bind(id)
+        .first();
+      if (!row) return null;
+      return { id: row.id as string, email: row.email as string, name: row.name as string };
+    },
+
+    async hasMailboxAccess(userId: string, mailboxId: string): Promise<boolean> {
+      const row = await db
+        .prepare("SELECT 1 FROM mailbox WHERE id = ? AND (owner_id = ? OR type = ?)")
+        .bind(mailboxId, userId, "shared")
+        .first();
+      return row !== null;
+    },
+
+    async getUserRole(userId: string, mailboxId: string): Promise<InboxRole | null> {
+      // Return 'owner', 'admin', 'agent', or 'viewer'
+      // based on your permission model.
+      const row = await db
+        .prepare("SELECT 1 FROM mailbox WHERE id = ? AND owner_id = ?")
+        .bind(mailboxId, userId)
+        .first();
+      return row ? "owner" : null;
+    },
+  };
+}
+```
+
+All user ID columns in the mail schema (`ownerId`, `assigneeId`, `assignedBy`, `authorId`, `appliedBy`) are plain text. No foreign keys to your auth tables. Wire them up however you want.
+
+---
+
+## 5. Receive your first email
+
+### Set up the inbound handler
+
+```typescript
+// src/index.ts
+import { createInboundHandler } from "@rafters/mail-cloudflare";
+import { createR2BlobStorage } from "@rafters/mail-cloudflare/storage";
+import { drizzle } from "drizzle-orm/d1";
+import * as schema from "@rafters/mail/schema";
+
+interface Env {
+  DB: D1Database;
+  EMAIL_STORAGE: R2Bucket;
+  RESEND_API_KEY: string;
+  RESEND_FROM_EMAIL: string;
+  EMAIL_DOMAIN: string;
+}
+
+export default {
+  async email(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext) {
+    const db = drizzle(env.DB, { schema });
+    const blobStorage = createR2BlobStorage(env.EMAIL_STORAGE);
+
+    const handler = createInboundHandler({ db, blobStorage });
+    await handler.handleIncoming({
+      raw: await new Response(message.raw).arrayBuffer(),
+      from: message.from,
+      to: message.to,
+      headers: Object.fromEntries(message.headers.entries()),
+    });
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+The inbound handler:
+
+1. Parses RFC 5322 headers (From, To, CC, Subject, Message-ID, In-Reply-To, References)
+2. Stores the raw `.eml` in R2 at `emails/{year}/{month-zero-padded}/{hash}.eml`
+3. Stores parsed HTML and plain text as separate blobs
+4. Inserts a row into `inbox_message` with blob storage keys
+5. Matches or creates a thread using In-Reply-To and References headers
+6. Creates system folders on the mailbox if they do not exist
+
+### Configure Cloudflare Email Routing
+
+In the Cloudflare dashboard:
+
+1. Go to your domain > Email > Email Routing
+2. Under Routing rules, add a catch-all or specific address rule
+3. Set the destination to your Worker
+
+Or via `wrangler.jsonc`:
+
+```jsonc
+{
+  "email_routing": {
+    "enabled": true,
+  },
+}
+```
+
+Deploy:
+
+```bash
+wrangler deploy
+```
+
+Send a test email to your domain. Check D1:
+
+```bash
+wrangler d1 execute mail-db --command "SELECT id, subject, from_email FROM inbox_message LIMIT 5"
+```
+
+---
+
+## 6. Send your first reply
+
+Wire up Resend for outbound email, then use `InboxEmailService` to reply to a thread.
+
+### Create the email service
+
+```typescript
+// src/mail-service.ts
+import { createInboxEmailService } from "@rafters/mail";
+import { createResendProvider } from "@rafters/mail-resend";
+import { createR2BlobStorage } from "@rafters/mail-cloudflare/storage";
+import { drizzle } from "drizzle-orm/d1";
+import * as schema from "@rafters/mail/schema";
+
+export function createMailService(env: {
+  DB: D1Database;
+  EMAIL_STORAGE: R2Bucket;
+  RESEND_API_KEY: string;
+  RESEND_FROM_EMAIL: string;
+  EMAIL_DOMAIN: string;
+}) {
+  const db = drizzle(env.DB, { schema });
+  const blobStorage = createR2BlobStorage(env.EMAIL_STORAGE);
+
+  const emailProvider = createResendProvider({
+    apiKey: env.RESEND_API_KEY,
+    fromEmail: env.RESEND_FROM_EMAIL,
+  });
+
+  return createInboxEmailService({ db, blobStorage, emailProvider });
+}
+```
+
+### Add a reply endpoint
+
+```typescript
+// src/index.ts (add to the existing worker)
+import { createMailService } from "./mail-service";
+import { createAuthAdapter } from "./auth-adapter";
+
+export default {
+  async email(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext) {
+    // ... inbound handler from step 5
+  },
+
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const url = new URL(request.url);
+
+    if (url.pathname === "/api/threads/reply" && request.method === "POST") {
+      const body = (await request.json()) as {
+        threadId: string;
+        mailboxId: string;
+        senderId: string;
+        bodyHtml: string;
+        body: string;
+      };
+
+      const mailService = createMailService(env);
+
+      const result = await mailService.replyToThread({
+        threadId: body.threadId,
+        mailboxId: body.mailboxId,
+        senderId: body.senderId,
+        bodyHtml: body.bodyHtml,
+        body: body.body,
+      });
+
+      return Response.json({ messageId: result.messageId });
+    }
+
+    return new Response("Not found", { status: 404 });
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+`replyToThread` does the following:
+
+1. Looks up the thread and its latest message
+2. Generates a new Message-ID (`<uuidv7@yourdomain.com>`)
+3. Sets In-Reply-To to the latest message's Message-ID
+4. Appends to the References chain (RFC 5322 compliant)
+5. Sends via Resend
+6. Stores the outbound message in D1 and the raw RFC 822 content in R2
+7. Moves the thread to the "sent" folder snapshot and updates the thread snippet
+
+Test it:
+
+```bash
+curl -X POST https://mail-worker.<your-subdomain>.workers.dev/api/threads/reply \
+  -H "Content-Type: application/json" \
+  -d '{
+    "threadId": "<thread-id-from-d1>",
+    "mailboxId": "<mailbox-id-from-d1>",
+    "senderId": "<your-user-id>",
+    "bodyHtml": "<p>Thanks for reaching out. We are looking into this.</p>",
+    "body": "Thanks for reaching out. We are looking into this."
+  }'
+```
+
+---
+
+## 7. What's next
+
+You now have a working inbound + outbound email system on the edge. Here is what each additional package unlocks.
+
+### AI classification
+
+```bash
+pnpm add @rafters/mail-workers-ai
+```
+
+Zero-shot classification using DeBERTa-v3 on Workers AI. Categorizes messages into 8 categories (support, feedback, abuse, partnership, spam, billing, legal, other), assigns priority, and auto-applies labels. Runs as a Cloudflare Workflow or Queue consumer.
+
+Add the AI binding to `wrangler.jsonc`:
+
+```jsonc
+{
+  "ai": {
+    "binding": "AI",
+  },
+}
+```
+
+### Email templates
+
+```bash
+pnpm add @rafters/mail-react-email
+```
+
+React Email templates with a renderer interface. Ship a `BaseEmail` wrapper with configurable branding (logo, links, copyright) and compose templates like OTP verification, welcome emails, and notifications. No hardcoded branding.
+
+### Team collaboration
+
+Already in core. Shared mailboxes support:
+
+- **Thread assignment**: assign threads to team members via `AssignmentService`
+- **Internal notes**: add markdown notes to threads via `NoteService` (not visible to external parties)
+- **Labels**: system labels, AI-generated labels, and custom labels via `LabelService`
+- **Folder management**: system folders (inbox, sent, drafts, spam, trash, archive) plus custom folders via `FolderService`
+- **Thread status**: open, pending, resolved, closed via `ThreadService`
+
+### OTP with better-auth
+
+```bash
+pnpm add @rafters/better-auth-resend
+```
+
+Glue package that wires Resend + React Email templates into better-auth's `emailOTP` plugin:
+
+```typescript
+import { resendOTP } from "@rafters/better-auth-resend";
+
+emailOTP({
+  sendVerificationOTP: resendOTP(env),
+});
+```
+
+---
+
+## Package map
+
+| Package                       | What it does                             | Depends on                                          |
+| ----------------------------- | ---------------------------------------- | --------------------------------------------------- |
+| `@rafters/mail`               | Schema, types, interfaces, threading     | nothing                                             |
+| `@rafters/mail-resend`        | Outbound via Resend (raw fetch)          | `@rafters/mail`                                     |
+| `@rafters/mail-cloudflare`    | Inbound via CF Email Routing, R2 storage | `@rafters/mail`                                     |
+| `@rafters/mail-react-email`   | Template rendering                       | `@rafters/mail`                                     |
+| `@rafters/mail-workers-ai`    | AI classification (DeBERTa-v3)           | `@rafters/mail`                                     |
+| `@rafters/better-auth-resend` | OTP glue for better-auth                 | `@rafters/mail-resend`, `@rafters/mail-react-email` |
+
+Core has zero vendor dependencies. Every adapter is swappable.
diff --git a/packages/better-auth-resend/README.md b/packages/better-auth-resend/README.md
new file mode 100644
index 0000000..80d967d
--- /dev/null
+++ b/packages/better-auth-resend/README.md
@@ -0,0 +1,54 @@
+# @rafters/better-auth-resend
+
+One-line emailOTP integration for [better-auth](https://better-auth.com) using [`@rafters/mail-resend`](https://www.npmjs.com/package/@rafters/mail-resend) + [`@rafters/mail-react-email`](https://www.npmjs.com/package/@rafters/mail-react-email). Glues the three together so better-auth's `emailOTP` plugin sends real emails through Resend with the rafters `OtpEmail` template.
+
+Part of [@rafters/mail](https://github.com/rafters-studio/mail).
+
+## Install
+
+```bash
+pnpm add @rafters/better-auth-resend @rafters/mail-resend @rafters/mail-react-email better-auth
+```
+
+## Usage
+
+```typescript
+import { betterAuth } from "better-auth";
+import { emailOTP } from "better-auth/plugins";
+import { resendOTP } from "@rafters/better-auth-resend";
+
+export const auth = betterAuth({
+  // ... your database, session, etc.
+  plugins: [
+    emailOTP({
+      sendVerificationOTP: resendOTP({
+        apiKey: env.RESEND_API_KEY,
+        from: "noreply@example.com",
+        appName: "Example",
+      }),
+    }),
+  ],
+});
+```
+
+That is the whole integration. `resendOTP` builds the Resend provider, renders `OtpEmail` via the React Email renderer, and returns the `sendVerificationOTP` function that better-auth's emailOTP plugin expects.
+
+## Configuration
+
+| Option    | Required | Description                                           |
+| --------- | -------- | ----------------------------------------------------- |
+| `apiKey`  | yes      | Resend API key                                        |
+| `from`    | yes      | Sender address -- must be a verified domain in Resend |
+| `appName` | yes      | Shown in the email subject and body (e.g., "Example") |
+
+## Documentation
+
+Per-package docs ship in the `docs/` directory and on npm:
+
+- [`usage.md`](./docs/usage.md) -- Full better-auth + emailOTP integration example, configuration options, troubleshooting, and how to replace the default template
+
+See the [monorepo README](https://github.com/rafters-studio/mail#readme) for the wider @rafters/mail architecture.
+
+## License
+
+MIT
diff --git a/packages/better-auth-resend/docs/usage.md b/packages/better-auth-resend/docs/usage.md
new file mode 100644
index 0000000..6e21ee4
--- /dev/null
+++ b/packages/better-auth-resend/docs/usage.md
@@ -0,0 +1,100 @@
+# better-auth + Resend OTP Integration
+
+`@rafters/better-auth-resend` glues three things together so better-auth's `emailOTP` plugin sends real emails via Resend using the rafters `OtpEmail` template:
+
+1. [`@rafters/mail-resend`](https://www.npmjs.com/package/@rafters/mail-resend) -- the Resend API client
+2. [`@rafters/mail-react-email`](https://www.npmjs.com/package/@rafters/mail-react-email) -- the `OtpEmail` React template and renderer
+3. [better-auth](https://better-auth.com) -- the auth system with the `emailOTP` plugin
+
+This package exports a single function, `resendOTP`, that returns the `sendVerificationOTP` function that better-auth's `emailOTP` plugin expects.
+
+## Install
+
+```bash
+pnpm add @rafters/better-auth-resend @rafters/mail-resend @rafters/mail-react-email better-auth
+```
+
+## Full example
+
+```typescript
+import { betterAuth } from "better-auth";
+import { emailOTP } from "better-auth/plugins";
+import { resendOTP } from "@rafters/better-auth-resend";
+
+export const auth = betterAuth({
+  database: yourDatabase,
+  session: yourSessionConfig,
+
+  plugins: [
+    emailOTP({
+      sendVerificationOTP: resendOTP({
+        apiKey: process.env.RESEND_API_KEY!,
+        from: "noreply@example.com",
+        appName: "Example",
+      }),
+    }),
+  ],
+});
+```
+
+That is the whole integration. `resendOTP` builds a Resend provider from your API key, renders `OtpEmail` via the React Email renderer, and returns a `sendVerificationOTP` function that better-auth calls when a user requests a one-time password.
+
+## Configuration
+
+| Option    | Required | Description                                                  |
+| --------- | -------- | ------------------------------------------------------------ |
+| `apiKey`  | yes      | Resend API key. Needs `transactional emails` permission.     |
+| `from`    | yes      | Sender address. Must be on a domain verified in Resend.      |
+| `appName` | yes      | Shown in the email subject (`"Your Example code"`) and body. |
+
+## What the user sees
+
+When a user requests a one-time password via better-auth's emailOTP plugin, this package sends an email using the `OtpEmail` template:
+
+- **Subject:** `Your <appName> code: <otp>`
+- **Body:** The OTP code in a large, copyable format, with an expiry note (defaults to 10 minutes, managed by better-auth's emailOTP plugin configuration)
+- **Sender:** The `from` address you configured
+
+The template is part of `@rafters/mail-react-email`, so its appearance and layout are documented there. If you want a different template, render your own and pass a custom `sendVerificationOTP` to better-auth directly instead of using this package.
+
+## Replacing the template
+
+If you need a custom OTP email design, you do not use this package. Instead, wire `emailOTP` to your own function:
+
+```typescript
+import { betterAuth } from "better-auth";
+import { emailOTP } from "better-auth/plugins";
+import { createResendProvider } from "@rafters/mail-resend";
+import { createReactEmailRenderer } from "@rafters/mail-react-email/renderer";
+import { YourCustomOtpEmail } from "./templates/your-otp.tsx";
+
+const provider = createResendProvider({ apiKey: process.env.RESEND_API_KEY! });
+const renderer = createReactEmailRenderer();
+
+export const auth = betterAuth({
+  plugins: [
+    emailOTP({
+      async sendVerificationOTP({ email, otp, type }) {
+        const { html, text } = await renderer.render(YourCustomOtpEmail({ otp, type }));
+        await provider.send({
+          to: email,
+          from: "noreply@example.com",
+          subject: `Your code: ${otp}`,
+          html,
+          text,
+        });
+      },
+    }),
+  ],
+});
+```
+
+This package exists only to remove that boilerplate for the common case of "use the default template".
+
+## Troubleshooting
+
+**Email never arrives.** Check the Resend dashboard for delivery events. Most first-run failures are domain verification, not code.
+
+**Resend returns 403.** Your API key is missing the `transactional emails` permission, or the `from` domain is not verified in the Resend account for that key.
+
+**Rate limited.** Resend free tier is 3,000 emails / month, 100 / day. Upgrade the plan or throttle emailOTP requests upstream.
diff --git a/packages/better-auth-resend/package.json b/packages/better-auth-resend/package.json
index 0df0cdd..f1289e4 100644
--- a/packages/better-auth-resend/package.json
+++ b/packages/better-auth-resend/package.json
@@ -2,8 +2,10 @@
   "name": "@rafters/better-auth-resend",
   "version": "0.0.1",
   "description": "better-auth emailOTP glue for @rafters/mail-resend + @rafters/mail-react-email",
+  "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "type": "module",
   "exports": {
diff --git a/packages/cloudflare/README.md b/packages/cloudflare/README.md
new file mode 100644
index 0000000..8d0ca62
--- /dev/null
+++ b/packages/cloudflare/README.md
@@ -0,0 +1,81 @@
+# @rafters/mail-cloudflare
+
+Cloudflare inbound email adapter for [@rafters/mail](https://github.com/rafters-studio/mail). R2 blob storage implementation, RFC 5322 email header parsing, and content hashing for idempotent ingestion.
+
+Pairs Cloudflare Email Routing (inbound) with R2 (blob storage) to give you the two hardest pieces of edge email: receiving raw messages and storing them somewhere durable.
+
+## Install
+
+```bash
+pnpm add @rafters/mail-cloudflare @rafters/mail
+```
+
+## Usage
+
+### R2 blob storage
+
+```typescript
+import { createR2Storage } from "@rafters/mail-cloudflare/storage";
+
+const storage = createR2Storage(env.BLOB_STORAGE);
+
+await storage.put("messages/msg-123/raw.eml", rawEmailBuffer);
+const raw = await storage.get("messages/msg-123/raw.eml");
+```
+
+`createR2Storage` implements the `BlobStorage` interface from `@rafters/mail`, so it drops into any service that expects a blob store.
+
+### Email parsing
+
+```typescript
+import { parseEmailHeaders, hashContent } from "@rafters/mail-cloudflare/parsing";
+
+const headers = parseEmailHeaders(rawEmail);
+// { messageId, from, to, subject, references, inReplyTo, date, ... }
+
+const hash = await hashContent(rawEmail);
+// sha256 for dedupe and integrity checks
+```
+
+### Inbound Email Routing handler
+
+Wire Email Routing to a Worker that stores the raw email in R2, parses headers, dedupes by hash, and hands off to your threading service:
+
+```typescript
+export default {
+  async email(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext) {
+    const raw = await new Response(message.raw).arrayBuffer();
+    const hash = await hashContent(new Uint8Array(raw));
+
+    if (await env.DB.get("messages", { hash })) return; // already ingested
+
+    const headers = parseEmailHeaders(new TextDecoder().decode(raw));
+    const storage = createR2Storage(env.BLOB_STORAGE);
+    await storage.put(`messages/${hash}/raw.eml`, new Uint8Array(raw));
+
+    // Thread matching, DB insert, classification dispatch, etc.
+  },
+};
+```
+
+## Exports
+
+| Subpath     | What                                                   |
+| ----------- | ------------------------------------------------------ |
+| `.`         | Top-level re-exports                                   |
+| `./storage` | `createR2Storage` (R2 implementation of `BlobStorage`) |
+| `./parsing` | `parseEmailHeaders`, `hashContent`                     |
+
+## Documentation
+
+Per-package docs ship in the `docs/` directory and on npm:
+
+- [`quickstart.md`](./docs/quickstart.md) -- Cloudflare Workers + D1 + R2 + Email Routing setup, from zero to receiving email
+- [`inbound.md`](./docs/inbound.md) -- Inbound email flow: parsing, dedupe, blob storage, thread matching
+- [`blob-storage.md`](./docs/blob-storage.md) -- Raw email + parsed body storage in R2, key schema, retrieval
+
+See the [monorepo README](https://github.com/rafters-studio/mail#readme) for the complete framework overview.
+
+## License
+
+MIT
diff --git a/packages/cloudflare/docs/blob-storage.md b/packages/cloudflare/docs/blob-storage.md
new file mode 100644
index 0000000..2817913
--- /dev/null
+++ b/packages/cloudflare/docs/blob-storage.md
@@ -0,0 +1,91 @@
+# Blob Storage
+
+How email content is stored and retrieved.
+
+---
+
+## Why blob storage
+
+Email bodies and attachments are large (kilobytes to megabytes). Storing them inline in the database would bloat query performance and row sizes. Instead, the database stores metadata and blob keys. The actual content lives in blob storage.
+
+---
+
+## The blob storage adapter
+
+```typescript
+interface BlobStorage {
+  put(key: string, content: string | ArrayBuffer): Promise<void>;
+  get(key: string): Promise<string | undefined>;
+  delete(key: string): Promise<void>;
+}
+```
+
+Any storage backend that supports key-value blob operations works: object storage (S3-compatible), file system, KV stores.
+
+---
+
+## What gets stored
+
+Each inbound message produces up to three blobs:
+
+| Blob | Key suffix | Content                   | Purpose                              |
+| ---- | ---------- | ------------------------- | ------------------------------------ |
+| Raw  | `.eml`     | Complete RFC 5322 message | IMAP FETCH BODY[], archival          |
+| HTML | `.html`    | Extracted HTML body       | IMAP FETCH BODY[TEXT], web display   |
+| Text | `.txt`     | Extracted plain text body | Snippets, search, plain text clients |
+
+The raw blob is required. HTML and text blobs are optional (a plain-text-only email has no HTML blob).
+
+---
+
+## Key format
+
+Keys follow a date-partitioned, content-addressed pattern:
+
+```
+emails/{year}/{month}/{content-hash}.{extension}
+```
+
+Example: `emails/2026/04/a1b2c3d4e5f6.eml`
+
+- **Date partitioning**: groups blobs by month for lifecycle management
+- **Content addressing**: the hash is derived from the email content, so duplicate emails produce the same key
+- **Month is zero-padded**: `04` not `4`
+
+---
+
+## Immutability
+
+Blobs are write-once. Once stored, they are never modified. This is essential for:
+
+- **IMAP correctness**: IMAP UIDs point to immutable messages. If content could change, the UID mapping would be unreliable.
+- **Threading integrity**: In-Reply-To/References point to specific messages by Message-ID. The content those references describe must be stable.
+- **Archival**: the raw `.eml` blob is the legal record of the email as received.
+
+Deletion happens only on EXPUNGE (permanent removal of a \Deleted message). The blob is deleted alongside the database record.
+
+---
+
+## Size tracking
+
+The message record stores `sizeBytes` -- the byte size of the raw blob. This is used by:
+
+- IMAP FETCH RFC822.SIZE
+- IMAP SEARCH LARGER/SMALLER
+- Dashboard storage usage reporting
+
+---
+
+## Attachments
+
+Attachments are parsed from the MIME structure of the raw email and tracked in the database:
+
+| Field       | Purpose                             |
+| ----------- | ----------------------------------- |
+| filename    | Original filename                   |
+| contentType | MIME type (e.g., `application/pdf`) |
+| sizeBytes   | Attachment size                     |
+| blobKey     | Key in blob storage                 |
+| contentId   | For inline images (CID references)  |
+
+Each attachment is a separate blob. The attachment record links it to the parent message.
diff --git a/packages/cloudflare/docs/inbound.md b/packages/cloudflare/docs/inbound.md
new file mode 100644
index 0000000..8c61fe4
--- /dev/null
+++ b/packages/cloudflare/docs/inbound.md
@@ -0,0 +1,122 @@
+# Inbound Email
+
+How incoming email enters the system.
+
+---
+
+## The inbound adapter
+
+The `InboundAdapter` interface handles incoming email. It receives a raw email, parses it, threads it, stores the content, and optionally classifies it.
+
+```typescript
+interface InboundAdapter {
+  handleIncoming(email: InboundEmail): Promise<void>;
+}
+```
+
+The adapter is responsible for:
+
+1. Parsing the raw RFC 5322 email into structured fields
+2. Finding or creating a thread (via In-Reply-To/References headers)
+3. Storing the raw email and parsed content in blob storage
+4. Creating the message record in the database
+5. Updating thread metadata (messageCount, lastMessageAt, snippet)
+
+---
+
+## Inbound email structure
+
+When an email arrives, the adapter receives:
+
+| Field       | Source                             |
+| ----------- | ---------------------------------- |
+| from        | From header (email + display name) |
+| to          | To header                          |
+| cc, bcc     | CC/BCC headers                     |
+| subject     | Subject header                     |
+| messageId   | Message-ID header                  |
+| inReplyTo   | In-Reply-To header                 |
+| references  | References header                  |
+| date        | Date header                        |
+| textBody    | Plain text content                 |
+| htmlBody    | HTML content                       |
+| rawEmail    | The complete RFC 5322 message      |
+| attachments | MIME attachments with metadata     |
+| headers     | All headers as key-value pairs     |
+
+---
+
+## Storage
+
+Each message stores content in three locations:
+
+1. **Database record**: structured metadata (from, to, subject, dates, flags, thread assignment). Used for listing, searching, and flag management.
+2. **Blob storage (raw)**: the complete RFC 5322 email as received. Immutable. Used by IMAP FETCH BODY[].
+3. **Blob storage (parsed)**: extracted HTML and plain text bodies. Used by IMAP FETCH BODY[TEXT] and for snippet generation.
+
+Blob keys follow a date-partitioned pattern: `emails/{year}/{month}/{content-hash}.{extension}`. Content-addressed storage means duplicate emails produce the same key.
+
+---
+
+## DNS configuration
+
+For email to reach your inbound adapter, configure these DNS records on your domain:
+
+### MX record
+
+Points incoming email to your email infrastructure:
+
+```
+yourdomain.com  MX  10  your-mail-handler
+```
+
+### SPF record
+
+Declares which servers can send email for your domain:
+
+```
+yourdomain.com  TXT  "v=spf1 include:your-provider ~all"
+```
+
+### DKIM record
+
+Cryptographic signature for outbound email authenticity. Your sending provider generates the key pair and publishes the public key:
+
+```
+selector._domainkey.yourdomain.com  TXT  "v=DKIM1; k=rsa; p=..."
+```
+
+### DMARC record
+
+Policy for handling emails that fail SPF/DKIM verification:
+
+```
+_dmarc.yourdomain.com  TXT  "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com"
+```
+
+---
+
+## Classification
+
+After storage, the inbound adapter can optionally classify the message using an AI classifier. The classifier assigns:
+
+- **category**: support, feedback, abuse, partnership, spam, billing, legal, other
+- **confidence**: 0-100 score
+- **summary**: one-line description of the message content
+
+Classification results are stored on the message record. They drive folder assignment, priority, and dashboard filtering.
+
+The classifier is a separate adapter (`ClassificationAdapter`). The default implementation uses zero-shot classification with a language model, but any classification strategy can be plugged in.
+
+---
+
+## IMAP integration
+
+When inbound processing completes and the message is stored, the inbound adapter can signal the IMAP server to notify connected clients:
+
+1. Message stored in database + blob storage
+2. Adapter signals the IMAP server (platform-specific: DO fetch, TCP callback, etc.)
+3. IMAP server pushes `* N EXISTS` to all IDLE clients on that mailbox
+4. Clients fetch the new message
+
+This is how real-time push works: the inbound adapter is the trigger, the IMAP IDLE mechanism is the delivery channel.
diff --git a/packages/cloudflare/docs/quickstart.md b/packages/cloudflare/docs/quickstart.md
new file mode 100644
index 0000000..ad99679
--- /dev/null
+++ b/packages/cloudflare/docs/quickstart.md
@@ -0,0 +1,185 @@
+# Quickstart: Cloudflare
+
+Set up @rafters/mail on Cloudflare Workers with D1 (database), R2 (blob storage), Email Routing (inbound), and Resend (outbound). From zero to receiving email in your inbox.
+
+---
+
+## Prerequisites
+
+- Cloudflare account with a domain
+- Resend account with a verified sending domain
+- Node.js 20+ and pnpm
+
+---
+
+## 1. Create the project
+
+```bash
+mkdir my-mail && cd my-mail
+pnpm init
+pnpm add @rafters/mail @rafters/mail-resend @rafters/mail-cloudflare @rafters/mail-workers-ai
+pnpm add -D wrangler typescript
+```
+
+---
+
+## 2. Configure wrangler
+
+```jsonc
+// wrangler.jsonc
+{
+  "name": "mail",
+  "compatibility_date": "2025-04-01",
+  "d1_databases": [{ "binding": "DB", "database_name": "mail", "database_id": "your-database-id" }],
+  "r2_buckets": [{ "binding": "BLOB_STORAGE", "bucket_name": "mail-blobs" }],
+}
+```
+
+Create the resources:
+
+```bash
+wrangler d1 create mail
+wrangler r2 bucket create mail-blobs
+```
+
+Copy the database_id from the output into your wrangler.jsonc.
+
+---
+
+## 3. Create the database
+
+Apply the schema migrations:
+
+```bash
+wrangler d1 execute mail --file node_modules/@rafters/mail/migrations/0001_initial.sql
+```
+
+---
+
+## 4. Set secrets
+
+```bash
+wrangler secret put RESEND_API_KEY
+# Paste your Resend API key when prompted
+```
+
+---
+
+## 5. Write the Worker
+
+```typescript
+// src/index.ts
+import { createResendProvider } from "@rafters/mail-resend";
+import { createR2BlobStorage, parseInboundEmail } from "@rafters/mail-cloudflare";
+
+export default {
+  // Handle inbound email from Cloudflare Email Routing
+  async email(message, env) {
+    const parsed = await parseInboundEmail(message);
+    const blobStorage = createR2BlobStorage(env.BLOB_STORAGE);
+
+    // Store raw email in blob storage
+    const blobKey = await blobStorage.put(parsed.rawEmail);
+
+    // Store message record in D1
+    // (wire up your service layer here)
+  },
+
+  // Handle HTTP requests (webhooks, API)
+  async fetch(request, env) {
+    return new Response("Mail worker running");
+  },
+};
+```
+
+---
+
+## 6. Configure Email Routing
+
+In the Cloudflare dashboard:
+
+1. Go to your domain > Email > Email Routing
+2. Enable Email Routing
+3. Add a catch-all rule or specific addresses
+4. Set the destination to your Worker
+
+This creates the MX records automatically.
+
+---
+
+## 7. Configure DNS for sending
+
+In your domain's DNS settings, add the records from Resend:
+
+```
+# SPF
+yourdomain.com  TXT  "v=spf1 include:amazonses.com ~all"
+
+# DKIM (Resend provides this)
+resend._domainkey.yourdomain.com  TXT  "v=DKIM1; k=rsa; p=..."
+
+# DMARC
+_dmarc.yourdomain.com  TXT  "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com"
+```
+
+Verify the domain in your Resend dashboard.
+
+---
+
+## 8. Deploy
+
+```bash
+wrangler types
+wrangler deploy
+```
+
+---
+
+## 9. Test
+
+Send an email to your domain. Check the Worker logs:
+
+```bash
+wrangler tail
+```
+
+You should see the inbound email parsed and stored.
+
+Send an outbound email:
+
+```typescript
+const provider = createResendProvider({ apiKey: env.RESEND_API_KEY });
+await provider.sendEmail({
+  from: "you@yourdomain.com",
+  to: ["recipient@example.com"],
+  subject: "Hello from the edge",
+  text: "Sent via @rafters/mail on Cloudflare Workers.",
+});
+```
+
+---
+
+## 10. Add IMAP (optional)
+
+To access your mailbox from Apple Mail, Thunderbird, or Outlook, add the IMAP server. See the [IMAP Quickstart](./imap-quickstart.md) for Cloudflare DO (WebSocket) or Node TCP (Fly.io) deployment options.
+
+---
+
+## What you have now
+
+- Inbound email via Cloudflare Email Routing
+- Outbound email via Resend
+- Message storage in D1 (metadata) + R2 (blobs)
+- Threading via RFC 5322 headers
+- Ready for classification (add @rafters/mail-workers-ai)
+- Ready for IMAP client access (add @rafters/mail-imap-cloudflare or @rafters/mail-imap-server)
+
+---
+
+## Next steps
+
+- [Classification](./classification.md) -- auto-categorize incoming email
+- [IMAP](./imap-quickstart.md) -- connect email clients
+- [Newsletters](./newsletters.md) -- send to subscriber lists
+- [App Passwords](./app-passwords.md) -- set up IMAP authentication
+- [Deployment Guide](./imap-deployment.md) -- deploy IMAP on Fly, Railway, or Docker
diff --git a/packages/cloudflare/package.json b/packages/cloudflare/package.json
index 9ab85aa..e050109 100644
--- a/packages/cloudflare/package.json
+++ b/packages/cloudflare/package.json
@@ -2,8 +2,10 @@
   "name": "@rafters/mail-cloudflare",
   "version": "0.0.1",
   "description": "Cloudflare Email Routing inbound adapter and R2 blob storage for @rafters/mail",
+  "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "type": "module",
   "exports": {
diff --git a/packages/core/README.md b/packages/core/README.md
new file mode 100644
index 0000000..abf87bb
--- /dev/null
+++ b/packages/core/README.md
@@ -0,0 +1,76 @@
+# @rafters/mail
+
+Email inbox framework for the edge. The core package: schema, types, service interfaces, threading logic, and database migrations.
+
+Part of [@rafters/mail](https://github.com/rafters-studio/mail), an email inbox framework for teams building on Cloudflare Workers, AWS Lambda, Deno Deploy, Vercel Edge, or anywhere Node runs.
+
+## Install
+
+```bash
+pnpm add @rafters/mail
+```
+
+## What you get
+
+**13 Drizzle tables** covering the full inbox + newsletter data model: mailboxes (personal and shared), folders, labels (system, AI, user), threads, messages, attachments, assignments, notes, audiences, subscribers, and broadcast audit.
+
+**Zod validators** for every API boundary operation. Types are inferred from schemas with `z.infer<>`, never hand-written.
+
+**Service implementations** for thread management, folder CRUD, label application, assignments, internal notes, and compose/reply with RFC 5322 header generation.
+
+**Adapter interfaces** that decouple core from any vendor:
+
+| Interface          | Purpose                                        | Ships in                    |
+| ------------------ | ---------------------------------------------- | --------------------------- |
+| `EmailProvider`    | Send email and manage mailing lists            | `@rafters/mail-resend`      |
+| `BlobStorage`      | Store and retrieve raw email and parsed bodies | `@rafters/mail-cloudflare`  |
+| `EmailClassifier`  | Classify email content                         | `@rafters/mail-workers-ai`  |
+| `TemplateRenderer` | Render email templates to HTML and text        | `@rafters/mail-react-email` |
+| `AuthAdapter`      | Resolve user identity and access control       | You implement               |
+| `InboundAdapter`   | Receive email from external sources            | `@rafters/mail-cloudflare`  |
+
+## Usage
+
+```typescript
+// Schema (Drizzle tables)
+import { mailbox, inboxThread, inboxMessage } from "@rafters/mail/schema";
+
+// Validators (API boundaries)
+import { composeEmailSchema, listThreadsSchema } from "@rafters/mail/schema";
+
+// Service implementations
+import { createMailServices, createInboxEmailService } from "@rafters/mail/services";
+
+// Threading
+import { generateMessageId, buildReferences } from "@rafters/mail/threading";
+
+// Auth adapter interface
+import type { AuthAdapter } from "@rafters/mail/auth";
+
+// Types
+import type { Thread, Folder, Label, ComposeEmail } from "@rafters/mail";
+```
+
+## Design principles
+
+1. **Zod is source of truth.** Types inferred via `z.infer<>`, never hand-written.
+2. **Zero vendor lock-in in core.** No Resend, Cloudflare, or React Email dependencies here.
+3. **Drizzle for queries, you own migrations.** Core exports schema and raw SQL; your app runs migrations with your tooling.
+4. **Plain text user references.** `ownerId`, `assigneeId`, and `authorId` are text columns with no FK to external auth tables.
+5. **Platform vocabulary.** `MailingList` (not Audience), `Subscriber` (not Contact), `Campaign` (not Broadcast). Vendor terms stay inside adapters.
+
+## Documentation
+
+Per-package docs ship in the `docs/` directory and on npm:
+
+- [`reference.md`](./docs/reference.md) -- Full schema and API reference (all 13 tables, service interfaces, Zod schemas, design decisions)
+- [`threading.md`](./docs/threading.md) -- RFC 5322 threading via `In-Reply-To` and `References`
+- [`migrations.md`](./docs/migrations.md) -- Database migration workflow
+- [`newsletters.md`](./docs/newsletters.md) -- Mailing lists, subscribers, campaigns, and broadcast audit
+- [`adapters.md`](./docs/adapters.md) -- How adapters connect core to external services
+
+See the [monorepo README](https://github.com/rafters-studio/mail#readme) for the wider framework overview and package list.
+
+## License
+
+MIT
diff --git a/packages/core/docs/adapters.md b/packages/core/docs/adapters.md
new file mode 100644
index 0000000..6b40ca0
--- /dev/null
+++ b/packages/core/docs/adapters.md
@@ -0,0 +1,989 @@
+# @rafters/mail Adapters Guide
+
+Adapters connect the @rafters/mail core to external services. The core has zero vendor dependencies. Every external concern lives in an adapter package that implements an interface defined in core.
+
+Five adapter packages ship today:
+
+| Package                       | Direction         | Interface                             |
+| ----------------------------- | ----------------- | ------------------------------------- |
+| `@rafters/mail-resend`        | Outbound          | `EmailProvider`                       |
+| `@rafters/mail-cloudflare`    | Inbound + Storage | `InboundAdapter`, `BlobStorage`       |
+| `@rafters/mail-react-email`   | Templates         | `TemplateRenderer`                    |
+| `@rafters/mail-workers-ai`    | Classification    | `EmailClassifier`                     |
+| `@rafters/better-auth-resend` | Auth glue         | N/A (wires adapters into better-auth) |
+
+---
+
+## @rafters/mail-resend
+
+Outbound email adapter. Wraps the Resend API via raw `fetch`. No Resend SDK dependency.
+
+### Install
+
+```bash
+pnpm add @rafters/mail-resend
+```
+
+### What it contains
+
+**ResendService** is the low-level API wrapper. Every request and response is validated with Zod. It handles authentication, error parsing, and rate limit detection.
+
+**ResendProvider** implements the `EmailProvider` interface from `@rafters/mail`. It translates platform vocabulary to Resend vocabulary at the boundary. Internal code never uses Resend terms.
+
+**MockEmailProvider** is an in-memory mock for testing. Stores all sent emails, created lists, and subscribers in arrays you can inspect.
+
+### Vocabulary mapping
+
+The platform uses its own terms. The adapter translates at the boundary.
+
+| @rafters/mail | Resend API |
+| ------------- | ---------- |
+| MailingList   | Audience   |
+| Subscriber    | Contact    |
+| Campaign      | Broadcast  |
+
+Your application code uses MailingList, Subscriber, and Campaign. Resend terms only appear inside the adapter.
+
+### Config
+
+```typescript
+interface ResendConfig {
+  apiKey: string;
+  fromEmail: string;
+  baseUrl?: string; // Defaults to https://api.resend.com
+}
+```
+
+### EmailProvider interface
+
+The full contract that `ResendProvider` implements:
+
+```typescript
+interface EmailProvider {
+  // Transactional
+  sendEmail(params: EmailParams): Promise<{ id: string }>;
+
+  // Mailing lists
+  createMailingList(name: string): Promise<MailingList>;
+  getMailingList(id: string): Promise<MailingList>;
+  deleteMailingList(id: string): Promise<void>;
+
+  // Subscribers
+  addSubscriber(listId: string, email: string, data?: SubscriberData): Promise<Subscriber>;
+  removeSubscriber(listId: string, subscriberId: string): Promise<void>;
+  updateSubscriber(subscriberId: string, updates: SubscriberUpdates): Promise<Subscriber>;
+  listSubscribers(listId: string): Promise<Subscriber[]>;
+
+  // Campaigns
+  sendCampaign(params: CampaignParams): Promise<{ id: string }>;
+  getCampaign(id: string): Promise<{ id: string; subject: string; sentAt: Date }>;
+  createCampaignDraft(params: CampaignParams): Promise<{ id: string }>;
+  sendCampaignDraft(campaignId: string): Promise<{ id: string }>;
+  getCampaignStatus(campaignId: string): Promise<CampaignStatus>;
+
+  // Audiences
+  listAudiences(): Promise<Audience[]>;
+}
+```
+
+### Usage
+
+#### Sending a transactional email
+
+```typescript
+import { ResendService, ResendProvider } from "@rafters/mail-resend";
+
+const resend = new ResendService({
+  apiKey: env.RESEND_API_KEY,
+  fromEmail: "hello@yourdomain.com",
+});
+
+const provider = new ResendProvider(resend);
+
+const { id } = await provider.sendEmail({
+  to: "user@example.com",
+  subject: "Your order shipped",
+  html: "<p>Tracking number: ABC123</p>",
+});
+```
+
+#### Managing mailing lists and subscribers
+
+```typescript
+const list = await provider.createMailingList("Product Updates");
+
+await provider.addSubscriber(list.id, "reader@example.com", {
+  firstName: "Jo",
+  lastName: "Smith",
+});
+
+const subscribers = await provider.listSubscribers(list.id);
+```
+
+#### Campaigns: one-shot and draft flow
+
+```typescript
+// One-shot: send immediately
+await provider.sendCampaign({
+  audienceId: list.id,
+  from: "news@yourdomain.com",
+  subject: "March update",
+  html: "<p>Here is what happened this month.</p>",
+});
+
+// Two-step: create draft, review, then send
+const draft = await provider.createCampaignDraft({
+  audienceId: list.id,
+  from: "news@yourdomain.com",
+  subject: "April update",
+  html: "<p>Draft content here.</p>",
+});
+
+// Later, after review:
+await provider.sendCampaignDraft(draft.id);
+
+// Check delivery status
+const status = await provider.getCampaignStatus(draft.id);
+```
+
+### Error handling
+
+`ResendService` throws `ResendError` on API failures:
+
+```typescript
+import { ResendError } from "@rafters/mail-resend";
+
+try {
+  await provider.sendEmail({ to: "bad", subject: "Test", html: "<p>hi</p>" });
+} catch (err) {
+  if (err instanceof ResendError) {
+    console.log(err.statusCode); // 422
+    console.log(err.resendMessage); // "Invalid email address"
+  }
+}
+```
+
+Rate limits return HTTP 429 with a `Retry-After` header. `ResendService` parses this and includes it on the error:
+
+```typescript
+try {
+  await provider.sendEmail(params);
+} catch (err) {
+  if (err instanceof ResendError && err.statusCode === 429) {
+    const retryAfter = err.retryAfter; // seconds to wait
+    // back off and retry
+  }
+}
+```
+
+All request payloads are validated with Zod before the fetch call. All responses are validated with Zod after parsing. If Resend changes their API shape, you get a clear Zod error instead of a silent data corruption.
+
+### Testing with MockEmailProvider
+
+```typescript
+import { MockEmailProvider } from "@rafters/mail-resend";
+
+const mock = new MockEmailProvider();
+
+await mock.sendEmail({
+  to: "test@example.com",
+  subject: "Hello",
+  html: "<p>Test</p>",
+});
+
+// Inspect what was sent
+console.log(mock.sentEmails);
+// [{ to: 'test@example.com', subject: 'Hello', html: '<p>Test</p>' }]
+
+const list = await mock.createMailingList("Beta Testers");
+await mock.addSubscriber(list.id, "tester@example.com");
+
+console.log(mock.subscribers);
+// [{ listId: '...', email: 'tester@example.com' }]
+```
+
+`MockEmailProvider` implements the same `EmailProvider` interface. Swap it in during tests with no code changes to your service layer.
+
+### Gotchas
+
+- The adapter uses raw `fetch`, not the Resend SDK. If you also install `resend` as a dependency, they will not share state or configuration. Pick one.
+- `fromEmail` must be a verified domain in your Resend account. Sending from an unverified domain returns a 403.
+- Resend rate limits are per-API-key, not per-request. If you run multiple workers sharing a key, coordinate your retry logic.
+- Zod validation on responses means a Resend API change can break your build before it breaks your data. This is intentional.
+
+---
+
+## @rafters/mail-cloudflare
+
+Inbound email and blob storage for Cloudflare. Receives email via Email Routing, parses RFC 5322 headers, stores raw content in R2, stores metadata in D1, and dispatches to a classification queue.
+
+### Install
+
+```bash
+pnpm add @rafters/mail-cloudflare
+```
+
+### What it contains
+
+**Email Routing worker handler.** Receives `EmailMessage` from Cloudflare Email Routing. Parses headers. Stores the raw `.eml` in R2. Stores parsed HTML and plain text in R2. Inserts a metadata row into `inbox_message` in D1. Matches or creates a thread. Dispatches to a classification queue.
+
+**R2 storage adapter.** Implements the `BlobStorage` interface from `@rafters/mail`. Handles put, get, and key generation for email content.
+
+### Inbound flow
+
+1. Cloudflare Email Routing delivers `EmailMessage` to the worker
+2. Worker parses RFC 5322 headers: From, To, CC, Subject, Message-ID, In-Reply-To, References, Date
+3. Raw `.eml` stored in R2
+4. Parsed HTML and plain text stored separately in R2
+5. Metadata row inserted into `inbox_message` in D1 with R2 keys
+6. Thread matching: look up existing thread by In-Reply-To header, then References. Create new thread if no match.
+7. Message dispatched to classification queue
+
+### R2 key format
+
+```
+emails/{year}/{month}/{sha256-first-16-chars}.{eml|html|txt}    (month is zero-padded)
+```
+
+Example: `emails/2026/04/a1b2c3d4e5f67890.eml`
+
+The SHA-256 hash is computed from the raw email content. First 16 hex characters provide collision resistance with readable keys. Three files per email: `.eml` (raw), `.html` (parsed HTML body), `.txt` (parsed plain text body).
+
+### BlobStorage interface
+
+```typescript
+interface BlobStorage {
+  putRaw(
+    key: string,
+    content: string | ArrayBuffer,
+    metadata?: Record<string, string>,
+  ): Promise<void>;
+  putText(key: string, content: string): Promise<void>;
+  putHtml(key: string, content: string): Promise<void>;
+  get(
+    key: string,
+    options?: { range?: { offset: number; length: number } },
+  ): Promise<BlobObject | null>;
+  generateKey(contentHash: string, extension: "eml" | "html" | "txt"): string;
+}
+```
+
+### Usage
+
+#### Wrangler configuration
+
+```jsonc
+// wrangler.jsonc
+{
+  "name": "mail-worker",
+  "main": "src/worker.ts",
+  "compatibility_date": "2026-03-01",
+  "email_routing": {
+    "enabled": true,
+  },
+  "r2_buckets": [{ "binding": "EMAIL_BUCKET", "bucket_name": "mail-storage" }],
+  "d1_databases": [{ "binding": "DB", "database_name": "mail-db", "database_id": "..." }],
+  "queues": {
+    "producers": [{ "queue": "email-classify", "binding": "CLASSIFY_QUEUE" }],
+  },
+}
+```
+
+#### Worker entry point
+
+```typescript
+import { handleInboundEmail } from "@rafters/mail-cloudflare";
+import { R2BlobStorage } from "@rafters/mail-cloudflare/storage";
+
+interface Env {
+  DB: D1Database;
+  EMAIL_BUCKET: R2Bucket;
+  CLASSIFY_QUEUE: Queue;
+}
+
+export default {
+  async email(message: EmailMessage, env: Env) {
+    const storage = new R2BlobStorage(env.EMAIL_BUCKET);
+
+    const { messageId, threadId } = await handleInboundEmail({
+      message,
+      db: env.DB,
+      storage,
+      classifyQueue: env.CLASSIFY_QUEUE,
+    });
+
+    console.log(`Stored message ${messageId} in thread ${threadId}`);
+  },
+};
+```
+
+#### Using BlobStorage directly
+
+```typescript
+import { R2BlobStorage } from "@rafters/mail-cloudflare/storage";
+
+const storage = new R2BlobStorage(env.EMAIL_BUCKET);
+
+// Generate a key from content hash
+const key = storage.generateKey("a1b2c3d4e5f67890", "eml");
+// -> "emails/2026/04/a1b2c3d4e5f67890.eml"
+
+// Store raw email
+await storage.putRaw(key, rawEmailBuffer, {
+  "content-type": "message/rfc822",
+});
+
+// Retrieve later
+const blob = await storage.get(key);
+if (blob) {
+  const text = await blob.text();
+}
+```
+
+### Thread matching
+
+Inbound emails are threaded using RFC 5322 headers:
+
+1. Check `In-Reply-To` header against existing `inbox_message.messageId` in D1
+2. If no match, check each Message-ID in the `References` header
+3. If still no match, create a new thread
+
+The thread's `subject` comes from the first message. The thread's `snippet` updates to the latest message (first 200 characters of plain text body). The `participants` JSON array accumulates all email addresses across the thread.
+
+### Testing
+
+No built-in mock for the inbound handler. For integration tests, use Miniflare (Cloudflare's local simulator) which provides local D1, R2, and Queue bindings.
+
+For unit testing the `BlobStorage` interface, create an in-memory implementation:
+
+```typescript
+class InMemoryBlobStorage implements BlobStorage {
+  private store = new Map<
+    string,
+    { content: string | ArrayBuffer; metadata?: Record<string, string> }
+  >();
+
+  async putRaw(key: string, content: string | ArrayBuffer, metadata?: Record<string, string>) {
+    this.store.set(key, { content, metadata });
+  }
+
+  async putText(key: string, content: string) {
+    this.store.set(key, { content, metadata: { "content-type": "text/plain" } });
+  }
+
+  async putHtml(key: string, content: string) {
+    this.store.set(key, { content, metadata: { "content-type": "text/html" } });
+  }
+
+  async get(key: string) {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    return {
+      text: async () =>
+        typeof entry.content === "string" ? entry.content : new TextDecoder().decode(entry.content),
+      arrayBuffer: async () =>
+        typeof entry.content === "string"
+          ? new TextEncoder().encode(entry.content).buffer
+          : entry.content,
+      customMetadata: entry.metadata,
+    };
+  }
+
+  generateKey(contentHash: string, extension: "eml" | "html" | "txt") {
+    const now = new Date();
+    return `emails/${now.getFullYear()}/${String(now.getMonth() + 1).padStart(2, "0")}/${contentHash}.${extension}`;
+  }
+}
+```
+
+### Gotchas
+
+- Cloudflare Email Routing must be enabled on your domain. This is a DNS configuration, not just a wrangler setting.
+- The worker receives the raw email as a stream. The handler reads it fully into memory for hashing and storage. Very large emails (25MB+ attachments) will consume worker memory. Cloudflare Workers have a 128MB limit.
+- R2 keys include year/month for lifecycle management. You can set R2 lifecycle rules to auto-delete old emails.
+- The classification queue dispatch is fire-and-forget from the inbound handler's perspective. If the queue is full or down, the email is still stored. Classification happens asynchronously.
+- Thread matching is by Message-ID headers only. Subject-line matching (re-attaching "Re: same subject" emails without proper headers) is not implemented. This is intentional: subject matching produces false positives.
+
+---
+
+## @rafters/mail-react-email
+
+Email templates built with React Email. All branding is configurable via props. No hardcoded values.
+
+### Install
+
+```bash
+pnpm add @rafters/mail-react-email
+```
+
+### What it contains
+
+**BaseEmail** component: provides the standard email layout with configurable header (logo), content area, and footer (links, copyright, optional unsubscribe).
+
+**OtpEmail** component: verification code display with configurable expiry text.
+
+**TemplateRenderer** interface implementation: renders React Email components to HTML and plain text.
+
+### BaseEmailProps
+
+```typescript
+interface BaseEmailProps {
+  preview: string; // Preview text shown in inbox list
+  children: ReactNode; // Email body content
+  includeUnsubscribe?: boolean; // Show unsubscribe link in footer
+  logoUrl?: string; // Header logo image URL
+  websiteUrl?: string; // Link target for logo and brand name
+  brandName?: string; // Shown in footer copyright
+  copyrightHolder?: string; // Legal entity for copyright line
+}
+```
+
+Every prop that touches branding is configurable. No defaults reference any specific product or domain.
+
+### TemplateRenderer interface
+
+```typescript
+interface TemplateRenderer {
+  render(
+    template: string,
+    props: Record<string, unknown>,
+  ): Promise<{ html: string; text?: string }>;
+}
+```
+
+### Usage
+
+#### BaseEmail component
+
+```tsx
+import { BaseEmail } from "@rafters/mail-react-email";
+import { Text, Link } from "@react-email/components";
+
+function WelcomeEmail({ name }: { name: string }) {
+  return (
+    <BaseEmail
+      preview={`Welcome to the team, ${name}`}
+      logoUrl="https://yourdomain.com/logo.png"
+      websiteUrl="https://yourdomain.com"
+      brandName="YourApp"
+      copyrightHolder="Your Company Inc."
+    >
+      <Text>Hi {name},</Text>
+      <Text>Your account is ready.</Text>
+      <Link href="https://yourdomain.com/dashboard">Open dashboard</Link>
+    </BaseEmail>
+  );
+}
+```
+
+#### OtpEmail component
+
+```tsx
+import { OtpEmail } from "@rafters/mail-react-email";
+
+function VerificationEmail({ code }: { code: string }) {
+  return (
+    <OtpEmail
+      code={code}
+      expiryMinutes={10}
+      preview="Your verification code"
+      logoUrl="https://yourdomain.com/logo.png"
+      websiteUrl="https://yourdomain.com"
+      brandName="YourApp"
+      copyrightHolder="Your Company Inc."
+    />
+  );
+}
+```
+
+#### Rendering to HTML
+
+```typescript
+import { render } from "@react-email/render";
+import { OtpEmail } from "@rafters/mail-react-email";
+
+const html = await render(OtpEmail({ code: "843291", expiryMinutes: 10 }));
+```
+
+#### Unsubscribe link
+
+When `includeUnsubscribe` is true, the footer includes a `{{{RESEND_UNSUBSCRIBE_URL}}}` placeholder. Resend replaces this with a real unsubscribe URL at send time. This only works when sending through Resend. For other providers, supply your own unsubscribe mechanism.
+
+### Testing
+
+React Email components are React components. Test them the same way:
+
+```tsx
+import { render } from "@react-email/render";
+import { OtpEmail } from "@rafters/mail-react-email";
+
+test("OTP email contains the code", async () => {
+  const html = await render(OtpEmail({ code: "123456", expiryMinutes: 5 }));
+  expect(html).toContain("123456");
+  expect(html).toContain("5 minutes");
+});
+
+test("BaseEmail renders brand name in footer", async () => {
+  const html = await render(
+    BaseEmail({
+      preview: "test",
+      brandName: "TestCo",
+      copyrightHolder: "TestCo LLC",
+      children: null,
+    }),
+  );
+  expect(html).toContain("TestCo");
+  expect(html).toContain("TestCo LLC");
+});
+```
+
+### Gotchas
+
+- The `{{{RESEND_UNSUBSCRIBE_URL}}}` placeholder is Resend-specific. If you use a different provider for broadcasts, you need to handle unsubscribe URLs yourself.
+- React Email `render()` is async. Do not call it in a synchronous context.
+- `logoUrl` must be an absolute URL. Relative paths do not work in email clients.
+- Email clients strip most CSS. React Email handles this with inline styles, but if you add custom children with complex CSS, test across clients (Litmus, Email on Acid).
+
+---
+
+## @rafters/mail-workers-ai
+
+AI-powered email classification using Cloudflare Workers AI. Zero-shot classification with configurable categories, priority rules, and auto-tagging.
+
+### Install
+
+```bash
+pnpm add @rafters/mail-workers-ai
+```
+
+### What it contains
+
+**classifyEmail function.** Sends email content to Workers AI for zero-shot classification. Returns a category, confidence score, tags, and priority.
+
+**ClassifyEmailWorkflow.** A Cloudflare Workflow (durable, step-based) that fetches email content from blob storage, classifies it, updates D1 and R2 metadata, moves spam, and applies labels.
+
+**handleEmailClassifyQueue.** Queue consumer function with ack/retry semantics. Same classification logic as the workflow, driven by Queue messages.
+
+### Model
+
+Uses `@cf/microsoft/deberta-v3-base-zeroshot-v1.1-all-33` for zero-shot text classification. No fine-tuning required. The model receives the email text and a list of candidate labels, then returns confidence scores for each.
+
+### Categories
+
+Eight built-in categories:
+
+| Category      | Description                          |
+| ------------- | ------------------------------------ |
+| `support`     | Help requests, how-to questions      |
+| `feedback`    | Product feedback, suggestions        |
+| `abuse`       | Harassment, threats, ToS violations  |
+| `partnership` | Business inquiries, collaboration    |
+| `spam`        | Unsolicited commercial email         |
+| `billing`     | Payment, subscription, refund issues |
+| `legal`       | DMCA, copyright, legal notices       |
+| `other`       | Does not fit other categories        |
+
+### Priority determination
+
+Priority is computed from category and keyword matching:
+
+```
+abuse, legal            -> always high
+urgent keywords found   -> urgent
+high keywords found     -> high
+support, billing        -> normal (default)
+feedback, partnership   -> normal (default)
+everything else         -> low
+```
+
+Default urgent keywords: `urgent`, `emergency`, `asap`, `immediately`, `critical`, `broken`, `down`, `outage`
+
+Default high-priority keywords: `important`, `priority`, `help`, `issue`, `problem`, `error`, `bug`, `crash`
+
+Both lists are configurable.
+
+### Auto-tagging
+
+Regex patterns match against the combined subject + body text. Default patterns:
+
+| Pattern                               | Tag               |
+| ------------------------------------- | ----------------- |
+| `install\|setup\|download`            | `installation`    |
+| `crash\|error\|bug\|broken`           | `bug-report`      |
+| `feature\|request\|suggest`           | `feature-request` |
+| `account\|login\|password\|auth`      | `account`         |
+| `payment\|billing\|subscribe\|refund` | `billing`         |
+
+Add your own patterns via `ClassifierConfig.tagPatterns`. Custom patterns merge with defaults.
+
+### EmailClassifier interface
+
+```typescript
+interface EmailClassification {
+  category:
+    | "support"
+    | "feedback"
+    | "abuse"
+    | "partnership"
+    | "spam"
+    | "billing"
+    | "legal"
+    | "other";
+  confidence: number; // 0-100
+  tags: string[];
+  priority: "low" | "normal" | "high" | "urgent";
+}
+
+interface EmailClassifier {
+  classify(from: string, subject: string, body: string): Promise<EmailClassification>;
+}
+```
+
+### ClassifierConfig
+
+```typescript
+interface ClassifierConfig {
+  tagPatterns?: Array<{ pattern: RegExp; tag: string }>;
+  urgentKeywords?: string[];
+  highPriorityKeywords?: string[];
+  classificationLabels?: string[];
+  maxInputLength?: number; // Default: 4000 characters
+}
+```
+
+### Usage
+
+#### Direct classification
+
+```typescript
+import { createEmailClassifier } from "@rafters/mail-workers-ai";
+
+interface Env {
+  AI: Ai;
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const classifier = createEmailClassifier(env.AI, {
+      tagPatterns: [
+        { pattern: /refund|chargeback/, tag: "refund-request" },
+        { pattern: /api|webhook|integration/, tag: "developer" },
+      ],
+      urgentKeywords: ["outage", "breach", "critical"],
+    });
+
+    const result = await classifier.classify(
+      "user@example.com",
+      "Urgent: Payment failed",
+      "I tried to pay but got an error. This is critical for our launch.",
+    );
+
+    // result:
+    // {
+    //   category: 'billing',
+    //   confidence: 87,
+    //   tags: ['billing', 'refund-request'],
+    //   priority: 'urgent'
+    // }
+
+    return Response.json(result);
+  },
+};
+```
+
+#### ClassifyEmailWorkflow (Cloudflare Workflow)
+
+The workflow runs as a durable, multi-step process:
+
+1. Fetch email content from blob storage (first 4KB)
+2. Classify with Workers AI
+3. Update `inbox_message` in D1 with category, confidence, spam score
+4. Update R2 object metadata with classification
+5. Move spam to spam folder
+6. Apply AI-generated labels (find-or-create in D1)
+
+```typescript
+import { ClassifyEmailWorkflow } from "@rafters/mail-workers-ai/workflow";
+
+// In wrangler.jsonc:
+// "workflows": [{ "name": "classify-email", "binding": "CLASSIFY_WORKFLOW", "class_name": "ClassifyEmailWorkflow" }]
+
+export { ClassifyEmailWorkflow };
+
+interface Env {
+  AI: Ai;
+  DB: D1Database;
+  EMAIL_BUCKET: R2Bucket;
+  CLASSIFY_WORKFLOW: Workflow;
+}
+
+// Trigger from inbound handler or API:
+export default {
+  async fetch(request: Request, env: Env) {
+    const instance = await env.CLASSIFY_WORKFLOW.create({
+      params: {
+        messageId: "msg_abc123",
+        blobKey: "emails/2026/04/a1b2c3d4e5f67890.eml",
+        mailboxId: "mbx_def456",
+      },
+    });
+
+    return Response.json({ workflowId: instance.id });
+  },
+};
+```
+
+#### Queue consumer
+
+```typescript
+import { handleEmailClassifyQueue } from "@rafters/mail-workers-ai/queue";
+
+interface Env {
+  AI: Ai;
+  DB: D1Database;
+  EMAIL_BUCKET: R2Bucket;
+}
+
+export default {
+  async queue(batch: MessageBatch, env: Env) {
+    await handleEmailClassifyQueue(batch, {
+      ai: env.AI,
+      db: env.DB,
+      storage: env.EMAIL_BUCKET,
+    });
+  },
+};
+```
+
+### Testing
+
+The classifier function is pure logic around an AI call. For unit tests, mock the AI binding:
+
+```typescript
+import { createEmailClassifier } from "@rafters/mail-workers-ai";
+
+const mockAi = {
+  async run(model: string, input: unknown) {
+    return [
+      { label: "support", score: 0.85 },
+      { label: "billing", score: 0.1 },
+      { label: "spam", score: 0.02 },
+    ];
+  },
+} as unknown as Ai;
+
+const classifier = createEmailClassifier(mockAi);
+
+const result = await classifier.classify(
+  "user@example.com",
+  "Help with login",
+  "I cannot access my account after resetting my password.",
+);
+
+expect(result.category).toBe("support");
+expect(result.confidence).toBe(85);
+expect(result.tags).toContain("account");
+expect(result.priority).toBe("high"); // "help" is a high-priority keyword
+```
+
+### Gotchas
+
+- The classifier truncates input to `maxInputLength` (default 4000 characters). Long emails lose context from the end. If your emails routinely exceed this, increase the limit, but watch Workers AI latency.
+- Zero-shot classification confidence varies. A score of 60 does not mean the same thing as a score of 90. Treat confidence as relative ranking, not absolute probability.
+- The `abuse` and `legal` categories always override to high priority regardless of keyword matching. This is a safety default. Do not lower it.
+- Spam classification moves the message to the spam folder automatically in the workflow. If the classifier is wrong, the user must manually move it back. Consider a confidence threshold before auto-moving (e.g., only move if confidence > 80).
+- Workers AI has per-request latency (50-200ms for this model). Classification is async by design. Do not block the inbound handler on it.
+- Custom `classificationLabels` replaces the default 8 categories entirely. If you override, you must provide the full set. There is no merge.
+
+---
+
+## @rafters/mail-react-email (Templates)
+
+Covered above. See the [@rafters/mail-react-email](#raftersmail-react-email) section.
+
+---
+
+## @rafters/better-auth-resend
+
+Glue package that wires `@rafters/mail-resend` and `@rafters/mail-react-email` into better-auth's `emailOTP` plugin. This is the only package with an auth opinion.
+
+### Install
+
+```bash
+pnpm add @rafters/better-auth-resend
+```
+
+This package depends on `@rafters/mail-resend` and `@rafters/mail-react-email`. Both are peer dependencies and must be installed.
+
+### What it does
+
+Provides a single function, `resendOTP`, that creates a `sendVerificationOTP` handler compatible with better-auth's `emailOTP` plugin. Under the hood it:
+
+1. Creates a `ResendService` instance from your environment
+2. Renders the `OtpEmail` template with `@rafters/mail-react-email`
+3. Sends the rendered email via the Resend transactional API
+
+### Usage
+
+```typescript
+import { betterAuth } from "better-auth";
+import { emailOTP } from "better-auth/plugins";
+import { resendOTP } from "@rafters/better-auth-resend";
+
+interface Env {
+  RESEND_API_KEY: string;
+  FROM_EMAIL: string; // Verified sender address
+}
+
+export function createAuth(env: Env) {
+  return betterAuth({
+    plugins: [
+      emailOTP({
+        sendVerificationOTP: resendOTP(env),
+      }),
+    ],
+  });
+}
+```
+
+That is the entire integration. The `resendOTP` function accepts an env object with `RESEND_API_KEY` and `FROM_EMAIL`. It returns an async function with the signature better-auth expects: `(email: string, otp: string) => Promise<void>`.
+
+### Customizing the OTP email
+
+To customize branding on the OTP email, pass options:
+
+```typescript
+resendOTP(env, {
+  logoUrl: "https://yourdomain.com/logo.png",
+  websiteUrl: "https://yourdomain.com",
+  brandName: "YourApp",
+  copyrightHolder: "Your Company Inc.",
+  expiryMinutes: 10,
+});
+```
+
+These options are forwarded directly to the `OtpEmail` component props.
+
+### Testing
+
+The `resendOTP` function creates a `ResendService` internally. For testing, use `MockEmailProvider` from `@rafters/mail-resend` at the service layer, or mock the `RESEND_API_KEY` env var and intercept fetch calls:
+
+```typescript
+import { resendOTP } from "@rafters/better-auth-resend";
+
+const send = resendOTP({
+  RESEND_API_KEY: "test_key",
+  FROM_EMAIL: "test@example.com",
+});
+
+// In a test with fetch mocking (MSW, vi.fn, etc.):
+globalThis.fetch = vi
+  .fn()
+  .mockResolvedValue(new Response(JSON.stringify({ id: "email_123" }), { status: 200 }));
+
+await send("user@example.com", "843291");
+
+expect(fetch).toHaveBeenCalledWith(
+  "https://api.resend.com/emails",
+  expect.objectContaining({
+    method: "POST",
+    headers: expect.objectContaining({
+      Authorization: "Bearer test_key",
+    }),
+  }),
+);
+```
+
+### Gotchas
+
+- This package is specifically for better-auth. If you use a different auth library, use `@rafters/mail-resend` and `@rafters/mail-react-email` directly.
+- The env object must have `RESEND_API_KEY` and `FROM_EMAIL`. These are read at call time, not at import time. Safe to use with Cloudflare Workers env bindings.
+- OTP expiry displayed in the email is cosmetic. The actual expiry is controlled by better-auth's `emailOTP` plugin configuration. Make sure both match.
+
+---
+
+## Adapter architecture
+
+All adapter interfaces are defined as Zod schemas in `@rafters/mail`. Types are inferred from schemas via `z.infer<>`. Adapter packages implement the interfaces.
+
+```
+@rafters/mail (core)
+  Defines: EmailProvider, BlobStorage, TemplateRenderer, EmailClassifier, InboundAdapter, AuthAdapter
+  Depends on: nothing
+
+@rafters/mail-resend
+  Implements: EmailProvider
+  Depends on: @rafters/mail
+
+@rafters/mail-cloudflare
+  Implements: InboundAdapter, BlobStorage
+  Depends on: @rafters/mail
+
+@rafters/mail-react-email
+  Implements: TemplateRenderer
+  Depends on: @rafters/mail
+
+@rafters/mail-workers-ai
+  Implements: EmailClassifier
+  Depends on: @rafters/mail
+
+@rafters/better-auth-resend
+  Implements: nothing (glue)
+  Depends on: @rafters/mail-resend, @rafters/mail-react-email
+```
+
+### Writing a custom adapter
+
+Implement the interface from core. Example for a hypothetical Postmark outbound adapter:
+
+```typescript
+import type { EmailProvider, EmailParams } from "@rafters/mail";
+
+export class PostmarkProvider implements EmailProvider {
+  constructor(
+    private serverToken: string,
+    private fromEmail: string,
+  ) {}
+
+  async sendEmail(params: EmailParams): Promise<{ id: string }> {
+    const res = await fetch("https://api.postmarkapp.com/email", {
+      method: "POST",
+      headers: {
+        "X-Postmark-Server-Token": this.serverToken,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        From: this.fromEmail,
+        To: params.to,
+        Subject: params.subject,
+        HtmlBody: params.html,
+        TextBody: params.text,
+      }),
+    });
+
+    const data = await res.json();
+    return { id: data.MessageID };
+  }
+
+  // Implement remaining EmailProvider methods...
+}
+```
+
+The core does not care which provider you use. Swap adapters by changing the import.
+
+### No barrel exports
+
+All adapter packages use subpath exports. Import from the specific entrypoint you need:
+
+```typescript
+// Good
+import { ResendProvider } from "@rafters/mail-resend";
+import { R2BlobStorage } from "@rafters/mail-cloudflare/storage";
+import { handleEmailClassifyQueue } from "@rafters/mail-workers-ai/queue";
+import { ClassifyEmailWorkflow } from "@rafters/mail-workers-ai/workflow";
+
+// Avoid: pulling the entire package
+import * as mailResend from "@rafters/mail-resend";
+```
+
+Edge runtimes have bundle size constraints (Cloudflare Workers: 1MB compressed). Subpath exports ensure you only bundle what you use.
diff --git a/packages/core/docs/migrations.md b/packages/core/docs/migrations.md
new file mode 100644
index 0000000..18e36c9
--- /dev/null
+++ b/packages/core/docs/migrations.md
@@ -0,0 +1,79 @@
+# Migrations
+
+How the database schema is created and updated.
+
+---
+
+## Design principle
+
+@rafters/mail exports raw SQL migration strings. It does not run migrations. Your deployment tool is responsible for applying them to your database.
+
+This separation means the framework works with any SQLite-compatible database without assuming a specific migration runner.
+
+---
+
+## Schema
+
+The core schema has 13 tables across two domains:
+
+### Inbox tables (10)
+
+| Table               | Purpose                                                         |
+| ------------------- | --------------------------------------------------------------- |
+| mailbox             | Email addresses that send and receive                           |
+| inbox_folder        | Folders per mailbox (inbox, sent, drafts, spam, trash, archive) |
+| inbox_label         | Labels for categorization (system and custom)                   |
+| inbox_thread        | Conversation threads                                            |
+| inbox_message       | Individual email messages                                       |
+| inbox_message_label | Message-to-label associations                                   |
+| inbox_thread_label  | Thread-to-label associations                                    |
+| inbox_attachment    | File attachments                                                |
+| thread_assignment   | Team member assignments to threads                              |
+| thread_note         | Internal notes on threads                                       |
+
+### Newsletter tables (3)
+
+| Table        | Purpose                          |
+| ------------ | -------------------------------- |
+| mailing_list | Named subscriber lists           |
+| subscriber   | People on mailing lists          |
+| campaign     | Broadcast messages sent to lists |
+
+---
+
+## System folders
+
+When a mailbox is created, these folders are initialized automatically:
+
+| Folder  | Slug    | Purpose                            |
+| ------- | ------- | ---------------------------------- |
+| Inbox   | inbox   | Default landing for incoming email |
+| Sent    | sent    | Outbound messages                  |
+| Drafts  | drafts  | Unsent compositions                |
+| Spam    | spam    | Spam-classified messages           |
+| Trash   | trash   | Soft-deleted messages              |
+| Archive | archive | Archived threads                   |
+
+System folders cannot be deleted. Custom folders can be created by the user.
+
+---
+
+## Conventions
+
+All tables follow these conventions:
+
+- **IDs**: UUIDv7 via default function. Text primary keys. Timestamp-ordered.
+- **Timestamps**: integer milliseconds.
+- **Soft delete**: every table has deletedAt. Null means active.
+- **JSON columns**: SQLite text with JSON mode. Parsed at read time.
+- **User references**: plain text columns (ownerId, assigneeId, etc.). No foreign keys to external auth tables. The auth adapter resolves identity at runtime.
+
+---
+
+## Applying migrations
+
+The migration SQL strings are exported from the core package. Apply them with whatever tool manages your database.
+
+The schema is designed to be extended. Add columns to existing tables or create new tables for your application. The core schema provides email infrastructure. Your application adds business logic on top.
+
+Foreign keys from your tables to mail tables work normally. Foreign keys from mail tables to your tables are intentionally avoided (the ownerId pattern) to keep the core decoupled.
diff --git a/packages/core/docs/newsletters.md b/packages/core/docs/newsletters.md
new file mode 100644
index 0000000..c201b9c
--- /dev/null
+++ b/packages/core/docs/newsletters.md
@@ -0,0 +1,118 @@
+# Newsletters and Broadcasts
+
+Sending email to audiences. Mailing lists, subscribers, campaigns.
+
+---
+
+## Vocabulary
+
+@rafters/mail uses specific terms:
+
+| Term         | Not this  | Meaning                          |
+| ------------ | --------- | -------------------------------- |
+| Mailing list | Audience  | A named list of subscribers      |
+| Subscriber   | Contact   | Someone on a mailing list        |
+| Campaign     | Broadcast | A message sent to a mailing list |
+
+Vendor terms (audience, contact, broadcast) appear only inside adapter implementations.
+
+---
+
+## Mailing lists
+
+A mailing list is a collection of subscribers who opted in to receive email.
+
+| Field       | Purpose                            |
+| ----------- | ---------------------------------- |
+| name        | Display name ("Weekly Newsletter") |
+| description | What subscribers signed up for     |
+| mailboxId   | Which mailbox sends campaigns      |
+
+Lists are per-mailbox. The support mailbox and the marketing mailbox have separate lists.
+
+---
+
+## Subscribers
+
+| Field          | Purpose                                       |
+| -------------- | --------------------------------------------- |
+| email          | Subscriber email address                      |
+| name           | Display name (optional)                       |
+| status         | subscribed, unsubscribed, bounced, complained |
+| subscribedAt   | When they opted in                            |
+| unsubscribedAt | When they opted out                           |
+| metadata       | Custom fields (JSON)                          |
+
+### Status lifecycle
+
+```
+subscribed -> unsubscribed (user opts out)
+subscribed -> bounced (delivery failure)
+subscribed -> complained (marked as spam)
+```
+
+Once a subscriber is `unsubscribed`, `bounced`, or `complained`, they do not receive future campaigns. Re-subscription requires explicit opt-in.
+
+---
+
+## Campaigns
+
+A campaign is a message sent to all active subscribers on a mailing list.
+
+| Field         | Purpose                                          |
+| ------------- | ------------------------------------------------ |
+| mailingListId | Target list                                      |
+| subject       | Email subject                                    |
+| htmlBody      | HTML content (rendered from template)            |
+| textBody      | Plain text fallback                              |
+| status        | draft, scheduled, sending, sent, failed          |
+| scheduledAt   | When to send (optional, for scheduled campaigns) |
+| sentAt        | When sending completed                           |
+
+### Campaign lifecycle
+
+```
+draft -> scheduled -> sending -> sent
+draft -> sending -> sent
+draft -> sending -> failed
+```
+
+### Sending
+
+Campaigns are sent individually to each subscriber (not BCC). Each send is a separate API call to the email provider. This allows per-recipient tracking (delivery, opens, clicks) and personalization.
+
+Rate limiting is handled by the email provider adapter. The campaign runner respects the provider's concurrency limits.
+
+---
+
+## Templates
+
+Campaign content is typically rendered from a template:
+
+```typescript
+const html = await renderer.render(NewsletterEmail, {
+  title: "Weekly Update",
+  content: markdownContent,
+  unsubscribeUrl: `https://yourdomain.com/unsubscribe?id=${subscriber.id}`,
+});
+```
+
+Every campaign email must include an unsubscribe link. The template adapter handles this requirement.
+
+---
+
+## Analytics
+
+Campaign analytics are derived from webhook events:
+
+| Metric       | Source                                      |
+| ------------ | ------------------------------------------- |
+| Sent         | Total send attempts                         |
+| Delivered    | Delivery confirmations from provider        |
+| Bounced      | Permanent delivery failures                 |
+| Opened       | Open tracking events (if tracking enabled)  |
+| Clicked      | Click tracking events (if tracking enabled) |
+| Unsubscribed | Unsubscribe actions from this campaign      |
+| Complained   | Spam complaints from this campaign          |
+
+Analytics are per-campaign. Aggregate metrics (subscriber growth, engagement rates) are computed from campaign history.
diff --git a/packages/core/docs/reference.md b/packages/core/docs/reference.md
new file mode 100644
index 0000000..9be87c1
--- /dev/null
+++ b/packages/core/docs/reference.md
@@ -0,0 +1,1387 @@
+# @rafters/mail Core Reference
+
+Version: 0.1.0
+Package: `@rafters/mail`
+Runtime: Edge-native (Cloudflare Workers, Deno Deploy, Vercel Edge, any V8 isolate)
+Database: SQLite (D1, Turso, libSQL)
+ORM: Drizzle
+Dependencies: Zero vendor dependencies. All external concerns are adapters.
+
+---
+
+## Table of Contents
+
+1. [Schema Reference](#schema-reference)
+2. [Service Interfaces](#service-interfaces)
+3. [Adapter Interfaces](#adapter-interfaces)
+4. [Threading](#threading)
+5. [Folders](#folders)
+6. [Labels](#labels)
+7. [Assignments](#assignments)
+8. [Notes](#notes)
+9. [Newsletter Tables](#newsletter-tables)
+10. [Zod Schemas and Enums](#zod-schemas-and-enums)
+11. [Migrations](#migrations)
+12. [Design Decisions](#design-decisions)
+
+---
+
+## Schema Reference
+
+10 inbox tables. 3 newsletter tables. All tables follow these conventions:
+
+- **IDs**: UUIDv7 via `$defaultFn`. Primary keys are `text` type.
+- **Timestamps**: `integer` with `mode: 'timestamp_ms'`. Default: `unixepoch('subsecond') * 1000`. Millisecond precision.
+- **Soft delete**: Every table has a `deletedAt` column. Null means active. Populated means soft-deleted.
+- **JSON columns**: SQLite `text` with `mode: 'json'`. Stored as serialized JSON strings, parsed at read time.
+- **User references**: Plain `text` columns (`ownerId`, `assigneeId`, `assignedBy`, `authorId`, `appliedBy`). No foreign key constraints to external auth tables. The AuthAdapter resolves identity at runtime.
+
+---
+
+### mailbox
+
+Email addresses that can send and receive. Each mailbox is either personal (one owner) or shared (team-operated).
+
+| Column           | Type      | Default                        | Nullable | Description                                                                                          |
+| ---------------- | --------- | ------------------------------ | -------- | ---------------------------------------------------------------------------------------------------- |
+| id               | text (PK) | UUIDv7                         | No       | Primary key.                                                                                         |
+| emailAddress     | text      | --                             | No       | The email address. Unique. Column: `email_address`.                                                  |
+| displayName      | text      | --                             | Yes      | Display name for the mailbox. Column: `display_name`.                                                |
+| type             | text      | 'personal'                     | No       | `personal` or `shared`. See `mailboxTypeSchema`.                                                     |
+| ownerId          | text      | --                             | Yes      | User who owns this mailbox. Plain text, no FK. Nullable (shared mailboxes may have no single owner). |
+| organizationId   | text      | --                             | No       | Organization this mailbox belongs to. Plain text, no FK. Required.                                   |
+| isActive         | integer   | 1                              | No       | Whether the mailbox can send/receive.                                                                |
+| autoReplyEnabled | integer   | 0                              | No       | Whether auto-reply is enabled.                                                                       |
+| autoReplySubject | text      | --                             | Yes      | Subject line for auto-reply messages.                                                                |
+| autoReplyBody    | text      | --                             | Yes      | Body content for auto-reply messages.                                                                |
+| forwardToEmail   | text      | --                             | Yes      | Email address to forward incoming messages to.                                                       |
+| forwardEnabled   | integer   | 0                              | No       | Whether forwarding is enabled.                                                                       |
+| signature        | text      | --                             | Yes      | Default email signature for this mailbox.                                                            |
+| description      | text      | --                             | Yes      | Description of the mailbox purpose.                                                                  |
+| icon             | text      | --                             | Yes      | Icon identifier for UI rendering.                                                                    |
+| color            | text      | --                             | Yes      | Hex color for UI rendering.                                                                          |
+| createdAt        | integer   | unixepoch('subsecond') \* 1000 | No       | Creation timestamp in ms.                                                                            |
+| updatedAt        | integer   | unixepoch('subsecond') \* 1000 | No       | Last update timestamp in ms.                                                                         |
+| deletedAt        | integer   | --                             | Yes      | Soft delete timestamp.                                                                               |
+
+**Indexes**: unique on `emailAddress`.
+
+**Notes**: A personal mailbox has one owner. A shared mailbox has one owner (typically an admin) and additional access is granted through the AuthAdapter. The `organizationId` column is required for multi-tenant deployments. The `ownerId` is nullable because shared mailboxes may not have a single owner.
+
+---
+
+### inbox_folder
+
+System and custom folders. Per-mailbox. System folders are created via `FolderService.initSystemFolders()` and cannot be renamed or deleted.
+
+| Column    | Type                    | Default                        | Nullable | Description                                          |
+| --------- | ----------------------- | ------------------------------ | -------- | ---------------------------------------------------- |
+| id        | text (PK)               | UUIDv7                         | No       | Primary key.                                         |
+| mailboxId | text (FK -> mailbox.id) | --                             | No       | Parent mailbox.                                      |
+| name      | text                    | --                             | No       | Display name.                                        |
+| slug      | text                    | --                             | No       | URL-safe identifier. System folders use fixed slugs. |
+| isSystem  | integer                 | 0                              | No       | 1 for system folders, 0 for custom.                  |
+| sortOrder | integer                 | 0                              | No       | Display order. System folders sort first.            |
+| createdAt | integer                 | unixepoch('subsecond') \* 1000 | No       | Creation timestamp in ms.                            |
+| deletedAt | integer                 | --                             | Yes      | Soft delete timestamp.                               |
+
+**Indexes**: unique on `(mailboxId, slug)`.
+
+**System folder slugs**: `inbox`, `sent`, `drafts`, `spam`, `trash`, `archive`. See [Folders](#folders) for details.
+
+---
+
+### inbox_label
+
+Labels for categorizing messages and threads. Three types: system, AI-generated, and user-created. Per-mailbox.
+
+| Column        | Type                    | Default                        | Nullable | Description                                                                |
+| ------------- | ----------------------- | ------------------------------ | -------- | -------------------------------------------------------------------------- |
+| id            | text (PK)               | UUIDv7                         | No       | Primary key.                                                               |
+| mailboxId     | text (FK -> mailbox.id) | --                             | Yes      | Parent mailbox. Nullable for global system labels shared across mailboxes. |
+| name          | text                    | --                             | No       | Display name.                                                              |
+| slug          | text                    | --                             | No       | URL-safe identifier.                                                       |
+| color         | text                    | --                             | Yes      | Hex color for UI rendering.                                                |
+| isSystem      | integer                 | 0                              | No       | 1 for system labels (important, starred, unread).                          |
+| isAiGenerated | integer                 | 0                              | No       | 1 for labels created by the classifier.                                    |
+| createdAt     | integer                 | unixepoch('subsecond') \* 1000 | No       | Creation timestamp in ms.                                                  |
+| deletedAt     | integer                 | --                             | Yes      | Soft delete timestamp.                                                     |
+
+**Indexes**: unique on `(mailboxId, slug)`.
+
+**Notes**: See [Labels](#labels) for the three label types and how they interact with messages and threads.
+
+---
+
+### inbox_thread
+
+Conversation grouping. One thread contains one or more messages. Threads track aggregate state: latest snippet, all participants, current folder, status, and priority.
+
+| Column        | Type                         | Default                        | Nullable | Description                                                            |
+| ------------- | ---------------------------- | ------------------------------ | -------- | ---------------------------------------------------------------------- |
+| id            | text (PK)                    | UUIDv7                         | No       | Primary key.                                                           |
+| mailboxId     | text (FK -> mailbox.id)      | --                             | No       | Parent mailbox.                                                        |
+| folderId      | text (FK -> inbox_folder.id) | --                             | Yes      | Current folder. Nullable (onDelete: "set null").                       |
+| subject       | text                         | --                             | No       | Thread subject. Set from the first message.                            |
+| snippet       | text                         | --                             | Yes      | Preview text. First 200 chars of the latest message's plain text body. |
+| participants  | text (JSON)                  | '[]'                           | No       | JSON array of email addresses that have participated.                  |
+| messageCount  | integer                      | 0                              | No       | Total messages in the thread.                                          |
+| unreadCount   | integer                      | 0                              | No       | Number of unread messages in the thread.                               |
+| status        | text                         | 'open'                         | No       | `open`, `pending`, `resolved`, `closed`. See `threadStatusSchema`.     |
+| priority      | text                         | 'normal'                       | No       | `low`, `normal`, `high`, `urgent`. See `threadPrioritySchema`.         |
+| lastMessageAt | integer                      | --                             | No       | Timestamp of the most recent message. Used for sort. Required.         |
+| startedAt     | integer                      | --                             | No       | Timestamp when the thread was created/started.                         |
+| updatedAt     | integer                      | unixepoch('subsecond') \* 1000 | No       | Last update timestamp in ms.                                           |
+| archivedAt    | integer                      | --                             | Yes      | Timestamp when the thread was archived.                                |
+| deletedAt     | integer                      | --                             | Yes      | Soft delete timestamp.                                                 |
+
+**Indexes**: on `(mailboxId, folderId)`, on `(mailboxId, status)`, on `lastMessageAt`.
+
+---
+
+### inbox_message
+
+Individual email messages. Stores RFC 5322 header data, envelope information, AI classification fields, and blob storage keys pointing to the raw email and parsed bodies.
+
+| Column          | Type                         | Default | Nullable | Description                                                                          |
+| --------------- | ---------------------------- | ------- | -------- | ------------------------------------------------------------------------------------ |
+| id              | text (PK)                    | UUIDv7  | No       | Primary key.                                                                         |
+| threadId        | text (FK -> inbox_thread.id) | --      | No       | Parent thread.                                                                       |
+| mailboxId       | text (FK -> mailbox.id)      | --      | No       | Parent mailbox.                                                                      |
+| messageId       | text                         | --      | No       | RFC 5322 Message-ID header value. Format: `<uuidv7@domain>` for outbound.            |
+| inReplyTo       | text                         | --      | Yes      | RFC 5322 In-Reply-To header. References the parent message's Message-ID.             |
+| references      | text                         | --      | Yes      | RFC 5322 References header. Space-separated list of Message-IDs in the thread chain. |
+| fromEmail       | text                         | --      | No       | Sender email address.                                                                |
+| fromName        | text                         | --      | Yes      | Sender display name.                                                                 |
+| toEmail         | text                         | --      | No       | Primary recipient email address.                                                     |
+| toName          | text                         | --      | Yes      | Primary recipient display name.                                                      |
+| replyToEmail    | text                         | --      | Yes      | Reply-To email address (if different from fromEmail).                                |
+| ccEmails        | text (JSON)                  | '[]'    | No       | JSON array of CC recipient email addresses.                                          |
+| bccEmails       | text (JSON)                  | '[]'    | No       | JSON array of BCC recipient email addresses.                                         |
+| subject         | text                         | --      | No       | Message subject line.                                                                |
+| blobKeyRaw      | text                         | --      | No       | Blob storage key for the raw .eml file. Required.                                    |
+| blobKeyHtml     | text                         | --      | Yes      | Blob storage key for the parsed HTML body.                                           |
+| blobKeyText     | text                         | --      | Yes      | Blob storage key for the parsed plain text body.                                     |
+| isOutbound      | integer                      | 0       | No       | Whether this is an outbound message. 0 = inbound, 1 = outbound.                      |
+| isRead          | integer                      | 0       | No       | Read status.                                                                         |
+| isStarred       | integer                      | 0       | No       | Star status.                                                                         |
+| aiCategory      | text                         | --      | Yes      | AI-assigned category. See `aiCategorySchema`.                                        |
+| aiConfidence    | integer                      | --      | Yes      | AI classification confidence score. 0-100.                                           |
+| aiSummary       | text                         | --      | Yes      | AI-generated summary of the message content.                                         |
+| isSpam          | integer                      | 0       | No       | Whether the message is classified as spam.                                           |
+| spamScore       | integer                      | --      | Yes      | Spam score from classifier. 0-100.                                                   |
+| sizeBytes       | integer                      | --      | Yes      | Total size of the message in bytes.                                                  |
+| attachmentCount | integer                      | 0       | No       | Number of attachments on the message.                                                |
+| sentAt          | integer                      | --      | Yes      | When the message was sent (from Date header or send time).                           |
+| receivedAt      | integer                      | --      | Yes      | When the message was received by the system.                                         |
+| deletedAt       | integer                      | --      | Yes      | Soft delete timestamp.                                                               |
+
+**Indexes**: unique on `messageId`, on `(threadId)`, on `(mailboxId, receivedAt)`, on `fromEmail`, on `receivedAt`, on `aiCategory`.
+
+**Notes**: This table has no `createdAt` or `updatedAt` columns. Temporal data is tracked via `receivedAt`, `sentAt`, and `deletedAt`. Content is blob-only: the `bodyPlainText` and `bodyHtml` inline columns do not exist. All message content is stored in blob storage and referenced by `blobKeyRaw` (required), `blobKeyHtml`, and `blobKeyText`.
+
+**Blob storage pattern**: Raw email is the source of truth. D1 stores parsed metadata for fast queries. If metadata is wrong, re-derive from the raw email in blob storage. Key format: `emails/{year}/{month}/{sha256-first-16-chars}.{eml|html|txt}` (month is zero-padded).
+
+---
+
+### inbox_message_label
+
+Join table. Many-to-many between messages and labels. Tracks who or what applied the label.
+
+| Column    | Type                          | Default                        | Nullable | Description                                                |
+| --------- | ----------------------------- | ------------------------------ | -------- | ---------------------------------------------------------- |
+| id        | text (PK)                     | UUIDv7                         | No       | Primary key.                                               |
+| messageId | text (FK -> inbox_message.id) | --                             | No       | The message.                                               |
+| labelId   | text (FK -> inbox_label.id)   | --                             | No       | The label.                                                 |
+| appliedBy | text                          | --                             | Yes      | User ID of who applied the label. Null means system or AI. |
+| appliedAt | integer                       | unixepoch('subsecond') \* 1000 | No       | When the label was applied.                                |
+
+**Indexes**: unique on `(messageId, labelId)`.
+
+---
+
+### inbox_thread_label
+
+Join table. Many-to-many between threads and labels. Used for thread-level filtering and organization.
+
+| Column    | Type                         | Default                        | Nullable | Description                                                |
+| --------- | ---------------------------- | ------------------------------ | -------- | ---------------------------------------------------------- |
+| id        | text (PK)                    | UUIDv7                         | No       | Primary key.                                               |
+| threadId  | text (FK -> inbox_thread.id) | --                             | No       | The thread.                                                |
+| labelId   | text (FK -> inbox_label.id)  | --                             | No       | The label.                                                 |
+| appliedBy | text                         | --                             | Yes      | User ID of who applied the label. Null means system or AI. |
+| appliedAt | integer                      | unixepoch('subsecond') \* 1000 | No       | When the label was applied.                                |
+
+**Indexes**: unique on `(threadId, labelId)`.
+
+---
+
+### inbox_attachment
+
+Attachment metadata. Actual content lives in blob storage. Supports both inline attachments (referenced by Content-ID in HTML body) and regular file attachments.
+
+| Column      | Type                          | Default                        | Nullable | Description                                                        |
+| ----------- | ----------------------------- | ------------------------------ | -------- | ------------------------------------------------------------------ |
+| id          | text (PK)                     | UUIDv7                         | No       | Primary key.                                                       |
+| messageId   | text (FK -> inbox_message.id) | --                             | No       | Parent message.                                                    |
+| filename    | text                          | --                             | Yes      | Original filename.                                                 |
+| contentType | text                          | --                             | No       | MIME type (e.g., `application/pdf`, `image/png`).                  |
+| sizeBytes   | integer                       | --                             | No       | File size in bytes.                                                |
+| blobKey     | text                          | --                             | No       | Blob storage key for the attachment content.                       |
+| contentId   | text                          | --                             | Yes      | Content-ID for inline attachments. Used in HTML `cid:` references. |
+| isInline    | integer                       | 0                              | No       | 1 if this is an inline attachment (embedded in HTML body).         |
+| createdAt   | integer                       | unixepoch('subsecond') \* 1000 | No       | Creation timestamp in ms.                                          |
+| deletedAt   | integer                       | --                             | Yes      | Soft delete timestamp.                                             |
+
+**Indexes**: on `messageId`, on `contentId`.
+
+---
+
+### thread_assignment
+
+Thread-level assignment for shared mailbox collaboration. One active assignment per thread at a time. See [Assignments](#assignments).
+
+| Column      | Type                         | Default                        | Nullable | Description                                                     |
+| ----------- | ---------------------------- | ------------------------------ | -------- | --------------------------------------------------------------- |
+| id          | text (PK)                    | UUIDv7                         | No       | Primary key.                                                    |
+| threadId    | text (FK -> inbox_thread.id) | --                             | No       | The thread being assigned.                                      |
+| assigneeId  | text                         | --                             | No       | User ID of the assignee. Plain text, no FK.                     |
+| assignedBy  | text                         | --                             | Yes      | User ID of who made the assignment. Null for system assignment. |
+| status      | text                         | 'active'                       | No       | `active`, `completed`, `reassigned`.                            |
+| note        | text                         | --                             | Yes      | Optional note about the assignment.                             |
+| assignedAt  | integer                      | unixepoch('subsecond') \* 1000 | No       | When the assignment was created.                                |
+| completedAt | integer                      | --                             | Yes      | When the assignment was completed.                              |
+| deletedAt   | integer                      | --                             | Yes      | Soft delete timestamp. Used for audit trail.                    |
+
+**Indexes**: on `(threadId, status)`, on `assigneeId`.
+
+**Constraint**: Only one row with `status = 'active'` per `threadId` at any time. Enforced at the service layer, not the database.
+
+---
+
+### thread_note
+
+Internal notes on threads. Markdown content. Not visible to external parties. Used for team collaboration on shared mailbox threads.
+
+| Column    | Type                         | Default                        | Nullable | Description                                    |
+| --------- | ---------------------------- | ------------------------------ | -------- | ---------------------------------------------- |
+| id        | text (PK)                    | UUIDv7                         | No       | Primary key.                                   |
+| threadId  | text (FK -> inbox_thread.id) | --                             | No       | Parent thread.                                 |
+| authorId  | text                         | --                             | No       | User ID of the note author. Plain text, no FK. |
+| content   | text                         | --                             | No       | Note body. Markdown.                           |
+| createdAt | integer                      | unixepoch('subsecond') \* 1000 | No       | Creation timestamp in ms.                      |
+| updatedAt | integer                      | unixepoch('subsecond') \* 1000 | No       | Last update timestamp in ms.                   |
+| deletedAt | integer                      | --                             | Yes      | Soft delete timestamp.                         |
+
+**Indexes**: on `threadId`.
+
+---
+
+## Service Interfaces
+
+All service interfaces are defined in `@rafters/mail`. Implementations receive a Drizzle database instance and any required adapters via constructor or factory function.
+
+---
+
+### InboxEmailService
+
+Outbound email operations from the inbox. Handles composing new emails and replying within existing threads.
+
+```typescript
+interface InboxEmailService {
+  replyToThread(params: ReplyToThreadParams): Promise<{ messageId: string }>;
+  composeEmail(params: ComposeEmailParams): Promise<{ threadId: string; messageId: string }>;
+}
+```
+
+#### replyToThread
+
+Send a reply within an existing thread.
+
+| Parameter        | Type     | Required | Description             |
+| ---------------- | -------- | -------- | ----------------------- |
+| params.threadId  | string   | Yes      | Thread to reply to.     |
+| params.senderId  | string   | Yes      | User ID of the sender.  |
+| params.bodyHtml  | string   | Yes      | HTML body of the reply. |
+| params.body      | string   | No       | Plain text alternative. |
+| params.ccEmails  | string[] | No       | CC recipients.          |
+| params.bccEmails | string[] | No       | BCC recipients.         |
+
+**Returns**: `{ messageId: string }` -- the ID of the newly created message.
+
+**Behavior**:
+
+1. Looks up the thread and its latest message.
+2. Generates a new Message-ID via `generateMessageId()`.
+3. Sets `In-Reply-To` to the latest message's Message-ID.
+4. Builds the `References` header by appending `In-Reply-To` to the existing chain.
+5. Sends via the EmailProvider adapter.
+6. Stores the outbound message in `inbox_message` with `isOutbound = true`.
+7. Moves the thread to the `sent` folder context and updates `lastMessageAt`, `snippet`, and `messageCount`.
+
+#### composeEmail
+
+Create a new thread with an outbound message.
+
+| Parameter        | Type     | Required | Description              |
+| ---------------- | -------- | -------- | ------------------------ |
+| params.mailboxId | string   | Yes      | Sending mailbox.         |
+| params.to        | string   | Yes      | Recipient email address. |
+| params.subject   | string   | Yes      | Subject line.            |
+| params.body      | string   | Yes      | HTML body.               |
+| params.plainText | string   | No       | Plain text alternative.  |
+| params.ccEmails  | string[] | No       | CC recipients.           |
+| params.bccEmails | string[] | No       | BCC recipients.          |
+
+**Returns**: `{ threadId: string; messageId: string }`.
+
+**Behavior**:
+
+1. Creates a new `inbox_thread` with the subject and initial participants.
+2. Creates a new `inbox_message` with `isOutbound = true` and a generated Message-ID.
+3. Sends via the EmailProvider adapter.
+4. Places the thread in the `sent` folder.
+
+---
+
+### ThreadService
+
+Thread management: retrieval, folder movement, status updates, and bulk operations.
+
+```typescript
+interface ThreadService {
+  getThread(threadId: string): Promise<Thread | undefined>;
+  listThreads(mailboxId: string, folderId?: string): Promise<Thread[]>;
+  moveToFolder(threadId: string, folderId: string): Promise<void>;
+  updateStatus(threadId: string, status: ThreadStatus): Promise<void>;
+  updatePriority(threadId: string, priority: ThreadPriority): Promise<void>;
+  archive(threadId: string): Promise<void>;
+  trash(threadId: string): Promise<void>;
+}
+```
+
+#### getThread
+
+Retrieve a single thread with its messages.
+
+| Parameter | Type   | Required | Description         |
+| --------- | ------ | -------- | ------------------- |
+| threadId  | string | Yes      | Thread to retrieve. |
+
+**Returns**: `Thread | undefined` -- thread record with nested messages, labels, and assignment. Returns `undefined` if the thread does not exist or is soft-deleted.
+
+#### listThreads
+
+List threads in a mailbox, optionally filtered by folder.
+
+| Parameter | Type   | Required | Description                                                   |
+| --------- | ------ | -------- | ------------------------------------------------------------- |
+| mailboxId | string | Yes      | Mailbox to list threads from.                                 |
+| folderId  | string | No       | Filter to a specific folder. If omitted, returns all threads. |
+
+**Returns**: `Thread[]` -- ordered by `lastMessageAt` descending.
+
+#### moveToFolder
+
+Move a thread to a different folder.
+
+| Parameter | Type   | Required | Description     |
+| --------- | ------ | -------- | --------------- |
+| threadId  | string | Yes      | Thread to move. |
+| folderId  | string | Yes      | Target folder.  |
+
+**Behavior**: Updates `inbox_thread.folderId`. Validates the target folder exists and belongs to the same mailbox.
+
+#### updateStatus
+
+Set the thread's workflow status.
+
+| Parameter | Type         | Required | Description                                          |
+| --------- | ------------ | -------- | ---------------------------------------------------- |
+| threadId  | string       | Yes      | Thread to update.                                    |
+| status    | ThreadStatus | Yes      | New status: `open`, `pending`, `resolved`, `closed`. |
+
+#### updatePriority
+
+Set the thread's priority level.
+
+| Parameter | Type           | Required | Description                                      |
+| --------- | -------------- | -------- | ------------------------------------------------ |
+| threadId  | string         | Yes      | Thread to update.                                |
+| priority  | ThreadPriority | Yes      | New priority: `low`, `normal`, `high`, `urgent`. |
+
+#### archive
+
+Move a thread to the archive folder.
+
+| Parameter | Type   | Required | Description        |
+| --------- | ------ | -------- | ------------------ |
+| threadId  | string | Yes      | Thread to archive. |
+
+**Behavior**: Finds the `archive` system folder for the thread's mailbox and updates `folderId`. Equivalent to `moveToFolder(threadId, archiveFolderId)`.
+
+#### trash
+
+Move a thread to the trash folder.
+
+| Parameter | Type   | Required | Description      |
+| --------- | ------ | -------- | ---------------- |
+| threadId  | string | Yes      | Thread to trash. |
+
+**Behavior**: Finds the `trash` system folder for the thread's mailbox and updates `folderId`. Trash auto-purge (30 days) is an app-level concern, not implemented in core.
+
+---
+
+### FolderService
+
+Folder CRUD and system folder initialization.
+
+```typescript
+interface FolderService {
+  createFolder(mailboxId: string, name: string): Promise<Folder>;
+  listFolders(mailboxId: string): Promise<Folder[]>;
+  deleteFolder(folderId: string): Promise<void>;
+  initSystemFolders(mailboxId: string): Promise<void>;
+}
+```
+
+#### createFolder
+
+Create a custom folder.
+
+| Parameter | Type   | Required | Description          |
+| --------- | ------ | -------- | -------------------- |
+| mailboxId | string | Yes      | Parent mailbox.      |
+| name      | string | Yes      | Folder display name. |
+
+**Returns**: `Folder` -- the created folder. Slug is derived from the name.
+
+**Behavior**: Sets `isSystem = 0`. Validates the slug does not collide with system folder slugs.
+
+#### listFolders
+
+List all folders for a mailbox.
+
+| Parameter | Type   | Required | Description     |
+| --------- | ------ | -------- | --------------- |
+| mailboxId | string | Yes      | Parent mailbox. |
+
+**Returns**: `Folder[]` -- ordered by `sortOrder`. System folders first, then custom folders.
+
+#### deleteFolder
+
+Soft-delete a custom folder.
+
+| Parameter | Type   | Required | Description       |
+| --------- | ------ | -------- | ----------------- |
+| folderId  | string | Yes      | Folder to delete. |
+
+**Throws**: If the folder is a system folder (`isSystem = 1`). System folders cannot be deleted.
+
+**Behavior**: Sets `deletedAt`. Threads in the deleted folder should be moved by the app (core does not auto-relocate).
+
+#### initSystemFolders
+
+Create the six system folders for a mailbox. Idempotent.
+
+| Parameter | Type   | Required | Description            |
+| --------- | ------ | -------- | ---------------------- |
+| mailboxId | string | Yes      | Mailbox to initialize. |
+
+**Behavior**: Creates `inbox`, `sent`, `drafts`, `spam`, `trash`, `archive` folders with `isSystem = 1`. Skips any that already exist. Should be called when a mailbox is created.
+
+---
+
+### LabelService
+
+Label CRUD and application to messages and threads.
+
+```typescript
+interface LabelService {
+  createLabel(mailboxId: string, name: string): Promise<Label>;
+  listLabels(mailboxId: string): Promise<Label[]>;
+  applyToMessage(messageId: string, labelId: string, appliedBy?: string): Promise<void>;
+  applyToThread(threadId: string, labelId: string, appliedBy?: string): Promise<void>;
+  removeFromMessage(messageId: string, labelId: string): Promise<void>;
+  removeFromThread(threadId: string, labelId: string): Promise<void>;
+}
+```
+
+#### createLabel
+
+Create a user-defined label.
+
+| Parameter | Type   | Required | Description         |
+| --------- | ------ | -------- | ------------------- |
+| mailboxId | string | Yes      | Parent mailbox.     |
+| name      | string | Yes      | Label display name. |
+
+**Returns**: `Label` -- the created label with `isSystem = 0`, `isAiGenerated = 0`.
+
+#### listLabels
+
+List all labels for a mailbox.
+
+| Parameter | Type   | Required | Description     |
+| --------- | ------ | -------- | --------------- |
+| mailboxId | string | Yes      | Parent mailbox. |
+
+**Returns**: `Label[]` -- all label types (system, AI, user).
+
+#### applyToMessage
+
+Apply a label to a message.
+
+| Parameter | Type   | Required | Description                                  |
+| --------- | ------ | -------- | -------------------------------------------- |
+| messageId | string | Yes      | Target message.                              |
+| labelId   | string | Yes      | Label to apply.                              |
+| appliedBy | string | No       | User ID. Null means system or AI applied it. |
+
+**Behavior**: Inserts into `inbox_message_label`. No-op if the label is already applied.
+
+#### applyToThread
+
+Apply a label to a thread.
+
+| Parameter | Type   | Required | Description                                  |
+| --------- | ------ | -------- | -------------------------------------------- |
+| threadId  | string | Yes      | Target thread.                               |
+| labelId   | string | Yes      | Label to apply.                              |
+| appliedBy | string | No       | User ID. Null means system or AI applied it. |
+
+**Behavior**: Inserts into `inbox_thread_label`. No-op if the label is already applied.
+
+#### removeFromMessage
+
+Remove a label from a message.
+
+| Parameter | Type   | Required | Description      |
+| --------- | ------ | -------- | ---------------- |
+| messageId | string | Yes      | Target message.  |
+| labelId   | string | Yes      | Label to remove. |
+
+**Behavior**: Deletes the row from `inbox_message_label`.
+
+#### removeFromThread
+
+Remove a label from a thread.
+
+| Parameter | Type   | Required | Description      |
+| --------- | ------ | -------- | ---------------- |
+| threadId  | string | Yes      | Target thread.   |
+| labelId   | string | Yes      | Label to remove. |
+
+**Behavior**: Deletes the row from `inbox_thread_label`.
+
+---
+
+### AssignmentService
+
+Thread assignment for shared mailbox collaboration. See [Assignments](#assignments).
+
+```typescript
+interface AssignmentService {
+  assign(threadId: string, assigneeId: string, assignedBy?: string): Promise<void>;
+  reassign(threadId: string, newAssigneeId: string, assignedBy?: string): Promise<void>;
+  complete(threadId: string): Promise<void>;
+  getActiveAssignment(threadId: string): Promise<Assignment | null>;
+}
+```
+
+#### assign
+
+Assign a thread to a user.
+
+| Parameter  | Type   | Required | Description                         |
+| ---------- | ------ | -------- | ----------------------------------- |
+| threadId   | string | Yes      | Thread to assign.                   |
+| assigneeId | string | Yes      | User ID of the assignee.            |
+| assignedBy | string | No       | User ID of who made the assignment. |
+
+**Throws**: If the thread already has an active assignment. Use `reassign` instead.
+
+**Behavior**: Creates a `thread_assignment` row with `status = 'active'`.
+
+#### reassign
+
+Reassign a thread to a different user.
+
+| Parameter     | Type   | Required | Description                                |
+| ------------- | ------ | -------- | ------------------------------------------ |
+| threadId      | string | Yes      | Thread to reassign.                        |
+| newAssigneeId | string | Yes      | User ID of the new assignee.               |
+| assignedBy    | string | No       | User ID of who initiated the reassignment. |
+
+**Behavior**: Sets the current active assignment's status to `reassigned` and soft-deletes it. Creates a new `thread_assignment` row with `status = 'active'` for the new assignee. The old assignment is preserved for audit.
+
+#### complete
+
+Mark the active assignment as completed.
+
+| Parameter | Type   | Required | Description                          |
+| --------- | ------ | -------- | ------------------------------------ |
+| threadId  | string | Yes      | Thread whose assignment to complete. |
+
+**Behavior**: Sets `status = 'completed'` on the active assignment. Does not soft-delete. A completed assignment is a terminal state.
+
+#### getActiveAssignment
+
+Get the current active assignment for a thread.
+
+| Parameter | Type   | Required | Description      |
+| --------- | ------ | -------- | ---------------- |
+| threadId  | string | Yes      | Thread to query. |
+
+**Returns**: `Assignment | null`. Null if no active assignment exists.
+
+---
+
+### NoteService
+
+Internal notes on threads. See [Notes](#notes).
+
+```typescript
+interface NoteService {
+  addNote(threadId: string, authorId: string, content: string): Promise<Note>;
+  listNotes(threadId: string): Promise<Note[]>;
+  deleteNote(noteId: string): Promise<void>;
+}
+```
+
+#### addNote
+
+Add an internal note to a thread.
+
+| Parameter | Type   | Required | Description                 |
+| --------- | ------ | -------- | --------------------------- |
+| threadId  | string | Yes      | Parent thread.              |
+| authorId  | string | Yes      | User ID of the note author. |
+| content   | string | Yes      | Markdown content.           |
+
+**Returns**: `Note` -- the created note.
+
+#### listNotes
+
+List all notes on a thread.
+
+| Parameter | Type   | Required | Description    |
+| --------- | ------ | -------- | -------------- |
+| threadId  | string | Yes      | Parent thread. |
+
+**Returns**: `Note[]` -- ordered by `createdAt` ascending. Excludes soft-deleted notes.
+
+#### deleteNote
+
+Soft-delete a note.
+
+| Parameter | Type   | Required | Description     |
+| --------- | ------ | -------- | --------------- |
+| noteId    | string | Yes      | Note to delete. |
+
+**Behavior**: Sets `deletedAt`. The note is preserved for audit trail but excluded from `listNotes` results.
+
+---
+
+## Adapter Interfaces
+
+Adapters are contracts that the consuming app must implement (or use a provided adapter package). The core package defines the interfaces as Zod schemas with inferred TypeScript types. The core has zero dependency on any adapter implementation.
+
+---
+
+### AuthAdapter
+
+Resolves user identity and access control. The app provides the implementation. No default implementation is shipped.
+
+```typescript
+const inboxUserSchema = z.object({
+  id: z.string(),
+  email: z.string().email(),
+  name: z.string().optional(),
+});
+
+const inboxRoleSchema = z.enum(["owner", "admin", "agent", "viewer"]);
+
+type InboxUser = z.infer<typeof inboxUserSchema>;
+type InboxRole = z.infer<typeof inboxRoleSchema>;
+
+interface AuthAdapter {
+  getCurrentUser(): Promise<InboxUser>;
+  getUserById(id: string): Promise<InboxUser | null>;
+  hasMailboxAccess(userId: string, mailboxId: string): Promise<boolean>;
+  getUserRole(userId: string, mailboxId: string): Promise<InboxRole | null>;
+}
+```
+
+#### getCurrentUser
+
+Return the authenticated user for the current request.
+
+**Returns**: `InboxUser`.
+
+**Notes**: How authentication works is entirely the app's concern. This could read from a session cookie, JWT, or any other mechanism.
+
+#### getUserById
+
+Look up a user by ID.
+
+| Parameter | Type   | Required | Description |
+| --------- | ------ | -------- | ----------- |
+| id        | string | Yes      | User ID.    |
+
+**Returns**: `InboxUser | null`. Null if the user does not exist.
+
+#### hasMailboxAccess
+
+Check whether a user has any level of access to a mailbox.
+
+| Parameter | Type   | Required | Description               |
+| --------- | ------ | -------- | ------------------------- |
+| userId    | string | Yes      | User to check.            |
+| mailboxId | string | Yes      | Mailbox to check against. |
+
+**Returns**: `boolean`.
+
+#### getUserRole
+
+Get the user's role for a specific mailbox.
+
+| Parameter | Type   | Required | Description               |
+| --------- | ------ | -------- | ------------------------- |
+| userId    | string | Yes      | User to check.            |
+| mailboxId | string | Yes      | Mailbox to check against. |
+
+**Returns**: `InboxRole | null`. Null if the user has no role (no access).
+
+**Roles**:
+
+- `owner`: Full control. Can delete the mailbox.
+- `admin`: Manage folders, labels, assignments. Cannot delete the mailbox.
+- `agent`: Can read, reply, assign, add notes. Cannot manage folders or labels.
+- `viewer`: Read-only access.
+
+---
+
+### InboundAdapter
+
+Receives email from an external source, parses it, stores it, and creates/updates the thread.
+
+```typescript
+const inboundEmailSchema = z.object({
+  raw: z.instanceof(ArrayBuffer),
+  from: z.string().email(),
+  to: z.string().email(),
+  headers: z.record(z.string()),
+});
+
+type InboundEmail = z.infer<typeof inboundEmailSchema>;
+
+interface InboundAdapter {
+  handleIncoming(email: InboundEmail): Promise<{ messageId: string; threadId: string }>;
+}
+```
+
+#### handleIncoming
+
+Process an inbound email.
+
+| Parameter     | Type                   | Required | Description                                                                                     |
+| ------------- | ---------------------- | -------- | ----------------------------------------------------------------------------------------------- |
+| email.raw     | ArrayBuffer            | Yes      | Raw RFC 5322 email bytes.                                                                       |
+| email.from    | string                 | Yes      | Sender email address (from envelope).                                                           |
+| email.to      | string                 | Yes      | Recipient email address (from envelope).                                                        |
+| email.headers | Record<string, string> | Yes      | Parsed headers. Must include Message-ID. Should include In-Reply-To, References, Subject, Date. |
+
+**Returns**: `{ messageId: string; threadId: string }`.
+
+**Behavior**:
+
+1. Store raw `.eml` in blob storage.
+2. Parse and store HTML and plain text bodies separately in blob storage.
+3. Insert metadata into `inbox_message`.
+4. Match to an existing thread via In-Reply-To/References headers. Create a new thread if no match.
+5. Update thread's `snippet`, `lastMessageAt`, `messageCount`, `participants`.
+6. Dispatch to classification queue/workflow.
+
+**Implementations**: `@rafters/mail-cloudflare` (Cloudflare Email Routing + R2).
+
+---
+
+### EmailProvider (OutboundAdapter)
+
+Sends email via an external provider. Also manages mailing lists, subscribers, and campaigns for newsletter functionality.
+
+```typescript
+const emailParamsSchema = z.object({
+  to: z.string().email(),
+  subject: z.string().min(1),
+  html: z.string().optional(),
+  text: z.string().optional(),
+  from: z.string().email().optional(),
+  replyTo: z.string().email().optional(),
+});
+
+type EmailParams = z.infer<typeof emailParamsSchema>;
+
+interface EmailProvider {
+  // Transactional
+  sendEmail(params: EmailParams): Promise<{ id: string }>;
+
+  // Mailing lists
+  createMailingList(name: string): Promise<MailingList>;
+  getMailingList(id: string): Promise<MailingList>;
+  deleteMailingList(id: string): Promise<void>;
+
+  // Subscribers
+  addSubscriber(listId: string, email: string, data?: SubscriberData): Promise<Subscriber>;
+  removeSubscriber(listId: string, subscriberId: string): Promise<void>;
+  updateSubscriber(subscriberId: string, updates: SubscriberUpdates): Promise<Subscriber>;
+  listSubscribers(listId: string): Promise<Subscriber[]>;
+
+  // Campaigns
+  sendCampaign(params: CampaignParams): Promise<{ id: string }>;
+  getCampaign(id: string): Promise<{ id: string; subject: string; sentAt: Date }>;
+  createCampaignDraft(params: CampaignParams): Promise<{ id: string }>;
+  sendCampaignDraft(campaignId: string): Promise<{ id: string }>;
+  getCampaignStatus(campaignId: string): Promise<CampaignStatus>;
+
+  // Audiences
+  listAudiences(): Promise<Audience[]>;
+}
+```
+
+#### sendEmail
+
+Send a single transactional email.
+
+| Parameter      | Type   | Required | Description                               |
+| -------------- | ------ | -------- | ----------------------------------------- |
+| params.to      | string | Yes      | Recipient.                                |
+| params.subject | string | Yes      | Subject line.                             |
+| params.html    | string | No       | HTML body.                                |
+| params.text    | string | No       | Plain text body.                          |
+| params.from    | string | No       | Sender override. Uses default if omitted. |
+| params.replyTo | string | No       | Reply-To address.                         |
+
+**Returns**: `{ id: string }` -- provider-assigned message ID.
+
+#### Mailing list methods
+
+`createMailingList`, `getMailingList`, `deleteMailingList` manage platform-wide mailing lists. These map to the `platform_audience` table and the provider's concept of audiences/lists.
+
+#### Subscriber methods
+
+`addSubscriber`, `removeSubscriber`, `updateSubscriber`, `listSubscribers` manage individual subscriptions. These map to `platform_subscriber` and the provider's subscriber/contact records.
+
+#### Campaign methods
+
+`sendCampaign` sends immediately. `createCampaignDraft` + `sendCampaignDraft` supports a two-step draft-then-send flow. `getCampaign` and `getCampaignStatus` retrieve campaign state and delivery status.
+
+**Vocabulary mapping**: The core uses platform vocabulary (MailingList, Subscriber, Campaign). Adapter implementations translate to vendor vocabulary at the boundary. Example: Resend uses Audience, Contact, Broadcast.
+
+**Implementations**: `@rafters/mail-resend` (Resend API via fetch).
+
+---
+
+### TemplateRenderer
+
+Renders email templates to HTML and optional plain text.
+
+```typescript
+interface TemplateRenderer {
+  render(
+    template: string,
+    props: Record<string, unknown>,
+  ): Promise<{ html: string; text?: string }>;
+}
+```
+
+#### render
+
+| Parameter | Type                    | Required | Description                                       |
+| --------- | ----------------------- | -------- | ------------------------------------------------- |
+| template  | string                  | Yes      | Template identifier (e.g., `'otp'`, `'welcome'`). |
+| props     | Record<string, unknown> | Yes      | Template data. Shape depends on the template.     |
+
+**Returns**: `{ html: string; text?: string }`. The `text` field is optional; not all renderers produce a plain text version.
+
+**Implementations**: `@rafters/mail-react-email` (React Email).
+
+---
+
+### EmailClassifier
+
+Classifies email content into categories with confidence scores and auto-generated tags.
+
+```typescript
+const emailClassificationSchema = z.object({
+  category: z.enum([
+    "support",
+    "feedback",
+    "abuse",
+    "partnership",
+    "spam",
+    "billing",
+    "legal",
+    "other",
+  ]),
+  confidence: z.number().min(0).max(100),
+  tags: z.array(z.string()),
+  priority: z.enum(["low", "normal", "high", "urgent"]),
+});
+
+type EmailClassification = z.infer<typeof emailClassificationSchema>;
+
+interface EmailClassifier {
+  classify(from: string, subject: string, body: string): Promise<EmailClassification>;
+}
+```
+
+#### classify
+
+| Parameter | Type   | Required | Description                                                   |
+| --------- | ------ | -------- | ------------------------------------------------------------- |
+| from      | string | Yes      | Sender email address.                                         |
+| subject   | string | Yes      | Message subject.                                              |
+| body      | string | Yes      | Plain text body (truncated to classifier's max input length). |
+
+**Returns**: `EmailClassification`.
+
+**Category-to-priority defaults**:
+
+- `abuse`, `legal`: always `high`.
+- `support`, `billing`: default `normal`.
+- `feedback`, `partnership`: default `normal`.
+- `other`: default `low`.
+- Keyword overrides can escalate to `urgent` or `high` regardless of category.
+
+**Helper function**:
+
+```typescript
+function isLegitimateCategory(category: EmailCategory): boolean;
+```
+
+Returns `true` for all categories except `spam`. Used by the inbound flow to decide whether a message stays in the inbox or moves to the spam folder.
+
+**Implementations**: `@rafters/mail-workers-ai` (Cloudflare Workers AI, DeBERTa-v3 zero-shot).
+
+---
+
+### BlobStorage
+
+Stores and retrieves raw email content, parsed bodies, and attachments.
+
+```typescript
+interface BlobObject {
+  text(): Promise<string>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  httpMetadata?: Record<string, string>;
+  customMetadata?: Record<string, string>;
+}
+
+interface BlobStorage {
+  put(key: string, content: string | ArrayBuffer, options?: BlobPutOptions): Promise<void>;
+
+  get(key: string, options?: BlobGetOptions): Promise<BlobObject | null>;
+
+  delete(key: string): Promise<void>;
+
+  generateKey(contentHash: string, extension: string): string;
+}
+```
+
+#### put
+
+Store content at a key.
+
+| Parameter | Type                  | Required | Description                  |
+| --------- | --------------------- | -------- | ---------------------------- |
+| key       | string                | Yes      | Storage key.                 |
+| content   | string or ArrayBuffer | Yes      | Content to store.            |
+| options   | BlobPutOptions        | No       | Metadata, content type, etc. |
+
+#### get
+
+Retrieve content by key.
+
+| Parameter | Type           | Required | Description       |
+| --------- | -------------- | -------- | ----------------- |
+| key       | string         | Yes      | Storage key.      |
+| options   | BlobGetOptions | No       | Range reads, etc. |
+
+**Returns**: `BlobObject | null`. Null if the key does not exist.
+
+#### delete
+
+Remove content by key.
+
+| Parameter | Type   | Required | Description  |
+| --------- | ------ | -------- | ------------ |
+| key       | string | Yes      | Storage key. |
+
+#### generateKey
+
+Generate a storage key from a content hash and file extension.
+
+| Parameter   | Type   | Required | Description                                        |
+| ----------- | ------ | -------- | -------------------------------------------------- |
+| contentHash | string | Yes      | SHA-256 hash of the content (first 16 chars used). |
+| extension   | string | Yes      | File extension: `eml`, `html`, `txt`.              |
+
+**Returns**: `string`. Format: `emails/{year}/{month}/{hash}.{extension}` (month is zero-padded, e.g. `01` not `1`).
+
+**Implementations**: `@rafters/mail-cloudflare` (Cloudflare R2). Community can add S3, GCS, etc.
+
+---
+
+## Threading
+
+RFC 5322 compliant. Gmail-style conversation grouping.
+
+### Message-ID Generation
+
+```typescript
+function generateMessageId(domain: string): string;
+```
+
+Returns: `<{uuidv7}@{domain}>`. Example: `<01912345-6789-7abc-def0-123456789abc@example.com>`.
+
+UUIDv7 guarantees uniqueness and provides natural time-ordering. The domain portion identifies the originating system.
+
+### References Chain
+
+```typescript
+function buildReferences(existingReferences: string | null, inReplyTo: string | null): string;
+```
+
+Appends the `In-Reply-To` value to the existing `References` chain. If `existingReferences` is null, the result is just the `In-Reply-To` value. If both are null, returns an empty string.
+
+**Example chain for a 4-message thread**:
+
+```
+Message 1: Message-ID: <A@ex.com>
+Message 2: Message-ID: <B@ex.com>, In-Reply-To: <A@ex.com>, References: <A@ex.com>
+Message 3: Message-ID: <C@ex.com>, In-Reply-To: <B@ex.com>, References: <A@ex.com> <B@ex.com>
+Message 4: Message-ID: <D@ex.com>, In-Reply-To: <C@ex.com>, References: <A@ex.com> <B@ex.com> <C@ex.com>
+```
+
+### Inbound Thread Matching
+
+When a new inbound message arrives:
+
+1. **Check In-Reply-To**: Look up `inbox_message` where `messageId = incomingMessage.inReplyTo`. If found, use that message's `threadId`.
+2. **Check References**: If In-Reply-To match fails, iterate the `References` header (newest to oldest) and look for any matching `inbox_message.messageId`. If found, use that message's `threadId`.
+3. **New thread**: If no match on either header, create a new `inbox_thread`.
+
+### Snippet Generation
+
+Thread snippet is the first 200 characters of the latest message's plain text body. Updated on every new message (inbound or outbound).
+
+---
+
+## Folders
+
+### System Folders
+
+Created by `FolderService.initSystemFolders()`. Cannot be renamed or deleted.
+
+| Slug      | Name    | Purpose                                                                 |
+| --------- | ------- | ----------------------------------------------------------------------- |
+| `inbox`   | Inbox   | Default landing folder for inbound email.                               |
+| `sent`    | Sent    | Outbound emails.                                                        |
+| `drafts`  | Drafts  | Unsent drafts.                                                          |
+| `spam`    | Spam    | AI-classified or manually flagged spam.                                 |
+| `trash`   | Trash   | Soft-deleted threads. Auto-purge after 30 days is an app-level concern. |
+| `archive` | Archive | Archived conversations.                                                 |
+
+### Custom Folders
+
+Created via `FolderService.createFolder()`. `isSystem = 0`. Can be renamed and deleted. Slug is derived from the name.
+
+### Folder Scope
+
+Folders are per-mailbox. Each mailbox has its own complete set of system and custom folders. There are no global or cross-mailbox folders.
+
+### Thread-Folder Relationship
+
+A thread exists in exactly one folder at a time (`inbox_thread.folderId`). Moving a thread moves it entirely. Individual messages do not have their own folder assignment.
+
+---
+
+## Labels
+
+### Three Label Types
+
+**System labels**: Created during mailbox initialization. `isSystem = 1`. Cannot be renamed or deleted.
+
+| Slug        | Purpose                                 |
+| ----------- | --------------------------------------- |
+| `important` | High-importance flag.                   |
+| `starred`   | User-starred for quick access.          |
+| `unread`    | Tracks unread state at the label level. |
+
+**AI-generated labels**: Created by the EmailClassifier. `isAiGenerated = 1`. Based on regex tag patterns applied during classification. Examples: `bug-report`, `feature-request`, `billing`, `account`.
+
+**User-created labels**: Created via `LabelService.createLabel()`. `isSystem = 0`, `isAiGenerated = 0`. Custom tags for organization.
+
+### Label Application
+
+Labels can be applied to both messages (via `inbox_message_label`) and threads (via `inbox_thread_label`). Both junction tables track:
+
+- **Who applied it**: `appliedBy` column. Null means system or AI.
+- **When**: `appliedAt` column.
+
+A label can be applied to a message, a thread, or both independently. Message-level labels are for granular classification. Thread-level labels are for filtering and views.
+
+### Label Uniqueness
+
+The `(mailboxId, slug)` pair is unique. Two labels in different mailboxes can have the same slug. Within a mailbox, each label slug is unique.
+
+---
+
+## Assignments
+
+Thread-level assignment for shared mailbox collaboration.
+
+### Rules
+
+- A thread can have at most one active assignment at a time.
+- The active assignment has `status = 'active'`.
+- `assign()` fails if an active assignment already exists. Use `reassign()` to change assignees.
+- `reassign()` sets the old assignment to `status = 'reassigned'`, soft-deletes it, and creates a new active assignment.
+- `complete()` sets `status = 'completed'`. This is a terminal state. The assignment row is not soft-deleted.
+- Assignment history is preserved via soft delete on reassignment. Completed assignments remain as active records. This provides a full audit trail.
+
+### Status Values
+
+| Status       | Meaning                                                    |
+| ------------ | ---------------------------------------------------------- |
+| `active`     | Currently assigned and in progress.                        |
+| `completed`  | Work finished. Terminal state.                             |
+| `reassigned` | Was active, then reassigned to someone else. Soft-deleted. |
+
+### Workflow Integration
+
+When an agent replies to a thread, the app should update the thread status from `open` to `pending` (awaiting customer response). This is an app-level convention, not enforced by core.
+
+---
+
+## Notes
+
+Internal notes on threads. Not visible to external parties. Markdown content.
+
+### Purpose
+
+Team collaboration on shared mailbox threads. Agents can leave context for each other: escalation reasons, customer history, resolution steps.
+
+### Behavior
+
+- Notes belong to a thread (`threadId`).
+- Notes have an author (`authorId`). Plain text user ID, no FK.
+- Content is Markdown.
+- `listNotes()` returns notes ordered by `createdAt` ascending. Excludes soft-deleted notes.
+- `deleteNote()` soft-deletes. The note is preserved for audit but hidden from the list.
+
+---
+
+## Newsletter Tables
+
+Three tables for outbound newsletter/broadcast functionality. Separate from the inbox schema but share the same database and the EmailProvider adapter.
+
+### platform_audience
+
+Platform-wide mailing lists.
+
+| Column         | Type      | Default                        | Nullable | Description                                            |
+| -------------- | --------- | ------------------------------ | -------- | ------------------------------------------------------ |
+| id             | text (PK) | UUIDv7                         | No       | Primary key.                                           |
+| name           | text      | --                             | No       | Audience name (e.g., "Newsletter", "Product Updates"). |
+| providerListId | text      | --                             | Yes      | External ID from the email provider.                   |
+| createdAt      | integer   | unixepoch('subsecond') \* 1000 | No       | Creation timestamp in ms.                              |
+| updatedAt      | integer   | unixepoch('subsecond') \* 1000 | No       | Last update timestamp in ms.                           |
+| deletedAt      | integer   | --                             | Yes      | Soft delete timestamp.                                 |
+
+### platform_subscriber
+
+User subscriptions to platform audiences.
+
+| Column               | Type                              | Default                        | Nullable | Description                          |
+| -------------------- | --------------------------------- | ------------------------------ | -------- | ------------------------------------ |
+| id                   | text (PK)                         | UUIDv7                         | No       | Primary key.                         |
+| audienceId           | text (FK -> platform_audience.id) | --                             | No       | Parent audience.                     |
+| userId               | text                              | --                             | No       | User ID. Plain text, no FK.          |
+| providerSubscriberId | text                              | --                             | Yes      | External ID from the email provider. |
+| createdAt            | integer                           | unixepoch('subsecond') \* 1000 | No       | Creation timestamp in ms.            |
+| deletedAt            | integer                           | --                             | Yes      | Soft delete timestamp.               |
+
+**Indexes**: unique on `(audienceId, userId)`.
+
+### broadcast_audit
+
+Compliance trail for sent broadcasts.
+
+| Column             | Type                              | Default                        | Nullable | Description                             |
+| ------------------ | --------------------------------- | ------------------------------ | -------- | --------------------------------------- |
+| id                 | text (PK)                         | UUIDv7                         | No       | Primary key.                            |
+| audienceId         | text (FK -> platform_audience.id) | --                             | No       | Target audience.                        |
+| subject            | text                              | --                             | No       | Broadcast subject line.                 |
+| sentBy             | text                              | --                             | No       | User ID of who triggered the send.      |
+| recipientCount     | integer                           | --                             | No       | Number of recipients at send time.      |
+| providerCampaignId | text                              | --                             | Yes      | External campaign ID from the provider. |
+| sentAt             | integer                           | --                             | No       | Send timestamp in ms.                   |
+| createdAt          | integer                           | unixepoch('subsecond') \* 1000 | No       | Row creation timestamp in ms.           |
+
+### Design Principle
+
+The email provider is the source of truth for subscriber data. These tables store:
+
+- Which audiences exist (registry).
+- Which users subscribe to which audiences (mapping).
+- Provider identifiers for sync.
+- Minimal audit trail for compliance.
+
+These tables do NOT store subscriber email addresses, unsubscribe status, or campaign content. The provider owns that data.
+
+---
+
+## Zod Schemas and Enums
+
+Every table has three Zod schemas: insert, select, update. Types are always inferred via `z.infer<>`, never written as TypeScript interfaces first.
+
+### Enum Schemas
+
+```typescript
+const mailboxTypeSchema = z.enum(["personal", "shared"]);
+type MailboxType = z.infer<typeof mailboxTypeSchema>;
+
+const threadStatusSchema = z.enum(["open", "pending", "resolved", "closed"]);
+type ThreadStatus = z.infer<typeof threadStatusSchema>;
+
+const threadPrioritySchema = z.enum(["low", "normal", "high", "urgent"]);
+type ThreadPriority = z.infer<typeof threadPrioritySchema>;
+
+const aiCategorySchema = z.enum([
+  "support",
+  "feedback",
+  "abuse",
+  "partnership",
+  "spam",
+  "billing",
+  "legal",
+  "other",
+]);
+type AiCategory = z.infer<typeof aiCategorySchema>;
+
+const systemFolderSchema = z.enum(["inbox", "sent", "drafts", "spam", "trash", "archive"]);
+type SystemFolder = z.infer<typeof systemFolderSchema>;
+```
+
+### Schema Pattern
+
+For each table (example: `inbox_thread`):
+
+```typescript
+// Insert: required fields for creating a record
+const insertInboxThreadSchema = z.object({
+  mailboxId: z.string().uuid(),
+  folderId: z.string().uuid(),
+  subject: z.string().min(1),
+  // ... other required fields
+});
+
+// Select: full record shape as returned from the database
+const selectInboxThreadSchema = z.object({
+  id: z.string().uuid(),
+  mailboxId: z.string().uuid(),
+  folderId: z.string().uuid(),
+  subject: z.string(),
+  snippet: z.string().nullable(),
+  participants: z.array(z.string()),
+  messageCount: z.number(),
+  status: threadStatusSchema,
+  priority: threadPrioritySchema,
+  lastMessageAt: z.number(),
+  unreadCount: z.number(),
+  startedAt: z.number(),
+  updatedAt: z.number(),
+  archivedAt: z.number().nullable(),
+  deletedAt: z.number().nullable(),
+});
+
+// Update: all fields optional except id
+const updateInboxThreadSchema = z.object({
+  folderId: z.string().uuid().optional(),
+  subject: z.string().min(1).optional(),
+  snippet: z.string().optional(),
+  // ... other updatable fields
+});
+
+// Inferred types
+type InsertInboxThread = z.infer<typeof insertInboxThreadSchema>;
+type SelectInboxThread = z.infer<typeof selectInboxThreadSchema>;
+type UpdateInboxThread = z.infer<typeof updateInboxThreadSchema>;
+```
+
+### Exports
+
+All schemas and inferred types are exported from the package. Apps use them for:
+
+- Runtime validation at API boundaries.
+- Type inference for service method parameters and return types.
+- Mock data generation with Zocker.
+
+---
+
+## Migrations
+
+The package exports raw SQL strings for table creation. It never runs migrations itself. Apps own their migration workflow.
+
+```typescript
+import { migrationSQL } from "@rafters/mail/migrations";
+```
+
+### Usage with Wrangler (D1)
+
+1. `wrangler d1 migrations create add-mail-tables`
+2. Copy `migrationSQL` into the generated `.sql` file.
+3. `wrangler d1 migrations apply`
+
+### Upgrade Migrations
+
+When the package adds columns or tables in a new version, apps must generate new migration files with the appropriate `ALTER TABLE` or `CREATE TABLE` statements. The package exports the full current schema SQL, not diffs between versions.
+
+---
+
+## Design Decisions
+
+### Why UUIDv7
+
+UUIDv7 encodes a Unix timestamp in the high bits. IDs are naturally time-ordered, which means:
+
+- B-tree indexes on ID columns are insert-optimized (new rows append, no page splits).
+- IDs double as coarse timestamps for ordering.
+- No coordination required for ID generation (no auto-increment, no sequence table).
+
+### Why integer timestamps in milliseconds
+
+SQLite has no native datetime type. Storing millisecond timestamps as integers avoids timezone ambiguity, string parsing overhead, and SQLite's inconsistent date function behavior. The `unixepoch('subsecond') * 1000` default generates values server-side.
+
+### Why soft delete everywhere
+
+Audit trail. Email systems need to answer "what happened and when." Hard deletes destroy evidence. Soft deletes preserve history while keeping it out of default queries. The `deletedAt IS NULL` filter is the convention for all read operations.
+
+### Why plain text user IDs with no FK
+
+The mail schema is designed to work with any auth system. Foreign keys to a `user` table would create a hard dependency on a specific auth schema. Plain text user IDs let the AuthAdapter resolve identity at runtime. Trade-off: no referential integrity at the database level. Accepted because the AuthAdapter enforces validity at the application level.
+
+### Why JSON columns
+
+SQLite stores JSON as text. Drizzle's `mode: 'json'` handles serialization/deserialization transparently. For `participants`, `ccEmails`, and `bccEmails`, the alternative would be separate junction tables. JSON columns are simpler for read-heavy workloads where the data is always loaded with the parent row. Trade-off: no indexed lookups on individual array elements. Accepted because these fields are displayed, not queried.
+
+### Why no barrel files
+
+Edge runtimes have bundle size constraints (Cloudflare Workers: 1MB compressed). Barrel exports (`index.ts` re-exporting everything) pull the entire module graph into every consumer. Subpath exports in `package.json` let consumers import exactly what they need. Example: `import { threadStatusSchema } from '@rafters/mail/schemas'` loads only the schemas, not the Drizzle tables or service interfaces.
+
+### Why Zod is source of truth
+
+Types inferred from Zod schemas via `z.infer<>` guarantee that runtime validation and compile-time types are always in sync. Writing TypeScript interfaces first and then duplicating the shape in Zod is a maintenance burden and a bug vector. Zod-first means one definition, two outputs (types + validation). This also enables mock data generation with Zocker for testing.
diff --git a/packages/core/docs/threading.md b/packages/core/docs/threading.md
new file mode 100644
index 0000000..1ff65cc
--- /dev/null
+++ b/packages/core/docs/threading.md
@@ -0,0 +1,83 @@
+# Threading
+
+How @rafters/mail builds and maintains email threads.
+
+---
+
+## How threads work
+
+Every email carries headers that identify its place in a conversation:
+
+- **Message-ID**: a globally unique identifier assigned when the email is sent
+- **In-Reply-To**: the Message-ID of the email being replied to
+- **References**: the full chain of Message-IDs in the conversation, oldest to newest
+
+When a new message arrives, the threading engine uses these headers to find or create a thread:
+
+1. Check `In-Reply-To` -- if it matches an existing message, join that thread
+2. Check `References` -- walk the chain looking for any known message
+3. Fall back to subject matching within the same mailbox (configurable)
+4. If no match, create a new thread
+
+---
+
+## Thread model
+
+A thread is a container for related messages:
+
+| Field         | Purpose                              |
+| ------------- | ------------------------------------ |
+| subject       | The conversation subject             |
+| snippet       | Preview of the most recent message   |
+| participants  | All email addresses involved         |
+| messageCount  | Total messages in the thread         |
+| unreadCount   | Messages not yet marked as read      |
+| status        | open, pending, resolved, closed      |
+| priority      | low, normal, high, urgent            |
+| folderId      | Current folder (nullable)            |
+| lastMessageAt | Timestamp of the most recent message |
+
+Threads track their own read state via `unreadCount` rather than a single boolean. A thread with 10 messages where 3 are unread shows `unreadCount: 3`.
+
+---
+
+## Building references
+
+When composing a reply, the system builds the References header by appending the In-Reply-To to the existing chain:
+
+```
+Original:     Message-ID: <A>
+First reply:  In-Reply-To: <A>, References: <A>
+Second reply: In-Reply-To: <B>, References: <A> <B>
+Third reply:  In-Reply-To: <C>, References: <A> <B> <C>
+```
+
+The chain is capped at 50 entries to prevent unbounded growth. When the cap is reached, the oldest references are dropped but the most recent are kept.
+
+---
+
+## Message-ID generation
+
+Outbound messages use UUIDv7 for Message-ID generation:
+
+```
+<019d5a9d-b939-77a3-8b8c-4e170fc35b76@yourdomain.com>
+```
+
+UUIDv7 is timestamp-ordered, which means Message-IDs naturally sort by creation time. This property is used by the IMAP UID mapping to derive UIDs from message ordering.
+
+---
+
+## Thread assignment
+
+Messages are assigned to threads at ingest time. The assignment is permanent -- a message belongs to one thread for its lifetime. If the threading engine cannot find a match, it creates a new single-message thread.
+
+Moving a thread between folders moves all its messages. Deleting a thread soft-deletes all its messages.
+
+---
+
+## Cross-mailbox threading
+
+Threads are scoped to a mailbox. A conversation between `support@yourdomain.com` and a customer lives in the support mailbox's thread. The same customer emailing `sales@yourdomain.com` starts a separate thread in the sales mailbox.
+
+This is intentional: different mailboxes serve different purposes. Cross-mailbox thread merging is not supported because it would break folder isolation and access control.
diff --git a/packages/core/package.json b/packages/core/package.json
index 5d67392..df0185b 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -2,8 +2,10 @@
   "name": "@rafters/mail",
   "version": "0.0.1",
   "description": "Email inbox framework for the edge. Schema, types, service interfaces, threading logic.",
+  "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "type": "module",
   "exports": {
diff --git a/packages/imap-cloudflare/README.md b/packages/imap-cloudflare/README.md
new file mode 100644
index 0000000..f3accf4
--- /dev/null
+++ b/packages/imap-cloudflare/README.md
@@ -0,0 +1,68 @@
+# @rafters/mail-imap-cloudflare
+
+Cloudflare Durable Object runtime for [`@rafters/mail-imap`](https://www.npmjs.com/package/@rafters/mail-imap). One Durable Object per mailbox, WebSocket transport, hibernation for IDLE, and an inbound-signal bridge so new mail wakes idle clients with an EXISTS notification.
+
+Near-zero idle cost: when no clients are connected, the DO hibernates. When a client holds IDLE, the DO stays warm only long enough to serve the connection and then hibernates again until new mail arrives or the client disconnects.
+
+## Install
+
+```bash
+pnpm add @rafters/mail-imap-cloudflare @rafters/mail-imap @rafters/mail
+```
+
+## Usage
+
+```typescript
+// src/worker.ts
+import { createImapDurableObject, createImapWorker } from "@rafters/mail-imap-cloudflare";
+import { createAuthAdapter } from "./adapters/auth.ts";
+import { createMailboxAdapter } from "./adapters/mailbox.ts";
+import { createMessageAdapter } from "./adapters/message.ts";
+
+// The DO class. Export the return value from your worker entry.
+export const ImapMailboxDO = createImapDurableObject({
+  createAdapters(env) {
+    return {
+      authAdapter: createAuthAdapter(env.DB),
+      mailboxAdapter: createMailboxAdapter(env.DB),
+      messageAdapter: createMessageAdapter(env.DB, env.BLOB_STORAGE),
+    };
+  },
+});
+
+// The worker entry that routes WebSocket upgrades to the correct DO
+// (one DO per email address).
+export default createImapWorker();
+```
+
+```jsonc
+// wrangler.jsonc
+{
+  "name": "mail-imap",
+  "compatibility_date": "2025-04-01",
+  "durable_objects": {
+    "bindings": [{ "name": "IMAP_MAILBOX", "class_name": "ImapMailboxDO" }],
+  },
+  "migrations": [{ "tag": "v1", "new_classes": ["ImapMailboxDO"] }],
+  "d1_databases": [{ "binding": "DB", "database_name": "mail", "database_id": "..." }],
+  "r2_buckets": [{ "binding": "BLOB_STORAGE", "bucket_name": "mail-blobs" }],
+}
+```
+
+Clients connect with `wss://imap.example.com/?email=user@example.com&mailboxId=mbx-123`. Standard email clients do not speak IMAP-over-WebSocket natively; this runtime is designed for web clients and custom bridges. For native TCP on port 993, use [`@rafters/mail-imap-server`](https://www.npmjs.com/package/@rafters/mail-imap-server).
+
+## Inbound signaling
+
+The DO exposes a `POST /notify?count=N` endpoint that your inbound email Worker calls after storing a new message. IDLE clients receive an EXISTS notification on the next tick.
+
+## Documentation
+
+Per-package docs ship in the `docs/` directory and on npm:
+
+- [`deployment.md`](./docs/deployment.md) -- Deployment guide covering Cloudflare Workers + Durable Objects setup, bindings, cost model, and monitoring
+
+See the [monorepo README](https://github.com/rafters-studio/mail#readme) for the complete IMAP architecture.
+
+## License
+
+MIT
diff --git a/packages/imap-cloudflare/docs/deployment.md b/packages/imap-cloudflare/docs/deployment.md
new file mode 100644
index 0000000..23bbc43
--- /dev/null
+++ b/packages/imap-cloudflare/docs/deployment.md
@@ -0,0 +1,237 @@
+# IMAP Deployment Guide
+
+Deploy `@rafters/mail-imap-server` on your platform of choice. Each guide assumes you have the server code written per the quickstart.
+
+---
+
+## Fly.io
+
+Best option for most deployments. $5-15/mo. TLS handled automatically.
+
+### Dockerfile
+
+```dockerfile
+FROM node:24-alpine
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile --prod
+COPY . .
+CMD ["node", "--import", "tsx", "src/main.ts"]
+```
+
+### fly.toml
+
+```toml
+app = "mail-imap"
+primary_region = "sjc"
+
+[build]
+
+[[services]]
+  internal_port = 1993
+  protocol = "tcp"
+
+  [[services.ports]]
+    port = 993
+    handlers = ["tls"]
+
+  [[services.tcp_checks]]
+    grace_period = "10s"
+    interval = "30s"
+    timeout = "5s"
+```
+
+### Deploy
+
+```bash
+fly launch --no-deploy
+fly secrets set DB_URL="libsql://your-db.turso.io" DB_TOKEN="your-token"
+fly certs add mail.yourdomain.com
+fly deploy
+```
+
+### DNS
+
+```
+mail.yourdomain.com  CNAME  mail-imap.fly.dev
+```
+
+### Health check
+
+Fly's TCP check verifies the server accepts connections. The IMAP greeting confirms the protocol is working.
+
+---
+
+## Railway
+
+Similar to Fly. TLS termination via Railway's proxy.
+
+### railway.json
+
+```json
+{
+  "build": { "builder": "DOCKERFILE" },
+  "deploy": {
+    "startCommand": "node --import tsx src/main.ts",
+    "healthcheckPath": null
+  }
+}
+```
+
+### Settings
+
+- Custom domain: `mail.yourdomain.com`
+- TCP proxy: enable, external port 993, internal port 1993
+- Railway provisions TLS automatically for custom domains
+
+### Secrets
+
+Set `DB_URL`, `DB_TOKEN`, and any auth secrets via Railway dashboard or CLI.
+
+---
+
+## AWS Fargate
+
+For teams already on AWS. ~$15-30/mo.
+
+### Architecture
+
+```
+Internet -> NLB (port 993, TLS via ACM) -> Fargate task (port 1993, plain TCP)
+```
+
+### Key resources
+
+- **NLB** (Network Load Balancer): TCP passthrough on port 993
+- **ACM certificate**: for `mail.yourdomain.com`
+- **ECS Service**: runs the container
+- **Security Group**: allow inbound 993 from 0.0.0.0/0
+
+### Task definition (simplified)
+
+```json
+{
+  "containerDefinitions": [
+    {
+      "name": "mail-imap",
+      "image": "your-ecr-repo/mail-imap:latest",
+      "portMappings": [{ "containerPort": 1993, "protocol": "tcp" }],
+      "environment": [{ "name": "PORT", "value": "1993" }],
+      "secrets": [
+        { "name": "DB_URL", "valueFrom": "arn:aws:ssm:..." },
+        { "name": "DB_TOKEN", "valueFrom": "arn:aws:ssm:..." }
+      ]
+    }
+  ]
+}
+```
+
+### NLB listener
+
+- Protocol: TLS
+- Port: 993
+- Certificate: ACM cert for `mail.yourdomain.com`
+- Target group: Fargate tasks on port 1993 (TCP)
+
+### DNS
+
+```
+mail.yourdomain.com  CNAME  your-nlb-dns.elb.amazonaws.com
+```
+
+---
+
+## Docker / VPS
+
+Direct deployment. You manage TLS.
+
+### With Let's Encrypt (certbot)
+
+```bash
+certbot certonly --standalone -d mail.yourdomain.com
+```
+
+### Server config
+
+```typescript
+import { readFileSync } from "node:fs";
+
+const server = createImapServer({
+  port: 993,
+  tls: {
+    cert: readFileSync("/etc/letsencrypt/live/mail.yourdomain.com/fullchain.pem"),
+    key: readFileSync("/etc/letsencrypt/live/mail.yourdomain.com/privkey.pem"),
+  },
+  // ... adapters
+});
+```
+
+### docker-compose.yml
+
+```yaml
+services:
+  imap:
+    build: .
+    ports:
+      - "993:993"
+    volumes:
+      - /etc/letsencrypt:/etc/letsencrypt:ro
+    environment:
+      - DB_URL=libsql://your-db.turso.io
+      - DB_TOKEN=your-token
+    restart: unless-stopped
+```
+
+### Certificate renewal
+
+```bash
+# Cron job: renew cert and restart container
+0 3 * * * certbot renew --quiet && docker compose restart imap
+```
+
+---
+
+## Not supported
+
+### Vercel
+
+Vercel Functions are stateless request/response. No persistent TCP connections. Cannot host IMAP.
+
+### Deno Deploy
+
+Deno Deploy is request/response. No TCP listeners. Use Deno in a Docker container instead.
+
+### Cloudflare Containers
+
+HTTP-only sidecars. No TCP port exposure. Cannot host IMAP.
+
+### Cloudflare (native TCP/993)
+
+Requires Spectrum (Enterprise plan, ~$5k/mo). Use the Cloudflare DO runtime (`@rafters/mail-imap-cloudflare`) with WebSocket transport instead, or deploy `@rafters/mail-imap-server` on Fly.
+
+---
+
+## Multi-domain
+
+One deployment serves all your domains. The `resolveMailboxId` callback maps email addresses to mailbox IDs:
+
+```typescript
+async resolveMailboxId(email) {
+  const domain = email.split("@")[1];
+  // Look up mailbox by email in your database
+  const mailbox = await db.query.mailbox.findFirst({
+    where: eq(mailbox.emailAddress, email),
+  });
+  return mailbox?.id;
+}
+```
+
+DNS: point each domain's mail subdomain at the same server.
+
+```
+mail.silvius.me       CNAME  mail-imap.fly.dev
+mail.runlegion.dev    CNAME  mail-imap.fly.dev
+mail.gitpress.app     CNAME  mail-imap.fly.dev
+```
+
+Apple Mail: configure each account with its domain's mail hostname. All resolve to the same server. The server routes by email address after LOGIN.
diff --git a/packages/imap-cloudflare/package.json b/packages/imap-cloudflare/package.json
index 7c85406..96a6e20 100644
--- a/packages/imap-cloudflare/package.json
+++ b/packages/imap-cloudflare/package.json
@@ -2,8 +2,10 @@
   "name": "@rafters/mail-imap-cloudflare",
   "version": "0.0.1",
   "description": "Cloudflare Durable Object runtime adapter for @rafters/mail-imap",
+  "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "type": "module",
   "exports": {
diff --git a/packages/imap-server/README.md b/packages/imap-server/README.md
new file mode 100644
index 0000000..f608ef4
--- /dev/null
+++ b/packages/imap-server/README.md
@@ -0,0 +1,91 @@
+# @rafters/mail-imap-server
+
+Node TCP/TLS runtime for [`@rafters/mail-imap`](https://www.npmjs.com/package/@rafters/mail-imap). Listens on port 993 (IMAPS). One TCP connection per IMAP session. Deploys anywhere Node runs: Fly, Railway, AWS Fargate, DigitalOcean, Docker, VPS.
+
+Standard email clients (Apple Mail, Thunderbird, Outlook, K-9) connect directly over TLS, no local proxy.
+
+## Install
+
+```bash
+pnpm add @rafters/mail-imap-server @rafters/mail-imap @rafters/mail
+```
+
+## Usage
+
+### TLS-terminated at the server
+
+```typescript
+import { createImapServer } from "@rafters/mail-imap-server";
+import { readFileSync } from "node:fs";
+import { createAuthAdapter, createMailboxAdapter, createMessageAdapter } from "./adapters.ts";
+
+const server = createImapServer({
+  adapters: {
+    authAdapter: createAuthAdapter(),
+    mailboxAdapter: createMailboxAdapter(),
+    messageAdapter: createMessageAdapter(),
+  },
+  tls: {
+    cert: readFileSync("/etc/letsencrypt/live/imap.example.com/fullchain.pem"),
+    key: readFileSync("/etc/letsencrypt/live/imap.example.com/privkey.pem"),
+  },
+  host: "0.0.0.0",
+  port: 993,
+  async resolveMailboxId(email) {
+    return lookupMailboxIdByEmail(email);
+  },
+});
+
+await server.listen();
+```
+
+### TLS-terminating proxy mode (Fly, Railway, ALB)
+
+On platforms that terminate TLS at the edge and forward plain TCP to your app, omit the `tls` config:
+
+```typescript
+const server = createImapServer({
+  adapters: {
+    /* ... */
+  },
+  // No tls field -- plain TCP mode.
+  host: "0.0.0.0",
+  port: Number(process.env.PORT ?? 993),
+  async resolveMailboxId(email) {
+    /* ... */
+  },
+});
+
+await server.listen();
+```
+
+The proxy handles TLS on 993 with its own certificate and forwards plain TCP to the server's internal port.
+
+## Configuration
+
+| Option             | Default       | Description                                                           |
+| ------------------ | ------------- | --------------------------------------------------------------------- |
+| `adapters`         | required      | `authAdapter`, `mailboxAdapter`, `messageAdapter`, `extensionAdapter` |
+| `resolveMailboxId` | required      | Function mapping authenticated email to mailbox ID                    |
+| `tls`              | optional      | `{ cert, key }`. Omit for plain TCP behind a TLS proxy                |
+| `host`             | `0.0.0.0`     | Bind address                                                          |
+| `port`             | `993`         | Listen port                                                           |
+| `maxConnections`   | `1000`        | Concurrent connection cap. Excess get `BYE Server too busy`           |
+| `sessionTimeoutMs` | `30 * 60_000` | Idle session timeout before `BYE Session timeout`                     |
+
+## Deployment
+
+The server is a long-lived Node process. It cannot run on serverless-function runtimes that do not support persistent TCP connections (Vercel, Deno Deploy). For those, deploy the Node server in Docker on a platform that does (Fly, Railway, Fargate, VPS).
+
+## Documentation
+
+Per-package docs ship in the `docs/` directory and on npm:
+
+- [`quickstart.md`](./docs/quickstart.md) -- Zero-to-running IMAP server in a few minutes with a working adapter stub
+- [`deployment.md`](./docs/deployment.md) -- Platform-by-platform deployment (Fly, Railway, Fargate, Docker, VPS) with TLS certificate handling
+
+See the [monorepo README](https://github.com/rafters-studio/mail#readme) for the IMAP architecture overview.
+
+## License
+
+MIT
diff --git a/packages/imap-server/docs/deployment.md b/packages/imap-server/docs/deployment.md
new file mode 100644
index 0000000..23bbc43
--- /dev/null
+++ b/packages/imap-server/docs/deployment.md
@@ -0,0 +1,237 @@
+# IMAP Deployment Guide
+
+Deploy `@rafters/mail-imap-server` on your platform of choice. Each guide assumes you have the server code written per the quickstart.
+
+---
+
+## Fly.io
+
+Best option for most deployments. $5-15/mo. TLS handled automatically.
+
+### Dockerfile
+
+```dockerfile
+FROM node:24-alpine
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile --prod
+COPY . .
+CMD ["node", "--import", "tsx", "src/main.ts"]
+```
+
+### fly.toml
+
+```toml
+app = "mail-imap"
+primary_region = "sjc"
+
+[build]
+
+[[services]]
+  internal_port = 1993
+  protocol = "tcp"
+
+  [[services.ports]]
+    port = 993
+    handlers = ["tls"]
+
+  [[services.tcp_checks]]
+    grace_period = "10s"
+    interval = "30s"
+    timeout = "5s"
+```
+
+### Deploy
+
+```bash
+fly launch --no-deploy
+fly secrets set DB_URL="libsql://your-db.turso.io" DB_TOKEN="your-token"
+fly certs add mail.yourdomain.com
+fly deploy
+```
+
+### DNS
+
+```
+mail.yourdomain.com  CNAME  mail-imap.fly.dev
+```
+
+### Health check
+
+Fly's TCP check verifies the server accepts connections. The IMAP greeting confirms the protocol is working.
+
+---
+
+## Railway
+
+Similar to Fly. TLS termination via Railway's proxy.
+
+### railway.json
+
+```json
+{
+  "build": { "builder": "DOCKERFILE" },
+  "deploy": {
+    "startCommand": "node --import tsx src/main.ts",
+    "healthcheckPath": null
+  }
+}
+```
+
+### Settings
+
+- Custom domain: `mail.yourdomain.com`
+- TCP proxy: enable, external port 993, internal port 1993
+- Railway provisions TLS automatically for custom domains
+
+### Secrets
+
+Set `DB_URL`, `DB_TOKEN`, and any auth secrets via Railway dashboard or CLI.
+
+---
+
+## AWS Fargate
+
+For teams already on AWS. ~$15-30/mo.
+
+### Architecture
+
+```
+Internet -> NLB (port 993, TLS via ACM) -> Fargate task (port 1993, plain TCP)
+```
+
+### Key resources
+
+- **NLB** (Network Load Balancer): TCP passthrough on port 993
+- **ACM certificate**: for `mail.yourdomain.com`
+- **ECS Service**: runs the container
+- **Security Group**: allow inbound 993 from 0.0.0.0/0
+
+### Task definition (simplified)
+
+```json
+{
+  "containerDefinitions": [
+    {
+      "name": "mail-imap",
+      "image": "your-ecr-repo/mail-imap:latest",
+      "portMappings": [{ "containerPort": 1993, "protocol": "tcp" }],
+      "environment": [{ "name": "PORT", "value": "1993" }],
+      "secrets": [
+        { "name": "DB_URL", "valueFrom": "arn:aws:ssm:..." },
+        { "name": "DB_TOKEN", "valueFrom": "arn:aws:ssm:..." }
+      ]
+    }
+  ]
+}
+```
+
+### NLB listener
+
+- Protocol: TLS
+- Port: 993
+- Certificate: ACM cert for `mail.yourdomain.com`
+- Target group: Fargate tasks on port 1993 (TCP)
+
+### DNS
+
+```
+mail.yourdomain.com  CNAME  your-nlb-dns.elb.amazonaws.com
+```
+
+---
+
+## Docker / VPS
+
+Direct deployment. You manage TLS.
+
+### With Let's Encrypt (certbot)
+
+```bash
+certbot certonly --standalone -d mail.yourdomain.com
+```
+
+### Server config
+
+```typescript
+import { readFileSync } from "node:fs";
+
+const server = createImapServer({
+  port: 993,
+  tls: {
+    cert: readFileSync("/etc/letsencrypt/live/mail.yourdomain.com/fullchain.pem"),
+    key: readFileSync("/etc/letsencrypt/live/mail.yourdomain.com/privkey.pem"),
+  },
+  // ... adapters
+});
+```
+
+### docker-compose.yml
+
+```yaml
+services:
+  imap:
+    build: .
+    ports:
+      - "993:993"
+    volumes:
+      - /etc/letsencrypt:/etc/letsencrypt:ro
+    environment:
+      - DB_URL=libsql://your-db.turso.io
+      - DB_TOKEN=your-token
+    restart: unless-stopped
+```
+
+### Certificate renewal
+
+```bash
+# Cron job: renew cert and restart container
+0 3 * * * certbot renew --quiet && docker compose restart imap
+```
+
+---
+
+## Not supported
+
+### Vercel
+
+Vercel Functions are stateless request/response. No persistent TCP connections. Cannot host IMAP.
+
+### Deno Deploy
+
+Deno Deploy is request/response. No TCP listeners. Use Deno in a Docker container instead.
+
+### Cloudflare Containers
+
+HTTP-only sidecars. No TCP port exposure. Cannot host IMAP.
+
+### Cloudflare (native TCP/993)
+
+Requires Spectrum (Enterprise plan, ~$5k/mo). Use the Cloudflare DO runtime (`@rafters/mail-imap-cloudflare`) with WebSocket transport instead, or deploy `@rafters/mail-imap-server` on Fly.
+
+---
+
+## Multi-domain
+
+One deployment serves all your domains. The `resolveMailboxId` callback maps email addresses to mailbox IDs:
+
+```typescript
+async resolveMailboxId(email) {
+  const domain = email.split("@")[1];
+  // Look up mailbox by email in your database
+  const mailbox = await db.query.mailbox.findFirst({
+    where: eq(mailbox.emailAddress, email),
+  });
+  return mailbox?.id;
+}
+```
+
+DNS: point each domain's mail subdomain at the same server.
+
+```
+mail.silvius.me       CNAME  mail-imap.fly.dev
+mail.runlegion.dev    CNAME  mail-imap.fly.dev
+mail.gitpress.app     CNAME  mail-imap.fly.dev
+```
+
+Apple Mail: configure each account with its domain's mail hostname. All resolve to the same server. The server routes by email address after LOGIN.
diff --git a/packages/imap-server/docs/quickstart.md b/packages/imap-server/docs/quickstart.md
new file mode 100644
index 0000000..e74103f
--- /dev/null
+++ b/packages/imap-server/docs/quickstart.md
@@ -0,0 +1,174 @@
+# IMAP Server Quickstart
+
+Deploy an IMAP server for your edge email inbox. Standard email clients (Apple Mail, Thunderbird, Outlook) connect directly.
+
+---
+
+## Two runtimes, one protocol
+
+| Runtime       | Package                         | Deploys on                    | TLS                   |
+| ------------- | ------------------------------- | ----------------------------- | --------------------- |
+| Cloudflare DO | `@rafters/mail-imap-cloudflare` | Cloudflare Workers            | Cloudflare edge       |
+| Node TCP      | `@rafters/mail-imap-server`     | Fly.io, Railway, Fargate, VPS | Proxy or self-managed |
+
+Both use the same protocol layer (`@rafters/mail-imap`) and the same adapter interfaces. Pick the runtime that fits your infrastructure.
+
+---
+
+## Option A: Fly.io (recommended for standard IMAP clients)
+
+### 1. Install
+
+```bash
+pnpm add @rafters/mail-imap @rafters/mail-imap-server
+```
+
+### 2. Create the server
+
+```typescript
+import { createImapServer } from "@rafters/mail-imap-server";
+
+const server = createImapServer({
+  // No TLS config -- Fly handles TLS termination
+  port: 1993,
+  adapters: {
+    authAdapter: {
+      async verifyAppPassword(email, password) {
+        // Verify against your D1/database
+      },
+    },
+    mailboxAdapter: {
+      // Implement: listFolders, getFolderByName, getFolderStats, getMessageUids
+    },
+    messageAdapter: {
+      // Implement: getMessage, getMessagesByIds, updateMessageFlags,
+      //            deleteMessage, getBlob, searchMessages
+    },
+  },
+  async resolveMailboxId(email) {
+    // Map email address to mailbox ID in your database
+  },
+});
+
+await server.listen();
+```
+
+### 3. Configure Fly
+
+```toml
+# fly.toml
+app = "my-mail-imap"
+
+[[services]]
+  internal_port = 1993
+  protocol = "tcp"
+
+  [[services.ports]]
+    port = 993
+    handlers = ["tls"]
+```
+
+### 4. Deploy
+
+```bash
+fly launch
+fly certs add mail.yourdomain.com
+fly deploy
+```
+
+### 5. DNS
+
+CNAME `mail.yourdomain.com` to `my-mail-imap.fly.dev`.
+
+### 6. Connect Apple Mail
+
+- Incoming Mail Server: `mail.yourdomain.com`
+- Port: 993
+- SSL: Yes
+- Authentication: Password (use an app-specific password)
+
+---
+
+## Option B: Cloudflare Durable Objects (WebSocket clients)
+
+For web-based email clients or custom apps that connect via WebSocket.
+
+### 1. Install
+
+```bash
+pnpm add @rafters/mail-imap @rafters/mail-imap-cloudflare
+```
+
+### 2. Create the DO and Worker
+
+```typescript
+// src/index.ts
+import { createImapDurableObject, createImapWorker } from "@rafters/mail-imap-cloudflare";
+
+export const ImapMailboxDO = createImapDurableObject({
+  createAdapters(env) {
+    return {
+      authAdapter: {
+        /* verify against env.DB */
+      },
+      mailboxAdapter: {
+        /* query env.DB */
+      },
+      messageAdapter: {
+        /* query env.DB, fetch env.BLOB_STORAGE */
+      },
+    };
+  },
+});
+
+const worker = createImapWorker();
+export default worker;
+```
+
+### 3. Configure wrangler
+
+```jsonc
+// wrangler.jsonc
+{
+  "name": "mail-imap",
+  "durable_objects": {
+    "bindings": [{ "name": "IMAP_MAILBOX", "class_name": "ImapMailboxDO" }],
+  },
+  "migrations": [{ "tag": "v1", "new_classes": ["ImapMailboxDO"] }],
+}
+```
+
+### 4. Deploy
+
+```bash
+wrangler types
+wrangler deploy
+```
+
+### 5. Connect
+
+WebSocket to `wss://mail-imap.yourdomain.workers.dev/?email=user@example.com&mailboxId=...`
+
+---
+
+## App passwords
+
+IMAP uses app-specific passwords, not your regular login credentials. Generate them in your dashboard (ctrl) and store hashed (argon2) in your database.
+
+The `AuthAdapter.verifyAppPassword(email, appPassword)` method is called on every LOGIN. Implement it to check the hash against your database.
+
+---
+
+## Multi-domain
+
+Both runtimes support multiple domains from a single deployment. The email address is the routing key. `user@silvius.me` and `user@runlegion.dev` are served by the same server, routed to different mailboxes by `resolveMailboxId`.
+
+---
+
+## IDLE (push notifications)
+
+The server supports IMAP IDLE (RFC 2177). When a client enters IDLE, it receives real-time `EXISTS` notifications when new mail arrives.
+
+For the Cloudflare runtime: the inbound email Worker signals the IMAP DO via `POST /notify?count=N`. The DO pushes to all IDLE sessions.
+
+For the Node runtime: call the server's notification mechanism after storing a new message in your inbound handler.
diff --git a/packages/imap-server/package.json b/packages/imap-server/package.json
index 1d505d7..dddc255 100644
--- a/packages/imap-server/package.json
+++ b/packages/imap-server/package.json
@@ -2,8 +2,10 @@
   "name": "@rafters/mail-imap-server",
   "version": "0.0.1",
   "description": "Node TCP/TLS IMAP server runtime for @rafters/mail-imap",
+  "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "type": "module",
   "exports": {
diff --git a/packages/imap/README.md b/packages/imap/README.md
new file mode 100644
index 0000000..4f2a13d
--- /dev/null
+++ b/packages/imap/README.md
@@ -0,0 +1,82 @@
+# @rafters/mail-imap
+
+IMAP4rev1 protocol layer for [@rafters/mail](https://github.com/rafters-studio/mail). Transport-agnostic command handlers, session state machine, UID mapping, and adapter interfaces. The protocol surface that makes standard email clients (Apple Mail, Thunderbird, Outlook, K-9) connect to your edge-native inbox.
+
+This package contains no transport. Pair it with a runtime:
+
+- [`@rafters/mail-imap-cloudflare`](https://www.npmjs.com/package/@rafters/mail-imap-cloudflare) -- Durable Object over WebSocket (hibernation, near-zero cost when idle)
+- [`@rafters/mail-imap-server`](https://www.npmjs.com/package/@rafters/mail-imap-server) -- Node TCP/TLS server for Fly, Railway, Fargate, Docker, VPS
+
+## Install
+
+```bash
+pnpm add @rafters/mail-imap @rafters/mail
+```
+
+You will almost always install one of the runtime adapters alongside this package. Use this package directly only if you are writing your own runtime.
+
+## What you get
+
+**IMAP4rev1 command handlers** covering the RFC 3501 surface plus common extensions:
+
+- Authentication: `CAPABILITY`, `LOGIN`, `LOGOUT`
+- Mailbox: `SELECT`, `EXAMINE`, `LIST`, `LSUB`, `STATUS`
+- Message: `FETCH`, `STORE`, `SEARCH`, `EXPUNGE`, `NOOP`, `CLOSE`, `UID` prefix
+- Session: `IDLE` (RFC 2177), `UNSELECT` (RFC 3691)
+- Extensions: `COPY`, `MOVE` (RFC 6851), `APPEND`
+
+**Session state machine** with `Not Authenticated`, `Authenticated`, and `Selected` states plus the RFC-correct transitions between them.
+
+**UID map** for stable, monotonic message UIDs per folder across sessions.
+
+**Flag mapping** between IMAP flags and `@rafters/mail` message field booleans (seen, answered, flagged, deleted, draft).
+
+**Adapter interfaces** that the runtime implementations wire to your database:
+
+- `AuthAdapter` -- `verifyAppPassword(email, password)` to your credential store
+- `MailboxAdapter` -- folder listing, folder stats, UID enumeration
+- `MessageAdapter` -- fetch messages, update flags, delete, blob retrieval, search
+- `ExtensionAdapter` -- `COPY`, `MOVE`, and `APPEND` operations
+
+You bring your own auth system. This package does not own credential storage, hashing, or app-password generation.
+
+## Usage
+
+Importing individual subpaths keeps bundle size small:
+
+```typescript
+// Protocol layer
+import { parseCommand, formatTagged, generateGreeting } from "@rafters/mail-imap";
+
+// Command handlers
+import { handleLogin, handleLogout } from "@rafters/mail-imap/commands/auth";
+import { handleSelect, handleList, handleStatus } from "@rafters/mail-imap/commands/mailbox";
+import { handleFetch, handleStore, handleSearch } from "@rafters/mail-imap/commands/message";
+import { handleIdleStart, handleIdleDone } from "@rafters/mail-imap/commands/session";
+import { handleCopy, handleMove, handleAppend } from "@rafters/mail-imap/commands/extensions";
+
+// Session state and UID map
+import { ImapSession } from "@rafters/mail-imap/session";
+import { UidMap } from "@rafters/mail-imap/uid-map";
+
+// Adapter interfaces
+import type {
+  AuthAdapter,
+  MailboxAdapter,
+  MessageAdapter,
+  ExtensionAdapter,
+} from "@rafters/mail-imap";
+```
+
+## Documentation
+
+Per-package docs ship in the `docs/` directory and on npm:
+
+- [`commands.md`](./docs/commands.md) -- Full IMAP4rev1 command reference with RFC section citations
+- [`authentication.md`](./docs/authentication.md) -- How `AuthAdapter` works, what the IMAP server enforces, and what the consumer owns
+
+See the [monorepo README](https://github.com/rafters-studio/mail#readme) for the wider IMAP architecture and runtime options.
+
+## License
+
+MIT
diff --git a/packages/imap/docs/authentication.md b/packages/imap/docs/authentication.md
new file mode 100644
index 0000000..008275f
--- /dev/null
+++ b/packages/imap/docs/authentication.md
@@ -0,0 +1,117 @@
+# IMAP Authentication
+
+How email clients authenticate with the IMAP server.
+
+---
+
+## The AuthAdapter
+
+The IMAP server delegates all authentication to the consumer via the `AuthAdapter` interface:
+
+```typescript
+interface AuthAdapter {
+  verifyAppPassword(email: string, appPassword: string): Promise<boolean>;
+}
+```
+
+The IMAP server calls this on every LOGIN command. It does not know or care how the credential is stored, hashed, or managed. That is entirely the consumer's responsibility.
+
+---
+
+## How LOGIN works
+
+```
+C: a001 LOGIN user@example.com some-credential
+S: a001 OK LOGIN completed
+```
+
+1. Client sends email + credential
+2. IMAP server calls `authAdapter.verifyAppPassword(email, credential)`
+3. Adapter returns `true` (authenticated) or `false` (rejected)
+4. IMAP server responds OK or NO
+
+The IMAP server enforces:
+
+- **No information leakage**: generic "LOGIN failed" on bad credentials (never reveals whether the email exists)
+- **Rate limiting**: 3 failed attempts per session, then disconnect
+- **TLS required**: credentials are never transmitted in plaintext
+
+Everything else -- credential storage, hashing, generation, revocation, UI -- is the consumer's domain.
+
+---
+
+## Implementing the adapter
+
+The adapter is a single function. Wire it to your auth system:
+
+### With an API token system
+
+```typescript
+const authAdapter: AuthAdapter = {
+  async verifyAppPassword(email, token) {
+    // Call your auth service
+    const valid = await myAuthService.validateToken(email, token);
+    return valid;
+  },
+};
+```
+
+### With a database lookup
+
+```typescript
+const authAdapter: AuthAdapter = {
+  async verifyAppPassword(email, password) {
+    const record = await db.findCredential(email);
+    if (!record) return false;
+    return await verifyHash(record.hash, password);
+  },
+};
+```
+
+### With an external auth provider
+
+```typescript
+const authAdapter: AuthAdapter = {
+  async verifyAppPassword(email, token) {
+    const response = await fetch("https://auth.example.com/verify", {
+      method: "POST",
+      body: JSON.stringify({ email, token }),
+    });
+    return response.ok;
+  },
+};
+```
+
+The IMAP server does not prescribe how credentials are created, stored, hashed, or managed. Any system that can answer "is this credential valid for this email?" works.
+
+---
+
+## Security guarantees from the IMAP server
+
+These are enforced regardless of the adapter implementation:
+
+| Guarantee                          | How                                               |
+| ---------------------------------- | ------------------------------------------------- |
+| No credential leakage in responses | Generic "LOGIN failed" message                    |
+| Brute force protection             | 3 attempts per session, then BYE + disconnect     |
+| Encrypted transport                | TLS required (server-managed or proxy-terminated) |
+| Session isolation                  | Each connection has its own attempt counter       |
+
+---
+
+## What the consumer owns
+
+| Concern               | Consumer's responsibility                          |
+| --------------------- | -------------------------------------------------- |
+| Credential storage    | Database table, KV store, auth service             |
+| Hashing               | argon2, bcrypt, scram -- consumer chooses          |
+| Generation UI         | Dashboard, CLI, API endpoint                       |
+| Revocation            | Delete the credential, next LOGIN fails            |
+| Per-device management | Multiple credentials per user if needed            |
+| Password policy       | Length, complexity, expiration -- consumer decides |
+
+---
+
+## Future: SASL
+
+If the consumer's auth system supports SASL mechanisms (OAUTHBEARER, SCRAM-SHA-256), the IMAP server may add AUTHENTICATE command support. The AuthAdapter interface would extend to support SASL negotiation. LOGIN with the current interface remains the default.
diff --git a/packages/imap/docs/commands.md b/packages/imap/docs/commands.md
new file mode 100644
index 0000000..21385a5
--- /dev/null
+++ b/packages/imap/docs/commands.md
@@ -0,0 +1,242 @@
+# IMAP Command Reference
+
+All commands supported by `@rafters/mail-imap`. Each command references the RFC section it implements.
+
+---
+
+## Any State (RFC 3501 Section 6.1)
+
+### CAPABILITY
+
+Returns the server's supported extensions.
+
+```
+C: a001 CAPABILITY
+S: * CAPABILITY IMAP4rev1 IDLE LITERAL+ UIDPLUS NAMESPACE ID
+S: a001 OK CAPABILITY completed
+```
+
+### NOOP
+
+Keepalive. Returns any pending notifications.
+
+```
+C: a001 NOOP
+S: a001 OK NOOP completed
+```
+
+### LOGOUT
+
+Cleanly disconnects. Server sends BYE before tagged OK.
+
+```
+C: a001 LOGOUT
+S: * BYE LOGOUT requested
+S: a001 OK LOGOUT completed
+```
+
+---
+
+## Not Authenticated State (RFC 3501 Section 6.2)
+
+### LOGIN
+
+Authenticate with email address and app-specific password.
+
+```
+C: a001 LOGIN user@example.com myapppassword
+S: a001 OK LOGIN completed
+```
+
+Security:
+
+- Generic "LOGIN failed" on bad credentials (no information leakage)
+- 3-attempt rate limit per session
+- Disconnect after max attempts
+
+---
+
+## Authenticated State (RFC 3501 Section 6.3)
+
+### SELECT
+
+Open a folder for read-write access.
+
+```
+C: a001 SELECT INBOX
+S: * 47 EXISTS
+S: * 3 RECENT
+S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
+S: * OK [PERMANENTFLAGS (\Answered \Flagged \Deleted \Seen \Draft \*)]
+S: * OK [UIDVALIDITY 1]
+S: * OK [UIDNEXT 48]
+S: * OK [UNSEEN 12]
+S: * OK [READ-WRITE]
+S: a001 OK [READ-WRITE] SELECT completed
+```
+
+### EXAMINE
+
+Open a folder read-only. Same response as SELECT but with `[READ-ONLY]`.
+
+### LIST
+
+List available folders.
+
+```
+C: a001 LIST "" *
+S: * LIST (\HasNoChildren \Inbox) "/" INBOX
+S: * LIST (\HasNoChildren \Sent) "/" Sent
+S: * LIST (\HasNoChildren \Drafts) "/" Drafts
+S: * LIST (\HasNoChildren \Trash) "/" Trash
+S: a001 OK LIST completed
+```
+
+Pattern wildcards: `*` matches everything, `%` matches within one hierarchy level.
+
+### LSUB
+
+List subscribed folders. MVP: same as LIST (all folders subscribed).
+
+### STATUS
+
+Get folder stats without selecting.
+
+```
+C: a001 STATUS INBOX (MESSAGES RECENT UNSEEN UIDNEXT UIDVALIDITY)
+S: * STATUS INBOX (MESSAGES 47 RECENT 3 UNSEEN 12 UIDNEXT 48 UIDVALIDITY 1)
+S: a001 OK STATUS completed
+```
+
+### APPEND (RFC 3501 Section 6.3.6 + RFC 4315)
+
+Upload a message to a folder.
+
+```
+C: a001 APPEND Sent (\Seen) {310}
+S: + Ready for literal data
+C: <message content>
+S: a001 OK [APPENDUID 1 305] APPEND completed
+```
+
+---
+
+## Selected State (RFC 3501 Section 6.4)
+
+### FETCH
+
+Retrieve message data. Supports individual items and macros.
+
+```
+C: a001 FETCH 1:* (FLAGS UID ENVELOPE)
+S: * 1 FETCH (FLAGS (\Seen) UID 101 ENVELOPE (...))
+S: * 2 FETCH (FLAGS () UID 102 ENVELOPE (...))
+S: a001 OK FETCH completed
+```
+
+Data items: FLAGS, UID, ENVELOPE, RFC822.SIZE, INTERNALDATE, BODYSTRUCTURE, BODY[section].
+
+Macros: ALL, FAST, FULL.
+
+BODY.PEEK[section] fetches without setting \Seen flag.
+
+### STORE
+
+Update message flags.
+
+```
+C: a001 STORE 1 +FLAGS (\Seen)
+S: * 1 FETCH (FLAGS (\Seen))
+S: a001 OK STORE completed
+```
+
+Modes: `FLAGS` (replace), `+FLAGS` (add), `-FLAGS` (remove). Add `.SILENT` to suppress response.
+
+### SEARCH
+
+Find messages by criteria.
+
+```
+C: a001 SEARCH UNSEEN SINCE 1-Mar-2026
+S: * SEARCH 3 7 12
+S: a001 OK SEARCH completed
+```
+
+Criteria: ALL, ANSWERED, DELETED, DRAFT, FLAGGED, NEW, SEEN, UNSEEN, FROM, TO, CC, BCC, SUBJECT, BEFORE, ON, SINCE, LARGER, SMALLER, TEXT, BODY, UID, NOT, OR.
+
+### EXPUNGE
+
+Permanently remove messages marked \Deleted.
+
+```
+C: a001 EXPUNGE
+S: * 3 EXPUNGE
+S: a001 OK EXPUNGE completed
+```
+
+### CLOSE
+
+Close folder and silently expunge deleted messages (no EXPUNGE responses).
+
+### COPY (RFC 3501 Section 6.4.7 + RFC 4315)
+
+Copy messages to another folder.
+
+```
+C: a001 COPY 1:3 Sent
+S: a001 OK [COPYUID 1 10,20,30 200,201,202] COPY completed
+```
+
+### MOVE (RFC 6851)
+
+Atomically move messages to another folder.
+
+```
+C: a001 MOVE 1 Archive
+S: * 1 EXPUNGE
+S: a001 OK [COPYUID 1 10 300] MOVE completed
+```
+
+### UNSELECT (RFC 3691)
+
+Close folder without expunging.
+
+---
+
+## Extensions
+
+### IDLE (RFC 2177)
+
+Wait for server push notifications.
+
+```
+C: a001 IDLE
+S: + idling
+... (time passes, new mail arrives)
+S: * 48 EXISTS
+C: DONE
+S: a001 OK IDLE completed
+```
+
+### UID prefix
+
+Any of FETCH, STORE, SEARCH, COPY, MOVE can be prefixed with UID to operate on UIDs instead of sequence numbers.
+
+```
+C: a001 UID FETCH 101 FLAGS
+S: * 1 FETCH (FLAGS (\Seen) UID 101)
+S: a001 OK FETCH completed
+```
+
+---
+
+## Flag Mapping
+
+| IMAP Flag       | @rafters/mail Field        | Notes              |
+| --------------- | -------------------------- | ------------------ |
+| \Seen           | isRead                     | Settable           |
+| \Flagged        | isStarred                  | Settable           |
+| \Deleted        | deletedAt (soft delete)    | Settable           |
+| \Answered       | thread has outbound reply  | Derived, read-only |
+| \Draft          | folder slug = "drafts"     | Derived, read-only |
+| Custom keywords | labels (inboxMessageLabel) | Settable           |
diff --git a/packages/imap/package.json b/packages/imap/package.json
index f20eb5f..91422a0 100644
--- a/packages/imap/package.json
+++ b/packages/imap/package.json
@@ -2,8 +2,10 @@
   "name": "@rafters/mail-imap",
   "version": "0.0.1",
   "description": "IMAP4rev1 protocol layer for @rafters/mail. Transport-agnostic command handlers and adapter interfaces.",
+  "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "type": "module",
   "exports": {
diff --git a/packages/react-email/README.md b/packages/react-email/README.md
new file mode 100644
index 0000000..ae21bad
--- /dev/null
+++ b/packages/react-email/README.md
@@ -0,0 +1,76 @@
+# @rafters/mail-react-email
+
+React Email template renderer for [@rafters/mail](https://github.com/rafters-studio/mail). Ships two baseline templates (`BaseEmail` and `OtpEmail`) and a `TemplateRenderer` implementation that produces HTML + text output from any React Email component.
+
+## Install
+
+```bash
+pnpm add @rafters/mail-react-email @rafters/mail
+```
+
+## Usage
+
+### Renderer
+
+```typescript
+import { createReactEmailRenderer } from "@rafters/mail-react-email/renderer";
+import { OtpEmail } from "@rafters/mail-react-email/otp";
+
+const renderer = createReactEmailRenderer();
+
+const { html, text } = await renderer.render(OtpEmail({ otp: "123456", appName: "Example" }));
+```
+
+`createReactEmailRenderer` returns a `TemplateRenderer` matching the interface in `@rafters/mail`, so it drops into any service that expects a renderer.
+
+### BaseEmail template
+
+`BaseEmail` is the shared layout for all rafters templates. Use it directly or extend it for your own templates:
+
+```typescript
+import { BaseEmail } from "@rafters/mail-react-email/templates";
+
+export function WelcomeEmail({ name }: { name: string }) {
+  return (
+    <BaseEmail preview="Welcome to Example">
+      <h1>Welcome, {name}</h1>
+      <p>Thanks for signing up.</p>
+    </BaseEmail>
+  );
+}
+```
+
+### OtpEmail template
+
+Prebuilt one-time password email, used by `@rafters/better-auth-resend` for the emailOTP flow:
+
+```typescript
+import { OtpEmail } from "@rafters/mail-react-email/otp";
+
+const component = OtpEmail({
+  otp: "123456",
+  appName: "Example",
+  expiresInMinutes: 10,
+});
+```
+
+## Exports
+
+| Subpath       | What                       |
+| ------------- | -------------------------- |
+| `.`           | Top-level re-exports       |
+| `./renderer`  | `createReactEmailRenderer` |
+| `./templates` | `BaseEmail`                |
+| `./otp`       | `OtpEmail`                 |
+
+## Documentation
+
+Per-package docs ship in the `docs/` directory and on npm:
+
+- [`templates.md`](./docs/templates.md) -- `BaseEmail`, `OtpEmail`, writing your own templates, and rendering through the `TemplateRenderer` interface
+
+See the [monorepo README](https://github.com/rafters-studio/mail#readme) for the @rafters/mail architecture.
+
+## License
+
+MIT
diff --git a/packages/react-email/docs/templates.md b/packages/react-email/docs/templates.md
new file mode 100644
index 0000000..1c23b96
--- /dev/null
+++ b/packages/react-email/docs/templates.md
@@ -0,0 +1,104 @@
+# React Email Templates
+
+`@rafters/mail-react-email` ships a small library of React Email templates and a renderer that produces HTML + plain text output. Templates are regular React components rendered through `@react-email/components`.
+
+## BaseEmail
+
+The shared layout for every rafters template. Use it directly or wrap it in a named template.
+
+```typescript
+import { BaseEmail } from "@rafters/mail-react-email/templates";
+
+export function WelcomeEmail({ name }: { name: string }) {
+  return (
+    <BaseEmail preview="Welcome to Example">
+      <h1>Welcome, {name}</h1>
+      <p>Thanks for signing up.</p>
+    </BaseEmail>
+  );
+}
+```
+
+`BaseEmail` supplies:
+
+- HTML `<html>` / `<body>` / `<head>` boilerplate with inlined styles
+- Email-safe container layout that works in Gmail, Outlook, Apple Mail
+- A `preview` prop that sets the email preview text shown in the inbox list before the user opens the message
+- Standard font stack and line-height for readable long-form content
+
+Children render inside the content block. Style children with React Email's `<Section>`, `<Row>`, `<Text>`, `<Button>`, and `<Hr>` for portable cross-client output.
+
+## OtpEmail
+
+Prebuilt one-time password email. Used by `@rafters/better-auth-resend` for the emailOTP verification flow.
+
+```typescript
+import { OtpEmail } from "@rafters/mail-react-email/otp";
+
+const component = OtpEmail({
+  otp: "123456",
+  appName: "Example",
+  expiresInMinutes: 10,
+});
+```
+
+Props:
+
+| Prop               | Required | Description                                    |
+| ------------------ | -------- | ---------------------------------------------- |
+| `otp`              | yes      | The one-time password to display               |
+| `appName`          | yes      | Shown in subject and body                      |
+| `expiresInMinutes` | optional | Displayed in the email body. Defaults to `10`. |
+
+## Renderer
+
+`createReactEmailRenderer()` returns a `TemplateRenderer` matching the interface in `@rafters/mail`. It renders any React Email component into a `{ html, text }` pair.
+
+```typescript
+import { createReactEmailRenderer } from "@rafters/mail-react-email/renderer";
+import { WelcomeEmail } from "./templates/welcome.tsx";
+
+const renderer = createReactEmailRenderer();
+
+const { html, text } = await renderer.render(WelcomeEmail({ name: "Sean" }));
+```
+
+The renderer uses React Email's `render` function under the hood. Plain text output is derived from the React tree automatically -- if you need custom text output, return a `<Text>` component with the exact text you want.
+
+## Writing your own template
+
+Wrap `BaseEmail` and add React Email components inside:
+
+```typescript
+import { BaseEmail } from "@rafters/mail-react-email/templates";
+import { Section, Text, Button, Hr } from "@react-email/components";
+
+export function OrderShippedEmail(props: {
+  customerName: string;
+  trackingNumber: string;
+  trackingUrl: string;
+}) {
+  return (
+    <BaseEmail preview={`Your order is on the way -- ${props.trackingNumber}`}>
+      <Section>
+        <Text>Hi {props.customerName},</Text>
+        <Text>Your order has shipped. Track it any time:</Text>
+        <Button href={props.trackingUrl}>Track package</Button>
+        <Hr />
+        <Text>Tracking number: {props.trackingNumber}</Text>
+      </Section>
+    </BaseEmail>
+  );
+}
+```
+
+Then render through the `TemplateRenderer` and pass the result to your email provider.
+
+## Exports
+
+| Subpath       | Exports                    |
+| ------------- | -------------------------- |
+| `.`           | Top-level re-exports       |
+| `./renderer`  | `createReactEmailRenderer` |
+| `./templates` | `BaseEmail`                |
+| `./otp`       | `OtpEmail`                 |
diff --git a/packages/react-email/package.json b/packages/react-email/package.json
index 19cc842..d707fd9 100644
--- a/packages/react-email/package.json
+++ b/packages/react-email/package.json
@@ -2,8 +2,10 @@
   "name": "@rafters/mail-react-email",
   "version": "0.0.1",
   "description": "React Email template renderer for @rafters/mail",
+  "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "type": "module",
   "exports": {
diff --git a/packages/resend/README.md b/packages/resend/README.md
new file mode 100644
index 0000000..c36830c
--- /dev/null
+++ b/packages/resend/README.md
@@ -0,0 +1,88 @@
+# @rafters/mail-resend
+
+Resend outbound email adapter for [@rafters/mail](https://github.com/rafters-studio/mail). Implements the `EmailProvider` interface (transactional send + mailing list management), plus a Resend webhook handler that maps delivery events to mail service updates, plus a mock provider for local tests.
+
+Uses Resend's HTTP API directly via `fetch`. No Resend SDK dependency, so the bundle stays edge-safe.
+
+## Install
+
+```bash
+pnpm add @rafters/mail-resend @rafters/mail
+```
+
+## Usage
+
+### Transactional provider
+
+```typescript
+import { createResendProvider } from "@rafters/mail-resend";
+
+const provider = createResendProvider({
+  apiKey: env.RESEND_API_KEY,
+  defaultFrom: "hello@example.com",
+});
+
+await provider.send({
+  to: "user@example.com",
+  subject: "Welcome",
+  html: "<p>Hi there.</p>",
+  text: "Hi there.",
+});
+```
+
+### Mock provider for tests
+
+```typescript
+import { createMockEmailProvider } from "@rafters/mail-resend/mock";
+
+const provider = createMockEmailProvider();
+await provider.send({ to: "u@test", subject: "hi", html: "<p>hi</p>", text: "hi" });
+
+expect(provider.sentEmails).toHaveLength(1);
+```
+
+### Webhook handler
+
+```typescript
+import { createResendWebhookHandler } from "@rafters/mail-resend/webhooks";
+
+const handler = createResendWebhookHandler({
+  signingSecret: env.RESEND_WEBHOOK_SECRET,
+  onDelivered(event) {
+    /* ... */
+  },
+  onBounced(event) {
+    /* ... */
+  },
+  onComplained(event) {
+    /* ... */
+  },
+});
+
+// In your Hono / Worker route:
+app.post("/webhooks/resend", async (c) => {
+  const result = await handler(c.req.raw);
+  return result.ok ? c.text("ok") : c.text(result.error, 400);
+});
+```
+
+## Exports
+
+| Subpath      | What                                    |
+| ------------ | --------------------------------------- |
+| `.`          | `createResendProvider`, `ResendService` |
+| `./mock`     | `createMockEmailProvider`               |
+| `./webhooks` | `createResendWebhookHandler`            |
+| `./types`    | Resend API request and response types   |
+
+## Documentation
+
+Per-package docs ship in the `docs/` directory and on npm:
+
+- [`outbound.md`](./docs/outbound.md) -- End-to-end outbound flow: compose, Resend send, webhook handling, and audit
+
+See the [monorepo README](https://github.com/rafters-studio/mail#readme) for the full @rafters/mail architecture.
+
+## License
+
+MIT
diff --git a/packages/resend/docs/outbound.md b/packages/resend/docs/outbound.md
new file mode 100644
index 0000000..d5c6c25
--- /dev/null
+++ b/packages/resend/docs/outbound.md
@@ -0,0 +1,136 @@
+# Outbound Email
+
+How the system sends email.
+
+---
+
+## The email provider
+
+Outbound email is sent through an `EmailProvider` adapter. The provider handles the HTTP API call to your email sending service.
+
+```typescript
+interface EmailProvider {
+  sendEmail(params: SendEmailParams): Promise<SendEmailResult>;
+}
+```
+
+Parameters:
+
+| Field   | Required | Purpose                     |
+| ------- | -------- | --------------------------- |
+| from    | yes      | Sender email address        |
+| to      | yes      | Recipient email address(es) |
+| subject | yes      | Email subject               |
+| html    | no       | HTML body                   |
+| text    | no       | Plain text body             |
+| cc      | no       | CC recipients               |
+| bcc     | no       | BCC recipients              |
+| replyTo | no       | Reply-To address            |
+| headers | no       | Custom headers              |
+
+At least one of `html` or `text` must be provided.
+
+---
+
+## Composing and replying
+
+### New message
+
+```typescript
+await mailService.compose({
+  mailboxId: "mbx_01J...",
+  senderId: "user_01J...",
+  to: ["recipient@example.com"],
+  subject: "Hello",
+  body: "Plain text content",
+  bodyHtml: "<p>HTML content</p>",
+});
+```
+
+The compose flow:
+
+1. Generates a Message-ID using UUIDv7
+2. Creates a new thread (or finds existing by subject)
+3. Sends via the EmailProvider
+4. Stores the sent message in the database with `isOutbound: true`
+5. Stores content in blob storage
+
+### Reply
+
+```typescript
+await mailService.replyToThread({
+  threadId: "thread_01J...",
+  mailboxId: "mbx_01J...",
+  senderId: "user_01J...",
+  body: "Reply text",
+  bodyHtml: "<p>Reply HTML</p>",
+});
+```
+
+The reply flow:
+
+1. Loads the thread and its most recent message
+2. Builds the References header from the thread's message chain
+3. Sets In-Reply-To to the most recent message's Message-ID
+4. Generates a new Message-ID
+5. Sends via the EmailProvider
+6. Stores the reply in the same thread with `isOutbound: true`
+7. Updates thread metadata (messageCount, lastMessageAt, snippet)
+
+---
+
+## Templates
+
+Email content can be rendered from templates using a template adapter. The default implementation uses React Email components:
+
+```typescript
+interface TemplateRenderer {
+  render(
+    component: unknown,
+    props: Record<string, unknown>,
+  ): Promise<{ html: string; text: string }>;
+}
+```
+
+Templates are React components that produce both HTML and plain text output. The renderer is framework-agnostic -- any system that produces HTML and text from a component can implement the interface.
+
+---
+
+## Webhooks
+
+Sending services provide webhook notifications for delivery events:
+
+| Event      | Meaning                                     |
+| ---------- | ------------------------------------------- |
+| delivered  | Email accepted by recipient's server        |
+| bounced    | Permanent delivery failure                  |
+| complained | Recipient marked as spam                    |
+| opened     | Recipient opened the email (tracking pixel) |
+| clicked    | Recipient clicked a link (link tracking)    |
+
+The webhook handler validates the signature, matches the event to a message by provider ID, and updates delivery status in the database.
+
+---
+
+## Delivery status
+
+Each outbound message tracks its delivery lifecycle:
+
+```
+sent -> delivered
+sent -> bounced
+sent -> delivered -> complained
+```
+
+Delivery status is stored on the message record. The IMAP server exposes this as message metadata -- clients can see whether a sent message was delivered or bounced.
+
+---
+
+## Multiple sending domains
+
+The EmailProvider is configured per mailbox or per domain. A single deployment can send from multiple domains:
+
+- `support@silvius.me` sends via one provider configuration
+- `hello@runlegion.dev` sends via another (or the same with different sender verification)
+
+Each domain needs its own DKIM/SPF records. The sending provider handles domain verification.
diff --git a/packages/resend/package.json b/packages/resend/package.json
index 8a3e8a7..504a198 100644
--- a/packages/resend/package.json
+++ b/packages/resend/package.json
@@ -2,8 +2,10 @@
   "name": "@rafters/mail-resend",
   "version": "0.0.1",
   "description": "Resend outbound email adapter for @rafters/mail",
+  "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "type": "module",
   "exports": {
diff --git a/packages/workers-ai/README.md b/packages/workers-ai/README.md
new file mode 100644
index 0000000..ac23641
--- /dev/null
+++ b/packages/workers-ai/README.md
@@ -0,0 +1,63 @@
+# @rafters/mail-workers-ai
+
+Cloudflare Workers AI email classifier for [@rafters/mail](https://github.com/rafters-studio/mail). Uses DeBERTa-v3 zero-shot classification to assign a category, priority, and auto-tags to every inbound message.
+
+Implements the `EmailClassifier` interface from core, so classification results flow through the standard message pipeline.
+
+## Install
+
+```bash
+pnpm add @rafters/mail-workers-ai @rafters/mail
+```
+
+## Usage
+
+```typescript
+import { createWorkersAIClassifier } from "@rafters/mail-workers-ai";
+import { DEFAULT_TAG_PATTERNS } from "@rafters/mail-workers-ai/config";
+
+const classifier = createWorkersAIClassifier({
+  ai: env.AI, // Cloudflare Workers AI binding
+  tagPatterns: DEFAULT_TAG_PATTERNS,
+});
+
+const result = await classifier.classify({
+  subject: "Your order has shipped",
+  body: "Tracking: 1Z999...",
+});
+
+// result = {
+//   category: "transactional",
+//   confidence: 0.94,
+//   priority: "normal",
+//   tags: ["shipping", "order"],
+// }
+```
+
+## Categories
+
+The classifier emits one of a small fixed set of categories per message:
+
+- `transactional` -- order confirmations, receipts, password resets
+- `notification` -- system or app alerts
+- `marketing` -- promotional and newsletter content
+- `personal` -- human correspondence
+- `spam` -- unwanted mail (moved to the spam folder by the pipeline)
+
+Priority (`urgent`, `high`, `normal`, `low`) is derived from the category plus subject-line signals. Tags are pattern-matched against configurable regex patterns -- override `tagPatterns` to add your own.
+
+## Runtime
+
+This package is designed for Cloudflare Workers AI and expects an `AI` binding. If you run it in another runtime, provide a stub that matches the `Ai` interface and returns compatible responses.
+
+## Documentation
+
+Per-package docs ship in the `docs/` directory and on npm:
+
+- [`classification.md`](./docs/classification.md) -- Categories, confidence scoring, priority derivation, tag patterns, and pipeline integration
+
+See the [monorepo README](https://github.com/rafters-studio/mail#readme) for the inbound classification flow end-to-end.
+
+## License
+
+MIT
diff --git a/packages/workers-ai/docs/classification.md b/packages/workers-ai/docs/classification.md
new file mode 100644
index 0000000..46e1a5a
--- /dev/null
+++ b/packages/workers-ai/docs/classification.md
@@ -0,0 +1,111 @@
+# Classification
+
+Automatic categorization of incoming email using AI or rule-based classifiers.
+
+---
+
+## The classification adapter
+
+```typescript
+interface ClassificationAdapter {
+  classify(message: ClassificationInput): Promise<ClassificationResult>;
+}
+
+interface ClassificationInput {
+  subject: string;
+  from: string;
+  textBody: string;
+  htmlBody?: string;
+}
+
+interface ClassificationResult {
+  category: AiCategory;
+  confidence: number; // 0-100
+  summary: string; // one-line description
+}
+```
+
+The adapter is called after a message is stored. Classification results are written to the message record.
+
+---
+
+## Categories
+
+| Category    | When to use                                                    |
+| ----------- | -------------------------------------------------------------- |
+| support     | Customer asking for help, bug reports, how-to questions        |
+| feedback    | Product feedback, feature requests, suggestions                |
+| billing     | Payment issues, invoice questions, subscription changes        |
+| partnership | Business proposals, integration requests, collaboration offers |
+| abuse       | Harassment, threats, terms of service violations               |
+| legal       | Legal notices, compliance requests, DMCA takedowns             |
+| spam        | Unsolicited commercial email, phishing attempts                |
+| other       | Everything else                                                |
+
+---
+
+## How classification is used
+
+### Folder assignment
+
+Classification can drive automatic folder assignment. A message classified as `spam` with confidence > 80 moves to the spam folder. A message classified as `support` stays in the inbox.
+
+### Priority
+
+High-confidence `billing` or `legal` classifications can automatically set thread priority to `high` or `urgent`.
+
+### Dashboard filtering
+
+The ctrl dashboard filters by category. "Show me all unresolved support threads" is a query on `aiCategory = 'support'` AND `status = 'open'`.
+
+---
+
+## Confidence scores
+
+The confidence score (0-100) indicates how certain the classifier is about its category assignment.
+
+| Range  | Meaning           | Action                             |
+| ------ | ----------------- | ---------------------------------- |
+| 80-100 | High confidence   | Auto-assign folder, set priority   |
+| 50-79  | Medium confidence | Suggest category, let user confirm |
+| 0-49   | Low confidence    | No automatic action                |
+
+Thresholds are configurable per mailbox. A high-volume support inbox might auto-assign at 70. A personal inbox might require 90.
+
+---
+
+## Spam detection
+
+Spam classification is separate from the general category classifier. The message record has dedicated fields:
+
+| Field     | Purpose      |
+| --------- | ------------ |
+| isSpam    | boolean flag |
+| spamScore | 0-100 score  |
+
+Spam detection can combine multiple signals: the AI classifier's spam category, header analysis (SPF/DKIM failures), content patterns, and sender reputation. The `isSpam` flag is the final decision after combining all signals.
+
+---
+
+## Implementing a classifier
+
+The simplest classifier uses zero-shot classification with a language model:
+
+```typescript
+const classifier: ClassificationAdapter = {
+  async classify(input) {
+    const result = await model.run({
+      text: `${input.subject}\n\n${input.textBody}`,
+      labels: ["support", "feedback", "billing", "partnership", "abuse", "legal", "spam", "other"],
+    });
+
+    return {
+      category: result.label as AiCategory,
+      confidence: Math.round(result.score * 100),
+      summary: await model.summarize(input.textBody, { maxLength: 100 }),
+    };
+  },
+};
+```
+
+You can also implement rule-based classification (regex patterns on subject/sender), or a hybrid that uses rules first and falls back to AI for uncertain cases.
diff --git a/packages/workers-ai/package.json b/packages/workers-ai/package.json
index 6c4dcdd..6719c29 100644
--- a/packages/workers-ai/package.json
+++ b/packages/workers-ai/package.json
@@ -2,8 +2,10 @@
   "name": "@rafters/mail-workers-ai",
   "version": "0.0.1",
   "description": "Workers AI email classifier adapter for @rafters/mail",
+  "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "type": "module",
   "exports": {