1 files changed, 100 insertions, 0 deletions
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..f0e72ae
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,100 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+This is `dots`, a dotfiles manager that combines Jinja2 templating with GNU Stow for symlink management. It enables maintaining a single set of dotfiles across multiple machines by using context-driven templating.
+
+## Core Architecture
+
+### Three-Phase Process
+
+1. **Compile**: Templates in `dots/` (files ending in `.j2`) are rendered using Jinja2 with context from `context.json`, output to `.compiled_dotfiles/`
+2. **Stow**: Compiled packages are symlinked to the target directory (default: `$HOME`) using GNU Stow
+3. **Clean**: Removes symlinks and clears `.compiled_dotfiles/`
+
+### Directory Structure
+
+- `dots/`: Source dotfiles organized as Stow packages (e.g., `nvim/`, `git/`, `sway/`)
+- `.compiled_dotfiles/`: Generated output after template compilation (git-ignored)
+- `dots_manager/`: Python package implementing the CLI tool
+- `context.json`: Configuration variables organized by platform and system
+
+### Context System
+
+`context.json` structure:
+```json
+{
+  "_global": { /* shared across all systems */ },
+  "osx": {
+    "_default": { /* defaults for all macOS systems */ },
+    "system_name": { /* specific system config */ }
+  },
+  "linux": { /* similar structure */ }
+}
+```
+
+Context merging: `_global` → `platform._default` → `platform.system_name`
+
+Templates access context variables directly: `{{ env.EDITOR }}`, `{{ window_manager.key.sup }}`
+
+### Key Modules
+
+- `cli.py`: Entry point, orchestrates compile/stow/clean operations
+- `config.py`: Loads context, detects platform/system via helper scripts in `dots/home/scripts/`
+- `template.py`: Jinja2 rendering with parallel processing
+- `stow.py`: Wraps GNU Stow commands for symlinking
+- `utils.py`: Parallelization and dictionary merging utilities
+
+## Common Commands
+
+### Setup
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+### Basic Usage
+```bash
+# Compile templates only
+dots --compile
+
+# Compile and stow
+dots --compile --stow
+
+# Remove symlinks and clean compiled files
+dots --clean
+
+# Full cycle with verbose output
+dots --clean --compile --stow --verbose
+```
+
+### Development/Testing
+```bash
+# Test with custom context file
+dots --compile --context ./test_context.json
+
+# Dry-run compilation (templates rendered but not stowed)
+dots --compile --output /tmp/test_dots
+
+# Override platform/system detection
+dots --compile --platform linux --system-name test-machine
+```
+
+## Important Implementation Details
+
+- Template files must have `.j2` extension; compiled output strips this extension
+- Jinja2 uses `StrictUndefined` - missing context variables will error during compilation
+- File permissions are preserved from templates to compiled files
+- Stow operations use `--no-folding` to prevent directory folding
+- Platform detection uses `$OSTYPE`; system name uses hostname or macOS `computername`
+- Template compilation is parallelized (workers = CPU count × 2)
+
+## When Working with Templates
+
+- Templates are in `dots/` as `<package>/<path>/<file>.j2`
+- After compilation, they appear in `.compiled_dotfiles/<package>/<path>/<file>` (no `.j2`)
+- Test context changes by running `dots --compile` and checking `.compiled_dotfiles/`
+- Never edit files in `.compiled_dotfiles/` directly - they are regenerated on compile