1 files changed, 94 insertions, 0 deletions
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..6ca3848
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,94 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Common Commands
+
+### Development
+- **Build**: `make build` or open the project in Xcode and press the run button
+- **Format code**: `make format`
+- **Lint code**: `make lint`
+- **Run tests**: `make test` or use Xcode's test navigator or ⌘+U
+
+### Distribution
+- **Create full distribution**: `make distribute`
+- **Archive for distribution**: `make archive`
+- **Package app**: `make package`
+
+## Architecture Overview
+
+### Core Structure
+This is a SwiftUI-based macOS application for creating Wardley Maps using a text-based domain-specific language.
+
+**Key Components:**
+- **MapDocument**: Document-based app architecture using SwiftUI's `FileDocument` protocol
+- **MapParser**: Text-to-diagram parsing engine with strategy pattern
+- **MapEditor**: Main editing interface with split view (text editor + visual map)
+- **MapRenderView**: SwiftUI view that renders the visual map
+
+### Data Flow
+1. User types text in `MapTextEditor`
+2. `MapParser` parses text using parser strategies
+3. Parsed data creates `ParsedMap` with vertices, edges, notes, etc.
+4. `MapRenderView` renders the visual representation
+5. Changes are automatically saved via document architecture
+
+### Parser Architecture
+The parser uses a strategy pattern with these components:
+- `MapParserStrategy` protocol for parsing different element types
+- Individual strategies: `VertexParserStrategy`, `EdgeParserStrategy`, `NoteParserStrategy`, etc.
+- `MapBuilder` accumulates parsed elements into final `ParsedMap`
+
+### Key Data Models
+- **Vertex**: Map nodes with position and label
+- **MapEdge**: Connections between vertices (with/without arrowheads)
+- **Note**: Text annotations at specific positions
+- **Blocker**: Obstacles placed in front of vertices
+- **Opportunity**: Evolution arrows showing movement
+- **Stage**: Different evolution frameworks (general, practice, data, etc.)
+
+### UI Architecture
+- **MapEditor**: Main container with adaptive layout (horizontal/vertical split)
+- **MapTextEditor**: Text editing with syntax highlighting and search
+- **MapRenderView**: Visual map rendering with zoom and pan
+- **EvolutionPicker**: Dropdown for selecting evolution framework
+- **SearchBar**: Text search functionality with highlight navigation
+
+## Map Language Reference
+
+The app uses a domain-specific language for creating Wardley Maps:
+
+### Basic Elements
+- **Nodes**: `Name (x,y)` where x,y are 0-100 coordinates
+- **Edges**: `Node -- Node` (line) or `Node -> Node` (arrow)
+- **Blockers**: `[Blocker] Node`
+- **Evolution**: `[Evolution] Node +/-x`
+- **Notes**: `[Note] (x,y) Text`
+- **Groups**: `[Group] NodeA, NodeB, NodeC`
+- **Axes**: `[I] x`, `[II] x`, `[III] x` for custom stage boundaries
+
+### File Format
+- Files use `.wmap` extension with UTI `systems.tranquil.map.wmap`
+- Plain text format parsed line by line
+- Each line can contain one map element
+
+## Development Notes
+
+### Testing
+- Unit tests are in `MapTests/MapTests.swift`
+- UI tests are in `MapUITests/`
+- Run tests with ⌘+U in Xcode
+
+### Auto-Updates
+- Uses Sparkle framework for automatic updates
+- Configuration in `Info.plist` and update commands
+
+### Code Style
+- Uses swift-format for consistent formatting
+- Run `make format` before committing
+- All Swift files include GPL license header
+
+### Key Dependencies
+- SwiftUI for UI framework
+- Sparkle for auto-updates
+- CoreGraphics for rendering calculations
+\ No newline at end of file