diff --git a/.claude/agents/docs.md b/.claude/agents/docs.md
index eff9e3a..b2026c7 100644
--- a/.claude/agents/docs.md
+++ b/.claude/agents/docs.md
@@ -71,7 +71,7 @@ You are a specialized documentation agent for the Statifier SCXML library with e
 
 ## Specialized Tasks
 
-- Migrate existing CLAUDE.md content to structured Diataxis documentation
+- Migrate existing CLAUDE.md and README.md content to structured Diataxis documentation
 - Create interactive SCXML examples with state machine visualizations
 - Generate API documentation from Elixir modules with @doc annotations
 - Develop tutorial series progressing from basic to advanced state machine concepts
diff --git a/.credo.exs b/.credo.exs
index 1e5371e..8c0278c 100644
--- a/.credo.exs
+++ b/.credo.exs
@@ -27,7 +27,7 @@
           "src/",
           "test/"
         ],
-        excluded: [~r"/lib/mix/test", ~r"/lib/mix/quality", ~r"/_build/", ~r"/deps/", ~r"/node_modules/"]
+        excluded: [~r"/lib/mix", ~r"/_build/", ~r"/deps/", ~r"/node_modules/"]
       },
       #
       # Load and configure plugins here:
diff --git a/.dialyzer_ignore.exs b/.dialyzer_ignore.exs
new file mode 100644
index 0000000..5766bde
--- /dev/null
+++ b/.dialyzer_ignore.exs
@@ -0,0 +1,4 @@
+[
+  # Ignore all Mix tasks - these are development tools, not core library functionality
+  ~r/lib\/mix\/tasks\/.*/
+]
\ No newline at end of file
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c1ebbd1..883944c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -224,3 +224,39 @@ jobs:
 
     - name: Run regression tests
       run: mix test.regression
+
+  example-tests:
+    name: Examples Test Suite
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: examples
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Elixir
+      uses: erlef/setup-beam@v1
+      with:
+        elixir-version: '1.18.3'
+        otp-version: '27.3'
+
+    - name: Cache deps
+      uses: actions/cache@v4
+      with:
+        path: |
+          examples/deps
+          examples/_build
+        key: example-deps-${{ runner.os }}-27.3-1.18.3-${{ hashFiles('examples/**/mix.lock') }}
+        restore-keys: |
+          example-deps-${{ runner.os }}-27.3-1.18.3-
+
+    - name: Install dependencies
+      run: mix deps.get
+
+    - name: Compile project
+      run: mix compile
+
+    - name: Run tests
+      run: mix test
diff --git a/.gitignore b/.gitignore
index 19e950a..a8abf1e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -21,6 +21,7 @@ erl_crash.dump
 
 # Generated docs site
 /docs/.vitepress/dist
+/docs/.vitepress/cache
 
 # Ignore package tarball (built via "mix hex.build").
 statifier-*.tar
diff --git a/CLAUDE.md b/CLAUDE.md
index 4035a59..933ec6d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -42,6 +42,13 @@ When verifying code changes, always follow this sequence (also automated via pre
 - `mix test test/statifier/logging/` - Run comprehensive logging infrastructure tests (30 tests)
 - `mix test test/statifier/actions/` - Run action execution tests with integrated StateChart logging
 
+**Documentation:**
+
+- `mix docs.validate` - Validate code examples in documentation files (README.md, docs/*.md)
+- `mix docs.validate --file README.md` - Validate specific file only
+- `mix docs.validate --verbose` - Show detailed validation output
+- `mix docs.validate --path docs/` - Validate specific directory
+
 **Development:**
 
 - `mix deps.get` - Install dependencies
@@ -214,7 +221,7 @@ The implementation follows a clean **Parse → Validate → Optimize** architect
 {:ok, optimized_document, warnings} = Statifier.Validator.validate(document)
 
 # 3. Interpret Phase: Use optimized document for runtime
-{:ok, state_chart} = Statifier.Interpreter.initialize(optimized_document)
+{:ok, state_chart} = Statifier.initialize(optimized_document)
 ```
 
 **Benefits:**
@@ -376,7 +383,7 @@ invoke_handlers = %{
   "email_service" => &MyApp.EmailService.handle_invoke/3
 }
 
-{:ok, state_chart} = Interpreter.initialize(document, [
+{:ok, state_chart} = Statifier.initialize(document, [
   invoke_handlers: invoke_handlers,
   log_level: :debug
 ])
@@ -629,13 +636,13 @@ When debugging state chart execution, configure enhanced logging for detailed vi
 
 ```elixir
 # Enable detailed tracing for debugging
-{:ok, state_chart} = Interpreter.initialize(document, [
+{:ok, state_chart} = Statifier.initialize(document, [
   log_adapter: :elixir,
   log_level: :trace
 ])
 
 # Alternative: use internal adapter for testing/development
-{:ok, state_chart} = Interpreter.initialize(document, [
+{:ok, state_chart} = Statifier.initialize(document, [
   log_adapter: :internal,  
   log_level: :trace
 ])
@@ -697,10 +704,10 @@ config :statifier,
 ```elixir
 # In dev environment, no additional configuration needed
 {:ok, document, _warnings} = Statifier.parse(xml)
-{:ok, state_chart} = Interpreter.initialize(document)  # Auto-configured for dev
+{:ok, state_chart} = Statifier.initialize(document)  # Auto-configured for dev
 
 # Manual configuration for other environments
-{:ok, state_chart} = Interpreter.initialize(document, [
+{:ok, state_chart} = Statifier.initialize(document, [
   log_adapter: :elixir,
   log_level: :trace
 ])
diff --git a/README.md b/README.md
index dc8aa08..e3f53a0 100644
--- a/README.md
+++ b/README.md
@@ -72,666 +72,78 @@ An Elixir implementation of SCXML (State Chart XML) state charts with a focus on
 - Enhanced datamodel support with JavaScript expression engine
 - Enhanced validation for complex SCXML constructs
 
-## Recent Completions
+## Documentation
 
-### **✅ Secure Invoke System with Centralized Parameters (v1.9.0)**
+For comprehensive guides, examples, and technical details, see the [Statifier Documentation](https://riddler.github.io/statifier):
 
-- **`Handler-Based Security`** - Replaces dangerous arbitrary function execution with secure handler registration system
-- **`SCXML Event Compliance`** - Generates proper `done.invoke.{id}`, `error.execution`, and `error.communication` events per specification
-- **`Centralized Parameter Processing`** - Unified `<param>` evaluation with strict (InvokeAction) and lenient (SendAction) error handling modes  
-- **`External Service Integration`** - Safe way to integrate SCXML state machines with external services and APIs
-- **`Complete Test Coverage`** - InvokeAction and InvokeHandler modules achieve 100% test coverage
-- **`Parameter Architecture Refactor`** - Consolidated parameter evaluation logic removes code duplication across actions
+- **[Getting Started](https://riddler.github.io/statifier/getting-started)** - Build your first state machine with working examples
+- **[External Services](https://riddler.github.io/statifier/external-services)** - Secure integration with APIs and external systems  
+- **[Changelog](https://riddler.github.io/statifier/changelog)** - Recent major feature completions
+- **[Roadmap](https://riddler.github.io/statifier/roadmap)** - Planned features and priorities
 
-### **✅ Complete History State Support (v1.4.0)**
-
-- **`Shallow History`** - Records and restores immediate children of parent states that contain active descendants
-- **`Deep History`** - Records and restores all atomic descendant states within parent states
-- **`History Tracking`** - Complete `Statifier.HistoryTracker` module with efficient MapSet operations
-- **`History Validation`** - Comprehensive `Statifier.Validator.HistoryStateValidator` with W3C specification compliance
-- **`History Resolution`** - Full W3C SCXML compliant history state transition resolution during interpreter execution
-- **`StateChart Integration`** - History tracking integrated into StateChart lifecycle with recording before onexit actions
-- **`SCION Test Coverage`** - Major improvement in SCION history test compliance (5/8 tests now passing)
-
-### **✅ Multiple Transition Target Support (v1.4.0)**
-
-- **`Space-Separated Parsing`** - Handles `target="state1 state2 state3"` syntax with proper whitespace splitting
-- **`API Enhancement`** - `Statifier.Transition.targets` field (list) replaces `target` field (string) for better readability
-- **`Validator Updates`** - All transition validators updated for list-based target validation with comprehensive testing
-- **`Parallel State Fixes`** - Critical parallel state exit logic improvements with proper W3C SCXML exit set computation
-- **`SCION Compatibility`** - history4b and history5 SCION tests now pass completely with multiple target support
-
-### **✅ SCXML-Compliant Processing Engine**
-
-- **`Microstep/Macrostep Execution`** - Implements SCXML event processing model with microstep (single transition set execution) and macrostep (series of microsteps until stable)
-- **`Eventless Transitions`** - Transitions without event attributes (called NULL transitions in SCXML spec) that fire automatically upon state entry
-- **`Exit Set Computation`** - Implements W3C SCXML exit set calculation algorithm for determining which states to exit during transitions
-- **`LCCA Algorithm`** - Full Least Common Compound Ancestor computation for accurate transition conflict resolution and exit set calculation
-- **`Cycle Detection`** - Prevents infinite loops with configurable iteration limits (100 iterations default)
-- **`Parallel Region Preservation`** - Proper SCXML exit semantics for transitions within and across parallel regions
-- **`Optimal Transition Set`** - SCXML-compliant transition conflict resolution where child state transitions take priority over ancestors
-
-### **✅ Enhanced Parallel State Support**
-
-- **`Cross-Parallel Boundaries`** - Proper exit semantics when transitions leave parallel regions
-- **`Sibling State Management`** - Automatic exit of parallel siblings when transitions exit their shared parent  
-- **`Self-Transitions`** - Transitions within parallel regions preserve unaffected parallel regions
-- **`Parallel Ancestor Detection`** - New functions for identifying parallel ancestors and region relationships
-- **`Enhanced Exit Logic`** - All parallel regions properly exited when transitioning to external states
-
-### **✅ Feature-Based Test Validation System**
-
-- **`Statifier.FeatureDetector`** - Analyzes SCXML documents to detect used features
-- **Feature validation** - Tests fail when they depend on unsupported features  
-- **False positive prevention** - No more "passing" tests that silently ignore unsupported features
-- **Capability tracking** - Clear visibility into which SCXML features are supported
-
-### **✅ Modular Validator Architecture**
-
-- **`Statifier.Validator`** - Main orchestrator (from 386-line monolith)
-- **`Statifier.Validator.StateValidator`** - State ID validation
-- **`Statifier.Validator.TransitionValidator`** - Transition target validation  
-- **`Statifier.Validator.InitialStateValidator`** - All initial state constraints
-- **`Statifier.Validator.ReachabilityAnalyzer`** - State reachability analysis
-- **`Statifier.Validator.Utils`** - Shared utilities
-
-### **✅ Initial State Elements**
-
-- **Parser support** - `<initial>` elements with `<transition>` children
-- **Interpreter logic** - Proper initial state entry via initial elements
-- **Comprehensive validation** - Conflict detection, target validation, structure validation
-- **Feature detection** - Automatic detection of initial element usage
-
-## Future Extensions
-
-The next major areas for development focus on expanding SCXML feature support:
-
-### **High Priority Features**
-
-- **Executable Content** - `<script>` elements (`<onentry>`, `<onexit>`, `<assign>` now supported!)
-- **History States** - Shallow and deep history state support
-
-### **Medium Priority Features**  
-
-- **Internal Transitions** - `type="internal"` transition support
-- **Targetless Transitions** - Transitions without target for pure actions
-- **Enhanced Error Handling** - Better error messages with source locations
-- **Performance Benchmarking** - Establish performance baselines and optimize hot paths
-
-## Usage Examples
-
-### Secure Invoke System
-
-The invoke system allows SCXML state machines to safely integrate with external services:
-
-```elixir
-# Define a secure handler
-defmodule MyApp.UserService do
-  def handle_invoke("create_user", params, state_chart) do
-    case create_user(params["name"], params["email"]) do
-      {:ok, user} -> 
-        {:ok, %{"user_id" => user.id}, state_chart}
-      {:error, reason} -> 
-        {:error, :execution, "User creation failed: #{reason}"}
-    end
-  end
-  
-  def handle_invoke(operation, _params, _state_chart) do
-    {:error, :execution, "Unknown operation: #{operation}"}
-  end
-end
-
-# Register handlers during StateChart initialization  
-invoke_handlers = %{
-  "user_service" => &MyApp.UserService.handle_invoke/3
-}
-
-{:ok, state_chart} = Interpreter.initialize(document, [
-  invoke_handlers: invoke_handlers
-])
-```
-
-```xml
-<!-- SCXML usage -->
-<state id="creating_user">
-  <onentry>
-    <invoke type="user_service" src="create_user" id="user_creation">
-      <param name="name" expr="user_name"/>
-      <param name="email" expr="user_email"/>
-    </invoke>
-  </onentry>
-  
-  <transition event="done.invoke.user_creation" target="success"/>
-  <transition event="error.execution" target="failed"/>
-</state>
-```
-
-## Installation
-
-Add `statifier` to your list of dependencies in `mix.exs`:
-
-```elixir
-def deps do
-  [
-    {:statifier, "~> 1.8"}
-  ]
-end
-```
-
-## Usage
-
-### Basic Example
-
-```elixir
-# Parse SCXML document
-xml = """
-<?xml version="1.0" encoding="UTF-8"?>
-<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" initial="start">
-  <state id="start">
-    <transition event="go" target="end"/>
-  </state>
-  <state id="end"/>
-</scxml>
-"""
-
-{:ok, document} = Statifier.parse(xml)
-
-# Initialize state chart
-{:ok, state_chart} = Statifier.Interpreter.initialize(document)
-
-# Check active states
-active_states = Statifier.Configuration.active_leaf_states(state_chart.configuration)
-# Returns: MapSet.new(["start"])
-
-# Send event
-event = Statifier.Event.new("go")
-{:ok, new_state_chart} = Statifier.Interpreter.send_event(state_chart, event)
-
-# Check new active states
-active_states = Statifier.Configuration.active_leaf_states(new_state_chart.configuration)
-# Returns: MapSet.new(["end"])
-```
-
-### Eventless Transitions Example
-
-```elixir
-# Automatic transitions without events fire immediately
-xml = """
-<?xml version="1.0" encoding="UTF-8"?>
-<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" initial="start">
-  <state id="start">
-    <transition target="processing"/>  <!-- No event - fires automatically -->
-  </state>
-  <state id="processing">
-    <transition target="done" cond="ready == true"/>  <!-- Conditional eventless -->
-  </state>
-  <state id="done"/>
-</scxml>
-"""
-
-{:ok, document} = Statifier.parse(xml)
-{:ok, state_chart} = Statifier.Interpreter.initialize(document)
-
-# Eventless transitions processed automatically during initialization
-active_states = Statifier.Configuration.active_leaf_states(state_chart.configuration)
-# Returns: MapSet.new(["processing"]) - automatically moved from start
-```
-
-### Parallel States Example
-
-```elixir
-xml = """
-<?xml version="1.0" encoding="UTF-8"?>
-<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0">
-  <parallel id="app">
-    <state id="ui" initial="idle">
-      <state id="idle">
-        <transition event="click" target="busy"/>
-      </state>
-      <state id="busy">
-        <transition event="done" target="idle"/>
-      </state>
-    </state>
-    <state id="network" initial="offline">
-      <state id="offline">
-        <transition event="connect" target="online"/>
-      </state>
-      <state id="online"/>
-    </state>
-  </parallel>
-</scxml>
-"""
-
-{:ok, document} = Statifier.parse(xml)
-{:ok, state_chart} = Statifier.Interpreter.initialize(document)
-
-# Both parallel regions active simultaneously
-active_states = Statifier.Configuration.active_leaf_states(state_chart.configuration)
-# Returns: MapSet.new(["idle", "offline"])
-```
-
-### History States Example
-
-```elixir
-# SCXML with shallow and deep history states
-xml = """
-<?xml version="1.0" encoding="UTF-8"?>
-<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" initial="main">
-  <state id="main" initial="sub1">
-    <!-- Shallow history - restores immediate children -->
-    <history id="main_hist" type="shallow">
-      <transition target="sub1"/>  <!-- Default when no history -->
-    </history>
-    
-    <state id="sub1">
-      <transition event="go" target="sub2"/>
-    </state>
-    
-    <state id="sub2">  
-      <transition event="go" target="sub3"/>
-    </state>
-    
-    <state id="sub3">
-      <transition event="exit" target="other"/>
-      <transition event="back" target="main_hist"/>  <!-- Restore history -->
-    </state>
-  </state>
-  
-  <state id="other">
-    <transition event="return" target="main_hist"/>  <!-- Restore to last sub-state -->
-  </state>
-</scxml>
-"""
-
-{:ok, document} = Statifier.parse(xml)
-{:ok, state_chart} = Statifier.Interpreter.initialize(document)
-
-# Progress through states
-{:ok, state_chart} = Statifier.Interpreter.send_event(state_chart, Statifier.Event.new("go"))
-{:ok, state_chart} = Statifier.Interpreter.send_event(state_chart, Statifier.Event.new("go"))
-# Active states: ["sub3"]
-
-{:ok, state_chart} = Statifier.Interpreter.send_event(state_chart, Statifier.Event.new("exit"))  
-# Active states: ["other"] - history recorded
-
-{:ok, state_chart} = Statifier.Interpreter.send_event(state_chart, Statifier.Event.new("return"))
-# Active states: ["sub3"] - history restored!
-```
-
-### Multiple Transition Targets Example
+## Quick Example
 
 ```elixir
-# SCXML with multiple target transitions
+# Simple traffic light state machine
 xml = """
 <?xml version="1.0" encoding="UTF-8"?>
-<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" initial="start">
-  <state id="start">
-    <!-- Multiple targets - enter multiple states simultaneously -->
-    <transition event="activate" target="system target1 target2"/>
+<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" initial="red">
+  <state id="red">
+    <transition event="timer" target="green"/>
   </state>
-  
-  <parallel id="system">
-    <state id="target1">
-      <transition event="done" target="end"/>
-    </state>
-    
-    <state id="target2">
-      <transition event="done" target="end"/>
-    </state>
-  </parallel>
-  
-  <state id="end"/>
-</scxml>
-"""
-
-{:ok, document} = Statifier.parse(xml)
-{:ok, state_chart} = Statifier.Interpreter.initialize(document)
-
-# Send activate event - enters multiple targets
-{:ok, state_chart} = Statifier.Interpreter.send_event(state_chart, Statifier.Event.new("activate"))
-
-# Check active states - multiple states active simultaneously
-active_states = Statifier.Configuration.active_leaf_states(state_chart.configuration)
-# Returns: MapSet.new(["target1", "target2"]) - both targets entered
-```
-
-### Document Validation
-
-```elixir
-{:ok, document} = Statifier.parse(xml)
-
-case Statifier.Validator.validate(document) do
-  {:ok, optimized_document, warnings} -> 
-    # Document is valid and optimized, warnings are non-fatal
-    IO.puts("Valid document with #{length(warnings)} warnings")
-    # optimized_document now has O(1) lookup maps built
-  {:error, errors, warnings} ->
-    # Document has validation errors
-    IO.puts("Validation failed with #{length(errors)} errors")
-end
-```
-
-### Assign Elements Example
-
-```elixir
-# SCXML with assign elements for dynamic data manipulation
-xml = """
-<?xml version="1.0" encoding="UTF-8"?>
-<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" initial="start">
-  <state id="start">
-    <onentry>
-      <assign location="userName" expr="'John Doe'"/>
-      <assign location="counter" expr="42"/>
-      <assign location="user.profile.name" expr="'Jane Smith'"/>
-      <assign location="users['admin'].active" expr="true"/>
-    </onentry>
-    <transition target="working"/>
+  <state id="green">
+    <transition event="timer" target="yellow"/>
   </state>
-  
-  <state id="working">
-    <onentry>
-      <assign location="counter" expr="counter + 1"/>
-      <assign location="status" expr="'processing'"/>
-    </onentry>
-    <onexit>
-      <assign location="status" expr="'completed'"/>
-    </onexit>
-    <transition event="finish" target="done"/>
+  <state id="yellow">
+    <transition event="timer" target="red"/>
   </state>
-  
-  <final id="done"/>
 </scxml>
 """
 
-{:ok, document} = Statifier.parse(xml)
-{:ok, state_chart} = Statifier.Interpreter.initialize(document)
+# Parse and initialize
+{:ok, document, _warnings} = Statifier.parse(xml)
+{:ok, state_chart} = Statifier.initialize(document)
 
-# Check the data model after onentry execution
-datamodel = state_chart.datamodel
-# Returns: %{
-#   "userName" => "John Doe",
-#   "counter" => 43,  # incremented to 43 in working state
-#   "user" => %{"profile" => %{"name" => "Jane Smith"}},
-#   "users" => %{"admin" => %{"active" => true}},
-#   "status" => "processing"
-# }
+# Send events to transition between states  
+{:ok, state_chart} = Statifier.send_sync(state_chart, "timer")
 ```
 
-### Logging and Test Environment
+## Installation
 
-Statifier includes a comprehensive logging system designed for both production use and clean test environments:
+Add `statifier` to your list of dependencies in `mix.exs`:
 
 ```elixir
-# Production logging with Elixir Logger integration
-{:ok, document} = Statifier.parse(xml)
-{:ok, state_chart} = Statifier.Interpreter.initialize(document, [
-  log_adapter: {Statifier.Logging.ElixirLoggerAdapter, []},
-  log_level: :info
-])
-
-# Test environment automatically uses TestAdapter (configured in test/test_helper.exs)
-# for clean output and log inspection
-
-# Using log helpers in tests
-defmodule MyStateMachineTest do
-  use Statifier.Case  # Provides logging test helpers
-
-  test "action execution with logging" do
-    xml = """
-    <scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" initial="start">
-      <state id="start">
-        <onentry>
-          <log expr="'Starting process'"/>
-          <assign location="status" expr="'active'"/>
-        </onentry>
-        <transition event="go" target="done"/>
-      </state>
-      <state id="done"/>
-    </scxml>
-    """
-    
-    {:ok, state_chart} = test_scxml(xml, "logging test", ["start"], [
-      {%{"name" => "go"}, ["done"]}
-    ])
-    
-    # Assert specific log entries were created
-    assert_log_entry(state_chart, message_contains: "Starting process")
-    assert_log_entry(state_chart, level: :debug, action_type: "assign_action")
-    
-    # Verify logs appear in chronological order
-    assert_log_order(state_chart, [
-      [message_contains: "Starting process"],
-      [action_type: "assign_action"]
-    ])
-  end
+def deps do
+  [
+    {:statifier, "~> 1.8"}
+  ]
 end
 ```
 
-**Key logging features:**
-
-- **Clean test output**: No log pollution in test console
-- **Structured metadata**: All logs include contextual information (state_id, action_type, phase)
-- **Chronological storage**: Logs stored oldest-first for intuitive debugging
-- **Test helpers**: `assert_log_entry()` and `assert_log_order()` for easy log verification
-- **Production integration**: ElixirLoggerAdapter integrates seamlessly with existing Logger setup
-
-## Development
-
-### Requirements
-
-- Elixir 1.17+
-- Erlang/OTP 26+
-
-### Setup
-
-```bash
-mix deps.get
-mix compile
-```
-
-### Code Quality Workflow
-
-The project maintains high code quality through automated checks:
-
-```bash
-# Local validation workflow (also runs via pre-push hook)
-mix format              # Auto-fix formatting
-mix test.regression     # Run critical regression tests (22 tests)
-mix credo --strict      # Static code analysis
-mix dialyzer            # Type checking
-```
-
-### Regression Testing
-
-The project uses automated regression testing to prevent breaking existing functionality:
-
-```bash
-# Run only tests that should always pass (118 tests)
-mix test.regression
-
-# Check which tests are currently passing to update regression suite
-mix test.baseline
-
-# Install git hooks for automated validation
-./scripts/setup-git-hooks.sh
-```
-
-The regression suite tracks:
+For comprehensive examples and usage patterns, see the [Getting Started Guide](https://riddler.github.io/statifier/getting-started).
 
-- **Internal tests**: All `test/statifier/**/*_test.exs` files (707 total tests) - comprehensive edge case coverage
-- **SCION tests**: Multiple passing tests including history, parallel, and conditional features
-- **W3C tests**: Several passing tests with continued improvement
-
-### Running Tests
-
-```bash
-# All internal tests (excludes SCION/W3C by default) - 707 tests
-mix test
-
-# All tests including SCION and W3C test suites
-mix test --include scion --include scxml_w3
-
-# Only regression tests (118 critical tests)
-mix test.regression
-
-# With coverage reporting
-mix coveralls
-
-# Specific test categories
-mix test --include scion test/scion_tests/history/
-mix test test/statifier/parser/scxml_test.exs
-mix test test/statifier/history/
-```
-
-## Architecture
-
-### Core Components
-
-- **`Statifier.Parser.SCXML`** - SAX-based XML parser with location tracking (parse phase)
-- **`Statifier.Validator`** - Modular validation orchestrator with focused sub-validators (validate + optimize phases)
-- **`Statifier.Validator.HistoryStateValidator`** - Dedicated validator for history state constraints and W3C compliance
-- **`Statifier.FeatureDetector`** - SCXML feature detection for test validation and capability tracking
-- **`Statifier.Interpreter`** - Synchronous state chart interpreter with compound state and history support
-- **`Statifier.StateChart`** - Runtime container with event queues and history tracking
-- **`Statifier.HistoryTracker`** - Core history state tracking with efficient MapSet operations
-- **`Statifier.Configuration`** - Active state management (leaf states only)
-- **`Statifier.Event`** - Event representation with origin tracking
-
-### Data Structures
-
-- **`Statifier.Document`** - Root SCXML document with states, metadata, O(1) lookup maps, and history helper functions
-- **`Statifier.State`** - Individual states with transitions, hierarchical nesting, and history type support
-- **`Statifier.Transition`** - State transitions with events and multiple targets (list-based)
-- **`Statifier.Data`** - Datamodel elements with expressions
-
-### Architecture Flow
-
-```elixir
-# 1. Parse: XML → Document structure
-{:ok, document} = Statifier.parse(xml)
-
-# 2. Validate: Check semantics + optimize with lookup maps  
-{:ok, optimized_document, warnings} = Statifier.Validator.validate(document)
-
-# 3. Interpret: Run state chart with optimized lookups
-{:ok, state_chart} = Statifier.Interpreter.initialize(optimized_document)
-```
-
-## Performance Optimizations
-
-The implementation includes several key optimizations for production use:
-
-### **O(1) State and Transition Lookups**
-
-- **State Lookup Map**: `%{state_id => state}` for instant state access
-- **Transition Lookup Map**: `%{state_id => [transitions]}` for fast transition queries  
-- **Built During Validation**: Lookup maps only created for valid documents
-- **Memory Efficient**: Uses existing document structure, no duplication
-
-### **Compound and Parallel State Entry**
-
-```elixir
-# Automatic hierarchical entry
-{:ok, state_chart} = Statifier.Interpreter.initialize(document)
-active_states = Statifier.Configuration.active_leaf_states(state_chart.configuration)
-# Returns only leaf states (compound/parallel states entered automatically)
-
-# Fast ancestor computation when needed
-ancestors = Statifier.Configuration.all_active_states(state_chart.configuration, state_chart.document) 
-# O(1) state lookups + O(d) ancestor traversal
-
-# Parallel states enter ALL child regions simultaneously
-# Compound states enter initial child recursively
-```
-
-### **Parse → Validate → Optimize Flow**
-
-- **Separation of Concerns**: Parser focuses on structure, validator on semantics
-- **Conditional Optimization**: Only builds lookup maps for valid documents
-- **Future-Proof**: Supports additional parsers (JSON, YAML) with same validation
-
-**Performance Impact:**
-
-- O(1) vs O(n) state lookups during interpretation
-- O(1) vs O(n) transition queries for event processing  
-- Source field optimization eliminates expensive lookups during event processing
-- Critical for responsive event processing in complex state charts
-
-## Regression Testing System
-
-The project includes a sophisticated regression testing system to ensure stability:
-
-### **Test Registry** (`test/passing_tests.json`)
-
-```json
-{
-  "internal_tests": ["test/statifier_test.exs", "test/statifier/**/*_test.exs"],
-  "scion_tests": ["test/scion_tests/basic/basic0_test.exs", ...],
-  "w3c_tests": []
-}
-```
-
-### **Wildcard Support**
-
-- Supports glob patterns like `test/statifier/**/*_test.exs`
-- Automatically expands to all matching test files
-- Maintains clean, maintainable test registry
-
-### **CI Integration**
-
-- Regression tests run before full test suite in CI
-- Prevents merging code that breaks core functionality
-- Fast feedback loop (63 tests vs 444 total tests)
-
-### **Local Development**
-
-```bash
-# Check current regression status
-mix test.regression
-
-# Update regression baseline after adding features
-mix test.baseline
-# Manually add newly passing tests to test/passing_tests.json
-
-# Pre-push hook automatically runs regression tests
-git push origin feature-branch
-```
+## Learn More
 
-## Contributing
+- **[Getting Started](https://riddler.github.io/statifier/getting-started)** - Build your first state machine with working examples
+- **[External Services](https://riddler.github.io/statifier/external-services)** - Integrate safely with APIs and external systems
+- **[Installation Guide](https://riddler.github.io/statifier/installation)** - Set up Statifier in your project
 
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Install git hooks: `./scripts/setup-git-hooks.sh`
-4. Make your changes following the code quality workflow:
-   - `mix format` (auto-fix formatting)
-   - Add tests for new functionality
-   - `mix test.regression` (ensure no regressions)
-   - `mix credo --strict` (static analysis)
-   - `mix dialyzer` (type checking)
-5. Update regression tests if you fix failing SCION/W3C tests:
-   - Run `mix test.baseline` to see current status
-   - Add newly passing tests to `test/passing_tests.json`
-6. Ensure all CI checks pass
-7. Commit your changes (`git commit -m 'Add amazing feature'`)
-8. Push to the branch (pre-push hook will run automatically)
-9. Open a Pull Request
+## Project Information
 
-### Code Style
+- **[Architecture](https://riddler.github.io/statifier/architecture)** - Technical design and component overview
+- **[Changelog](https://riddler.github.io/statifier/changelog)** - Recent major feature completions and implementation details
+- **[Roadmap](https://riddler.github.io/statifier/roadmap)** - Planned features and development priorities
 
-- All code is formatted with `mix format`
-- Static analysis with Credo (strict mode)
-- Type checking with Dialyzer
-- Comprehensive test coverage (90%+ maintained)
-- Detailed documentation with `@moduledoc` and `@doc`
-- Pattern matching preferred over multiple assertions in tests
-- Git pre-push hook enforces validation workflow automatically
-- Regression tests ensure core functionality never breaks
+## Resources
 
-## License
+- **[GitHub Repository](https://github.com/riddler/statifier)** - Source code and issues  
+- **[Hex Package](https://hex.pm/packages/statifier)** - Package information
+- **[HexDocs API](https://hexdocs.pm/statifier/)** - Complete API documentation
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+---
 
-## Acknowledgments
+::: info Active Development Notice
+This project is under active development. While stable for production use, APIs may evolve as we continue improving SCXML compliance and functionality.
+:::
 
-- [W3C SCXML Specification](https://www.w3.org/TR/scxml/) - Official specification
-- [SCION Test Suite](https://github.com/jbeard4/SCION) - Comprehensive test cases
+For comprehensive technical details about the implementation, see the [Architecture Documentation](https://riddler.github.io/statifier/architecture).
diff --git a/coveralls.json b/coveralls.json
index ca4a11a..03d37b4 100644
--- a/coveralls.json
+++ b/coveralls.json
@@ -1,5 +1,5 @@
 {
-  "skip_files": [ "test/support", "lib/mix/tasks/test.*.ex", "lib/mix/tasks/quality.ex" ],
+  "skip_files": [ "test/support", "lib/mix/tasks" ],
   "coverage_options": {
     "treat_no_relevant_lines_as_covered": true,
     "output_dir": "cover/",
diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js
index c1edc5b..1f4fa7a 100644
--- a/docs/.vitepress/config.js
+++ b/docs/.vitepress/config.js
@@ -16,6 +16,8 @@ export default defineConfig({
     nav: [
       { text: 'Home', link: '/' },
       { text: 'Get Started', link: '/getting-started' },
+      { text: 'External Services', link: '/external-services' },
+      { text: 'Changelog', link: '/changelog' },
       { 
         text: 'Links', 
         items: [
@@ -28,10 +30,20 @@ export default defineConfig({
 
     sidebar: [
       {
-        text: 'Introduction',
+        text: 'Documentation',
         items: [
           { text: 'What is Statifier?', link: '/' },
-          { text: 'Getting Started', link: '/getting-started' }
+          { text: 'Installation', link: '/installation' },
+          { text: 'Getting Started', link: '/getting-started' },
+          { text: 'External Services', link: '/external-services' }
+        ]
+      },
+      {
+        text: 'Project Info',
+        items: [
+          { text: 'Architecture', link: '/architecture' },
+          { text: 'Changelog', link: '/changelog' },
+          { text: 'Roadmap', link: '/roadmap' }
         ]
       }
     ],
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..dcb1362
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,68 @@
+# Architecture
+
+Statifier follows a clean **Parse → Validate → Optimize** architecture with modular components and efficient data structures.
+
+## Core Components
+
+- **`Statifier.Parser.SCXML`** - SAX-based XML parser with location tracking (parse phase)
+- **`Statifier.Validator`** - Modular validation orchestrator with focused sub-validators (validate + optimize phases)
+- **`Statifier.Validator.HistoryStateValidator`** - Dedicated validator for history state constraints and W3C compliance
+- **`Statifier.FeatureDetector`** - SCXML feature detection for test validation and capability tracking
+- **`Statifier.Interpreter`** - Synchronous state chart interpreter with compound state and history support
+- **`Statifier.StateChart`** - Runtime container with event queues and history tracking
+- **`Statifier.HistoryTracker`** - Core history state tracking with efficient MapSet operations
+- **`Statifier.Configuration`** - Active state management (leaf states only)
+- **`Statifier.Event`** - Event representation with origin tracking
+
+## Data Structures
+
+- **`Statifier.Document`** - Root SCXML document with states, metadata, O(1) lookup maps, and history helper functions
+- **`Statifier.State`** - Individual states with transitions, hierarchical nesting, and history type support
+- **`Statifier.Transition`** - State transitions with event, conditions, targets (list for multiple target support), and source optimization
+- **`Statifier.Data`** - Datamodel elements with IDs and expressions
+
+## Architecture Flow
+
+The implementation follows a clean **Parse → Validate → Optimize** architecture:
+
+```elixir
+# 1. Parse Phase: XML → Document structure
+{:ok, document} = Statifier.Parser.SCXML.parse(xml_string)
+
+# 2. Validate + Optimize Phase: Check semantics + build lookup maps
+{:ok, optimized_document, warnings} = Statifier.Validator.validate(document)
+
+# 3. Interpret Phase: Use optimized document for runtime
+{:ok, state_chart} = Statifier.Interpreter.initialize(optimized_document)
+```
+
+**Benefits:**
+
+- Parsers focus purely on structure (supports future JSON/YAML parsers)
+- Validation catches semantic errors before optimization
+- Only valid documents get expensive optimization treatment
+- Clear separation of concerns across phases
+
+## Performance Optimizations
+
+### **O(1) State and Transition Lookups**
+
+- **State lookups**: `Document.find_state/2` uses `state_lookup` map for O(1) access
+- **Transition lookups**: `Document.get_transitions_from_state/2` uses `transitions_by_source` map
+- **Built during validation**: Maps constructed only for valid documents via `Document.build_lookup_maps/1`
+
+### **Compound and Parallel State Entry**
+
+- **Leaf state storage**: `Configuration` stores only leaf states, computes ancestors dynamically
+- **Optimized ancestor computation**: `Configuration.active_ancestors/2` uses O(1) document lookups
+- **Efficient MapSet operations**: Direct construction vs incremental building where possible
+- **History state integration**: `HistoryTracker` uses same O(1) lookups for efficient recording/restoration
+
+### **Parse → Validate → Optimize Flow**
+
+- **SAX-based parsing**: Memory-efficient XML processing with accurate location tracking
+- **Modular validation**: Focused sub-validators (StateValidator, TransitionValidator, etc.)
+- **Lazy optimization**: Expensive operations only performed on valid documents
+- **Source field optimization**: Transitions include source state for faster event processing
+
+This architecture ensures Statifier remains performant while maintaining clean code organization and comprehensive W3C SCXML compliance.
diff --git a/docs/changelog.md b/docs/changelog.md
new file mode 100644
index 0000000..d72a30b
--- /dev/null
+++ b/docs/changelog.md
@@ -0,0 +1,75 @@
+# Changelog
+
+## ✅ Recent Major Completions
+
+### **Secure Invoke System with Centralized Parameters (v1.9.0)**
+
+- **Handler-Based Security** - Replaces dangerous arbitrary function execution with secure handler registration system
+- **SCXML Event Compliance** - Generates proper `done.invoke.{id}`, `error.execution`, and `error.communication` events per specification
+- **Centralized Parameter Processing** - Unified `<param>` evaluation with strict (InvokeAction) and lenient (SendAction) error handling modes  
+- **External Service Integration** - Safe way to integrate SCXML state machines with external services and APIs
+- **Complete Test Coverage** - InvokeAction and InvokeHandler modules achieve 100% test coverage
+- **Parameter Architecture Refactor** - Consolidated parameter evaluation logic removes code duplication across actions
+
+### **Complete History State Support (v1.4.0)**
+
+- **Shallow History** - Records and restores immediate children of parent states that contain active descendants
+- **Deep History** - Records and restores all atomic descendant states within parent states
+- **History Tracking** - Complete `Statifier.HistoryTracker` module with efficient MapSet operations
+- **History Validation** - Comprehensive `Statifier.Validator.HistoryStateValidator` with W3C specification compliance
+- **History Resolution** - Full W3C SCXML compliant history state transition resolution during interpreter execution
+- **StateChart Integration** - History tracking integrated into StateChart lifecycle with recording before onexit actions
+- **SCION Test Coverage** - Major improvement in SCION history test compliance (5/8 tests now passing)
+
+### **Multiple Transition Target Support (v1.4.0)**
+
+- **Space-Separated Parsing** - Handles `target="state1 state2 state3"` syntax with proper whitespace splitting
+- **API Enhancement** - `Statifier.Transition.targets` field (list) replaces `target` field (string) for better readability
+- **Validator Updates** - All transition validators updated for list-based target validation with comprehensive testing
+- **Parallel State Fixes** - Critical parallel state exit logic improvements with proper W3C SCXML exit set computation
+- **SCION Compatibility** - history4b and history5 SCION tests now pass completely with multiple target support
+
+### **SCXML-Compliant Processing Engine**
+
+- **Microstep/Macrostep Execution** - Implements SCXML event processing model with microstep (single transition set execution) and macrostep (series of microsteps until stable)
+- **Eventless Transitions** - Transitions without event attributes (called NULL transitions in SCXML spec) that fire automatically upon state entry
+- **Exit Set Computation** - Implements W3C SCXML exit set calculation algorithm for determining which states to exit during transitions
+- **LCCA Algorithm** - Full Least Common Compound Ancestor computation for accurate transition conflict resolution and exit set calculation
+- **Cycle Detection** - Prevents infinite loops with configurable iteration limits (100 iterations default)
+- **Parallel Region Preservation** - Proper SCXML exit semantics for transitions within and across parallel regions
+- **Optimal Transition Set** - SCXML-compliant transition conflict resolution where child state transitions take priority over ancestors
+
+### **Enhanced Parallel State Support**
+
+- **Cross-Parallel Boundaries** - Proper exit semantics when transitions leave parallel regions
+- **Sibling State Management** - Automatic exit of parallel siblings when transitions exit their shared parent  
+- **Self-Transitions** - Transitions within parallel regions preserve unaffected parallel regions
+- **Parallel Ancestor Detection** - New functions for identifying parallel ancestors and region relationships
+- **Enhanced Exit Logic** - All parallel regions properly exited when transitioning to external states
+
+### **Feature-Based Test Validation System**
+
+- **Statifier.FeatureDetector** - Analyzes SCXML documents to detect used features
+- **Feature validation** - Tests fail when they depend on unsupported features  
+- **False positive prevention** - No more "passing" tests that silently ignore unsupported features
+- **Capability tracking** - Clear visibility into which SCXML features are supported
+
+### **Modular Validator Architecture**
+
+- **Statifier.Validator** - Main orchestrator (from 386-line monolith)
+- **Statifier.Validator.StateValidator** - State ID validation
+- **Statifier.Validator.TransitionValidator** - Transition target validation  
+- **Statifier.Validator.InitialStateValidator** - All initial state constraints
+- **Statifier.Validator.ReachabilityAnalyzer** - State reachability analysis
+- **Statifier.Validator.Utils** - Shared utilities
+
+### **Initial State Elements**
+
+- **Parser support** - `<initial>` elements with `<transition>` children
+- **Interpreter logic** - Proper initial state entry via initial elements
+- **Comprehensive validation** - Conflict detection, target validation, structure validation
+- **Feature detection** - Automatic detection of initial element usage
+
+## Implementation Status
+
+For current feature status and working capabilities, see the main [README](https://github.com/riddler/statifier/blob/main/README.md).
diff --git a/docs/external-services.md b/docs/external-services.md
new file mode 100644
index 0000000..4532686
--- /dev/null
+++ b/docs/external-services.md
@@ -0,0 +1,217 @@
+# Working with External Services
+
+Statifier's secure invoke system allows SCXML state machines to safely integrate with external services like APIs, databases, and business logic services.
+
+## Security Model
+
+The invoke system uses **handler-based security** instead of arbitrary code execution:
+
+- Only registered handlers can be invoked
+- Handlers operate in a controlled environment  
+- No risk of code injection or unauthorized execution
+- Full exception safety with proper error handling
+
+## Basic Handler Implementation
+
+Create a handler module that implements the invoke interface:
+
+```elixir
+defmodule MyApp.UserService do
+  def handle_invoke("create_user", params, state_chart) do
+    case create_user(params["name"], params["email"]) do
+      {:ok, user} -> 
+        {:ok, %{"user_id" => user.id}, state_chart}
+      {:error, reason} -> 
+        {:error, :execution, "User creation failed: #{reason}"}
+    end
+  end
+  
+  def handle_invoke("delete_user", params, state_chart) do
+    case delete_user(params["user_id"]) do
+      :ok -> 
+        {:ok, state_chart}  # Success with no return data
+      {:error, :not_found} -> 
+        {:error, :execution, "User not found"}
+      {:error, reason} -> 
+        {:error, :execution, "Delete failed: #{reason}"}
+    end
+  end
+  
+  def handle_invoke(operation, _params, _state_chart) do
+    {:error, :execution, "Unknown operation: #{operation}"}
+  end
+  
+  # Your business logic
+  defp create_user(name, email) do
+    {:ok, %{id: 123, name: name, email: email}}
+  end
+  
+  defp delete_user(_user_id) do
+    :ok
+  end
+end
+```
+
+## Handler Registration
+
+Register your handlers when initializing the state chart:
+
+```elixir
+# Register handlers during StateChart initialization
+invoke_handlers = %{
+  "user_service" => &MyApp.UserService.handle_invoke/3
+}
+
+xml = """
+<?xml version="1.0" encoding="UTF-8"?>
+<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" initial="start">
+  <state id="start">
+    <transition event="create_user" target="creating"/>
+  </state>
+  <state id="creating">
+    <onentry>
+      <invoke type="user_service" src="create_user" id="user_creation">
+        <param name="name" expr="'John Doe'"/>
+        <param name="email" expr="'john@example.com'"/>
+      </invoke>
+    </onentry>
+    <transition event="done.invoke.user_creation" target="success"/>
+    <transition event="error.execution" target="failed"/>
+  </state>
+  <state id="success"/>
+  <state id="failed"/>
+</scxml>
+"""
+
+{:ok, document, _warnings} = Statifier.parse(xml)
+{:ok, state_chart} = Statifier.initialize(document, [
+  invoke_handlers: invoke_handlers
+])
+```
+
+## SCXML Event Generation
+
+The invoke system automatically generates SCXML-compliant events:
+
+- `done.invoke.{id}` - Generated on successful completion
+- `error.execution` - Generated when the handler reports an execution error  
+- `error.communication` - Generated when the handler cannot be reached
+
+```xml
+<!-- skip-validation -->
+<state id="calling_service">
+  <onentry>
+    <invoke type="api_service" src="get_data" id="api_call">
+      <param name="endpoint" expr="api_endpoint"/>
+    </invoke>
+  </onentry>
+  
+  <!-- Handle different outcomes -->
+  <transition event="done.invoke.api_call" target="success"/>
+  <transition event="error.execution" target="retry" cond="retry_count < 3"/>
+  <transition event="error.execution" target="failed" cond="retry_count >= 3"/>
+  <transition event="error.communication" target="offline"/>
+</state>
+```
+
+## Parameter Processing  
+
+The invoke system supports both expression and location parameters:
+
+```xml
+<!-- skip-validation -->
+<invoke type="user_service" src="update_profile" id="profile_update">
+  <!-- Expression parameters (evaluated) -->
+  <param name="user_id" expr="current_user.id"/>
+  <param name="timestamp" expr="Date.now()"/>
+  
+  <!-- Location parameters (from data model) -->
+  <param name="profile_data" location="user_profile"/>
+</invoke>
+```
+
+## Error Handling
+
+Handlers can return different types of errors:
+
+```elixir
+def handle_invoke("risky_operation", params, state_chart) do
+  try do
+    result = perform_operation(params)
+    {:ok, result, state_chart}
+  rescue
+    # All exceptions are caught and converted to error events
+    e -> {:error, :execution, "Operation failed: #{Exception.message(e)}"}
+  end
+end
+
+# Helper function for the example
+defp perform_operation(_params) do
+  # Your risky operation here
+  {:ok, %{"result" => "success"}}
+end
+```
+
+## Complete Example
+
+Here's a complete user registration workflow:
+
+```elixir
+defmodule MyApp.RegistrationService do
+  def handle_invoke("validate_email", %{"email" => email}, state_chart) do
+    if String.contains?(email, "@") do
+      {:ok, %{"valid" => true}, state_chart}
+    else
+      {:ok, %{"valid" => false}, state_chart}
+    end
+  end
+  
+  def handle_invoke("create_account", params, state_chart) do
+    # Simulate account creation
+    {:ok, %{"account_id" => "acc_123"}, state_chart}
+  end
+end
+
+xml = """
+<?xml version="1.0" encoding="UTF-8"?>
+<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" initial="validating">
+  <datamodel>
+    <data id="email" expr="'user@example.com'"/>
+  </datamodel>
+  
+  <state id="validating">
+    <onentry>
+      <invoke type="registration" src="validate_email" id="email_check">
+        <param name="email" location="email"/>
+      </invoke>
+    </onentry>
+    <transition event="done.invoke.email_check" target="creating" cond="event.data.valid"/>
+    <transition event="done.invoke.email_check" target="invalid_email"/>
+  </state>
+  
+  <state id="creating">
+    <onentry>
+      <invoke type="registration" src="create_account" id="account_creation">
+        <param name="email" location="email"/>
+      </invoke>
+    </onentry>
+    <transition event="done.invoke.account_creation" target="complete"/>
+    <transition event="error.execution" target="creation_failed"/>
+  </state>
+  
+  <state id="complete"/>
+  <state id="invalid_email"/>
+  <state id="creation_failed"/>
+</scxml>
+"""
+
+# Initialize with handler
+{:ok, document, _warnings} = Statifier.parse(xml)
+{:ok, state_chart} = Statifier.initialize(document, [
+  invoke_handlers: %{"registration" => &MyApp.RegistrationService.handle_invoke/3}
+])
+
+# The state machine will automatically validate email and create account
+```
+
+This secure approach ensures your SCXML state machines can integrate with external systems while maintaining security and reliability.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index c2a8632..e013aba 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -1,6 +1,6 @@
 # Getting Started with Statifier
 
-Welcome to Statifier! This guide will walk you through setting up your first SCXML state machine.
+Statifier is an Elixir implementation of SCXML (State Chart XML) state machines with a focus on W3C compliance. This guide will help you build your first state machine.
 
 ## Installation
 
@@ -22,7 +22,7 @@ mix deps.get
 
 ## Your First State Machine
 
-Let's create a simple state machine for a traffic light:
+Let's create a simple traffic light state machine:
 
 ```elixir
 # Define the SCXML document
@@ -32,7 +32,7 @@ xml = """
   <state id="red">
     <transition event="timer" target="green"/>
   </state>
-  <state id="green">  
+  <state id="green">
     <transition event="timer" target="yellow"/>
   </state>
   <state id="yellow">
@@ -41,52 +41,71 @@ xml = """
 </scxml>
 """
 
-# Parse the document
-{:ok, document, warnings} = Statifier.parse(xml)
+# Parse and initialize the state chart
+{:ok, document, _warnings} = Statifier.parse(xml)
+{:ok, state_chart} = Statifier.initialize(document)
 
-# Initialize the state chart
-{:ok, state_chart} = Statifier.Interpreter.initialize(document)
+# Check the initial state
+IO.puts("Current state: #{inspect(state_chart.configuration.active_states)}")
+# Output: Current state: #MapSet<["red"]>
 
-# Check current state
-IO.inspect(Statifier.Configuration.active_states(state_chart.configuration))
-# [:red]
+# Send events to transition between states
+{:ok, state_chart} = Statifier.send_sync(state_chart, "timer")
+IO.puts("After timer: #{inspect(state_chart.configuration.active_states)}")
+# Output: After timer: #MapSet<["green"]>
 
-# Send an event
-event = %Statifier.Event{name: "timer"}
-{:ok, new_state_chart} = Statifier.Interpreter.send_event(state_chart, event)
+{:ok, state_chart} = Statifier.send_sync(state_chart, "timer")
+IO.puts("After timer: #{inspect(state_chart.configuration.active_states)}")
+# Output: After timer: #MapSet<["yellow"]>
 
-# Check new state  
-IO.inspect(Statifier.Configuration.active_states(new_state_chart.configuration))
-# [:green]
+{:ok, state_chart} = Statifier.send_sync(state_chart, "timer")
+IO.puts("After timer: #{inspect(state_chart.configuration.active_states)}")
+# Output: After timer: #MapSet<["red"]>
 ```
 
-## Understanding the Flow
+## Working with Data
 
-Statifier follows a clean **Parse → Validate → Optimize** architecture:
+Statifier supports data models and expressions for dynamic state machines:
 
-1. **Parse**: Convert XML string to structured document
-2. **Validate**: Check semantic correctness and build optimization maps  
-3. **Execute**: Use optimized document for high-performance runtime
+```elixir
+xml_with_data = """
+<?xml version="1.0" encoding="UTF-8"?>
+<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" initial="checking">
+  <datamodel>
+    <data id="balance" expr="100"/>
+    <data id="amount" expr="0"/>
+  </datamodel>
+  
+  <state id="checking">
+    <onentry>
+      <assign location="amount" expr="50"/>
+    </onentry>
+    <transition event="withdraw" target="approved" cond="balance >= amount"/>
+    <transition event="withdraw" target="denied" cond="balance < amount"/>
+  </state>
+  
+  <state id="approved"/>
+  <state id="denied"/>
+</scxml>
+"""
 
-## Key Components
+{:ok, document, _warnings} = Statifier.parse(xml_with_data)
+{:ok, state_chart} = Statifier.initialize(document)
 
-- **`Statifier.parse/1`** - Main entry point for parsing SCXML
-- **`Statifier.Interpreter`** - Core runtime engine for state chart execution
-- **`Statifier.Event`** - Represents events sent to the state machine
-- **`Statifier.Configuration`** - Tracks active states and provides state queries
+# The state chart starts with balance=100, amount=50 (set in onentry)
+{:ok, state_chart} = Statifier.send_sync(state_chart, "withdraw")
+IO.puts("Withdrawal result: #{inspect(state_chart.configuration.active_states)}")
+# Output: Withdrawal result: #MapSet<["approved"]>
+```
 
 ## Next Steps
 
-Now that you have the basics working, explore these topics:
-
-- **Hierarchical States** - Nested states with parent-child relationships
-- **Parallel States** - Concurrent execution of multiple state regions  
-- **Conditional Transitions** - Event processing with conditional logic
-- **Data Model** - Working with variables and expressions
-- **History States** - Remembering previous state configurations
+Now that you have a basic state machine running, you can explore more advanced features:
 
-## Getting Help
+- **Hierarchical States**: Create nested states with automatic initial child entry
+- **Parallel States**: Run multiple state regions concurrently  
+- **History States**: Save and restore previous states
+- **External Services**: Integrate with APIs and external systems using the secure invoke system
+- **Conditional Logic**: Use complex expressions in transition conditions
 
-- **[API Documentation](https://hexdocs.pm/statifier/)** - Complete function reference
-- **[GitHub Issues](https://github.com/riddler/statifier/issues)** - Report bugs or request features
-- **[Examples Repository](https://github.com/riddler/statifier/tree/master/test)** - Browse test files for more examples
+For more examples, see the README.md file in the repository.
diff --git a/docs/index.md b/docs/index.md
index df1829c..189bb7e 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -5,13 +5,10 @@ hero:
   name: Statifier
   text: SCXML State Machines for Elixir
   tagline: Complete W3C compliant implementation with high-performance state chart execution
-  image:
-    src: /logo.svg
-    alt: Statifier Logo
   actions:
     - theme: brand
       text: Get Started
-      link: /getting-started
+      link: /tutorials/getting-started
     - theme: alt
       text: View on GitHub
       link: https://github.com/riddler/statifier
@@ -83,11 +80,10 @@ xml = """
 
 # Initialize state chart
 {:ok, document, _warnings} = Statifier.parse(xml)
-{:ok, state_chart} = Statifier.Interpreter.initialize(document)
+{:ok, state_chart} = Statifier.initialize(document)
 
 # Process events
-event = %Statifier.Event{name: "start"}
-{:ok, new_state_chart} = Statifier.Interpreter.send_event(state_chart, event)
+{:ok, new_state_chart} = Statifier.send_sync(state_chart, "start")
 ```
 
 ## Installation
@@ -95,19 +91,26 @@ event = %Statifier.Event{name: "start"}
 Add `statifier` to your list of dependencies in `mix.exs`:
 
 ```elixir
-def deps do
-  [
-    {:statifier, "~> 1.7"}
-  ]
-end
+{:statifier, "~> 1.7"}
 ```
 
 ## Learn More
 
-- **[Getting Started](/getting-started)** - Build your first state machine
+- **[Getting Started](/getting-started)** - Build your first state machine with working examples
+- **[External Services](/external-services)** - Integrate safely with APIs and external systems
+- **[Installation Guide](/installation)** - Set up Statifier in your project
+
+## Project Information
+
+- **[Architecture](/architecture)** - Technical design and component overview
+- **[Changelog](/changelog)** - Recent major feature completions and implementation details
+- **[Roadmap](/roadmap)** - Planned features and development priorities
+
+## Resources
+
 - **[GitHub Repository](https://github.com/riddler/statifier)** - Source code and issues  
 - **[Hex Package](https://hex.pm/packages/statifier)** - Package information
-- **[API Documentation](https://hexdocs.pm/statifier/)** - Complete module documentation
+- **[HexDocs API](https://hexdocs.pm/statifier/)** - Complete API documentation
 
 ---
 
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 0000000..97feac6
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,57 @@
+# Installation
+
+## Requirements
+
+- Elixir 1.17+
+- Erlang/OTP 26+
+
+## Adding to Your Project
+
+Add `statifier` to your list of dependencies in `mix.exs`:
+
+```elixir
+def deps do
+  [
+    {:statifier, "~> 1.8"}
+  ]
+end
+```
+
+Then run:
+
+```bash
+mix deps.get
+mix compile
+```
+
+## Verification
+
+To verify your installation works correctly, you can run this simple test:
+
+```elixir
+# Create a basic SCXML document
+xml = """
+<?xml version="1.0" encoding="UTF-8"?>
+<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" initial="start">
+  <state id="start">
+    <transition event="go" target="end"/>
+  </state>
+  <state id="end"/>
+</scxml>
+"""
+
+# Parse and initialize
+{:ok, document, _warnings} = Statifier.parse(xml)
+{:ok, state_chart} = Statifier.initialize(document)
+
+# Should output: MapSet containing "start"
+IO.inspect(Statifier.Configuration.active_leaf_states(state_chart.configuration))
+```
+
+If this runs without errors and outputs `#MapSet<["start"]>`, your installation is working correctly.
+
+## Next Steps
+
+- **[Getting Started Guide](/getting-started)** - Build your first state machine with working examples
+- **[External Services](/external-services)** - Learn about secure integration with APIs and external systems
+- **[API Documentation](https://hexdocs.pm/statifier/)** - Explore the complete API reference
diff --git a/docs/roadmap.md b/docs/roadmap.md
new file mode 100644
index 0000000..3980cea
--- /dev/null
+++ b/docs/roadmap.md
@@ -0,0 +1,63 @@
+# Roadmap
+
+The next major areas for development focus on expanding SCXML feature support and improving the developer experience.
+
+## High Priority Features
+
+### **Enhanced Executable Content**
+
+- **`<script>` elements** - Inline JavaScript execution within SCXML documents
+- **`<send>` elements** - External event sending with delays and target specification
+- **More action types** - Additional executable content per SCXML specification
+
+### **Advanced Transition Types**
+
+- **Internal Transitions** - `type="internal"` transition support for actions without state changes
+- **Targetless Transitions** - Transitions without target for pure action execution
+- **Conditional Action Execution** - Enhanced conditional logic in executable content
+
+## Medium Priority Features  
+
+### **Developer Experience**
+
+- **Enhanced Error Handling** - Better error messages with precise source location information
+- **Performance Benchmarking** - Establish performance baselines and optimize hot paths
+- **Enhanced Validation** - More comprehensive SCXML document validation with detailed error reporting
+
+### **Advanced Data Model Support**
+
+- **JavaScript Expression Engine** - Full ECMAScript expression evaluation for complex data manipulation
+- **Enhanced Variable Scoping** - Proper variable scoping rules per SCXML specification
+- **Type System Integration** - Better integration with Elixir's type system
+
+### **Runtime Enhancements**
+
+- **Dynamic State Machine Modification** - Runtime modification of state machine structure
+- **State Machine Composition** - Combining multiple state machines into larger systems
+- **Enhanced Event Processing** - More sophisticated event queuing and processing
+
+## Long-term Vision
+
+### **Ecosystem Integration**
+
+- **Phoenix Integration** - First-class Phoenix framework integration for web applications
+- **LiveView Components** - State machine-driven LiveView components
+- **OTP Supervision** - Better integration with OTP supervision trees
+
+### **Advanced Features**
+
+- **Distributed State Machines** - State machines spanning multiple nodes
+- **State Machine Persistence** - Persistent state machine state across application restarts
+- **Visual Development Tools** - Graphical state machine design and debugging tools
+
+### **Performance & Scalability**
+
+- **Concurrent State Machine Execution** - Highly concurrent state machine processing
+- **Memory Optimization** - Reduced memory footprint for large state machines
+- **Incremental Compilation** - Faster state machine compilation and optimization
+
+## Current Focus
+
+Development is currently focused on completing the core SCXML specification compliance while maintaining the clean architecture and high test coverage that makes Statifier reliable for production use.
+
+For current implementation status, see the [Changelog](/changelog).
diff --git a/examples/apps/approval_workflow/README.md b/examples/apps/approval_workflow/README.md
index ee4d347..87f00f8 100644
--- a/examples/apps/approval_workflow/README.md
+++ b/examples/apps/approval_workflow/README.md
@@ -142,6 +142,7 @@ The workflow now uses SCXML `<invoke>` elements for automatic service integratio
 ### Query Operations
 
 ```elixir
+# skip-validation (don't check this code block in CI)
 # Get current active state(s)
 states = PurchaseOrderMachine.current_states(pid)
 
@@ -173,6 +174,7 @@ The comprehensive test suite includes:
 ### Key Test Scenarios
 
 ```elixir
+# skip-validation (don't check this code block in CI)
 # Small PO (≤ $5,000) → Manager approval
 test "manager approval path for small amounts"
 
@@ -240,6 +242,7 @@ The workflow is defined in `priv/scxml/purchase_order.xml` using:
 ### Key SCXML Features Demonstrated
 
 ```xml
+<!-- skip-validation --> 
 <!-- Conditional routing based on amount -->
 <transition target="manager_approval" cond="amount &lt;= 5000"/>
 <transition target="executive_approval" cond="amount &gt; 5000"/>
@@ -287,6 +290,8 @@ The `PurchaseOrderMachine` module:
 ### Invoke Handler System
 
 ```elixir
+# skip-validation (don't check this code block in CI)
+
 # Secure service integration via invoke handlers
 use Statifier.StateMachine,
   scxml: "purchase_order.xml",
diff --git a/lib/mix/tasks/docs.validate.ex b/lib/mix/tasks/docs.validate.ex
new file mode 100644
index 0000000..76f3c1c
--- /dev/null
+++ b/lib/mix/tasks/docs.validate.ex
@@ -0,0 +1,556 @@
+defmodule Mix.Tasks.Docs.Validate do
+  @moduledoc """
+  Validates code examples in documentation files.
+
+  This task extracts Elixir code blocks from markdown files and validates them:
+  - Syntax checking (compilation)
+  - Basic execution for simple examples
+  - API compatibility checking
+  - SCXML validation for state machine examples
+
+  ## Usage
+
+      mix docs.validate                    # Validate all docs
+      mix docs.validate --path docs/       # Validate specific directory
+      mix docs.validate --file README.md   # Validate specific file
+      mix docs.validate --fix              # Auto-fix simple issues
+      mix docs.validate --verbose          # Show detailed output
+
+  ## Example Code Block Formats
+
+  The task recognizes several code block patterns:
+
+  ### Basic Elixir Code
+  ```elixir
+  {:ok, document} = Statifier.parse(xml)
+  ```
+
+  ### Expected Outputs (validates return values)
+  ```elixir
+  active_states = MapSet.new(["idle", "running"])
+  # Returns: MapSet.new(["idle", "running"])
+  ```
+
+  ### SCXML Examples (validates XML structure)
+  ```xml
+  <scxml initial="start">
+    <state id="start"/>
+  </scxml>
+  ```
+
+  ### Skip Validation (for pseudo-code)
+  ```elixir
+  # skip-validation
+  SomeHypotheticalAPI.call()
+  ```
+  """
+
+  use Mix.Task
+
+  alias Statifier.{Parser.SCXML, Validator}
+
+  @shortdoc "Validates code examples in documentation files"
+
+  @default_paths [
+    "README.md",
+    "docs/**/*.md",
+    "examples/**/README.md"
+  ]
+
+  @switches [
+    path: :string,
+    file: :string,
+    fix: :boolean,
+    verbose: :boolean,
+    help: :boolean
+  ]
+
+  @aliases [
+    p: :path,
+    f: :file,
+    v: :verbose,
+    h: :help
+  ]
+
+  def run(args) do
+    {opts, _, _} = OptionParser.parse(args, switches: @switches, aliases: @aliases)
+
+    if opts[:help] do
+      print_help()
+    else
+      Application.ensure_all_started(:statifier)
+
+      paths = determine_paths(opts)
+      files = find_markdown_files(paths)
+
+      if opts[:verbose] do
+        Mix.shell().info("Found #{length(files)} markdown files to validate")
+      end
+
+      results = Enum.map(files, &validate_file(&1, opts))
+
+      print_summary(results, opts)
+
+      if Enum.any?(results, &(&1.errors != [])) do
+        System.halt(1)
+      end
+    end
+  end
+
+  # Determine which files to validate
+  defp determine_paths(opts) do
+    cond do
+      opts[:file] -> [opts[:file]]
+      opts[:path] -> ["#{opts[:path]}/**/*.md"]
+      true -> @default_paths
+    end
+  end
+
+  # Find all markdown files matching patterns
+  defp find_markdown_files(patterns) do
+    patterns
+    |> Enum.flat_map(&Path.wildcard/1)
+    |> Enum.filter(&File.regular?/1)
+    |> Enum.filter(&should_validate_file?/1)
+    |> Enum.uniq()
+    |> Enum.sort()
+  end
+
+  # Filter out files we shouldn't validate
+  defp should_validate_file?(file_path) do
+    excluded_patterns = [
+      ~r{/_build/},
+      ~r{/deps/},
+      ~r{/\.git/},
+      ~r{/node_modules/},
+      ~r{/cover/},
+      ~r{/tmp/},
+      ~r{/priv/plts/}
+    ]
+
+    not Enum.any?(excluded_patterns, &Regex.match?(&1, file_path))
+  end
+
+  # Validate a single markdown file
+  defp validate_file(file_path, opts) do
+    content = File.read!(file_path)
+    code_blocks = extract_code_blocks(content)
+
+    if opts[:verbose] do
+      Mix.shell().info("Validating #{file_path} (#{length(code_blocks)} code blocks)")
+    end
+
+    errors =
+      code_blocks
+      |> Enum.with_index(1)
+      |> Enum.flat_map(fn {{type, code, line_num}, block_index} ->
+        validate_code_block(type, code, file_path, line_num, block_index, opts)
+      end)
+
+    %{
+      file: file_path,
+      blocks: length(code_blocks),
+      errors: errors
+    }
+  end
+
+  # Extract code blocks from markdown content
+  defp extract_code_blocks(content) do
+    content
+    |> String.split("\n")
+    |> Enum.with_index(1)
+    |> extract_blocks([])
+    |> Enum.reverse()
+  end
+
+  # State machine for parsing code blocks
+  defp extract_blocks([], acc), do: acc
+
+  defp extract_blocks([{line, line_num} | rest], acc) do
+    cond do
+      String.starts_with?(line, "```elixir") ->
+        {block_lines, remaining, _} = collect_code_block(rest, [])
+        code = Enum.join(block_lines, "\n")
+        extract_blocks(remaining, [{:elixir, code, line_num} | acc])
+
+      String.starts_with?(line, "```xml") ->
+        {block_lines, remaining, _} = collect_code_block(rest, [])
+        code = Enum.join(block_lines, "\n")
+        extract_blocks(remaining, [{:xml, code, line_num} | acc])
+
+      true ->
+        extract_blocks(rest, acc)
+    end
+  end
+
+  # Collect lines until closing ```
+  defp collect_code_block([], acc), do: {Enum.reverse(acc), [], 0}
+
+  defp collect_code_block([{line, line_num} | rest], acc) do
+    if String.starts_with?(line, "```") do
+      {Enum.reverse(acc), rest, line_num}
+    else
+      collect_code_block(rest, [line | acc])
+    end
+  end
+
+  # Validate different types of code blocks
+  defp validate_code_block(:elixir, code, file, line_num, block_index, opts) do
+    cond do
+      String.contains?(code, "skip-validation") ->
+        if opts[:verbose] do
+          Mix.shell().info("  Skipping block #{block_index} (marked skip-validation)")
+        end
+
+        []
+
+      String.contains?(code, "# Returns:") ->
+        validate_elixir_with_expected_output(code, file, line_num, block_index, opts)
+
+      true ->
+        validate_elixir_syntax(code, file, line_num, block_index, opts)
+    end
+  end
+
+  defp validate_code_block(:xml, code, file, line_num, block_index, opts) do
+    if String.contains?(code, "skip-validation") do
+      if opts[:verbose] do
+        Mix.shell().info("  Skipping block #{block_index} (marked skip-validation)")
+      end
+
+      []
+    else
+      validate_scxml_syntax(code, file, line_num, block_index, opts)
+    end
+  end
+
+  # Validate Elixir syntax by attempting to compile
+  defp validate_elixir_syntax(code, file, line_num, block_index, _opts) do
+    # Determine validation approach based on code type
+    case needs_wrapping?(code) do
+      true ->
+        # Regular expressions - wrap in function
+        validate_wrapped_code(code, file, line_num, block_index)
+
+      :module_wrap ->
+        # Standalone functions - wrap in module
+        validate_module_wrapped_code(code, file, line_num, block_index)
+
+      false ->
+        # Full modules or module-level constructs - compile directly
+        validate_direct_code(code, file, line_num, block_index)
+    end
+  rescue
+    error ->
+      [{:syntax_error, file, line_num, block_index, format_compile_error(error)}]
+  end
+
+  # Check if code contains module-level constructs that shouldn't be wrapped
+  defp needs_wrapping?(code) do
+    # Full module definitions don't need wrapping
+    full_module_patterns = [
+      # Module definitions
+      ~r/^\s*defmodule\s/m,
+      # Protocol implementations
+      ~r/^\s*defimpl\s/m,
+      # Protocol definitions
+      ~r/^\s*defprotocol\s/m
+    ]
+
+    # Standalone function definitions need to be wrapped in a module
+    standalone_function_patterns = [
+      # Function definitions
+      ~r/^\s*def\s/m,
+      # Private function definitions
+      ~r/^\s*defp\s/m
+    ]
+
+    # Other module-level constructs that need special handling
+    other_module_patterns = [
+      # Struct definitions
+      ~r/^\s*defstruct\s/m,
+      # Exception definitions
+      ~r/^\s*defexception\s/m,
+      # Module attributes
+      ~r/^\s*@\w+\s/m,
+      # Use directives
+      ~r/^\s*use\s/m,
+      # Import directives
+      ~r/^\s*import\s/m,
+      # Alias directives
+      ~r/^\s*alias\s/m,
+      # Require directives
+      ~r/^\s*require\s/m
+    ]
+
+    cond do
+      # Full modules can be compiled directly
+      Enum.any?(full_module_patterns, &Regex.match?(&1, code)) -> false
+      # Standalone functions need module wrapping (different from expression wrapping)
+      Enum.any?(standalone_function_patterns, &Regex.match?(&1, code)) -> :module_wrap
+      # Other module constructs need direct compilation
+      Enum.any?(other_module_patterns, &Regex.match?(&1, code)) -> false
+      # Everything else needs expression wrapping
+      true -> true
+    end
+  end
+
+  # Validate code that needs to be wrapped in a function
+  defp validate_wrapped_code(code, file, line_num, block_index) do
+    wrapped_code = """
+    defmodule DocExample#{block_index} do
+      def run do
+        #{code}
+      end
+    end
+    """
+
+    case Code.compile_string(wrapped_code, "#{file}:#{line_num}") do
+      [] -> []
+      _modules -> []
+    end
+  end
+
+  # Validate standalone functions that need to be wrapped in a module
+  defp validate_module_wrapped_code(code, file, line_num, block_index) do
+    wrapped_code = """
+    defmodule DocExample#{block_index} do
+      #{code}
+    end
+    """
+
+    case Code.compile_string(wrapped_code, "#{file}:#{line_num}") do
+      [] -> []
+      _modules -> []
+    end
+  end
+
+  # Validate code that can be compiled directly (module-level constructs)
+  defp validate_direct_code(code, file, line_num, _block_index) do
+    case Code.compile_string(code, "#{file}:#{line_num}") do
+      [] -> []
+      _modules -> []
+    end
+  end
+
+  # Validate Elixir code with expected outputs
+  defp validate_elixir_with_expected_output(code, file, line_num, block_index, opts) do
+    [actual_code, expected_output] = String.split(code, "# Returns:", parts: 2)
+    expected = String.trim(expected_output)
+
+    # First validate syntax
+    syntax_errors = validate_elixir_syntax(actual_code, file, line_num, block_index, opts)
+
+    if syntax_errors == [] do
+      # Try to execute and compare output (for simple cases)
+      try_execute_and_compare(actual_code, expected, file, line_num, block_index, opts)
+    else
+      syntax_errors
+    end
+  end
+
+  # Attempt to execute simple code and compare results
+  defp try_execute_and_compare(code, expected, file, line_num, block_index, opts) do
+    # Only attempt execution for simple, safe expressions
+    if safe_to_execute?(code) do
+      {result, _} = Code.eval_string(code, [], __ENV__)
+      result_str = inspect(result)
+
+      if result_str != expected do
+        [
+          {:output_mismatch, file, line_num, block_index,
+           "Expected: #{expected}, Got: #{result_str}"}
+        ]
+      else
+        if opts[:verbose] do
+          Mix.shell().info("  ✓ Block #{block_index} output matches expected")
+        end
+
+        []
+      end
+    else
+      # For complex code, just validate that expected format looks reasonable
+      if String.contains?(expected, ["MapSet", "ok", "error"]) do
+        []
+      else
+        [
+          {:suspicious_output, file, line_num, block_index,
+           "Expected output format seems unusual: #{expected}"}
+        ]
+      end
+    end
+  rescue
+    _ ->
+      # Execution failed, but that's okay - we're mainly checking format
+      []
+  end
+
+  # Check if code is safe to execute (no side effects)
+  defp safe_to_execute?(code) do
+    safe_patterns = [
+      ~r/^MapSet\./,
+      ~r/^[%{].*[}]$/s,
+      ~r/^\[.*\]$/s,
+      ~r/^:\w+$/,
+      ~r/^".*"$/,
+      ~r/^\d+$/
+    ]
+
+    dangerous_patterns = [
+      ~r/File\./,
+      ~r/System\./,
+      ~r/Process\./,
+      ~r/GenServer\./,
+      ~r/spawn/,
+      ~r/send/,
+      ~r/start_link/
+    ]
+
+    code_trimmed = String.trim(code)
+
+    Enum.any?(safe_patterns, &Regex.match?(&1, code_trimmed)) and
+      not Enum.any?(dangerous_patterns, &Regex.match?(&1, code_trimmed))
+  end
+
+  # Validate SCXML syntax
+  defp validate_scxml_syntax(xml_code, file, line_num, block_index, opts) do
+    try do
+      case SCXML.parse(xml_code) do
+        {:ok, document} ->
+          # Also run validator to catch semantic issues
+          case Validator.validate(document) do
+            {:ok, _, warnings} ->
+              if opts[:verbose] and warnings != [] do
+                Mix.shell().info("  ⚠ Block #{block_index} has warnings: #{length(warnings)}")
+              end
+
+              []
+
+            {:error, errors, _} ->
+              [
+                {:scxml_validation_error, file, line_num, block_index,
+                 "SCXML validation failed: #{format_errors(errors)}"}
+              ]
+          end
+
+        {:error, reason} ->
+          [
+            {:scxml_parse_error, file, line_num, block_index,
+             "SCXML parse failed: #{inspect(reason)}"}
+          ]
+      end
+    rescue
+      error ->
+        [
+          {:scxml_parse_error, file, line_num, block_index,
+           "SCXML parse exception: #{format_compile_error(error)}"}
+        ]
+    end
+  end
+
+  # Format compilation errors for display
+  defp format_compile_error(%CompileError{description: desc}), do: desc
+  defp format_compile_error(error), do: inspect(error)
+
+  # Format validation errors
+  defp format_errors(errors) when is_list(errors) do
+    errors |> Enum.take(3) |> Enum.join(", ")
+  end
+
+  defp format_errors(error), do: inspect(error)
+
+  # Print results summary
+  defp print_summary(results, opts) do
+    total_files = length(results)
+    total_blocks = Enum.sum(Enum.map(results, & &1.blocks))
+    files_with_errors = Enum.count(results, &(&1.errors != []))
+    total_errors = Enum.sum(Enum.map(results, &length(&1.errors)))
+
+    Mix.shell().info("\n📊 Documentation Validation Summary")
+    Mix.shell().info("Files checked: #{total_files}")
+    Mix.shell().info("Code blocks: #{total_blocks}")
+
+    if total_errors == 0 do
+      Mix.shell().info(IO.ANSI.green() <> "✅ All examples valid!" <> IO.ANSI.reset())
+    else
+      Mix.shell().error(
+        IO.ANSI.red() <>
+          "❌ Found #{total_errors} errors in #{files_with_errors} files" <> IO.ANSI.reset()
+      )
+
+      if not Keyword.get(opts, :verbose, false) do
+        Mix.shell().info("Run with --verbose for detailed error information")
+      end
+    end
+
+    if Keyword.get(opts, :verbose, false) or total_errors > 0 do
+      print_detailed_results(results)
+    end
+  end
+
+  # Print detailed results
+  defp print_detailed_results(results) do
+    results
+    |> Enum.filter(&(&1.errors != []))
+    |> Enum.each(fn %{file: file, errors: errors} ->
+      Mix.shell().info("\n📄 #{file}:")
+      Enum.each(errors, &print_error/1)
+    end)
+  end
+
+  # Print individual errors
+  defp print_error({type, _file, line_num, block_index, message}) do
+    color =
+      case type do
+        :syntax_error -> IO.ANSI.red()
+        :output_mismatch -> IO.ANSI.yellow()
+        :scxml_parse_error -> IO.ANSI.red()
+        :scxml_validation_error -> IO.ANSI.yellow()
+        :suspicious_output -> IO.ANSI.blue()
+        _ -> ""
+      end
+
+    type_str = type |> Atom.to_string() |> String.replace("_", " ") |> String.upcase()
+
+    Mix.shell().info(
+      "  #{color}#{type_str}#{IO.ANSI.reset()} (line #{line_num}, block #{block_index}): #{message}"
+    )
+  end
+
+  # Print help information
+  defp print_help do
+    Mix.shell().info("""
+    mix docs.validate - Validates code examples in documentation files
+
+    USAGE:
+        mix docs.validate [OPTIONS]
+
+    OPTIONS:
+        --path PATH     Validate files in specific directory
+        --file FILE     Validate specific file
+        --fix           Auto-fix simple issues (not yet implemented)
+        --verbose       Show detailed output
+        --help          Show this help
+
+    EXAMPLES:
+        mix docs.validate                    # Validate all documentation
+        mix docs.validate --path docs/       # Validate docs directory
+        mix docs.validate --file README.md   # Validate README only
+        mix docs.validate --verbose          # Show detailed results
+
+    The task validates:
+    - Elixir code syntax (compilation check)
+    - Expected output format matching
+    - SCXML document structure and validation
+    - API compatibility with current library version
+
+    Automatically excludes:
+    - _build/ directories (compiled artifacts)
+    - deps/ directories (dependencies)
+    - .git/ directories (version control)
+    - node_modules/ directories (Node.js deps)
+    - cover/ directories (coverage reports)
+    - tmp/ and priv/plts/ directories
+    """)
+  end
+end
diff --git a/lib/mix/tasks/quality.ex b/lib/mix/tasks/quality.ex
index 5338337..5d472fa 100644
--- a/lib/mix/tasks/quality.ex
+++ b/lib/mix/tasks/quality.ex
@@ -9,6 +9,7 @@ defmodule Mix.Tasks.Quality do
   - Trailing whitespace check (and auto-fix if needed)
   - Markdown linting (and auto-fix if needed, if markdownlint-cli2 is available)
   - Regression tests (critical tests that should always pass)
+  - Examples tests (validates example applications work correctly)
   - Test coverage check (requires >90% coverage)
   - Static code analysis with Credo (strict mode)
   - Type checking with Dialyzer
@@ -61,13 +62,16 @@ defmodule Mix.Tasks.Quality do
     # Step 4: Regression tests
     run_regression_tests()
 
-    # Step 5: Coverage check
+    # Step 5: Examples tests
+    run_examples_tests()
+
+    # Step 6: Coverage check
     run_coverage_check()
 
-    # Step 6: Static analysis
+    # Step 7: Static analysis
     run_static_analysis()
 
-    # Step 7: Type checking (unless skipped)
+    # Step 8: Type checking (unless skipped)
     unless opts[:skip_dialyzer] do
       run_type_checking()
     end
@@ -286,6 +290,35 @@ defmodule Mix.Tasks.Quality do
     end
   end
 
+  defp run_examples_tests do
+    Mix.shell().info("📚 Running examples tests...")
+
+    # Change to examples directory and run tests
+    original_dir = File.cwd!()
+    examples_dir = Path.join(original_dir, "examples")
+
+    if File.exists?(examples_dir) do
+      try do
+        File.cd!(examples_dir)
+
+        case System.cmd("mix", ["test"], stderr_to_stdout: true) do
+          {_output, 0} ->
+            Mix.shell().info("✅ Examples tests passed")
+
+          {output, _exit_code} ->
+            Mix.shell().error("❌ Examples tests failed!")
+            Mix.shell().info("Output from examples tests:")
+            Mix.shell().info(output)
+            Mix.raise("Examples tests failed")
+        end
+      after
+        File.cd!(original_dir)
+      end
+    else
+      Mix.shell().info("ℹ️  No examples directory found, skipping examples tests")
+    end
+  end
+
   defp run_coverage_check do
     Mix.shell().info("📊 Running test coverage check...")
 
diff --git a/lib/statifier.ex b/lib/statifier.ex
index b1811ae..296e091 100644
--- a/lib/statifier.ex
+++ b/lib/statifier.ex
@@ -72,6 +72,37 @@ defmodule Statifier do
     StateMachine.send_event(server, event_name, event_data)
   end
 
+  @doc """
+  Initialize a StateChart from a validated SCXML document.
+
+  This is a convenience function that wraps `Interpreter.initialize/2` to provide
+  a simpler API for creating StateChart instances from parsed documents.
+
+  ## Options
+
+  - `:log_level` - Log level for state machine execution (`:trace`, `:debug`, `:info`, `:warning`, `:error`)
+  - `:log_adapter` - Log adapter to use (defaults to environment-specific adapter)
+  - `:invoke_handlers` - Map of invoke type to handler function for `<invoke>` elements
+
+  ## Examples
+
+      {:ok, document, _warnings} = Statifier.parse(xml_string)
+      {:ok, state_chart} = Statifier.initialize(document)
+
+      # With options
+      handlers = %{"user_service" => &MyApp.UserService.handle_invoke/3}
+      {:ok, state_chart} = Statifier.initialize(document,
+        log_level: :debug,
+        invoke_handlers: handlers
+      )
+
+  """
+  @spec initialize(Statifier.Document.t(), keyword()) ::
+          {:ok, Statifier.StateChart.t()} | {:error, [String.t()], [String.t()]}
+  def initialize(document, opts \\ []) do
+    Interpreter.initialize(document, opts)
+  end
+
   @doc """
   Send an event to a StateChart synchronously.
 
@@ -80,7 +111,7 @@ defmodule Statifier do
 
   ## Examples
 
-      {:ok, state_chart} = Statifier.Interpreter.initialize(document)
+      {:ok, state_chart} = Statifier.initialize(document)
       {:ok, new_state_chart} = Statifier.send_sync(state_chart, "start")
       {:ok, final_state_chart} = Statifier.send_sync(new_state_chart, "process", %{data: "value"})
 
@@ -92,17 +123,6 @@ defmodule Statifier do
     Interpreter.send_event(state_chart, event)
   end
 
-  @doc """
-  Check if a document has been validated.
-
-  Returns true if the document has been processed through the validator,
-  regardless of whether it passed validation.
-  """
-  @spec validated?(Statifier.Document.t()) :: boolean()
-  def validated?(document) do
-    document.validated
-  end
-
   # Private helper to reduce nesting depth
   defp handle_validation(document, strict?) do
     case Validator.validate(document) do
diff --git a/test/statifier_test.exs b/test/statifier_test.exs
index 2195ca8..3390623 100644
--- a/test/statifier_test.exs
+++ b/test/statifier_test.exs
@@ -2,7 +2,7 @@ defmodule StatifierTest do
   use ExUnit.Case
   doctest Statifier
 
-  alias Statifier.{Configuration, Document, Interpreter, StateMachine, Validator}
+  alias Statifier.{Configuration, Document, StateMachine, Validator}
 
   describe "Statifier.parse/2" do
     test "parses basic SCXML document successfully" do
@@ -141,30 +141,6 @@ defmodule StatifierTest do
     end
   end
 
-  describe "Statifier.validated?/1" do
-    test "returns true for validated documents" do
-      xml = """
-      <scxml initial="start">
-        <state id="start"/>
-      </scxml>
-      """
-
-      {:ok, document, _warnings} = Statifier.parse(xml)
-      assert Statifier.validated?(document) == true
-    end
-
-    test "returns false for unvalidated documents" do
-      xml = """
-      <scxml initial="start">
-        <state id="start"/>
-      </scxml>
-      """
-
-      {:ok, document, _warnings} = Statifier.parse(xml, validate: false)
-      assert Statifier.validated?(document) == false
-    end
-  end
-
   describe "integration tests" do
     test "full workflow: parse -> interpret" do
       xml = """
@@ -183,7 +159,7 @@ defmodule StatifierTest do
       assert {:ok, document, _warnings} = Statifier.parse(xml, validate: false)
 
       # Interpret
-      assert {:ok, state_chart} = Interpreter.initialize(document)
+      assert {:ok, state_chart} = Statifier.initialize(document)
 
       # Verify initial state is active
       active_states = Configuration.active_leaf_states(state_chart.configuration)
@@ -208,7 +184,7 @@ defmodule StatifierTest do
       assert document.validated == true
 
       # Interpret
-      assert {:ok, state_chart} = Interpreter.initialize(document)
+      assert {:ok, state_chart} = Statifier.initialize(document)
 
       # Verify initial state is active
       active_states = Configuration.active_leaf_states(state_chart.configuration)
@@ -269,7 +245,7 @@ defmodule StatifierTest do
       """
 
       {:ok, document, _warnings} = Statifier.parse(xml)
-      {:ok, state_chart} = Interpreter.initialize(document)
+      {:ok, state_chart} = Statifier.initialize(document)
 
       # Send event synchronously
       assert {:ok, new_state_chart} = Statifier.send_sync(state_chart, "start")
@@ -296,7 +272,7 @@ defmodule StatifierTest do
       """
 
       {:ok, document, _warnings} = Statifier.parse(xml)
-      {:ok, state_chart} = Interpreter.initialize(document)
+      {:ok, state_chart} = Statifier.initialize(document)
 
       assert {:ok, new_state_chart} = Statifier.send_sync(state_chart, "data", %{payload: "test"})
 
diff --git a/test/support/statifier_case.ex b/test/support/statifier_case.ex
index 593a6e0..d6af6e2 100644
--- a/test/support/statifier_case.ex
+++ b/test/support/statifier_case.ex
@@ -72,7 +72,7 @@ defmodule Statifier.Case do
   defp run_scxml_test(xml, _description, expected_initial_config, events) do
     # Parse and initialize the state chart
     {:ok, document, _warnings} = Statifier.parse(xml)
-    {:ok, state_chart} = Interpreter.initialize(document)
+    {:ok, state_chart} = Statifier.initialize(document)
 
     # Verify initial configuration
     assert_configuration(state_chart, expected_initial_config)
@@ -112,7 +112,7 @@ defmodule Statifier.Case do
 
   This helper creates a StateChart with the TestAdapter properly configured,
   which is needed for tests that directly test actions without going through
-  the full Interpreter.initialize process.
+  the full Statifier.initialize process.
   """
   @spec test_state_chart() :: StateChart.t()
   def test_state_chart do