diff --git a/CLAUDE.md b/CLAUDE.md
index 6631e4e..8723eac 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,7 +4,24 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-**Directory MapView** - Map-style directory navigator with zoom and pan
+**Directory MapView** - A reimagined file picker dialog that displays the filesystem like a road map.
+
+### Vision
+
+Traditional file dialogs show directories as indented trees or lists. You never see what's beside you or the broader context. Directory MapView changes this:
+
+- Directories appear as connected pathways/roads with labels
+- Current path highlighted like a navigation route
+- "You are here" marker at current location
+- Zoom out to see the big picture, zoom in for details
+- Pan around to explore like Google Maps
+
+### Interaction Model
+
+- **Mouse wheel**: Zoom in/out
+- **Left-click + drag**: Pan the view
+- **Click on directory**: Navigate there
+- **Hover**: Show directory info
 
 ## Development Commands
 
@@ -15,21 +32,31 @@ pip install -e ".[dev]"
 # Run tests
 pytest
 
-# Run a single test
-pytest tests/test_file.py::test_name
+# Run the demo
+python -m dir_mapview.demo
 ```
 
 ## Architecture
 
-*TODO: Describe the project architecture*
+### Technical Approach
+
+- **PyQt6/PySide6** for the widget
+- **QGraphicsScene** for zoomable/pannable canvas
+- **Tree layout algorithm** for positioning directories
+- Lazy loading for large filesystems
+- Caching for performance
 
 ### Key Modules
 
-*TODO: List key modules and their purposes*
+- `src/dir_mapview/widget.py` - Main MapView widget (QGraphicsView subclass)
+- `src/dir_mapview/scene.py` - Scene management and directory rendering
+- `src/dir_mapview/layout.py` - Directory tree layout algorithm
+- `src/dir_mapview/scanner.py` - Filesystem scanning with lazy loading
+- `src/dir_mapview/dialog.py` - Drop-in file picker dialog replacement
 
 ### Key Paths
 
-- **Source code**: `src/dir-mapview/`
+- **Source code**: `src/dir_mapview/`
 - **Tests**: `tests/`
 - **Documentation**: `docs/` (symlink to project-docs)