docs: add DEAR_LLM.md with repository context for AI agents
Create a concise overview document to help AI agents understand
the Sketch repository architecture, components, and common development
workflows. Includes information about the dual binary pattern,
container system, and development gotchas that would be helpful
context for future AI assistance.
Co-Authored-By: sketch <hello@sketch.dev>
diff --git a/DEAR_LLM.md b/DEAR_LLM.md
new file mode 100644
index 0000000..71a4298
--- /dev/null
+++ b/DEAR_LLM.md
@@ -0,0 +1,68 @@
+# DEAR_LLM.md for Sketch Repository
+
+## Repository Architecture
+
+Sketch is an agentic coding tool with a multi-layer architecture:
+
+1. **Outer Sketch**: The CLI command (`sketch`) running on the user's machine
+2. **Inner Sketch**: The binary running inside Docker containers
+3. **Container System**: Docker containers isolate work environments
+
+## Key Components
+
+### Outer Sketch (Host)
+
+- **cmd/sketch/main.go**: Entry point and CLI definitions
+- **dockerimg/**: Container management (building, configuration, orchestration)
+
+### Inner Sketch (Container)
+
+- **loop/agent.go**: Core agent logic and tool implementations
+- **loop/server/**: Server implementation inside containers
+
+### Shared Components
+
+- **webui/**: Web-based user interface components
+- **llm/**: Language model interaction
+
+## Development Workflows
+
+### Development Modes
+
+1. **Container Mode** (Default): `go run ./cmd/sketch -C /path/to/codebase`
+
+ - Creates Docker container for code analysis
+ - Safe and isolated environment
+
+2. **Unsafe Mode**: `go run ./cmd/sketch -unsafe -C /path/to/codebase`
+ - Runs directly on host OS without containerization
+ - Useful for quick testing during development
+
+### Source/Container Relationship
+
+- Target codebase: Copied into container via `COPY . /app`
+- Sketch itself: Binary built specifically for containers (`GOOS=linux`)
+- Container configuration: Generated based on target codebase detection
+
+## Common Gotchas
+
+1. **Container Caching**: Docker image caching may require `-force-rebuild-container` when the target codebase changes
+
+2. **Two Git Contexts**:
+
+ - Sketch's own repository (where outer and inner Sketch code lives)
+ - The target repository being analyzed by Sketch
+ - Keep these separate in your mental model
+
+3. **Inner/Outer Code Changes**:
+ - Changes to inner Sketch (loop/agent.go) are built into the Linux binary for containers
+ - Changes to outer Sketch (dockerimg/) affect how containers are created
+
+## Flags and Settings
+
+- `-unsafe`: Run without containerization
+- `-force-rebuild-container`: Force Docker image rebuilding
+- `-verbose`: Show detailed output and logs
+- `-C /path/to/repo`: Specify target codebase path
+
+See CONTRIBUTING.md for additional development guidance.