diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..65f67aa
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,48 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build
+
+```bash
+uv run build.py
+```
+
+Regenerates all theme files from `src/*.yaml` via Jinja2 templates into `dist/`. There is no watch mode — rerun after any YAML or template change. Python 3.12+ required; dependencies managed via `uv` (`pyproject.toml`).
+
+## Architecture
+
+Apex is a **theme factory** — a build system that generates native theme configs for 14+ applications from a single semantic color specification.
+
+**Data flow:**
+1. `src/neon.yaml` and `src/aeon.yaml` define the canonical color palette and semantic roles
+2. `templates/<app>/*.j2` define per-application output formats (Lua, JSON, TOML, CSS, Conf, etc.)
+3. `templates/<app>/meta.yaml` controls the build strategy:
+   - `strategy: individual` → outputs `apex-neon.<ext>` and `apex-aeon.<ext>` separately
+   - `strategy: aggregated` → outputs a single file containing both schemes (e.g., `apex.json` for Zed)
+4. `build.py` orchestrates rendering; `dist/` holds all generated artifacts (gitignored)
+
+**Adding a new app target:** create `templates/<app>/`, add a `meta.yaml` with strategy, write `.j2` templates using the YAML variables, then run the build.
+
+## Theme Design Rules
+
+`GEMINI.md` is the authoritative source of truth for color semantics. Key axioms:
+
+- **Red (`#ff0044`) = Active Intent** — cursor, current location, selection, critical errors. Text on red backgrounds must be `#050505` (Neon) or `#0a0a0a` (Aeon).
+- **Cyan = Informational** — never use for errors or destruction.
+- **Purple = Sacred** — reserved for root access and exceptional system states.
+- **Bright ANSI variants (8–15)** are for escalated/active states only.
+- Do not introduce colors without a semantic reason. If it has no signal purpose, remove it.
+
+Before modifying `src/*.yaml`, consult `GEMINI.md` to verify that any new or changed role fits the semantic palette.
+
+## Conventions
+
+- Commit style: Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`)
+- Template output names: `apex-<scheme>.<ext>` for individual; base name for aggregated
+- YAML keys in `src/`: keep consistent with existing semantic roles; add new roles only when truly necessary
+- `dist/` is build output — never edit by hand
+
+## Validation
+
+After changes, run `uv run build.py` and inspect relevant files in `dist/`. For Neovim-specific validation, `scripts/nvim-audit.sh` is available.