Add CLAUDE.md for Claude Code guidance

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,96 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+CutList is a Windows Forms 1D bin packing optimization application that helps users optimize material cutting. It calculates efficient bin packing solutions to minimize waste when cutting stock materials into required parts.
+
+**Framework**: .NET 8.0 (Windows Forms)
+**Key Dependencies**: Math-Expression-Evaluator (input parsing), Newtonsoft.Json (serialization)
+
+## Build Commands
+
+```bash
+# Build entire solution
+dotnet build CutList.sln
+
+# Build specific project
+dotnet build CutList/CutList.csproj
+dotnet build CutList.Core/CutList.Core.csproj
+
+# Run the application
+dotnet run --project CutList/CutList.csproj
+
+# Clean build
+dotnet clean CutList.sln
+```
+
+## Architecture
+
+### Project Structure
+
+- **CutList/** - Main Windows Forms application (UI layer)
+- **CutList.Core/** - Core library with domain models and packing algorithms (shareable, platform-agnostic)
+
+### Key Patterns
+
+**MVP (Model-View-Presenter)**
+- `MainForm` implements `IMainView` (pure UI, no business logic)
+- `MainFormPresenter` orchestrates all business logic
+- `Document` contains application state
+
+**Result Pattern**
+- `Result<T>` in Common/Result.cs for standardized error handling
+- Use `Result<T>.Success(value)` and `Result<T>.Failure(error)` instead of exceptions for expected errors
+
+**Factory Pattern**
+- `IEngineFactory` creates packing engines
+- Allows swapping algorithm implementations
+
+### Data Flow
+
+1. User enters parts/bins in MainForm
+2. MainFormPresenter calls CutListService.Pack()
+3. CutListService converts input models to core models (MultiBin, BinItem)
+4. MultiBinEngine coordinates packing across bin types
+5. AdvancedFitEngine performs 1D bin packing (first-fit decreasing with optimization)
+6. Results displayed in ResultsForm
+
+### Key Services
+
+- **CutListService**: Bridges UI models to core packing algorithms
+- **DocumentService**: JSON file persistence
+
+### Domain Models (CutList.Core)
+
+- **BinItem**: Item to be packed (with label, length)
+- **MultiBin**: Stock bin type with length, quantity (-1 = unlimited), priority
+- **Bin**: Packed bin containing items
+- **Tool**: Cutting tool with kerf/blade width
+
+### Unit Handling
+
+- **ArchUnits**: Converts feet/inches/fractions to decimals (accepts "12'", "6\"", "12 1/2\"", etc.)
+- **FormatHelper**: Converts decimals to mixed fractions for display
+- Internal calculations use inches; format on display
+
+## Important Conventions
+
+- **Nullable reference types enabled** - handle nulls explicitly
+- **Collections are encapsulated** - use AsReadOnly(), access via Add* methods
+- **Validation in domain models** - constructors and properties validate inputs
+- **Parameterless constructors** on Tool/MultiBin are for JSON serialization only
+- **Spacing property** on engines handles blade/kerf width
+- **Priority system**: Lower priority bins are used first
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `Presenters/MainFormPresenter.cs` | Main business logic orchestrator |
+| `Services/CutListService.cs` | Packing algorithm interface |
+| `CutList.Core/Nesting/AdvancedFitEngine.cs` | Core packing algorithm |
+| `CutList.Core/Nesting/MultiBinEngine.cs` | Multi-bin orchestration |
+| `CutList.Core/ArchUnits.cs` | Unit conversion |
+| `CutList.Core/FormatHelper.cs` | Output formatting |