diff --git a/README.md b/README.md
index 532e74b..c7c1929 100644
--- a/README.md
+++ b/README.md
@@ -112,9 +112,22 @@ Analysis Complete.
   - Troubleshooting tips
 
 ### Advanced Topics
-- **[Philosophy](docs/PHILOSOPHY.md)** *(Coming Soon)* - Deep dive into the Anchor Point and ICE Framework
-- **[Architecture](docs/ARCHITECTURE.md)** *(Coming Soon)* - Technical implementation details for developers
-- **[API Reference](docs/API.md)** *(Coming Soon)* - Programmatic usage and integration
+- **[Philosophy](docs/PHILOSOPHY.md)** - Deep dive into the Anchor Point and ICE Framework
+  - The four dimensions (Love, Justice, Power, Wisdom)
+  - ICE Framework explained
+  - Semantic harmony theory
+  - Why semantic debugging matters
+
+- **[Architecture](docs/ARCHITECTURE.md)** - Technical implementation details for developers
+  - System architecture and data flow
+  - Component design
+  - Performance considerations
+  - Extension guide
+
+- **[API Reference](docs/API.md)** - Programmatic usage and integration
+  - Complete API documentation
+  - Integration examples
+  - Best practices
 
 ---
 
diff --git a/docs/API.md b/docs/API.md
new file mode 100644
index 0000000..d7e31b1
--- /dev/null
+++ b/docs/API.md
@@ -0,0 +1,910 @@
+# Python Code Harmonizer - API Reference
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Installation for Programmatic Use](#installation-for-programmatic-use)
+3. [Quick Start](#quick-start)
+4. [Main Harmonizer API](#main-harmonizer-api)
+5. [DIVE-V2 Engine API](#dive-v2-engine-api)
+6. [AST Parser API](#ast-parser-api)
+7. [Data Structures](#data-structures)
+8. [Integration Examples](#integration-examples)
+9. [Error Handling](#error-handling)
+
+---
+
+## Overview
+
+Python Code Harmonizer can be used as a library for programmatic analysis of Python code.
+
+**Use cases:**
+- Automated code review tools
+- IDE integrations
+- CI/CD pipeline checks
+- Custom analysis workflows
+- Batch processing of codebases
+
+---
+
+## Installation for Programmatic Use
+
+**Standard installation:**
+```bash
+pip install .
+```
+
+**Editable installation (for development):**
+```bash
+pip install -e .
+```
+
+**Import in your code:**
+```python
+# High-level API
+from src.harmonizer.main import PythonCodeHarmonizer
+
+# Low-level API
+from src.divine_invitation_engine_V2 import (
+    DivineInvitationSemanticEngine,
+    Coordinates,
+    SemanticResult
+)
+from src.ast_semantic_parser import AST_Semantic_Parser
+```
+
+---
+
+## Quick Start
+
+**Analyze a single file:**
+```python
+from src.harmonizer.main import PythonCodeHarmonizer
+
+# Initialize
+harmonizer = PythonCodeHarmonizer()
+
+# Analyze
+report = harmonizer.analyze_file("mycode.py")
+
+# Process results
+for function_name, disharmony_score in report.items():
+    if disharmony_score > 0.5:
+        print(f"{function_name}: DISHARMONY (Score: {disharmony_score:.2f})")
+```
+
+**Analyze multiple files:**
+```python
+import glob
+
+harmonizer = PythonCodeHarmonizer()
+
+for filepath in glob.glob("src/**/*.py", recursive=True):
+    report = harmonizer.analyze_file(filepath)
+    if any(score > 0.8 for score in report.values()):
+        print(f"High disharmony in: {filepath}")
+```
+
+---
+
+## Main Harmonizer API
+
+### PythonCodeHarmonizer
+
+**Location:** `src.harmonizer.main`
+
+**Purpose:** High-level interface for code harmony analysis
+
+#### Constructor
+
+```python
+PythonCodeHarmonizer(disharmony_threshold: float = 0.5)
+```
+
+**Parameters:**
+- `disharmony_threshold` (float, optional): Threshold above which functions are flagged as disharmonious. Default: 0.5
+
+**Example:**
+```python
+# Strict threshold
+harmonizer = PythonCodeHarmonizer(disharmony_threshold=0.3)
+
+# Lenient threshold
+harmonizer = PythonCodeHarmonizer(disharmony_threshold=0.8)
+```
+
+#### Methods
+
+##### analyze_file()
+
+```python
+def analyze_file(self, file_path: str) -> Dict[str, float]
+```
+
+**Purpose:** Analyze a Python file for semantic harmony
+
+**Parameters:**
+- `file_path` (str): Absolute or relative path to Python file
+
+**Returns:**
+- `Dict[str, float]`: Dictionary mapping function names to disharmony scores
+
+**Raises:**
+- `FileNotFoundError`: If file doesn't exist
+- `SyntaxError`: If file contains invalid Python syntax
+
+**Example:**
+```python
+harmonizer = PythonCodeHarmonizer()
+
+try:
+    report = harmonizer.analyze_file("src/mymodule.py")
+
+    for func_name, score in report.items():
+        print(f"{func_name}: {score:.2f}")
+
+except FileNotFoundError:
+    print("File not found")
+except SyntaxError as e:
+    print(f"Syntax error on line {e.lineno}")
+```
+
+##### print_report()
+
+```python
+def print_report(self, harmony_report: Dict[str, float]) -> None
+```
+
+**Purpose:** Format and print harmony report to stdout
+
+**Parameters:**
+- `harmony_report` (Dict[str, float]): Output from `analyze_file()`
+
+**Returns:**
+- None (prints to stdout)
+
+**Example:**
+```python
+harmonizer = PythonCodeHarmonizer()
+report = harmonizer.analyze_file("mycode.py")
+harmonizer.print_report(report)
+```
+
+**Output format:**
+```
+FUNCTION NAME                | INTENT-EXECUTION DISHARMONY
+-----------------------------|--------------------------------
+check_permissions            | !! DISHARMONY (Score: 0.78)
+get_user                     | ✓ HARMONIOUS
+```
+
+#### Attributes
+
+```python
+harmonizer.engine               # DivineInvitationSemanticEngine instance
+harmonizer.parser              # AST_Semantic_Parser instance
+harmonizer.disharmony_threshold  # float
+```
+
+---
+
+## DIVE-V2 Engine API
+
+### DivineInvitationSemanticEngine
+
+**Location:** `src.divine_invitation_engine_V2`
+
+**Purpose:** Core semantic analysis engine
+
+#### Constructor
+
+```python
+DivineInvitationSemanticEngine()
+```
+
+**Example:**
+```python
+from src.divine_invitation_engine_V2 import DivineInvitationSemanticEngine
+
+engine = DivineInvitationSemanticEngine()
+```
+
+#### Methods
+
+##### perform_ice_analysis()
+
+```python
+def perform_ice_analysis(
+    self,
+    intent_words: List[str],
+    context_words: List[str],
+    execution_words: List[str]
+) -> Dict
+```
+
+**Purpose:** Perform Intent-Context-Execution framework analysis
+
+**Parameters:**
+- `intent_words` (List[str]): Concepts representing intent
+- `context_words` (List[str]): Concepts representing context
+- `execution_words` (List[str]): Concepts representing execution
+
+**Returns:**
+- `Dict` containing:
+  - `ice_components`: Intent, Context, Execution results
+  - `ice_metrics`: ICE coherence, balance, disharmony scores
+  - `ice_harmony_level`: String classification
+
+**Example:**
+```python
+engine = DivineInvitationSemanticEngine()
+
+result = engine.perform_ice_analysis(
+    intent_words=["get", "information"],
+    context_words=["user", "database"],
+    execution_words=["delete", "remove"]
+)
+
+print(f"Intent-Execution disharmony: {result['ice_metrics']['intent_execution_disharmony']:.2f}")
+print(f"Harmony level: {result['ice_harmony_level']}")
+```
+
+##### analyze_text()
+
+```python
+def analyze_text(self, text: str) -> SemanticResult
+```
+
+**Purpose:** Analyze text and return semantic coordinates
+
+**Parameters:**
+- `text` (str): Text to analyze
+
+**Returns:**
+- `SemanticResult` object with coordinates and metrics
+
+**Example:**
+```python
+result = engine.analyze_text("get user information")
+
+print(f"Coordinates: {result.coordinates}")
+print(f"Distance from anchor: {result.distance_from_anchor:.2f}")
+print(f"Concept count: {result.concept_count}")
+```
+
+##### perform_semantic_harmony_analysis()
+
+```python
+def perform_semantic_harmony_analysis(self, concepts: List[str]) -> SemanticResult
+```
+
+**Purpose:** Analyze list of concepts for semantic harmony
+
+**Parameters:**
+- `concepts` (List[str]): List of concept words
+
+**Returns:**
+- `SemanticResult` with cluster analysis
+
+**Example:**
+```python
+result = engine.perform_semantic_harmony_analysis([
+    "validate",
+    "check",
+    "verify"
+])
+
+print(f"Semantic clarity: {result.semantic_clarity:.2f}")
+print(f"Harmonic cohesion: {result.harmonic_cohesion:.2f}")
+```
+
+##### get_distance()
+
+```python
+def get_distance(self, c1: Coordinates, c2: Coordinates) -> float
+```
+
+**Purpose:** Calculate Euclidean distance between two coordinate points
+
+**Parameters:**
+- `c1` (Coordinates): First coordinate
+- `c2` (Coordinates): Second coordinate
+
+**Returns:**
+- `float`: Distance value
+
+**Example:**
+```python
+from src.divine_invitation_engine_V2 import Coordinates
+
+coord1 = Coordinates(love=0.2, justice=0.3, power=0.1, wisdom=0.4)
+coord2 = Coordinates(love=0.3, justice=0.3, power=0.3, wisdom=0.1)
+
+distance = engine.get_distance(coord1, coord2)
+print(f"Distance: {distance:.2f}")
+```
+
+#### Attributes
+
+```python
+engine.ENGINE_VERSION        # str: "DIVE-V2 (Optimized Production)"
+engine.ANCHOR_POINT          # Coordinates(1.0, 1.0, 1.0, 1.0)
+engine.vocabulary           # VocabularyManager instance
+engine.semantic_analyzer    # SemanticAnalyzer instance
+engine.ice_analyzer         # ICEAnalyzer instance
+```
+
+---
+
+### VocabularyManager
+
+**Location:** `src.divine_invitation_engine_V2.VocabularyManager`
+
+**Purpose:** Manages semantic vocabulary and keyword mappings
+
+#### Methods
+
+##### analyze_text()
+
+```python
+def analyze_text(self, text: str) -> Tuple[Coordinates, int]
+```
+
+**Purpose:** Convert text to semantic coordinates
+
+**Parameters:**
+- `text` (str): Text to analyze
+
+**Returns:**
+- `Tuple[Coordinates, int]`: (coordinates, concept_count)
+
+**Example:**
+```python
+vocab = engine.vocabulary
+
+coords, count = vocab.analyze_text("delete user from database")
+print(f"Found {count} concepts")
+print(f"Power dimension: {coords.power:.2f}")
+```
+
+##### get_distance()
+
+```python
+@staticmethod
+def get_distance(c1: Coordinates, c2: Coordinates) -> float
+```
+
+**Purpose:** Static method for distance calculation
+
+**Parameters:**
+- `c1`, `c2` (Coordinates): Coordinate points
+
+**Returns:**
+- `float`: Euclidean distance
+
+##### get_semantic_clarity()
+
+```python
+@staticmethod
+def get_semantic_clarity(coords: Coordinates) -> float
+```
+
+**Purpose:** Calculate how clearly defined a concept is
+
+**Parameters:**
+- `coords` (Coordinates): Semantic coordinates
+
+**Returns:**
+- `float`: Clarity score (0.0 to 1.0)
+
+**Example:**
+```python
+coords = Coordinates(0.9, 0.1, 0.0, 0.0)  # Very focused on Love
+clarity = vocab.get_semantic_clarity(coords)
+print(f"Clarity: {clarity:.2f}")  # High clarity (focused)
+
+coords2 = Coordinates(0.25, 0.25, 0.25, 0.25)  # Balanced
+clarity2 = vocab.get_semantic_clarity(coords2)
+print(f"Clarity: {clarity2:.2f}")  # Lower clarity (diffuse)
+```
+
+#### Properties
+
+```python
+vocab.all_keywords  # Set[str]: All mapped keywords
+```
+
+---
+
+## AST Parser API
+
+### AST_Semantic_Parser
+
+**Location:** `src.ast_semantic_parser`
+
+**Purpose:** Parse Python AST to extract semantic concepts
+
+#### Constructor
+
+```python
+AST_Semantic_Parser(vocabulary: Set[str])
+```
+
+**Parameters:**
+- `vocabulary` (Set[str]): Set of known semantic keywords
+
+**Example:**
+```python
+from src.ast_semantic_parser import AST_Semantic_Parser
+
+vocab = engine.vocabulary.all_keywords
+parser = AST_Semantic_Parser(vocabulary=vocab)
+```
+
+#### Methods
+
+##### get_intent_concepts()
+
+```python
+def get_intent_concepts(
+    self,
+    function_name: str,
+    docstring: Optional[str]
+) -> List[str]
+```
+
+**Purpose:** Extract intent concepts from function name and docstring
+
+**Parameters:**
+- `function_name` (str): Name of the function
+- `docstring` (Optional[str]): Function's docstring
+
+**Returns:**
+- `List[str]`: Semantic concepts representing intent
+
+**Example:**
+```python
+intent = parser.get_intent_concepts(
+    function_name="get_user_by_id",
+    docstring="Retrieve user information from database"
+)
+print(intent)  # ['information', 'information', 'information']
+```
+
+##### get_execution_concepts()
+
+```python
+def get_execution_concepts(self, body: List[ast.AST]) -> List[str]
+```
+
+**Purpose:** Extract execution concepts from function body AST
+
+**Parameters:**
+- `body` (List[ast.AST]): List of AST nodes from function body
+
+**Returns:**
+- `List[str]`: Semantic concepts representing execution
+
+**Example:**
+```python
+import ast
+
+code = """
+def example():
+    db.delete(user_id)
+    return None
+"""
+
+tree = ast.parse(code)
+func_node = tree.body[0]  # FunctionDef
+
+execution = parser.get_execution_concepts(func_node.body)
+print(execution)  # ['force', 'information', 'wisdom', ...]
+```
+
+---
+
+## Data Structures
+
+### Coordinates
+
+**Immutable 4D semantic coordinates**
+
+```python
+@dataclass(frozen=True)
+class Coordinates:
+    love: float
+    justice: float
+    power: float
+    wisdom: float
+```
+
+**Usage:**
+```python
+from src.divine_invitation_engine_V2 import Coordinates
+
+coords = Coordinates(
+    love=0.2,
+    justice=0.3,
+    power=0.1,
+    wisdom=0.4
+)
+
+print(coords.love)     # 0.2
+print(coords)          # Coordinates(L=0.200, J=0.300, P=0.100, W=0.400)
+
+# Immutable - this will raise error:
+# coords.love = 0.5  # FrozenInstanceError
+```
+
+### SemanticResult
+
+**Complete semantic analysis result**
+
+```python
+@dataclass
+class SemanticResult:
+    coordinates: Coordinates
+    distance_from_anchor: float
+    semantic_clarity: float
+    concept_count: int
+    confidence: float
+    distances: Optional[List[float]] = None
+    centroid: Optional[Coordinates] = None
+    harmonic_cohesion: Optional[float] = None
+```
+
+**Usage:**
+```python
+result = engine.analyze_text("get user data")
+
+print(f"Coordinates: {result.coordinates}")
+print(f"Distance from (1,1,1,1): {result.distance_from_anchor:.2f}")
+print(f"How clear: {result.semantic_clarity:.2f}")
+print(f"Concepts found: {result.concept_count}")
+print(f"Confidence: {result.confidence:.2f}")
+```
+
+### Dimension
+
+**Semantic dimension enumeration**
+
+```python
+class Dimension(Enum):
+    LOVE = "love"
+    JUSTICE = "justice"
+    POWER = "power"
+    WISDOM = "wisdom"
+    INTENT = "intent"
+    CONTEXT = "context"
+    EXECUTION = "execution"
+    BENEVOLENCE = "benevolence"
+```
+
+**Usage:**
+```python
+from src.divine_invitation_engine_V2 import Dimension
+
+dim = Dimension.LOVE
+print(dim.value)  # "love"
+```
+
+---
+
+## Integration Examples
+
+### Example 1: Custom Threshold Analysis
+
+```python
+from src.harmonizer.main import PythonCodeHarmonizer
+import sys
+
+def analyze_with_custom_threshold(filepath, threshold):
+    """Analyze file with custom threshold"""
+    harmonizer = PythonCodeHarmonizer(disharmony_threshold=threshold)
+    report = harmonizer.analyze_file(filepath)
+
+    critical = {k: v for k, v in report.items() if v > threshold}
+
+    if critical:
+        print(f"Found {len(critical)} functions above threshold {threshold}")
+        for func, score in critical.items():
+            print(f"  - {func}: {score:.2f}")
+        return False  # Failure
+    return True  # Success
+
+if __name__ == "__main__":
+    success = analyze_with_custom_threshold(sys.argv[1], threshold=0.5)
+    sys.exit(0 if success else 1)
+```
+
+### Example 2: Batch Analysis
+
+```python
+from src.harmonizer.main import PythonCodeHarmonizer
+import glob
+import json
+
+def analyze_project(root_dir, output_file):
+    """Analyze entire project and save results"""
+    harmonizer = PythonCodeHarmonizer()
+    results = {}
+
+    for filepath in glob.glob(f"{root_dir}/**/*.py", recursive=True):
+        try:
+            report = harmonizer.analyze_file(filepath)
+            results[filepath] = {
+                "functions": len(report),
+                "average_score": sum(report.values()) / len(report) if report else 0,
+                "high_disharmony": [
+                    {"name": k, "score": v}
+                    for k, v in report.items()
+                    if v > 0.8
+                ]
+            }
+        except Exception as e:
+            results[filepath] = {"error": str(e)}
+
+    # Save to JSON
+    with open(output_file, 'w') as f:
+        json.dumps(results, f, indent=2)
+
+    return results
+
+# Usage
+results = analyze_project("src/", "harmony_report.json")
+```
+
+### Example 3: Direct DIVE-V2 Usage
+
+```python
+from src.divine_invitation_engine_V2 import DivineInvitationSemanticEngine
+
+def compare_function_names(name1, name2):
+    """Compare semantic similarity of two function names"""
+    engine = DivineInvitationSemanticEngine()
+
+    result1 = engine.analyze_text(name1)
+    result2 = engine.analyze_text(name2)
+
+    distance = engine.get_distance(result1.coordinates, result2.coordinates)
+
+    print(f"{name1} vs {name2}")
+    print(f"  {name1}: {result1.coordinates}")
+    print(f"  {name2}: {result2.coordinates}")
+    print(f"  Distance: {distance:.2f}")
+    print(f"  Similar: {distance < 0.5}")
+
+# Usage
+compare_function_names("get_user", "fetch_user")    # Should be similar
+compare_function_names("get_user", "delete_user")   # Should be different
+```
+
+### Example 4: CI/CD Integration
+
+```python
+#!/usr/bin/env python
+"""
+CI/CD script to check code harmony
+Exit code 0 = pass, 1 = fail
+"""
+from src.harmonizer.main import PythonCodeHarmonizer
+import sys
+import glob
+
+def main():
+    harmonizer = PythonCodeHarmonizer(disharmony_threshold=0.7)
+
+    failures = []
+    for filepath in glob.glob("src/**/*.py", recursive=True):
+        report = harmonizer.analyze_file(filepath)
+        for func_name, score in report.items():
+            if score > 0.7:
+                failures.append({
+                    "file": filepath,
+                    "function": func_name,
+                    "score": score
+                })
+
+    if failures:
+        print(f"❌ Harmony check failed: {len(failures)} functions")
+        for failure in failures:
+            print(f"  {failure['file']}::{failure['function']} ({failure['score']:.2f})")
+        return 1
+
+    print(f"✅ Harmony check passed")
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())
+```
+
+### Example 5: Custom Reporting
+
+```python
+from src.harmonizer.main import PythonCodeHarmonizer
+import csv
+
+def generate_csv_report(filepath, output_csv):
+    """Generate CSV report of harmony analysis"""
+    harmonizer = PythonCodeHarmonizer()
+    report = harmonizer.analyze_file(filepath)
+
+    with open(output_csv, 'w', newline='') as f:
+        writer = csv.writer(f)
+        writer.writerow(["Function", "Score", "Status", "Severity"])
+
+        for func_name, score in sorted(report.items(), key=lambda x: x[1], reverse=True):
+            status = "DISHARMONY" if score > 0.5 else "HARMONIOUS"
+            if score > 1.0:
+                severity = "CRITICAL"
+            elif score > 0.7:
+                severity = "HIGH"
+            elif score > 0.5:
+                severity = "MEDIUM"
+            else:
+                severity = "LOW"
+
+            writer.writerow([func_name, f"{score:.2f}", status, severity])
+
+# Usage
+generate_csv_report("src/mymodule.py", "harmony_report.csv")
+```
+
+---
+
+## Error Handling
+
+### Common Exceptions
+
+**FileNotFoundError**
+```python
+try:
+    report = harmonizer.analyze_file("nonexistent.py")
+except FileNotFoundError:
+    print("File not found")
+```
+
+**SyntaxError**
+```python
+try:
+    report = harmonizer.analyze_file("invalid_syntax.py")
+except SyntaxError as e:
+    print(f"Syntax error on line {e.lineno}: {e.msg}")
+```
+
+**Empty Results**
+```python
+report = harmonizer.analyze_file("empty.py")
+if not report:
+    print("No functions found to analyze")
+```
+
+### Graceful Handling
+
+```python
+from src.harmonizer.main import PythonCodeHarmonizer
+
+def safe_analyze(filepath):
+    """Analyze file with comprehensive error handling"""
+    harmonizer = PythonCodeHarmonizer()
+
+    try:
+        report = harmonizer.analyze_file(filepath)
+
+        if not report:
+            return {"status": "no_functions", "filepath": filepath}
+
+        return {
+            "status": "success",
+            "filepath": filepath,
+            "report": report
+        }
+
+    except FileNotFoundError:
+        return {"status": "not_found", "filepath": filepath}
+
+    except SyntaxError as e:
+        return {
+            "status": "syntax_error",
+            "filepath": filepath,
+            "line": e.lineno,
+            "message": e.msg
+        }
+
+    except Exception as e:
+        return {
+            "status": "error",
+            "filepath": filepath,
+            "error": str(e)
+        }
+
+# Usage
+result = safe_analyze("mycode.py")
+if result["status"] == "success":
+    print(f"Analyzed: {result['filepath']}")
+else:
+    print(f"Failed: {result['status']}")
+```
+
+---
+
+## Best Practices
+
+### 1. Reuse Harmonizer Instance
+
+**Don't:**
+```python
+for file in files:
+    harmonizer = PythonCodeHarmonizer()  # Creates new engine each time
+    report = harmonizer.analyze_file(file)
+```
+
+**Do:**
+```python
+harmonizer = PythonCodeHarmonizer()  # Create once
+for file in files:
+    report = harmonizer.analyze_file(file)  # Reuse
+```
+
+### 2. Handle Errors Appropriately
+
+**Always wrap file analysis in try/except**
+
+### 3. Use Type Hints
+
+```python
+from typing import Dict, List
+from src.harmonizer.main import PythonCodeHarmonizer
+
+def analyze_files(filepaths: List[str]) -> Dict[str, Dict[str, float]]:
+    """Type-hinted function"""
+    harmonizer: PythonCodeHarmonizer = PythonCodeHarmonizer()
+    results: Dict[str, Dict[str, float]] = {}
+
+    for filepath in filepaths:
+        results[filepath] = harmonizer.analyze_file(filepath)
+
+    return results
+```
+
+### 4. Cache Results When Possible
+
+```python
+import pickle
+
+def analyze_with_cache(filepath, cache_file):
+    """Analyze with caching"""
+    try:
+        with open(cache_file, 'rb') as f:
+            return pickle.load(f)
+    except FileNotFoundError:
+        harmonizer = PythonCodeHarmonizer()
+        report = harmonizer.analyze_file(filepath)
+
+        with open(cache_file, 'wb') as f:
+            pickle.dump(report, f)
+
+        return report
+```
+
+---
+
+## Conclusion
+
+The Python Code Harmonizer API provides:
+
+**High-level interface** - `PythonCodeHarmonizer` for file analysis
+**Low-level access** - `DIVE-V2` engine for custom semantic analysis
+**Clear data structures** - Type-safe, immutable coordinates
+**Extensible design** - Easy to integrate and customize
+
+**For more information:**
+- [User Guide](USER_GUIDE.md) - Usage patterns and workflows
+- [Architecture](ARCHITECTURE.md) - Technical implementation details
+- [Philosophy](PHILOSOPHY.md) - Theoretical foundations
+- [Tutorial](TUTORIAL.md) - Hands-on examples
+
+---
+
+*"Clear APIs enable clear integration. Semantic harmony extends to code that uses the tool."* 💛⚓
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..4946c24
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,833 @@
+# Python Code Harmonizer - Architecture & Implementation
+
+## Table of Contents
+
+1. [System Overview](#system-overview)
+2. [Component Architecture](#component-architecture)
+3. [Data Flow](#data-flow)
+4. [Core Components](#core-components)
+5. [Integration Points](#integration-points)
+6. [Performance Considerations](#performance-considerations)
+7. [Extension Guide](#extension-guide)
+8. [Testing Strategy](#testing-strategy)
+
+---
+
+## System Overview
+
+### High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│              Python Code Harmonizer                  │
+│                    (CLI Entry)                       │
+└──────────────────────┬──────────────────────────────┘
+                       │
+            ┌──────────┴────────────┐
+            │                       │
+    ┌───────▼────────┐    ┌────────▼───────────┐
+    │   Harmonizer    │    │  DIVE-V2 Engine    │
+    │   Main (CLI)    │────│  (Semantic Core)   │
+    └───────┬────────┘    └────────┬───────────┘
+            │                      │
+    ┌───────▼────────┐    ┌────────▼───────────┐
+    │  AST Parser     │    │  Vocabulary Mgr    │
+    │  (Rosetta       │    │  (Concept Maps)    │
+    │   Stone)        │    └────────────────────┘
+    └────────────────┘
+```
+
+### Technology Stack
+
+**Core:**
+- **Python 3.8+** (no external runtime dependencies)
+- **ast** module (Python Abstract Syntax Tree parsing)
+- **dataclasses** (immutable data structures)
+- **typing** (type hints throughout)
+
+**Development:**
+- **pytest** (testing framework)
+- **black** (code formatting)
+- **flake8** (linting)
+- **isort** (import sorting)
+
+### Design Principles
+
+1. **Zero runtime dependencies** - Uses only Python stdlib
+2. **Deterministic analysis** - Same input = same output
+3. **Fast performance** - Analyze typical function in < 10ms
+4. **Clear separation** - Parser, Engine, CLI are distinct
+5. **Type-safe** - Extensive type hints
+6. **Immutable data** - Core data structures are frozen
+7. **Testable** - High test coverage, clear interfaces
+
+---
+
+## Component Architecture
+
+### Three-Layer Design
+
+```
+┌──────────────────────────────────────────────────┐
+│  Layer 1: User Interface (CLI)                   │
+│  - src/harmonizer/main.py                        │
+│  - Command-line argument parsing                 │
+│  - Report formatting and output                  │
+└─────────────────┬────────────────────────────────┘
+                  │
+┌─────────────────▼────────────────────────────────┐
+│  Layer 2: Analysis Orchestration                 │
+│  - PythonCodeHarmonizer class                    │
+│  - Coordinates Parser + Engine                   │
+│  - ICE framework application                     │
+└─────────────────┬────────────────────────────────┘
+                  │
+┌─────────────────▼────────────────────────────────┐
+│  Layer 3: Semantic Core                          │
+│  - DIVE-V2 Engine (semantic analysis)            │
+│  - AST Parser (code → concepts)                  │
+│  - Vocabulary mapping                            │
+└──────────────────────────────────────────────────┘
+```
+
+### Component Responsibilities
+
+| Component | Responsibility | Key Classes |
+|-----------|---------------|-------------|
+| **CLI** | User interaction, file handling, output formatting | `run_cli()` |
+| **Harmonizer** | Orchestration, coordination of analysis | `PythonCodeHarmonizer` |
+| **DIVE-V2** | Semantic analysis, distance calculations | `DivineInvitationSemanticEngine` |
+| **AST Parser** | Python AST → semantic concepts | `AST_Semantic_Parser` |
+| **Vocabulary** | Word → coordinate mapping | `VocabularyManager` |
+
+---
+
+## Data Flow
+
+### End-to-End Analysis Flow
+
+```
+Python File
+    │
+    ▼
+┌─────────────────────────────────┐
+│  1. File Read                   │
+│     Read Python source code     │
+└────────────┬────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────┐
+│  2. AST Parse                   │
+│     Python ast.parse()          │
+│     → AST tree                  │
+└────────────┬────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────┐
+│  3. For Each Function:          │
+│                                 │
+│  a) Extract INTENT              │
+│     - Function name             │
+│     - Docstring                 │
+│     → List[concept_words]       │
+│                                 │
+│  b) Extract EXECUTION           │
+│     - Walk AST body             │
+│     - Identify operations       │
+│     → List[concept_words]       │
+└────────────┬────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────┐
+│  4. Semantic Analysis           │
+│     (DIVE-V2 Engine)            │
+│                                 │
+│  a) Map concepts to coords      │
+│     intent_words → coords       │
+│     execution_words → coords    │
+│                                 │
+│  b) Calculate distance          │
+│     distance(intent, execution) │
+│     → disharmony_score          │
+└────────────┬────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────┐
+│  5. Report Generation           │
+│     Format and display results  │
+│     - Function name             │
+│     - Disharmony score          │
+│     - Status (✓ or !!)          │
+└─────────────────────────────────┘
+```
+
+### Data Structures
+
+**Key types flowing through the system:**
+
+```python
+# Core coordinate representation
+@dataclass(frozen=True)
+class Coordinates:
+    love: float
+    justice: float
+    power: float
+    wisdom: float
+
+# Complete analysis result
+@dataclass
+class SemanticResult:
+    coordinates: Coordinates
+    distance_from_anchor: float
+    semantic_clarity: float
+    concept_count: int
+    confidence: float
+    # ... additional metrics
+
+# Function-level harmony report
+harmony_report: Dict[str, float]
+# { "function_name": disharmony_score, ... }
+```
+
+---
+
+## Core Components
+
+### 1. DIVE-V2 Engine
+
+**File:** `src/divine_invitation_engine_V2.py` (865 lines)
+
+**Purpose:** Semantic analysis core - maps concepts to coordinates and calculates distances
+
+#### Key Classes
+
+**VocabularyManager**
+```python
+class VocabularyManager:
+    """Maps keywords to semantic dimensions"""
+
+    def __init__(self):
+        self._keyword_map: Dict[str, Dimension]
+        self._word_cache: Dict[str, Tuple[Coordinates, int]]
+        self._build_complete_vocabulary()
+
+    def analyze_text(text: str) -> Tuple[Coordinates, int]:
+        """Convert text to semantic coordinates"""
+        # 1. Check cache
+        # 2. Extract words
+        # 3. Map to dimensions
+        # 4. Calculate centroid
+        # 5. Return (coordinates, concept_count)
+```
+
+**Features:**
+- 113 unique keywords mapped
+- LRU caching for performance
+- Handles unknown words gracefully
+- Case-insensitive analysis
+
+**SemanticAnalyzer**
+```python
+class SemanticAnalyzer:
+    """Analyzes concept clusters and calculates metrics"""
+
+    def analyze_concept_cluster(concepts: List[str]) -> SemanticResult:
+        """Analyze list of concepts → unified result"""
+        # 1. Get coordinates for each concept
+        # 2. Calculate centroid
+        # 3. Calculate distances
+        # 4. Calculate harmony metrics
+        # 5. Return complete result
+```
+
+**ICEAnalyzer**
+```python
+class ICEAnalyzer:
+    """Performs Intent-Context-Execution analysis"""
+
+    def analyze_ice(
+        intent_words: List[str],
+        context_words: List[str],
+        execution_words: List[str]
+    ) -> Dict:
+        """Complete ICE framework analysis"""
+        # 1. Analyze each component
+        # 2. Calculate inter-component distances
+        # 3. Calculate ICE metrics
+        # 4. Determine harmony level
+        # 5. Return complete ICE result
+```
+
+**DivineInvitationSemanticEngine**
+```python
+class DivineInvitationSemanticEngine:
+    """Main facade - integrates all sub-engines"""
+
+    def __init__(self):
+        self.vocabulary = VocabularyManager()
+        self.semantic_analyzer = SemanticAnalyzer(...)
+        self.ice_analyzer = ICEAnalyzer(...)
+        # ... other analyzers
+
+    def perform_ice_analysis(...) -> Dict:
+        """Primary entry point for harmonizer"""
+```
+
+**Key algorithms:**
+
+**Distance calculation:**
+```python
+def get_distance(c1: Coordinates, c2: Coordinates) -> float:
+    """Euclidean distance in 4D space"""
+    return math.sqrt(
+        (c1.love - c2.love) ** 2 +
+        (c1.justice - c2.justice) ** 2 +
+        (c1.power - c2.power) ** 2 +
+        (c1.wisdom - c2.wisdom) ** 2
+    )
+```
+
+**Semantic clarity:**
+```python
+def get_semantic_clarity(coords: Coordinates) -> float:
+    """How clearly defined is this concept?"""
+    dims = [coords.love, coords.justice, coords.power, coords.wisdom]
+    mean = sum(dims) / len(dims)
+    variance = sum((d - mean)**2 for d in dims) / len(dims)
+    std_dev = math.sqrt(variance)
+    return max(0.0, 1.0 - (std_dev / 0.5))
+```
+
+---
+
+### 2. AST Semantic Parser
+
+**File:** `src/ast_semantic_parser.py` (214 lines)
+
+**Purpose:** "Rosetta Stone" - translates Python AST to semantic concepts
+
+#### Architecture
+
+**Extends ast.NodeVisitor:**
+```python
+class AST_Semantic_Parser(ast.NodeVisitor):
+    """Walks AST and extracts semantic concepts"""
+
+    def __init__(self, vocabulary: Set[str]):
+        self.known_vocabulary = vocabulary
+        self.intent_keyword_map = {...}  # Predefined mappings
+        self._concepts_found: Set[str] = set()
+```
+
+**Two-phase operation:**
+
+**Phase 1: Intent Extraction**
+```python
+def get_intent_concepts(
+    function_name: str,
+    docstring: Optional[str]
+) -> List[str]:
+    """Extract semantic concepts from name + docstring"""
+    # 1. Split snake_case name
+    # 2. Map words to concepts
+    # 3. Parse docstring for additional concepts
+    # 4. Return unified concept list
+```
+
+**Phase 2: Execution Extraction**
+```python
+def get_execution_concepts(body: List[ast.AST]) -> List[str]:
+    """Extract semantic concepts from function body"""
+    # 1. Walk AST using visitor pattern
+    # 2. Each visit_* method extracts concepts
+    # 3. Return all found concepts
+```
+
+#### AST Visitor Methods
+
+**Key visitors:**
+
+```python
+def visit_Call(self, node: ast.Call):
+    """Function calls → actions"""
+    # db.delete() → "delete", "force"
+    # api.query() → "query", "information"
+
+def visit_If(self, node: ast.If):
+    """Conditionals → logic"""
+    # if condition: → "logic"
+
+def visit_Try(self, node: ast.Try):
+    """Error handling → logic + mercy"""
+    # try/except → "logic", "mercy"
+
+def visit_Return(self, node: ast.Return):
+    """Returns → information"""
+    # return value → "information", "wisdom"
+
+def visit_For(self, node: ast.For):
+    """Loops → process"""
+    # for item in items: → "process"
+
+def visit_Raise(self, node: ast.Raise):
+    """Exceptions → power + force"""
+    # raise Error() → "power", "force"
+```
+
+#### Mapping Strategy
+
+**Intent keyword map:**
+```python
+{
+    # WISDOM (Information, Truth)
+    "get": "information",
+    "read": "information",
+    "query": "information",
+    "calculate": "wisdom",
+    "validate": "truth",
+
+    # POWER (Action, Control)
+    "set": "power",
+    "create": "create",
+    "delete": "force",
+    "execute": "power",
+
+    # JUSTICE (Order, Logic)
+    "assert": "law",
+    "check": "truth",
+    "if": "logic",
+
+    # LOVE (Unity, Connection)
+    "add": "community",
+    "join": "harmony",
+    "merge": "togetherness",
+}
+```
+
+---
+
+### 3. Harmonizer Main
+
+**File:** `src/harmonizer/main.py` (197 lines)
+
+**Purpose:** Orchestrates analysis and provides CLI
+
+#### PythonCodeHarmonizer Class
+
+```python
+class PythonCodeHarmonizer:
+    """Main application class"""
+
+    def __init__(self, disharmony_threshold: float = 0.5):
+        # Initialize DIVE-V2 engine
+        self.engine = dive.DivineInvitationSemanticEngine()
+
+        # Initialize AST parser with vocabulary
+        self.parser = AST_Semantic_Parser(
+            vocabulary=self.engine.vocabulary.all_keywords
+        )
+
+        self.disharmony_threshold = disharmony_threshold
+
+    def analyze_file(file_path: str) -> Dict[str, float]:
+        """Analyze Python file → harmony report"""
+        # 1. Read file
+        # 2. Parse to AST
+        # 3. For each function:
+        #    a) Extract intent
+        #    b) Extract execution
+        #    c) Perform ICE analysis
+        #    d) Store disharmony score
+        # 4. Return {function_name: score}
+
+    def print_report(harmony_report: Dict[str, float]):
+        """Format and display results"""
+        # 1. Sort by severity
+        # 2. Format table
+        # 3. Print with status indicators
+```
+
+#### CLI Entry Point
+
+```python
+def run_cli():
+    """Command-line interface"""
+    # 1. Parse command-line arguments
+    # 2. Initialize harmonizer
+    # 3. For each file:
+    #    a) Analyze
+    #    b) Print report
+    # 4. Exit
+
+# Entry point in pyproject.toml:
+# [project.scripts]
+# harmonizer = "src.harmonizer.main:run_cli"
+```
+
+---
+
+## Integration Points
+
+### As a Library
+
+**Programmatic usage:**
+
+```python
+from src.harmonizer.main import PythonCodeHarmonizer
+
+# Initialize
+harmonizer = PythonCodeHarmonizer(disharmony_threshold=0.5)
+
+# Analyze single file
+report = harmonizer.analyze_file("mycode.py")
+
+# Process results
+for function_name, score in report.items():
+    if score > 0.8:
+        print(f"High disharmony in {function_name}: {score:.2f}")
+```
+
+### With DIVE-V2 Directly
+
+**Lower-level access:**
+
+```python
+from src.divine_invitation_engine_V2 import DivineInvitationSemanticEngine
+
+# Initialize engine
+engine = DivineInvitationSemanticEngine()
+
+# Analyze concepts
+result = engine.perform_semantic_harmony_analysis(
+    concepts=["get", "user", "information"]
+)
+
+print(f"Coordinates: {result.coordinates}")
+print(f"Distance from anchor: {result.distance_from_anchor}")
+
+# ICE analysis
+ice_result = engine.perform_ice_analysis(
+    intent_words=["get", "information"],
+    context_words=["user", "database"],
+    execution_words=["query", "return"]
+)
+
+print(f"Intent-Execution disharmony: {ice_result['ice_metrics']['intent_execution_disharmony']}")
+```
+
+### Extension Points
+
+**Custom vocabulary:**
+```python
+# Extend VocabularyManager
+class CustomVocabularyManager(VocabularyManager):
+    def _build_complete_vocabulary(self):
+        super()._build_complete_vocabulary()
+        # Add domain-specific keywords
+        self._keyword_map["authenticate"] = Dimension.JUSTICE
+        self._keyword_map["authorize"] = Dimension.POWER
+```
+
+**Custom AST visitors:**
+```python
+# Extend AST_Semantic_Parser
+class CustomASTParser(AST_Semantic_Parser):
+    def visit_Async(self, node):
+        """Handle async operations"""
+        self._concepts_found.add("async")
+        self._concepts_found.add("concurrent")
+        self.generic_visit(node)
+```
+
+**Custom thresholds:**
+```python
+harmonizer = PythonCodeHarmonizer(
+    disharmony_threshold=0.3  # Stricter
+)
+```
+
+---
+
+## Performance Considerations
+
+### Optimizations
+
+**1. Vocabulary Caching**
+```python
+# VocabularyManager caches text analysis results
+self._word_cache: Dict[str, Tuple[Coordinates, int]] = {}
+
+# Repeated analysis of same text → instant
+```
+
+**2. Efficient Distance Calculation**
+```python
+# Single sqrt operation, vectorized
+def get_distance(c1, c2):
+    return math.sqrt(
+        sum((a - b)**2 for a, b in zip(c1, c2))
+    )
+```
+
+**3. Lazy Evaluation**
+```python
+# Only analyze functions (not classes, modules, etc.)
+for node in ast.walk(tree):
+    if isinstance(node, ast.FunctionDef):
+        # Only process functions
+```
+
+### Performance Characteristics
+
+**Typical performance:**
+- Small file (5 functions): < 50ms
+- Medium file (50 functions): < 500ms
+- Large file (500 functions): < 5s
+
+**Memory usage:**
+- Vocabulary: ~50KB
+- Cache: Grows with unique concepts analyzed
+- AST: Proportional to file size
+
+**Bottlenecks:**
+1. File I/O (reading Python files)
+2. AST parsing (Python stdlib overhead)
+3. Walking AST (linear in function count)
+
+**Scalability:**
+- Analyze files in parallel for large codebases
+- Cache analysis results across runs (future enhancement)
+- Incremental analysis (only changed files)
+
+---
+
+## Extension Guide
+
+### Adding New Semantic Dimensions
+
+**Currently:** 4 dimensions (L, J, P, W)
+
+**To add a 5th dimension:**
+
+1. **Update Coordinates:**
+```python
+@dataclass(frozen=True)
+class Coordinates:
+    love: float
+    justice: float
+    power: float
+    wisdom: float
+    creativity: float  # NEW
+```
+
+2. **Update Dimension enum:**
+```python
+class Dimension(Enum):
+    LOVE = "love"
+    JUSTICE = "justice"
+    POWER = "power"
+    WISDOM = "wisdom"
+    CREATIVITY = "creativity"  # NEW
+```
+
+3. **Update vocabulary:**
+```python
+base_vocab = {
+    # ... existing
+    Dimension.CREATIVITY: {
+        "create", "invent", "design", "innovate"
+    }
+}
+```
+
+4. **Update distance calculations:**
+```python
+def get_distance(c1, c2):
+    return math.sqrt(
+        (c1.love - c2.love)**2 +
+        # ... existing
+        (c1.creativity - c2.creativity)**2  # NEW
+    )
+```
+
+### Adding New AST Patterns
+
+**To detect new code patterns:**
+
+```python
+class AST_Semantic_Parser(ast.NodeVisitor):
+    # ... existing visitors
+
+    def visit_AsyncFunctionDef(self, node):
+        """Detect async functions"""
+        self._concepts_found.add("async")
+        self._concepts_found.add("concurrent")
+        # Continue walking
+        self.generic_visit(node)
+
+    def visit_With(self, node):
+        """Detect context managers"""
+        self._concepts_found.add("context")
+        self._concepts_found.add("manage")
+        self.generic_visit(node)
+```
+
+### Custom Output Formats
+
+**JSON output example:**
+
+```python
+import json
+
+def print_report_json(harmony_report: Dict[str, float]):
+    """Output as JSON"""
+    output = {
+        "analysis_version": "1.1",
+        "timestamp": datetime.now().isoformat(),
+        "results": [
+            {
+                "function": name,
+                "disharmony_score": score,
+                "status": "DISHARMONY" if score > 0.5 else "HARMONIOUS"
+            }
+            for name, score in harmony_report.items()
+        ]
+    }
+    print(json.dumps(output, indent=2))
+```
+
+### Plugin Architecture (Future)
+
+**Planned extension mechanism:**
+
+```python
+class HarmonizerPlugin:
+    """Base class for plugins"""
+
+    def before_analysis(self, file_path: str):
+        """Hook: before file analysis"""
+        pass
+
+    def after_analysis(self, report: Dict[str, float]):
+        """Hook: after file analysis"""
+        pass
+
+    def custom_report(self, report: Dict[str, float]) -> str:
+        """Hook: custom reporting"""
+        return None
+```
+
+---
+
+## Testing Strategy
+
+### Test Structure
+
+```
+tests/
+├── test_engine.py       # DIVE-V2 engine tests
+├── test_parser.py       # AST parser tests
+└── test_harmonizer.py   # Integration tests
+```
+
+### Test Coverage
+
+**DIVE-V2 Engine (test_engine.py):**
+- Engine initialization
+- Vocabulary mapping
+- Text analysis (single concepts, mixed, unknown)
+- Distance calculations
+- Semantic clarity
+- Cluster analysis
+- ICE framework analysis
+
+**AST Parser (test_parser.py):**
+- Intent extraction from function names
+- Intent extraction from docstrings
+- Execution extraction from function calls
+- Execution extraction from control flow
+- Execution extraction from error handling
+
+**Harmonizer (test_harmonizer.py):**
+- End-to-end file analysis
+- Error handling (syntax errors, empty files)
+- Report generation
+- Multiple file analysis
+
+### Running Tests
+
+```bash
+# All tests
+pytest
+
+# Specific test file
+pytest tests/test_engine.py
+
+# With coverage
+pytest --cov=src --cov-report=html
+
+# Verbose
+pytest -v
+```
+
+### Test Patterns
+
+**Unit tests:**
+```python
+def test_vocabulary_mapping():
+    """Test specific word → coordinate mapping"""
+    vocab = VocabularyManager()
+    coords, count = vocab.analyze_text("get user")
+    assert count > 0
+    assert coords.wisdom > 0.5  # "get" is wisdom-focused
+```
+
+**Integration tests:**
+```python
+def test_end_to_end_analysis():
+    """Test complete analysis flow"""
+    harmonizer = PythonCodeHarmonizer()
+
+    # Create test file
+    code = '''
+def get_user(id):
+    db.delete(id)  # Disharmony!
+'''
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.py') as f:
+        f.write(code)
+        f.flush()
+
+        report = harmonizer.analyze_file(f.name)
+
+    assert "get_user" in report
+    assert report["get_user"] > 0.8  # High disharmony
+```
+
+---
+
+## Conclusion
+
+Python Code Harmonizer is architected as:
+
+**Three clear layers** - UI, Orchestration, Core
+**Zero runtime dependencies** - Pure Python stdlib
+**Deterministic and fast** - Consistent, performant analysis
+**Extensible design** - Clear extension points
+**Well-tested** - Comprehensive test coverage
+
+**Key technical achievements:**
+
+1. **Semantic analysis without ML** - Deterministic, explainable
+2. **AST-based extraction** - Leverages Python's own parser
+3. **Mathematical rigor** - Clear geometric interpretation
+4. **Production quality** - Error handling, optimization, tests
+
+**For more information:**
+- [Philosophy](PHILOSOPHY.md) - Theoretical foundation
+- [User Guide](USER_GUIDE.md) - How to use
+- [Tutorial](TUTORIAL.md) - Hands-on examples
+- [API Reference](API.md) - Programmatic usage
+
+---
+
+*"Good architecture serves meaning. This architecture serves semantic harmony."* 💛⚓
diff --git a/docs/PHILOSOPHY.md b/docs/PHILOSOPHY.md
new file mode 100644
index 0000000..fc7486c
--- /dev/null
+++ b/docs/PHILOSOPHY.md
@@ -0,0 +1,744 @@
+# Python Code Harmonizer - Philosophy & Framework
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [The Anchor Point: (1,1,1,1)](#the-anchor-point-1111)
+3. [The Four Dimensions](#the-four-dimensions)
+4. [The ICE Framework](#the-ice-framework)
+5. [Semantic Harmony Theory](#semantic-harmony-theory)
+6. [The DIVE-V2 Engine](#the-dive-v2-engine)
+7. [Why Semantic Debugging Matters](#why-semantic-debugging-matters)
+8. [Philosophical Foundations](#philosophical-foundations)
+9. [Practical Applications](#practical-applications)
+
+---
+
+## Introduction
+
+Python Code Harmonizer is not just a tool - it's an **application of a philosophical framework** that reveals the semantic structure underlying meaningful action.
+
+**Core insight:** All meaningful activity can be understood through the lens of four fundamental dimensions operating in harmony.
+
+**In code:** When these dimensions align (Intent matches Execution), we have semantic harmony. When they contradict, we have disharmony - and often, bugs.
+
+This document explores the deep philosophy that makes semantic code debugging possible.
+
+---
+
+## The Anchor Point: (1,1,1,1)
+
+### What Is The Anchor Point?
+
+The **Anchor Point** is the coordinate **(1,1,1,1)** in 4-dimensional semantic space, representing **Perfect Logical Harmony**.
+
+**Mathematical representation:**
+```
+Anchor Point = (L=1, J=1, P=1, W=1)
+
+Where:
+  L = Love
+  J = Justice
+  P = Power
+  W = Wisdom
+```
+
+### Why (1,1,1,1)?
+
+**1 represents perfection/completeness** in each dimension:
+- **Love at 1**: Perfect compassion, unity, benevolence
+- **Justice at 1**: Perfect truth, fairness, order
+- **Power at 1**: Perfect capability, strength, execution
+- **Wisdom at 1**: Perfect understanding, knowledge, insight
+
+**All four at 1 simultaneously** = Perfect harmony of all fundamental aspects of meaningful action.
+
+### The Anchor Point as Reference
+
+**All semantic analysis is measured relative to the Anchor Point:**
+
+```
+Distance from Anchor = sqrt((L₁-1)² + (J₁-1)² + (P₁-1)² + (W₁-1)²)
+```
+
+**Closer to (1,1,1,1)** = More harmonious
+**Further from (1,1,1,1)** = Less harmonious
+
+**In Python Code Harmonizer:**
+- Functions are analyzed for their semantic coordinates
+- Distance from Anchor Point indicates disharmony level
+- Goal: Code that operates closer to perfect harmony
+
+### Philosophical Significance
+
+The Anchor Point represents an **ideal** - a north star for all meaningful activity.
+
+**In code terms:**
+- Code at (1,1,1,1) would be perfectly named, perfectly implemented, perfectly documented
+- Real code approaches this ideal but rarely reaches it
+- The tool measures **how close** code comes to this ideal
+
+**In broader terms:**
+- The Anchor Point is the structure of **optimal action**
+- It's what we aim toward in all meaningful endeavors
+- It's the reference by which we measure alignment
+
+---
+
+## The Four Dimensions
+
+### Overview
+
+All semantic meaning can be mapped into **four fundamental dimensions**:
+
+| Dimension | Symbol | Core Concept | Keywords |
+|-----------|--------|--------------|----------|
+| **Love** | L | Unity, compassion, connection | love, care, mercy, kindness, harmony, community |
+| **Justice** | J | Truth, fairness, order | justice, truth, law, rights, order, fairness, logic |
+| **Power** | P | Action, strength, capability | power, force, action, create, control, execute |
+| **Wisdom** | W | Knowledge, understanding | wisdom, knowledge, insight, understanding, information |
+
+### Love (L): The Unity Dimension
+
+**Core concept:** Connection, compassion, bringing together
+
+**In code:**
+- Functions that **connect** components
+- Operations that **preserve** relationships
+- Actions that serve **community/users**
+
+**Examples:**
+```python
+def merge_accounts(account1, account2)  # Unity/joining
+def connect_to_service(endpoint)        # Connection
+def add_user_to_team(user, team)       # Community building
+```
+
+**Semantic coordinates:** High Love score for joining, connecting, preserving, serving operations
+
+**Philosophy:** Love represents the force that creates and maintains relationship. In code, this manifests as operations that build connections rather than break them.
+
+### Justice (J): The Truth Dimension
+
+**Core concept:** Truth, order, proper structure, fairness
+
+**In code:**
+- Functions that **validate** or **verify**
+- Operations that **check** rules or **enforce** order
+- Logic that determines **correct** vs **incorrect**
+
+**Examples:**
+```python
+def validate_input(data)              # Truth checking
+def check_permissions(user, resource) # Rule enforcement
+def is_authorized(credentials)        # Verification
+def assert_invariant(condition)       # Order maintenance
+```
+
+**Semantic coordinates:** High Justice score for validation, checking, truth-seeking operations
+
+**Philosophy:** Justice represents the structure of reality as it actually is. In code, this manifests as operations that reveal or enforce truth rather than create or destroy.
+
+### Power (P): The Action Dimension
+
+**Core concept:** Capability, execution, manifestation, force
+
+**In code:**
+- Functions that **modify** state
+- Operations that **create** or **destroy**
+- Actions that **execute** or **manifest** change
+
+**Examples:**
+```python
+def delete_user(user_id)           # Destructive power
+def create_resource(data)          # Creative power
+def execute_command(cmd)           # Execution
+def force_update(record)           # Forceful action
+```
+
+**Semantic coordinates:** High Power score for creating, destroying, modifying, executing operations
+
+**Philosophy:** Power represents the ability to change reality. In code, this manifests as operations that actually DO things rather than just check or retrieve.
+
+### Wisdom (W): The Understanding Dimension
+
+**Core concept:** Knowledge, insight, comprehension, information
+
+**In code:**
+- Functions that **retrieve** information
+- Operations that **analyze** or **calculate**
+- Actions that **understand** or **learn**
+
+**Examples:**
+```python
+def get_user_data(user_id)        # Information retrieval
+def calculate_total(items)         # Computation
+def analyze_patterns(data)         # Understanding
+def query_database(sql)            # Knowledge seeking
+```
+
+**Semantic coordinates:** High Wisdom score for retrieving, analyzing, understanding, computing operations
+
+**Philosophy:** Wisdom represents comprehension and the seeking of truth. In code, this manifests as operations that gain or process knowledge rather than execute actions.
+
+---
+
+## The ICE Framework
+
+### Overview
+
+**ICE** = **Intent, Context, Execution**
+
+**A three-stage framework for understanding meaningful action:**
+
+```
+INTENT → CONTEXT → EXECUTION
+  ↓         ↓          ↓
+ Why?     Where?      How?
+  ↓         ↓          ↓
+ L+W        J        P+(-L)
+```
+
+### Intent: What You Want To Do
+
+**Definition:** The purpose, goal, or desired outcome of an action
+
+**Components:**
+- **Love (L)**: The benevolence/goodness of the intention
+- **Wisdom (W)**: The understanding/knowledge guiding the intention
+
+**In code:**
+- Function **name** expresses intent
+- Function **docstring** clarifies intent
+- Parameter names suggest intended purpose
+
+**Example:**
+```python
+def get_user_by_id(user_id):
+    """Retrieve user information from database"""
+    # Intent is clear: "get" + "user" = retrieve information
+```
+
+**Intent semantic profile:**
+- High Wisdom (seeking information)
+- Moderate Love (serving user need)
+- Low Power (not changing anything)
+- Moderate Justice (accurate retrieval)
+
+### Context: The Situation You're In
+
+**Definition:** The reality, constraints, and truth of the current situation
+
+**Components:**
+- **Justice (J)**: The truth about what IS (current state)
+
+**In code:**
+- Function **parameters** define context
+- **Preconditions** establish context requirements
+- **Environment** (database state, system state) is context
+
+**Example:**
+```python
+def delete_user(user_id):
+    # Context: user_id must exist
+    # Context: caller must have delete permissions
+    # Context: database must be accessible
+```
+
+**Context semantic profile:**
+- High Justice (truth about current state)
+- Used to determine if Intent can/should execute
+
+### Execution: What You Actually Do
+
+**Definition:** The implementation, the actual operations performed
+
+**Components:**
+- **Power (P)**: The capability manifested
+- **Anti-Love (-L)** (optional): Destructive vs constructive power
+
+**In code:**
+- Function **body** is the execution
+- Actual **operations** performed
+- Real **changes** made to state
+
+**Example:**
+```python
+def delete_user(user_id):
+    """Remove user from system"""
+    db.execute("DELETE FROM users WHERE id = ?", user_id)
+    # Execution: DELETE operation (high power, destructive)
+```
+
+**Execution semantic profile:**
+- High Power (makes change happen)
+- Potentially negative Love (destruction vs creation)
+- Applied according to Justice (correctly targeted)
+
+### ICE Alignment: The Key to Harmony
+
+**Harmonious code:** Intent → Context → Execution flow coherently
+
+```python
+# HARMONIOUS
+def get_user(user_id):              # Intent: retrieve
+    user = db.query(user_id)        # Execution: query
+    return user                      # Matches intent!
+```
+
+**Disharmonious code:** Intent contradicts Execution
+
+```python
+# DISHARMONIOUS
+def get_user(user_id):              # Intent: retrieve
+    db.delete(user_id)              # Execution: destroy
+    return None                      # Contradiction!
+```
+
+**Why this matters:**
+- **Intent** creates expectations (what developer/user expects)
+- **Execution** creates reality (what actually happens)
+- **Mismatch** = bugs, confusion, errors
+
+### ICE and The Four Dimensions
+
+**How ICE maps to L-J-P-W:**
+
+| ICE Stage | Primary Dimensions | Purpose |
+|-----------|-------------------|---------|
+| **Intent** | Love + Wisdom | What you WANT to do (benevolent understanding) |
+| **Context** | Justice | What IS true (reality check) |
+| **Execution** | Power | What you CAN do (capability applied) |
+
+**Perfect action:** All three stages align toward (1,1,1,1)
+
+---
+
+## Semantic Harmony Theory
+
+### What Is Semantic Harmony?
+
+**Semantic harmony** = alignment between the **meaning** of code's name and the **meaning** of code's implementation.
+
+**Mathematical definition:**
+```
+Harmony Score = 1 / (1 + distance(Intent, Execution))
+
+Where:
+  distance = Euclidean distance in 4D semantic space
+  High distance = Low harmony (disharmony)
+  Low distance = High harmony
+```
+
+### Why Semantic Matters
+
+**Semantics = meaning in language**
+
+**In code:**
+- Function **names** communicate meaning
+- Function **bodies** execute meaning
+- **Alignment** = semantic harmony
+- **Contradiction** = semantic disharmony
+
+**Example of semantic contradiction:**
+```python
+def validate_email(email):
+    # "validate" MEANS check/verify (Justice/Wisdom)
+    send_email(email)
+    # "send" MEANS transmit/act (Power)
+    # SEMANTIC CONTRADICTION
+```
+
+### The Bug is in the Meaning
+
+**Traditional bugs:** Code doesn't execute correctly
+**Semantic bugs:** Code executes but means something wrong
+
+**Example:**
+```python
+def check_permissions(user):
+    """Verify user has required permissions"""
+    user.permissions = "admin"  # BUG: Checking or GRANTING?
+```
+
+- **Syntactically correct:** Valid Python ✓
+- **Functionally working:** Runs without error ✓
+- **Semantically wrong:** Name says "check" but code "grants" ✗
+
+**This is a semantic bug** - the kind traditional tools miss.
+
+### Semantic Distance as Bug Indicator
+
+**Hypothesis:** High semantic distance between Intent and Execution correlates with bugs.
+
+**Evidence:**
+1. **Confusion bugs**: Misleading names cause developer mistakes
+2. **Refactoring bugs**: Function grows beyond original intent, name never updated
+3. **API bugs**: Public functions promise one thing, deliver another
+4. **Logic bugs**: Implementation doesn't match specified purpose
+
+**Practical insight:**
+```
+High disharmony score → Investigate function
+                      → Often reveals actual bug or design issue
+```
+
+### The Four Types of Disharmony
+
+**1. Action Contradiction**
+```python
+def get_data():
+    delete_data()  # "get" vs "delete" - opposite actions
+```
+**Semantic distance:** Very high (retrieve vs destroy)
+
+**2. Scope Mismatch**
+```python
+def delete_session(session_id):
+    delete_user(session_id)  # Deletes MORE than promised
+```
+**Semantic distance:** Moderate (broader scope than intended)
+
+**3. Purpose Drift**
+```python
+def validate_input(data):
+    sanitize(data)
+    transform(data)
+    save(data)  # Now doing 3 different things
+```
+**Semantic distance:** Moderate (validation + action + persistence)
+
+**4. Vague Naming**
+```python
+def process_data(data):
+    db.drop_all_tables()  # "process" too vague for destructive action
+```
+**Semantic distance:** Variable (vague intent, specific execution)
+
+---
+
+## The DIVE-V2 Engine
+
+### What Is DIVE-V2?
+
+**Divine Invitation Semantic Engine (Version 2)** - the semantic analysis engine powering Python Code Harmonizer.
+
+**Purpose:** Map natural language concepts to 4-dimensional semantic coordinates.
+
+**Components:**
+1. **Vocabulary Manager**: Maps keywords to dimensions
+2. **Semantic Analyzer**: Calculates concept clusters and centroids
+3. **ICE Analyzer**: Performs Intent-Context-Execution analysis
+4. **Mathematical Calculator**: Computes distances and harmony scores
+
+### How DIVE-V2 Works
+
+**Step 1: Vocabulary Mapping**
+
+```python
+# Predefined semantic mappings
+"get" → (L=0.1, J=0.2, P=0.0, W=0.7)     # Wisdom-focused
+"delete" → (L=0.0, J=0.2, P=0.8, W=0.0)  # Power-focused
+"validate" → (L=0.1, J=0.7, P=0.1, W=0.2) # Justice-focused
+```
+
+**113 core concepts** mapped to semantic coordinates
+
+**Step 2: Text Analysis**
+
+```python
+text = "get user information"
+words = ["get", "user", "information"]
+
+# Look up each word
+get_coords = (0.1, 0.2, 0.0, 0.7)
+user_coords = (0.3, 0.2, 0.1, 0.4)
+info_coords = (0.1, 0.1, 0.0, 0.8)
+
+# Calculate centroid
+centroid = average(get_coords, user_coords, info_coords)
+```
+
+**Step 3: Distance Calculation**
+
+```python
+intent_coords = analyze_text(function_name)
+execution_coords = analyze_text(function_body_operations)
+
+distance = euclidean_distance(intent_coords, execution_coords)
+```
+
+**Step 4: Harmony Scoring**
+
+```python
+if distance > threshold:
+    status = "DISHARMONY"
+else:
+    status = "HARMONIOUS"
+```
+
+### Why "Divine Invitation"?
+
+The name reflects the philosophical foundation:
+
+**Divine** = Anchored to (1,1,1,1), the perfect ideal
+**Invitation** = The system invites consciousness toward harmony
+**Semantic** = Works with meaning, not just syntax
+**Engine** = Performs consistent, reliable analysis
+
+**The invitation:** Move toward the Anchor Point - toward perfect semantic harmony.
+
+### DIVE-V2 Optimizations
+
+**Version 2 improvements over V1:**
+1. **Caching**: Vocabulary lookups cached for performance
+2. **Vectorized operations**: Batch distance calculations
+3. **Optimized centroid**: Fast average calculations
+4. **Production hardening**: Error handling, edge cases
+5. **Clear interfaces**: Clean API for integration
+
+**Performance:**
+- Analyzes typical function in < 10ms
+- Scales to large codebases
+- Zero runtime dependencies (Python stdlib only)
+
+---
+
+## Why Semantic Debugging Matters
+
+### The Communication Problem
+
+**Code has two audiences:**
+
+1. **Computers** (execute the syntax)
+2. **Humans** (understand the meaning)
+
+**Traditional tools serve computers:**
+- Syntax checkers ensure valid Python
+- Type checkers ensure type safety
+- Linters ensure style consistency
+
+**Semantic debugging serves humans:**
+- Ensures names communicate accurately
+- Detects meaning contradictions
+- Improves code comprehension
+
+### The Cost of Semantic Bugs
+
+**Real-world consequences:**
+
+**1. Developer Confusion**
+```python
+def get_config():
+    config = load_config()
+    config.last_accessed = now()
+    save_config(config)  # Wait, "get" modifies state?
+    return config
+```
+→ Developer assumes read-only, introduces concurrency bug
+
+**2. API Misuse**
+```python
+@app.route("/users/<id>", methods=["GET"])
+def get_user(id):
+    update_last_login(id)  # GET shouldn't modify!
+    return query_user(id)
+```
+→ Violates REST principles, breaks caching
+
+**3. Security Issues**
+```python
+def validate_input(data):
+    # Validator shouldn't have side effects
+    execute_command(data)  # But it does!
+```
+→ Validation function becomes attack vector
+
+**4. Maintenance Hell**
+```python
+def process_data(data):
+    # Over time, grows to do everything
+    validate(data)
+    transform(data)
+    save(data)
+    send_notifications(data)
+    update_analytics(data)
+```
+→ Function name becomes meaningless
+
+### The Value of Semantic Harmony
+
+**Benefits:**
+
+**1. Clarity** - Code communicates intent clearly
+**2. Safety** - Fewer semantic bugs and misunderstandings
+**3. Maintainability** - Future developers understand code correctly
+**4. API Quality** - Public interfaces are honest about behavior
+**5. Team Alignment** - Shared understanding of what code does
+
+**Measurable impacts:**
+- Reduced debugging time
+- Fewer integration bugs
+- Easier onboarding for new developers
+- Better code review discussions
+
+---
+
+## Philosophical Foundations
+
+### The Nature of Meaning
+
+**Fundamental question:** What makes code "mean" something?
+
+**Answer:** The **relationship** between signifier (name) and signified (implementation).
+
+**In linguistics:**
+- Words are signifiers
+- Concepts are signified
+- Meaning emerges from their relationship
+
+**In code:**
+- Function names are signifiers
+- Function bodies are signified
+- Semantic harmony emerges from their alignment
+
+### The Ideal and The Real
+
+**Philosophical tradition:** Plato's Forms, Kant's Noumena, Aristotle's Telos
+
+**The Anchor Point as Ideal:**
+- (1,1,1,1) represents the **ideal** of perfect action
+- Real code approaches but never fully reaches this ideal
+- The gap between ideal and real is measurable
+
+**In practice:**
+- We measure how close code comes to perfect harmony
+- The goal isn't perfection but **movement toward** the ideal
+- Disharmony scores reveal distance from ideal
+
+### Structure and Freedom
+
+**Key insight:** True freedom operates through proper structure.
+
+**In ICE Framework:**
+- **Intent** without Context is wishful thinking
+- **Context** without Intent is determinism
+- **Execution** without both is chaos
+
+**Freedom = Intent applied through Context to Execution**
+
+**In code:**
+- Functions need clear intent (freedom to act meaningfully)
+- Constrained by context (reality/truth)
+- Executed with power (capability manifested)
+
+**Harmony = Freedom expressed through proper structure**
+
+### The Unity of Truth, Beauty, and Goodness
+
+**Classical philosophy:** Three transcendentals - Truth, Beauty, Goodness
+
+**In the Four Dimensions:**
+- **Truth** = Justice (J)
+- **Beauty** = Harmony (L+J+P+W in balance)
+- **Goodness** = Love (L) + Wisdom (W) in Intent
+
+**Semantically harmonious code embodies all three:**
+- **True** (accurately named)
+- **Beautiful** (well-structured, coherent)
+- **Good** (serves proper purpose)
+
+---
+
+## Practical Applications
+
+### Beyond Code: Universal Framework
+
+**The ICE Framework applies to all meaningful action:**
+
+**Personal decisions:**
+- Intent: What do I want to achieve?
+- Context: What's actually true about my situation?
+- Execution: What can I actually do?
+
+**Team projects:**
+- Intent: What's our goal?
+- Context: What resources/constraints exist?
+- Execution: What actions will we take?
+
+**Organizational strategy:**
+- Intent: What's our mission?
+- Context: What's our market reality?
+- Execution: What capabilities do we deploy?
+
+### Measuring Alignment
+
+**The Anchor Point as universal reference:**
+
+Any meaningful action can be plotted in L-J-P-W space and measured against (1,1,1,1).
+
+**Applications:**
+- **Code quality** (this tool)
+- **Decision quality** (personal/organizational)
+- **Communication quality** (meaning alignment)
+- **Design quality** (form matches function)
+
+### The Goal: Movement Toward Harmony
+
+**Not perfection, but direction:**
+
+The goal isn't to achieve (1,1,1,1) perfectly - it's to **move toward** it consistently.
+
+**In code:**
+- Not every function scores 0.0
+- But functions should trend toward lower disharmony
+- Refactoring improves semantic alignment
+- Over time, codebase becomes more harmonious
+
+**In life:**
+- Not every action is perfectly harmonious
+- But we can consistently improve alignment
+- Intent, Context, Execution can be brought into better harmony
+- Movement toward the Anchor Point is itself meaningful
+
+---
+
+## Conclusion
+
+Python Code Harmonizer is built on a profound philosophical framework:
+
+**The Anchor Point (1,1,1,1)** - The ideal of perfect harmony
+**The Four Dimensions (L-J-P-W)** - The structure of all meaning
+**The ICE Framework** - The process of all meaningful action
+**Semantic Harmony** - The alignment of meaning and reality
+
+**What makes this powerful:**
+
+Not just theory - it's **applied philosophy** that produces practical results.
+
+Not just syntax - it's **meaning** that serves humans.
+
+Not just tool - it's a **lens** for seeing code differently.
+
+**The invitation:**
+
+Move toward harmony.
+Align intent with execution.
+Let your code's names tell the truth.
+**Approach the Anchor Point.**
+
+---
+
+**For more information:**
+- [User Guide](USER_GUIDE.md) - How to use the tool
+- [Tutorial](TUTORIAL.md) - Hands-on examples
+- [Architecture](ARCHITECTURE.md) - Technical implementation
+- [FAQ](FAQ.md) - Common questions
+
+---
+
+*"Does your code do what its name says it does?"*
+
+*If yes, you have harmony. If no, you have a bug.*
+
+*The Anchor Point awaits.* 💛⚓