diff --git a/CLAUDE.md b/CLAUDE.md
index 2632325..0366b33 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -180,15 +180,20 @@ See `docs/ARCHITECTURE.md` for full schema. Key tables:
 - `carts` / `cart_items` - Shopping cart
 - `orders` / `order_items` - Orders and line items
 - **`roles`** - Role definitions (private, educator, company)
+  - **Primary Key:** `code` (enum: 'private' | 'educator' | 'company') - No separate UUID id!
+  - Benefit: Direct readability in junction tables
 - **`user_roles`** - Many-to-Many User ↔ Roles (with approval workflow prepared for Phase 2/3)
+  - Foreign Key: `roleCode` references `roles.code`
 - **`product_role_visibility`** - Many-to-Many Product ↔ Roles (controls product visibility)
+  - Foreign Key: `roleCode` references `roles.code`
 
 **Role-based Visibility (MVP):**
 - Products are ONLY visible if they have `product_role_visibility` entries
 - Users ONLY see products matching their approved roles in `user_roles`
 - Opt-in visibility: No role assignment = invisible to everyone
+- **Auto-assignment:** New users automatically receive `'private'` role on first login
 
-Use Drizzle ORM for all database operations. All tables use UUID primary keys.
+Use Drizzle ORM for all database operations. Most tables use UUID primary keys (except `roles` which uses enum code as PK).
 
 ## Development Commands (Once Set Up)