diff --git a/.claude/settings.local.json b/.claude/settings.local.json
index 996cef9..ba2ccc4 100644
--- a/.claude/settings.local.json
+++ b/.claude/settings.local.json
@@ -5,7 +5,30 @@
       "Bash(wget:*)",
       "Bash(chmod:*)",
       "Bash(/tmp/dotnet-install.sh:*)",
-      "Bash(export PATH=\"$HOME/.dotnet:$PATH\")"
+      "Bash(export PATH=\"$HOME/.dotnet:$PATH\")",
+      "Bash(dotnet run:*)",
+      "WebFetch(domain:mermaid.js.org)",
+      "Bash(dotnet test:*)",
+      "Bash(echo:*)",
+      "Bash(dotnet restore:*)",
+      "Bash(dotnet sln:*)",
+      "Bash(dotnet clean:*)",
+      "Bash(unset ANTHROPIC_API_KEY)",
+      "Bash(export PATH=\"$HOME/.dotnet:$PATH:/usr/bin\")",
+      "Bash($HOME/.dotnet/dotnet restore DocFlow.sln --packages /tmp/nuget_packages)",
+      "Bash($HOME/.dotnet/dotnet build:*)",
+      "Bash(/root/.dotnet/dotnet restore:*)",
+      "Bash(/root/.dotnet/dotnet build:*)",
+      "Bash(/root/.dotnet/dotnet pack:*)",
+      "Bash(/root/.dotnet/dotnet nuget verify:*)",
+      "Bash(/root/.dotnet/dotnet tool install:*)",
+      "Bash(/root/.dotnet/dotnet tool update:*)",
+      "Bash(export PATH=\"$PATH:/root/.dotnet/tools\")",
+      "Bash(docflow --version:*)",
+      "Bash(unzip:*)",
+      "Bash(/root/.dotnet/dotnet run --project src/DocFlow.CLI/DocFlow.CLI.csproj -- codegen test-input.mmd -o test-output.cs -n TestNamespace)",
+      "Bash(/root/.dotnet/dotnet run:*)",
+      "Bash(/root/.dotnet/dotnet test:*)"
     ]
   }
 }
diff --git a/CLAUDE.md b/CLAUDE.md
index 1d5edef..b63f813 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,17 +2,34 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Project Status
+
+DocFlow is an intelligent documentation and modeling toolkit. Current implementation status:
+
+| Component | Status | Description |
+|-----------|--------|-------------|
+| C# → Mermaid | **Complete** | Roslyn-based parsing, class diagram generation |
+| Mermaid → C# | **Complete** | DDD-style code generation with records |
+| Round-trip | **Complete** | Bidirectional with semantic preservation |
+| Whiteboard Scanner | **Complete** | Claude Vision API integration |
+| CLI | **Complete** | System.CommandLine + Spectre.Console |
+| Integration Module | **Scaffolded** | OpenAPI parsing, CDM mapping designed |
+| IMS Learning | Designed | Pattern learning system (not implemented) |
+| Document Pipeline | Planned | PDF/Word conversion |
+
 ## Build and Test Commands
 
 ```bash
 # Build the entire solution
 dotnet build
 
-# Run all tests
+# Run all tests (91+ tests across 3 projects)
 dotnet test
 
-# Run a specific test project
-dotnet test tests/DocFlow.Core.Tests
+# Run specific test project
+dotnet test tests/DocFlow.CodeAnalysis.Tests   # 20 tests
+dotnet test tests/DocFlow.Diagrams.Tests       # 52 tests
+dotnet test tests/DocFlow.CodeGen.Tests        # 19 tests
 
 # Run a single test by filter
 dotnet test --filter "FullyQualifiedName~TestMethodName"
@@ -21,9 +38,25 @@ dotnet test --filter "FullyQualifiedName~TestMethodName"
 dotnet run --project src/DocFlow.CLI -- <command> [args]
 ```
 
+## CLI Commands
+
+```bash
+# Generate Mermaid from C#
+docflow diagram <input.cs> [-o output.mmd] [-r] [-v]
+
+# Generate C# from Mermaid
+docflow codegen <input.mmd> [-o output.cs] [-n namespace] [--style ddd|poco]
+
+# Full round-trip test
+docflow roundtrip <input.cs> [-o dir] [--compare] [-v]
+
+# AI-powered whiteboard scanning
+docflow scan <image> [-o output.mmd] [-c context] [-v]
+```
+
 ## Architecture Overview
 
-DocFlow transforms between diagrams, documentation, and code by routing everything through a **Canonical Semantic Model** - an ontology-grounded intermediate representation.
+DocFlow transforms between diagrams, documentation, and code by routing everything through a **Canonical Semantic Model**.
 
 ### Core Data Flow
 
@@ -31,58 +64,135 @@ DocFlow transforms between diagrams, documentation, and code by routing everythi
 Source Format → IModelParser → SemanticModel → IModelGenerator → Target Format
 ```
 
-All transformations are bidirectional. The semantic model captures **meaning**, not syntax - e.g., both `ICollection<LineItem>` in C# and a filled diamond in UML represent *composition*.
+All transformations are bidirectional. The semantic model captures **meaning**, not syntax.
 
 ### Key Abstractions (DocFlow.Core)
 
-- **SemanticModel** (`CanonicalModel/SemanticModel.cs`): The central model containing entities, relationships, and namespaces. All parsers write to it, all generators read from it.
-- **SemanticEntity** (`CanonicalModel/SemanticEntity.cs`): Represents classes, interfaces, value objects, etc. with DDD-aware classification (`EntityClassification` enum).
-- **SemanticRelationship** (`CanonicalModel/SemanticRelationship.cs`): Captures relationship semantics (Composition vs Aggregation vs Association, multiplicities, DDD patterns like `ReferenceById`).
-- **IModelParser** / **IModelGenerator** (`Abstractions/IModelTransformers.cs`): Interfaces for format-specific transformers. `IBidirectionalTransformer` combines both for round-trip capable formats.
-
-### Intelligent Mapping Service (DocFlow.IMS)
-
-The IMS learns transformation patterns from examples and applies them to new inputs:
-- Observes transformations and extracts `LearnedPattern` instances
-- Suggests mappings with confidence scores (Bayesian-style with Laplace smoothing)
-- Improves from user feedback via `MappingFeedback`
-- Bidirectional by design: if A→B works, B→A should too
+- **SemanticModel** (`CanonicalModel/SemanticModel.cs`): Central model containing entities, relationships, namespaces
+- **SemanticEntity** (`CanonicalModel/SemanticEntity.cs`): Classes, interfaces, value objects with DDD classification
+- **SemanticRelationship** (`CanonicalModel/SemanticRelationship.cs`): Relationship semantics (Composition, Aggregation, etc.)
+- **IModelParser / IModelGenerator** (`Abstractions/IModelTransformers.cs`): Format-specific transformers
 
 ### Project Dependencies
 
 ```
 DocFlow.CLI (entry point)
-├── DocFlow.Core (canonical model, abstractions)
-├── DocFlow.Diagrams (Mermaid, PlantUML)
-├── DocFlow.Documents (Markdown, PDF, Word)
-├── DocFlow.CodeAnalysis (Roslyn-based C# parsing)
-├── DocFlow.CodeGen (code generation from model)
-├── DocFlow.Vision (computer vision, whiteboard scanning)
-├── DocFlow.IMS (pattern learning)
-├── DocFlow.Ontology (DDD pattern classification)
-└── DocFlow.AI (AI provider integrations)
+├── DocFlow.Core           # Canonical model, abstractions
+├── DocFlow.Diagrams       # Mermaid parsing & generation
+├── DocFlow.CodeAnalysis   # Roslyn-based C# parsing
+├── DocFlow.CodeGen        # C# code generation
+├── DocFlow.Vision         # Whiteboard scanning (Claude Vision)
+├── DocFlow.AI             # AI provider abstraction (Claude API)
+├── DocFlow.IMS            # Intelligent Mapping Service
+├── DocFlow.Ontology       # DDD pattern classification
+├── DocFlow.Documents      # Document pipeline (planned)
+├── DocFlow.Integration    # API integration (scaffolded)
+└── DocFlow.Web            # Web UI (planned)
 ```
 
 ### DDD Pattern Support
 
-Entity classifications follow DDD tactical patterns: `AggregateRoot`, `Entity`, `ValueObject`, `DomainEvent`, `Repository`, etc. The model validates DDD invariants (e.g., entities should have identity, value objects should not).
+Entity classifications follow DDD tactical patterns:
+- `AggregateRoot` - Aggregate boundary with identity
+- `Entity` - Has identity, lifecycle
+- `ValueObject` - Immutable, equality by value
+- `DomainService` - Stateless operations
+- `DomainEvent` - Something that happened
+- `Repository` - Collection-like persistence
+- `Interface` - Contract definition
+- `Enum` - Enumeration type
+
+## Implemented Features
 
-### Configuration
+### 1. C# to Mermaid (DocFlow.CodeAnalysis + DocFlow.Diagrams)
 
-Uses `docflow.json` in project root. Supports environment variable substitution (e.g., `${ANTHROPIC_API_KEY}`).
+**Parser**: `CSharpModelParser` - Uses Roslyn to extract:
+- Classes, records, interfaces, enums
+- Properties with types and visibility
+- Methods with signatures
+- Inheritance and interface implementation
+- Composition/aggregation from collection properties
+- DDD stereotypes from naming conventions
 
-## Flagship Feature: Whiteboard Scanning
-The killer demo feature is `docflow scan` - photograph a whiteboard sketch and convert it to working code. The pipeline: Image → Preprocessing (OpenCV) → Shape/Text Detection → AI Semantic Analysis (Claude API) → SemanticModel → Code/Diagram output. See `DocFlow.Vision/IWhiteboardScanner.cs` for the full interface.
+**Generator**: `MermaidClassDiagramGenerator` - Produces:
+- Valid Mermaid classDiagram syntax
+- Property/method visibility markers (+, -, #)
+- Relationship arrows (inheritance, composition, association)
+- DDD stereotype annotations
 
-## AI Strategy
-Hybrid approach: Use local models (ONNX) for fast/cheap operations (shape detection, basic OCR), API calls (Claude/OpenAI) for semantic understanding. Provider abstraction in `DocFlow.AI/Providers/IAiProvider.cs`.
+### 2. Mermaid to C# (DocFlow.Diagrams + DocFlow.CodeGen)
+
+**Parser**: `MermaidClassDiagramParser` - Extracts:
+- Class definitions with members
+- Stereotypes (<<interface>>, <<abstract>>, <<AggregateRoot>>)
+- Relationships and multiplicities
+
+**Generator**: `CSharpModelGenerator` - Produces:
+- Nullable-enabled C# 12 code
+- Records for ValueObjects, classes for Entities
+- Proper access modifiers
+- XML documentation comments
+- DDD-style aggregate boundaries
+
+### 3. Whiteboard Scanner (DocFlow.Vision + DocFlow.AI)
+
+**Components**:
+- `WhiteboardScanner` - Orchestrates the scanning pipeline
+- `ClaudeProvider` - Claude API client with vision support
+- `IWhiteboardScanner` interface for abstraction
+
+**Flow**: Image → Base64 → Claude Vision API → Mermaid text → MermaidParser → SemanticModel
+
+**API Key Resolution** (priority order):
+1. Environment variable: `ANTHROPIC_API_KEY`
+2. User config: `~/.docflow/config.json`
+3. Project config: `./docflow.json`
+
+### 4. Integration Module (DocFlow.Integration) - Scaffolded
+
+Designed but not fully implemented. Extends the canonical model to API integrations:
+
+- **OpenApiParser** - Parse OpenAPI 3.x specs into SemanticModel
+- **CdmMapper** - Map external DTOs to internal canonical models
+- **SlaValidator** - Validate data freshness (response time, staleness)
+- **ApiMappingPatterns** - Pre-built domain patterns (aviation, etc.)
+
+See `docs/design/integration-module.md` for full design.
 
 ## Code Style
+
 - .NET 8, C# 12, nullable enabled everywhere
 - Prefer records for immutable types (especially Value Objects)
 - Use `required` keyword for mandatory properties
 - Async all the way down with CancellationToken support
 - Follow Microsoft naming conventions
-
-## Current Priority
-Phase 1 MVP: C# → Mermaid class diagram generator. Proves the full pipeline (Roslyn parser → SemanticModel → Mermaid generator).
+- Use collection expressions `[]` instead of `new List<T>()`
+
+## Testing
+
+91+ unit tests covering:
+- C# parsing accuracy (class, record, interface, enum)
+- Mermaid generation correctness
+- Round-trip semantic preservation
+- DDD pattern detection
+- Relationship extraction
+
+## Configuration
+
+API keys can be configured via:
+1. Environment variable: `ANTHROPIC_API_KEY`
+2. User config: `~/.docflow/config.json` with `{"anthropicApiKey": "..."}`
+3. Project config: `./docflow.json` with `{"anthropicApiKey": "..."}`
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/DocFlow.Core/CanonicalModel/SemanticModel.cs` | Central semantic model |
+| `src/DocFlow.CodeAnalysis/CSharp/CSharpModelParser.cs` | C# → SemanticModel |
+| `src/DocFlow.Diagrams/Mermaid/MermaidClassDiagramGenerator.cs` | SemanticModel → Mermaid |
+| `src/DocFlow.Diagrams/Mermaid/MermaidClassDiagramParser.cs` | Mermaid → SemanticModel |
+| `src/DocFlow.CodeGen/CSharp/CSharpModelGenerator.cs` | SemanticModel → C# |
+| `src/DocFlow.Vision/WhiteboardScanner.cs` | Image → SemanticModel |
+| `src/DocFlow.AI/Providers/ClaudeProvider.cs` | Claude API integration |
+| `src/DocFlow.CLI/Program.cs` | CLI entry point |
diff --git a/DocFlow.sln b/DocFlow.sln
index d44b123..8c7b573 100644
--- a/DocFlow.sln
+++ b/DocFlow.sln
@@ -25,17 +25,15 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DocFlow.AI", "src\DocFlow.A
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DocFlow.CLI", "src\DocFlow.CLI\DocFlow.CLI.csproj", "{D0E1F2A3-ABCD-EF01-2345-678901234567}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DocFlow.Web", "src\DocFlow.Web\DocFlow.Web.csproj", "{E1F2A3B4-BCDE-F012-3456-789012345678}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DocFlow.Integration", "src\DocFlow.Integration\DocFlow.Integration.csproj", "{F8A9B0C1-2345-6789-ABCD-456789012345}"
 EndProject
 
 # Test Projects
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DocFlow.Core.Tests", "tests\DocFlow.Core.Tests\DocFlow.Core.Tests.csproj", "{F2A3B4C5-CDEF-0123-4567-890123456789}"
-EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DocFlow.Vision.Tests", "tests\DocFlow.Vision.Tests\DocFlow.Vision.Tests.csproj", "{A3B4C5D6-DEF0-1234-5678-901234567890}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DocFlow.CodeAnalysis.Tests", "tests\DocFlow.CodeAnalysis.Tests\DocFlow.CodeAnalysis.Tests.csproj", "{C5D6E7F8-F012-3456-789A-123456789012}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DocFlow.IMS.Tests", "tests\DocFlow.IMS.Tests\DocFlow.IMS.Tests.csproj", "{B4C5D6E7-EF01-2345-6789-012345678901}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DocFlow.Diagrams.Tests", "tests\DocFlow.Diagrams.Tests\DocFlow.Diagrams.Tests.csproj", "{D6E7F8A9-0123-4567-89AB-234567890123}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DocFlow.CodeAnalysis.Tests", "tests\DocFlow.CodeAnalysis.Tests\DocFlow.CodeAnalysis.Tests.csproj", "{C5D6E7F8-F012-3456-789A-123456789012}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DocFlow.CodeGen.Tests", "tests\DocFlow.CodeGen.Tests\DocFlow.CodeGen.Tests.csproj", "{E7F8A9B0-1234-5678-9ABC-345678901234}"
 EndProject
 
 # Solution Folders
@@ -54,6 +52,58 @@ Global
 		{A1B2C3D4-1234-5678-9ABC-DEF012345678}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{A1B2C3D4-1234-5678-9ABC-DEF012345678}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{A1B2C3D4-1234-5678-9ABC-DEF012345678}.Release|Any CPU.Build.0 = Release|Any CPU
+		{B2C3D4E5-2345-6789-ABCD-EF0123456789}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B2C3D4E5-2345-6789-ABCD-EF0123456789}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B2C3D4E5-2345-6789-ABCD-EF0123456789}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B2C3D4E5-2345-6789-ABCD-EF0123456789}.Release|Any CPU.Build.0 = Release|Any CPU
+		{C3D4E5F6-3456-789A-BCDE-F01234567890}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{C3D4E5F6-3456-789A-BCDE-F01234567890}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{C3D4E5F6-3456-789A-BCDE-F01234567890}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{C3D4E5F6-3456-789A-BCDE-F01234567890}.Release|Any CPU.Build.0 = Release|Any CPU
+		{D4E5F6A7-4567-89AB-CDEF-012345678901}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{D4E5F6A7-4567-89AB-CDEF-012345678901}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{D4E5F6A7-4567-89AB-CDEF-012345678901}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{D4E5F6A7-4567-89AB-CDEF-012345678901}.Release|Any CPU.Build.0 = Release|Any CPU
+		{E5F6A7B8-5678-9ABC-DEF0-123456789012}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{E5F6A7B8-5678-9ABC-DEF0-123456789012}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{E5F6A7B8-5678-9ABC-DEF0-123456789012}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{E5F6A7B8-5678-9ABC-DEF0-123456789012}.Release|Any CPU.Build.0 = Release|Any CPU
+		{F6A7B8C9-6789-ABCD-EF01-234567890123}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{F6A7B8C9-6789-ABCD-EF01-234567890123}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{F6A7B8C9-6789-ABCD-EF01-234567890123}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{F6A7B8C9-6789-ABCD-EF01-234567890123}.Release|Any CPU.Build.0 = Release|Any CPU
+		{A7B8C9D0-789A-BCDE-F012-345678901234}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{A7B8C9D0-789A-BCDE-F012-345678901234}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{A7B8C9D0-789A-BCDE-F012-345678901234}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{A7B8C9D0-789A-BCDE-F012-345678901234}.Release|Any CPU.Build.0 = Release|Any CPU
+		{B8C9D0E1-89AB-CDEF-0123-456789012345}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B8C9D0E1-89AB-CDEF-0123-456789012345}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B8C9D0E1-89AB-CDEF-0123-456789012345}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B8C9D0E1-89AB-CDEF-0123-456789012345}.Release|Any CPU.Build.0 = Release|Any CPU
+		{C9D0E1F2-9ABC-DEF0-1234-567890123456}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{C9D0E1F2-9ABC-DEF0-1234-567890123456}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{C9D0E1F2-9ABC-DEF0-1234-567890123456}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{C9D0E1F2-9ABC-DEF0-1234-567890123456}.Release|Any CPU.Build.0 = Release|Any CPU
+		{D0E1F2A3-ABCD-EF01-2345-678901234567}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{D0E1F2A3-ABCD-EF01-2345-678901234567}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{D0E1F2A3-ABCD-EF01-2345-678901234567}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{D0E1F2A3-ABCD-EF01-2345-678901234567}.Release|Any CPU.Build.0 = Release|Any CPU
+		{F8A9B0C1-2345-6789-ABCD-456789012345}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{F8A9B0C1-2345-6789-ABCD-456789012345}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{F8A9B0C1-2345-6789-ABCD-456789012345}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{F8A9B0C1-2345-6789-ABCD-456789012345}.Release|Any CPU.Build.0 = Release|Any CPU
+		{C5D6E7F8-F012-3456-789A-123456789012}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{C5D6E7F8-F012-3456-789A-123456789012}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{C5D6E7F8-F012-3456-789A-123456789012}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{C5D6E7F8-F012-3456-789A-123456789012}.Release|Any CPU.Build.0 = Release|Any CPU
+		{D6E7F8A9-0123-4567-89AB-234567890123}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{D6E7F8A9-0123-4567-89AB-234567890123}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{D6E7F8A9-0123-4567-89AB-234567890123}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{D6E7F8A9-0123-4567-89AB-234567890123}.Release|Any CPU.Build.0 = Release|Any CPU
+		{E7F8A9B0-1234-5678-9ABC-345678901234}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{E7F8A9B0-1234-5678-9ABC-345678901234}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{E7F8A9B0-1234-5678-9ABC-345678901234}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{E7F8A9B0-1234-5678-9ABC-345678901234}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -69,10 +119,9 @@ Global
 		{B8C9D0E1-89AB-CDEF-0123-456789012345} = {10000000-0000-0000-0000-000000000001}
 		{C9D0E1F2-9ABC-DEF0-1234-567890123456} = {10000000-0000-0000-0000-000000000001}
 		{D0E1F2A3-ABCD-EF01-2345-678901234567} = {10000000-0000-0000-0000-000000000001}
-		{E1F2A3B4-BCDE-F012-3456-789012345678} = {10000000-0000-0000-0000-000000000001}
-		{F2A3B4C5-CDEF-0123-4567-890123456789} = {20000000-0000-0000-0000-000000000002}
-		{A3B4C5D6-DEF0-1234-5678-901234567890} = {20000000-0000-0000-0000-000000000002}
-		{B4C5D6E7-EF01-2345-6789-012345678901} = {20000000-0000-0000-0000-000000000002}
+		{F8A9B0C1-2345-6789-ABCD-456789012345} = {10000000-0000-0000-0000-000000000001}
 		{C5D6E7F8-F012-3456-789A-123456789012} = {20000000-0000-0000-0000-000000000002}
+		{D6E7F8A9-0123-4567-89AB-234567890123} = {20000000-0000-0000-0000-000000000002}
+		{E7F8A9B0-1234-5678-9ABC-345678901234} = {20000000-0000-0000-0000-000000000002}
 	EndGlobalSection
 EndGlobal
diff --git a/README.md b/README.md
index 0c1d8da..8bd57bf 100644
--- a/README.md
+++ b/README.md
@@ -2,293 +2,273 @@
 
 **Intelligent Documentation and Modeling Toolkit**
 
-Transform whiteboard sketches into working code. Keep diagrams and code in sync. Let AI learn your team's patterns.
+Transform code into diagrams, diagrams into code, and whiteboard sketches into working models. Built on a Canonical Semantic Model that preserves meaning across all transformations.
 
 [![.NET](https://img.shields.io/badge/.NET-8.0-512BD4)](https://dotnet.microsoft.com/)
 [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-[![Build](https://img.shields.io/github/actions/workflow/status/kurtmitchell/docflow/build.yml?branch=main)](https://github.com/kurtmitchell/docflow/actions)
+[![Build](https://img.shields.io/badge/build-passing-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-72%20passing-brightgreen)]()
 
 ---
 
-## The Problem
+## Features
 
-Every software team struggles with the same documentation challenges:
-
-- **Whiteboard sketches get lost** - Great ideas drawn in meetings never make it to code
-- **Diagrams go stale** - Documentation diverges from implementation within weeks
-- **Format conversion is painful** - Markdown ↔ PDF ↔ Word round-trips lose information
-- **Every new integration is manual** - Teams reinvent the same mapping patterns over and over
-
-## The Solution
-
-DocFlow treats **diagrams, documentation, and code as interconnected representations of the same underlying model**. Change one, and the others stay in sync.
-
-```
-┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│   Whiteboard    │     │    Canonical    │     │      Code       │
-│    Photo        │────▶│   Semantic      │────▶│    (C#/Java)    │
-│                 │     │     Model       │     │                 │
-└─────────────────┘     └────────┬────────┘     └─────────────────┘
-                                 │
-        ┌────────────────────────┼────────────────────────┐
-        ▼                        ▼                        ▼
-┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│    Mermaid      │     │   Documentation │     │    PlantUML     │
-│    Diagram      │     │   (Markdown)    │     │    Diagram      │
-└─────────────────┘     └─────────────────┘     └─────────────────┘
-```
+| Feature | Status | Description |
+|---------|--------|-------------|
+| C# to Mermaid | **Implemented** | Generate class diagrams from C# source code |
+| Mermaid to C# | **Implemented** | Generate DDD-style C# from Mermaid diagrams |
+| Round-trip Sync | **Implemented** | Bidirectional transformation with semantic preservation |
+| Whiteboard Scanning | **Implemented** | AI-powered diagram extraction from photos |
+| Professional CLI | **Implemented** | Spectre.Console with rich output |
+| API Integration | **Scaffolded** | OpenAPI parsing, CDM mapping (designed) |
+| Document Pipeline | Planned | PDF/Word/Markdown conversion |
+| IMS Learning | Planned | Pattern learning from examples |
 
 ---
 
-## ✨ Key Features
-
-### 📷 Whiteboard to Code (Flagship Feature)
+## Quick Start
 
-Snap a photo of your whiteboard sketch and get working code:
+### Installation
 
+**Linux/macOS/WSL:**
 ```bash
-$ docflow scan whiteboard.jpg --output domain-model
-
-📷 Processing whiteboard image...
-🔍 Detected: UML Class Diagram (94% confidence)
-🧠 Identified 5 entities, 4 relationships
-✅ Generated: domain-model.mmd (Mermaid)
-✅ Generated: domain-model.cs (C# classes)
-✅ Generated: domain-model.md (Documentation)
+curl -sSL https://raw.githubusercontent.com/kurtmitchell/docflow/main/install.sh | bash
 ```
 
-Uses computer vision and AI to understand your sketches - even messy ones.
-
-### 🔄 Bidirectional Code ↔ Diagram Sync
-
-Generate diagrams from code:
-```bash
-$ docflow diagram ./src/Domain --output architecture.mmd
+**Windows PowerShell:**
+```powershell
+irm https://raw.githubusercontent.com/kurtmitchell/docflow/main/install.ps1 | iex
 ```
 
-Generate code from diagrams:
+**From Source:**
 ```bash
-$ docflow codegen class-diagram.mmd --output ./src/Models --lang csharp
+git clone https://github.com/kurtmitchell/docflow.git
+cd docflow
+dotnet build
+dotnet run --project src/DocFlow.CLI -- --help
 ```
 
-### 🧠 Intelligent Mapping Service (IMS)
-
-DocFlow learns your team's patterns and applies them automatically:
+### Usage Examples
 
 ```bash
-$ docflow learn --source existing-model.cs --target existing-diagram.mmd
+# Generate Mermaid class diagram from C# source
+docflow diagram Domain.cs -o domain.mmd
 
-📚 Learning from example...
-   Extracted 23 patterns
-   Updated confidence on 45 existing patterns
-   
-$ docflow convert NewModel.cs --to mermaid
+# Generate C# code from Mermaid diagram
+docflow codegen diagram.mmd -o Models.cs --namespace MyApp.Domain
 
-🤖 Applied 12 learned patterns (avg confidence: 94%)
-✅ Generated: NewModel.mmd
-```
+# AI-powered whiteboard scanning (requires API key)
+docflow scan whiteboard.jpg -o extracted.mmd
 
-The IMS improves with every transformation you make.
+# Full round-trip test with comparison
+docflow roundtrip Domain.cs --compare -v
+```
 
-### 📄 Document Pipeline
+### API Key Configuration
 
-Convert between formats with diagrams preserved:
+The whiteboard scanner requires a Claude API key. Configure it using one of these methods (in priority order):
 
+**1. Environment Variable:**
 ```bash
-$ docflow convert design-doc.md --to pdf --render-diagrams
-$ docflow convert specification.docx --to markdown
+export ANTHROPIC_API_KEY='sk-ant-...'
 ```
 
-### 🏛️ DDD-Aware Code Generation
-
-DocFlow understands Domain-Driven Design patterns:
-
-```bash
-$ docflow codegen order-model.mmd --style ddd
+**2. User Config (~/.docflow/config.json):**
+```json
+{
+  "anthropicApiKey": "sk-ant-..."
+}
+```
 
-# Generates:
-# - Aggregate roots with proper encapsulation
-# - Value objects as immutable records
-# - Repository interfaces
-# - Domain events
+**3. Project Config (./docflow.json):**
+```json
+{
+  "anthropicApiKey": "sk-ant-..."
+}
 ```
 
 ---
 
-## 🚀 Quick Start
+## Architecture
 
-### Installation
-
-```bash
-# Install as a global .NET tool
-dotnet tool install --global DocFlow.CLI
+DocFlow uses a **Canonical Semantic Model** as the universal truth layer. All formats translate to and from this model, enabling lossless bidirectional transformations.
 
-# Or clone and build from source
-git clone https://github.com/kurtmitchell/docflow.git
-cd docflow
-dotnet build
 ```
-
-### Configuration
-
-Create a `docflow.json` in your project root:
-
-```json
-{
-  "ai": {
-    "provider": "claude",
-    "apiKey": "${ANTHROPIC_API_KEY}"
-  },
-  "codeGen": {
-    "language": "csharp",
-    "style": "ddd",
-    "useRecordsForValueObjects": true
-  },
-  "ims": {
-    "enableLearning": true,
-    "patternStorePath": ".docflow/patterns.db"
-  }
-}
+                    ┌─────────────────────────────────────┐
+                    │       Canonical Semantic Model      │
+                    │  (Entities, Relationships, DDD)     │
+                    └──────────────┬──────────────────────┘
+                                   │
+       ┌───────────────┬───────────┼───────────┬───────────────┐
+       │               │           │           │               │
+       ▼               ▼           ▼           ▼               ▼
+┌─────────────┐ ┌─────────────┐ ┌───────┐ ┌─────────┐ ┌─────────────┐
+│   C# Code   │ │   Mermaid   │ │  API  │ │  Docs   │ │  Whiteboard │
+│   (Roslyn)  │ │  Diagrams   │ │ Specs │ │  (TBD)  │ │   (Vision)  │
+└─────────────┘ └─────────────┘ └───────┘ └─────────┘ └─────────────┘
 ```
 
-### Your First Scan
+### Why a Canonical Model?
 
-```bash
-# Scan a whiteboard photo
-docflow scan meeting-whiteboard.jpg
+Direct format conversion (A → B) breaks down when:
+- Information exists in A but not B (lossy)
+- You need round-trips (A → B → A ≠ A)
+- Semantic meaning differs between formats
 
-# Convert C# to Mermaid diagram  
-docflow diagram ./src/Domain/Order.cs
+DocFlow's approach: **A → Canonical Model → B**
 
-# Generate C# from a Mermaid class diagram
-docflow codegen order.mmd --lang csharp --output ./src/Models/
-```
+The model captures *meaning*, not just syntax. It knows that `ICollection<LineItem>` in C# and a filled diamond in Mermaid both represent *composition*.
 
----
+### DDD Support
 
-## 📖 Documentation
+The semantic model understands Domain-Driven Design patterns:
 
-| Guide | Description |
-|-------|-------------|
-| [Getting Started](docs/getting-started.md) | Installation and first steps |
-| [Whiteboard Scanning](docs/whiteboard-scanning.md) | Tips for best results with photos |
-| [Code Generation](docs/code-generation.md) | Customizing generated code |
-| [IMS Deep Dive](docs/intelligent-mapping.md) | How the learning system works |
-| [API Reference](docs/api-reference.md) | For library consumers |
+| Classification | Generated As |
+|----------------|--------------|
+| AggregateRoot | Class with `<<AggregateRoot>>` stereotype |
+| Entity | Class with identity property |
+| ValueObject | Immutable record type |
+| DomainService | Service class |
+| Enum | Enumeration |
+| Interface | Interface contract |
 
 ---
 
-## 🏗️ Architecture
-
-DocFlow is built on a **Canonical Semantic Model** - an ontologically-grounded representation that all formats translate to and from:
+## Project Structure
 
 ```
 DocFlow/
-├── DocFlow.Core           # Canonical model & abstractions
-├── DocFlow.Diagrams       # Mermaid, PlantUML parsing/generation
-├── DocFlow.Documents      # Markdown, PDF, Word conversion
-├── DocFlow.CodeAnalysis   # Roslyn-based C# analysis
-├── DocFlow.CodeGen        # Code generation from model
-├── DocFlow.Vision         # Computer vision & whiteboard scanning
-├── DocFlow.IMS            # Intelligent Mapping Service
-├── DocFlow.Ontology       # DDD pattern classification & reasoning
-├── DocFlow.AI             # AI provider integrations
-└── DocFlow.CLI            # Command-line interface
+├── src/
+│   ├── DocFlow.Core           # Canonical model & abstractions
+│   ├── DocFlow.Diagrams       # Mermaid parsing & generation
+│   ├── DocFlow.CodeAnalysis   # Roslyn-based C# parsing
+│   ├── DocFlow.CodeGen        # C# code generation from model
+│   ├── DocFlow.Vision         # AI-powered whiteboard scanning
+│   ├── DocFlow.AI             # Claude API integration
+│   ├── DocFlow.IMS            # Intelligent Mapping Service (pattern learning)
+│   ├── DocFlow.Ontology       # DDD pattern classification
+│   ├── DocFlow.Documents      # Document pipeline (planned)
+│   ├── DocFlow.Integration    # API integration automation (scaffolded)
+│   ├── DocFlow.Web            # Web UI (planned)
+│   └── DocFlow.CLI            # Command-line interface
+├── tests/
+│   ├── DocFlow.CodeAnalysis.Tests  # 20 tests
+│   ├── DocFlow.Diagrams.Tests      # 52 tests
+│   └── DocFlow.CodeGen.Tests       # 19 tests
+├── docs/
+│   ├── ARCHITECTURE.md        # Technical architecture
+│   ├── CLI-REFERENCE.md       # Complete CLI documentation
+│   ├── CHANGELOG.md           # Version history
+│   └── design/                # Design documents
+└── samples/
+    └── whiteboard-demos/      # Whiteboard scanner examples
 ```
 
-### Why a Canonical Model?
+### DocFlow.Integration (Scaffolded)
 
-Most tools treat format conversion as direct translation (A → B). This breaks down when:
-- Information exists in A but not B (lossy)
-- You need to round-trip (A → B → A ≠ A)
-- Semantics differ between formats
+The Integration module extends DocFlow's canonical model pattern to enterprise API integrations:
 
-DocFlow's approach: **A → Canonical Model → B**
+- **OpenAPI/Swagger parsing** → Semantic model extraction
+- **CDM (Canonical Data Model) mapping** → External API ↔ internal model
+- **SLA validation** → Data freshness checking
+- **Pre-built domain patterns** → Aviation, e-commerce, etc.
 
-The canonical model captures *meaning*, not just syntax. It knows that `ICollection<LineItem>` in C# and a filled diamond arrow in UML both represent *composition* - and generates appropriate output for each format.
+See [docs/design/integration-module.md](docs/design/integration-module.md) for the full design.
 
 ---
 
-## 🤝 Contributing
+## CLI Commands
 
-We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `diagram <input>` | `d` | Generate Mermaid from C# source |
+| `codegen <input>` | `c` | Generate C# from Mermaid diagram |
+| `roundtrip <input>` | `r` | Full C# → Mermaid → C# round-trip |
+| `scan <image>` | `s` | AI-powered whiteboard scanning |
 
-### Development Setup
+See [docs/CLI-REFERENCE.md](docs/CLI-REFERENCE.md) for complete documentation.
 
-```bash
-# Clone the repo
-git clone https://github.com/kurtmitchell/docflow.git
-cd docflow
+---
+
+## Development
 
+### Prerequisites
+
+- .NET 8.0 SDK
+- Claude API key (for whiteboard scanning)
+
+### Build & Test
+
+```bash
 # Build
 dotnet build
 
-# Run tests
+# Run all tests
 dotnet test
 
-# Run the CLI locally
-dotnet run --project src/DocFlow.CLI -- scan test-image.jpg
+# Run CLI locally
+dotnet run --project src/DocFlow.CLI -- diagram MyClass.cs
 ```
 
-### Areas We Need Help
+### Test Coverage
 
-- 🖼️ **Training data** - Whiteboard photos with corresponding diagrams
-- 🌐 **Language support** - TypeScript, Python, Go code generation
-- 📊 **Diagram types** - Sequence diagrams, state machines, ER diagrams
-- 🧪 **Testing** - Edge cases, real-world scenarios
+- **91+ unit tests** across 3 test projects
+- C# parsing, Mermaid generation, round-trip preservation
+- DDD pattern detection and classification
 
 ---
 
-## 📜 License
+## Documentation
 
-MIT License - see [LICENSE](LICENSE) for details.
+| Document | Description |
+|----------|-------------|
+| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Technical architecture and design |
+| [CLI-REFERENCE.md](docs/CLI-REFERENCE.md) | Complete CLI command reference |
+| [CHANGELOG.md](docs/CHANGELOG.md) | Version history and release notes |
+| [Integration Design](docs/design/integration-module.md) | API integration module design |
 
 ---
 
-## 🙏 Acknowledgments
+## Roadmap
 
-DocFlow was designed and built by:
+### v0.1.0-preview (Current)
+- [x] C# → Mermaid class diagram generation
+- [x] Mermaid → C# code generation (DDD-style)
+- [x] Bidirectional round-trip with semantic preservation
+- [x] AI-powered whiteboard scanning
+- [x] Professional CLI with Spectre.Console
+- [x] Integration module scaffolded
 
-- **Kurt Mitchell** - Architecture, implementation, domain expertise
-- **Claude (Anthropic)** - Co-design, code generation, documentation
+### v0.2.0
+- [ ] IMS pattern learning from examples
+- [ ] PlantUML support
+- [ ] Sequence diagram support
+- [ ] Integration module implementation
 
-Special thanks to the open source projects that make DocFlow possible:
-- [Roslyn](https://github.com/dotnet/roslyn) - C# code analysis
-- [OpenCvSharp](https://github.com/shimat/opencvsharp) - Computer vision
-- [Markdig](https://github.com/xoofx/markdig) - Markdown processing
-- [Spectre.Console](https://github.com/spectreconsole/spectre.console) - Beautiful CLI
+### v0.3.0
+- [ ] PDF/Word document pipeline
+- [ ] VS Code extension
+- [ ] Web UI (Blazor)
 
 ---
 
-## 🗺️ Roadmap
+## License
 
-### v0.1 (Current)
-- [x] Core canonical model
-- [x] C# → Mermaid class diagram
-- [x] Basic whiteboard scanning
-- [ ] Mermaid → C# code generation
-- [ ] CLI with basic commands
+MIT License - see [LICENSE](LICENSE) for details.
 
-### v0.2
-- [ ] IMS pattern learning
-- [ ] PDF/Word document pipeline
-- [ ] PlantUML support
-- [ ] Java code analysis/generation
+---
 
-### v0.3
-- [ ] GA-optimized diagram layouts
-- [ ] Sequence diagram support
-- [ ] VS Code extension
-- [ ] Team pattern sharing
+## Acknowledgments
 
-### v1.0
-- [ ] Full round-trip support all formats
-- [ ] Blazor web UI
-- [ ] Self-hosted model support
-- [ ] Enterprise features
+Built by **Kurt Mitchell** with **Claude (Anthropic)** as co-designer and implementation partner.
+
+Open source dependencies:
+- [Roslyn](https://github.com/dotnet/roslyn) - C# code analysis
+- [Spectre.Console](https://github.com/spectreconsole/spectre.console) - CLI framework
+- [Microsoft.OpenApi](https://github.com/microsoft/OpenAPI.NET) - OpenAPI parsing
 
 ---
 
 <p align="center">
-  <strong>Stop losing your whiteboard ideas. Start shipping with DocFlow.</strong>
+  <strong>Transform your diagrams. Generate your code. Ship faster with DocFlow.</strong>
 </p>
diff --git a/config.json b/config.json
new file mode 100644
index 0000000..69feb58
--- /dev/null
+++ b/config.json
@@ -0,0 +1,3 @@
+{
+  "anthropicApiKey": "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"
+}
\ No newline at end of file
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..a34800b
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,351 @@
+# DocFlow Architecture
+
+This document describes the technical architecture of DocFlow, explaining the design decisions and patterns that enable bidirectional transformation between code, diagrams, and documentation.
+
+## Core Concept: Canonical Semantic Model
+
+DocFlow's architecture centers on a **Canonical Semantic Model** - an intermediate representation that captures the *meaning* of software models, not just their syntax.
+
+### The Problem with Direct Translation
+
+Traditional tools translate directly between formats (A → B). This approach fails when:
+
+1. **Information Loss**: Format A has concepts that B cannot represent
+2. **Round-Trip Failure**: A → B → A produces different output than the original
+3. **Semantic Mismatch**: The same concept has different syntax in each format
+
+### The DocFlow Solution
+
+```
+┌─────────────┐     ┌─────────────────────────────────────┐     ┌─────────────┐
+│   Source    │     │       Canonical Semantic Model      │     │   Target    │
+│   Format    │────▶│                                     │────▶│   Format    │
+│  (C#, etc)  │     │  Entities, Properties, Operations   │     │  (Mermaid)  │
+└─────────────┘     │  Relationships, Classifications     │     └─────────────┘
+       │            │  DDD Patterns, Stereotypes          │            │
+       │            └─────────────────────────────────────┘            │
+       │                              │                                │
+       │                              ▼                                │
+       │            ┌─────────────────────────────────────┐            │
+       └───────────▶│         Round-Trip Support          │◀───────────┘
+                    │     Semantic preservation via       │
+                    │     canonical representation        │
+                    └─────────────────────────────────────┘
+```
+
+By routing all transformations through the canonical model, DocFlow:
+- Preserves semantic meaning across formats
+- Enables true round-trip transformations
+- Supports adding new formats without N×M parser/generator combinations
+
+---
+
+## Semantic Model Structure
+
+### SemanticModel
+
+The root container holding the complete model:
+
+```csharp
+public sealed class SemanticModel
+{
+    public string Id { get; init; }
+    public string? Name { get; set; }
+    public Dictionary<string, SemanticEntity> Entities { get; init; }
+    public List<SemanticRelationship> Relationships { get; init; }
+    public List<SemanticNamespace> Namespaces { get; init; }
+    public ModelProvenance? Provenance { get; set; }
+}
+```
+
+### SemanticEntity
+
+Represents any type-like construct (class, interface, enum, etc.):
+
+```csharp
+public sealed class SemanticEntity
+{
+    public string Id { get; init; }
+    public string Name { get; init; }
+    public EntityClassification Classification { get; set; }
+    public bool IsAbstract { get; set; }
+    public List<SemanticProperty> Properties { get; init; }
+    public List<SemanticOperation> Operations { get; init; }
+    public List<string> Stereotypes { get; init; }
+}
+```
+
+### Entity Classifications (DDD Support)
+
+```csharp
+public enum EntityClassification
+{
+    Class,           // Generic class
+    AggregateRoot,   // DDD aggregate boundary
+    Entity,          // DDD entity with identity
+    ValueObject,     // DDD immutable value
+    DomainService,   // Stateless domain operations
+    DomainEvent,     // Something that happened
+    Repository,      // Collection-like persistence
+    Interface,       // Contract definition
+    Enum,            // Enumeration
+    Record           // Immutable data carrier
+}
+```
+
+### SemanticRelationship
+
+Captures relationships with full semantic information:
+
+```csharp
+public sealed class SemanticRelationship
+{
+    public string SourceEntityId { get; init; }
+    public string TargetEntityId { get; init; }
+    public RelationshipType Type { get; init; }  // Inheritance, Composition, etc.
+    public string? SourceMultiplicity { get; set; }
+    public string? TargetMultiplicity { get; set; }
+}
+```
+
+---
+
+## Parser → Generator Pattern
+
+All transformations follow the same pattern:
+
+```
+IModelParser: Input → SemanticModel
+IModelGenerator: SemanticModel → Output
+```
+
+### Parser Interface
+
+```csharp
+public interface IModelParser
+{
+    string FormatName { get; }
+    IReadOnlyList<string> SupportedExtensions { get; }
+
+    Task<ParseResult> ParseAsync(
+        ParserInput input,
+        ParserOptions? options = null,
+        CancellationToken cancellationToken = default);
+}
+```
+
+### Generator Interface
+
+```csharp
+public interface IModelGenerator
+{
+    string FormatName { get; }
+    string DefaultExtension { get; }
+
+    Task<GenerateResult> GenerateAsync(
+        SemanticModel model,
+        GeneratorOptions? options = null,
+        CancellationToken cancellationToken = default);
+}
+```
+
+### Implemented Transformers
+
+| Component | Parser | Generator |
+|-----------|--------|-----------|
+| C# | `CSharpModelParser` | `CSharpModelGenerator` |
+| Mermaid | `MermaidClassDiagramParser` | `MermaidClassDiagramGenerator` |
+| Whiteboard | `WhiteboardScanner` | - |
+
+---
+
+## Whiteboard Scanning Pipeline
+
+The whiteboard scanner uses AI vision to extract diagrams from photos:
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Image     │────▶│   Base64    │────▶│   Claude    │────▶│   Mermaid   │
+│   (JPG/PNG) │     │   Encode    │     │ Vision API  │     │    Text     │
+└─────────────┘     └─────────────┘     └─────────────┘     └──────┬──────┘
+                                                                   │
+                                                                   ▼
+┌─────────────┐     ┌─────────────┐     ┌─────────────────────────────────┐
+│  Semantic   │◀────│   Mermaid   │◀────│         Prompt Engineering       │
+│   Model     │     │   Parser    │     │  - Diagram type detection        │
+└─────────────┘     └─────────────┘     │  - Entity/relationship extract   │
+                                        │  - Mermaid syntax generation     │
+                                        └─────────────────────────────────┘
+```
+
+### Key Components
+
+**WhiteboardScanner** (`DocFlow.Vision/WhiteboardScanner.cs`)
+- Orchestrates the scanning pipeline
+- Handles image loading and format detection
+- Manages diagram type detection
+- Converts AI output to SemanticModel
+
+**ClaudeProvider** (`DocFlow.AI/Providers/ClaudeProvider.cs`)
+- Implements `IAiProvider` interface
+- Handles Claude API communication
+- Supports vision (image analysis) and text completion
+- Multi-source API key resolution
+
+### Prompt Engineering
+
+The whiteboard scanner uses carefully crafted prompts:
+
+1. **Diagram Type Detection**: Quick classification of diagram type with confidence score
+2. **Entity Extraction**: Detailed analysis to extract classes, properties, methods
+3. **Relationship Mapping**: Identify inheritance, composition, association patterns
+4. **Mermaid Generation**: Output valid Mermaid classDiagram syntax
+
+---
+
+## Integration Module Architecture
+
+The Integration module (scaffolded, not fully implemented) extends the canonical model pattern to API integrations:
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                        External API Ecosystem                            │
+├─────────────────┬─────────────────┬─────────────────┬───────────────────┤
+│   OpenAPI 3.x   │   Swagger 2.0   │   GraphQL       │   JSON Samples    │
+└────────┬────────┴────────┬────────┴────────┬────────┴─────────┬─────────┘
+         │                 │                 │                  │
+         └─────────────────┴─────────────────┴──────────────────┘
+                                    │
+                                    ▼
+                    ┌───────────────────────────────┐
+                    │     Canonical Semantic Model   │
+                    │   (Same as Code/Diagrams!)     │
+                    └───────────────┬───────────────┘
+                                    │
+                    ┌───────────────┴───────────────┐
+                    │         CDM Mapper             │
+                    │   (IMS-powered mapping)        │
+                    └───────────────┬───────────────┘
+                                    │
+                                    ▼
+                    ┌───────────────────────────────┐
+                    │   Internal Canonical Model     │
+                    │   (Your Domain Model)          │
+                    └───────────────────────────────┘
+```
+
+### Pre-built Domain Patterns
+
+The Integration module includes pre-seeded patterns for common domains:
+
+**Aviation Domain:**
+| External Pattern | Canonical Target | Confidence |
+|------------------|------------------|------------|
+| `tail_num`, `aircraft_id` | TailNumber | 95% |
+| `arr_time`, `eta` | ArrivalDateTime | 93% |
+| `pax`, `passenger_count` | PassengerCount | 90% |
+
+### SLA Validation
+
+The SlaValidator checks data freshness to catch stale data issues:
+
+```csharp
+var report = await slaValidator.ValidateDataFreshnessAsync(new SlaValidationRequest
+{
+    EndpointUrl = "https://api.example.com/v1/data",
+    ExpectedMaxAge = TimeSpan.FromSeconds(30),
+    SampleCount = 100
+});
+```
+
+See [docs/design/integration-module.md](design/integration-module.md) for full design.
+
+---
+
+## Intelligent Mapping Service (IMS)
+
+The IMS (designed, not fully implemented) learns transformation patterns from examples:
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│   Observed      │────▶│   Pattern       │────▶│   Learned       │
+│   Transformation│     │   Extraction    │     │   Patterns      │
+└─────────────────┘     └─────────────────┘     └────────┬────────┘
+                                                         │
+                                                         ▼
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│   Suggestions   │◀────│   Pattern       │◀────│   New Input     │
+│  with Confidence│     │   Matching      │     │                 │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+```
+
+### Key Concepts
+
+- **LearnedPattern**: A transformation pattern with confidence score
+- **PatternMatcher**: Applies patterns to new inputs
+- **FeedbackLoop**: User corrections improve future suggestions
+
+---
+
+## Project Dependencies
+
+```
+DocFlow.CLI
+├── DocFlow.Core              # Canonical model, abstractions
+├── DocFlow.Diagrams          # Mermaid parsing & generation
+│   └── DocFlow.Core
+├── DocFlow.CodeAnalysis      # Roslyn-based C# parsing
+│   └── DocFlow.Core
+├── DocFlow.CodeGen           # C# code generation
+│   └── DocFlow.Core
+├── DocFlow.Vision            # Whiteboard scanning
+│   ├── DocFlow.Core
+│   └── DocFlow.AI
+├── DocFlow.AI                # AI provider abstraction
+│   └── DocFlow.Core
+├── DocFlow.IMS               # Pattern learning
+│   └── DocFlow.Core
+├── DocFlow.Ontology          # DDD classification
+│   └── DocFlow.Core
+├── DocFlow.Integration       # API integration
+│   ├── DocFlow.Core
+│   ├── DocFlow.IMS
+│   └── DocFlow.CodeGen
+├── DocFlow.Documents         # Document pipeline (planned)
+│   └── DocFlow.Core
+└── DocFlow.Web               # Web UI (planned)
+    └── DocFlow.Core
+```
+
+---
+
+## Design Principles
+
+### 1. Semantic Preservation
+All transformations preserve meaning. A class in C# should have the same semantic representation whether it came from source code, a Mermaid diagram, or a whiteboard photo.
+
+### 2. Extensibility
+Adding a new format requires only a parser and/or generator. The canonical model stays unchanged.
+
+### 3. DDD-First
+The model understands Domain-Driven Design patterns natively. Aggregates, entities, and value objects are first-class concepts.
+
+### 4. Async All the Way
+All I/O-bound operations are async with CancellationToken support.
+
+### 5. Nullable Safety
+Nullable reference types are enabled throughout. No `NullReferenceException` surprises.
+
+---
+
+## Technology Stack
+
+| Layer | Technology |
+|-------|------------|
+| Runtime | .NET 8.0 |
+| Language | C# 12 |
+| C# Parsing | Microsoft.CodeAnalysis.CSharp (Roslyn) |
+| CLI | System.CommandLine + Spectre.Console |
+| AI | Anthropic Claude API |
+| OpenAPI | Microsoft.OpenApi.Readers |
+| Testing | xUnit + FluentAssertions |
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
new file mode 100644
index 0000000..568a10e
--- /dev/null
+++ b/docs/CHANGELOG.md
@@ -0,0 +1,114 @@
+# Changelog
+
+All notable changes to DocFlow will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0-preview] - 2025-01-04
+
+### Added
+
+#### Core Pipeline
+- **Canonical Semantic Model** - Universal intermediate representation for all transformations
+- **SemanticModel** with entities, relationships, and namespaces
+- **DDD Classifications** - AggregateRoot, Entity, ValueObject, DomainService, DomainEvent, Repository, Interface, Enum
+- **Relationship Types** - Inheritance, Composition, Aggregation, Association, Dependency, Implementation
+
+#### C# to Mermaid (DocFlow.CodeAnalysis + DocFlow.Diagrams)
+- Roslyn-based C# parsing for classes, records, interfaces, enums
+- Property extraction with types and visibility modifiers
+- Method extraction with parameters and return types
+- Inheritance and interface implementation detection
+- Composition/aggregation inference from collection properties
+- DDD stereotype detection from naming conventions
+- Mermaid classDiagram generation with proper syntax
+
+#### Mermaid to C# (DocFlow.Diagrams + DocFlow.CodeGen)
+- Mermaid classDiagram parser with stereotype support
+- C# code generator with nullable-enabled output
+- Records for ValueObjects, classes for Entities
+- XML documentation comment generation
+- Proper access modifier mapping (+, -, #)
+
+#### Round-Trip Support
+- Full bidirectional transformation: C# → Mermaid → C#
+- Semantic preservation across transformations
+- `--compare` flag for diff visualization
+
+#### Whiteboard Scanner (DocFlow.Vision + DocFlow.AI)
+- AI-powered diagram extraction from photos
+- Claude Vision API integration (claude-sonnet-4-20250514)
+- Diagram type detection with confidence scoring
+- Support for JPG, PNG, GIF, WEBP formats
+- Context hints for improved accuracy
+
+#### Claude API Integration (DocFlow.AI)
+- `ClaudeProvider` with vision and text completion support
+- Multi-source API key resolution:
+  1. Environment variable: `ANTHROPIC_API_KEY`
+  2. User config: `~/.docflow/config.json`
+  3. Project config: `./docflow.json`
+- Helpful error messages with configuration instructions
+
+#### CLI (DocFlow.CLI)
+- Professional CLI with System.CommandLine
+- Rich output with Spectre.Console (colors, tables, panels)
+- ASCII art banner
+- Commands:
+  - `diagram` (alias: `d`) - Generate Mermaid from C#
+  - `codegen` (alias: `c`) - Generate C# from Mermaid
+  - `roundtrip` (alias: `r`) - Full round-trip test
+  - `scan` (alias: `s`) - Whiteboard scanning
+- Global options: `--verbose`, `--quiet`
+
+#### Integration Module (DocFlow.Integration) - Scaffolded
+- OpenAPI 3.x parser foundation (`OpenApiParser`)
+- CDM mapping engine design (`CdmMapper`)
+- SLA validation for data freshness (`SlaValidator`)
+- Pre-built aviation domain patterns (`ApiMappingPatterns`)
+- Integration specification model (`IntegrationSpec`)
+
+#### Testing
+- 91+ unit tests across 3 test projects
+- DocFlow.CodeAnalysis.Tests (20 tests)
+- DocFlow.Diagrams.Tests (52 tests)
+- DocFlow.CodeGen.Tests (19 tests)
+
+#### Documentation
+- Comprehensive README with feature status
+- CLAUDE.md for AI assistant context
+- Architecture documentation
+- CLI reference
+- Integration module design document
+
+### Technical Details
+
+- **.NET 8.0** with C# 12 features
+- **Nullable reference types** enabled throughout
+- **Async/await** with CancellationToken support
+- **Records** for immutable types
+- **Collection expressions** for clean syntax
+
+### Dependencies
+
+- Microsoft.CodeAnalysis.CSharp (Roslyn) - C# parsing
+- Spectre.Console - CLI framework
+- System.CommandLine - Command parsing
+- Microsoft.OpenApi.Readers - OpenAPI parsing
+- OpenCvSharp4 - Image preprocessing (Vision)
+
+---
+
+## Unreleased
+
+### Planned for v0.2.0
+- IMS (Intelligent Mapping Service) pattern learning
+- PlantUML support
+- Sequence diagram support
+- Full Integration module implementation
+
+### Planned for v0.3.0
+- PDF/Word document pipeline
+- VS Code extension
+- Web UI (Blazor)
diff --git a/docs/CLI-REFERENCE.md b/docs/CLI-REFERENCE.md
new file mode 100644
index 0000000..e5682d9
--- /dev/null
+++ b/docs/CLI-REFERENCE.md
@@ -0,0 +1,327 @@
+# CLI Reference
+
+Complete documentation for the DocFlow command-line interface.
+
+## Installation
+
+```bash
+# From source
+dotnet run --project src/DocFlow.CLI -- <command> [options]
+
+# As installed tool
+docflow <command> [options]
+```
+
+## Global Options
+
+These options are available on all commands:
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--verbose` | `-v` | Show detailed output including entity tables and full generated content |
+| `--quiet` | `-q` | Minimal output, only errors. Useful for scripting |
+| `--help` | `-h`, `-?` | Show help and usage information |
+
+---
+
+## Commands
+
+### diagram
+
+Generate a Mermaid class diagram from C# source code.
+
+**Usage:**
+```bash
+docflow diagram <input> [options]
+docflow d <input> [options]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<input>` | C# source file or directory to parse |
+
+**Options:**
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--output <file>` | `-o` | Output file path (default: same name with .mmd extension) |
+| `--recursive` | `-r` | Process all .cs files in directory recursively |
+| `--no-relationships` | | Exclude relationship lines from diagram |
+
+**Examples:**
+
+```bash
+# Single file
+docflow diagram Domain/Order.cs
+
+# Directory (non-recursive)
+docflow diagram Domain/
+
+# Directory (recursive) with custom output
+docflow diagram src/Domain -r -o architecture.mmd
+
+# Exclude relationships
+docflow diagram Order.cs --no-relationships
+
+# Verbose output
+docflow diagram Order.cs -v
+```
+
+**Output:**
+
+- Creates a `.mmd` file with valid Mermaid classDiagram syntax
+- Displays entity count and relationship count
+- Shows generated Mermaid content (unless `--quiet`)
+
+---
+
+### codegen
+
+Generate C# code from a Mermaid class diagram.
+
+**Usage:**
+```bash
+docflow codegen <input> [options]
+docflow c <input> [options]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<input>` | Mermaid diagram file (.mmd) to parse |
+
+**Options:**
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--output <file>` | `-o` | Output file path (default: same name with .cs extension) |
+| `--namespace <name>` | `-n` | Namespace for generated code (default: derived from filename) |
+| `--style <style>` | | Code style: `ddd` (default) or `poco` |
+
+**Styles:**
+
+| Style | Description |
+|-------|-------------|
+| `ddd` | Domain-Driven Design style with aggregates, value objects as records |
+| `poco` | Plain Old CLR Objects - simple classes without DDD patterns |
+
+**Examples:**
+
+```bash
+# Basic generation
+docflow codegen domain.mmd
+
+# Custom namespace
+docflow codegen domain.mmd -n MyApp.Domain.Models
+
+# POCO style
+docflow codegen domain.mmd --style poco
+
+# Custom output location
+docflow codegen diagram.mmd -o src/Models/Generated.cs
+```
+
+**Output:**
+
+- Creates a `.cs` file with nullable-enabled C# 12 code
+- Records for ValueObjects, classes for Entities
+- Proper access modifiers and XML documentation
+
+---
+
+### roundtrip
+
+Perform a full round-trip transformation: C# → Mermaid → C#
+
+**Usage:**
+```bash
+docflow roundtrip <input> [options]
+docflow r <input> [options]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<input>` | C# source file to round-trip |
+
+**Options:**
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--output <dir>` | `-o` | Output directory for generated files |
+| `--compare` | | Show semantic diff between original and generated |
+
+**Examples:**
+
+```bash
+# Basic round-trip
+docflow roundtrip Domain/Order.cs
+
+# With comparison
+docflow roundtrip Order.cs --compare
+
+# Custom output directory
+docflow roundtrip Order.cs -o ./generated
+
+# Verbose with comparison
+docflow roundtrip Order.cs --compare -v
+```
+
+**Output Files:**
+
+| File | Description |
+|------|-------------|
+| `<name>.mmd` | Intermediate Mermaid diagram |
+| `<name>.generated.cs` | Round-tripped C# code |
+
+**Comparison Output:**
+
+When using `--compare`, displays:
+- Entity count comparison (original vs round-trip)
+- Relationship count comparison
+- Entity classification breakdown (with `--verbose`)
+
+---
+
+### scan
+
+Scan a whiteboard or diagram image using AI vision.
+
+**Usage:**
+```bash
+docflow scan <image> [options]
+docflow s <image> [options]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<image>` | Whiteboard or diagram image to scan (PNG, JPG, WEBP, GIF) |
+
+**Options:**
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--output <file>` | `-o` | Output file path for extracted Mermaid diagram |
+| `--context <hint>` | `-c` | Context hint for better interpretation |
+
+**Supported Formats:**
+
+- `.jpg`, `.jpeg`
+- `.png`
+- `.gif`
+- `.webp`
+
+**Examples:**
+
+```bash
+# Basic scan
+docflow scan whiteboard.jpg
+
+# With context hint
+docflow scan meeting-notes.png -c "e-commerce domain model"
+
+# Custom output
+docflow scan diagram.jpg -o extracted.mmd
+
+# Verbose output
+docflow scan whiteboard.jpg -v
+```
+
+**Configuration Required:**
+
+The scan command requires a Claude API key. Configure using one of:
+
+1. **Environment variable:**
+   ```bash
+   export ANTHROPIC_API_KEY='sk-ant-...'
+   ```
+
+2. **User config:** `~/.docflow/config.json`
+   ```json
+   { "anthropicApiKey": "sk-ant-..." }
+   ```
+
+3. **Project config:** `./docflow.json`
+   ```json
+   { "anthropicApiKey": "sk-ant-..." }
+   ```
+
+**Output:**
+
+- Diagram type with confidence score
+- Entity count and relationship count
+- Analysis time
+- Generated Mermaid diagram
+- Saves `.mmd` file
+
+---
+
+## Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | Success |
+| 1 | Error (file not found, parse error, generation error, missing config) |
+
+---
+
+## Examples
+
+### Full Workflow
+
+```bash
+# 1. Start with a whiteboard photo
+docflow scan whiteboard.jpg -o domain.mmd -c "order management"
+
+# 2. Generate C# from the extracted diagram
+docflow codegen domain.mmd -n MyApp.Domain -o Models.cs
+
+# 3. Later, update the C# and regenerate the diagram
+docflow diagram Models.cs -o domain-updated.mmd
+
+# 4. Verify round-trip preservation
+docflow roundtrip Models.cs --compare -v
+```
+
+### Scripting
+
+```bash
+# Quiet mode for scripts
+OUTPUT=$(docflow diagram src/Domain -r -q)
+echo "Generated: $OUTPUT"
+
+# Check exit code
+if docflow codegen diagram.mmd -q; then
+    echo "Success"
+else
+    echo "Failed"
+fi
+```
+
+### Batch Processing
+
+```bash
+# Process all C# files in a directory
+for file in src/Domain/*.cs; do
+    docflow diagram "$file" -q
+done
+
+# Combine into single diagram
+docflow diagram src/Domain -r -o full-model.mmd
+```
+
+---
+
+## Tips
+
+1. **Use context hints** with `scan` for better accuracy on domain-specific diagrams
+2. **Use verbose mode** (`-v`) when debugging transformation issues
+3. **Use quiet mode** (`-q`) in CI/CD pipelines
+4. **Use `--compare`** with roundtrip to verify semantic preservation
+5. **Set up user config** (`~/.docflow/config.json`) to avoid repeating API key setup
diff --git a/docs/design/integration-module.md b/docs/design/integration-module.md
new file mode 100644
index 0000000..b8dca5a
--- /dev/null
+++ b/docs/design/integration-module.md
@@ -0,0 +1,279 @@
+# DocFlow.Integration Module - Design Document
+
+## Status: Scaffolded (Core Types Implemented, Full Features Planned)
+
+The Integration module has been scaffolded with core types and interfaces. The OpenAPI parser, schema models, and SLA validator foundations are in place. Full implementation is planned for a future release.
+
+**Implemented:**
+- `ISchemaParser` interface and `SchemaParseResult`
+- `OpenApiParser` foundation
+- `IntegrationSpec`, `ApiEndpoint`, `FieldMapping` models
+- `ApiMappingPatterns` with aviation domain patterns
+- `SlaValidator` structure
+
+**Planned:**
+- Full OpenAPI/Swagger parsing
+- CDM mapping engine
+- Code generation (DTOs, AutoMapper, HTTP clients)
+- CLI commands for integration workflows
+
+---
+
+## Overview
+
+DocFlow.Integration extends the platform from documents/code into **enterprise API integration automation**. It uses the same Canonical Semantic Model pattern to map between external API schemas and internal Canonical Data Models.
+
+## Core Insight
+
+The same architecture that transforms C# ↔ Mermaid can transform External API ↔ CDM:
+
+```
+DOCUMENTS/CODE DOMAIN              API INTEGRATION DOMAIN
+──────────────────────             ─────────────────────
+
+┌─────────────┐                    ┌─────────────────┐
+│   C# Code   │                    │  OpenAPI Spec   │
+├─────────────┤                    ├─────────────────┤
+│   Mermaid   │                    │  JSON Samples   │
+├─────────────┤                    ├─────────────────┤
+│  PlantUML   │                    │  GraphQL Schema │
+└──────┬──────┘                    └────────┬────────┘
+       │         ┌──────────────────┐       │
+       └────────►│    CANONICAL     │◄──────┘
+                 │  SEMANTIC MODEL  │
+                 └────────┬─────────┘
+                          │
+       ┌──────────────────┼──────────────────┐
+       ▼                  ▼                  ▼
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│  Generated  │    │  Generated  │    │ Integration │
+│    Code     │    │  Diagrams   │    │    Code     │
+└─────────────┘    └─────────────┘    └─────────────┘
+```
+
+The IMS learns patterns in both domains!
+
+---
+
+## Project Structure
+
+```
+src/DocFlow.Integration/
+├── Schemas/                    # External API schema parsing
+│   ├── OpenApi/               # OpenAPI 3.x / Swagger 2.0
+│   ├── JsonSchema/            # JSON Schema
+│   ├── GraphQL/               # GraphQL schemas
+│   └── Soap/                  # Legacy WSDL/SOAP
+│
+├── Models/                     # Integration-specific models
+│   ├── IntegrationSpec.cs     # Complete integration specification
+│   └── ApiEndpoint.cs         # API endpoint and parameter models
+│
+├── Patterns/                   # IMS pattern definitions
+│   └── ApiMappingPatterns.cs  # Domain-specific mapping patterns
+│
+├── Mapping/                    # CDM mapping engine
+│   └── CdmMapper.cs           # Maps external → CDM with IMS
+│
+├── CodeGen/                    # Integration code generation
+│   ├── DtoGenerator.cs        # External DTOs
+│   ├── MapperGenerator.cs     # AutoMapper profiles
+│   ├── ClientGenerator.cs     # Typed HTTP clients
+│   └── ValidatorGenerator.cs  # FluentValidation validators
+│
+├── Validation/                 # Integration validation
+│   └── SlaValidator.cs        # SLA compliance checking (!)
+│
+└── Analysis/                   # Change detection
+    ├── BreakingChangeDetector.cs
+    └── DriftDetector.cs
+```
+
+---
+
+## Key Types
+
+### IntegrationSpec
+
+Complete specification for an external API integration:
+- External system info (name, base URL, version)
+- CDM reference
+- Endpoint integrations with field mappings
+- SLA requirements
+- Authentication configuration
+- IMS confidence report
+
+### FieldMapping
+
+Maps source field to target field:
+- Source/target field names
+- Transformation rule (type conversion, formatting, etc.)
+- IMS confidence score
+- Reasoning explanation
+- Auto-mapped / verified flags
+
+### ApiMappingPatterns
+
+Pre-built patterns for common domains:
+- **Aviation**: tail_num → TailNumber, arr_time → ArrivalDateTime, pax → PassengerCount
+- **DateTime**: ISO/Unix timestamp conversions
+- **Identifiers**: Primary key, foreign key, correlation ID patterns
+- **Contact**: Email, phone, name patterns
+- **Audit**: created_at, updated_at patterns
+
+---
+
+## CLI Commands (Planned)
+
+```bash
+# Generate integration scaffold from OpenAPI spec
+docflow integrate <spec.json> --cdm <path>
+  -o, --output <dir>           Output directory
+  -n, --namespace <name>       Namespace for generated code
+  --skip-client                Don't generate HTTP client
+  --interactive                Prompt for low-confidence mappings
+
+# Analyze mapping coverage
+docflow integrate analyze <spec.json> --cdm <path>
+  --report <file>              Output detailed report
+
+# Validate against updated API spec
+docflow integrate validate <spec.json> --against <new-spec.json>
+  --breaking-only              Only show breaking changes
+
+# Learn patterns from existing mappers
+docflow integrate learn <existing-mapper.cs>
+  --source-dto <dto.cs>
+  --target-cdm <cdm.cs>
+
+# SLA compliance validation
+docflow integrate sla <endpoint-url> --expected <30s>
+  --samples 100                Number of samples
+  --report <file>              Output report
+```
+
+---
+
+## Generated Artifacts
+
+### 1. External DTOs
+
+```csharp
+public sealed record FlightBridgeReservationDto
+{
+    [JsonPropertyName("res_id")]
+    public string? ResId { get; init; }
+    
+    [JsonPropertyName("arr_time")]
+    public string? ArrTime { get; init; }
+    // ...
+}
+```
+
+### 2. AutoMapper Profiles
+
+```csharp
+CreateMap<FlightBridgeReservationDto, Reservation>()
+    .ForMember(dest => dest.ReservationId, 
+        opt => opt.MapFrom(src => src.ResId))  // 98% confidence
+    .ForMember(dest => dest.ArrivalDateTime, 
+        opt => opt.MapFrom(src => ParseDateTime(src.ArrTime)));  // 95%
+```
+
+### 3. Typed HTTP Clients
+
+```csharp
+public interface IFlightBridgeClient
+{
+    Task<Reservation?> GetReservationAsync(string id, CancellationToken ct);
+    Task<FlightStatus?> GetFlightStatusAsync(string tailNumber, CancellationToken ct);
+}
+```
+
+### 4. FluentValidation Validators
+
+```csharp
+RuleFor(x => x.TailNum)
+    .Matches(@"^[A-Z0-9]{2,7}$")
+    .WithMessage("Invalid tail number format");
+```
+
+---
+
+## SLA Validation Feature
+
+Automated data freshness checking - would have caught the 1200 Aero issue!
+
+```csharp
+var report = await slaValidator.ValidateDataFreshnessAsync(new SlaValidationRequest
+{
+    EndpointUrl = "https://api.1200aero.com/v1/flights/status/N12345",
+    ExpectedMaxAge = TimeSpan.FromSeconds(30),
+    SampleCount = 100,
+    SampleInterval = TimeSpan.FromSeconds(5)
+});
+
+// Output:
+// 🚨 SLA Validation: SevereViolation
+// Expected Max Age: 00:00:30
+// Actual Average Age: 02:34:17  ← This is the problem!
+// Compliance: 0%
+```
+
+---
+
+## IMS Integration Learning
+
+The IMS learns from:
+1. **Built-in patterns** - Domain-specific knowledge (aviation, etc.)
+2. **Existing integrations** - Analyze your manual mappers
+3. **User feedback** - Corrections improve future suggestions
+
+```
+docflow integrate learn ./src/Integrations/FlightBridge/Mapper.cs
+
+📚 Learning from example...
+   Extracted 23 new patterns
+   Updated confidence on 45 existing patterns
+   
+Next integration will have 94% auto-mapping accuracy!
+```
+
+---
+
+## Implementation Status
+
+Current project status:
+1. ✅ Core C# ↔ Mermaid pipeline (complete)
+2. ✅ Whiteboard scanning with Claude Vision (complete)
+3. ✅ Integration module scaffolded (types and interfaces)
+4. ⏳ Document pipeline (PDF/Word) - planned
+5. ⏳ Full Integration module implementation - planned
+
+The architecture is in place and ready for full implementation!
+
+---
+
+## Aviation Domain Patterns (Pre-seeded)
+
+| External Field Pattern | CDM Target | Confidence |
+|------------------------|------------|------------|
+| `tail_num`, `aircraft_id`, `registration` | TailNumber | 95% |
+| `arr_time`, `eta`, `arrival` | ArrivalDateTime | 93% |
+| `dep_time`, `etd`, `departure` | DepartureDateTime | 93% |
+| `origin_icao`, `from_airport` | OriginAirportCode | 92% |
+| `dest_icao`, `to_airport` | DestinationAirportCode | 92% |
+| `pax`, `passenger_count` | PassengerCount | 90% |
+| `fuel_qty`, `fuel_amount` | FuelQuantity | 88% |
+| `fbo_id`, `handler` | FboId | 85% |
+
+---
+
+## Connection to OpenFlight CDM Work
+
+This module directly applies the CDM architecture work from Signature Aviation:
+- Same canonical model principles
+- Same DDD patterns
+- Same integration challenges (FlightBridge, 1200 Aero, etc.)
+
+DocFlow.Integration is the tool that would have automated much of that integration work.
diff --git a/install.ps1 b/install.ps1
new file mode 100644
index 0000000..f4cc533
--- /dev/null
+++ b/install.ps1
@@ -0,0 +1,164 @@
+# DocFlow Installation Script (Windows)
+# Installs DocFlow as a global .NET tool
+
+$ErrorActionPreference = "Stop"
+
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$CliProject = Join-Path $ScriptDir "src\DocFlow.CLI"
+
+Write-Host ""
+Write-Host "  ____              _____ _" -ForegroundColor Cyan
+Write-Host " |  _ \  ___   ___ |  ___| | _____      __" -ForegroundColor Cyan
+Write-Host " | | | |/ _ \ / __|| |_  | |/ _ \ \ /\ / /" -ForegroundColor Cyan
+Write-Host " | |_| | (_) | (__ |  _| | | (_) \ V  V /" -ForegroundColor Cyan
+Write-Host " |____/ \___/ \___||_|   |_|\___/ \_/\_/" -ForegroundColor Cyan
+Write-Host ""
+Write-Host " Intelligent Documentation and Modeling Toolkit" -ForegroundColor Gray
+Write-Host ""
+
+# Check for .NET SDK
+try {
+    $dotnetVersion = dotnet --version
+    Write-Host "✓ Found .NET SDK: $dotnetVersion" -ForegroundColor Green
+} catch {
+    Write-Host "❌ .NET SDK not found. Please install .NET 8.0 or later." -ForegroundColor Red
+    Write-Host "   https://dotnet.microsoft.com/download"
+    exit 1
+}
+
+# Build the project
+Write-Host ""
+Write-Host "📦 Building DocFlow..." -ForegroundColor Yellow
+dotnet build $ScriptDir -c Release --nologo -v q
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+# Pack the CLI tool
+Write-Host ""
+Write-Host "📦 Packing CLI tool..." -ForegroundColor Yellow
+$nupkgDir = Join-Path $ScriptDir "nupkg"
+dotnet pack $CliProject -c Release --nologo -v q -o $nupkgDir
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+# Uninstall existing version if present
+Write-Host ""
+Write-Host "🔄 Checking for existing installation..." -ForegroundColor Yellow
+$existingTool = dotnet tool list -g | Select-String "docflow"
+if ($existingTool) {
+    Write-Host "   Removing existing version..." -ForegroundColor Gray
+    dotnet tool uninstall -g DocFlow.CLI 2>$null
+}
+
+# Install globally
+Write-Host ""
+Write-Host "🚀 Installing DocFlow globally..." -ForegroundColor Yellow
+dotnet tool install -g DocFlow.CLI --add-source $nupkgDir --no-cache
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+Write-Host ""
+Write-Host "✅ DocFlow installed successfully!" -ForegroundColor Green
+Write-Host ""
+
+# Check PATH
+$toolsPath = Join-Path $env:USERPROFILE ".dotnet\tools"
+if ($env:PATH -notlike "*$toolsPath*") {
+    Write-Host "⚠️  Note: You may need to restart your terminal or add to PATH:" -ForegroundColor Yellow
+    Write-Host "   $toolsPath" -ForegroundColor Gray
+    Write-Host ""
+}
+
+# API Key Configuration
+Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor DarkGray
+Write-Host "🔑 API Key Configuration (for whiteboard scanning)" -ForegroundColor Cyan
+Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor DarkGray
+Write-Host ""
+Write-Host "The 'docflow scan' command requires an Anthropic API key."
+Write-Host "Get your key at: https://console.anthropic.com/settings/keys" -ForegroundColor Blue
+Write-Host ""
+
+$configureKey = Read-Host "Would you like to configure your API key now? (y/N)"
+
+if ($configureKey -eq 'y' -or $configureKey -eq 'Y') {
+    Write-Host ""
+    $apiKey = Read-Host "Enter your Anthropic API key" -AsSecureString
+    $apiKeyPlain = [Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($apiKey))
+    
+    if ($apiKeyPlain) {
+        Write-Host ""
+        Write-Host "How would you like to store the key?"
+        Write-Host "  1) Environment variable (user-level, persistent)"
+        Write-Host "  2) Config file (~/.docflow/config.json)"
+        Write-Host "  3) Both"
+        Write-Host ""
+        $storageOption = Read-Host "Choose option (1/2/3)"
+        
+        switch ($storageOption) {
+            "1" {
+                [Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", $apiKeyPlain, "User")
+                $env:ANTHROPIC_API_KEY = $apiKeyPlain
+                Write-Host ""
+                Write-Host "✓ API key saved as user environment variable" -ForegroundColor Green
+                Write-Host "  Restart your terminal for changes to take effect." -ForegroundColor Gray
+            }
+            "2" {
+                $configDir = Join-Path $env:USERPROFILE ".docflow"
+                if (-not (Test-Path $configDir)) {
+                    New-Item -ItemType Directory -Path $configDir | Out-Null
+                }
+                $configFile = Join-Path $configDir "config.json"
+                $configContent = @{
+                    anthropicApiKey = $apiKeyPlain
+                } | ConvertTo-Json
+                $configContent | Out-File -FilePath $configFile -Encoding UTF8
+                Write-Host ""
+                Write-Host "✓ API key saved to $configFile" -ForegroundColor Green
+            }
+            "3" {
+                # Environment variable
+                [Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", $apiKeyPlain, "User")
+                $env:ANTHROPIC_API_KEY = $apiKeyPlain
+                
+                # Config file
+                $configDir = Join-Path $env:USERPROFILE ".docflow"
+                if (-not (Test-Path $configDir)) {
+                    New-Item -ItemType Directory -Path $configDir | Out-Null
+                }
+                $configFile = Join-Path $configDir "config.json"
+                $configContent = @{
+                    anthropicApiKey = $apiKeyPlain
+                } | ConvertTo-Json
+                $configContent | Out-File -FilePath $configFile -Encoding UTF8
+                
+                Write-Host ""
+                Write-Host "✓ API key saved as user environment variable" -ForegroundColor Green
+                Write-Host "✓ API key saved to $configFile" -ForegroundColor Green
+                Write-Host "  Restart your terminal for env changes to take effect." -ForegroundColor Gray
+            }
+            default {
+                Write-Host "Skipped. You can configure later." -ForegroundColor Gray
+            }
+        }
+    }
+} else {
+    Write-Host ""
+    Write-Host "You can configure your API key later:" -ForegroundColor White
+    Write-Host ""
+    Write-Host "  Option 1: Environment variable" -ForegroundColor Gray
+    Write-Host '    $env:ANTHROPIC_API_KEY = "your-key"' -ForegroundColor DarkGray
+    Write-Host "    Or set permanently via System Properties > Environment Variables" -ForegroundColor DarkGray
+    Write-Host ""
+    Write-Host "  Option 2: Config file (~/.docflow/config.json)" -ForegroundColor Gray
+    Write-Host '    {"anthropicApiKey": "your-key"}' -ForegroundColor DarkGray
+    Write-Host ""
+    Write-Host "  Option 3: Project config (./docflow.json in your project)" -ForegroundColor Gray
+    Write-Host '    {"anthropicApiKey": "your-key"}' -ForegroundColor DarkGray
+}
+
+Write-Host ""
+Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor DarkGray
+Write-Host "Usage:" -ForegroundColor White
+Write-Host "  docflow diagram <file.cs>     Generate Mermaid from C#" -ForegroundColor Gray
+Write-Host "  docflow codegen <file.mmd>    Generate C# from Mermaid" -ForegroundColor Gray
+Write-Host "  docflow scan <image>          Scan whiteboard photo" -ForegroundColor Gray
+Write-Host "  docflow --help                Show all commands" -ForegroundColor Gray
+Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor DarkGray
+Write-Host ""
diff --git a/install.sh b/install.sh
new file mode 100644
index 0000000..4cc0187
--- /dev/null
+++ b/install.sh
@@ -0,0 +1,155 @@
+#!/bin/bash
+# DocFlow Installation Script
+# Installs DocFlow as a global .NET tool
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLI_PROJECT="$SCRIPT_DIR/src/DocFlow.CLI"
+
+echo ""
+echo "  ____              _____ _"
+echo " |  _ \  ___   ___ |  ___| | _____      __"
+echo " | | | |/ _ \ / __|| |_  | |/ _ \ \ /\ / /"
+echo " | |_| | (_) | (__ |  _| | | (_) \ V  V /"
+echo " |____/ \___/ \___||_|   |_|\___/ \_/\_/"
+echo ""
+echo " Intelligent Documentation and Modeling Toolkit"
+echo ""
+
+# Check for .NET SDK
+if ! command -v dotnet &> /dev/null; then
+    echo "❌ .NET SDK not found. Please install .NET 8.0 or later."
+    echo "   https://dotnet.microsoft.com/download"
+    exit 1
+fi
+
+DOTNET_VERSION=$(dotnet --version)
+echo "✓ Found .NET SDK: $DOTNET_VERSION"
+
+# Build the project
+echo ""
+echo "📦 Building DocFlow..."
+dotnet build "$SCRIPT_DIR" -c Release --nologo -v q
+
+# Pack the CLI tool
+echo ""
+echo "📦 Packing CLI tool..."
+dotnet pack "$CLI_PROJECT" -c Release --nologo -v q -o "$SCRIPT_DIR/nupkg"
+
+# Uninstall existing version if present
+echo ""
+echo "🔄 Checking for existing installation..."
+if dotnet tool list -g | grep -q "docflow"; then
+    echo "   Removing existing version..."
+    dotnet tool uninstall -g DocFlow.CLI 2>/dev/null || true
+fi
+
+# Install globally
+echo ""
+echo "🚀 Installing DocFlow globally..."
+dotnet tool install -g DocFlow.CLI --add-source "$SCRIPT_DIR/nupkg" --no-cache
+
+echo ""
+echo "✅ DocFlow installed successfully!"
+echo ""
+
+# Check if ~/.dotnet/tools is in PATH
+if [[ ":$PATH:" != *":$HOME/.dotnet/tools:"* ]]; then
+    echo "⚠️  Note: Add ~/.dotnet/tools to your PATH:"
+    echo "   export PATH=\"\$PATH:\$HOME/.dotnet/tools\""
+    echo ""
+fi
+
+# API Key Configuration
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🔑 API Key Configuration (for whiteboard scanning)"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "The 'docflow scan' command requires an Anthropic API key."
+echo "Get your key at: https://console.anthropic.com/settings/keys"
+echo ""
+
+read -p "Would you like to configure your API key now? (y/N): " CONFIGURE_KEY
+
+if [[ "$CONFIGURE_KEY" =~ ^[Yy]$ ]]; then
+    echo ""
+    read -sp "Enter your Anthropic API key: " API_KEY
+    echo ""
+    
+    if [ -n "$API_KEY" ]; then
+        echo ""
+        echo "How would you like to store the key?"
+        echo "  1) Environment variable (added to ~/.bashrc)"
+        echo "  2) Config file (~/.docflow/config.json)"
+        echo "  3) Both"
+        echo ""
+        read -p "Choose option (1/2/3): " STORAGE_OPTION
+        
+        case $STORAGE_OPTION in
+            1)
+                echo "" >> ~/.bashrc
+                echo "# DocFlow API Key" >> ~/.bashrc
+                echo "export ANTHROPIC_API_KEY='$API_KEY'" >> ~/.bashrc
+                echo ""
+                echo "✓ API key added to ~/.bashrc"
+                echo "  Run 'source ~/.bashrc' or restart your terminal."
+                ;;
+            2)
+                mkdir -p ~/.docflow
+                cat > ~/.docflow/config.json << EOF
+{
+  "anthropicApiKey": "$API_KEY"
+}
+EOF
+                chmod 600 ~/.docflow/config.json
+                echo ""
+                echo "✓ API key saved to ~/.docflow/config.json"
+                ;;
+            3)
+                # Environment variable
+                echo "" >> ~/.bashrc
+                echo "# DocFlow API Key" >> ~/.bashrc
+                echo "export ANTHROPIC_API_KEY='$API_KEY'" >> ~/.bashrc
+                
+                # Config file
+                mkdir -p ~/.docflow
+                cat > ~/.docflow/config.json << EOF
+{
+  "anthropicApiKey": "$API_KEY"
+}
+EOF
+                chmod 600 ~/.docflow/config.json
+                echo ""
+                echo "✓ API key added to ~/.bashrc"
+                echo "✓ API key saved to ~/.docflow/config.json"
+                echo "  Run 'source ~/.bashrc' or restart your terminal."
+                ;;
+            *)
+                echo "Skipped. You can configure later."
+                ;;
+        esac
+    fi
+else
+    echo ""
+    echo "You can configure your API key later:"
+    echo ""
+    echo "  Option 1: Environment variable"
+    echo "    export ANTHROPIC_API_KEY='your-key'"
+    echo ""
+    echo "  Option 2: Config file (~/.docflow/config.json)"
+    echo '    {"anthropicApiKey": "your-key"}'
+    echo ""
+    echo "  Option 3: Project config (./docflow.json in your project)"
+    echo '    {"anthropicApiKey": "your-key"}'
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Usage:"
+echo "  docflow diagram <file.cs>     Generate Mermaid from C#"
+echo "  docflow codegen <file.mmd>    Generate C# from Mermaid"
+echo "  docflow scan <image>          Scan whiteboard photo"
+echo "  docflow --help                Show all commands"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
diff --git a/nuget.config b/nuget.config
new file mode 100644
index 0000000..3a9f6b3
--- /dev/null
+++ b/nuget.config
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+  <packageSources>
+    <clear />
+    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
+  </packageSources>
+</configuration>
\ No newline at end of file
diff --git a/samples/ECommerce/Domain.cs b/samples/ECommerce/Domain.cs
new file mode 100644
index 0000000..12ee576
--- /dev/null
+++ b/samples/ECommerce/Domain.cs
@@ -0,0 +1,145 @@
+namespace ECommerce.Domain;
+
+/// <summary>
+/// Represents a customer in the e-commerce system.
+/// </summary>
+public class Customer
+{
+    public Guid Id { get; init; }
+    public required string Name { get; set; }
+    public required string Email { get; set; }
+    public Address? ShippingAddress { get; set; }
+    public DateTime CreatedAt { get; init; } = DateTime.UtcNow;
+}
+
+/// <summary>
+/// A customer's address - value object with no identity.
+/// </summary>
+public record Address(
+    string Street,
+    string City,
+    string State,
+    string PostalCode,
+    string Country);
+
+/// <summary>
+/// An order placed by a customer - aggregate root.
+/// </summary>
+public class Order
+{
+    public Guid Id { get; init; }
+    public Guid CustomerId { get; init; }
+    public required OrderStatus Status { get; set; }
+    public ICollection<LineItem> LineItems { get; init; } = new List<LineItem>();
+    public Money Total => CalculateTotal();
+    public DateTime CreatedAt { get; init; } = DateTime.UtcNow;
+    public DateTime? ShippedAt { get; set; }
+
+    /// <summary>
+    /// Add a product to the order.
+    /// </summary>
+    public void AddLineItem(Product product, int quantity)
+    {
+        var lineItem = new LineItem
+        {
+            Id = Guid.NewGuid(),
+            ProductId = product.Id,
+            ProductName = product.Name,
+            UnitPrice = product.Price,
+            Quantity = quantity
+        };
+        LineItems.Add(lineItem);
+    }
+
+    /// <summary>
+    /// Calculate the total price of the order.
+    /// </summary>
+    public Money CalculateTotal()
+    {
+        var total = LineItems.Sum(li => li.UnitPrice.Amount * li.Quantity);
+        var currency = LineItems.FirstOrDefault()?.UnitPrice.Currency ?? "USD";
+        return new Money(total, currency);
+    }
+
+    /// <summary>
+    /// Ship the order.
+    /// </summary>
+    public void Ship()
+    {
+        if (Status != OrderStatus.Confirmed)
+            throw new InvalidOperationException("Can only ship confirmed orders");
+        Status = OrderStatus.Shipped;
+        ShippedAt = DateTime.UtcNow;
+    }
+}
+
+/// <summary>
+/// A line item within an order - entity owned by Order aggregate.
+/// </summary>
+public class LineItem
+{
+    public Guid Id { get; init; }
+    public Guid ProductId { get; init; }
+    public required string ProductName { get; set; }
+    public required Money UnitPrice { get; set; }
+    public int Quantity { get; set; }
+}
+
+/// <summary>
+/// Represents a monetary amount - value object.
+/// </summary>
+public record Money(decimal Amount, string Currency)
+{
+    public static Money Zero(string currency = "USD") => new(0, currency);
+
+    public static Money operator +(Money a, Money b)
+    {
+        if (a.Currency != b.Currency)
+            throw new InvalidOperationException("Cannot add money with different currencies");
+        return new Money(a.Amount + b.Amount, a.Currency);
+    }
+}
+
+/// <summary>
+/// A product available for purchase.
+/// </summary>
+public class Product
+{
+    public Guid Id { get; init; }
+    public required string Name { get; set; }
+    public string? Description { get; set; }
+    public required Money Price { get; set; }
+    public required string Sku { get; set; }
+    public int StockQuantity { get; set; }
+}
+
+/// <summary>
+/// Status of an order throughout its lifecycle.
+/// </summary>
+public enum OrderStatus
+{
+    Draft,
+    Confirmed,
+    Shipped,
+    Delivered,
+    Cancelled
+}
+
+/// <summary>
+/// Event raised when an order is placed.
+/// </summary>
+public record OrderPlacedEvent(
+    Guid OrderId,
+    Guid CustomerId,
+    decimal TotalAmount,
+    DateTime OccurredAt);
+
+/// <summary>
+/// Repository interface for persisting orders.
+/// </summary>
+public interface IOrderRepository
+{
+    Task<Order?> GetByIdAsync(Guid id, CancellationToken cancellationToken = default);
+    Task<IReadOnlyList<Order>> GetByCustomerIdAsync(Guid customerId, CancellationToken cancellationToken = default);
+    Task SaveAsync(Order order, CancellationToken cancellationToken = default);
+}
diff --git a/samples/ECommerce/Domain.generated.cs b/samples/ECommerce/Domain.generated.cs
new file mode 100644
index 0000000..0ca8445
--- /dev/null
+++ b/samples/ECommerce/Domain.generated.cs
@@ -0,0 +1,87 @@
+namespace Domain.Domain;
+
+public enum OrderStatus
+{
+    Draft,
+    Confirmed,
+    Shipped,
+    Delivered,
+    Cancelled
+}
+
+public interface IOrderRepository
+{
+}
+
+public record Address(
+    string Street,
+    string City,
+    string State,
+    string PostalCode,
+    string Country);
+
+public record Money(
+    decimal Amount,
+    string Currency)
+{
+    public static Money Zero(object currency)
+    {
+        throw new NotImplementedException();
+    }
+}
+
+public record OrderPlacedEvent(
+    Guid OrderId,
+    Guid CustomerId,
+    decimal TotalAmount,
+    DateTime OccurredAt);
+
+public class Customer
+{
+    public Guid Id { get; init; }
+    public string Name { get; set; }
+    public string Email { get; set; }
+    public Address ShippingAddress { get; set; }
+    public DateTime CreatedAt { get; init; }
+}
+
+public class LineItem
+{
+    public Guid Id { get; init; }
+    public Guid ProductId { get; set; }
+    public string ProductName { get; set; }
+    public Money UnitPrice { get; set; }
+    public int Quantity { get; set; }
+}
+
+public class Product
+{
+    public Guid Id { get; init; }
+    public string Name { get; set; }
+    public string Description { get; set; }
+    public Money Price { get; set; }
+    public string Sku { get; set; }
+    public int StockQuantity { get; set; }
+}
+
+public class Order
+{
+    public Guid Id { get; init; }
+    public Guid CustomerId { get; set; }
+    public OrderStatus Status { get; set; }
+    public ICollection<LineItem> LineItems { get; init; } = new List<LineItem>();
+    public Money Total { get; set; }
+    public DateTime CreatedAt { get; init; }
+    public DateTime? ShippedAt { get; set; }
+
+    public void AddLineItem(object product, object quantity)
+    {
+    }
+    public Money CalculateTotal()
+    {
+        throw new NotImplementedException();
+    }
+    public void Ship()
+    {
+    }
+}
diff --git a/samples/ECommerce/Domain.mmd b/samples/ECommerce/Domain.mmd
new file mode 100644
index 0000000..abf401d
--- /dev/null
+++ b/samples/ECommerce/Domain.mmd
@@ -0,0 +1,78 @@
+classDiagram
+    class Customer {
+        <<Entity>>
+        +Id : Guid
+        +Name : string
+        +Email : string
+        +ShippingAddress : Address
+        +CreatedAt : DateTime
+    }
+    class Address {
+        <<ValueObject>>
+        +Street : string
+        +City : string
+        +State : string
+        +PostalCode : string
+        +Country : string
+    }
+    class Order {
+        <<AggregateRoot>>
+        +Id : Guid
+        +CustomerId : Guid
+        +Status : OrderStatus
+        +LineItems : ICollection~LineItem~
+        +Total : Money
+        +CreatedAt : DateTime
+        +ShippedAt : DateTime?
+        +AddLineItem(product, quantity) void
+        +CalculateTotal() Money
+        +Ship() void
+    }
+    class LineItem {
+        <<Entity>>
+        +Id : Guid
+        +ProductId : Guid
+        +ProductName : string
+        +UnitPrice : Money
+        +Quantity : int
+    }
+    class Money {
+        <<ValueObject>>
+        +Amount : decimal
+        +Currency : string
+        +Zero(currency) Money$
+    }
+    class Product {
+        <<Entity>>
+        +Id : Guid
+        +Name : string
+        +Description : string
+        +Price : Money
+        +Sku : string
+        +StockQuantity : int
+    }
+    class OrderPlacedEvent {
+        <<ValueObject>>
+        +OrderId : Guid
+        +CustomerId : Guid
+        +TotalAmount : decimal
+        +OccurredAt : DateTime
+    }
+    class IOrderRepository {
+        <<interface>>
+    }
+    class OrderStatus {
+        <<enumeration>>
+        +Draft : OrderStatus
+        +Confirmed : OrderStatus
+        +Shipped : OrderStatus
+        +Delivered : OrderStatus
+        +Cancelled : OrderStatus
+    }
+
+    Customer --> Address : ShippingAddress
+    Order --> OrderStatus : Status
+    Order --* "*" LineItem : LineItems
+    Order --> Money : Total
+    LineItem --> Money : UnitPrice
+    Product --> Money : Price
diff --git a/samples/whiteboard-demos/README.md b/samples/whiteboard-demos/README.md
new file mode 100644
index 0000000..f2aa78b
--- /dev/null
+++ b/samples/whiteboard-demos/README.md
@@ -0,0 +1,270 @@
+# Whiteboard Scanner Demo
+
+Test the DocFlow AI-powered whiteboard scanning feature with your own images.
+
+## Prerequisites
+
+### 1. Build DocFlow
+
+```bash
+cd /path/to/DocFlow
+dotnet build
+```
+
+### 2. Configure Claude API Key
+
+The scanner uses Claude's Vision API. Set up your key using one of these methods:
+
+**Option 1: Environment Variable (Recommended)**
+```bash
+# Linux/macOS/WSL
+export ANTHROPIC_API_KEY='sk-ant-api03-...'
+
+# Windows Command Prompt
+set ANTHROPIC_API_KEY=sk-ant-api03-...
+
+# Windows PowerShell
+$env:ANTHROPIC_API_KEY='sk-ant-api03-...'
+```
+
+**Option 2: User Config File**
+
+Create `~/.docflow/config.json`:
+```json
+{
+  "anthropicApiKey": "sk-ant-api03-..."
+}
+```
+
+**Option 3: Project Config File**
+
+Create `docflow.json` in your working directory:
+```json
+{
+  "anthropicApiKey": "sk-ant-api03-..."
+}
+```
+
+Get your API key at: https://console.anthropic.com/
+
+---
+
+## Usage
+
+### Basic Scan
+
+```bash
+# Using the CLI directly
+dotnet run --project src/DocFlow.CLI -- scan path/to/whiteboard.jpg
+
+# With output file
+dotnet run --project src/DocFlow.CLI -- scan whiteboard.jpg -o diagram.mmd
+
+# With context hint for better accuracy
+dotnet run --project src/DocFlow.CLI -- scan whiteboard.jpg -c "e-commerce order management"
+
+# Verbose mode
+dotnet run --project src/DocFlow.CLI -- scan whiteboard.jpg -v
+```
+
+### If Installed Globally
+
+```bash
+docflow scan whiteboard.jpg
+docflow scan whiteboard.jpg -o output.mmd -c "DDD aggregate design"
+```
+
+---
+
+## Supported Image Formats
+
+| Format | Extension |
+|--------|-----------|
+| JPEG | `.jpg`, `.jpeg` |
+| PNG | `.png` |
+| GIF | `.gif` |
+| WebP | `.webp` |
+
+---
+
+## Tips for Best Results
+
+### Image Quality
+
+1. **Good Lighting**: Ensure the whiteboard is well-lit without glare or shadows
+2. **High Contrast**: Use dark markers (black, blue) on white background
+3. **Clear Handwriting**: Write legibly with thick marker strokes
+4. **Clean Background**: Erase old content, avoid clutter
+
+### Camera Angle
+
+1. **Perpendicular**: Take photos straight-on, not at an angle
+2. **Full Frame**: Include all diagram elements in the shot
+3. **Stable**: Avoid motion blur - hold camera steady
+4. **High Resolution**: Use highest quality camera setting
+
+### Diagram Style
+
+1. **Standard Notation**: Use recognizable UML-style boxes
+2. **Clear Labels**: Write class names and property names clearly
+3. **Distinct Arrows**: Make relationship lines clear with proper arrowheads
+4. **Spacing**: Leave space between elements
+
+---
+
+## Example Diagrams to Draw
+
+### Simple Class Diagram
+
+```
+┌────────────────────┐
+│     Customer       │
+├────────────────────┤
+│ - id: int          │
+│ - name: string     │
+│ - email: string    │
+├────────────────────┤
+│ + save()           │
+│ + validate()       │
+└────────────────────┘
+         │
+         │ places
+         ▼
+┌────────────────────┐
+│      Order         │
+├────────────────────┤
+│ - orderId: int     │
+│ - date: DateTime   │
+│ - total: decimal   │
+└────────────────────┘
+```
+
+### DDD Aggregate
+
+```
+    <<Aggregate Root>>
+┌────────────────────┐
+│   Reservation      │
+├────────────────────┤
+│ - id               │
+│ - status           │
+└────────────────────┘
+         │
+    ┌────┴────┐
+    ▼         ▼
+┌────────┐  ┌──────────┐
+│ Flight │  │ Passenger│
+└────────┘  └──────────┘
+```
+
+---
+
+## Example Output
+
+```
+$ docflow scan whiteboard.jpg -c "order management"
+
+  ____                   _____   _
+ |  _ \    ___     ___  |  ___| | |   ___   __      __
+ | | | |  / _ \   / __| | |_    | |  / _ \  \ \ /\ / /
+ | |_| | | (_) | | (__  |  _|   | | | (_) |  \ V  V /
+ |____/   \___/   \___| |_|     |_|  \___/    \_/\_/
+
+v1.0.0-preview - Intelligent Documentation and Modeling Toolkit
+
+Scanning whiteboard image: whiteboard.jpg
+
+╭──────────────────┬───────────────╮
+│ Property         │ Value         │
+├──────────────────┼───────────────┤
+│ Diagram Type     │ ClassDiagram  │
+│ Confidence       │ 87%           │
+│ Entities Found   │ 4             │
+│ Relationships    │ 3             │
+│ Analysis Time    │ 2.1s          │
+╰──────────────────┴───────────────╯
+
+Detected Entities:
+┌────────────┬────────────┬────────────┐
+│ Entity     │ Properties │ Operations │
+├────────────┼────────────┼────────────┤
+│ Customer   │ 3          │ 2          │
+│ Order      │ 4          │ 1          │
+│ OrderLine  │ 2          │ 0          │
+│ Product    │ 3          │ 0          │
+└────────────┴────────────┴────────────┘
+
+╭─Generated Mermaid Diagram────────────────────────────────╮
+│ classDiagram                                             │
+│     class Customer {                                     │
+│         -id: int                                         │
+│         -name: string                                    │
+│         -email: string                                   │
+│         +save()                                          │
+│         +validate()                                      │
+│     }                                                    │
+│     class Order {                                        │
+│         -orderId: int                                    │
+│         -date: DateTime                                  │
+│         -status: string                                  │
+│         -total: decimal                                  │
+│         +calculateTotal()                                │
+│     }                                                    │
+│     Customer --> Order                                   │
+│     Order *-- OrderLine                                  │
+│     OrderLine --> Product                                │
+╰──────────────────────────────────────────────────────────╯
+
+Success! Diagram saved to whiteboard.mmd
+Completed in 2847ms
+```
+
+---
+
+## Next Steps
+
+After generating the Mermaid diagram, you can:
+
+```bash
+# Generate C# code from the diagram
+docflow codegen whiteboard.mmd -o Models.cs -n MyApp.Domain
+
+# Verify with round-trip
+docflow roundtrip Models.cs --compare
+
+# View the Mermaid diagram
+# Copy content to https://mermaid.live for visualization
+```
+
+---
+
+## Troubleshooting
+
+### "Claude API key not configured"
+
+Set one of the configuration options shown above.
+
+### "Unsupported image format"
+
+Use JPG, PNG, GIF, or WEBP formats.
+
+### Poor Recognition Results
+
+- Improve lighting and contrast
+- Take a straighter photo
+- Use thicker markers
+- Add context with `-c` flag
+- Ensure all text is legible
+
+### API Errors
+
+- Verify API key is valid
+- Check Anthropic account credits
+- Ensure internet connectivity
+- Check for rate limiting (wait and retry)
+
+### Empty or Minimal Output
+
+- The image may be too small or blurry
+- Content may not be recognizable as a diagram
+- Try adding a context hint with `-c`
diff --git a/samples/whiteboard-demos/whiteboard-ddd.cs b/samples/whiteboard-demos/whiteboard-ddd.cs
new file mode 100644
index 0000000..6ffc858
--- /dev/null
+++ b/samples/whiteboard-demos/whiteboard-ddd.cs
@@ -0,0 +1,21 @@
+namespace whiteboard-ddd.Domain;
+
+public class Customer
+{
+}
+
+public class LineItem
+{
+}
+
+public class Order
+{
+}
+
+public class Product
+{
+}
+
+public class ShippingAddress
+{
+}
diff --git a/samples/whiteboard-demos/whiteboard-ddd.mmd b/samples/whiteboard-demos/whiteboard-ddd.mmd
new file mode 100644
index 0000000..0d3ef23
--- /dev/null
+++ b/samples/whiteboard-demos/whiteboard-ddd.mmd
@@ -0,0 +1,34 @@
+classDiagram
+    class Order {
+        <<aggregate root>>
+        -ID
+        -Status
+        -orderDate
+    }
+    
+    class Product {
+        -Qrulart
+    }
+    
+    class LineItem {
+        -Quantity
+        -Price
+    }
+    
+    class ShippingAddress {
+        -Street
+        -City
+        -ZipCode
+        -Cits
+        -mm
+    }
+    
+    class Customer {
+        -CidSi
+        -nome
+    }
+    
+    Order *-- Product
+    Order *-- LineItem
+    Order *-- ShippingAddress
+    Order --> Customer : references
\ No newline at end of file
diff --git a/samples/whiteboard-demos/whiteboard-ddd.png b/samples/whiteboard-demos/whiteboard-ddd.png
new file mode 100644
index 0000000..7d71529
Binary files /dev/null and b/samples/whiteboard-demos/whiteboard-ddd.png differ
diff --git a/samples/whiteboard-demos/whiteboard-ecommerce.mmd b/samples/whiteboard-demos/whiteboard-ecommerce.mmd
new file mode 100644
index 0000000..3e97be6
--- /dev/null
+++ b/samples/whiteboard-demos/whiteboard-ecommerce.mmd
@@ -0,0 +1,65 @@
+classDiagram
+    class User {
+        +id
+        +email
+        +passwordHash
+    }
+    
+    class Amail {
+        +passwordHash
+    }
+    
+    class Orderitem {
+        +status
+        +craad
+    }
+    
+    class Status {
+        +craad
+    }
+    
+    class UnitPrice {
+        +sku
+    }
+    
+    class Product {
+        +name
+        +name
+    }
+    
+    class Name {
+        +name
+    }
+    
+    class Sku {
+        +scku
+    }
+    
+    class Category {
+        +amount
+        +transactionId
+    }
+    
+    class Amount {
+        +transactionId
+    }
+    
+    class Method {
+        +transactionId
+    }
+    
+    User --> Amail
+    User --> Orderitem
+    Amail --> UnitPrice
+    Orderitem --> Status
+    Status --> UnitPrice
+    Orderitem --> Product
+    Status --> Name
+    UnitPrice --> Sku
+    Product --> Name
+    Name --> Sku
+    Product --> Category
+    Name --> Amount
+    Sku --> Method
+    Category --> Amount
+    Amount --> Method
\ No newline at end of file
diff --git a/samples/whiteboard-demos/whiteboard-ecommerce.png b/samples/whiteboard-demos/whiteboard-ecommerce.png
new file mode 100644
index 0000000..646553e
Binary files /dev/null and b/samples/whiteboard-demos/whiteboard-ecommerce.png differ
diff --git a/samples/whiteboard-demos/whiteboard-inheritance.mmd b/samples/whiteboard-demos/whiteboard-inheritance.mmd
new file mode 100644
index 0000000..6850473
--- /dev/null
+++ b/samples/whiteboard-demos/whiteboard-inheritance.mmd
@@ -0,0 +1,17 @@
+classDiagram
+    class Vehicle {
+        +make : String
+        +model : String
+        +year : int
+    }
+    
+    class Car {
+        +numDoors : int
+    }
+    
+    class Motorcicle {
+        +hasSidecar : boolean
+    }
+    
+    Vehicle <|-- Car
+    Vehicle <|-- Motorcicle
\ No newline at end of file
diff --git a/samples/whiteboard-demos/whiteboard-inheritance.png b/samples/whiteboard-demos/whiteboard-inheritance.png
new file mode 100644
index 0000000..65699a1
Binary files /dev/null and b/samples/whiteboard-demos/whiteboard-inheritance.png differ
diff --git a/samples/whiteboard-demos/whiteboard-test.mmd b/samples/whiteboard-demos/whiteboard-test.mmd
new file mode 100644
index 0000000..020a1d8
--- /dev/null
+++ b/samples/whiteboard-demos/whiteboard-test.mmd
@@ -0,0 +1,18 @@
+classDiagram
+    class Customer {
+        +name : String
+        +email : String
+    }
+    
+    class Order {
+        +total : Number
+    }
+    
+    class Product {
+        +name : String
+        +price : Number
+    }
+    
+    Customer --> Order
+    Customer --> Product
+    Order --> Product
\ No newline at end of file
diff --git a/samples/whiteboard-demos/whiteboard-test.png b/samples/whiteboard-demos/whiteboard-test.png
new file mode 100644
index 0000000..a985582
Binary files /dev/null and b/samples/whiteboard-demos/whiteboard-test.png differ
diff --git a/src/DocFlow.AI/DocFlow.AI.csproj b/src/DocFlow.AI/DocFlow.AI.csproj
index 9f739ab..85a4d72 100644
--- a/src/DocFlow.AI/DocFlow.AI.csproj
+++ b/src/DocFlow.AI/DocFlow.AI.csproj
@@ -17,7 +17,7 @@
     <PackageReference Include="Microsoft.Extensions.Http" Version="8.0.0" />
     <PackageReference Include="Microsoft.Extensions.Options" Version="8.0.0" />
     <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.0" />
-    <PackageReference Include="System.Text.Json" Version="8.0.0" />
+    <PackageReference Include="System.Text.Json" Version="8.0.5" />
   </ItemGroup>
 
 </Project>
diff --git a/src/DocFlow.AI/Providers/ClaudeProvider.cs b/src/DocFlow.AI/Providers/ClaudeProvider.cs
new file mode 100644
index 0000000..39ef3a5
--- /dev/null
+++ b/src/DocFlow.AI/Providers/ClaudeProvider.cs
@@ -0,0 +1,780 @@
+using System.Diagnostics;
+using System.Net.Http.Headers;
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+
+namespace DocFlow.AI.Providers;
+
+/// <summary>
+/// Claude AI provider implementation for DocFlow.
+/// Uses the Anthropic Messages API for vision and text analysis.
+/// </summary>
+public sealed class ClaudeProvider : IAiProvider, IDisposable
+{
+    private const string ApiBaseUrl = "https://api.anthropic.com/v1/messages";
+    private const string ApiVersion = "2023-06-01";
+    private const int DefaultMaxTokens = 4096;
+
+    private const string UserConfigFileName = "config.json";
+    private const string ProjectConfigFileName = "docflow.json";
+    private const string DocFlowConfigDir = ".docflow";
+
+    private readonly HttpClient _httpClient;
+    private readonly ILogger<ClaudeProvider>? _logger;
+    private readonly AiProviderOptions _options;
+    private readonly bool _ownsHttpClient;
+    private readonly string? _resolvedApiKey;
+
+    public string ProviderId => "Claude";
+    public bool SupportsVision => true;
+
+    /// <summary>
+    /// Create a ClaudeProvider with default options.
+    /// API key is resolved from environment, user config, or project config.
+    /// </summary>
+    public ClaudeProvider(ILogger<ClaudeProvider>? logger = null)
+        : this(new AiProviderOptions(), null, logger)
+    {
+    }
+
+    /// <summary>
+    /// Create a ClaudeProvider with explicit options.
+    /// </summary>
+    public ClaudeProvider(
+        AiProviderOptions options,
+        HttpClient? httpClient = null,
+        ILogger<ClaudeProvider>? logger = null)
+    {
+        _options = options;
+        _logger = logger;
+
+        // Resolve API key from multiple sources
+        _resolvedApiKey = ResolveApiKey(options, logger);
+
+        if (httpClient != null)
+        {
+            _httpClient = httpClient;
+            _ownsHttpClient = false;
+        }
+        else
+        {
+            _httpClient = new HttpClient
+            {
+                Timeout = options.Timeout
+            };
+            _ownsHttpClient = true;
+        }
+
+        // Set up headers
+        if (!string.IsNullOrEmpty(_resolvedApiKey))
+        {
+            _httpClient.DefaultRequestHeaders.Add("x-api-key", _resolvedApiKey);
+        }
+        _httpClient.DefaultRequestHeaders.Add("anthropic-version", ApiVersion);
+        _httpClient.DefaultRequestHeaders.Accept.Add(
+            new MediaTypeWithQualityHeaderValue("application/json"));
+    }
+
+    /// <summary>
+    /// Create a ClaudeProvider for dependency injection.
+    /// </summary>
+    public ClaudeProvider(
+        IOptions<AiProviderOptions> options,
+        HttpClient httpClient,
+        ILogger<ClaudeProvider> logger)
+        : this(options.Value, httpClient, logger)
+    {
+    }
+
+    public Task<bool> IsAvailableAsync(CancellationToken cancellationToken = default)
+    {
+        if (string.IsNullOrEmpty(_resolvedApiKey))
+        {
+            _logger?.LogWarning("Claude API key not configured");
+            return Task.FromResult(false);
+        }
+
+        // Could do a test request here, but for now just check the key exists
+        return Task.FromResult(true);
+    }
+
+    /// <summary>
+    /// Resolves the API key from multiple sources in priority order:
+    /// 1. Options (explicitly provided)
+    /// 2. Environment variable: ANTHROPIC_API_KEY
+    /// 3. User config: ~/.docflow/config.json
+    /// 4. Project config: ./docflow.json
+    /// </summary>
+    /// <returns>The API key if found, null otherwise</returns>
+    public static string? ResolveApiKey(AiProviderOptions? options = null, ILogger? logger = null)
+    {
+        // 1. Check options (explicitly provided)
+        if (!string.IsNullOrEmpty(options?.ClaudeApiKey))
+        {
+            logger?.LogDebug("Using API key from options");
+            return options.ClaudeApiKey;
+        }
+
+        // 2. Check environment variable
+        var envKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY");
+        if (!string.IsNullOrEmpty(envKey))
+        {
+            logger?.LogDebug("Using API key from ANTHROPIC_API_KEY environment variable");
+            return envKey;
+        }
+
+        // 3. Check user config file (~/.docflow/config.json)
+        var userConfigPath = GetUserConfigPath();
+        var userKey = LoadApiKeyFromConfig(userConfigPath, logger);
+        if (!string.IsNullOrEmpty(userKey))
+        {
+            logger?.LogDebug("Using API key from user config: {Path}", userConfigPath);
+            return userKey;
+        }
+
+        // 4. Check project config file (./docflow.json)
+        var projectConfigPath = Path.Combine(Directory.GetCurrentDirectory(), ProjectConfigFileName);
+        var projectKey = LoadApiKeyFromConfig(projectConfigPath, logger);
+        if (!string.IsNullOrEmpty(projectKey))
+        {
+            logger?.LogDebug("Using API key from project config: {Path}", projectConfigPath);
+            return projectKey;
+        }
+
+        return null;
+    }
+
+    /// <summary>
+    /// Gets the API key, throwing an exception with helpful instructions if not found.
+    /// </summary>
+    public static string GetApiKeyOrThrow(AiProviderOptions? options = null)
+    {
+        var apiKey = ResolveApiKey(options);
+
+        if (string.IsNullOrEmpty(apiKey))
+        {
+            var userConfigPath = GetUserConfigPath();
+            var projectConfigPath = Path.Combine(Directory.GetCurrentDirectory(), ProjectConfigFileName);
+
+            throw new ApiKeyNotFoundException(
+                $$"""
+                Claude API key not configured.
+
+                Please configure your API key using one of these methods (in priority order):
+
+                1. Environment variable:
+                   Linux/macOS: export ANTHROPIC_API_KEY='sk-ant-...'
+                   Windows CMD: set ANTHROPIC_API_KEY=sk-ant-...
+                   PowerShell:  $env:ANTHROPIC_API_KEY='sk-ant-...'
+
+                2. User config file: {{userConfigPath}}
+                   {
+                     "anthropicApiKey": "sk-ant-..."
+                   }
+
+                3. Project config file: {{projectConfigPath}}
+                   {
+                     "anthropicApiKey": "sk-ant-..."
+                   }
+
+                Get your API key at: https://console.anthropic.com/
+                """);
+        }
+
+        return apiKey;
+    }
+
+    /// <summary>
+    /// Gets the path to the user config directory (~/.docflow)
+    /// </summary>
+    public static string GetUserConfigDirectory()
+    {
+        // Cross-platform: Use HOME on Unix, USERPROFILE on Windows
+        var homeDir = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
+        return Path.Combine(homeDir, DocFlowConfigDir);
+    }
+
+    /// <summary>
+    /// Gets the path to the user config file (~/.docflow/config.json)
+    /// </summary>
+    public static string GetUserConfigPath()
+    {
+        return Path.Combine(GetUserConfigDirectory(), UserConfigFileName);
+    }
+
+    private static string? LoadApiKeyFromConfig(string configPath, ILogger? logger)
+    {
+        try
+        {
+            if (!File.Exists(configPath))
+            {
+                return null;
+            }
+
+            var json = File.ReadAllText(configPath);
+            var config = JsonSerializer.Deserialize<DocFlowConfig>(json, new JsonSerializerOptions
+            {
+                PropertyNameCaseInsensitive = true
+            });
+
+            return config?.AnthropicApiKey;
+        }
+        catch (JsonException ex)
+        {
+            logger?.LogWarning(ex, "Failed to parse config file: {Path}", configPath);
+            return null;
+        }
+        catch (IOException ex)
+        {
+            logger?.LogWarning(ex, "Failed to read config file: {Path}", configPath);
+            return null;
+        }
+    }
+
+    public async Task<ImageAnalysisResult> AnalyzeImageAsync(
+        ImageAnalysisRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        var stopwatch = Stopwatch.StartNew();
+
+        try
+        {
+            // Build the message content with image
+            var imageBase64 = Convert.ToBase64String(request.ImageData);
+            var mediaType = request.MimeType switch
+            {
+                "image/png" => "image/png",
+                "image/gif" => "image/gif",
+                "image/webp" => "image/webp",
+                _ => "image/jpeg"
+            };
+
+            var userContent = new List<object>
+            {
+                new
+                {
+                    type = "image",
+                    source = new
+                    {
+                        type = "base64",
+                        media_type = mediaType,
+                        data = imageBase64
+                    }
+                },
+                new
+                {
+                    type = "text",
+                    text = request.Prompt
+                }
+            };
+
+            var requestBody = new ClaudeRequest
+            {
+                Model = _options.ClaudeModel,
+                MaxTokens = request.MaxTokens ?? DefaultMaxTokens,
+                System = request.SystemPrompt,
+                Messages =
+                [
+                    new ClaudeMessage
+                    {
+                        Role = "user",
+                        Content = userContent
+                    }
+                ]
+            };
+
+            if (request.Temperature.HasValue)
+            {
+                requestBody.Temperature = request.Temperature.Value;
+            }
+
+            var response = await SendRequestAsync(requestBody, cancellationToken);
+            stopwatch.Stop();
+
+            if (response.Error != null)
+            {
+                return new ImageAnalysisResult
+                {
+                    Success = false,
+                    ErrorMessage = $"{response.Error.Type}: {response.Error.Message}",
+                    Duration = stopwatch.Elapsed
+                };
+            }
+
+            var content = ExtractTextContent(response);
+
+            return new ImageAnalysisResult
+            {
+                Success = true,
+                Content = content,
+                Usage = response.Usage != null ? new TokenUsage
+                {
+                    PromptTokens = response.Usage.InputTokens,
+                    CompletionTokens = response.Usage.OutputTokens
+                } : null,
+                Duration = stopwatch.Elapsed
+            };
+        }
+        catch (HttpRequestException ex)
+        {
+            _logger?.LogError(ex, "HTTP error calling Claude API");
+            return new ImageAnalysisResult
+            {
+                Success = false,
+                ErrorMessage = $"HTTP error: {ex.Message}",
+                Duration = stopwatch.Elapsed
+            };
+        }
+        catch (TaskCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            throw;
+        }
+        catch (TaskCanceledException ex)
+        {
+            _logger?.LogError(ex, "Claude API request timed out");
+            return new ImageAnalysisResult
+            {
+                Success = false,
+                ErrorMessage = "Request timed out",
+                Duration = stopwatch.Elapsed
+            };
+        }
+        catch (Exception ex)
+        {
+            _logger?.LogError(ex, "Unexpected error calling Claude API");
+            return new ImageAnalysisResult
+            {
+                Success = false,
+                ErrorMessage = ex.Message,
+                Duration = stopwatch.Elapsed
+            };
+        }
+    }
+
+    public async Task<TextCompletionResult> CompleteTextAsync(
+        TextCompletionRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        var stopwatch = Stopwatch.StartNew();
+
+        try
+        {
+            var messages = new List<ClaudeMessage>();
+
+            // Add conversation history if present
+            if (request.ConversationHistory != null)
+            {
+                foreach (var msg in request.ConversationHistory)
+                {
+                    messages.Add(new ClaudeMessage
+                    {
+                        Role = msg.Role == MessageRole.User ? "user" : "assistant",
+                        Content = msg.Content
+                    });
+                }
+            }
+
+            // Add the current prompt
+            messages.Add(new ClaudeMessage
+            {
+                Role = "user",
+                Content = request.Prompt
+            });
+
+            var requestBody = new ClaudeRequest
+            {
+                Model = _options.ClaudeModel,
+                MaxTokens = request.MaxTokens ?? DefaultMaxTokens,
+                System = request.SystemPrompt,
+                Messages = messages
+            };
+
+            if (request.Temperature.HasValue)
+            {
+                requestBody.Temperature = request.Temperature.Value;
+            }
+
+            var response = await SendRequestAsync(requestBody, cancellationToken);
+            stopwatch.Stop();
+
+            if (response.Error != null)
+            {
+                return new TextCompletionResult
+                {
+                    Success = false,
+                    ErrorMessage = $"{response.Error.Type}: {response.Error.Message}",
+                    Duration = stopwatch.Elapsed
+                };
+            }
+
+            var content = ExtractTextContent(response);
+
+            return new TextCompletionResult
+            {
+                Success = true,
+                Content = content,
+                Usage = response.Usage != null ? new TokenUsage
+                {
+                    PromptTokens = response.Usage.InputTokens,
+                    CompletionTokens = response.Usage.OutputTokens
+                } : null,
+                Duration = stopwatch.Elapsed
+            };
+        }
+        catch (HttpRequestException ex)
+        {
+            _logger?.LogError(ex, "HTTP error calling Claude API");
+            return new TextCompletionResult
+            {
+                Success = false,
+                ErrorMessage = $"HTTP error: {ex.Message}",
+                Duration = stopwatch.Elapsed
+            };
+        }
+        catch (TaskCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            throw;
+        }
+        catch (Exception ex)
+        {
+            _logger?.LogError(ex, "Unexpected error calling Claude API");
+            return new TextCompletionResult
+            {
+                Success = false,
+                ErrorMessage = ex.Message,
+                Duration = stopwatch.Elapsed
+            };
+        }
+    }
+
+    public async Task<StructuredOutputResult<T>> GenerateStructuredAsync<T>(
+        StructuredOutputRequest request,
+        CancellationToken cancellationToken = default) where T : class
+    {
+        var stopwatch = Stopwatch.StartNew();
+
+        try
+        {
+            var userContent = new List<object>();
+
+            // Add image if present
+            if (request.ImageData != null)
+            {
+                var imageBase64 = Convert.ToBase64String(request.ImageData);
+                var mediaType = request.ImageMimeType ?? "image/jpeg";
+
+                userContent.Add(new
+                {
+                    type = "image",
+                    source = new
+                    {
+                        type = "base64",
+                        media_type = mediaType,
+                        data = imageBase64
+                    }
+                });
+            }
+
+            // Add text prompt
+            userContent.Add(new
+            {
+                type = "text",
+                text = request.Prompt
+            });
+
+            var requestBody = new ClaudeRequest
+            {
+                Model = _options.ClaudeModel,
+                MaxTokens = request.MaxTokens ?? DefaultMaxTokens,
+                System = request.SystemPrompt,
+                Messages =
+                [
+                    new ClaudeMessage
+                    {
+                        Role = "user",
+                        Content = userContent.Count == 1 ? request.Prompt : userContent
+                    }
+                ]
+            };
+
+            if (request.Temperature.HasValue)
+            {
+                requestBody.Temperature = request.Temperature.Value;
+            }
+
+            var response = await SendRequestAsync(requestBody, cancellationToken);
+            stopwatch.Stop();
+
+            if (response.Error != null)
+            {
+                return new StructuredOutputResult<T>
+                {
+                    Success = false,
+                    ErrorMessage = $"{response.Error.Type}: {response.Error.Message}",
+                    Duration = stopwatch.Elapsed
+                };
+            }
+
+            var content = ExtractTextContent(response);
+
+            // Try to parse as JSON
+            T? data = null;
+            string? parseError = null;
+
+            if (!string.IsNullOrEmpty(content))
+            {
+                try
+                {
+                    // Try to extract JSON from the response (it might be wrapped in markdown)
+                    var jsonContent = ExtractJson(content);
+                    data = JsonSerializer.Deserialize<T>(jsonContent, new JsonSerializerOptions
+                    {
+                        PropertyNameCaseInsensitive = true
+                    });
+                }
+                catch (JsonException ex)
+                {
+                    parseError = $"Failed to parse JSON: {ex.Message}";
+                    _logger?.LogWarning(ex, "Failed to parse Claude response as JSON");
+                }
+            }
+
+            return new StructuredOutputResult<T>
+            {
+                Success = data != null,
+                Data = data,
+                RawResponse = content,
+                ErrorMessage = parseError,
+                Usage = response.Usage != null ? new TokenUsage
+                {
+                    PromptTokens = response.Usage.InputTokens,
+                    CompletionTokens = response.Usage.OutputTokens
+                } : null,
+                Duration = stopwatch.Elapsed
+            };
+        }
+        catch (Exception ex)
+        {
+            _logger?.LogError(ex, "Error in GenerateStructuredAsync");
+            return new StructuredOutputResult<T>
+            {
+                Success = false,
+                ErrorMessage = ex.Message,
+                Duration = stopwatch.Elapsed
+            };
+        }
+    }
+
+    private async Task<ClaudeResponse> SendRequestAsync(
+        ClaudeRequest request,
+        CancellationToken cancellationToken)
+    {
+        var jsonOptions = new JsonSerializerOptions
+        {
+            PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower,
+            DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
+        };
+
+        var json = JsonSerializer.Serialize(request, jsonOptions);
+        _logger?.LogDebug("Sending request to Claude API: {RequestLength} chars", json.Length);
+
+        using var content = new StringContent(json, Encoding.UTF8, "application/json");
+        using var response = await _httpClient.PostAsync(ApiBaseUrl, content, cancellationToken);
+
+        var responseJson = await response.Content.ReadAsStringAsync(cancellationToken);
+        _logger?.LogDebug("Received response from Claude API: {StatusCode}", response.StatusCode);
+
+        var result = JsonSerializer.Deserialize<ClaudeResponse>(responseJson, jsonOptions);
+
+        if (result == null)
+        {
+            return new ClaudeResponse
+            {
+                Error = new ClaudeError
+                {
+                    Type = "parse_error",
+                    Message = "Failed to parse API response"
+                }
+            };
+        }
+
+        return result;
+    }
+
+    private static string ExtractTextContent(ClaudeResponse response)
+    {
+        if (response.Content == null || response.Content.Count == 0)
+            return string.Empty;
+
+        var textParts = new List<string>();
+
+        foreach (var block in response.Content)
+        {
+            if (block.Type == "text" && !string.IsNullOrEmpty(block.Text))
+            {
+                textParts.Add(block.Text);
+            }
+        }
+
+        return string.Join("\n", textParts);
+    }
+
+    private static string ExtractJson(string content)
+    {
+        // Try to extract JSON from markdown code blocks
+        var jsonStart = content.IndexOf("```json", StringComparison.OrdinalIgnoreCase);
+        if (jsonStart >= 0)
+        {
+            jsonStart = content.IndexOf('\n', jsonStart) + 1;
+            var jsonEnd = content.IndexOf("```", jsonStart, StringComparison.Ordinal);
+            if (jsonEnd > jsonStart)
+            {
+                return content[jsonStart..jsonEnd].Trim();
+            }
+        }
+
+        // Try to find JSON object or array
+        var firstBrace = content.IndexOf('{');
+        var firstBracket = content.IndexOf('[');
+
+        if (firstBrace >= 0 || firstBracket >= 0)
+        {
+            var start = (firstBrace >= 0 && firstBracket >= 0)
+                ? Math.Min(firstBrace, firstBracket)
+                : Math.Max(firstBrace, firstBracket);
+
+            var isArray = content[start] == '[';
+            var endChar = isArray ? ']' : '}';
+
+            var depth = 0;
+            for (var i = start; i < content.Length; i++)
+            {
+                if (content[i] == (isArray ? '[' : '{')) depth++;
+                else if (content[i] == endChar) depth--;
+
+                if (depth == 0)
+                {
+                    return content[start..(i + 1)];
+                }
+            }
+        }
+
+        return content;
+    }
+
+    public void Dispose()
+    {
+        if (_ownsHttpClient)
+        {
+            _httpClient.Dispose();
+        }
+    }
+}
+
+#region Claude API Models
+
+internal sealed class ClaudeRequest
+{
+    public required string Model { get; init; }
+
+    [JsonPropertyName("max_tokens")]
+    public int MaxTokens { get; init; } = 4096;
+
+    public string? System { get; init; }
+
+    public double? Temperature { get; set; }
+
+    public required List<ClaudeMessage> Messages { get; init; }
+}
+
+internal sealed class ClaudeMessage
+{
+    public required string Role { get; init; }
+
+    // Can be string or array of content blocks
+    public required object Content { get; init; }
+}
+
+internal sealed class ClaudeResponse
+{
+    public string? Id { get; init; }
+    public string? Type { get; init; }
+    public string? Role { get; init; }
+    public List<ContentBlock>? Content { get; init; }
+    public string? Model { get; init; }
+
+    [JsonPropertyName("stop_reason")]
+    public string? StopReason { get; init; }
+
+    public ClaudeUsage? Usage { get; init; }
+    public ClaudeError? Error { get; init; }
+}
+
+internal sealed class ContentBlock
+{
+    public string? Type { get; init; }
+    public string? Text { get; init; }
+}
+
+internal sealed class ClaudeUsage
+{
+    [JsonPropertyName("input_tokens")]
+    public int InputTokens { get; init; }
+
+    [JsonPropertyName("output_tokens")]
+    public int OutputTokens { get; init; }
+}
+
+internal sealed class ClaudeError
+{
+    public string? Type { get; init; }
+    public string? Message { get; init; }
+}
+
+#endregion
+
+#region Config Models
+
+/// <summary>
+/// DocFlow configuration file format for config.json and docflow.json
+/// </summary>
+public sealed class DocFlowConfig
+{
+    /// <summary>
+    /// Anthropic/Claude API key
+    /// </summary>
+    [JsonPropertyName("anthropicApiKey")]
+    public string? AnthropicApiKey { get; init; }
+
+    /// <summary>
+    /// OpenAI API key (for future use)
+    /// </summary>
+    [JsonPropertyName("openaiApiKey")]
+    public string? OpenAiApiKey { get; init; }
+
+    /// <summary>
+    /// Preferred AI provider
+    /// </summary>
+    [JsonPropertyName("preferredProvider")]
+    public string? PreferredProvider { get; init; }
+}
+
+/// <summary>
+/// Exception thrown when the API key is not found in any configured location.
+/// </summary>
+public sealed class ApiKeyNotFoundException : Exception
+{
+    public ApiKeyNotFoundException(string message) : base(message)
+    {
+    }
+
+    public ApiKeyNotFoundException(string message, Exception innerException)
+        : base(message, innerException)
+    {
+    }
+}
+
+#endregion
diff --git a/src/DocFlow.CLI/DocFlow.CLI.csproj b/src/DocFlow.CLI/DocFlow.CLI.csproj
index e0bf6bb..18bc86c 100644
--- a/src/DocFlow.CLI/DocFlow.CLI.csproj
+++ b/src/DocFlow.CLI/DocFlow.CLI.csproj
@@ -8,7 +8,9 @@
     <RootNamespace>DocFlow.CLI</RootNamespace>
     <LangVersion>latest</LangVersion>
     <AssemblyName>docflow</AssemblyName>
+    <PackageId>DocFlow.CLI</PackageId>
     <PackAsTool>true</PackAsTool>
+    <IsPackable>true</IsPackable>
     <ToolCommandName>docflow</ToolCommandName>
     <PackageOutputPath>./nupkg</PackageOutputPath>
     <Description>DocFlow CLI - Intelligent documentation and modeling toolkit</Description>
@@ -25,6 +27,7 @@
     <ProjectReference Include="..\DocFlow.IMS\DocFlow.IMS.csproj" />
     <ProjectReference Include="..\DocFlow.Ontology\DocFlow.Ontology.csproj" />
     <ProjectReference Include="..\DocFlow.AI\DocFlow.AI.csproj" />
+    <ProjectReference Include="..\DocFlow.Integration\DocFlow.Integration.csproj" />
   </ItemGroup>
 
   <ItemGroup>
diff --git a/src/DocFlow.CLI/Program.cs b/src/DocFlow.CLI/Program.cs
new file mode 100644
index 0000000..cf1eabd
--- /dev/null
+++ b/src/DocFlow.CLI/Program.cs
@@ -0,0 +1,900 @@
+using System.CommandLine;
+using System.CommandLine.Builder;
+using System.CommandLine.Parsing;
+using System.Diagnostics;
+using DocFlow.AI.Providers;
+using DocFlow.CodeAnalysis.CSharp;
+using DocFlow.CodeGen.CSharp;
+using DocFlow.Core.Abstractions;
+using DocFlow.Core.CanonicalModel;
+using DocFlow.Diagrams.Mermaid;
+using DocFlow.Vision;
+using Spectre.Console;
+
+namespace DocFlow.CLI;
+
+public class Program
+{
+    private const string Version = "1.0.0-preview";
+
+    public static async Task<int> Main(string[] args)
+    {
+        var rootCommand = BuildRootCommand();
+
+        var parser = new CommandLineBuilder(rootCommand)
+            .UseDefaults()
+            .UseExceptionHandler((ex, context) =>
+            {
+                AnsiConsole.MarkupLine($"[red]Error:[/] {ex.Message}");
+                if (context.ParseResult.GetValueForOption(VerboseOption))
+                {
+                    AnsiConsole.WriteException(ex);
+                }
+                context.ExitCode = 1;
+            })
+            .Build();
+
+        return await parser.InvokeAsync(args);
+    }
+
+    // Global options
+    private static readonly Option<bool> VerboseOption = new(
+        aliases: ["-v", "--verbose"],
+        description: "Show detailed output");
+
+    private static readonly Option<bool> QuietOption = new(
+        aliases: ["-q", "--quiet"],
+        description: "Minimal output, only errors");
+
+    private static RootCommand BuildRootCommand()
+    {
+        var rootCommand = new RootCommand("DocFlow - Intelligent Documentation and Modeling Toolkit");
+
+        rootCommand.AddCommand(BuildDiagramCommand());
+        rootCommand.AddCommand(BuildCodegenCommand());
+        rootCommand.AddCommand(BuildRoundtripCommand());
+        rootCommand.AddCommand(BuildScanCommand());
+
+        // Custom version option with ASCII banner
+        rootCommand.SetHandler(() =>
+        {
+            ShowBanner();
+            AnsiConsole.MarkupLine("\nUse [green]docflow --help[/] to see available commands.");
+        });
+
+        return rootCommand;
+    }
+
+    #region Diagram Command
+
+    private static Command BuildDiagramCommand()
+    {
+        var inputArg = new Argument<FileInfo>(
+            name: "input",
+            description: "C# source file or directory to parse");
+
+        var outputOption = new Option<FileInfo?>(
+            aliases: ["-o", "--output"],
+            description: "Output file path (default: same name with .mmd extension)");
+
+        var recursiveOption = new Option<bool>(
+            aliases: ["-r", "--recursive"],
+            description: "Process all .cs files in directory");
+
+        var noRelationshipsOption = new Option<bool>(
+            name: "--no-relationships",
+            description: "Exclude relationship lines from diagram");
+
+        var command = new Command("diagram", "Generate Mermaid class diagram from C# source")
+        {
+            inputArg,
+            outputOption,
+            recursiveOption,
+            noRelationshipsOption,
+            VerboseOption,
+            QuietOption
+        };
+
+        command.AddAlias("d");
+
+        command.SetHandler(async (context) =>
+        {
+            var input = context.ParseResult.GetValueForArgument(inputArg);
+            var output = context.ParseResult.GetValueForOption(outputOption);
+            var recursive = context.ParseResult.GetValueForOption(recursiveOption);
+            var noRelationships = context.ParseResult.GetValueForOption(noRelationshipsOption);
+            var verbose = context.ParseResult.GetValueForOption(VerboseOption);
+            var quiet = context.ParseResult.GetValueForOption(QuietOption);
+
+            context.ExitCode = await ExecuteDiagramCommand(input, output, recursive, noRelationships, verbose, quiet);
+        });
+
+        return command;
+    }
+
+    private static async Task<int> ExecuteDiagramCommand(
+        FileInfo input, FileInfo? output, bool recursive, bool noRelationships, bool verbose, bool quiet)
+    {
+        if (!quiet) ShowBanner();
+
+        // Validate input
+        if (!input.Exists && !Directory.Exists(input.FullName))
+        {
+            AnsiConsole.MarkupLine($"[red]Error:[/] File or directory not found: [yellow]{input.FullName}[/]");
+            AnsiConsole.MarkupLine("[dim]Tip: Make sure the path exists and you have read permissions.[/]");
+            return 1;
+        }
+
+        var files = new List<string>();
+        if (Directory.Exists(input.FullName))
+        {
+            var searchOption = recursive ? SearchOption.AllDirectories : SearchOption.TopDirectoryOnly;
+            files.AddRange(Directory.GetFiles(input.FullName, "*.cs", searchOption));
+            if (files.Count == 0)
+            {
+                AnsiConsole.MarkupLine($"[yellow]Warning:[/] No .cs files found in [cyan]{input.FullName}[/]");
+                return 1;
+            }
+        }
+        else
+        {
+            files.Add(input.FullName);
+        }
+
+        if (!quiet)
+        {
+            AnsiConsole.MarkupLine($"\n[blue]Parsing[/] {files.Count} C# file(s)...\n");
+        }
+
+        var parser = new CSharpModelParser();
+        var combinedModel = new SemanticModel { Name = Path.GetFileNameWithoutExtension(input.Name) };
+        var stopwatch = Stopwatch.StartNew();
+
+        await AnsiConsole.Status()
+            .StartAsync("Parsing C# source files...", async ctx =>
+            {
+                foreach (var file in files)
+                {
+                    ctx.Status($"Parsing [cyan]{Path.GetFileName(file)}[/]...");
+
+                    var parseResult = await parser.ParseAsync(ParserInput.FromFile(file));
+                    if (!parseResult.Success)
+                    {
+                        AnsiConsole.MarkupLine($"[red]Error parsing {Path.GetFileName(file)}:[/]");
+                        foreach (var error in parseResult.Errors)
+                        {
+                            AnsiConsole.MarkupLine($"  [red]•[/] {error.Code}: {error.Message}");
+                        }
+                        continue;
+                    }
+
+                    // Merge into combined model
+                    foreach (var entity in parseResult.Model.Entities.Values)
+                    {
+                        if (!combinedModel.Entities.ContainsKey(entity.Id))
+                            combinedModel.AddEntity(entity);
+                    }
+                    foreach (var rel in parseResult.Model.Relationships)
+                    {
+                        combinedModel.Relationships.Add(rel);
+                    }
+
+                    if (verbose)
+                    {
+                        AnsiConsole.MarkupLine($"  [green]✓[/] {Path.GetFileName(file)}: {parseResult.Model.Entities.Count} entities");
+                    }
+                }
+            });
+
+        if (combinedModel.Entities.Count == 0)
+        {
+            AnsiConsole.MarkupLine("[red]Error:[/] No entities found in the source file(s).");
+            return 1;
+        }
+
+        // Remove relationships if requested
+        if (noRelationships)
+        {
+            combinedModel.Relationships.Clear();
+        }
+
+        // Generate Mermaid
+        var generator = new MermaidClassDiagramGenerator();
+        var generateResult = await generator.GenerateAsync(combinedModel);
+
+        if (!generateResult.Success)
+        {
+            AnsiConsole.MarkupLine("[red]Error generating diagram:[/]");
+            foreach (var error in generateResult.Errors)
+            {
+                AnsiConsole.MarkupLine($"  [red]•[/] {error.Code}: {error.Message}");
+            }
+            return 1;
+        }
+
+        stopwatch.Stop();
+
+        // Determine output path
+        var outputPath = output?.FullName ?? Path.ChangeExtension(input.FullName, ".mmd");
+        await File.WriteAllTextAsync(outputPath, generateResult.Content!);
+
+        // Display results
+        if (!quiet)
+        {
+            PrintModelSummary(combinedModel, verbose);
+
+            AnsiConsole.WriteLine();
+            var panel = new Panel(generateResult.Content!)
+            {
+                Header = new PanelHeader("[green]Generated Mermaid Diagram[/]"),
+                Border = BoxBorder.Rounded,
+                Padding = new Padding(1, 0)
+            };
+            AnsiConsole.Write(panel);
+
+            AnsiConsole.WriteLine();
+            AnsiConsole.MarkupLine($"[green]Success![/] Diagram saved to [cyan]{outputPath}[/]");
+            AnsiConsole.MarkupLine($"[dim]Completed in {stopwatch.ElapsedMilliseconds}ms[/]");
+        }
+        else
+        {
+            Console.WriteLine(outputPath);
+        }
+
+        return 0;
+    }
+
+    #endregion
+
+    #region Codegen Command
+
+    private static Command BuildCodegenCommand()
+    {
+        var inputArg = new Argument<FileInfo>(
+            name: "input",
+            description: "Mermaid diagram file (.mmd) to parse");
+
+        var outputOption = new Option<FileInfo?>(
+            aliases: ["-o", "--output"],
+            description: "Output file path (default: same name with .cs extension)");
+
+        var namespaceOption = new Option<string?>(
+            aliases: ["-n", "--namespace"],
+            description: "Namespace for generated code (default: derived from filename)");
+
+        var styleOption = new Option<string>(
+            aliases: ["--style"],
+            getDefaultValue: () => "ddd",
+            description: "Code style: 'ddd' (Domain-Driven Design) or 'poco' (Plain Old CLR Objects)");
+
+        var command = new Command("codegen", "Generate C# code from Mermaid diagram")
+        {
+            inputArg,
+            outputOption,
+            namespaceOption,
+            styleOption,
+            VerboseOption,
+            QuietOption
+        };
+
+        command.AddAlias("c");
+
+        command.SetHandler(async (context) =>
+        {
+            var input = context.ParseResult.GetValueForArgument(inputArg);
+            var output = context.ParseResult.GetValueForOption(outputOption);
+            var ns = context.ParseResult.GetValueForOption(namespaceOption);
+            var style = context.ParseResult.GetValueForOption(styleOption);
+            var verbose = context.ParseResult.GetValueForOption(VerboseOption);
+            var quiet = context.ParseResult.GetValueForOption(QuietOption);
+
+            context.ExitCode = await ExecuteCodegenCommand(input, output, ns, style!, verbose, quiet);
+        });
+
+        return command;
+    }
+
+    private static async Task<int> ExecuteCodegenCommand(
+        FileInfo input, FileInfo? output, string? ns, string style, bool verbose, bool quiet)
+    {
+        if (!quiet) ShowBanner();
+
+        if (!input.Exists)
+        {
+            AnsiConsole.MarkupLine($"[red]Error:[/] File not found: [yellow]{input.FullName}[/]");
+            AnsiConsole.MarkupLine("[dim]Tip: Make sure the Mermaid diagram file exists.[/]");
+            return 1;
+        }
+
+        if (!quiet)
+        {
+            AnsiConsole.MarkupLine($"\n[blue]Parsing[/] Mermaid diagram: [cyan]{input.Name}[/]\n");
+        }
+
+        var stopwatch = Stopwatch.StartNew();
+        SemanticModel? model = null;
+
+        await AnsiConsole.Status()
+            .StartAsync("Parsing Mermaid diagram...", async ctx =>
+            {
+                var parser = new MermaidClassDiagramParser();
+                var parseResult = await parser.ParseAsync(ParserInput.FromFile(input.FullName));
+
+                if (!parseResult.Success)
+                {
+                    AnsiConsole.MarkupLine("[red]Error parsing Mermaid diagram:[/]");
+                    foreach (var error in parseResult.Errors)
+                    {
+                        AnsiConsole.MarkupLine($"  [red]•[/] Line {error.Line}: {error.Message}");
+                    }
+                    return;
+                }
+
+                model = parseResult.Model;
+
+                // Set namespace
+                if (!string.IsNullOrEmpty(ns))
+                {
+                    model.Name = ns;
+                }
+
+                ctx.Status("Generating C# code...");
+
+                // Generate C#
+                var generator = new CSharpModelGenerator();
+                var generateResult = await generator.GenerateAsync(model);
+
+                if (!generateResult.Success)
+                {
+                    AnsiConsole.MarkupLine("[red]Error generating code:[/]");
+                    foreach (var error in generateResult.Errors)
+                    {
+                        AnsiConsole.MarkupLine($"  [red]•[/] {error.Code}: {error.Message}");
+                    }
+                    model = null;
+                    return;
+                }
+
+                // Save output
+                var outputPath = output?.FullName ?? Path.ChangeExtension(input.FullName, ".cs");
+                await File.WriteAllTextAsync(outputPath, generateResult.Content!);
+
+                stopwatch.Stop();
+
+                if (!quiet)
+                {
+                    PrintModelSummary(model, verbose);
+
+                    AnsiConsole.WriteLine();
+                    var panel = new Panel(generateResult.Content!)
+                    {
+                        Header = new PanelHeader("[green]Generated C# Code[/]"),
+                        Border = BoxBorder.Rounded,
+                        Padding = new Padding(1, 0)
+                    };
+                    AnsiConsole.Write(panel);
+
+                    AnsiConsole.WriteLine();
+                    AnsiConsole.MarkupLine($"[green]Success![/] Code saved to [cyan]{outputPath}[/]");
+                    AnsiConsole.MarkupLine($"[dim]Completed in {stopwatch.ElapsedMilliseconds}ms[/]");
+                }
+                else
+                {
+                    Console.WriteLine(outputPath);
+                }
+            });
+
+        return model != null ? 0 : 1;
+    }
+
+    #endregion
+
+    #region Roundtrip Command
+
+    private static Command BuildRoundtripCommand()
+    {
+        var inputArg = new Argument<FileInfo>(
+            name: "input",
+            description: "C# source file to round-trip");
+
+        var outputOption = new Option<DirectoryInfo?>(
+            aliases: ["-o", "--output"],
+            description: "Output directory for generated files");
+
+        var compareOption = new Option<bool>(
+            name: "--compare",
+            description: "Show semantic diff between original and generated");
+
+        var command = new Command("roundtrip", "Full round-trip test: C# -> Mermaid -> C#")
+        {
+            inputArg,
+            outputOption,
+            compareOption,
+            VerboseOption,
+            QuietOption
+        };
+
+        command.AddAlias("r");
+
+        command.SetHandler(async (context) =>
+        {
+            var input = context.ParseResult.GetValueForArgument(inputArg);
+            var output = context.ParseResult.GetValueForOption(outputOption);
+            var compare = context.ParseResult.GetValueForOption(compareOption);
+            var verbose = context.ParseResult.GetValueForOption(VerboseOption);
+            var quiet = context.ParseResult.GetValueForOption(QuietOption);
+
+            context.ExitCode = await ExecuteRoundtripCommand(input, output, compare, verbose, quiet);
+        });
+
+        return command;
+    }
+
+    private static async Task<int> ExecuteRoundtripCommand(
+        FileInfo input, DirectoryInfo? outputDir, bool compare, bool verbose, bool quiet)
+    {
+        if (!quiet) ShowBanner();
+
+        if (!input.Exists)
+        {
+            AnsiConsole.MarkupLine($"[red]Error:[/] File not found: [yellow]{input.FullName}[/]");
+            return 1;
+        }
+
+        var baseDir = outputDir?.FullName ?? Path.GetDirectoryName(input.FullName)!;
+        var baseName = Path.GetFileNameWithoutExtension(input.Name);
+
+        if (!quiet)
+        {
+            AnsiConsole.MarkupLine($"\n[blue]Round-trip test:[/] [cyan]{input.Name}[/]\n");
+        }
+
+        var stopwatch = Stopwatch.StartNew();
+        SemanticModel? originalModel = null;
+        SemanticModel? roundTripModel = null;
+        string? mermaidContent = null;
+        string? csharpContent = null;
+
+        await AnsiConsole.Status()
+            .Spinner(Spinner.Known.Dots)
+            .StartAsync("Running round-trip...", async ctx =>
+            {
+                // Step 1: Parse original C#
+                ctx.Status("[bold]Step 1/4:[/] Parsing original C#...");
+                var csharpParser = new CSharpModelParser();
+                var originalResult = await csharpParser.ParseAsync(ParserInput.FromFile(input.FullName));
+
+                if (!originalResult.Success)
+                {
+                    AnsiConsole.MarkupLine("[red]Error parsing C# source:[/]");
+                    foreach (var error in originalResult.Errors)
+                        AnsiConsole.MarkupLine($"  [red]•[/] {error.Message}");
+                    return;
+                }
+
+                originalModel = originalResult.Model;
+
+                // Step 2: Generate Mermaid
+                ctx.Status("[bold]Step 2/4:[/] Generating Mermaid diagram...");
+                var mermaidGenerator = new MermaidClassDiagramGenerator();
+                var mermaidResult = await mermaidGenerator.GenerateAsync(originalModel);
+                mermaidContent = mermaidResult.Content;
+
+                var mermaidPath = Path.Combine(baseDir, $"{baseName}.mmd");
+                await File.WriteAllTextAsync(mermaidPath, mermaidContent!);
+
+                // Step 3: Parse Mermaid back
+                ctx.Status("[bold]Step 3/4:[/] Parsing generated Mermaid...");
+                var mermaidParser = new MermaidClassDiagramParser();
+                var mermaidParseResult = await mermaidParser.ParseAsync(ParserInput.FromContent(mermaidContent!));
+
+                if (!mermaidParseResult.Success)
+                {
+                    AnsiConsole.MarkupLine("[red]Error parsing generated Mermaid:[/]");
+                    foreach (var error in mermaidParseResult.Errors)
+                        AnsiConsole.MarkupLine($"  [red]•[/] {error.Message}");
+                    return;
+                }
+
+                roundTripModel = mermaidParseResult.Model;
+
+                // Step 4: Generate C#
+                ctx.Status("[bold]Step 4/4:[/] Generating C# from round-tripped model...");
+                var csharpGenerator = new CSharpModelGenerator();
+                var csharpResult = await csharpGenerator.GenerateAsync(roundTripModel);
+                csharpContent = csharpResult.Content;
+
+                var csharpPath = Path.Combine(baseDir, $"{baseName}.generated.cs");
+                await File.WriteAllTextAsync(csharpPath, csharpContent!);
+            });
+
+        stopwatch.Stop();
+
+        if (originalModel == null || roundTripModel == null)
+        {
+            return 1;
+        }
+
+        if (!quiet)
+        {
+            // Show comparison table
+            AnsiConsole.WriteLine();
+            var table = new Table()
+                .Border(TableBorder.Rounded)
+                .AddColumn(new TableColumn("[bold]Metric[/]").LeftAligned())
+                .AddColumn(new TableColumn("[bold]Original[/]").Centered())
+                .AddColumn(new TableColumn("[bold]Round-Trip[/]").Centered())
+                .AddColumn(new TableColumn("[bold]Status[/]").Centered());
+
+            var entitiesMatch = originalModel.Entities.Count == roundTripModel.Entities.Count;
+            var relsMatch = originalModel.Relationships.Count == roundTripModel.Relationships.Count;
+
+            table.AddRow(
+                "Entities",
+                originalModel.Entities.Count.ToString(),
+                roundTripModel.Entities.Count.ToString(),
+                entitiesMatch ? "[green]✓ Match[/]" : "[yellow]≠ Differ[/]");
+
+            table.AddRow(
+                "Relationships",
+                originalModel.Relationships.Count.ToString(),
+                roundTripModel.Relationships.Count.ToString(),
+                relsMatch ? "[green]✓ Match[/]" : "[yellow]≠ Differ[/]");
+
+            AnsiConsole.Write(table);
+
+            if (compare || verbose)
+            {
+                // Classification comparison
+                AnsiConsole.WriteLine();
+                AnsiConsole.MarkupLine("[bold]Entity Classifications:[/]");
+
+                var classTable = new Table()
+                    .Border(TableBorder.Simple)
+                    .AddColumn("Classification")
+                    .AddColumn("Original")
+                    .AddColumn("Round-Trip")
+                    .AddColumn("Status");
+
+                var classifications = originalModel.Entities.Values
+                    .Select(e => e.Classification)
+                    .Union(roundTripModel.Entities.Values.Select(e => e.Classification))
+                    .Distinct()
+                    .OrderBy(c => c.ToString());
+
+                foreach (var classification in classifications)
+                {
+                    var origCount = originalModel.Entities.Values.Count(e => e.Classification == classification);
+                    var rtCount = roundTripModel.Entities.Values.Count(e => e.Classification == classification);
+                    var match = origCount == rtCount;
+
+                    classTable.AddRow(
+                        classification.ToString(),
+                        origCount.ToString(),
+                        rtCount.ToString(),
+                        match ? "[green]✓[/]" : "[yellow]≠[/]");
+                }
+
+                AnsiConsole.Write(classTable);
+            }
+
+            // Output files
+            AnsiConsole.WriteLine();
+            AnsiConsole.MarkupLine("[bold]Generated Files:[/]");
+            AnsiConsole.MarkupLine($"  [cyan]1.[/] {Path.Combine(baseDir, $"{baseName}.mmd")}");
+            AnsiConsole.MarkupLine($"  [cyan]2.[/] {Path.Combine(baseDir, $"{baseName}.generated.cs")}");
+
+            if (verbose && csharpContent != null)
+            {
+                AnsiConsole.WriteLine();
+                var panel = new Panel(csharpContent)
+                {
+                    Header = new PanelHeader("[green]Generated C# Code[/]"),
+                    Border = BoxBorder.Rounded,
+                    Padding = new Padding(1, 0)
+                };
+                AnsiConsole.Write(panel);
+            }
+
+            AnsiConsole.WriteLine();
+            AnsiConsole.MarkupLine($"[green]Round-trip complete![/] [dim]({stopwatch.ElapsedMilliseconds}ms)[/]");
+        }
+
+        return 0;
+    }
+
+    #endregion
+
+    #region Scan Command
+
+    private static Command BuildScanCommand()
+    {
+        var inputArg = new Argument<FileInfo>(
+            name: "image",
+            description: "Whiteboard or diagram image to scan (PNG, JPG, WEBP)");
+
+        var outputOption = new Option<FileInfo?>(
+            aliases: ["-o", "--output"],
+            description: "Output file path for extracted Mermaid diagram");
+
+        var contextOption = new Option<string?>(
+            aliases: ["-c", "--context"],
+            description: "Context hint for the diagram (e.g., 'e-commerce domain model')");
+
+        var command = new Command("scan", "Scan whiteboard or diagram image using AI vision")
+        {
+            inputArg,
+            outputOption,
+            contextOption,
+            VerboseOption,
+            QuietOption
+        };
+
+        command.AddAlias("s");
+
+        command.SetHandler(async (context) =>
+        {
+            var input = context.ParseResult.GetValueForArgument(inputArg);
+            var output = context.ParseResult.GetValueForOption(outputOption);
+            var contextHint = context.ParseResult.GetValueForOption(contextOption);
+            var verbose = context.ParseResult.GetValueForOption(VerboseOption);
+            var quiet = context.ParseResult.GetValueForOption(QuietOption);
+
+            context.ExitCode = await ExecuteScanCommand(input, output, contextHint, verbose, quiet);
+        });
+
+        return command;
+    }
+
+    private static async Task<int> ExecuteScanCommand(
+        FileInfo input, FileInfo? output, string? contextHint, bool verbose, bool quiet)
+    {
+        if (!quiet) ShowBanner();
+
+        // Check for API key using the multi-source resolution
+        var apiKey = ClaudeProvider.ResolveApiKey();
+        if (string.IsNullOrEmpty(apiKey))
+        {
+            var userConfigPath = ClaudeProvider.GetUserConfigPath();
+            var projectConfigPath = Path.Combine(Directory.GetCurrentDirectory(), "docflow.json");
+
+            AnsiConsole.WriteLine();
+            var panel = new Panel(
+                "[red]Claude API key not configured![/]\n\n" +
+                "Configure your API key using one of these methods [dim](in priority order)[/]:\n\n" +
+                "[bold]1. Environment variable:[/]\n" +
+                "   [dim]Linux/macOS:[/] export ANTHROPIC_API_KEY='sk-ant-...'\n" +
+                "   [dim]Windows:[/]     set ANTHROPIC_API_KEY=sk-ant-...\n" +
+                "   [dim]PowerShell:[/]  $env:ANTHROPIC_API_KEY='sk-ant-...'\n\n" +
+                $"[bold]2. User config:[/] [cyan]{userConfigPath}[/]\n" +
+                "   [dim]{ \"anthropicApiKey\": \"sk-ant-...\" }[/]\n\n" +
+                $"[bold]3. Project config:[/] [cyan]{projectConfigPath}[/]\n" +
+                "   [dim]{ \"anthropicApiKey\": \"sk-ant-...\" }[/]\n\n" +
+                "[dim]Get your API key at https://console.anthropic.com/[/]")
+            {
+                Header = new PanelHeader("[bold yellow]Configuration Required[/]"),
+                Border = BoxBorder.Double,
+                Padding = new Padding(2, 1)
+            };
+            AnsiConsole.Write(panel);
+            return 1;
+        }
+
+        // Validate input file
+        if (!input.Exists)
+        {
+            AnsiConsole.MarkupLine($"[red]Error:[/] Image file not found: [yellow]{input.FullName}[/]");
+            return 1;
+        }
+
+        var extension = input.Extension.ToLowerInvariant();
+        var supportedFormats = new[] { ".jpg", ".jpeg", ".png", ".gif", ".webp" };
+        if (!supportedFormats.Contains(extension))
+        {
+            AnsiConsole.MarkupLine($"[red]Error:[/] Unsupported image format: [yellow]{extension}[/]");
+            AnsiConsole.MarkupLine($"[dim]Supported formats: {string.Join(", ", supportedFormats)}[/]");
+            return 1;
+        }
+
+        if (!quiet)
+        {
+            AnsiConsole.MarkupLine($"\n[blue]Scanning[/] whiteboard image: [cyan]{input.Name}[/]\n");
+        }
+
+        var stopwatch = Stopwatch.StartNew();
+        WhiteboardScanResult? result = null;
+
+        try
+        {
+            await AnsiConsole.Status()
+                .Spinner(Spinner.Known.Dots)
+                .StartAsync("Analyzing image with AI...", async ctx =>
+                {
+                    // Create the scanner with MermaidParser for full model parsing
+                    var mermaidParser = new MermaidClassDiagramParser();
+                    var scanner = new WhiteboardScanner(new ClaudeProvider(), mermaidParser);
+
+                    ctx.Status("Detecting diagram type...");
+
+                    var scanInput = new WhiteboardInput
+                    {
+                        FilePath = input.FullName,
+                        ContextHint = contextHint
+                    };
+
+                    ctx.Status("Extracting diagram elements...");
+
+                    result = await scanner.ScanAsync(scanInput);
+                });
+        }
+        catch (Exception ex)
+        {
+            AnsiConsole.MarkupLine($"[red]Error:[/] {ex.Message}");
+            if (verbose)
+            {
+                AnsiConsole.WriteException(ex);
+            }
+            return 1;
+        }
+
+        stopwatch.Stop();
+
+        if (result == null || !result.Success)
+        {
+            AnsiConsole.MarkupLine("[red]Error:[/] Failed to scan whiteboard image");
+            if (result?.Errors.Count > 0)
+            {
+                foreach (var error in result.Errors)
+                {
+                    AnsiConsole.MarkupLine($"  [red]•[/] {error.Code}: {error.Message}");
+                }
+            }
+            return 1;
+        }
+
+        // Display results
+        if (!quiet)
+        {
+            // Show detection info
+            AnsiConsole.WriteLine();
+            var detectionTable = new Table()
+                .Border(TableBorder.Rounded)
+                .AddColumn("Property")
+                .AddColumn("Value");
+
+            detectionTable.AddRow("Diagram Type", $"[cyan]{result.DetectedDiagramType}[/]");
+            detectionTable.AddRow("Confidence", $"[green]{result.OverallConfidence:P0}[/]");
+            detectionTable.AddRow("Entities Found", result.Model.Entities.Count.ToString());
+            detectionTable.AddRow("Relationships", result.Model.Relationships.Count.ToString());
+
+            if (result.Statistics != null)
+            {
+                detectionTable.AddRow("Analysis Time", $"{result.Statistics.AnalysisDuration.TotalSeconds:F1}s");
+            }
+
+            AnsiConsole.Write(detectionTable);
+
+            // Show entities preview
+            if (result.Model.Entities.Count > 0 && (verbose || result.Model.Entities.Count <= 10))
+            {
+                AnsiConsole.WriteLine();
+                AnsiConsole.MarkupLine("[bold]Detected Entities:[/]");
+
+                var entityTable = new Table()
+                    .Border(TableBorder.Simple)
+                    .AddColumn("Entity")
+                    .AddColumn("Properties")
+                    .AddColumn("Operations");
+
+                foreach (var entity in result.Model.Entities.Values.OrderBy(e => e.Name))
+                {
+                    entityTable.AddRow(
+                        $"[cyan]{entity.Name}[/]",
+                        entity.Properties.Count.ToString(),
+                        entity.Operations.Count.ToString());
+                }
+
+                AnsiConsole.Write(entityTable);
+            }
+
+            // Show the generated Mermaid
+            if (result.GeneratedOutputs.TryGetValue("Mermaid", out var mermaidResult) &&
+                !string.IsNullOrEmpty(mermaidResult.Content))
+            {
+                AnsiConsole.WriteLine();
+                var panel = new Panel(mermaidResult.Content)
+                {
+                    Header = new PanelHeader("[green]Generated Mermaid Diagram[/]"),
+                    Border = BoxBorder.Rounded,
+                    Padding = new Padding(1, 0)
+                };
+                AnsiConsole.Write(panel);
+
+                // Save the output
+                var outputPath = output?.FullName ?? Path.ChangeExtension(input.FullName, ".mmd");
+                await File.WriteAllTextAsync(outputPath, mermaidResult.Content);
+
+                AnsiConsole.WriteLine();
+                AnsiConsole.MarkupLine($"[green]Success![/] Diagram saved to [cyan]{outputPath}[/]");
+            }
+
+            // Show any warnings
+            if (result.Warnings.Count > 0)
+            {
+                AnsiConsole.WriteLine();
+                foreach (var warning in result.Warnings)
+                {
+                    AnsiConsole.MarkupLine($"[yellow]Warning:[/] {warning.Message}");
+                }
+            }
+
+            AnsiConsole.MarkupLine($"[dim]Completed in {stopwatch.ElapsedMilliseconds}ms[/]");
+        }
+        else
+        {
+            // Quiet mode: just output the path
+            if (result.GeneratedOutputs.TryGetValue("Mermaid", out var mermaidResult) &&
+                !string.IsNullOrEmpty(mermaidResult.Content))
+            {
+                var outputPath = output?.FullName ?? Path.ChangeExtension(input.FullName, ".mmd");
+                await File.WriteAllTextAsync(outputPath, mermaidResult.Content);
+                Console.WriteLine(outputPath);
+            }
+        }
+
+        return 0;
+    }
+
+    #endregion
+
+    #region Helpers
+
+    private static void ShowBanner()
+    {
+        AnsiConsole.Write(new FigletText("DocFlow")
+            .Color(Color.Blue));
+
+        AnsiConsole.MarkupLine($"[dim]v{Version} - Intelligent Documentation and Modeling Toolkit[/]");
+        AnsiConsole.WriteLine();
+    }
+
+    private static void PrintModelSummary(SemanticModel model, bool verbose)
+    {
+        AnsiConsole.MarkupLine($"[green]Parsed:[/] {model.Entities.Count} entities, {model.Relationships.Count} relationships");
+
+        if (verbose)
+        {
+            AnsiConsole.WriteLine();
+            var table = new Table()
+                .Border(TableBorder.Rounded)
+                .AddColumn("Entity")
+                .AddColumn("Classification")
+                .AddColumn("Properties")
+                .AddColumn("Operations");
+
+            foreach (var entity in model.Entities.Values.OrderBy(e => e.Name))
+            {
+                var classification = entity.Classification switch
+                {
+                    EntityClassification.AggregateRoot => "[bold magenta]AggregateRoot[/]",
+                    EntityClassification.Entity => "[cyan]Entity[/]",
+                    EntityClassification.ValueObject => "[green]ValueObject[/]",
+                    EntityClassification.DomainService => "[yellow]Service[/]",
+                    EntityClassification.Interface => "[blue]Interface[/]",
+                    EntityClassification.Enum => "[dim]Enum[/]",
+                    _ => entity.Classification.ToString()
+                };
+
+                table.AddRow(
+                    entity.Name,
+                    classification,
+                    entity.Properties.Count.ToString(),
+                    entity.Operations.Count.ToString());
+            }
+
+            AnsiConsole.Write(table);
+        }
+    }
+
+    #endregion
+}
diff --git a/src/DocFlow.CodeAnalysis/CSharp/CSharpModelParser.cs b/src/DocFlow.CodeAnalysis/CSharp/CSharpModelParser.cs
new file mode 100644
index 0000000..ccc6919
--- /dev/null
+++ b/src/DocFlow.CodeAnalysis/CSharp/CSharpModelParser.cs
@@ -0,0 +1,630 @@
+using System.Diagnostics;
+using DocFlow.Core.Abstractions;
+using DocFlow.Core.CanonicalModel;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp;
+using Microsoft.CodeAnalysis.CSharp.Syntax;
+using RoslynSemanticModel = Microsoft.CodeAnalysis.SemanticModel;
+using CanonicalSemanticModel = DocFlow.Core.CanonicalModel.SemanticModel;
+
+namespace DocFlow.CodeAnalysis.CSharp;
+
+/// <summary>
+/// Parses C# source code into a SemanticModel using Roslyn.
+/// Extracts classes, records, interfaces, enums, properties, methods, and relationships.
+/// </summary>
+public sealed class CSharpModelParser : IModelParser
+{
+    public string SourceFormat => "CSharp";
+    public IReadOnlyList<string> SupportedExtensions => [".cs"];
+
+    public bool CanParse(ParserInput input)
+    {
+        if (input.Content != null) return true;
+        if (input.FilePath != null) return input.FilePath.EndsWith(".cs", StringComparison.OrdinalIgnoreCase);
+        return false;
+    }
+
+    public async Task<ParseResult> ParseAsync(ParserInput input, ParserOptions? options = null, CancellationToken cancellationToken = default)
+    {
+        options ??= new ParserOptions();
+        var stopwatch = Stopwatch.StartNew();
+
+        string sourceCode;
+        if (input.Content != null)
+        {
+            sourceCode = input.Content;
+        }
+        else if (input.FilePath != null)
+        {
+            sourceCode = await File.ReadAllTextAsync(input.FilePath, cancellationToken);
+        }
+        else
+        {
+            return ParseResult.Failed(new ParseError { Code = "NO_INPUT", Message = "No content or file path provided" });
+        }
+
+        var syntaxTree = CSharpSyntaxTree.ParseText(sourceCode, cancellationToken: cancellationToken);
+        var root = await syntaxTree.GetRootAsync(cancellationToken);
+
+        var compilation = CSharpCompilation.Create("TempAssembly")
+            .AddReferences(MetadataReference.CreateFromFile(typeof(object).Assembly.Location))
+            .AddSyntaxTrees(syntaxTree);
+
+        var roslynModel = compilation.GetSemanticModel(syntaxTree);
+
+        var model = new CanonicalSemanticModel
+        {
+            Name = input.FilePath != null ? Path.GetFileNameWithoutExtension(input.FilePath) : "ParsedModel",
+            Provenance = new ModelProvenance
+            {
+                SourceFormat = SourceFormat,
+                SourceFiles = input.FilePath != null ? [input.FilePath] : [],
+                ToolVersion = "1.0.0"
+            }
+        };
+
+        var errors = new List<ParseError>();
+        var warnings = new List<ParseWarning>();
+        var entityMap = new Dictionary<string, SemanticEntity>();
+
+        // First pass: collect all type declarations
+        var typeDeclarations = root.DescendantNodes()
+            .OfType<TypeDeclarationSyntax>()
+            .ToList();
+
+        foreach (var typeDecl in typeDeclarations)
+        {
+            var entity = ParseTypeDeclaration(typeDecl, roslynModel, options, input.FilePath);
+            if (entity != null)
+            {
+                model.AddEntity(entity);
+                var fullName = GetFullTypeName(typeDecl, roslynModel);
+                entityMap[fullName] = entity;
+            }
+        }
+
+        // Parse enums
+        var enumDeclarations = root.DescendantNodes().OfType<EnumDeclarationSyntax>();
+        foreach (var enumDecl in enumDeclarations)
+        {
+            var entity = ParseEnumDeclaration(enumDecl, input.FilePath);
+            if (entity != null)
+            {
+                model.AddEntity(entity);
+                var symbol = roslynModel.GetDeclaredSymbol(enumDecl);
+                if (symbol != null)
+                {
+                    entityMap[symbol.ToDisplayString()] = entity;
+                }
+            }
+        }
+
+        // Second pass: establish relationships
+        foreach (var typeDecl in typeDeclarations)
+        {
+            var fullName = GetFullTypeName(typeDecl, roslynModel);
+            if (!entityMap.TryGetValue(fullName, out var sourceEntity)) continue;
+
+            // Inheritance relationships
+            if (typeDecl.BaseList != null)
+            {
+                foreach (var baseType in typeDecl.BaseList.Types)
+                {
+                    var typeInfo = roslynModel.GetTypeInfo(baseType.Type);
+                    var baseTypeName = typeInfo.Type?.ToDisplayString() ?? baseType.Type.ToString();
+
+                    if (entityMap.TryGetValue(baseTypeName, out var targetEntity))
+                    {
+                        var isInterface = typeInfo.Type?.TypeKind == TypeKind.Interface;
+                        model.AddRelationship(
+                            sourceEntity.Id,
+                            targetEntity.Id,
+                            isInterface ? RelationshipType.Implementation : RelationshipType.Inheritance,
+                            isInterface ? "implements" : "extends"
+                        );
+                    }
+                }
+            }
+
+            // Property-based relationships
+            foreach (var property in sourceEntity.Properties)
+            {
+                var relationship = InferRelationshipFromProperty(property, sourceEntity, entityMap, model);
+                if (relationship != null)
+                {
+                    model.Relationships.Add(relationship);
+                }
+            }
+        }
+
+        stopwatch.Stop();
+
+        return new ParseResult
+        {
+            Model = model,
+            Success = errors.Count == 0,
+            Errors = errors,
+            Warnings = warnings,
+            Statistics = new ParseStatistics
+            {
+                EntitiesParsed = model.Entities.Count,
+                RelationshipsParsed = model.Relationships.Count,
+                ParseDuration = stopwatch.Elapsed
+            }
+        };
+    }
+
+    private SemanticEntity? ParseTypeDeclaration(TypeDeclarationSyntax typeDecl, RoslynSemanticModel roslynModel, ParserOptions options, string? filePath)
+    {
+        var symbol = roslynModel.GetDeclaredSymbol(typeDecl);
+        if (symbol == null) return null;
+
+        var entity = new SemanticEntity
+        {
+            Id = Guid.NewGuid().ToString(),
+            Name = typeDecl.Identifier.Text,
+            Description = GetXmlDocSummary(typeDecl),
+            Classification = InferClassification(typeDecl, symbol),
+            Source = options.IncludeSourceInfo ? new SourceInfo
+            {
+                SourceType = SourceFormat,
+                FilePath = filePath,
+                LineNumber = typeDecl.GetLocation().GetLineSpan().StartLinePosition.Line + 1
+            } : null
+        };
+
+        // Add stereotypes
+        if (typeDecl is InterfaceDeclarationSyntax)
+            entity.Stereotypes.Add("interface");
+        if (typeDecl is RecordDeclarationSyntax)
+            entity.Stereotypes.Add("record");
+        if (typeDecl.Modifiers.Any(SyntaxKind.AbstractKeyword))
+            entity.Stereotypes.Add("abstract");
+        if (typeDecl.Modifiers.Any(SyntaxKind.SealedKeyword))
+            entity.Stereotypes.Add("sealed");
+
+        // Parse properties
+        var properties = typeDecl.Members.OfType<PropertyDeclarationSyntax>();
+        foreach (var prop in properties)
+        {
+            var semanticProp = ParseProperty(prop, roslynModel);
+            if (semanticProp != null)
+            {
+                entity.Properties.Add(semanticProp);
+            }
+        }
+
+        // Parse record primary constructor parameters as properties
+        if (typeDecl is RecordDeclarationSyntax recordDecl && recordDecl.ParameterList != null)
+        {
+            foreach (var param in recordDecl.ParameterList.Parameters)
+            {
+                var semanticProp = ParseRecordParameter(param, roslynModel);
+                if (semanticProp != null)
+                {
+                    entity.Properties.Add(semanticProp);
+                }
+            }
+        }
+
+        // Parse methods
+        var methods = typeDecl.Members.OfType<MethodDeclarationSyntax>();
+        foreach (var method in methods)
+        {
+            var semanticOp = ParseMethod(method, roslynModel);
+            if (semanticOp != null)
+            {
+                entity.Operations.Add(semanticOp);
+            }
+        }
+
+        return entity;
+    }
+
+    private SemanticEntity? ParseEnumDeclaration(EnumDeclarationSyntax enumDecl, string? filePath)
+    {
+        var entity = new SemanticEntity
+        {
+            Id = Guid.NewGuid().ToString(),
+            Name = enumDecl.Identifier.Text,
+            Description = GetXmlDocSummary(enumDecl),
+            Classification = EntityClassification.Enum,
+            Source = new SourceInfo
+            {
+                SourceType = SourceFormat,
+                FilePath = filePath,
+                LineNumber = enumDecl.GetLocation().GetLineSpan().StartLinePosition.Line + 1
+            }
+        };
+
+        entity.Stereotypes.Add("enumeration");
+
+        // Add enum members as properties (convention for representing enum values)
+        foreach (var member in enumDecl.Members)
+        {
+            entity.Properties.Add(new SemanticProperty
+            {
+                Name = member.Identifier.Text,
+                Type = new SemanticType { Name = enumDecl.Identifier.Text },
+                Visibility = Visibility.Public,
+                Semantics = PropertySemantics.State
+            });
+        }
+
+        return entity;
+    }
+
+    private SemanticProperty? ParseProperty(PropertyDeclarationSyntax prop, RoslynSemanticModel roslynModel)
+    {
+        var typeInfo = roslynModel.GetTypeInfo(prop.Type);
+        var typeName = typeInfo.Type?.ToDisplayString() ?? prop.Type.ToString();
+
+        var semanticType = ParseType(typeName, typeInfo.Type);
+        var visibility = GetVisibility(prop.Modifiers);
+
+        var semanticProp = new SemanticProperty
+        {
+            Name = prop.Identifier.Text,
+            Type = semanticType,
+            Description = GetXmlDocSummary(prop),
+            Visibility = visibility,
+            IsRequired = HasRequiredAttribute(prop) || prop.Modifiers.Any(SyntaxKind.RequiredKeyword),
+            IsReadOnly = IsReadOnlyProperty(prop),
+            Semantics = InferPropertySemantics(prop.Identifier.Text, semanticType)
+        };
+
+        // Parse attributes
+        foreach (var attrList in prop.AttributeLists)
+        {
+            foreach (var attr in attrList.Attributes)
+            {
+                semanticProp.Attributes.Add(new SemanticAttribute
+                {
+                    Name = attr.Name.ToString()
+                });
+            }
+        }
+
+        return semanticProp;
+    }
+
+    private SemanticProperty? ParseRecordParameter(ParameterSyntax param, RoslynSemanticModel roslynModel)
+    {
+        if (param.Type == null) return null;
+
+        var typeInfo = roslynModel.GetTypeInfo(param.Type);
+        var typeName = typeInfo.Type?.ToDisplayString() ?? param.Type.ToString();
+        var semanticType = ParseType(typeName, typeInfo.Type);
+
+        return new SemanticProperty
+        {
+            Name = param.Identifier.Text,
+            Type = semanticType,
+            Visibility = Visibility.Public,
+            IsRequired = true, // Record parameters are typically required
+            IsReadOnly = true, // Record properties are init-only
+            Semantics = InferPropertySemantics(param.Identifier.Text, semanticType)
+        };
+    }
+
+    private SemanticOperation? ParseMethod(MethodDeclarationSyntax method, RoslynSemanticModel roslynModel)
+    {
+        // Skip property accessors and compiler-generated methods
+        if (method.Modifiers.Any(SyntaxKind.PrivateKeyword) &&
+            (method.Identifier.Text.StartsWith("get_") || method.Identifier.Text.StartsWith("set_")))
+            return null;
+
+        var returnTypeInfo = roslynModel.GetTypeInfo(method.ReturnType);
+        var returnTypeName = returnTypeInfo.Type?.ToDisplayString() ?? method.ReturnType.ToString();
+
+        var operation = new SemanticOperation
+        {
+            Name = method.Identifier.Text,
+            ReturnType = returnTypeName == "void" ? null : ParseType(returnTypeName, returnTypeInfo.Type),
+            Description = GetXmlDocSummary(method),
+            Visibility = GetVisibility(method.Modifiers),
+            IsAbstract = method.Modifiers.Any(SyntaxKind.AbstractKeyword),
+            IsStatic = method.Modifiers.Any(SyntaxKind.StaticKeyword),
+            IsAsync = method.Modifiers.Any(SyntaxKind.AsyncKeyword)
+        };
+
+        foreach (var param in method.ParameterList.Parameters)
+        {
+            if (param.Type == null) continue;
+            var paramTypeInfo = roslynModel.GetTypeInfo(param.Type);
+            var paramTypeName = paramTypeInfo.Type?.ToDisplayString() ?? param.Type.ToString();
+
+            operation.Parameters.Add(new SemanticParameter
+            {
+                Name = param.Identifier.Text,
+                Type = ParseType(paramTypeName, paramTypeInfo.Type),
+                IsOptional = param.Default != null,
+                DefaultValue = param.Default?.Value.ToString()
+            });
+        }
+
+        return operation;
+    }
+
+    private SemanticType ParseType(string typeName, ITypeSymbol? typeSymbol)
+    {
+        var isNullable = typeName.EndsWith("?") ||
+                         (typeSymbol?.NullableAnnotation == NullableAnnotation.Annotated);
+        var baseName = typeName.TrimEnd('?');
+
+        // Check for collection types
+        if (IsCollectionType(baseName, typeSymbol))
+        {
+            var elementType = GetCollectionElementType(baseName, typeSymbol);
+            return new SemanticType
+            {
+                Name = GetCollectionTypeName(baseName),
+                IsCollection = true,
+                IsNullable = isNullable,
+                GenericArguments = elementType != null ? [elementType] : []
+            };
+        }
+
+        // Check for primitive types
+        var isPrimitive = IsPrimitiveType(baseName);
+
+        return new SemanticType
+        {
+            Name = SimplifyTypeName(baseName),
+            IsPrimitive = isPrimitive,
+            IsNullable = isNullable
+        };
+    }
+
+    private bool IsCollectionType(string typeName, ITypeSymbol? typeSymbol)
+    {
+        var collectionPatterns = new[] { "ICollection", "IList", "List", "IEnumerable", "IReadOnlyList", "IReadOnlyCollection", "HashSet", "ISet" };
+        return collectionPatterns.Any(p => typeName.Contains(p + "<")) ||
+               (typeSymbol is IArrayTypeSymbol);
+    }
+
+    private string GetCollectionTypeName(string typeName)
+    {
+        if (typeName.Contains("ICollection")) return "ICollection";
+        if (typeName.Contains("IList") || typeName.Contains("List<")) return "List";
+        if (typeName.Contains("IEnumerable")) return "IEnumerable";
+        if (typeName.Contains("HashSet") || typeName.Contains("ISet")) return "Set";
+        if (typeName.EndsWith("[]")) return "Array";
+        return "Collection";
+    }
+
+    private SemanticType? GetCollectionElementType(string typeName, ITypeSymbol? typeSymbol)
+    {
+        // Handle arrays
+        if (typeSymbol is IArrayTypeSymbol arrayType)
+        {
+            return ParseType(arrayType.ElementType.ToDisplayString(), arrayType.ElementType);
+        }
+
+        // Handle generic collections
+        if (typeSymbol is INamedTypeSymbol namedType && namedType.TypeArguments.Length > 0)
+        {
+            var elementType = namedType.TypeArguments[0];
+            return ParseType(elementType.ToDisplayString(), elementType);
+        }
+
+        // Try to parse from string
+        var genericStart = typeName.IndexOf('<');
+        var genericEnd = typeName.LastIndexOf('>');
+        if (genericStart > 0 && genericEnd > genericStart)
+        {
+            var elementTypeName = typeName.Substring(genericStart + 1, genericEnd - genericStart - 1);
+            return ParseType(elementTypeName, null);
+        }
+
+        return null;
+    }
+
+    private bool IsPrimitiveType(string typeName)
+    {
+        var primitives = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
+        {
+            "string", "int", "long", "short", "byte", "float", "double", "decimal",
+            "bool", "boolean", "char", "DateTime", "DateTimeOffset", "TimeSpan",
+            "Guid", "int32", "int64", "int16", "uint", "uint32", "uint64",
+            "System.String", "System.Int32", "System.Int64", "System.Boolean",
+            "System.Decimal", "System.Double", "System.Single", "System.Guid",
+            "System.DateTime", "System.DateTimeOffset", "System.TimeSpan"
+        };
+        return primitives.Contains(typeName.Split('.').Last());
+    }
+
+    private string SimplifyTypeName(string typeName)
+    {
+        // Remove namespace prefixes for common types
+        var simplified = typeName
+            .Replace("System.Collections.Generic.", "")
+            .Replace("System.", "");
+
+        // Get just the type name for simple types
+        if (!simplified.Contains('<') && simplified.Contains('.'))
+        {
+            simplified = simplified.Split('.').Last();
+        }
+
+        return simplified;
+    }
+
+    private EntityClassification InferClassification(TypeDeclarationSyntax typeDecl, INamedTypeSymbol symbol)
+    {
+        var name = typeDecl.Identifier.Text;
+
+        // Interface
+        if (typeDecl is InterfaceDeclarationSyntax)
+            return EntityClassification.Interface;
+
+        // Record (likely ValueObject)
+        if (typeDecl is RecordDeclarationSyntax)
+        {
+            // Records with Id might be entities
+            var hasId = typeDecl.Members.OfType<PropertyDeclarationSyntax>()
+                .Any(p => p.Identifier.Text.Equals("Id", StringComparison.OrdinalIgnoreCase));
+            if (hasId) return EntityClassification.Entity;
+            return EntityClassification.ValueObject;
+        }
+
+        // Check for DDD pattern names
+        if (name.EndsWith("Repository")) return EntityClassification.Repository;
+        if (name.EndsWith("Service")) return EntityClassification.DomainService;
+        if (name.EndsWith("Factory")) return EntityClassification.Factory;
+        if (name.EndsWith("Event") || name.EndsWith("Occurred") || name.EndsWith("Created") || name.EndsWith("Updated"))
+            return EntityClassification.DomainEvent;
+        if (name.EndsWith("Command")) return EntityClassification.Command;
+        if (name.EndsWith("Query")) return EntityClassification.Query;
+        if (name.EndsWith("Handler")) return EntityClassification.Handler;
+        if (name.EndsWith("Dto") || name.EndsWith("DTO")) return EntityClassification.DataTransferObject;
+        if (name.EndsWith("ViewModel") || name.EndsWith("VM")) return EntityClassification.ViewModel;
+        if (name.EndsWith("Validator")) return EntityClassification.Validator;
+        if (name.EndsWith("Mapper")) return EntityClassification.Mapper;
+        if (name.EndsWith("Controller")) return EntityClassification.Controller;
+        if (name.EndsWith("Specification") || name.EndsWith("Spec")) return EntityClassification.Specification;
+
+        // Check for Id property (Entity or AggregateRoot)
+        var properties = typeDecl.Members.OfType<PropertyDeclarationSyntax>().ToList();
+        var hasIdProperty = properties.Any(p =>
+            p.Identifier.Text.Equals("Id", StringComparison.OrdinalIgnoreCase) ||
+            p.Identifier.Text.EndsWith("Id", StringComparison.OrdinalIgnoreCase) && p.Identifier.Text.Length <= 5);
+
+        if (hasIdProperty)
+        {
+            // Check if it has collection properties of other entities (likely AggregateRoot)
+            var hasCollectionOfEntities = properties.Any(p =>
+            {
+                var typeStr = p.Type.ToString();
+                return (typeStr.Contains("ICollection<") || typeStr.Contains("List<") || typeStr.Contains("IList<")) &&
+                       !IsPrimitiveType(typeStr);
+            });
+
+            return hasCollectionOfEntities ? EntityClassification.AggregateRoot : EntityClassification.Entity;
+        }
+
+        // Abstract class
+        if (typeDecl.Modifiers.Any(SyntaxKind.AbstractKeyword))
+            return EntityClassification.AbstractClass;
+
+        return EntityClassification.Class;
+    }
+
+    private PropertySemantics InferPropertySemantics(string propertyName, SemanticType type)
+    {
+        var lowerName = propertyName.ToLowerInvariant();
+
+        if (lowerName == "id" || lowerName.EndsWith("id") && propertyName.Length <= 5)
+            return PropertySemantics.Identity;
+
+        if (lowerName.Contains("createdat") || lowerName.Contains("updatedat") ||
+            lowerName.Contains("created") || lowerName.Contains("modified") ||
+            lowerName.Contains("timestamp"))
+            return PropertySemantics.Audit;
+
+        if (lowerName == "version" || lowerName == "rowversion" || lowerName == "concurrencytoken")
+            return PropertySemantics.Version;
+
+        if (type.IsCollection)
+            return PropertySemantics.Collection;
+
+        if (!type.IsPrimitive && !type.IsNullable)
+            return PropertySemantics.Navigation;
+
+        return PropertySemantics.State;
+    }
+
+    private SemanticRelationship? InferRelationshipFromProperty(SemanticProperty property, SemanticEntity sourceEntity, Dictionary<string, SemanticEntity> entityMap, CanonicalSemanticModel model)
+    {
+        // Skip primitive types and identity properties
+        if (property.Type.IsPrimitive || property.Semantics == PropertySemantics.Identity)
+            return null;
+
+        SemanticEntity? targetEntity = null;
+        var targetTypeName = property.Type.IsCollection && property.Type.GenericArguments.Count > 0
+            ? property.Type.GenericArguments[0].Name
+            : property.Type.Name;
+
+        // Find target entity
+        foreach (var (name, entity) in entityMap)
+        {
+            if (name.EndsWith("." + targetTypeName) || name == targetTypeName || entity.Name == targetTypeName)
+            {
+                targetEntity = entity;
+                break;
+            }
+        }
+
+        if (targetEntity == null) return null;
+
+        var relationType = property.Type.IsCollection
+            ? RelationshipType.Composition  // Collections typically indicate composition (owned)
+            : RelationshipType.Association; // Single references are associations
+
+        return new SemanticRelationship
+        {
+            Id = Guid.NewGuid().ToString(),
+            SourceEntityId = sourceEntity.Id,
+            TargetEntityId = targetEntity.Id,
+            Type = relationType,
+            Name = property.Name,
+            TargetRole = property.Name,
+            SourceMultiplicity = Multiplicity.One,
+            TargetMultiplicity = property.Type.IsCollection ? Multiplicity.ZeroOrMore : (property.Type.IsNullable ? Multiplicity.ZeroOrOne : Multiplicity.One),
+            IsBidirectional = false
+        };
+    }
+
+    private Visibility GetVisibility(SyntaxTokenList modifiers)
+    {
+        if (modifiers.Any(SyntaxKind.PublicKeyword)) return Visibility.Public;
+        if (modifiers.Any(SyntaxKind.PrivateKeyword) && modifiers.Any(SyntaxKind.ProtectedKeyword)) return Visibility.PrivateProtected;
+        if (modifiers.Any(SyntaxKind.ProtectedKeyword) && modifiers.Any(SyntaxKind.InternalKeyword)) return Visibility.ProtectedInternal;
+        if (modifiers.Any(SyntaxKind.ProtectedKeyword)) return Visibility.Protected;
+        if (modifiers.Any(SyntaxKind.InternalKeyword)) return Visibility.Internal;
+        if (modifiers.Any(SyntaxKind.PrivateKeyword)) return Visibility.Private;
+        return Visibility.Private; // Default in C#
+    }
+
+    private bool HasRequiredAttribute(PropertyDeclarationSyntax prop)
+    {
+        return prop.AttributeLists
+            .SelectMany(al => al.Attributes)
+            .Any(a => a.Name.ToString().Contains("Required"));
+    }
+
+    private bool IsReadOnlyProperty(PropertyDeclarationSyntax prop)
+    {
+        if (prop.AccessorList == null) return true; // Expression-bodied property
+
+        var hasSetter = prop.AccessorList.Accessors
+            .Any(a => a.Kind() == SyntaxKind.SetAccessorDeclaration);
+        var hasInitOnly = prop.AccessorList.Accessors
+            .Any(a => a.Kind() == SyntaxKind.InitAccessorDeclaration);
+
+        return !hasSetter || hasInitOnly;
+    }
+
+    private string? GetXmlDocSummary(SyntaxNode node)
+    {
+        var trivia = node.GetLeadingTrivia()
+            .Select(t => t.GetStructure())
+            .OfType<DocumentationCommentTriviaSyntax>()
+            .FirstOrDefault();
+
+        if (trivia == null) return null;
+
+        var summaryElement = trivia.ChildNodes()
+            .OfType<XmlElementSyntax>()
+            .FirstOrDefault(e => e.StartTag.Name.ToString() == "summary");
+
+        return summaryElement?.Content.ToString().Trim();
+    }
+
+    private string GetFullTypeName(TypeDeclarationSyntax typeDecl, RoslynSemanticModel roslynModel)
+    {
+        var symbol = roslynModel.GetDeclaredSymbol(typeDecl);
+        return symbol?.ToDisplayString() ?? typeDecl.Identifier.Text;
+    }
+}
diff --git a/src/DocFlow.CodeGen/CSharp/CSharpModelGenerator.cs b/src/DocFlow.CodeGen/CSharp/CSharpModelGenerator.cs
new file mode 100644
index 0000000..4341b41
--- /dev/null
+++ b/src/DocFlow.CodeGen/CSharp/CSharpModelGenerator.cs
@@ -0,0 +1,463 @@
+using System.Text;
+using DocFlow.Core.Abstractions;
+using DocFlow.Core.CanonicalModel;
+
+namespace DocFlow.CodeGen.CSharp;
+
+/// <summary>
+/// Generates C# code from a SemanticModel.
+/// Uses modern C# 12 syntax with file-scoped namespaces, records for value objects, etc.
+/// </summary>
+public sealed class CSharpModelGenerator : IModelGenerator
+{
+    public string TargetFormat => "CSharp";
+    public string DefaultExtension => ".cs";
+
+    public Task<GenerateResult> GenerateAsync(SemanticModel model, GeneratorOptions? options = null, CancellationToken cancellationToken = default)
+    {
+        options ??= new GeneratorOptions();
+
+        var sb = new StringBuilder();
+        var warnings = new List<GenerateWarning>();
+
+        // Determine namespace
+        var namespaceName = GetNamespace(model, options);
+
+        // File-scoped namespace
+        sb.AppendLine($"namespace {namespaceName};");
+        sb.AppendLine();
+
+        // Build relationship lookup for generating navigation properties
+        var compositionsBySource = model.Relationships
+            .Where(r => r.Type == RelationshipType.Composition)
+            .GroupBy(r => r.SourceEntityId)
+            .ToDictionary(g => g.Key, g => g.ToList());
+
+        var associationsBySource = model.Relationships
+            .Where(r => r.Type == RelationshipType.Association)
+            .GroupBy(r => r.SourceEntityId)
+            .ToDictionary(g => g.Key, g => g.ToList());
+
+        var inheritanceBySource = model.Relationships
+            .Where(r => r.Type == RelationshipType.Inheritance)
+            .ToDictionary(r => r.SourceEntityId, r => r);
+
+        var implementationsBySource = model.Relationships
+            .Where(r => r.Type == RelationshipType.Implementation)
+            .GroupBy(r => r.SourceEntityId)
+            .ToDictionary(g => g.Key, g => g.ToList());
+
+        // Generate each entity
+        var entityIds = options.EntityFilter?.ToHashSet() ?? model.Entities.Keys.ToHashSet();
+        var entities = model.Entities.Values
+            .Where(e => entityIds.Contains(e.Id))
+            .OrderBy(e => GetEntityOrder(e.Classification))
+            .ThenBy(e => e.Name);
+
+        foreach (var entity in entities)
+        {
+            GenerateEntity(sb, entity, model, inheritanceBySource, implementationsBySource, options);
+            sb.AppendLine();
+        }
+
+        var content = sb.ToString().TrimEnd() + Environment.NewLine;
+
+        // Write to file if output path specified
+        if (options.OutputPath != null)
+        {
+            File.WriteAllText(options.OutputPath, content);
+        }
+
+        return Task.FromResult(new GenerateResult
+        {
+            Content = content,
+            Success = true,
+            Warnings = warnings
+        });
+    }
+
+    private void GenerateEntity(
+        StringBuilder sb,
+        SemanticEntity entity,
+        SemanticModel model,
+        Dictionary<string, SemanticRelationship> inheritanceBySource,
+        Dictionary<string, List<SemanticRelationship>> implementationsBySource,
+        GeneratorOptions options)
+    {
+        // XML documentation
+        if (options.IncludeComments && !string.IsNullOrEmpty(entity.Description))
+        {
+            sb.AppendLine("/// <summary>");
+            foreach (var line in entity.Description.Split('\n'))
+            {
+                sb.AppendLine($"/// {line.Trim()}");
+            }
+            sb.AppendLine("/// </summary>");
+        }
+
+        // Determine type keyword and base types
+        var typeKeyword = GetTypeKeyword(entity);
+        var baseTypes = GetBaseTypes(entity, model, inheritanceBySource, implementationsBySource);
+
+        // Handle enums specially
+        if (entity.Classification == EntityClassification.Enum)
+        {
+            GenerateEnum(sb, entity);
+            return;
+        }
+
+        // Handle interfaces specially
+        if (entity.Classification == EntityClassification.Interface)
+        {
+            GenerateInterface(sb, entity, baseTypes, options);
+            return;
+        }
+
+        // Record types (ValueObjects, Events)
+        if (typeKeyword == "record")
+        {
+            GenerateRecord(sb, entity, baseTypes, options);
+            return;
+        }
+
+        // Regular class
+        GenerateClass(sb, entity, baseTypes, options);
+    }
+
+    private void GenerateEnum(StringBuilder sb, SemanticEntity entity)
+    {
+        sb.AppendLine($"public enum {entity.Name}");
+        sb.AppendLine("{");
+
+        var members = entity.Properties.Select(p => p.Name).ToList();
+        for (var i = 0; i < members.Count; i++)
+        {
+            var comma = i < members.Count - 1 ? "," : "";
+            sb.AppendLine($"    {members[i]}{comma}");
+        }
+
+        sb.AppendLine("}");
+    }
+
+    private void GenerateInterface(StringBuilder sb, SemanticEntity entity, string baseTypes, GeneratorOptions options)
+    {
+        var declaration = string.IsNullOrEmpty(baseTypes)
+            ? $"public interface {entity.Name}"
+            : $"public interface {entity.Name} : {baseTypes}";
+
+        sb.AppendLine(declaration);
+        sb.AppendLine("{");
+
+        foreach (var method in entity.Operations)
+        {
+            GenerateInterfaceMethod(sb, method, options);
+        }
+
+        sb.AppendLine("}");
+    }
+
+    private void GenerateRecord(StringBuilder sb, SemanticEntity entity, string baseTypes, GeneratorOptions options)
+    {
+        var properties = entity.Properties.Where(p => p.Semantics != PropertySemantics.Collection).ToList();
+
+        // Build primary constructor parameters
+        var parameters = properties
+            .Select(p => $"{FormatTypeName(p.Type, p.IsRequired)} {p.Name}")
+            .ToList();
+
+        var paramString = string.Join(",\n    ", parameters);
+        var declaration = properties.Count > 0
+            ? $"public record {entity.Name}(\n    {paramString})"
+            : $"public record {entity.Name}";
+
+        if (!string.IsNullOrEmpty(baseTypes))
+        {
+            declaration += $" : {baseTypes}";
+        }
+
+        // Check if we need a body (for static methods, etc.)
+        var staticMethods = entity.Operations.Where(o => o.IsStatic).ToList();
+
+        if (staticMethods.Count == 0)
+        {
+            sb.AppendLine($"{declaration};");
+        }
+        else
+        {
+            sb.AppendLine(declaration);
+            sb.AppendLine("{");
+
+            foreach (var method in staticMethods)
+            {
+                GenerateMethod(sb, method, options);
+            }
+
+            sb.AppendLine("}");
+        }
+    }
+
+    private void GenerateClass(StringBuilder sb, SemanticEntity entity, string baseTypes, GeneratorOptions options)
+    {
+        // Class modifiers
+        var modifiers = "public";
+        if (entity.Stereotypes.Contains("abstract") || entity.Classification == EntityClassification.AbstractClass)
+            modifiers += " abstract";
+        if (entity.Stereotypes.Contains("sealed"))
+            modifiers += " sealed";
+
+        var declaration = string.IsNullOrEmpty(baseTypes)
+            ? $"{modifiers} class {entity.Name}"
+            : $"{modifiers} class {entity.Name} : {baseTypes}";
+
+        sb.AppendLine(declaration);
+        sb.AppendLine("{");
+
+        // Properties
+        foreach (var property in entity.Properties)
+        {
+            GenerateProperty(sb, property, options);
+        }
+
+        // Methods
+        if (entity.Operations.Count > 0 && entity.Properties.Count > 0)
+        {
+            sb.AppendLine();
+        }
+
+        foreach (var method in entity.Operations)
+        {
+            GenerateMethod(sb, method, options);
+        }
+
+        sb.AppendLine("}");
+    }
+
+    private void GenerateProperty(StringBuilder sb, SemanticProperty property, GeneratorOptions options)
+    {
+        // XML doc comment
+        if (options.IncludeComments && !string.IsNullOrEmpty(property.Description))
+        {
+            sb.AppendLine($"    /// <summary>{property.Description}</summary>");
+        }
+
+        // Attributes
+        if (property.IsRequired && !property.Type.IsNullable)
+        {
+            // Use required keyword instead of attribute for C# 11+
+        }
+
+        foreach (var attr in property.Attributes)
+        {
+            sb.AppendLine($"    [{attr.Name}]");
+        }
+
+        var visibility = GetVisibilityKeyword(property.Visibility);
+        var typeName = FormatTypeName(property.Type, property.IsRequired);
+        var requiredKeyword = property.IsRequired && !property.Type.IsNullable && !property.Type.IsPrimitive ? "required " : "";
+        var accessor = GetPropertyAccessor(property);
+
+        sb.AppendLine($"    {visibility} {requiredKeyword}{typeName} {property.Name} {accessor}");
+    }
+
+    private void GenerateMethod(StringBuilder sb, SemanticOperation method, GeneratorOptions options)
+    {
+        if (options.IncludeComments && !string.IsNullOrEmpty(method.Description))
+        {
+            sb.AppendLine($"    /// <summary>{method.Description}</summary>");
+        }
+
+        var visibility = GetVisibilityKeyword(method.Visibility);
+        var modifiers = new List<string> { visibility };
+
+        if (method.IsStatic) modifiers.Add("static");
+        if (method.IsAbstract) modifiers.Add("abstract");
+        if (method.IsAsync) modifiers.Add("async");
+
+        var returnType = method.ReturnType != null ? FormatTypeName(method.ReturnType, false) : "void";
+        var parameters = string.Join(", ", method.Parameters.Select(p =>
+            $"{FormatTypeName(p.Type, !p.IsOptional)} {p.Name}" + (p.DefaultValue != null ? $" = {p.DefaultValue}" : "")));
+
+        var modifierStr = string.Join(" ", modifiers);
+        var signature = $"    {modifierStr} {returnType} {method.Name}({parameters})";
+
+        if (method.IsAbstract)
+        {
+            sb.AppendLine($"{signature};");
+        }
+        else
+        {
+            sb.AppendLine(signature);
+            sb.AppendLine("    {");
+            if (method.ReturnType != null)
+            {
+                sb.AppendLine($"        throw new NotImplementedException();");
+            }
+            sb.AppendLine("    }");
+        }
+    }
+
+    private void GenerateInterfaceMethod(StringBuilder sb, SemanticOperation method, GeneratorOptions options)
+    {
+        if (options.IncludeComments && !string.IsNullOrEmpty(method.Description))
+        {
+            sb.AppendLine($"    /// <summary>{method.Description}</summary>");
+        }
+
+        var returnType = method.ReturnType != null ? FormatTypeName(method.ReturnType, false) : "void";
+        var parameters = string.Join(", ", method.Parameters.Select(p =>
+            $"{FormatTypeName(p.Type, !p.IsOptional)} {p.Name}" + (p.DefaultValue != null ? $" = {p.DefaultValue}" : "")));
+
+        sb.AppendLine($"    {returnType} {method.Name}({parameters});");
+    }
+
+    private string GetTypeKeyword(SemanticEntity entity)
+    {
+        return entity.Classification switch
+        {
+            EntityClassification.ValueObject => "record",
+            EntityClassification.DomainEvent => "record",
+            EntityClassification.DataTransferObject => "record",
+            EntityClassification.Interface => "interface",
+            EntityClassification.Enum => "enum",
+            _ when entity.Stereotypes.Contains("record") => "record",
+            _ => "class"
+        };
+    }
+
+    private string GetBaseTypes(
+        SemanticEntity entity,
+        SemanticModel model,
+        Dictionary<string, SemanticRelationship> inheritanceBySource,
+        Dictionary<string, List<SemanticRelationship>> implementationsBySource)
+    {
+        var baseTypes = new List<string>();
+
+        // Inheritance (single base class)
+        if (inheritanceBySource.TryGetValue(entity.Id, out var inheritance))
+        {
+            var baseEntity = model.GetEntity(inheritance.TargetEntityId);
+            if (baseEntity != null)
+            {
+                baseTypes.Add(baseEntity.Name);
+            }
+        }
+
+        // Implementations (multiple interfaces)
+        if (implementationsBySource.TryGetValue(entity.Id, out var implementations))
+        {
+            foreach (var impl in implementations)
+            {
+                var interfaceEntity = model.GetEntity(impl.TargetEntityId);
+                if (interfaceEntity != null)
+                {
+                    baseTypes.Add(interfaceEntity.Name);
+                }
+            }
+        }
+
+        return string.Join(", ", baseTypes);
+    }
+
+    private string FormatTypeName(SemanticType type, bool isRequired)
+    {
+        var name = type.Name;
+
+        // Handle generic types
+        if (type.IsCollection && type.GenericArguments.Count > 0)
+        {
+            var elementType = FormatTypeName(type.GenericArguments[0], false);
+            name = type.Name switch
+            {
+                "ICollection" => $"ICollection<{elementType}>",
+                "List" => $"List<{elementType}>",
+                "IList" => $"IList<{elementType}>",
+                "IEnumerable" => $"IEnumerable<{elementType}>",
+                "Set" or "HashSet" => $"HashSet<{elementType}>",
+                "IReadOnlyList" => $"IReadOnlyList<{elementType}>",
+                _ => $"ICollection<{elementType}>"
+            };
+        }
+
+        // Handle nullable
+        if (type.IsNullable && !name.EndsWith("?"))
+        {
+            name += "?";
+        }
+
+        return name;
+    }
+
+    private string GetPropertyAccessor(SemanticProperty property)
+    {
+        if (property.IsReadOnly)
+        {
+            return property.Semantics == PropertySemantics.Identity
+                ? "{ get; init; }"
+                : "{ get; }";
+        }
+
+        return property.Semantics switch
+        {
+            PropertySemantics.Identity => "{ get; init; }",
+            PropertySemantics.Collection => $"{{ get; init; }} = new List<{GetCollectionElementType(property.Type)}>();",
+            PropertySemantics.Audit => "{ get; init; }",
+            _ => "{ get; set; }"
+        };
+    }
+
+    private string GetCollectionElementType(SemanticType type)
+    {
+        if (type.GenericArguments.Count > 0)
+        {
+            return FormatTypeName(type.GenericArguments[0], false);
+        }
+        return "object";
+    }
+
+    private static string GetVisibilityKeyword(Visibility visibility)
+    {
+        return visibility switch
+        {
+            Visibility.Public => "public",
+            Visibility.Private => "private",
+            Visibility.Protected => "protected",
+            Visibility.Internal => "internal",
+            Visibility.ProtectedInternal => "protected internal",
+            Visibility.PrivateProtected => "private protected",
+            _ => "public"
+        };
+    }
+
+    private static string GetNamespace(SemanticModel model, GeneratorOptions options)
+    {
+        if (options.ExtendedOptions.TryGetValue("Namespace", out var ns) && ns is string nsStr)
+        {
+            return nsStr;
+        }
+
+        // Try to infer from model name or use default
+        if (!string.IsNullOrEmpty(model.Name))
+        {
+            return $"{model.Name}.Domain";
+        }
+
+        return "Generated.Domain";
+    }
+
+    private static int GetEntityOrder(EntityClassification classification)
+    {
+        // Order: Enums first, then interfaces, then value objects, then entities, then services
+        return classification switch
+        {
+            EntityClassification.Enum => 0,
+            EntityClassification.Interface => 1,
+            EntityClassification.ValueObject => 2,
+            EntityClassification.DomainEvent => 3,
+            EntityClassification.Entity => 4,
+            EntityClassification.AggregateRoot => 5,
+            EntityClassification.Repository => 6,
+            EntityClassification.DomainService => 7,
+            _ => 10
+        };
+    }
+}
diff --git a/src/DocFlow.Diagrams/Mermaid/MermaidClassDiagramGenerator.cs b/src/DocFlow.Diagrams/Mermaid/MermaidClassDiagramGenerator.cs
new file mode 100644
index 0000000..1dfb92a
--- /dev/null
+++ b/src/DocFlow.Diagrams/Mermaid/MermaidClassDiagramGenerator.cs
@@ -0,0 +1,275 @@
+using System.Text;
+using DocFlow.Core.Abstractions;
+using DocFlow.Core.CanonicalModel;
+
+namespace DocFlow.Diagrams.Mermaid;
+
+/// <summary>
+/// Generates Mermaid class diagram syntax from a SemanticModel.
+/// Produces valid Mermaid classDiagram that can be rendered by Mermaid.js.
+/// </summary>
+public sealed class MermaidClassDiagramGenerator : IModelGenerator
+{
+    public string TargetFormat => "Mermaid";
+    public string DefaultExtension => ".mmd";
+
+    public Task<GenerateResult> GenerateAsync(SemanticModel model, GeneratorOptions? options = null, CancellationToken cancellationToken = default)
+    {
+        options ??= new GeneratorOptions();
+
+        var sb = new StringBuilder();
+        sb.AppendLine("classDiagram");
+
+        var warnings = new List<GenerateWarning>();
+        var entityIds = options.EntityFilter?.ToHashSet() ?? model.Entities.Keys.ToHashSet();
+
+        // Generate class definitions
+        foreach (var entity in model.Entities.Values.Where(e => entityIds.Contains(e.Id)))
+        {
+            GenerateClassDefinition(sb, entity, options);
+        }
+
+        sb.AppendLine();
+
+        // Generate relationships
+        if (options.IncludeRelationships)
+        {
+            foreach (var relationship in model.Relationships)
+            {
+                if (!entityIds.Contains(relationship.SourceEntityId) ||
+                    !entityIds.Contains(relationship.TargetEntityId))
+                    continue;
+
+                var sourceEntity = model.GetEntity(relationship.SourceEntityId);
+                var targetEntity = model.GetEntity(relationship.TargetEntityId);
+
+                if (sourceEntity == null || targetEntity == null)
+                {
+                    warnings.Add(new GenerateWarning
+                    {
+                        Code = "MISSING_ENTITY",
+                        Message = $"Relationship references missing entity"
+                    });
+                    continue;
+                }
+
+                GenerateRelationship(sb, relationship, sourceEntity, targetEntity);
+            }
+        }
+
+        var content = sb.ToString();
+
+        // Write to file if output path specified
+        if (options.OutputPath != null)
+        {
+            File.WriteAllText(options.OutputPath, content);
+        }
+
+        return Task.FromResult(new GenerateResult
+        {
+            Content = content,
+            Success = true,
+            Warnings = warnings
+        });
+    }
+
+    private void GenerateClassDefinition(StringBuilder sb, SemanticEntity entity, GeneratorOptions options)
+    {
+        var safeName = SanitizeName(entity.Name);
+
+        // Add stereotype annotation
+        var stereotype = GetStereotype(entity);
+        if (stereotype != null)
+        {
+            sb.AppendLine($"    class {safeName} {{");
+            sb.AppendLine($"        <<{stereotype}>>");
+        }
+        else
+        {
+            sb.AppendLine($"    class {safeName} {{");
+        }
+
+        // Add properties (using Mermaid's colon syntax: +name : type)
+        foreach (var property in entity.Properties)
+        {
+            var visibility = GetVisibilitySymbol(property.Visibility);
+            var typeName = FormatTypeName(property.Type);
+
+            sb.AppendLine($"        {visibility}{property.Name} : {typeName}");
+        }
+
+        // Add methods (if any and not too many)
+        var publicMethods = entity.Operations
+            .Where(o => o.Visibility == Visibility.Public)
+            .Take(10) // Limit to keep diagram readable
+            .ToList();
+
+        foreach (var method in publicMethods)
+        {
+            var visibility = GetVisibilitySymbol(method.Visibility);
+            var returnType = method.ReturnType != null ? FormatTypeName(method.ReturnType) : "void";
+            var parameters = string.Join(", ", method.Parameters.Select(p => $"{p.Name}"));
+            // Mermaid syntax: modifiers ($/*) go at the very end after return type
+            var modifiers = method.IsAbstract ? "*" : (method.IsStatic ? "$" : "");
+
+            sb.AppendLine($"        {visibility}{method.Name}({parameters}) {returnType}{modifiers}");
+        }
+
+        sb.AppendLine("    }");
+    }
+
+    private void GenerateRelationship(StringBuilder sb, SemanticRelationship relationship, SemanticEntity source, SemanticEntity target)
+    {
+        var sourceName = SanitizeName(source.Name);
+        var targetName = SanitizeName(target.Name);
+
+        var arrow = GetRelationshipArrow(relationship.Type);
+        var sourceMultiplicity = FormatMultiplicity(relationship.SourceMultiplicity);
+        var targetMultiplicity = FormatMultiplicity(relationship.TargetMultiplicity);
+
+        // Build the relationship line
+        var line = new StringBuilder();
+        line.Append($"    {sourceName} ");
+
+        // Add source multiplicity if not "1"
+        if (sourceMultiplicity != "1")
+        {
+            line.Append($"\"{sourceMultiplicity}\" ");
+        }
+
+        line.Append(arrow);
+
+        // Add target multiplicity if not "1"
+        if (targetMultiplicity != "1")
+        {
+            line.Append($" \"{targetMultiplicity}\"");
+        }
+
+        line.Append($" {targetName}");
+
+        // Add label if present
+        if (!string.IsNullOrEmpty(relationship.Name) &&
+            relationship.Type != RelationshipType.Inheritance &&
+            relationship.Type != RelationshipType.Implementation)
+        {
+            line.Append($" : {relationship.Name}");
+        }
+
+        sb.AppendLine(line.ToString());
+    }
+
+    private string? GetStereotype(SemanticEntity entity)
+    {
+        // Prioritize explicit stereotypes
+        if (entity.Stereotypes.Contains("interface")) return "interface";
+        if (entity.Stereotypes.Contains("abstract")) return "abstract";
+        if (entity.Stereotypes.Contains("enumeration")) return "enumeration";
+
+        // Map classifications to stereotypes
+        return entity.Classification switch
+        {
+            EntityClassification.AggregateRoot => "AggregateRoot",
+            EntityClassification.Entity => "Entity",
+            EntityClassification.ValueObject => "ValueObject",
+            EntityClassification.DomainService => "Service",
+            EntityClassification.DomainEvent => "Event",
+            EntityClassification.Repository => "Repository",
+            EntityClassification.Factory => "Factory",
+            EntityClassification.Specification => "Specification",
+            EntityClassification.Interface => "interface",
+            EntityClassification.AbstractClass => "abstract",
+            EntityClassification.Enum => "enumeration",
+            EntityClassification.DataTransferObject => "DTO",
+            EntityClassification.ViewModel => "ViewModel",
+            EntityClassification.Command => "Command",
+            EntityClassification.Query => "Query",
+            EntityClassification.Handler => "Handler",
+            _ => null
+        };
+    }
+
+    private string GetVisibilitySymbol(Visibility visibility)
+    {
+        return visibility switch
+        {
+            Visibility.Public => "+",
+            Visibility.Private => "-",
+            Visibility.Protected => "#",
+            Visibility.Internal => "~",
+            Visibility.ProtectedInternal => "#",
+            Visibility.PrivateProtected => "-",
+            _ => "+"
+        };
+    }
+
+    private string GetRelationshipArrow(RelationshipType type)
+    {
+        return type switch
+        {
+            RelationshipType.Inheritance => "--|>",
+            RelationshipType.Implementation => "..|>",
+            RelationshipType.Composition => "--*",
+            RelationshipType.Aggregation => "--o",
+            RelationshipType.Association => "-->",
+            RelationshipType.Dependency => "..>",
+            RelationshipType.Realization => "..|>",
+            RelationshipType.ReferenceById => "..>",
+            RelationshipType.PublishesEvent => "..>",
+            RelationshipType.HandlesEvent => "..>",
+            _ => "-->"
+        };
+    }
+
+    private string FormatMultiplicity(Multiplicity multiplicity)
+    {
+        if (multiplicity.LowerBound == 1 && multiplicity.UpperBound == 1)
+            return "1";
+        if (multiplicity.LowerBound == 0 && multiplicity.UpperBound == 1)
+            return "0..1";
+        if (multiplicity.LowerBound == 0 && multiplicity.UpperBound == null)
+            return "*";
+        if (multiplicity.LowerBound == 1 && multiplicity.UpperBound == null)
+            return "1..*";
+        if (multiplicity.LowerBound == multiplicity.UpperBound)
+            return multiplicity.LowerBound?.ToString() ?? "*";
+
+        var lower = multiplicity.LowerBound?.ToString() ?? "0";
+        var upper = multiplicity.UpperBound?.ToString() ?? "*";
+        return $"{lower}..{upper}";
+    }
+
+    private string FormatTypeName(SemanticType type)
+    {
+        if (type.IsCollection && type.GenericArguments.Count > 0)
+        {
+            var elementType = FormatTypeName(type.GenericArguments[0]);
+            return $"{type.Name}~{elementType}~";
+        }
+
+        var name = type.Name;
+        if (type.IsNullable && !name.EndsWith("?"))
+        {
+            name += "?";
+        }
+
+        return name;
+    }
+
+    private string GetPropertyModifiers(SemanticProperty property)
+    {
+        // Note: Mermaid doesn't have native syntax for required/readonly markers
+        // We omit these to ensure valid diagram syntax
+        return "";
+    }
+
+    private string SanitizeName(string name)
+    {
+        // Mermaid doesn't like certain characters in class names
+        return name
+            .Replace("<", "_")
+            .Replace(">", "_")
+            .Replace(",", "_")
+            .Replace(" ", "_")
+            .Replace(".", "_");
+    }
+}
diff --git a/src/DocFlow.Diagrams/Mermaid/MermaidClassDiagramParser.cs b/src/DocFlow.Diagrams/Mermaid/MermaidClassDiagramParser.cs
new file mode 100644
index 0000000..21d2b9c
--- /dev/null
+++ b/src/DocFlow.Diagrams/Mermaid/MermaidClassDiagramParser.cs
@@ -0,0 +1,412 @@
+using System.Diagnostics;
+using System.Text.RegularExpressions;
+using DocFlow.Core.Abstractions;
+using DocFlow.Core.CanonicalModel;
+
+namespace DocFlow.Diagrams.Mermaid;
+
+/// <summary>
+/// Parses Mermaid classDiagram syntax into a SemanticModel.
+/// Supports classes, stereotypes, properties, methods, and relationships.
+/// </summary>
+public sealed partial class MermaidClassDiagramParser : IModelParser
+{
+    public string SourceFormat => "Mermaid";
+    public IReadOnlyList<string> SupportedExtensions => [".mmd", ".mermaid"];
+
+    public bool CanParse(ParserInput input)
+    {
+        if (input.Content != null)
+            return input.Content.TrimStart().StartsWith("classDiagram", StringComparison.OrdinalIgnoreCase);
+        if (input.FilePath != null)
+            return SupportedExtensions.Any(ext => input.FilePath.EndsWith(ext, StringComparison.OrdinalIgnoreCase));
+        return false;
+    }
+
+    public async Task<ParseResult> ParseAsync(ParserInput input, ParserOptions? options = null, CancellationToken cancellationToken = default)
+    {
+        options ??= new ParserOptions();
+        var stopwatch = Stopwatch.StartNew();
+
+        string content;
+        if (input.Content != null)
+        {
+            content = input.Content;
+        }
+        else if (input.FilePath != null)
+        {
+            content = await File.ReadAllTextAsync(input.FilePath, cancellationToken);
+        }
+        else
+        {
+            return ParseResult.Failed(new ParseError { Code = "NO_INPUT", Message = "No content or file path provided" });
+        }
+
+        var model = new SemanticModel
+        {
+            Name = input.FilePath != null ? Path.GetFileNameWithoutExtension(input.FilePath) : "ParsedDiagram",
+            Provenance = new ModelProvenance
+            {
+                SourceFormat = SourceFormat,
+                SourceFiles = input.FilePath != null ? [input.FilePath] : [],
+                ToolVersion = "1.0.0"
+            }
+        };
+
+        var errors = new List<ParseError>();
+        var warnings = new List<ParseWarning>();
+        var entityByName = new Dictionary<string, SemanticEntity>(StringComparer.OrdinalIgnoreCase);
+
+        var lines = content.Split('\n').Select(l => l.Trim()).ToList();
+
+        // First pass: Parse class definitions
+        var currentClass = (SemanticEntity?)null;
+        var inClassBody = false;
+
+        for (var i = 0; i < lines.Count; i++)
+        {
+            var line = lines[i];
+            var lineNum = i + 1;
+
+            // Skip empty lines and comments
+            if (string.IsNullOrWhiteSpace(line) || line.StartsWith("%%"))
+                continue;
+
+            // Skip classDiagram declaration
+            if (line.Equals("classDiagram", StringComparison.OrdinalIgnoreCase))
+                continue;
+
+            // Class definition start: "class ClassName {"
+            var classMatch = ClassDefinitionRegex().Match(line);
+            if (classMatch.Success)
+            {
+                var className = classMatch.Groups["name"].Value;
+                currentClass = new SemanticEntity
+                {
+                    Id = Guid.NewGuid().ToString(),
+                    Name = className,
+                    Classification = EntityClassification.Class,
+                    Source = options.IncludeSourceInfo ? new SourceInfo
+                    {
+                        SourceType = SourceFormat,
+                        FilePath = input.FilePath,
+                        LineNumber = lineNum
+                    } : null
+                };
+                model.AddEntity(currentClass);
+                entityByName[className] = currentClass;
+                inClassBody = line.Contains('{');
+                continue;
+            }
+
+            // End of class body
+            if (line == "}" && inClassBody && currentClass != null)
+            {
+                inClassBody = false;
+                currentClass = null;
+                continue;
+            }
+
+            // Inside class body
+            if (inClassBody && currentClass != null)
+            {
+                // Stereotype: <<SomeStereotype>>
+                var stereotypeMatch = StereotypeRegex().Match(line);
+                if (stereotypeMatch.Success)
+                {
+                    var stereotype = stereotypeMatch.Groups["stereotype"].Value;
+                    currentClass.Stereotypes.Add(stereotype.ToLowerInvariant());
+                    currentClass.Classification = MapStereotypeToClassification(stereotype);
+                    continue;
+                }
+
+                // Method: +methodName(params) ReturnType or +methodName(params) ReturnType$
+                var methodMatch = MethodRegex().Match(line);
+                if (methodMatch.Success)
+                {
+                    var operation = ParseMethod(methodMatch);
+                    if (operation != null)
+                        currentClass.Operations.Add(operation);
+                    continue;
+                }
+
+                // Property: +Name : Type
+                var propertyMatch = PropertyRegex().Match(line);
+                if (propertyMatch.Success)
+                {
+                    var property = ParseProperty(propertyMatch);
+                    if (property != null)
+                        currentClass.Properties.Add(property);
+                    continue;
+                }
+            }
+
+            // Relationship: ClassName1 --> ClassName2 : label
+            var relationshipMatch = RelationshipRegex().Match(line);
+            if (relationshipMatch.Success)
+            {
+                var relationship = ParseRelationship(relationshipMatch, entityByName, model);
+                if (relationship != null)
+                {
+                    model.Relationships.Add(relationship);
+                }
+                else
+                {
+                    warnings.Add(new ParseWarning
+                    {
+                        Code = "UNRESOLVED_RELATIONSHIP",
+                        Message = $"Could not resolve entities in relationship: {line}",
+                        Line = lineNum
+                    });
+                }
+            }
+        }
+
+        stopwatch.Stop();
+
+        return new ParseResult
+        {
+            Model = model,
+            Success = errors.Count == 0,
+            Errors = errors,
+            Warnings = warnings,
+            Statistics = new ParseStatistics
+            {
+                EntitiesParsed = model.Entities.Count,
+                RelationshipsParsed = model.Relationships.Count,
+                ParseDuration = stopwatch.Elapsed
+            }
+        };
+    }
+
+    private SemanticProperty ParseProperty(Match match)
+    {
+        var visibility = ParseVisibility(match.Groups["visibility"].Value);
+        var name = match.Groups["name"].Value;
+        // Type is optional - default to "object" if not specified
+        var typeName = match.Groups["type"].Success && !string.IsNullOrWhiteSpace(match.Groups["type"].Value)
+            ? match.Groups["type"].Value
+            : "object";
+
+        return new SemanticProperty
+        {
+            Name = name,
+            Type = ParseType(typeName),
+            Visibility = visibility,
+            Semantics = InferPropertySemantics(name, typeName)
+        };
+    }
+
+    private SemanticOperation ParseMethod(Match match)
+    {
+        var visibility = ParseVisibility(match.Groups["visibility"].Value);
+        var name = match.Groups["name"].Value;
+        var paramsStr = match.Groups["params"].Value;
+        var returnType = match.Groups["return"].Value;
+        var modifiers = match.Groups["modifiers"].Value;
+
+        var operation = new SemanticOperation
+        {
+            Name = name,
+            ReturnType = string.IsNullOrEmpty(returnType) || returnType == "void" ? null : ParseType(returnType.TrimEnd('$', '*')),
+            Visibility = visibility,
+            IsStatic = modifiers.Contains('$') || returnType.EndsWith('$'),
+            IsAbstract = modifiers.Contains('*') || returnType.EndsWith('*')
+        };
+
+        // Parse parameters
+        if (!string.IsNullOrWhiteSpace(paramsStr))
+        {
+            var paramParts = paramsStr.Split(',', StringSplitOptions.TrimEntries);
+            foreach (var param in paramParts)
+            {
+                if (string.IsNullOrWhiteSpace(param)) continue;
+
+                // Parameters might be just names or "type name"
+                var parts = param.Split(' ', StringSplitOptions.RemoveEmptyEntries);
+                var paramName = parts.Length > 0 ? parts[^1] : param;
+                var paramType = parts.Length > 1 ? parts[0] : "object";
+
+                operation.Parameters.Add(new SemanticParameter
+                {
+                    Name = paramName,
+                    Type = ParseType(paramType)
+                });
+            }
+        }
+
+        return operation;
+    }
+
+    private SemanticRelationship? ParseRelationship(Match match, Dictionary<string, SemanticEntity> entityByName, SemanticModel model)
+    {
+        var sourceName = match.Groups["source"].Value;
+        var sourceMultStr = match.Groups["sourceMult"].Value;
+        var arrow = match.Groups["arrow"].Value;
+        var targetMultStr = match.Groups["targetMult"].Value;
+        var targetName = match.Groups["target"].Value;
+        var label = match.Groups["label"].Value;
+
+        if (!entityByName.TryGetValue(sourceName, out var sourceEntity) ||
+            !entityByName.TryGetValue(targetName, out var targetEntity))
+        {
+            return null;
+        }
+
+        var relType = ParseRelationshipType(arrow);
+        var sourceMult = string.IsNullOrEmpty(sourceMultStr) ? Multiplicity.One : Multiplicity.Parse(sourceMultStr.Trim('"'));
+        var targetMult = string.IsNullOrEmpty(targetMultStr) ? Multiplicity.One : Multiplicity.Parse(targetMultStr.Trim('"'));
+
+        return new SemanticRelationship
+        {
+            Id = Guid.NewGuid().ToString(),
+            SourceEntityId = sourceEntity.Id,
+            TargetEntityId = targetEntity.Id,
+            Type = relType,
+            Name = string.IsNullOrEmpty(label) ? null : label.Trim(),
+            SourceMultiplicity = sourceMult,
+            TargetMultiplicity = targetMult
+        };
+    }
+
+    private SemanticType ParseType(string typeName)
+    {
+        typeName = typeName.Trim();
+
+        // Handle nullable types
+        var isNullable = typeName.EndsWith('?');
+        if (isNullable)
+            typeName = typeName.TrimEnd('?');
+
+        // Handle generic types with Mermaid's tilde notation: ICollection~Item~
+        var genericMatch = GenericTypeRegex().Match(typeName);
+        if (genericMatch.Success)
+        {
+            var baseName = genericMatch.Groups["base"].Value;
+            var argName = genericMatch.Groups["arg"].Value;
+            return new SemanticType
+            {
+                Name = baseName,
+                IsCollection = IsCollectionTypeName(baseName),
+                IsNullable = isNullable,
+                GenericArguments = [ParseType(argName)]
+            };
+        }
+
+        return new SemanticType
+        {
+            Name = typeName,
+            IsPrimitive = IsPrimitiveTypeName(typeName),
+            IsNullable = isNullable
+        };
+    }
+
+    private static Visibility ParseVisibility(string symbol)
+    {
+        return symbol switch
+        {
+            "+" => Visibility.Public,
+            "-" => Visibility.Private,
+            "#" => Visibility.Protected,
+            "~" => Visibility.Internal,
+            _ => Visibility.Public
+        };
+    }
+
+    private static RelationshipType ParseRelationshipType(string arrow)
+    {
+        return arrow switch
+        {
+            "--|>" or "<|--" => RelationshipType.Inheritance,
+            "..|>" or "<|.." => RelationshipType.Implementation,
+            "--*" or "*--" => RelationshipType.Composition,
+            "--o" or "o--" => RelationshipType.Aggregation,
+            "-->" or "<--" => RelationshipType.Association,
+            "..>" or "<.." => RelationshipType.Dependency,
+            _ => RelationshipType.Association
+        };
+    }
+
+    private static EntityClassification MapStereotypeToClassification(string stereotype)
+    {
+        // Normalize: remove spaces and convert to lowercase for matching
+        var normalized = stereotype.ToLowerInvariant().Replace(" ", "");
+        return normalized switch
+        {
+            "aggregateroot" => EntityClassification.AggregateRoot,
+            "entity" => EntityClassification.Entity,
+            "valueobject" => EntityClassification.ValueObject,
+            "service" => EntityClassification.DomainService,
+            "domainservice" => EntityClassification.DomainService,
+            "event" => EntityClassification.DomainEvent,
+            "domainevent" => EntityClassification.DomainEvent,
+            "repository" => EntityClassification.Repository,
+            "factory" => EntityClassification.Factory,
+            "specification" => EntityClassification.Specification,
+            "interface" => EntityClassification.Interface,
+            "abstract" => EntityClassification.AbstractClass,
+            "enumeration" => EntityClassification.Enum,
+            "enum" => EntityClassification.Enum,
+            "dto" => EntityClassification.DataTransferObject,
+            "viewmodel" => EntityClassification.ViewModel,
+            "command" => EntityClassification.Command,
+            "query" => EntityClassification.Query,
+            "handler" => EntityClassification.Handler,
+            _ => EntityClassification.Class
+        };
+    }
+
+    private static PropertySemantics InferPropertySemantics(string name, string typeName)
+    {
+        var lowerName = name.ToLowerInvariant();
+
+        if (lowerName == "id" || (lowerName.EndsWith("id") && name.Length <= 5))
+            return PropertySemantics.Identity;
+
+        if (lowerName.Contains("createdat") || lowerName.Contains("updatedat"))
+            return PropertySemantics.Audit;
+
+        if (IsCollectionTypeName(typeName))
+            return PropertySemantics.Collection;
+
+        return PropertySemantics.State;
+    }
+
+    private static bool IsCollectionTypeName(string typeName)
+    {
+        var collections = new[] { "ICollection", "IList", "List", "IEnumerable", "IReadOnlyList", "HashSet", "ISet", "Array" };
+        return collections.Any(c => typeName.Contains(c, StringComparison.OrdinalIgnoreCase));
+    }
+
+    private static bool IsPrimitiveTypeName(string typeName)
+    {
+        var primitives = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
+        {
+            "string", "int", "long", "short", "byte", "float", "double", "decimal",
+            "bool", "boolean", "char", "DateTime", "DateTimeOffset", "TimeSpan", "Guid"
+        };
+        return primitives.Contains(typeName);
+    }
+
+    // Regex patterns using source generators for performance
+    [GeneratedRegex(@"^\s*class\s+(?<name>\w+)\s*\{?\s*$")]
+    private static partial Regex ClassDefinitionRegex();
+
+    // Stereotype regex: handles both single words and multi-word (e.g., "aggregate root")
+    [GeneratedRegex(@"^\s*<<(?<stereotype>[\w\s]+)>>\s*$")]
+    private static partial Regex StereotypeRegex();
+
+    // Property regex: visibility + name, optionally followed by : Type
+    // Examples: -ID, +name : String, #status : OrderStatus
+    [GeneratedRegex(@"^\s*(?<visibility>[+\-#~])(?<name>\w+)(?:\s*:\s*(?<type>.+?))?\s*$")]
+    private static partial Regex PropertyRegex();
+
+    [GeneratedRegex(@"^\s*(?<visibility>[+\-#~])(?<name>\w+)\s*\((?<params>[^)]*)\)\s*(?<return>\S+)?(?<modifiers>[$*])?.*$")]
+    private static partial Regex MethodRegex();
+
+    [GeneratedRegex(@"^\s*(?<source>\w+)\s*(?<sourceMult>""[^""]*"")?\s*(?<arrow><?\|?[-\.]+[\*o]?(?:\|?>?|>))\s*(?<targetMult>""[^""]*"")?\s*(?<target>\w+)\s*(?::\s*(?<label>.+))?\s*$")]
+    private static partial Regex RelationshipRegex();
+
+    [GeneratedRegex(@"^(?<base>\w+)~(?<arg>[^~]+)~$")]
+    private static partial Regex GenericTypeRegex();
+}
diff --git a/src/DocFlow.Integration/DocFlow.Integration.csproj b/src/DocFlow.Integration/DocFlow.Integration.csproj
new file mode 100644
index 0000000..016b95c
--- /dev/null
+++ b/src/DocFlow.Integration/DocFlow.Integration.csproj
@@ -0,0 +1,26 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <RootNamespace>DocFlow.Integration</RootNamespace>
+    <LangVersion>latest</LangVersion>
+    <Description>Enterprise API integration automation - schema parsing, CDM mapping, code generation</Description>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\DocFlow.Core\DocFlow.Core.csproj" />
+    <ProjectReference Include="..\DocFlow.IMS\DocFlow.IMS.csproj" />
+    <ProjectReference Include="..\DocFlow.CodeGen\DocFlow.CodeGen.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.OpenApi.Readers" Version="1.6.13" />
+    <PackageReference Include="NJsonSchema" Version="11.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Http" Version="8.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Options" Version="8.0.0" />
+  </ItemGroup>
+
+</Project>
diff --git a/src/DocFlow.Integration/Mapping/CdmMapper.cs b/src/DocFlow.Integration/Mapping/CdmMapper.cs
new file mode 100644
index 0000000..a14bd5b
--- /dev/null
+++ b/src/DocFlow.Integration/Mapping/CdmMapper.cs
@@ -0,0 +1,409 @@
+using System.Text.RegularExpressions;
+using DocFlow.Core.CanonicalModel;
+using DocFlow.Integration.Models;
+using DocFlow.Integration.Patterns;
+using DocFlow.IMS;
+using Microsoft.Extensions.Logging;
+
+namespace DocFlow.Integration.Mapping;
+
+/// <summary>
+/// Maps external API schemas to your Canonical Data Model using pattern matching and IMS learning.
+/// </summary>
+public sealed class CdmMapper
+{
+    private readonly IIntelligentMappingService? _ims;
+    private readonly ILogger<CdmMapper>? _logger;
+    
+    public CdmMapper(
+        IIntelligentMappingService? ims = null,
+        ILogger<CdmMapper>? logger = null)
+    {
+        _ims = ims;
+        _logger = logger;
+    }
+    
+    /// <summary>
+    /// Generate mapping suggestions between external schema and CDM
+    /// </summary>
+    public async Task<MappingResult> MapToCdmAsync(
+        SemanticModel externalSchema,
+        SemanticModel cdm,
+        MappingOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        options ??= new MappingOptions();
+        
+        var entityMappings = new List<EntityMapping>();
+        var unmappedEntities = new List<string>();
+        
+        foreach (var externalEntity in externalSchema.Entities.Values)
+        {
+            var mapping = await MapEntityAsync(
+                externalEntity, cdm, options, cancellationToken);
+                
+            if (mapping != null)
+            {
+                entityMappings.Add(mapping);
+            }
+            else
+            {
+                unmappedEntities.Add(externalEntity.Name);
+            }
+        }
+        
+        // Calculate confidence report
+        var confidenceReport = CalculateConfidenceReport(entityMappings);
+        
+        _logger?.LogInformation(
+            "Mapped {MappedCount}/{TotalCount} entities. Overall confidence: {Confidence:P1}",
+            entityMappings.Count,
+            externalSchema.Entities.Count,
+            confidenceReport.OverallConfidence);
+        
+        return new MappingResult
+        {
+            EntityMappings = entityMappings,
+            UnmappedEntities = unmappedEntities,
+            ConfidenceReport = confidenceReport
+        };
+    }
+    
+    private async Task<EntityMapping?> MapEntityAsync(
+        SemanticEntity externalEntity,
+        SemanticModel cdm,
+        MappingOptions options,
+        CancellationToken cancellationToken)
+    {
+        // Try to find matching CDM entity
+        var cdmEntity = FindMatchingCdmEntity(externalEntity, cdm);
+        
+        if (cdmEntity == null && !options.CreateMappingsForUnmatchedEntities)
+        {
+            return null;
+        }
+        
+        var fieldMappings = new List<FieldMapping>();
+        var totalConfidence = 0.0;
+        
+        foreach (var externalProperty in externalEntity.Properties)
+        {
+            var fieldMapping = await MapFieldAsync(
+                externalProperty, 
+                cdmEntity, 
+                options,
+                cancellationToken);
+                
+            if (fieldMapping != null)
+            {
+                fieldMappings.Add(fieldMapping);
+                totalConfidence += fieldMapping.Confidence;
+            }
+            else
+            {
+                // Create unmatched field mapping
+                fieldMappings.Add(new FieldMapping
+                {
+                    SourceField = externalProperty.Name,
+                    TargetField = "???",
+                    Confidence = 0,
+                    IsAutoMapped = false,
+                    Reasoning = "No matching CDM field found"
+                });
+            }
+        }
+        
+        var avgConfidence = fieldMappings.Count > 0 
+            ? totalConfidence / fieldMappings.Count 
+            : 0;
+        
+        return new EntityMapping
+        {
+            ExternalEntityName = externalEntity.Name,
+            CdmEntityName = cdmEntity?.Name ?? externalEntity.Name,
+            FieldMappings = fieldMappings,
+            Confidence = avgConfidence,
+            Status = avgConfidence > 0.9 
+                ? IntegrationStatus.Verified 
+                : avgConfidence > 0.7 
+                    ? IntegrationStatus.NeedsReview 
+                    : IntegrationStatus.InProgress
+        };
+    }
+    
+    private SemanticEntity? FindMatchingCdmEntity(
+        SemanticEntity externalEntity, 
+        SemanticModel cdm)
+    {
+        var externalName = NormalizeName(externalEntity.Name);
+        
+        // Exact match
+        var exact = cdm.Entities.Values
+            .FirstOrDefault(e => NormalizeName(e.Name) == externalName);
+        if (exact != null) return exact;
+        
+        // Try removing common suffixes
+        var withoutSuffix = RemoveCommonSuffixes(externalName);
+        var suffixMatch = cdm.Entities.Values
+            .FirstOrDefault(e => NormalizeName(e.Name) == withoutSuffix);
+        if (suffixMatch != null) return suffixMatch;
+        
+        // Try fuzzy matching based on properties
+        var bestMatch = cdm.Entities.Values
+            .Select(e => new 
+            { 
+                Entity = e, 
+                Score = CalculatePropertyOverlap(externalEntity, e) 
+            })
+            .Where(x => x.Score > 0.5)
+            .OrderByDescending(x => x.Score)
+            .FirstOrDefault();
+            
+        return bestMatch?.Entity;
+    }
+    
+    private async Task<FieldMapping?> MapFieldAsync(
+        SemanticProperty externalProperty,
+        SemanticEntity? cdmEntity,
+        MappingOptions options,
+        CancellationToken cancellationToken)
+    {
+        // First, try IMS suggestions if available
+        if (_ims != null)
+        {
+            var suggestion = await TryGetImsSuggestionAsync(
+                externalProperty, cdmEntity, cancellationToken);
+            if (suggestion != null) return suggestion;
+        }
+        
+        // Fall back to pattern matching
+        var patternMatch = TryPatternMatch(externalProperty);
+        if (patternMatch != null && cdmEntity != null)
+        {
+            // Verify the pattern match target exists in CDM entity
+            var targetProperty = cdmEntity.Properties
+                .FirstOrDefault(p => p.Name.Equals(
+                    patternMatch.Value.targetField, 
+                    StringComparison.OrdinalIgnoreCase));
+                    
+            if (targetProperty != null)
+            {
+                return new FieldMapping
+                {
+                    SourceField = externalProperty.Name,
+                    TargetField = targetProperty.Name,
+                    Confidence = 0.85, // High confidence for pattern matches
+                    IsAutoMapped = true,
+                    Reasoning = $"Pattern match: {patternMatch.Value.pattern}"
+                };
+            }
+        }
+        
+        // Try name-based matching
+        if (cdmEntity != null)
+        {
+            var nameMatch = TryNameMatch(externalProperty, cdmEntity);
+            if (nameMatch != null) return nameMatch;
+        }
+        
+        return null;
+    }
+    
+    private async Task<FieldMapping?> TryGetImsSuggestionAsync(
+        SemanticProperty externalProperty,
+        SemanticEntity? cdmEntity,
+        CancellationToken cancellationToken)
+    {
+        if (_ims == null || cdmEntity == null) return null;
+        
+        try
+        {
+            // Build a mini model for the IMS query
+            var sourceModel = new SemanticModel();
+            var tempEntity = new SemanticEntity
+            {
+                Id = Guid.NewGuid().ToString(),
+                Name = "Source"
+            };
+            tempEntity.Properties.Add(externalProperty);
+            sourceModel.AddEntity(tempEntity);
+            
+            var suggestions = await _ims.SuggestMappingsAsync(
+                sourceModel, "CDM", cancellationToken: cancellationToken);
+                
+            var highConfidence = suggestions.HighConfidence.FirstOrDefault();
+            if (highConfidence != null)
+            {
+                return new FieldMapping
+                {
+                    SourceField = externalProperty.Name,
+                    TargetField = highConfidence.Transformation.Description,
+                    Confidence = highConfidence.Confidence,
+                    IsAutoMapped = true,
+                    Reasoning = highConfidence.Reasoning
+                };
+            }
+        }
+        catch (Exception ex)
+        {
+            _logger?.LogWarning(ex, "IMS suggestion failed for {Property}", externalProperty.Name);
+        }
+        
+        return null;
+    }
+    
+    private static (string pattern, string targetField)? TryPatternMatch(SemanticProperty property)
+    {
+        var propName = property.Name.ToLowerInvariant();
+        
+        foreach (var pattern in ApiMappingPatterns.GetAllPatterns())
+        {
+            if (Regex.IsMatch(propName, pattern.Condition, RegexOptions.IgnoreCase))
+            {
+                if (pattern.Parameters.TryGetValue("targetField", out var target))
+                {
+                    return (pattern.Condition, target.ToString()!);
+                }
+            }
+        }
+        
+        return null;
+    }
+    
+    private static FieldMapping? TryNameMatch(
+        SemanticProperty externalProperty, 
+        SemanticEntity cdmEntity)
+    {
+        var normalizedExternal = NormalizeName(externalProperty.Name);
+        
+        foreach (var cdmProperty in cdmEntity.Properties)
+        {
+            var normalizedCdm = NormalizeName(cdmProperty.Name);
+            
+            // Exact match after normalization
+            if (normalizedExternal == normalizedCdm)
+            {
+                return new FieldMapping
+                {
+                    SourceField = externalProperty.Name,
+                    TargetField = cdmProperty.Name,
+                    Confidence = 0.95,
+                    IsAutoMapped = true,
+                    Reasoning = "Exact name match"
+                };
+            }
+            
+            // Contains match
+            if (normalizedCdm.Contains(normalizedExternal) || 
+                normalizedExternal.Contains(normalizedCdm))
+            {
+                return new FieldMapping
+                {
+                    SourceField = externalProperty.Name,
+                    TargetField = cdmProperty.Name,
+                    Confidence = 0.75,
+                    IsAutoMapped = true,
+                    Reasoning = "Partial name match"
+                };
+            }
+        }
+        
+        return null;
+    }
+    
+    private static string NormalizeName(string name)
+    {
+        // Remove common prefixes/suffixes, convert to lowercase, remove separators
+        return Regex.Replace(name, @"[_\-\s]", "").ToLowerInvariant();
+    }
+    
+    private static string RemoveCommonSuffixes(string name)
+    {
+        var suffixes = new[] { "dto", "model", "entity", "request", "response", "vm", "viewmodel" };
+        
+        foreach (var suffix in suffixes)
+        {
+            if (name.EndsWith(suffix, StringComparison.OrdinalIgnoreCase))
+            {
+                return name[..^suffix.Length];
+            }
+        }
+        
+        return name;
+    }
+    
+    private static double CalculatePropertyOverlap(
+        SemanticEntity external, 
+        SemanticEntity cdm)
+    {
+        var externalProps = external.Properties
+            .Select(p => NormalizeName(p.Name))
+            .ToHashSet();
+            
+        var cdmProps = cdm.Properties
+            .Select(p => NormalizeName(p.Name))
+            .ToHashSet();
+            
+        var intersection = externalProps.Intersect(cdmProps).Count();
+        var union = externalProps.Union(cdmProps).Count();
+        
+        return union > 0 ? (double)intersection / union : 0;
+    }
+    
+    private static MappingConfidenceReport CalculateConfidenceReport(
+        List<EntityMapping> mappings)
+    {
+        var allFieldMappings = mappings.SelectMany(m => m.FieldMappings).ToList();
+        
+        return new MappingConfidenceReport
+        {
+            TotalMappings = allFieldMappings.Count,
+            HighConfidence = allFieldMappings.Count(m => m.Confidence > 0.9),
+            MediumConfidence = allFieldMappings.Count(m => m.Confidence > 0.7 && m.Confidence <= 0.9),
+            LowConfidence = allFieldMappings.Count(m => m.Confidence > 0 && m.Confidence <= 0.7),
+            Unmapped = allFieldMappings.Count(m => m.Confidence == 0),
+            OverallConfidence = allFieldMappings.Count > 0 
+                ? allFieldMappings.Average(m => m.Confidence) 
+                : 0,
+            Issues = allFieldMappings
+                .Where(m => m.Confidence < 0.7)
+                .Select(m => new MappingIssue
+                {
+                    Field = m.SourceField,
+                    Type = m.Confidence == 0 ? MappingIssueType.NoMatch : MappingIssueType.AmbiguousMatch,
+                    Description = m.Reasoning ?? "Low confidence mapping"
+                })
+                .ToList()
+        };
+    }
+}
+
+public sealed class MappingOptions
+{
+    /// <summary>
+    /// Create mappings even for entities with no CDM match
+    /// </summary>
+    public bool CreateMappingsForUnmatchedEntities { get; init; } = true;
+    
+    /// <summary>
+    /// Minimum confidence threshold for auto-approving mappings
+    /// </summary>
+    public double AutoApproveThreshold { get; init; } = 0.9;
+    
+    /// <summary>
+    /// Use IMS for pattern suggestions
+    /// </summary>
+    public bool UseIms { get; init; } = true;
+    
+    /// <summary>
+    /// Domain-specific pattern set to use
+    /// </summary>
+    public string? DomainPatternSet { get; init; }
+}
+
+public sealed class MappingResult
+{
+    public List<EntityMapping> EntityMappings { get; init; } = [];
+    public List<string> UnmappedEntities { get; init; } = [];
+    public MappingConfidenceReport ConfidenceReport { get; init; } = new();
+}
diff --git a/src/DocFlow.Integration/Models/ApiEndpoint.cs b/src/DocFlow.Integration/Models/ApiEndpoint.cs
new file mode 100644
index 0000000..4b253f9
--- /dev/null
+++ b/src/DocFlow.Integration/Models/ApiEndpoint.cs
@@ -0,0 +1,138 @@
+using DocFlow.Core.CanonicalModel;
+
+namespace DocFlow.Integration.Models;
+
+/// <summary>
+/// Represents an API endpoint in the semantic model
+/// </summary>
+public sealed class ApiEndpoint
+{
+    public required string Id { get; init; }
+    public required string Path { get; init; }
+    public required HttpMethod Method { get; init; }
+    public string? Summary { get; init; }
+    public string? Description { get; init; }
+    
+    /// <summary>
+    /// Request body entity (if any)
+    /// </summary>
+    public string? RequestEntityId { get; set; }
+
+    /// <summary>
+    /// Response body entity
+    /// </summary>
+    public string? ResponseEntityId { get; set; }
+    
+    /// <summary>
+    /// Path parameters (e.g., /reservations/{id})
+    /// </summary>
+    public List<ApiParameter> PathParameters { get; init; } = [];
+    
+    /// <summary>
+    /// Query parameters
+    /// </summary>
+    public List<ApiParameter> QueryParameters { get; init; } = [];
+    
+    /// <summary>
+    /// Required headers
+    /// </summary>
+    public List<ApiParameter> Headers { get; init; } = [];
+    
+    /// <summary>
+    /// Expected response codes and their meanings
+    /// </summary>
+    public Dictionary<int, string> ResponseCodes { get; init; } = [];
+    
+    /// <summary>
+    /// Rate limiting info if known
+    /// </summary>
+    public RateLimitInfo? RateLimit { get; init; }
+}
+
+public sealed class ApiParameter
+{
+    public required string Name { get; init; }
+    public required SemanticType Type { get; init; }
+    public bool IsRequired { get; init; }
+    public string? Description { get; init; }
+    public string? DefaultValue { get; init; }
+    public string? Example { get; init; }
+}
+
+public enum HttpMethod
+{
+    Get,
+    Post,
+    Put,
+    Patch,
+    Delete,
+    Head,
+    Options
+}
+
+public sealed class RateLimitInfo
+{
+    public int? RequestsPerMinute { get; init; }
+    public int? RequestsPerHour { get; init; }
+    public int? RequestsPerDay { get; init; }
+}
+
+/// <summary>
+/// API-specific metadata that extends SemanticEntity for integration scenarios.
+/// Store this in SemanticEntity.Metadata["api"] for entities parsed from API schemas.
+/// </summary>
+public sealed class ApiEntityMetadata
+{
+    /// <summary>
+    /// The external system this entity comes from (e.g., "FlightBridge", "1200Aero")
+    /// </summary>
+    public required string SourceSystem { get; init; }
+    
+    /// <summary>
+    /// Original field/property name in external system
+    /// </summary>
+    public string? ExternalName { get; init; }
+    
+    /// <summary>
+    /// JSON path in API response (e.g., "$.data.reservation.id")
+    /// </summary>
+    public string? JsonPath { get; init; }
+    
+    /// <summary>
+    /// Is this field required by the external API?
+    /// </summary>
+    public bool IsExternallyRequired { get; init; }
+    
+    /// <summary>
+    /// External validation rules (regex, min/max, etc.)
+    /// </summary>
+    public List<ExternalValidation> Validations { get; init; } = [];
+    
+    /// <summary>
+    /// Sample values seen from this field (useful for type inference)
+    /// </summary>
+    public List<string> SampleValues { get; init; } = [];
+    
+    /// <summary>
+    /// Data freshness requirements (SLA)
+    /// </summary>
+    public TimeSpan? MaxDataAge { get; init; }
+}
+
+public sealed class ExternalValidation
+{
+    public required ValidationType Type { get; init; }
+    public required string Rule { get; init; }
+    public string? ErrorMessage { get; init; }
+}
+
+public enum ValidationType
+{
+    Regex,
+    MinLength,
+    MaxLength,
+    MinValue,
+    MaxValue,
+    Enum,
+    Custom
+}
diff --git a/src/DocFlow.Integration/Models/IntegrationSpec.cs b/src/DocFlow.Integration/Models/IntegrationSpec.cs
new file mode 100644
index 0000000..1009a70
--- /dev/null
+++ b/src/DocFlow.Integration/Models/IntegrationSpec.cs
@@ -0,0 +1,288 @@
+namespace DocFlow.Integration.Models;
+
+/// <summary>
+/// A complete integration specification between an external API and your CDM.
+/// This is what DocFlow generates and what drives code generation.
+/// </summary>
+public sealed class IntegrationSpec
+{
+    public required string Id { get; init; }
+    public required string Name { get; init; }
+    public string? Description { get; init; }
+    public required string Version { get; init; }
+    
+    /// <summary>
+    /// The external system being integrated
+    /// </summary>
+    public required ExternalSystemInfo ExternalSystem { get; init; }
+    
+    /// <summary>
+    /// Reference to your Canonical Data Model
+    /// </summary>
+    public required CdmReference CanonicalModel { get; init; }
+    
+    /// <summary>
+    /// All endpoints being integrated
+    /// </summary>
+    public List<EndpointIntegration> Endpoints { get; init; } = [];
+    
+    /// <summary>
+    /// Entity mappings (external DTO → CDM entity)
+    /// </summary>
+    public List<EntityMapping> EntityMappings { get; init; } = [];
+    
+    /// <summary>
+    /// Global transformation rules
+    /// </summary>
+    public List<TransformationRule> GlobalTransforms { get; init; } = [];
+    
+    /// <summary>
+    /// SLA requirements
+    /// </summary>
+    public SlaRequirements? Sla { get; init; }
+    
+    /// <summary>
+    /// Authentication configuration
+    /// </summary>
+    public AuthConfig? Authentication { get; init; }
+    
+    /// <summary>
+    /// When this spec was generated/last updated
+    /// </summary>
+    public DateTime GeneratedAt { get; init; }
+    
+    /// <summary>
+    /// IMS confidence scores for auto-generated mappings
+    /// </summary>
+    public MappingConfidenceReport? ConfidenceReport { get; init; }
+}
+
+public sealed class ExternalSystemInfo
+{
+    /// <summary>External system name (e.g., "FlightBridge", "1200Aero")</summary>
+    public required string Name { get; init; }
+    
+    /// <summary>Base URL for API calls</summary>
+    public required string BaseUrl { get; init; }
+    
+    /// <summary>Link to API documentation</summary>
+    public string? DocumentationUrl { get; init; }
+    
+    /// <summary>API version</summary>
+    public string? Version { get; init; }
+    
+    /// <summary>Contact information for the external team</summary>
+    public string? Contact { get; init; }
+}
+
+public sealed class CdmReference
+{
+    /// <summary>CDM name (e.g., "OpenFlight CDM")</summary>
+    public required string Name { get; init; }
+    
+    /// <summary>CDM version</summary>
+    public required string Version { get; init; }
+    
+    /// <summary>Path to CDM C# source files</summary>
+    public string? SourcePath { get; init; }
+    
+    /// <summary>Path to CDM schema definition</summary>
+    public string? SchemaPath { get; init; }
+}
+
+public sealed class EndpointIntegration
+{
+    public required ApiEndpoint Endpoint { get; init; }
+    
+    /// <summary>
+    /// What CDM operation does this endpoint support?
+    /// </summary>
+    public required CdmOperation Operation { get; init; }
+    
+    /// <summary>
+    /// Mappings specific to this endpoint
+    /// </summary>
+    public List<FieldMapping> FieldMappings { get; init; } = [];
+    
+    /// <summary>
+    /// Is this endpoint integration complete and verified?
+    /// </summary>
+    public IntegrationStatus Status { get; init; }
+}
+
+public enum CdmOperation
+{
+    /// <summary>GET - retrieve data</summary>
+    Query,
+    
+    /// <summary>POST - create new entity</summary>
+    Create,
+    
+    /// <summary>PUT/PATCH - update entity</summary>
+    Update,
+    
+    /// <summary>DELETE - remove entity</summary>
+    Delete,
+    
+    /// <summary>Webhook/event subscription</summary>
+    Subscribe,
+    
+    /// <summary>Outbound notification</summary>
+    Notify
+}
+
+public enum IntegrationStatus
+{
+    NotStarted,
+    InProgress,
+    
+    /// <summary>IMS auto-mapped but needs human verification</summary>
+    NeedsReview,
+    
+    /// <summary>Human verified correct</summary>
+    Verified,
+    
+    /// <summary>Deployed and working in production</summary>
+    Production
+}
+
+public sealed class EntityMapping
+{
+    public required string ExternalEntityName { get; init; }
+    public required string CdmEntityName { get; init; }
+    public List<FieldMapping> FieldMappings { get; init; } = [];
+    public double Confidence { get; init; }
+    public IntegrationStatus Status { get; init; }
+}
+
+public sealed class FieldMapping
+{
+    /// <summary>Source field name in external API (e.g., "arr_time")</summary>
+    public required string SourceField { get; init; }
+    
+    /// <summary>Target field name in CDM (e.g., "ArrivalDateTime")</summary>
+    public required string TargetField { get; init; }
+    
+    /// <summary>Transformation to apply during mapping</summary>
+    public TransformationRule? Transformation { get; init; }
+    
+    /// <summary>IMS confidence score (0-1)</summary>
+    public double Confidence { get; init; }
+    
+    /// <summary>Why this mapping was suggested (e.g., "IMS: 94% match based on 47 prior examples")</summary>
+    public string? Reasoning { get; init; }
+    
+    /// <summary>Was this mapping auto-generated by IMS?</summary>
+    public bool IsAutoMapped { get; init; }
+    
+    /// <summary>Has a human verified this mapping?</summary>
+    public bool IsVerified { get; init; }
+}
+
+public sealed class TransformationRule
+{
+    public required string Id { get; init; }
+    public required TransformationType Type { get; init; }
+    public required string Expression { get; init; }
+    public Dictionary<string, object> Parameters { get; init; } = [];
+}
+
+public enum TransformationType
+{
+    /// <summary>No transformation, direct copy</summary>
+    Direct,
+    
+    /// <summary>Type conversion (string → DateTime, int → decimal)</summary>
+    TypeConversion,
+    
+    /// <summary>Date format conversion, string formatting</summary>
+    Format,
+    
+    /// <summary>Value lookup/translation table</summary>
+    Lookup,
+    
+    /// <summary>Computed value from expression</summary>
+    Calculation,
+    
+    /// <summary>Combine multiple fields</summary>
+    Concatenation,
+    
+    /// <summary>Split single field into multiple</summary>
+    Split,
+    
+    /// <summary>If/then/else logic</summary>
+    Conditional,
+    
+    /// <summary>Custom C# expression</summary>
+    Custom
+}
+
+public sealed class SlaRequirements
+{
+    /// <summary>Maximum acceptable response latency</summary>
+    public TimeSpan MaxLatency { get; init; }
+    
+    /// <summary>Maximum acceptable data age (e.g., 30 seconds for real-time feeds)</summary>
+    public TimeSpan MaxDataAge { get; init; }
+    
+    /// <summary>Minimum uptime percentage (e.g., 99.9%)</summary>
+    public double MinUptime { get; init; }
+    
+    /// <summary>Maximum error rate per 1000 requests</summary>
+    public int MaxErrorRate { get; init; }
+}
+
+public sealed class AuthConfig
+{
+    public required AuthType Type { get; init; }
+    public Dictionary<string, string> Parameters { get; init; } = [];
+}
+
+public enum AuthType
+{
+    None,
+    ApiKey,
+    Basic,
+    Bearer,
+    OAuth2,
+    Certificate,
+    Custom
+}
+
+public sealed class MappingConfidenceReport
+{
+    public int TotalMappings { get; init; }
+    
+    /// <summary>Mappings with confidence > 90%</summary>
+    public int HighConfidence { get; init; }
+    
+    /// <summary>Mappings with confidence 70-90%</summary>
+    public int MediumConfidence { get; init; }
+    
+    /// <summary>Mappings with confidence below 70%</summary>
+    public int LowConfidence { get; init; }
+    
+    /// <summary>Fields with no mapping found</summary>
+    public int Unmapped { get; init; }
+    
+    public double OverallConfidence { get; init; }
+    public List<MappingIssue> Issues { get; init; } = [];
+}
+
+public sealed class MappingIssue
+{
+    public required string Field { get; init; }
+    public required MappingIssueType Type { get; init; }
+    public required string Description { get; init; }
+    public List<string> Suggestions { get; init; } = [];
+}
+
+public enum MappingIssueType
+{
+    NoMatch,
+    AmbiguousMatch,
+    TypeMismatch,
+    NullabilityMismatch,
+    ValidationConflict,
+    SlaRisk
+}
diff --git a/src/DocFlow.Integration/Patterns/ApiMappingPatterns.cs b/src/DocFlow.Integration/Patterns/ApiMappingPatterns.cs
new file mode 100644
index 0000000..4c1acd3
--- /dev/null
+++ b/src/DocFlow.Integration/Patterns/ApiMappingPatterns.cs
@@ -0,0 +1,374 @@
+using DocFlow.IMS;
+using DocFlow.Integration.Models;
+
+namespace DocFlow.Integration.Patterns;
+
+/// <summary>
+/// Pre-built patterns for common API field mapping scenarios.
+/// These seed the IMS with domain knowledge to improve auto-mapping accuracy.
+/// </summary>
+public static class ApiMappingPatterns
+{
+    /// <summary>
+    /// Common aviation industry field mappings.
+    /// Based on patterns observed across FlightBridge, 1200Aero, and other aviation APIs.
+    /// </summary>
+    public static class Aviation
+    {
+        public static readonly PatternRule TailNumber = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(tail[_-]?(num|number|no)|aircraft[_-]?id|reg(istration)?|ac[_-]?reg)",
+            Parameters = new Dictionary<string, object>
+            {
+                ["targetField"] = "TailNumber",
+                ["description"] = "Aircraft tail number / registration"
+            }
+        };
+        
+        public static readonly PatternRule FlightNumber = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(flight[_-]?(num|number|no|id)|flt[_-]?(num|no)|callsign)",
+            Parameters = new Dictionary<string, object>
+            {
+                ["targetField"] = "FlightNumber",
+                ["description"] = "Flight number identifier"
+            }
+        };
+        
+        public static readonly PatternRule ArrivalTime = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(arr(ival)?[_-]?(time|dt|date|datetime)?|eta|ata|landing[_-]?time)",
+            Parameters = new Dictionary<string, object>
+            {
+                ["targetField"] = "ArrivalDateTime",
+                ["description"] = "Arrival date/time"
+            }
+        };
+        
+        public static readonly PatternRule DepartureTime = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(dep(arture)?[_-]?(time|dt|date|datetime)?|etd|atd|takeoff[_-]?time)",
+            Parameters = new Dictionary<string, object>
+            {
+                ["targetField"] = "DepartureDateTime",
+                ["description"] = "Departure date/time"
+            }
+        };
+        
+        public static readonly PatternRule OriginAirport = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(origin|departure|from)[_-]?(icao|iata|airport|apt)?[_-]?(code|id)?",
+            Parameters = new Dictionary<string, object>
+            {
+                ["targetField"] = "OriginAirportCode",
+                ["description"] = "Origin airport ICAO/IATA code"
+            }
+        };
+        
+        public static readonly PatternRule DestinationAirport = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(dest(ination)?|arrival|to)[_-]?(icao|iata|airport|apt)?[_-]?(code|id)?",
+            Parameters = new Dictionary<string, object>
+            {
+                ["targetField"] = "DestinationAirportCode",
+                ["description"] = "Destination airport ICAO/IATA code"
+            }
+        };
+        
+        public static readonly PatternRule PassengerCount = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(pax|passenger)[_-]?(count|num|qty|number)?|num[_-]?passengers|souls",
+            Parameters = new Dictionary<string, object>
+            {
+                ["targetField"] = "PassengerCount",
+                ["description"] = "Number of passengers"
+            }
+        };
+        
+        public static readonly PatternRule FuelQuantity = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(fuel)[_-]?(qty|quantity|amount|gallons|liters|lbs|weight)",
+            Parameters = new Dictionary<string, object>
+            {
+                ["targetField"] = "FuelQuantity",
+                ["description"] = "Fuel quantity"
+            }
+        };
+        
+        public static readonly PatternRule FboIdentifier = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(fbo|handler)[_-]?(id|code|name)?",
+            Parameters = new Dictionary<string, object>
+            {
+                ["targetField"] = "FboId",
+                ["description"] = "Fixed Base Operator identifier"
+            }
+        };
+        
+        public static readonly PatternRule ReservationId = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(res(ervation)?|booking)[_-]?(id|num|number|code)",
+            Parameters = new Dictionary<string, object>
+            {
+                ["targetField"] = "ReservationId",
+                ["description"] = "Reservation identifier"
+            }
+        };
+        
+        /// <summary>
+        /// Get all aviation patterns
+        /// </summary>
+        public static IEnumerable<PatternRule> All => new[]
+        {
+            TailNumber, FlightNumber, ArrivalTime, DepartureTime,
+            OriginAirport, DestinationAirport, PassengerCount,
+            FuelQuantity, FboIdentifier, ReservationId
+        };
+    }
+    
+    /// <summary>
+    /// Common date/time transformation patterns
+    /// </summary>
+    public static class DateTime
+    {
+        public static readonly TransformationRule IsoToDateTime = new()
+        {
+            Id = "iso-to-datetime",
+            Type = TransformationType.TypeConversion,
+            Expression = "DateTime.Parse(source, CultureInfo.InvariantCulture, DateTimeStyles.RoundtripKind)"
+        };
+        
+        public static readonly TransformationRule UnixSecondsToDateTime = new()
+        {
+            Id = "unix-seconds-to-datetime",
+            Type = TransformationType.TypeConversion,
+            Expression = "DateTimeOffset.FromUnixTimeSeconds((long)source).UtcDateTime"
+        };
+        
+        public static readonly TransformationRule UnixMillisToDateTime = new()
+        {
+            Id = "unix-millis-to-datetime",
+            Type = TransformationType.TypeConversion,
+            Expression = "DateTimeOffset.FromUnixTimeMilliseconds((long)source).UtcDateTime"
+        };
+        
+        public static readonly TransformationRule DateTimeToIso = new()
+        {
+            Id = "datetime-to-iso",
+            Type = TransformationType.TypeConversion,
+            Expression = "((DateTime)source).ToString(\"O\")"
+        };
+        
+        public static readonly TransformationRule DateTimeToUnixSeconds = new()
+        {
+            Id = "datetime-to-unix-seconds",
+            Type = TransformationType.TypeConversion,
+            Expression = "new DateTimeOffset((DateTime)source).ToUnixTimeSeconds()"
+        };
+        
+        /// <summary>
+        /// Common date format conversions
+        /// </summary>
+        public static readonly TransformationRule UsDateToIso = new()
+        {
+            Id = "us-date-to-iso",
+            Type = TransformationType.Format,
+            Expression = "DateTime.ParseExact(source, \"MM/dd/yyyy\", CultureInfo.InvariantCulture).ToString(\"yyyy-MM-dd\")"
+        };
+        
+        public static IEnumerable<TransformationRule> All => new[]
+        {
+            IsoToDateTime, UnixSecondsToDateTime, UnixMillisToDateTime,
+            DateTimeToIso, DateTimeToUnixSeconds, UsDateToIso
+        };
+    }
+    
+    /// <summary>
+    /// Common identifier patterns
+    /// </summary>
+    public static class Identifiers
+    {
+        public static readonly PatternRule PrimaryKey = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)^(id|[a-z]+[_-]?id|pk|primary[_-]?key|guid|uuid)$",
+            Parameters = new Dictionary<string, object>
+            {
+                ["semantics"] = "Identity",
+                ["description"] = "Primary key identifier"
+            }
+        };
+        
+        public static readonly PatternRule ForeignKey = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)^([a-z]+)[_-]?id$",
+            Parameters = new Dictionary<string, object>
+            {
+                ["semantics"] = "Navigation",
+                ["description"] = "Foreign key reference"
+            }
+        };
+        
+        public static readonly PatternRule ExternalReference = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(external|ext|ref|reference|source)[_-]?(id|key|num|code)",
+            Parameters = new Dictionary<string, object>
+            {
+                ["description"] = "External system reference"
+            }
+        };
+        
+        public static readonly PatternRule CorrelationId = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(correlation|tracking|trace|request)[_-]?id",
+            Parameters = new Dictionary<string, object>
+            {
+                ["description"] = "Correlation/tracking identifier"
+            }
+        };
+        
+        public static IEnumerable<PatternRule> All => new[]
+        {
+            PrimaryKey, ForeignKey, ExternalReference, CorrelationId
+        };
+    }
+    
+    /// <summary>
+    /// Common contact/person patterns
+    /// </summary>
+    public static class Contact
+    {
+        public static readonly PatternRule Email = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(email|e[_-]?mail)[_-]?(address)?",
+            Parameters = new Dictionary<string, object>
+            {
+                ["targetField"] = "EmailAddress",
+                ["validation"] = @"^[^@]+@[^@]+\.[^@]+$"
+            }
+        };
+        
+        public static readonly PatternRule Phone = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(phone|tel(ephone)?|mobile|cell)[_-]?(num|number)?",
+            Parameters = new Dictionary<string, object>
+            {
+                ["targetField"] = "PhoneNumber"
+            }
+        };
+        
+        public static readonly PatternRule FirstName = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(first|given)[_-]?name|fname",
+            Parameters = new Dictionary<string, object>
+            {
+                ["targetField"] = "FirstName"
+            }
+        };
+        
+        public static readonly PatternRule LastName = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(last|family|sur)[_-]?name|lname",
+            Parameters = new Dictionary<string, object>
+            {
+                ["targetField"] = "LastName"
+            }
+        };
+        
+        public static IEnumerable<PatternRule> All => new[]
+        {
+            Email, Phone, FirstName, LastName
+        };
+    }
+    
+    /// <summary>
+    /// Common audit/timestamp patterns
+    /// </summary>
+    public static class Audit
+    {
+        public static readonly PatternRule CreatedAt = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(created|create|inserted|insert)[_-]?(at|on|date|time|datetime|timestamp)?",
+            Parameters = new Dictionary<string, object>
+            {
+                ["targetField"] = "CreatedAt",
+                ["semantics"] = "Audit"
+            }
+        };
+        
+        public static readonly PatternRule UpdatedAt = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(updated|update|modified|modify|changed)[_-]?(at|on|date|time|datetime|timestamp)?",
+            Parameters = new Dictionary<string, object>
+            {
+                ["targetField"] = "UpdatedAt",
+                ["semantics"] = "Audit"
+            }
+        };
+        
+        public static readonly PatternRule CreatedBy = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(created|inserted)[_-]?by[_-]?(user|id)?",
+            Parameters = new Dictionary<string, object>
+            {
+                ["targetField"] = "CreatedBy",
+                ["semantics"] = "Audit"
+            }
+        };
+        
+        public static readonly PatternRule UpdatedBy = new()
+        {
+            Type = PatternRuleType.NamePattern,
+            Condition = @"(?i)(updated|modified|changed)[_-]?by[_-]?(user|id)?",
+            Parameters = new Dictionary<string, object>
+            {
+                ["targetField"] = "UpdatedBy",
+                ["semantics"] = "Audit"
+            }
+        };
+        
+        public static IEnumerable<PatternRule> All => new[]
+        {
+            CreatedAt, UpdatedAt, CreatedBy, UpdatedBy
+        };
+    }
+    
+    /// <summary>
+    /// Get all built-in patterns
+    /// </summary>
+    public static IEnumerable<PatternRule> GetAllPatterns()
+    {
+        foreach (var pattern in Aviation.All) yield return pattern;
+        foreach (var pattern in Identifiers.All) yield return pattern;
+        foreach (var pattern in Contact.All) yield return pattern;
+        foreach (var pattern in Audit.All) yield return pattern;
+    }
+    
+    /// <summary>
+    /// Get all built-in transformations
+    /// </summary>
+    public static IEnumerable<TransformationRule> GetAllTransformations()
+    {
+        return DateTime.All;
+    }
+}
diff --git a/src/DocFlow.Integration/Schemas/ISchemaParser.cs b/src/DocFlow.Integration/Schemas/ISchemaParser.cs
new file mode 100644
index 0000000..d5702ee
--- /dev/null
+++ b/src/DocFlow.Integration/Schemas/ISchemaParser.cs
@@ -0,0 +1,115 @@
+using DocFlow.Core.Abstractions;
+using DocFlow.Core.CanonicalModel;
+
+namespace DocFlow.Integration.Schemas;
+
+/// <summary>
+/// Parses external API schema formats into the semantic model.
+/// </summary>
+public interface ISchemaParser : IModelParser
+{
+    /// <summary>
+    /// Supported schema formats (e.g., "OpenAPI3", "Swagger2", "JsonSchema", "GraphQL")
+    /// </summary>
+    IReadOnlyList<string> SupportedFormats { get; }
+    
+    /// <summary>
+    /// Parse schema and extract API endpoints
+    /// </summary>
+    Task<SchemaParseResult> ParseSchemaAsync(
+        ParserInput input, 
+        SchemaParserOptions? options = null,
+        CancellationToken cancellationToken = default);
+}
+
+/// <summary>
+/// Extended parse result that includes API endpoint information
+/// </summary>
+public sealed class SchemaParseResult
+{
+    /// <summary>
+    /// The parsed semantic model
+    /// </summary>
+    public required SemanticModel Model { get; init; }
+
+    /// <summary>
+    /// Whether parsing succeeded
+    /// </summary>
+    public bool Success { get; init; }
+
+    /// <summary>
+    /// Errors encountered during parsing
+    /// </summary>
+    public IReadOnlyList<ParseError> Errors { get; init; } = [];
+
+    /// <summary>
+    /// Warnings encountered during parsing
+    /// </summary>
+    public IReadOnlyList<ParseWarning> Warnings { get; init; } = [];
+
+    /// <summary>
+    /// API endpoints extracted from the schema
+    /// </summary>
+    public List<Models.ApiEndpoint> Endpoints { get; init; } = [];
+
+    /// <summary>
+    /// External system info extracted from schema metadata
+    /// </summary>
+    public Models.ExternalSystemInfo? ExternalSystem { get; init; }
+
+    /// <summary>
+    /// Authentication requirements
+    /// </summary>
+    public Models.AuthConfig? Authentication { get; init; }
+
+    /// <summary>
+    /// Rate limiting info if specified
+    /// </summary>
+    public Models.RateLimitInfo? RateLimit { get; init; }
+
+    /// <summary>
+    /// Statistics about the parsing operation
+    /// </summary>
+    public ParseStatistics? Statistics { get; init; }
+
+    /// <summary>
+    /// Create a failed result
+    /// </summary>
+    public static SchemaParseResult Failed(ParseError error) => new()
+    {
+        Model = new SemanticModel { Name = "Error" },
+        Success = false,
+        Errors = [error]
+    };
+}
+
+/// <summary>
+/// Options for schema parsing
+/// </summary>
+public sealed class SchemaParserOptions
+{
+    /// <summary>
+    /// Include source information in the model
+    /// </summary>
+    public bool IncludeSourceInfo { get; init; } = true;
+
+    /// <summary>
+    /// Include only endpoints matching these paths (glob patterns)
+    /// </summary>
+    public List<string>? EndpointFilter { get; init; }
+
+    /// <summary>
+    /// Include request/response examples in the model
+    /// </summary>
+    public bool IncludeExamples { get; init; } = true;
+
+    /// <summary>
+    /// Flatten nested objects into separate entities
+    /// </summary>
+    public bool FlattenNestedObjects { get; init; } = true;
+
+    /// <summary>
+    /// Generate entity names from schema $ref names
+    /// </summary>
+    public bool UseRefNames { get; init; } = true;
+}
diff --git a/src/DocFlow.Integration/Schemas/OpenApi/OpenApiParser.cs b/src/DocFlow.Integration/Schemas/OpenApi/OpenApiParser.cs
new file mode 100644
index 0000000..b5e9158
--- /dev/null
+++ b/src/DocFlow.Integration/Schemas/OpenApi/OpenApiParser.cs
@@ -0,0 +1,415 @@
+using System.Text.RegularExpressions;
+using DocFlow.Core.Abstractions;
+using DocFlow.Core.CanonicalModel;
+using DocFlow.Integration.Models;
+using Microsoft.Extensions.Logging;
+using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi.Readers;
+
+namespace DocFlow.Integration.Schemas.OpenApi;
+
+/// <summary>
+/// Parses OpenAPI 3.x specifications into the semantic model.
+/// </summary>
+public sealed class OpenApiParser : ISchemaParser
+{
+    private readonly ILogger<OpenApiParser>? _logger;
+    
+    public OpenApiParser(ILogger<OpenApiParser>? logger = null)
+    {
+        _logger = logger;
+    }
+    
+    public string SourceFormat => "OpenAPI";
+    public IReadOnlyList<string> SupportedExtensions => [".json", ".yaml", ".yml"];
+    public IReadOnlyList<string> SupportedFormats => ["OpenAPI3", "OpenAPI3.0", "OpenAPI3.1"];
+    
+    public bool CanParse(ParserInput input)
+    {
+        if (input.FilePath is not null)
+        {
+            var ext = Path.GetExtension(input.FilePath).ToLowerInvariant();
+            return SupportedExtensions.Contains(ext);
+        }
+        
+        // Try to detect OpenAPI content
+        if (input.Content is not null)
+        {
+            return input.Content.Contains("openapi") || input.Content.Contains("swagger");
+        }
+        
+        return false;
+    }
+    
+    public async Task<ParseResult> ParseAsync(
+        ParserInput input,
+        ParserOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        // Convert base ParseResult to SchemaParseResult
+        var schemaResult = await ParseSchemaAsync(input, new SchemaParserOptions(), cancellationToken);
+        return new ParseResult
+        {
+            Model = schemaResult.Model,
+            Success = schemaResult.Success,
+            Errors = schemaResult.Errors.ToList(),
+            Warnings = schemaResult.Warnings.ToList(),
+            Statistics = schemaResult.Statistics
+        };
+    }
+    
+    public async Task<SchemaParseResult> ParseSchemaAsync(
+        ParserInput input, 
+        SchemaParserOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        options ??= new SchemaParserOptions();
+        
+        var model = new SemanticModel
+        {
+            Name = "OpenAPI Schema",
+            Provenance = new ModelProvenance
+            {
+                SourceFormat = SourceFormat,
+                CreatedAt = DateTime.UtcNow
+            }
+        };
+        
+        var endpoints = new List<ApiEndpoint>();
+        var errors = new List<ParseError>();
+        var warnings = new List<ParseWarning>();
+        
+        try
+        {
+            // Read the OpenAPI document
+            OpenApiDocument document;
+            
+            if (input.FilePath is not null)
+            {
+                using var stream = File.OpenRead(input.FilePath);
+                var readResult = await new OpenApiStreamReader().ReadAsync(stream, cancellationToken);
+                document = readResult.OpenApiDocument;
+                
+                foreach (var diagnostic in readResult.OpenApiDiagnostic.Errors)
+                {
+                    errors.Add(new ParseError
+                    {
+                        Code = "OPENAPI_ERROR",
+                        Message = diagnostic.Message
+                    });
+                }
+            }
+            else if (input.Content is not null)
+            {
+                using var stream = new MemoryStream(System.Text.Encoding.UTF8.GetBytes(input.Content));
+                var readResult = await new OpenApiStreamReader().ReadAsync(stream, cancellationToken);
+                document = readResult.OpenApiDocument;
+            }
+            else
+            {
+                return new SchemaParseResult
+                {
+                    Model = model,
+                    Success = false,
+                    Errors = [new ParseError { Code = "NO_INPUT", Message = "No input provided" }]
+                };
+            }
+            
+            // Extract external system info
+            var externalSystem = ExtractExternalSystemInfo(document);
+            model.Name = externalSystem.Name;
+            
+            // Extract schemas as entities
+            if (document.Components?.Schemas != null)
+            {
+                foreach (var (name, schema) in document.Components.Schemas)
+                {
+                    var entity = ParseSchemaToEntity(name, schema, options);
+                    model.AddEntity(entity);
+                }
+            }
+            
+            // Extract endpoints
+            foreach (var (path, pathItem) in document.Paths)
+            {
+                foreach (var (method, operation) in pathItem.Operations)
+                {
+                    if (ShouldIncludeEndpoint(path, options.EndpointFilter))
+                    {
+                        var endpoint = ParseEndpoint(path, method, operation, model);
+                        endpoints.Add(endpoint);
+                    }
+                }
+            }
+            
+            // Extract authentication
+            var authConfig = ExtractAuthConfig(document);
+            
+            _logger?.LogInformation(
+                "Parsed OpenAPI spec: {EntityCount} entities, {EndpointCount} endpoints",
+                model.Entities.Count, endpoints.Count);
+            
+            return new SchemaParseResult
+            {
+                Model = model,
+                Success = errors.Count == 0,
+                Endpoints = endpoints,
+                ExternalSystem = externalSystem,
+                Authentication = authConfig,
+                Errors = errors,
+                Warnings = warnings,
+                Statistics = new ParseStatistics
+                {
+                    EntitiesParsed = model.Entities.Count,
+                    RelationshipsParsed = model.Relationships.Count
+                }
+            };
+        }
+        catch (Exception ex)
+        {
+            _logger?.LogError(ex, "Failed to parse OpenAPI spec");
+            
+            return new SchemaParseResult
+            {
+                Model = model,
+                Success = false,
+                Errors = [new ParseError { Code = "PARSE_EXCEPTION", Message = ex.Message }]
+            };
+        }
+    }
+    
+    private static ExternalSystemInfo ExtractExternalSystemInfo(OpenApiDocument document)
+    {
+        var info = document.Info;
+        var servers = document.Servers;
+        
+        return new ExternalSystemInfo
+        {
+            Name = info?.Title ?? "Unknown API",
+            BaseUrl = servers?.FirstOrDefault()?.Url ?? "https://api.example.com",
+            Version = info?.Version,
+            DocumentationUrl = info?.Contact?.Url?.ToString(),
+            Contact = info?.Contact?.Email
+        };
+    }
+    
+    private SemanticEntity ParseSchemaToEntity(
+        string name, 
+        OpenApiSchema schema,
+        SchemaParserOptions options)
+    {
+        var entity = new SemanticEntity
+        {
+            Id = Guid.NewGuid().ToString(),
+            Name = name,
+            Description = schema.Description,
+            Classification = InferClassification(name, schema)
+        };
+        
+        // Parse properties
+        foreach (var (propName, propSchema) in schema.Properties)
+        {
+            var property = new SemanticProperty
+            {
+                Name = ToPascalCase(propName),
+                Type = MapSchemaType(propSchema),
+                Description = propSchema.Description,
+                IsRequired = schema.Required?.Contains(propName) ?? false,
+                Visibility = Visibility.Public
+            };
+            
+            // Store original API name in metadata for mapping
+            property.Attributes.Add(new SemanticAttribute
+            {
+                Name = "JsonPropertyName",
+                Arguments = new Dictionary<string, object> { ["name"] = propName }
+            });
+            
+            entity.Properties.Add(property);
+        }
+        
+        return entity;
+    }
+    
+    private static EntityClassification InferClassification(string name, OpenApiSchema schema)
+    {
+        // Simple heuristics - IMS will improve these over time
+        var nameLower = name.ToLowerInvariant();
+        
+        if (nameLower.EndsWith("request")) return EntityClassification.Command;
+        if (nameLower.EndsWith("response")) return EntityClassification.DataTransferObject;
+        if (nameLower.EndsWith("event")) return EntityClassification.DomainEvent;
+        if (nameLower.EndsWith("dto")) return EntityClassification.DataTransferObject;
+        
+        // Default to DTO for API schemas
+        return EntityClassification.DataTransferObject;
+    }
+    
+    private static SemanticType MapSchemaType(OpenApiSchema schema)
+    {
+        return schema.Type switch
+        {
+            "string" when schema.Format == "date-time" => SemanticType.DateTime,
+            "string" when schema.Format == "uuid" => SemanticType.Guid,
+            "string" => SemanticType.String,
+            "integer" when schema.Format == "int64" => SemanticType.Long,
+            "integer" => SemanticType.Int,
+            "number" => SemanticType.Decimal,
+            "boolean" => SemanticType.Bool,
+            "array" => SemanticType.CollectionOf(
+                schema.Items != null ? MapSchemaType(schema.Items) : SemanticType.String),
+            _ when schema.Reference != null => SemanticType.EntityReference(
+                schema.Reference.Id, schema.Reference.Id),
+            _ => SemanticType.String
+        };
+    }
+    
+    private ApiEndpoint ParseEndpoint(
+        string path,
+        OperationType method,
+        OpenApiOperation operation,
+        SemanticModel model)
+    {
+        var endpoint = new ApiEndpoint
+        {
+            Id = Guid.NewGuid().ToString(),
+            Path = path,
+            Method = MapHttpMethod(method),
+            Summary = operation.Summary,
+            Description = operation.Description
+        };
+        
+        // Parse path parameters
+        foreach (var param in operation.Parameters.Where(p => p.In == ParameterLocation.Path))
+        {
+            endpoint.PathParameters.Add(new ApiParameter
+            {
+                Name = param.Name,
+                Type = param.Schema != null ? MapSchemaType(param.Schema) : SemanticType.String,
+                IsRequired = param.Required,
+                Description = param.Description
+            });
+        }
+        
+        // Parse query parameters
+        foreach (var param in operation.Parameters.Where(p => p.In == ParameterLocation.Query))
+        {
+            endpoint.QueryParameters.Add(new ApiParameter
+            {
+                Name = param.Name,
+                Type = param.Schema != null ? MapSchemaType(param.Schema) : SemanticType.String,
+                IsRequired = param.Required,
+                Description = param.Description
+            });
+        }
+        
+        // Parse request body
+        if (operation.RequestBody?.Content != null)
+        {
+            var jsonContent = operation.RequestBody.Content
+                .FirstOrDefault(c => c.Key.Contains("json")).Value;
+                
+            if (jsonContent?.Schema?.Reference != null)
+            {
+                endpoint.RequestEntityId = jsonContent.Schema.Reference.Id;
+            }
+        }
+        
+        // Parse response
+        var successResponse = operation.Responses
+            .FirstOrDefault(r => r.Key.StartsWith("2")).Value;
+            
+        if (successResponse?.Content != null)
+        {
+            var jsonContent = successResponse.Content
+                .FirstOrDefault(c => c.Key.Contains("json")).Value;
+                
+            if (jsonContent?.Schema?.Reference != null)
+            {
+                endpoint.ResponseEntityId = jsonContent.Schema.Reference.Id;
+            }
+        }
+        
+        // Parse response codes
+        foreach (var (code, response) in operation.Responses)
+        {
+            if (int.TryParse(code, out var statusCode))
+            {
+                endpoint.ResponseCodes[statusCode] = response.Description ?? "";
+            }
+        }
+        
+        return endpoint;
+    }
+    
+    private static Models.HttpMethod MapHttpMethod(OperationType method) => method switch
+    {
+        OperationType.Get => Models.HttpMethod.Get,
+        OperationType.Post => Models.HttpMethod.Post,
+        OperationType.Put => Models.HttpMethod.Put,
+        OperationType.Patch => Models.HttpMethod.Patch,
+        OperationType.Delete => Models.HttpMethod.Delete,
+        OperationType.Head => Models.HttpMethod.Head,
+        OperationType.Options => Models.HttpMethod.Options,
+        _ => Models.HttpMethod.Get
+    };
+    
+    private static AuthConfig? ExtractAuthConfig(OpenApiDocument document)
+    {
+        if (document.Components?.SecuritySchemes == null)
+            return null;
+            
+        var scheme = document.Components.SecuritySchemes.FirstOrDefault();
+        if (scheme.Value == null)
+            return null;
+            
+        return scheme.Value.Type switch
+        {
+            SecuritySchemeType.ApiKey => new AuthConfig
+            {
+                Type = AuthType.ApiKey,
+                Parameters = new Dictionary<string, string>
+                {
+                    ["name"] = scheme.Value.Name ?? "api_key",
+                    ["in"] = scheme.Value.In.ToString().ToLowerInvariant()
+                }
+            },
+            SecuritySchemeType.Http when scheme.Value.Scheme == "bearer" => new AuthConfig
+            {
+                Type = AuthType.Bearer
+            },
+            SecuritySchemeType.Http when scheme.Value.Scheme == "basic" => new AuthConfig
+            {
+                Type = AuthType.Basic
+            },
+            SecuritySchemeType.OAuth2 => new AuthConfig
+            {
+                Type = AuthType.OAuth2,
+                Parameters = new Dictionary<string, string>
+                {
+                    ["flow"] = scheme.Value.Flows?.AuthorizationCode != null ? "authorization_code" : "client_credentials"
+                }
+            },
+            _ => null
+        };
+    }
+    
+    private static bool ShouldIncludeEndpoint(string path, List<string>? filters)
+    {
+        if (filters == null || filters.Count == 0)
+            return true;
+            
+        return filters.Any(filter => 
+            Regex.IsMatch(path, "^" + Regex.Escape(filter).Replace("\\*", ".*") + "$"));
+    }
+    
+    private static string ToPascalCase(string name)
+    {
+        if (string.IsNullOrEmpty(name)) return name;
+        
+        // Handle snake_case and kebab-case
+        var parts = name.Split(['_', '-'], StringSplitOptions.RemoveEmptyEntries);
+        return string.Concat(parts.Select(p => 
+            char.ToUpperInvariant(p[0]) + p[1..].ToLowerInvariant()));
+    }
+}
diff --git a/src/DocFlow.Integration/Validation/SlaValidator.cs b/src/DocFlow.Integration/Validation/SlaValidator.cs
new file mode 100644
index 0000000..86f2a2d
--- /dev/null
+++ b/src/DocFlow.Integration/Validation/SlaValidator.cs
@@ -0,0 +1,480 @@
+using System.Diagnostics;
+using System.Text.Json;
+using System.Text.RegularExpressions;
+using Microsoft.Extensions.Logging;
+
+namespace DocFlow.Integration.Validation;
+
+/// <summary>
+/// Validates SLA compliance for API integrations.
+/// 
+/// Inspired by the 1200 Aero discovery where flight data was 2-5 hours stale
+/// instead of the contracted 30-second freshness requirement.
+/// </summary>
+public sealed class SlaValidator
+{
+    private readonly HttpClient _httpClient;
+    private readonly ILogger<SlaValidator>? _logger;
+    
+    public SlaValidator(HttpClient? httpClient = null, ILogger<SlaValidator>? logger = null)
+    {
+        _httpClient = httpClient ?? new HttpClient();
+        _logger = logger;
+    }
+    
+    /// <summary>
+    /// Validate data freshness against SLA requirements.
+    /// Samples the endpoint multiple times and analyzes data timestamps.
+    /// </summary>
+    public async Task<SlaValidationReport> ValidateDataFreshnessAsync(
+        SlaValidationRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        _logger?.LogInformation(
+            "Starting SLA validation for {Endpoint} with {SampleCount} samples, expected max age: {MaxAge}",
+            request.EndpointUrl, request.SampleCount, request.ExpectedMaxAge);
+        
+        var samples = new List<DataFreshnessSample>();
+        var errors = new List<string>();
+        
+        for (int i = 0; i < request.SampleCount; i++)
+        {
+            if (cancellationToken.IsCancellationRequested)
+                break;
+                
+            try
+            {
+                var sample = await CollectSampleAsync(request, cancellationToken);
+                samples.Add(sample);
+                
+                _logger?.LogDebug(
+                    "Sample {Index}: Data age = {Age}, Response time = {ResponseTime}ms",
+                    i + 1, sample.DataAge, sample.ResponseTime.TotalMilliseconds);
+            }
+            catch (Exception ex)
+            {
+                errors.Add($"Sample {i + 1}: {ex.Message}");
+                _logger?.LogWarning(ex, "Failed to collect sample {Index}", i + 1);
+            }
+            
+            // Wait between samples
+            if (i < request.SampleCount - 1 && request.SampleInterval > TimeSpan.Zero)
+            {
+                await Task.Delay(request.SampleInterval, cancellationToken);
+            }
+        }
+        
+        var report = AnalyzeSamples(samples, request, errors);
+        
+        _logger?.LogInformation(
+            "SLA validation complete. Verdict: {Verdict}, Compliance: {Compliance:P1}",
+            report.Verdict, report.CompliancePercentage / 100);
+        
+        return report;
+    }
+    
+    /// <summary>
+    /// Quick check - single sample to verify endpoint is returning fresh data
+    /// </summary>
+    public async Task<DataFreshnessSample> QuickCheckAsync(
+        SlaValidationRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        return await CollectSampleAsync(request, cancellationToken);
+    }
+    
+    private async Task<DataFreshnessSample> CollectSampleAsync(
+        SlaValidationRequest request,
+        CancellationToken cancellationToken)
+    {
+        var stopwatch = Stopwatch.StartNew();
+        var sampledAt = DateTime.UtcNow;
+        
+        // Make the request
+        using var httpRequest = new HttpRequestMessage(HttpMethod.Get, request.EndpointUrl);
+        
+        // Add auth headers if provided
+        if (request.AuthHeaders != null)
+        {
+            foreach (var (key, value) in request.AuthHeaders)
+            {
+                httpRequest.Headers.TryAddWithoutValidation(key, value);
+            }
+        }
+        
+        using var response = await _httpClient.SendAsync(httpRequest, cancellationToken);
+        var content = await response.Content.ReadAsStringAsync(cancellationToken);
+        
+        stopwatch.Stop();
+        
+        // Extract data timestamp from response
+        var dataTimestamp = ExtractDataTimestamp(content, request.TimestampJsonPath);
+        
+        return new DataFreshnessSample
+        {
+            SampledAt = sampledAt,
+            DataTimestamp = dataTimestamp,
+            DataAge = dataTimestamp.HasValue ? sampledAt - dataTimestamp.Value : null,
+            ResponseTime = stopwatch.Elapsed,
+            HttpStatusCode = (int)response.StatusCode,
+            Success = response.IsSuccessStatusCode
+        };
+    }
+    
+    private DateTime? ExtractDataTimestamp(string content, string? jsonPath)
+    {
+        if (string.IsNullOrEmpty(content))
+            return null;
+            
+        try
+        {
+            using var doc = JsonDocument.Parse(content);
+            
+            // If a specific JSON path is provided, use it
+            if (!string.IsNullOrEmpty(jsonPath))
+            {
+                var element = NavigateJsonPath(doc.RootElement, jsonPath);
+                if (element.HasValue)
+                {
+                    return ParseTimestamp(element.Value);
+                }
+            }
+            
+            // Otherwise, search for common timestamp field names
+            var timestampFields = new[]
+            {
+                "timestamp", "updated_at", "updatedAt", "lastUpdated", 
+                "last_updated", "modified", "modifiedAt", "modified_at",
+                "data_timestamp", "dataTimestamp", "asOf", "as_of"
+            };
+            
+            var timestamp = FindTimestampField(doc.RootElement, timestampFields);
+            if (timestamp.HasValue)
+                return timestamp;
+                
+            // Check nested data object
+            if (doc.RootElement.TryGetProperty("data", out var dataElement))
+            {
+                timestamp = FindTimestampField(dataElement, timestampFields);
+                if (timestamp.HasValue)
+                    return timestamp;
+            }
+        }
+        catch (JsonException ex)
+        {
+            _logger?.LogWarning(ex, "Failed to parse JSON response for timestamp extraction");
+        }
+        
+        return null;
+    }
+    
+    private JsonElement? NavigateJsonPath(JsonElement root, string path)
+    {
+        // Simple JSON path navigation ($.data.timestamp format)
+        var parts = path.TrimStart('$', '.').Split('.');
+        var current = root;
+        
+        foreach (var part in parts)
+        {
+            // Handle array indexing [0]
+            var match = Regex.Match(part, @"^(\w+)\[(\d+)\]$");
+            if (match.Success)
+            {
+                var propName = match.Groups[1].Value;
+                var index = int.Parse(match.Groups[2].Value);
+                
+                if (!current.TryGetProperty(propName, out var arrayElement))
+                    return null;
+                    
+                if (arrayElement.ValueKind != JsonValueKind.Array || 
+                    index >= arrayElement.GetArrayLength())
+                    return null;
+                    
+                current = arrayElement[index];
+            }
+            else
+            {
+                if (!current.TryGetProperty(part, out var nextElement))
+                    return null;
+                current = nextElement;
+            }
+        }
+        
+        return current;
+    }
+    
+    private DateTime? FindTimestampField(JsonElement element, string[] fieldNames)
+    {
+        if (element.ValueKind != JsonValueKind.Object)
+            return null;
+            
+        foreach (var fieldName in fieldNames)
+        {
+            if (element.TryGetProperty(fieldName, out var value))
+            {
+                var timestamp = ParseTimestamp(value);
+                if (timestamp.HasValue)
+                    return timestamp;
+            }
+        }
+        
+        return null;
+    }
+    
+    private DateTime? ParseTimestamp(JsonElement element)
+    {
+        return element.ValueKind switch
+        {
+            JsonValueKind.String when DateTime.TryParse(
+                element.GetString(), out var dt) => dt.ToUniversalTime(),
+                
+            JsonValueKind.Number when element.TryGetInt64(out var unix) => 
+                unix > 1_000_000_000_000 
+                    ? DateTimeOffset.FromUnixTimeMilliseconds(unix).UtcDateTime
+                    : DateTimeOffset.FromUnixTimeSeconds(unix).UtcDateTime,
+                    
+            _ => null
+        };
+    }
+    
+    private SlaValidationReport AnalyzeSamples(
+        List<DataFreshnessSample> samples,
+        SlaValidationRequest request,
+        List<string> errors)
+    {
+        var validSamples = samples.Where(s => s.Success && s.DataAge.HasValue).ToList();
+        
+        if (validSamples.Count == 0)
+        {
+            return new SlaValidationReport
+            {
+                EndpointUrl = request.EndpointUrl,
+                ExpectedMaxAge = request.ExpectedMaxAge,
+                Verdict = SlaVerdict.Unknown,
+                TotalSamples = samples.Count,
+                ValidSamples = 0,
+                Samples = samples,
+                Errors = errors,
+                Notes = ["No valid samples with extractable timestamps"]
+            };
+        }
+        
+        var dataAges = validSamples.Select(s => s.DataAge!.Value).ToList();
+        var samplesOverSla = validSamples.Count(s => s.DataAge > request.ExpectedMaxAge);
+        var compliancePercentage = (double)(validSamples.Count - samplesOverSla) / validSamples.Count * 100;
+        
+        // Determine verdict
+        var avgAge = TimeSpan.FromTicks((long)dataAges.Average(a => a.Ticks));
+        var maxAge = dataAges.Max();
+        
+        SlaVerdict verdict;
+        if (compliancePercentage >= 99)
+        {
+            verdict = SlaVerdict.Compliant;
+        }
+        else if (compliancePercentage >= 95)
+        {
+            verdict = SlaVerdict.MarginallyCompliant;
+        }
+        else if (avgAge > request.ExpectedMaxAge * 10)
+        {
+            // Data is 10x older than expected - severe violation (like 1200 Aero!)
+            verdict = SlaVerdict.SevereViolation;
+        }
+        else
+        {
+            verdict = SlaVerdict.MinorViolation;
+        }
+        
+        var notes = new List<string>();
+        
+        if (verdict == SlaVerdict.SevereViolation)
+        {
+            notes.Add($"⚠️ SEVERE: Average data age ({avgAge}) is significantly higher than SLA ({request.ExpectedMaxAge})");
+            notes.Add($"This may indicate stale data caching or upstream data delays.");
+        }
+        
+        if (maxAge > request.ExpectedMaxAge * 2)
+        {
+            notes.Add($"Maximum observed data age ({maxAge}) is more than 2x the SLA requirement.");
+        }
+        
+        return new SlaValidationReport
+        {
+            EndpointUrl = request.EndpointUrl,
+            ExpectedMaxAge = request.ExpectedMaxAge,
+            ActualAverageAge = avgAge,
+            ActualMaxAge = maxAge,
+            ActualMinAge = dataAges.Min(),
+            SamplesOverSla = samplesOverSla,
+            TotalSamples = samples.Count,
+            ValidSamples = validSamples.Count,
+            CompliancePercentage = compliancePercentage,
+            Verdict = verdict,
+            Samples = samples,
+            Errors = errors,
+            Notes = notes,
+            
+            // Response time stats
+            AverageResponseTime = TimeSpan.FromMilliseconds(
+                validSamples.Average(s => s.ResponseTime.TotalMilliseconds)),
+            MaxResponseTime = validSamples.Max(s => s.ResponseTime),
+            MinResponseTime = validSamples.Min(s => s.ResponseTime)
+        };
+    }
+}
+
+/// <summary>
+/// Request for SLA validation
+/// </summary>
+public sealed class SlaValidationRequest
+{
+    /// <summary>
+    /// The endpoint URL to validate
+    /// </summary>
+    public required string EndpointUrl { get; init; }
+    
+    /// <summary>
+    /// Expected maximum data age per SLA (e.g., 30 seconds)
+    /// </summary>
+    public required TimeSpan ExpectedMaxAge { get; init; }
+    
+    /// <summary>
+    /// Number of samples to collect
+    /// </summary>
+    public int SampleCount { get; init; } = 10;
+    
+    /// <summary>
+    /// Time to wait between samples
+    /// </summary>
+    public TimeSpan SampleInterval { get; init; } = TimeSpan.FromSeconds(5);
+    
+    /// <summary>
+    /// JSON path to the timestamp field (e.g., "$.data.updated_at")
+    /// If not specified, common timestamp fields will be searched
+    /// </summary>
+    public string? TimestampJsonPath { get; init; }
+    
+    /// <summary>
+    /// Authentication headers to include
+    /// </summary>
+    public Dictionary<string, string>? AuthHeaders { get; init; }
+}
+
+/// <summary>
+/// Individual sample result
+/// </summary>
+public sealed class DataFreshnessSample
+{
+    /// <summary>
+    /// When this sample was taken
+    /// </summary>
+    public DateTime SampledAt { get; init; }
+    
+    /// <summary>
+    /// Timestamp extracted from the data
+    /// </summary>
+    public DateTime? DataTimestamp { get; init; }
+    
+    /// <summary>
+    /// Age of the data at sample time
+    /// </summary>
+    public TimeSpan? DataAge { get; init; }
+    
+    /// <summary>
+    /// How long the HTTP request took
+    /// </summary>
+    public TimeSpan ResponseTime { get; init; }
+    
+    /// <summary>
+    /// HTTP status code
+    /// </summary>
+    public int HttpStatusCode { get; init; }
+    
+    /// <summary>
+    /// Was the request successful?
+    /// </summary>
+    public bool Success { get; init; }
+}
+
+/// <summary>
+/// Complete SLA validation report
+/// </summary>
+public sealed class SlaValidationReport
+{
+    public required string EndpointUrl { get; init; }
+    public TimeSpan ExpectedMaxAge { get; init; }
+    
+    // Data freshness stats
+    public TimeSpan? ActualAverageAge { get; init; }
+    public TimeSpan? ActualMaxAge { get; init; }
+    public TimeSpan? ActualMinAge { get; init; }
+    
+    // Compliance stats
+    public int SamplesOverSla { get; init; }
+    public int TotalSamples { get; init; }
+    public int ValidSamples { get; init; }
+    public double CompliancePercentage { get; init; }
+    
+    // Verdict
+    public SlaVerdict Verdict { get; init; }
+    
+    // Response time stats
+    public TimeSpan? AverageResponseTime { get; init; }
+    public TimeSpan? MaxResponseTime { get; init; }
+    public TimeSpan? MinResponseTime { get; init; }
+    
+    // Details
+    public List<DataFreshnessSample> Samples { get; init; } = [];
+    public List<string> Errors { get; init; } = [];
+    public List<string> Notes { get; init; } = [];
+    
+    /// <summary>
+    /// Generate a summary for display
+    /// </summary>
+    public string GetSummary()
+    {
+        var emoji = Verdict switch
+        {
+            SlaVerdict.Compliant => "✅",
+            SlaVerdict.MarginallyCompliant => "⚠️",
+            SlaVerdict.MinorViolation => "❌",
+            SlaVerdict.SevereViolation => "🚨",
+            _ => "❓"
+        };
+        
+        return $"""
+            {emoji} SLA Validation: {Verdict}
+            
+            Endpoint: {EndpointUrl}
+            Expected Max Age: {ExpectedMaxAge}
+            Actual Average Age: {ActualAverageAge?.ToString() ?? "N/A"}
+            Actual Max Age: {ActualMaxAge?.ToString() ?? "N/A"}
+            
+            Compliance: {CompliancePercentage:F1}% ({ValidSamples - SamplesOverSla}/{ValidSamples} samples within SLA)
+            
+            Response Time: avg {AverageResponseTime?.TotalMilliseconds:F0}ms, max {MaxResponseTime?.TotalMilliseconds:F0}ms
+            """;
+    }
+}
+
+/// <summary>
+/// SLA compliance verdict
+/// </summary>
+public enum SlaVerdict
+{
+    /// <summary>Could not determine compliance</summary>
+    Unknown,
+    
+    /// <summary>All samples within SLA requirements</summary>
+    Compliant,
+    
+    /// <summary>Minor violations but generally compliant (95%+)</summary>
+    MarginallyCompliant,
+    
+    /// <summary>Some samples exceed SLA</summary>
+    MinorViolation,
+    
+    /// <summary>Data is significantly older than SLA (like 1200 Aero!)</summary>
+    SevereViolation
+}
diff --git a/src/DocFlow.Vision/WhiteboardScanner.cs b/src/DocFlow.Vision/WhiteboardScanner.cs
new file mode 100644
index 0000000..af50a61
--- /dev/null
+++ b/src/DocFlow.Vision/WhiteboardScanner.cs
@@ -0,0 +1,515 @@
+using System.Diagnostics;
+using System.Text.RegularExpressions;
+using DocFlow.AI.Providers;
+using DocFlow.Core.Abstractions;
+using DocFlow.Core.CanonicalModel;
+using Microsoft.Extensions.Logging;
+
+namespace DocFlow.Vision;
+
+/// <summary>
+/// Whiteboard scanner implementation using Claude's vision API.
+/// Analyzes whiteboard photos and extracts Mermaid diagrams.
+/// </summary>
+public sealed partial class WhiteboardScanner : IWhiteboardScanner
+{
+    private readonly IAiProvider _aiProvider;
+    private readonly IModelParser? _mermaidParser;
+    private readonly ILogger<WhiteboardScanner>? _logger;
+
+    // Supported image formats
+    private static readonly HashSet<string> SupportedExtensions = new(StringComparer.OrdinalIgnoreCase)
+    {
+        ".jpg", ".jpeg", ".png", ".gif", ".webp", ".heic"
+    };
+
+    private const string SystemPrompt = """
+        You are an expert at analyzing software architecture diagrams and converting them to Mermaid syntax.
+        You have deep knowledge of UML, DDD (Domain-Driven Design), and software modeling patterns.
+        Your task is to accurately extract diagram elements and relationships from whiteboard photos.
+        """;
+
+    private const string DiagramAnalysisPrompt = """
+        Analyze this whiteboard/sketch image of a software diagram.
+
+        1. Identify the diagram type (UML class diagram, flowchart, ER diagram, sequence diagram, etc.)
+        2. Extract all entities/classes with their properties and methods
+        3. Identify relationships between entities (inheritance, composition, association, dependency)
+        4. Note any stereotypes or annotations visible (<<interface>>, <<abstract>>, <<aggregate root>>, etc.)
+
+        Return ONLY valid Mermaid classDiagram syntax. No explanations, just the Mermaid code.
+
+        Use proper Mermaid syntax:
+        - Start with: classDiagram
+        - Classes: class ClassName { }
+        - Properties: +propertyName : Type (public), -propertyName : Type (private), #propertyName : Type (protected)
+        - Methods: +methodName() ReturnType
+        - Stereotypes: class ClassName { <<stereotype>> }
+        - Inheritance: Parent <|-- Child
+        - Composition: Container *-- Part
+        - Aggregation: Container o-- Part
+        - Association: ClassA --> ClassB
+        - Dependency: ClassA ..> ClassB
+
+        If you can't identify something clearly, make your best guess based on context.
+        If there are multiple interpretations, choose the most common software modeling interpretation.
+
+        IMPORTANT: Output ONLY the Mermaid code, no markdown code blocks, no explanations.
+        """;
+
+    private const string DiagramTypePrompt = """
+        Quickly analyze this image and determine what type of software diagram it shows.
+
+        Respond with ONLY a JSON object in this exact format:
+        {"type": "CLASS_DIAGRAM", "confidence": 0.85, "alternativeTypes": [{"type": "ER_DIAGRAM", "confidence": 0.10}]}
+
+        Valid types: CLASS_DIAGRAM, SEQUENCE_DIAGRAM, FLOWCHART, ER_DIAGRAM, STATE_DIAGRAM,
+                     ACTIVITY_DIAGRAM, USE_CASE_DIAGRAM, COMPONENT_DIAGRAM, ARCHITECTURE_DIAGRAM,
+                     MIND_MAP, DATA_FLOW_DIAGRAM, NETWORK_DIAGRAM, INFORMAL_SKETCH, UNKNOWN
+
+        Output ONLY the JSON, nothing else.
+        """;
+
+    /// <summary>
+    /// Create a WhiteboardScanner with default Claude provider.
+    /// </summary>
+    public WhiteboardScanner(ILogger<WhiteboardScanner>? logger = null)
+        : this(new ClaudeProvider(), null, logger)
+    {
+    }
+
+    /// <summary>
+    /// Create a WhiteboardScanner with explicit AI provider.
+    /// </summary>
+    public WhiteboardScanner(
+        IAiProvider aiProvider,
+        IModelParser? mermaidParser = null,
+        ILogger<WhiteboardScanner>? logger = null)
+    {
+        _aiProvider = aiProvider;
+        _mermaidParser = mermaidParser;
+        _logger = logger;
+    }
+
+    public async Task<WhiteboardScanResult> ScanAsync(
+        WhiteboardInput input,
+        WhiteboardScanOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        options ??= new WhiteboardScanOptions();
+        var totalStopwatch = Stopwatch.StartNew();
+        var errors = new List<ScanError>();
+        var warnings = new List<ScanWarning>();
+
+        try
+        {
+            // Load the image data
+            var (imageData, mimeType) = await LoadImageAsync(input, cancellationToken);
+
+            if (imageData == null || imageData.Length == 0)
+            {
+                return CreateFailedResult("No image data provided", errors);
+            }
+
+            _logger?.LogInformation("Scanning whiteboard image ({Size} bytes)", imageData.Length);
+
+            // Detect diagram type first
+            var detectionStopwatch = Stopwatch.StartNew();
+            var diagramType = await DetectDiagramTypeAsync(imageData, cancellationToken);
+            detectionStopwatch.Stop();
+
+            _logger?.LogInformation(
+                "Detected diagram type: {Type} (confidence: {Confidence:P0})",
+                diagramType.PrimaryType, diagramType.Confidence);
+
+            // Build the prompt with any context hints
+            var prompt = DiagramAnalysisPrompt;
+            if (!string.IsNullOrEmpty(input.ContextHint))
+            {
+                prompt = $"Context: {input.ContextHint}\n\n{prompt}";
+            }
+
+            // Call the AI provider to analyze the image
+            var analysisStopwatch = Stopwatch.StartNew();
+            var analysisResult = await _aiProvider.AnalyzeImageAsync(new ImageAnalysisRequest
+            {
+                ImageData = imageData,
+                MimeType = mimeType,
+                Prompt = prompt,
+                SystemPrompt = SystemPrompt,
+                OutputFormat = OutputFormat.Mermaid,
+                MaxTokens = 4096,
+                Temperature = 0.1 // Low temperature for more deterministic output
+            }, cancellationToken);
+            analysisStopwatch.Stop();
+
+            if (!analysisResult.Success)
+            {
+                _logger?.LogError("AI analysis failed: {Error}", analysisResult.ErrorMessage);
+                errors.Add(new ScanError
+                {
+                    Code = "AI_ANALYSIS_FAILED",
+                    Message = analysisResult.ErrorMessage ?? "Unknown AI error"
+                });
+                return CreateFailedResult(analysisResult.ErrorMessage ?? "AI analysis failed", errors);
+            }
+
+            var mermaidContent = CleanMermaidOutput(analysisResult.Content ?? string.Empty);
+            _logger?.LogDebug("Generated Mermaid:\n{Mermaid}", mermaidContent);
+
+            if (string.IsNullOrWhiteSpace(mermaidContent))
+            {
+                errors.Add(new ScanError
+                {
+                    Code = "EMPTY_RESULT",
+                    Message = "AI returned empty diagram content"
+                });
+                return CreateFailedResult("No diagram content extracted", errors);
+            }
+
+            // Parse the Mermaid into a SemanticModel
+            SemanticModel model;
+            if (_mermaidParser != null)
+            {
+                var parseResult = await _mermaidParser.ParseAsync(
+                    ParserInput.FromContent(mermaidContent),
+                    cancellationToken: cancellationToken);
+
+                if (!parseResult.Success)
+                {
+                    // Include warnings but continue if we have partial results
+                    foreach (var error in parseResult.Errors)
+                    {
+                        warnings.Add(new ScanWarning
+                        {
+                            Code = "PARSE_WARNING",
+                            Message = $"Mermaid parse issue: {error.Message}"
+                        });
+                    }
+                }
+
+                model = parseResult.Model;
+            }
+            else
+            {
+                // Create a basic model from the Mermaid content
+                model = CreateBasicModelFromMermaid(mermaidContent);
+            }
+
+            // Update model provenance
+            model.Provenance = new ModelProvenance
+            {
+                SourceFormat = "Whiteboard",
+                CreatedAt = DateTime.UtcNow,
+                SourceFiles = input.FilePath != null ? [input.FilePath] : [],
+                Notes = [$"Detected as {diagramType.PrimaryType} with {diagramType.Confidence:P0} confidence"]
+            };
+
+            totalStopwatch.Stop();
+
+            // Create the generate result for Mermaid output
+            var generatedOutputs = new Dictionary<string, GenerateResult>
+            {
+                ["Mermaid"] = new GenerateResult
+                {
+                    Success = true,
+                    Content = mermaidContent
+                }
+            };
+
+            return new WhiteboardScanResult
+            {
+                Model = model,
+                Success = true,
+                DetectedDiagramType = diagramType.PrimaryType,
+                OverallConfidence = diagramType.Confidence,
+                GeneratedOutputs = generatedOutputs,
+                Errors = errors,
+                Warnings = warnings,
+                Statistics = new ScanStatistics
+                {
+                    EntitiesCreated = model.Entities.Count,
+                    RelationshipsCreated = model.Relationships.Count,
+                    DetectionDuration = detectionStopwatch.Elapsed,
+                    AnalysisDuration = analysisStopwatch.Elapsed,
+                    TotalDuration = totalStopwatch.Elapsed
+                }
+            };
+        }
+        catch (OperationCanceledException)
+        {
+            throw;
+        }
+        catch (Exception ex)
+        {
+            _logger?.LogError(ex, "Error scanning whiteboard");
+            errors.Add(new ScanError
+            {
+                Code = "SCAN_EXCEPTION",
+                Message = ex.Message
+            });
+            return CreateFailedResult(ex.Message, errors);
+        }
+    }
+
+    public async Task<DiagramTypeDetection> DetectDiagramTypeAsync(
+        byte[] imageData,
+        CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            var result = await _aiProvider.AnalyzeImageAsync(new ImageAnalysisRequest
+            {
+                ImageData = imageData,
+                MimeType = "image/jpeg",
+                Prompt = DiagramTypePrompt,
+                MaxTokens = 256,
+                Temperature = 0.1
+            }, cancellationToken);
+
+            if (!result.Success || string.IsNullOrEmpty(result.Content))
+            {
+                return new DiagramTypeDetection
+                {
+                    PrimaryType = DiagramType.Unknown,
+                    Confidence = 0.0
+                };
+            }
+
+            // Parse the JSON response
+            return ParseDiagramTypeResponse(result.Content);
+        }
+        catch (Exception ex)
+        {
+            _logger?.LogWarning(ex, "Failed to detect diagram type, defaulting to Unknown");
+            return new DiagramTypeDetection
+            {
+                PrimaryType = DiagramType.Unknown,
+                Confidence = 0.0
+            };
+        }
+    }
+
+    private static async Task<(byte[]? Data, string MimeType)> LoadImageAsync(
+        WhiteboardInput input,
+        CancellationToken cancellationToken)
+    {
+        if (input.ImageData != null)
+        {
+            return (input.ImageData, "image/jpeg");
+        }
+
+        if (input.ImageStream != null)
+        {
+            using var ms = new MemoryStream();
+            await input.ImageStream.CopyToAsync(ms, cancellationToken);
+            return (ms.ToArray(), "image/jpeg");
+        }
+
+        if (!string.IsNullOrEmpty(input.FilePath))
+        {
+            if (!File.Exists(input.FilePath))
+            {
+                throw new FileNotFoundException($"Image file not found: {input.FilePath}");
+            }
+
+            var extension = Path.GetExtension(input.FilePath).ToLowerInvariant();
+            if (!SupportedExtensions.Contains(extension))
+            {
+                throw new NotSupportedException($"Unsupported image format: {extension}");
+            }
+
+            var data = await File.ReadAllBytesAsync(input.FilePath, cancellationToken);
+            var mimeType = extension switch
+            {
+                ".png" => "image/png",
+                ".gif" => "image/gif",
+                ".webp" => "image/webp",
+                _ => "image/jpeg"
+            };
+
+            return (data, mimeType);
+        }
+
+        return (null, "image/jpeg");
+    }
+
+    private static string CleanMermaidOutput(string content)
+    {
+        if (string.IsNullOrWhiteSpace(content))
+            return string.Empty;
+
+        // Remove markdown code blocks if present
+        var cleaned = content.Trim();
+
+        // Remove ```mermaid ... ``` wrapper
+        if (cleaned.StartsWith("```mermaid", StringComparison.OrdinalIgnoreCase))
+        {
+            var endIndex = cleaned.IndexOf('\n');
+            if (endIndex > 0)
+                cleaned = cleaned[(endIndex + 1)..];
+        }
+        else if (cleaned.StartsWith("```", StringComparison.Ordinal))
+        {
+            var endIndex = cleaned.IndexOf('\n');
+            if (endIndex > 0)
+                cleaned = cleaned[(endIndex + 1)..];
+        }
+
+        // Remove trailing ``` if present
+        if (cleaned.EndsWith("```", StringComparison.Ordinal))
+        {
+            cleaned = cleaned[..^3];
+        }
+
+        // Ensure it starts with classDiagram
+        cleaned = cleaned.Trim();
+        if (!cleaned.StartsWith("classDiagram", StringComparison.OrdinalIgnoreCase))
+        {
+            cleaned = "classDiagram\n" + cleaned;
+        }
+
+        return cleaned.Trim();
+    }
+
+    private DiagramTypeDetection ParseDiagramTypeResponse(string content)
+    {
+        try
+        {
+            // Extract JSON from the response
+            var jsonMatch = JsonRegex().Match(content);
+            if (!jsonMatch.Success)
+            {
+                return new DiagramTypeDetection
+                {
+                    PrimaryType = DiagramType.Unknown,
+                    Confidence = 0.0
+                };
+            }
+
+            var json = jsonMatch.Value;
+
+            // Simple JSON parsing for the type field
+            var typeMatch = TypeRegex().Match(json);
+            var confidenceMatch = ConfidenceRegex().Match(json);
+
+            var typeString = typeMatch.Success ? typeMatch.Groups[1].Value : "UNKNOWN";
+            var confidence = confidenceMatch.Success
+                ? double.TryParse(confidenceMatch.Groups[1].Value, out var c) ? c : 0.5
+                : 0.5;
+
+            var primaryType = MapStringToDiagramType(typeString);
+
+            // Parse alternatives if present
+            var alternatives = new List<DiagramTypeCandidate>();
+            var alternativesMatch = AlternativesRegex().Match(json);
+            if (alternativesMatch.Success)
+            {
+                var altContent = alternativesMatch.Groups[1].Value;
+                var altTypeMatches = TypeRegex().Matches(altContent);
+                var altConfMatches = ConfidenceRegex().Matches(altContent);
+
+                for (var i = 0; i < Math.Min(altTypeMatches.Count, altConfMatches.Count); i++)
+                {
+                    alternatives.Add(new DiagramTypeCandidate
+                    {
+                        Type = MapStringToDiagramType(altTypeMatches[i].Groups[1].Value),
+                        Confidence = double.TryParse(altConfMatches[i].Groups[1].Value, out var altConf) ? altConf : 0.0
+                    });
+                }
+            }
+
+            return new DiagramTypeDetection
+            {
+                PrimaryType = primaryType,
+                Confidence = confidence,
+                Alternatives = alternatives
+            };
+        }
+        catch (Exception ex)
+        {
+            _logger?.LogWarning(ex, "Failed to parse diagram type response: {Content}", content);
+            return new DiagramTypeDetection
+            {
+                PrimaryType = DiagramType.Unknown,
+                Confidence = 0.0
+            };
+        }
+    }
+
+    private static DiagramType MapStringToDiagramType(string typeString) => typeString.ToUpperInvariant() switch
+    {
+        "CLASS_DIAGRAM" => DiagramType.ClassDiagram,
+        "SEQUENCE_DIAGRAM" => DiagramType.SequenceDiagram,
+        "FLOWCHART" => DiagramType.Flowchart,
+        "ER_DIAGRAM" or "ENTITY_RELATIONSHIP_DIAGRAM" => DiagramType.EntityRelationshipDiagram,
+        "STATE_DIAGRAM" => DiagramType.StateDiagram,
+        "ACTIVITY_DIAGRAM" => DiagramType.ActivityDiagram,
+        "USE_CASE_DIAGRAM" => DiagramType.UseCaseDiagram,
+        "COMPONENT_DIAGRAM" => DiagramType.ComponentDiagram,
+        "DEPLOYMENT_DIAGRAM" => DiagramType.DeploymentDiagram,
+        "ARCHITECTURE_DIAGRAM" => DiagramType.ArchitectureDiagram,
+        "NETWORK_DIAGRAM" => DiagramType.NetworkDiagram,
+        "MIND_MAP" => DiagramType.MindMap,
+        "DATA_FLOW_DIAGRAM" => DiagramType.DataFlowDiagram,
+        "INFORMAL_SKETCH" => DiagramType.InformalSketch,
+        _ => DiagramType.Unknown
+    };
+
+    private static SemanticModel CreateBasicModelFromMermaid(string mermaidContent)
+    {
+        // Extract class names from the Mermaid content
+        var model = new SemanticModel { Name = "WhiteboardDiagram" };
+
+        var classMatches = ClassNameRegex().Matches(mermaidContent);
+        var seenClasses = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+
+        foreach (Match match in classMatches)
+        {
+            var className = match.Groups[1].Value;
+            if (seenClasses.Add(className))
+            {
+                model.CreateEntity(className, EntityClassification.Class);
+            }
+        }
+
+        return model;
+    }
+
+    private static WhiteboardScanResult CreateFailedResult(string errorMessage, List<ScanError> errors)
+    {
+        if (errors.Count == 0)
+        {
+            errors.Add(new ScanError
+            {
+                Code = "SCAN_FAILED",
+                Message = errorMessage
+            });
+        }
+
+        return new WhiteboardScanResult
+        {
+            Model = new SemanticModel { Name = "Error" },
+            Success = false,
+            DetectedDiagramType = DiagramType.Unknown,
+            OverallConfidence = 0.0,
+            Errors = errors
+        };
+    }
+
+    // Compiled regex patterns for performance
+    [GeneratedRegex(@"\{[^{}]*\}")]
+    private static partial Regex JsonRegex();
+
+    [GeneratedRegex(@"""type""\s*:\s*""([^""]+)""")]
+    private static partial Regex TypeRegex();
+
+    [GeneratedRegex(@"""confidence""\s*:\s*([0-9.]+)")]
+    private static partial Regex ConfidenceRegex();
+
+    [GeneratedRegex(@"""alternativeTypes""\s*:\s*\[(.*?)\]", RegexOptions.Singleline)]
+    private static partial Regex AlternativesRegex();
+
+    [GeneratedRegex(@"class\s+(\w+)")]
+    private static partial Regex ClassNameRegex();
+}
diff --git a/tests/DocFlow.CodeAnalysis.Tests/CSharp/CSharpModelParserTests.cs b/tests/DocFlow.CodeAnalysis.Tests/CSharp/CSharpModelParserTests.cs
new file mode 100644
index 0000000..c1eaed6
--- /dev/null
+++ b/tests/DocFlow.CodeAnalysis.Tests/CSharp/CSharpModelParserTests.cs
@@ -0,0 +1,381 @@
+using DocFlow.CodeAnalysis.CSharp;
+using DocFlow.Core.Abstractions;
+using DocFlow.Core.CanonicalModel;
+using Xunit;
+
+namespace DocFlow.CodeAnalysis.Tests.CSharp;
+
+public class CSharpModelParserTests
+{
+    private readonly CSharpModelParser _parser = new();
+
+    [Fact]
+    public async Task ParseAsync_SimpleClass_ExtractsNameAndProperties()
+    {
+        var code = """
+            public class Customer
+            {
+                public string Name { get; set; }
+                public int Age { get; set; }
+            }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(code));
+
+        Assert.True(result.Success);
+        Assert.Single(result.Model.Entities);
+
+        var entity = result.Model.Entities.Values.First();
+        Assert.Equal("Customer", entity.Name);
+        Assert.Equal(2, entity.Properties.Count);
+        Assert.Contains(entity.Properties, p => p.Name == "Name" && p.Type.Name == "string");
+        Assert.Contains(entity.Properties, p => p.Name == "Age" && p.Type.Name == "int");
+    }
+
+    [Fact]
+    public async Task ParseAsync_Record_ClassifiedAsValueObject()
+    {
+        var code = """
+            public record Address(string Street, string City, string PostalCode);
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(code));
+
+        Assert.True(result.Success);
+        var entity = result.Model.Entities.Values.First();
+        Assert.Equal("Address", entity.Name);
+        Assert.Equal(EntityClassification.ValueObject, entity.Classification);
+        Assert.Contains(entity.Stereotypes, s => s == "record");
+    }
+
+    [Fact]
+    public async Task ParseAsync_ClassWithIdAndCollection_ClassifiedAsAggregateRoot()
+    {
+        var code = """
+            public class Order
+            {
+                public Guid Id { get; init; }
+                public ICollection<LineItem> LineItems { get; init; }
+            }
+
+            public class LineItem
+            {
+                public Guid Id { get; init; }
+            }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(code));
+
+        Assert.True(result.Success);
+        var order = result.Model.Entities.Values.First(e => e.Name == "Order");
+        Assert.Equal(EntityClassification.AggregateRoot, order.Classification);
+    }
+
+    [Fact]
+    public async Task ParseAsync_ClassWithIdOnly_ClassifiedAsEntity()
+    {
+        var code = """
+            public class Product
+            {
+                public Guid Id { get; init; }
+                public string Name { get; set; }
+            }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(code));
+
+        Assert.True(result.Success);
+        var entity = result.Model.Entities.Values.First();
+        Assert.Equal(EntityClassification.Entity, entity.Classification);
+    }
+
+    [Fact]
+    public async Task ParseAsync_Interface_ClassifiedAsInterface()
+    {
+        var code = """
+            public interface IOrderRepository
+            {
+                Task<Order> GetByIdAsync(Guid id);
+            }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(code));
+
+        Assert.True(result.Success);
+        var entity = result.Model.Entities.Values.First();
+        Assert.Equal("IOrderRepository", entity.Name);
+        Assert.Equal(EntityClassification.Interface, entity.Classification);
+    }
+
+    [Fact]
+    public async Task ParseAsync_Enum_ClassifiedAsEnum()
+    {
+        var code = """
+            public enum OrderStatus
+            {
+                Draft,
+                Confirmed,
+                Shipped
+            }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(code));
+
+        Assert.True(result.Success);
+        var entity = result.Model.Entities.Values.First();
+        Assert.Equal("OrderStatus", entity.Name);
+        Assert.Equal(EntityClassification.Enum, entity.Classification);
+        Assert.Equal(3, entity.Properties.Count);
+    }
+
+    [Fact]
+    public async Task ParseAsync_Inheritance_CreatesRelationship()
+    {
+        var code = """
+            public class Animal { }
+            public class Dog : Animal { }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(code));
+
+        Assert.True(result.Success);
+        Assert.Equal(2, result.Model.Entities.Count);
+
+        var inheritanceRel = result.Model.Relationships
+            .FirstOrDefault(r => r.Type == RelationshipType.Inheritance);
+        Assert.NotNull(inheritanceRel);
+
+        var dog = result.Model.Entities.Values.First(e => e.Name == "Dog");
+        var animal = result.Model.Entities.Values.First(e => e.Name == "Animal");
+        Assert.Equal(dog.Id, inheritanceRel.SourceEntityId);
+        Assert.Equal(animal.Id, inheritanceRel.TargetEntityId);
+    }
+
+    [Fact]
+    public async Task ParseAsync_InterfaceImplementation_CreatesRelationship()
+    {
+        var code = """
+            public interface IService { }
+            public class MyService : IService { }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(code));
+
+        Assert.True(result.Success);
+        var implRel = result.Model.Relationships
+            .FirstOrDefault(r => r.Type == RelationshipType.Implementation);
+        Assert.NotNull(implRel);
+    }
+
+    [Fact]
+    public async Task ParseAsync_CollectionProperty_CreatesCompositionRelationship()
+    {
+        var code = """
+            public class Order
+            {
+                public Guid Id { get; init; }
+                public ICollection<LineItem> Items { get; init; }
+            }
+
+            public class LineItem
+            {
+                public Guid Id { get; init; }
+            }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(code));
+
+        Assert.True(result.Success);
+        var compositionRel = result.Model.Relationships
+            .FirstOrDefault(r => r.Type == RelationshipType.Composition);
+        Assert.NotNull(compositionRel);
+
+        var order = result.Model.Entities.Values.First(e => e.Name == "Order");
+        Assert.Equal(order.Id, compositionRel.SourceEntityId);
+    }
+
+    [Fact]
+    public async Task ParseAsync_ReferenceProperty_CreatesAssociationRelationship()
+    {
+        var code = """
+            public class Order
+            {
+                public Guid Id { get; init; }
+                public Customer Customer { get; set; }
+            }
+
+            public class Customer
+            {
+                public Guid Id { get; init; }
+            }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(code));
+
+        Assert.True(result.Success);
+        var associationRel = result.Model.Relationships
+            .FirstOrDefault(r => r.Type == RelationshipType.Association);
+        Assert.NotNull(associationRel);
+    }
+
+    [Fact]
+    public async Task ParseAsync_Visibility_ParsedCorrectly()
+    {
+        var code = """
+            public class Example
+            {
+                public string PublicProp { get; set; }
+                private string PrivateProp { get; set; }
+                protected string ProtectedProp { get; set; }
+                internal string InternalProp { get; set; }
+            }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(code));
+
+        Assert.True(result.Success);
+        var entity = result.Model.Entities.Values.First();
+
+        Assert.Contains(entity.Properties, p => p.Name == "PublicProp" && p.Visibility == Visibility.Public);
+        Assert.Contains(entity.Properties, p => p.Name == "PrivateProp" && p.Visibility == Visibility.Private);
+        Assert.Contains(entity.Properties, p => p.Name == "ProtectedProp" && p.Visibility == Visibility.Protected);
+        Assert.Contains(entity.Properties, p => p.Name == "InternalProp" && p.Visibility == Visibility.Internal);
+    }
+
+    [Fact]
+    public async Task ParseAsync_RequiredAttribute_DetectedAsRequired()
+    {
+        var code = """
+            using System.ComponentModel.DataAnnotations;
+
+            public class Customer
+            {
+                [Required]
+                public string Name { get; set; }
+            }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(code));
+
+        Assert.True(result.Success);
+        var entity = result.Model.Entities.Values.First();
+        var nameProp = entity.Properties.First(p => p.Name == "Name");
+        Assert.True(nameProp.IsRequired);
+    }
+
+    [Fact]
+    public async Task ParseAsync_RequiredKeyword_DetectedAsRequired()
+    {
+        var code = """
+            public class Customer
+            {
+                public required string Name { get; set; }
+            }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(code));
+
+        Assert.True(result.Success);
+        var entity = result.Model.Entities.Values.First();
+        var nameProp = entity.Properties.First(p => p.Name == "Name");
+        Assert.True(nameProp.IsRequired);
+    }
+
+    [Fact]
+    public async Task ParseAsync_Methods_ExtractedCorrectly()
+    {
+        var code = """
+            public class Calculator
+            {
+                public int Add(int a, int b) => a + b;
+                public static double Multiply(double x, double y) => x * y;
+            }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(code));
+
+        Assert.True(result.Success);
+        var entity = result.Model.Entities.Values.First();
+
+        Assert.Contains(entity.Operations, m => m.Name == "Add" && !m.IsStatic);
+        Assert.Contains(entity.Operations, m => m.Name == "Multiply" && m.IsStatic);
+    }
+
+    [Fact]
+    public async Task ParseAsync_IdProperty_HasIdentitySemantics()
+    {
+        var code = """
+            public class Entity
+            {
+                public Guid Id { get; init; }
+            }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(code));
+
+        Assert.True(result.Success);
+        var entity = result.Model.Entities.Values.First();
+        var idProp = entity.Properties.First(p => p.Name == "Id");
+        Assert.Equal(PropertySemantics.Identity, idProp.Semantics);
+    }
+
+    [Fact]
+    public async Task ParseAsync_GenericCollection_ParsedCorrectly()
+    {
+        var code = """
+            public class Container
+            {
+                public List<string> Items { get; set; }
+            }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(code));
+
+        Assert.True(result.Success);
+        var entity = result.Model.Entities.Values.First();
+        var prop = entity.Properties.First();
+
+        Assert.True(prop.Type.IsCollection);
+        Assert.Single(prop.Type.GenericArguments);
+        Assert.Equal("string", prop.Type.GenericArguments[0].Name);
+    }
+
+    [Fact]
+    public async Task ParseAsync_NullableType_ParsedCorrectly()
+    {
+        var code = """
+            public class Example
+            {
+                public DateTime? OptionalDate { get; set; }
+            }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(code));
+
+        Assert.True(result.Success);
+        var entity = result.Model.Entities.Values.First();
+        var prop = entity.Properties.First();
+
+        Assert.True(prop.Type.IsNullable);
+    }
+
+    [Fact]
+    public void CanParse_CSharpContent_ReturnsTrue()
+    {
+        var input = ParserInput.FromContent("public class Test { }");
+        Assert.True(_parser.CanParse(input));
+    }
+
+    [Fact]
+    public void CanParse_CsFilePath_ReturnsTrue()
+    {
+        var input = ParserInput.FromFile("test.cs");
+        Assert.True(_parser.CanParse(input));
+    }
+
+    [Fact]
+    public void SupportedExtensions_ContainsCsExtension()
+    {
+        Assert.Contains(".cs", _parser.SupportedExtensions);
+    }
+}
diff --git a/tests/DocFlow.CodeAnalysis.Tests/DocFlow.CodeAnalysis.Tests.csproj b/tests/DocFlow.CodeAnalysis.Tests/DocFlow.CodeAnalysis.Tests.csproj
new file mode 100644
index 0000000..f115649
--- /dev/null
+++ b/tests/DocFlow.CodeAnalysis.Tests/DocFlow.CodeAnalysis.Tests.csproj
@@ -0,0 +1,28 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+    <IsTestProject>true</IsTestProject>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
+    <PackageReference Include="xunit" Version="2.6.2" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.5.4">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+    <PackageReference Include="coverlet.collector" Version="6.0.0">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\DocFlow.CodeAnalysis\DocFlow.CodeAnalysis.csproj" />
+  </ItemGroup>
+
+</Project>
diff --git a/tests/DocFlow.CodeGen.Tests/CSharp/CSharpModelGeneratorTests.cs b/tests/DocFlow.CodeGen.Tests/CSharp/CSharpModelGeneratorTests.cs
new file mode 100644
index 0000000..fd83648
--- /dev/null
+++ b/tests/DocFlow.CodeGen.Tests/CSharp/CSharpModelGeneratorTests.cs
@@ -0,0 +1,348 @@
+using DocFlow.CodeGen.CSharp;
+using DocFlow.Core.Abstractions;
+using DocFlow.Core.CanonicalModel;
+using Xunit;
+
+namespace DocFlow.CodeGen.Tests.CSharp;
+
+public class CSharpModelGeneratorTests
+{
+    private readonly CSharpModelGenerator _generator = new();
+
+    [Fact]
+    public async Task GenerateAsync_Entity_GeneratesClass()
+    {
+        var model = new SemanticModel();
+        var entity = model.CreateEntity("Customer", EntityClassification.Entity);
+        entity.Properties.Add(new SemanticProperty
+        {
+            Name = "Id",
+            Type = SemanticType.Guid,
+            Visibility = Visibility.Public,
+            Semantics = PropertySemantics.Identity
+        });
+        entity.Properties.Add(new SemanticProperty
+        {
+            Name = "Name",
+            Type = SemanticType.String,
+            Visibility = Visibility.Public
+        });
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("public class Customer", result.Content);
+        Assert.Contains("public Guid Id { get; init; }", result.Content);
+        Assert.Contains("public string Name { get; set; }", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_ValueObject_GeneratesRecord()
+    {
+        var model = new SemanticModel();
+        var entity = model.CreateEntity("Address", EntityClassification.ValueObject);
+        entity.Properties.Add(new SemanticProperty
+        {
+            Name = "Street",
+            Type = SemanticType.String,
+            Visibility = Visibility.Public
+        });
+        entity.Properties.Add(new SemanticProperty
+        {
+            Name = "City",
+            Type = SemanticType.String,
+            Visibility = Visibility.Public
+        });
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("public record Address", result.Content);
+        Assert.Contains("string Street", result.Content);
+        Assert.Contains("string City", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_Enum_GeneratesEnumDeclaration()
+    {
+        var model = new SemanticModel();
+        var entity = model.CreateEntity("OrderStatus", EntityClassification.Enum);
+        entity.Properties.Add(new SemanticProperty { Name = "Draft", Type = new SemanticType { Name = "OrderStatus" } });
+        entity.Properties.Add(new SemanticProperty { Name = "Confirmed", Type = new SemanticType { Name = "OrderStatus" } });
+        entity.Properties.Add(new SemanticProperty { Name = "Shipped", Type = new SemanticType { Name = "OrderStatus" } });
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("public enum OrderStatus", result.Content);
+        Assert.Contains("Draft,", result.Content);
+        Assert.Contains("Confirmed,", result.Content);
+        Assert.Contains("Shipped", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_Interface_GeneratesInterfaceDeclaration()
+    {
+        var model = new SemanticModel();
+        var entity = model.CreateEntity("IOrderRepository", EntityClassification.Interface);
+        entity.Operations.Add(new SemanticOperation
+        {
+            Name = "GetByIdAsync",
+            ReturnType = new SemanticType { Name = "Order" },
+            Visibility = Visibility.Public,
+            Parameters =
+            [
+                new SemanticParameter { Name = "id", Type = SemanticType.Guid }
+            ]
+        });
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("public interface IOrderRepository", result.Content);
+        Assert.Contains("Order GetByIdAsync(Guid id);", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_CollectionProperty_GeneratesICollectionWithInit()
+    {
+        var model = new SemanticModel();
+        var entity = model.CreateEntity("Order", EntityClassification.AggregateRoot);
+        entity.Properties.Add(new SemanticProperty
+        {
+            Name = "LineItems",
+            Type = SemanticType.CollectionOf(new SemanticType { Name = "LineItem" }),
+            Visibility = Visibility.Public,
+            Semantics = PropertySemantics.Collection
+        });
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("public ICollection<LineItem> LineItems { get; init; } = new List<LineItem>();", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_ReferenceProperty_GeneratesProperty()
+    {
+        var model = new SemanticModel();
+        var order = model.CreateEntity("Order", EntityClassification.Entity);
+        var customer = model.CreateEntity("Customer", EntityClassification.Entity);
+
+        order.Properties.Add(new SemanticProperty
+        {
+            Name = "Customer",
+            Type = new SemanticType { Name = "Customer", ReferencedEntityId = customer.Id },
+            Visibility = Visibility.Public,
+            Semantics = PropertySemantics.Navigation
+        });
+
+        model.AddRelationship(order.Id, customer.Id, RelationshipType.Association, "Customer");
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("public Customer Customer { get; set; }", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_Inheritance_GeneratesBaseClass()
+    {
+        var model = new SemanticModel();
+        var animal = model.CreateEntity("Animal");
+        var dog = model.CreateEntity("Dog");
+        model.AddRelationship(dog.Id, animal.Id, RelationshipType.Inheritance);
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("public class Dog : Animal", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_InterfaceImplementation_IncludesInterface()
+    {
+        var model = new SemanticModel();
+        var iface = model.CreateEntity("IService", EntityClassification.Interface);
+        var impl = model.CreateEntity("MyService");
+        model.AddRelationship(impl.Id, iface.Id, RelationshipType.Implementation);
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("public class MyService : IService", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_StaticMethod_HasStaticModifier()
+    {
+        var model = new SemanticModel();
+        var entity = model.CreateEntity("Factory");
+        entity.Operations.Add(new SemanticOperation
+        {
+            Name = "Create",
+            ReturnType = new SemanticType { Name = "Factory" },
+            Visibility = Visibility.Public,
+            IsStatic = true
+        });
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("public static Factory Create()", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_RequiredProperty_HasRequiredKeyword()
+    {
+        var model = new SemanticModel();
+        var entity = model.CreateEntity("Customer");
+        entity.Properties.Add(new SemanticProperty
+        {
+            Name = "Name",
+            Type = new SemanticType { Name = "Customer" }, // Non-primitive to get required keyword
+            Visibility = Visibility.Public,
+            IsRequired = true
+        });
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("required", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_WithDescription_IncludesXmlDoc()
+    {
+        var model = new SemanticModel();
+        var entity = model.CreateEntity("Customer");
+        entity.Description = "Represents a customer in the system";
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("/// <summary>", result.Content);
+        Assert.Contains("Represents a customer in the system", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_UseFileScopedNamespace()
+    {
+        var model = new SemanticModel { Name = "MyApp" };
+        model.CreateEntity("Test");
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("namespace MyApp.Domain;", result.Content);
+        Assert.DoesNotContain("namespace MyApp.Domain\n{", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_NullableProperty_IncludesQuestionMark()
+    {
+        var model = new SemanticModel();
+        var entity = model.CreateEntity("Order");
+        entity.Properties.Add(new SemanticProperty
+        {
+            Name = "ShippedAt",
+            Type = SemanticType.Nullable(SemanticType.DateTime),
+            Visibility = Visibility.Public
+        });
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("DateTime?", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_DomainEvent_GeneratesRecord()
+    {
+        var model = new SemanticModel();
+        var entity = model.CreateEntity("OrderCreatedEvent", EntityClassification.DomainEvent);
+        entity.Properties.Add(new SemanticProperty
+        {
+            Name = "OrderId",
+            Type = SemanticType.Guid,
+            Visibility = Visibility.Public
+        });
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("public record OrderCreatedEvent", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_MethodWithParameters_IncludesParameters()
+    {
+        var model = new SemanticModel();
+        var entity = model.CreateEntity("Calculator");
+        entity.Operations.Add(new SemanticOperation
+        {
+            Name = "Add",
+            ReturnType = SemanticType.Int,
+            Visibility = Visibility.Public,
+            Parameters =
+            [
+                new SemanticParameter { Name = "a", Type = SemanticType.Int },
+                new SemanticParameter { Name = "b", Type = SemanticType.Int }
+            ]
+        });
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("public int Add(int a, int b)", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_AbstractClass_HasAbstractModifier()
+    {
+        var model = new SemanticModel();
+        var entity = model.CreateEntity("BaseEntity", EntityClassification.AbstractClass);
+        entity.Stereotypes.Add("abstract");
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("public abstract class BaseEntity", result.Content);
+    }
+
+    [Fact]
+    public void TargetFormat_IsCSharp()
+    {
+        Assert.Equal("CSharp", _generator.TargetFormat);
+    }
+
+    [Fact]
+    public void DefaultExtension_IsCs()
+    {
+        Assert.Equal(".cs", _generator.DefaultExtension);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_OrdersEntitiesCorrectly()
+    {
+        var model = new SemanticModel();
+        model.CreateEntity("MyClass", EntityClassification.Class);
+        model.CreateEntity("MyEnum", EntityClassification.Enum);
+        model.CreateEntity("MyInterface", EntityClassification.Interface);
+        model.CreateEntity("MyValueObject", EntityClassification.ValueObject);
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+
+        // Enums should come first, then interfaces, then value objects, then classes
+        var enumIndex = result.Content!.IndexOf("enum MyEnum");
+        var interfaceIndex = result.Content.IndexOf("interface MyInterface");
+        var recordIndex = result.Content.IndexOf("record MyValueObject");
+        var classIndex = result.Content.IndexOf("class MyClass");
+
+        Assert.True(enumIndex < interfaceIndex, "Enum should come before interface");
+        Assert.True(interfaceIndex < recordIndex, "Interface should come before record");
+        Assert.True(recordIndex < classIndex, "Record should come before class");
+    }
+}
diff --git a/tests/DocFlow.CodeGen.Tests/DocFlow.CodeGen.Tests.csproj b/tests/DocFlow.CodeGen.Tests/DocFlow.CodeGen.Tests.csproj
new file mode 100644
index 0000000..a810806
--- /dev/null
+++ b/tests/DocFlow.CodeGen.Tests/DocFlow.CodeGen.Tests.csproj
@@ -0,0 +1,28 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+    <IsTestProject>true</IsTestProject>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
+    <PackageReference Include="xunit" Version="2.6.2" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.5.4">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+    <PackageReference Include="coverlet.collector" Version="6.0.0">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\DocFlow.CodeGen\DocFlow.CodeGen.csproj" />
+  </ItemGroup>
+
+</Project>
diff --git a/tests/DocFlow.Diagrams.Tests/DocFlow.Diagrams.Tests.csproj b/tests/DocFlow.Diagrams.Tests/DocFlow.Diagrams.Tests.csproj
new file mode 100644
index 0000000..d1a4c9d
--- /dev/null
+++ b/tests/DocFlow.Diagrams.Tests/DocFlow.Diagrams.Tests.csproj
@@ -0,0 +1,28 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+    <IsTestProject>true</IsTestProject>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
+    <PackageReference Include="xunit" Version="2.6.2" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.5.4">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+    <PackageReference Include="coverlet.collector" Version="6.0.0">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\DocFlow.Diagrams\DocFlow.Diagrams.csproj" />
+  </ItemGroup>
+
+</Project>
diff --git a/tests/DocFlow.Diagrams.Tests/Mermaid/MermaidClassDiagramGeneratorTests.cs b/tests/DocFlow.Diagrams.Tests/Mermaid/MermaidClassDiagramGeneratorTests.cs
new file mode 100644
index 0000000..93b4be6
--- /dev/null
+++ b/tests/DocFlow.Diagrams.Tests/Mermaid/MermaidClassDiagramGeneratorTests.cs
@@ -0,0 +1,272 @@
+using DocFlow.Core.Abstractions;
+using DocFlow.Core.CanonicalModel;
+using DocFlow.Diagrams.Mermaid;
+using Xunit;
+
+namespace DocFlow.Diagrams.Tests.Mermaid;
+
+public class MermaidClassDiagramGeneratorTests
+{
+    private readonly MermaidClassDiagramGenerator _generator = new();
+
+    [Fact]
+    public async Task GenerateAsync_EmptyModel_ReturnsClassDiagramHeader()
+    {
+        var model = new SemanticModel();
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.StartsWith("classDiagram", result.Content);
+    }
+
+    [Theory]
+    [InlineData(EntityClassification.AggregateRoot, "<<AggregateRoot>>")]
+    [InlineData(EntityClassification.Entity, "<<Entity>>")]
+    [InlineData(EntityClassification.ValueObject, "<<ValueObject>>")]
+    [InlineData(EntityClassification.DomainService, "<<Service>>")]
+    [InlineData(EntityClassification.Repository, "<<Repository>>")]
+    [InlineData(EntityClassification.Interface, "<<interface>>")]
+    [InlineData(EntityClassification.Enum, "<<enumeration>>")]
+    public async Task GenerateAsync_EntityClassification_GeneratesCorrectStereotype(
+        EntityClassification classification, string expectedStereotype)
+    {
+        var model = new SemanticModel();
+        model.AddEntity(new SemanticEntity
+        {
+            Id = "1",
+            Name = "TestEntity",
+            Classification = classification
+        });
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains(expectedStereotype, result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_Property_FormatsAsNameColonType()
+    {
+        var model = new SemanticModel();
+        var entity = new SemanticEntity { Id = "1", Name = "Customer" };
+        entity.Properties.Add(new SemanticProperty
+        {
+            Name = "Name",
+            Type = new SemanticType { Name = "string" },
+            Visibility = Visibility.Public
+        });
+        model.AddEntity(entity);
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("+Name : string", result.Content);
+    }
+
+    [Theory]
+    [InlineData(Visibility.Public, "+")]
+    [InlineData(Visibility.Private, "-")]
+    [InlineData(Visibility.Protected, "#")]
+    [InlineData(Visibility.Internal, "~")]
+    public async Task GenerateAsync_Visibility_GeneratesCorrectSymbol(
+        Visibility visibility, string expectedSymbol)
+    {
+        var model = new SemanticModel();
+        var entity = new SemanticEntity { Id = "1", Name = "Test" };
+        entity.Properties.Add(new SemanticProperty
+        {
+            Name = "Prop",
+            Type = new SemanticType { Name = "int" },
+            Visibility = visibility
+        });
+        model.AddEntity(entity);
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains($"{expectedSymbol}Prop : int", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_InheritanceRelationship_GeneratesCorrectArrow()
+    {
+        var model = new SemanticModel();
+        var parent = model.CreateEntity("Animal");
+        var child = model.CreateEntity("Dog");
+        model.AddRelationship(child.Id, parent.Id, RelationshipType.Inheritance);
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("Dog --|> Animal", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_ImplementationRelationship_GeneratesCorrectArrow()
+    {
+        var model = new SemanticModel();
+        var iface = model.CreateEntity("IService", EntityClassification.Interface);
+        var impl = model.CreateEntity("MyService");
+        model.AddRelationship(impl.Id, iface.Id, RelationshipType.Implementation);
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("MyService ..|> IService", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_CompositionRelationship_GeneratesCorrectArrow()
+    {
+        var model = new SemanticModel();
+        var order = model.CreateEntity("Order", EntityClassification.AggregateRoot);
+        var lineItem = model.CreateEntity("LineItem", EntityClassification.Entity);
+        var rel = model.AddRelationship(order.Id, lineItem.Id, RelationshipType.Composition, "LineItems");
+        rel.TargetMultiplicity = Multiplicity.ZeroOrMore;
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("Order --*", result.Content);
+        Assert.Contains("LineItem", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_AssociationRelationship_GeneratesCorrectArrow()
+    {
+        var model = new SemanticModel();
+        var order = model.CreateEntity("Order");
+        var customer = model.CreateEntity("Customer");
+        model.AddRelationship(order.Id, customer.Id, RelationshipType.Association, "Customer");
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("Order --> Customer", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_Multiplicity_RenderedCorrectly()
+    {
+        var model = new SemanticModel();
+        var order = model.CreateEntity("Order");
+        var item = model.CreateEntity("Item");
+        var rel = model.AddRelationship(order.Id, item.Id, RelationshipType.Composition);
+        rel.SourceMultiplicity = Multiplicity.One;
+        rel.TargetMultiplicity = Multiplicity.ZeroOrMore;
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("\"*\"", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_GenericType_UsesTildeNotation()
+    {
+        var model = new SemanticModel();
+        var entity = new SemanticEntity { Id = "1", Name = "Container" };
+        entity.Properties.Add(new SemanticProperty
+        {
+            Name = "Items",
+            Type = new SemanticType
+            {
+                Name = "ICollection",
+                IsCollection = true,
+                GenericArguments = [new SemanticType { Name = "Item" }]
+            },
+            Visibility = Visibility.Public
+        });
+        model.AddEntity(entity);
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("ICollection~Item~", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_StaticMethod_HasDollarSign()
+    {
+        var model = new SemanticModel();
+        var entity = new SemanticEntity { Id = "1", Name = "Factory" };
+        entity.Operations.Add(new SemanticOperation
+        {
+            Name = "Create",
+            ReturnType = new SemanticType { Name = "Factory" },
+            IsStatic = true,
+            Visibility = Visibility.Public
+        });
+        model.AddEntity(entity);
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("Create() Factory$", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_Enum_ListsMembers()
+    {
+        var model = new SemanticModel();
+        var entity = new SemanticEntity
+        {
+            Id = "1",
+            Name = "Status",
+            Classification = EntityClassification.Enum
+        };
+        entity.Properties.Add(new SemanticProperty { Name = "Active", Type = new SemanticType { Name = "Status" } });
+        entity.Properties.Add(new SemanticProperty { Name = "Inactive", Type = new SemanticType { Name = "Status" } });
+        model.AddEntity(entity);
+
+        var result = await _generator.GenerateAsync(model);
+
+        Assert.True(result.Success);
+        Assert.Contains("<<enumeration>>", result.Content);
+        Assert.Contains("Active", result.Content);
+        Assert.Contains("Inactive", result.Content);
+    }
+
+    [Fact]
+    public async Task GenerateAsync_Output_IsParseableByMermaidParser()
+    {
+        var model = new SemanticModel();
+        var customer = model.CreateEntity("Customer", EntityClassification.Entity);
+        customer.Properties.Add(new SemanticProperty
+        {
+            Name = "Id",
+            Type = SemanticType.Guid,
+            Visibility = Visibility.Public
+        });
+        customer.Properties.Add(new SemanticProperty
+        {
+            Name = "Name",
+            Type = SemanticType.String,
+            Visibility = Visibility.Public
+        });
+
+        var generateResult = await _generator.GenerateAsync(model);
+        Assert.True(generateResult.Success);
+
+        // Verify it can be parsed back
+        var parser = new MermaidClassDiagramParser();
+        var parseResult = await parser.ParseAsync(ParserInput.FromContent(generateResult.Content!));
+
+        Assert.True(parseResult.Success);
+        Assert.Single(parseResult.Model.Entities);
+        Assert.Equal("Customer", parseResult.Model.Entities.Values.First().Name);
+    }
+
+    [Fact]
+    public void TargetFormat_IsMermaid()
+    {
+        Assert.Equal("Mermaid", _generator.TargetFormat);
+    }
+
+    [Fact]
+    public void DefaultExtension_IsMmd()
+    {
+        Assert.Equal(".mmd", _generator.DefaultExtension);
+    }
+}
diff --git a/tests/DocFlow.Diagrams.Tests/Mermaid/MermaidClassDiagramParserTests.cs b/tests/DocFlow.Diagrams.Tests/Mermaid/MermaidClassDiagramParserTests.cs
new file mode 100644
index 0000000..b70a50f
--- /dev/null
+++ b/tests/DocFlow.Diagrams.Tests/Mermaid/MermaidClassDiagramParserTests.cs
@@ -0,0 +1,366 @@
+using DocFlow.Core.Abstractions;
+using DocFlow.Core.CanonicalModel;
+using DocFlow.Diagrams.Mermaid;
+using Xunit;
+
+namespace DocFlow.Diagrams.Tests.Mermaid;
+
+public class MermaidClassDiagramParserTests
+{
+    private readonly MermaidClassDiagramParser _parser = new();
+
+    [Fact]
+    public async Task ParseAsync_SimpleClass_ExtractsEntity()
+    {
+        var mermaid = """
+            classDiagram
+                class Customer {
+                    +Id : Guid
+                    +Name : string
+                }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(mermaid));
+
+        Assert.True(result.Success);
+        Assert.Single(result.Model.Entities);
+
+        var entity = result.Model.Entities.Values.First();
+        Assert.Equal("Customer", entity.Name);
+        Assert.Equal(2, entity.Properties.Count);
+    }
+
+    [Theory]
+    [InlineData("<<AggregateRoot>>", EntityClassification.AggregateRoot)]
+    [InlineData("<<Entity>>", EntityClassification.Entity)]
+    [InlineData("<<ValueObject>>", EntityClassification.ValueObject)]
+    [InlineData("<<Service>>", EntityClassification.DomainService)]
+    [InlineData("<<Repository>>", EntityClassification.Repository)]
+    [InlineData("<<interface>>", EntityClassification.Interface)]
+    [InlineData("<<enumeration>>", EntityClassification.Enum)]
+    public async Task ParseAsync_Stereotype_MapsToClassification(
+        string stereotype, EntityClassification expectedClassification)
+    {
+        var mermaid = $$"""
+            classDiagram
+                class Test {
+                    {{stereotype}}
+                }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(mermaid));
+
+        Assert.True(result.Success);
+        var entity = result.Model.Entities.Values.First();
+        Assert.Equal(expectedClassification, entity.Classification);
+    }
+
+    [Theory]
+    [InlineData("+", Visibility.Public)]
+    [InlineData("-", Visibility.Private)]
+    [InlineData("#", Visibility.Protected)]
+    [InlineData("~", Visibility.Internal)]
+    public async Task ParseAsync_Visibility_ParsedCorrectly(
+        string symbol, Visibility expectedVisibility)
+    {
+        var mermaid = $$"""
+            classDiagram
+                class Test {
+                    {{symbol}}Prop : string
+                }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(mermaid));
+
+        Assert.True(result.Success);
+        var prop = result.Model.Entities.Values.First().Properties.First();
+        Assert.Equal(expectedVisibility, prop.Visibility);
+    }
+
+    [Fact]
+    public async Task ParseAsync_PropertyWithType_ExtractsNameAndType()
+    {
+        var mermaid = """
+            classDiagram
+                class Customer {
+                    +Name : string
+                    +Age : int
+                    +CreatedAt : DateTime
+                }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(mermaid));
+
+        Assert.True(result.Success);
+        var entity = result.Model.Entities.Values.First();
+
+        Assert.Contains(entity.Properties, p => p.Name == "Name" && p.Type.Name == "string");
+        Assert.Contains(entity.Properties, p => p.Name == "Age" && p.Type.Name == "int");
+        Assert.Contains(entity.Properties, p => p.Name == "CreatedAt" && p.Type.Name == "DateTime");
+    }
+
+    [Fact]
+    public async Task ParseAsync_GenericType_ParsedWithTildeNotation()
+    {
+        var mermaid = """
+            classDiagram
+                class Order {
+                    +Items : ICollection~LineItem~
+                }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(mermaid));
+
+        Assert.True(result.Success);
+        var prop = result.Model.Entities.Values.First().Properties.First();
+
+        Assert.Equal("ICollection", prop.Type.Name);
+        Assert.True(prop.Type.IsCollection);
+        Assert.Single(prop.Type.GenericArguments);
+        Assert.Equal("LineItem", prop.Type.GenericArguments[0].Name);
+    }
+
+    [Fact]
+    public async Task ParseAsync_NullableType_ParsedCorrectly()
+    {
+        var mermaid = """
+            classDiagram
+                class Order {
+                    +ShippedAt : DateTime?
+                }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(mermaid));
+
+        Assert.True(result.Success);
+        var prop = result.Model.Entities.Values.First().Properties.First();
+        Assert.True(prop.Type.IsNullable);
+    }
+
+    [Fact]
+    public async Task ParseAsync_InheritanceRelationship_Parsed()
+    {
+        var mermaid = """
+            classDiagram
+                class Animal {
+                }
+                class Dog {
+                }
+                Dog --|> Animal
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(mermaid));
+
+        Assert.True(result.Success);
+        Assert.Single(result.Model.Relationships);
+
+        var rel = result.Model.Relationships.First();
+        Assert.Equal(RelationshipType.Inheritance, rel.Type);
+    }
+
+    [Fact]
+    public async Task ParseAsync_ImplementationRelationship_Parsed()
+    {
+        var mermaid = """
+            classDiagram
+                class IService {
+                    <<interface>>
+                }
+                class MyService {
+                }
+                MyService ..|> IService
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(mermaid));
+
+        Assert.True(result.Success);
+        var rel = result.Model.Relationships.First();
+        Assert.Equal(RelationshipType.Implementation, rel.Type);
+    }
+
+    [Fact]
+    public async Task ParseAsync_CompositionRelationship_Parsed()
+    {
+        var mermaid = """
+            classDiagram
+                class Order {
+                }
+                class LineItem {
+                }
+                Order --* LineItem
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(mermaid));
+
+        Assert.True(result.Success);
+        var rel = result.Model.Relationships.First();
+        Assert.Equal(RelationshipType.Composition, rel.Type);
+    }
+
+    [Fact]
+    public async Task ParseAsync_AssociationRelationship_Parsed()
+    {
+        var mermaid = """
+            classDiagram
+                class Order {
+                }
+                class Customer {
+                }
+                Order --> Customer
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(mermaid));
+
+        Assert.True(result.Success);
+        var rel = result.Model.Relationships.First();
+        Assert.Equal(RelationshipType.Association, rel.Type);
+    }
+
+    [Fact]
+    public async Task ParseAsync_RelationshipWithMultiplicity_Parsed()
+    {
+        var mermaid = """
+            classDiagram
+                class Order {
+                }
+                class LineItem {
+                }
+                Order --* "*" LineItem : items
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(mermaid));
+
+        Assert.True(result.Success);
+        var rel = result.Model.Relationships.First();
+        Assert.Equal("items", rel.Name);
+    }
+
+    [Fact]
+    public async Task ParseAsync_Method_ParsedCorrectly()
+    {
+        var mermaid = """
+            classDiagram
+                class Calculator {
+                    +Add(a, b) int
+                }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(mermaid));
+
+        Assert.True(result.Success);
+        var entity = result.Model.Entities.Values.First();
+        Assert.Single(entity.Operations);
+
+        var method = entity.Operations.First();
+        Assert.Equal("Add", method.Name);
+        Assert.Equal(2, method.Parameters.Count);
+    }
+
+    [Fact]
+    public async Task ParseAsync_StaticMethod_DetectedByDollarSign()
+    {
+        var mermaid = """
+            classDiagram
+                class Factory {
+                    +Create() Factory$
+                }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(mermaid));
+
+        Assert.True(result.Success);
+        var method = result.Model.Entities.Values.First().Operations.First();
+        Assert.True(method.IsStatic);
+    }
+
+    [Fact]
+    public async Task ParseAsync_RoundTrip_ProducesEquivalentModel()
+    {
+        // Create original model
+        var originalModel = new SemanticModel();
+        var customer = originalModel.CreateEntity("Customer", EntityClassification.Entity);
+        customer.Properties.Add(new SemanticProperty
+        {
+            Name = "Id",
+            Type = SemanticType.Guid,
+            Visibility = Visibility.Public
+        });
+        customer.Properties.Add(new SemanticProperty
+        {
+            Name = "Name",
+            Type = SemanticType.String,
+            Visibility = Visibility.Public
+        });
+
+        var order = originalModel.CreateEntity("Order", EntityClassification.AggregateRoot);
+        order.Properties.Add(new SemanticProperty
+        {
+            Name = "Id",
+            Type = SemanticType.Guid,
+            Visibility = Visibility.Public
+        });
+
+        originalModel.AddRelationship(order.Id, customer.Id, RelationshipType.Association, "Customer");
+
+        // Generate Mermaid
+        var generator = new MermaidClassDiagramGenerator();
+        var generateResult = await generator.GenerateAsync(originalModel);
+        Assert.True(generateResult.Success);
+
+        // Parse back
+        var parseResult = await _parser.ParseAsync(ParserInput.FromContent(generateResult.Content!));
+        Assert.True(parseResult.Success);
+
+        // Verify equivalence
+        Assert.Equal(originalModel.Entities.Count, parseResult.Model.Entities.Count);
+        Assert.Equal(originalModel.Relationships.Count, parseResult.Model.Relationships.Count);
+
+        var roundTripCustomer = parseResult.Model.Entities.Values.First(e => e.Name == "Customer");
+        Assert.Equal(EntityClassification.Entity, roundTripCustomer.Classification);
+        Assert.Equal(2, roundTripCustomer.Properties.Count);
+    }
+
+    [Fact]
+    public void CanParse_MermaidContent_ReturnsTrue()
+    {
+        var input = ParserInput.FromContent("classDiagram\n  class Test { }");
+        Assert.True(_parser.CanParse(input));
+    }
+
+    [Fact]
+    public void CanParse_NonMermaidContent_ReturnsFalse()
+    {
+        var input = ParserInput.FromContent("public class Test { }");
+        Assert.False(_parser.CanParse(input));
+    }
+
+    [Fact]
+    public void CanParse_MmdFilePath_ReturnsTrue()
+    {
+        var input = ParserInput.FromFile("diagram.mmd");
+        Assert.True(_parser.CanParse(input));
+    }
+
+    [Fact]
+    public void SupportedExtensions_ContainsMmd()
+    {
+        Assert.Contains(".mmd", _parser.SupportedExtensions);
+    }
+
+    [Fact]
+    public async Task ParseAsync_IdProperty_HasIdentitySemantics()
+    {
+        var mermaid = """
+            classDiagram
+                class Entity {
+                    +Id : Guid
+                }
+            """;
+
+        var result = await _parser.ParseAsync(ParserInput.FromContent(mermaid));
+
+        Assert.True(result.Success);
+        var prop = result.Model.Entities.Values.First().Properties.First();
+        Assert.Equal(PropertySemantics.Identity, prop.Semantics);
+    }
+}