diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..645017e
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,105 @@
+# Forge - Structured CSS Authoring
+
+A typed, local, variant-driven way to author CSS. Compiles to real CSS but removes the chaos: no global conflicts, no selector gymnastics, no inline styles. Built for Hono JSX with SSR support.
+
+## The Problem
+
+CSS is hostile to humans at scale: global namespace, no markup-to-definition link, requires inline styles for per-instance variance, silent conflicts, selector complexity.
+
+## The Solution
+
+- **Local styles** - Attached via generated class names, not strings
+- **Parts** - Named sub-components replace selectors (no `.Button > .Icon` nonsense)
+- **Variants** - Typed parameters replace inline styles (no `style={{ color: x }}`)
+- **Deterministic** - Known merge order, dev warnings for conflicts
+- **Compiles to CSS** - Not a new language, not runtime CSS-in-JS, just organized CSS generation
+
+## Core Concepts
+
+**`define(name?, def)`** - Creates a styled component. Returns a component function.
+- Accepts CSS properties in camelCase (auto-converts to kebab-case)
+- Numbers auto-converted to `px` (except unitless props like `opacity`, `zIndex`)
+- Generates CSS classes and registers styles globally
+
+**Parts** - Sub-components within a component (e.g., Header, Body, Footer)
+- Defined via `parts: { PartName: { ...styles } }`
+- Accessible in render as `parts.PartName`
+- Generate classes like `ComponentName_PartName`
+
+**Variants** - Conditional styling based on props
+- Boolean: `variants: { active: { color: 'blue' } }` → ``
+- Keyed: `variants: { size: { small: {...}, large: {...} } }` → ``
+- Work on both root and parts
+- Generate classes like `ComponentName.variant-key`
+
+**States** - Pseudo-selectors like hover, focus
+- `states: { hover: { background: 'blue' } }` → `.Class:hover { ... }`
+
+**Custom Render** - Override default rendering
+- `render({ props, parts }) { return ... }`
+- Compose parts manually, pass props through
+
+## File Structure
+
+- `src/index.tsx` - Main implementation (`define`, `Styles`, CSS generation)
+- `src/types.ts` - `TagDef` type with all CSS properties, helper sets
+- **`examples/`** - **REFERENCE THESE** for real-world usage patterns:
+ - `helpers.tsx` - Layout wrapper, reusable components (Body, Header, ThemeToggle)
+ - `index.tsx` - Landing page with grid, cards, parts, and custom render
+ - `button.tsx` - Button variants (intent, size, disabled)
+ - `profile.tsx` - Complex component with multiple parts and variants
+ - `navigation.tsx` - Tabs, pills, breadcrumbs, vertical nav patterns
+- `src/tests/` - Comprehensive test suite with test helpers
+
+## Implementation Details
+
+- **Static CSS generation** - CSS created at component definition time, not runtime
+- **Global styles registry** - `styles` object stores all CSS as plain objects
+- **`Styles` component** - Renders `