diff --git a/CLAUDE.md b/CLAUDE.md
index 43c994c..a771f79 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1 +1,49 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
@AGENTS.md
+
+## Commands
+
+```bash
+npm run dev # start dev server at localhost:3000
+npm run build # production build
+npm run lint # ESLint (no test suite exists yet)
+```
+
+## Architecture
+
+This is a single-page admin console for managing AI video assistants. It is a Next.js 16 app using the App Router, React 19, Tailwind CSS v4, and shadcn components backed by Radix UI primitives.
+
+**Navigation model** — the app has no Next.js routes beyond `/`. All "pages" are React components in `src/components/pages/` that are conditionally rendered by `AppShell` based on a `NavKey` state value. `AppShell` owns the active page and sidebar-collapsed state and threads them down as props.
+
+**Component layers:**
+- `src/app/` — Next.js entry: `layout.tsx` (fonts, theme-flash script, metadata) and `page.tsx` (renders ``)
+- `src/components/layout/` — `AppShell` (page-switching shell), `Sidebar` (collapsible nav, 252 → 76px), `Topbar` (theme toggle, notifications), `ThemeToggle`
+- `src/components/pages/` — one component per nav section; `PlaceholderPage` is a shared editorial header for unimplemented pages
+- `src/components/ui/` — shadcn primitives (button, card, badge, dialog, etc.)
+- `src/hooks/` — `use-mobile.ts`
+- `src/lib/utils.ts` — `cn()` (clsx + tailwind-merge)
+- `src/data/mock.ts` — static mock data (no API layer yet)
+
+**Path alias** — `@/` maps to `src/`.
+
+## Design System
+
+`DESIGN.md` is the authoritative spec. `src/app/globals.css` is the implementation — it sets the CSS custom properties consumed by all Tailwind utilities. Key rules:
+
+- **Two themes from one navy palette.** Dark navy is the default (applied via `` and a no-flash `localStorage` script in `layout.tsx`). Light is cool off-white. Toggle is a `ThemeToggle` component in `Topbar`.
+- **Never hardcode hex values.** Drive color from semantic tokens: `bg-background`, `text-foreground`, `bg-card`, `text-ink`, `border-hairline`, `bg-surface-strong`, `text-muted-foreground`, etc.
+- **Display typography** uses Cormorant Garamond (`--font-display`, `font-weight: 300`). Apply via the `.font-display` class or `.display-{mega|xl|lg|md|sm}` size helpers. **Never bold display copy.**
+- **Body typography** uses Inter (`--font-sans`, `font-weight: 400/500`).
+- **All CTAs and nav items are pill-shaped** (`rounded-full`). Cards use `rounded-2xl`; hero bands use `rounded-3xl`.
+- **Gradient orbs** (mint, peach, lavender, sky, rose) are atmosphere-only — they appear as blurred `radial-gradient` backgrounds on hero panels and brand/avatar icons, never as button fills or text colors.
+
+## Theming Implementation
+
+`globals.css` defines `:root` (light) and `.dark` variable blocks. All shadcn variables (`--background`, `--card`, `--primary`, `--border`, …) plus editorial extras (`--ink`, `--canvas-soft`, `--surface-strong`, `--hairline*`, `--gradient-*`, `--body-text`) are declared there. The `@theme inline` block wires them into Tailwind utilities.
+
+## shadcn / Radix
+
+`components.json` configures shadcn with style `radix-luma`. Add new primitives via `npx shadcn add ` — they land in `src/components/ui/`. Icon library is Lucide React.