diff --git a/CLAUDE.md b/CLAUDE.md
index 8e83c789f4..32e5a951a8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,7 +4,55 @@
> A new Claude Code session reading only this file should understand the project structure,
> development patterns, and how to get productive immediately.
-## Quick Orientation
+---
+
+# PART 0 — How to use this document
+
+## 0.1 The workflow
+1. Read this file to understand the project purpose, architecture, and standards
+2. Follow the **Task Protocol** and **Hard Gates** before claiming any task complete
+3. Every task produces: **code changes** with tests + docs, and a **Verification Log**
+
+## 0.2 The two outputs every task must produce
+- **Code changes** with tests + docs updates
+- A **Verification Log** containing exact commands and pass/fail results
+
+---
+
+# PART 1 — Mission and non-negotiables
+
+## 1.1 Mission
+Build an **AI-native**, **gorgeous**, **easy-to-use**, **Cloudflare-optimized** application suite where correctness is proven by:
+- **E2E-TDD Playwright** (primary verification)
+- **100% feature coverage** (enforced via `e2e/FEATURES.md` inventory)
+- **100% unit test coverage** (enforced by test thresholds)
+- **strict linting** and **quantitative quality gates**
+
+## 1.2 Non-negotiables
+- AI is the primary developer — the system must be **self-explaining** and **self-diagnosing**
+- Prefer **Cloudflare-only** primitives; only use **Neon/Upstash** when the Cloudflare stack cannot meet requirements
+- Use **Zod everywhere** at boundaries; error messages must be **human-readable**
+- Implement "distinguished engineer" error handling everywhere (taxonomy + envelopes + idempotency + retries + fallbacks)
+- Every major system is instrumented: logs, traces, events, notifications are **enriched and correlated**
+- Documentation is first-class: JSDoc/TypeDoc on exports + docs with tables/examples/references
+
+---
+
+# PART 2 — Project Purpose Summary
+
+**bolt.diy** is an open-source, AI-powered full-stack web development IDE that runs in the browser. It lets developers chat with AI models to generate, edit, and deploy web applications — all within an integrated environment featuring a code editor, terminal, file manager, and live preview.
+
+- **Primary users**: Web developers, indie hackers, and learners who want AI-assisted code generation
+- **First value**: User types a prompt, AI generates a working web app they can preview and deploy
+- **Primary entities**: Chats, Files/Projects, Providers/Models, Deployments, Settings
+
+The monorepo also includes:
+- **Project Sites** (`apps/project-sites/`): A SaaS website builder powered by AI, serving generated business websites on Cloudflare Workers
+- **Shared Package** (`packages/shared/`): Zod schemas, constants, RBAC middleware, utilities shared between packages
+
+---
+
+# PART 3 — Quick Orientation
This is a monorepo containing:
@@ -45,67 +93,407 @@ bolt.diy/
│ ├── middleware/ # RBAC + entitlements
│ ├── utils/ # errors, crypto, sanitize, redact
│ └── constants/ # DOMAINS, AUTH, PRICING, CAPS, ENTITLEMENTS, ROLES
+├── e2e/ # Root-level E2E tests for bolt.diy main app
+│ ├── FEATURES.md # Authoritative feature inventory
+│ ├── COVERAGE.yml # Feature → spec mapping
+│ ├── fixtures.ts # Shared Playwright fixtures
+│ ├── playwright.config.ts # Playwright config for main app
+│ └── specs/ # 14 spec files, 96+ tests
├── supabase/migrations/ # Reference Postgres schema (D1 SQLite used in prod)
├── docs/ # MkDocs documentation site
├── electron/ # Electron desktop wrapper
└── .github/workflows/ # CI/CD pipelines
```
-## MANDATORY: Test-Driven Development (TDD)
+---
+
+# PART 4 — Cloudflare-first architecture (fallback only when necessary)
+
+## 4.1 Default Cloudflare primitives (use first)
+Use these unless there is a concrete reason not to:
+
+**Compute / routing**
+- Workers (Hono) for APIs and SSR functions
+- Pages for front-end hosting when suitable
+
+**Storage**
+- R2 for uploads/assets
+- KV for small config, cache snapshots, feature flag snapshots
+- Durable Objects for stateful flows, collaboration, presence, progress, per-tenant state
+- Queues for async jobs; Cron Triggers for scheduled tasks
+- D1 for simple relational needs (when Postgres features not required)
+
+**Edge**
+- Caching with explicit rules (SWR for safe content, never cache auth/billing/permissions)
+- Turnstile for abuse prevention
+
+## 4.2 Fallback decision tree: Neon + Upstash (only if required)
+**Neon Postgres (fallback)** — use only if you need:
+- Postgres semantics (advanced SQL, joins, concurrency, extensions)
+- Strong relational modeling beyond D1 scope
+- **RLS** as the primary tenant isolation guarantee
+- Heavy analytics queries / OLAP-like needs
+
+When using Neon with Workers, prefer **Cloudflare Hyperdrive** to stabilize connections.
+
+**Upstash Redis (fallback)** — use only if you need:
+- Redis-specific primitives: sorted sets, streams, locks, atomic counters at scale
+- Global rate limiting beyond what KV/DO can reasonably do
+- High-throughput cache invalidation patterns
+
+## 4.3 Project Sites Worker Stack
+| Layer | Technology | Purpose |
+|-------|-----------|---------|
+| Ingress/API | Cloudflare Workers + Hono | API gateway, site serving |
+| Database | Cloudflare D1 (SQLite) | System of record |
+| Cache | Cloudflare KV | Host resolution (60s TTL), prompt hot-patching |
+| Storage | Cloudflare R2 | Static sites, marketing assets |
+| Background | Cloudflare Workflows | AI site generation pipeline |
+| AI | Cloudflare Workers AI | LLM inference (Llama 3.1) |
+| Payments | Stripe | Checkout, subscriptions, webhooks |
+| Email | Resend / SendGrid | Magic links, transactional |
+| Analytics | PostHog (server-side) | Funnel events |
+| Errors | Sentry (HTTP API) | Exception tracking |
+
+### Key Design Decisions
+- **No Supabase JS client** — D1 via parameterized SQL for Workers compat
+- **Dash-based subdomains**: `{slug}-sites.megabyte.space` (not nested wildcards)
+- **R2 paths**: `sites/{slug}/{version}/{file}`, marketing at `marketing/index.html`
+- **Queues NOT yet enabled** — `QUEUE` binding is optional in Env type
+- **CSP must include `'unsafe-inline'`** — homepage uses inline `
+
+
+
+
+
+ Project Sites - Your Website, Handled. Finally.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+