oddessentials · oddessentials · Dec 28, 2025 · Dec 28, 2025 · Dec 28, 2025 · Dec 28, 2025
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -27,6 +27,8 @@ jobs:
       compat_critical: ${{ steps.filter.outputs.schemas == 'true' || steps.filter.outputs.compat_script == 'true' || steps.filter.outputs.services == 'true' }}
       # Tier 2: Visual tests
       web_terminal: ${{ steps.filter.outputs.web_terminal }}
+      # Tier 2b: Docs viewer tests
+      docs: ${{ steps.filter.outputs.docs }}
       # Tier 3: Governance-only (does NOT trigger integration gate)
       contracts_docs: ${{ steps.filter.outputs.contracts_docs }}
       governance: ${{ steps.filter.outputs.governance }}
@@ -57,6 +59,8 @@ jobs:
               - 'scripts/*.py'
               - 'scripts/*.ps1'
               - '.github/workflows/**'
+            docs:
+              - 'docs/**'
 
       # Explicit filter-failed detection with CI annotation
       - name: Check filter health
@@ -583,6 +587,50 @@ jobs:
         if: always()
         run: docker compose -f docker-compose.integration.yml down -v
 
+  # ============================================================
+  # Docs Viewer Tests (Playwright)
+  # Only runs when /docs changes - isolated from main test suite
+  # ============================================================
+  docs-tests:
+    name: Docs Viewer Tests
+    runs-on: ubuntu-latest
+    needs: [paths-filter]
+    # Run ONLY when docs files change
+    if: needs.paths-filter.outputs.docs == 'true'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: |
+          cd docs
+          npm ci
+
+      - name: Install Playwright browsers
+        run: |
+          cd docs
+          npx playwright install chromium webkit --with-deps
+
+      - name: Run docs viewer tests
+        run: |
+          cd docs
+          npx playwright test
+        timeout-minutes: 5
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-playwright-report
+          path: docs/playwright-report/
+          retention-days: 7
+
   # ============================================================
   # Distribution Audit (naming, version, artifact consistency)
   # ============================================================

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -325,7 +325,7 @@ jobs:
             sha256sum -c SHA256SUMS --ignore-missing
             ```
 
-            See [Verifying Releases](./docs/VERIFYING_RELEASES.md) for full verification instructions.
+            See [Verifying Releases](./docs/agents/VERIFYING_RELEASES.md) for full verification instructions.
 
   # Publish npm package
   npm-publish:

diff --git a/README.md b/README.md
@@ -19,7 +19,12 @@ A self-contained, local-first demonstration platform showcasing modern, producti
 
 ![Demo](screenshots/3.x/demo.gif)
 
-[Download Demo (MP4)](https://github.com/oddessentials/odd-demonstration/raw/main/screenshots/3.x/demo.mp4)
+🎥 <a href="https://youtu.be/Z3iev0YyYCw" target="_blank" rel="noopener noreferrer">
+Click here to watch the dashboard demo on YouTube
+
+💾 [Click here to download the dasbhoard demo (MP4)](https://github.com/oddessentials/odd-demonstration/raw/main/screenshots/3.x/demo.mp4)
+
+</a>
 
 ---
 
@@ -32,8 +37,8 @@ A self-contained, local-first demonstration platform showcasing modern, producti
 **Authoritative Resources**
 
 - 🗺️ [Blueprints & Design](contracts/blueprint.md)
-- 📐 [Invariants](docs/INVARIANTS.md)
-- ✅ [Feature Coverage](docs/FEATURES.md)
+- 📐 [Invariants](docs/agents/INVARIANTS.md)
+- ✅ [Feature Coverage](docs/agents/FEATURES.md)
 
 **Diagrams**
 
@@ -65,7 +70,7 @@ A self-contained, local-first demonstration platform showcasing modern, producti
 ## 📦 Installation Details
 
 > **Note:** currently releases are unsigned bootstrap builds.
-> See [Verifying Releases](./docs/VERIFYING_RELEASES.md) for checksums.
+> See [Verifying Releases](./docs/agents/VERIFYING_RELEASES.md) for checksums.
 
 ### Verify installation
 
@@ -87,7 +92,7 @@ odd-dashboard doctor
 | Linux   | ARM64         | `odd-dashboard-linux-arm64`     |
 
 **System Requirements:** 8GB RAM minimum (16GB recommended), 4+ CPU cores, 15GB disk.
-See [Support Matrix](./docs/SUPPORT_MATRIX.md) for full hardware requirements and Docker Desktop configuration.
+See [Support Matrix](./docs/agents/SUPPORT_MATRIX.md) for full hardware requirements and Docker Desktop configuration.
 
 ---
 
@@ -372,11 +377,84 @@ kind delete cluster --name task-observatory
 
 ---
 
+## 🔬 Experiment
+
+Here are the results of the experiment associated with this repository.
+
+[![Experiment Results](screenshots/3.x/assessment-meta-data-2025-12-27.png)](https://oddessentials.github.io/odd-demonstration/)
+
+<a href="https://oddessentials.github.io/odd-demonstration/" target="_blank">View the full experiment →</a>
+
+---
+
+## 🔍 Audit (raw details)
+
+This project includes comprehensive audit documentation capturing the implementation journey across 31+ phases:
+
+| Document                                                          | Description                                                                                              |
+| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| [📋 session-summary.md](./audit/session-summary.md)               | High-level project overview with technology stack, key features, and quick access points                 |
+| [✅ task.md](./audit/task.md)                                     | Phase-by-phase implementation checklist tracking all completed work from foundation to hardening         |
+| [📖 walkthrough.md](./audit/walkthrough.md)                       | Detailed implementation walkthrough covering core services, observability, automation, and verification  |
+| [📑 complete-session-audit.md](./audit/complete-session-audit.md) | Comprehensive technical audit with executive summary, phase details, and architecture decisions          |
+| [📦 conversations.zip](./audit/conversations.zip)                 | \*Archived conversation logs from the development sessions. \*.pb files require some priorietery unlock. |
+
+### 🎬 Audit Video
+
+[![Watch the Audit Video](https://img.youtube.com/vi/Z3iev0YyYCw/maxresdefault.jpg)](https://youtu.be/Z3iev0YyYCw)
+
+_\* Because the converations.zip doesn't seem accessible, I've recorded the Google Anti-Gravity conversations that made up the vast majority of this development effort (from start to finish) in this video._
+
+---
+
 ## 📚 Documentation
 
+### Guides
+
 - [Beginner Setup Guide](./README_beginner.md) - Step-by-step with prerequisites
 - [Contributing](./CONTRIBUTING.md) - Development guidelines
-- [Audit](./audit/) - Implementation details and walkthroughs
+
+### Agent Documentation (docs/agents/)
+
+Authoritative reference documentation for builders and autonomous agents:
+
+| Document                                                        | Description                                            |
+| --------------------------------------------------------------- | ------------------------------------------------------ |
+| [📐 INVARIANTS.md](./docs/agents/INVARIANTS.md)                 | System invariants and CI enforcement map               |
+| [✅ FEATURES.md](./docs/agents/FEATURES.md)                     | Feature coverage and implementation status             |
+| [🧪 TESTING.md](./docs/agents/TESTING.md)                       | Testing strategy, harnesses, and determinism contracts |
+| [📦 RELEASE_CHECKLIST.md](./docs/agents/RELEASE_CHECKLIST.md)   | Release preparation and verification steps             |
+| [🔐 SECRET_MANAGEMENT.md](./docs/agents/SECRET_MANAGEMENT.md)   | Secrets handling and rotation procedures               |
+| [📋 SUPPORT_MATRIX.md](./docs/agents/SUPPORT_MATRIX.md)         | Platform support and hardware requirements             |
+| [✔️ VERIFYING_RELEASES.md](./docs/agents/VERIFYING_RELEASES.md) | Release verification and checksum validation           |
+
+### 📖 Further Reading & Background
+
+The following articles document the motivation and evolution of this repository.  
+They are **not required reading**, but provide additional context for interested readers.
+
+- **From Puppeteer to Conductor (Part 3 of 3)**  
+  _Designing autonomous systems without sacrificing safety or determinism_  
+  https://medium.com/@pete.palles/from-puppeteer-to-conductor-520c8f18e37f
+
+- **The Renaissance Engineers (Part 2 of 3)**  
+  _Dark Magic, Dog Food, Determinism, and the Humans in the Loop_
+  https://medium.com/@pete.palles/the-renaissance-engineers-e3c1efa15572
+
+- **The Future of Software Engineering (Part 1 of 3)**  
+  _Supercolonies: Where the Most Skilled Engineers Command Hives and Swarms_  
+  https://medium.com/@pete.palles/the-future-of-software-engineering-51de53d2e45a
+
+---
+
+## 👤 Author
+
+<img src="docs/img/pete-palles-512.jpg" alt="Pete Palles" width="96" style="border-radius:50%;" />
+
+**Pete Palles**  
+🔗 LinkedIn: https://www.linkedin.com/in/petepalles
+
+Peter is a Software Engineering Manager at a large enterprise healthcare organization, where he leads a team of highly skilled software engineers. He is also the Founder and CEO of Odd Essentials, LLC. With more than 20 years of experience spanning full-stack development, systems engineering, and applied AI, Peter has architected, designed, and delivered large-scale software systems end-to-end. At the ripe age of 41, Pete is currently completing his MBA at the University of Pittsburgh’s Katz Graduate School of Business.
 
 ---
 

diff --git a/audit/session-summary.md b/audit/session-summary.md
@@ -1,7 +1,7 @@
 # Distributed Task Observatory - Session Summary
 
-**Last Updated:** 2025-12-27
-**Phases Completed:** 0-31.6 (Phase 31.6: CI Docker Build Context Fix)
+**Last Updated:** 2025-12-28
+**Phases Completed:** 0-32 (Phase 32: Docs Directory Refactor)
 
 ## Objective
 
@@ -78,6 +78,9 @@ Implement a complete, production-grade distributed task processing system demons
 - **PTY Server Coverage** - 81% (47 unit tests)
 - **Tiered Visual Test Strategy** (Phase 31.5) - Nightly workflow, server-side failure injection, deterministic fallback testing
 - **CI Docker Build Context Fix** (Phase 31.6) - Fixed CI contexts, added `validate-dockerfile-context.py` prevention script
+- **Mermaid Animator Expansion** (Phase 31.7) - Multi-tokenizer architecture for 20+ Mermaid types, 110+ passing unit tests
+- **Docs Viewer & E2E Tests** (Phase 31.8) - GitHub Pages experiment viewer with comparison mode, Playwright E2E tests
+- **Docs Directory Refactor** (Phase 32) - Moved 7 .md files to `docs/agents/`, enhanced README documentation section
 
 ## Quick Start
 

diff --git a/audit/task.md b/audit/task.md
@@ -104,7 +104,7 @@
 - [x] Update BUILD.bazel for TypeScript tests
 
 ## Phase 17: Testing Optimizations & CI Hardening [x]
-- [x] Create `docs/INVARIANTS.md` with cross-platform and contract guarantees
+- [x] Create `docs/agents/INVARIANTS.md` with cross-platform and contract guarantees
 - [x] Add unified coverage enforcement via `coverage-config.json` and `check-coverage.py`
 - [x] Parallelize Go tests with pwsh < 7 fallback
 - [x] Add `dorny/paths-filter` for reliable change detection
@@ -118,3 +118,23 @@
 - [x] Add validation to CI workflow
 - [x] Update INVARIANTS.md with accurate B1-B4 documentation
 
+## Phase 31.7: Mermaid Animator Expansion [x]
+- [x] Implement Phase 1 tokenizers (Flowchart, State, Sequence)
+- [x] Implement Phase 2 tokenizers (Sankey, Pie, Radar, Gantt, Mindmap, GitGraph, Class)
+- [x] Create type detection router (`src/type-router.js`)
+- [x] Add animation strategies (stream-flow, reveal, trace, cascade, branch-grow)
+- [x] 110+ passing unit tests across 20+ suites
+
+## Phase 31.8: Docs Viewer & E2E Tests [x]
+- [x] Create GitHub Pages experiment viewer (`docs/index.html`, `docs/app.js`)
+- [x] Implement side-by-side comparison mode for assessments
+- [x] Add responsive mobile stacking for compare mode
+- [x] Add Playwright E2E tests (`docs/tests/docs-viewer.spec.js`)
+- [x] Integrate with CI via path-filtered triggers
+
+## Phase 32: Docs Directory Refactor [x]
+- [x] Move 7 .md files from `docs/` to `docs/agents/`
+- [x] Update all functional code references (README.md, scripts, doctor.rs)
+- [x] Update internal cross-references in moved files
+- [x] Enhance README Documentation section with docs/agents table
+- [x] Update audit session data with new phases
diff --git a/docs/FEATURES.md → docs/agents/FEATURES.md b/docs/FEATURES.md → docs/agents/FEATURES.md
diff --git a/docs/INVARIANTS.md → docs/agents/INVARIANTS.md b/docs/INVARIANTS.md → docs/agents/INVARIANTS.md
diff --git a/docs/RELEASE_CHECKLIST.md → docs/agents/RELEASE_CHECKLIST.md b/docs/RELEASE_CHECKLIST.md → docs/agents/RELEASE_CHECKLIST.md
diff --git a/docs/SECRET_MANAGEMENT.md → docs/agents/SECRET_MANAGEMENT.md b/docs/SECRET_MANAGEMENT.md → docs/agents/SECRET_MANAGEMENT.md
@@ -66,7 +66,7 @@ Secrets are defined at the environment level, NOT repository level.
 2. Export private key: `gpg --export-secret-keys --armor KEY_ID`
 3. Update `GPG_PRIVATE_KEY` and `GPG_PASSPHRASE`
 4. Export and publish public key to `keys/release-signing.pub`
-5. Update key fingerprint in `docs/VERIFYING_RELEASES.md`
+5. Update key fingerprint in `VERIFYING_RELEASES.md`
 6. Update GitHub user GPG keys
 
 ## Emergency Revocation

diff --git a/docs/SUPPORT_MATRIX.md → docs/agents/SUPPORT_MATRIX.md b/docs/SUPPORT_MATRIX.md → docs/agents/SUPPORT_MATRIX.md
@@ -104,7 +104,7 @@ The following platforms are **not supported**:
 Running on unsupported platforms will result in:
 ```
 ERROR: Unsupported platform: {os}-{arch}
-See supported configurations: https://github.com/oddessentials/odd-demonstration/blob/main/docs/SUPPORT_MATRIX.md
+See supported configurations: https://github.com/oddessentials/odd-demonstration/blob/main/docs/agents/SUPPORT_MATRIX.md
 ```
 
 ## Checking Platform Support

diff --git a/docs/TESTING.md → docs/agents/TESTING.md b/docs/TESTING.md → docs/agents/TESTING.md
diff --git a/docs/VERIFYING_RELEASES.md → docs/agents/VERIFYING_RELEASES.md b/docs/VERIFYING_RELEASES.md → docs/agents/VERIFYING_RELEASES.md