Adds docs.validate mix task, runs example tests in CI (#100)

* Adds Statifier.initialize
* Runs example tests during CI
* Includes README as source for docs in agent
* Adds docs.validate mix task
* Streamlines README and creates comprehensive docs

Co-authored-by: Claude <noreply@anthropic.com>

Author: johnnyt

.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

.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:

.dialyzer_ignore.exs

@@ -0,0 +1,4 @@
+[
+  # Ignore all Mix tasks - these are development tools, not core library functionality
+  ~r/lib\/mix\/tasks\/.*/
+]

.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

.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

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
 ])