diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..187fe2f
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,96 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**Randall** is an office desk reservation system. It uses a .NET 10 backend (Clean Architecture) with a React 19 + TypeScript frontend, served via Nginx reverse proxy in Docker.
+
+Default admin: `admin@randall.local` / `Admin@123`
+
+## Commands
+
+### Backend
+```bash
+# Run (port 5180)
+dotnet run --project src/backend/src/Randall.Api
+
+# Unit tests
+dotnet test src/backend/tests/unit/Randall.Domain.UnitTests
+
+# Integration tests
+dotnet test src/backend/tests/integration/Randall.Api.IntegrationTests
+
+# All backend tests
+dotnet test src/backend
+```
+
+### Frontend
+```bash
+cd src/frontend
+npm run dev        # Dev server (port 5173, proxies /api → localhost:5180)
+npm run build
+npm run lint
+```
+
+### E2E Tests
+```bash
+cd tests/e2e
+npx playwright test
+npx playwright test --headed
+npx playwright test --ui
+```
+
+### Docker
+```bash
+docker compose -f cicd/docker/docker-compose.yml up --build
+# Runs on port 80; backend health check at :8080/health
+```
+
+## Architecture
+
+### Backend — Clean Architecture (4 layers)
+
+| Layer | Project | Role |
+|-------|---------|------|
+| API | `Randall.Api` | Controllers, JWT middleware, request/response |
+| Application | `Randall.Application` | Use-case handlers, DTOs, DI registration |
+| Domain | `Randall.Domain` | Entities, business rules, `Result<T>` pattern |
+| Infrastructure | `Randall.Infrastructure` | EF Core, SQLite, JWT generation, password hashing |
+
+**Key patterns:**
+- **Result pattern:** `Result<T>` (railway-oriented error handling) used throughout domain and application layers.
+- **Repository pattern:** interfaces in Domain, implementations in Infrastructure.
+- **Handlers:** each use case has a dedicated handler class in Application (organized by feature: Admin, Auth, Reservations, Workplaces).
+
+**Domain constraints:**
+- One active reservation per employee per day
+- One active reservation per workplace per day
+
+**Database:** SQLite at `randall.db` (Docker: `/app/data/randall.db`). Migrations apply automatically on startup. Seeded with 16 workplaces + admin account on first run (skipped if DB is non-empty).
+
+### Frontend
+
+- **Pages:** `AuthPage`, `PlannerPage`, `AdminPage` — routed via React Router
+- **API client:** `src/api/client.ts` — centralized typed fetch wrapper
+- **Auth state:** JWT stored in localStorage, passed as Bearer token
+- **Dev proxy:** Vite proxies `/api` to backend, so no CORS issues locally
+
+### Request Flow
+
+```
+React SPA → Nginx (/api/* proxied) → ASP.NET Core Controller
+  → Application Handler → Domain Entity → Infrastructure (EF Core / SQLite)
+```
+
+### Testing Strategy
+
+| Layer | Framework | Approach |
+|-------|-----------|----------|
+| Unit | xUnit | Domain entities in isolation |
+| Integration | xUnit + WebApplicationFactory | Full API endpoints with in-process SQLite |
+| E2E | Playwright | Full user journeys through browser |
+
+### CI/CD (GitHub Actions)
+
+Pipeline jobs run in order: unit tests → integration tests → E2E (Docker-based) → deploy (main branch only via SSH + Docker Compose).